syren 0.6.0

A parallel Rust framework for agent-based models with ECS storage, scheduling, messaging, environments, and optional GPU execution.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56

//! Lifecycle hooks for agent spawn and despawn events.
//!
//! ## Design
//!
//! Hooks are Boxed closures stored inside [`crate::agents::AgentTemplate`]. They are
//! **never** called inside `System::run`. Instead, they are invoked by the
//! model orchestration layer (e.g. `Model::tick`) after
//! `apply_deferred_commands` completes and the resolved entity handles are
//! available.
//!
//! Hook invocation is wired through the model-owned
//! [`AgentRegistry`](super::registry::AgentRegistry). The model flushes spawn
//! and despawn hooks after each deferred command drain reports the entities it
//! created or removed.
//!
//! ## Constraints
//!
//! * Hooks **must not** be called while a query iteration is live.
//! * Hooks receive an [`ECSReference`] and an [`Entity`]; they may enqueue
//!   further [`crate::Command`]s via [`ECSReference::defer`] but must not call
//!   [`ECSReference::with_exclusive`].
//! * Both hook types are `Send + Sync` so that [`crate::agents::AgentTemplate`] remains
//!   `Send + Sync`.

use crate::engine::entity::Entity;
use crate::engine::manager::ECSReference;

/// Called after an agent entity is resolved from a `Command::Spawn`.
///
/// Receives a shared [`ECSReference`] (for deferred commands or reads) and
/// the freshly resolved [`Entity`] handle.
///
/// # Timing
///
/// Invoked by `AgentRegistry::flush_spawn_hooks` **after**
/// `apply_deferred_commands` returns.  Never called inside a running system.
pub type SpawnHook = Box<dyn Fn(ECSReference<'_>, Entity) + Send + Sync>;

/// Called after a batch of agent entities is resolved from a batch spawn.
pub type SpawnBatchHook = Box<dyn Fn(ECSReference<'_>, &[Entity]) + Send + Sync>;

/// Called after a tagged despawn command is applied.
///
/// Receives an [`ECSReference`] and the entity that was destroyed. The hook may
/// enqueue additional commands via [`ECSReference::defer`] but must not perform
/// immediate structural mutations.
///
/// # Timing
///
/// Invoked by `AgentRegistry::flush_despawn_hooks` after
/// `apply_deferred_commands` reports a tagged despawn. Never called inside a
/// running system.
pub type DespawnHook = Box<dyn Fn(ECSReference<'_>, Entity) + Send + Sync>;

/// Called after a batch of tagged agent despawns is applied.
pub type DespawnBatchHook = Box<dyn Fn(ECSReference<'_>, &[Entity]) + Send + Sync>;