john/McRogueFace
1
0
Fork 0
Code Issues 32 Pull requests Projects Releases Wiki Activity

Playground: Developer troubleshooting documentation for WASM deployments #240

New issue
Open
opened 2026-02-02 20:51:26 +00:00 by john · 0 comments
john commented 2026-02-02 20:51:26 +00:00
Owner
Copy link

Overview

Create comprehensive documentation to help game developers troubleshoot issues when deploying McRogueFace games via Emscripten/WASM.

Scope

Create docs/emscripten-debugging.md

Quick Diagnostics Section

Browser console commands for checking interpreter state:

window.getPythonState();      // Check for error state
window.clearPythonError();    // Clear error state
window.dumpPythonGlobals();   // Dump Python namespace
window.dumpLoadedModules();   // List loaded modules

Common Issues Section

  • "Loss of all output" - PyErr state stuck
  • "Infinite loop" / Tab freezes - No timeout protection
  • Build crashes with cryptic errors - Debug build instructions
  • Asset loading failures - Virtual filesystem paths
  • Audio not working - Stubbed in WASM builds

Debug Build Instructions

emmake cmake -B build-debug \
    -DMCRF_SDL2=ON \
    -DCMAKE_BUILD_TYPE=Debug

Chrome DevTools Setup

  • DWARF extension installation
  • Source panel navigation
  • Breakpoint usage in C++ code

Update CLAUDE.md

Add reference to troubleshooting guide in Emscripten section.

References

Related

Part of playground improvement initiative documented in docs/PLAYGROUND_IMPROVEMENT_PLAN.md (Phase 6)

## Overview Create comprehensive documentation to help game developers troubleshoot issues when deploying McRogueFace games via Emscripten/WASM. ## Scope ### Create `docs/emscripten-debugging.md` #### Quick Diagnostics Section Browser console commands for checking interpreter state: ```javascript window.getPythonState(); // Check for error state window.clearPythonError(); // Clear error state window.dumpPythonGlobals(); // Dump Python namespace window.dumpLoadedModules(); // List loaded modules ``` #### Common Issues Section - "Loss of all output" - PyErr state stuck - "Infinite loop" / Tab freezes - No timeout protection - Build crashes with cryptic errors - Debug build instructions - Asset loading failures - Virtual filesystem paths - Audio not working - Stubbed in WASM builds #### Debug Build Instructions ```bash emmake cmake -B build-debug \ -DMCRF_SDL2=ON \ -DCMAKE_BUILD_TYPE=Debug ``` #### Chrome DevTools Setup - DWARF extension installation - Source panel navigation - Breakpoint usage in C++ code ### Update CLAUDE.md Add reference to troubleshooting guide in Emscripten section. ## References - [PEP 776 - Emscripten Support](https://peps.python.org/pep-0776/) - [Pyodide Debugging Tips](https://pyodide.org/en/stable/development/debugging.html) - [Pyodide WASM Constraints](https://pyodide.org/en/stable/usage/wasm-constraints.html) ## Related Part of playground improvement initiative documented in `docs/PLAYGROUND_IMPROVEMENT_PLAN.md` (Phase 6)
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
master
threedee
emscripten-mcrogueface
rogueliketutorial25
alpha_presentable
alpha_streamline_2
alpha_streamline_1
interpreter_mode
grid_entity_integration
reprs_and_member_names
break_up_ui_h
standardize_font_handling
standardize_vector_handling
standardize_color_handling
standardize_texture_handling
raii_pyobjects
rebase-for-7DRL_Feb-2024
engjam_uicollection
engjam_ui_overhaul
0.2.3-prerelease-7drl2026-emscripten
Labels
Clear labels   
Alpha Release Requirement

This issue is a blocker to 0.1 Alpha release of McRogueFace.

  
Bugfix

   
Demo Target

Functionality to demonstrate; Depends on new features, but this issue isn't for writing them.

  
Documentation

   
Major Feature

Significant time and effort required.

  
Minor Feature

Some effort required to create or overhaul functionality.

  
priority:tier1-active

Current development focus - critical path to v1.0

  
priority:tier2-foundation

Important foundation work - not blocking v1.0

  
priority:tier3-future

Future features - deferred until after v1.0

  
priority:tier4-deferred

   
Refactoring & Cleanup

no new functionality, just improving the codebase.

  
system:animation

Animation and property interpolation

  
system:documentation

Documentation infrastructure

  
system:grid

Grid system and spatial containers

  
system:input

Input handling and events

  
system:performance

Performance optimization and profiling

  
system:procgen

Procedural Generation (Noise, BSP, Heightmap)

  
system:python-binding

Python/C++ binding layer

  
system:rendering

Rendering pipeline and visuals

  
system:ui-hierarchy

UI component hierarchy and composition

  
Tiny Feature

quick and easy - a few lines or with little interconnection around the codebase

  
workflow:blocked

Blocked by other work - waiting on dependencies

  
workflow:needs-benchmark

Needs performance testing and benchmarks

  
workflow:needs-documentation

Needs documentation before or after implementation

No labels
Alpha Release Requirement
Bugfix
Demo Target
Documentation
Major Feature
Minor Feature
priority:tier1-active
priority:tier2-foundation
priority:tier3-future
priority:tier4-deferred
Refactoring & Cleanup
system:animation
system:documentation
system:grid
system:input
system:performance
system:procgen
system:python-binding
system:rendering
system:ui-hierarchy
Tiny Feature
workflow:blocked
workflow:needs-benchmark
workflow:needs-documentation
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
john/McRogueFace#240
No description provided.