security-game/docs/process/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

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.

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