Caffeine Engine - Current Status & Implementation Roadmap
Branch: 121-44-audio-preview-spatial-placement
Date: 2026-05-18
1. BUILD & IDE STATUS ✅#
Completed#
- ✅ doppio.exe fully builds and launches (1.2 MB)
- ✅ All executables built: doppio, caf-encode, caffeine-combined
- ✅ SDL3 integrated and working
- ✅ Clean default UI layout (Hierarchy + Viewport only)
- ✅ File picker works for project creation
- ✅ Project manager operational
Known Issues to Fix#
- ⚠️ FilePicker window requires scrolling (fixed window size ~600x400)
- Fix: Make window resizable and increase default size
- File:
doppio-archived/src/doppio/editor/FilePicker.cppline 96-97
2. ARCHITECTURE OVERVIEW#
ECS (Entity Component System)#
Status: ✅ Fully implemented and working
Core Files:
src/caffeine/ecs/Entity.hpp- Entity definitionsrc/caffeine/ecs/World.hpp- World/scene managementsrc/caffeine/ecs/Components.hpp- Basic components (Position2D, Velocity2D, Rotation, Scale2D, Sprite, Health, Tag, ParticleEmitterComponent)src/caffeine/ecs/ComponentID.hpp- Component type systemsrc/caffeine/ecs/ComponentQuery.hpp- Entity querying
Current Components Available:
- Transform: Position2D, Velocity2D, Acceleration2D, Rotation, Scale2D
- Visual: Sprite (name, frameIndex only - minimal)
- Audio: AudioComponents.hpp (exists but not integrated)
- Animation: AnimationComponents.hpp (exists)
- Camera: CameraComponents.hpp
- Light: LightComponents.hpp
- Particle: ParticleEmitterComponent
- Mesh: MeshComponents.hpp (3D, not priority for 2D)
- Health/Tag: For basic game mechanics
3. FEATURE GAPS & PRIORITIES#
🔴 CRITICAL (Blocking Game Development)#
1. Inspector Panel - Minimal (15-20% complete)#
-
Current State:
- Only 6 component drawers implemented (Transform, Sprite, Camera, RigidBody2D, AudioSource, Script)
- Sprite drawer is basic: just name + frameIndex
- No property discovery/reflection system
- Hard-coded drawer registration
-
What's Missing:
- Dynamic component property inspection
- Proper enum selection UI (e.g., for ColliderShape, ToolMode)
- Vector/color pickers
- Asset reference selectors
- Dropdown selectors for components
- Undo/redo support
-
File:
src/editor/InspectorPanel.hpp/cpp -
Priority: 🔴 CRITICAL - Can't edit entities without this
-
Effort: ~3-5 days
2. Physics System - Incomplete (30% implemented)#
-
Current State:
- Components exist: RigidBody2D, Collider2D, PhysicsMaterial
- PhysicsSystem2D has 700+ lines of implementation
- Collision detection logic exists
- Force/impulse system exists
-
What's Missing:
- Physics simulation not hooked into editor/game loop properly
- Collision callbacks not firing (callOnCollision exists but untested)
- No visual debugging (collision visualizers)
- No physics settings UI in editor
- Sleep optimization incomplete
-
Files:
src/caffeine/physics/PhysicsComponents2D.hpp,src/caffeine/physics/PhysicsSystem2D.hpp -
Priority: 🔴 CRITICAL - No game without physics
-
Effort: ~2-3 days to integrate properly
3. Scripting System - Scaffolding only (5% usable)#
-
Current State:
- ScriptEngine exists with lifecycle hooks: onCreate, onUpdate, onDestroy, onCollision
- ScriptEngine can load scripts and call them
- Script watcher for hot-reload
-
What's Missing:
- No script binding - engine classes not exposed to scripts
- No runtime - what language? (Lua? C#? Custom?)
- No entity access - scripts can't modify entities
- No API documentation
- Script component UI in inspector
-
Files:
src/script/ScriptEngine.hpp/cpp,src/caffeine/script/ScriptSystem.cpp -
Priority: 🔴 CRITICAL - Game logic impossible without this
-
Effort: ~5-7 days (depends on language choice)
4. 2D Tools - Partial (40% usable)#
-
Tilemap Editor:
- ✅ Brush, Bucket, Eraser, Picker tools defined
- ✅ TileLayer and Tilemap classes exist
- ❌ No tileset loading/display
- ❌ No rendering
- ❌ No grid visualization
- ❌ No tool UI integration
-
Sprite Handling:
- ✅ Sprite component exists
- ❌ No sprite atlas/sheet support
- ❌ No frame animation UI
- ❌ No sprite preview in inspector
-
Files:
src/editor/TilemapEditor.hpp/cpp -
Priority: 🔴 CRITICAL for 2D - Can't make 2D games without tilesets
-
Effort: ~4-6 days
🟡 HIGH (Important for full feature set)#
5. Component Registration/Discovery#
- Current State: Components are discoverable via ECS but Inspector doesn't auto-discover them
- Need: Reflection/metadata system so inspector can show all component properties
- Priority: HIGH - Unlocks dynamic UI generation
- Effort: ~2-3 days
6. Asset Pipeline#
- Current State: Basic asset browser exists
- Missing:
- Texture import/settings
- Sprite atlas creation
- Tileset definition files
- Audio asset metadata
- Priority: HIGH
- Effort: ~3-5 days
7. Scene Serialization#
- Current State: Likely partial
- Missing: Save/load entity hierarchies with full state
- Priority: HIGH
- Effort: ~2-3 days
🟢 MEDIUM (Nice to have)#
8. Particle System Integration#
- ParticleEmitterComponent exists but likely not wired to renderer
- Effort: ~1-2 days
9. Animation System#
- AnimationComponents exist
- Effort: ~2-3 days
10. 3D Support#
- Components3D.hpp exists
- Effort: Defer - focus on 2D first
4. IMMEDIATE NEXT STEPS (Priority Order)#
Week 1:#
-
Fix FilePicker window sizing (1 hour)
- Make resizable, increase default size to 800x600
-
Expand Inspector with property types (2-3 days)
- Add UI for all basic property types (float, int, bool, Vec2, color, enum)
- Test with Transform and Sprite components
- Add component add/remove UI
-
Integrate Physics visually (2 days)
- Hook PhysicsSystem2D into scene editor
- Add collision debug visualization
- Test RigidBody2D + Collider2D on entities
Week 2:#
-
Basic Scripting Integration (3-5 days)
- Choose scripting language (recommend: Lua for simplicity, or C# if .NET available)
- Create bindings for basic engine functions
- Allow attaching scripts to entities
- Test onCreate/onUpdate lifecycle
-
2D Editor Tools (4-6 days)
- Implement tileset editor
- Implement tilemap painter
- Grid visualization
- Basic rendering integration
5. REFERENCE ARCHITECTURE (Unity-inspired)#
Inspector (Property Editor)#
Entity: "Player"
├─ Transform
│ ├─ Position: (0, 0) [Vec2Drawer]
│ ├─ Rotation: 45° [SliderDrawer]
│ └─ Scale: (1, 1) [Vec2Drawer]
├─ Sprite
│ ├─ Texture: [AssetSelector]
│ ├─ Frame: 0 [IntDrawer]
│ └─ Color: white [ColorDrawer]
├─ RigidBody2D
│ ├─ Mass: 1.0 [FloatDrawer]
│ ├─ Gravity Scale: 1.0 [FloatDrawer]
│ ├─ Constraints: [FlagDrawer]
│ └─ Collision Matrix [LayerMaskDrawer]
├─ Collider2D
│ ├─ Shape: AABB [EnumDrawer]
│ ├─ Size: (32, 32) [Vec2Drawer]
│ ├─ Layer: 0 [LayerDrawer]
│ └─ Is Trigger: false [BoolDrawer]
└─ [+ Add Component...]
ScriptAPI (example Lua)#
-- Player.lua
entity:getComponent("RigidBody2D").velocity = {100, 0}
entity:getComponent("Sprite").frameIndex = 1
input.isKeyDown("w") -- true/false
6. FILE CHECKLIST#
Core Systems (Check/expand these)#
- [ ]
src/caffeine/ecs/Components.hpp- Add missing component types - [ ]
doppio-archived/src/doppio/editor/InspectorPanel.cpp- Expand with property drawers - [ ]
src/caffeine/physics/PhysicsSystem2D.hpp- Wire to main game loop - [ ]
src/caffeine/script/ScriptEngine.cpp- Add engine bindings - [ ]
doppio-archived/src/doppio/editor/TilemapEditor.cpp- Implement rendering - [ ]
doppio-archived/src/doppio/editor/FilePicker.cpp- Fix window sizing
Next Exploration#
- [ ] How scenes are serialized (look for SceneSerializer)
- [ ] How assets are loaded (look in
src/caffeine/assets) - [ ] Render pipeline (look in
src/caffeine/render) - [ ] How systems integrate into main game loop (look in
src/caffeine/engine)
7. BUILD & TESTING#
Current Build Status#
cd build && cmake --build . --config Release
# doppio.exe ready in build/Release/
# Test game creation:
./build/Release/doppio.exe
# → Create project → Open scene → Edit entities
What to Test Next#
- Create new 2D project
- Add entity with Sprite + RigidBody2D + Collider2D
- Verify inspector shows all properties
- Save/load scene
- Run game with physics
SUMMARY#
Caffeine Engine is a solid skeleton with ECS, physics, scripting, and 2D tools scaffolding in place. The critical path to usable game development is:
- Inspector expansion (15-20 hours) - Make it show/edit all component properties
- Physics integration (10-15 hours) - Hook to game loop, add debug visualization
- Scripting bindings (20-30 hours) - Expose engine API to script language
- 2D tools completion (25-35 hours) - Tileset editor, tilemap painter
- Testing & bug fixes (ongoing)
Realistic timeline: 3-4 weeks for a usable 2D indie game editor at Unity-lite feature level.