b3dSetParent

Sets parent-child hierarchy relationship (child inherits parent transform). Takes childEntity (child entity handle), parentEntity (parent entity handle, 0 to detach), inheritCollision (reserved, not implemented). Returns nothing. Validates child exists, removes child from old parent's children list if had previous parent, if parentEntity=0 detaches child (makes root entity with parent=nullptr), otherwise validates new parent exists and establishes relationship (child.parent=&parent, adds child to parent.children), marks child.worldMatrixDirty=true. Hierarchy enables grouped transforms (child moves/rotates/scales with parent).

This function creates entity hierarchy. Parent-child relationship: child entity's transform becomes relative to parent, child's world transform = parent's world transform * child's local transform, moving/rotating/scaling parent affects all children (children move/rotate/scale with parent), child's position/rotation/scale values interpreted as local (relative to parent, not world). Detaching: parentEntity=0 detaches child from parent (makes child root-level entity), child.parent=nullptr, child removed from old parent's children list, child's local transform becomes world transform (coordinates unchanged, now interpreted as world coordinates). Previous parent handling: if child already had parent (child.parent!=nullptr), removes child from old parent's children list: siblings.erase(remove(siblings.begin(), siblings.end(), &child), siblings.end()), prevents duplicate entries, enables reparenting (move child from one parent to another). New parent establishment: validates new parent exists (parentEntity handle lookup), sets child.parent = &parent (pointer to parent entity), adds child to parent.children list (parent.children.push_back(&child)), establishes bidirectional relationship. WorldMatrix dirty flag: marks child.worldMatrixDirty=true (hierarchy change invalidates cached matrix), during next render: UpdateEntityWorldMatrix recalculates child's worldMatrix = parentWorldMatrix * childLocalMatrix, propagates dirty flag to all descendants (entire subtree recalculated). InheritCollision parameter: reserved for future use (TODO comment in code), not currently implemented, intended for physics collision inheritance (child collision shapes part of parent compound shape). Use cases: (1) Character armatures (bones parented in skeleton hierarchy), (2) Vehicle components (wheels/turrets parented to vehicle body), (3) Scene organization (group related objects, move groups together), (4) Attachments (weapons parented to character hands), (5) Hierarchical animation (robotic arms, door hinges). Common pattern: create parent entity (pivot or mesh), create children, b3dSetParent(child, parent, 0) for each child, transform parent to move entire group. Typical usage: wheel=b3dLoadMesh("wheel.glb"), car=b3dLoadMesh("car.glb"), b3dSetParent(wheel, car, 0), moving car moves wheel, wheel position relative to car. Coordinate spaces: child's position/rotation/scale in parent's local space, to get world coordinates: multiply by parent's world matrix (handled automatically during rendering). Transform propagation: parent transform changes propagate to all descendants (entire hierarchy), child transform changes don't affect parent or siblings, deep hierarchies multiply matrices down chain (grandparent * parent * child). Performance: establishing hierarchy is O(1) (pointer assignment, vector operations), matrix propagation during render is O(N) where N=hierarchy depth, deep hierarchies more expensive (matrix multiplication cascade). Circular hierarchy prevention: no validation to prevent circular hierarchies (A parent of B, B parent of A), circular hierarchies cause infinite loops during matrix updates (avoid by design). Related: b3dGetParent returns entity's parent handle, UpdateEntityWorldMatrix recalculates world matrix from hierarchy, b3dPositionEntity/RotateEntity/ScaleEntity modify local transform when parented.