Sprites: atlases and animations¶
The sprite plugin (src/rtype/plugins/sprite/, rtype::plugins::sprite) cuts textures into named frames and plays
animations made of them. It knows nothing of the renderer: it writes the SpriteRenderer of each animated entity, which
the graphics plugin draws as before. The game adds SpritePlugin, and on a client SpriteDrawPlugin, which draws the entities and requires SpritePlugin, GraphicsPlugin and ShaderPlugin; a server adds SpritePlugin alone if
it wants its animators to advance.
Atlases¶
A SpriteAtlas is a texture, its frames (a name, a rectangle of the texture, an origin) and its animations. The
AtlasAssets resource keeps them by AssetId, as TextureAssets keeps textures, and builds them three ways:
// An Aseprite or TexturePacker JSON file: its image, frames and animations (Aseprite's frame tags).
const AssetId ship = atlases->load("assets/ship.json");
// A uniform sheet without a file: a grid, and animations in code.
SpriteAtlas enemy = SpriteAtlas::grid("assets/r-typesheet26.gif", {63.0F, 48.0F}, 6, {2.0F, 0.0F}, 0, {1.0F, 1.0F});
enemy.addAnimation("fly", {0, 1, 2, 3, 4, 5}, 0.08F);
const AssetId enemies = atlases->add("enemy", std::move(enemy));
// Separate images packed into one texture at load time: one frame per image, named after the file's stem.
const std::array images{std::filesystem::path{"assets/spark.png"}, std::filesystem::path{"assets/smoke.png"}};
const AssetId fx = atlases->pack("fx", images);
- The atlas is built at once, on every side: a server gets the same frames and animations, and an error is reported
where the atlas is asked for. One that cannot be built is recorded as failed, with the reason, which is printed: a
missing atlas does not stop the game. Its texture is handed to
TextureAssetsby the client'srtype.Sprite.Texturessystem and loaded before the frame that draws it, like any texture. - The JSON file is what Aseprite (File > Export Sprite Sheet, JSON Data) and TexturePacker export, in their "Hash"
or "Array" layout. Frames keep the file's order. Each frame's
duration(milliseconds) is read, and a trimmed frame keeps its origin where it was in the untrimmed image. Each frame tag becomes an animation, with itsdirection(forward, reverse, pingpong, pingpong_reverse) and itsrepeatcount.meta.imageis relative to the file. The parser lives insprite/detail/AtlasJson, the only file that includes nlohmann_json. - Packing decodes the images (stb_image, through
backend/graphics/ImageDecoding), packs them with stb_rect_pack into the smallest power-of-two texture up to 4096x4096, a pixel apart by default so linear filtering never bleeds, and hands the pixels toTextureAssets::loadPixels(). - A frame's origin (the point the sprite is placed and turned around) is its centre, unless the file gives a
TexturePacker
pivot, or code gives one toaddFrame().
Animations¶
A SpriteAnimation is a list of frames, each with its duration, a direction (kForward, kReverse, kPingPong: there
and back without showing an end twice) and a repeat count (0: forever). sample(time) gives the frame shown at a time
and whether the repetitions are over.
An entity plays one with a SpriteAnimator:
commands.spawn()
.add(Transform{.position = {100.0F, 300.0F}})
.add(SpriteRenderer{.layer = 5})
.add(SpriteAnimator{.atlas = ship, .animation = animationId("idle")});
animationisanimationId(name), a hash of the name: the same in every process and independent of the tags' order, so a server can replicate which animation plays. To switch, set it and puttimeback to 0.timeis the seconds played at speed 1,speedmultiplies the frame time (0 freezes), andplayingstops the clock.- Every field is reflected. The
rtype.Sprite.Animatesystem (PostUpdate, every side) advances the playing animators, stops a finite animation on its last frame (playingturns false, anAnimationFinishedevent is sent), and writes the frame's texture, source and origin into the entity'sSpriteRenderer, only when they change, so an idle sprite stays unchanged for change detection and replication. - A sprite without an animator is drawn from its own
source: a script writes it as avec4,xandyits position in the texture,zandwits size (source = { x = 0, y = 0, z = 51, w = 115 }, the whole of a 51x115 image).
From scripts¶
The SpritePlugin registers engine calls on AtlasAssets. An atlas is
made with one call and filled by name with the others, since call arguments hold no lists: an animation's frames are a
range, first and count (0: up to the last frame).
local ship = engine.call("rtype.sprite.createAtlas", {
name = "game.ship", texture = "assets/ship.png",
frameSize = { x = 48, y = 48 }, count = 5, spacing = { x = 17, y = 0 }, -- a grid; count 0: no frames
})
engine.call("rtype.sprite.addAnimation", { atlas = ship, name = "fly", frameDuration = 0.1, direction = "pingPong" })
engine.call("rtype.sprite.createAtlas", { name = "game.laser", texture = "assets/laser.png" })
engine.call("rtype.sprite.addFrame", { -- named "0"; returns its index
atlas = "game.laser", position = { x = 108, y = 151 }, size = { x = 80, y = 16 }, -- origin: its centre
})
local explosion = engine.call("rtype.sprite.loadAtlas", { path = "assets/explosion.json" })
rtype.sprite.addFrame and rtype.sprite.addAnimation change an atlas already added (AtlasAssets::edit()). An
unknown atlas or direction, or an index that is not a frame, is an error.
The engine.assets.atlas form makes those calls from one table, and only
returns the atlas's id on a side without the SpritePlugin:
local ship = engine.assets.atlas({
name = "game.ship", texture = "assets/ship.png",
grid = { frameSize = { x = 48, y = 48 }, count = 5, spacing = { x = 17, y = 0 } },
animations = { fly = { frames = { 0, 1, 2, 3, 4 }, frameDuration = 0.1, direction = "pingPong" } },
})
Performance¶
examples/plugins/SpriteBenchmark animates N sprites (10 000 by default) of one atlas, drifting and bouncing, and
prints the frame times. Release build on an Apple M-series laptop (MoltenVK, so presentation waits for the 120 Hz
display): 50 000 animated sprites stay at 120 FPS, 100 000 run at 72 FPS (13.9 ms) and 200 000 at 38 FPS (26.4 ms).
Every sprite of one texture is one instanced draw (see the sprite batching of docs/Vulkan.md).