Entradas de compêndio: os cinco kinds

api.compendiums.add captura um recurso que já existe na campanha. O campo kind escolhe o tipo do recurso; resourceId recebe seu UUID real. O servidor guarda um snapshot com dependências em um arquivo portátil. Ele não recebe um objeto arbitrário de ficha no lugar de resourceId.

Execute os exemplos em um módulo montado na campanha descartável, usando o api e o signal do bloco. É necessário ser GM, possuir os documentos de exemplo na mesma campanha e escolher um compêndio de mesa desbloqueado. Compêndios nativos e de sistema instalado são somente leitura. Crie o destino uma vez e guarde created.id como packId:

export async function createExamplePack(api, signal) {
  const created = await api.compendiums.create({ name: "Beacon Collection" }, {
    requestId: crypto.randomUUID(), signal,
  });
  return created.id;
}

kind: "actor": Cópia de ator

Use o UUID de um ator Beacon Scout criado no tipo character do sistema de exemplo. O snapshot preserva o tipo e os dados do ator.

export async function storeActor(api, packId, resourceId, signal, requestId = crypto.randomUUID()) {
  const added = await api.compendiums.add({
    packId,
    kind: "actor",
    resourceId,
    name: "Beacon Scout",
  }, { requestId, signal });
  return api.compendiums.read({ packId, id: added.id }, { signal });
}

Resultado esperado: storeActor(api, packId, resourceId, signal) retorna a entrada com kind: "actor", id, name, data e version. O documento original permanece na campanha.

Valide: confira a entrada no compêndio; importe uma cópia numa campanha de teste compatível e abra o documento criado.

kind: "item": Cópia de item

Use o UUID do item Beacon Rope, do tipo gear registrado no sistema da campanha. O snapshot preserva tipo e dados do item.

export async function storeItem(api, packId, resourceId, signal, requestId = crypto.randomUUID()) {
  const added = await api.compendiums.add({
    packId,
    kind: "item",
    resourceId,
    name: "Beacon Rope",
  }, { requestId, signal });
  return api.compendiums.read({ packId, id: added.id }, { signal });
}

Resultado esperado: storeItem(api, packId, resourceId, signal) retorna a entrada com kind: "item", id, name, data e version. O documento original permanece na campanha.

Valide: confira a entrada no compêndio; importe uma cópia numa campanha de teste compatível e abra o documento criado.

kind: "journal": Cópia de diário

Use o UUID do diário Beacon Notes. O mesmo kind aceita os tipos nativos de diário; missão continua sendo kind journal ao entrar no compêndio.

export async function storeJournal(api, packId, resourceId, signal, requestId = crypto.randomUUID()) {
  const added = await api.compendiums.add({
    packId,
    kind: "journal",
    resourceId,
    name: "Beacon Notes",
  }, { requestId, signal });
  return api.compendiums.read({ packId, id: added.id }, { signal });
}

Resultado esperado: storeJournal(api, packId, resourceId, signal) retorna a entrada com kind: "journal", id, name, data e version. O documento original permanece na campanha.

Valide: confira a entrada no compêndio; importe uma cópia numa campanha de teste compatível e abra o documento criado.

kind: "scene": Cópia de cena

Use o UUID da cena Beacon Harbor da campanha. O corpo retornado por read pode mostrar apenas o nome; o bundle portátil conserva os recursos exportados e dependências.

export async function storeScene(api, packId, resourceId, signal, requestId = crypto.randomUUID()) {
  const added = await api.compendiums.add({
    packId,
    kind: "scene",
    resourceId,
    name: "Beacon Harbor",
  }, { requestId, signal });
  return api.compendiums.read({ packId, id: added.id }, { signal });
}

Resultado esperado: storeScene(api, packId, resourceId, signal) retorna a entrada com kind: "scene", id, name, data e version. O documento original permanece na campanha.

Valide: confira a entrada no compêndio; importe uma cópia numa campanha de teste compatível e abra o documento criado.

kind: "deck": Cópia de baralho

Use o UUID da instância de baralho Beacon Signals, obtido em api.cards.state().decks. Não use um deck_definition_id: add espera um baralho existente.

export async function storeDeck(api, packId, resourceId, signal, requestId = crypto.randomUUID()) {
  const added = await api.compendiums.add({
    packId,
    kind: "deck",
    resourceId,
    name: "Beacon Signals",
  }, { requestId, signal });
  return api.compendiums.read({ packId, id: added.id }, { signal });
}

Resultado esperado: storeDeck(api, packId, resourceId, signal) retorna a entrada com kind: "deck", id, name, data e version. O documento original permanece na campanha.

Valide: confira a entrada no compêndio; importe uma cópia numa campanha de teste compatível e abra o baralho para conferir as cartas.

Ler e importar são ações diferentes

state lista metadados, sem os corpos nem os arquivos portáteis. read retorna dados autorizados; ele não cria documentos. import cria uma cópia e exige GM. Use o id da entrada retornada no exemplo acima:

export async function importExampleEntry(api, packId, entryId, signal) {
  return api.compendiums.import({ packId, id: entryId }, {
    requestId: crypto.randomUUID(), signal,
  });
}

O destino da importação é a campanha do bloco atual; não existe um campo para escolher outra campanha nesta chamada. Para testar outra campanha, use um bloco montado nela e seus próprios IDs de recursos e compêndios. Cada ação lógica precisa de UUID próprio; conserve o UUID e passe o quinto argumento da função apenas para repetir o mesmo add após falha de transporte. Se add confirmou e read falhou, consulte state/read antes de adicionar novamente, pois as duas chamadas não formam uma única transação.

Erros e validação

Sem GM, uma escrita é rejeitada. Recursos de outra campanha e packs inacessíveis ficam indisponíveis; um pack bloqueado rejeita edição; kind desconhecido rejeita add. Importar em sistema incompatível falha. Não confunda falha de leitura com ausência de dados nem tente forçar versões. Para configure/remove/delete, leia a versão atual do pack/entrada e use o campo version da operação documentada.

Valide cada kind com um recurso real, depois tente o mesmo add com jogador, pack bloqueado e UUID de outra campanha. Confirme que o original não mudou e que a cópia importada conserva seus recursos. Uma leitura com grant válido pode ser permitida ao jogador; importar continua sendo ação de GM.

Como usar a IA para criar uma biblioteca de snapshots

Confira frontend.json e compendiums/services.py na release alvo. Amplie storeScene para selecionar uma cena legível e um compêndio desbloqueado do GM. Use resourceId real, requestId novo por ação e leia o resultado. Mostre erros, estado vazio e retry sem duplicar a captura. Não envie JSON arbitrário de cena para add nem substitua o bundle por um nome.