zwitschi/gig-line
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
c11cb4caa4e950fc12b641b99f168f280c8a147a
gig-line/AGENTS.md
T
zwitschi 386d4bee78 geo: one tool directory, one unit boundary, per-asset provenance 
Geo/tools/ is now every geographic script, with Geo/README.md documenting each
one; the Blender-side builders moved beside their outputs in Art/blender/*/ and
import their helpers from Geo/tools/osm_common.py.

That module gains to_unreal_local() and to_blender_local(): the only place in the
repository that multiplies metres by 100, so a second silent scale cannot be
introduced. block_height_report.py adds height provenance for the block — 3 of
15 buildings have no height data and render at a placeholder 6.4 m.
asset_metadata.py writes and audits <asset>.geo.json sidecars; four now exist
(hero-facade, terrain, street, blockout) and the audit recomputes each centre from
the origin, failing anything that disagrees.
2026-11-07 12:28:26 +01:00

127 lines
10 KiB
Markdown
Raw Blame History

# 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.
- 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.
## 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.
- 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 (`[-]` 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`.
## Parallel agent workflow
- Designate one coordinator to serialize assignments, updates to the shared roadmap, 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 roadmap section and items 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; the roadmap 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 roadmap and memory changes, and update ownership and status. Follow the visual review and user-approval requirements before marking visual work done.
## 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`.
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.
Reference in new issue View Git Blame Copy Permalink