phaethix/cyberpunk-edgerunner-sim

Cyberpunk: Edge-Runner Simulator

   

Live fast. Modify everything. Don't lose yourself.

A cyberpunk-themed single-player RPG, ported from a terminal text adventure to a web-based single-page application (SPA).

Play as an edge-runner in Night City (year 2089). Take gigs from the fixer, buy and install cyberware upgrades, manage your humanity and health — and watch out: lose it all and the chrome takes over.

Table of Contents

• —Overview
• —Key Mechanics
• —Architecture
• —Tech Stack
• —Installation
• —Development
• —API Reference
• —Contributing
• —License

Overview

Play as an edge-runner in Night City (year 2089). Take gigs from the fixer, buy and install cyberware upgrades, manage your humanity and health — and watch out: lose it all and the chrome takes over.

Key Mechanics

Gigs

Eight gigs ranging from low-risk courier runs to extreme cyberpsycho hunts. Success chance = clamp(15, 90, 50 + bonus*2 - difficulty//2). Failure costs money, humanity, and HP.

Cyberware

Six installable upgrades, each with a price, combat bonus, and humanity cost. Uninstall any installed piece for a 50% refund.

Recovery

Architecture

graph TD
    subgraph Client ["Browser (Vanilla JS SPA)"]
        H[index.html] --> CSS
        H --> JS
        CSS[style.css<br/>Tailwind + custom] --> Browser
        JS[app.js<br/>State + API + render] --> Browser
    end

    subgraph Server ["Python / FastAPI"]
        Router["HTTP Router"] --> Static["StaticFiles (/static/)"]
        Router --> API_Status["GET /api/status"]
        Router --> API_Gig["POST /api/gig"]
        Router --> API_Buy["POST /api/buy"]
        Router --> API_Uninstall["POST /api/uninstall"]
        Router --> API_Heal["POST /api/heal"]
        Router --> API_Rest["POST /api/rest"]
        Router --> API_Restart["POST /api/restart"]

        API_Status --> GS
        API_Gig --> GS
        API_Buy --> GS
        API_Uninstall --> GS
        API_Heal --> GS
        API_Rest --> GS
        API_Restart --> GS

        GS["GameState<br/>mutable session state"] --> Data["Game Data<br/>CYBERWARE / JOBS<br/>constant dicts"]

        Static --> WEB["web/ directory<br/>index.html + app.js + style.css"]
    end

    Browser -- fetch() --> Router
    Router -- JSON response --> Browser

Tech Stack

Installation

Prerequisites

• —Python 3.10 or later

Setup

# Create and activate a virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies (includes pytest + ruff for development)
pip install -r requirements.txt

# Start the server
python -m server.main

Access

Open http://localhost:8000 in your browser.

The production image uses the slimmed-down requirements-prod.txt (no test tooling). See `Dockerfile` for details.

Development

# Run the test suite
pytest

# Check code style
ruff check .

Please ensure both pass before opening a pull request. See CONTRIBUTING.md for the full workflow, commit-message conventions, and branching strategy.

API Reference

Endpoints

Response Format

All endpoints return JSON with a consistent envelope:

{
  "success": true,
  "message": "Installed Optical Zoom Implants for $800. Combat bonus +5. Humanity -4%.",
  "state": {
    "money": 200,
    "hp": 100,
    "humanity": 96.0,
    "combat_bonus": 5,
    "owned": [{"id": "optic_zoom", "name": "Optical Zoom Implants"}],
    "day": 1,
    "game_over": false,
    "humanity_color": "#00ff88"
  },
  "job_result": { ... }
}

For gigs, job_result contains: success, job_name, roll, effective_diff, success_chance, risk_level, plus either reward (on success) or loss/hp_cost (on failure).

Contributing

Contributions are welcome! Please read CONTRIBUTING.md and our Code of Conduct before opening an issue or pull request.

License

Released under the MIT License.