rogsh Development Guide
This skill helps you work on rogsh, an educational roguelike game that teaches Unix command-line skills through dungeon exploration. Players navigate a virtual filesystem-based dungeon using real Unix commands, battling corrupted processes and solving system problems.
Project Architecture
rogsh consists of these core components:
1. **Virtual Filesystem**: In-memory tree structure simulating directories as dungeon rooms
2. **Process System**: Virtual process table for enemy entities (ZombieProcess, ForkSprite, LogLeech)
3. **Command Parser**: Interprets Unix commands and maps them to game actions
4. **Resource Management**: HP (System Integrity), EP (CPU Quota), Disk Usage, Threat Level
5. **Knowledge System**: Meta-progression tracking for unlocking new commands
Game Mechanics
Each Unix command = 1 turnCommands consume EP based on complexityPlayers manage system resources while exploringCombat uses process management commands (ps, kill, nice)Security puzzles use permission commands (chmod, chown, gpg, ssh)Step-by-Step Implementation Guide
1. Understand the Minimal Implementation Principle
**CRITICAL**: rogsh follows a strict minimal implementation philosophy:
Only implement what is explicitly requestedDo NOT add extra features or improvements unless askedDo NOT optimize or refactor code beyond the immediate taskFix bugs/type errors ONLY when necessary to complete the requested change2. Review the Codebase
Before making changes:
Read `README.md` for game concepts and designCheck existing implementation filesIdentify which component your task affects (filesystem, commands, enemies, etc.)3. Implement Virtual Filesystem Changes
When working on the virtual filesystem:
Maintain the tree structure for directory hierarchyEnsure all operations are isolated from the real filesystemTest navigation commands (cd, ls, pwd)Verify directory generation follows game logic4. Implement Command Parser Changes
When adding or modifying commands:
Use Unix-like syntax but operate on virtual entitiesEnsure commands consume appropriate EPAdd game-specific output alongside Unix-standard outputImplement help text via `man` commandCommands to prioritize: ls, cd, cat, ps, kill, find, grep, chmod, tar5. Implement Enemy/Process System
When working on enemies:
Each enemy is a virtual process with PIDImplement behavior for: ZombieProcess, ForkSprite, LogLeechUse process management commands for combatTrack threat levels and resource consumption6. Safety and Sandboxing
Always ensure:
Unix commands are NEVER executed on the actual OSVirtual filesystem is completely isolatedCommand effects are sandboxed within the game environmentNo access to real system resources7. Testing Your Changes
Test the specific component you modified:
Unit test virtual filesystem operationsTest command parser with various inputsValidate game state transitionsEnsure sandboxing works correctlyIf you modified tutorial: test the tutorial flow8. MVP Feature Set
For MVP implementation, focus only on:
Virtual filesystem generation (10-15 directories)Basic commands: ls, cd, cat, ps, kill, find, grep, chmod, tarThree enemies: ZombieProcess, ForkSprite, LogLeechSingle zone with 1-2 depth levels and one bossSimple scoring and game over conditionsTutorial scenarioTechnology Stack
Typical implementation uses:
**Core Engine**: Python or Rust**Command Parser**: Python argparse or Rust nom**UI Layer**: Text-based (curses) or web-based (xterm.js)**Data Storage**: SQLite or JSON for savesEducational Goals
The game teaches:
Filesystem navigation (ls, cd, pwd)File manipulation (cat, head, tail, rm, chmod)Process management (ps, kill, top)Text processing (grep, find, awk, sed)System administration through gameplay metaphorsExample Workflow
When asked to "add a new enemy type":
1. Read the enemy system code (champierre/rogsh:rogsh/combat.py)
2. Create the minimal enemy class with required attributes
3. Add it to the enemy spawn table
4. Implement ONLY the specific behavior requested
5. Do NOT add extra abilities, balancing, or optimization
6. Test that it spawns and behaves as requested
7. Stop
Constraints
Do NOT execute real Unix commandsDo NOT access the real filesystemDo NOT add features beyond the specific requestDo NOT refactor existing code unless explicitly askedKeep implementation minimal and focused