Skip to main content
nebulaModding docs
Nebula home

kit.replay

Recording and playing back poses, puppets posed from data, input files played frame-exactly, rewind of the player and chosen actors.

#About kit.replay

The kit.replay module of LumaKit gives you recording and playing back poses, puppets posed from data, input files played frame-exactly, rewind of the player and chosen actors.

To use the module, add lumakit to the needs of your mod's luma.json and write:

LumaScript
use kit.replay

#How the module works

Poses and inputs recorded a world step at a time, tracks written as bytes that read the same on every platform, puppets posed from a track, an input track played back step for step, the game's random numbers seeded, and rewind of the player and chosen actors. Handles are small structs; their functions are also module functions (replay.stop_recording(r), replay.pose_at(t, n)). A track's data lives in LumaKit, counted for the mod that made it, and goes with that mod or at free(); a Track value is its number and its length. What is recorded, each world step (on step: the game's own steps, so a track is frame-exact at any speed): What.Player the player's place, turn (from the player's own front and up), animation name and frame, and form What.Actor an actor's place, turn (its rotation), animation frame What.Inputs what the game read from player 0's controls that step (svc.input game), and the player's pose at the first step: the state the reads moved the player from Bytes: "LKT1", little-endian, floats as IEEE 754 single: the same file on every platform. A pose alone is the same form with one pose. Playing inputs back: svc.input.inject (the calling mod needs the permission input.inject:), one step's read set before each step; the player put at the track's first pose (place, turn, animation and its frame) in the step the first read is taken, so the reads move the player from the state they were recorded from (the frame of the animation steers the player's walk: the same reads from another frame drift apart); the track's end, the mod stopping or stop() on the pending ends the injection. Rewind keeps the last seconds of steps of each thing asked for (at most 60 s) and back(n) puts each n steps back: the player by place and matrix, an actor by place and rotation; the world around them is not rewound.

The module's source is lumakit/source/replay.lum.

#Declarations

Name Kind Description
What Enum
Pose Struct
Track Struct
Recorder Struct
Puppet Struct
Rewind Struct
current_pose Function The pose of w now. An actor that is gone, and What.Inputs (which has no pose): a script error.
pose_at Function The pose of step frame of a pose track; none past its end, for an input track or a freed one.
free Function The track's data given up now (it goes with its mod otherwise).
pose_encode Function A pose as bytes (a track of one pose), and back; none when the bytes are no pose.
pose_decode Function
encode Function A track as bytes; empty for a track that is not the calling mod's any more.
decode Function A track from bytes, counted for the calling mod; none when they are no track (wrong head, cut short, a number out of range, more than an hour of steps).
record Function Recording of w from the next world step, for the calling mod, until stop or discard (or an hour).
stop_recording Function The recording ends: its track (stop is a word of the language, so the function is stop_recording). A recorder stopped or discarded before gives an empty track.
discard Function The recording ends and its steps are thrown away.
puppet Function A puppet showing look, for the calling mod; at most 15 at once for all mods: past that, and when the stage cannot make one, an empty handle whose alive() is false and whose other calls do nothing.
set_pose Function The puppet placed as the pose says: its place, its turn, its animation at the pose's frame (started when the name changes and the puppet's model has it).
pose Function The puppet at a track's step; hidden past the track's end (shown again by a step inside it).
view Function The puppet's object, for a mod that draws on it (draw.inst opacity) or reads it. After remove(): a script error .
alive Function
remove Function The puppet killed with the game's own kill; may be called again.
play_inputs Task An input track played back for the calling mod: each world step reads the track's next step instead of the player's controls. Ends at the track's end; an input track playing before ends first. The calling mod needs the permission input.inject.
seed Function The game's random numbers from n from now on, for as long as the calling mod is on: MR::getRandom answers a 32-bit generator of the kit's own (xorshift), the same on every platform, so a run of recorded inputs meets the same numbers again.
rewind Function The last seconds (at most 60) of each of what kept from now on, for the calling mod. What.Inputs is not kept.
put_player Function The player put at a pose: place, turn and animation (a recorded start, a rewind). Nothing where no player exists.
back Function Each thing put back frames steps, or as far as is kept: the steps gone back. What is kept after that point is dropped (the future is recorded anew). A step's pose is kept as the step begins, so the newest kept is one step before now: frames back is the kept pose that many from the end.
end Function Nothing is kept any more; may be called again.

#What

LumaScript
pub enum What { Player, Actor(a: ref<LiveActor>), Inputs }

#Pose

LumaScript
pub struct Pose { at: vec3, rotation: quat, action: text, frame: f32, form: text? = none }

#Track

LumaScript
pub struct Track {
    id: u32
    frames: u32
    fn pose_at(self, frame: u32) -> Pose? { return pose_at(self, frame) }
    fn encode(self) -> bytes { return encode(self) }
    fn free(self) { free(self) }
}

#Recorder

LumaScript
pub struct Recorder {
    id: u32
    fn stop_recording(self) -> Track { return stop_recording(self) }
    fn discard(self) { discard(self) }
}

#Puppet

LumaScript
pub struct Puppet {
    id: u32
    fn pose(self, t: Track, frame: u32) { pose(self, t, frame) }
    fn set_pose(self, p: Pose) { set_pose(self, p) }
    fn view(self) -> LiveActor { return view(self) }
    fn remove(self) { remove(self) }
    fn alive(self) -> bool { return alive(self) }
}

#Rewind

LumaScript
pub struct Rewind {
    id: u32
    fn back(self, frames: u32) -> u32 { return back(self, frames) }
    fn end(self) { end(self) }
}

#current_pose

LumaScript
pub fn current_pose(w: What) -> Pose

The pose of w now. An actor that is gone, and What.Inputs (which has no pose): a script error.

#pose_at

LumaScript
pub fn pose_at(t: Track, frame: u32) -> Pose?

The pose of step frame of a pose track; none past its end, for an input track or a freed one.

#free

LumaScript
pub fn free(t: Track)

The track's data given up now (it goes with its mod otherwise).

#pose_encode

LumaScript
pub fn pose_encode(p: Pose) -> bytes

A pose as bytes (a track of one pose), and back; none when the bytes are no pose.

#pose_decode

LumaScript
pub fn pose_decode(b: bytes) -> Pose?

#encode

LumaScript
pub fn encode(t: Track) -> bytes

A track as bytes; empty for a track that is not the calling mod's any more.

#decode

LumaScript
pub fn decode(b: bytes) -> Track?

A track from bytes, counted for the calling mod; none when they are no track (wrong head, cut short, a number out of range, more than an hour of steps).

#record

LumaScript
pub fn record(w: What) -> Recorder

Recording of w from the next world step, for the calling mod, until stop or discard (or an hour).

#stop_recording

LumaScript
pub fn stop_recording(r: Recorder) -> Track

The recording ends: its track (stop is a word of the language, so the function is stop_recording). A recorder stopped or discarded before gives an empty track.

#discard

LumaScript
pub fn discard(r: Recorder)

The recording ends and its steps are thrown away.

#puppet

LumaScript
pub fn puppet(look: model) -> Puppet

A puppet showing look, for the calling mod; at most 15 at once for all mods: past that, and when the stage cannot make one, an empty handle whose alive() is false and whose other calls do nothing.

#set_pose

LumaScript
pub fn set_pose(p: Puppet, pose: Pose)

The puppet placed as the pose says: its place, its turn, its animation at the pose's frame (started when the name changes and the puppet's model has it).

#pose

LumaScript
pub fn pose(p: Puppet, t: Track, frame: u32)

The puppet at a track's step; hidden past the track's end (shown again by a step inside it).

#view

LumaScript
pub fn view(p: Puppet) -> LiveActor

The puppet's object, for a mod that draws on it (draw.inst opacity) or reads it. After remove(): a script error .

#alive

LumaScript
pub fn alive(p: Puppet) -> bool

#remove

LumaScript
pub fn remove(p: Puppet)

The puppet killed with the game's own kill; may be called again.

#play_inputs

LumaScript
pub task play_inputs(t: Track)

An input track played back for the calling mod: each world step reads the track's next step instead of the player's controls. Ends at the track's end; an input track playing before ends first. The calling mod needs the permission input.inject.

#seed

LumaScript
pub fn seed(n: u32)

The game's random numbers from n from now on, for as long as the calling mod is on: MR::getRandom answers a 32-bit generator of the kit's own (xorshift), the same on every platform, so a run of recorded inputs meets the same numbers again.

#rewind

LumaScript
pub fn rewind(what: list<What>, seconds: f32) -> Rewind

The last seconds (at most 60) of each of what kept from now on, for the calling mod. What.Inputs is not kept.

#put_player

LumaScript
pub fn put_player(p: Pose)

The player put at a pose: place, turn and animation (a recorded start, a rewind). Nothing where no player exists.

#back

LumaScript
pub fn back(r: Rewind, frames: u32) -> u32

Each thing put back frames steps, or as far as is kept: the steps gone back. What is kept after that point is dropped (the future is recorded anew). A step's pose is kept as the step begins, so the newest kept is one step before now: frames back is the kept pose that many from the end.

#end

LumaScript
pub fn end(r: Rewind)

Nothing is kept any more; may be called again.

#Further reading