Skip to content

Latest commit

 

History

133 Commits

Folders and files

Repository files navigation

SpriteLoop for Defold

Defold extension version

For SpriteLoop desktop app bugs and feature requests, use the SpriteLoop app issue tracker.

SpriteLoop for Defold adds native playback for .spla animation packages. It includes a spriteloop component, editor integration, Bob builders, Lua helpers, and a small example project.

SpriteLoop component in Defold

Install

Add a tagged GitHub archive URL to your Defold project dependencies:

https://github.com/Balkan-Ram-Games/spriteloop-defold/archive/refs/tags/v0.16.0-alpha.zip

Then fetch libraries from the Defold editor. The archive exposes the extension folder at spriteloop/, which lets Defold discover spriteloop/ext.manifest.

After the first install, restart the Defold editor before opening collections or game objects that already contain embedded SpriteLoop components. Defold can fetch the extension files without errors, but already-loaded editor resources may not recognize the newly registered custom component type until the editor starts again.

Editor compatibility

The editor plugin is validated with Defold 1.13.2, 1.14.0 and 1.14.1. It uses the shader reflection pipeline available since 1.12.2 and accepts both the older resource loader arguments and the shared load context introduced in 1.14.0. Defold 1.14.1 needs this release or newer: earlier extension versions fail to load SpriteLoop resources with its rewritten resource loader.

Older editors may require rebuilding pluginSpla.jar with their matching Bob version: the current generated protobuf classes cannot load in Defold 1.12.2.

Use

Create a SpriteLoop component and point its package field at a .spla file in your project. Scripts can control the component through:

local spriteloop = require "spriteloop.spriteloop"

function init(self)
    spriteloop.play_anim("#robot", "idle", { loop = true })
end

The animation argument may be either the exported animation ID or the display name. Exact IDs are matched before names.

The included example project shows an embedded SpriteLoop component, movement script, collision object, collection proxy load/unload flow, and cache debug UI. The example project has separate consume_events() and listen() event scenes so each queue-draining approach can be tested in isolation.

Animation Events

SpriteLoop emits frame events when playback enters a frame. Starting an animation emits events on frame 0, normal playback emits events for every crossed frame, and set_frame() or set_time() emits only events on the destination frame. You can either drain the event queue yourself with consume_events(), or register Lua callbacks and drain/dispatch the queue with dispatch_events().

Event emission is enabled by default. Disable it for an entire playback session with:

spriteloop.play_anim("#robot", "idle", {
    loop = true,
    emit_events = false,
})

For direct positioning, emit_events affects only that operation and does not change whether subsequent playback emits events:

spriteloop.set_frame("#robot", 10, { emit_events = false })
spriteloop.set_time("#robot", 0.5, { emit_events = false })

Direct positioning never emits events from intermediate frames. Explicitly selecting the current frame emits that frame's events again unless disabled. Playing or seeking never removes events that were already queued.

Use consume_events() when you want explicit control over batching, ordering, or delayed handling:

local spriteloop = require "spriteloop.spriteloop"

function update(self, dt)
    for _, event in ipairs(spriteloop.consume_events("#robot")) do
        print(event.name, event.data, event.animation_id, event.animation_name, event.frame, event.source_frame)
    end
end

consume_events() returns all pending events since the previous consume call and clears the queue for that component. Pending events remain available until consumed or displaced by the configured queue limit.

Use listen() when you prefer callback-style gameplay code:

local spriteloop = require "spriteloop.spriteloop"

function init(self)
    self.step_listener = spriteloop.listen("#robot", "step", function(event)
        print("step at frame", event.frame)
    end)
end

function update(self, dt)
    spriteloop.dispatch_events("#robot")
end

function final(self)
    spriteloop.unlisten("#robot", self.step_listener)
end

listen() is a Lua wrapper over the same native event queue. Call dispatch_events(url) regularly, usually from update(), to consume queued events and invoke matching callbacks. consume_events(url) and dispatch_events(url) both drain the same queue, so do not call both for the same component in the same frame unless you expect the second call to return no events. Use unlisten(url) to remove every listener for a component, unlisten(url, event_name) to remove every listener for one event name, or unlisten(url, listener_id) to remove one listener returned by listen().

If you use listeners and still want to inspect the consumed events manually, use the table returned by dispatch_events():

function update(self, dt)
    local events = spriteloop.dispatch_events("#robot")

    for _, event in ipairs(events) do
        print(event.name, event.frame)
    end
end

Each event table contains:

  • event_name and name: the exported event name.
  • data: the exported event payload string, or an empty string.
  • animation_id: the exported ID of the animation that emitted the event.
  • animation_name: the display name of the animation that emitted the event.
  • frame: the zero-based frame index inside the exported animation.
  • source_frame: the original editor/source frame number.

The same API is available from spriteloop.spla for manually loaded handles: spla.consume_events(handle).

Each component and low-level handle has an independent bounded event queue. Set the maximum number of pending events in game.project:

[spriteloop]
max_pending_events = 256

The default is 256. Zero and negative values also use 256. When the queue is full, SpriteLoop drops the oldest event, keeps the newest event, increments dropped_event_count, and logs one warning for that player. get_info() exposes pending_event_count, max_pending_events, and dropped_event_count.

Skins and Part Variants

A SpriteLoop component selects the exported default skin by default. You can select another initial skin in the Defold editor. Runtime scripts can change the active skin and override individual part variants through the component-oriented Lua API:

local spriteloop = require "spriteloop.spriteloop"

function init(self)
    local component = "#robot"

    -- Applies the skin's part variants and visibility settings.
    spriteloop.set_skin(component, "blue_robot")

    -- Overrides one part after applying the skin.
    spriteloop.set_variant(component, "head", "head_helmet")

    spriteloop.play_anim(component, "idle", { loop = true })
end

Skin and part APIs accept runtime keys, display names, and the internal IDs exported in the .spla package. Exact IDs are matched first, then keys, then names:

local changed = spriteloop.set_skin(url, skin_id_or_name)
local changed = spriteloop.set_variant(url, part_key_or_name, variant_key_or_name)
local changed = spriteloop.clear_variant(url, part_key_or_name)
spriteloop.clear_variants(url)
local transform = spriteloop.get_part_transform(url, part_key_or_name)
  • set_skin() returns true when the skin ID or name exists.
  • set_variant() returns true when the part resolves and the variant resolves to a variant belonging to that part. Pass "default" (case-insensitive) to clear that part's manual override.
  • clear_variant() returns true when the part resolves.
  • clear_variants() removes every manual part override.

The Default option shown for a part in SpriteLoop is not normally an exported variant. It means that the part has no manual variant override. Use set_variant(url, part, "default") or clear_variant() to select this state for one part, and clear_variants() to restore it for every part. Real variant lookup happens first. If a variant actually uses default as its name, key, or ID, that variant is selected instead; use clear_variant() to reset that part.

Failed animation, skin, part, or variant lookups log a Defold warning while still returning false.

Manual part variants take precedence over the active skin. Clearing an override restores the variant selected by the active skin, or the part's base image when the skin does not override it. Changing skins does not clear manual part overrides.

Part transforms

Query the current resolved transform of any image or Empty Part by id, runtime key, or display name:

local transform = spriteloop.get_part_transform("#player", "right_hand")
local centered = spriteloop.get_part_transform("#player", "right_hand", {
    origin = "center",
})

The returned table contains position and scale vectors, rotation in degrees, a skew vector in degrees, and opacity. Coordinates are centered, Y-up SpriteLoop-component-local values before the component, game object, or standalone handle transform is applied. The default origin is the authored part pivot. origin = "center" returns the transformed center of the base image rectangle; it intentionally does not follow variant or sprite-state dimensions. For Empty Parts, pivot and center return the same position.

The values match the discrete frame currently rendered. Missing parts or parts not present in that frame return nil and log a warning. Use an Empty Part when an attachment needs a custom location rather than an existing image-part pivot. The standalone API provides the same query as spla.get_part_transform(handle, part, options).

Use get_info() to discover the skins and variants available in the loaded package:

local info = spriteloop.get_info("#robot")

print("active skin index", info.skin_index) -- zero-based, or -1

for _, skin in ipairs(info.skins) do
    print(skin.id, skin.name, skin.override_count)
end

for _, variant in ipairs(info.variants) do
    print(variant.part_key, variant.key, variant.name, variant.id, variant.rotation, variant.z_offset)
end

info.skins and info.variants are Lua arrays. skin_index is the native zero-based package index and is -1 when no skin is active.

The same skin and part functions are also available from the low-level spriteloop.spla module for handles returned by spla.load():

local spla = require "spriteloop.spla"
local handle = spla.load("/character.spla")

spla.set_skin(handle, "blue_robot")
spla.set_variant(handle, "head", "head_helmet")

Runtime Tint

Scripts can tint a whole SpriteLoop character at runtime. Runtime tint is an RGB multiplier applied on top of the tint authored in the .spla package, and defaults to white:

local spriteloop = require "spriteloop.spriteloop"

spriteloop.set_tint("#robot", 1, 0.45, 0.45)
spriteloop.clear_tint("#robot")

Tint channels are clamped to the 0..1 range. Changing tint frequently on many components can increase vertex cache misses and vertex buffer uploads because SpriteLoop applies the multiplier through per-vertex color.

The same API is available from spriteloop.spla for manually loaded handles:

spla.set_tint(handle, 0.5, 0.8, 1)
spla.clear_tint(handle)

Masks in custom render scripts

Masks work automatically with the built-in renderer. If you use masks with a custom render script, call prepare_masks() once at the start of its update():

local spriteloop = require "spriteloop.spriteloop"

function update(self, dt)
    spriteloop.prepare_masks()
    -- Your existing rendering code follows.
end

One call handles all SpriteLoop components. Projects without masks need no extra setup. Call this only from render-script update(), never from game-object or GUI scripts, init(), on_message() or on_reload().

Repeated masked animations automatically share cached results to improve performance. Each instance keeps its own transform and tint. Performance gains depend on animation variety and cache capacity.

Set SpriteLoop → Mask Cache Budget Mb in Project Settings (spriteloop.mask_cache_budget_mb) to choose the retained mask texture budget in MiB. The default is 32; supported values are 0–128, with 0 disabling retention. Invalid values use the default and log a warning. This budget does not include other graphics memory. Mask rendering also keeps up to 8 MiB of recycled render targets and up to 16 MiB of scratch targets.

For web projects with masks, use Defold 1.14.1 or newer. Earlier versions check framebuffer status on every render-target bind, which makes heavy mask scenes much slower in browsers.

Project Settings

Setting Default Meaning
spriteloop.max_count 1024 Maximum SpriteLoop components per collection.
spriteloop.max_pending_events 256 Maximum queued animation events per component.
spriteloop.mask_cache_budget_mb 32 Retained mask texture budget in MiB (0–128).

Known Limitations

  • iOS and macOS Metal are untested at runtime; builds pass in CI.
  • Android OpenGL ES: an engine race in render-target deletion (defold/defold#13581) can crash Android. SpriteLoop recycles its own mask targets to avoid it, but render targets created by your own Lua code are still exposed until Defold fixes it.
  • Characters from different .spla exports use separate textures and do not batch together. Large mixed crowds cost about one draw call per visible actor.
  • Vulkan builds may log Could not find '@render' socket. once at startup. It is a harmless Defold engine message and is unrelated to SpriteLoop.

Supported Native Extension Libraries

The repository currently includes prebuilt native extension libraries for these Defold arc-platform folders:

x86_64-win32
x86_64-linux
x86_64-osx
arm64-osx
wasm-web
wasm_pthread-web
arm64-android
armv7-android
arm64-ios
arm64_sim-ios

More Defold arc-platforms can be added by committing the matching library under spriteloop/lib/<arc-platform>/ and validating the example project for that target.

Defold/Bob uses x86_64-macos as the macOS build platform, but native extension libraries still live under x86_64-osx and arm64-osx. This is expected.

Defold's current WebAssembly HTML5 arc-platform is wasm-web; the older asm.js-style js-web platform is intentionally not shipped by this extension.

The arm64_sim-ios library targets the iOS Simulator on Apple Silicon and replaces the legacy x86_64-ios artifact. The arm64-ios library targets physical iOS devices. Extension CI validates both iOS targets.

Validate

Validate the example project with Bob from the repository root. Use the platform matching the library you want to check:

python3 utils/validate.py --bob path/to/bob.jar --platform x86_64-win32

For macOS validation, use Bob's macOS platform name:

python3 utils/validate.py --bob path/to/bob.jar --platform x86_64-macos

For HTML5/WebAssembly validation, use Defold's WebAssembly platform name:

python3 utils/validate.py --bob path/to/bob.jar --platform wasm-web

For the threaded WebAssembly engine:

python3 utils/validate.py --bob path/to/bob.jar --platform wasm_pthread-web

The validation script selects Bob's wasm-web platform with the explicit wasm_pthread-web architecture and checks for the matching threaded SDK library. Extension CI builds both web architectures separately for the selected Defold version. These checks validate compilation and linking; they do not run the game in a browser.

For Android validation, use Defold's Android arc-platform names:

python3 utils/validate.py --bob path/to/bob.jar --platform arm64-android
python3 utils/validate.py --bob path/to/bob.jar --platform armv7-android

For iOS device validation, use Defold's iOS device platform:

python3 utils/validate.py --bob path/to/bob.jar --platform arm64-ios

For iOS Simulator validation:

python3 utils/validate.py --bob path/to/bob.jar --platform arm64_sim-ios

On Windows, the same command works from PowerShell:

python utils\validate.py --bob path\to\bob.jar --platform x86_64-win32

Pass --java path/to/java if Java is not on PATH. The script checks that the committed extension files and platform library are present, then runs Bob with clean build. Bob output is hidden on success; pass --verbose to print the full build log.

If spriteloop/pluginsrc/ or spriteloop/commonsrc/spriteloop_ddf.proto changes, rebuild the editor/Bob plugin jar before validating. Use Bob matching the editor's exact engine revision: protobuf builder APIs can change even between builds with the same version label. A mismatched jar can produce a getSrcBuilder / GeneratedMessageV3$Builder error during HTML5 builds. Restart the editor after replacing the plugin jar so it reloads the Java classes.

Rebuild command:

python3 utils/build_spriteloop_plugin.py --bob path/to/bob.jar --platform x86_64-win32

Layout

game.project              # Example and validation project
spriteloop/               # Defold native extension
  ext.manifest
  spla.lua
  spriteloop.lua
  api/
  commonsrc/
  editor/
  include/
  lib/
  plugins/
  pluginsrc/
  src/
example/                  # Example content
input/                    # Example input bindings
utils/                    # Maintenance scripts

Releases

Sponsor this project

Used by

Contributors

Languages

⌂ 换网址