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.
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 practically doesn't exist, so parenting it would have no effect. For prop_physics, it's generally better to use a prop_dynamic or prop_dynamic_override instead or use the physics constraint system.
- 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 : The Child's Solidity is suspended whilst it is parented. It will pass through walls and other solid objects.
- If the Parent is Killed, all of its current Children are also removed from the game.
- Maintains offset. Bug: The parent field does not work correctly for some entities in CS:S. Instead, use a logic_auto and call SetParent at the start of the map
- Additionally, an attachment point can be set by setting the value to parent,attachment. This behaves like SetParentAttachmentMaintainOffset.
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.
- If you leave the parameter blank, it has the same effect as the ClearParent input (see below).
- Maintains offset.
Note: there is a limit of 512 for entities which can be in a single parenting hierarchy/chain
You can also fire a SetParentAttachment input at the child-entity to attach it to a specific attachment point on its parent. The parameter is the name of the attachment point.
- The Child instantly teleports to the attachment point. This is the only method which does not maintain the offset.
You can also fire a SetParentAttachmentMaintainOffset input at the child-entity to attach it to a specific attachment point on it's parent. This works exactly the same as the SetParentAttachment input except the child-entity will maintain it's relative position to and distance from the parent at the time it is attached.
- Maintains offset, but the Child shadows/orbits the attachment point position instead of the parent's EntityOrigin.
Example : Combine_Dead_Ragdoll,anim_attachment_RH
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.
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.
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.