Skip to main content

qualia_core_db/hypermedia_authoring/
portals.rs

1//! Portals / worlds — world building, objects, portals, avatars, physics.
2//!
3//! ~20 required functions.
4
5use std::collections::BTreeMap;
6
7/// A world — a spatial environment with objects and portals.
8#[derive(Debug, Clone)]
9pub struct World {
10    pub id: String,
11    pub name: String,
12    pub bounds: WorldBounds,
13    pub objects: BTreeMap<String, WorldObject>,
14    pub portals: BTreeMap<String, Portal>,
15    pub avatars: BTreeMap<String, Avatar>,
16    pub physics_config: PhysicsConfig,
17}
18
19#[derive(Debug, Clone, Default)]
20pub struct WorldBounds {
21    pub min: [f32; 3],
22    pub max: [f32; 3],
23}
24
25#[derive(Debug, Clone, Default)]
26pub struct PhysicsConfig {
27    pub gravity: [f32; 3],
28    pub fixed_timestep: f32,
29    pub substeps: u32,
30}
31
32impl World {
33    /// Named world with `id` (default ±1000 bounds, empty).
34    pub fn new(id: &str, name: &str) -> Self {
35        Self {
36            id: id.to_string(),
37            name: name.to_string(),
38            bounds: WorldBounds {
39                min: [-1000.0; 3],
40                max: [1000.0; 3],
41            },
42            objects: BTreeMap::new(),
43            portals: BTreeMap::new(),
44            avatars: BTreeMap::new(),
45            physics_config: PhysicsConfig {
46                gravity: [0.0, -9.81, 0.0],
47                fixed_timestep: 1.0 / 60.0,
48                substeps: 1,
49            },
50        }
51    }
52
53    /// Add an object to the world.
54    pub fn add_object(&mut self, obj: WorldObject) {
55        self.objects.insert(obj.id.clone(), obj);
56    }
57
58    /// Add an inter-world portal.
59    pub fn add_portal(&mut self, portal: Portal) {
60        self.portals.insert(portal.id.clone(), portal);
61    }
62
63    /// Add a resident avatar.
64    pub fn add_avatar(&mut self, avatar: Avatar) {
65        self.avatars.insert(avatar.id.clone(), avatar);
66    }
67
68    /// Set the world's gravity vector.
69    pub fn set_gravity(&mut self, x: f32, y: f32, z: f32) {
70        self.physics_config.gravity = [x, y, z];
71    }
72
73    /// Number of objects in the world.
74    pub fn object_count(&self) -> usize {
75        self.objects.len()
76    }
77
78    /// Number of portals in the world.
79    pub fn portal_count(&self) -> usize {
80        self.portals.len()
81    }
82}
83
84/// A world object with physics properties.
85#[derive(Debug, Clone)]
86pub struct WorldObject {
87    pub id: String,
88    pub name: String,
89    pub position: [f32; 3],
90    pub rotation: [f32; 4],
91    pub scale: [f32; 3],
92    pub velocity: [f32; 3],
93    pub angular_velocity: [f32; 3],
94    pub mass: f32,
95    pub collider: Collider,
96    pub static_object: bool,
97}
98
99#[derive(Debug, Clone)]
100pub enum Collider {
101    Box { half_extents: [f32; 3] },
102    Sphere { radius: f32 },
103    Capsule { radius: f32, height: f32 },
104    Mesh { mesh_id: String },
105}
106
107impl WorldObject {
108    /// Named physics object with `id` at the origin.
109    pub fn new(id: &str, name: &str) -> Self {
110        Self {
111            id: id.to_string(),
112            name: name.to_string(),
113            position: [0.0; 3],
114            rotation: [0.0, 0.0, 0.0, 1.0],
115            scale: [1.0; 3],
116            velocity: [0.0; 3],
117            angular_velocity: [0.0; 3],
118            mass: 1.0,
119            collider: Collider::Sphere { radius: 0.5 },
120            static_object: false,
121        }
122    }
123
124    /// Set object position.
125    pub fn set_position(&mut self, x: f32, y: f32, z: f32) {
126        self.position = [x, y, z];
127    }
128
129    /// Set linear velocity.
130    pub fn set_velocity(&mut self, x: f32, y: f32, z: f32) {
131        self.velocity = [x, y, z];
132    }
133
134    /// Set mass (kg); static objects use 0 conventions per the
135    /// physics step.
136    pub fn set_mass(&mut self, mass: f32) {
137        self.mass = mass.max(0.0);
138    }
139
140    /// Assign a collider shape.
141    pub fn set_collider(&mut self, collider: Collider) {
142        self.collider = collider;
143    }
144
145    /// Apply a force for one timestep (simplified Euler integration).
146    pub fn apply_force(&mut self, fx: f32, fy: f32, fz: f32, dt: f32) {
147        if self.static_object || self.mass == 0.0 {
148            return;
149        }
150        let ax = fx / self.mass;
151        let ay = fy / self.mass;
152        let az = fz / self.mass;
153        self.velocity[0] += ax * dt;
154        self.velocity[1] += ay * dt;
155        self.velocity[2] += az * dt;
156    }
157
158    /// Step physics for this object (Euler integration with gravity).
159    pub fn step_physics(&mut self, gravity: [f32; 3], dt: f32) {
160        if self.static_object {
161            return;
162        }
163        self.velocity[0] += gravity[0] * dt;
164        self.velocity[1] += gravity[1] * dt;
165        self.velocity[2] += gravity[2] * dt;
166        self.position[0] += self.velocity[0] * dt;
167        self.position[1] += self.velocity[1] * dt;
168        self.position[2] += self.velocity[2] * dt;
169    }
170}
171
172/// A portal connecting two worlds.
173#[derive(Debug, Clone)]
174pub struct Portal {
175    pub id: String,
176    pub position: [f32; 3],
177    pub rotation: [f32; 4],
178    pub target_world: String,
179    pub target_position: [f32; 3],
180    pub radius: f32,
181    pub active: bool,
182}
183
184impl Portal {
185    /// Portal at the origin linking to `target_world`.
186    pub fn new(id: &str, target_world: &str) -> Self {
187        Self {
188            id: id.to_string(),
189            position: [0.0; 3],
190            rotation: [0.0, 0.0, 0.0, 1.0],
191            target_world: target_world.to_string(),
192            target_position: [0.0; 3],
193            radius: 1.0,
194            active: true,
195        }
196    }
197
198    /// Set portal position in the source world.
199    pub fn set_position(&mut self, x: f32, y: f32, z: f32) {
200        self.position = [x, y, z];
201    }
202
203    /// Set the target world and landing coordinates.
204    pub fn set_target(&mut self, world: &str, x: f32, y: f32, z: f32) {
205        self.target_world = world.to_string();
206        self.target_position = [x, y, z];
207    }
208
209    /// Activate the portal (traversable).
210    pub fn activate(&mut self) {
211        self.active = true;
212    }
213
214    /// Deactivate the portal.
215    pub fn deactivate(&mut self) {
216        self.active = false;
217    }
218}
219
220/// An avatar representing a user in the world.
221#[derive(Debug, Clone)]
222pub struct Avatar {
223    pub id: String,
224    pub user_did: String,
225    pub position: [f32; 3],
226    pub rotation: [f32; 4],
227    pub appearance: AvatarAppearance,
228    pub movement_mode: MovementMode,
229}
230
231#[derive(Debug, Clone, Default)]
232pub struct AvatarAppearance {
233    pub model_id: Option<String>,
234    pub height: f32,
235    pub scale: f32,
236}
237
238#[derive(Debug, Clone, Copy, PartialEq, Eq)]
239pub enum MovementMode {
240    Walking,
241    Flying,
242    Teleporting,
243    Sitting,
244}
245
246impl Avatar {
247    /// Avatar bound to `user_did` at the origin.
248    pub fn new(id: &str, user_did: &str) -> Self {
249        Self {
250            id: id.to_string(),
251            user_did: user_did.to_string(),
252            position: [0.0; 3],
253            rotation: [0.0, 0.0, 0.0, 1.0],
254            appearance: AvatarAppearance {
255                model_id: None,
256                height: 1.8,
257                scale: 1.0,
258            },
259            movement_mode: MovementMode::Walking,
260        }
261    }
262
263    /// Teleport the avatar to a position.
264    pub fn move_to(&mut self, x: f32, y: f32, z: f32) {
265        self.position = [x, y, z];
266    }
267
268    /// Set locomotion mode (walk/fly/etc).
269    pub fn set_movement_mode(&mut self, mode: MovementMode) {
270        self.movement_mode = mode;
271    }
272
273    /// Set avatar model id, height, and scale.
274    pub fn set_appearance(&mut self, model_id: &str, height: f32, scale: f32) {
275        self.appearance.model_id = Some(model_id.to_string());
276        self.appearance.height = height;
277        self.appearance.scale = scale;
278    }
279}
280
281#[cfg(test)]
282mod tests {
283    use super::*;
284
285    #[test]
286    fn world_creation() {
287        let world = World::new("w1", "My World");
288        assert_eq!(world.name, "My World");
289        assert_eq!(world.object_count(), 0);
290    }
291
292    #[test]
293    fn world_add_object() {
294        let mut world = World::new("w1", "World");
295        world.add_object(WorldObject::new("o1", "Cube"));
296        assert_eq!(world.object_count(), 1);
297    }
298
299    #[test]
300    fn world_add_portal() {
301        let mut world = World::new("w1", "World");
302        world.add_portal(Portal::new("p1", "w2"));
303        assert_eq!(world.portal_count(), 1);
304    }
305
306    #[test]
307    fn world_set_gravity() {
308        let mut world = World::new("w1", "World");
309        world.set_gravity(0.0, -20.0, 0.0);
310        assert_eq!(world.physics_config.gravity, [0.0, -20.0, 0.0]);
311    }
312
313    #[test]
314    fn object_physics_step() {
315        let mut obj = WorldObject::new("o1", "Ball");
316        obj.set_position(0.0, 10.0, 0.0);
317        obj.step_physics([0.0, -9.81, 0.0], 1.0 / 60.0);
318        // After one step, velocity should be -9.81/60, position should drop.
319        assert!(obj.velocity[1] < 0.0);
320        assert!(obj.position[1] < 10.0);
321    }
322
323    #[test]
324    fn object_apply_force() {
325        let mut obj = WorldObject::new("o1", "Ball");
326        obj.set_mass(2.0);
327        obj.apply_force(10.0, 0.0, 0.0, 1.0);
328        // a = F/m = 5, v = 5 * 1 = 5
329        assert!((obj.velocity[0] - 5.0).abs() < 0.01);
330    }
331
332    #[test]
333    fn object_static_no_physics() {
334        let mut obj = WorldObject::new("o1", "Wall");
335        obj.static_object = true;
336        obj.set_position(0.0, 10.0, 0.0);
337        obj.step_physics([0.0, -9.81, 0.0], 1.0);
338        assert_eq!(obj.position, [0.0, 10.0, 0.0]);
339    }
340
341    #[test]
342    fn portal_creation() {
343        let portal = Portal::new("p1", "w2");
344        assert_eq!(portal.target_world, "w2");
345        assert!(portal.active);
346    }
347
348    #[test]
349    fn portal_activate_deactivate() {
350        let mut portal = Portal::new("p1", "w2");
351        portal.deactivate();
352        assert!(!portal.active);
353        portal.activate();
354        assert!(portal.active);
355    }
356
357    #[test]
358    fn avatar_creation() {
359        let avatar = Avatar::new("a1", "did:q42:user1");
360        assert_eq!(avatar.user_did, "did:q42:user1");
361        assert_eq!(avatar.movement_mode, MovementMode::Walking);
362    }
363
364    #[test]
365    fn avatar_move() {
366        let mut avatar = Avatar::new("a1", "user1");
367        avatar.move_to(10.0, 0.0, 5.0);
368        assert_eq!(avatar.position, [10.0, 0.0, 5.0]);
369    }
370
371    #[test]
372    fn avatar_set_appearance() {
373        let mut avatar = Avatar::new("a1", "user1");
374        avatar.set_appearance("model_a", 1.9, 1.1);
375        assert_eq!(avatar.appearance.height, 1.9);
376        assert_eq!(avatar.appearance.scale, 1.1);
377    }
378}