Skip to content

t1k:unity:base:pivot-hierarchy

FieldValue
Modulebase
Version5.116.6
Effortmedium
Tools—

Keywords: _Visual, 3d prefab, hierarchy, nested prefab, pivot, prefab, transform, visual

/t1k:unity:base:pivot-hierarchy

Guide for the “empty parent + offset child” hierarchy pattern. Applies to pivot fixing, rotation pivots, orbits, attachment sockets, animation isolation, and DOTS ECS baking.

Scope: GameObject hierarchy restructuring for pivot control. Does NOT cover animation rigging, IK solvers, or physics joints.

  1. Create empty parent GO at logical position (feet, rotation center, socket)
  2. Add child GO with mesh/visual at calculated offset
  3. Parent controls world position/rotation; child controls visual offset
Root (empty) ← position = feet / rotation center / socket
└─ Mesh (child) ← localPosition = (0, offset, 0), has MeshFilter + MeshRenderer

3D Prefab Split — Logic Root + Visual Prefab

Section titled “3D Prefab Split — Logic Root + Visual Prefab”

A 3D prefab with scripts AND a mesh is two prefabs, not one:

PrefabHoldsNever holds
X (logic root)Scripts, colliders, rigidbodies, config refs, anchors/socketsMeshes, materials, any renderer (MeshRenderer, TrailRenderer, ParticleSystem, LineRenderer)
X_Visual (nested child prefab)MeshFilter/MeshRenderer, materials, visual-only childrenGameplay scripts
Sling.prefab ← scripts (SlingController, ...), colliders
└─ Sling_Visual.prefab ← nested prefab instance: meshes, materials only
  • The visual is a prefab instance under the root, not loose child objects. Swap, reskin or re-export the visual without touching scripts or their serialized refs.
  • Scripts reach visual parts through a serialized ref to the child (or a small view component on the root), never by name lookup.
  • Name the visual <RootName>_Visual. Scale and offset go on the visual child (see Core Concept), not the root.
  • Applies to every 3D object with gameplay: Sling, Ball, Bomb, Slot. A pure-decor prop with no script stays one prefab.
  • A Level-style prefab that places many objects nests the logic roots; each root nests its own _Visual.

Splitting an existing prefab by hand (YAML) — traps:

  • Find EVERY serialized ref from the root’s scripts into the moved objects by grepping the moved fileIDs across all documents, never by guessing field names (Target_Golden had two: TargetXRay.outline and TargetGlint.body, both renderers). Each becomes a stripped proxy document in the host, and the field is repointed to the proxy.
  • A stripped proxy’s fileID is (sourceFileID ^ prefabInstanceFileID) & 0x7FFFFFFFFFFFFFFF (checked against Prop_Tnt.prefab). Pick a random-looking instance ID, otherwise IDs that share high bits XOR to tiny numbers.
  • Keep the old subtree intact under a new X_Visual root so child names and local transforms do not change.
  • Hand edits are unverified until the prefab is opened in the Editor (or a batchmode confirm runs with the Editor closed); a wrong ref nulls silently.

Unity built-in primitive half-heights at scale 1:

PrimitiveHeightHalf-HeightOffset Formula
Capsule2m1.01.0 * scale.y
Cylinder2m1.01.0 * scale.y
Cube1m0.50.5 * scale.y
Sphere1m0.50.5 * scale.y
Custom meshvariesbounds.extents.ymesh.bounds.extents.y * scale.y

Scale goes on child, not parent. Offset in parent-local space.

  • PostTransformMatrix conflicts with TransformBaker — adding manually in a custom baker causes entity count drops and broken SubScene loading. Only use via TransformUsageFlags.NonUniformScale.
  • “Fix the data, not the code” — restructure the prefab hierarchy rather than compensating in runtime systems.
  • += offset accumulates per frame — use = (absolute) or fix in prefab.

→ Full use cases (A-F), DOTS baking behavior, ECS parent-child setup, decision framework: references/use-cases-and-ecs.md

FileContents
use-cases-and-ecs.md (references/use-cases-and-ecs.md)Use cases A-F with code, DOTS baking, ECS gotchas, decision framework