spawning

Flock spawning patterns for the boids simulation — sphere and grid distributions. Each function spawns Model-bearing entities and returns an array of seed records (SpawnSeed) describing each entity's id, position, and initial velocity. Callers feed the seeds into BoidData:add to build the parallel simulation buffers.

Exports

• Spawn.sphere(origin: OriginVec, radius: number, count: number, model: string, opts: SpawnOpts?) -> { SpawnSeed } — spawn count boids uniformly distributed by volume inside a sphere. Initial velocities are random unit-sphere directions scaled by speeds in [1, 3].
• Spawn.grid(origin: OriginVec, spacing: number, cols: number, rows: number, layers: number?, model: string, opts: SpawnOpts?) -> { SpawnSeed } — spawn boids on a 3D grid centred on origin. Initial velocities are small random offsets so the grid disperses on first tick.

Types:

• OriginVec = { x?: number, y?: number, z?: number, [number]: number? } — map or array form accepted; missing components fall back to 0.
• SpawnOpts = { scale?: number } — uniform entity scale (default 0.5).
• SpawnSeed = { entityId: string, px, py, pz: number, vx, vy, vz: number } — one entry per spawned boid.

Usage

local Spawn = require("@builtin::modules.boids.spawning")

local seeds = Spawn.sphere({ x = 0, y = 5, z = 0 }, 10, 50, "cube")
for _, s in ipairs(seeds) do
    boidData:add(s.entityId, s.px, s.py, s.pz, s.vx, s.vy, s.vz)
end

Notes

• Both functions call entity.spawn(name) with "boid_" .. index and add a Model component to the returned proxy. The names are not unique across multiple calls — if you spawn multiple flocks the entity-name collisions are handled by the engine (entities are identified by id, not name).
• Spawning happens immediately on each call; no batching, no deferred registration.
• These helpers are used by Flock.new and Flock:addBoids in the parent boids.module.