docs: add comprehensive README with full project overview
Covers game modes, controls, gadget system, maps, level editor, project structure, dev setup, API, and technical details. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Jose Luis
148
README.md
Normal file
148
README.md
Normal file
@@ -0,0 +1,148 @@
|
||||
# ⚡ Logic Gates — Circuit Simulator RPG
|
||||
|
||||
A logic gate circuit simulator combined with a Pokemon-style tile-based world. Players explore **Neon Town**, interact with NPCs, and craft logic circuits in a **Workshop** to solve puzzle doors and progress through the game.
|
||||
|
||||
**Live:** [logic.montlab.dev](https://logic.montlab.dev)
|
||||
|
||||
## 🎮 Game Modes
|
||||
|
||||
### World Mode (exploration)
|
||||
- Walk around pixel-art maps rendered from PNG backgrounds
|
||||
- Talk to NPCs, read signs, enter buildings through doors
|
||||
- Find puzzle doors that require specific circuit outputs to unlock
|
||||
- Open your **backpack** to manage saved gadgets
|
||||
|
||||
### Workshop Mode (circuit editor)
|
||||
- Full-featured logic gate simulator with drag-and-drop
|
||||
- Gates: AND, OR, NOT, NAND, NOR, XOR, INPUT, OUTPUT, CLOCK
|
||||
- Wire gates together by dragging between ports
|
||||
- Real-time simulation with GTKWave-style waveform viewer
|
||||
- Save circuits as **custom components** for reuse
|
||||
- Save circuits as **gadgets** to your backpack for use on puzzles
|
||||
|
||||
## 🕹️ Controls
|
||||
|
||||
### World
|
||||
| Key | Action |
|
||||
|-----|--------|
|
||||
| WASD / Arrows | Move |
|
||||
| E / Enter / Space | Interact with NPCs, signs, doors |
|
||||
| I | Open Backpack |
|
||||
| TAB | Open Workshop |
|
||||
| F3 | Toggle debug collision overlay |
|
||||
|
||||
### Workshop
|
||||
| Key | Action |
|
||||
|-----|--------|
|
||||
| Click + Drag | Place and connect gates |
|
||||
| Shift + Drag | Cut wires / create bus connectors |
|
||||
| Mouse wheel | Zoom |
|
||||
| Arrows / +/- | Pan and zoom |
|
||||
| 0 | Reset camera |
|
||||
|
||||
### Backpack
|
||||
| Key | Action |
|
||||
|-----|--------|
|
||||
| ↑↓ / WS | Navigate gadget list |
|
||||
| E / Enter | Select → Use / Toss |
|
||||
| I / ESC / B | Close |
|
||||
|
||||
## 🎒 Gadget System
|
||||
|
||||
Circuits become portable items:
|
||||
|
||||
1. **Build** a circuit in the Workshop with INPUT and OUTPUT gates
|
||||
2. **Save as Gadget** (pink button, top-right) — names it and stores in your backpack
|
||||
3. **Use on puzzle doors** — the game runs your circuit's truth table against the puzzle's required outputs
|
||||
4. If outputs match → puzzle solved, door unlocks!
|
||||
|
||||
## 🗺️ Maps
|
||||
|
||||
| Map | Size | Description |
|
||||
|-----|------|-------------|
|
||||
| Neon Town | 20×18 | Hub town with buildings, NPCs, signs |
|
||||
| Circuit Lab | 10×12 | Professor's lab with workshop tables |
|
||||
| House Interior | 8×8 | Generic house (WIP) |
|
||||
| Route 1 | 20×36 | Path to next area (WIP) |
|
||||
|
||||
### Bidirectional Door System
|
||||
Every door is a two-way link with explicit coordinates — entering a building through a specific door returns you to that exact door when you exit. `spawn` only exists on the starting map (Neon Town).
|
||||
|
||||
## 🛠️ Level Editor
|
||||
|
||||
Standalone editor at `/editor.html` for visually editing maps:
|
||||
|
||||
- **Wall painting** — click/drag to paint collision masks
|
||||
- **Entity placement** — NPCs, exits, interactions, spawn points
|
||||
- **🔗 Bi-Link tool** — create bidirectional door links between maps in one click
|
||||
- **Properties panel** — edit entity properties (dialog, facing, target map/coords)
|
||||
- **Zoom/pan** — mouse wheel, +/-, arrows, right-click drag
|
||||
- **Server save/load** — saves directly to `maps.js` via API
|
||||
- **Keyboard shortcuts** — 1-7 for tools, Ctrl+S to save, Delete to remove
|
||||
|
||||
## 📁 Project Structure
|
||||
|
||||
```
|
||||
├── index.html # Main game page
|
||||
├── editor.html # Standalone level editor
|
||||
├── server.js # Node.js server (static + API)
|
||||
├── Dockerfile # Docker build (node:20-alpine)
|
||||
├── assets/
|
||||
│ ├── map/ # PNG map backgrounds (lab, pallet-town, house, route-1)
|
||||
│ └── character/ # Player sprites (32×32, 4 directions × 3 frames)
|
||||
│ └── npcs/ # NPC sprites (16×16)
|
||||
├── css/
|
||||
│ └── style.css # Workshop UI styles
|
||||
├── js/
|
||||
│ ├── app.js # Entry point, wires everything together
|
||||
│ ├── state.js # Circuit editor state
|
||||
│ ├── gates.js # Gate creation and evaluation
|
||||
│ ├── connections.js # Wire/connection logic
|
||||
│ ├── renderer.js # Circuit editor canvas rendering
|
||||
│ ├── events.js # Circuit editor mouse/keyboard events
|
||||
│ ├── components.js # Custom component system (save/eval/edit)
|
||||
│ ├── saveLoad.js # Circuit serialization
|
||||
│ ├── levels.js # Puzzle level definitions
|
||||
│ ├── constants.js # Shared constants
|
||||
│ └── world/
|
||||
│ ├── gameMode.js # Mode coordinator (world ↔ workshop)
|
||||
│ ├── maps.js # Map definitions (walls, exits, NPCs, interactions)
|
||||
│ ├── sprites.js # PNG asset loading and drawing
|
||||
│ ├── worldRenderer.js# World canvas rendering (map, NPCs, player, HUD, debug)
|
||||
│ ├── worldInput.js # World keyboard input (movement, interaction)
|
||||
│ ├── worldState.js # World game state (player, dialog, puzzles, gadgets)
|
||||
│ └── inventory.js # Gadget backpack (data model + full-screen UI)
|
||||
```
|
||||
|
||||
## 🚀 Development
|
||||
|
||||
### Run locally
|
||||
```bash
|
||||
npm start # or: node server.js
|
||||
# Open http://localhost:3000
|
||||
```
|
||||
|
||||
### Deploy (Docker via Coolify)
|
||||
```bash
|
||||
docker build -t logic-gates .
|
||||
docker run -p 3000:3000 logic-gates
|
||||
```
|
||||
|
||||
Deployed automatically via Coolify on Hetzner at `logic.montlab.dev`.
|
||||
|
||||
### API Endpoints
|
||||
| Method | Endpoint | Description |
|
||||
|--------|----------|-------------|
|
||||
| GET | `/api/maps` | Get current maps.js content |
|
||||
| PUT | `/api/maps` | Update maps.js (creates .bak backup) |
|
||||
|
||||
## 🔧 Technical Details
|
||||
|
||||
- **Rendering**: Vanilla Canvas 2D, no frameworks
|
||||
- **Modules**: ES6 modules (`type="module"`)
|
||||
- **Tile system**: 16px native tiles, 3× scale = 48px on screen
|
||||
- **Collision**: `Set<"x,y">` for O(1) wall lookups
|
||||
- **Player sprite**: 32×32 native, drawn at 48×48 (same visual size as 16×16 NPC sprites at 48×48)
|
||||
- **Camera**: Follows player, centered on screen
|
||||
- **Movement**: Interpolated tile-based (0.15s per tile)
|
||||
- **Circuit evaluation**: Fixed-point iteration (max 20 passes) — supports latches/flip-flops
|
||||
Reference in New Issue
Block a user