gig-line/AGENTS.md

# AGENTS.md

Instructions and living roadmap for autonomous agents, AI coding assistants, and contributors working on this repository.

## Project Goal

Develop and test on Linux; ship Windows and Linux builds, with Linux as the primary development and CI platform. The game supports walking and driving through a real city.
The initial release is **`0.1.0`**: a walkable exterior demo around **6840 Hollywood Blvd / El Capitan Entertainment Centre**, including buildings on the south side of Hollywood Blvd between Highland Avenue and Orange Drive, plus buildings whose footprint lies within 50 m of the north-side frontage.

- Verify the address, building footprints, and demo boundaries **before** modeling.
- If the address, footprint, or boundary cannot be verified from permitted sources, do not model that structure. Record the unresolved item in `Geo/` with the sources checked and continue with verified structures only.
- Treat similarly named venues as **distinct structures** where source data indicates; do not merge footprints by assumption.
- use available research and reference data in local project `/run/media/system/DATA/Documents/06-games/security-game/`.

## Toolchain

| Tool | Role |
| --- | --- |
| Unreal Engine | Rendering, gameplay, World Partition, Chaos Vehicles |
| Blender | Modeling, UVs, baking, collision meshes, character prep |
| MPFB | Human base meshes; baked materials, deform skeletons |
| QGIS | Geographic cleanup, coordinate conversion, elevation prep |
| Blosm | OSM building/street blockouts in Blender |
| Git + Git LFS | Source control, large assets, tagged releases |

- Pin compatible versions in `Docs/toolchain.md`.
- Validate Blender→Unreal mesh, skeleton, material, and scale transfers **before** producing assets.

## Repository Layout

- `Game/` — Unreal project, configuration, source, game-ready content.
- `Art/` — editable Blender files and original textures.
- `Geo/` — source manifests, permitted geographic data, processing scripts.
- `Tools/` — repeatable import/export helpers.
- `Docs/` — setup, licenses, architecture, release checks.

**Git/LFS rules:**

- Track `.uasset`, `.umap`, `.blend`, and large source binaries with LFS.
- Ignore `Binaries/`, `Intermediate/`, `Saved/`, and Derived Data Cache.
- Never commit Unreal Engine source, credentials, or non-redistributable assets.

## Release Policy

Semantic Versioning: `MAJOR.MINOR.PATCH`.

- Each major milestone → **minor** release (e.g. `0.2.0`, possibly as `0.2.0-alpha.1` first).
- Each release containing only bug fixes, performance changes, documentation, or tuning of existing features → **patch** release (e.g. `0.2.1`). Any new feature, map area, or asset category → **minor** release.
- Patches contain fixes, optimization, docs, or refinements **only** — never new scope.
- Tag as `vX.Y.Z`; maintain `CHANGELOG.md`.
- During `0.x`, document breaking changes and asset migrations.
- `1.0.0` marks the stable, agreed game scope — not completion of a whole city.

## Geographic & Art Pipeline

1. Save a versioned OSM extract; document date, bounds, and source.
2. Acquire separately licensed elevation data for the demo bounds unless the source DEM shows less than 1 m height variation across the demo area; record the decision in `Geo/` metadata.
3. In QGIS, use a suitable local projected CRS (e.g. EPSG:26911) and record a local origin.
4. Import OSM blockouts through Blosm; clean and detail them in Blender.
5. Preserve geographic coordinates in metadata; convert to local Unreal coordinates with explicit meter→centimeter conversion.
6. Export modular buildings, sidewalks, roads, collision, and materials.
7. Use licensed reference photography for manual façade work.
8. Treat OSM as **layout data only** — not authoritative façade, height, or pavement detail.

Always use a consistent scale test, named export presets, and repeatable import settings.

## Licensing & Distribution

- Publish project-owned code under a chosen open-source license.
- Unreal remains proprietary/source-available; this is **not** a fully open-source stack.
- Keep code, art, engine, and geographic-data licensing **separate**.
- Record asset provenance and redistribution permissions in `THIRD_PARTY_NOTICES.md`.
- Verify licenses for every MPFB asset, texture, animation, vehicle, and audio file.
- An asset whose license cannot be verified must not be committed. Record it as unresolved in `THIRD_PARTY_NOTICES.md` and replace it with a redistributable asset before the release.
- Include "© OpenStreetMap contributors" and the appropriate license link; review ODbL obligations for distributed derived databases.
- Do **not** use extracted Google imagery or geometry without explicit applicable rights.
- Keep restricted assets out of the public repository; prefer redistributable replacements.
- Review Epic distribution requirements before publishing builds.

## Roadmap

The living roadmap with per-version task checklists is in **[ROADMAP.md](ROADMAP.md)**.

- Each version is a `##` heading; task groups are `###` headings with `- [ ]` steps (`[-]` in progress, `[x]` done).
- When **all** steps in a version section are done: write a short descriptive entry to `CHANGELOG.md`, then remove the version section from `ROADMAP.md` to keep it concise.
- Finish each milestone's release checks **before** expanding scope. Cut map size and simulation complexity before compromising the core walking/driving experience.
- Define the release checks in `Docs/release-checks.md`. If a check fails, do not tag the release; open a patch task in `ROADMAP.md` and report the failing check in `CHANGELOG.md`.