Skip to content

Automatic process animation

Assign an animation to self.graph. Each process plays it independently on the existing simulation clock. A static graph() stays on the selected graphic.

require("malvado").import_globals()
local hero
local Player = process(function(self)
self.file = hero
while true do
self.graph = animation("walk")
frame()
end
end)
start(function()
hero = load_asset("hero.json")
Player({x = 100, y = 100})
end)

Use animation(name, options?), animation(library, name, options?), or library:animation(name, options?) for native atlas/Aseprite sequences. The explicit namespace is mv.graphics.animation; mv.animation is an alias. Implicit forms require the actual scheduled process and its self.file. Explicit forms work without that context. All selectors require asset support.

For FPGs, converted manifests, or atlases with individual graphic IDs, define a sequence once and reuse it:

local walk = animation(library, {7, 42, 7}, {fps = 8, loop = true})
-- Inside a process:
self.graph = walk

Custom ID lists contain 1..4096 entries; repeated and nonconsecutive IDs work. Every ID must exist. fps defaults to 8 and must be finite in 1/3600..1000. Uniform durations are rounded to the nearest microsecond. loop defaults to true and must be boolean. Named sequences preserve their native frame durations and tag direction; they accept loop, not an fps override. Aseprite repeat-count metadata retains its existing descriptive meaning; it is not a playback limit. Unknown options, names, IDs, sparse lists and invalid contexts raise errors. Per-frame custom duration tables are not part of this initial interface.

Definitions are immutable and shareable. Named lookup reuses cached identity while the definition is in use, so assigning the same animation each tick does not restart it or create a new definition. Switching to another definition starts at its first frame. Removing and then reassigning a definition starts it again. Create custom definitions once instead of rebuilding a list each tick.

A new selection displays its first frame in that tick. Subsequent running ticks advance playback, even when process-local fps reduces behavior activations. Sleeping processes remain hidden and pause playback. Frozen processes keep the current frame visible and pause playback. Wakeup resumes without catching up paused time. Non-looping sequences hold their final frame. Rendering does not advance time. Both Lua game entry forms use the same rules.

Descriptors retain their source library and frame graphics/images. Changing self.file does not reinterpret a selected sequence. A process’s graph reference keeps its definition alive; normal garbage collection releases unused definitions. The native definition owns its copied timing data. No extra scheduler is used. Headless libraries can define geometry/timing without images, with the same metadata-only limits as static graphs.

The default collider is the fixed union of every frame’s local rectangle, including pivots and trim offsets. This prevents geometry from changing during playback. It can be larger than an individual frame. Use an explicit self.collider for tighter gameplay geometry, or false to disable it. Nil restores the union. World/process collision participation, ordering and transforms remain unchanged.

The Aseprite example is a runnable named sequence with its PNG/JSON included. See the migration guide for static/manual and explicit namespace alternatives.

definition:sample(elapsed_ms) returns the reusable static frame descriptor at a finite time in 0..1e12 milliseconds. It uses the definition’s loop rule and does not change any process. Use graph(library, id) for a specific static ID. The existing animation_frame(atlas, name, elapsed_ms, loop?) sampler remains.

mv.graphics.animation_elapsed(process) returns playback milliseconds within the sequence (wrapping when it loops), or nil for a static graph. It is an advanced inspection/synchronization helper; dead or invalid handles raise errors. The update happens after scheduled process behavior, so a process observes the completed previous tick’s advance until that tick’s update finishes.

Include malvado/animation.h and link malvado_core. Create an immutable MvAnimation from copied MvAnimationFrame values (positive IDs, durations in 1..3600000000 microseconds, up to 8192 expanded entries). The larger native limit covers expanded Aseprite ping-pong tags. Each player owns a separate MvAnimationState state = {0}. Call mv_animation_advance once per running simulation tick, then mv_animation_sample for its zero-based index and ID. Keep the definition alive until all callers finish; destroy accepts NULL. Creation returns NULL for invalid input or allocation failure. Sample/advance return 0 on invalid arguments without changing output/state. Use a fixed rate in 1..1000000; reset state before changing it. Looping state stays bounded.

C games keep resource, draw and collider control explicit. Select a fixed collider that covers the sequence’s local frame bounds to use Lua’s default union policy. Native atlas helpers mv_atlas_animation_frame_count and mv_atlas_animation_frame_at expose expanded IDs and millisecond durations as copied records, without retaining caller buffers. Count is zero for a missing name; frame lookup returns 0 without changing output on invalid input.

The core definition/player has no Lua, asset-parser or graphics dependency. The binding handles implicit context, named caching and graph ownership; it uses the same native playback math as C callers. C games advance state from their existing scheduler callback, not a new animation scheduler.

The native C animation example advances player state from the shared scheduler without Lua or graphics. Its definition is caller-owned and released after the context stops its users. C-only and installed SDK checks run the example.

mv_process_animation_clock_set(ctx, process, animation, tick_rate) retains an immutable definition and resets its process-owned clock. Each successful mv_animation_retain also needs one mv_animation_destroy. The original caller can release its definition immediately after clock assignment.

The clock advances at the end of the existing native process tick while the process is running. Cadence does not change this rate. Sleep and freeze pause it without catch-up. Assignment during a tick skips that tick; assignment outside a tick advances on the next tick. Non-looping definitions hold their last frame. Each process owns independent elapsed time and fractional remainder.

Use an integer simulation rate from 1 to 1,000,000 Hz that matches the host. Fractional host rates are unsupported by this service. No timer or scheduler is created. mv_process_animation_clock_get copies state and the sampled frame; when absent it leaves both outputs unchanged and writes presence zero. Output pointers are required and must not overlap. Invalid inputs and dead/foreign handles preserve state and outputs. Clear is idempotent. Replacement, clear, process return/kill and context destruction release the retained definition.

This clock samples graph IDs as metadata. It does not load assets, select an image, change colliders or render a frame. Graph assignment/clear does not stop the clock. Use mv_process_animation_clock_clear to stop it explicitly.

Lua animated process graphs now use the native process clock. Lua no longer stores or advances a second elapsed-time record. Rendering and graphics.animation_elapsed(process) read the same native state. The clock advances after scheduler cleanup, so destructor-issued sleep/freeze signals apply before playback advances.

A new descriptor resets playback. Reassigning the same cached descriptor keeps its time, unless the native clock was cleared; that assignment attaches a new clock at zero. Assigning a non-animation graph clears Lua’s clock. For metadata-only/headless descriptors, native clock clear leaves the Lua descriptor selected but without a sampled frame or elapsed value. Loaded visual animations own a bound clock: standalone clock clear returns MV_BUSY. Clear or replace the graph to stop them. Native clients can inspect the same clock and pause it through process signals. Lua animation bounds keep their existing behavior.

C, Lua and Rust checks share tests/fixtures/process-animation.txt. The mixed C/Lua host also verifies native clear and Lua reattachment. The native cleanup fixture checks that a destructor can freeze another clock before advancement. Native image-frame assignment is available through animated image graphs. Loaded Lua animated descriptors now use that visual binding. Persistent process commands remain alpha.7 work.

mv_animation_count(definition) returns its immutable frame count, or zero for NULL. Rust exposes this as Animation::len() and is_empty().

mv_process_image_animation_bind_owned pairs an existing definition with one copied image descriptor per frame, in sequence order. The count must match. The definition’s graph IDs, durations and loop behavior stay unchanged. Success retains the definition and all images; the original owners may then be released. Optional binding-owner transfer, validation, stable union colliders and cleanup follow the native image-animation setters. Failure keeps the old graph, clock and caller ownership. This lets bindings reuse validated timing without copying or reconstructing durations and preserve definition identity across reads.

Native selection for Lua visual animations

Section titled “Native selection for Lua visual animations”

Loaded Lua animations bind their original native definition to copied visual frames. C selects the visible image at the end of the scheduler tick; Lua draws that native selection in its existing graph-before-command order. The default collider uses the same stable union as before. Durations, original graph IDs, loop behavior, process cadence, sleep/freeze and end holding stay unchanged.

Unchanged reads and repeated assignment of the same cached descriptor preserve userdata identity and playback time. A changed descriptor resets playback. Native replacement or clear is reflected on frozen processes. Definition identity is checked through the private core bridge; no public identity token or second timing record is added. Lua queries do not copy frame arrays every tick. The native draw is completed before later Lua allocations can release its borrowed image.

Frame-array scratch storage is Lua-owned until native binding copies and retains it. Lua errors and native validation failure preserve the prior native binding. Metadata-only/headless descriptors retain their existing non-visual path. Lua sample(time) remains available for explicit sampling. The mixed visual fixture checks native frame selection and IDs, cached assignment, forced GC, 5 FPS process activation with 60 Hz timing, and frozen C replacement/clear.