From eceaff1397e1c813f4e798f0f0863e54e1d8bc46 Mon Sep 17 00:00:00 2001 From: Zwitschi Date: Fri, 6 Nov 2026 21:20:57 +0100 Subject: [PATCH] chore: scaffold repository and record 0.1.0 setup state Create Game/, Art/, Geo/, Tools/, Docs/ with LFS and ignore rules, record the workstation audit, toolchain pins, setup checklist, release checks, and licensing policy. ROADMAP 0.1.0 environment tasks marked to match verified state. --- .gitattributes | 64 +++++++ .gitignore | 38 ++++ AGENTS.md | 87 +++++++++ Art/README.md | 19 ++ CHANGELOG.md | 9 + Docs/build.md | 21 +++ Docs/licensing.md | 30 ++++ Docs/release-checks.md | 44 +++++ Docs/setup.md | 63 +++++++ Docs/toolchain.md | 39 ++++ Game/README.md | 18 ++ Geo/README.md | 35 ++++ PLAN.md | 126 +++++++++++++ README.md | 41 +++++ ROADMAP.md | 398 +++++++++++++++++++++++++++++++++++++++++ THIRD_PARTY_NOTICES.md | 50 ++++++ Tools/README.md | 18 ++ 17 files changed, 1100 insertions(+) create mode 100644 .gitattributes create mode 100644 .gitignore create mode 100644 AGENTS.md create mode 100644 Art/README.md create mode 100644 CHANGELOG.md create mode 100644 Docs/build.md create mode 100644 Docs/licensing.md create mode 100644 Docs/release-checks.md create mode 100644 Docs/setup.md create mode 100644 Docs/toolchain.md create mode 100644 Game/README.md create mode 100644 Geo/README.md create mode 100644 PLAN.md create mode 100644 README.md create mode 100644 ROADMAP.md create mode 100644 THIRD_PARTY_NOTICES.md create mode 100644 Tools/README.md diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..2632989 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,64 @@ +# Text normalisation +* text=auto eol=lf +*.bat text eol=crlf +*.cmd text eol=crlf +*.sh text eol=lf +*.md text eol=lf +*.json text eol=lf +*.uproject text eol=lf +*.cs text eol=lf +*.ini text eol=lf + +# Unreal content and binaries — Git LFS +*.uasset filter=lfs diff=lfs merge=lfs -text +*.umap filter=lfs diff=lfs merge=lfs -text lockable +*.ubulk filter=lfs diff=lfs merge=lfs -text +*.uexp filter=lfs diff=lfs merge=lfs -text +*.upk filter=lfs diff=lfs merge=lfs -text + +# Blender sources — Git LFS, lockable +*.blend filter=lfs diff=lfs merge=lfs -text lockable +*.blend1 filter=lfs diff=lfs merge=lfs -text + +# Interchange and asset formats +*.fbx filter=lfs diff=lfs merge=lfs -text +*.obj filter=lfs diff=lfs merge=lfs -text +*.usd filter=lfs diff=lfs merge=lfs -text +*.usdz filter=lfs diff=lfs merge=lfs -text +*.glb filter=lfs diff=lfs merge=lfs -text + +# Textures +*.png filter=lfs diff=lfs merge=lfs -text +*.jpg filter=lfs diff=lfs merge=lfs -text +*.jpeg filter=lfs diff=lfs merge=lfs -text +*.tga filter=lfs diff=lfs merge=lfs -text +*.tif filter=lfs diff=lfs merge=lfs -text +*.tiff filter=lfs diff=lfs merge=lfs -text +*.psd filter=lfs diff=lfs merge=lfs -text +*.exr filter=lfs diff=lfs merge=lfs -text +*.hdr filter=lfs diff=lfs merge=lfs -text +*.dds filter=lfs diff=lfs merge=lfs -text + +# Audio and video +*.wav filter=lfs diff=lfs merge=lfs -text +*.flac filter=lfs diff=lfs merge=lfs -text +*.ogg filter=lfs diff=lfs merge=lfs -text +*.mp3 filter=lfs diff=lfs merge=lfs -text +*.mp4 filter=lfs diff=lfs merge=lfs -text +*.mov filter=lfs diff=lfs merge=lfs -text + +# Geographic sources +*.osm.pbf filter=lfs diff=lfs merge=lfs -text +*.pbf filter=lfs diff=lfs merge=lfs -text +*.gpkg filter=lfs diff=lfs merge=lfs -text +*.shp filter=lfs diff=lfs merge=lfs -text +*.shx filter=lfs diff=lfs merge=lfs -text +*.dbf filter=lfs diff=lfs merge=lfs -text +*.las filter=lfs diff=lfs merge=lfs -text +*.laz filter=lfs diff=lfs merge=lfs -text +*.dem filter=lfs diff=lfs merge=lfs -text + +# Archives +*.zip filter=lfs diff=lfs merge=lfs -text +*.7z filter=lfs diff=lfs merge=lfs -text +*.tar.gz filter=lfs diff=lfs merge=lfs -text diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..e24c20e --- /dev/null +++ b/.gitignore @@ -0,0 +1,38 @@ +# Unreal Engine generated output — never commit +Binaries/ +DerivedDataCache/ +Intermediate/ +Saved/ +Build/Receipts/ +*.VC.db +*.VC.opendb +*.opensdf +*.sdf +*.suo +*.sln +*.xcodeproj/ +*.xcworkspace/ +.vs/ + +# Engine installations are external to this repository +/Engine/ +/UnrealEngine*/ + +# Blender backups and temp +*.blend1 +*.blend2 + +# Python tooling +__pycache__/ +*.py[cod] +.venv/ +venv/ +.pytest_cache/ +.ruff_cache/ + +# Editors and OS +.idea/ +.vscode/ +.DS_Store +Thumbs.db +*~ diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..215dbe0 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,87 @@ +# 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](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`. diff --git a/Art/README.md b/Art/README.md new file mode 100644 index 0000000..9b70f02 --- /dev/null +++ b/Art/README.md @@ -0,0 +1,19 @@ +# Art + +Editable sources and original textures. Exported, game-ready output goes to `Game/Content/`. + +## Layout (as content arrives) + +| Path | Contents | +| --- | --- | +| `Art/blender/` | `.blend` sources, one file per building or asset family | +| `Art/textures/` | Original texture sources before baking or compression | +| `Art/reference/` | Licensed reference photography, development only — see attribution rules | + +## Rules + +- Every `.blend` saves with a real-world metric scene scale. No exceptions; scale drift is the main source of import defects. +- Named export presets only. Record the preset name and its settings next to the asset that used it. +- Textures enter as a documented source (author, licence, source URL) and are listed in [../THIRD_PARTY_NOTICES.md](../THIRD_PARTY_NOTICES.md). +- Reference photography stays out of the shipped build. It is evidence, not content, and its licences are recorded before it is committed. +- `.blend` files are LFS-tracked and lockable; pull before editing. diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..6850df8 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,9 @@ +# Changelog + +All notable changes to this project are documented here. + +Format: [Keep a Changelog](https://keepachangelog.com/) style, versions follow [Semantic Versioning](https://semver.org/). Entries are added when a version section in `AGENTS.md` is completed. + +## Unreleased + +No completed releases yet. diff --git a/Docs/build.md b/Docs/build.md new file mode 100644 index 0000000..5dc523c --- /dev/null +++ b/Docs/build.md @@ -0,0 +1,21 @@ +# Build + +Fresh-checkout build procedure. To be completed once the pinned engine is installed and a blank project has been packaged — see [setup.md](setup.md). Until then this file records only the constraints that are already known. + +## Constraints + +- Engine installation is external to the repository. Record its path and exact version in [toolchain.md](toolchain.md). +- Build output (`Binaries/`, `Intermediate/`, `Saved/`, `DerivedDataCache/`) is never committed. +- Large content is LFS-tracked, so a fresh clone needs `git lfs install && git lfs pull` before any build. + +## Procedure (placeholder) + +```bash +git clone gig-line && cd gig-line +git lfs install && git lfs pull +# engine path, project generation, build, and packaging commands — fill in after setup +``` + +## Packaged Linux build + +Record here: the packaging command, output path, size, and the controls document path. The packaged build must launch and quit cleanly on the development workstation before `v0.1.0` is tagged. diff --git a/Docs/licensing.md b/Docs/licensing.md new file mode 100644 index 0000000..ba4e07a --- /dev/null +++ b/Docs/licensing.md @@ -0,0 +1,30 @@ +# Licensing + +Licensing is tracked in four separate layers. Do not merge them; each has different obligations. + +| Layer | What it covers | Status | +| --- | --- | --- | +| Project code | `Game/Source`, `Tools/`, `Geo/` scripts | **Open decision** — proposal: MIT. Choose before the first public commit. | +| Project art | Blender sources, baked textures, exported meshes | Project-owned, shipped under the same terms as the code unless a texture says otherwise. | +| Engine | Unreal Engine | Proprietary / source-available. Not redistributable as engine source. Distribution follows Epic's terms. | +| Geographic data | OSM extract, elevation data | ODbL and the elevation provider's own licence. Attribution and share-alike review required before distributing a derived database. | + +## Rules + +1. An asset whose licence cannot be verified does not get committed. Record it as unresolved in [THIRD_PARTY_NOTICES.md](../THIRD_PARTY_NOTICES.md) and replace it with a redistributable asset before the release it would ship in. +2. Reference photography is development evidence, not shipped content. Keep it in the repository only when its licence permits redistribution, and state in the notices that it is not built into the game. +3. OSM is layout data only. Do not treat it as authoritative for façades, heights, or pavement detail, and do not import it as a texture or panorama source. +4. Never use extracted Google imagery, Street View, or geometry. No exception. +5. Attribution: "© OpenStreetMap contributors" with a link to appears in the shipped build's UI (a `0.1.0` release check) and in the notices. +6. Credentials, licence keys, and account tokens never enter the repository. Engine licence acceptance is recorded by date and account email only. + +## Open decisions + +- **Code licence.** MIT is proposed: short, compatible with the assets' separate terms, and no copyleft spill onto art. Decide before publishing the repository. +- **Documentation licence.** Default to the code licence unless a reason appears to separate them. +- **ODbL posture.** Decide whether distributed builds contain a derived geographic database (a modified OSM extract) or only rendered geometry. The answer changes the share-alike obligations for the shipped product. Record the decision here and in the release notes. +- **Reference photography retention.** The El Capitan reference set is CC BY / CC BY-SA / public domain and currently lives in a sibling project. If it is copied here, carry the per-file attribution and the CC BY-SA review note with it. + +## Provenance sources + +Primary record: [THIRD_PARTY_NOTICES.md](../THIRD_PARTY_NOTICES.md). The sibling project at `…/06-games/security-game/docs/screens/refs/hollywood/SIDECAR.md` holds the per-file provenance for the El Capitan block reference photographs and must be carried over verbatim if those files are reused. diff --git a/Docs/release-checks.md b/Docs/release-checks.md new file mode 100644 index 0000000..ae04fd0 --- /dev/null +++ b/Docs/release-checks.md @@ -0,0 +1,44 @@ +# Release checks + +Every version in `ROADMAP.md` ends with release checks. A version is not tagged until all of its checks pass. If a check fails, do not tag; open a patch task in `ROADMAP.md` and report the failing check in `CHANGELOG.md`. + +Record results in the table at the end of this file, with the date, the exact build under test, and the evidence (screenshot, log, or command output). A check without recorded evidence counts as failed. + +## General checks (every release) + +1. **Fresh checkout builds.** Clone into a clean directory, `git lfs pull`, build and package using only the documented external engine installation. No machine-specific paths, no uncommitted steps. +2. **No packaging errors.** The packaged build launches, reaches gameplay, and quits cleanly. Logs contain no missing-asset, missing-map, or shader-compile errors. +3. **Licensing.** Every new asset has provenance in `THIRD_PARTY_NOTICES.md`, or is recorded as unresolved and kept out of the build. +4. **Version discipline.** Patch releases contain fixes, optimisation, docs, or tuning only — no new scope. + +## Performance check + +Measured at 1440p on the development workstation: Bazzite, Ryzen 7 7700X, 64 GB RAM, RTX 5070 Ti 16 GB. + +- Record the quality preset, the exact upscaling state (off, DLSS/TSR/FXAA and mode), and the engine version. +- Report frame rate without frame generation and with frame generation, separately. +- Target: 60 FPS at 1440p without frame generation. +- Capture a frame-time graph over a fixed traversal route, not a single sample. State the route. + +## `0.1.0` checks + +1. Player traverses both the south-side frontage and the north-side frontage of the demo without falling through geometry, including the designated crossing. Walk the route twice: once normally, once with collision debug visualisation enabled. +2. Building placement, street width, sidewalk depth, and site identity match the reference photography. Compare side by side and note every deliberate deviation. "Looks right" is not evidence. +3. No blocking collision, no invisible walls, no gaps at sidewalk/road seams. +4. 60 FPS at 1440p per the performance check above. +5. Fresh checkout builds against the documented external engine installation. +6. Linux build packaged and launched; controls documented in `Docs/` and shown in-game. +7. Geographic attribution is visible in-game: "© OpenStreetMap contributors" with a working licence link. +8. Tag `v0.1.0`, write the `CHANGELOG.md` entry, then remove the completed section from `ROADMAP.md`. + +## Check-record template + +| Version | Check | Result | Evidence | Date | +| --- | --- | --- | --- | --- | +| `0.1.0` | Traversal, both sides | — | — | — | +| `0.1.0` | Placement vs references | — | — | — | +| `0.1.0` | Collision and packaging | — | — | — | +| `0.1.0` | 60 FPS at 1440p | — | — | — | +| `0.1.0` | Fresh checkout build | — | — | — | +| `0.1.0` | Packaged Linux build | — | — | — | +| `0.1.0` | Attribution display | — | — | — | diff --git a/Docs/setup.md b/Docs/setup.md new file mode 100644 index 0000000..5bbdf72 --- /dev/null +++ b/Docs/setup.md @@ -0,0 +1,63 @@ +# Setup + +Ordered procedure for bringing the workstation and the project to a buildable state. Status markers follow `ROADMAP.md`: + +- `[x]` done and verified +- `[-]` started, not finished +- `[ ]` not started + +Anything marked **human step** needs credentials, licence acceptance, or a decision that cannot be automated. Never store Epic credentials, tokens, or licence keys in the repository. + +## 1. System + +- `[-]` Update Bazzite with its supported mechanism. + `ujust update` (or `rpm-ostree upgrade`), then reboot. Deployment `45.20261105` is already staged and needs a reboot to boot. +- `[ ]` Verify the NVIDIA driver and Vulkan from the desktop session. + `nvidia-smi` must name the RTX 5070 Ti and driver `615.78.08`; `vulkaninfo --summary` must list a discrete NVIDIA GPU. These checks cannot be run from an agent shell — see [environment.md](environment.md). +- `[ ]` Install `git-lfs`, `cmake`, `ninja-build`, `clang` as an ostree layer, reboot, then `git lfs install`. + +## 2. Engine acquisition + +- `[ ]` **Human step.** Create an Epic account, accept the Unreal license, and join the Epic Games GitHub organisation if the source route is used. Record the account email and the date of acceptance here; record no credentials. +- `[ ]` **Human step.** Acquire one pinned engine build. Two routes: + - **Launcher build**: install the Linux Epic Games Launcher, download the pinned engine version, install to the DATA volume, and disable auto-update so the pin holds. + - **Source build**: clone the pinned `release` branch from the Epic Games GitHub organisation, then `./Setup.sh`, `./GenerateProjectFiles.sh`, `make -j16`. Budget 120–200 GB and a multi-hour first build on 16 threads. +- `[ ]` Record the exact engine version and build route in [toolchain.md](toolchain.md). +- `[ ]` Validate that the engine editor opens and a blank project runs on Bazzite. Unreal does not support this distribution; record any workarounds. + +## 3. Tooling pins + +- `[x]` Blender 5.2 LTS (Flatpak) and MPFB 2.0.18 recorded. +- `[ ]` Install QGIS (`flatpak install flathub org.qgis.qgis`) and record its version. +- `[ ]` Install Blosm in Blender, record its version, and confirm it loads on Blender 5.2. Fall back to a side-by-side Blender 4.5 LTS only for the blockout step if it does not. +- `[ ]` Confirm the geo tool Python environment (venv with `pyproj`, `GDAL`, `shapely` from the QGIS or distrobox environment) and record it. + +## 4. Project bootstrap + +- `[ ]` Create the C++ Unreal project at `Game/GigLine/GigLine.uproject` with Enhanced Input enabled and Blueprint gameplay enabled. Commit `Config/`, `Source/`, and `GigLine.uproject`; leave `Binaries/`, `Intermediate/`, `Saved/`, and the DDC out of the repository — `.gitignore` already covers them. +- `[ ]` Point the local Derived Data Cache at the DATA volume. Confirm the setting name and section against the pinned engine's documentation rather than copying a config snippet from another version. +- `[ ]` Enable Git LFS integration in the editor before importing content, so large assets are routed to LFS on import rather than on a later re-add. +- `[ ]` Package and launch a blank Linux build from the command line, so the packaging path is proven before any content exists. +- `[ ]` Export one static mesh from Blender with a known metric size and import it into Unreal. Verify the 100× scale conversion (1 m → 100 uu), the pivot, normals, and material assignment. +- `[ ]` Export one MPFB character with baked materials and a deform skeleton and verify it imports with the expected skeleton hierarchy and scale. +- `[ ]` Commit the baseline and write the fresh-checkout build procedure into [build.md](build.md). + +## 5. Repository + +```bash +git clone gig-line +cd gig-line +git lfs install # requires git-lfs; otherwise every LFS-tracked add fails +git lfs pull +``` + +Sizes: the engine lives outside the repository (pinned install path recorded in `toolchain.md`). The repository holds the Unreal project, Blender sources, geo sources, and tooling. + +## Known blockers + +| Blocker | Owner | Needed for | +| --- | --- | --- | +| Reboot into the staged `45.20261105` deployment | human | Everything; the current deployment is older than the staged one | +| Epic account, license acceptance, engine download | human | All Unreal work | +| `git-lfs` package install (needs admin) | human | Any content commit | +| `nvidia-smi` / Vulkan confirmation in a normal terminal | human | Engine validation | diff --git a/Docs/toolchain.md b/Docs/toolchain.md new file mode 100644 index 0000000..cc10c0a --- /dev/null +++ b/Docs/toolchain.md @@ -0,0 +1,39 @@ +# Toolchain + +Pinned versions for this project. Record the exact build string a tool reports, not just the version family, and re-record it after every upgrade. The most common cause of scale, material, and import mismatches is silently mixing two versions of the same tool. + +Audited 2026-11-06 on the development workstation. + +## Pins + +| Component | Pinned | Source | Status | +| --- | --- | --- | --- | +| Bazzite | `44.20261026` (Kinoite, `bazzite-dx-nvidia`) | `ujust update` / `rpm-ostree upgrade` | Running. `45.20261105` staged, reboot pending. | +| NVIDIA driver | `615.78.08`, open kernel module | Bazzite image | Loaded as kernel module. Desktop-session `nvidia-smi` / Vulkan check still pending, see [environment.md](environment.md). | +| Unreal Engine | `5.8.x` — pin one exact build | Epic (license required) | Not installed. | +| Unreal Linux toolchain | engine-bundled clang | Engine source tree | Not installed. Do not substitute the system compiler. | +| Blender | `5.2` LTS (upstream patch `5.2.3`) | Flatpak `org.blender.Blender` | Installed. | +| MPFB | `2.0.18` (extension `mpfb`, declares Blender >= 4.2) | Blender extensions platform | Installed. Load-and-export check on 5.2 still pending. | +| Blosm | latest release at install time | blosm.com / Gumroad | Not installed. Version must be recorded before first use. | +| QGIS | `3.44.15` LTR | qgis.org | Not installed. | +| Git | `2.56.0` | Bazzite image | Installed. | +| Git LFS | `3.x` | `rpm-ostree` layer | Not installed. **Required** before committing any file matched by `.gitattributes`. | +| distrobox | `1.8.2.5` | Bazzite image | Installed. | +| Python (tooling) | `3.14.8` system | Bazzite image | Installed. Use a venv for geo/tool scripts. | +| ffmpeg | `8.1.3` | Bazzite image | Installed. | + +Unreal Engine 5.9 is in preview and Unreal Engine 6 has been announced as of November 2026. Neither is a pin candidate for `0.x`. One engine family per milestone; a family change is a breaking change and belongs in `CHANGELOG.md`. + +## Pin rules + +- One engine build per release. Record the launcher or source build, the patch version, and the build date in this file and in the release entry. +- Blender stays on an LTS family (`5.2`). Every add-on version used for a shipped asset is recorded here. +- Upgrading a pinned tool mid-milestone requires re-running the scale test and the Blender→Unreal import check before further asset work. +- Never install a tool from an unverified source. Record the download origin next to the version. + +## Open compatibility risks + +1. **Blosm on Blender 5.2.** Blosm versions historically lag Blender releases. Verify Blosm against the installed Blender 5.2 before the blockout step. If it fails, add a side-by-side Blender 4.5 LTS Flatpak and convert that step's output only; do not mix Blender versions within one asset. +2. **MPFB 2.0.18 on Blender 5.2.** The extension declares Blender >= 4.2 but predates 5.x. The acceptance test is the `0.1.0` requirement to export one MPFB character with baked materials and a deform skeleton and import it into Unreal. +3. **QGIS LTR transition.** QGIS 4.4.0 entered LTR on 2026-10-30 but LTR binaries were still `3.44.15` at audit time. Do not pin `4.4.0` until its installers exist; switching LTR later is a documented migration. +4. **Driver and Vulkan validation on Bazzite.** Not an officially supported Unreal distribution. Validate before asset production, as `ROADMAP.md` requires. diff --git a/Game/README.md b/Game/README.md new file mode 100644 index 0000000..c766ade --- /dev/null +++ b/Game/README.md @@ -0,0 +1,18 @@ +# Game + +The Unreal project lives at `Game/GigLine/GigLine.uproject` once created. Nothing here yet. + +## What gets committed + +- `Config/` — engine and project settings, including the quality presets used for release checks +- `Source/` — C++ modules +- `Content/` — `0.1.0` map, materials, meshes; LFS-tracked +- `GigLine.uproject` + +## What does not + +`Binaries/`, `Intermediate/`, `Saved/`, `DerivedDataCache/` — all generated. `.gitignore` covers them; do not add exceptions. + +## Engine + +Installed outside the repository. Its path and exact version are recorded in [../Docs/toolchain.md](../Docs/toolchain.md). Nothing in this directory may assume a machine-specific engine path; the documented build procedure is [../Docs/build.md](../Docs/build.md). diff --git a/Geo/README.md b/Geo/README.md new file mode 100644 index 0000000..a66650b --- /dev/null +++ b/Geo/README.md @@ -0,0 +1,35 @@ +# Geo + +Geographic sources, manifests, and the scripts that turn them into Blender imports. + +OSM is layout data only. It is not authoritative for façade detail, height, or pavement, and it is never sampled as a texture or panorama source. + +## Required manifest + +Every extract gets a manifest file `Geo/manifests/-.md` recording: + +| Field | Example | +| --- | --- | +| Source | Overpass API / Geofabrik / OSM extract provider | +| Extract date | date the query ran or the file was downloaded | +| Query or file URL | the exact query text or download URL | +| Data timestamp | OSM data date reported by the source (may differ from the extract date) | +| Bounds | west, south, east, north in WGS84 decimal degrees | +| Licence | ODbL 1.0, attribution string | +| Checksum | SHA-256 of the committed file | +| CRS and local origin | projected CRS plus the chosen origin, with its WGS84 coordinates | +| Files | every file produced from this extract | + +## Demo bounds + +`0.1.0` covers 6840 Hollywood Blvd / El Capitan Entertainment Centre, buildings on the south side of Hollywood Boulevard between Highland Avenue and Orange Drive, and north-side buildings whose footprint lies within 50 m of the north frontage. Verify address, footprints, and boundaries against source data before modeling; anything unverifiable is recorded here as unresolved and is not modeled. + +## Coordinate convention + +- Work in a local projected CRS (EPSG:26911, NAD83 / UTM zone 11N, is the default candidate) and record the local origin explicitly. +- Blender and Unreal both take metres → Unreal units at 1 m = 100 uu. The conversion is applied once, in one place, and recorded in the manifest. Never apply a second silent scale on import. +- Preserve the original geographic coordinates in metadata so any asset can be traced back to its position. + +## Unresolved items + +Record here any structure whose address, footprint, or boundary could not be verified from permitted sources, with the sources checked. It does not get modeled. diff --git a/PLAN.md b/PLAN.md new file mode 100644 index 0000000..7e91f9b --- /dev/null +++ b/PLAN.md @@ -0,0 +1,126 @@ +# PLAN.md + +## Goal + +Build a Linux-first Unreal Engine game for walking and driving through a real city. + +**Initial release: `0.1.0`** — a walkable exterior demo around **6840 Hollywood Blvd / El Capitan Entertainment Centre**, including the surrounding block frontage and buildings directly across Hollywood Boulevard. + +Verify the address, building footprints, and demo boundaries before modeling. Treat these as distinct structures where the source data indicates; do not assume similarly named venues share one footprint. + +## Stack + +- **Unreal Engine:** rendering, gameplay, World Partition, Chaos Vehicles. +- **Blender:** modeling, UVs, baking, collision meshes, character preparation. +- **MPFB:** human base meshes; export baked materials and deform skeletons. +- **QGIS:** geographic cleanup, coordinate conversion, elevation preparation. +- **Blosm:** OSM building and street blockouts in Blender. +- **Git + Git LFS:** source control, large assets, tagged releases. + +Pin compatible tool versions in `docs/toolchain.md`. Validate Blender-to-Unreal mesh, skeleton, material, and scale transfers before producing assets. + +## Release Policy + +Use Semantic Versioning: `MAJOR.MINOR.PATCH`. + +- Each major development milestone receives a **minor release**. +- Each completed small stabilization task receives a **patch release**. +- New milestone functionality lands in prereleases such as `0.2.0-alpha.1`, not in patches. +- Patches contain fixes, optimization, documentation, or refinements without expanding scope. +- Tag releases as `v0.1.0`; maintain `CHANGELOG.md`. +- During `0.x`, document breaking changes and asset migrations. +- `1.0.0` marks the stable, agreed game scope—not completion of an entire city. + +## Initial Local Setup + +Target workstation: Bazzite Linux, Ryzen 7 7700X, 64 GB RAM, RTX 5070 Ti 16 GB. + +1. Update Bazzite using its supported mechanism; verify NVIDIA/Vulkan operation. +2. Register an Epic account and accept the Unreal license. Obtain a pinned Linux engine build or build from Epic's authorized source repository. +3. Validate Unreal on Bazzite before asset production; it is not necessarily an officially supported distribution. +4. Install the engine-required compiler/SDK, Git, Git LFS, and an editor. Use Distrobox for isolated command-line dependencies where useful. +5. Pin Blender, MPFB, Blosm, and QGIS versions; confirm add-on compatibility. +6. Keep the project and Derived Data Cache on SSD storage. Reserve several hundred GB for engine files, assets, caches, and builds. +7. Create a C++ Unreal project with Blueprint gameplay iteration and Enhanced Input. +8. Package and launch a blank Linux build immediately. +9. Test one static mesh and one MPFB character export before proceeding. + +### Repository + +- `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. + +Track `.uasset`, `.umap`, `.blend`, and large source binaries with LFS. +Ignore generated `Binaries/`, `Intermediate/`, `Saved/`, and Derived Data Cache. +Do not commit Unreal Engine source, credentials, or non-redistributable assets. + +## Geographic and Art Pipeline + +1. Save a versioned OSM extract and document its date, bounds, and source. +2. Acquire separately licensed elevation data if needed. +3. In QGIS, use a suitable local projected CRS, such as 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-to-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—not authoritative façade, height, or pavement detail. + +Use a consistent scale test, named export presets, and repeatable import settings. + +## Initial Demo: `0.1.0` + +### Included + +- Named site frontage, surrounding block frontage, and buildings across the street. +- Walkable sidewalks and a designated street crossing. +- First-person movement, mouse look, collision, reset, and pause. +- Recognizable hero façades; simplified background buildings. +- Fixed daytime lighting, basic ambience, and geographic attribution. +- Packaged Linux build with documented controls. + +### Excluded + +Driving, interiors, crowds, traffic simulation, multiplayer, and a full-city map. + +### Acceptance + +- Player can traverse both sides of the demo without falling through geometry. +- Building placement, street scale, and site identity have been checked against references. +- No blocking collision or packaging defects. +- Target 60 FPS at 1440p on the development workstation using a documented quality preset. +- Record whether upscaling is enabled and report performance without frame generation. +- A fresh project checkout builds with the documented external engine installation. + +## Indicative Timeline + +Solo-development estimate: **approximately 30–40 weeks**, subject to asset quality and available hours. + +| Release | Weeks | Larger task | Small patch tasks after release | +| --- | ---: | --- | --- | +| `0.1.0` | 1–6 | Local setup and initial walkable Hollywood block | `0.1.1` collision fixes; `0.1.2` scale/façade corrections; `0.1.3` packaging and setup fixes | +| `0.2.0` | 7–9 | MPFB player body, third-person camera, basic animation | `0.2.1` rig fixes; `0.2.2` skin/hair tuning; `0.2.3` camera clipping fixes | +| `0.3.0` | 10–13 | One Chaos vehicle, enter/exit interaction, closed driving route | `0.3.1` handling tuning; `0.3.2` vehicle collision fixes; `0.3.3` input fixes | +| `0.4.0` | 14–17 | Expand to a small connected neighborhood; stream map cells | `0.4.1` seam fixes; `0.4.2` streaming corrections; `0.4.3` HLOD tuning | +| `0.5.0` | 18–21 | Pedestrians, crosswalk behavior, limited ambient traffic | `0.5.1` navigation fixes; `0.5.2` crossing fixes; `0.5.3` simulation optimization | +| `0.6.0` | 22–24 | Visual/audio pass and evening lighting preset | `0.6.1` lighting fixes; `0.6.2` material corrections; `0.6.3` audio balancing | +| `0.7.0` | 25–27 | Settings, control rebinding, save/load, accessibility basics | `0.7.1` save fixes; `0.7.2` UI fixes; `0.7.3` input persistence fixes | +| `0.8.0` | 28–30 | Performance budgets and broader Linux hardware testing | `0.8.1` VRAM reductions; `0.8.2` frame-time fixes; `0.8.3` compatibility fixes | +| `0.9.0` | 31–34 | Feature freeze, public beta, license and build audit | `0.9.1` blocker fixes; `0.9.2` regression fixes; `0.9.3` documentation fixes | +| `1.0.0` | 35–40 | Stable neighborhood-scale walking/driving release | `1.0.x` maintenance and compatibility fixes | + +Finish each milestone's release checks before expanding scope. Cut map size and simulation complexity before compromising the core walking/driving experience. + +## Licensing and Distribution + +- Publish project-owned code under a chosen open-source license. +- Unreal remains proprietary/source-available; this is **not a fully open-source engine stack**. +- Separate code, art, engine, and geographic-data licensing. +- Record asset provenance and redistribution permissions in `THIRD_PARTY_NOTICES.md`. +- Verify licenses for every MPFB asset, texture, animation, vehicle, and audio file. +- 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. diff --git a/README.md b/README.md new file mode 100644 index 0000000..ee5acbf --- /dev/null +++ b/README.md @@ -0,0 +1,41 @@ +# Gig Line + +A Linux-first Unreal Engine game about walking and driving through a real city. The first release, `0.1.0`, is a walkable exterior demo around **6840 Hollywood Blvd / El Capitan Entertainment Centre**, covering the south-side frontage between Highland Avenue and Orange Drive plus the north-side frontage within 50 m of the boulevard. + +## Status + +Pre-production. Workstation setup and repository scaffolding are in progress; no engine, content, or geographic data is committed yet. Current state is tracked in [ROADMAP.md](ROADMAP.md), and the per-task setup state in [Docs/setup.md](Docs/setup.md). + +## Layout + +| Path | Contents | +| --- | --- | +| `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, toolchain pins, licensing, release checks | + +## Getting started + +```bash +git lfs install # required: content, images, audio, and geo files are LFS-tracked +git lfs pull +``` + +The engine is installed outside the repository and pinned in [Docs/toolchain.md](Docs/toolchain.md). The full procedure is in [Docs/setup.md](Docs/setup.md). + +## Documents + +- [ROADMAP.md](ROADMAP.md) — living task list, source of truth for progress +- [PLAN.md](PLAN.md) — scope, stack, release policy, timeline +- [AGENTS.md](AGENTS.md) — contributor and agent rules +- [Docs/toolchain.md](Docs/toolchain.md) — pinned versions +- [Docs/environment.md](Docs/environment.md) — workstation audit +- [Docs/release-checks.md](Docs/release-checks.md) — release gate definitions +- [Docs/licensing.md](Docs/licensing.md) and [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) — licensing +- [CHANGELOG.md](CHANGELOG.md) — release history + +## Licensing + +Code licence is an open decision (MIT proposed). Engine, art, and geographic data are licensed separately; see [Docs/licensing.md](Docs/licensing.md). OSM-derived output carries "© OpenStreetMap contributors". diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 0000000..1ba3981 --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,398 @@ +# ROADMAP.md + +Living roadmap for this project. This file is the single source of truth for current progress. + +## 0.1.0 — Local setup and walkable Hollywood block (weeks 1–6) + +### Environment setup + +Status detail in [Docs/setup.md](Docs/setup.md); workstation audit in [Docs/environment.md](Docs/environment.md); pins in [Docs/toolchain.md](Docs/toolchain.md). + +- [-] Update Bazzite using its supported mechanism; verify NVIDIA driver and Vulkan operation. +- [ ] Register an Epic account and accept the Unreal license; obtain a pinned Linux engine build or build from Epic's authorized source repository. +- [ ] Validate Unreal runs on Bazzite before asset production (not an officially supported distribution). +- [-] Install the engine-required compiler/SDK, Git, Git LFS, and an editor; use Distrobox for isolated CLI dependencies where useful. +- [-] Pin Blender, MPFB, Blosm, and QGIS versions; confirm add-on compatibility; record in `docs/toolchain.md`. +- [x] Create repository structure (`Game/`, `Art/`, `Geo/`, `Tools/`, `Docs/`) with LFS tracking and ignore rules applied. +- [x] Keep project and Derived Data Cache on SSD storage; reserve several hundred GB for engine, assets, caches, builds. + +### Project bootstrap + +- [ ] Create a C++ Unreal project with Blueprint gameplay iteration and Enhanced Input. +- [ ] Package and launch a blank Linux build. +- [ ] Export one static mesh from Blender and import into Unreal; verify scale and materials. +- [ ] Export one MPFB character with baked materials and deform skeleton; verify import. +- [ ] Document initial setup in `Docs/`: engine install, project checkout, fresh-checkout build procedure. + +### Geographic data + +- [ ] Save a versioned OSM extract; document date, bounds, and source in `Geo/`. +- [ ] Acquire separately licensed elevation data if needed. +- [ ] In QGIS, set a suitable local projected CRS (e.g. EPSG:26911) and record a local origin. +- [ ] Verify the address, building footprints, and demo boundaries for 6840 Hollywood Blvd against source data. +- [ ] Import OSM blockouts through Blosm; clean and detail them in Blender. +- [ ] Preserve geographic coordinates in metadata; define explicit meter→centimeter conversion to local Unreal coordinates. + +### Asset production + +- [ ] Establish a consistent scale test, named export presets, and repeatable import settings. +- [ ] Collect licensed reference photography for manual façade work. +- [ ] Model hero façade for the El Capitan Entertainment Centre site. +- [ ] Model surrounding block frontage. +- [ ] Model simplified background buildings directly across Hollywood Boulevard. +- [ ] Build sidewalks, roads, and collision meshes. +- [ ] Materials and look development for all exported assets. + +### Gameplay + +- [ ] First-person movement, mouse look, and Enhanced Input bindings. +- [ ] Collision, reset, and pause functionality. +- [ ] Walkable sidewalks and a designated street crossing. +- [ ] Fixed daytime lighting and basic ambience. +- [ ] Geographic attribution display ("© OpenStreetMap contributors" + license link). + +### Release checks + +- [ ] Player can traverse both sides of the demo without falling through geometry. +- [ ] Building placement, street scale, and site identity checked against references. +- [ ] No blocking collision or packaging defects. +- [ ] 60 FPS at 1440p on the dev workstation (Bazzite, Ryzen 7 7700X, 64 GB RAM, RTX 5070 Ti 16 GB) using a documented quality preset; record upscaling state; report performance without frame generation. +- [ ] Fresh project checkout builds with the documented external engine installation. +- [ ] Package Linux build with documented controls. +- [ ] Tag `v0.1.0` and write `CHANGELOG.md` entry; then remove this section. + +## 0.1.1 — Collision fixes (patch) + +### Patch tasks + +- [ ] Audit and fix any collision gaps or fall-through geometry found in `0.1.0`. +- [ ] Regression-test traversal on both sides of the demo. +- [ ] Verify no new packaging defects. +- [ ] Tag `v0.1.1` and write `CHANGELOG.md` entry; then remove this section. + +## 0.1.2 — Scale and façade corrections (patch) + +### Patch tasks + +- [ ] Correct building scale and street proportions flagged against references. +- [ ] Refine hero façade details where reference photography shows discrepancies. +- [ ] Tag `v0.1.2` and write `CHANGELOG.md` entry; then remove this section. + +## 0.1.3 — Packaging and setup fixes (patch) + +### Patch tasks + +- [ ] Fix any packaging or build issues encountered in `0.1.x`. +- [ ] Update `Docs/` setup instructions for anything that changed. +- [ ] Tag `v0.1.3` and write `CHANGELOG.md` entry; then remove this section. + +## 0.2.0 — MPFB player body, third-person camera, basic animation (weeks 7–9) + +### Character setup + +- [ ] Generate MPFB human base mesh; export baked materials and deform skeleton. +- [ ] Import character into Unreal; validate skeleton, scale, and materials. +- [ ] Create basic idle/walk animation set. +- [ ] Verify animation plays correctly on the imported rig. + +### Camera and controls + +- [ ] Add third-person camera following the player body. +- [ ] Add first/third-person toggle. +- [ ] Add camera collision to prevent clipping through geometry. +- [ ] Document any input changes. + +### Release checks + +- [ ] Third-person traversal works end-to-end in the demo area. +- [ ] No blocking animation or rig defects. +- [ ] Performance target still met at 1440p. +- [ ] Tag `v0.2.0` and write `CHANGELOG.md` entry; then remove this section. + +## 0.2.1 — Rig fixes (patch) + +### Patch tasks + +- [ ] Fix skeletal/rigging defects reported after `0.2.0`. +- [ ] Tag `v0.2.1` and write `CHANGELOG.md` entry; then remove this section. + +## 0.2.2 — Skin and hair tuning (patch) + +### Patch tasks + +- [ ] Tune skin shading and hair materials on the player character. +- [ ] Tag `v0.2.2` and write `CHANGELOG.md` entry; then remove this section. + +## 0.2.3 — Camera clipping fixes (patch) + +### Patch tasks + +- [ ] Fix remaining camera clipping cases in `0.2.x`. +- [ ] Tag `v0.2.3` and write `CHANGELOG.md` entry; then remove this section. + +## 0.3.0 — Chaos vehicle, enter/exit, closed driving route (weeks 10–13) + +### Vehicle production + +- [ ] Model one vehicle in Blender with collision meshes; export to Unreal. +- [ ] Set up Chaos Vehicle with wheel and physics configuration. +- [ ] Implement enter/exit interaction. +- [ ] Build a closed driving route with boundaries. +- [ ] Tune basic handling to a drivable state. + +### Release checks + +- [ ] Player can enter, drive the closed route, and exit without defects. +- [ ] No blocking vehicle collision or packaging defects. +- [ ] Performance target still met at 1440p. +- [ ] Tag `v0.3.0` and write `CHANGELOG.md` entry; then remove this section. + +## 0.3.1 — Handling tuning (patch) + +### Patch tasks + +- [ ] Refine vehicle handling feel based on `0.3.0` feedback. +- [ ] Tag `v0.3.1` and write `CHANGELOG.md` entry; then remove this section. + +## 0.3.2 — Vehicle collision fixes (patch) + +### Patch tasks + +- [ ] Fix vehicle collision defects (mesh/physics mismatches). +- [ ] Tag `v0.3.2` and write `CHANGELOG.md` entry; then remove this section. + +## 0.3.3 — Input fixes (patch) + +### Patch tasks + +- [ ] Fix vehicle/character input issues in `0.3.x`. +- [ ] Tag `v0.3.3` and write `CHANGELOG.md` entry; then remove this section. + +## 0.4.0 — Small connected neighborhood and map streaming (weeks 14–17) + +### World expansion + +- [ ] Extend geo pipeline to a small connected neighborhood beyond the demo block. +- [ ] Produce modular buildings, sidewalks, and roads for the expanded area. +- [ ] Set up World Partition with streaming cells. +- [ ] Configure HLOD for distant buildings. +- [ ] Verify no seams or popping between streamed cells during traversal. + +### Release checks + +- [ ] Continuous walking (and driving) across the expanded area works. +- [ ] Streaming does not introduce blocking defects. +- [ ] Performance target re-validated at 1440p with streaming active. +- [ ] Tag `v0.4.0` and write `CHANGELOG.md` entry; then remove this section. + +## 0.4.1 — Seam fixes (patch) + +### Patch tasks + +- [ ] Fix visible seams between streamed cells. +- [ ] Tag `v0.4.1` and write `CHANGELOG.md` entry; then remove this section. + +## 0.4.2 — Streaming corrections (patch) + +### Patch tasks + +- [ ] Correct streaming/loading issues found in `0.4.x`. +- [ ] Tag `v0.4.2` and write `CHANGELOG.md` entry; then remove this section. + +## 0.4.3 — HLOD tuning (patch) + +### Patch tasks + +- [ ] Tune HLOD quality and distance settings. +- [ ] Tag `v0.4.3` and write `CHANGELOG.md` entry; then remove this section. + +## 0.5.0 — Pedestrians, crosswalk behavior, ambient traffic (weeks 18–21) + +### Simulation + +- [ ] Add pedestrian characters with navigation. +- [ ] Implement crosswalk behavior (pedestrians use the designated crossing). +- [ ] Add limited ambient traffic on the street network. +- [ ] Optimize simulation cost to stay within frame budget. + +### Release checks + +- [ ] Pedestrians and traffic behave without blocking defects. +- [ ] Performance target re-validated at 1440p. +- [ ] Tag `v0.5.0` and write `CHANGELOG.md` entry; then remove this section. + +## 0.5.1 — Navigation fixes (patch) + +### Patch tasks + +- [ ] Fix pedestrian navigation issues. +- [ ] Tag `v0.5.1` and write `CHANGELOG.md` entry; then remove this section. + +## 0.5.2 — Crossing fixes (patch) + +### Patch tasks + +- [ ] Fix crosswalk behavior defects. +- [ ] Tag `v0.5.2` and write `CHANGELOG.md` entry; then remove this section. + +## 0.5.3 — Simulation optimization (patch) + +### Patch tasks + +- [ ] Optimize pedestrian/traffic simulation cost. +- [ ] Tag `v0.5.3` and write `CHANGELOG.md` entry; then remove this section. + +## 0.6.0 — Visual/audio pass and evening lighting preset (weeks 22–24) + +### Look and sound + +- [ ] Create an evening lighting preset. +- [ ] Complete a visual polish pass across the neighborhood. +- [ ] Add ambient audio (city ambience, traffic, basic SFX). +- [ ] Verify licenses for all added audio files. + +### Release checks + +- [ ] Both day and evening presets render without defects. +- [ ] Audio plays without gaps or licensing issues. +- [ ] Performance target re-validated at 1440p. +- [ ] Tag `v0.6.0` and write `CHANGELOG.md` entry; then remove this section. + +## 0.6.1 — Lighting fixes (patch) + +### Patch tasks + +- [ ] Fix lighting defects in day/evening presets. +- [ ] Tag `v0.6.1` and write `CHANGELOG.md` entry; then remove this section. + +## 0.6.2 — Material corrections (patch) + +### Patch tasks + +- [ ] Fix material errors found in `0.6.x`. +- [ ] Tag `v0.6.2` and write `CHANGELOG.md` entry; then remove this section. + +## 0.6.3 — Audio balancing (patch) + +### Patch tasks + +- [ ] Balance audio levels across the scene. +- [ ] Tag `v0.6.3` and write `CHANGELOG.md` entry; then remove this section. + +## 0.7.0 — Settings, control rebinding, save/load, accessibility (weeks 25–27) + +### Systems + +- [ ] Build settings menu (graphics and audio options). +- [ ] Implement control rebinding with persistence. +- [ ] Implement save/load for player state. +- [ ] Add accessibility basics (e.g. FOV, subtitle, colorblind options as applicable). + +### Release checks + +- [ ] Settings, rebinding, and save/load all persist across restarts. +- [ ] No blocking UI defects. +- [ ] Tag `v0.7.0` and write `CHANGELOG.md` entry; then remove this section. + +## 0.7.1 — Save fixes (patch) + +### Patch tasks + +- [ ] Fix save/load defects. +- [ ] Tag `v0.7.1` and write `CHANGELOG.md` entry; then remove this section. + +## 0.7.2 — UI fixes (patch) + +### Patch tasks + +- [ ] Fix UI issues in `0.7.x`. +- [ ] Tag `v0.7.2` and write `CHANGELOG.md` entry; then remove this section. + +## 0.7.3 — Input persistence fixes (patch) + +### Patch tasks + +- [ ] Fix rebinding persistence issues. +- [ ] Tag `v0.7.3` and write `CHANGELOG.md` entry; then remove this section. + +## 0.8.0 — Performance budgets and broader Linux hardware testing (weeks 28–30) + +### Performance + +- [ ] Define performance budgets (frame time, VRAM) and document them. +- [ ] Profile the full neighborhood; fix budget violations. +- [ ] Test on broader Linux hardware and VRAM configurations; document results. +- [ ] Re-validate the 1440p quality preset with upscaling state recorded. + +### Release checks + +- [ ] Performance budgets met on documented hardware matrix. +- [ ] No blocking compatibility defects. +- [ ] Tag `v0.8.0` and write `CHANGELOG.md` entry; then remove this section. + +## 0.8.1 — VRAM reductions (patch) + +### Patch tasks + +- [ ] Reduce VRAM usage where profiling shows excess. +- [ ] Tag `v0.8.1` and write `CHANGELOG.md` entry; then remove this section. + +## 0.8.2 — Frame-time fixes (patch) + +### Patch tasks + +- [ ] Fix frame-time spikes found in `0.8.x`. +- [ ] Tag `v0.8.2` and write `CHANGELOG.md` entry; then remove this section. + +## 0.8.3 — Compatibility fixes (patch) + +### Patch tasks + +- [ ] Fix compatibility issues from the hardware testing matrix. +- [ ] Tag `v0.8.3` and write `CHANGELOG.md` entry; then remove this section. + +## 0.9.0 — Feature freeze, public beta, license and build audit (weeks 31–34) + +### Freeze and audit + +- [ ] Freeze features; document the freeze in `CHANGELOG.md`. +- [ ] Produce a public beta build for testers. +- [ ] Complete license audit: `THIRD_PARTY_NOTICES.md`, all MPFB assets, textures, animations, vehicles, audio. +- [ ] Review ODbL obligations for any distributed derived geographic database. +- [ ] Review Epic distribution requirements before publishing. +- [ ] Verify a fresh checkout builds and packages reproducibly. + +### Release checks + +- [ ] Beta feedback triaged; blockers logged for `0.9.x`. +- [ ] Tag `v0.9.0` and write `CHANGELOG.md` entry; then remove this section. + +## 0.9.1 — Blocker fixes (patch) + +### Patch tasks + +- [ ] Fix blockers reported during the public beta. +- [ ] Tag `v0.9.1` and write `CHANGELOG.md` entry; then remove this section. + +## 0.9.2 — Regression fixes (patch) + +### Patch tasks + +- [ ] Fix regressions introduced by `0.9.x` fixes. +- [ ] Tag `v0.9.2` and write `CHANGELOG.md` entry; then remove this section. + +## 0.9.3 — Documentation fixes (patch) + +### Patch tasks + +- [ ] Update all `Docs/` for accuracy before `1.0.0`. +- [ ] Tag `v0.9.3` and write `CHANGELOG.md` entry; then remove this section. + +## 1.0.0 — Stable neighborhood-scale walking/driving release (weeks 35–40) + +### Final release + +- [ ] Complete final acceptance sweep across all `0.x` features. +- [ ] Confirm the stable, agreed game scope is met (neighborhood-scale walking and driving). +- [ ] Final build, documentation, and licensing verification. +- [ ] Tag `v1.0.0` and write `CHANGELOG.md` entry; then remove this section. diff --git a/THIRD_PARTY_NOTICES.md b/THIRD_PARTY_NOTICES.md new file mode 100644 index 0000000..8bc5034 --- /dev/null +++ b/THIRD_PARTY_NOTICES.md @@ -0,0 +1,50 @@ +# Third-party notices + +Provenance and redistribution status for everything in this repository that is not original project work. Policy lives in [Docs/licensing.md](Docs/licensing.md). + +Status values: **verified** (licence confirmed and permits our use), **pending** (not yet checked), **unresolved** (checked and not cleared — must not be committed or shipped). + +## Tools (not distributed) + +| Component | Version | Licence | Status | +| --- | --- | --- | --- | +| Unreal Engine | 5.8.x (pin) | Epic Games EULA, proprietary | verified — not redistributable; distribution per Epic terms | +| Blender | 5.2 LTS | GPL-2.0-or-later | verified — tool only, no GPL code linked into a shipped build | +| MPFB | 2.0.18 | CC0 (base mesh and add-on assets) | verified — confirm per-asset at character production | +| Blosm | pin at install | check at install | **pending** | +| QGIS | 3.44.15 LTR | GPL-2.0-or-later | **pending** — tool only | +| Git LFS | 3.x | MIT | **pending** | + +## Geographic data + +| Component | Source | Licence | Status | +| --- | --- | --- | --- | +| OSM extract (demo bounds) | not yet acquired | ODbL 1.0 | **pending** — record extract date, bounds, and source in `Geo/` on acquisition | +| Elevation data | not yet decided | per provider | **pending** — decide after the DEM variation check in `ROADMAP.md` | + +Attribution string for any OSM-derived output: "© OpenStreetMap contributors", . + +## Reference photography (development only, not shipped) + +Available in the sibling project `…/06-games/security-game/docs/screens/refs/hollywood/`, with per-file provenance in its `SIDECAR.md`. Nothing here is committed to this repository yet; the licences below are recorded so the set can be brought over with correct attribution. + +| File | Subject | Author | Licence | Shipped | +| --- | --- | --- | --- | --- | +| `el-capitan-facade-day-wikimedia-2009-10-27.jpg` | El Capitan facade, day | woo | CC BY 2.0 | no | +| `el-capitan-theatre-blade-sign-day-wikimedia-2008-10.jpg` | blade sign and temple frontage | Andreas Praefcke | CC BY 3.0 | no | +| `el-capitan-theatre-marquee-neighbour-day-wikimedia-2009-07-11.jpg` | west neighbour marquee | Alan Light | CC BY 2.0 | no | +| `premiere-staging-street-day-wikimedia-2006-02-12.jpg` | premiere staging | John Barreiros | CC BY 2.0 | no | +| `masonic-temple-historic-pd-1922.jpg` | Masonic Temple, 1922 | Charles W. Beam | public domain | no | +| `ovation-hollywood-across-street-pd-2006-12-28.jpg` | Ovation Hollywood, across street | Gary Minnaert | public domain | no | +| `walk-of-fame-terrazzo-ovation-day-cc0-2019-06-20.jpg` | Walk of Fame terrazzo band | Luijtenphotos | CC0 | no | +| `walk-of-fame-star-closeup-cc0-2022-07-08.jpg` | star close-up | Benoît Prieur | CC0 | no | +| `hollywood-boulevard-night-context-ccbysa.jpg` | boulevard at night (near Vine) | Downtowngal | CC BY-SA 3.0 | no | + +Notes: +- The CC BY-SA frame is used for colour and lighting study only. No texture, mesh, or material is derived from it. Any future derivative needs a fresh share-alike review before use. +- Pre-existing crop and redaction notes live in the sidecar and apply to any reuse. +- These photos are evidence for proportions, signage, and staging. They are licensed as photographs, not as building designs; do not treat them as permission to reproduce signage artwork at full fidelity. Venue lettering and trademarks are separate rights. + +## Assets + +No shipped 3D, texture, or audio assets exist yet. Add a row per asset category with author, source, licence, and redistribution status before the first content commit. diff --git a/Tools/README.md b/Tools/README.md new file mode 100644 index 0000000..a64d994 --- /dev/null +++ b/Tools/README.md @@ -0,0 +1,18 @@ +# Tools + +Repeatable import/export and processing helpers. Anything that was done twice by hand belongs here. + +## Conventions + +- One script, one job. No interactive prompts; every input is an argument. +- Each script documents its input format, output format, and the exact tool version it was tested with. +- Blender scripts run headless (`blender --background --python`), so they can be re-run for a regression check. +- No credentials, no absolute machine paths, no writes outside the project by default. +- A script that produces game content logs what it produced, so `Game/Content` can be audited against it. + +## Planned helpers + +- Blender export preset runner (named presets, metric scale assertion) +- Blender→Unreal scale test (export a known-size cube, verify 100× conversion) +- OSM extract fetch and manifest writer (records date, bounds, checksum) +- QGIS processing steps as batch scripts, so the geo cleanup is reproducible rather than GUI-only