Struct Balls 

pub struct Balls {

    bodies: Pending<Entity, RigidBodyHandle>,
    instances: Pending<Entity, RenderEntity>,
    shows: Pending<Entity, bool>,
    retired: Pending<(), Vec<BallInstance>>,
    settled_bodies: Vec<(Entity, Settled<RigidBodyHandle>)>,
    settled_instances: Vec<(Entity, Settled<RenderEntity>)>,
    settled_shows: Vec<(Entity, Settled<bool>)>,
    settled_retired: Vec<((), Settled<Vec<BallInstance>>)>,
    expired: Vec<Entity>,
    sweep_asked: bool,
    drops: u32,
    clear: bool,
    last_snapshot: Option<Arc<GamePhysics>>,
    requests: u32,
    spawn_elapsed: f32,
    sweep_elapsed: f32,
    status_elapsed: f32,
    pub automatic_drops: bool,
    poses_sent: usize,
    showing: Vec<ShowCandidate>,
    sweeping: Vec<BallInstance>,
    despawns: Vec<RigidBodyHandle>,
    orphans: Vec<RenderEntity>,
    rng: u64,
}

The balls, living on their own entity in the gameplay world.

A body’s pose is authoritative in the physics world and drawn by the render world, so this object is the one place the two meet: it reads the handles the snapshot names off the ball entities, and publishes the resulting poses as a job.

It reaches the other worlds through the Scene its tick is handed, so it keeps no channel of its own: what it does keep is the answers waiting to be folded into the balls they name, and the buffers those answers land in, so a tick that folds nothing allocates nothing but the poses it sends.

Fields

bodies: Pending<Entity, RigidBodyHandle>

The bodies the physics world owes: one request per ball, asked under the ball it is for.

instances: Pending<Entity, RenderEntity>

The instances the render world owes: one request per ball, asked under the ball it is for.

shows: Pending<Entity, bool>

The shows the render world owes: one request per ball, asked under the ball whose instance is being shown. What it answers is whether the instance really wears its assets.

retired: Pending<(), Vec<BallInstance>>

What a sweep swept away: one request per sweep, asked under no key at all, because what it names is the whole scene rather than one ball.

settled_bodies: Vec<(Entity, Settled<RigidBodyHandle>)>

Where the answers land, reused across ticks.

settled_instances: Vec<(Entity, Settled<RenderEntity>)>

settled_shows: Vec<(Entity, Settled<bool>)>

settled_retired: Vec<((), Settled<Vec<BallInstance>>)>

expired: Vec<Entity>

The balls a request was given up on this tick, and has to reclaim.

sweep_asked: bool

Whether a sweep is still owed an answer: a second sweep asked before the first answered would have its answer dropped, and with it the instances the first one retired.

drops: u32

How many drops have been made, picking each ball’s look. The counter only orders the looks: a ball is found by its entity, not by it.

clear: bool

A clear requested but not yet consumed by the tick.

last_snapshot: Option<Arc<GamePhysics>>

The snapshot the previous tick published, to skip repeated work.

requests: u32

Ball drops requested but not yet consumed by the tick.

spawn_elapsed: f32

Seconds since the previous automatic drop.

sweep_elapsed: f32

Seconds since the previous view sweep.

status_elapsed: f32

Seconds since the previous status line.

automatic_drops: bool

Whether the spawn cadence drops balls without a panel request.

poses_sent: usize

Pose entries the last job carried, for the status line.

showing: Vec<ShowCandidate>

The balls the tick has decided to show, reused across ticks.

sweeping: Vec<BallInstance>

The instances a sweep tests against the camera’s view, reused across sweeps.

despawns: Vec<RigidBodyHandle>

The bodies a tick has to send away, kept until a send goes through so a full queue only delays the cleanup.

orphans: Vec<RenderEntity>

The instances that have nobody left to stand for, kept the same way.

rng: u64

The xorshift state for spawn placement.

Implementations

impl Balls

pub fn new(scene: &Scene) -> Self

The balls, driving the worlds their tick is handed.

pub fn queue_drop(&mut self)

Ask for one more ball on the next tick.

pub fn queue_clear(&mut self)

Ask the next tick to put every ball away.

fn random_signed(&mut self) -> f32

The next symmetric random float in -1..1.

fn drop_ball(&mut self, world: &World, state: Entity, scene: &Scene)

Spawn one ball and ask the render and physics worlds for its halves.

The look picks the collider shape as well as the mesh and material, so both worlds agree on what the drop is. The ball entity is queued first: it is what both answers name, so neither half can arrive for a ball that does not exist.

A world that refuses the request outright — its queue is full, or it has stopped — costs this drop and no more: the ball is despawned before any answer can name it.

fn clear_balls(&mut self, world: &World, scene: &Scene)

Put every ball away, bodies and instances included.

The instances are despawned rather than kept hidden: one the camera cannot see has no reason to stay. The music is left alone — the panel drives it, not the balls. A ball whose halves are still in flight is gone by the time they arrive, so they are cleaned up as orphans.

fn fold_answers( &mut self, world: &World, state: Entity, scene: &Scene, delta_seconds: f32, )

Fold the answers the other worlds sent since the last tick into the balls they name, show the ones that now have both halves, and put away the ones that waited too long.

Every wait is bounded by the same timeout, so this is the one place a request is given up on: an answer that never came names its ball, and the ball is reclaimed with whatever halves it did receive.

fn despawn_bodies(&mut self, scene: &Scene)

Despawn the bodies the tick has collected, in one job.

A despawn is idempotent, so the list is kept until a send goes through: a full queue delays the cleanup by a tick instead of losing it.

fn despawn_instances(&mut self, scene: &Scene)

Despawn the instances the tick has collected, in one job.

fn sweep_outside_view(&mut self, world: &World, scene: &Scene)

Ask the render world to despawn the shown instances the camera can no longer see. Each answer names the ball it belonged to, so the body and the ball entity go with the instance.

The sweep repeats every SWEEP_PERIOD seconds, so a ball the camera loses is put away within one period, and one whose sweep met a full queue within two.

fn publish(&mut self, world: &World, scene: &Scene)

Publish the snapshot’s poses onto the balls they name.