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 reference photography for manual façade work, ignore licensing for internal development use and do not commit reference images to the repository.
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.

## Visual review (screenshots)

Any change that affects the game's appearance — meshes, materials, lighting, levels, character, camera, post-processing — must be rendered for human review:

1. Run `Tools/render_screenshots.sh` (rebuilds `Game/GigLine/Content/Test/ReviewMap.umap` from current content, runs the game on it, captures the fixed camera list, copies the PNGs into `Screenshots/`).
2. Update `Screenshots/README.md`: one row per screenshot with what it shows and an approval state; describe any new shots or scene changes in the same change.
3. The PNGs are **never committed** — `.gitignore` keeps only `Screenshots/README.md`. Review happens on disk.
4. Wait for the user's approval before treating a visual change as done; record approval by ticking the table in `Screenshots/README.md`.

New content that needs a different camera angle gets a new entry in the shot list in `Tools/ue_build_review_map.py`.

## Roadmap

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

- `ROADMAP.md` is the single, central TODO and progress list for all agents. Put planned work and actionable follow-ups there rather than creating parallel task lists.
- When working on a level-three (`###`) section, append ` - active - <sessionId>` to its heading, using your current session ID. Remove the suffix when you stop working on that section. Mark checklist items currently being worked on `- [-]` or `- [~]`; update the marks as their status changes.
- Planned work is listed as checkbox items in `ROADMAP.md`, marked **open** (`- [ ]`), **in progress/active** (`- [-]` or `- [~]`), or **done** (`- [x]`). Keep the marks accurate.

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

## Memory

**[MEMORY.md](MEMORY.md)** is shared session memory for agents and collaborators. Write to it whenever you:

- discover a fact about the environment, a tool, or a data source that cost time to establish;
- hit a gotcha, trap, or surprising failure mode, and what actually caused it;
- find or fix a bug, and how it was found so it can be found again;
- make a decision that does not fit a `ROADMAP.md` checkbox, such as a workaround, an assumption, or a rejected approach and why.

Keep entries short and dated, with the evidence: the command, the log line, or the file path. Anything that belongs in a formal document (setup steps, tool versions, licensing) goes in `Docs/` as well — memory is for coordination, not a replacement for the record. Do not let `MEMORY.md` become a second roadmap: planned work stays in `ROADMAP.md`.