diff --git a/Strategic-Direction.-.md b/Strategic-Direction.md similarity index 96% rename from Strategic-Direction.-.md rename to Strategic-Direction.md index 385485f..cfff17d 100644 --- a/Strategic-Direction.-.md +++ b/Strategic-Direction.md @@ -1,366 +1,366 @@ -# 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 +# 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