security-game/docs/getting-started.md

Setup, Run and Test, and Controls

Setup

1. Download the Godot 4.3+ editor (official build) and put godot on your PATH. CI pins 4.3; local development is verified with 4.7.2.
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

# 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

# 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: 16 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

The unit test runner is the project's own lightweight harness (no editor plugin required) so CI can run it without the editor.

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