Gameplay API guides
C callbacks, Lua coroutines and Rust futures use the same process scheduler. Use the API reference to find the exact public names, types and platform requirements.
Run and stop processes
Section titled “Run and stop processes”| Language | Start and advance | Finish or cancel |
|---|---|---|
| C | Create an MvContext, add callbacks and drive ticks from the host. |
Return a completion result or send a kill signal. Release owned handles and destroy the context after the last tick. See the C contract. |
| Lua | Define processes with mv.process and start them with mv.start or in a returned game table. Call frame() inside a process to yield. |
Return from the process or signal it using its handle. The runner handles shutdown. See Lua processes. |
| Rust | Use Game::new and Game::spawn. Drive native ticks from the host. Call process.frame().await inside the future. |
Return Ok(()) or send a kill signal. Dropping Game cancels any remaining processes. See Rust processes. |
Cancel a process by its handle. An owned C or Rust handle can record the end reason after the process ends. Attached children end with their owner. A detached child can continue until its own completion or game shutdown. See the process cleanup contract and runner timing.
Organize a level
Section titled “Organize a level”Use one process for the game controller and one for the active level. Start the level’s enemies and effects from the level process so they end with it. Keep the score and other state that lasts across levels in the controller. End the current level before starting the next one. A process created during a tick starts on the next tick.
The process tree example shows the lifetime pattern in
Lua. The controller starts a group with two children, then calls
kill_tree with the group handle. The same pattern can clean
up a level when the player finishes it or returns to a menu.
Choose a reference
Section titled “Choose a reference”| Task | C and Lua reference | Rust reference |
|---|---|---|
| Open a window, draw and read input | Platform functions, drawing, keyboard and text input | Window, drawing, input |
| Load assets and animate sprites | Asset functions, images, animations | Atlas, FPG, cameras and animation |
| Use text and fonts | Text | Fonts |
| Move, follow and check collisions | Cameras, collision and worlds | Cameras, collision and worlds |
| Play sounds and music | Audio | Rust audio |
Use the C headers for signatures and status values. Use the Lua flat exports and namespace reference for module names, constants and methods. Build the Rust API reference locally with the installed SDK command.
Keep resources alive
Section titled “Keep resources alive”Release direct C image, font and audio objects before closing the service that created them. Pair each managed retain with a release. In Lua, a reachable userdata value or queued command can keep the native resource alive after the process ends. In Rust, safe wrappers retain the service they need and release their references when dropped. See resource lifetime for sharing, transfer, failure and cleanup rules.
Choose a runtime and target
Section titled “Choose a runtime and target”Run scheduler-only code with the C core or the default Rust crate. Use
malvado run --headless for a Lua project that needs no window or audio
device. The Lua runner owns its loop. C and Rust callers drive their own
input, audio and rendering.
Use a matching desktop SDK for native projects. The Android CLI export target is arm64 from macOS or Linux. See SDK and projects and the platform matrix for format, toolchain and device limits. The language matrix describes which features each API provides.