PixelSpriteFrames

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

A document’s frames as an AnimatedSprite2D can play them, kept in step with the artwork the way PixelSpriteTexture is.

The exported route builds one spritesheet and points every frame at an atlas region of it, which is one texture in memory and an ordinary PNG anyone can open. This builds a texture per frame instead. That is the price of not exporting: it is what you draw against while the animation is being made, and the sheet is what you ship.

The timing is the exporter’s, so an animation previewed here and an animation exported run at the same speed rather than merely looking similar.

Properties

document

@export var document: PixelDocument

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

Methods

path_changed

static func path_changed(document: PixelDocument) -> int

Puts document, just read off disk again, on every live frames built from the file it came from, and answers how many there were. Same contract as PixelSpriteTexture.path_changed; the rebuild is queued rather than done, so a PixelSprite2D rebuilding the frames it holds in the same pass composites the animation once.

set_document

func set_document(value: PixelDocument) -> void

Sets document, follows its signals instead of the old one’s, and rebuilds.

rebuild

func rebuild() -> void

Composites every frame of every animation the document describes, now, for a caller that has changed the document behind the signals.

Constants

ANIMATION

const ANIMATION: StringName = PixelDocument.DEFAULT_ANIMATION

What an untagged document’s single animation is called.

No longer the only animation there is — a tagged document describes one per tag — but still the name a document with nothing to play falls back to, which is why anything that has to name an animation before asking the document can start here. The name itself belongs to PixelDocument, because the document is what decides which animations exist.

HIDDEN_PROPERTIES

const HIDDEN_PROPERTIES: Array[StringName] = [&"animations"]

SpriteFrames keeps every animation, every frame and every texture in one animations property, and it is the whole of what rebuild writes. An edit to it is one the next document change wipes; document is the thing to set.

The engine already withholds it from the inspector, so the editor half changes nothing today. It is here to say so, and to keep it withheld if that ever moves — test_inspector_fields.gd is what would notice.

Not stored either, since 17 September 2026: every frame of every animation is a texture composited from document, which already holds the pixels, so a .tres or scene holding this was carrying the whole animation twice. Loading sets the document, which rebuilds it.