Entity Hierarchy (parenting)

When a group of entities are parented together, they form a rigid movement hierarchy family which will move together as if all the entities were one physical object. Each child-entity will follow its parent's movement.

A simple example would be parenting a light_dynamic to a lamp prop so the light becomes part of the lamp and moves with it.

The child-parent relationship is always defined in the object properties of the child-entity. The parent-entity doesn't have any say in choosing its followers. This leads to the rather awkward use of 'parenting' as a reflexive verb throughout the documentation, eg "must be parented", "parent the child to the parent", "entities can have parents", etc.

All entities can have parents, though many entities do not include it in their FGD entries, and it may not necessarily function correctly. For example, prop_physics behave oddly when parented because they are physically simulated objects, and a logic_relay for example isn't visible or moves on its own, so parenting it would have little effect. For prop_physics, it's generally better to use a prop_dynamic or prop_dynamic_override instead or use the physics constraint system.

Warning: There is a limit of 512 entities permitted to be in a single parenting hierarchy/chain.

Todo: What happens if this limit is exceeded?

Child Behavior

• The Offset is the distance (and any rotational offset) between the Child and Parent entities at the time the relationship is activated. Whilst the offset is maintained, the Child will move parallel to its parent's movements, and "orbit" the parent's origin at the offset distance when the parent rotates. Only the SetParentAttachment input changes the offset; it instantly "teleports" the child to the parent's attachment point and holds it there instead.

• Collision : Physics simulation will no longer occur for children, causing them to potentially pass through walls or other solid objects if the parent moves them there. Scripted movements such as animations or brush-based entities will still occur, so you can chain different brush entities together to form a complex moving contraption.

• If the Parent is Killed, all of its current Children are also removed from the game.

• If a child does not define behavior for player interaction (+USE) or touching these will be relayed to the parent. This allows you to parent a prop_dynamic to a func_button and then have the player +USE the model to interact with the button, for example.

Keyvalues

parentname

To create a child-parent relationship between two entities, set the child-entity's parentname keyvalue to the parent-entity's targetname.

• Maintains offset.
• Additionally, an attachment point can be set by setting the value to parent,attachment. This can be used to have an entity follow an animated part of the model, such as the Howitzer handle in . It behaves like SetParentAttachmentMaintainOffset.
  For example: Howitzer_prop,Handle.
  Note:This way of setting attachment is supported only for parentname keyvalue and not for SetParent input.

The Howitzer handle, as separate prop, following the "Handle" $attachment of the Howitzer model.

updatechildren

Keyvalue available on prop_dynamic since Left 4 Dead.

If set to 1 the entity will update touches for any children that are attached to its attachment points as this prop animates. This allows SetParentAttached triggers or func_brushes to touch properly.

Confirm:Is this taken care of in src13 by other means?

Inputs

SetParent

You can also fire a SetParent input at the child-entity to change its child-parent relationship.

• Use the targetname of the new parent as the input parameter to make the child follow the new parent. (can also be a special targetname such as !activator.)
• If you leave the parameter blank, it has the same effect as the ClearParent input (see below).
• Maintains offset.

SetParentAttachment

Takes name of a specific attachment point that exists on its parent as parameter. If used on entity without a parent it prints warning to console and does nothing.
Use at least a 0.02 second delay between SetParent and SetParentAttachment input, to ensure they run in the right order.

• The child entity will be teleported to the location and rotation of the attachment point.

Your child entity will align its location and axis with the parent models attachment location and axis. You can find out the attachment location and axis by loading the model in HLMV or by command ent_attachments.
The only way to change this is by either recompiling the parent model to change its attachments, or recompiling the child model to change its entire rotation.

A Personality core in Portal following an $attachment of the GLaDOS model using SetParentAttachment.
As you can see, the Sphere has its axis shown in hammer, GLaDOS has her attachments axis shown in HLMV.
The sphere aligns its axis with the axis of GLADOS' Attachment point.

SetParentAttachmentMaintainOffset

Identical to SetParentAttachment input with a difference that the entity is not teleported to the specified attachment point.

ClearParent

You can also fire a ClearParent input at the child-entity to remove its child-parent relationship. This simply 'unparents' or 'detaches' the child-entity from its current parent, so the child is then free to move (or not) independently of its former parent.

KillHierarchy

If you fire a KillHierarchy input at the parent-entity, it removes the parent-entity and all of its children from the world.

• If you fire a Kill input at the parent-entity, its children will be detected and eventually also destroyed, logging a warning in the console. This happens almost immediately, but it may be possible for other logic or outputs to be executed before they're fully cleaned up.

Alternatives

A few "alternatives" exist to the standard entity hierarchy system. They may be suitable for specific purposes or are specialized to a particular set of entities.

• Physics Constraints are designed to constrain physically simulated entities like prop_physics. They can wobble, break, and do various other cool things.
• logic_measure_movement causes an entity to mimic the movements of another with room for flexibility. You could use this to move entities that cannot usually be parented, like logic entities or physics props.
• prop_dynamic_ornament takes advantage of bonemerging, the same system weapons use to attach to their owners' hands. This still uses parenting under the hood.

Programmers can also use FollowEntity() to take advantage of bonemerging without having to use prop_dynamic_ornament.

External links

Map example .VMF (NPC_Citizen holding a small pipe) - By Madcow

• https://twhl.info/index.php/vault/view/5027

Map example .VMF and .BSP (Improved Alternative methods) - By gtamike_TSGK

• http://gtamike.tsgk.com/gtamike_TSGK/test_area_parent_attachments.rar

See also

• Attachment_points_for_HL2 - List of attachment points to parent