---
id: AGD-0072
ticket: blitz3d-engineering-lessons
title: Licoes de engenharia do Blitz3D para o Prometeu
status: open
created: 2026-11-04
resolved:
decision:
tags: [architecture, runtime, tooling, research]
---

## Contexto

**Worker:** Agenda Worker. **Dominio owner:** `runtime`, pesquisa comparativa de mecanismos internos da maquina, fronteiras de execucao e provider de metadata.

O usuario pediu uma analise do Blitz3D e esclareceu o objetivo: extrair licoes de engenharia de um engine experiente. Em 2026-11-04, solicitou separar runtime e Studio. Esta agenda conserva as ideias pertinentes ao runtime; autoria, core/SDK e ferramentas foram transferidos para [DSC-0100 / AGD-0102 no Studio](../../../../studio/discussion/workflow/agendas/AGD-0102-licoes-do-blitz3d-para-autoria-e-ferramentas.md).

Base examinada:

- Blitz3D: commit [`f132a78c9f2da255905bf477cb845994324b865a`](https://github.com/blitz-research/blitz3d_soloud/commit/f132a78c9f2da255905bf477cb845994324b865a), datado de 2024-10-19, resolvido a partir de `main` na consulta de 2026-11-04.
- Prometeu runtime: checkout `a4bec5bc4577850543f57c79f5124ca00169e1b3`, specs de GFX, audio, Registry/PBX, tempo, assets, portabilidade e debugging; composer/cache, audio desktop e catalogos nativos.
- Metodo: leitura estatica de fontes, exemplos e build metadata. O Blitz3D nao foi compilado ou executado; nao foram medidos desempenho ou qualidade perceptual.

O runtime ja possui separacao entre producao logica e render, publicacao de comandos de audio, recursos com identidade/geracao e catalogos nativos. A comparacao procura mecanismos uteis para pensar essas responsabilidades e contraexemplos para verificar suas fronteiras. Nao parte da premissa de que exista uma falha equivalente no Prometeu.

## Problema

Quais escolhas do Blitz3D ajudam a avaliar validade de caches, compartilhamento de recursos, publicacao, isolamento entre fases, limites de trabalho e seguranca do runtime?

A avaliacao separa fato observado, licao inferida, aplicabilidade local e limite da evidencia. Conveniencias de linguagem, assinatura apresentada ao autor e bibliotecas de gameplay sao responsabilidades da agenda de Studio.

## Pontos Criticos

### 1. Um cache precisa declarar de que mudanca depende

**Fato:** [`Surface::Monitor`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/blitz3d/surface.h) distingue alteracoes geometricas e de material. [`MeshModel::Rep`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/blitz3d/meshmodel.cpp) compara `geom_changes` com `box_valid`, `coll_valid` e `norms_valid`, reconstruindo bounding box, collider ou normais quando necessario. [`Entity`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/blitz3d/entity.cpp) invalida transforms descendentes e recompõe o resultado sob demanda.

**Licao:** a parte decisiva do cache e seu protocolo de validade: dependencias, evento invalidante e momento de reconstrucao. Contadores separados evitam tratar toda alteracao como mudanca de tudo.

**Aplicabilidade:** comparar esse modelo com `SceneViewportCache`, `SceneViewportResolver`, recursos de glyph/paleta e seus consumidores. O Prometeu ja atualiza linhas, colunas e regioes; a investigacao util e procurar invalidacao excessiva ou dependencias esquecidas em troca/reload de banco. E uma hipotese de revisao, nao um defeito demonstrado.

**Limite:** lazy rebuild pode concentrar trabalho no primeiro uso. Na fronteira assincrona Prometeu, ele precisa ocorrer no owner correto e nao pode exigir acesso mutavel do render ao estado vivo da VM. Em [`Surface::getMesh`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/blitz3d/surface.cpp), apesar dos marcadores de validade, o caminho ativo zera ambos antes do upload quando detecta trabalho. A existencia de dirty flags nao prova atualizacao parcial efetiva.

### 2. Dado compartilhado e configuracao da instancia merecem vidas distintas

**Fato:** [`CachedTexture`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/blitz3d/cachedtexture.cpp) compartilha frames por uma chave que considera arquivo, flags, dimensoes e recorte de animacao. [`Brush::write`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/blitz3d/brush.cpp) separa a representacao compartilhada quando uma copia precisa ser modificada.

**Licao:** copias baratas precisam de semantica de alias explicita. Compartilhar o payload e diferente de compartilhar toda configuracao mutavel. Uma chave de cache deve incluir os parametros que alteram o resultado.

**Aplicabilidade:** manter clara a distincao entre identidade do asset, residencia do banco, payload retido e parametros de cada uso. O modelo de samples imutaveis e owners retidos do Prometeu ja aplica parte dessa separacao. Copy-on-write e uma ferramenta possivel para descritores internos; nao e uma mudanca proposta para a semantica de objetos guest.

**Limite:** busca por path e refcount manual sao detalhes historicos, nao metas. Identidade por `asset_id`/geracao e as regras publicadas de unload devem continuar sendo avaliadas pelo contrato Prometeu. Compartilhamento tambem pode reter memoria e mover custo para a primeira escrita.

### 3. Atualizacao e apresentacao sao fases diferentes, mas a separacao deve ser real

**Fato:** [`World`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/blitz3d/world.cpp) oferece `update`, `capture` e `render(tween)`. [`Object::capture` e `beginRender`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/blitz3d/object.cpp) preservam posicao/escala/rotacao e calculam transforms interpolados separados, usando interpolacao linear e quaternion slerp.

**Licao:** o estado simulado pode ser autoritativo enquanto a apresentacao usa um estado derivado. Isso ajuda a raciocinar sobre velocidades de simulacao e apresentacao diferentes.

**Aplicabilidade:** reforca o frame logico de 60 Hz, os snapshots fechados e a apresentacao host-owned do Prometeu. Interpolacao visual seria uma escolha adicional, dependente de necessidade real e de contrato proprio; o exemplo nao demonstra que ela seja necessaria ao pixel art atual.

**Contraponto concreto:** `Object::beginRender` chama `updateSounds`; `World::render` atualiza listeners, e [`Listener::renderListener`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/blitz3d/listener.cpp) envia estado espacial ao audio. Parte do audio espacial depende, portanto, da chamada de render e da enumeracao de objetos visiveis. O aprendizado para o Prometeu e verificar que render descartado, pausa de apresentacao ou execucao headless nao governem trabalho de simulacao/audio por acidente. Nao se afirma que um defeito equivalente exista aqui.

### 4. Configure a reproducao antes de torna-la observavel

**Fato:** em [`bbaudio_soloud.cpp`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/bbruntime/bbaudio_soloud.cpp), `Sound` representa material/defaults e `channel` identifica uma reproducao. Quando existe pitch customizado, `bbPlaySound` inicia a voz pausada, ajusta o sample rate e so depois libera a reproducao. Musica usa `WavStream`, enquanto efeitos usam `Wav`.

**Licao:** preparar uma operacao e publica-la sao momentos distintos. Evitar observacao de estado parcialmente configurado pode ser mais importante que a simplicidade de cada setter. A separacao entre material e reproducao tambem deixa claras as responsabilidades dos controles.

**Aplicabilidade:** o `play` Prometeu ja fornece todos os parametros e o mixer consome comandos publicados. O padrao do Blitz reforca essa escolha. Streaming ensina que musica longa possui outro perfil de residencia e I/O; a necessidade concreta deve preceder qualquer proposta de novo servico.

**Limite:** o adapter do Blitz nao estabelece as garantias de callback, backpressure, pausas por sessao e reclamacao fora do callback presentes no contrato Prometeu. O simples uso de SoLoud nao resolve essas responsabilidades. Defaults mutaveis de `Sound` tambem diferem dos samples imutaveis atuais.

### 5. Limites de trabalho e fallback fazem parte de um algoritmo

**Fato:** o solver de [`World`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/blitz3d/world.cpp) limita tentativas com `MAX_HITS=10` e restaura a posicao inicial ao atingir o limite. [`MeshCollider`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/blitz3d/meshcollider.cpp) descarta candidatos por uma hierarquia de AABBs antes de testar triangulos. A hierarquia e interna a cada mesh; as listas de objetos por tipo nao constituem um broad phase espacial global.

**Licao:** limitar trabalho, definir comportamento de esgotamento e distinguir filtragem barata de trabalho detalhado sao responsabilidades explicitas do algoritmo. A presenca de uma aceleracao local nao demonstra que o custo do sistema inteiro esteja limitado.

**Aplicabilidade:** usar esse exemplo como criterio de revisao dos mecanismos nativos que ja possuem quotas e limites: verificar a unidade de trabalho, onde o custo aparece, o estado preservado em recusa e a ausencia de efeitos parciais indevidos. Um algoritmo nativo novo precisaria definir esses aspectos antes de ser proposto como contrato de maquina.

**Limite e transferencia:** overlap/sweep 2D, movimento contra tilemap e respostas de gameplay passam para a pesquisa de core/SDK no Studio. Esta agenda nao propoe periferico de colisao, syscall, fisica ou 3D. Os limites e epsilons do Blitz nao sao valores recomendados para o Prometeu.

### 6. Metadata do provider precisa de autoridade e representacao explicitas

**Fato:** o Blitz registra interfaces em `rtSym` e as expoe por [`Runtime::nextSym`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/bbruntime_dll/bbruntime_dll.cpp). O Prometeu ja oferece [`syscalls::catalogue()`](../../../crates/console/prometeu-hal/src/syscalls.rs), `intrinsic_catalog()` e [exportacao de catalogos](../../../crates/console/prometeu-vm/src/catalog.rs).

**Licao:** metadata com owner conhecido torna observavel o contrato que um consumer pretende usar. Identidade, ABI, custos e efeitos precisam permanecer coerentes com execucao e validacao; representacao compartilhavel nao significa compartilhar ponteiros ou layouts nativos.

**Aplicabilidade:** manter a distincao entre catalogo de intrinsics, catalogo de syscalls e Registry por imagem. Qualquer investigacao deve verificar a fidelidade do provider e suas evidencias de exportacao, sem presumir que catalogos distintos tenham os mesmos campos ou finalidade.

**Limite e transferencia:** porte do catalogo para Java, declaracoes SDK, nomes de parametros PBS, hover, completion, signature help e documentacao da API pertencem ao Studio. A pesquisa de coerencia desses consumidores foi transferida integralmente; nao e obrigacao de implementacao desta agenda. Nenhuma mudanca de formato de catalogo e proposta aqui.

### 7. Validacao da maquina e independente da experiencia de debug

**Fato:** verificacoes de existencia de banco e limites em [`bbbank.cpp`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/bbruntime/bbbank.cpp) sao condicionadas a `debug`. O debugger Blitz tambem acessa declaracoes e estruturas do compilador por ponteiros.

**Licao:** informacao adicional de debug e validacao obrigatoria sao responsabilidades diferentes. A maquina precisa conservar suas regras de seguranca em todos os modos; representacoes consumidas fora do owner devem ter um contrato proprio.

**Aplicabilidade:** usar esse contraponto para avaliar loader/verifier, handles, limites e interpretacao de metadata/faults existentes, preservando o resultado logico entre modos. O runtime recebe metadados PBX e fornece contexto de execucao e faults pelos contratos publicados; isso nao o torna owner da sintaxe de origem ou da UI.

**Limite e transferencia:** emissao de nomes/spans pelo compilador e apresentacao de diagnosticos ao autor pertencem ao Studio. A agenda de Studio conserva os exemplos de `StmtNode::debug` e `debugtree.cpp`. Nenhuma perda de origem ou divergencia de validacao foi demonstrada no Prometeu por esta pesquisa.

## Opcoes

### Opcao A - Aprofundar caches e ownership a partir de um workload

- **Abordagem:** seguir invalidacao, retencao e reconstrucao no composer/asset/audio atual, motivado por uma carga ou erro observavel.
- **Pro:** compara mecanismos concretos disponiveis neste repositorio.
- **Contra:** pode nao encontrar problema; precisa medir antes de recomendar otimizacao.
- **Tradeoff:** melhor ponto de partida para investigacao interna com alvo delimitado.

### Opcao B - Examinar fronteiras e publicacao em cenarios adversos

- **Abordagem:** usar render descartado, pausa, headless e esgotamento de trabalho para revisar independencia entre fases e efeitos de comandos.
- **Pro:** aproveita os contraexemplos concretos do Blitz e os contratos ja publicados.
- **Contra:** uma revisao ampla pode repetir evidencia existente sem acrescentar informacao.
- **Tradeoff:** escolher somente um cenario com duvida concreta, preservando quotas, ordering e ownership vigentes.

### Opcao C - Reter a pesquisa como referencia para necessidades futuras

- **Abordagem:** manter mecanismos e limites documentados, retomando quando houver proposta ou problema correspondente.
- **Pro:** evita inventar trabalho sem evidencia de necessidade.
- **Contra:** nao produz uma nova medicao ou revisao interna agora.
- **Tradeoff:** adequada enquanto os achados apenas corroborarem o desenho atual.

## Sugestao / Recomendacao

Manter **C** como estado desta pesquisa. Se surgir problema observavel de custo/retencao, priorizar **A**. Se a duvida for acoplamento ou ordem entre fases, selecionar um cenario de **B**.

Os aprendizados mais diretamente transferiveis ao runtime sao protocolos de validade de cache, separacao entre payload e uso, preparacao antes da publicacao e limites com fallback explicito. As fronteiras fechadas de render e audio do Prometeu ja respondem a parte dos riscos observados no Blitz. Nao ha evidencia, nesta analise, que justifique substitui-las.

## Transferencia e Fronteiras de Responsabilidade

Separacao solicitada pelo usuario em 2026-11-04. Destino de autoria/ferramentas: [DSC-0100 / AGD-0102](../../../../studio/discussion/workflow/agendas/AGD-0102-licoes-do-blitz3d-para-autoria-e-ferramentas.md). Os IDs pertencem a indices independentes por repositorio.

| Tema da pesquisa original | Permanece no runtime | Responsabilidade transferida ao Studio |
| --- | --- | --- |
| API por tarefa completa | Somente respeito aos contratos de maquina consumidos | Ergonomia de linguagem/core/SDK, imports e percurso de autoria. |
| Metadata ate a IDE | Autoridade, representacao e fidelidade dos catalogos do provider | Porte/importacao, projecoes semanticas, ajuda e documentacao da API. |
| Caches e invalidacao | Protocolos de validade, dependencia e reconstrucao interna | Nenhuma investigacao interna de cache transferida. |
| Recursos compartilhados | Identidade, residencia, owners e parametros por uso | Eventuais abstracoes de instancia de core/SDK, quando houver caso de uso. |
| Atualizacao e apresentacao | Fases, snapshots, clocks e independencia do audio/render | Conveniencias de atualizacao/desenho de gameplay, respeitando suas discussoes locais. |
| Preparar audio antes de publicar | Comandos completos, publicacao, callback e reclamacao | Nenhuma entrega de audio SDK criada ou reativada. |
| Colisao e trabalho limitado | Principio de limite/fallback e custo das consultas | Hipoteses de helpers geometricos e respostas de gameplay em biblioteca. |
| Exemplos pequenos | Fornecimento dos contratos/host de execucao existentes | Ensino, corpus de autoria e encaminhamento de qualificacao instalada ao owner existente. |
| Debugging e origem | Validacao da maquina, leitura de metadata e faults | Emissao de origem pelo compilador e experiencia de diagnostico do autor. |

As perguntas e sugestoes de evidencia transferidas estao detalhadas na agenda de destino. A transferencia nao equivale a implementacao, validacao ou aceite tecnico. A agenda de runtime nao depende do fechamento de nenhuma agenda do Studio.

Escolha de host/backend continua com [DSC-0047 / AGD-0050](AGD-0050-portable-host-backend-strategy.md). Background service/media continua com [DSC-0045 / AGD-0048](AGD-0048-background-service-audio-execution.md). Esta pesquisa nao adiciona obrigacoes a essas discussoes.

Os achados continuam em agenda de pesquisa; nao sao publicados como `discussion/lessons/`, pois nao derivam de nova decisao executada no Prometeu.

## Perguntas em Aberto

- [ ] Existe workload ou erro observavel que justifique investigar invalidacao/reconstrucao de cache ou retencao de owners?
- [ ] Qual dependencia interna especifica merece revisao, e qual estado publicado permitiria demonstra-la?
- [ ] Ha cenario de render descartado, pausa ou headless cuja independencia de audio/simulacao ainda precise de evidencia?
- [ ] Algum mecanismo nativo tem limite de trabalho ou fallback ainda insuficientemente demonstrado?
- [ ] Ha inconsistencia concreta entre metadata exportada pelo provider e seu comportamento, sem confundir isso com a adaptacao feita pelos consumers?

## Criterio para Encerrar

A pesquisa comparativa esta entregue com fontes, aplicabilidade e limites. A separacao organizacional esta concluida quando a agenda Studio preservar os itens recebidos, os links cruzados resolverem e os dois workflows validarem.

Para uma futura decisao de mudanca no runtime, selecionar um problema concreto de sua responsabilidade, confirmar evidencia e fechar alternativas/comportamento. A pesquisa nao cria um plano de implementacao nem uma exigencia de alterar mecanismos que ja cumprem seu contrato.

## Proximo Passo Sugerido

Retomar o achado correspondente quando houver workload, defeito ou proposta concreta de runtime. Autoria e ferramentas prosseguem na agenda Studio, com escopo independente.

## Validacao da Pesquisa

- Leitura estatica em commit fixo; fontes originais preservadas entre as duas agendas.
- Implementacoes existentes de catalogos, snapshots, caches e staging reconhecidas explicitamente.
- Sem benchmarks, teste de execucao ou avaliacao perceptual do Blitz.
- Separacao editorial de agendas; nenhuma alteracao em specs ou implementacao e nenhum item transferido marcado como executado.
