---
id: AGD-0102
ticket: blitz3d-studio-engineering-lessons
title: Licoes do Blitz3D para autoria e ferramentas
status: open
created: 2026-11-04
resolved:
decision:
tags: [studio, compiler, pbs, sdk, research]
---

## Contexto

**Worker:** Agenda Worker. **Dominio owner:** `studio`, pesquisa de experiencia de autoria. **Interfaces:** `compiler/general` para metadata, emissao e diagnosticos comuns; `compiler/pbs` para linguagem, core/SDK e projecoes editoriais.

O usuario solicitou separar as licoes do Blitz3D entre runtime e Studio em 2026-11-04. Esta agenda recebe o conteudo de autoria/ferramentas da [agenda do runtime AGD-0072 / DSC-0069](../../../../runtime/discussion/workflow/agendas/AGD-0072-licoes-de-engenharia-do-blitz3d-para-o-prometeu.md). O objetivo e aprendizado de engenharia a partir de codigo existente.

Base da pesquisa: [`blitz-research/blitz3d_soloud`, commit `f132a78c9f2da255905bf477cb845994324b865a`](https://github.com/blitz-research/blitz3d_soloud/commit/f132a78c9f2da255905bf477cb845994324b865a), datado de 2024-10-19. Analise estatica; o engine nao foi compilado ou executado. Contexto local consultado: checkout Studio `1d8b8c21014b5b2e94bcd6621dbea177afc0d4eb`, specs de PBS, catalogos, atribuicao de debug e agendas ativas. Nenhuma implementacao foi auditada integralmente ou qualificada nesta transferencia.

O runtime conserva caches, ownership de recursos, fases de execucao/render/audio, publicacao de comandos, limites de trabalho e validacao da maquina. Esta agenda concentra a experiencia de quem escreve, compila, compreende e executa jogos pelo Studio.

## Problema

Como aproveitar a experiencia do Blitz3D para tornar tarefas comuns de jogo compreensiveis e concisas, mantendo coerencia entre SDK, compilador, ajuda editorial e resultado executado?

O Studio ja possui catalogos versionados, metadata semantica para parametros, signature help, exemplos instalados e discussoes proprias de sprites/animação, composicao e qualificacao de jogo. A comparacao precisa identificar ganhos concretos sobre essa base. A existencia de um padrao interessante no Blitz nao demonstra uma lacuna no Studio.

## Pontos Criticos

### 1. Ergonomia de uma tarefa completa

**Fato:** os tutoriais de [movimento](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/BLITZ3D_INSTALL/tutorials/GCUK_Tuts/movement.bb) e [colisao](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/BLITZ3D_INSTALL/tutorials/GCUK_Tuts/collision.bb) conectam criacao, configuracao, input/movimento, atualizacao, desenho e consulta de contato em programas curtos.

**Licao:** avaliar a superficie publica pela tarefa que o autor consegue concluir, incluindo imports, recursos, inicializacao, parametros e erros. A quantidade de primitivas disponiveis nao mede esse percurso.

**Aplicabilidade:** comparar pequenos exemplos PBS de mover personagem, consultar representacao visual, avancar animacao, emitir desenho e persistir estado. Usar os principios ja publicados na [Language Charter](../../../docs/specs/compiler-languages/pbs/1.%20Language%20Charter.md). Identificar precisamente se eventual atrito pertence a linguagem, core, SDK, projeto ou UI.

**Limite:** simplicidade no chamador nao autoriza novo syscall, estado oculto ou alteracao do modelo de ciclos. A separacao entre avancar animacao e emitir desenho deve respeitar as discussoes locais existentes.

### 2. Coerencia entre assinatura aceita e ajuda exibida

**Fato:** [`blitz/libs.cpp`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/blitz/libs.cpp) transforma registros do runtime em declaracoes do compilador; [`blitz/main.cpp`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/blitz/main.cpp) exporta sintaxe com `+k`; [`blitzide/libs.cpp`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/blitzide/libs.cpp) usa essa saida para keywords e ajuda rapida.

**Licao:** as ferramentas devem explicar a mesma API que o compilador aceita, com origem e responsabilidade de cada metadado claras.

**Aplicabilidade:** seguir um callable real por declaracao SDK/core, modelo semantico, compilacao, hover, completion e signature help. O Studio ja tem `FrontendSignatureHelp`, `PbsEditorialSignatureHelp` e nomes canonicos no modelo semantico. Investigar divergencias demonstradas nesses caminhos, aproveitando o contrato existente.

**Limite normativo:** [Runtime Catalog Support](../../../docs/specs/compiler/24.%20Runtime%20Catalog%20Support%20Specification.md) exige catalogos locais versionados, porte manual dos consumidores e verificacao independente. Esta pesquisa preserva essa escolha: nao propoe geracao automatica de enums, parser de Rust, consulta ao checkout irmao em builds normais ou uma nova fonte de autoridade. Nomes de parametros da API PBS pertencem ao modelo semantico; ABI, custos e efeitos do provider continuam runtime-owned. O aprendizado do Blitz e a coerencia observavel, nao seu formato compacto de assinaturas.

### 3. Exemplos pequenos como instrumentos de ensino e avaliacao

**Fato:** `BLITZ3D_INSTALL` contem tutoriais isolados, samples visuais, jogos e um media viewer. O tutorial de colisao exercita uma cadeia de uso completa.

**Licao:** exemplos pequenos tornam o modelo ensinavel e revelam boilerplate, imports dificeis e combinacoes pouco naturais entre APIs. Um sample ganha valor de regressao quando tem caminho de execucao e resultado esperado definidos.

**Aplicabilidade:** aproveitar o corpus ja existente em `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/resources/pbs-knowledge/examples/game/1/`, incluindo input/main, colecoes, lifecycle e memcard. Identificar uma tarefa mal explicada ou sem exemplo antes de criar outro corpus. Distinguir compilacao do fonte, empacotamento instalado e execucao do PBX resultante.

**Limite:** a [qualificacao do jogo de referencia](AGD-0088-studio-reference-game-qualification.md) ja e owner da prova integrada instalada. Esta agenda recebe criterios de ergonomia e aprendizado, sem absorver aquela entrega ou acrescentar seus gates. Audio permanece fora da wave dessa qualificacao, conforme sua revisao de escopo; o exemplo de audio do Blitz nao reativa a integracao de audio abandonada.

### 4. Helpers de gameplay pertencem primeiro a core/SDK

**Fato:** [`World`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/blitz3d/world.cpp) organiza regras direcionais de colisao, consultas sobre movimento e respostas de parar/deslizar. [`Object`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/blitz3d/object.cpp) separa captura de estado e representacao interpolada.

**Licao:** uma camada de conveniencia pode combinar poucos mecanismos com comportamento explicito para resolver tarefas frequentes. Consulta, avancar estado e emitir desenho devem ter efeitos reconheciveis.

**Aplicabilidade:** investigar bibliotecas PBS de gameplay apenas a partir de um exemplo que demonstre necessidade: overlap/sweep 2D, movimento contra tilemap ou outra operacao pequena. Declarar ordem, custos, limites, resultados e fallback. Dados compartilhados e estado por instancia tambem podem orientar tipos de SDK, sem herdar implicitamente copy-on-write ou semantica de alias do C++.

**Limite e ownership:** Sprite/Animator pertencem a [DSC-0098 / AGD-0100](AGD-0100-pbs-core-sprite-and-animation.md); a abstracao de emissao pertence a [DSC-0099 / AGD-0101](AGD-0101-pbs-composer-facing-blitable-contract.md). Esta agenda nao escolhe API, modifica essas discussoes, exige sua conclusao ou inclui implementacao de colisao nelas. Helpers geometricos futuros precisam de escopo proprio quando houver demanda. Novas capacidades da maquina exigiriam handoff separado ao runtime, nunca uma dependencia presumida desta pesquisa.

### 5. Preservar a explicacao do programa ate o diagnostico

**Fato:** [`StmtNode::debug`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/compiler/stmtnode.cpp) emite hooks com posicao de origem; [`debugtree.cpp`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/debugger/debugtree.cpp) usa tipos e declaracoes para exibir variaveis e campos.

**Licao:** uma ferramenta precisa conservar origem, nomes e contexto suficientes para explicar o que falhou. Correcao do bytecode nao estabelece a qualidade dessa explicacao.

**Aplicabilidade:** seguir um erro atribuivel ao fonte por frontend, IR, PBX e retorno host/UI/MCP, verificando se a localizacao e a categoria sobrevivem. A [spec de emissao](../../../docs/specs/compiler/15.%20Bytecode%20and%20PBX%20Mapping%20Specification.md) ja exige `function_names` e `pc_to_span` minimos; nao tratar sua existencia como funcionalidade faltante. `BytecodeModule` ja carrega `DebugInfo`.

**Limite:** o acoplamento do debugger Blitz a ponteiros/estruturas do compilador e um contraponto, nao recomendacao de ABI. A emissao e apresentacao da origem pertencem ao Studio; a interpretacao dos metadados, faults e seguranca da execucao permanecem com o runtime. Load errors nao devem receber PC de instrucao executada inventado. O debug workspace/consumer externo conserva suas responsabilidades proprias; esta agenda nao incorpora trabalho daquele repositorio.

## Transferencia e Interfaces

| Tema recebido da pesquisa original | Owner e alvo de investigacao | Evidencia proposta para eventual aprofundamento |
| --- | --- | --- |
| APIs por tarefa completa | `compiler/pbs`: core/SDK, imports/barrels e exemplos PBS | Fonte curto pelo caminho real, efeitos e erros explicitos; comparar a tarefa antes/depois de qualquer proposta. |
| Assinaturas e ajuda coerentes | `compiler/general` + `compiler/pbs`: consumidores do catalogo, metadata semantica, `FrontendSignatureHelp`, LSP | A mesma chamada apresenta nomes/tipos/ordem consistentes na compilacao e nas superficies editoriais; preservar catalogos e porte manual publicados. |
| Exemplos ensinaveis e executaveis | `studio` + `compiler/pbs`: knowledge/examples instalados; handoff de prova integrada a DSC-0086 | Identificar fonte e distribuicao, compilar exemplo real e definir resultado esperado; nao chamar simples paridade de JAR de execucao do jogo. |
| Helpers de gameplay | `compiler/pbs`: bibliotecas sobre os contratos atuais | Demonstrar necessidade e camada responsavel, com ordem/limite/fallback; encaminhar sprites/composicao aos owners existentes. |
| Origem e diagnosticos do autor | `compiler/general` + `studio`: `DebugInfo`, atribuicao e retorno UI/MCP | Preservar origem real e categoria ao longo do pipeline; registrar lacuna concreta quando existir, sem inventar spans/PCs. |

Esta tabela transfere perguntas e sugestoes de evidencia. Nao declara implementacao, aceite tecnico ou novo gate mandatorio. Contratos publicados e discussoes existentes conservam sua autoridade. Os dois repositorios mantem indices e IDs independentes.

## Opcoes

### Opcao A - Comparacao focada de uma tarefa de autoria

- **Abordagem:** selecionar uma tarefa pequena e seguir sua API, metadata, ajuda e exemplo pelos mecanismos existentes.
- **Pro:** produz evidencia concreta com escopo curto e reaproveita entregas existentes.
- **Contra:** uma tarefa pode nao representar todos os perfis de usuario.
- **Tradeoff:** melhor retorno inicial para distinguir qualidade de uso de cobertura de subsistema.

### Opcao B - Revisao transversal de metadata e diagnosticos

- **Abordagem:** avaliar varios tipos de callable e categorias de erro, mantendo fronteiras entre provider, compiler e editor.
- **Pro:** pode localizar divergencias sistematicas entre consumidores.
- **Contra:** exige corpus maior e pode repetir a qualificacao ja coberta por specs/testes.
- **Tradeoff:** apropriada quando houver divergencia ou relato concreto que justifique a amplitude.

### Opcao C - Expandir primeiro bibliotecas e exemplos de gameplay

- **Abordagem:** escolher um helper ainda necessario e amadurecer sua API em agenda propria.
- **Pro:** melhora diretamente a experiencia do autor quando a demanda e demonstrada.
- **Contra:** risco de criar abstracoes antes do caso de uso ou duplicar sprites/composicao.
- **Tradeoff:** depende de necessidade concreta e owner delimitado; nao e implementacao autorizada por esta transferencia.

## Sugestao / Recomendacao

Preferir **A**. O maior aprendizado do Blitz e oferecer um percurso curto entre intencao, codigo e feedback. Escolher uma tarefa suportada, comparar sua experiencia no Studio e registrar somente atritos reproduziveis.

Usar **B** quando a tarefa revelar divergencia de assinatura ou diagnostico. Considerar **C** apenas quando a dificuldade estiver na ausencia de uma composicao de gameplay, respeitando os owners de sprites/animação e emissao. O runtime permanece fornecedor dos contratos publicados; esta pesquisa de consumo pode avancar independentemente da agenda de runtime.

## Perguntas em Aberto

- [ ] Qual tarefa existente melhor representa a experiencia de autoria que se deseja avaliar?
- [ ] A eventual dificuldade esta em linguagem/core/SDK, descoberta editorial, projeto ou UI?
- [ ] Ha divergencia reproduzivel entre assinatura aceita e ajuda, ou a base atual ja cobre o achado do Blitz?
- [ ] Quais exemplos instalados precisam apenas de melhor explicacao e quais demonstram uma composicao ainda ausente?
- [ ] Existe demanda concreta de helper geometrico ou basta encaminhar os achados aos temas ativos de sprites/composicao?
- [ ] Algum erro perde sua origem real entre emissao e apresentacao? Em qual consumer e com qual fixture?

## Criterio para Encerrar

Para convergir em uma futura decision, selecionar uma dificuldade observada, identificar owner e superficies afetadas, comparar alternativas e definir resultado verificavel. Quando o caso estiver coberto, registrar a evidencia em vez de inventar uma mudanca.

A transferencia solicitada esta concluida quando esta agenda preservar as fontes e perguntas recebidas, a agenda do runtime contiver somente suas responsabilidades e os links entre ambas resolverem. Essa conclusao organizacional nao fecha tecnicamente as propostas nem autoriza implementacao.

## Proximo Passo Sugerido

Escolher um pequeno fluxo de autoria ja suportado e comparar codigo, feedback editorial e resultado executado, considerando as discussoes existentes. As capacidades ainda em debate devem continuar com seus owners.

## Validacao e Estado

- Pesquisa e transferencia de responsabilidade; agenda aberta.
- Sources do Blitz fixadas em commit, com fatos separados de aplicabilidade e limites.
- Contratos locais e escopos de agendas existentes consultados; nenhuma qualificacao de comportamento reivindicada.
- Sem mudancas em specs, SDK, compilador, runtime ou UI decorrentes desta transferencia.
