Talos Engine
Get started
Menu
Talos docs

sprite

Since 0.6
Plain text

Use it in a scene entity's components list as { "type": "sprite", … }. The contract writes the fields flat and refuses unknown keys.

Fields

FieldTypeRequiredDefaultAllowed valuesDescription
framesSpriteFrame[]yesEvery frame the sprite can show, at least one. Absent an animation, it shows frames[0].
animationsSpriteAnimation[]no
animationstringnoThe animation playing from load, by name (sprite-frame-missing when it has none of that name).
pixelsPerMetrenumberno100How many of the pictures' pixels make a metre, above zero; the entity's scale multiplies the result. Default 100.
billboardSpriteBillboardnocylindrical, spherical, fixed, flat"cylindrical" (default): turns about the world's up axis to face the camera and stays upright, the classic 2.5D character. "spherical": faces the camera fully, tilting with it (a glow, a particle-like prop). "fixed": does not turn; the picture lies in the entity's XY plane and faces its -Z (a sign, a crossed foliage card). "flat": the 2D sprite; does not turn, lies in the entity's XY plane facing +Z (toward a 2D camera looking down -Z), right along the entity's +X and up its +Y, so a turn about Z turns the picture. Draws views[0] of each frame, and is ordered by sortLayer and order.
anchorVec2no[0[x, y], each 0..1: the point of every picture that sits on the entity's origin, as a fraction of its width from the left and its height from the top. A view's own pivot (pixels) wins. Default [0.5, 1] (the middle of the bottom edge, standing on its origin); [0.5, 0.5] (the centre) for a flat sprite.
sortLayernumbernoFlat sprites only: the draw layer, -32..32, default 0. A sprite on a higher layer is drawn over one on a lower layer. The engine draws it 1 m nearer +Z per layer (plus order / 1024 m), so an orthographic camera looking down -Z shows the order and depth does the rest.
ordernumbernoFlat sprites only: the order within sortLayer, -500..500, default 0; higher is drawn over lower. Need not be whole (a top-down game can set it from -y). Two overlapping sprites with the same layer and order have no defined winner: give them different orders.
flipXbooleannofalseDraw every picture flipped left to right about its pivot (a character facing the other way). Combines with a view's mirror. Default false; ctx.sprite.flipX sets it.
flipYbooleannofalseDraw every picture flipped top to bottom about its pivot. Default false; ctx.sprite.flipY sets it.
colorstringno#RRGGBB (or #RGB) tint multiplied into the pictures, as a mesh's color is; a room's light level is a grey. A value that is not a hex colour draws untinted with one warning.
opacitynumberno0..1, default 1. Below 1 the sprite is drawn see-through, blended over what is behind it.
alphaCutoffnumberno0..1, default 0.5: a pixel whose alpha is below it is not drawn at all.
filterSpriteFilternonearest, linearHow the pictures are magnified: "nearest" (hard pixel edges) or "linear" (smooth). Absent: the scene's meta.render.filter, so a retro look's nearest filter applies.
litbooleannoDefault false: drawn as painted (unlit), with fog. True: lit by the scene's lights as a surface facing the camera.
visiblebooleannotrueWhether the sprite is drawn. Default true.

Rules that can refuse it