Heist Master

Heist Master is a terminal-based RPG heist game that blends strategy, planning, and high-stakes action. Players assemble a crew, manage finances, evade the police, and execute daring missions with branching outcomes.

Features

• Deep economy system with cash wallet, black market trading, and off-grid crypto storage.
• Police and wanted system from level 0 to 5 that changes NPC behavior and investigation intensity.
• Mission system with story and side contracts, reputation gating, and progressive difficulty.
• Event system that triggers planning, heist, and escape complications with meaningful choices.
• Rich terminal UI using rich, colorama, and pyfiglet for polished menus and HUD elements.
• Save/load persistence with JSON storage and leaderboard tracking.
• Data-driven content using JSON definitions for items, dialogue, missions, and high scores.
• Automated tests covering player state, economy mechanics, police logic, events, and locations.

Installation

1. Clone the repository:

git clone https://github.com/yourname/heist-master.git
cd heist-master

2. Create a Python virtual environment:

python -m venv venv

3. Activate the environment:

Windows:

venv\Scripts\Activate.ps1

macOS / Linux:

source venv/bin/activate

4. Install dependencies:

pip install -r requirements.txt

Running the Game

python main.py

The game launches a terminal menu where you can start a new game, load a save, and explore the leaderboard.

Gameplay Guide

Main Loop

• Start a new game and choose your difficulty.
• Build reputation and accumulate cash.
• Complete story missions and side contracts.
• Manage heat to avoid increased police presence.
• Use the black market to buy illegal tools or sell stolen goods.
• Hide funds in crypto to protect wealth from police seizure.

Game Systems

Economy

• game.economy.Wallet: Tracks cash and transaction history.
• game.economy.BlackMarket: Buy illegal gear and sell stolen items.
• game.economy.CryptoWallet: Store money off-grid and apply market fluctuations.
• game.economy.EconomyManager: Centralized financial operations.

Police

• game.police.WantedSystem: Converts heat into wanted stars and police response.
• game.police.Investigation: Builds police cases from evidence and heat.
• game.police.BribeSystem: Pay off police to reduce wanted level.
• game.police.PoliceManager: Coordinates police updates and bribe resolution.

UI

• game.ui.Menu: Rich-powered menu rendering.
• game.ui.HUD: Displays money, reputation, heat, and wanted stars.
• game.ui.AsciiArt: Title art and game over screens.
• game.ui.Dialogue: Typewriter dialogue presentation.
• game.ui.LoadingScreen: Progress bars for loading sequences.

Save System

• game.save.SaveManager: Save and load game state to JSON.
• game.save.LeaderboardManager: Maintain the top ten scores.

Data Files

• data/items.json: Illegal market items and stolen goods definitions.
• data/dialogue.json: Narrative and heist dialogue.
• data/missions.json: Story and side mission definitions.
• data/leaderboard.json: Persistent leaderboard file.

Testing

Run the unit tests with:

python -m pytest tests

The tests cover:

• Player state and heist progression
• Economy management and black market interactions
• Police wanted level escalation and bribery
• Event generation and resolution logic
• Location briefing retrieval

Screenshots

██████╗ ███████╗██╗████████╗███████╗
██╔══██╗██╔════╝██║╚══██╔══╝██╔════╝
██████╔╝█████╗  ██║   ██║   █████╗  
██╔═══╝ ██╔══╝  ██║   ██║   ██╔══╝  
██║     ███████╗██║   ██║   ███████╗
╚═╝     ╚══════╝╚═╝   ╚═╝   ╚══════╝

Project Structure

• game/core/ - Engine, config, state, logger
• game/characters/ - Player and crew management
• game/locations/ - Heist locations and planning
• game/missions/ - Story and side contracts
• game/events/ - Dynamic heist events
• game/economy/ - Wallet, black market, crypto storage
• game/police/ - Wanted and investigation systems
• game/ui/ - Terminal menus, HUD, dialogue, loading screens
• game/save/ - Save and leaderboard persistence
• data/ - JSON-driven content definitions
• tests/ - Automated unit tests

Notes

This project is designed to be extensible and modular. New missions, events, economy items, and UI features can be added by extending the corresponding package files and JSON definitions.