john
/
McRogueFace
1
0
Fork 0
Code Issues 46 Pull Requests Projects 1 Releases Wiki Activity
Page: Design-Proposals
Pages
AI-and-Pathfinding Adding-Python-Bindings Animation-System Design-Proposals Entity-Management Grid-Entity-Lifecycle Grid-Rendering-Pipeline Grid-System Grid-TCOD-Integration Home Input-and-Events Issue-Roadmap Performance-Optimization-Workflow Performance-and-Profiling Procedural-Generation Proposal-Next-Gen-Grid-Entity-System Python-Binding-Layer Rendering-and-Visuals Strategic-Direction UI-Component-Hierarchy Writing-Tests
1 Design-Proposals
John McCardle edited this page 2025-10-25 22:54:48 +00:00
Table of Contents

Design Proposals

This page indexes all 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: Design Phase
Complexity: Major architectural overhaul
Timeline: 130-180 hours (3-4 months part-time)

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

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

Key Issues:

  • #115 - SpatialHash for 10,000+ entities
  • #116 - Dirty flag system
  • #113 - Batch operations
  • #117 - Memory pool
  • #123 - Subgrid system
  • #124 - Grid Point Animation

Migration Strategy: 4-phase backward-compatible rollout

  • Phase 1: Performance foundation (SpatialHash, dirty flags)
  • Phase 2: Multi-tile support
  • Phase 3: Flexible content
  • Phase 4: Layer system

Decision Status: ⏳ Awaiting approval after Phase 1 (performance) completion

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
    • Proposed solution
    • Migration path
    • Performance impact
    • Implementation complexity
  4. Link related issues - Connect to Gitea issues
  5. Request review - Discussion in issue comments or wiki discussion

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]

### Technical Details

[Code examples, data structures, algorithms]

### Migration Path

[How do we get from current to proposed without breaking existing code?]

## Performance Impact

[Benchmarks, complexity analysis, memory impact]

## Implementation Complexity

[Estimated effort, risk areas, dependencies]

## Open Questions

[Unknowns that need resolution]

## Decision

[Approved? Deferred? Alternative approach?]

Historical Context

Many proposals emerge from:

  • Strategic analysis - FINAL_RECOMMENDATIONS.md identified foundation issues
  • User feedback - Tutorial burnout revealed animation system problems
  • Performance profiling - F3 overlay exposes bottlenecks
  • Issue tracking - Patterns in open issues suggest architectural needs

Evaluation Criteria

Proposals are evaluated on:

1. Alignment with Strategic Direction

  • Does it fix foundation issues?
  • Does it unblock tutorials?
  • Does it align with "beginner-friendly" mission?

See Strategic-Direction for project priorities.

2. Technical Merit

  • Is the solution sound?
  • Are tradeoffs clearly documented?
  • Is performance impact understood?

3. Implementation Feasibility

  • Is effort estimate realistic?
  • Are dependencies clear?
  • Can it be done incrementally?

4. Backward Compatibility

  • Does it break existing code?
  • Is migration path clear?
  • Can old and new coexist?

5. User Impact

  • Does it improve user experience?
  • Does it add complexity or simplify?
  • Is it well-documented?

Deferred Proposals

None currently. Deferred proposals will be listed here with rationale.

Rejected Proposals

None currently. Rejected proposals will be listed here with lessons learned.

Completed Proposals

Profiling System (Issue #104)

Status: ✅ Implemented (October 2025)
Complexity: Moderate
Implementation Time: ~2 weeks

Overview:

  • ScopedTimer RAII helper for instrumentation
  • ProfilingMetrics struct in GameEngine
  • F3 overlay for real-time visualization
  • Benchmark scripts for baseline testing

Impact:

  • Enabled data-driven optimization decisions
  • Identified grid rendering as primary bottleneck
  • Provides user-visible performance feedback

Related Pages: Performance-and-Profiling

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: