Log inGet started
Package

Sprite2D.component

This package holds more than this page lists. See all of its files in its world.

README.md

Sprite2D

An animated 2D sprite for pixel-art characters: plays named animations (sprite sheet animation) from a twoDKit.catalog character sheet, faces left or right by mirroring, and stays snapped to the art's 16-pixels-per-tile grid so it never shimmers. It also adds the motion effects (dash after-images, jump dust, landing bursts, wall-kick and wall-slide dust) from the animation changes it sees.

Put it on any entity. twoDKit.Player2D expects one beside it on the player's body and drives its character, anim, facing and blink every frame; on its own it is a plain animated sprite for NPCs, enemies or props.

e.component.add("twoDKit.Sprite2D", { character = "fox", anim = "run", facing = -1 })
e.component.get("twoDKit.Sprite2D"):play("jump")

Fields

FieldDefaultSyncWhat
character"knight"yesSheet: knight, robot, fox, mage, or an id registered with Catalog.registerCharacter. Changing it swaps the sheet live.
anim"idle"yesidle, run, jump, fall, wallSlide, dash, land, hurt, or any name the sheet declares; missing ones fall back (see catalog).
facing1yes1 faces right, -1 faces left (sheets are drawn facing right).
speed1noAnimation speed multiplier.
z0.1noDepth offset of the picture (higher draws in front).
pixelSnaptruenoKeep the picture on the 1/16 pixel grid.
effectstruenoDraw dust, landing, dash ring and after-image effects (play mode only).
blinkfalseyesBlink on and off (dithered), e.g. while invulnerable after a hit. Every peer blinks it.
flash0noExtra 0..1 mix toward white, this peer only. A dash already flashes on every peer.
fade0noExtra 0..1 dithered fade, this peer only. hurt already fades on every peer.
followDelay-1noSeconds animation changes wait before they show. -1 = automatic: on someone else's player, the engine's pose smoothing delay (multiplayer.smoothing(id).delay, 0.1 s by default), so a jump starts as the smoothed body leaves the ground; 0 on your own.

Methods

  • play(name, restart?): switch animation; with restart, replay the current one from its first frame.
  • isFinished(): has a non-looping animation (jump, land, dash) reached its last frame?
  • animTime(): seconds the current animation has played on this peer.

How it works

Looping animations wrap back to their col frame (the standard fall loops frames 1..2 after frame 0); non-looping ones hold their last frame. The picture is a temporary child entity drawn through twoDKit.sprites, so each peer draws its own and nothing visual is saved. Because character, anim and facing are synced, the entity's owner sets them and every peer plays the same animation and spawns the same effects locally (twoDKit.fx), with no extra network traffic. It also animates in edit mode while the clock is paused, so you can preview a sheet.

What a peer is drawing

sprite:shown() returns the animation and facing this peer draws right now. On someone else's player that is the synced anim / facing one followDelay later; on your own it is the same as the fields.