# Publicação de pacotes — App e CLI do AI Game Dev · AI Game Developer Wiki

Publique um pacote no registro da comunidade do AI Game Dev: publicador, upload, notas de versão, canais beta, depreciação, yank e outras fontes.

Esta página foi traduzida automaticamente do inglês. [Leia o original em inglês](https://ai-game.dev/docs/wiki/app/publishing-packages).

O registro da comunidade é onde os usuários encontram e instalam pacotes por id: `gamedev pkg add acme.level-tools`, ou **Browse** na janela Packages, com atualizações automáticas e avaliações de 1 a 5 estrelas. Qualquer conta registrada no ai-game.dev pode publicar, os pacotes são gratuitos e cada versão passa por verificações automáticas em vez de uma revisão manual. Esta página cobre todo o caminho: seu publicador, o primeiro upload, notas de versão, canais de pré-release, depreciação, yank e as outras formas de compartilhar um pacote.

![O catálogo de pacotes em ai-game.dev: um pacote de engine em destaque, filtros de categoria e fileiras de pacotes oficiais e da comunidade](https://ai-game.dev/images/wiki/app/catalog-packages.webp)

O catálogo de pacotes: pacotes oficiais e pacotes da comunidade, cada um com seu comando de instalação.

## Reivindique um publicador

O id do seu publicador é a primeira metade de cada id de pacote que você publica (`acme` em `acme.level-tools`). Reivindique-o uma única vez; é por ordem de chegada:

```bash
gamedev login
gamedev pkg publisher claim acme --name "Acme Tools"
```

Um id de publicador tem de 2 a 40 letras minúsculas, dígitos e hífens simples. O id do próprio AI Game Dev (`aigd`), nomes de engines (`unity`, `godot`, `unreal`, `brutal`, `bevy`, `threejs`), marcas registradas e similares como `un1ty` ou `unity-tools` são reservados. Uma conta precisa de um e-mail verificado e pode ter até 3 publicadores.

A conta que reivindica um publicador é seu **proprietário**. Um proprietário pode adicionar **mantenedores** por e-mail; mantenedores podem fazer upload, yank, depreciar, editar notas de versão, mover canais e gerar tokens. Apenas um proprietário gerencia membros e [publicadores confiáveis](https://ai-game.dev/pt-br/docs/wiki/app/trusted-publishing).

## Publique uma versão

Coloque `"publisher": "acme"` em `aigd-package.json`, aumente a `version`, faça o build e então:

```bash
gamedev pkg publish level-tools
```

A CLI empacota a pasta (as mesmas verificações e os mesmos bytes de `gamedev pkg pack`), faz o upload e aguarda as verificações. Uma versão passa por estes estados:

| Estado | Significado |
| --- | --- |
| `uploaded`, `checking` | Aguardando ou executando as verificações automáticas |
| `published` | Passou em todas as verificações; entra no índice assinado em cerca de um minuto |
| `rejected` | Uma verificação falhou; o relatório indica cada falha. Corrija e envie a mesma versão novamente |
| `yanked` | Retirada pelo publicador: os intervalos a ignoram, instalações existentes a mantêm |
| `revoked` | Removida pelo AI Game Dev (malware, conta roubada): todo app a desativa |

**As versões são imutáveis.** Um número de versão publicado, com yank ou revogado nunca pode ser enviado novamente; apenas um rejeitado pode. Entregue a correção como uma nova versão.

![A página de um pacote no catálogo: nome, publicador, versão, botão e comando de instalação, prévias dos starters, um painel About e a versão mais recente](https://ai-game.dev/images/wiki/app/catalog-package-page.webp)

A página de um pacote da comunidade no catálogo. Os usuários o instalam com um clique ou um comando.

## Notas de versão

Cada versão pode trazer notas de versão em Markdown. Os usuários as veem por versão na janela Packages (**Versions**) e no painel do publicador. Informe-as no upload:

```bash
gamedev pkg publish level-tools --notes RELEASE_NOTES.md
```

Sem `--notes`, o registro pega a seção do seu `CHANGELOG.md` (na pasta do pacote, incluído no arquivo) a partir do título da versão (`## 1.2.0`, `## [1.2.0]` ou `## v1.2.0`) até o próximo título de mesmo nível ou superior, limitada a 20 KB:

```text
# Changelog

## [1.2.0]

- Export levels as glTF.
- Fix the collectible count in nested scenes.
```

As notas têm no máximo 20 KB de Markdown, são sanitizadas como um README e verificadas contra injeção de prompt como qualquer outro texto em um pacote. Um membro pode editá-las depois no painel do publicador. O índice assinado carrega os primeiros 4 KB, com um link para o restante.

## Canais: latest, beta e outros

Um canal (uma dist-tag) nomeia a versão que os usuários recebem quando a pedem pelo nome:

```bash
gamedev pkg add acme.level-tools          # the latest channel
gamedev pkg add acme.level-tools@beta     # whatever beta points to
```

- Uma pré-release (`1.3.0-beta.1`) nunca é instalada por padrão: `latest` é a versão estável publicada mais alta, a menos que você a defina, e ela nunca pode apontar para uma pré-release.
- Os outros canais você nomeia (`beta`, `next`, `nightly`): letras minúsculas, começando com uma letra, até 16 caracteres. Um pacote tem no máximo 5 canais, incluindo `latest`.
- Uma versão com yank ou revogada não pode receber tag; um canal que aponta para uma versão que recebe yank é removido.
- Publique uma pré-release como pré-release semver (`1.3.0-beta.2`). Uma pré-release chamada `alpha`, `beta`, `rc`, `next`, `preview`, `canary`, `nightly`, `dev` ou `experimental` move esse canal para si automaticamente, a menos que um membro tenha definido o canal manualmente; qualquer canal também pode ser movido no painel do publicador (**Channels**).
- `gamedev pkg add acme.level-tools@beta` grava o canal em `packages.json`, `{ "source": "^1.3.0-beta.1", "channel": "beta" }`. Os testadores recebem a versão do canal enquanto ela for mais nova que a mais recente estável, e passam para a versão estável assim que ela sai, na atualização seguinte.

## Descontinuar um pacote ou uma versão

A descontinuação avisa os usuários para seguirem em frente sem quebrar nada que já está instalado:

- **Um pacote:** uma mensagem (de até 300 caracteres) e, opcionalmente, o id de um pacote substituto. O app e a CLI mostram a mensagem e o substituto; as cópias instaladas continuam funcionando e o pacote ainda pode ser adicionado.
- **Uma versão:** uma mensagem como "perda de dados ao exportar cenas aninhadas, atualize para 1.2.1".

Ao escolher uma versão, o app prefere uma que não esteja descontinuada. Os dois tipos são reversíveis e ficam registrados no log de auditoria do registro. Defina-os no painel do publicador.

## Yank e revogação

Faça yank de uma versão que você publicou por engano: os intervalos de versão passam a ignorá-la a partir daí, e as instalações que já a têm continuam com ela. O yank é reversível, e um token de publicador pode fazer yank. A revogação é o kill switch do AI Game Dev para uma versão maliciosa ou roubada: ela sai do índice e todo app que a tem a desativa na próxima leitura do índice.

## Publicar a partir de CI

Duas formas, ambas mostradas em [Publicação Confiável](https://ai-game.dev/pt-br/docs/wiki/app/trusted-publishing):

- **Publicação Confiável (recomendada):** o GitHub Actions ou o GitLab CI comprova qual repositório e workflow está publicando; nenhum segredo é armazenado em lugar nenhum e cada versão registra sua proveniência. Uma GitHub Action e um template de GitLab CI prontos, [IvanMurzak/gamedev-publish-action](https://github.com/IvanMurzak/gamedev-publish-action), são descritos lá.
- **Um token de publicador:** `gamedev pkg publisher token create acme --label ci --days 90`, armazenado como um segredo de CI e passado como `AI_GAME_DEV_PUBLISHER_TOKEN`.

## O painel do publicador

Tudo o que um publicador gerencia depois do primeiro envio está no painel do publicador em [ai-game.dev/publisher](https://ai-game.dev/publisher), para proprietários e mantenedores conectados: seus publicadores e pacotes, cada versão com seu estado e relatório de verificação, notas de versão, canais, descontinuação e yank, membros e funções, tokens de publicador e publicadores confiáveis com trechos de workflow para copiar. Veja [Regras e verificações do registro](https://ai-game.dev/pt-br/docs/wiki/app/package-registry#panel).

## Outras fontes: GitHub, npm e pastas

O registro não é a única forma de compartilhar um pacote. Essas fontes instalam sem as verificações do registro, então rode `gamedev pkg validate` você mesmo, e elas são a forma de compartilhar um pacote que usa API proposta:

```bash
gamedev pkg add github:acme/level-tools           # the default branch: moves with each push
gamedev pkg add github:acme/level-tools@v1.2.0    # a tag: pinned, never auto-updated
gamedev pkg add npm:acme-level-tools@^1.2.0       # an npm package and range
gamedev pkg add file:../level-tools               # a folder
```

- **GitHub:** com uma tag, o app baixa um asset de release cujo nome termina em `.aigd.tgz` (anexe o arquivo que o `gamedev pkg pack` gerou); caso contrário, o repositório naquele commit, então `aigd-package.json` precisa estar na raiz e `dist/` precisa estar commitado.
- **npm:** faça `npm publish` da pasta do pacote. O arquivo npm precisa conter `aigd-package.json` e `dist/`; adicione `"engines": { "aigd": "<range>" }` ao `package.json` também, para que o app pule as versões que não consegue executar sem baixá-las.
- **Equipes:** adicione o pacote no nível de Projeto para que ele seja commitado em `.ai-game-dev/packages.json` e cada colega de equipe receba a mesma versão, fixada pelo lock file do projeto.

## Páginas relacionadas

- [Publicação Confiável](https://ai-game.dev/pt-br/docs/wiki/app/trusted-publishing) para CI sem um segredo armazenado.
- [Regras e verificações do registro](https://ai-game.dev/pt-br/docs/wiki/app/package-registry) para saber o que as verificações recusam.
- [Referência da CLI de pacotes](https://ai-game.dev/pt-br/docs/wiki/app/package-cli#publish) para todas as opções de `publish`.

---

Source (HTML): https://ai-game.dev/pt-br/docs/wiki/app/publishing-packages

Machine-translated (pt-BR) from the English page: https://ai-game.dev/docs/wiki/app/publishing-packages
