Skip to content

Native collision and static worlds in Rust

malvado::collision wraps the delivered C collision API without another collision algorithm or physics scheduler. It works without Lua, raylib, or a window. Run the complete headless example after mise run test-rust:

Terminal window
MALVADO_SDK_PREFIX="$PWD/build-rust/Debug/relocated sdk" mise exec -- \
cargo run --manifest-path bindings/rust/Cargo.toml -p malvado --example world

Create an owned World, add rectangles, and move an explicit shape/transform:

use malvado::collision::{Rect, Shape, Transform, World};
let mut world = World::new()?;
world.add_rect(Rect { x: 10.0, y: 0.0, width: 10.0, height: 10.0 })?;
let shape = Shape::circle(1.0)?;
let mut position = Transform { y: 5.0, ..Default::default() };
let contact = world.move_by(shape, &mut position, 100.0, 0.0)?;
assert_eq!(position.x, 9.0);
assert_eq!(contact.hit, Some(1));
# Ok::<(), malvado::Error>(())

Shape constructors validate through native geometry. with_offset returns a new immutable shape. Transform defaults to position/angle zero and scale one. shape.overlaps(transform, other, other_transform) tests transformed shapes; tangency is not overlap. Rect::contains includes the lower edges and excludes the upper edges. Invalid dimensions, offsets, transforms, or unrepresentable numeric geometry return Error::InvalidArgument.

World rectangle IDs start at one and follow insertion order. add_rect copies the rectangle and requires exclusive mutable access. Error::WorldInsert preserves the C API’s combined failure for invalid input, allocation failure, or capacity exhaustion; it does not claim to distinguish those causes. Failed insertion leaves existing geometry and later IDs unchanged.

query returns the first overlapping rectangle ID or None. sweep returns a copied Sweep with optional hit ID, permitted fraction, and contact normal. move_by updates only the supplied Transform, through the same C world move operation. On failure it leaves that value unchanged. Initial overlap, unsupported or unrepresentable sweeps and nonfinite displacement return InvalidArgument. On success without a hit, fraction is one. Move along the unblocked axis in a separate call to slide; there is no hidden movement loop in this wrapper.

World owns its native allocation and drops it once. It has no engine dependency and can outlive a context. It cannot be sent to another thread. A completed world can be shared through the native Resource<World> manager; resource shared access does not permit later geometry mutation.

handle.set_collider(shape, transform) copies explicit values into the native process. Update it after changing that transform. clear_collider() is idempotent for a live process. collides_with(other) rejects a foreign context and excludes self-collision. first_collision(type_id) returns an optional owned handle; collisions(type_id) returns owned handles in creation order. Type zero selects all types. Missing colliders give no hits; sleeping and frozen processes are included. Dead or closed handles return the corresponding error. Failed collider updates leave the previous native collider unchanged.

Fixed registration does not follow visual-property changes. New processes now derive colliders from selected primitive or sprite graphs by default; see the bound selection contract below. Safe sprite assignment uses the process sprite API. See the collision contract for the shared geometry and native limits.

New process handles use their assigned primitive or sprite graph for collision geometry. Current native x/y, angle and scale apply on every collision query. Changing a property or graph, clearing a graph, or calling contextual world movement takes effect without rendering or another engine tick. Queries need no render frame. Sprite assignment retains its window; primitive-only contexts need no graphics. Animated sprite graphs use a fixed local union of all frame bounds. The visible frame can change without changing that default collider.

Use actor.bind_collider(Some(shape))? to select a copied local override that follows those same properties. actor.bind_collider(None)? restores selected graph geometry. A local override survives graph clearing and replacement. clear_collider() disables all selection until the next bind or fixed set. set_collider(shape, transform) retains its independent fixed-transform contract. A failed bind preserves the previous selection.

use malvado::{Game, graphic::{Graphic, Geometry, Color}};
let game = Game::new()?;
let a = game.spawn(Default::default(), |p| async move {loop {p.frame().await;}})?;
let b = game.spawn(Default::default(), |p| async move {loop {p.frame().await;}})?;
let graphic = Graphic { geometry: Geometry::circle(2.0)?, color: Color {r:255,g:255,b:255,a:255} };
a.set_graphic(graphic)?;
b.set_graphic(graphic)?;
b.set_position(3.0, 0.0)?;
assert!(a.collides_with(&b)?);
a.clear_collider()?;
assert!(!a.collides_with(&b)?);
a.bind_collider(None)?;
assert!(a.collides_with(&b)?);
# Ok::<(), malvado::Error>(())

Bind validates the current selected shape/transform and returns InvalidArgument for invalid geometry or numeric limits. Invalid bound source properties make queries return InvalidArgument; explicit invalid targets also return that error. Type queries skip invalid candidates. Repairing properties restores bound geometry on the next query. Dead/closed handles return NotFound/Closed. Sleep and freeze retain collision geometry. No shape pointer, process resource, activation, tick or extra scheduler is retained or created.

bound_collider.rs shares the C/Lua golden trace and checks property/graph changes, world writeback, local override, clear/restore, invalid-source recovery, local offsets/rotation, fixed-transform independence and failed binds, plus handle lifetime errors. The installed SDK consumer calls bind with and without a local shape; the signature probe rejects an incompatible SDK.

world.query_selected(&actor)? uses the collider selected by native process state. world.move_selected(&actor, dx, dy)? moves with that same geometry. Primitive graphs and local overrides follow current native properties. Disabled selection or no graph means free movement and no query hit. Nothing is retained and no tick or future activation is added.

use malvado::{Game, collision::{World, Rect}, graphic::{Graphic, Geometry, Color}};
let game = Game::new()?;
let actor = game.spawn(Default::default(), |p| async move {loop {p.frame().await;}})?;
actor.set_graphic(Graphic {geometry:Geometry::circle(1.0)?,color:Color {r:255,g:255,b:255,a:255}})?;
actor.set_position(0.0, 5.0)?;
let mut world = World::new()?;
world.add_rect(Rect {x:10.0,y:0.0,width:10.0,height:10.0})?;
assert_eq!(world.move_selected(&actor, 100.0, 0.0)?.hit, Some(1));
assert_eq!(actor.position()?, (9.0, 5.0));
assert_eq!(world.query_selected(&actor)?, None);
# Ok::<(), malvado::Error>(())

Fixed registrations query their registered transform. Selected movement translates both that transform and native process position by the permitted displacement, preserving their offset in native double arithmetic. Ordinary visual-property writes still leave a fixed registration independent. Native validates both destinations before committing either, including process position overflow when the collider destination itself is valid.

Invalid selected geometry, unsupported sweep, initial overlap or numeric input returns InvalidArgument; dead/closed handles return NotFound/Closed. Failure preserves process/collider positions and selection. The borrowed World can outlive the engine, as before. Sleep/freeze do not block an explicit move. Image/animation graph selection uses the delivered process sprite API. Existing query_process/move_process calls keep their explicit optional-shape contract, including free movement with None; they do not move fixed registrations.

selected_world.rs checks every selection mode, rotated/scaled geometry, sliding, fixed-offset translation/independence, invalid-input/geometry and overflow atomicity, missing graphs and world/handle lifetimes. The existing C/Lua/Rust world golden trace now uses selected operations. The bounded SDK world sample and relocated installed consumer use these native APIs.

world.query_process(&actor, Some(shape))? uses the actor’s native x/y, angle and scale. It returns the first overlapping world rectangle ID or None. world.move_process(&actor, Some(shape), dx, dy)? atomically updates the actor’s x/y with the same native movement used by Lua. Pass None to disable geometry and apply free movement. A registered process collider is not selected or updated implicitly. Explicit shape selection keeps ownership and side effects clear when the caller supplies its own geometry.

use malvado::{Game, Error};
use malvado::collision::{World, Rect, Shape};
let game = Game::new()?;
let actor = game.spawn(Default::default(), |p| async move { p.frame().await; Ok(()) })?;
actor.set_position(0.0, 5.0)?;
let mut world = World::new()?;
world.add_rect(Rect { x: 10.0, y: 0.0, width: 10.0, height: 10.0 })?;
let contact = world.move_process(&actor, Some(Shape::circle(1.0)?), 100.0, 0.0)?;
assert_eq!(actor.position()?, (9.0, 5.0));
assert_eq!(contact.hit, Some(1));
# Ok::<(), Error>(())

Calls borrow the world and handle, copy optional geometry, and retain nothing. They do not run a tick or poll a future. Sleep and freeze do not prevent an explicit move. Failed movement preserves position; native errors return InvalidArgument, NotFound, or Closed. Displacement must be finite and within the native DBL_MAX / 16 limit. World can still outlive the engine; using a closed process handle returns Closed. Shape-independent movement ignores angle/scale, including nonpositive scale.