Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

0.25.0 - Typed arguments

See the migration guide for breaking changes.

Typed arguments

Functions taking callbacks, names or tables of options are documented as exactly what they take, so the Lua language server checks the calls:

/// Spawns an enemy
#[derive(ScriptData)]
#[script_data(namespace = "game")]
struct SpawnOptions {
    name: String,
    speed: Option<Speed>,
    on_death: Option<FunctionOf<fn(V<Entity>) -> ()>>,
}

#[derive(ScriptData)]
#[script_data(namespace = "game")]
enum Speed {
    Named(ByName<Pace>),     // "Slow" | "Fast"
    Exact(f32),              // 2.5
}
game.spawn({ name = "goblin", speed = "Fast", on_death = function(entity) end }) -- `entity` is an ecs.Entity
game.spawn({ name = "goblin", speed = "fast" })   -- not a Pace
game.spawn({ speed = 2 })                         -- missing `name`
game.spawn({ name = "goblin", sped = 2 })         -- no field `sped`
  • FunctionOf<fn(A) -> R>: a function, documented as fun(arg1: A): R, so the parameters of a callback written inline are typed.
  • ByName<E>: a unit variant of a reflected enum, passed by its name as in Rust and documented as the names, "Slow" | "Fast".
  • #[derive(ScriptData)]: plain data, copied to and from scripts rather than referenced.
    • A struct is a map of its fields (a table in Lua, an object in Rune). Each field converts by its own type, so it can be a callback, a name or a union. Unknown, missing and mistyped fields are errors naming the field.
    • An enum whose variants each hold one value is the value of any of them, and may hold itself.
    • Both are data types in the book and the LAD file (LadType::Data): a class of the fields or an alias of the union in Lua.
  • ValueOf<A, R> takes the conversion: ValueOf<A, ScriptValue> is any value, typed as whatever was passed, i.e. fn boxed(v: ValueOf<A, ScriptValue>) -> V<MyBox<A>> gives a MyBox<integer> for boxed(5).

See Typed arguments.

Native types

Vectors (Vec2, Vec3, Vec4, Vec3A, DVec2, DVec3, IVec2, IVec3, UVec2, UVec3) and Quat values made by functions are stored by Lua and Rune themselves, and functions read their arguments without converting them to ScriptValues. Transform components are native handles: world.get_component(e, Transform) reads and writes the component directly (t.translation.x = 5 included). Other types opt in with script_native!, see Writing Bindings. Scripts behave the same: native values are copies like the values functions return, and work wherever references to vectors do.

Other changes

  • Unions only try the types which could convert a value (FromScript::could_convert), instead of building an error for each type which can’t.
  • Nested unions are documented as one union, Union<A, Union<B, C>> is A | B | C.
  • In the Lua language server files, function types in unions and lists are parenthesized: fun(): a | b returns the union.