Packs de compêndio: 3 tipos instalados e 7 locais

Um pack usa o campo type, chamado de “kind de pack” na documentação. Ele é diferente de entry.kind retornado pelo diretório e de entry.type, o tipo de documento do sistema. Não coloque kind na raiz de manifest.json.

Há duas origens com limites diferentes: coleções fornecidas por um pacote de sistema instalado e catálogos locais preparados pelo operador. Todos os dados Beacon abaixo são fictícios e originais.

Preparação do sistema instalado

Use a release alvo que suporta content.compendiums; o recurso existe desde o VTT 0.2.1. O sistema precisa estar instalado, ativo na versão exata da campanha e não revogado. Comece com o pacote mínimo e use este manifesto. Ele registra explicitamente character, gear e spell; esses nomes pertencem apenas ao sistema de exemplo.

{
  "id": "example.beacon",
  "name": "Beacon Example System",
  "version": "1.0.0",
  "sdk": {
    "requires": ">=1.0.0 <2.0.0",
    "tested": "1.0.0"
  },
  "entry": "main.js",
  "description": "Original example document types and compendium data.",
  "author": "Example author",
  "license": "MIT",
  "system": {
    "actorTypes": [
      {
        "id": "character",
        "label": "Character"
      }
    ],
    "itemTypes": [
      {
        "id": "gear",
        "label": "Gear"
      },
      {
        "id": "spell",
        "label": "Spell"
      }
    ]
  },
  "content": {
    "compendiums": [
      "compendiums/beacon.json"
    ]
  }
}

Coloque a coleção em compendiums/beacon.json dentro do mesmo pacote. Baixe a coleção com os três packs. O main.js mínimo abaixo apenas demonstra os tipos e os dados; adicione suas fichas pelas superfícies do SDK. Inclua a licença escolhida, adapte autor/nome e siga a instalação ZIP ou assinatura de Sistemas e módulos. Não altere arquivos depois que a release estiver instalada.

export default {
  start() {},
  register() {},
  stop() {},
};

Sistema instalado: actor_pack

Importa Beacon Scout como ator character, com stamina 6.

Esta é uma coleção completa com um único pack; use-a sozinha ou combine packs no array packs do arquivo baixável.

{
  "name": "Beacon Examples",
  "packs": [
    {
      "id": "beacon-actors",
      "label": "Beacon Actors",
      "type": "actor_pack",
      "entries": [
        {
          "id": "beacon-scout",
          "name": "Beacon Scout",
          "type": "character",
          "systemId": "example.beacon",
          "data": {
            "stamina": 6
          }
        }
      ]
    }
  ]
}

Valide: confira beacon-scout no pack do sistema e importe como GM. O diretório mostra kind: "actor"; o documento importado usa type: "character".

Sistema instalado: item_pack

Importa Beacon Rope como item gear, com length 10.

Esta é uma coleção completa com um único pack; use-a sozinha ou combine packs no array packs do arquivo baixável.

{
  "name": "Beacon Examples",
  "packs": [
    {
      "id": "beacon-items",
      "label": "Beacon Items",
      "type": "item_pack",
      "entries": [
        {
          "id": "beacon-rope",
          "name": "Beacon Rope",
          "type": "gear",
          "systemId": "example.beacon",
          "data": {
            "length": 10
          }
        }
      ]
    }
  ]
}

Valide: confira beacon-rope no pack do sistema e importe como GM. O diretório mostra kind: "item"; o documento importado usa type: "gear".

Sistema instalado: spell_pack

Importa Beacon Glow como item spell, com color blue. spell_pack é um alias de compatibilidade para item; o core não ganha regras de magia.

Esta é uma coleção completa com um único pack; use-a sozinha ou combine packs no array packs do arquivo baixável.

{
  "name": "Beacon Examples",
  "packs": [
    {
      "id": "beacon-spells",
      "label": "Beacon Spells",
      "type": "spell_pack",
      "entries": [
        {
          "id": "beacon-glow",
          "name": "Beacon Glow",
          "type": "spell",
          "systemId": "example.beacon",
          "data": {
            "color": "blue"
          }
        }
      ]
    }
  ]
}

Valide: confira beacon-glow no pack do sistema e importe como GM. O diretório mostra kind: "item"; o documento importado usa type: "spell".

Validar o contrato antes da instalação

Cada coleção é limitada a 8 MiB, 64 packs e 20.000 entradas; cada entrada a 256 KiB e a profundidade JSON a 24 níveis. O manifesto aceita até 16 caminhos de coleção. IDs precisam ser únicos dentro do seu pack/coleção, ter até 120 caracteres e usar letras ASCII, números, ponto, sublinhado, dois-pontos ou hífen; precisam começar por letra ou número. Nome/label têm até 120 caracteres. Os tipos das entradas precisam estar registrados no manifesto e systemId precisa ser example.beacon neste exemplo.

Uma coleção de sistema instalado NÃO leva campanhas. O host vincula acesso à versão aprovada da campanha. Um jogador só a vê sob concessão válida; importar exige GM. As coleções declaradas não são servidas por assets.json: descubra os IDs por api.compendiums.state e leia pela API autorizada.

Para rodar o validador real no checkout de desenvolvimento, salve os JSONs como manifest.json e compendiums/beacon.json numa pasta descartável. Execute o código abaixo a partir de python manage.py shell, com essa pasta no diretório de trabalho ou ajustando os dois caminhos:

import json
from pathlib import Path
from gravewright.compendiums.content import validate_collection

manifest = json.loads(Path("manifest.json").read_text(encoding="utf-8"))
collection = json.loads(Path("compendiums/beacon.json").read_text(encoding="utf-8"))
validate_collection(
    collection,
    manifest["id"],
    {row["id"] for row in manifest["system"]["actorTypes"]},
    {row["id"] for row in manifest["system"]["itemTypes"]},
)
print("Collection accepted")

Catálogos locais: preparação do operador

Esta é uma integração de arquivos do operador do host, não uma capacidade de escrita oferecida ao módulo de navegador. No checkout de desenvolvimento, use a pasta configurada em settings.GRAVEWRIGHT_CONTENT_ROOT; não presuma um diretório global nem edite a .env para experimentar. A configuração e o Runner determinam a raiz efetiva.

O catálogo local usa uma subpasta com index.json e um array campaigns contendo UUIDs reais autorizados pelo operador. O UUID abaixo é fictício: troque-o pelo da sua campanha descartável, configurada com example.beacon. Esses catálogos são somente leitura na mesa. journal_pack/scene_pack/card_pack/deck_pack pertencem a esta origem e são rejeitados em content.compendiums de um pacote instalado.

Baixe o index.json local completo e a arte original beacon.webp. Preserve a árvore local/index.json e local/artwork/beacon.webp. Cada bloco abaixo é um pack completo para o array packs do index. A configuração mínima da coleção é:

{
  "name": "Beacon Local Examples",
  "systemId": "example.beacon",
  "campaigns": [
    "00000000-0000-4000-8000-000000000001"
  ],
  "packs": []
}

Catálogo local: actor_pack

{
  "id": "beacon-actors",
  "label": "Beacon Actors",
  "type": "actor_pack",
  "entries": [
    {
      "id": "beacon-scout",
      "name": "Beacon Scout",
      "type": "character",
      "systemId": "example.beacon",
      "data": {
        "stamina": 6
      }
    }
  ]
}

Resultado esperado e validação: Cria um ator character. O tipo precisa existir no sistema da campanha; este exemplo usa stamina 6. Recarregue os compêndios, leia a entrada pelo ID e importe como GM; confira o recurso criado na campanha descartável.

Catálogo local: item_pack

{
  "id": "beacon-items",
  "label": "Beacon Items",
  "type": "item_pack",
  "entries": [
    {
      "id": "beacon-rope",
      "name": "Beacon Rope",
      "type": "gear",
      "systemId": "example.beacon",
      "data": {
        "length": 10
      }
    }
  ]
}

Resultado esperado e validação: Cria um item gear com length 10. Não use um tipo de item de outro sistema. Recarregue os compêndios, leia a entrada pelo ID e importe como GM; confira o recurso criado na campanha descartável.

Catálogo local: spell_pack

{
  "id": "beacon-spells",
  "label": "Beacon Spells",
  "type": "spell_pack",
  "entries": [
    {
      "id": "beacon-glow",
      "name": "Beacon Glow",
      "type": "spell",
      "systemId": "example.beacon",
      "data": {
        "color": "blue"
      }
    }
  ]
}

Resultado esperado e validação: Cria um item spell. Continua sendo kind item no diretório e não uma entidade nativa de magia. Recarregue os compêndios, leia a entrada pelo ID e importe como GM; confira o recurso criado na campanha descartável.

Catálogo local: journal_pack

{
  "id": "beacon-journals",
  "label": "Beacon Journals",
  "type": "journal_pack",
  "entries": [
    {
      "id": "beacon-notes",
      "name": "Beacon Notes",
      "type": "diary",
      "systemId": "example.beacon",
      "data": {}
    }
  ]
}

Resultado esperado e validação: Cria um diário vazio diary chamado Beacon Notes. Preencha conteúdo original pela interface depois de importar. Recarregue os compêndios, leia a entrada pelo ID e importe como GM; confira o recurso criado na campanha descartável.

Catálogo local: scene_pack

{
  "id": "beacon-scenes",
  "label": "Beacon Scenes",
  "type": "scene_pack",
  "entries": [
    {
      "id": "beacon-harbor",
      "name": "Beacon Harbor",
      "type": "scene",
      "systemId": "example.beacon",
      "data": {
        "width": 1400,
        "height": 980
      }
    }
  ]
}

Resultado esperado e validação: Cria a cena Beacon Harbor com 1400 × 980 pixels. Esta entrada mínima não inclui mapa de fundo, paredes ou objetos. Recarregue os compêndios, leia a entrada pelo ID e importe como GM; confira o recurso criado na campanha descartável.

Catálogo local: card_pack

{
  "id": "beacon-cards",
  "label": "Beacon Cards",
  "type": "card_pack",
  "entries": [
    {
      "id": "beacon-card-deck",
      "name": "Beacon Signals",
      "type": "deck",
      "systemId": "example.beacon",
      "data": {
        "cards": [
          {
            "name": "Beacon Signal",
            "artwork": "artwork/beacon.webp",
            "quantity": 1
          }
        ]
      }
    }
  ]
}

Resultado esperado e validação: Cria uma instância de baralho com uma carta Beacon Signal. A arte WebP precisa existir relativa à pasta do index. Recarregue os compêndios, leia a entrada pelo ID e importe como GM; confira o recurso criado na campanha descartável.

Catálogo local: deck_pack

{
  "id": "beacon-decks",
  "label": "Beacon Decks",
  "type": "deck_pack",
  "entries": [
    {
      "id": "beacon-deck",
      "name": "Beacon Watch",
      "type": "deck",
      "systemId": "example.beacon",
      "data": {
        "cards": [
          {
            "name": "Beacon Watch",
            "artwork": "artwork/beacon.webp",
            "quantity": 2
          }
        ]
      }
    }
  ]
}

Resultado esperado e validação: Cria uma instância de baralho com duas cartas Beacon Watch. quantity expande as cópias. card_pack e deck_pack usam o mesmo importador. Recarregue os compêndios, leia a entrada pelo ID e importe como GM; confira o recurso criado na campanha descartável.

Instalar apenas o catálogo local de exemplo

Com os dois downloads salvos sob uma pasta local e a campanha de teste criada, execute o trecho no python manage.py shell da instalação descartável. Ajuste sample para o caminho onde os arquivos foram baixados e campaign_id para o UUID real. O script lê a raiz configurada e cria uma nova pasta beacon-examples; falha se ela já existir, preservando instalações e conteúdo anterior.

import json
import shutil
from pathlib import Path
from uuid import UUID
from django.conf import settings

sample = Path("downloaded-examples/local").resolve()
campaign_id = str(UUID("00000000-0000-4000-8000-000000000001"))
collection = json.loads((sample / "index.json").read_text(encoding="utf-8"))
artwork = sample / "artwork" / "beacon.webp"
if not artwork.is_file():
    raise FileNotFoundError(artwork)
collection["campaigns"] = [campaign_id]
root = Path(settings.GRAVEWRIGHT_CONTENT_ROOT).resolve()
destination = root / "beacon-examples"
destination.mkdir(parents=True, exist_ok=False)
(destination / "artwork").mkdir()
shutil.copy2(artwork, destination / "artwork" / "beacon.webp")
(destination / "index.json").write_text(
    json.dumps(collection, ensure_ascii=False, indent=2), encoding="utf-8"
)
print(destination)

Erros e verificações finais

Coleção de sistema com tipo não registrado, systemId errado, IDs repetidos ou um dos quatro packs exclusivos de catálogo local falha na validação antes da instalação. Na mesa, uma versão não ativa/revogada ou bytes alterados tornam o conteúdo indisponível. Não use falha de integridade como motivo para editar o pacote instalado: gere nova versão.

No catálogo local, campaigns ausente ou com UUID errado faz o catálogo não aparecer. Card/deck exige de 1 a 500 cartas, quantity inteiro entre 1 e 500, total de até 500 e WebP válido de até 10 MiB dentro da pasta do catálogo; caminho externo ou arquivo faltante falha. Confira a árvore e o resultado de cada importação. A visibilidade inicial é do GM; conceda leitura pelo fluxo de permissões e confirme que o jogador pode ler, mas não importar.

Como usar a IA para criar packs de conteúdo original

Confira content.py, catalog.py e o manifesto da release alvo. Crie um sistema instalado com um actor_pack, um item_pack e um spell_pack usando somente descritores declarados, systemId correto e conteúdo original. Gere JSONs completos, valide com validate_collection e mostre state/read/import. Explique por que journal_pack, scene_pack, card_pack e deck_pack não podem entrar nesse ZIP; se eu pedir catálogo local, use a setting efetiva e campanhas explícitas sem sobrescrever arquivos existentes.