107 lines
3.9 KiB
Markdown
107 lines
3.9 KiB
Markdown
|
# Open The Box
|
||
|
|
|
||
|
|
A CLI box-opening game where curiosity is the engine and every box is a mystery. Built in C# on .NET 10 with a progressive interface that evolves as you play.
|
||
|
|
|
||
|
|
> *Open a box. It contains another box. That one has a key. The key opens a chest. The chest holds a story fragment. The story unlocks a character. The character reveals a place. The place offers an adventure. The adventure rewards... a box.*
|
||
|
|
|
||
|
|
## Features
|
||
|
|
|
||
|
|
- **Progressive CLI** -- Start with bare `Console.ReadLine` numbered menus. Unlock colors, arrow-key navigation, panels, portraits, and full layouts by finding Meta Boxes.
|
||
|
|
- **25+ box types** with weighted loot tables, conditional drops, and nested auto-opening boxes.
|
||
|
|
- **9 interactive adventures** powered by [Loreline](https://loreline.app) scripting (Space, Medieval, Pirate, Contemporary, Sentimental, Prehistoric, Cosmic, Microscopic, Dark Fantasy).
|
||
|
|
- **160+ items** -- cosmetics, materials, consumables, adventure tokens, lore fragments, fortune cookies.
|
||
|
|
- **34 crafting recipes** across 16 workstation types.
|
||
|
|
- **Auto-activation system** -- items interact automatically (key + chest, badge + adventure).
|
||
|
|
- **Character customization** -- hair, eyes, body, legs, arms, tints with ASCII portrait.
|
||
|
|
- **Bilingual** -- full English and French support (UI + adventures).
|
||
|
|
- **Save/Load** -- JSON-based save files.
|
||
|
|
- **Music Box** -- `Console.Beep` melodies (Windows).
|
||
|
|
- **Fortune Cookies** -- 20 box-themed wisdom messages.
|
||
|
|
|
||
|
|
## Architecture
|
||
|
|
|
||
|
|
The game follows the **Black Box Sim** pattern ([Brian Cronin](https://www.youtube.com/watch?v=jhcHlg7YhPg)): strict separation between simulation and presentation.
|
||
|
|
|
||
|
|
```
|
||
|
|
Input (keyboard)
|
||
|
|
|
|
||
|
|
v
|
||
|
|
GameAction -- command sent to the simulation
|
||
|
|
|
|
||
|
|
v
|
||
|
|
+----------------+
|
||
|
|
| GameSimulation | -- BLACK BOX: zero I/O, pure logic
|
||
|
|
| (GameState) |
|
||
|
|
+-------+--------+
|
||
|
|
|
|
||
|
|
v
|
||
|
|
GameEvent[] -- events describing what happened
|
||
|
|
|
|
||
|
|
v
|
||
|
|
+----------------+
|
||
|
|
| IRenderer | -- BasicRenderer (phase 0) or SpectreRenderer (phases 1-8)
|
||
|
|
+----------------+
|
||
|
|
```
|
||
|
|
|
||
|
|
The simulation never reads input or writes output. It receives actions and returns events. The game loop in `Program.cs` bridges input/renderer to simulation.
|
||
|
|
|
||
|
|
## Prerequisites
|
||
|
|
|
||
|
|
- **Windows 10/11**
|
||
|
|
- **.NET 10 SDK** -- install via `winget install Microsoft.DotNet.SDK.10`
|
||
|
|
|
||
|
|
## Setup
|
||
|
|
|
||
|
|
```powershell
|
||
|
|
git clone <repo-url>
|
||
|
|
cd openthebox
|
||
|
|
.\init.ps1
|
||
|
|
```
|
||
|
|
|
||
|
|
The init script will:
|
||
|
|
1. Check for .NET 10 SDK (offers to install if missing)
|
||
|
|
2. Download [Loreline](https://github.com/Loreline/loreline/releases) v0.7.1 DLL
|
||
|
|
3. Restore NuGet packages (Spectre.Console)
|
||
|
|
|
||
|
|
## Build & Run
|
||
|
|
|
||
|
|
```powershell
|
||
|
|
dotnet build
|
||
|
|
dotnet run --project src/OpenTheBox
|
||
|
|
```
|
||
|
|
|
||
|
|
## Project Structure
|
||
|
|
|
||
|
|
```
|
||
|
|
openthebox/
|
||
|
|
+-- src/OpenTheBox/
|
||
|
|
| +-- Program.cs # Entry point, game loop
|
||
|
|
| +-- Core/ # Pure models, enums, no dependencies
|
||
|
|
| +-- Simulation/ # BLACK BOX: GameSimulation, engines, actions, events
|
||
|
|
| +-- Rendering/ # IRenderer, BasicRenderer, SpectreRenderer, Panels
|
||
|
|
| +-- Adventures/ # Loreline integration
|
||
|
|
| +-- Persistence/ # Save/Load
|
||
|
|
| +-- Localization/ # JSON string manager
|
||
|
|
+-- content/
|
||
|
|
| +-- data/ # boxes.json, items.json, interactions.json, recipes.json
|
||
|
|
| +-- strings/ # en.json, fr.json
|
||
|
|
| +-- adventures/ # 9 themes, each with .lor + .fr.lor files
|
||
|
|
+-- docs/GDD.md # Game Design Document (French)
|
||
|
|
+-- init.ps1 # Setup script
|
||
|
|
+-- global.json # Pins .NET 10 SDK
|
||
|
|
```
|
||
|
|
|
||
|
|
## Tech Stack
|
||
|
|
|
||
|
|
| Component | Technology |
|
||
|
|
|-----------|-----------|
|
||
|
|
| Runtime | .NET 10, C# 14 |
|
||
|
|
| CLI rendering | [Spectre.Console](https://spectreconsole.net) |
|
||
|
|
| Interactive fiction | [Loreline](https://loreline.app) (.lor scripts) |
|
||
|
|
| Serialization | System.Text.Json |
|
||
|
|
| Localization | JSON string tables + Loreline translation files |
|
||
|
|
|
||
|
|
## License
|
||
|
|
|
||
|
|
All rights reserved.
|