security-game/docs/getting-started.md

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

# 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 and Migration

The game keeps four small JSON files in Godot's user:// directory, which is ~/.local/share/godot/app_userdata/Gig Line/ on Linux, %APPDATA%\Godot\app_userdata\Gig Line\ on Windows and ~/Library/Application Support/Godot/app_userdata/Gig Line/ on macOS:

File	Contents
settings.json	Camera, HUD, binding, difficulty, audio, accessibility and tutorial flags. Missing keys are filled from the current defaults; there is no schema version because the field set grew compatibly.
campaign.json	Campaign index, completed venues, difficulty, shift number and last grade. Older files with missing fields open at the safe defaults.
shift_results.json	Completed-shift review history, appended as an array.
shift_state.json	Resumable mid-shift checkpoint, version 1. It stores the venue, guard/door/flashlight/body-camera state, coordinator snapshot and NPC rows.

Writes go to a sibling .tmp file and are renamed only after the complete JSON is written. A corrupt or partial file is ignored on load, so the player gets defaults rather than a crash and a valid old file is not overwritten by a failed replace. The migration fixtures used by the tests live in src/test/fixtures/saves/.

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 those files while the game is closed; to roll back, restore the previous copies. Shift history is diagnostic and is not required to resume a checkpoint.

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