API de scripting: paridade e roadmap
Uma superfície de scripting, duas linguagens: o que Lua e Dryad fazem hoje, o que foi adicionado nesta passagem e o plano ordenado para crescer a API sem deixar as duas divergir.
1. Regras de desenho#
- Um nome, um significado. Cada capacidade existe nas duas linguagens com nomes paralelos:
Lua
caffeine.<área>.<verbo>, Dryadcaffeine_<área>_<verbo>. As tabelas de nomes (teclas, eixos e ações) são C++ partilhado (ScriptInputNames.hpp), por isso ambas aceitam as mesmas strings. - Bindings finos. A lógica vive nos módulos do engine; um binding valida argumentos, chama-a e regista erros. Os natives nunca falham com um id inválido, sem mundo ou com um nome desconhecido.
- Reflexão primeiro. Os dados de componentes passam por
caffeine.component/caffeine_component_*, guiados pelo registo de reflexão, por isso novos componentes ficam scriptáveis sem novos bindings. - As mensagens continuam o único caminho de mutação do editor. Os scripts atuam no mundo de jogo, não no estado do editor.
- Uma funcionalidade está pronta quando tem teste nas duas linguagens (
tests/test_script.cpp,tests/test_dryad_host.cpp).
2. Matriz de paridade#
| Área | Lua | Dryad |
|---|---|---|
Lifecycle onCreate, onUpdate, onFixedUpdate |
sim | yes |
onDestroy, onCollision, onPostProcess |
sim | não |
| Position and scale | sim | sim (caffeine_get/set_position, scale, translate) |
| Generic components (reflection) | sim | yes |
Time (delta, time, fixedDelta, scale, pause, frame) |
sim | novo (caffeine_time_*) |
| Input (keys, axes, actions, mouse) | sim | novo (caffeine_input_*) |
| World create, destroy, alive, distance | parcial | novo (caffeine_world_*) |
| Math: 2D and 3D vectors, scalar helpers | new 3D | Dryad stdlib |
| Events, UI, draw2d, picking, assets, native modules | sim | não |
| Post-process, animation, effects, navigation | sim | não |
3. Adicionado nesta passagem#
Natives do Dryad#
| Native | Devolve |
|---|---|
caffeine_time_delta(), _unscaled_delta(), _total(), _fixed_delta(), _scale(), _frame() |
segundos / escala / número do frame |
caffeine_time_set_scale(s), caffeine_time_paused(), caffeine_time_set_paused(b) |
controlo do tempo |
caffeine_input_key_down(name) |
bool |
caffeine_input_axis(name) |
-1..1 (Horizontal, Vertical, LookX, LookY) |
caffeine_input_action_down(name), _action_pressed(name) |
bool (premida, acabou de premir) |
caffeine_input_mouse_x(), _y(), _dx(), _dy(), _mouse_down(button) |
posição, delta, 1/2/3 |
caffeine_world_create([name]), _destroy(e), _is_alive(e), _distance(a, b) |
id, nada, bool, metros (1e9 se desconhecido) |
Lua math (caffeine.math)#
vec2, vec3, add, sub, mul, scale, dot, cross, length, lengthSquared, distance,
normalize, lerpVec, clamp, clamp01, lerp, inverseLerp, remap, smoothstep, approach, sign,
radians, degrees, pi, epsilon. As funções de vetor aceitam {x, y} ou {x, y, z}; o resultado só tem z
quando um operando o tem, por isso os scripts 2D existentes não mudam.
3b. O componente Script#
O ScriptComponent já não é só um caminho. Campos (todos no Inspector por reflexão e guardados na cena;
cenas antigas carregam com os valores por omissão):
| Campo | Omissão | Significado |
|---|---|---|
Script |
vazio | caminho .lua ou .dyd, relativo ao projeto |
Enabled |
ligado | um script desativado é ignorado por completo: sem onCreate, sem updates |
Order |
0 | o menor corre primeiro no frame; empates mantêm a ordem das entidades (estável) |
Properties |
vazio | overrides por entidade das variáveis expostas do script, ex.: speed=4.5; god=true; label=hi (Lua e Dryad) |
Isolated |
desligado | Lua: esta entidade corre a sua própria cópia do script, com globais privadas |
As entradas de Properties separam-se com ; ou nova linha. O valor é booleano para true/false, número
quando converte por inteiro e texto caso contrário; entradas malformadas são ignoradas. São aplicadas
antes de cada hook dessa entidade. Limites: sem Isolated, o estado Lua é partilhado por ficheiro, por isso
os overrides definem entradas, não dão globais privadas; o estado Dryad é sempre partilhado por ficheiro. As cópias
isoladas ainda não são libertadas quando a entidade é destruída.
Agrupar scripts#
Os scripts classificam-se em grupos e subgrupos, de duas formas (ScriptCatalog.hpp):
- Etiquetas no cabeçalho, nas primeiras 40 linhas, após
--,//ou#:@group Gameplay/Combat/Melee,@name Sword swing,@description ...,@tags weapon, player. - Pastas: sem
@group,scripts/Gameplay/AI/patrol.luafica no grupoGameplay/AI.
scanScripts(projectRoot) lê todos os .lua e .dyd em scripts/; buildScriptTree devolve uma árvore
ordenada (find("Gameplay/Combat"), totalScripts()), com os soltos em Ungrouped. Ainda não está ligado ao
painel Assets nem ao seletor de componentes; ver o roadmap.
3c. Cobertura: o que o engine tem e os scripts não alcançam#
O registo documenta agora todos os bindings (232 funções, 29 namespaces, ver a Referência da API). Comparada com os módulos do engine, a superfície scriptável ainda não tem:
| Módulo do engine | Scripts hoje | Em falta |
|---|---|---|
Física 3D (PhysicsWorld3D) |
caffeine.physics3d: raycast, forças, impulso, velocidade, gravidade |
consultas de overlap e callbacks de colisão/trigger. O runtime passa a correr o PhysicsSystem3D (antes não corria) |
Áudio (AudioSystem) |
caffeine.audio: play de WAV, 2D posicional, handles, volume, loop |
OGG/MP3, emissores 3D, o componente AudioEmitter, pitch por som |
| Cenas | caffeine.scene (load, reload, current) e caffeine.session (dados entre cenas), só na aplicação runtime |
carregamento aditivo, transições, o modo play do editor |
| Câmara e luzes | componentes via caffeine.component |
helpers: screenToRay, worldToScreen, look-at |
| Terreno, água, fluidos | só componentes | consultas de altura, water_height, pintura de splat |
| Prefabs | nenhum | instanciar com overrides |
| Assets | só texto | carregar texturas, malhas, materiais; hooks de hot reload |
| Photon e render features | forward-render e post-process | qualidade do Photon, controlos de reflexos e probes |
| Corrotinas e temporizadores | nenhum | after, every, wait |
| Dados de save, JSON, utilitários de texto | nenhum | armazenamento persistente, parsing |
Acrescentado até agora: caffeine.entity (nomes, procura), caffeine.hierarchy (pai, filhos, raiz, sem ciclos),
caffeine.random (determinístico), cada um em Lua e Dryad a partir de uma implementação partilhada.
4. Roadmap#
Cada passo chega com testes nas duas linguagens e uma página nesta secção.
Fase S1 — Fechar as lacunas de paridade#
- [ ]
onDestroy,onCollision(entity, other)eonPostProcessno Dryad; despacho a partir doScriptSystem. - [ ] Eventos no Dryad:
caffeine_events_emit/on/offsobre oEventBus. - [ ]
caffeine.world.hasComponentdo Lua via registo de reflexão (hoje só conhece quatro nomes). - [x] Procura por nome e hierarquia (
caffeine.entity,caffeine.hierarchy); faltafindWith(component). - [ ] Prefabs:
instantiate(prefab, position),destroyAfter(entity, seconds).
Fase S2 — Estrutura e ergonomia#
- [ ] Objeto de entidade no Lua (
local e = caffeine.entity(id),e:position(),e:get("Light")) sobre os mesmos natives, mais userdataVec3eQuatcom operadores, em vez de tabelas simples. - [ ] Temporizadores e corrotinas:
caffeine.timer.after/every/cancel,caffeine.wait(seconds)num agendador de corrotinas movido peloScriptSystem; o equivalente Dryad como natives. - [x] Overrides por entidade das variáveis expostas (
Properties), só Lua; falta o Dryad. - [ ] Sistema de módulos para o Dryad (
import) resolvido a partir da raiz do projeto, como ocaffeine.require. - [ ] Relatório de erros: nome do script, linha e uma entrada na Consola por cada falha, nunca um no-op silencioso.
Fase S3 — Superfície de gameplay 3D#
- [ ] Física 3D:
raycast,overlapSphere,addForce,setVelocity, callbacks de colisão e trigger. - [ ] Câmara e picking em 3D:
screenToRay,worldToScreen,pick3d. - [ ] Áudio:
play,stop,setVolume, fontes 3D. - [ ] Paridade de animação, navegação e efeitos no Dryad.
- [ ] Controlo de cenas:
loadScene,reloadScene, valores persistentes entre cenas.
Fase S4 — Ferramentas#
- [x] Referência da API gerada a partir de um registo (
src/caffeine/script/api/*.json), verificado por um teste; faltam o autocompletar no editor e a matriz de paridade gerada. - [ ] Limites de sandbox: orçamento de instruções por frame, limite de memória, watchdog de scripts presos.
- [ ] Hot reload que mantém o estado do script onde as variáveis expostas o permitem.
- [ ] Depuração: breakpoints e vista de variáveis no editor de scripts (Lua primeiro).
- [ ] Mostrar a árvore de grupos de scripts no painel Assets e no seletor Add Component; filtro por grupo e pesquisa por etiqueta.