Skip to main content

minkowski_space/
config.rs

1use crate::collision::{CollisionGroup, CollisionGroupId, CollisionGroupPair};
2use crate::m_vector::MVector;
3use std::collections::BTreeSet;
4use vector2d::Vector2D;
5
6/// Errors returned when a physical or world configuration violates the
7/// simulation invariants.
8#[derive(Clone, Debug, PartialEq)]
9pub enum ConfigError {
10    /// A configuration value is not finite (`NaN`, positive infinity, or negative infinity).
11    NonFinite { field: &'static str },
12    /// A configuration value is negative although only non-negative values are valid.
13    Negative { field: &'static str },
14    /// A configuration value must be greater than zero.
15    NonPositive { field: &'static str },
16    /// A velocity is equal to or greater than the speed of light.
17    SuperluminalVelocity,
18    /// The selected operation is not supported by the object or world.
19    UnsupportedOperation(&'static str),
20    /// A collision pair refers to a group that is not defined in the configuration.
21    InvalidCollisionGroupPair,
22}
23
24impl std::fmt::Display for ConfigError {
25    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
26        match self {
27            Self::NonFinite { field } => write!(f, "{field} must be finite"),
28            Self::Negative { field } => write!(f, "{field} must not be negative"),
29            Self::NonPositive { field } => write!(f, "{field} must be greater than zero"),
30            Self::SuperluminalVelocity => write!(f, "velocity must be subluminal"),
31            Self::UnsupportedOperation(op) => write!(f, "unsupported operation: {op}"),
32            Self::InvalidCollisionGroupPair => {
33                write!(f, "collision pair references an undefined group")
34            }
35        }
36    }
37}
38impl std::error::Error for ConfigError {}
39
40fn valid_number(value: f64, field: &'static str) -> Result<(), ConfigError> {
41    if !value.is_finite() {
42        return Err(ConfigError::NonFinite { field });
43    }
44    Ok(())
45}
46fn valid_velocity(v: Vector2D<f64>) -> Result<(), ConfigError> {
47    valid_number(v.x, "velocity.x")?;
48    valid_number(v.y, "velocity.y")?;
49    if v.length_squared() >= crate::MAX_SAFE_SPEED_SQUARED {
50        return Err(ConfigError::SuperluminalVelocity);
51    }
52    Ok(())
53}
54
55/// The integration strategy used by an object.
56#[derive(Copy, Clone, Debug, Eq, PartialEq)]
57pub enum MotionMode {
58    /// The trajectory is fixed at creation and can be integrated analytically.
59    AlwaysConstantVelocity,
60    /// Velocity and proper acceleration may be changed through the world API.
61    Dynamic,
62}
63
64/// The initial position of a registered object.
65#[derive(Copy, Clone, Debug, PartialEq)]
66pub enum StartPosition {
67    /// An explicit spacetime position in laboratory coordinates.
68    Position(MVector<f64>),
69    /// A spatial position at the world's current laboratory time.
70    PositionNow(Vector2D<f64>),
71}
72
73/// Immutable physical configuration used when spawning an object.
74#[derive(Copy, Clone, Debug)]
75pub struct ObjectConfig {
76    /// Initial position in laboratory coordinates.
77    pub position: StartPosition,
78    /// Initial velocity in units where the speed of light is `1`.
79    pub velocity: Vector2D<f64>,
80    /// Object radius in spatial units.
81    pub radius: f64,
82    /// Integration strategy used by the object.
83    pub motion_mode: MotionMode,
84    /// Collision group assigned to the object.
85    pub collision_group: CollisionGroup,
86}
87
88impl ObjectConfig {
89    /// Validates all values exposed by the public fields.
90    pub fn validate(&self) -> Result<(), ConfigError> {
91        match self.position {
92            StartPosition::Position(p) => {
93                valid_number(p.time, "position.time")?;
94                valid_number(p.pos.x, "position.x")?;
95                valid_number(p.pos.y, "position.y")?;
96            }
97            StartPosition::PositionNow(p) => {
98                valid_number(p.x, "position.x")?;
99                valid_number(p.y, "position.y")?;
100            }
101        }
102        valid_velocity(self.velocity)?;
103        valid_number(self.radius, "radius")?;
104        if self.radius < 0.0 {
105            return Err(ConfigError::Negative { field: "radius" });
106        }
107        Ok(())
108    }
109
110    /// Creates and validates a constant-velocity object configuration.
111    ///
112    /// Returns an error when the initial velocity or position is invalid.
113    pub fn try_at_position_with_const_speed(
114        initial_pos: Vector2D<f64>,
115        initial_velocity: Vector2D<f64>,
116    ) -> Result<Self, ConfigError> {
117        let config = Self::at_position_with_const_speed(initial_pos, initial_velocity);
118        config.validate().map(|_| config)
119    }
120
121    /// Creates a constant-velocity object configuration at a spatial position.
122    ///
123    /// The position is interpreted at the world's current laboratory time.
124    /// Call [`Self::validate`] before using untrusted input.
125    pub fn at_position_with_const_speed(
126        initial_pos: Vector2D<f64>,
127        initial_velocity: Vector2D<f64>,
128    ) -> ObjectConfig {
129        ObjectConfig {
130            position: StartPosition::PositionNow(initial_pos),
131            velocity: initial_velocity,
132            radius: 0.0,
133            motion_mode: MotionMode::AlwaysConstantVelocity,
134            collision_group: CollisionGroup::Empty,
135        }
136    }
137
138    /// Creates a dynamic object configuration at a spatial position.
139    ///
140    /// The initial velocity and acceleration are zero.
141    pub fn at_position(initial_pos: Vector2D<f64>) -> ObjectConfig {
142        ObjectConfig {
143            position: StartPosition::PositionNow(initial_pos),
144            velocity: Default::default(),
145            radius: 0.0,
146            motion_mode: MotionMode::Dynamic,
147            collision_group: CollisionGroup::Empty,
148        }
149    }
150    /// Creates a dynamic object configuration at the spacetime origin.
151    ///
152    /// The object is assigned the supplied collision group.
153    pub fn default_with_group(collision_group: CollisionGroup) -> ObjectConfig {
154        ObjectConfig {
155            position: StartPosition::Position(Default::default()),
156            velocity: Default::default(),
157            radius: 0.0,
158            motion_mode: MotionMode::Dynamic,
159            collision_group,
160        }
161    }
162}
163
164impl Default for ObjectConfig {
165    fn default() -> Self {
166        Self {
167            position: StartPosition::Position(Default::default()),
168            velocity: Default::default(),
169            radius: 0.0,
170            motion_mode: MotionMode::Dynamic,
171            collision_group: CollisionGroup::Empty,
172        }
173    }
174}
175
176/// Configuration of a simulation world.
177#[derive(Clone, Debug)]
178pub struct WorldConfig {
179    /// Observer proper-time step used by dynamic integration.
180    pub proper_time_step: f64,
181    /// Spatial size of a cell used by broad-phase collision detection.
182    pub spatial_hash_cell_size: f64,
183    /// Collision groups defined for this world.
184    pub collision_groups: BTreeSet<CollisionGroupId>,
185    /// Pairs of groups that are allowed to collide.
186    pub collision_pairs: BTreeSet<CollisionGroupPair>,
187    /// Collision group assigned to the observer.
188    pub observer_collision_group: CollisionGroup,
189    /// Collision radius assigned to the observer.
190    pub observer_collision_radius: f64,
191}
192
193impl WorldConfig {
194    /// Creates a default world configuration with the supplied collision pairs.
195    ///
196    /// Each tuple contains the numeric IDs of two collision groups. The groups
197    /// are added to the configuration automatically.
198    pub fn with_collisions(collisions: Vec<(u32, u32)>) -> Self {
199        let mut res = Self::default();
200        collisions.into_iter().for_each(|(l, r)| {
201            let l = CollisionGroupId(l);
202            let r = CollisionGroupId(r);
203            res.collision_groups.insert(l);
204            res.collision_groups.insert(r);
205            res.collision_pairs.insert(CollisionGroupPair(l, r));
206        });
207        res
208    }
209
210    /// Allocates a group identifier owned by this configuration.
211    ///
212    /// The returned ID is inserted into [`Self::collision_groups`] and can be
213    /// used to construct a [`CollisionGroup::CollisionGroup`].
214    pub fn define_collision_group(&mut self) -> CollisionGroupId {
215        let id = CollisionGroupId(
216            self.collision_groups
217                .iter()
218                .map(|group| group.0)
219                .max()
220                .map_or(0, |id| id.saturating_add(1)),
221        );
222        self.collision_groups.insert(id);
223        id
224    }
225
226    /// Validates the physical and numerical invariants of this configuration.
227    pub fn validate(&self) -> Result<(), ConfigError> {
228        valid_number(self.proper_time_step, "proper_time_step")?;
229        if self.proper_time_step <= 0.0 {
230            return Err(ConfigError::NonPositive {
231                field: "proper_time_step",
232            });
233        }
234        valid_number(self.spatial_hash_cell_size, "spatial_hash_cell_size")?;
235        if self.spatial_hash_cell_size <= 0.0 {
236            return Err(ConfigError::NonPositive {
237                field: "spatial_hash_cell_size",
238            });
239        }
240        valid_number(self.observer_collision_radius, "frame_collision_radius")?;
241        if self.observer_collision_radius < 0.0 {
242            return Err(ConfigError::Negative {
243                field: "frame_collision_radius",
244            });
245        }
246        if self.collision_pairs.iter().any(|pair| {
247            !self.collision_groups.contains(&pair.0) || !self.collision_groups.contains(&pair.1)
248        }) {
249            return Err(ConfigError::InvalidCollisionGroupPair);
250        }
251        Ok(())
252    }
253}
254
255impl Default for WorldConfig {
256    fn default() -> Self {
257        Self {
258            proper_time_step: 1.0 / 120.0,
259            spatial_hash_cell_size: 1.0,
260            collision_groups: BTreeSet::new(),
261            collision_pairs: BTreeSet::new(),
262            observer_collision_group: CollisionGroup::Empty,
263            observer_collision_radius: 0.0,
264        }
265    }
266}