Skip to content

Latest commit

 

History

History
77 lines (52 loc) · 6.91 KB

performance.md

File metadata and controls

77 lines (52 loc) · 6.91 KB

Generator performance

Development build: dist/yard-2026.11.16-performance-v01.zip (install from disk in Blender's Extensions preferences). Existing release archives and saved vessels are not replaced.

Faster creation, unchanged default geometry

New ships automatically append a validated stock Geometry Nodes library instead of rebuilding roughly 11,000 nodes in Python. Every ship gets its own local nested groups, ownership and material bindings; this is not a copy of an existing edited ship. Native editability and no-addon reopening are retained.

Libraries are accepted only when their source digest, binary digest, Blender version and build hash match. The bundled libraries target Blender 5.2.3 LTS, build e13b728c6880. Other builds, missing libraries or changed add-on Python source use procedural construction instead. That path has a faster node-layout traversal but can still take several minutes for a large ship. Nothing is downloaded or cached in user directories at runtime.

Optional editing controls

Select a new ship and open 3D View → N → Yard → Performance. Both switches default to off:

  • Viewport Preview caps effective Detail Level at 1 in the viewport. True openings remain, but seals and some facade bays are omitted. Final renders use the requested Detail Level. Yard Bake and GLB explicitly disable preview on disposable copies, leaving your editing setting unchanged. A deliberately requested Detail Level 0 or 1 stays 0 or 1 in final output; the setting does not force 2.
  • Instance Equipment keeps supplied object/collection equipment at the native mounts instanced instead of immediately copying every mesh. Rendering keeps those instances; Yard Bake/GLB realizes delivery geometry and preserves face-domain mount metadata. This applies to supplied native-mount assets, not every procedural rail, window or placeholder, nor arbitrary equipment attached through deck sockets.

Mesh-only downstream modifiers and third-party exporters may ignore instances or capture viewport preview. Turn Instance Equipment off (or explicitly Realize Instances before mesh-only processing), and turn Viewport Preview off for an exporter without a final-quality path. Yard's own Bake/GLB paths handle both automatically.

Existing ships and custom nodes

Existing graphs and defaults are never silently replaced. Older graphs do not acquire these switches just by opening the file. Generate a new ship, or explicitly use Regenerate Safely… with graph-replacement consent. Regeneration preserves named input values, deck/socket equipment and a backup of the old graph; custom node edits are not migrated. A legacy 398-input detailed graph gains only the two default-false performance controls. See attachments.md.

The native 34-site mount registry is unchanged. Preview and instancing are native saved-node behavior and do not require Yard to evaluate after reopening. Deck-socket following after further edits still requires Yard, as before.

Measured results and limits

Local factory-startup Blender 5.2.3 measurements, not guaranteed speedups:

Measurement Before After
CRUISE creation, original procedural → validated stock template 327.93 s 0.97 s
Original investigation: node-layout time, original → indexed traversal 149.28 s 77.57 s
CRUISE warm Length edit, requested Detail 2 → preview-equivalent Detail 1, final benchmark 176.49 ms 153.08 ms
Synthetic 33-mount equipment warm edit, realized → instanced 183.12 ms 154.85 ms
  • Stock creation figures are single runs on the compatible build. Creation includes scene construction, not the first full geometry evaluation, and is not rendering time. It does not imply a comparable live-edit speedup.
  • All 13 original parameter cases still match for geometry/material-index fingerprints, role hashes, material role names, vertex/face/triangle counts and triangles by role. Default hull sampling and window quality were not reduced.
  • The final CRUISE detail comparison uses seven measured warm edits after warmups. Detail 1 has 647,592 triangles rather than 820,936; its visual simplification is intentional and opt-in for editing.
  • The equipment experiment uses one shared synthetic 128×64 sphere at all 33 active CRUISE mounts, four alternating timing blocks, 15 measured edits per block. The combined median reduction is 15.44%. Fully realized counts remain 776,109 vertices / 893,958 faces / 1,347,336 triangles. This is not a measured memory-byte, drawing-FPS or production-fleet benefit.
  • Regression checks include actual RENDER-depsgraph detail, final-quality Bake/GLB, independent groups/materials, invalid-library fallback cleanup, explicit regeneration/rollback, legacy controls, and save/reopen without Yard. Geometry comparisons replace neither artistic closeup review nor a beauty render; neither was performed for this change.

Reproduction (source checkout)

Use a new label/output directory for each run; historical evidence is not overwritten:

python tools/blender.py -b --factory-startup --python-exit-code 1 \
  --python tools/benchmark_generator.py -- --label stock-rerun

# Bypass libraries; optionally add --legacy-layout for the old traversal.
python tools/blender.py -b --factory-startup --python-exit-code 1 \
  --python tools/benchmark_generator.py -- --procedural --label procedural-rerun

python tools/blender.py -b --factory-startup --python-exit-code 1 \
  --python tests/generator_performance.py -- --output artifacts/generator-performance/validation-rerun

python tools/blender.py -b --factory-startup --python-exit-code 1 \
  --python tools/benchmark_equipment_instances.py -- --output artifacts/generator-performance/equipment-rerun.json

After changing any yard/*.py file, explicitly rebuild both generated libraries before packaging:

python tools/blender.py -b --factory-startup --python-exit-code 1 \
  --python tools/build_stock_graph.py -- --replace
python tools/write_controls_doc.py
python tools/build_performance_package.py
python tools/blender.py -b --factory-startup --python-exit-code 1 \
  --python tests/attachment_package.py -- \
  --archive dist/yard-2026.11.16-performance-v01.zip \
  --output artifacts/generator-performance/package-rerun --performance

Use the intended Blender release build when rebuilding. The package builder refuses stale library/source digests and existing archive names. The smoke test exercises the archive under a Blender extension namespace, including stock generation and full-quality bake.

Evidence in the repository: artifacts/generator-performance/2026-11-16/{baseline,cached-layout,implemented-v02,implementation-comparison-v02}.json, implementation-summary-v02.csv, artifacts/generator-performance/implementation-v02/validation.json, and artifacts/generator-performance/equipment-v01.json. The dated investigation in docs/generator-performance-2026-11-16.md records the earlier experiments separately.