Vector Art Files

The pack

vectorArt

function vectorArt(): Pack<{ vectorArt: VectorArtApi }>

The vector-art pack: read line-art sprite files and put their shapes on the vector-2d layer. Everything but load is pure, so the format can be read and checked headless.

Helpers

addArt

function addArt(vector: Vector2dApi, art: VecArtFile | VecArtShape, name?: string, opts: ArtAddOptions = {}): VecShape

PUT A SHAPE ON THE LAYER: one vector.shape(parts, style) call, exactly as if it had been typed in. The returned shape is an ordinary retained shape — move it, turn it, shatter it — and its parts keep their names, so shape.part('flame') reaches what the file called flame.

animateArt

function animateArt(shape: VecShape, art: VecArtShape, t: number): void

RUN A SHAPE'S MOTION at t seconds — spins, pulses and blinks are slot writes and cost nothing; a ramp cycle is a restyle, which re-packs the layer, so it moves in 48 steps a turn and only when the step changes. Call it from a step with the game's own clock.

artBounds

function artBounds(shape: VecArtShape): { x: number; y: number; w: number; h: number; radius: number }

Where a shape actually reaches, in art space, with every part's transform baked in: its box, and its RADIUS — the farthest point from the origin, which is the circle a game collides with.

artRotation

function artRotation(shape: VecArtShape, heading: number): number

The rotation that points a shape along a heading (radians, 0 = +x, the way Math.atan2(vy, vx) reads). Art that faces up needs a quarter turn added; art with no front ignores the heading.

artScale

const artScale = (shape: VecArtShape, size: number): number=> …

The scale that draws a shape size world units across its design box.

artShape

function artShape(art: VecArtFile | VecArtShape, name?: string): VecArtShape

The shape a file names, or its first when no name is given. Throws on a name the file does not have.

parseVectorArt

function parseVectorArt(json: unknown, warnings?: string[]): VecArtFile

READ A FILE, leniently. Unknown fields are dropped, numbers given as strings are read, a bad part is skipped rather than failing the set, and the caps hold. A bare shape ({ parts: [...] }) reads as a set of one named shape. Pass warnings to hear what was dropped.

Functions

artMotionAt

function artMotionAt(part: VecArtPart, t: number): { rot: number; scale: number; visible: boolean; rampShift: number }

What a part's motion makes of it at time t seconds: its rotation, its scale, whether it shows, its ramp.

artParts

function artParts(shape: VecArtShape): ArtResolvedPart[]

A shape's parts, ready for game.vector.shape(parts, style). Style a part does not set is left unset, so the renderer's own fallback to the shape's style (from artShapeStyle) does the inheriting.

artShapeStyle

function artShapeStyle(shape: VecArtShape): VecArtStyle & { fill?: VecArtFill; pivot?: ArtPt | null }

The shape-level options: its style, its face and its pivot. Spread a position over it.

partClosed

function partClosed(part: VecArtPart): boolean

Does this part's outline close? An arc and a chevron never do; anything else unless it says not.

partPoints

function partPoints(part: VecArtPart): ArtPt[]

A part's outline in its OWN space — before its x, y, rot and scale.

partToArt

function partToArt(part: { x?: number; y?: number; rot?: number; scale?: number }, p: ArtPt): ArtPt

A point in a part's own space, lifted into its shape's space.

primPoints

function primPoints(p: VecArtPrim): ArtPt[]

The points of a primitive, from the renderer's own factories.

readVectorShape

function readVectorShape(v: unknown, warn: (m: string) => void = () => {}, where = 'shape'): VecArtShape | null

One shape from anything shaped like one. Null when nothing in it can be drawn.

serializeVectorArt

function serializeVectorArt(file: VecArtFile, space: number | undefined = undefined): string

The canonical file: numbers rounded (two places for geometry, three for the rest), nothing written that is a default. What a tool saves and what a diff reads.

Constants

artGameScale

const artGameScale = (shape: VecArtShape): number=> …

The scale a game draws a shape at by default: its gameSize, which is its design box when it has none.

artMoves

const artMoves = (art: VecArtShape): boolean=> …

Does any part of this shape move on its own?

VECTOR_ART_FORMAT

const VECTOR_ART_FORMAT: "phaser-ae-vector-art"

The format field every file carries.

VECTOR_ART_LIMITS

const VECTOR_ART_LIMITS: { readonly shapes: 256; readonly parts: 64; readonly points: 512; readonly stops: 16; readonly steps: 128; }

Caps a reader holds a file to, so a broken or hostile file cannot stall a game.

VECTOR_ART_PRIMS

const VECTOR_ART_PRIMS: readonly ["circle", "ellipse", "rect", "roundedRect", "polygon", "star", "triangle", "capsule", "cross", "chevron", "arc"]

The primitive kinds, in a stable order.

VECTOR_ART_SIZE

const VECTOR_ART_SIZE: 100

The box art is drawn in when a shape does not say: points sit in −50..50.

VECTOR_ART_VERSION

const VECTOR_ART_VERSION: 1

The version this code reads and writes.

Types

ArtAddOptions

interface ArtAddOptions

Where and how big a shape goes on the layer.

• x?: number — World x. Default 0.
• y?: number — World y. Default 0.
• rot?: number — Rotation, radians. Ignored when heading is given.
• heading?: number — Point it along this heading (radians, 0 = +x), whichever way the art faces.
• size?: number — How many world units the art's design box spans. Beats scale. Default the shape's gameSize.
• scale?: number — Plain scale over the art's own units. Default the scale its gameSize asks for.
• wrap?: { w: number; h: number } | null — Draw the Asteroids wrap ghosts.
• glow?: number — A multiplier over every glow in the shape. Default 1.
• alpha?: number — A multiplier over every alpha in the shape. Default 1.

ArtPt

interface ArtPt

A point as the renderer takes it.

• x: number — Horizontal position in art units; +x is right.
• y: number — Vertical position in art units; +y is down.

ArtRamp

type ArtRamp = readonly string[] | 'rainbow'

A colour run along a whole outline — stops evenly spaced by arc length, or the hue wheel.

ArtResolvedPart

interface ArtResolvedPart

A part ready for the renderer: game.vector.shape([...parts], style) takes these as they are.

• points: ArtPt[] — The outline in the part's own space, before x, y, rot and scale.
• closed: boolean — Whether the outline closes.
• name?: string — The part's handle, when it has one.
• x: number — Offset within the shape, in art units.
• y: number — Offset within the shape, in art units.
• rot: number — Rotation about the part's own origin, radians.
• scale: number — Scale about the part's own origin.
• fill?: VecArtFill — The part's own solid face; unset to take the shape's.
• color?: string — Stroke colour, css; unset to take the shape's.
• color2?: string — Second colour that each segment grades to from color; unset to take the shape's.
• ramp?: ArtRamp — Colour run along the whole outline; beats color and color2.
• rampShift?: number — Turns the ramp along the outline, 0..1.
• alpha?: number — Opacity, 0..1.
• width?: number — Core width in art units.
• glow?: number — Phosphor halo brightness; 0 for a bare line.
• glowWidth?: number — Halo to core width multiplier.
• dash?: number — Dash period in art units; 0 for solid.
• dwell?: number — Beam dwell, 0..1: how much brighter the ends of strokes burn.
• z?: number — Depth, 0..1: larger draws in front.

ArtXY

type ArtXY = readonly [number, number]

A point as the file stores it: [x, y].

VecArtFile

interface VecArtFile

A file: a set of shapes by name.

• format: typeof VECTOR_ART_FORMAT — Always VECTOR_ART_FORMAT; a reader rejects a file without it.
• version: number — The format version the file was written for; this code reads VECTOR_ART_VERSION.
• name?: string — The set's name.
• shapes: Record<string, VecArtShape> — The shapes, by name. Insertion order is the set's order.

VecArtFill

type VecArtFill = | string | readonly string[] | { color?: string; to?: string; stops?: readonly string[]; angle?: number; radial?: boolean } | null

A solid face: a flat colour, a list of stops, or a ramp with a direction. null is none.

VecArtMotion

interface VecArtMotion

What a part does on its own, from a clock. Applied by artMotionAt; nothing in a file moves unless a game (or a viewer) asks.

• spin?: number — Turns, radians a second.
• pulse?: number — Breathes: scale swings by this much either side of 1.
• hz?: number — How fast it pulses, per second. Default 2.
• blink?: number — Blinks on and off this many times a second.
• cycle?: number — Runs its ramp round the outline this many times a second.
• phase?: number — Where in its cycle it starts, 0..1, so a row of lights can chase.

VecArtPart

interface VecArtPart extends VecArtStyle

One outline inside a shape.

• name?: string — A handle, so a game can reach it — shape.part('flame').
• points?: readonly ArtXY[] — The outline, [x, y] pairs in the shape's own art space.
• prim?: VecArtPrim — Or a factory. points wins when both are given.
• closed?: boolean — Does the outline close? Default true. An arc is always open.
• fill?: VecArtFill — The solid face. Falls back to the shape's.
• x?: number — Offset within the shape.
• y?: number — Offset within the shape.
• rot?: number — Turned about the part's own origin, radians.
• scale?: number — Scaled about the part's own origin.
• motion?: VecArtMotion — What it does on its own.

VecArtPrim

type VecArtPrim = | { kind: 'circle'; r: number; steps?: number } | { kind: 'ellipse'; rx: number; ry: number; steps?: number } | { kind: 'rect'; w: number; h: number } | { kind: 'roundedRect'; w: number; h: number; r: number; steps?: number } | { kind: 'polygon'; r: number; sides: number; rot?: number } | { kind: 'star'; points: number; outer: number; inner: number; rot?: number } | { kind: 'triangle'; w: number; h: number } | { kind: 'capsule'; len: number; r: number; steps?: number } | { kind: 'cross'; arm: number; half: number } | { kind: 'chevron'; w: number; h: number } | { kind: 'arc'; r: number; from: number; to: number; steps?: number }

A part drawn by one of the shape factories rather than listed point by point.

VecArtPrimKind

type VecArtPrimKind = typeof VECTOR_ART_PRIMS[number]

The name of a primitive: one of VECTOR_ART_PRIMS.

VecArtShape

interface VecArtShape

One sprite: parts under one transform.

• size?: number — The box it was drawn in: its points sit in −size/2..size/2. Default 100.
• gameSize?: number — How many WORLD units across the game draws that box, unless it says otherwise — a ship 32, a big rock 80, a shot 6. It matters because a stroke's width is in world units and does not scale with the shape: width: 2 is two units at any size, so the weight a line reads at is width against THIS. Default size.
• facing?: 'up' | 'right' | 'none' — Which way it points: 'up' (the default), 'right', or 'none' for a thing with no front.
• role?: string — What it is in the game — player, enemy, rock, shot, pickup, effect, prop, ui. Free text.
• tags?: readonly string[] — Free labels.
• style?: VecArtStyle — The look every part falls back to.
• fill?: VecArtFill — The face every part falls back to.
• pivot?: ArtXY | null — The point it turns and scales about, in art space. Default the origin.
• parts: readonly VecArtPart[] — Its outlines, in draw order.

VecArtStyle

interface VecArtStyle

How a stroke is drawn. Every field is the renderer's VecStyle field of the same name.

• color?: string — Stroke colour, css.
• color2?: string — A second colour: each SEGMENT grades from color to this.
• ramp?: ArtRamp — A colour run along the WHOLE outline, which beats color / color2.
• rampShift?: number — Turns the ramp along the outline, 0..1.
• alpha?: number — Opacity 0..1.
• width?: number — Core width in art units. Under 1 is a hairline.
• glow?: number — Phosphor halo brightness, 0 for a bare line.
• glowWidth?: number — Halo/core width multiplier. Omitted: the renderer's own stamp.
• dash?: number — Dash period in art units, 0 for solid.
• dwell?: number — Beam dwell 0..1 — the ends of strokes burn brighter.
• z?: number — Depth 0..1; larger draws in front, and a nearer fill hides what is behind it.

VectorArtApi

type VectorArtApi = typeof kit & { /** * Fetch a file and read it, through the asset loader — so a pack's `baseURL` applies, the load shows on the * preloader, and a failure says which file. Read leniently: a bad part is dropped, not fatal. */ load(url: string): Promise<VecArtFile>; }

game.vectorArt — the format's reader and helpers, plus a loader that goes through the game's assets.