Sprites and animation
Everything klyph draws from a texture is a quad: an entity's Sprite, a glyph of text, a
particle, a rectangle on the canvas. This page covers loading textures, drawing them as sprites,
cutting sheets into frames, playing animations, and the camera that turns world units into
points on screen.
The snippets on this page are code for the setup block of runApp, where assets, commands,
camera and addSystem are members of the App in scope.
Assets
app.assets loads files from the assets/ folder next to the executable, which the Gradle
plugin fills from your project's assets/ on every build. AppConfig(assetRoot = ...) points it
somewhere else. Every loader caches: the first call for a path reads and uploads the file, later
calls reuse it.
| Call | Returns |
|---|---|
assets.region(path, filter, address) | The whole of a PNG or JPEG file as a TextureRegion, the picture a Sprite shows, in a texture shared with other files. |
assets.texture(path, filter, address) | A Texture of its own from a PNG or JPEG file, to cut regions from or to repeat. |
assets.spriteSheet(path, columns, rows, filter) | The texture cut into a grid of equal cells. |
assets.image(path) | An Image you can read and change, not cached and not uploaded. |
assets.createTexture(image, filter, address) | A new texture from an Image, every call. |
assets.font(path, filter), assets.sound(path), assets.musicTrack(path) | Fonts, sounds and music, covered on their pages. |
Each loader that reads a file throws FileException when the file is missing and ImageException
when it is not a valid image. Every one has an OrNull sibling, such as regionOrNull, that
returns null instead, for files that may or may not be there.
Sprites
A Sprite draws a region of a texture as a quad placed on its entity's Transform by its origin,
the center by default. Its size starts as the region's size in texels, so at the camera's default zoom each texel covers one
point. To size a sprite by one side and keep its shape, use the region's aspectRatio, its width
over its height: Sprite(region, width = height * region.aspectRatio, height = height).
val ship = assets.region("ship.png")
commands.spawn {
add(Transform, Transform(x = 640f, y = 360f))
add(Sprite, Sprite(ship))
}
The other properties tint, order and mirror it. color multiplies every texel, so
Color.WHITE shows the texture unchanged. A higher layer draws on top of a lower one. The
Transform adds rotation in radians, clockwise on screen because y points down, and scale.
val ship = assets.region("ship.png")
commands.spawn {
add(Transform, Transform(x = 646f, y = 368f, rotation = 0.3f, scaleX = 0.5f, scaleY = 0.5f))
add(Sprite, Sprite(ship, color = Color.BLACK.withAlpha(0.4f), layer = -1, isFlippedX = true))
}
The origin is the point of the picture that lies on the Transform. originX and originY are
fractions of the sprite's size from its top-left corner, and the default, (0.5, 0.5), is the
center. For a character that stands on the ground, (0.5, 1) is the middle of the bottom edge,
which puts the Transform at his feet. Rotation, scale and flips pivot about the origin, so a hero
squashed on landing keeps his feet on the floor. A Collider does not follow the origin, as
Scrolling worlds shows.
val hero = assets.region("hero.png")
commands.spawn {
// The origin (0.5, 1) is the middle of the bottom edge, so the Transform is at the hero's feet.
add(Transform, Transform(x = 640f, y = 500f))
add(Sprite, Sprite(hero, originX = 0.5f, originY = 1f))
}
To cover an area with one small texture, give the sprite a tileWidth or tileHeight, the size in
world units of one repeat. The texture then repeats across the sprite instead of stretching. It
must be loaded with address = SamplerAddress.REPEAT; Scrolling worlds has the
rules for tiling. Sprite.tiled sets both tile sizes to the region's own size, times scale:
val bricks = assets.texture("bricks.png", filter = SamplerFilter.NEAREST, address = SamplerAddress.REPEAT)
commands.spawn {
add(Transform, Transform(x = 640f, y = 600f))
// A wall of 1280 by 240 units with the 16 by 16 bricks drawn at twice their size, 32 by 32.
add(Sprite, Sprite.tiled(bricks.asRegion(), width = 1280f, height = 240f, scale = 2f))
}
Within one layer, sprites are grouped by texture, so where two sprites with different textures overlap in the same layer, which one is on top is not defined. Give them different layers. Each distinct pair of layer and texture costs one draw call, so use a few layers as draw-order groups, such as background, world and effects, rather than one per sprite.
assets.region helps with that on its own: it packs the files it loads into shared textures,
atlas pages of 2048 by 2048 texels, so sprites that show different files in one layer usually
share one draw call. Each file keeps a border of its own edge texels around it on the page, so it
looks the same as it would on a texture of its own. A file loaded with
address = SamplerAddress.REPEAT or larger than 2046 texels on a side gets its own texture
instead, files loaded with different filters go to different pages, and assets.texture never
packs anything. The texture of a packed region is the shared page, so cut regions from
assets.texture(path), not from it. To see a frame with the atlas off while debugging, run with
-Pklyph.atlas=0 or set AppConfig(atlas = TextureAtlas.NONE); the draws count in the F3 overlay
shows the difference.
sprite.isVisible = false hides a sprite without removing it, and a hidden sprite costs no
drawing work.
Regions and sprite sheets
A TextureRegion is a rectangle of a texture in texels, measured from its top-left corner.
assets.region(path) covers the whole of a file, texture.asRegion() the whole of a texture you
hold already, and texture.region(x, y, width, height) a part of one:
val tiles = assets.texture("tiles.png")
val grass = tiles.region(x = 0, y = 0, width = 32, height = 32)
val wall = tiles.region(x = 32, y = 0, width = 32, height = 32)
commands.spawn {
add(Transform, Transform(x = 16f, y = 16f))
add(Sprite, Sprite(grass))
}
commands.spawn {
add(Transform, Transform(x = 48f, y = 16f))
add(Sprite, Sprite(wall, layer = 1))
}
A SpriteSheet is an ordered list of regions on one texture, such as the frames of an animation
or the tiles of a tile set. assets.spriteSheet cuts a file into a uniform grid, and
SpriteSheet.fromGrid takes margins, spacing and explicit cell sizes. Cells are numbered row by
row from the top-left, so cell (column, row) is sheet[row * columns + column].
// Six frames of 128 by 128 texels side by side.
val explosion = assets.spriteSheet("explosion.png", columns = 6, rows = 1)
// A tile set with one texel of border and two texels between its cells.
val tiles = SpriteSheet.fromGrid(assets.texture("tiles.png"), columns = 8, rows = 8, margin = 1, spacing = 2)
println("${explosion.size} explosion frames; tile 9 is ${tiles[9]}")
Animation
A SpriteAnimation component plays a list of regions on its entity's Sprite. Every frame, at
the start of LATE_UPDATE, the engine advances it by the frame's time and sets the sprite's
region to the current frame. The entity needs both components.
commands.spawn {
add(Transform, Transform(x = 100f, y = 100f))
add(Sprite, Sprite(coin[0]))
add(SpriteAnimation, SpriteAnimation(coin, frameDuration = 80.milliseconds))
}
The mode decides what happens after the last frame. AnimationMode.LOOP, the default, starts
over. AnimationMode.PING_PONG plays back and forth: four frames play as 0, 1, 2, 3, 2, 1, 0, 1.
AnimationMode.ONCE stops on the last frame.
A ONCE animation also has an end. With AnimationEnd.HOLD, the default, the entity stays on
its last frame. With AnimationEnd.DESTROY the engine destroys the entity, with its children,
once the last frame has been shown for its full duration. That is all an explosion needs:
commands.spawn {
add(Transform, Transform(x = x, y = y))
add(Sprite, Sprite(explosion[0]))
add(SpriteAnimation, SpriteAnimation(explosion, 60.milliseconds, AnimationMode.ONCE, AnimationEnd.DESTROY))
}
When a ONCE animation finishes, the engine publishes one AnimationFinished event for the
entity, whatever its end. LATE_UPDATE and RENDER systems see it in the same frame. With
AnimationEnd.DESTROY the entity is already gone by then, so check world.isAlive before you
touch its components.
var finished = 0
addSystem(Phase.LATE_UPDATE) { app ->
app.events.forEach<AnimationFinished> { event ->
finished++
// With AnimationEnd.DESTROY the entity is already gone.
println("Explosion $finished done, alive: ${app.world.isAlive(event.entity)}")
}
}
animation.playhead is the Animation that tracks the frame. Pause it, jump to a frame with
seek or start over with restart:
addSystem(Phase.UPDATE) { app ->
val walk = app.world.get(player, SpriteAnimation).playhead
val isMoving = app.input.keyboard.axis(Scancode.A, Scancode.D) != 0f
walk.isPaused = !isMoving
if (!isMoving) walk.seek(0)
}
speed changes how fast an animation plays without changing its frameDuration: the engine
advances it by the frame's delta times speed. 1 is the normal rate, 2 twice as fast, and 0
holds the current frame like isPaused. A negative speed throws IllegalArgumentException.
animation.speed is the playhead's Animation.speed, so either works:
addSystem(Phase.UPDATE) { app ->
// The legs keep up with the ground: half rate at a standstill, one and a half at full pace.
val run = app.world.get(player, SpriteAnimation)
val pace = abs(app.input.keyboard.axis(Scancode.A, Scancode.D))
run.speed = 0.5f + pace
}
The frames of a SpriteAnimation may come from different textures. The animation keeps the list
it is given rather than copying it, so many entities can share one list; do not change the list
afterwards. SpriteAnimation(sheet, ...) shares the sheet's own list.
The camera
app.camera is the view sprites are drawn through. It starts at zoom 1 on every display: one
world unit is one point, the unit window.width and the mouse position are given in, which is
two pixels across on a high-density display. The renderer applies the display's pixel density,
so a game never multiplies by it. The camera is centered on the middle of the window, so world
(0, 0) is the window's top-left corner.
camera.x and camera.y are the world point at the center of the view, zoom scales the world
(2 shows it twice as large) and rotation turns the view. lookAt(x, y) moves the camera to a
point. follow(x, y, smoothing, delta) moves it part of the way toward a point, so called every
frame it eases after a moving target. The result depends only on the time that passed: at a
smoothing of 5 it covers about 99% of the distance to a still target within a second.
camera.bounds keeps the view inside a Rect of the world, such as a level's edges. lookAt
and follow clamp right away, and the engine clamps once more before it draws, so writing x,
y or zoom directly is fine too. Along an axis where the view is larger than the bounds, the
camera centers on them.
// Show the world twice as large and never past the level's edges.
camera.zoom = 2f
camera.bounds = Rect(x = 0f, y = 0f, width = 4000f, height = 3000f)
camera.lookAt(2000f, 1500f)
addSystem(Phase.LATE_UPDATE) { app ->
val target = app.world.get(player, Transform)
app.camera.follow(target.x, target.y, smoothing = 5f, delta = app.time.delta)
}
Follow from LATE_UPDATE, after the systems of UPDATE have moved the target, so the camera
never lags a frame behind it. Scrolling worlds covers following an Interpolated
entity and shaking the view.
camera.worldToScreen and camera.screenToWorld convert between world units and screen points,
with (0, 0) at the window's top-left corner. Screen points are also what app.canvas draws in by
default, which makes labels over entities simple:
addSystem(Phase.RENDER) { app ->
val target = app.world.get(player, Transform)
val above = app.camera.worldToScreen(Vec2(target.x, target.y - 40f))
app.canvas.drawText(app.assets.defaultFont, "P1", x = above.x, y = above.y, scale = 2f)
}
camera.visibleWidth and visibleHeight give the size of the visible area in world units. When
the window is resized, the engine updates the camera's viewport and leaves its position alone.
Sampling: linear or nearest
Every texture has a SamplerFilter, chosen when it loads, that decides how it looks when drawn
larger or smaller than its texels. SamplerFilter.LINEAR, the default, blends neighboring texels
and suits painted art. SamplerFilter.NEAREST keeps hard pixel edges and suits pixel art and
bitmap fonts drawn at whole scales.
val hero = assets.spriteSheet("hero.png", columns = 4, rows = 1, filter = SamplerFilter.NEAREST)
camera.zoom = 4f
commands.spawn {
add(Transform, Transform(x = 40f, y = 30f))
add(Sprite, Sprite(hero[0]))
}
A game made of pixel art sets the filter once instead of in every call:
AppConfig(textureFilter = SamplerFilter.NEAREST) becomes the default of every texture, sprite
sheet and font that is loaded without a filter argument, and a call that passes one still wins.
The built-in font keeps its nearest sampling and assets.disc its linear one.
The cache key is the path, the filter and the address together, so the same file loaded with both
filters becomes two textures. The address, SamplerAddress.CLAMP by default, matters only for
tiling, which Scrolling worlds covers.
Textures without files
Some art is easier to make in code. Image is a grid of pixels you can set one at a time or paint
in bulk: fill sets every pixel to a color, fillRect a rectangle of them, drawLine a line one
pixel wide, fillCircle paints a soft-edged disc, and draw(image, x, y) lays another image over
it, blending by alpha. Give draw a source rectangle with sourceX, sourceY, sourceWidth and
sourceHeight to lay only that part of the image, such as one picture cut out of a sheet. The
shapes and draw leave out whatever falls outside the image. assets.createTexture(image) uploads
the result. Two regions come ready-made: assets.whitePixel, one white texel to stretch into bars
and backgrounds, and assets.disc(diameter), a white disc with a soft edge for particles, bullets
and shadows, cached by diameter. Tint both with the sprite's color.
val checker = Image(2, 2).apply {
set(0, 0, Color.WHITE)
set(1, 1, Color.WHITE)
}
val board = assets.createTexture(checker, SamplerFilter.NEAREST).asRegion()
commands.spawn {
add(Transform, Transform(x = 200f, y = 200f))
add(Sprite, Sprite(board, width = 64f, height = 64f))
}
commands.spawn {
add(Transform, Transform(x = 400f, y = 200f))
add(Sprite, Sprite(assets.disc(24), color = Color(1f, 0.8f, 0.2f)))
}
commands.spawn {
add(Transform, Transform(x = 640f, y = 700f))
add(Sprite, Sprite(assets.whitePixel, width = 1280f, height = 40f, color = Color(0.2f, 0.6f, 0.3f)))
}