security-game/PLAN.md

# Game Plan: Gig Line

## Premise

You are a private security guard working the entrance of a stylized reconstruction of the real El Capitan Entertainment Centre on Hollywood Boulevard. You keep the steps and doors clear, check who is allowed in, and deal with tourists, performers, influencers, confused visitors, intoxicated pedestrians, trespassers, people in mental-health crisis, and rare determined threats.

The game is about **judgment, communication, access verification, and proportionate escalation**, not about attacking everyone who approaches.

## Design Pillars

- **Lowest effective response wins.** Observation, a gesture, or a clear direction should solve most situations.
- **People are not labels.** Clothes, props, credentials, and behavior tell the player what they need; internal NPC types stay in the debug overlay.
- **Every decision has a record.** Incidents, evidence, radio reports, and outcomes feed the shift review.
- **Emergency help is a last resort.** Responders handle crises the guard cannot safely manage; calling them has costs.
- **Readability beats raw fidelity.** The GL Compatibility renderer, clear silhouettes, the focus ring, and the HUD stay legible.

## Core Gameplay Loop

1. Watch the entrance, steps, queue, and sidewalk.
2. Work out why each person is approaching.
3. Use a gesture or short direction before escalating.
4. Verify authorized access when the venue requires it.
5. Escalate only when the person refuses, forces entry, or presents a genuine threat.
6. Record the incident and call for help when it is justified.
7. Review the shift: safety, judgment, accuracy, crowd reaction, and reputation.

A shift lasts roughly 10–15 minutes. Most people comply when approached calmly.

## Access and Verification

Some people are authorized to enter. The guard may admit them by:

- recognizing a person the guard already knows; or
- verifying a venue-appropriate artifact: wristband, ID, ticket, credential, or guest list.

Artifacts can be valid, expired, counterfeit, mismatched, missing, or ambiguous. The player inspects the details the venue asks for instead of judging by appearance.

Decisions are admit, redirect, hold, or refuse. Incorrectly denying an authorized person hurts reputation; admitting an unauthorized person is a security failure. Recognition is a player decision and is recorded as evidence.

## Escalation Model

| Level | Player response | Intent |
| --- | --- | --- |
| 0 | Observation | Watch harmless behavior; intervene only when needed. |
| 1 | Simple deterrence / polite direction | Raise a hand, make eye contact, point to the sidewalk or check-in area, shake the head, give a short instruction. |
| 2 | Formal warning | State the rule and ask for compliance; optionally arm the body camera. |
| 3 | Blocking and positioning | Stand between the person and the door, secure the entrance, keep distance and an escape route, ask for their reason. |
| 4 | Radio for security assistance | Request a second guard, supervisor, building management, or other support. |
| 5 | Emergency response | Hold and confirm the emergency call only for an immediate threat such as a weapon, assault, forced entry, or serious threat to occupants. |

At Level 2 an NPC may leave, argue, pretend not to understand, record the guard, call someone, or move closer. At Level 3 the goal is to deny access **without starting a fight**. Physical contact creates legal, employment, and public-relations consequences.

At Level 4 the report matters: location, description, behavior, weapons seen, and immediate danger. Exaggerated reports damage credibility. At Level 5 the call may evacuate the building, close the street, trigger a review, cost reputation, or open an investigation if unjustified. Responders may command, restrain, evacuate, or arrest; they are not a routine stronger attack.

## NPC Behavior Types

- **Tourists:** take photos, sit on steps, drift toward restricted doors; usually respond well to polite directions.
- **Street performers:** may block stairs or argue when moved; can be redirected to a permitted area.
- **Influencers and filmmakers:** film the guard, test boundaries, and create public-relations risk.
- **Confused visitors:** may have appointments or genuinely believe the building is public; reward patient explanation.
- **Intoxicated pedestrians:** move unpredictably, ignore instructions, and need extra distance or assistance.
- **Trespassers:** test entrances, use distractions, and may return after being told to leave.
- **Violent threats:** rare, escalate quickly, and justify emergency response only when behavior shows immediate danger.
- **People in mental-health crisis:** may loiter, behave unpredictably, and respond poorly to aggression; require patience and careful de-escalation. The setting may refer to a 51/50 hold, but the game should present the person respectfully, not as an automatic threat.

## Special Systems

### Reputation

The shift evaluates peaceful resolutions, response time, radio accuracy, unnecessary confrontations, public complaints, property damage, entrance security, and whether assistance was justified. Calling armed help too often scores poorly even when no one is hurt.

### Evidence and Body Camera

Interactions are recorded automatically. The body camera is a real state the player can toggle; a formal warning also arms it. The shift review uses the recorded events and evidence to show whether the response was justified.

### Crowd Reaction

Nearby pedestrians react to the guard. Calm professionalism attracts little attention; aggression draws a crowd; visible weapons or responders can cause panic. Good de-escalation keeps the boulevard moving.

### Radio Limits

The emergency radio has a cooldown, and the call requires a short report. Assistance takes time to arrive, so the guard must keep monitoring the situation.

## Shift Structure

- **Early:** harmless tourists, delivery workers, people resting on the steps.
- **Midday:** heavier crowds, more entry attempts, more filming.
- **Evening:** lower light, more intoxicated pedestrians and aggressive groups.
- **Late:** a rare serious incident may test whether the player recognizes a real threat without overreacting to ordinary behavior.

## Outcomes

A successful shift keeps the building secure, resolves most incidents without force, keeps public access clear, makes justified emergency calls, avoids bystander injuries, and follows policy.

A poor shift involves excessive force, confronting innocent people, ignoring a real threat, false reports, allowing unauthorized entry, causing a crowd or panic, or behaving recklessly even if the door stayed locked.

## Venues

### El Capitan Entertainment Centre (6840 Hollywood Blvd)

The original scenario: the historic Masonic Temple / El Capitan Entertainment Centre, with six Ionic columns, eight stone steps, the Hollywood Walk of Fame sidewalk, neighbouring theatre and retail frontage, and the four-lane boulevard. Tourists, performers, influencers, confused visitors, intoxicated pedestrians, trespassers, people in crisis, and rare violent threats approach from the street.

Authorized people are recognized or present a valid wristband. Wristbands vary by color, pattern, date, and event marking, and may be valid, expired, counterfeit, or missing.

### The Joke Shop

A Sunset Strip comedy club inspired by The Comedy Store at 8433 Sunset Blvd: a
low black hall under a deep, signature-covered canopy, a circular blade sign,
red velvet curtains and the dry hillside rising behind it. The door person
checks IDs, tickets, reservations, guest-list status, and screens guests with a
handheld wand under venue policy.

The wand does **not** identify a weapon automatically. Keys, belts, and phones can trigger false alarms; the player must ask the guest to identify the item and apply procedure. A guest with valid credentials can still require assistance if they threaten staff or patrons.

Typical events:

- a busy weekend show creates a long line;
- a performer arrives through the guest entrance;
- a guest has a reservation but no ID;
- a fake or borrowed ID appears;
- a wand alert comes from keys or a belt;
- a guest refuses screening but insists on entering;
- someone tries to follow an authorized person through the door;
- a late audience member arrives during the performance.

Joke Shop escalation follows the common ladder: direction, explanation, repeat request, refusal, manager/security assistance, emergency only for immediate danger.

### Hollywood Boulevard Late Night TV Studio

A busy studio entrance with audience members, production staff, performers, guests, deliveries, celebrity arrivals, tourists, influencers, and the same range of street behavior as the building scenario.

Staff and guests are recognized or present a wristband, credential, ticket, guest-list confirmation, or other approved marker. The player keeps the steps clear, protects arrivals and equipment, manages filming boundaries, watches for tailgating, and calls for help only when there is immediate danger.

Typical events:

- a crowd gathers for a celebrity arrival;
- tourists block the entrance for photographs;
- a performer sets up in the audience queue;
- an influencer ignores the filming boundary;
- a confused visitor believes the studio is open;
- an intoxicated pedestrian approaches the stage door;
- a trespasser blends into an audience group;
- an authorized guest arrives without a wristband;
- someone presents a counterfeit credential;
- a violent threat appears during a crowded arrival.

## Presentation and Controls

The game is first-person: WASD and mouse look, a focus cone on nearby people, a billboarded focus circle, `Tab`/mouse-wheel cycling for aim-free selection, and a radial action menu opened with left click or `Space`. `Shift` is precision walk. Gamepad input is supported, and keys/buttons can be remapped in Settings.

The action wheel prioritizes de-escalation: Stop, Look, Point, No, Ask, Inspect, Wand, Warn, Block, Reason, Recognize, Radio. Emergency stays on `R` and is not a wheel slice. `W` is walk, never the wand; `C` is the optional wand shortcut.

The visual direction is readable stylized realism:

- **Blender library:** 8 skinned NPC variants, 18 gear pieces, and 20 street/venue props, with baked albedo/normal/AO/ORM maps, a manifest, and procedural fallbacks. `Rig/Head` stays the focus anchor.
- **Realism pass:** AI-assisted per-phase skyline panoramas, v2 surface tiles with normal maps, wet asphalt at night, a warm day haze, phase-specific sun/exposure/fog, a visible flashlight beam, and denser foliage.
- **References and QA:** runtime UI art lives in `assets/images/ui/`; reference/art-direction sets live in `docs/screens/designs/` and `docs/screens/concepts/`; captures live in `docs/screenshots/`; realism runs live in `docs/screens/realism/`. `screen_designs.py compare/judge` and `tools/check_screenshots.sh` guard drift.
- **Storage convention:** see [ADR-0014](docs/adr/0014-runtime-image-root.md). Never overwrite an existing image; new outputs get a new path or `-vN` suffix.

The path from the current vertical slice to the 0.10.0 release candidate — content depth, onboarding, accessibility, platform QA and release readiness — is tracked in [`TODO.md`](TODO.md); this plan stays at the product/design level.

Primary decisions: [ADR-0007](docs/adr/0007-locomotion-and-input-layers.md), [ADR-0008](docs/adr/0008-cone-focus-and-head-ring.md), [ADR-0009](docs/adr/0009-radial-action-menu.md), [ADR-0010](docs/adr/0010-procedural-npc-presentation.md), [ADR-0011](docs/adr/0011-aim-free-selection-and-precision-walk.md), [ADR-0012](docs/adr/0012-surface-materials-and-generated-props.md), [ADR-0013](docs/adr/0013-blender-authored-npc-characters.md).

## Tech Stack

- **Engine:** Godot 4.7.2, GL Compatibility renderer (Web parity); optional Forward+ Desktop HQ build.
- **Language:** GDScript.
- **Architecture:** venue-driven simulation; shared systems plus `Resource`-based scenario data.
- **Navigation:** `NavigationRegion3D` / `NavigationAgent3D`.
- **NPC behavior:** lightweight custom finite state machines driven by `NpcProfile` resources.
- **UI/audio:** Godot `Control` nodes, themes, procedural audio, and JSON-backed localized strings.
- **Persistence:** JSON in `user://` for settings and shift history.
- **Testing:** custom headless runner (`src/test/test_runner.gd`); GUT was evaluated and not adopted. Python tooling tests cover the asset/screenshot pipelines.
- **Source control/CI:** git on Gitea; `.gitea/workflows/build.yml` runs headless checks and builds/publishes releases on tags.
- **Targets:** Windows, Linux, macOS, and Web. Release artifacts include portables, an NSIS installer, an AppImage, a Web zip, and an optional Desktop HQ zip (Forward+ volumetric lighting; Vulkan required).

## Versioning and Delivery

`config/version` in `project.godot` is the single version source (currently `0.9.3`). Releases are tagged `v<version>`; the CI pipeline builds and publishes the standard artifacts plus the optional Desktop HQ zip. Version bumps follow [Semantic Versioning](https://semver.org/). See [`docs/RELEASING.md`](docs/RELEASING.md) and [`README.md`](README.md) for commands.

## 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.

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

## Future Ideas

- A rare Bob Dobbs cameo (Easter-egg appearance; placement note in `MEMORY.md`).
- Specific unusual NPC behaviors, such as slapping their own face, using hands as scissors, or interacting with props unexpectedly.
- Live 3D body-camera replay; additional venues or seasonal events; real voice/dialogue audio; an image-to-mesh prop pipeline.