PixelSpriteFrames

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

Every frame of a sprite from the Pixel tab as SpriteFrames, one animation per tag, for a plain AnimatedSprite2D. A PixelSprite2D holds one already, so you need this only for a node that isn’t one.

Set document to a .jcsprite and put this in the node’s sprite_frames. It updates as you draw in the Pixel tab, with no export step, and plays at the same speed as an exported animation. Set palette to draw it in other colours; the sprite file doesn’t change.

Example: each coin’s sparkle in the example game, Meadow/Coin/Sparkle, is a plain AnimatedSprite2D on sparkle.frames.tres, one of these saved as a file. From code, with the villager in villager_gold.jcpalette on a sprite of its own:

var sparkle: AnimatedSprite2D = $Meadow/Coin/Sparkle
sparkle.sprite_frames = load("res://examples/art/sparkle.frames.tres")
sparkle.play("twinkle")

var gold := PixelSpriteFrames.new()
gold.document = load("res://examples/art/villager.jcsprite")
gold.palette = load("res://examples/art/villager_gold.jcpalette")
var villager := AnimatedSprite2D.new()
villager.sprite_frames = gold
add_child(villager)
villager.play("idle")

Properties

document

@export var document: PixelDocument

The document whose frames these are: one animation per tag, rebuilt as the document changes.

palette

@export var palette: PixelPalette

A palette to draw these frames 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 sets of frames can show the same sprite in different colours. Set it to null to go back to the sprite’s own colours.

Example: a PixelSprite2D passes its PixelSprite2D.palette to these frames, the way Hub/Villager2 in the example game wears villager_gold.jcpalette. Under a plain AnimatedSprite2D, set it on the frames instead:

var frames := PixelSpriteFrames.new()
frames.document = load("res://examples/art/villager.jcsprite")
var sprite: AnimatedSprite2D = $AnimatedSprite2D
sprite.sprite_frames = frames
frames.palette = load("res://examples/art/villager_gold.jcpalette")
frames.palette = null

Methods

set_layer_visible

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

Shows or hides the layer called name in these frames alone; the document’s PixelLayer.visible is not written. Rebuilds now.

is_layer_visible

func is_layer_visible(name: String) -> bool

Whether the layer called name shows here: the override when there is 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.

rebuild

func rebuild() -> void

Redraws every frame now. Call it after changing the sprite’s pixels from code to see the change this frame instead of the next.

Signals

document_changed

signal document_changed

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

palette_changed

signal palette_changed(palette: PixelPalette)

Emitted once the frames are redrawn in the palette you set.