0 Fork 0

Files

T

zwitschi 4d27109668 refactor(tools): group the sixty scripts by what they talk to

One directory with sixty scripts stopped being navigable, and the grouping is also the sandbox boundary:

  Tools/unreal/    commandlets and the two map builders, with ue_common.py and ue_placement.py as the
                   shared imports (they need the engine)
  Tools/blender/   builders, exporters, the FBX preset, the MPFB character pipeline, blender_screenshots
                   (they need the Blender Flatpak)
  Tools/review/    the visual loop: render_screenshots.sh, judge_screenshot.py, hero_compare.py,
                   build_comparison_md.py, e2e_asset_check.py, hero_iterate.sh, visual_loop.py,
                   visual_targets.json
  Tools/gen/       image and texture generation: the ComfyUI driver, deterministic texture writers,
                   reference fetching
  Tools/input/     OS-level input injection
  root             _common.py, check-lfs.sh, addon_compat_probe.py, sibling_asset_audit.py, tests/

Every moved script now resolves the repository root as ../.. and puts the tools root plus its siblings on
sys.path, so 'import ue_common' still works from unreal/. The test suite bootstrap does the same for the five
folders. render_screenshots.sh takes the folder as a third argument to run_cmdlet, and the e2e driver,
hero_iterate.sh and the comparison generator were repointed.

51 README rows now link to their new location, the README gains a Layout section naming each folder's
sandbox, and the architecture notes and Blender README follow the moves.

Verified: 108 tests pass, prettier is clean, judge_screenshot.py and hero_compare.py run from their new
homes, and the e2e run was aborted mid-way (it had been rebuilding an empty DemoMap for 15 minutes) and is
being rerun against the new layout.

2026-11-10 12:40:30 +01:00

2.6 KiB

Raw Blame History

Solution Strategy

Technology decisions

Unreal Engine 5.8.4 for rendering, World Partition, physics (Chaos), and the Enhanced Input system. Chosen for its Linux support, open C++ source, and real-time rendering quality.
Blender 5.2 LTS for all 3D modelling, UV work, and collision mesh authoring. Driven headlessly via bpy Python scripts, not MCP.
QGIS 4.2.3 for geographic data cleanup, coordinate conversion (EPSG:26911), and DEM preparation.
Blosm 2.7.28 for OSM building and street blockouts inside Blender (layout data only — not authoritative façade, height, or pavement detail).
MPFB 2.0.18 for human base meshes and baked materials (NPCs in 0.2.0+).

Top-level decomposition

The system is a single Unreal game module (GigLine) with no plugins beyond EnhancedInput. Content is organised by domain under /Game/Hollywood/:

Site/ — terrain, road, sidewalks, kerbs, crossing markings, site materials
ElCapitan/ — hero façade mesh and materials
Frontage/ — south-side block building meshes
North/ — north-side building meshes
Input/ — Enhanced Input actions and mapping context

All modelling and geographic processing live outside the game project in Art/, Geo/, and Tools/. The Game/ directory contains only engine-ready content and C++ source.

Quality achievement

Realism first: reference photography and measured data drive every façade decision; renders are compared against the photographs with Tools/review/visual_loop.py, and a façade is built from the shared 4.96 m module kit so the street wall reads consistently. Materials are authored in Unreal with world-aligned generated textures, and lighting is fixed daytime so a shot is comparable between runs.
Performance as a budget, not a driver: dynamic-only lighting (no build step, no static shadow maps), world-space-noise materials (cheap procedural variation), minimal overdraw for street-level geometry, and a 60 FPS at 1440p floor that every release must meet. It closes the quality list because it constrains how much realism fits, not what the block should look like.
Walkability: complex-as-simple collision on terrain (C++ helper forces the flag on the asset), block-all collision on every site mesh, swept transect QA verifies zero raycast holes.
Fidelity: geographic data verified before modelling (footprints, bounds, DEM); building placement checked against street mesh, never in isolation; reference photography drives façade work.
Reproducibility: pinned toolchain in Docs/toolchain.md, named export presets, Tools/check-lfs.sh gate, fresh-checkout build procedure in Docs/build.md.

2.6 KiB Raw Blame History

Solution Strategy

Technology decisions

Top-level decomposition

Quality achievement

2.6 KiB

Raw Blame History