From be82d944ca62020da8727fa62d5b870576ea07fb Mon Sep 17 00:00:00 2001 From: John McCardle Date: Sat, 7 Feb 2026 23:50:35 +0000 Subject: [PATCH] Update Strategic Direction --- ...c-Direction.-.md => Strategic-Direction.md | 358 +++++++++--------- 1 file changed, 179 insertions(+), 179 deletions(-) rename Strategic-Direction.-.md => Strategic-Direction.md (97%) diff --git a/Strategic-Direction.-.md b/Strategic-Direction.md similarity index 97% rename from Strategic-Direction.-.md rename to Strategic-Direction.md index e80fab4..4764e8f 100644 --- a/Strategic-Direction.-.md +++ b/Strategic-Direction.md @@ -1,180 +1,180 @@ -# Strategic Direction - -**McRogueFace v0.2.5** | February 2026 - -**Related Pages:** -- [[Issue-Roadmap]] - Detailed issue tracking by system and priority -- [[Performance-and-Profiling]] - Profiling infrastructure -- [[Animation-System]] - Animation architecture -- [[Development-Workflow]] - Day-to-day development process -- [[Home]] - Documentation hub - ---- - -## Current State Assessment - -McRogueFace is a C++/Python 2D game engine for roguelikes. It wraps SFML, libtcod, and OpenGL behind a Python scripting layer, delivering C++ performance with Python ergonomics. The engine has been in development since late 2022 and is now **game-ready for 2D roguelikes**. - -### What Has Been Built - -**Core Engine (Production-Ready):** -- UI hierarchy: Frame, Caption, Sprite, Grid, Entity, Arc, Circle, Line with parent-child composition -- Animation system with 24+ easing functions, property locking, callbacks, safe recursive callbacks -- Scene management with keyboard handlers, transitions, cleanup -- Input handling: Key, MouseButton, InputState enums; click/hover/move callbacks on all drawables; grid cell callbacks -- Multi-layer grid system with TileLayer/ColorLayer, chunk-based rendering, z-ordering, rotation, camera control -- Grid-based entity system with collections, pathfinding, FOV -- Procedural generation: DiscreteMap, HeightMap, NoiseSource, BSP with adjacency graphs -- Tiled import (TileSetFile, TileMapFile, WangSet with resolve/apply pipeline) -- LDtk import (LdtkProject, AutoRuleSet with pattern-matching resolution) -- Timer objects with stopwatch semantics (pause, resume, restart, one-shot) -- Audio: sound buffers, playback, volume control -- Documentation: MCRF_* macro system, auto-generated HTML/Markdown/man pages, Python type stubs - -**Platform Support:** -- Linux native builds -- Windows cross-compilation (MinGW-w64) -- WebAssembly/Emscripten with SDL2+OpenGL ES 2 backend -- Headless mode for CI/automated testing - -**Testing and Tooling:** -- 100+ unit tests across unit, integration, regression, and benchmark suites -- Interactive demo system with per-feature screens -- Automation API (screenshots, simulated input) -- Profiling infrastructure (F3 overlay, ScopedTimer, metrics) - -**Experimental 3D Pipeline:** -- Viewport3D with OpenGL scene graph embedded in 2D UI -- Camera3D, Entity3D, MeshLayer, Model3D (glTF), Billboard, Shader3D, VoxelGrid -- Greedy meshing, frustum culling, serialization -- These modules work and are tested but have known gaps (Entity3D.animate() is a stub, some collection methods missing). They represent proof-of-concept scouting for the McVoxelFace era. - -### Proving Grounds - -- **Crypt of Sokoban** (7DRL 2025) was the alpha proving ground -- the first complete game built on McRogueFace. -- **7DRL 2026** is the current milestone. Engine preparation is complete; widget primitives are prototyped and tested. -- **r/roguelikedev tutorial series** (#167) is the community-facing demonstration target. - ---- - -## Engine Eras - -The original plan called for three separate engines. In practice, they have converged into one engine with **eras** of focused development. The shared foundation -- Python bindings, UI hierarchy, animation system, scene management, input handling, audio -- is the same regardless of whether the game uses tile grids, vector graphics, or voxel terrain. - -| Era | Focus | Status | -|-----|-------|--------| -| **McRogueFace** (current) | 2D tiles, roguelike systems, procgen | Active -- 7DRL 2026 imminent | -| **McVectorFace** (future) | Sparse grids, vector graphics, physics | Planned | -| **McVoxelFace** (future) | Voxel terrain, 3D gameplay | Proof-of-concept scouting done | - -Each era adds capabilities to the same engine. Nothing is thrown away. A Grid is still useful for inventory screens in a 3D game. Sparse grid layers plus a polygon class would cover vector graphics. There is no reason to fork. - ---- - -## Development Philosophy - -These principles guide all development decisions: - -1. **Build the engine, prove it with games.** Game jams and the tutorial series are the proof. An engine nobody makes games with is just a library. - -2. **Foundation first, then features.** But "foundation" includes making the engine pleasant to use, not just performant. - -3. **One engine, not three.** Capabilities accumulate across eras; nothing is thrown away. - -4. **Python ergonomics matter.** If it is annoying to use from Python, it is a bug. The API should feel natural to Python developers, not like a thin C++ wrapper. - -5. **Maintain momentum.** Build tools quickly before losing interest. The 72-hour deep-dive pattern is a feature, not a bug -- channel it into focused sprints. - -6. **McRogueFace should be usable by others.** Not just a personal tool. The roguelike community is the first audience. - ---- - -## Immediate Focus - -### 7DRL 2026 (February 2026) - -The engine is prepared. All 2D systems are production-ready. The jam is the proving ground -- it will expose any remaining rough edges in the workflow of building a complete game on McRogueFace. - -### Post-Jam (March-April 2026) - -Lessons from 7DRL will drive the next wave of work: -- Polish and publish the engine based on real-world jam experience -- Fix any pain points discovered during actual game development -- Progress on the r/roguelikedev tutorial series (#167) -- Address any critical bugs surfaced during the jam - -### Ongoing - -The engine ships continuously. There is no single "v1.0 release date." Each version should be usable. Breaking changes are avoided where possible, and when necessary, they are documented. - ---- - -## What Remains - -32 open issues remain, grouped by area. See [[Issue-Roadmap]] for detailed per-issue tracking. - -**3D Pipeline Gaps (4 issues):** Entity3D needs animate() support (#242), viewport parent tracking (#244), collection method parity (#243), and screen_to_world() improvements (#245). These are tier-2 foundation work -- important for the McVoxelFace era but not blocking 2D development. - -**Multi-Tile Entities (5 issues):** Oversized sprites (#236), composite sprites (#237), texture display bounds (#235), entity origin offsets (#234), and the umbrella enhancement (#233). All tier-3 future work for richer entity rendering. - -**WASM/Emscripten Debugging (3 issues):** Debug infrastructure (#238), automated browser testing (#239), and developer troubleshooting docs (#240). Tier-3 tooling to improve the WebAssembly development experience. - -**Grid Enhancements (3 issues):** Sparse grid layers (#152), UIGrid.cpp refactoring (#149), and infinite world grid stitching (#67). Foundation and future work for larger and more flexible worlds. - -**LLM Agent Testbed (3 issues):** The grounded multi-agent testbed (#154), turn-based LLM orchestration (#156), and agent simulation environment (#55). Research applications that demonstrate the engine's value beyond traditional game development. - -**Platform and Distribution (7 issues):** Packaging without embedded interpreter (#70), Jupyter notebook interface (#54), multiple windows (#62), accessibility modes (#45), alternative input methods (#53), RenderTexture failure handling (#227), and subinterpreter support (#220). - -**Other (7 issues):** Particle system (#107), Color/Vector animation targets (#218), grid point animation (#124), memory pool for entities (#117), TexturePool RenderTexture reuse (#145), tutorial demo game (#167), and subinterpreter tests (#46). - -Most of these are tier-2 or tier-3 -- important but not urgent. The engine is functional for its current era. Issues will be addressed based on what games need, not on a predetermined schedule. - ---- - -## Decision Framework - -When considering new work, ask these questions in order: - -### 1. Does it serve the current era? - -McRogueFace is in the 2D roguelike era. Work that improves 2D tile-based game development gets priority. 3D pipeline improvements are welcome when momentum is there, but they should not block 2D progress. - -### 2. Did a real game expose this need? - -Problems discovered while building actual games (7DRL, tutorial series) take priority over theoretical improvements. If nobody has hit the limitation in practice, it can wait. - -### 3. Does it make the engine more usable by others? - -Documentation, ergonomic API improvements, packaging, and tutorial work multiply the engine's value. A feature that only the author would use is lower priority than one the community needs. - -### 4. Is it foundation or feature? - -Foundation work (performance, API consistency, bug fixes, documentation) compounds over time. Features are valuable but should build on a solid foundation. When in doubt, fix the foundation. - -### 5. Can it wait? - -If the answer is yes and there is foundation work to do, it should wait. Scope discipline is what separates shipping engines from perpetual projects. - -**Rule of thumb:** If a real game needs it now, do it now. If it is foundation work for the current era, prioritize it. Everything else goes on the backlog. - ---- - -## Long-Term Trajectory - -The engine's trajectory follows the games that drive it: - -- **Now:** 2D roguelikes (7DRL 2026, tutorial series, community adoption) -- **Next:** More ambitious 2D projects that stress-test grid stitching, multi-tile entities, and larger worlds -- **Eventually:** McVectorFace era (sparse grids, vector graphics, physics) and McVoxelFace era (voxel terrain, 3D gameplay) -- same engine, new capabilities, bigger games - -The 3D proof-of-concept scouting is already done. When the time comes for the McVoxelFace era, the foundation (Viewport3D, VoxelGrid, shaders, Model3D) already exists and just needs to be completed. - ---- - -**Navigation:** -- [[Home]] - Documentation hub -- [[Issue-Roadmap]] - Detailed issue tracking -- [[Development-Workflow]] - Day-to-day process -- [[Performance-and-Profiling]] - Profiling infrastructure - +# Strategic Direction + +**McRogueFace v0.2.5** | February 2026 + +**Related Pages:** +- [[Issue-Roadmap]] - Detailed issue tracking by system and priority +- [[Performance-and-Profiling]] - Profiling infrastructure +- [[Animation-System]] - Animation architecture +- [[Development-Workflow]] - Day-to-day development process +- [[Home]] - Documentation hub + +--- + +## Current State Assessment + +McRogueFace is a C++/Python 2D game engine for roguelikes. It wraps SFML, libtcod, and OpenGL behind a Python scripting layer, delivering C++ performance with Python ergonomics. The engine has been in development since late 2022 and is now **game-ready for 2D roguelikes**. + +### What Has Been Built + +**Core Engine (Production-Ready):** +- UI hierarchy: Frame, Caption, Sprite, Grid, Entity, Arc, Circle, Line with parent-child composition +- Animation system with 24+ easing functions, property locking, callbacks, safe recursive callbacks +- Scene management with keyboard handlers, transitions, cleanup +- Input handling: Key, MouseButton, InputState enums; click/hover/move callbacks on all drawables; grid cell callbacks +- Multi-layer grid system with TileLayer/ColorLayer, chunk-based rendering, z-ordering, rotation, camera control +- Grid-based entity system with collections, pathfinding, FOV +- Procedural generation: DiscreteMap, HeightMap, NoiseSource, BSP with adjacency graphs +- Tiled import (TileSetFile, TileMapFile, WangSet with resolve/apply pipeline) +- LDtk import (LdtkProject, AutoRuleSet with pattern-matching resolution) +- Timer objects with stopwatch semantics (pause, resume, restart, one-shot) +- Audio: sound buffers, playback, volume control +- Documentation: MCRF_* macro system, auto-generated HTML/Markdown/man pages, Python type stubs + +**Platform Support:** +- Linux native builds +- Windows cross-compilation (MinGW-w64) +- WebAssembly/Emscripten with SDL2+OpenGL ES 2 backend +- Headless mode for CI/automated testing + +**Testing and Tooling:** +- 100+ unit tests across unit, integration, regression, and benchmark suites +- Interactive demo system with per-feature screens +- Automation API (screenshots, simulated input) +- Profiling infrastructure (F3 overlay, ScopedTimer, metrics) + +**Experimental 3D Pipeline:** +- Viewport3D with OpenGL scene graph embedded in 2D UI +- Camera3D, Entity3D, MeshLayer, Model3D (glTF), Billboard, Shader3D, VoxelGrid +- Greedy meshing, frustum culling, serialization +- These modules work and are tested but have known gaps (Entity3D.animate() is a stub, some collection methods missing). They represent proof-of-concept scouting for the McVoxelFace era. + +### Proving Grounds + +- **Crypt of Sokoban** (7DRL 2025) was the alpha proving ground -- the first complete game built on McRogueFace. +- **7DRL 2026** is the current milestone. Engine preparation is complete; widget primitives are prototyped and tested. +- **r/roguelikedev tutorial series** (#167) is the community-facing demonstration target. + +--- + +## Engine Eras + +The original plan called for three separate engines. In practice, they have converged into one engine with **eras** of focused development. The shared foundation -- Python bindings, UI hierarchy, animation system, scene management, input handling, audio -- is the same regardless of whether the game uses tile grids, vector graphics, or voxel terrain. + +| Era | Focus | Status | +|-----|-------|--------| +| **McRogueFace** (current) | 2D tiles, roguelike systems, procgen | Active -- 7DRL 2026 imminent | +| **McVectorFace** (future) | Sparse grids, vector graphics, physics | Planned | +| **McVoxelFace** (future) | Voxel terrain, 3D gameplay | Proof-of-concept scouting done | + +Each era adds capabilities to the same engine. Nothing is thrown away. A Grid is still useful for inventory screens in a 3D game. Sparse grid layers plus a polygon class would cover vector graphics. There is no reason to fork. + +--- + +## Development Philosophy + +These principles guide all development decisions: + +1. **Build the engine, prove it with games.** Game jams and the tutorial series are the proof. An engine nobody makes games with is just a library. + +2. **Foundation first, then features.** But "foundation" includes making the engine pleasant to use, not just performant. + +3. **One engine, not three.** Capabilities accumulate across eras; nothing is thrown away. + +4. **Python ergonomics matter.** If it is annoying to use from Python, it is a bug. The API should feel natural to Python developers, not like a thin C++ wrapper. + +5. **Maintain momentum.** Build tools quickly before losing interest. The 72-hour deep-dive pattern is a feature, not a bug -- channel it into focused sprints. + +6. **McRogueFace should be usable by others.** Not just a personal tool. The roguelike community is the first audience. + +--- + +## Immediate Focus + +### 7DRL 2026 (February 2026) + +The engine is prepared. All 2D systems are production-ready. The jam is the proving ground -- it will expose any remaining rough edges in the workflow of building a complete game on McRogueFace. + +### Post-Jam (March-April 2026) + +Lessons from 7DRL will drive the next wave of work: +- Polish and publish the engine based on real-world jam experience +- Fix any pain points discovered during actual game development +- Progress on the r/roguelikedev tutorial series (#167) +- Address any critical bugs surfaced during the jam + +### Ongoing + +The engine ships continuously. There is no single "v1.0 release date." Each version should be usable. Breaking changes are avoided where possible, and when necessary, they are documented. + +--- + +## What Remains + +32 open issues remain, grouped by area. See [[Issue-Roadmap]] for detailed per-issue tracking. + +**3D Pipeline Gaps (4 issues):** Entity3D needs animate() support (#242), viewport parent tracking (#244), collection method parity (#243), and screen_to_world() improvements (#245). These are tier-2 foundation work -- important for the McVoxelFace era but not blocking 2D development. + +**Multi-Tile Entities (5 issues):** Oversized sprites (#236), composite sprites (#237), texture display bounds (#235), entity origin offsets (#234), and the umbrella enhancement (#233). All tier-3 future work for richer entity rendering. + +**WASM/Emscripten Debugging (3 issues):** Debug infrastructure (#238), automated browser testing (#239), and developer troubleshooting docs (#240). Tier-3 tooling to improve the WebAssembly development experience. + +**Grid Enhancements (3 issues):** Sparse grid layers (#152), UIGrid.cpp refactoring (#149), and infinite world grid stitching (#67). Foundation and future work for larger and more flexible worlds. + +**LLM Agent Testbed (3 issues):** The grounded multi-agent testbed (#154), turn-based LLM orchestration (#156), and agent simulation environment (#55). Research applications that demonstrate the engine's value beyond traditional game development. + +**Platform and Distribution (7 issues):** Packaging without embedded interpreter (#70), Jupyter notebook interface (#54), multiple windows (#62), accessibility modes (#45), alternative input methods (#53), RenderTexture failure handling (#227), and subinterpreter support (#220). + +**Other (7 issues):** Particle system (#107), Color/Vector animation targets (#218), grid point animation (#124), memory pool for entities (#117), TexturePool RenderTexture reuse (#145), tutorial demo game (#167), and subinterpreter tests (#46). + +Most of these are tier-2 or tier-3 -- important but not urgent. The engine is functional for its current era. Issues will be addressed based on what games need, not on a predetermined schedule. + +--- + +## Decision Framework + +When considering new work, ask these questions in order: + +### 1. Does it serve the current era? + +McRogueFace is in the 2D roguelike era. Work that improves 2D tile-based game development gets priority. 3D pipeline improvements are welcome when momentum is there, but they should not block 2D progress. + +### 2. Did a real game expose this need? + +Problems discovered while building actual games (7DRL, tutorial series) take priority over theoretical improvements. If nobody has hit the limitation in practice, it can wait. + +### 3. Does it make the engine more usable by others? + +Documentation, ergonomic API improvements, packaging, and tutorial work multiply the engine's value. A feature that only the author would use is lower priority than one the community needs. + +### 4. Is it foundation or feature? + +Foundation work (performance, API consistency, bug fixes, documentation) compounds over time. Features are valuable but should build on a solid foundation. When in doubt, fix the foundation. + +### 5. Can it wait? + +If the answer is yes and there is foundation work to do, it should wait. Scope discipline is what separates shipping engines from perpetual projects. + +**Rule of thumb:** If a real game needs it now, do it now. If it is foundation work for the current era, prioritize it. Everything else goes on the backlog. + +--- + +## Long-Term Trajectory + +The engine's trajectory follows the games that drive it: + +- **Now:** 2D roguelikes (7DRL 2026, tutorial series, community adoption) +- **Next:** More ambitious 2D projects that stress-test grid stitching, multi-tile entities, and larger worlds +- **Eventually:** McVectorFace era (sparse grids, vector graphics, physics) and McVoxelFace era (voxel terrain, 3D gameplay) -- same engine, new capabilities, bigger games + +The 3D proof-of-concept scouting is already done. When the time comes for the McVoxelFace era, the foundation (Viewport3D, VoxelGrid, shaders, Model3D) already exists and just needs to be completed. + +--- + +**Navigation:** +- [[Home]] - Documentation hub +- [[Issue-Roadmap]] - Detailed issue tracking +- [[Development-Workflow]] - Day-to-day process +- [[Performance-and-Profiling]] - Profiling infrastructure + *Last updated: 2026-02-07* \ No newline at end of file