Add "Strategic-Direction"
parent
77a8c011e4
commit
c62b7a7b8b
|
|
@ -0,0 +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
|
||||||
Loading…
Reference in New Issue