From 26a1d52add7ec9308831a7ac51bbbd458ff13869 Mon Sep 17 00:00:00 2001 From: John McCardle Date: Sat, 7 Feb 2026 23:02:12 +0000 Subject: [PATCH] Update "Strategic-Direction.-" --- Strategic-Direction.-.md | 180 +++++++++++++++++++ Strategic-Direction.md | 366 --------------------------------------- 2 files changed, 180 insertions(+), 366 deletions(-) create mode 100644 Strategic-Direction.-.md delete mode 100644 Strategic-Direction.md diff --git a/Strategic-Direction.-.md b/Strategic-Direction.-.md new file mode 100644 index 0000000..e80fab4 --- /dev/null +++ b/Strategic-Direction.-.md @@ -0,0 +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 + +*Last updated: 2026-02-07* \ No newline at end of file diff --git a/Strategic-Direction.md b/Strategic-Direction.md deleted file mode 100644 index 5e5ca94..0000000 --- a/Strategic-Direction.md +++ /dev/null @@ -1,366 +0,0 @@ -# Strategic Direction - -**Last Updated:** October 2025 (post-profiling system implementation) -**Source:** FINAL_RECOMMENDATIONS.md (October 2023 strategic analysis) -**Status:** Active guidance for development priorities - -**Related Pages:** -- [[Performance-and-Profiling]] - Profiling system (completed ✅) -- [[Animation-System]] - Current animation architecture -- [[Proposal-Next-Gen-Grid-Entity-System]] - Major architectural proposal - ---- - -## Current State Assessment - -### Achievements (2023-2025) -- ✅ Comprehensive C++/Python game engine with SFML/libtcod integration -- ✅ Animation system with 24+ easing functions -- ✅ Profiling infrastructure (F3 overlay, ScopedTimer, metrics) - **Completed Oct 2025** -- ✅ 70% complete tutorial series (parts 0-6 implemented) -- ✅ Three-audience strategy (beginners, game jammers, researchers) - -### Known Problems -- ⚠️ Animation system has API inconsistencies and bugs -- ⚠️ Grid rendering lacks dirty flag optimization (re-renders static content every frame) -- ⚠️ Tutorial continuation blocked by animation issues -- ⚠️ No public release (features not stable enough) - -### Recent Progress (October 2025) -- ✅ **Profiling system implemented** - Issue #104 completed -- ✅ **Benchmarks created** - tests/benchmark_static_grid.py, tests/benchmark_moving_entities.py -- 🔄 **Next:** Grid dirty flags (#116), SpatialHash (#115), Animation system overhaul (#120) - ---- - -## Core Recommendation: Foundation First - -**Principle:** Fix foundation systems before expanding features. - -### Immediate Focus (Next 3-6 Months) -1. **Grid rendering optimization** - Dirty flags, viewport culling -2. **Animation system overhaul** - Fix APIs, squash bugs, consistent behavior -3. **Performance profiling** - ~~Measure~~ ✅, optimize, compete with TCOD - -### Defer Until Foundation Stable -- ECS architecture rewrite -- Living world/MMO features -- Python wheel distribution -- Tutorials 7-13 (advanced content) -- Research platform features - -**Why:** Stable, performant engine with consistent APIs is achievable in 3-6 months. Chasing bigger visions before fixing foundation repeats burnout cycle. - ---- - -## What to Pursue, Defer, or Abandon - -### ✅ PURSUE (Active Development) - -**Core Features:** -- Three-audience strategy (beginners, jammers, researchers) -- Pythonic API with clean abstractions -- "Batteries included but removable" philosophy -- Forward-only tutorial progression -- Performance competitive with libtcod - -**Foundation Systems:** -- Grid rendering optimization (#116, #115, #113) -- Animation system fixes (#120, #119, #100) -- Python binding consistency (#126, #109, #101) -- Documentation infrastructure (#92, #91, #97) - -### ⏸️ DEFER (Until After v1.0) - -**Good Ideas, Wrong Timing:** -- Python wheel packaging (`pip install mcrogueface`) - Wait for stable API -- Advanced tutorials 7-13 - Complete basic tutorials first -- Research platform features - Build community first -- Multi-window support (#62) - Limited demand -- Shader support (#106) - Advanced feature -- Particle system (#107) - Advanced feature - -**Rationale:** These are valuable but require stable foundation. Attempting them now creates scope creep and burnout risk. - -### ❌ ABANDON (Not Aligned with Project Vision) - -**Out of Scope:** -- Living world MMO features - Wrong project, years of work, no user demand -- Full ECS rewrite - Wrong timing, makes tutorials harder for beginners -- 50,000 tile ecosystem - Wrong scale for target audience -- Tile state machines - Too complex for beginner-friendly engine - -**Rationale:** McRogueFace is a **beginner-friendly roguelike engine**, not an MMO platform or research simulator. Stay focused on core mission. - ---- - -## Critical Path to v1.0 - -### Phase 1: Performance Foundation (✅ Partially Complete) -**Timeline:** October-November 2025 - -- [✅] Task #104: Profiling infrastructure (F3 overlay, ScopedTimer) -- [✅] Benchmarks: static grid, moving entities -- [🔄] Task #116: Grid dirty flag system -- [🔄] Task #115: SpatialHash for entity queries -- [⏳] Task #113: Batch operations API - -**Success Metric:** 60 FPS with 10,000 entities and 100x100 grid - -### Phase 2: Animation System Overhaul -**Timeline:** December 2025 - January 2026 - -- [⏳] Task #120: Property locking system -- [⏳] Task #100: Rotation support -- [⏳] API consistency audit -- [⏳] Comprehensive test suite -- [⏳] Documentation update - -**Success Metric:** Tutorial-ready animation system with consistent API - -### Phase 3: Tutorial Completion -**Timeline:** February - March 2026 - -- [✅] Parts 0-6: Implemented and working -- [⏳] Parts 7-10: Complete on stable foundation -- [⏳] Parts 11-13: Advanced content (optional) -- [⏳] Tutorial testing framework -- [⏳] Documentation sprint - -**Success Metric:** Professional tutorial ready for public release - -### Phase 4: Public Release -**Timeline:** April 2026 - -- API freeze (v1.0) -- Python wheel packaging -- Documentation finalization -- Public announcement - -**Success Metric:** First stable public release - ---- - -## Key Principles - -### 1. Fix Foundation Before Features - -**Wrong:** "Let's add ECS while animation system has bugs" -**Right:** "Let's fix animation bugs, THEN evaluate if ECS is needed" - -### 2. Measure Before Optimizing - -**Wrong:** "Grid rendering seems slow, let's rewrite it" -**Right:** "Let's profile grid rendering (✅), identify bottlenecks, optimize hot paths" - -### 3. Simplicity Over Completeness - -**Wrong:** "Let's support every possible use case" -**Right:** "Let's nail the beginner experience first" - -### 4. Ship Incrementally - -**Wrong:** "Can't release until everything is perfect" -**Right:** "Release tutorial parts 0-4 as Early Access while fixing rest" - -### 5. Listen to Burnout Signals - -**Wrong:** "Power through tutorial frustrations" -**Right:** "Tutorial burnout = foundation problem. Stop and fix foundation." - ---- - -## Decision Framework - -When considering new work, ask: - -### 1. Does it fix foundation? -- ✅ Grid dirty flags - Yes (core performance) -- ✅ Animation bug fixes - Yes (tutorial blocker) -- ❌ ECS rewrite - No (architectural experiment) - -### 2. Does it unblock tutorials? -- ✅ Animation API consistency - Yes (tutorial depends on it) -- ❌ Living world features - No (tutorials don't need it) - -### 3. Does it align with "beginner-friendly"? -- ✅ Pythonic API improvements - Yes (easier to learn) -- ❌ Advanced shader system - No (intimidating for beginners) - -### 4. Can it wait until v1.0? -- ⏸️ Python wheel packaging - Yes (good feature, not urgent) -- ❌ Performance fixes - No (embarrassing performance hurts adoption) - -**Rule of Thumb:** If it doesn't fix foundation, unblock tutorials, or improve beginner experience, defer it. - ---- - -## Synergies & Dependencies - -### Critical Path Dependencies - -``` -Profiling System (✅ Done) - ↓ -Grid Optimization (#116, #115) - ↓ -Animation System Overhaul (#120) - ↓ -Tutorial Completion (Parts 7-10) - ↓ -Public Release (v1.0) -``` - -**Each phase blocks the next.** Don't skip ahead. - -### Parallel Work (Can Do Anytime) - -Independent improvements that don't block critical path: -- Documentation updates (#92, #91, #97) -- Python binding patterns (#101, #109) -- Test infrastructure improvements -- Bug fixes not affecting tutorials - -**Rule:** These can fill time while waiting on reviews or builds, but never at expense of critical path. - ---- - -## Warnings & Anti-Patterns - -### Warning Signs of Scope Creep - -- "Let's add just one more feature before release" -- "This ECS idea is so cool, let's explore it" -- "We should support [edge case] before v1.0" -- "Let's redesign [working system] to be more elegant" - -**Response:** Stop. Refer to this document. Is it on critical path? No? Defer. - -### Known Burnout Triggers - -Based on September 2025 tutorial burnout: - -1. **Teaching broken features** - Tutorial work on unstable APIs -2. **Working around bugs** - Complex code to avoid animation issues -3. **Scope creep during tutorial** - Adding features mid-tutorial -4. **Perfectionism** - Rewriting working code - -**Response:** Recognize burnout signals early. Stop tutorial work. Fix foundation. Resume tutorials on stable base. - ---- - -## Success Metrics - -### v1.0 Release Criteria - -**Performance:** -- ✅ 60 FPS with 100x100 grid -- ✅ 60 FPS with 10,000 entities (requires #115) -- Grid render time <2ms for static content (requires #116) - -**API Stability:** -- Animation system has consistent APIs (#120) -- Python bindings follow patterns (#126, #101) -- No major breaking changes expected - -**Documentation:** -- Tutorial parts 0-6 polished (✅ code exists) -- Tutorial parts 7-10 completed -- API documentation generated (#97) -- Python type stubs available (#91) - -**User Experience:** -- Tutorial can be followed start-to-finish -- Examples run without errors -- Performance competitive with libtcod - -**Release Readiness:** -- API frozen -- Changelog prepared -- Python wheel available -- Public announcement ready - ---- - -## Monthly Check-In Questions - -At end of each month, evaluate: - -1. **Are we on critical path?** - - If not, why did we deviate? - - Was deviation justified? - -2. **Did we ship anything?** - - Code merged to master - - Tutorial parts completed - - Documentation updated - - Issues closed - -3. **Is burnout risk increasing?** - - Working on frustrating bugs? - - Scope creeping? - - Losing motivation? - - **Response:** Return to foundation work - -4. **What's blocking next phase?** - - Dependencies clear? - - Resources available? - - Technical unknowns identified? - -5. **Should we adjust timeline?** - - Faster than expected? - - Unforeseen blockers? - - Change priorities? - ---- - -## Current Status (October 2025) - -### ✅ Recent Wins -- Profiling system implemented (Issue #104) -- Benchmarks created -- F3 overlay functional -- ScopedTimer infrastructure in place - -### 🔄 In Progress -- Grid System wiki documentation (this sprint) -- Issue organization and labeling - -### ⏳ Next Up (November 2025) -- Issue #116: Grid dirty flag system -- Issue #115: SpatialHash implementation -- Issue #120: Animation property locking - -### 📅 Upcoming Milestones -- **Q4 2025:** Performance foundation complete -- **Q1 2026:** Animation system overhaul -- **Q2 2026:** Tutorial completion -- **Q2 2026:** v1.0 public release - ---- - -## Resources - -**Source Documents:** -- `FINAL_RECOMMENDATIONS.md` - Full strategic analysis (October 2023) -- `MASTER_TASK_SCHEDULE.md` - Comprehensive task catalog -- `ROADMAP.md` - High-level project roadmap - -**Related Issues:** -- [#104](../issues/104) - Profiling system (✅ complete) -- [#115](../issues/115) - SpatialHash optimization -- [#116](../issues/116) - Grid dirty flags -- [#120](../issues/120) - Animation property locking -- [#126](../issues/126) - Perfect Python interface - -**Related Wiki Pages:** -- [[Performance-and-Profiling]] - Profiling infrastructure -- [[Animation-System]] - Current animation implementation -- [[Proposal-Next-Gen-Grid-Entity-System]] - Future architecture proposal - ---- - -**Navigation:** -- [[Home]] - Documentation hub -- [[Performance-and-Profiling]] - Current performance work -- [[Animation-System]] - Animation system details \ No newline at end of file