docs: bring every document in line with the current build
README rewritten around the actual state (walkable DemoMap, blockout facades, planned patches); Tools/README now lists all seventeen tools by role; build.md gains the content pipeline table and the two enforced rules (one unit conversion, collision decided at import). Setup gains a content-pipeline row, the toolchain state notes the demo level exercises the engine path, release checks record the Blender pre-check that backs traversal, PLAN points at ROADMAP/MEMORY/Screenshots, and THIRD_PARTY_NOTICES gains rows for the hero facade and the candidate props. Also fixed the last stale reference to Geo/scripts in MEMORY.md - a sweep found old paths in six documents after the tool move, which the memory entry now warns about.
This commit is contained in:
1 parent
1a1230ab6b
commit
e48a0cd82b
9 files changed
+105
-33
No files matched your search
+44
-18
@@ -1,26 +1,52 @@
|
||||
# Tools
|
||||
|
||||
Repeatable import/export and processing helpers. Anything that was done twice by hand belongs here.
|
||||
Repeatable helpers that drive Blender, Unreal, and the reference/asset sources. Nothing here is hand-run twice: every step that produced committed content has a script.
|
||||
|
||||
Geographic tools live in [`Geo/tools/`](../Geo/README.md) and the Blender-side builders live next to their output in `Art/blender/*/`; this folder holds everything that talks to Unreal, the network, or the repository.
|
||||
|
||||
## 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.
|
||||
- One script, one job. Every input is an argument; no interactive prompts.
|
||||
- Absolute paths where a tool crosses into a sandbox (Blender Flatpak, the Unreal commandlet). Those processes do not share the repo's working directory.
|
||||
- Unreal commandlets swallow `print()`, so each writes a result file under `/tmp/gigline/`. Read the file; do not trust the exit code alone.
|
||||
- No credentials, no writes outside the project by default.
|
||||
|
||||
## Helpers
|
||||
## Repository and assets
|
||||
|
||||
- `render_screenshots.sh` — visual-review pipeline: rebuilds `/Game/Test/ReviewMap` from current content (`ue_build_review_map.py`), runs the game on it in `-game` mode, lets `AGigLineShotActor` (`Game/GigLine/Source/GigLine/`) capture the fixed camera list, and copies the PNGs into the gitignored `Screenshots/`. See `Screenshots/README.md`.
|
||||
- `check-lfs.sh` — repository guard: fails if `git-lfs` or the `lfs` filter is missing, or if an LFS-tracked file was committed as a plain blob.
|
||||
- Geographic tools and their shared helpers live in `Geo/tools/` (see `Geo/README.md`).
|
||||
- Blender-side builders that turn geo data into meshes live beside their output: `Art/blender/terrain/terrain_from_dem.py`, `Art/blender/street/street_mesh.py`, `Art/blender/site/site_assembly.py`, `Art/blender/blockout/blosm_blockout.py`. They import their helpers from `Geo/tools/osm_common.py`, which is also the only place that converts metres to Unreal centimetres.
|
||||
- `sibling_asset_audit.py` — reads the sibling project's prop library straight from GLB headers and writes `Art/props/reuse-manifest.json`; copies nothing.
|
||||
- `page_image_fetch.py` — resolves a web page's `og:image` and downloads it, with page URL and hash in a local sidecar. Works for Flickr, Commons file pages, and most photo blogs.
|
||||
- `commons_fetch.py` — Wikimedia Commons reference fetcher. Search, exact `File:` titles, or a whole Commons category (`--category`), thumbnails, provenance `sidecar.json` per folder. Wikimedia throttles `upload.wikimedia.org` (HTTP 429), so keep batches to six or fewer files and pass `--delay 3`; a throttled file is skipped and recorded rather than aborting the run. Writes only into the gitignored `Art/reference/`; reference images are never committed.
|
||||
| Tool | Purpose |
|
||||
| --- | --- |
|
||||
| `check-lfs.sh` | Fails if the `lfs` filter is missing or an LFS-tracked file was committed as a plain blob |
|
||||
| `sibling_asset_audit.py` | Reads the sibling project's prop library from GLB headers into `Art/props/reuse-manifest.json`; copies nothing |
|
||||
| `scale_test_export.py` / `ue_scale_test_import.py` | The 1 m = 100 uu scale test; the named presets `ue_metric_v1` live in these two files |
|
||||
|
||||
## Planned helpers
|
||||
- Blender export preset runner (named presets, metric scale assertion)
|
||||
- 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
|
||||
## Reference gathering
|
||||
|
||||
| Tool | Purpose |
|
||||
| --- | --- |
|
||||
| `commons_fetch.py` | Wikimedia Commons: search, exact `File:` titles, or a whole category; writes a provenance `sidecar.json` |
|
||||
| `page_image_fetch.py` | Resolves a web page's `og:image` and downloads it (Flickr, Commons file pages, photo blogs) |
|
||||
| `addon_compat_probe.py` | Verifies MPFB/Blosm can load and generate headless on the pinned Blender |
|
||||
|
||||
## Blender content
|
||||
|
||||
| Tool | Purpose |
|
||||
| --- | --- |
|
||||
| `hero_facade_build.py` | Parametric hero façade; emits a JSON report naming the evidence behind every part |
|
||||
| `mpfb_character_export.py` | MPFB human, standard rig, baked skin, FBX export |
|
||||
|
||||
## Unreal import and level building
|
||||
|
||||
| Tool | Purpose |
|
||||
| --- | --- |
|
||||
| `ue_import_site.py` | Imports the six site FBXs into `/Game/Hollywood/Site`, setting collision complexity per mesh |
|
||||
| `ue_hero_facade_import.py` | Imports the façade and places it on the measured building line |
|
||||
| `ue_build_demo_map.py` | Builds `/Game/Hollywood/DemoMap`: lighting, façade, site meshes, player start |
|
||||
| `ue_build_review_map.py` | Rebuilds `Test/ReviewMap`, stages the shot camera list, and stages the demo-map views |
|
||||
| `ue_create_input_assets.py` | Creates `/Game/Input` actions and the mapping context headlessly |
|
||||
| `ue_character_import.py` | Skeletal import plus the material/texture chain Interchange skips |
|
||||
|
||||
## Visual review
|
||||
|
||||
| Tool | Purpose |
|
||||
| --- | --- |
|
||||
| `render_screenshots.py` / `render_screenshots.sh` | Rebuilds the review map, runs the game, captures the shot list into `Screenshots/` |
|
||||
Reference in new issue
Block a user