MobHierarchyMixin

Qualified name: algan.animatable\_base.mob\_hierarchy.MobHierarchyMixin

class MobHierarchyMixin

Bases: object

Parent, child and descendant management, mixed into Mob.

A Mob’s children follow its transforms: move, rotate, scale or recolor a parent and the change propagates down. Use add_children() to build a hierarchy, or a Group when you just want to handle several Mobs as one.

The hierarchy is a graph, not a tree: a Mob may have several parents and then accumulates all of their changes, which is what lets two overlapping Groups each arrange the same member. It is read when an animation is recorded, not when it plays, so re-parenting between two recorded animations leaves the first one alone – see Grouping Mobs.

Methods

add_children	Attach Mobs as children, so they follow this Mob's transforms.
add_parent	Attach this Mob to another as one of its children.
get_children	Get this Mob's children, optionally reaching further down the hierarchy.
get_descendants	Get every Mob at or below this one, flattened into one list.
remove_child	Detach a child so it stops following this Mob's transforms.
remove_parent	Detach this Mob from one of its parents, so it stops following that Mob's transforms.
replace_children	Swap out this Mob's children for a different set.

add_children(*mobs)

Attach Mobs as children, so they follow this Mob’s transforms.

Once attached, moving, rotating, scaling or recoloring this Mob carries the children along. Adding a Mob that is already a child does nothing.

Animation

Not animated: the hierarchy changes immediately, and only affects animations recorded from here on. Children keep their own spawn state – attaching an unspawned Mob does not spawn it.

Parameters:

*mobs – Mobs to attach. Nested iterables are flattened, so mob.add_children([a, b]) and mob.add_children(a, b) are the same.

Returns:

This Mob, so calls can be chained.

Return type:

Mob

Raises:

• TypeError – If any item is not an Animatable.

• HierarchyError – If a Mob appears twice, is its own child, belongs to another Scene, or the change would create a cycle.

add_parent(other_mob)

Attach this Mob to another as one of its children.

The mirror image of add_children() called from the child’s side: child.add_parent(parent) and parent.add_children(child) build the same link, so this Mob follows other_mob’s transforms from here on. A Mob may have several parents, and then accumulates every one of their changes. Re-adding an existing parent does nothing.

Animation

Not animated: the hierarchy changes immediately, and only affects animations recorded from here on.

Parameters:

other_mob (Mob) – The Mob to become a parent of this one.

Returns:

This Mob, so calls can be chained.

Return type:

Mob

Raises:

• TypeError – If other_mob is not an Animatable.

• .HierarchyError – If other_mob is this Mob, belongs to another Scene, or is already somewhere below it – any of which would make the graph a cycle.

get_children(generation=0, include_components=True)

Get this Mob’s children, optionally reaching further down the hierarchy.

Parameters:

• generation (int) – How many levels down to collect: 0 for direct children, 1 for grandchildren, and so on – each level replaces the one above rather than adding to it. Defaults to 0.

• include_components (bool) – Whether to include children that are structural components of the Mob (the parts a shape builds itself from) as opposed to Mobs you added. Defaults to True.

Returns:

The children at that generation. The Mobs are live, not copies.

Return type:

list[Mob]

See also

get_descendants()

Every level at once, flattened.

get_descendants(include_self=True)

Get every Mob at or below this one, flattened into one list.

Parameters:

include_self (bool) – Whether this Mob is the first element of the list. Defaults to True.

Returns:

This Mob (unless excluded) followed by its children, their children, and so on. The Mobs are live, not copies.

Return type:

list[Mob]

remove_child(mob)

Detach a child so it stops following this Mob’s transforms.

The child stays in the scene and keeps its own state; it is simply no longer driven by this Mob. Any other parents it has are untouched, so it goes on following those.

Animation

Not animated: the hierarchy changes immediately, and only affects animations recorded from here on.

Parameters:

mob (Mob) – The child to detach.

Returns:

This Mob, so calls can be chained.

Return type:

Mob

Raises:

ValueError – If mob is not a child of this Mob.

remove_parent(other_mob)

Detach this Mob from one of its parents, so it stops following that Mob’s transforms.

The reverse of add_parent(), and drops both halves of the link – this Mob leaves other_mob’s children as well. Any other parents it has are untouched, and it stays in the scene with its own state. Removing a Mob that is not a parent does nothing.

Animation

Not animated: the hierarchy changes immediately, and only affects animations recorded from here on.

Parameters:

other_mob (Mob) – The Mob to stop treating as a parent.

Returns:

This Mob, so calls can be chained.

Return type:

Mob

replace_children(mobs, *, link_parents=True)

Swap out this Mob’s children for a different set.

Children that are not in the new set have their link to this Mob dropped, so they stop following its transforms; they are not despawned and remain in the scene on their own.

Animation

Not animated: the hierarchy changes immediately, and only affects animations recorded from here on. Already-recorded animation is unchanged.

Parameters:

• mobs – The new children. Nested iterables are flattened, so a list of Groups is accepted.

• link_parents (bool) – Whether to maintain the children’s upward links to this Mob. Defaults to True; pass False only when the caller manages those links itself.

Returns:

This Mob, so calls can be chained.

Return type:

Mob

Raises:

• TypeError – If any item is not an Animatable.

• HierarchyError – If a Mob appears twice, is its own child, belongs to another Scene, or the change would create a cycle.