instances.from_elements (procNode)

Turn elements into a piece set, ready for instances.to_points to place. The elements are the entities io.import answers, or any points that carry parent and a pose.

local piece = asset.resolve("@builtin::bundles.lamp_post", "bundle")
local set = g.instances.from_elements({ elements = g.io.import({ source = piece }) })
local copies = g.instances.to_points({ points = slots, pieces = set.pieces })

How it works

• Which elements become pieces. Every element that carries a Mesh becomes one piece point. The point holds that Mesh and the element's Material, or the default material when the element names none.
  • io.import gives an entity drawn by a Model its Mesh and Material (see io.import).
  • The mesh stays a reference to the mesh asset. Nothing is read onto the device until the copies are drawn.
• Pose. A piece stands at the pose its element stands at once every parent's pose is applied, root first: position, then rotation, then per-axis scale.
  • An element that draws nothing still contributes its pose to its children, so a root entity and the offsets its children carry are applied.
  • instances.to_points applies each piece's own pose after the target point's, so the whole set stands at every target point.
• Names. Each piece carries its element's name, and the same text under group, which instances.to_points matches target points on when match is on. The pieces are named by the entity names, not by the mesh assets they hold.
• Bounds. The detail bounds is { min, max, center, size }: the box the pieces' meshes span, each mesh's own box carried through its piece's pose. It is the piece set's extent in its own space, read without spawning it. A mesh asset's box is the one renderer.mesh.bounds answers, and a geometry's is the box of its points.
• What is left out. An element that carries no Mesh (a root, an empty) is not a piece. report lists, one { element, note } row each:
  • an element left out for carrying another component (a Light, a SkinnedModel, a script component);
  • a component a piece leaves behind on an element that does draw;
  • a pose that turns under a parent scaled unevenly between its axes, where the composed pose keeps the rotation and the per-axis scale and drops the shear between them;
  • a mesh whose box is unknown;
  • every row the elements' own reported detail carries (what io.import could not put on an element).
• No mesh at all. Elements of which none carries a Mesh are refused, naming how many were given.

Inputs

• elements (Points). The elements: io.import of an asset, or points carrying parent (the number of the element they hang under, -1 for none), P, orient, scale and, on the ones that draw, Mesh and Material.
• group (String). Default "variant". The attribute each piece's element name is written under. Empty writes none.

Outputs

• pieces: the piece set, one point per drawn element: Mesh, Material, P, orient, scale, name, id and the group attribute; the detail bounds.
• report: the { element, note } rows described above.