PixelSprite2D

Extends AnimatedSprite2D. Read from the plugin's source on every build.

A node that draws a sprite from the Pixel tab and plays its tags as animations. Set document to a .jcsprite and it draws, with no export step.

Each tag is an animation, played by its name: play("run"). The node updates as you draw in the Pixel tab, and when you save while the game runs. Set palette to draw it in other colours; the sprite file doesn’t change. For artwork that isn’t a sprite node, use PixelSpriteTexture or PixelSpriteFrames.

Example: in the example game the player runs, lands and goes back to idle with no handler, and the landing sound plays on the frame the artist marked. The second villager wears villager_gold.jcpalette, set on its node in the scene. The same from code:

var player: PixelSprite2D = $Player/Sprite
var land: AudioStreamPlayer = $Sounds/Land
player.play("run")
player.play_then("land", "idle")
player.frame_event.connect(func(marker: StringName) -> void:
    if marker == &"land":
        land.play()
)

var villager: PixelSprite2D = $Hub/Villager2
villager.palette = load("res://examples/art/villager_gold.jcpalette")
villager.palette = null

Properties

document

@export var document: PixelDocument

The document this node draws: its frames are built from it, and rebuilt as it changes.

preview_in_editor

@export var preview_in_editor: bool = true

Plays the animation in the editor while you build the scene. Godot’s own AnimatedSprite2D stays on its first frame until the game runs. Turn this off to hold the node still in the editor; the game is the same either way.

palette

@export var palette: PixelPalette

A palette to draw this node in, instead of the sprite’s own colours. The sprite’s first swatch is drawn as this palette’s first swatch, its second as the second, and so on. The sprite file is never changed, so two nodes can show the same sprite in different colours. Set it to null to go back to the sprite’s own colours.

Example: the example game sets villager_gold.jcpalette on Hub/Villager2 in the scene. From code, on Hub/Villager, then back to the document’s colours:

var villager := $Hub/Villager as PixelSprite2D
villager.palette_changed.connect(func(palette): print("now in ", palette))
villager.palette = load("res://examples/art/villager_gold.jcpalette")
villager.palette = null

flash

@export_range(0.0, 1.0) var flash: float = 0.0

How far the sprite is flashed to flash_swatch, from 0, no flash, to 1, every solid pixel it draws in that one colour; a part-clear pixel is tinted toward it. Tween it for a hit: the colour comes from the palette the node wears, so a sprite in palette flashes in that palette’s swatch, a palette switch mid-flash carries on in the new one, and with no palette it is the sprite’s own colours. Clear pixels stay clear. The flash is drawn above the sprite without its CanvasItem.material, so a shader of the game’s own leaves it alone.

Example: a hit that flashes swatch 3 and fades back in a fifth of a second:

var slime: PixelSprite2D = $Slime
slime.flash_swatch = 3
slime.create_tween().tween_property(slime, "flash", 0.0, 0.2).from(1.0)

flash_swatch

@export_range(0, 255) var flash_swatch: int = 0

Which swatch flash flashes to, counted from 0 like PixelPalette.colors: the swatch of palette when the node wears one, else of the sprite’s own colours. A swatch the palette doesn’t have flashes nothing.

Methods

swap_document

func swap_document(value: PixelDocument) -> void

Changes the sprite’s artwork mid-animation, like a costume change: the node keeps the animation and frame it was on, where value has them, and otherwise starts on its first tag. Setting document starts over instead.

rebuild

func rebuild() -> void

Redraws the frames now. Call it after changing the sprite’s pixels from code, such as with PixelDocument.recolor, to see the change this frame instead of the next.

set_flash

func set_flash(value: float) -> void

Sets flash, held between 0 and 1, and redraws.

set_flash_swatch

func set_flash_swatch(value: int) -> void

Sets flash_swatch and redraws.

flash_color

func flash_color() -> Color

The colour the flash draws over the sprite now: swatch flash_swatch of the palette the node wears, or of the sprite’s own colours with no palette, its alpha the swatch’s times flash. Clear when the flash is off or the palette has no such swatch.

set_layer_visible

func set_layer_visible(name: String, on: bool) -> void

Shows or hides the layer called name on this node alone: the document’s PixelLayer.visible is not written, so another node on the same document is unchanged. Rebuilds now.

is_layer_visible

func is_layer_visible(name: String) -> bool

Whether the layer called name shows on this node: its override when it has one, else the document’s own flag; false for no such layer.

clear_layer_overrides

func clear_layer_overrides() -> void

Drops every override set_layer_visible made on this node.

play_then

func play_then(tag: StringName, next: StringName) -> void

Plays tag, and next when it finishes, with no handler: play_then("attack", "idle"). A looping tag plays once, since the next one is the reason to stop looping. Replaces anything queued.

queue

func queue(tag: StringName) -> void

Plays tag after whatever is queued, each as the one before it finishes; at once when nothing is playing. stop() empties the queue by the next frame; pause() keeps it.

queued

func queued() -> Array[StringName]

The tags waiting to play, in order, for a game that wants to know.

Signals

document_changed

signal document_changed

Emitted after the sprite is redrawn: when you set document or palette, change a layer’s visibility, call rebuild, or save the sprite while the game runs.

tag_finished

signal tag_finished(tag: StringName)

The animation named tag reached its end: once when a tag that plays once finishes, and once per loop on one that loops. animation_finished and animation_looped in one signal, with the name.

frame_event

signal frame_event(name: StringName)

Emitted when the animation reaches a frame the artist marked in the Pixel tab, with the marker’s name. A ping-pong animation that passes a marked frame twice emits it twice.

palette_changed

signal palette_changed(palette: PixelPalette)

Emitted once the sprite is redrawn in the palette you set.