AsepriteOptionstype#

type AsepriteOptions = {
    name: string?,
    json: any
}

Configures a sheet read from an Aseprite JSON export.

Builderrecord#

record Builder ...

Builds a sheet one frame, tag, and slice at a time.

What every constructor here goes through, and what an importer for a format nothing else reads writes into.

sheet: Sheet

tags: {[string]: Tag}

slices: {Slice}

frame: function(self: Builder, x: number, y: number, w: number, h: number, duration: number?): Builder

tag: function(self: Builder, name: string, from: integer, to: integer, direction: Direction?): Builder

slice: function(
    self: Builder,
    name: string,
    x: number,
    y: number,
    w: number,
    h: number,
    pivotX: number?,
    pivotY: number?
): Builder

sliceKeys: function(self: Builder, name: string, data: string?, keys: {SliceKey}): Builder

finish: function(self: Builder): Sheet

Directiontype#

type Direction = "forward" | "reverse" | "pingpong"

Selects how a tag walks its span.

pingpong plays forward and then back without repeating either end, so a three-frame tag is 1, 2, 3, 2 and then round again.

These identifiers reach an Aseprite export and configuration a developer writes, so they are a compatibility surface.

GridOptionstype#

type GridOptions = {
    name: string,
    imageWidth: number,
    imageHeight: number,
    frameWidth: number,
    frameHeight: number,
    margin: number?,
    spacing: number?,
    columns: integer?,
    rows: integer?,
    count: integer?,
    duration: number?,
    tags: {[string]: Tag}?,
    slices: {Slice}?
}

Configures a sheet cut into a uniform grid.

PivotValuestruct#

struct PivotValue ...

A sprite's anchor as fractions of its frame. A bound slice follows its authored keys during GPU animation without updating the component.

x: number

y: number

sheet: integer

slice: integer

Recttype#

type Rect = {
    x: number?,
    y: number?,
    w: number,
    h: number,
    duration: number?
}

Defines one frame's pixel rectangle and duration.

x and y default to zero, and duration to DEFAULT_DURATION milliseconds. These keys are the sheet format's own and are a compatibility surface.

RectsOptionstype#

type RectsOptions = {
    name: string,
    imageWidth: number,
    imageHeight: number,
    frames: {Rect},
    tags: {[string]: Tag}?,
    slices: {Slice}?
}

Configures a sheet cut into explicitly listed rectangles.

Sheetrecord#

record Sheet ...

Represents an image divided into frames.

name: string

id: integer

count: integer

imageWidth: number

imageHeight: number

rects: {number}

durations: {number}

uvs: {number}

tagFrom: {[integer]: integer}

tagTo: {[integer]: integer}

tagDirection: {[integer]: Direction}

tagNames: {string}

tagIds: {[string]: integer}

tagOrder: {[integer]: {integer}}

tagTiming: {[integer]: {number}}

tagCycle: {[integer]: number}

sliceList: {Slice}

sliceIds: {[string]: integer}

image: integer

originU: number

originV: number

scaleU: number

scaleV: number

rect: function(self: Sheet, frame: integer): (number, number, number, number)

duration: function(self: Sheet, frame: integer): number

uv: function(self: Sheet, frame: integer): (number, number, number, number)

hasTag: function(self: Sheet, name: string): boolean

tag: function(self: Sheet, name: string): (integer, integer, Direction)

tagId: function(self: Sheet, name: string?): integer

tagName: function(self: Sheet, id: integer): string

tagCount: function(self: Sheet): integer

cycle: function(self: Sheet, id: integer): number

frameAt: function(self: Sheet, id: integer, time: number): integer

pivot: function(
    self: Sheet,
    name: string,
    frame: integer?
): components.FFIInstance<PivotValue, components.FFIComponent<PivotValue>>

slice: function(self: Sheet, name: string): Slice?

sliceId: function(self: Sheet, name: string?): integer

sliceName: function(self: Sheet, id: integer): string

sliceKeyAt: function(self: Sheet, id: integer, frame: integer): SliceKey?

pivotOf: function(self: Sheet, id: integer, frame: integer): (number, number)

boundImage: function(self: Sheet): integer

bind: function(self: Sheet, image: integer, u0: number?, v0: number?, u1: number?, v1: number?): Sheet

sprite: function(
    self: Sheet,
    frame: integer?
): components.FFIInstance<rendercomponents.Sprite, components.FFIComponent<rendercomponents.Sprite>>

Slicetype#

type Slice = {
    name: string,
    data: string?,
    keys: {SliceKey}
}

Represents a named region that moves across frames.

Aseprite's slices carry hitboxes, attachment points, and nine-patch borders. Tecs reads pivots out of them; everything else is the game's to use. These keys are the sheet format's own and are a compatibility surface.

SliceKeytype#

type SliceKey = {
    frame: integer?,
    x: number?,
    y: number?,
    w: number?,
    h: number?,
    centerX: number?,
    centerY: number?,
    centerW: number?,
    centerH: number?,
    pivotX: number?,
    pivotY: number?
}

Defines where a slice sits from one frame onward and which points it carries.

A slice holds a key until the next one, so a slice that never moves is one key at frame one. A nil centerX means the slice names no nine-slice center, and a nil pivotX means it names no pivot. These keys are the sheet format's own and are a compatibility surface.

Tagtype#

type Tag = {
    from: integer,
    to: integer,
    direction: Direction?
}

Defines an inclusive frame span and its playback direction.

Aseprite calls this a frame tag, and a tag's name is what an animation asks for. direction defaults to "forward". These keys are the sheet format's own and are a compatibility surface.

buildfunction#

function build(name: string, imageWidth: number, imageHeight: number): Builder

Creates a builder for a sheet the other constructors cannot describe.

The model is what the builder writes, so an atlas from any tool reaches the same sheet an Aseprite export does. Frames, tags, and slices are added in any order, and finish registers the result.

Arguments

Returns

Raises

byIdfunction#

function byId(id: integer): Sheet?

Returns the sheet a registration index names.

Arguments

Returns

byNamefunction#

function byName(name: string): Sheet?

Returns the sheet a name names.

Building a second sheet under a taken name replaces what this returns, so a reload points new entities at the new sheet. Entities already carrying the old id keep drawing the old one, which is what stops a reload pulling a frame out from under them.

Arguments

Returns

fromAsepritefunction#

function fromAseprite(options: AsepriteOptions): Sheet

Creates a sheet from an Aseprite JSON export.

One reader in front of the model rather than a second model: frames, their durations, frame tags with their directions, and slices with their keys all land in the sheet the builder writes.

The reader accepts Aseprite's array layout and its object layout, sorting the latter by frame name. It ignores spriteSourceSize, so export with trimming off.

Arguments

Returns

Raises

gridfunction#

function grid(options: GridOptions): Sheet

Creates a sheet whose frames form a uniform grid.

Margin surrounds the grid and spacing separates the cells, so a cell's left edge is margin + column * (frameWidth + spacing). Both default to zero, which is an image cut with nothing between its cells. Frames come out in row-major order.

Arguments

Returns

Raises

rectsfunction#

function rects(options: RectsOptions): Sheet

Creates a sheet from explicitly listed frame rectangles.

For an image no grid describes: frames of differing sizes, or an atlas whose cells a packing tool placed. Rectangles are not checked against the image, so one running off the edge samples whatever the image holds there.

Arguments

Returns

Raises

replacefunction#

function replace(built: Sheet): Sheet?, string?

Folds a freshly built sheet into the one already registered under its name, keeping the old sheet's id.

The reverse of what building under a taken name does, and it exists because a reload wants the reverse. Building again answers new entities with the new sheet and leaves every entity already playing on the old one, which is right for two sheets that happen to share a name and wrong for one file that was re-exported. This overwrites in place instead, so an Animation holding the id continues and shows the new frames on its next step without the world changing.

The refusals exist because a component holds an index into this sheet, so anything this refuses is a change that would renumber one. Tag ids follow the tag names in sorted order and slice ids follow the slices, so adding, removing, or renaming either is a restart. Frames are free to change: an entity carries a tag and a time, and each step resolves its frame from the cycle.

Replacement keeps the live sheet's bind and rescales the new frames against it, so a caller need not bind again.

The sheet handed in is spent. Its id resolves to the live sheet rather than to itself, because the two share their frame tables once the fold is done and only one of them may be bound.

Arguments

Returns

revisionfunction#

function revision(): integer

Returns how many times any sheet's frames have changed.

Bumped by registration and by bind, both of which move where a frame's region points. Anything holding a copy of those regions compares this against what it copied at rather than being told, which keeps the dependency running one way: a sheet knows nothing about who read it.

Returns

DEFAULT_DURATIONvariable#

const DEFAULT_DURATION: number

The milliseconds a frame is held when nothing says otherwise, which is what Aseprite writes for a frame nobody retimed.

Pivotvariable#

const Pivot

Anchors a sprite directly, or follows a sheet slice. Snapshots store names.