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.

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