bevy

What the Bevy plugin adds for scripts. Bevy’s own types (like bevy::Transform) live in this module too, but they come from your app’s type registry and aren’t listed here. Components, resources, and messages covers what scripts can call on them.

Hooks

Each of these registers a function for the plugin to run. f can be a function by name, a method, or a closure. Its parameters are filled by type on every run, each with a component of the entity or a resource, and a T? parameter accepts an entity that has no T. Trailing parameters with defaults keep them.

Call these from a script’s top-level code, which runs once each time the script compiles. Registering faults from inside a hook, when f isn’t a function, or when a parameter is neither a component nor a resource. Hooks explains how they run.

fn fall(t: bevy::Transform) {
    t.translation.y -= 9.8 * bevy::time::delta();
}

bevy::update(fall);

start

fn start(f)

Registers f to run once for each entity with the script, before its first update. If it faults, or the entity is missing a component it needs, it’s tried again the next frame.

update

fn update(f)

Registers f to run every frame, in Bevy’s Update schedule.

fixed_update

fn fixed_update(f)

Registers f to run every fixed tick, in Bevy’s FixedUpdate schedule.

stop

fn stop(f)

Registers f to run when an entity’s script stops, which is when its Script is removed or replaced, or when the entity despawns. A despawned entity has no components left, so f should only take resources.

bevy::Entity

struct Entity(int)

An entity in the Bevy world, held as the bits of its id. Scripts get one from spawn, bevy::ecs::me, a component’s entities(), or an Entity field of another type.

spawn

fn spawn() -> Entity

Spawns an entity with no components and returns it.

let brick = bevy::Entity::spawn();
let placed = bevy::Transform::default();
placed.translation.x = 120.0;
bevy::Transform::insert(brick, placed);

despawn

fn despawn(self) -> bool

Despawns the entity, and returns false if it was already gone.

exists

fn exists(self) -> bool

Returns true if the entity hasn’t been despawned.

bevy::ecs

me

fn me() -> Entity

Returns the entity the running hook is for. Faults outside a hook, like in a script’s top-level code.

attach_script

fn attach_script(entity: Entity, path: str)

Gives entity the script at path (relative to assets/), replacing any script it already had. Faults if the entity doesn’t exist.

let ball = bevy::Entity::spawn();
bevy::ecs::attach_script(ball, "scripts/ball.mim");

bevy::time

delta

fn delta() -> float

Returns the seconds since the last frame. Inside fixed_update, it’s the length of a fixed tick instead.

elapsed

fn elapsed() -> float

Returns the seconds since the app started. Inside fixed_update, it follows the fixed clock.

bevy::input

Keys and mouse buttons are Bevy’s own enums, bevy::KeyCode and bevy::MouseButton.

bevy::update(|t: bevy::Transform| {
    if bevy::input::pressed(bevy::KeyCode::KeyA) {
        t.translation.x -= 300.0 * bevy::time::delta();
    }
});

pressed

fn pressed(button: KeyCode) -> bool

Returns true while the key button is held down.

just_pressed

fn just_pressed(button: KeyCode) -> bool

Returns true during the frame the key button went down.

just_released

fn just_released(button: KeyCode) -> bool

Returns true during the frame the key button came up.

mouse_pressed

fn mouse_pressed(button: MouseButton) -> bool

Returns true while the mouse button button is held down.

mouse_just_pressed

fn mouse_just_pressed(button: MouseButton) -> bool

Returns true during the frame the mouse button button went down.

mouse_just_released

fn mouse_just_released(button: MouseButton) -> bool

Returns true during the frame the mouse button button came up.

cursor

fn cursor() -> Vec2?

Returns the cursor’s position in 2D world space, as the first camera sees it. It’s null while the cursor is outside the primary window. The result is a Vec2 from std::math.

bevy::log

info

fn info(message: str)

Logs message at the info level through Bevy’s logger.

warn

fn warn(message: str)

Logs message at the warn level through Bevy’s logger.

error

fn error(message: str)

Logs message at the error level through Bevy’s logger.