gig-line/AGENTS.md

AGENTS.md

Working rules for autonomous agents, AI coding assistants, and contributors. Planned work is tracked in TODO.md; development direction is in ROADMAP.md.

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.
• Active remote repository (origin): https://git.allucanget.biz/zwitschi/gig-line.git. Verify connectivity before use.

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.

Blender skills

.agents/skills/blender-skills/ holds 94 Blender skill packs (MIT, blender-skills 1.3.0). They are agent instructions, not add-ons, and nothing in the pipeline depends on them.

All agents must consult the relevant skill packs before starting a task in that discipline. Each patch section in TODO.md lists its suggested skills; the general mapping is:

• Modeling / procedural assets — blender-modeler, procedural-modeling, geometry-nodes, hard-surface.
• Façades and architecture — archviz, historical-worlds (1920s Hollywood Blvd direction), realistic-style.
• Materials and textures — materials, texture-workflow, lookdev.
• UVs and export — uv-workflow, export-pipeline, unreal-export (verify against the ue_metric_v1 / ue_character_v1 presets in Tools/).
• Collision — collision-proxy (UCX/UHX naming, hulls, simple colliders).
• Scene assembly / optimization — scene-assembly, asset-optimization, lod-pipeline.
• Review and QA — qa-review, references (reference-image-match and visual-match checklists), camera-cinematography (matching reference camera angles).

Caveat: the skill packs assume MCP-driven interactive Blender. This project runs Blender headless via scripts in Tools/ — use the skills as method guides (checklists, naming conventions, proportions, validation steps), not for their MCP tooling. The headless scripts remain the execution path.

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 committed so reviewers see exactly what the build rendered (.gitignore does not exclude them). Keep them in sync with this README: drop retired shots in the same change.
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 and TODO

The two files have separate roles:

• TODO.md is the single, central task list for all agents: checkbox items, progress marks, and active-section ownership. Put all planned actionable work and follow-ups there. Do not create parallel task lists elsewhere.
• ROADMAP.md holds the development plan: milestone goals, scope, decisions, and release gates for each version. It is a planning document and contains no checkbox items. Read it for future direction; record scope changes there as prose, and record the resulting tasks in TODO.md.

Rules for TODO.md:

• Mark items open (- [ ]), in progress/active (- [-] or - [~]), or done (- [x]). Keep the marks accurate.
• 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 the items you are working on - [-] or - [~].
• Existing in-progress marks can describe unfinished work, not necessarily a live session; use the active heading and assignment details to identify current ownership.
• Each version is a ## heading; task groups are ### headings with - [ ] steps.
• When all steps in a version section are done: write a short descriptive entry to CHANGELOG.md, remove the version section from TODO.md, and leave its goal in ROADMAP.md.
• Release checks for each version are listed at the end of its TODO.md section; Docs/release-checks.md defines the checks themselves. If a check fails, do not tag the release; open a patch task in TODO.md and report the failing check in CHANGELOG.md.
• Finish each milestone's release checks before expanding scope. Cut map size and simulation complexity before compromising the core walking/driving experience.

Git workflow

Every agent works on a dedicated git branch. Never commit work directly to main (except the coordinator's integration merges).

Before starting any task:

1. Scan TODO.md and pick a task — a level-three (###) section — to work on. Use ROADMAP.md for the goal and scope of the version you are working in. Prefer sections that are already active (they may be yours) or open items in sections that are not owned by another agent. Check the active heading and assignment details to identify ownership.
2. Create a branch for that task from the current main: git checkout -b <topic>-<version> (e.g. git checkout -b facade-hero-0.1.4). One branch per task; do not stack unrelated tasks on one branch.
3. Record the active branch in the heading of the section you are working on in TODO.md: append - active - <sessionId> (and, if useful, the branch name) to the level-three heading. This is the only way other agents can see that work is in progress on this section.
4. Commit changes often on that branch — small, focused commits with clear messages. Do not accumulate large uncommitted changes.
5. Push to remote when a checklist item is done — each completed - [x] item in that section should be committed and pushed. This keeps the remote state visible and makes progress recoverable.
6. When the section is complete, report the branch, changes, checks, and unresolved issues to the coordinator for integration (see Parallel agent workflow below). Do not merge into main yourself unless authorized.

Branch hygiene:

• Branch from the current main revision, not from a stale local checkout.
• Keep TODO.md checkbox updates on your branch — they are part of the work.
• If a task needs a different camera angle, or affects visual review, follow the Visual review section before pushing.
• If a task is abandoned, remove the - active - <sessionId> suffix from the heading in TODO.md and leave the branch for the coordinator to clean up.

Parallel agent workflow

• Designate one coordinator to serialize assignments, updates to the shared TODO.md, and integration into main. Agree on task and file or asset ownership before work starts; avoid assigning the same section or binary asset to multiple agents at once.
• The coordinator records the session ID, branch name, and owned files or assets alongside the active TODO.md section on the shared main coordination copy. Publish and synchronize this state through the remote when agents use different machines. Branch-local changes are not visible to other worktrees until integrated; TODO.md is not an atomic lock.
• For parallel implementation, use a separate branch and Git worktree per agent, based on the agreed main revision. Do not switch branches in a directory another agent is using. Create branches, commits, pushes, and merges only when authorized; never overwrite another agent's uncommitted work.
• Keep ignored local references, generated files, build outputs, and Unreal editor processes in mind: worktrees do not automatically share ignored files, and shared output paths or concurrent editors can collide. Arrange required inputs and isolated outputs before running tools.
• Blender and Unreal binary assets cannot be meaningfully merged like text. Give each asset one owner; use Git LFS locks when supported by the remote, but do not assume locking is available.
• When work is ready, report the branch, changes, checks, unresolved issues, and relevant memory findings to the coordinator. Review and integrate branches into main one at a time, reconcile TODO.md and memory changes, and update ownership and status. Follow the visual review and user-approval requirements before marking visual work done.

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 TODO.md item, such as a workaround, an assumption, or a rejected approach and why. Record scope or direction decisions in ROADMAP.md as prose.

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 task list: planned work stays in TODO.md, and development direction stays in ROADMAP.md.

Memory edits on an agent's branch are not shared live. Communicate important findings to the coordinator during work and reconcile them into the shared main copy when integrating.