propagateTransforms

Computes the WorldTransform of every entity that has a parent and a Transform.

Only entities in a hierarchy get a WorldTransform. An entity without a parent has none: its Transform already is in world space, and the renderer reads it directly. A child combines its parent's world transform P with its own transform L: its position is L's position scaled by P's scale, rotated by P's rotation and moved by P's position; its rotation is the sum of both rotations; its scale is the product of both scales, axis by axis. P is the parent's Transform when the parent is a root, and the identity when the parent has no Transform, so such a child's world transform is a copy of its own. Parents are computed before their children. A child gets a WorldTransform the first time it is seen with a parent and a Transform, and loses it once it has no Transform; World.removeParent removes it at once.

The engine calls this twice per frame, after the fixed update stage and before collision detection, and again after the late update stage and before rendering, so users normally never call it. The cost grows with the number of entities in hierarchies, not with the number of entities, so a world without parents costs next to nothing. Allocates nothing once every child has its WorldTransform.

Samples

val world = World()
val ship = world.create()
val gun = world.create()
world.add(ship, Transform, Transform(x = 100f, y = 50f, scaleX = 2f, scaleY = 2f))
world.add(gun, Transform, Transform(x = 10f, y = 0f))
world.setParent(gun, ship)

world.propagateTransforms()
assertPrints(world.get(gun, WorldTransform), "WorldTransform(x=120.0, y=50.0, rotation=0.0, scale=2.0x2.0)")

world.get(ship, Transform).x = 0f
world.propagateTransforms()
assertPrints(world.get(gun, WorldTransform).x, "20.0")

// Only entities with a parent get a WorldTransform: the ship's Transform is already in world space.
assertPrints(world.getOrNull(ship, WorldTransform), "null")
world.removeParent(gun)
assertFalse(world.has(gun, WorldTransform))