zwitschi
2ba40f3578
Group the top-level docs into docs/project, docs/design, docs/assets and docs/process, each with its own README index. Delete the superseded docs/screens/head-review page and sheets. Rewrite every markdown link, absolute docs path and tool/test reference to the new locations, fix the pre-existing broken anchors and remove the dead Joke Shop photo-board link. check_docs OK, Python tooling 167/167.
218 lines
16 KiB
Markdown
218 lines
16 KiB
Markdown
# Gig Line
|
||
|
||
Gig 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.
|
||
|
||
## Development Priorities
|
||
|
||
The active planning order lives in [`PLAN.md`](PLAN.md) (gap analysis and release roadmap), [`TODO.md`](TODO.md) (executable checklist) and [`AGENTS.md`](AGENTS.md):
|
||
|
||
1. **`0.9.9`–`0.9.12` patches** — finish the Quaternius NPC base on the accepted 62-joint runtime, roll it out to the 12 roles, close the scheduled venue/prop/lighting polish, then verify performance, Web and accessibility.
|
||
2. **`0.10.0` minor** — public readiness: external playtests, balance acceptance, legal/storefront/signing decisions, the platform matrix and the documentation/picture lock.
|
||
3. **`0.10.x` → `0.11.0`** — live incident replay, a fourth venue and the localization foundation.
|
||
4. **`0.12.0` → `1.0.0`** — signed storefront builds, a frozen save contract, content complete, release candidates and the stable release.
|
||
|
||
Versions are assigned only when a track's scope is accepted into a release. Every major, minor and patch version requires a changelog entry, a local release build and artifact verification before tagging.
|
||
|
||
## ⬇️ Downloads
|
||
|
||
| Platform | Package |
|
||
| --- | --- |
|
||
| **Windows — installer** | [`gig-line-setup-<ver>.exe`](https://git.allucanget.biz/zwitschi/security-game/releases) · contains all game data, shortcuts + uninstaller |
|
||
| **Windows — portable** | [`gig-line-windows-<ver>.exe`](https://git.allucanget.biz/zwitschi/security-game/releases) · 64-bit, no install needed |
|
||
| **Linux — AppImage** | [`gig-line-<ver>-x86_64.AppImage`](https://git.allucanget.biz/zwitschi/security-game/releases) · single file, `chmod +x` and run |
|
||
| **Linux — portable** | [`gig-line-linux-<ver>.x86_64`](https://git.allucanget.biz/zwitschi/security-game/releases) · 64-bit, `chmod +x` and run |
|
||
| **macOS** | [`gig-line-macos-<ver>.zip`](https://git.allucanget.biz/zwitschi/security-game/releases) · unsigned build, quarantine note below |
|
||
| **Web (browser)** | [`gig-line-web-<ver>.zip`](https://git.allucanget.biz/zwitschi/security-game/releases) · unzip and serve the folder from any static host (no special headers) |
|
||
| **Desktop HQ** | [`gig-line-desktop-hq-<ver>.zip`](https://git.allucanget.biz/zwitschi/security-game/releases) · optional Forward+ build with volumetric fog/SDFGI/flashlight; requires a Vulkan-capable GPU/driver |
|
||
|
||
**All releases:** <https://git.allucanget.biz/zwitschi/security-game/releases>
|
||
|
||
> Downloads are public (no sign-in required) since the host's instance-wide
|
||
> `REQUIRE_SIGNIN_VIEW` was disabled on 2026-10-31.
|
||
>
|
||
> **Latest published: v0.9.9** — the character-roster patch: all twelve NPCs now
|
||
> use the CC0 Quaternius base with the five tint slots, role gear and baked maps.
|
||
> Superseded: v0.9.8, the character-development patch: the
|
||
> 12-character library, realistic face pass, four crowd-variety variants and the
|
||
> wrist/hip/knee deformation fixes. Previous 0.9.x patches added the
|
||
> Hollywood/Joke Shop maps, UI/accessibility polish, NPC visual optimization,
|
||
> texture/material refinement and integration checkpoint.
|
||
>
|
||
> **Current source: v0.9.8** — tagged from the same commit. The 0.10.0
|
||
> development track remains gated on the Quaternius NPC rollout, local-map work
|
||
> and release approvals.
|
||
> Releases are built automatically when a `vX.Y.Z` tag is pushed
|
||
> (see [`docs/process/RELEASING.md`](docs/process/RELEASING.md)); manual builds use
|
||
> `./tools/build_releases.sh`. Installer/AppImage packaging runs in the same pipeline
|
||
> (NSIS + appimagetool) and uploads with the portable binaries.
|
||
>
|
||
> macOS builds are unsigned: right-click → Open, or clear the quarantine with
|
||
> `xattr -dr com.apple.quarantine gig-line-macos.zip`. Build instructions and
|
||
> the release pipeline live in [`docs/process/RELEASING.md`](docs/process/RELEASING.md).
|
||
|
||
If you are here to develop or test locally instead of downloading, jump to
|
||
[Setup and Run](#setup-and-run) below.
|
||
|
||
The project is under active development. The design and architecture are documented, and a playable prototype vertical slice exists (Godot 4 + GDScript): a stylized El Capitan Entertainment Centre block, a first-person guard, simulated NPCs with intents and reactions, the six-level escalation model, access inspection and admission decisions, radio calls with credibility checks, reputation, crowd mood, and an end-of-shift review.
|
||
|
||
## Screenshots
|
||
|
||
Every capture is rendered from the current build by [`tools/check_screenshots.sh`](tools/check_screenshots.sh)
|
||
(21 captures, compared against the runtime art). The full gallery, including every UI state, is in
|
||
[`docs/screenshots/`](docs/screenshots/README.md).
|
||
|
||
### Venues
|
||
|
||
| | |
|
||
| --- | --- |
|
||
|  | **Hollywood Boulevard — day.** The El Capitan Entertainment Centre block: six Ionic columns, Masonic parapet, event banners, eight stone steps and the Walk of Fame terrazzo. |
|
||
|  | **Hollywood Boulevard — late.** Sconces pool on the limestone, street lamps light the boulevard and the skyline fades into night haze. |
|
||
|  | **Night patrol.** A tight flashlight spot picks out the door and the person in front of it; movement and awareness change at night. |
|
||
|  | **The Joke Shop.** A black Sunset Strip club under its signature-covered canopy, circular blade sign, red curtains and the dry hillside behind. |
|
||
|  | **TV Studio arrival.** Stone facade, bulb canopy, black car and crowd barriers for a late celebrity arrival. |
|
||
|
||
### Interaction and systems
|
||
|
||
| | |
|
||
| --- | --- |
|
||
|  | **Focus and targeting.** The cone focus ring, name tag and target chip; `Tab`/wheel cycles nearby people without aiming. |
|
||
|  | **Access inspection.** A venue-correct wristband check with evidence shown before the admit/refuse decision. |
|
||
|  | **Radio report.** Security assistance with location, behaviour and what was actually seen. |
|
||
|  | **Wand screening.** A false alarm on keys: ask the guest to identify the item before choosing a response. |
|
||
|  | **Escalation.** Level 3 blocking with the shape meter, body camera armed and the reaction log. |
|
||
|  | **Body-camera timeline.** Every recorded event, step by step, in the shift review. |
|
||
|  | **Precision walk.** Half-speed close work on the steps, with the HUD state chip visible. |
|
||
|
||
### Shell and UI
|
||
|
||
| | |
|
||
| --- | --- |
|
||
|  | **Venue menu.** Day and night rows for Hollywood, the Joke Shop and the TV Studio, campaign continue and review links. |
|
||
|  | **Settings.** Difficulty, volumes, HUD scale, reduce motion, captions and key/button remapping, all persisted. |
|
||
|  | **Shift review.** Grade, policy outcome, incidents, responder results and campaign Continue. |
|
||
|  | **Action wheel.** De-escalation first: stop, look, point, no, ask, inspect, warn, block, reason, recognize, radio. |
|
||
|
||
### 3D asset progress
|
||
|
||
The character roster is built from the CC0 Quaternius bases (ADR-0017/ADR-0018) and audited
|
||
before use; the procedural library and the MakeHuman head stay as the tested fallback. The
|
||
sheets below show the
|
||
current library and will be replaced after the 12 × 6 baseline review.
|
||
|
||
| | |
|
||
| --- | --- |
|
||
|  | **Character library.** Twelve role-dressed variants (4.5–6.4k triangles each) on three CC0 Quaternius bases, with five tint slots, attach-point gear and baked maps. |
|
||
|  | **Street and venue props.** Twenty library props with colliders, navigation avoidance and colour atlases. |
|
||
|  | **Neutral baseline.** 8 characters × 6 views (front, three-quarter, profile, back, full body, crowd) used for the 0.9.4 pass and the current re-evaluation. |
|
||
|  | **Texture refinement.** 128 → 256 px NPC maps and a 4× fabric weave, shown before/after on the same camera. |
|
||
|  | **Crowd variety prototypes.** Four approved looks (bun/slim, bald/broad, coat/umbrella, hood/cup) queued for the roster build. |
|
||
|
||
More sheets and the review criteria are in [`docs/blender_previews/`](docs/blender_previews/README.md)
|
||
and [`docs/assets/3d-model-review.md`](docs/assets/3d-model-review.md).
|
||
|
||
## Game Overview
|
||
|
||
A typical shift lasts 10–15 minutes: watch the entrance and sidewalk, judge why
|
||
each person is approaching, verify access with recognition, wristbands, IDs,
|
||
tickets or credentials, and escalate only when necessary. The game rewards calm
|
||
resolution over force. The venue menu splits Hollywood Boulevard into Day and
|
||
Night rows; the full mechanics — the three venues, the six-level
|
||
escalation model, and the core systems — are in
|
||
[`docs/design/gameplay.md`](docs/design/gameplay.md); the design rationale lives in
|
||
[`PLAN.md`](PLAN.md).
|
||
|
||
## Architecture
|
||
|
||
A venue-driven simulation: shared systems (movement, perception, interaction,
|
||
access verification, escalation, radio, crowd, reputation, evidence, shift
|
||
review) driven by per-venue scenario data, on Godot 4 + GDScript. The full
|
||
arc42-style document is [`docs/project/architecture.md`](docs/project/architecture.md);
|
||
decisions are recorded as ADRs in [`docs/adr/`](docs/adr).
|
||
|
||
## Tech Stack
|
||
|
||
- **Engine:** Godot 4.7.2 · **Language:** GDScript
|
||
- **NPCs:** CC0 Quaternius skinned library (`assets/models/blender/`, ADR-0018) with a tested procedural fallback; lightweight FSMs on `NpcProfile`
|
||
- **World:** procedural `WorldBuilder` + generated prop models
|
||
- **Art:** v2 skyline/surface textures in `assets/textures/ai/game_ready/v2/picks/`; UI/scene art in `assets/images/`
|
||
- **Asset tooling:** `asset_pipeline.py`, `model_pipeline.py`, `npc_pipeline.py`, `blender_assets.py`, `scene_concepts.py`, `screen_designs.py`, `check_screenshots.sh`
|
||
- **Testing:** custom headless runner (`src/test/test_runner.gd`)
|
||
- **Targets:** Windows, Linux, macOS, Web
|
||
|
||
The asset pipelines, model tools, and screenshot gates are documented in
|
||
[`docs/assets/asset-tooling.md`](docs/assets/asset-tooling.md).
|
||
|
||
## Setup and Run
|
||
|
||
```bash
|
||
python3 -m pip install -r requirements-tools.txt
|
||
|
||
godot --editor --path . # open in the editor
|
||
godot --path . # run the game
|
||
godot --headless --path . --script res://src/test/test_runner.gd # run all tests
|
||
```
|
||
|
||
Full setup, every run/test/smoke command, and the controls table are in
|
||
[`docs/process/getting-started.md`](docs/process/getting-started.md).
|
||
|
||
## Project Documentation
|
||
|
||
- [`PLAN.md`](PLAN.md) — Game design plan, development priorities and scenario details.
|
||
- [`TODO.md`](TODO.md) — Priority-ordered tasks: character and local-map development, release milestones, and future work.
|
||
- [`docs/README.md`](docs/README.md) — Documentation index, current priorities and visual previews.
|
||
- [`docs/assets/npc-model-sourcing.md`](docs/assets/npc-model-sourcing.md) — Character-source evaluation, licence rules and the character-development plan.
|
||
- [`docs/assets/makehuman-head-review.md`](docs/assets/makehuman-head-review.md) — Local MakeHuman head prototype, provenance and review verdict.
|
||
- [`AGENTS.md`](AGENTS.md) — Development, commit, build and collaboration workflow.
|
||
- [`DONE.md`](DONE.md) — Completed task sections.
|
||
- [`MEMORY.md`](MEMORY.md) — Persistent session notes.
|
||
- [`CHANGELOG.md`](CHANGELOG.md) — User-facing changes by version.
|
||
- [`docs/project/architecture.md`](docs/project/architecture.md) — arc42-style architecture documentation.
|
||
- [`docs/design/gameplay.md`](docs/design/gameplay.md) — Gameplay systems, venues, and the escalation model.
|
||
- [`docs/design/venues.md`](docs/design/venues.md) — Real-site references, game mapping and limitations for Hollywood, the Joke Shop and the TV Studio.
|
||
- [`docs/assets/asset-tooling.md`](docs/assets/asset-tooling.md) — Asset pipelines, model tools, and screenshot gates.
|
||
- [`tools/README.md`](tools/README.md) — Tool inventory, categories, test commands and AI-skill evaluation.
|
||
- [`.agents/skills/gig-line-blender-asset-contract`](.agents/skills/gig-line-blender-asset-contract/SKILL.md) — tracked AI skill for Blender/NPC/gear asset work.
|
||
- [`.agents/skills/gig-line-release-qa`](.agents/skills/gig-line-release-qa/SKILL.md) — tracked AI skill for release and visual-QA work.
|
||
- [`docs/process/getting-started.md`](docs/process/getting-started.md) — Setup, run/test commands, and controls.
|
||
- [`docs/project/development-status.md`](docs/project/development-status.md) — Implemented features and what's next.
|
||
- [`docs/design/accessibility.md`](docs/design/accessibility.md) — Accessibility features, known gaps and statement.
|
||
- [`docs/design/known-limitations.md`](docs/design/known-limitations.md) — Release-candidate blockers and accepted limitations.
|
||
- [`docs/process/release-qa.md`](docs/process/release-qa.md) — Manual smoke checklist and release-candidate balance protocol.
|
||
- [`CREDITS.md`](CREDITS.md) — Credits, AI/reference provenance and licensing notes.
|
||
- [`PRIVACY.md`](PRIVACY.md) — Local-only data, save files and development API use.
|
||
- [`docs/assets/blender-assets.md`](docs/assets/blender-assets.md) — Blender asset library: characters, gear, props, attach points.
|
||
- [`docs/assets/npc-model-sourcing.md`](docs/assets/npc-model-sourcing.md) — character sources, the shipped roster table and the build steps; 0.9.5 texture comparison is in [`docs/blender_previews/sheet_texture_refinement_0.9.5.jpg`](docs/blender_previews/sheet_texture_refinement_0.9.5.jpg).
|
||
- [`docs/adr/`](docs/adr) — Architecture Decision Records.
|
||
|
||
## Development Status
|
||
|
||
v0.9.8 is the current source version: the character-development patch with the
|
||
12-character library, realistic face and crowd variants, pose/deformation fixes
|
||
and save-migration/release hardening. It sits on the 0.9.6 integration
|
||
checkpoint, 0.9.5 texture refinement, 0.9.4 NPC visual optimization, 0.9.3
|
||
UI/accessibility polish, 0.9.2 Hollywood/Joke Shop maps and the 0.9.x engine
|
||
baseline. The active work is the `0.9.9`–`0.9.12` patch line (Quaternius NPC
|
||
base, roster, venue/asset polish, performance) followed by the `0.10.0`
|
||
public-readiness minor. See
|
||
[`docs/project/development-status.md`](docs/project/development-status.md) for the implemented list
|
||
and [`TODO.md`](TODO.md) for the priority-ordered roadmap. Manual verification uses
|
||
[`docs/process/release-qa.md`](docs/process/release-qa.md).
|
||
|
||
## Credits, Privacy and Accessibility
|
||
|
||
Gig Line is a local-only single-player game: there is no runtime telemetry or
|
||
network service, and saves stay in Godot's local `user://` folder. The
|
||
body-camera overlay is simulated. Asset provenance, AI-assisted image usage and
|
||
credits are recorded in [`CREDITS.md`](CREDITS.md); the local-data policy is in
|
||
[`PRIVACY.md`](PRIVACY.md); accessibility features and gaps are in
|
||
[`docs/design/accessibility.md`](docs/design/accessibility.md); and release-candidate blockers
|
||
are listed in [`docs/design/known-limitations.md`](docs/design/known-limitations.md).
|
||
|
||
## 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.
|