Pacotes

Esta página foi traduzida automaticamente e pode conter erros. Encontrou um problema? Use o link "Edit this page" para ajudar a corrigir.

Um pacote (package) é uma unidade de funcionalidade distribuível — qualquer combinação de assets, código-fonte Zig, bibliotecas nativas e plugins de runtime — que você pode instalar em um projeto sem copiar arquivos manualmente. É a resposta do Turian ao Package Manager e à Asset Store da Unity, construído sobre o próprio gerenciador de pacotes do Zig.

Status: o MVP entrega pacotes de assets de ponta a ponta (instalar → compilar → executar). Pacotes de código-fonte, nativos e plugins estão previstos no manifesto e serão disponibilizados em lançamentos futuros.

Conceitos

Termo Significado
Pacote A unidade de criação/distribuição: um manifesto turian-package.json mais assets, código-fonte, bibliotecas nativas e/ou um ponto de entrada de plugin.
OAP (.oap) O contêiner de assets de runtime processado (cooked) que seu jogo envia. Os assets de um pacote são processados na game.oap do projeto em tempo de compilação.
Módulo Uma unidade de compilação do Zig (b.addModule) — o equivalente ao asmdef da Unity.
Plugin O ponto de entrada de registro do pacote no runtime/editor.

A justificativa completa e o esquema estão disponíveis no ADR 0001.

project.json é a fonte da verdade

Todo projeto Turian possui um project.json que registra a identidade do projeto e suas dependências declaradas. O arquivo build.zig.zon do projeto é gerado a partir do project.json — semelhante a como a Unity e o Flax regeneram seus .csproj/.sln. Você nunca edita manualmente o build.zig.zon; a CLI e o Studio alteram o project.json e regeneram o ZON a cada compilação. Isso mantém o gerenciamento de dependências em um formato JSON familiar e seguro, gerando o ZON automaticamente e evitando erros de sintaxe.

{
  "turian_version": "0.16",
  "name": "My Game",
  "version": "0.0.0",
  "dependencies": {
    "com.acme.physics": { "url": "git+https://example.com/physics#v1.2.0", "hash": "..." }
  }
}

A resolução de dependências (versões, conflitos, hashes, o lockfile) é delegada ao gerenciador de pacotes do Zig. A camada do Turian adiciona o manifesto de integração com o engine, descoberta, injeção no pipeline de assets e verificações de compatibilidade do engine.

O manifesto: turian-package.json

Um pacote se declara com um turian-package.json em sua raiz:

{
  "name": "com.example.color-palette",
  "version": "1.0.0",
  "author": "Example",
  "description": "A sample asset-only package",
  "license": "MIT",
  "engine_compat": ">=1.0.0",
  "types": ["asset"],
  "assets": ["assets"]
}
Campo Obrigatório Notas
name ✓ DNS reverso, globalmente único.
version ✓ Semver.
types ✓ Um ou mais dentre asset, source, native, plugin.
assets Diretórios de assets relativos à raiz do pacote (padrão ["assets"]).
modules Módulos Zig exportados: { "name", "root" } (pacotes de código-fonte).
native Bibliotecas nativas: { "name", "kind", "lib", "include" }.
plugin Ponto de entrada de runtime: { "register", "entry" }.
engine_compat Intervalo semver verificado em relação à versão do engine em execução.
dependencies Mapeamento de nome do pacote → intervalo semver.

Instalando um pacote

# A partir de um diretório local
turian-cli package install ./path/to/package --project my-game

# A partir de um repositório git
turian-cli package install git+https://example.com/my-package --project my-game

Por padrão, os pacotes são instalados em um armazenamento central compartilhado entre todos os seus projetos — $TURIAN_PACKAGE_HOME, caso contrário ~/.cache/turian/packages (%APPDATA%\turian\packages no Windows) — organizado como <name>/<version>/ para que múltiplas versões coexistam. O projeto registra quais pacotes e versões ele utiliza no project.json; nada é duplicado por projeto. É assim também que uma empresa pode estruturar uma asset store interna: um único armazenamento compartilhado para muitos projetos.

Passe o parâmetro --vendored para copiar um pacote para <project>/packages/ (para commitá-lo junto com o projeto ou trabalhar offline). As cópias vendored (locais do projeto) têm precedência sobre o armazenamento central.

turian-cli package install ./pkg            # → armazenamento central (padrão)
turian-cli package install ./pkg --vendored # → <project>/packages/
turian-cli package list   --project my-game
turian-cli package info   com.example.color-palette --project my-game
turian-cli package remove com.example.color-palette --project my-game   # mantém a cópia no armazenamento compartilhado

O próximo turian-cli build descobre cada pacote instalado (armazenamento central + vendored) e processa (cook) seus assets na game.oap automaticamente — sem necessidade de cópia manual.

Os assets de pacotes instalados aparecem no Studio → Asset Browser sob uma seção Packages somente leitura: você os edita no pacote original, não no projeto que os consome.

Colisões e compatibilidade

  • Nomes de pacotes duplicados e GUIDs compartilhados entre dois pacotes resultam em erros fatais (hard errors) que interrompem o build com um diagnóstico claro — os autores de pacotes devem manter os GUIDs dos assets globalmente únicos.
  • Um pacote cujo intervalo engine_compat exclui a versão do engine em execução gera um aviso (mas o build ainda prossegue).

← Toda a documentação Editar esta página