Update roadmap for 7DRL 2026 and post-jam 1.0 planning
Rewrite ROADMAP.md to reflect current project state: - Summarize 0.2 series shipped features (3D/voxel, procgen, Tiled/LDtk, WASM, animation callbacks, multi-layer grids, doc macros) - 7DRL 2026 dates (Feb 28 - Mar 8) and remaining prep - Post-jam priorities: API freeze process, pain point fixes, roguelikedev tutorial series, pip/virtualenv integration - Engine eras model (McRogueFace -> McVectorFace -> McVoxelFace) - Future directions: McRogueFace Lite (MicroPython/PicoCalc), standard library widgets, package management - Open issue groupings (30 issues across 8 areas) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
parent
9176dca055
commit
4404d1082a
1 changed files with 82 additions and 185 deletions
267
ROADMAP.md
267
ROADMAP.md
|
|
@ -1,223 +1,120 @@
|
|||
# McRogueFace - Development Roadmap
|
||||
|
||||
## Project Status
|
||||
**Version**: 0.2.6-prerelease | **Era**: McRogueFace (2D roguelikes)
|
||||
|
||||
**Current State**: Active development - C++ game engine with Python scripting
|
||||
**Latest Release**: Alpha 0.1
|
||||
**Issue Tracking**: See [Gitea Issues](https://gamedev.ffwf.net/gitea/john/McRogueFace/issues) for current tasks and bugs
|
||||
For detailed architecture, philosophy, and decision framework, see the [Strategic Direction](https://gamedev.ffwf.net/gitea/john/McRogueFace/wiki/Strategic-Direction) wiki page. For per-issue tracking, see the [Issue Roadmap](https://gamedev.ffwf.net/gitea/john/McRogueFace/wiki/Issue-Roadmap).
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Strategic Vision
|
||||
## What Has Shipped
|
||||
|
||||
### Engine Philosophy
|
||||
**Alpha 0.1** (2024) -- First complete release. Milestone: all datatypes behaving.
|
||||
|
||||
- **C++ First**: Performance-critical code stays in C++
|
||||
- **Python Close Behind**: Rich scripting without frame-rate impact
|
||||
- **Game-Ready**: Each improvement should benefit actual game development
|
||||
**0.2 series** (Jan-Feb 2026) -- Weekly updates to GitHub. Key additions:
|
||||
- 3D/Voxel pipeline (experimental): Viewport3D, Camera3D, Entity3D, VoxelGrid with greedy meshing and serialization
|
||||
- Procedural generation: HeightMap, BSP, NoiseSource, DiscreteMap
|
||||
- Tiled and LDtk import with Wang tile / AutoRule resolution
|
||||
- Emscripten/SDL2 backend for WebAssembly deployment
|
||||
- Animation callbacks, mouse event system, grid cell callbacks
|
||||
- Multi-layer grid system with chunk-based rendering and dirty-flag caching
|
||||
- Documentation macro system with auto-generated API docs, man pages, and type stubs
|
||||
- Windows cross-compilation, mobile-ish WASM support, SDL2_mixer audio
|
||||
|
||||
### Architecture Goals
|
||||
|
||||
1. **Clean Inheritance**: Drawable → UI components, proper type preservation
|
||||
2. **Collection Consistency**: Uniform iteration, indexing, and search patterns
|
||||
3. **Resource Management**: RAII everywhere, proper lifecycle handling
|
||||
4. **Multi-Platform**: Windows/Linux feature parity maintained
|
||||
**Proving grounds**: Crypt of Sokoban (7DRL 2025) was the first complete game. 7DRL 2026 is the current target.
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ Architecture Decisions
|
||||
## Current Focus: 7DRL 2026
|
||||
|
||||
### Three-Layer Grid Architecture
|
||||
Following successful roguelike patterns (Caves of Qud, Cogmind, DCSS):
|
||||
**Dates**: February 28 -- March 8, 2026
|
||||
|
||||
1. **Visual Layer** (UIGridPoint) - Sprites, colors, animations
|
||||
2. **World State Layer** (TCODMap) - Walkability, transparency, physics
|
||||
3. **Entity Perspective Layer** (UIGridPointState) - Per-entity FOV, knowledge
|
||||
Engine preparation is complete. All 2D systems are production-ready. The jam will expose remaining rough edges in the workflow of building a complete game on McRogueFace.
|
||||
|
||||
### Performance Architecture
|
||||
Critical for large maps (1000x1000):
|
||||
|
||||
- **Spatial Hashing** for entity queries (not quadtrees!)
|
||||
- **Batch Operations** with context managers (10-100x speedup)
|
||||
- **Memory Pooling** for entities and components
|
||||
- **Dirty Flag System** to avoid unnecessary updates
|
||||
- **Zero-Copy NumPy Integration** via buffer protocol
|
||||
|
||||
### Key Insight from Research
|
||||
"Minimizing Python/C++ boundary crossings matters more than individual function complexity"
|
||||
- Batch everything possible
|
||||
- Use context managers for logical operations
|
||||
- Expose arrays, not individual cells
|
||||
- Profile and optimize hot paths only
|
||||
Open prep items:
|
||||
- **#248** -- Crypt of Sokoban Remaster (game content for the jam)
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Development Phases
|
||||
## Post-7DRL: The Road to 1.0
|
||||
|
||||
For detailed task tracking and current priorities, see the [Gitea issue tracker](https://gamedev.ffwf.net/gitea/john/McRogueFace/issues).
|
||||
After 7DRL, the priority shifts from feature development to **API stability**. 1.0 means the Python API is frozen: documented, stable, and not going to break.
|
||||
|
||||
### Phase 1: Foundation Stabilization ✅
|
||||
**Status**: Complete
|
||||
**Key Issues**: #7 (Safe Constructors), #71 (Base Class), #87 (Visibility), #88 (Opacity)
|
||||
### API Freeze Process
|
||||
1. Catalog every public Python class, method, and property
|
||||
2. Identify anything that should change before committing (naming, signatures, defaults)
|
||||
3. Make breaking changes in a single coordinated pass
|
||||
4. Document the stable API as the contract
|
||||
5. Experimental modules (3D/Voxel) get an explicit `experimental` label and are exempt from the freeze
|
||||
|
||||
### Phase 2: Constructor & API Polish ✅
|
||||
**Status**: Complete
|
||||
**Key Features**: Pythonic API, tuple support, standardized defaults
|
||||
|
||||
### Phase 3: Entity Lifecycle Management ✅
|
||||
**Status**: Complete
|
||||
**Key Issues**: #30 (Entity.die()), #93 (Vector methods), #94 (Color helpers), #103 (Timer objects)
|
||||
|
||||
### Phase 4: Visibility & Performance ✅
|
||||
**Status**: Complete
|
||||
**Key Features**: AABB culling, name system, profiling tools
|
||||
|
||||
### Phase 5: Window/Scene Architecture ✅
|
||||
**Status**: Complete
|
||||
**Key Issues**: #34 (Window object), #61 (Scene object), #1 (Resize events), #105 (Scene transitions)
|
||||
|
||||
### Phase 6: Rendering Revolution ✅
|
||||
**Status**: Complete
|
||||
**Key Issues**: #50 (Grid backgrounds), #6 (RenderTexture), #8 (Viewport rendering)
|
||||
|
||||
### Phase 7: Documentation & Distribution ✅
|
||||
**Status**: Complete (2025-10-30)
|
||||
**Key Issues**: #85 (Docstrings), #86 (Parameter docs), #108 (Type stubs), #97 (API docs)
|
||||
**Completed**: All classes and functions converted to MCRF_* macro system with automated HTML/Markdown/man page generation
|
||||
|
||||
See [current open issues](https://gamedev.ffwf.net/gitea/john/McRogueFace/issues?state=open) for active work.
|
||||
### Post-Jam Priorities
|
||||
- Fix pain points discovered during actual 7DRL game development
|
||||
- Progress on the r/roguelikedev tutorial series (#167)
|
||||
- API consistency audit and freeze
|
||||
- Better pip/virtualenv integration for adding packages to McRogueFace's embedded interpreter
|
||||
|
||||
---
|
||||
|
||||
## 🔮 Future Vision: Pure Python Extension Architecture
|
||||
## Engine Eras
|
||||
|
||||
### Concept: McRogueFace as a Traditional Python Package
|
||||
**Status**: Long-term vision
|
||||
**Complexity**: Major architectural overhaul
|
||||
One engine, accumulating capabilities. Nothing is thrown away.
|
||||
|
||||
Instead of being a C++ application that embeds Python, McRogueFace could be redesigned as a pure Python extension module that can be installed via `pip install mcrogueface`.
|
||||
|
||||
### Technical Approach
|
||||
|
||||
1. **Separate Core Engine from Python Embedding**
|
||||
- Extract SFML rendering, audio, and input into C++ extension modules
|
||||
- Remove embedded CPython interpreter
|
||||
- Use Python's C API to expose functionality
|
||||
|
||||
2. **Module Structure**
|
||||
```
|
||||
mcrfpy/
|
||||
├── __init__.py # Pure Python coordinator
|
||||
├── _core.so # C++ rendering/game loop extension
|
||||
├── _sfml.so # SFML bindings
|
||||
├── _audio.so # Audio system bindings
|
||||
└── engine.py # Python game engine logic
|
||||
```
|
||||
|
||||
3. **Inverted Control Flow**
|
||||
- Python drives the main loop instead of C++
|
||||
- C++ extensions handle performance-critical operations
|
||||
- Python manages game logic, scenes, and entity systems
|
||||
|
||||
### Benefits
|
||||
|
||||
- **Standard Python Packaging**: `pip install mcrogueface`
|
||||
- **Virtual Environment Support**: Works with venv, conda, poetry
|
||||
- **Better IDE Integration**: Standard Python development workflow
|
||||
- **Easier Testing**: Use pytest, standard Python testing tools
|
||||
- **Cross-Python Compatibility**: Support multiple Python versions
|
||||
- **Modular Architecture**: Users can import only what they need
|
||||
|
||||
### Challenges
|
||||
|
||||
- **Major Refactoring**: Complete restructure of codebase
|
||||
- **Performance Considerations**: Python-driven main loop overhead
|
||||
- **Build Complexity**: Multiple extension modules to compile
|
||||
- **Platform Support**: Need wheels for many platform/Python combinations
|
||||
- **API Stability**: Would need careful design to maintain compatibility
|
||||
|
||||
### Example Usage (Future Vision)
|
||||
|
||||
```python
|
||||
import mcrfpy
|
||||
from mcrfpy import Scene, Frame, Sprite, Grid
|
||||
|
||||
# Create game directly in Python
|
||||
game = mcrfpy.Game(width=1024, height=768)
|
||||
|
||||
# Define scenes using Python classes
|
||||
class MainMenu(Scene):
|
||||
def on_enter(self):
|
||||
self.ui.append(Frame(100, 100, 200, 50))
|
||||
self.ui.append(Sprite("logo.png", x=400, y=100))
|
||||
|
||||
def on_keypress(self, key, pressed):
|
||||
if key == "ENTER" and pressed:
|
||||
self.game.set_scene("game")
|
||||
|
||||
# Run the game
|
||||
game.add_scene("menu", MainMenu())
|
||||
game.run()
|
||||
```
|
||||
|
||||
This architecture would make McRogueFace a first-class Python citizen, following standard Python packaging conventions while maintaining high performance through C++ extensions.
|
||||
| Era | Focus | Status |
|
||||
|-----|-------|--------|
|
||||
| **McRogueFace** | 2D tiles, roguelike systems, procgen | Active -- approaching 1.0 |
|
||||
| **McVectorFace** | Sparse grids, vector graphics, physics | Planned |
|
||||
| **McVoxelFace** | Voxel terrain, 3D gameplay | Proof-of-concept complete |
|
||||
|
||||
---
|
||||
|
||||
## 📋 Major Feature Areas
|
||||
## 3D/Voxel Pipeline (Experimental)
|
||||
|
||||
For current status and detailed tasks, see the corresponding Gitea issue labels:
|
||||
The 3D pipeline is proof-of-concept scouting for the McVoxelFace era. It works and is tested but is explicitly **not** part of the 1.0 API freeze.
|
||||
|
||||
### Core Systems
|
||||
- **UI/Rendering System**: Issues tagged `[Major Feature]` related to rendering
|
||||
- **Grid/Entity System**: Pathfinding, FOV, entity management
|
||||
- **Animation System**: Property animation, easing functions, callbacks
|
||||
- **Scene/Window Management**: Scene lifecycle, transitions, viewport
|
||||
**What exists**: Viewport3D, Camera3D, Entity3D, MeshLayer, Model3D (glTF), Billboard, Shader3D, VoxelGrid with greedy meshing, face culling, RLE serialization, and navigation projection.
|
||||
|
||||
### Performance Optimization
|
||||
- **#115**: SpatialHash for 10,000+ entities
|
||||
- **#116**: Dirty flag system
|
||||
- **#113**: Batch operations for NumPy-style access
|
||||
- **#117**: Memory pool for entities
|
||||
**Known gaps**: Some Entity3D collection methods, animation stubs, shader pipeline incomplete.
|
||||
|
||||
### Advanced Features
|
||||
- **#118**: Scene as Drawable (scenes can be drawn/animated)
|
||||
- **#122**: Parent-Child UI System
|
||||
- **#123**: Grid Subgrid System (256x256 chunks)
|
||||
- **#124**: Grid Point Animation
|
||||
- **#106**: Shader support
|
||||
- **#107**: Particle system
|
||||
|
||||
### Documentation
|
||||
- **#92**: Inline C++ documentation system
|
||||
- **#91**: Python type stub files (.pyi)
|
||||
- **#97**: Automated API documentation extraction
|
||||
- **#126**: Generate perfectly consistent Python interface
|
||||
**Maturity track**: These modules will mature on their own timeline, driven by games that need 3D. They won't block 2D stability.
|
||||
|
||||
---
|
||||
|
||||
## 📚 Resources
|
||||
## Future Directions
|
||||
|
||||
These are ideas on the horizon -- not yet concrete enough for issues, but worth capturing.
|
||||
|
||||
### McRogueFace Lite
|
||||
A spiritual port to MicroPython targeting the PicoCalc and other microcontrollers. Could provide a migration path to retro ROMs or compete in the Pico-8 space. The core idea: strip McRogueFace down to its essential tile/entity/scene model and run it on constrained hardware.
|
||||
|
||||
### McVectorFace Era
|
||||
The next major capability expansion. Sparse grid layers, a polygon/shape rendering class, and eventually physics integration. This would support games that aren't purely tile-based -- top-down action, strategy maps with irregular regions, or hybrid tile+vector visuals. See the [Strategic Direction](https://gamedev.ffwf.net/gitea/john/McRogueFace/wiki/Strategic-Direction) wiki for the full era model.
|
||||
|
||||
### McRogueFace Standard Library
|
||||
A built-in collection of reusable GUI widgets and game UI patterns: menus, dialogs, inventory screens, stat bars, text input fields, scrollable lists. These would ship with the engine as importable Python modules, saving every game from reimplementing the same UI primitives. Think of it as `mcrfpy.widgets` -- batteries included.
|
||||
|
||||
### Pip/Virtualenv Integration
|
||||
Rather than inverting the architecture to make McRogueFace a pip-installable package, the nearer-term goal is better integration in the other direction: making it easy to install and use third-party Python packages within McRogueFace's embedded interpreter. This could mean virtualenv awareness, a `mcrf install` command, or bundling pip itself.
|
||||
|
||||
---
|
||||
|
||||
## Open Issues by Area
|
||||
|
||||
30 open issues across the tracker. Key groupings:
|
||||
|
||||
- **Multi-tile entities** (#233-#237) -- Oversized sprites, composite entities, origin offsets
|
||||
- **Grid enhancements** (#152, #149, #67) -- Sparse layers, refactoring, infinite worlds
|
||||
- **Performance** (#117, #124, #145) -- Memory pools, grid point animation, texture reuse
|
||||
- **LLM agent testbed** (#154, #156, #55) -- Multi-agent simulation, turn-based orchestration
|
||||
- **Platform/distribution** (#70, #54, #62, #53) -- Packaging, Jupyter, multiple windows, input methods
|
||||
- **WASM tooling** (#238-#240) -- Debug infrastructure, automated browser testing, troubleshooting docs
|
||||
- **Rendering** (#107, #218) -- Particle system, Color/Vector animation targets
|
||||
|
||||
See the [Gitea issue tracker](https://gamedev.ffwf.net/gitea/john/McRogueFace/issues) for current status.
|
||||
|
||||
---
|
||||
|
||||
## Resources
|
||||
|
||||
- **Issue Tracker**: [Gitea Issues](https://gamedev.ffwf.net/gitea/john/McRogueFace/issues)
|
||||
- **Source Code**: [Gitea Repository](https://gamedev.ffwf.net/gitea/john/McRogueFace)
|
||||
- **Documentation**: See `CLAUDE.md` for build instructions and development guide
|
||||
- **Tutorial**: See `roguelike_tutorial/` for implementation examples
|
||||
- **Workflow**: See "Gitea-First Workflow" section in `CLAUDE.md` for issue management best practices
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Development Workflow
|
||||
|
||||
**Gitea is the Single Source of Truth** for this project. Before starting any work:
|
||||
|
||||
1. **Check Gitea Issues** for existing tasks, bugs, or related work
|
||||
2. **Create granular issues** for new features or problems
|
||||
3. **Update issues** when work affects other systems
|
||||
4. **Document discoveries** - if something is undocumented or misleading, create a task to fix it
|
||||
5. **Cross-reference commits** with issue numbers (e.g., "Fixes #104")
|
||||
|
||||
See the "Gitea-First Workflow" section in `CLAUDE.md` for detailed guidelines on efficient development practices using the Gitea MCP tools.
|
||||
|
||||
---
|
||||
|
||||
*For current priorities, task tracking, and bug reports, please use the [Gitea issue tracker](https://gamedev.ffwf.net/gitea/john/McRogueFace/issues).*
|
||||
- **Wiki**: [Strategic Direction](https://gamedev.ffwf.net/gitea/john/McRogueFace/wiki/Strategic-Direction), [Issue Roadmap](https://gamedev.ffwf.net/gitea/john/McRogueFace/wiki/Issue-Roadmap), [Development Workflow](https://gamedev.ffwf.net/gitea/john/McRogueFace/wiki/Development-Workflow)
|
||||
- **Build Guide**: See `CLAUDE.md` for build instructions
|
||||
- **Tutorial**: `roguelike_tutorial/` for implementation examples
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue