john/McRogueFace

Fork 0

[Demo Target] r/roguelikedev Tutorial Series Demo Game #167

New issue

Open

opened 2025-12-29 03:54:52 +00:00 by john · 1 comment

john commented

2025-12-29 03:54:52 +00:00

Owner

Summary

Create a tutorial series and accompanying demo game targeting the r/roguelikedev annual "Complete Roguelike Tutorial" event, typically held over 8 weeks each summer.

Background

The 2024/2025 attempt to write McRogueFace tutorials alongside the community event revealed the engine wasn't ready. Those blocking issues have since been closed. Summer 2026 is the target.

r/roguelikedev Tutorial Structure (Traditional)

The community follows a ~13 part tutorial based on libtcod/Python:

Setting up / Drawing the '@'
Moving around
The generic Entity and map
Field of view
Placing enemies and kicking them
Combat and AI
Creating the Interface (UI)
Items and inventory
Ranged attacks and targeting
Saving and loading
Delving into the dungeon
Monster and item variety
Equipment

McRogueFace Adaptation

Map each traditional part to McRogueFace features:

Parts 1-3: Grid, Entity, sprites, keyboard input
Part 4: Built-in FOV from libtcod integration
Parts 5-6: Entity interactions, turn handling
Part 7: Frame, Caption, UI composition
Parts 8-9: Game logic in Python
Part 10: Python json for save/load
Parts 11-13: Procedural generation, game content

Deliverables

Tutorial text (8 parts matching community schedule)
Progressive code snapshots (runnable after each part)
Demo game showing completed result
Video walkthroughs (optional but valuable)

Success Criteria

Complete beginner can follow tutorials with no prior McRogueFace experience
Each week's content completable in 2-4 hours
Final result is a playable roguelike

Timeline

Early 2026: Draft tutorials, test with beta readers
Summer 2026: Release alongside community event
Post-event: Refine based on feedback

Website needs tutorial section
README needs getting-started pointer
Crypt of Sokoban provides reference but is too complex for tutorials

## Summary Create a tutorial series and accompanying demo game targeting the r/roguelikedev annual "Complete Roguelike Tutorial" event, typically held over 8 weeks each summer. ## Background The 2024/2025 attempt to write McRogueFace tutorials alongside the community event revealed the engine wasn't ready. Those blocking issues have since been closed. Summer 2026 is the target. ## r/roguelikedev Tutorial Structure (Traditional) The community follows a ~13 part tutorial based on libtcod/Python: 1. Setting up / Drawing the '@' 2. Moving around 3. The generic Entity and map 4. Field of view 5. Placing enemies and kicking them 6. Combat and AI 7. Creating the Interface (UI) 8. Items and inventory 9. Ranged attacks and targeting 10. Saving and loading 11. Delving into the dungeon 12. Monster and item variety 13. Equipment ## McRogueFace Adaptation Map each traditional part to McRogueFace features: - Parts 1-3: Grid, Entity, sprites, keyboard input - Part 4: Built-in FOV from libtcod integration - Parts 5-6: Entity interactions, turn handling - Part 7: Frame, Caption, UI composition - Parts 8-9: Game logic in Python - Part 10: Python `json` for save/load - Parts 11-13: Procedural generation, game content ## Deliverables 1. **Tutorial text** (8 parts matching community schedule) 2. **Progressive code snapshots** (runnable after each part) 3. **Demo game** showing completed result 4. **Video walkthroughs** (optional but valuable) ## Success Criteria - Complete beginner can follow tutorials with no prior McRogueFace experience - Each week's content completable in 2-4 hours - Final result is a playable roguelike ## Timeline - **Early 2026**: Draft tutorials, test with beta readers - **Summer 2026**: Release alongside community event - **Post-event**: Refine based on feedback ## Related - Website needs tutorial section - README needs getting-started pointer - Crypt of Sokoban provides reference but is too complex for tutorials

john added the

Tiny Feature

label

2025-12-29 03:55:17 +00:00

john added a new dependency

2025-12-29 03:55:39 +00:00

#165 [Documentation] Update mcrogueface.github.io website

john added

priority:tier2-foundation

Demo Target

and removed

Tiny Feature

labels

2025-12-29 03:56:41 +00:00

john commented

2026-04-10 03:24:01 +00:00

Author

Owner

Tutorial scripts updated to current API (commit 1805b98)

All 14 tutorial parts (0-13) in docs/tutorials/ were broken after commit 6d5e99a removed legacy string enum comparisons. Every tutorial now uses the current enum-based API:

Changes across all 13 modified files (Part 0 had no key handler):

key == "W" / action != "start" → key == mcrfpy.Key.W / action != mcrfpy.InputState.PRESSED
Manual FOV computation → ColorLayer.draw_fov() (handles FOV + explored-state tracking in one call)
grid.add_layer("color", z_index=-1) → mcrfpy.ColorLayer() + grid.add_layer()
entities.remove(index) bug → entities.remove(entity_ref) (31 instances fixed across Parts 5-13)
Removed manual exploration tracking functions (draw_fov handles internally)

Net result: -765 lines, +388 lines. All 14 parts tested and passing in headless mode.

Remaining work for #167:

Tutorial prose/documentation (the .py files have code + comments but no accompanying tutorial text)
docs/templates/roguelike/ still uses very old API (createScene, sceneUI, keypressScene) — separate fix needed
Video walkthroughs (optional per issue description)
Beta reader testing before Summer 2026 community event

**Tutorial scripts updated to current API** (commit 1805b98) All 14 tutorial parts (0-13) in `docs/tutorials/` were broken after commit 6d5e99a removed legacy string enum comparisons. Every tutorial now uses the current enum-based API: **Changes across all 13 modified files (Part 0 had no key handler):** - `key == "W"` / `action != "start"` → `key == mcrfpy.Key.W` / `action != mcrfpy.InputState.PRESSED` - Manual FOV computation → `ColorLayer.draw_fov()` (handles FOV + explored-state tracking in one call) - `grid.add_layer("color", z_index=-1)` → `mcrfpy.ColorLayer()` + `grid.add_layer()` - `entities.remove(index)` bug → `entities.remove(entity_ref)` (31 instances fixed across Parts 5-13) - Removed manual exploration tracking functions (draw_fov handles internally) **Net result:** -765 lines, +388 lines. All 14 parts tested and passing in headless mode. **Remaining work for #167:** - Tutorial prose/documentation (the `.py` files have code + comments but no accompanying tutorial text) - `docs/templates/roguelike/` still uses very old API (`createScene`, `sceneUI`, `keypressScene`) — separate fix needed - Video walkthroughs (optional per issue description) - Beta reader testing before Summer 2026 community event

john referenced this issue from a commit

2026-04-10 05:09:18 +00:00

Update all 13 tutorial scripts to current enum-based API, refs #167

john referenced this issue

2026-04-17 03:26:00 +00:00

[Documentation] API audit follow-through: close the gaps from docs/api-audit-2026-04.md #314