Add initial README and architecture decision records for venue-driven simulation game

- Introduced README.md outlining game concept, mechanics, and planned venues. - Added ADRs for venue-driven architecture, de-escalation-first model, explicit access verification, local single-player focus, event-based incident recording, and choice of Godot 4 with GDScript.
2026-10-31 11:16:53 +01:00
commit e23f284ad4
@@ -0,0 +1,290 @@
 # Step Line
 Step Line is a workplace security simulation about observation, communication, access verification, and proportionate escalation. The player works security at public-facing venues around Hollywood Boulevard, managing stairs, entrances, crowds, guests, staff, and occasional serious threats.
 The central design goal is simple:
 > The player wins by choosing the lowest level of escalation that keeps everyone safe.
 This is a planned game project. The repository currently contains the game design, architecture documentation, and technical plan. The selected engine is Godot 4 with GDScript; a playable prototype has not yet been implemented.
 ## Game Overview
 A typical shift lasts 10–15 minutes. The player:
 1. Watches the entrance, steps, queue, and surrounding sidewalk.
 2. Determines why each person is approaching.
 3. Uses simple gestures or polite directions first.
 4. Verifies authorized access using recognition, wristbands, credentials, tickets, or guest lists.
 5. Escalates only when a person refuses directions, attempts unauthorized entry, or presents a genuine threat.
 6. Records the incident through body-camera and radio systems.
 7. Finishes the shift with a performance review based on safety, judgment, and professionalism.
 The game rewards calm resolutions rather than aggressive behavior. Emergency assistance and armed responders are rare last-resort systems with meaningful consequences.
 ## Planned Venues
 ### Hollywood Boulevard Building
 The original scenario places the guard at the top of the steps outside a fictional building. Tourists, street performers, influencers, confused visitors, intoxicated pedestrians, trespassers, people experiencing a mental-health crisis, and rare violent threats may approach the entrance.
 Authorized people must either be recognized by the guard or present a valid wristband. Wristbands can have different colors, patterns, dates, or event markings. They may be valid, expired, counterfeit, or missing.
 ### The Joke Shop
 The Joke Shop is a comedy-club scenario. The door person checks IDs, tickets, reservations, and guest-list status, then uses a handheld security wand according to venue policy. The player must interpret wand alerts rather than treating every alert as proof of a weapon; keys, belts, phones, and other harmless objects can trigger false alarms.
 ### Hollywood Boulevard Late Night TV Studio
 This scenario combines the previously defined NPC types with a busy television-studio entrance. The player manages audience members, production staff, performers, guests, deliveries, celebrity arrivals, tourists, street performers, influencers, confused visitors, intoxicated pedestrians, trespassers, people experiencing a mental-health crisis, and rare violent threats.
 The studio uses wristbands, credentials, tickets, guest-list confirmation, and personal recognition to authorize entry. Crowd control, filming boundaries, following authorized guests through the door, and counterfeit credentials are key events.
 ## Escalation Model
 The common escalation model has six levels:
 0. **Observation** — Decide whether intervention is necessary.
 1. **Simple deterrence and polite direction** — Raise an open hand, make eye contact, point toward the sidewalk or check-in area, shake the head, or give a short instruction.
 2. **Formal warning** — Clearly explain the rule and request compliance.
 3. **Blocking and physical positioning** — Secure the entrance, maintain distance, preserve an escape route, and deny access without starting a fight.
 4. **Radio for security assistance** — Request a supervisor, second guard, building management, or other appropriate support.
 5. **Emergency response** — Hold the emergency-radio button and confirm only when there is an immediate threat, such as a weapon, assault, forced entry, or serious threat to occupants.
 An off-duty law-enforcement officer or armed emergency responder may arrive during a valid emergency. This character is not intended to be a routine stronger attack. Their role is crisis control, evacuation, restraint, arrest, or other appropriate intervention, with force governed by the situation and meaningful consequences for unjustified calls.
 ## Core Systems
 - **NPC behavior:** NPCs have different motivations, temperaments, compliance levels, and reactions to the player’s approach.
 - **Access verification:** Recognition, wristbands, IDs, tickets, credentials, and guest lists determine who may enter.
 - **Nonverbal deterrence:** Small actions such as raising a hand can resolve low-risk situations without dialogue or force.
 - **Dialogue and tone:** Professional, friendly, firm, or suspicious approaches affect outcomes.
 - **Escalation:** The player chooses the lowest effective response.
 - **Radio assistance:** Calls require useful information and may take time to arrive.
 - **Evidence:** Body-camera records support shift review and accountability.
 - **Crowd reaction:** Aggressive behavior, visible weapons, and emergency response can create panic or attract a crowd.
 - **Reputation:** Peaceful resolutions, accurate reports, low property damage, and justified calls improve performance; unnecessary confrontations and false reports reduce it.
 - **Shift review:** The player receives feedback on access decisions, escalation choices, public complaints, injuries, and security outcomes.
 ## Architecture Overview
 The planned solution uses a venue-driven simulation architecture. Venue configuration supplies rules, access types, NPC pools, equipment, events, and escalation policies. Shared simulation systems provide movement, perception, interactions, dialogue, access verification, escalation, radio calls, crowds, reputation, evidence, and shift review.
 ```text
 Venue Scenario / Rules
          |
          v
   Shift Coordinator -----> Event Scheduler
          |                         |
          v                         v
   NPC Simulation <---------- Interaction System
          |                         |
          v                         v
   Access Verification ----> Escalation / Response
          |                         |
          +-------------> Reputation / Evidence
                                      |
                                      v
                                Shift Review
 ```
 The architecture maps onto Godot 4 nodes, scenes, and custom resources as described in [Tech Stack](#tech-stack). See the full arc42-style outline in [Architecture](#architecture) and the decisions in [`docs/adr/`](docs/adr/).
 ## Tech Stack
 - **Engine:** Godot Engine 4.x
 - **Language:** GDScript
 - **Architecture:** Venue-driven simulation using nodes, scenes, and custom `Resource`-based scenario data
 - **Navigation:** `NavigationRegion3D` and `NavigationAgent3D`
 - **NPC behavior:** Custom lightweight finite state machines driven by `NpcProfile` resources
 - **UI and audio:** Godot `Control` nodes, themes, audio buses, and `AudioStreamPlayer` nodes
 - **Testing:** GUT (Godot Unit Test) in headless mode
 - **Source control:** git with GitHub Actions for headless tests and later desktop exports
 - **Targets:** Windows, Linux, and macOS desktop first; web later
 ### Setup
 1. Install the Godot 4.x editor.
 2. (Once the project is scaffolded) open the project: `godot --editor --path .`
 ### Run and Test
 - Run the game: `godot --path .`
 - Run tests headlessly via GUT (configured during project setup).
 These commands apply after `project.godot` and the Godot folder structure exist.
 ## Architecture
 This section follows the structure of the arc42 architecture documentation template.
 ### 1. Introduction and Goals
 #### Functional goals
 - Simulate believable security work at multiple public-facing venues.
 - Provide clear, low-pressure deterrence options before verbal or physical escalation.
 - Make access verification a meaningful gameplay decision.
 - Support distinct NPC behaviors and scenario events.
 - Make emergency response rare, consequential, and justified by observable danger.
 - Provide shift-level feedback so players can learn from decisions.
 #### Quality goals
 - **Clarity:** Players should understand why an NPC is allowed, denied, or escalated.
 - **Extensibility:** New venues should reuse shared systems and primarily provide configuration and content.
 - **Testability:** Rules and outcomes should be testable without rendering or real-time input.
 - **Consistency:** Similar situations should follow predictable venue and escalation rules.
 - **Respectful representation:** Mental-health crises and public interactions should not be reduced to stereotypes or treated as automatic threats.
 ### 2. Constraints
 - The first implementation should be small enough for a playable vertical slice.
 - The engine is Godot 4 with GDScript; the prototype has not yet been implemented.
 - Venue-specific policies must be configurable rather than hard-coded into individual NPCs.
 - The game must preserve the de-escalation-first design described in [`PLAN.md`](PLAN.md).
 - The project uses the repository workflow described in [`AGENTS.md`](AGENTS.md).
 ### 3. Context and Scope
 The player interacts with NPCs, venue entrances, access artifacts, equipment, staff, and response services. The game itself owns the simulated world, rules, scoring, events, and shift review. External services are currently out of scope; radio, body camera, and emergency response are simulated systems.
 ### 4. Solution Strategy
 - Use a shared simulation core with venue-specific scenario data.
 - Represent NPC behavior using state machines or behavior trees with configurable traits.
 - Model escalation as explicit, auditable state transitions.
 - Separate access verification from NPC identity and presentation details.
 - Keep scoring and reputation event-driven so every action can be reviewed.
 - Use authored scenario events alongside procedural routine traffic.
 - Make the first playable target one venue and one complete shift before adding breadth.
 ### 5. Building Block View
 #### Level 1: Major components
 - **Presentation layer:** Camera, UI, prompts, interaction feedback, queues, and shift review.
 - **Input and interaction layer:** Player gestures, dialogue choices, access checks, equipment use, and radio controls.
 - **Simulation layer:** NPC movement, perception, intent, navigation, crowd behavior, and venue state.
 - **Rules layer:** Access policy, escalation policy, prohibited items, response thresholds, and venue configuration.
 - **Incident layer:** Incident lifecycle, evidence, radio reports, consequences, reputation, and review.
 - **Content layer:** Venue definitions, NPC profiles, dialogue, events, visual/audio assets, and shift schedules.
 #### Level 2: Key components
 - `ShiftCoordinator` starts, advances, and ends a shift.
 - `VenueScenario` provides venue rules, locations, event pools, and access policies.
 - `NPCController` manages an NPC’s intent, movement, compliance, and reaction.
 - `InteractionSystem` resolves gestures, dialogue, warnings, and physical positioning.
 - `AccessVerifier` evaluates recognition, wristbands, IDs, tickets, credentials, and guest lists.
 - `EscalationManager` tracks the current response level and available actions.
 - `RadioSystem` receives reports and schedules security or emergency responses.
 - `IncidentRecorder` stores actions, observations, evidence, and outcomes.
 - `ReputationEvaluator` converts incidents and shift outcomes into performance feedback.
 - `CrowdSystem` models queues, attention, congestion, and public reaction.
 - `ShiftReview` presents decisions, consequences, and improvement opportunities.
 ### 6. Runtime View
 #### Routine interaction
 1. An NPC selects or receives an intent such as taking a photo, entering, waiting, or trespassing.
 2. The player observes the NPC and chooses whether to intervene.
 3. A gesture or verbal interaction changes the NPC’s state.
 4. The NPC complies, negotiates, refuses, or escalates.
 5. The rules layer validates access and determines available next actions.
 6. The incident recorder stores the interaction.
 7. Reputation and crowd systems react to the outcome.
 #### Access check
 1. The player stops or receives an approaching person.
 2. The player recognizes the person or inspects a wristband, ID, credential, ticket, or guest-list record.
 3. The access verifier checks the artifact against the venue policy.
 4. The player admits, redirects, holds, or refuses entry.
 5. The decision is recorded for shift review.
 #### Emergency response
 1. NPC behavior crosses the configured immediate-threat threshold.
 2. The player holds and confirms the emergency-radio action.
 3. The player submits a concise report describing location and behavior.
 4. The response system dispatches an appropriate responder.
 5. Crowd, venue, reputation, and incident systems apply consequences.
 6. The shift review evaluates whether the call was justified.
 ### 7. Deployment View
 The initial target is a single-player local game. The expected runtime consists of one client process containing presentation, simulation, rules, content, and persistence for local settings and shift results. No online backend is required for the first prototype.
 Future options include external analytics, cloud saves, or replay sharing, but they are not part of the initial architecture.
 ### 8. Cross-Cutting Concepts
 - **Event-based incident recording:** Important actions emit records consumed by evidence, reputation, and review systems.
 - **Data-driven venue rules:** Access, escalation, equipment, and event differences live in scenario data.
 - **State transitions:** NPCs, incidents, and shifts expose explicit states for debugging and testing.
 - **Accessibility:** Input alternatives should exist for gestures, dialogue, visual alerts, and audio cues.
 - **Safety and proportionality:** The rules layer prevents ordinary noncompliance from automatically becoming a violent encounter.
 - **Determinism where useful:** Scenario tests should be able to use fixed seeds and scripted NPC behavior.
 - **Localization:** Dialogue and prompts should be externalized from logic.
 - **Observability:** Debug overlays should show NPC intent, access status, escalation level, active incidents, and response timers during development.
 ### 9. Architecture Decisions
 Architecture decisions are recorded as ADRs:
 - [ADR-0001: Venue-driven simulation architecture](docs/adr/0001-venue-driven-simulation-architecture.md)
 - [ADR-0002: De-escalation-first escalation model](docs/adr/0002-de-escalation-first-escalation-model.md)
 - [ADR-0003: Explicit access-verification system](docs/adr/0003-explicit-access-verification-system.md)
 - [ADR-0004: Local single-player first](docs/adr/0004-local-single-player-first.md)
 - [ADR-0005: Event-based incident recording](docs/adr/0005-event-based-incident-recording.md)
 - [ADR-0006: Godot 4 with GDScript](docs/adr/0006-godot-4-gdscript.md)
 ### 10. Quality Requirements
 | Requirement | Target |
 | --- | --- |
 | Player comprehension | Players can identify the reason for an access or escalation decision through UI and feedback. |
 | Response proportionality | Routine NPC behavior should be resolvable without emergency response. |
 | Extensibility | A new venue can be added primarily through scenario data and content. |
 | Performance | The target venue should support a believable crowd without harming input or simulation responsiveness. |
 | Testability | Access and escalation rules can be tested independently of presentation. |
 | Accessibility | Core actions are available through clear input alternatives and readable feedback. |
 ### 11. Risks and Technical Debt
 - NPC behavior may feel artificial if traits and reactions are too deterministic.
 - Crowd simulation may become expensive around busy studio or comedy-club entrances.
 - Access verification can become frustrating if the UI does not clearly show what the player is checking.
 - Emergency response can overshadow the core game if it is too powerful or too frequent.
 - Mental-health-crisis scenarios require careful writing, playtesting, and respectful presentation.
 - The choice of engine may affect navigation, crowd scale, tooling, and content authoring.
 ### 12. Glossary
 - **Access artifact:** A wristband, ID, ticket, credential, or other item used to verify entry.
 - **Authorized person:** Someone permitted to enter under the current venue policy.
 - **Door person:** The entrance security worker in The Joke Shop scenario.
 - **Incident:** A recorded interaction or event requiring player judgment.
 - **NPC:** Non-player character.
 - **Scenario:** A venue-specific configuration of rules, content, locations, and events.
 - **Shift:** One playable work period, normally 10–15 minutes.
 - **Simple deterrence:** A low-pressure gesture such as raising a hand, making eye contact, or pointing.
 ## Project Documentation
 - [`PLAN.md`](PLAN.md) — Game design plan and scenario details.
 - [`AGENTS.md`](AGENTS.md) — Development and collaboration workflow.
 - [`TODO.md`](TODO.md) — Active checkbox task list, when created.
 - [`DONE.md`](DONE.md) — Completed task sections, when created.
 - [`MEMORY.md`](MEMORY.md) — Persistent session notes, when created.
 - [`docs/adr/`](docs/adr/) — Architecture Decision Records.
 ## Development Status
 The project is in the pre-prototype stage: the design and architecture are documented, Godot 4 is the selected engine, and the next milestone is to create a minimal venue prototype implementing one complete NPC interaction from observation through shift review.
 ## Development Workflow
 Follow [`AGENTS.md`](AGENTS.md): inspect the repository first, record work as checkbox tasks in `TODO.md`, move completed sections to `DONE.md`, update `MEMORY.md` with durable context, and keep this README synchronized with setup and architecture changes.
@@ -0,0 +1,34 @@
 # ADR-0001: Venue-driven simulation architecture
 - **Status:** Accepted
 - **Date:** TBD
 ## Context
 The game is planned to include multiple venues with different access rules, equipment, crowd patterns, NPC mixes, and scenario events. The Hollywood Boulevard building, The Joke Shop comedy club, and the late-night TV studio share core interaction and escalation mechanics but differ in their policies and content.
 Hard-coding each venue into the simulation would make new scenarios expensive to create and would encourage inconsistent behavior between venues.
 ## Decision
 Use a shared simulation core with venue-driven configuration and content. A `VenueScenario` supplies locations, access policies, equipment, NPC pools, dialogue, schedules, event pools, and escalation constraints. Shared systems handle movement, interactions, access verification, incidents, reputation, crowds, and shift review.
 ## Consequences
 ### Positive
 - New venues can reuse tested systems.
 - Venue rules remain visible and easier to review.
 - Scenarios can be tested independently of rendering.
 - Different venues can share NPC types while changing their context.
 ### Negative
 - The data model must be designed carefully.
 - Some venue-specific behavior may need extension hooks.
 - Content authoring tools or validation will become important as the number of venues grows.
 ## Alternatives considered
 - **One custom implementation per venue:** Rejected because it duplicates logic and increases maintenance cost.
 - **One universal ruleset:** Rejected because ID checks, wristbands, wand screening, and studio credentials have materially different behavior.
@@ -0,0 +1,43 @@
 # ADR-0002: De-escalation-first escalation model
 - **Status:** Accepted
 - **Date:** TBD
 ## Context
 The game involves security work, access denial, rare violent threats, and an emergency responder with greater authority. A design focused on attacking NPCs would undermine the intended workplace-simulation experience and make ordinary public behavior indistinguishable from danger.
 The plan explicitly calls for observation, gestures, dialogue, formal warnings, positioning, assistance, and emergency response in increasing levels.
 ## Decision
 Represent escalation as explicit levels from 0 through 5:
 0. Observation
 1. Simple deterrence and polite direction
 2. Formal warning
 3. Blocking and physical positioning
 4. Radio for security assistance
 5. Emergency response
 The player is rewarded for selecting the lowest effective level. Emergency assistance is reserved for immediate threats and is evaluated after the incident. Physical force is not a default interaction.
 ## Consequences
 ### Positive
 - Reinforces judgment and communication as the main skills.
 - Makes simple actions, including raising a hand, mechanically meaningful.
 - Gives the player clear feedback about proportionality.
 - Keeps emergency response rare and consequential.
 ### Negative
 - NPC reactions and threat assessment require more nuanced modeling.
 - Players may need clear feedback to understand why an escalation was or was not justified.
 - Designing fair edge cases will require playtesting.
 ## Alternatives considered
 - **Combat-first design:** Rejected because it conflicts with the game’s core premise.
 - **Binary allow/deny interaction:** Rejected because it removes the interesting judgment between harmless behavior, refusal, and immediate danger.
@@ -0,0 +1,44 @@
 # ADR-0003: Explicit access-verification system
 - **Status:** Accepted
 - **Date:** TBD
 ## Context
 Authorized people may need to enter the building, while unauthorized people may look similar or behave confidently. The plan requires the guard to recognize a person or inspect a wristband. Other venues add IDs, tickets, credentials, guest lists, and handheld wand screening.
 If access is decided only by NPC type or scripted identity, the player does not perform meaningful security work.
 ## Decision
 Make access verification a dedicated system. It evaluates one or more access artifacts and venue policy, including:
 - Personal recognition
 - Wristband color, pattern, date, or event marking
 - Government-issued ID and age requirement
 - Ticket, reservation, or guest-list status
 - Staff, performer, or production credential
 - Prohibited-item and wand-screening results
 The player must inspect or select the relevant evidence. Valid, expired, counterfeit, mismatched, missing, and ambiguous artifacts are distinct outcomes. The system records both the evidence and the player’s decision for shift review.
 ## Consequences
 ### Positive
 - Makes admission decisions an active gameplay mechanic.
 - Supports all planned venues without changing the core interaction model.
 - Creates fair reasons for both admission and refusal.
 - Enables feedback when the player denies an authorized person or admits an unauthorized one.
 ### Negative
 - The UI must present enough information without becoming tedious.
 - Content creators need tools for generating believable artifact variations.
 - False positives and ambiguous cases require careful balancing.
 ## Alternatives considered
 - **Automatic recognition only:** Rejected because it removes verification gameplay.
 - **Appearance-based access:** Rejected because it is unreliable and conflicts with the intended design.
 - **One universal credential:** Rejected because venues have different admission policies.
@@ -0,0 +1,32 @@
 # ADR-0004: Local single-player first
 - **Status:** Accepted
 - **Date:** TBD
 ## Context
 The project is at the planning stage and no engine, backend, or multiplayer requirement has been established. The core experience is a single guard making decisions during a short shift. Early development needs fast iteration on rules, NPC behavior, UI, and scenario content.
 ## Decision
 Build the first playable version as a local single-player game. Keep simulation, presentation, content, and shift results in one client process. Do not require an online service or multiplayer layer for the initial prototype.
 ## Consequences
 ### Positive
 - Reduces infrastructure and deployment complexity.
 - Makes deterministic scenario testing easier.
 - Allows the team to validate the core game loop before committing to networking.
 - Keeps the first vertical slice small.
 ### Negative
 - Multiplayer and online analytics are deferred.
 - Some future features may require refactoring if they depend on network authority.
 - Local persistence and platform support still need to be designed later.
 ## Alternatives considered
 - **Multiplayer-first:** Rejected because it adds complexity before the single-player loop is proven.
 - **Backend-first simulation:** Rejected because the planned game does not currently require a service or shared world.
@@ -0,0 +1,37 @@
 # ADR-0005: Event-based incident recording
 - **Status:** Accepted
 - **Date:** TBD
 ## Context
 The game needs body-camera evidence, radio reports, crowd reactions, reputation scoring, and a shift review. These systems all need to understand what happened during an interaction, including the NPC’s behavior, the player’s response, access evidence, escalation level, and final outcome.
 If each system observes gameplay independently, scoring can become inconsistent and replaying or reviewing an incident becomes difficult.
 ## Decision
 Record important gameplay actions as structured incident events. Events should include an incident identifier, timestamp or simulation step, actor, observed behavior, player action, evidence, escalation level, response, and outcome where applicable.
 The incident recorder is the source for body-camera review, reputation evaluation, crowd consequences, radio accountability, and shift summaries. Presentation may display events, but it does not own the authoritative incident history.
 ## Consequences
 ### Positive
 - Creates consistent scoring and review across venues.
 - Makes debugging and automated tests easier.
 - Supports future replay, analytics, or accessibility features.
 - Keeps UI concerns separate from game rules.
 ### Negative
 - Requires a stable event schema.
 - Event volume must be managed during busy crowd scenes.
 - Historical data may need migration when the schema changes.
 ## Alternatives considered
 - **Each subsystem tracks its own state:** Rejected because it risks contradictory outcomes.
 - **Only store final shift scores:** Rejected because it cannot explain or review individual decisions.
 - **Record raw input only:** Rejected because raw input does not capture the interpreted situation or policy outcome.
@@ -0,0 +1,34 @@
 # ADR-0006: Godot 4 with GDScript
 - **Status:** Accepted
 - **Date:** TBD
 ## Context
 The project needs a game engine and programming language before implementation can begin. The game is a local single-player workplace simulation with navigation, crowds, NPC behavior, UI for access checks and dialogue, audio, and shift-scoring systems. The project benefits from fast iteration, low cost, and the ability to run rules and scenario tests headlessly.
 ## Decision
 Use the Godot Engine 4.x with GDScript for gameplay logic. Model the venue-driven architecture as nodes, scenes, and custom `Resource` types. Use Godot's navigation, UI, audio, and headless mode. Test with the GUT framework.
 ## Consequences
 ### Positive
 - Free and open-source license with no per-seat or royalty cost.
 - Built-in 3D rendering, navigation, animation, UI, and audio reduce external dependencies.
 - GDScript is tightly integrated and fast to iterate on.
 - Headless mode supports deterministic, GUI-free automated tests.
 - Custom resources make scenario data editable and data-driven.
 ### Negative
 - GDScript is less suited to very large, performance-critical systems than some alternatives.
 - The team commits to Godot's editor workflow and version cadence.
 - C# remains an option only if future needs justify adding a toolchain.
 ## Alternatives considered
 - **Unity with C#:** Rejected due to licensing uncertainty and a heavier editor/workflow.
 - **Bevy with Rust:** Rejected because Rust adds friction and iteration time for a prototype team.
 - **Web-based TypeScript (Three.js/Babylon.js):** Rejected because Godot provides more out-of-the-box game systems and simpler desktop export.