t1k:unity:base:pivot-hierarchy
| Field | Value |
|---|---|
| Module | base |
| Version | 5.116.6 |
| Effort | medium |
| Tools | — |
Keywords: _Visual, 3d prefab, hierarchy, nested prefab, pivot, prefab, transform, visual
How to invoke
Section titled “How to invoke”/t1k:unity:base:pivot-hierarchyUnity Pivot & Hierarchy Patterns
Section titled “Unity Pivot & Hierarchy Patterns”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.
Core Concept
Section titled “Core Concept”- Create empty parent GO at logical position (feet, rotation center, socket)
- Add child GO with mesh/visual at calculated offset
- Parent controls world position/rotation; child controls visual offset
Root (empty) ← position = feet / rotation center / socket └─ Mesh (child) ← localPosition = (0, offset, 0), has MeshFilter + MeshRenderer3D 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:
| Prefab | Holds | Never holds |
|---|---|---|
X (logic root) | Scripts, colliders, rigidbodies, config refs, anchors/sockets | Meshes, materials, any renderer (MeshRenderer, TrailRenderer, ParticleSystem, LineRenderer) |
X_Visual (nested child prefab) | MeshFilter/MeshRenderer, materials, visual-only children | Gameplay 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.outlineandTargetGlint.body, both renderers). Each becomes astrippedproxy document in the host, and the field is repointed to the proxy. - A stripped proxy’s fileID is
(sourceFileID ^ prefabInstanceFileID) & 0x7FFFFFFFFFFFFFFF(checked againstProp_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_Visualroot 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.
Offset Calculation Reference
Section titled “Offset Calculation Reference”Unity built-in primitive half-heights at scale 1:
| Primitive | Height | Half-Height | Offset Formula |
|---|---|---|---|
| Capsule | 2m | 1.0 | 1.0 * scale.y |
| Cylinder | 2m | 1.0 | 1.0 * scale.y |
| Cube | 1m | 0.5 | 0.5 * scale.y |
| Sphere | 1m | 0.5 | 0.5 * scale.y |
| Custom mesh | varies | bounds.extents.y | mesh.bounds.extents.y * scale.y |
Scale goes on child, not parent. Offset in parent-local space.
Hard rules
Section titled “Hard rules”- 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.
+= offsetaccumulates 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
Reference Files
Section titled “Reference Files”| File | Contents |
|---|---|
use-cases-and-ecs.md (references/use-cases-and-ecs.md) | Use cases A-F with code, DOTS baking, ECS gotchas, decision framework |