130 lines
6.1 KiB
Markdown
130 lines
6.1 KiB
Markdown
# Setup, Run and Test, and Controls
|
|
|
|
## Setup
|
|
|
|
1. Download Godot **4.7.2** (official build) and put `godot` on your PATH. The project, local tooling and CI use the same version; engine upgrades require import, headless, screenshot and Desktop HQ smoke checks before changing the baseline.
|
|
2. Open or run the project from this directory.
|
|
|
|
## Run and Test
|
|
|
|
```bash
|
|
# Open in the editor
|
|
godot --editor --path .
|
|
|
|
# Run the game
|
|
godot --path .
|
|
|
|
# Headless smoke boot (120 frames then exit)
|
|
godot --headless --path . --quit-after 120
|
|
|
|
# Run all unit tests headlessly (exit code 0 = pass)
|
|
godot --headless --path . --script res://src/test/test_runner.gd
|
|
|
|
# Check docs README coverage, tracked images and local links
|
|
python3 tools/check_docs.py
|
|
|
|
# Save a screenshot to user:// (windowed)
|
|
godot --path . --script res://src/test/take_screenshot.gd
|
|
|
|
# Visual-regression smoke: render the staged captures + prop gallery, then compare them
|
|
./tools/check_screenshots.sh
|
|
|
|
# Windowed control smoke: focus circle, action wheel, wheel cycling + right-click clear; saves PNGs, exits 1 on failure
|
|
godot --path . --script res://src/test/smoke_focus_radial.gd
|
|
|
|
# Session-shell smoke: menu → shift → pause → settings → menu (headless or windowed)
|
|
godot --headless --path . --script res://src/test/smoke_session_shell.gd
|
|
|
|
# End-to-end interaction smoke: inspection, radio, Help search, wand and review
|
|
godot --headless --path . --script res://src/test/smoke_ui_flows.gd
|
|
|
|
# PLAN-verb smoke: recognize, request reason, body camera, warning, blocking
|
|
godot --headless --path . --script res://src/test/smoke_plan_verbs.gd
|
|
|
|
# Prop-collision smoke (windowed): guard stops at a bench, guest routes around it
|
|
godot --path . --script res://src/test/smoke_props.gd
|
|
|
|
# NPC budget smoke: 24 full-rig avatars against the documented frame budget
|
|
godot --headless --path . --script res://src/test/smoke_npc_budget.gd
|
|
|
|
# Movement smoke (windowed): steps, precision walk, footsteps and landing
|
|
godot --path . --script res://src/test/smoke_movement.gd
|
|
|
|
# Crowd smoke: rubbernecking on aggression, panic clearing the entrance
|
|
godot --headless --path . --script res://src/test/smoke_crowd.gd
|
|
|
|
# Emergency smoke: unjustified call, investigation note, evacuation aftermath
|
|
godot --headless --path . --script res://src/test/smoke_emergency.gd
|
|
|
|
# Body-camera timeline smoke: review → timeline → step through → back to review
|
|
godot --headless --path . --script res://src/test/smoke_timeline.gd
|
|
|
|
# Audio smoke: crowd bed follows mood, radio open/close crackle
|
|
godot --headless --path . --script res://src/test/smoke_audio.gd
|
|
|
|
# Scenario-content smoke: wand refusal, celebrity crowd spike
|
|
godot --headless --path . --script res://src/test/smoke_scenario_content.gd
|
|
|
|
# Tutorial smoke (windowed): completion, replay and skip; isolated user data
|
|
XDG_DATA_HOME=/tmp/gigline-tutorial godot --path . --fixed-fps 60 --script res://src/test/smoke_tutorial.gd -- --tutorial
|
|
|
|
# Campaign/checkpoint smoke (windowed): resume, review continue, help; isolated data
|
|
XDG_DATA_HOME=/tmp/gigline-campaign godot --path . --fixed-fps 60 --script res://src/test/smoke_campaign.gd
|
|
```
|
|
|
|
The unit test runner is the project's own lightweight harness (no editor plugin required) so CI can run it without the editor.
|
|
|
|
## Save Data
|
|
|
|
The game writes four JSON files in Godot's `user://` directory:
|
|
|
|
| Platform | Location |
|
|
| --- | --- |
|
|
| Linux | `~/.local/share/godot/app_userdata/Gig Line/` |
|
|
| Windows | `%APPDATA%\Godot\app_userdata\Gig Line\` |
|
|
| macOS | `~/Library/Application Support/Godot/app_userdata/Gig Line/` |
|
|
|
|
Files: `settings.json`, `campaign.json`, `shift_results.json` and the versioned
|
|
`shift_state.json` checkpoint. The schema, migration/default-filling rules,
|
|
atomic-write behavior and checkpoint contents are in
|
|
[`architecture.md#persistence-and-save-contract`](architecture.md#persistence-and-save-contract).
|
|
|
|
For a clean first launch, delete the four files (or the whole `Gig Line` user
|
|
directory). Settings' **Reset campaign** clears campaign progress separately.
|
|
To back up or move a profile, copy the files while the game is closed; restore
|
|
them to roll back. Shift history is diagnostic and not required to resume.
|
|
|
|
## Controls
|
|
|
|
Keyboard and mouse are the default; a gamepad works without configuration (left stick moves,
|
|
right stick looks, A opens/confirms the wheel, B cancels, X inspects, Y calls the radio, LB walks
|
|
slowly, RB uses the wand). Keys and pad buttons can be rebound in Settings, and the remaps persist
|
|
in `user://settings.json`. The HUD legend switches to gamepad hints when a pad event arrives.
|
|
|
|
| Input | Action |
|
|
| --- | --- |
|
|
| W/A/S/D + mouse | Move and look |
|
|
| Space / left click | Action wheel for the focused person (Stop, Look, Point, No, Ask, Inspect, Wand, Warn, Block, Reason, Recognize, Radio) |
|
|
| A / D or ←/→ | Step through the action wheel (while it is open) |
|
|
| Space / left click | Confirm the highlighted action (while the wheel is open) |
|
|
| Esc / right click | Close the top panel; Esc with nothing open pauses the shift (Esc again resumes) |
|
|
| ← / → or ↑ / ↓ | Navigate the venue menu and the pause / settings panels |
|
|
| Enter | Start the highlighted venue from the menu, or confirm in a panel |
|
|
| 1 / 2 / 3 | Quick gestures without the wheel: raise hand, point, head shake (Level 1) |
|
|
| Q | Polite direction (Level 1) |
|
|
| 4 | Formal warning (Level 2) |
|
|
| 5 | Blocking and positioning (Level 3) |
|
|
| 6 | Security assistance radio (Level 4) |
|
|
| R | Emergency radio, hold on-screen button ~1.6s (Level 5) |
|
|
| E | Inspect access artifacts / close inspection |
|
|
| C | Handheld wand screening (wand venues only) |
|
|
| A / D | Allow / deny entry during inspection or wand check |
|
|
| V | Cycle venue (debug shortcut; restart via V restarts the current shift) |
|
|
| Tab / mouse wheel ↓ / ↑ | Cycle the target among nearby NPCs, nearest first (aim-free; the target stays selected) |
|
|
| Right click (nothing open) | Clear the focused person and return to aim-based focus |
|
|
| Shift (hold) | Precision walk at roughly half speed for close work at the door |
|
|
| G | Toggle flashlight (widens NPC perception at night) |
|
|
| B | Toggle the body camera; a formal warning switches it on automatically |
|
|
| L | Lock / unlock the restricted door (thwarts forced entry) |
|
|
| F | Toggle debug overlay |
|