GroveEngine/CLAUDE_NEXT_SESSION.md

GroveEngine - Session Successor Prompt

Context

GroveEngine is a C++17 hot-reload game engine with a 2D bgfx-based renderer module.

Current State - BgfxRenderer (27 Nov 2025)

Completed Phases

Phase	Feature	Status
5	IIO Pipeline (messages → SceneCollector → RenderGraph)	Done
5.5	Sprite shader with GPU instancing (80-byte SpriteInstance)	Done
6	Texture loading via stb_image	Done
6.5	Debug overlay (FPS/stats via bgfx debug text)	Done
7	Text rendering with embedded 8x8 bitmap font	Done
8A	Multi-texture support (sorted batching by textureId)	Done
8B	Tilemap rendering (TilemapPass with instanced tiles)	Done

Key Files

modules/BgfxRenderer/
├── BgfxRendererModule.cpp       # Main module entry
├── Shaders/
│   ├── vs_sprite.sc, fs_sprite.sc  # Instanced sprite shader
│   ├── varying.def.sc              # Shader inputs/outputs
│   └── *.bin.h                     # Compiled shader bytecode
├── Passes/
│   ├── ClearPass.cpp            # Clear framebuffer
│   ├── TilemapPass.cpp          # Tilemap grid rendering
│   ├── SpritePass.cpp           # Instanced sprite rendering (sorted by texture)
│   ├── TextPass.cpp             # Text rendering (glyph quads)
│   └── DebugPass.cpp            # Debug lines/shapes
├── Text/
│   └── BitmapFont.h/.cpp        # Embedded 8x8 CP437-style font
├── Resources/
│   ├── TextureLoader.cpp        # stb_image PNG/JPG loading
│   └── ResourceCache.cpp        # Texture cache with numeric IDs
├── Scene/
│   └── SceneCollector.cpp       # IIO message parsing (render:*)
├── Debug/
│   └── DebugOverlay.cpp         # FPS/stats display
└── Frame/
    └── FramePacket.h            # SpriteInstance, TextCommand, TilemapChunk

ResourceCache - Texture ID System

// Load texture and get numeric ID
uint16_t texId = resourceCache->loadTextureWithId(device, "path/to/image.png");

// Get texture by ID (for sprite rendering)
rhi::TextureHandle tex = resourceCache->getTextureById(texId);

IIO Message Formats

Sprite (render:sprite)

{ "x": 100.0, "y": 50.0, "scaleX": 32.0, "scaleY": 32.0,
  "rotation": 0.0, "u0": 0.0, "v0": 0.0, "u1": 1.0, "v1": 1.0,
  "textureId": 1, "color": 0xFFFFFFFF, "layer": 0 }

Text (render:text)

{ "x": 10.0, "y": 10.0, "text": "Hello",
  "fontSize": 16, "color": 0xFFFFFFFF, "layer": 100 }

Tilemap (render:tilemap)

{ "x": 0.0, "y": 0.0, "width": 10, "height": 10,
  "tileW": 16, "tileH": 16, "textureId": 0,
  "tileData": "1,0,1,0,1,0,..." }  // comma-separated tile indices

Next Task: Phase 9 - Choose One

Option A: Layer Sorting

• Currently sprites are sorted by textureId only
• Add proper layer sorting (render back-to-front)
• Sort key: (layer << 16) | textureId for efficient batching

Option B: Dynamic Texture Loading via IIO

• render:texture:load message to load textures at runtime
• Returns textureId that can be used in sprites
• Useful for dynamically loaded assets

Option C: Particle System

• ParticlePass for particle effects
• GPU instanced particles with lifetime/velocity
• FramePacket already has ParticleInstance struct

Option D: Camera Features

• Zoom and pan support (already in ViewInfo)
• Screen shake effects
• Smooth camera following

Build & Test

cd build-bgfx
cmake --build . -j4
cd tests && ./test_23_bgfx_sprites_visual

Notes

• Shaders are pre-compiled (embedded in .bin.h)
• shaderc at: build-bgfx/_deps/bgfx-build/cmake/bgfx/shaderc
• All passes reuse sprite shader (same instancing layout)
• TilemapPass: tile index 0 = empty, 1+ = actual tiles
• SpritePass: stable_sort by textureId preserves layer order within same texture