Runtime capabilities — patch notes
A patch note from 2026-10-14 describing the picking, overlay, map surface, sprite LOD and native-module work of that period, with its migration checklist.
Date: 2026-10-14 Scope: Caffeine engine core + scripting (Doppio consumes the same APIs) RFC: planning/engine-runtime-capabilities-rfc.md
This document is intended for all engine users (internal teams and third-party projects). It summarizes what landed in two implementation phases and how to adopt it safely.
Design principles (unchanged)#
- Optional — Projects that only use sprites + scripts pay no map/native/LOD cost unless they use these APIs.
- Neutral — No real-world map providers, HTTP Tile URLs, or game-specific names in core.
- Editor ≠ runtime — Doppio plugins stay separate from play-mode native modules.
- Single Lua contract — Documented in runtime-apis.md.
Phase 1 (foundation)#
| Feature | Summary |
|---|---|
| Picking | Scene::pickEntityAtWorld , raycastSelectEntity , PlayRenderContext , PickQueryRegistry |
| Overlays | Render::Overlay2D + caffeine.draw2d.* |
| UI | Lua helpers on existing UISystem |
| Scripts | require , caffeine.assets.loadText , PlayClock , GameStateStack |
| Map (data model) | MapSurface2DComponent (bounds + chunk size only) |
Tests: tests/test_pick_query.cpp ( [pick] ).
Phase 2 (this patch)#
1. Native runtime modules#
- ABI:
include/caffeine/runtime/NativeModuleAPI.h - Host:
Script::NativeModuleHost(dlopen/LoadLibrary,caffeine_native_module_info, optionalcaffeine_native_call) - Lua:
caffeine.native.load,caffeine.native.call(module, fn, json?) - Docs: native-modules.md
2. Overlay RHI path#
- API:
Overlay2D::buildRhiMesh,Overlay2D::drawRhi(SDL GPU / no ImGui entry point) - Shaders:
overlay2d.vert/overlay2d.fragin tree; wire into builtin shader registration to enable GPU draw - Docs: overlay-2d-rhi.md
3. Map surface — editor + events#
- Component:
MapSurface2DComponentserialized in.caf(type id 55) - Editor: Add Component → Map Surface 2D
- Runtime:
Scene::tickMapSurfaceChunkRequestsemitsEvents::OnMapSurfaceChunkRequest - Lua:
caffeine.map.onChunkRequest(fn)orcaffeine.events.on("mapChunkRequest", fn) - Note: You supply all content (textures, meshes, data). The engine only reports which logical chunks are visible.
4. 2D sprite LOD#
- Component:
SpriteLod2DComponent(type id 56), zoom thresholds + scale factor - System:
Scene::applySpriteLod2Ddriven by active play camera zoom - Editor: Add Component → Sprite LOD 2D(captures current transform scale as base)
5. Custom Lua picking#
- API:
caffeine.pick.register,unregister,query - Custom handlers run before entity AABB pick; return a numeric custom id or false
Migration checklist for game teams#
- [ ] Replace ad-hoc screen→world math with
caffeine.pick.screenToWorld/PlayRenderContext - [ ] Move vector debug draw to
caffeine.draw2dinstead of editor-only gizmos - [ ] For large surfaces, add
MapSurface2D+ handlemapChunkRequestin Lua (or C++ viaEventBus) - [ ] For dense 2D scenes, add
SpriteLod2Don marker entities - [ ] For heavy sim outside Lua, add
native/my_module.sousing the documented ABI - [ ] Read runtime-apis.md (English) before upgrading scripts
Binary scene format#
| Type ID | Component |
|---|---|
| 55 | MapSurface2DComponent |
| 56 | SpriteLod2DComponent |
Older .caf files load unchanged; new components are opt-in.
Known follow-ups#
- Register
overlay2dshaders inBuiltinShader+ CMake for full GPU overlay draw without ImGui - Richer
caffeine.native.call(typed Moon tables ↔ JSON) - Inspector widgets for map bounds (today: component defaults + future inspector polish)
- Optional
SpatialGrid2Dhelpers documented under spatial-partitioning.md usage patterns
Files touched (high level)#
src/caffeine/scene/PickQuery.hpp,PickRaycast.*,MapSurfaceSystem.*,SpriteLod2DSystem.*src/caffeine/render/Overlay2D.hpp/.cpp,src/caffeine/render/shaders/overlay2d.vert/.fragsrc/caffeine/script/RuntimeScriptBindings.cpp,NativeModuleHost.*,AssetTextLoader.*src/caffeine/runtime/PlayClock.hpp/.cpp,GameStateStack.*src/caffeine/ecs/MapComponents.hpp,LodComponents.hppinclude/caffeine/runtime/NativeModuleAPI.hsrc/caffeine/scene/SceneSerializer.hpp,ComponentRegistry.cppdocs/scripting/*,docs/rendering/overlay-2d-rhi.md, this file
Support#
Questions or regressions: attach project native/ layout, script snippets using new APIs, and whether play mode is 2D or 3D (affects PlayRenderContext ).