john/McRogueFace
1
0
Fork 0
Code Issues 32 Pull requests Projects Releases Wiki Activity
Page: Design Proposals
Pages
AI and Pathfinding Adding Python Bindings Animation System Design Proposals Development Workflow Entity Management Grid Interaction Patterns Grid Rendering Pipeline Grid System Grid TCOD Integration Headless Mode Home Input and Events Issue Roadmap LLM Agent Testbed Architecture Performance Optimization Workflow Performance and Profiling Procedural-Generation Proposal: Next Generation Grid & Entity System Python Binding Layer Rendering and Visuals Strategic Direction UI Component Hierarchy UI Widget Patterns Writing Tests
3 Design Proposals
John McCardle edited this page 2026-02-07 23:48:04 +00:00
Table of Contents

Design Proposals

This page indexes major architectural proposals and design documents for McRogueFace.

Related Pages:

Active Proposals

Next-Generation Grid & Entity System

Page: Proposal-Next-Gen-Grid-Entity-System Status: Partially Implemented Complexity: Major architectural overhaul

Overview: Comprehensive redesign of UIEntity/UIGrid systems to support:

  • Flexible entity content (any UIDrawable, not just sprites)
  • Multi-tile entities (2x2, 3x3, arbitrary sizes)
  • Spatial optimization (O(1) entity queries)
  • Memory efficiency (optional gridstate, chunk loading)

Completed Phases:

  • Phase 1 (Performance): SpatialHash (#115 - Closed), dirty flags (#116 - Closed), batch operations (#113 - Closed)
  • Dynamic layer system (#147 - Closed)
  • Chunk-based rendering (#123 - Closed)
  • Dirty flag RenderTexture caching (#148 - Closed)

Remaining:

  • #117 - Memory pool for entities (Open)
  • #124 - Grid point animation (Open)
  • Multi-tile entity support (#233, #236, #237 - Open)

Proposal Process

Submitting a Proposal

  1. Identify the problem - What limitation are we addressing?
  2. Research current system - Document existing architecture and shortcomings
  3. Draft proposal - Create wiki page with problem statement, solution, migration path, performance impact
  4. Link related issues - Connect to Gitea issues
  5. Request review - Discussion in issue comments

Proposal Template

# Proposal: [Feature Name]

**Status:** [Design Phase / Under Review / Approved / Rejected / Implemented]
**Complexity:** [Minor / Moderate / Major]
**Impact:** [Systems affected]

## Problem Statement
[What problem does this solve?]

## Current Limitations
[What's broken or missing?]

## Proposed Solution
[High-level architecture and approach]

## Migration Path
[How to get from current to proposed without breaking existing code]

## Performance Impact
[Benchmarks, complexity analysis, memory impact]

## Implementation Complexity
[Estimated effort, risk areas, dependencies]

Evaluation Criteria

Proposals are evaluated on:

  1. Alignment with Strategic Direction - Does it fix foundation issues? Does it unblock tutorials?
  2. Technical Merit - Is the solution sound? Are tradeoffs documented?
  3. Implementation Feasibility - Is effort realistic? Can it be done incrementally?
  4. Backward Compatibility - Does it break existing code? Is migration clear?
  5. User Impact - Does it improve user experience?

Completed Proposals

Profiling System (#104)

Status: Implemented (October 2025) Complexity: Moderate

  • ScopedTimer RAII helper for instrumentation
  • ProfilingMetrics struct in GameEngine
  • F3 overlay for real-time visualization
  • Benchmark API (start_benchmark(), end_benchmark(), log_benchmark())

Related Pages: Performance-and-Profiling

Dynamic Layer System (#147)

Status: Implemented (November 2025) Complexity: Major

  • ColorLayer and TileLayer as standalone objects
  • Arbitrary number of layers per grid with z_index ordering
  • Layers below entities (z < 0) and above entities (z >= 0)
  • grid.add_layer(), grid.remove_layer(), grid.layer("name")

Related Pages: Grid-Rendering-Pipeline, Grid-System

Chunk-Based Rendering (#123)

Status: Implemented (November 2025) Complexity: Major

  • Large grids divided into chunks with per-chunk RenderTexture caching
  • Only visible chunks processed (viewport culling)
  • 1000x1000+ grids render efficiently

Related Pages: Grid-Rendering-Pipeline

Dirty Flag Caching (#148)

Status: Implemented (November 2025) Complexity: Moderate

  • Layer changes mark containing chunks as dirty
  • Unchanged chunks reuse cached RenderTexture
  • Static scenes have near-zero CPU cost after initial render

Related Pages: Grid-Rendering-Pipeline, Performance-and-Profiling

Performance Foundation (#113, #115, #116)

Status: Implemented (Late 2025) Complexity: Major

  • SpatialHash for O(1) entity queries (entities_in_radius())
  • Dirty flag propagation through UIDrawable hierarchy
  • Batch operations for grid manipulation

Related Pages: Performance-Optimization-Workflow

Procedural Generation Systems (#192)

Status: Implemented (January 2026) Complexity: Major

  • HeightMap with noise generation, thresholding, kernel transforms
  • BSP tree with splitting, iteration, adjacency queries
  • NoiseSource with configurable octaves and lacunarity
  • Integration with Grid layers (apply_threshold, apply_ranges)

Related Pages: Procedural-Generation

Tiled/LDtk Import

Status: Implemented (January 2026) Complexity: Major

  • Tiled XML/JSON import with TileSetFile, WangSet types
  • LDtk project import with AutoRuleSet pattern matching
  • Wang tile terrain resolution and application

Proposal Status Legend

  • Design Phase - Proposal being drafted, research ongoing
  • Under Review - Proposal complete, awaiting feedback
  • Approved - Green-lit for implementation
  • In Progress - Implementation underway
  • Deferred - Good idea, wrong timing
  • Rejected - Not aligned with project direction
  • Implemented - Complete and merged

Navigation: