Manifiesto y permisos

plugin.manifest.json indica a la ciudad quién eres, dónde está tu experiencia y qué puede solicitar. Aprobamos una combinación exacta de versión, entrada y permisos. Si cambias alguno, la nueva versión necesita otra aprobación.

Ejemplo

plugin.manifest.json

{
  "schema": "zenclub.plugin/v1",
  "id": "my-garden",
  "name": "My garden",
  "description": "Tend a small garden at your own pace.",
  "coverLabel": "A small garden",
  "version": "1.0.0",
  "sdkProtocol": "zenclub.rpc/1",
  "hostApi": {"major": 1, "minMinor": 2},
  "entry": "https://my-garden.example/v1.0.0/",
  "permissions": ["lifecycle.report", "storage.read", "storage.write", "session.report"],
  "optionalPermissions": ["moments.create", "header.setActions"],
  "modes": ["watch", "manual"],
  "tags": ["garden", "slow"]
}

Campos

Campo	Regla
`schema`	Siempre `zenclub.plugin/v1`.
`id`	De 1 a 80 letras, cifras, puntos, guiones bajos o guiones, empezando por una letra o cifra. No cambia nunca.
`name, description, coverLabel`	Texto sin formato, con un máximo de 2048 caracteres por campo. `coverLabel` es el breve texto de la portada.
`version`	Versión semántica, como `1.4.0` o `1.5.0-beta.1`. Debe coincidir con `version`, que pasas a `connect()`.
`sdkProtocol`	Siempre `zenclub.rpc/1`.
`hostApi`	La API del host más antigua que necesitas, con el formato `{major, minMinor}`. Solicita la versión menor más baja que funcione.
`entry`	URL HTTPS absoluta de tu página, sin nombre de usuario, contraseña ni fragmento. Solo se acepta HTTP sin cifrar en localhost. No puede compartir el origen de la plataforma.
`permissions`	Capacidades imprescindibles para tu experiencia. No puede haber duplicados.
`optionalPermissions`	Hasta 32 capacidades que usarás si se conceden. No repitas ninguna obligatoria.
`milestones`	Opcional: una clave fija, una versión de regla y un nivel máximo, aprobados por separado por el equipo operador junto con la capacidad de informar.
`modes`	Uno o más de `watch`, `manual` y `listen`. Solo puedes informar de un modo declarado.
`tags`	Hasta 10 etiquetas de 32 caracteres como máximo.

Capacidades

Cada método del SDK es una capacidad. Si no se te ha concedido, la llamada falla con FORBIDDEN antes de salir del marco. Comprueba primero las opcionales con sdk.supports(name).

Capacidad	API del host	Uso
`lifecycle.report`	1.0	Informa de la carga, de que está lista o de un fallo.
`storage.read`	1.0	Lee una ranura de guardado.
`storage.write`	1.0	Escribe en una ranura de guardado y comprueba su revisión.
`session.report`	1.0	Informa si la sesión está en marcha, en pausa o terminada para medir el tiempo.
`runs.finish`	1.0	Registra una partida terminada o reiniciada, con hasta 20 métricas numéricas.
`moments.create`	1.0	Ofrece a quien visita una imagen para guardar. La plataforma puede pedirle permiso primero.
`achievements.request`	1.0	Pide a la plataforma que verifique y conceda una insignia.
`counters.add`	1.2	Suma al recuento compartido que la persona operadora haya definido para ti.
`events.report`	1.2	Informa de un evento breve con nombre, como el final de un capítulo.
`shares.request`	1.2	Abre el panel para compartir de la plataforma y compartir una insignia o tu experiencia.
`navigation.exit`	1.2	Sal en calma hacia la página de detalles de tu experiencia.
`display.immersive`	1.3	Pide a la plataforma que oculte el marco que te rodea.
`header.setActions`	1.4	Coloca tus acciones en la cabecera de la plataforma.
`milestones.report`	1.6	Informar de una decoración aprobada de la ciudad privada a partir de una partida guardada confirmada, cuando el jugador haya activado el registro.

Valida antes de solicitarlo

La herramienta de línea de comandos realiza las mismas comprobaciones que la plataforma y confirma que la API del host solicitada está disponible. Validar no concede permisos; solo lo hace una aprobación.

shell

npx zenclub-plugin validate plugin.manifest.json --host=https://zenclub.app

Versiones de la API del host

La API del host actual es 1.6 y acepta complementos que soliciten de 1.0 a 1.6. Solicita la versión menor más baja que necesites y comprueba los métodos opcionales con sdk.supports(). Para recibir la preferencia de sonido, exige 1.5 o posterior tanto en tu manifiesto como en connect(). Los complementos antiguos sin declaraciones de hitos reciben las mismas concesiones y el mismo contexto que antes.

Hitos opcionales de la ciudad

Declara milestones.report como opcional y añade exactamente una entrada milestones. La primera versión incluye ocho claves fijas: homestead, pond, clouds, bamboo, tea, stream, bell y lotus. Cada versión de regla es la clave seguida de .1, con maxTier: 2. La aprobación fija esa combinación exacta, la versión, la entrada y la capacidad. Una declaración escrita por el propio complemento nunca concede acceso.

plugin.manifest.json

{
  "hostApi": {"major": 1, "minMinor": 6},
  "optionalPermissions": ["milestones.report"],
  "milestones": [{"key": "tea", "ruleVersion": "tea.1", "maxTier": 2}]
}

Un complemento creado con SDK 0.9 puede mantener una versión mínima anterior cuando los informes son opcionales. En un host de 1.0–1.5, sin aprobación o con almacenamiento solo en el dispositivo, mantén la partida normal y omite los informes. Las aprobaciones de hosts anteriores deben omitir la nueva concesión. Los informes de hitos obligatorios requieren 1.6; el registro nunca debe ser un requisito para jugar o iniciar sesión.