Population

Draws a .population asset — one mesh at every transform the asset carries, as ONE draw call per variant at any instance count.

entity.spawn("forest").component.add("Population", { source = "forest" })

The component owns what the draw costs: one GPU transform buffer and one instanced-draw registration per variant. It builds them on awake, rebuilds them when source changes or the asset's contents change on disk, and releases them on destroy — so a scene reload replaces the draws instead of stacking a second set, and despawning the entity takes them with it. A reload whose recipe and matrices are the ones the draws were built from keeps them: the write that created the asset reaches a component added right after it as such a reload, frames after the component has drawn it.

Fields

Field	Meaning
source	The .population asset to draw.
castsShadows	false renders the instances while blocking no light.

Reading what it draws

Both answers come back from the renderer, across every live registration:

local pop = entity.find("forest").component.get("Population")
pop:instanceCount()   -- instances the engine reports drawing
pop:drawCalls()       -- registrations — one per variant, at any instance count

Where it comes from

populationRef:instantiate(target?, opts?) spawns exactly this: one entity carrying this component. That is also what Asset { source = <a population> } drives, which is how a baked procedural population reaches a scene — a root record plus one child holding the reference, at any instance count.

The matrices a population carries are taken in this entity's space, so its instances stand where the recipe placed them relative to the entity and move, turn and scale with it.