30 KiB

Raw Blame History

McRogueFace - Development Roadmap

🚨 URGENT PRIORITIES - July 9, 2025 🚨

IMMEDIATE ACTION REQUIRED (Next 48 Hours)

CRITICAL DEADLINE: RoguelikeDev Tutorial Event starts July 15 - Need to advertise by July 11!

1. Tutorial Emergency Plan (2 DAYS)

Day 1 (July 9): Parts 1-2 (Setup, Moving @, Drawing Map, Entities)
Day 2 (July 10): Parts 3-4 (FOV, Combat/AI)
July 11: Announce on r/roguelikedev with 4 completed parts
July 12-14: Complete remaining 10 parts before event starts

1b. Sizzle Reel Demo (URGENT)

Expand animation_sizzle_reel_working.py with Grid/Entity demos:
- Grid scrolling and zooming animations
- Entity movement patterns (patrol, chase, flee)
- Particle effects using entity spawning
- Tile animation demonstrations
- Color cycling and transparency effects
- Mass entity choreography (100+ entities)
- Performance stress test with 1000+ entities

2. TCOD Integration Sprint

UIGrid TCOD Integration (8 hours)
- Add TCODMap* to UIGrid constructor
- Implement mcrfpy.libtcod.compute_fov()
- Add batch operations for NumPy-style access
- Create CellView for ergonomic .at((x,y)) access
UIEntity Pathfinding (4 hours)
- Add path_to(target) method using A*
- Implement Dijkstra maps for multiple targets
- Cache paths in UIEntity for performance

3. Performance Critical Path

Implement SpatialHash for 10,000+ entities (2 hours)
Add dirty flag system to UIGrid (1 hour)
Batch update context managers (2 hours)
Memory pool for entities (2 hours)

4. Bug Fixing Pipeline

Set up GitHub Issues automation
Create test for each bug before fixing
Track: Memory leaks, Segfaults, Python/C++ boundary errors

🎯 STRATEGIC ARCHITECTURE VISION

Three-Layer Grid Architecture (From Compass Research)

Following successful roguelike patterns (Caves of Qud, Cogmind, DCSS):

Visual Layer (UIGridPoint) - Sprites, colors, animations
World State Layer (TCODMap) - Walkability, transparency, physics
Entity Perspective Layer (UIGridPointState) - Per-entity FOV, knowledge

Performance Architecture (Critical for 1000x1000 maps)

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

Project Status: 🎉 ALPHA 0.1 RELEASE! 🎉

Current State: Documentation system complete, TCOD integration urgent
Latest Update: Completed Phase 7 documentation infrastructure (2025-07-08)
Branch: alpha_streamline_2
Open Issues: ~46 remaining + URGENT TCOD/Tutorial work

📋 TCOD Integration Implementation Details

Phase 1: Core UIGrid Integration (Day 1 Morning)

// UIGrid.h additions
class UIGrid : public UIDrawable {
private:
    TCODMap* world_state;  // Add TCOD map
    std::unordered_map<int, UIGridPointState*> entity_perspectives;
    bool batch_mode = false;
    std::vector<CellUpdate> pending_updates;

Phase 2: Python Bindings (Day 1 Afternoon)

# New API surface
grid = mcrfpy.Grid(100, 100)
grid.compute_fov(player.x, player.y, radius=10)  # Returns visible cells
grid.at((x, y)).walkable = False  # Ergonomic access
with grid.batch_update():  # Context manager for performance
    # All updates batched

Phase 3: Entity Integration (Day 2 Morning)

# UIEntity additions
entity.path_to(target_x, target_y)  # A* pathfinding
entity.flee_from(threat)  # Dijkstra map
entity.can_see(other_entity)  # FOV check

Critical Success Factors:

Batch everything - Never update single cells in loops
Lazy evaluation - Only compute FOV for entities that need it
Sparse storage - Don't store full grids per entity
Profile early - Find the 20% of code taking 80% of time

Recent Achievements

2025-07-08: PyArgHelpers Infrastructure Complete! 🔧

Standardized Python API Argument Parsing

Unified position handling: (x, y) tuples or separate x, y args
Consistent size parsing: (w, h) tuples or width, height args
Grid-specific helpers for tile-based positioning
Proper conflict detection between positional and keyword args
All UI components migrated: Frame, Caption, Sprite, Grid, Entity
Improved error messages: "Value must be a number (int or float)"
Foundation for Phase 7 documentation efforts

2025-07-05: ALPHA 0.1 ACHIEVED! 🎊🍾

All Alpha Blockers Resolved!

Z-order rendering with performance optimization (Issue #63)
Python Sequence Protocol for collections (Issue #69)
Comprehensive Animation System (Issue #59)
Moved RenderTexture to Beta (not needed for Alpha)
McRogueFace is ready for Alpha release!

2025-07-05: Z-order Rendering Complete! 🎉

Issue #63 Resolved: Consistent z-order rendering with performance optimization

Dirty flag pattern prevents unnecessary per-frame sorting
Lazy sorting for both Scene elements and Frame children
Frame children now respect z_index (fixed inconsistency)
Automatic dirty marking on z_index changes and collection modifications
Performance: O(1) check for static scenes vs O(n log n) every frame

2025-07-05: Python Sequence Protocol Complete! 🎉

Issue #69 Resolved: Full sequence protocol implementation for collections

Complete setitem, delitem, contains support
Slice operations with extended slice support (step != 1)
Concatenation (+) and in-place concatenation (+=) with validation
Negative indexing throughout, index() and count() methods
Type safety: UICollection (Frame/Caption/Sprite/Grid), EntityCollection (Entity only)
Default value support: None for texture/font parameters uses engine defaults

2025-07-05: Animation System Complete! 🎉

Issue #59 Resolved: Comprehensive animation system with 30+ easing functions

Property-based animations for all UI classes (Frame, Caption, Sprite, Grid, Entity)
Individual color component animation (r/g/b/a)
Sprite sequence animation and text typewriter effects
Pure C++ execution without Python callbacks
Delta animation support for relative values

2025-01-03: Major Stability Update

Major Cleanup: Removed deprecated registerPyAction system (-180 lines) Bug Fixes: 12 critical issues including Grid segfault, Issue #78 (middle click), Entity setters New Features: Entity.index() (#73), EntityCollection.extend() (#27), Sprite validation (#33) Test Coverage: Comprehensive test suite with timer callback pattern established

🔧 CURRENT WORK: Alpha Streamline 2 - Major Architecture Improvements

Recent Completions:

✅ Phase 1-4 Complete - Foundation, API Polish, Entity Lifecycle, Visibility/Performance
✅ Phase 5 Complete - Window/Scene Architecture fully implemented!
- Window singleton with properties (#34)
- OOP Scene support with lifecycle methods (#61)
- Window resize events (#1)
- Scene transitions with animations (#105)
✅ Phase 6 Complete - Rendering Revolution achieved!
- Grid background colors (#50) ✅
- RenderTexture overhaul (#6) ✅
- UIFrame clipping support ✅
- Viewport-based rendering (#8) ✅

Active Development:

Branch: alpha_streamline_2
Current Phase: Phase 7 - Documentation & Distribution
Achievement: PyArgHelpers infrastructure complete - standardized Python API
Strategic Vision: See STRATEGIC_VISION.md for platform roadmap
Latest: All UI components now use consistent argument parsing patterns!

🏗️ Architectural Dependencies Map

Foundation Layer:
├── #71 Base Class (_Drawable) 
│   ├── #10 Visibility System (needs AABB from base)
│   ├── #87 visible property
│   └── #88 opacity property
│
├── #7 Safe Constructors (affects all classes)
│   └── Blocks any new class creation until resolved
│
└── #30 Entity/Grid Integration (lifecycle management)
    └── Enables reliable entity management

Window/Scene Layer:
├── #34 Window Object
│   ├── #61 Scene Object (depends on Window)
│   ├── #14 SFML Exposure (helps implement Window)
│   └── Future: Multi-window support

Rendering Layer:
└── #6 RenderTexture Overhaul
    ├── Enables clipping
    ├── Off-screen rendering
    └── Post-processing effects

🚀 Alpha Streamline 2 - Comprehensive Phase Plan

Phase 1: Foundation Stabilization (1-2 weeks)

Goal: Safe, predictable base for all future work

1. #7 - Audit and fix unsafe constructors (CRITICAL - do first!)
   - Find all manually implemented no-arg constructors
   - Verify map compatibility requirements
   - Make pointer-safe or remove
   
2. #71 - _Drawable base class implementation
   - Common properties: x, y, w, h, visible, opacity
   - Virtual methods: get_bounds(), render()
   - Proper Python inheritance setup
   
3. #87 - visible property
   - Add to base class
   - Update all render methods to check
   
4. #88 - opacity property (depends on #87)
   - 0.0-1.0 float range
   - Apply in render methods
   
5. #89 - get_bounds() method
   - Virtual method returning (x, y, w, h)
   - Override in each UI class
   
6. #98 - move()/resize() convenience methods
   - move(dx, dy) - relative movement
   - resize(w, h) - absolute sizing

Rationale: Can't build on unsafe foundations. Base class enables all UI improvements.

Phase 2: Constructor & API Polish (1 week)

Goal: Pythonic, intuitive API

1. #101 - Standardize (0,0) defaults for all positions
2. #38 - Frame children parameter: Frame(children=[...])
3. #42 - Click handler in __init__: Button(click=callback)
4. #90 - Grid size tuple: Grid(grid_size=(10, 10))
5. #19 - Sprite texture swapping: sprite.texture = new_texture
6. #52 - Grid skip out-of-bounds entities (performance)

Rationale: Quick wins that make the API more pleasant before bigger changes.

Phase 3: Entity Lifecycle Management (1 week)

Goal: Bulletproof entity/grid relationships

1. #30 - Entity.die() and grid association
   - Grid.entities.append(e) sets e.grid = self
   - Grid.entities.remove(e) sets e.grid = None
   - Entity.die() calls self.grid.remove(self)
   - Entity can only be in 0 or 1 grid
   
2. #93 - Vector arithmetic methods
   - add, subtract, multiply, divide
   - distance, normalize, dot product
   
3. #94 - Color helper methods
   - from_hex("#FF0000"), to_hex()
   - lerp(other_color, t) for interpolation
   
4. #103 - Timer objects
   timer = mcrfpy.Timer("my_timer", callback, 1000)
   timer.pause()
   timer.resume()
   timer.cancel()

Rationale: Games need reliable entity management. Timer objects enable entity AI.

Phase 4: Visibility & Performance (1-2 weeks)

Goal: Only render/process what's needed

1. #10 - [UNSCHEDULED] Full visibility system with AABB
   - Postponed: UIDrawables can exist in multiple collections
   - Cannot reliably determine screen position due to multiple render contexts
   - Needs architectural solution for parent-child relationships
   
2. #52 - Grid culling (COMPLETED in Phase 2)
   
3. #39/40/41 - Name system for finding elements
   - name="button1" property on all UIDrawables
   - only_one=True for unique names
   - scene.find("button1") returns element
   - collection.find("enemy*") returns list
   
4. #104 - Basic profiling/metrics
   - Frame time tracking
   - Draw call counting
   - Python vs C++ time split

Rationale: Performance is feature. Finding elements by name is huge QoL.

Phase 5: Window/Scene Architecture ✅ COMPLETE! (2025-07-06)

Goal: Modern, flexible architecture

1. ✅ #34 - Window object (singleton first)
   window = mcrfpy.Window.get()
   window.resolution = (1920, 1080)
   window.fullscreen = True
   window.vsync = True
   
2. ✅ #1 - Window resize events
   scene.on_resize(self, width, height) callback implemented
   
3. ✅ #61 - Scene object (OOP scenes)
   class MenuScene(mcrfpy.Scene):
       def on_keypress(self, key, state):
           # handle input
       def on_enter(self):
           # setup UI
       def on_exit(self):
           # cleanup
       def update(self, dt):
           # frame update
           
4. ✅ #14 - SFML exposure research
   - Completed comprehensive analysis
   - Recommendation: Direct integration as mcrfpy.sfml
   - SFML 3.0 migration deferred to late 2025
   
5. ✅ #105 - Scene transitions
   mcrfpy.setScene("menu", "fade", 1.0)
   # Supports: fade, slide_left, slide_right, slide_up, slide_down

Result: Entire window/scene system modernized with OOP design!

Phase 6: Rendering Revolution (3-4 weeks) ✅ COMPLETE!

Goal: Professional rendering capabilities

1. ✅ #50 - Grid background colors [COMPLETED]
   grid.background_color = mcrfpy.Color(50, 50, 50)
   - Added background_color property with animation support
   - Default dark gray background (8, 8, 8, 255)
   
2. ✅ #6 - RenderTexture overhaul [COMPLETED]
   ✅ Base infrastructure in UIDrawable
   ✅ UIFrame clip_children property
   ✅ Dirty flag optimization system
   ✅ Nested clipping support
   ✅ UIGrid already has appropriate RenderTexture implementation
   ❌ UICaption/UISprite clipping not needed (no children)
   
3. ✅ #8 - Viewport-based rendering [COMPLETED]
   - Fixed game resolution (window.game_resolution)
   - Three scaling modes: "center", "stretch", "fit"
   - Window to game coordinate transformation
   - Mouse input properly scaled with windowToGameCoords()
   - Python API fully integrated
   - Tests: test_viewport_simple.py, test_viewport_visual.py, test_viewport_scaling.py
   
4. #106 - Shader support [DEFERRED TO POST-PHASE 7]
   sprite.shader = mcrfpy.Shader.load("glow.frag")
   frame.shader_params = {"intensity": 0.5}
   
5. #107 - Particle system [DEFERRED TO POST-PHASE 7]
   emitter = mcrfpy.ParticleEmitter()
   emitter.texture = spark_texture
   emitter.emission_rate = 100
   emitter.lifetime = (0.5, 2.0)

Phase 6 Achievement Summary:

Grid backgrounds (#50) ✅ - Customizable background colors with animation
RenderTexture overhaul (#6) ✅ - UIFrame clipping with opt-in architecture
Viewport rendering (#8) ✅ - Three scaling modes with coordinate transformation
UIGrid already had optimal RenderTexture implementation for its use case
UICaption/UISprite clipping unnecessary (no children to clip)
Performance optimized with dirty flag system
Backward compatibility preserved throughout
Effects/Shader/Particle systems deferred for focused delivery

Rationale: This unlocks professional visual effects but is complex.

Phase 7: Documentation & Distribution (1-2 weeks)

Goal: Ready for the world

1. ✅ #85 - Replace all "docstring" placeholders [COMPLETED 2025-07-08]
2. ✅ #86 - Add parameter documentation [COMPLETED 2025-07-08]
3. ✅ #108 - Generate .pyi type stubs for IDE support [COMPLETED 2025-07-08]
4. ❌ #70 - PyPI wheel preparation [CANCELLED - Architectural mismatch]
5. API reference generator tool

📋 Critical Path & Parallel Tracks

🔴 Critical Path (Must do in order)

Safe Constructors (#7) → Base Class (#71) → Visibility (#10) → Window (#34) → Scene (#61)

🟡 Parallel Tracks (Can be done alongside critical path)

Track A: Entity Systems

Entity/Grid integration (#30)
Timer objects (#103)
Vector/Color helpers (#93, #94)

Track B: API Polish

Constructor improvements (#101, #38, #42, #90)
Sprite texture swap (#19)
Name/search system (#39/40/41)

Track C: Performance

Grid culling (#52)
Visibility culling (part of #10)
Profiling tools (#104)

💎 Quick Wins to Sprinkle Throughout

Color helpers (#94) - 1 hour
Vector methods (#93) - 1 hour
Grid backgrounds (#50) - 30 minutes
Default positions (#101) - 30 minutes

🎯 Recommended Execution Order

Week 1-2: Foundation (Critical constructors + base class)
Week 3: Entity lifecycle + API polish
Week 4: Visibility system + performance
Week 5-6: Window/Scene architecture
Week 7-9: Rendering revolution (or defer to gamma)
Week 10: Documentation + release prep

🆕 New Issues to Create/Track

Timer Objects - Pythonic timer management (#103) - Completed Phase 3
Event System Enhancement - Mouse enter/leave, drag, right-click
Resource Manager - Centralized asset loading
Serialization System - Save/load game state
Scene Transitions - Fade, slide, custom effects (#105) - Completed Phase 5
Profiling Tools - Performance metrics (#104) - Completed Phase 4
Particle System - Visual effects framework (#107)
Shader Support - Custom rendering effects (#106)

📋 Phase 6 Implementation Strategy

RenderTexture Overhaul (#6) - Technical Approach

Current State:

UIGrid already uses RenderTexture for entity rendering
Scene transitions use RenderTextures for smooth animations
Direct rendering to window for Frame, Caption, Sprite

Implementation Plan:

Base Infrastructure:
- Add sf::RenderTexture* target to UIDrawable base
- Modify render() to check if target exists
- If target: render to texture, then draw texture to parent
- If no target: render directly (backward compatible)
Clipping Support:
- Frame enforces bounds on children via RenderTexture
- Children outside bounds are automatically clipped
- Nested frames create render texture hierarchy
Performance Optimization:
- Lazy RenderTexture creation (only when needed)
- Dirty flag system (only re-render when changed)
- Texture pooling for commonly used sizes
Integration Points:
- Scene transitions already working with RenderTextures
- UIGrid can be reference implementation
- Test with deeply nested UI structures

Quick Wins Before Core Work:

Grid Background (#50) - 30 min implementation
- Add background_color and background_texture properties
- Render before entities in UIGrid::render()
- Good warm-up before tackling RenderTexture
Research Tasks:
- Study UIGrid's current RenderTexture usage
- Profile scene transition performance
- Identify potential texture size limits

🚀 NEXT PHASE: Beta Features & Polish

Alpha Complete! Moving to Beta Priorities:

#69 - Python Sequence Protocol for collections - Completed! (2025-07-05)
#63 - Z-order rendering for UIDrawables - Completed! (2025-07-05)
#59 - Animation system - Completed! (2025-07-05)
#6 - RenderTexture concept - Extensive Overhaul
#47 - New README.md for Alpha release - Completed

#78 - Middle Mouse Click sends "C" keyboard event - Fixed
#77 - Fix error message copy/paste bug - Fixed
#74 - Add missing Grid.grid_y property - Fixed
#37 - Fix Windows build module import from "scripts" directory - Isolated Fix Issue #37 is on hold until we have a Windows build environment available. I actually suspect this is already fixed by the updates to the makefile, anyway.
Entity Property Setters - Fix "new style getargs format" error - Fixed
Sprite Texture Setter - Fix "error return without exception set" - Fixed
keypressScene() Validation - Add proper error handling - Fixed

🔄 Complete Iterator System

Status: Core iterators complete (#72 closed), Grid point iterators still pending

Grid Point Iterator Implementation - Complete the remaining grid iteration work
#73 - Add entity.index() method for collection removal - Fixed
#69 ⚠️ Alpha Blocker - Refactor all collections to use Python Sequence Protocol - Completed! (2025-07-05)

Dependencies: Grid point iterators → #73 entity.index() → #69 Sequence Protocol overhaul

🗂 ISSUE TRIAGE BY SYSTEM (78 Total Issues)

🎮 Core Engine Systems

Iterator/Collection System (2 issues)

#73 - Entity index() method for removal - Fixed
#69 ⚠️ Alpha Blocker - Sequence Protocol refactor - Completed! (2025-07-05)

Python/C++ Integration (7 issues)

#76 - UIEntity derived type preservation in collections - Multiple Integrations
#71 - Drawable base class hierarchy - Extensive Overhaul
#70 - PyPI wheel distribution - Extensive Overhaul
[~] #32 - Executable behave like python command - Extensive Overhaul (90% Complete: -h, -V, -c, -m, -i, script execution, sys.argv, --exec all implemented. Only stdin (-) support missing)
#35 - TCOD as built-in module - Extensive Overhaul
[~] #14 - Expose SFML as built-in module - Research Complete, Implementation Pending
#46 - Subinterpreter threading tests - Multiple Integrations

UI/Rendering System (12 issues)

#63 ⚠️ Alpha Blocker - Z-order for UIDrawables - Multiple Integrations
#59 ⚠️ Alpha Blocker - Animation system - Completed! (2025-07-05)
#6 ⚠️ Alpha Blocker - RenderTexture for all UIDrawables - Extensive Overhaul
#10 - UIDrawable visibility/AABB system - Extensive Overhaul
#8 - UIGrid RenderTexture viewport sizing - Multiple Integrations
#9 - UIGrid RenderTexture resize handling - Multiple Integrations
#52 - UIGrid skip out-of-bounds entities - Isolated Fix
#50 - UIGrid background color field - Isolated Fix
#19 - Sprite get/set texture methods - Multiple Integrations
#17 - Move UISprite position into sf::Sprite - Isolated Fix
#33 - Sprite index validation against texture range - Fixed

Grid/Entity System (6 issues)

#30 - Entity/Grid association management (.die() method) - Extensive Overhaul
#16 - Grid strict mode for entity knowledge/visibility - Extensive Overhaul
#67 - Grid stitching for infinite worlds - Extensive Overhaul
#15 - UIGridPointState cleanup and standardization - Multiple Integrations
#20 - UIGrid get_grid_size standardization - Multiple Integrations
#12 - GridPoint/GridPointState forbid direct init - Isolated Fix

Scene/Window Management (5 issues)

#61 - Scene object encapsulating key callbacks - Completed Phase 5
#34 - Window object for resolution/scaling - Completed Phase 5
#62 - Multiple windows support - Extensive Overhaul
#49 - Window resolution & viewport controls - Multiple Integrations
#1 - Scene resize event handling - Completed Phase 5

🔧 Quality of Life Features

UI Enhancement Features (8 issues)

#39 - Name field on UIDrawables - Multiple Integrations
#40 - only_one arg for unique naming - Multiple Integrations
#41 - .find(name) method for collections - Multiple Integrations
#38 - children arg for Frame initialization - Isolated Fix
#42 - Click callback arg for UIDrawable init - Isolated Fix
#27 - UIEntityCollection.extend() method - Fixed
#28 - UICollectionIter for scene ui iteration - Isolated Fix
#26 - UIEntityCollectionIter implementation - Isolated Fix

🧹 Refactoring & Cleanup

Code Cleanup (7 issues)

#3 ⚠️ Alpha Blocker - Remove McRFPy_API::player_input - Completed
#2 ⚠️ Alpha Blocker - Review registerPyAction necessity - Completed
#7 - Remove unsafe no-argument constructors - Multiple Integrations
#21 - PyUIGrid dealloc cleanup - Isolated Fix
#75 - REPL thread separation from SFML window - Multiple Integrations

📚 Demo & Documentation

Documentation (2 issues)

#47 ⚠️ Alpha Blocker - Alpha release README.md - Isolated Fix
#48 - Dependency compilation documentation - Isolated Fix

Demo Projects (6 issues)

#54 - Jupyter notebook integration demo - Multiple Integrations
#55 - Hunt the Wumpus AI demo - Multiple Integrations
#53 - Web interface input demo - Multiple Integrations (New automation API could help)
#45 - Accessibility mode demos - Multiple Integrations (New automation API could help test)
#36 - Dear ImGui integration tests - Extensive Overhaul
#65 - Python Explorer scene (replaces uitest) - Extensive Overhaul

🎮 STRATEGIC DIRECTION

Engine Philosophy Maintained

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

Architecture Goals

Clean Inheritance: Drawable → UI components, proper type preservation
Collection Consistency: Uniform iteration, indexing, and search patterns
Resource Management: RAII everywhere, proper lifecycle handling
Multi-Platform: Windows/Linux feature parity maintained

📚 REFERENCES & CONTEXT

Issue Dependencies (Key Chains):

Iterator System: Grid points → #73 → #69 (Alpha Blocker)
UI Hierarchy: #71 → #63 (Alpha Blocker)
Rendering: #6 (Alpha Blocker) → #8, #9 → #10
Entity System: #30 → #16 → #67
Window Management: #34 → #49, #61 → #62

Commit References:

167636c: Iterator improvements (UICollection/UIEntityCollection complete)
Recent work: 7DRL 2025 completion, RPATH updates, console improvements

Architecture Files:

Iterator patterns: src/UICollection.cpp, src/UIGrid.cpp
Python integration: src/McRFPy_API.cpp, src/PyObjectUtils.h
Game implementation: src/scripts/ (Crypt of Sokoban complete game)

🔮 FUTURE VISION: Pure Python Extension Architecture

Concept: McRogueFace as a Traditional Python Package

Status: Unscheduled - Long-term vision Complexity: Major architectural overhaul

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

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

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

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

Implementation Phases (If Pursued)

Proof of Concept: Simple SFML binding as Python extension
Core Extraction: Separate rendering from Python embedding
Module Design: Define clean API boundaries
Incremental Migration: Move systems one at a time
Compatibility Layer: Support existing games during transition

Example Usage (Future Vision)

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.

🚀 IMMEDIATE NEXT STEPS (Priority Order)

Today (July 9) - EXECUTE NOW:

Start Tutorial Part 1 - Basic setup and @ movement (2 hours)
Implement UIGrid.at((x,y)) - CellView pattern (1 hour)
Create Grid demo for sizzle reel (1 hour)
Fix any blocking bugs discovered during tutorial writing

Tomorrow (July 10) - CRITICAL PATH:

Tutorial Parts 2-4 - Map drawing, entities, FOV, combat
Implement compute_fov() in UIGrid
Add batch_update context manager
Expand sizzle reel with entity choreography

July 11 - ANNOUNCEMENT DAY:

Polish 4 tutorial parts
Create announcement post for r/roguelikedev
Record sizzle reel video
Submit announcement by end of day

Architecture Decision Log:

DECIDED: Use three-layer architecture (visual/world/perspective)
DECIDED: Spatial hashing over quadtrees for entities
DECIDED: Batch operations are mandatory, not optional
DECIDED: TCOD integration as mcrfpy.libtcod submodule
DECIDED: Tutorial must showcase McRogueFace strengths, not mimic TCOD

Risk Mitigation:

If TCOD integration delays: Use pure Python FOV for tutorial
If performance issues: Focus on <100x100 maps for demos
If tutorial incomplete: Ship with 4 solid parts + roadmap
If bugs block progress: Document as "known issues" and continue

Last Updated: 2025-07-09 (URGENT SPRINT MODE) Next Review: July 11 after announcement

30 KiB Raw Blame History