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