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.
This commit is contained in:
zwitschi committed
commit
eceaff1397
17 files changed
+1100
No files matched your search
@@ -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 <remote> 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.
|
||||
@@ -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 <https://www.openstreetmap.org/copyright> 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.
|
||||
@@ -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 | — | — | — |
|
||||
@@ -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 <remote> 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 |
|
||||
@@ -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.
|
||||
Reference in new issue
Block a user