Samuel Bouchet
ea487cd332
Compile the game to WebAssembly so it runs entirely client-side in the browser. Uses xterm.js for terminal emulation and Spectre.Console off-screen rendering for full ANSI output fidelity. Saves use localStorage. CI deploys to itch.io via Butler on push to main.
147 lines
5.4 KiB
Markdown
147 lines
5.4 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
|
|
```
|
|
|
|
## Distribute
|
|
|
|
### Desktop (self-contained)
|
|
|
|
```powershell
|
|
dotnet publish src/OpenTheBox -c Release -r win-x64 -o "builds/$(Get-Date -Format yyyyMMdd_HHmmss)_win"
|
|
dotnet publish src/OpenTheBox -c Release -r linux-x64 -o "builds/$(Get-Date -Format yyyyMMdd_HHmmss)_linux"
|
|
```
|
|
|
|
This produces a self-contained single-file executable. The target machine does **not** need .NET installed. Distribute the entire folder (exe + `content/`).
|
|
|
|
### Web (Blazor WASM → itch.io)
|
|
|
|
```powershell
|
|
dotnet publish src/OpenTheBox.Web -c Release -o publish
|
|
```
|
|
|
|
The `publish/wwwroot/` folder contains a static site playable in any browser. Upload it to itch.io as an HTML5 project.
|
|
|
|
**CI/CD:** The GitHub Actions workflow `.github/workflows/deploy-itch.yml` automatically publishes to itch.io (user: Lythom, channel: html5) on every push to `main`. Requires the `BUTLER_API_KEY` secret configured in the repository.
|
|
|
|
## Tests
|
|
|
|
```powershell
|
|
dotnet test
|
|
```
|
|
|
|
43 content validation tests verify all JSON data files deserialize correctly, cross-references are valid, and localization keys exist.
|
|
|
|
## 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
|
|
+-- src/OpenTheBox.Web/
|
|
| +-- Program.cs # Blazor WASM entry point
|
|
| +-- WebGameHost.cs # Async game loop for browser
|
|
| +-- WebTerminal.cs # xterm.js ↔ C# bridge
|
|
| +-- WebSaveManager.cs # localStorage saves
|
|
| +-- wwwroot/ # HTML, JS, CSS served to browser
|
|
+-- .github/workflows/
|
|
| +-- deploy-itch.yml # CI: build WASM + Butler push to itch.io
|
|
+-- content/
|
|
| +-- data/ # boxes.json, items.json, interactions.json, recipes.json
|
|
| +-- strings/ # en.json, fr.json
|
|
| +-- adventures/ # 9 themes, each with .lor + .fr.lor files
|
|
+-- 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 |
|
|
|
|
## Terminal GUI
|
|
|
|
All content is expected to be renderer in a 120x30 characters frame.
|
|
|
|
## License
|
|
|
|
All rights reserved.
|