security-game/PLAN.md

Game Plan: Step Line

Premise

You play a private security guard stationed at the top of the steps outside a fictional building on Hollywood Boulevard. Your job is to keep the entrance and steps clear while dealing with tourists, trespassers, performers, protesters, intoxicated pedestrians, and occasional determined intruders.

The game is about judgment, communication, and escalation management, not simply attacking anyone who approaches.

---

Core Gameplay Loop

1. Watch the stairs, entrance, and sidewalk.
2. Identify why each person is approaching.
3. Give verbal warnings and directions.
4. Escalate only when necessary.
5. Call for assistance in rare dangerous situations.
6. Maintain public safety, building security, and your employer’s reputation.

People should not all behave the same way. Some are confused, some are rude, some are filming, and a very small number are deliberately attempting to enter.

Authorized Access

Some people are authorized to enter the building. The security guard must verify them before granting access.

An authorized person can be admitted if either:

• The guard already knows and recognizes them.
• The person presents a valid event or staff wristband, which the guard checks before opening the entrance.

The wristband check should require the player to inspect details such as its color, pattern, date, or event marking. NPCs may have valid wristbands, expired wristbands, counterfeit wristbands, or no wristband at all.

The player should avoid relying on appearance or assumptions. A familiar person may still need verification if the building’s current policy requires it, while an unfamiliar person with a valid wristband may be admitted after a successful check. Incorrectly denying an authorized person harms the building’s reputation; admitting someone without authorization creates a security failure.

---

Escalation System

Level 0: Observation

The guard watches NPC behavior and decides whether intervention is needed.

Examples:

• Someone taking a photograph from the sidewalk
• A tourist reading a map
• A person sitting briefly on the edge of the steps
• Someone approaching the entrance with a delivery package

The player should avoid interrupting harmless behavior. Unnecessary confrontations reduce the guard’s performance rating.

---

Level 1: Simple Deterrence and Polite Direction

The player can begin with a simple, nonverbal deterrent before speaking. These actions are quick and low-pressure, making them useful when someone is only approaching the steps casually or appears unsure.

Possible actions include:

• Raise an open hand to signal “stop” or “please wait”
• Make eye contact
• Point toward the public sidewalk
• Gesture toward the wristband-check area
• Shake the head gently when someone approaches a restricted entrance

If the person continues, the player uses a short verbal prompt.

Example commands:

• “Please keep the stairs clear.”
• “The entrance is for authorized guests only.”
• “You can’t remain here.”
• “Please move back to the sidewalk.”

At this stage, most NPCs comply immediately.

---

Level 2: Formal Warning

If the person remains on the steps or continues toward the entrance, the player issues a formal warning.

Possible dialogue:

“This is private property. You have been asked to leave. Please move away from the entrance now.”

The player may activate a visible security light or body camera. This creates a record of the interaction and can discourage repeat offenders.

At this level, the NPC may:

• Leave
• Argue
• Pretend not to understand
• Start recording the guard
• Call someone else
• Move closer to the door

---

Level 3: Blocking and Physical Positioning

The guard moves into a defensive position between the NPC and the building.

Gameplay actions:

• Stand in front of the entrance
• Point toward the public sidewalk
• Lock or secure the door
• Request the person’s reason for entry
• Keep distance while maintaining a clear escape route
• Use a flashlight or radio warning tone at night

The player should not automatically shove or strike people. Physical contact creates legal, employment, and public-relations consequences.

This level is about denying access without creating a fight.

---

Level 4: Radio for Security Assistance

If the person refuses to leave, attempts to force the door, threatens staff, or repeatedly returns, the player uses the radio.

Possible assistance:

• A second security guard
• Building management
• Police dispatch
• Nearby security personnel

The radio call takes time, so the player must continue monitoring the person while waiting. The player can choose what information to report:

• Location
• Description
• Behavior
• Whether weapons have been seen
• Whether anyone is in immediate danger

Incorrect or exaggerated reports damage the guard’s credibility.

---

Level 5: Emergency Response

This is reserved for immediate threats, such as:

• A person displaying a weapon
• An attempted forced entry while people are inside
• An assault on the guard or another person
• A serious threat against occupants
• A violent struggle that cannot be safely disengaged

The player presses and holds a clearly marked Emergency Radio button. A confirmation prompt prevents accidental activation.

The call brings an off-duty law-enforcement officer or armed emergency responder to the location. This character has greater authority and can control a dangerous situation, but the call has serious consequences:

• The building may be evacuated
• The street may be closed
• The guard’s actions are reviewed
• The building loses reputation
• The player may face an investigation if the call was unjustified
• The officer may use force only when the game’s threat assessment supports it

The officer should not function as a convenient “stronger attack.” Their role is to handle a crisis the player cannot safely manage. In most scenarios, their arrival results in commands, restraint, evacuation, or arrest rather than automatic gunfire.

---

NPC Behavior Types

Tourists

• Take photos
• Sit on steps
• Wander toward restricted doors
• Usually respond well to polite directions

Street Performers

• May block stairs
• May become argumentative if moved
• Can be redirected to a permitted area

Influencers and Filmmakers

• Film the guard
• Test boundaries for content
• May accuse the guard of overreacting
• Create public-relations risk

Confused Visitors

• Have appointments or directions
• May genuinely believe the building is public
• Reward patient explanations

Intoxicated Pedestrians

• Move unpredictably
• May ignore instructions
• Require additional distance and assistance

Trespassers

• Repeatedly test entrances
• Use distractions
• May return after being told to leave

Violent Threats

• Rare
• Escalate quickly
• Trigger the emergency response system only when their behavior indicates immediate danger

51/50s

Crazy Homeless Individuals may be referred to as "51/50s" in the context of the game, indicating a person who may be experiencing a mental health crisis and could pose a potential threat to themselves or others.

• May loiter near entrances
• Can be unpredictable in behavior
• Often respond poorly to aggressive confrontation
• Require careful de-escalation and patience

---

Special Systems

Reputation Meter

The player is evaluated on:

• Number of incidents resolved peacefully
• Response time
• Accuracy of radio reports
• Number of unnecessary confrontations
• Public complaints
• Property damage
• Whether the entrance remained secure

A player who calls armed assistance too often should score poorly, even if no one was injured.

Evidence and Body Camera

Interactions are automatically recorded. After each shift, the player reviews incidents and sees whether their escalation was justified.

This encourages players to think before acting.

Public Crowd Reaction

Nearby pedestrians react to the guard’s behavior:

• Calm professionalism attracts little attention
• Aggressive behavior creates a crowd
• Visible weapons or emergency responders cause panic
• Good de-escalation keeps the boulevard moving normally

Limited Radio Battery or Cooldown

The emergency radio should not be infinitely available. A call has a cooldown and may require the player to give a short report first.

---

Shift Structure

Each shift lasts 10–15 minutes.

Early Shift

Mostly harmless tourists, delivery workers, and people sitting on the stairs.

Midday

Crowds become heavier. More people attempt to enter the building or film interactions.

Evening

Lighting decreases. Intoxicated pedestrians and aggressive groups become more common.

Late Shift

A rare serious incident may occur, testing whether the player recognizes a genuine threat instead of overreacting to ordinary behavior.

---

Win and Loss Conditions

Successful Shift

• Building remains secure
• Most incidents are resolved without physical force
• Public access remains clear
• Emergency calls are justified
• No bystanders are injured
• The player follows company policy

Poor Performance

• Excessive use of force
• Repeatedly confronting innocent people
• Ignoring a real threat
• Making false radio reports
• Allowing repeated unauthorized entry
• Causing a crowd or panic

A shift can be technically “secure” but still receive a poor rating if the guard behaves recklessly.

---

Venues and Scenarios

The game should support multiple venues, each with its own access rules, crowd patterns, equipment, and escalation procedures. The core gameplay remains the same: observe, verify access, communicate clearly, and use the lowest effective level of escalation.

The Joke Shop

The Joke Shop is a comedy club scenario where the player works as a door person at the entrance. The player is responsible for checking identification, confirming that guests are attending the correct show, and screening guests for weapons with a handheld security wand.

Primary Responsibilities

• Check each guest’s government-issued ID where required.
• Confirm that the guest meets the venue’s age requirement.
• Verify that the ID appears valid and belongs to the person presenting it.
• Check tickets, reservations, or guest-list status.
• Use the handheld wand according to venue policy.
• Direct guests through the entrance without blocking the sidewalk.
• Refuse entry when a guest has an invalid ID, no valid admission, or a prohibited item.

Guest Outcomes

A guest may have:

• A valid ID and ticket
• A valid ID but no ticket or reservation
• An expired, damaged, or questionable ID
• An ID that does not match the guest
• A prohibited item detected by the wand
• A harmless item that causes a false alarm
• No ID when identification is required

The player must make decisions based on the venue’s rules and observable evidence, not on a guest’s appearance or attitude. A calm guest with a valid ID should be admitted efficiently, while an aggressive guest with valid credentials may still require assistance if they threaten staff or other patrons.

Joke Shop Escalation

1. Nonverbal direction: Raise a hand, point to the ID-check area, or gesture for the guest to wait.
2. Routine explanation: Explain the ID, ticket, or wand-check requirement.
3. Repeat request: Clearly state what is missing or what must happen before entry.
4. Refusal of entry: Keep the guest outside and direct them away from the entrance.
5. Manager or security assistance: Call for a supervisor or another staff member when a guest argues, refuses screening, or blocks the line.
6. Emergency response: Call emergency services only for an immediate threat, such as a weapon, assault, or serious attempt to force entry.

The handheld wand should not automatically identify an item as a weapon. The player must interpret the alert, ask the guest to identify the item, and follow venue procedure. The goal is to create a believable screening challenge while keeping the emphasis on communication and proportionate responses.

Scenario Events

• A busy weekend comedy show creates a long line.
• A performer arrives through the guest entrance and must be recognized or verified.
• A guest forgets their ID but appears on the reservation list.
• A fake or borrowed ID is presented.
• A wand alert comes from keys, a belt buckle, or a phone.
• A guest refuses the screening but insists on entering.
• A disruptive guest attempts to follow another person through the door.
• A late-arriving audience member tries to enter during a performance.

Hollywood Boulevard Late Night TV Studio

This scenario takes place outside a late-night television studio on Hollywood Boulevard. The guard manages the front steps, studio entrance, guest arrivals, deliveries, audience members, and the public crowd gathered around the building.

The studio encounters all of the NPC types described in the game plan:

• Tourists stopping to take photos or watch arrivals
• Street performers occupying the steps or performing near the entrance
• Influencers and filmmakers recording the guard, guests, or celebrity arrivals
• Confused visitors looking for the wrong entrance or trying to attend a show without understanding the access rules
• Intoxicated pedestrians approaching the entrance or disrupting the crowd
• Trespassers testing the doors, trying to follow authorized guests, or returning after being directed away
• Violent threats, which are rare but require careful recognition and emergency escalation

The studio also has authorized guests and staff. They must either be recognized by the guard or present a valid wristband, credential, guest-list confirmation, or other approved access marker. The player must check these credentials without holding up the audience line or allowing unauthorized people to enter.

Studio Responsibilities

• Keep the front steps and entrance clear.
• Direct tourists and performers away from restricted areas.
• Check wristbands, credentials, tickets, or guest-list status.
• Admit authorized staff, performers, guests, and audience members.
• Manage influencers and filmmakers without unnecessarily obstructing lawful filming.
• Protect celebrity arrivals and production equipment from crowding.
• Coordinate with studio staff, production assistants, and additional security guards.
• Watch for attempts to follow authorized people through the entrance.
• Call for emergency assistance only when there is an immediate threat.

Studio Scenario Events

• A crowd gathers to watch a celebrity arrive.
• Tourists stop on the steps and block the entrance for photographs.
• A street performer sets up in front of the audience queue.
• An influencer repeatedly ignores the restricted filming boundary.
• A confused visitor believes the studio is open to the public.
• An intoxicated pedestrian wanders toward the stage door.
• A trespasser tries to blend into an audience group.
• An authorized guest arrives without their wristband and must be verified another way.
• Someone presents a counterfeit wristband or credential.
• A violent threat appears during a crowded arrival, requiring the player to protect the entrance while calling for assistance.

The scenario should test the player’s ability to distinguish ordinary Hollywood Boulevard activity from a genuine security problem. The best solution is usually a simple gesture, clear direction, or credential check rather than immediate escalation.

Future venues can reuse this structure while changing the rules, equipment, staff roles, and types of access decisions.

Tech Stack

Engine: Godot 4

The game is built with the Godot Engine 4.x editor. Godot was chosen for its free and open-source license, built-in 3D rendering, navigation, animation, audio, and UI systems, and its low weight for fast prototyping and iteration.

Language: GDScript

Gameplay logic is written in GDScript. It is tightly integrated with the engine, fast to iterate on, and avoids an external build toolchain for the prototype phase.

Architecture Mapping

The venue-driven architecture maps onto Godot as follows:

• Nodes and scenes: Each major system (ShiftCoordinator, NPCController, InteractionSystem, AccessVerifier, EscalationManager, RadioSystem, IncidentRecorder, ReputationEvaluator, CrowdSystem, ShiftReview) is a Godot node or scene.
• Scenarios as resources: VenueScenario and content such as NpcProfile, Dialogue, EventPool, and AccessPolicy are defined as custom Godot Resource types so venue content is data-driven and inspectable in the editor.
• Navigation: NavigationRegion3D and NavigationAgent3D drive NPC and player movement.
• NPC behavior: Lightweight custom finite state machines built on the NPCController node, with behavior traits coming from NpcProfile resources.
• UI: Godot Control nodes and themes for prompts, access inspection, radio reports, dialogue, timers, and the shift review screen.
• Audio: Godot audio buses and AudioStreamPlayer nodes for voices, crowd noise, radio, and environment sound.

Content and Data

• Scenario and entity configuration uses typed Godot Resource files (.tres), created either in the editor or via scripts.
• Localized dialogue and text are stored in JSON files when they need to be editable outside the editor.
• Save data and shift results use JSON in Godot's user:// directory.

Testing

• Unit and scenario tests use a lightweight custom headless runner (src/test/test_runner.gd). GUT was evaluated but requires the editor plugin.
• Tests run in headless mode so rules, access verification, escalation, and scoring can be verified without rendering or user input.

Version Control and CI

• Source is tracked with git.
• Gitea Actions (.gitea/workflows/build.yml) runs headless Godot tests on push/PR and exports Linux/Windows/macOS desktop builds plus the NSIS installer and AppImage on tags.

Planned Commands

The following commands apply once the Godot project is scaffolded:

• Open the editor: godot --editor --path .
• Run the game: godot --path .
• Run tests headlessly: godot --headless --path . res://src/test/test_runner.tscn

Export Targets

Desktop is the first target: Windows, Linux, and macOS. Web export is a later option.

Player Control, Focus, and Action Menu (next pass)

The prototype already walks and looks in first person, but the control scheme fights itself and targeting is a hairline. This pass replaces that with three things that belong together: solid locomotion, a visible focus on a person, and a round action menu for what to do with them.

Decisions: ADR-0007 locomotion and input layers, ADR-0008 cone focus and head ring, ADR-0009 radial action menu, ADR-0010 procedural NPC presentation.

What is wrong today

• W is walk-forward in the input map and wand-screening in GameManager._handle_key. Walking at someone with a wand venue fires the wand.
• A / D are strafe and also allow/deny during inspection.
• Q is polite direction and is also bound as cancel.
• Focus is an 8 m physics ray from the camera. Missing a capsule by a few pixels clears the target. There is no mark in the world that you have someone.
• NPC bodies are colored capsules with props. They read as markers, not people.
• Actions live on number keys 1–6 plus Q / E / W / R. That is a cheat-sheet, not a verb you pick while looking at a person.
• Esc only toggles mouse capture. There is no "I changed my mind" for an action in progress.

Movement and look

Keep first-person WASD + mouse look. Fix the feel and stop stealing those keys.

• Body yaw from mouse X, head pitch from mouse Y, pitch clamped (already -80 to 80).
• Move relative to body yaw only (already). Add short acceleration / deceleration so starts and stops are not instant.
• Gravity only when not is_on_floor(); floor_snap_length so the steps work.
• Mouse look runs only while MOUSE_MODE_CAPTURED and no modal UI is open (radial, inspection, wand, radio, shift review).
• Walk speed stays around 3.2 m/s. No sprint, no crouch in this pass.
• While the radial is open: freeze look and WASD so A / D can cycle the menu. Recapture the mouse when the menu closes.
• Esc with a modal open closes that modal and does nothing else. Esc with nothing open keeps the current capture/release toggle.

Equipment stays on its own keys because it is not about a person: G flashlight, L door lock, Tab cycle nearby people, V venue (debug), F debug overlay. R stays the dedicated emergency radio (hold-to-confirm on the existing panel). Those do not go on the wheel.

Wand leaves W. It is a slice on the wheel (greyed when the venue has no wand) and an optional extra key that is not WASD, suggested C.

Focus area

Replace the hairline ray as the primary picker.

• A focus cone in front of the camera: people within about 10 m whose head projects inside a screen-space circle around the crosshair (about 90 px / 10 degrees).
• If several heads sit in the circle, pick the one closest to the center, then the nearer one if tied.
• The person must be in front (dot with camera forward > 0) and not fully occluded by the building. A short ray to the head is enough for occlusion.
• Tab still cycles people inside 12 m as the aim-free path. Cycling sets the same focused person the cone would.
• Clearing: look away until the head leaves the circle for a few frames (small grace so a bob does not drop them), or they walk out of range.

Head ring

When a person is in focus, draw a thin ring around their head.

• Attach to the avatar Head node, sitting just above the skull, billboarded to the camera so it stays a circle on screen.
• Slow spin is fine; no ping-pong scale spam.
• Idle focus: pale gold, modest size. Radial open on that person: brighter, slightly larger.
• Optional small name under the ring (display_name only, not the archetype cheat Violent Threat in the world). The existing HUD target line can keep the archetype for the prototype.
• One ring at a time. Everyone else has none.

Implementation sketch: MeshInstance3D torus or a thin unshaded ring mesh on the avatar, toggled from GuardController / GameManager when focus changes. Screen-space fallback (unproject head, draw a Control circle) is acceptable if the 3D torus z-fights on hats.

Round action HUD

A doughnut / pie menu centered on the screen, opened on the focused person.

Open

• Left mouse button, or Space, while someone is in focus and no other modal is open.
• If nobody is in focus, log the existing "aim first" line and do not open.
• The click that opens the menu must not also pick a slice.

While open

• Mouse becomes visible. Look and walk freeze.
• Center of the doughnut shows the focused person's display_name.
• Slices, clockwise from the top, de-escalation first:
  1. Raise hand (stop / wait)
  2. Point away
  3. Head shake
  4. Polite direction (old Q)
  5. Inspect access (old E)
  6. Wand (grey if the venue has no wand)
  7. Formal warning
  8. Block
  9. Radio assist
• Emergency is not on the wheel (R only).
• Highlight follows the mouse angle when the cursor is over the ring. Left / Right or A / D step the highlight. Wrap around.

Confirm

• Click a slice: that action runs, menu closes, mouse recaptured.
• Space while a slice is highlighted: same.
• Inspect or wand: close the wheel, then open the existing inspect / wand panel. Allow / deny on that panel stay A / D (walk is frozen only while the wheel is up; once the inspect panel is open, WASD can move again, so allow/deny on A / D remains a press handler and must ignore repeats / echo, which it already does). Safer: keep walk frozen for inspect/wand too, until the panel closes. Prefer freeze until the whole interaction ends.
• Radio assist: close the wheel, open the existing radio panel.

Cancel

• Esc or right mouse button: hide the menu, no action, no recorder event, recapture mouse.
• Focus and the head ring stay as they were.

Number keys 1–6 may remain as shortcuts that skip the wheel so a smoke-test script still works. They must not fire while the wheel is open (the wheel owns A / D / Space). Document both in the README.

NPC display

Stay on the procedural capsule rig (no Mixamo / GLB dependency this pass). Make them read as people at conversation distance.

• Neck between torso and head; shoes; simple hair cap (color from seed); two dark eye spheres on the face so a head has a front.
• Keep archetype props (camera, box, hat, sign, bag). Keep height / brightness variation from the visual seed.
• Collision capsule matches the scaled height so the focus ray / cone hits the body you see.
• Head stays a named node other systems can find (get_node("Rig/Head")) for the ring and the cone.
• Walk bob and the "look at the guard when noticed" cue stay.
• Do not put the internal type name (Trespasser, Violent Threat) on the body. The player should judge from clothes, props, and behavior. The debug overlay (F) can still print the type.

AI textures in assets/textures/ai/ stay out of this pass unless a specific map (shirt, hair) is already the right size.

Input map (target)

Action	Bind
Walk	WASD / arrows (arrows do not walk while the wheel is open; they step the highlight)
Look	Mouse, captured
Open / confirm action menu	LMB, Space
Cancel menu	RMB, Esc
Step highlight	A / D, left / right arrows
Emergency radio	R
Flashlight	G
Door lock	L
Cycle nearby people	Tab
Wand shortcut	C (not W)
Inspect shortcut	E still allowed when the wheel is closed

Files this pass is expected to touch

• src/game/guard_controller.gd — cone focus, no look while modal, accel, floor snap.
• src/game/npc_avatar.gd — face / hair / neck, head marker, ring toggle.
• src/game/ui/action_radial.gd — new Control, _draw doughnut, slice pick.
• src/game/ui/hud.gd — host the radial; stop teaching number-key verbs as the only path.
• src/game/game_manager.gd — input routing, freeze flags, open/confirm/cancel.
• project.godot — input map.
• src/core/strings.gd — controls line, aim-first, no new tone-of-voice.
• src/test/tests/test_focus_and_radial.gd — cone pick, wrap, cancel emits nothing, W is not wand.
• README controls table and smoke checklist.

Design Direction

The game should feel like a tense workplace simulation with occasional crisis moments. The most satisfying outcome is not overpowering an NPC; it is recognizing the situation early and resolving it calmly.

A useful guiding rule:

The player wins by choosing the lowest level of escalation that keeps everyone safe.