Version 1.0.0 - A coffee break cyberspace stealth roguelike built with Python and TCOD

For Players: See README.txt for game instructions

For Game Knowledge: See the Comprehensive Wiki for all game systems, mechanics, and guides

For Developers/Modders: This guide covers building from source, modding, and contributing

Copyright (C) 2025 Adam Forster

This program is free software licensed under the MIT License. You can freely use, modify, and distribute it. See LICENSE file for full details.

Rogue Signal Protocol is a coffee break stealth-focused cyberspace roguelike where you infiltrate corporate networks as a digital ghost. Complete runs in 10-15 minutes as you navigate procedurally generated levels, avoid sophisticated AI security systems, and discover the dark secrets hidden in the corporate data vaults.

• Deterministic Gameplay: No randomness or luck - pure skill-based tactical decisions
• 8 Unique Enemy Types: Scanners, Hunters, Viruses, Firewalls, and Admin Avatar boss
• 13 Powerful Exploits: Combat, stealth, and utility abilities with heat management
• Enemy Movement Prediction: See enemies' next 3 planned moves for tactical advantage
• Blind Spot Stealth Mechanics: Hide in shadows to avoid detection
• Dynamic Threat System: High detection spawns the Admin Avatar boss
• Achievement System: Track progress across runs with persistent unlocks
• Rich Narrative: Discover 20+ story fragments revealing Project Chimera
• Dual Rendering Modes: Switch between graphical sprites or classic ASCII/Unicode glyphs
• Particle Effect Explosions: Visual feedback for combat and exploits
• Full Audio: Sound effects and atmospheric music (toggleable)
• Keyboard or Mouse: Playable with full support for both input methods
• True Permadeath: Saves deleted on death, auto-save on exit

Choose from 13 different exploits across 4 categories:

Combat: Buffer Overflow, Code Injection, Logic Bomb, Denial of Service Stealth: System Hop, Traffic Masquerade, Decoy Swarm, Memory Leak Utility: Threat Scan, Network Scan, Log Wiper, Antivirus Emergency: System Crash

• Dynamic Level Layouts: Each run features unique room arrangements
• Balanced Enemy Placement: Intelligent spawn systems for fair challenge
• Resource Distribution: Strategic placement of upgrades and pickups

Discover the dark truth through environmental storytelling:

• Project Chimera: Uncover the real purpose behind the "testing"
• Dr. Aris Thorne: Learn about the obsessed lead researcher
• Digital Consciousness: Explore themes of mind uploading and identity

This is the 1.0 release - feature-complete and stable.

• Complete stealth gameplay loop
• All 8 enemy types with unique behaviors
• Full exploit system with 13 abilities
• 3-level campaign with escalating difficulty
• Ascension mode with meta-progression
• Save/load system with permadeath
• Audio system with music and SFX
• Complete story content (20+ fragments)
• Full gamepad support with remapping
• Cross-platform: Windows and Linux (including Steam Deck)

• Python 3.10+
• Windows 10/11 (primary support)

1. Clone the repository

   git clone https://github.com/Dragynrain/RogueSignalProtocol.git
   cd RogueSignalProtocol

2. Set up virtual environment (recommended)

   python -m venv .venv
   .venv\Scripts\activate

3. Install dependencies

   pip install -r requirements.txt

4. Run the game

   .venv\Scripts\python.exe RogueSignalProtocol.py

Navigate through 3 increasingly dangerous network levels, reach the gateway (>) on each level, and uncover the truth behind the Omni-Lyra Cognitive Resilience Initiative.

• Movement: Arrow Keys, WASD, QEZC (diagonals), or Numpad (8-directional)
• Wait/Rest: Space, Period (.), or Numpad 5 to pass turn
• Exploits: 1-5 keys to use equipped exploits
• Inventory: I key to manage codes and exploits
  • Up/Down: Navigate items
  • Enter: Use/equip/unequip selected item
  • I/ESC: Close inventory
• Look Mode: L key to examine entities and terrain
• Lore Fragments: F key to view discovered story fragments
• Achievements: V key to view unlocked achievements
• Ascension: N key to toggle ascension progression system
• Help: ? (Shift+/) for complete controls reference
• Pause: ESC key
• Confirm: Enter key for dialogues and menus

Universal Mouse Behavior (Standardized):

• Left-Click: Select/activate items, click buttons, move in-game
• Right-Click: Go back to previous screen, cancel action/mode (works in ALL menus)
• Mouse Wheel: Scroll through lists, menus, help pages (works in ALL scrollable screens)
• Hover: Highlight menu options, show tooltips and entity info

Consistency:

• Right-click ALWAYS returns to previous screen or cancels current action
• Mouse wheel ALWAYS scrolls in lists, settings, achievements, help, inventory, lore viewer
• All mouse controls have keyboard equivalents for full keyboard-only play

• Stealth: Hide in shadows (*) to avoid enemy detection
• Heat Management: Exploit usage generates heat; overheating causes damage
• Detection System: High detection levels spawn the Admin Avatar
• Resource Management: Balance CPU (health), RAM (exploit capacity), and Heat

• Engine: Python 3.10+ with python-tcod (19.4.0+)
• Audio: pygame (2.6.1+)
• Build: PyInstaller for exe creation
• Testing: pytest with 700+ tests (unit + integration)
• Architecture: Modular component system with JSON-driven configuration

RogueSignalProtocol/
├── RogueSignalProtocol.py       # Main entry point
├── src/rsp/                     # Core game package
│   ├── core/                    # Engine, config, state, loop
│   ├── entities/                # Player, enemies, positions
│   ├── combat/                  # Combat system, inventory
│   ├── level/                   # Map, generation, pathfinding
│   ├── input/                   # Input handling, gamepad
│   ├── rendering/               # Graphics, glyphs, UI rendering
│   ├── ui/                      # Menus, dialogs, screens
│   ├── systems/                 # Audio, achievements, save
│   └── utils/                   # Colors, unicode, debug
│
├── Configuration (JSON-driven):
├── game_content.json            # Items, exploits, loot tables
├── game_rules.json              # Balance, colors, gameplay rules
├── graphics_tiles.json          # Sprite mappings
├── narrative_content.json       # Narrative fragments
│
├── Assets:
├── graphics/                    # PNG sprites (150+ files)
├── sound/                       # WAV sound effects (40+ files)
├── music/                       # MP3 background music
├── KreativeSquare.ttf           # Game font
│
├── Build System:
├── build/
│   ├── build.bat                # Windows build script (alpha/beta/release)
│   ├── build-linux.sh           # Linux build script
│   ├── BUILD_GUIDE.md           # Build documentation
│   ├── BUILD_TYPES.md           # Logging system docs
│   └── clean.bat                # Cleanup script
│
├── packaging/
│   └── linux/                   # Linux packaging (AppImage, Flatpak, AUR)
│       ├── README.md            # Linux distribution guide
│       └── TEST_CHECKLIST.md    # Package testing checklist
│
├── Testing:
├── tests/
│   ├── unit/                    # Unit tests
│   ├── integration/             # Integration tests
│   └── fixtures/                # Test data builders
├── test_commands.py             # Test runner with coverage
└── pytest.ini                   # Test configuration

• Modular Design: Clean separation (rendering, input, AI, combat, etc.)
• JSON-Driven: All content easily moddable through JSON files
• Component System: Entities use composition over inheritance
• Event-Driven: Message log system for game events
• State Management: Clean state transitions and save/load
• Coordinate Helpers: TCOD coordinate system wrappers (avoid bugs!)

The game has comprehensive test coverage with a custom test runner.

# Run full test suite with coverage
python test_commands.py full

# Quick unit tests only (fast feedback)
python test_commands.py quick

# Integration tests only
python test_commands.py integration

# Generate coverage report
python test_commands.py coverage  # Creates htmlcov/

# Test only changed files
python test_commands.py changed

# Direct pytest (uses pytest.ini config)
.venv\Scripts\python.exe -m pytest

tests/
├── unit/                     # Fast, isolated tests
│   ├── test_dialogue_system.py
│   ├── test_enemy_ai.py
│   └── ...
├── integration/              # Full system tests
│   ├── test_combat_scenarios.py
│   ├── test_level_generation.py
│   └── ...
└── fixtures/                 # Reusable test data
    ├── combat_fixtures.py
    ├── enemy_fixtures.py
    └── ...

• Update tests with code changes - Always!
• Use fixtures - Don't duplicate test setup
• Integration over mocks - Test real behavior
• Run full suite before commits - python test_commands.py full

The game uses a build system supporting both Windows and Linux.

Debug Build (For Testing):

cd build
build.bat alpha

• Includes DEBUG logging
• Creates game_debug.log for bug reports

Release Build (Default):

cd build
build.bat release

• Minimal WARNING-level logging only
• Creates game_errors.log (errors only)

Build from a Linux environment (native, WSL2, or VM):

# Activate virtual environment
source .venv/bin/activate

# Install PyInstaller if needed
pip install pyinstaller

# Run the build script
./build/build-linux.sh

Output: dist/RogueSignalProtocol (no .exe extension)

For distribution packages (AppImage, Flatpak, AUR), see packaging/linux/README.md.

dist/                         # Complete distribution
├── RogueSignalProtocol.exe   # Windows executable (or no extension on Linux)
├── README.txt                # End-user instructions
├── build_info.txt            # Build type and date
├── debug_mode.flag           # Present in debug builds only
├── game_content.json         # All JSON configs
├── graphics/                 # All sprites
├── sound/                    # All SFX
└── music/                    # All music

releases/                     # Timestamped archives (Windows only)
└── RogueSignalProtocol_Release_2026-04-01_143022.zip

• build/BUILD_GUIDE.md - Complete build instructions
• build/BUILD_TYPES.md - Logging system documentation
• packaging/linux/README.md - Linux packaging guide

All game content is JSON-driven and easily moddable!

Defines all items, exploits, and loot:

{
  "exploits": {
    "buffer_overflow": {
      "name": "Buffer Overflow",
      "category": "combat",
      "base_damage": 35,
      "heat_cost": 25,
      "ram_cost": 1,
      "targeting": "single",
      "description": "Overload target with malicious data..."
    }
  },
  "code_hacks": { ... },
  "loot_tables": { ... }
}

Defines balance, colors, gameplay rules:

{
  "gameplay": {
    "default_player_cpu": 100,
    "max_heat": 100,
    "trace_increase_amount": 1
  },
  "colors": {
    "basic": { "cyan": [20, 255, 200] },
    "data_codes": {
      "crimson": [255, 20, 80],
      "azure": [0, 200, 255]
    }
  }
}

Maps entities to sprite variants:

{
  "player": {
    "variants": ["player01.png", "player02.png", ...]
  },
  "enemies": {
    "scanner": ["scanner01.png", "scanner02.png", ...]
  }
}

Modify existing exploits:

• Change damage, heat cost, RAM cost
• Update descriptions and colors
• Adjust range and targeting

Change game balance:

• Edit game_rules.json values (player HP, heat limits, etc.)
• No code changes needed!

Add/modify sprites:

• Create PNG files in graphics/
• Update graphics_tiles.json with new variants
• Restart game to see changes

Modify story:

• Edit narrative_content.json
• Add/edit fragments
• Changes appear immediately

Adjust colors:

• Edit game_rules.json color definitions
• All UI colors are JSON-driven

Tweak enemy stats:

• Edit game_content.json enemy definitions
• Change HP, damage, vision range

Add NEW exploits:

• Cannot just add to JSON
• Requires code in src/rsp/combat/combat.py:
  1. Add to game_content.json (stats/description)
  2. Add case in _execute_specific_exploit()
  3. Implement _execute_your_exploit() method
  4. Add sound file (optional)
  5. Update help screens if needed

Add NEW enemy behaviors:

• Cannot just add to JSON
• Requires code in src/rsp/entities/enemies.py

Add NEW mechanics:

• Always requires code
• Example: New status effects, new tile types, new systems

All game code is in the src/rsp/ package:

Core (rsp.core):

• loop.py - Main game loop and rendering coordination
• engine.py - Turn processing and game state
• session.py - Session management and level progression
• config.py - Configuration management
• data.py / data_loading.py - JSON loading and validation

Rendering (rsp.rendering):

• core.py - Base rendering system
• graphics.py - Graphics mode with sprites
• glyphs.py - ASCII/glyph mode
• ui.py - UI elements and panels
• coordinates.py - TCOD coordinate helpers

Entities (rsp.entities):

• player.py - Player entity
• enemies.py - Enemy AI and behavior management
• characters.py - Character base classes
• position.py - Position class and utilities

Combat (rsp.combat):

• combat.py - Exploit system and damage calculation
• inventory.py - Item management
• turn_manager.py - Turn processing

Level (rsp.level):

• generator.py - Level generation
• map.py - Map data structures
• pathfinding.py - A* pathfinding

Input (rsp.input):

• handler.py - Main input handler
• gamepad.py - Gamepad support
• mappings.py - Key bindings

UI (rsp.ui):

• menus.py - Main menu, settings, etc.
• dialogue.py - Dialogue boxes and prompts

Systems (rsp.systems):

• audio.py - Sound and music
• achievements.py - Achievement tracking
• save.py - Save/load system

JSON-Driven Configuration:

# All config loaded from JSON - no hardcoded values!
GameConfig.load_config()  # Loads game_rules.json
GameData.load_data()      # Loads game_content.json

Component System:

class Enemy:
    def __init__(self):
        self.position = Position(x, y)
        self.state = EnemyState.UNAWARE
        self.movement_queue = []  # Predictable AI

Message Log Pattern:

# Game events go to message log, not print()
message_log.add_message("Enemy detected!", Colors.RED)

CRITICAL: TCOD uses (x, y) for functions but [y, x] for arrays!

# CORRECT - use helpers
from rsp.rendering.coordinates import CoordinateHelpers
CoordinateHelpers.set_alpha_region(console, x=10, y=5, width=30, height=15, alpha=255)

# CORRECT - TCOD functions use (x, y)
console.print(x=10, y=5, string="Hello")

# WRONG - direct array access
console.rgba["bg"][x, y, 3] = 255  # BUG! Should be [y, x]!

Always use CoordinateHelpers for array access!

• Coordinate system rules
• Graphics rendering
• Console vs SDL pixels
• Common pitfalls

Three separate coordinate systems:

1. Console chars (80x50) - Text rendering
2. Game viewport (55x44 glyph / ~27x21 graphics) - In-game tiles
3. SDL pixels (window size) - Direct sprite rendering

Don't mix them! See TCOD_GUIDE.md for conversion formulas.

# Activate venv
.venv\Scripts\activate

# Run game
python RogueSignalProtocol.py

# Enable debug logging (create flag file)
echo > debug_mode.flag
python RogueSignalProtocol.py

# Run tests before committing
python test_commands.py full

1. Make changes to code or JSON
2. Test immediately with python test_commands.py quick
3. Run from source to verify behavior
4. Update tests if you changed APIs
5. Full test suite before commit: python test_commands.py full
6. Build alpha to test exe: cd build && build.bat alpha

• Create debug_mode.flag for verbose logging
• Check game_debug.log after crashes
• Use logging.debug() liberally in code
• Integration tests catch more bugs than unit tests
• Test with built exe - some issues only appear there!

Modify existing exploit balance:

1. Edit game_content.json (damage, heat cost, etc.)
2. Run from source to test
3. No code changes needed!

Add NEW exploit (requires code):

1. Add to game_content.json (definition)
2. Edit src/rsp/combat/combat.py:
   • Add case in _execute_specific_exploit()
   • Implement _execute_your_exploit() method
3. Add sound file to sound/ (optional)
4. Update help screen in src/rsp/ui/menu_help_graphics.py
5. Write integration test

Add new enemy type (requires code):

1. Define in game_content.json (stats)
2. Add sprite to graphics/ and update graphics_tiles.json
3. Add AI behavior in src/rsp/entities/enemies.py if special
4. Update help screen
5. Write integration test for spawning/behavior

Modify game balance (JSON only):

1. Edit game_rules.json values
2. Run from source to test
3. Update tests if expectations changed
4. No code changes needed!

Add sound effect:

1. Add WAV file to sound/
2. Reference in code: sound_manager.play_sound("new_sound")
3. Test in-game

Change colors (JSON only):

1. Edit game_rules.json color definitions
2. Changes appear immediately

• Format: PNG with transparency
• Size: Flexible (scaled to tile size)
• Naming: entity##.png (e.g., player01.png, scanner02.png)
• Location: graphics/ folder
• Registration: Add to graphics_tiles.json

• Format: WAV (uncompressed)
• Location: sound/ folder
• Naming: Descriptive (e.g., exploit_buffer_overflow.wav)
• Usage: sound_manager.play_sound("sound_name")

• Format: OGG (normalized volume)
• Location: music/ folder
• Naming: level#_theme.ogg or descriptive
• Usage: Played automatically per level

• File: terminal10x16_gs_ro.png
• Format: Monospace bitmap font
• Size: 10x16 pixels per glyph
• Don't modify unless you know what you're doing!

1. Fail-fast philosophy: Missing config files = crash immediately
2. Required files:
   • game_content.json - Items, exploits, loot
   • game_rules.json - Balance, colors, rules
   • narrative_content.json - Narrative content
   • graphics_tiles.json - Sprite mappings
3. Optional file:
   • user_settings.json - User preferences (created if missing)

# Config files validated on load
try:
    GameConfig.load_config()
except FileNotFoundError:
    print("CRITICAL: game_rules.json missing!")
    sys.exit(1)

No fallback values! All data comes from JSON.

Located in user_settings.json (created automatically):

{
  "master_volume": 0.7,
  "sfx_volume": 0.8,
  "music_volume": 0.6,
  "graphics_mode": "graphics",
  "dialogue_preferences": {
    "show_overclock_warning": true
  }
}

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes
4. Add/update tests - This is critical!
5. Run full test suite: python test_commands.py full
6. Commit changes: git commit -m "Add amazing feature"
7. Push to branch: git push origin feature/amazing-feature
8. Open a Pull Request

Code:

• Keep files under 2000 lines (split at ~1800)
• One purpose per module
• Unicode character set (CascadiaCode TrueType font, full box-drawing support)
• Update tests with every change
• Run full test suite before PR

Testing:

• All new features need tests
• Prefer integration tests over mocks
• Use tests/fixtures/ builders
• Test edge cases and error conditions

Configuration:

• New content goes in JSON files when possible
• Don't hardcode values
• Document JSON schema changes
• Validate JSON files after editing

Commits:

• Clear, technical commit messages
• No AI attribution tags
• Keep commits focused and atomic

Use GitHub Issues with:

• Description of the bug
• Steps to reproduce
• Expected vs actual behavior
• game_debug.log file (if applicable)
• System info (Windows version, Python version)

1. Simplicity over complexity - Prefer simple functional code
2. JSON-driven content - Easy modding without code changes
3. Fail fast - Better to crash than silently fail
4. ASCII-first - Graphics are enhancement, not requirement
5. Test everything - Integration tests > unit tests
6. No over-engineering - YAGNI principle

• Don't worry about performance until it's actually a problem
• No preemptive optimization
• Focus on code clarity and correctness first
• Optimize only when users report issues

• Functional where possible - Minimize state
• Clear names - enemy_vision_range not evr
• Type hints - Use them liberally
• Docstrings - For public APIs
• Comments - For "why", not "what"

• build/BUILD_GUIDE.md - Building executables
• build/BUILD_TYPES.md - Logging system
• .claude/TCOD_GUIDE.md - TCOD coordinate systems
• .claude/CLAUDE.md - Development guidelines
• README.txt - End-user game instructions

• python-tcod Documentation
• Roguelike Development
• Project Repository

MIT License - Free and Open Source Software

You can:

• Use for any purpose (including commercial)
• Study and modify the code
• Redistribute copies
• Distribute modified versions
• Create proprietary derivatives

You must:

• Include the original copyright notice
• Include the MIT license text

Maximum freedom for everyone - use it however you want!

For full contributing guidelines, see CONTRIBUTING.md

For modding and advanced development, see sections above.

Rogue Signal Protocol - Copyright (C) 2025 Adam Forster - MIT License