Skip to content

Latest commit

 

History

History
103 lines (75 loc) · 12.8 KB

attachments.md

File metadata and controls

103 lines (75 loc) · 12.8 KB

Persistent attachments and safe regeneration

Blender workflow

  1. Append equipment as an object, or create a collection instance. Its origin is the mounting foot; authored dimensions are in metres.
  2. Position it on a cabin roof, main deck or raised foredeck. Select one equipment object, then the deck empty or ship carrier last (active).
  3. In N → Yard → Persistent deck attachments, choose Attach / Rebind Equipment to Active Deck. Choose Active cabin deck, Main deck or Raised foredeck in the dialog. First attachment preserves the current world pose and stand-off. Rebinding an existing socket uses its saved normalized coordinates on the explicitly chosen deck.
  4. Change the deck's centre, length, width or storey height. Equipment follows after the short debounced update. Update Attachment Placement forces it immediately. Equipment-local rotation, scale and manual offsets remain untouched.
  5. Ordinary design edits need no regeneration. To rebuild standard construction, use Regenerate Safely…, read the warning, and explicitly enable Replace stock node construction.
  6. Save As a new .blend for review. Regeneration itself never saves/overwrites any file. Detach Equipment (Keep World Pose) removes a binding without moving the equipment.

A socket is a separate arrow empty under the ship root. Its saved yard_attachment JSON contains a revision, attachment ID, target deck ID, normalized UV, metric offset and heading. A deck receives a persistent yard_deck_id; lookup is restricted to that ship's assigned active decks, never global object names, copied owner UUIDs or generated mesh indices. Rename decks/equipment freely. Duplicate the whole hierarchy, then Make Node Setup Unique, before independent procedural editing.

Placement contract

  • uv=(u,v) are fractions of the effective half-length / half-width: (0,0) is the cabin footprint centre, u=1 bow, v=1 port. Values must be finite and within [-1,1].
  • Cabin targets cover every enabled/assigned level (up to 24). Existing UVs keep the bounded cabin footprint, not the terrace overhang; use metric XY offsets to reach a terrace. Z is the horizontal roof slab upper surface. Wall lean does not tilt it.
  • Main deck UV runs from stern to foredeck break (or bow when the foredeck is disabled); Foredeck runs from break to bow. V follows the hull half-width at that X. Saved target IDs are ship-local @yard:main and @yard:foredeck, independent of names/slots.
  • Main/foredeck Z is raycast against actual upward, tagged evaluated deck geometry, including sheer and raised extrusion, never equipment or cabin roofs. Keep origins inside the hull and away from the break/end caps. Disabling an occupied foredeck holds all sockets and blocks regeneration/export until restored or explicitly rebound. Frames remain level about ship Z; this is not a sloped-footprint conformer.
  • offset=(x,y,z) is in ship-local metres, not a scale-dependent fraction; heading is degrees about ship +Z.
  • Asset-local transforms are separate from the socket. Deck resizing moves the equipment but does not stretch it. Root scaling still scales the entire ship; use uniform root scale.
  • Missing/disabled/ambiguous targets hold the entire ship's last good socket placement and show an error, rather than silently snapping to another deck. Regeneration refuses unresolved bindings. Yard deck removal, truncated layout and preset removal of an occupied deck are blocked before mutation. Direct Blender deletion is not intercepted; restore, detach or explicitly rebind afterward.

Safe regeneration guarantees and limits

The API builds a new standard graph on a temporary carrier, restores every existing input by name and socket type, and evaluates finite, nonempty geometry before swapping the real master. It initializes all fresh sockets first, so recycled Socket_N identifiers cannot scramble assignments. It then validates the real carrier, including the unchanged downstream stack.

The ship root, carrier, deck/window objects, existing equipment, material/source IDs, root transforms and other modifiers are retained. On failure the original graph and its input values are restored, socket transforms/status are rolled back, and newly allocated staging IDs are removed. Unrelated orphans are never purged.

Custom node construction is replaced, not migrated. Explicit opt-in is mandatory. The complete previous master/nested graph remains saved with a fake user and the root's yard_previous_graph reference. A Text datablock named Yard regeneration backup • … .json records the original native inputs, ID names and attachment specs; its name is on yard_regeneration_report. Inspect the previous graph in the node editor, or use Blender Undo immediately after the operator. There is no automatic backup-restore UI. Retained backups intentionally increase file size; Yard does not purge them.

Unsupported custom/changed input types, animated carriers, linked data, incompatible/older schemas and missing legacy effective defaults fail safely instead of guessing at migration. Legacy parented hardware is preserved as-is; it does not become deck-relative unless explicitly attached.

Python API

from yard import attachments
from yard.regeneration import regenerate

socket = attachments.attach(root, equipment, deck,
    uv=(-0.25, 0.48), offset=(0, 0, 0), heading=0,
    identifier='liferaft.port.custom')
# Alternatively: attachments.attach(root, equipment, 'MAIN', uv=(-0.4, 0.3))
# Or use 'FOREDECK' when Raised Foredeck is enabled.
attachments.sync(root)  # explicit for background scripts
attachments.rebind(socket, another_deck, uv=(0.2, -0.3))
report = regenerate(root, replace_graph=True)
attachments.detach(equipment)  # keeps world pose

Omit uv to adopt existing world placement instead of seating the origin on the roof. Adopt a multi-part assembly using one parent/collection instance; wrap animated/constrained equipment in an unanimated assembly empty. attachments.spec(socket) reads the saved record; attachments.plan(root) validates all frames without moving anything. The existing native 34-site registry and assets.set_asset() are unchanged and can coexist with these arbitrary deck sockets.

Scope

  • Targets support all cabin roof decks, the sheered main deck and the enabled raised foredeck. Interior floors, hull-side anchors, arbitrary mesh faces, automatic obstacle avoidance, certified clearances and collision repair are not implemented. The normalized footprint is not an equipment-footprint containment test: keep clear of chamfers, stair openings, railings and other equipment. Analytic deck rules can differ slightly from sampled GN foundations; the four-vessel roof audit uses an explicit 2 mm budget (measured maximum 1.10 mm, Cargo), not exact mechanical seating. The earlier workboat-only test used 1 mm.
  • Standard deck control parenting/transforms are assumed. Move/rotate the ship with its root, not its carrier. Arbitrary constrained/transformed control rigs and custom surface graphs require reviewed integration.
  • Saved poses and source instances reopen/render without Yard enabled. Following subsequent deck edits requires Yard's updater (or explicit sync); these arbitrary sockets are not a native driver/Geometry Nodes rig. Update runs on load, before saving and after interactive design edits. Headless scripts call sync explicitly.
  • Bake and GLB include the carrier plus all socket descendants, including nested collection instances, collection-origin offsets, child transforms, evaluated modifiers and materials. Delivery geometry is recursively realized and temporary IDs are cleaned up on success/failure. Render-hidden direct equipment objects, cameras/lights, unrelated ship children and controls are excluded. The GLB exporter limits selection to the active scene to prevent cross-scene duplicates. Source equipment is not reparented, moved or converted.
  • The GLB sidecar adds an attachments array (stable specs, socket matrix in ship space and object names). The native Mounts output and append-only 34-site registry remain unchanged; only available native sites appear in the manifest. Arbitrary static legacy supports, chains and anchors are not automatically attached or exported as socket equipment. Attach/wrap them explicitly if required.

Four-vessel validation and current delivery

Installable development build.

The actual saved Hero Cargo, Assist Workboat, Ferry and Cruise were edited and regenerated with stock construction. All 398 inputs per ship, 29 sockets across 17 cabin roofs + main/foredeck targets, local equipment poses, source collections and graph backups survived. Tests include nested approved liferaft instances with nonzero collection origins and ordinary parented child meshes. These are engineering fixtures with small marker meshes, not a restyled marketing fleet or a clearance certification.

Superseded: v01 was interrupted by a test material-name collision. v02 regeneration is valid, but its GLBs leaked a selected Cargo from another scene. Use only all_decks_exports_v03 for final GLBs. These historical outputs were not overwritten.

python tools/blender.py -b --factory-startup --python-exit-code 1 \
  --python tests/all_deck_attachments.py -- --output artifacts/attachments/new_fleet_run
python tools/blender.py -b --factory-startup --python-exit-code 1 \
  --python tests/all_deck_exports_saved.py -- --output artifacts/attachments/new_export_run
python tools/blender.py -b --factory-startup --python-exit-code 1 \
  --python tests/all_deck_surface_safety.py -- --output artifacts/attachments/new_surface_report.json

The saved-fleet suite retains native root transforms and downstream modifiers. It uses a separate validation scene to avoid intentional ocean simulation dependencies; it does not migrate legacy static equipment into sockets. Final export audit runs in an independent Blender process from the real regenerated checkpoint, without repeating expensive stock builds.

Verified example and tests

The workboat example uses two approved liferaft-canister instances and one searchlight. Its top deck was shortened 22%, narrowed 15%, moved 0.5 m forward, and the lower storey raised 0.65 m, then the stock ship graph was regenerated. All 398 native inputs, the three attachment identities/UVs/local poses/source collections and legacy hardware were retained. Measured roof contact error stayed below 0.30 mm in this example. The changed deck is real evaluated ship geometry, not a moved backdrop.

python tools/blender.py -b --factory-startup --python-exit-code 1 \
  --python tests/deck_attachment_regeneration.py -- --output artifacts/attachments/new_run
python tools/blender.py -b --factory-startup --python-exit-code 1 \
  --python tests/attachment_safety_edges.py -- --folder artifacts/attachments/deck_regeneration_v04
uv run --with pillow python tools/review_deck_regeneration.py \
  --folder artifacts/attachments/deck_regeneration_v04 --output previews/attachments/new_review

Use a new output directory; examples/reports are not overwritten. The integration suite includes real stock generation, live edits, actual roof raycasts, pre/post-swap injected failures and no-addon reopening. The fast edge suite additionally verifies duplicated-ship isolation, invalid inputs, disabled/ambiguous targets and deliberately changed socket identifiers using copies of an already validated graph.