concinnity-engine 0.19.53

//! SpawnSystem: the per-frame entity churn. Ticks Lifetime countdowns and
//! Spawner cadences, and drains the runtime DespawnRequest / ReparentRequest /
//! SpawnRequest events. GPU slot decisions come from the engine's `RenderSlots`
//! allocator; the backend effects are recorded into the frame's op queue and
//! replayed at submission:
//!   mod.rs      system + the per-frame drains
//!   despawn.rs  subtree removal + draw-slot retirement
//!
//! Instantiating a copy of a placement is `concinnity_core::spawn`: what a copy
//! carries and when one is due is the world's, and the draw slot it lands in is
//! this crate's, handed over through the seams that module's builders take.
//!
//! Scheduled immediately before GraphicsSystem so a despawned entity is
//! already gone from the GlobalTransform x RenderHandle join when transforms
//! are pushed (it contributes nothing to any pass this same frame), and so a
//! spawn reuses slots freed this same frame before the backend grows its draw
//! list. The world clock (Lifetime + Spawner) freezes while a menu is open
//! (`MenuActive`, published by OverlaySystem earlier this tick).

use concinnity_core::components::SkeletonPose;
use concinnity_core::components::{
    DespawnRequest, EntityTarget, ReparentRequest, SpawnRequest, VisibilityRequest,
};
use concinnity_core::ecs::asset_id::AssetId;
use concinnity_core::ecs::{
    Entity, EventCursor, FrameTime, MenuActive, PipelineContext, StepResult, System,
};
use concinnity_core::render::ops::RenderOps;
use concinnity_core::transform::propagation;

use crate::ecs::ActiveRenderQueues;
use crate::gfx::render_slots::RenderSlots;

// Resolve a request target to a live entity. A named target goes through the
// world's name index; an entity-addressed one is already what the caller means,
// including entities that never had a name.
fn resolve_target(ctx: &PipelineContext, target: EntityTarget) -> Option<Entity> {
    match target {
        EntityTarget::Name(name) => resolve_name(ctx, name),
        EntityTarget::Entity(entity) => Some(entity),
    }
}

// The entity an asset id resolves to. Borrows the index only for the lookup,
// so the caller is free to take `&mut ctx` immediately after.
fn resolve_name(ctx: &PipelineContext, name: AssetId) -> Option<Entity> {
    ctx.entity_of(name)
}

mod despawn;
mod visibility;

use concinnity_core::spawn as template;

// Allocate a destination draw slot and record the backend clone for it: the
// `clone_slot` seam `template::spawn_from_template` drives. The slot index is
// known immediately (the engine owns allocation); the GPU copy applies when
// the frame's ops replay. A clone that fails at replay leaves a hidden slot,
// logged there.
fn record_clone_static(
    ops: &mut RenderOps,
    slots: &mut RenderSlots,
    src: usize,
    model: [[f32; 4]; 4],
) -> Option<usize> {
    use concinnity_core::render::draw_slot::SlotAlloc;
    let dst = slots.allocate_draw();
    let idx = match dst {
        SlotAlloc::Reuse(i) | SlotAlloc::Append(i) => i,
    };
    ops.record(move |backend| {
        if let Err(e) = backend.clone_static_draw_object(src, model, dst) {
            tracing::warn!("SpawnSystem: draw-slot clone of {} failed: {}", src, e);
        }
    });
    Some(idx)
}

// Claim a pre-reserved skinned instance and record its reveal: the
// `acquire_slot` seam `template::spawn_skinned_from_template` drives. `None`
// when the template's reserve is exhausted, exactly like the old backend
// claim.
fn record_skinned_claim(
    ops: &mut RenderOps,
    slots: &mut RenderSlots,
    template: usize,
    model: [[f32; 4]; 4],
) -> Option<usize> {
    let instance = slots.claim_skinned(template)?;
    ops.record(move |backend| backend.reveal_skinned_instance(instance, model));
    Some(instance)
}

#[derive(Debug, Default)]
pub(crate) struct SpawnSystem {
    // Cursor into the Events<DespawnRequest> queue (runtime entity despawn:
    // cn debug `despawn`, and gameplay-driven removal once that path exists).
    despawn_cmd_cursor: EventCursor,
    // Cursor into the Events<ReparentRequest> queue (runtime re-parenting:
    // cn debug `reparent`, and gameplay-driven moves once that path exists).
    reparent_cmd_cursor: EventCursor,
    // Cursor into the Events<SpawnRequest> queue (runtime entity spawn: cn debug
    // `spawn`, and gameplay-driven spawning once that path exists).
    spawn_cmd_cursor: EventCursor,
    // Cursor into the Events<VisibilityRequest> queue (runtime show/hide:
    // Behavior show/hide nodes).
    visibility_cmd_cursor: EventCursor,
}

impl SpawnSystem {
    pub(crate) fn new() -> Self {
        Self::default()
    }
}

impl System for SpawnSystem {
    fn step(&mut self, ctx: &mut PipelineContext) -> StepResult {
        // The recording surfaces graphics init published; absent means
        // graphics never inited, so there are no draw slots to churn. Taken
        // out for the drain (see `ActiveRenderQueues`) so `ctx` stays freely
        // borrowable.
        let Some(mut queues) = ActiveRenderQueues::take(ctx.resources) else {
            return StepResult::Continue;
        };
        self.drain(ctx, &mut queues.ops, &mut queues.slots);
        ActiveRenderQueues::put(ctx.resources, queues);
        StepResult::Continue
    }
}

impl SpawnSystem {
    fn drain(&mut self, ctx: &mut PipelineContext, ops: &mut RenderOps, slots: &mut RenderSlots) {
        // Per-frame delta for the time-based ticks. Clamped to non-negative so
        // a clock reset never rushes an expiry.
        let dt = ctx
            .resource::<FrameTime>()
            .copied()
            .unwrap_or_default()
            .dt
            .max(0.0);
        // Copied out of the context so the event drains below can hold scratch
        // while the cascades they feed take `ctx` mutably.
        let frame = ctx.frame;
        // The menu state OverlaySystem published earlier this tick.
        let menu_active = ctx.resource::<MenuActive>().map(|m| m.0).unwrap_or(false);

        // Timed despawn: decrement every Lifetime by this frame's dt and
        // despawn the entities whose countdown reached zero, through the
        // same cascade a DespawnRequest uses. This is the churn that
        // returns draw slots to the free list for the spawn drain below
        // to recycle. Frozen while a menu is open so the world clock
        // (timed despawns + cadence spawns below) truly pauses.
        if !menu_active {
            let expired = template::tick_lifetimes(ctx, dt);
            for &entity in expired.iter() {
                despawn::despawn_subtree(ctx, ops, slots, entity);
            }
        }

        // Runtime entity despawn: drain DespawnRequest events, resolve
        // each name to its entity, hide that entity's draw slots, and
        // remove it (and its descendants) from the ECS. Done before
        // GraphicsSystem's transform push so a despawned entity is already
        // gone from the GlobalTransform x RenderHandle join this frame and
        // contributes nothing to any pass.
        let despawn_targets = match ctx.events::<DespawnRequest>() {
            Some(events) => {
                frame.collect(events.read(&mut self.despawn_cmd_cursor).map(|r| r.target))
            }
            None => frame.collect([]),
        };
        for &target in &despawn_targets {
            if let Some(entity) = resolve_target(ctx, target) {
                despawn::despawn_subtree(ctx, ops, slots, entity);
            }
        }

        // Runtime show/hide: drain VisibilityRequest events, resolve each
        // name to its entity, and switch its subtree's Hidden tags and draw
        // slots. After the despawn drain so a request naming a just-removed
        // entity simply finds nothing to switch.
        let vis_reqs = match ctx.events::<VisibilityRequest>() {
            Some(events) => frame.collect(events.read(&mut self.visibility_cmd_cursor).copied()),
            None => frame.collect([]),
        };
        for &req in &vis_reqs {
            if let Some(entity) = resolve_target(ctx, req.target) {
                visibility::set_subtree_visibility(ctx, ops, entity, req.visible);
            }
        }

        // Runtime re-parenting: drain ReparentRequest events, resolve the
        // child + parent names to entities, and re-point the child's
        // Parent edge (recomposing world matrices). After the despawn
        // drain so a reparent naming a just-removed entity simply finds
        // nothing to move.
        let reparents = match ctx.events::<ReparentRequest>() {
            Some(events) => frame.collect(events.read(&mut self.reparent_cmd_cursor).copied()),
            None => frame.collect([]),
        };
        for &req in &reparents {
            let Some(child) = resolve_target(ctx, req.child) else {
                continue;
            };
            let parent = req.parent.and_then(|p| resolve_target(ctx, p));
            // A named-but-unresolved parent skips, so a typo never
            // silently detaches the child to a root.
            if req.parent.is_some() && parent.is_none() {
                continue;
            }
            propagation::reparent(ctx, child, parent);
        }

        // Runtime entity spawn: drain SpawnRequest events, resolve each
        // template name to its entity, and instantiate a copy at the
        // requested transform. Each cloned draw slot reuses one freed by
        // an earlier despawn / Lifetime expiry before the backend grows
        // its draw_objects, so steady spawn/despawn churn does not leak
        // slots. After the despawn / reparent drains so a spawn can reuse
        // slots freed this same frame.
        let spawn_reqs = match ctx.events::<SpawnRequest>() {
            Some(events) => frame.collect(events.read(&mut self.spawn_cmd_cursor).copied()),
            None => frame.collect([]),
        };
        for &req in spawn_reqs.iter() {
            let Some(template) = resolve_name(ctx, req.template) else {
                continue;
            };
            // A skinned template (a SkeletonPose entity) claims a
            // pre-reserved instance slot; a static one clones a draw
            // slot. Dispatch on which the template carries.
            if ctx.get::<SkeletonPose>(template).is_some() {
                template::spawn_skinned_from_template(
                    ctx,
                    template,
                    req.name,
                    req.transform,
                    req.lifetime_secs,
                    |tmpl, model| record_skinned_claim(ops, slots, tmpl, model),
                );
            } else {
                template::spawn_from_template(
                    ctx,
                    template,
                    req.name,
                    req.transform,
                    req.lifetime_secs,
                    |src, model| record_clone_static(ops, slots, src, model),
                );
            }
        }

        // Cadence-driven spawn: advance every Spawner's clock and
        // instantiate the copies now due, at the spawner's position.
        // Transient (unnamed) and Lifetime-bounded, so a steady spawner
        // churns through recycled draw slots. After the SpawnRequest
        // drain so both spawn paths reuse slots freed this frame. Frozen
        // while a menu is open so spawner clocks do not advance behind
        // the pause.
        let due_spawns = if menu_active {
            frame.collect([])
        } else {
            template::tick_spawners(ctx, dt)
        };
        for &due in due_spawns.iter() {
            let Some(template) = resolve_name(ctx, due.template) else {
                continue;
            };
            if ctx.get::<SkeletonPose>(template).is_some() {
                template::spawn_skinned_from_template(
                    ctx,
                    template,
                    None,
                    due.transform,
                    due.lifetime,
                    |tmpl, model| record_skinned_claim(ops, slots, tmpl, model),
                );
            } else {
                template::spawn_from_template(
                    ctx,
                    template,
                    None,
                    due.transform,
                    due.lifetime,
                    |src, model| record_clone_static(ops, slots, src, model),
                );
            }
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use concinnity_core::ecs::{Arena, ComponentStorage, FrameContext, Resources};
    use concinnity_core::profile::FrameProfile;
    use concinnity_host::store::blob::BlobData;

    // Build an isolated PipelineContext over fresh storage, with no backend.
    fn run<R>(body: impl FnOnce(&mut PipelineContext) -> R) -> R {
        let mut components = ComponentStorage::default();
        let mut blob = BlobData::empty();
        let mut profile = FrameProfile::default();
        let mut resources = Resources::new();
        let scratch = Arena::with_capacity(64 * 1024);
        let mut ctx = PipelineContext {
            components: &mut components,
            blob: &mut blob,
            profile: &mut profile,
            resources: &mut resources,
            frame: FrameContext::new(&scratch),
        };
        body(&mut ctx)
    }

    #[test]
    fn an_entity_target_resolves_to_itself_without_a_name_index() {
        run(|ctx| {
            let entity = ctx.components.spawn();
            assert_eq!(
                resolve_target(ctx, EntityTarget::Entity(entity)),
                Some(entity)
            );
        });
    }

    #[test]
    fn a_named_target_resolves_through_the_index() {
        run(|ctx| {
            let entity = ctx.components.spawn();
            ctx.identify(entity, AssetId(7));
            assert_eq!(
                resolve_target(ctx, EntityTarget::Name(AssetId(7))),
                Some(entity)
            );
            assert_eq!(resolve_target(ctx, EntityTarget::Name(AssetId(8))), None);
        });
    }

    #[test]
    fn a_named_target_without_a_name_index_resolves_to_nothing() {
        run(|ctx| {
            assert_eq!(resolve_target(ctx, EntityTarget::Name(AssetId(7))), None);
        });
    }
}