ATLAS_FORMATvariablenacatamalon
ATLAS_FORMAT: 1The version of the .atlas format this engine writes, and the newest it reads. It only goes up
for a change an older reader could not survive: a new optional field does not move it.
createSpritevariablenacatamalon
createSprite: TCreateSpritePuts a picture in the scene: an image from useLoadTexture, a frame of a sheet, or a plain
coloured rectangle when it has neither.
It is placed by its anchor, its middle unless you say otherwise, so transform: { x: 160, y: 120 }
centres it there. Everything about it is a plain field you can change at any time
(hero.transform.x += 1, hero.tint = red), and the next frame shows it.
Example
export const Level: TSceneFn = () => {
const texture = useLoadTexture({ src: '/assets/hero.png' });
const hero = createSprite({ texture, transform: { x: 160, y: 120 } });
// No picture: a coloured rectangle, placed by its top-left corner.
createSprite({ width: 320, height: 16, tint: getColor('#3a2a1a'), anchor: { x: 0, y: 0 }, transform: { y: 224 } });
useUpdate((delta) => {
hero.transform.rotation += delta;
});
return createScene();
};parseAtlasDocfunctionnacatamalon
parseAtlasDoc(value: unknown, src: string) => TAtlasDocReads an .atlas file, already parsed from JSON, and checks all of it at once.
All of it and at once, rather than whatever a sprite happens to touch, because tools read these
files as much as games do: an editor has to say "this file is broken, here" while its author is
looking at it. Every message names src, since a project has many sheets and this is the last
place that knows which one it was.
Parameters
valueunknownThe file's contents, parsed from JSON.
srcstringWhere it came from, for the messages.
TAtlasDoctypenacatamalon
What an .atlas file holds: which image, how it is cut, and the named runs its frames make.
Cut one of two ways and never both: a regular grid, or a packed table of rectangles, which
is what a packing tool writes.
Properties
formatnumberkind'atlas'texturestringThe image, relative to the
.atlasfile.gridoptionalTAtlasGridSpecpackedoptionalRecord<string, TAtlasPixelRect>Frame name to rectangle, in the order the frames are numbered.
sequencesoptionalRecord<string, TAtlasSequenceDoc>
TAtlasDocFrametypenacatamalon
One frame of a sheet as a document cuts it: the window into the image in 0-1, and its size in pixels, with its name when the sheet is packed.
Properties
nameoptionalstringuvOffset{ x, y }uvScale{ x, y }widthnumberheightnumber
TAtlasFrametypenacatamalon
The window into the image one frame occupies, in 0-1: what atlasFrame works out and what a
sprite ends up carrying.
Properties
uvOffset{ x, y }uvScale{ x, y }
TAtlasGridSpectypenacatamalon
How a sheet laid out in a regular grid is cut: the size of a cell, or how many there are, and the gaps round and between them.
Give the cell size or the count on each axis, and the other is worked out from the image. That is what lets the same file describe a sheet whose size is not a whole number of cells, a common thing in sheets made by hand: whatever is left over at the edge is simply not a frame.
Properties
frameWidthoptionalnumberWidth of one cell in pixels.
frameHeightoptionalnumberHeight of one cell in pixels.
columnsoptionalnumberCells across. Worked out from the image when left out.
rowsoptionalnumberCells down. Worked out from the image when left out.
marginoptionalnumberEmpty pixels round the whole sheet. Default
0.spacingoptionalnumberEmpty pixels between two cells. Default
0.countoptionalnumberHow many cells are frames, counting row by row, for a last row that is not full.
TAtlasPixelRecttypenacatamalon
One frame of a packed sheet, in the sheet's pixels.
Properties
xnumberynumberwnumberhnumber
TAtlasSequenceDoctypenacatamalon
A named run of frames: which ones, how fast, and what comes after.
Properties
framesnumber | string[]The frames to play in order: numbers in a grid, names in a packed sheet, mixed freely. Repeats are allowed.
fpsoptionalnumberFrames per second. Default
12.loopoptionalbooleanStarts again at the end. Default
true;falserests on the last frame.nextoptionalstringThe run to play when this one ends: a punch that drops back to standing. Only means something with
loop: false, since a run that loops never ends.In the file and not in the script that starts the punch, because what follows a punch is a decision about the animation, and one written into code makes retiming a character a code change. A name no run answers to is said once and the run rests on its last frame.
TCreateSpritetypenacatamalon
TCreateSprite: (options: TSpriteOptions & { width, height }) => TSprite & { width, height }The two ways to call createSprite. Given a width and a height (a coloured rectangle, or a
picture drawn at a size of its own), the sprite that comes back has them as numbers, so
paddle.width can be used in sums straight away. Given neither, they stay optional: the size is
the picture's, and it is not known until the picture has loaded.
TSpriteOptionstypenacatamalon
What createSprite is asked for: a picture (texture, key or atlas), its size, where it
goes and how it looks. All of it is optional.
Properties
materialoptionalTSpriteMaterialAn effect of its own, from
createMaterial. Omitted is the built-in shader.uniformsoptionalTUniformValuesThis sprite's own values for that material's knobs, laid over the material's own.
widthoptionalnumberOmitted: the texture's width once it has loaded.
heightoptionalnumberOmitted: the texture's height once it has loaded.
transformoptionalPartial<TTransform2d>Where it is, how it is turned and how big. Only what is given: the rest is no turn and a scale of 1, so
{ x, y }is enough. Copied, so the object handed in stays the caller's.textureoptionalTTextureA texture from
useLoadTexture. Wins overkey.keyoptionalstringThe key a texture was loaded under, for a sprite built where the record is not at hand.
tintoptionalTColoranchoroptional{ x, y }Which point of the sprite sits on its transform, in 0-1 of its own size:
{ x: 0.5, y: 0.5 }is its middle and the default,{ x: 0.5, y: 1 }the middle of its bottom edge (a character standing on a floor),{ x: 0, y: 0.5 }its left edge (a bar that grows to the right). Rotation and scale happen around it.atlasoptionalTSpriteAtlasA sheet from
createSpriteAtlas. It supplies the image and, withframe, which part of it to show. Anything given explicitly (texture,uvOffset,uvScale) wins over it.frameoptionalnumberWhich frame of
atlasto show, numbered from 0. Ignored without an atlas. Default0.uvOffsetoptional{ x, y }Shows only part of the texture: where the window starts, in 0-1 across the image. Comes with
uvScale, and both together are how one image holds many frames.uvScaleoptional{ x, y }How big that window is, in 0-1:
{ x: 0.5, y: 1 }is half the width, full height.flipXoptionalbooleanShows the picture mirrored left to right, which is how one drawing covers a character facing either way. It mirrors what is shown and not where it is: the sprite stays exactly where it was, and so does the place it can be touched.
flipYoptionalbooleanThe same top to bottom.
visibleoptionalbooleanWhether it is drawn. Default
true.falsemakes it straight away hidden, which is how a set of them is prepared in advance and shown one at a time.smoothoptionalbooleanOverrides the game's
smoothfor this sprite alone:falsekeeps pixel art crisp when it is scaled up,trueblends between texels.zIndexoptionalnumberWhich sprites it is drawn in front of, within its own scene: higher numbers go on top, and negatives are allowed. Sprites with the same number keep the order they were created in. Default
0. It can be changed at any time and takes effect on the next frame drawn.onPointerOveroptionalTPointerListenerCalled when the mouse or a finger comes over this sprite. Only sprites with at least one of these events count when deciding what is under the pointer, so a decoration on top does not steal them.
onPointerOutoptionalTPointerListenerCalled when the pointer stops being over this sprite, or leaves the game.
onPointerMoveoptionalTPointerListenerCalled when the pointer moves while over this sprite.
onPointerDownoptionalTPointerListenerCalled when a button is pressed, or a finger touches, over this sprite.
onPointerUpoptionalTPointerListenerCalled when a button is released, or a finger lifts, over this sprite.
onClickoptionalTPointerListenerCalled when this sprite is pressed and released without leaving it: what a button does. Pressing on it and releasing somewhere else does not count. The cursor turns into a hand over it.
TSpriteTexturetypenacatamalon
A picture that part of a scene is drawn into instead of the screen: a screen inside the game, a monitor, a handheld's display.
It sits on the object whose contents it shows. Everything on that object and under it is drawn
into texture every frame, in the picture's own pixels, and anything else can show texture the
way it shows a loaded image. The object is where the picture's world ends: a camera asked for in
there belongs to the picture, and a lamp in there lights only the picture.
Plain data like every record, apart from texture.gpu, which is the renderer's.
Properties
type'sprite-texture'idstringwidthnumberIn pixels. Also how wide the world inside is, before any camera.
heightnumberIn pixels. Also how tall the world inside is, before any camera.
seesTSpriteTextureSeesWhat is drawn into it.
'inside': only what is on its object and under it, a world of its own.'scene': the models of the world around it as well, seen from its own camera, which is a security camera and a monitor showing it.backgroundTColorWhat the picture is cleared to every frame, behind everything drawn into it.
textureTTextureThe picture itself, ready from the first frame and found in the game's textures by its
key.
TSpriteTextureOptionstypenacatamalon
What createSpriteTexture is asked for.
Properties
widthnumberIn pixels, rounded down and at least 1.
heightnumberIn pixels, rounded down and at least 1.
seesoptionalTSpriteTextureSees'inside', the default: only what the component draws, a world of its own.'scene': the models and particles in depth of the world around it as well, seen from the component's own 3D camera (or the scene's, if it asks for none) and lit by the scene's lamps, with whatever the component draws on top. That is a security camera: the flat part of the scene, its sprites and its texts, is not in the room and is not seen.backgroundoptionalTColorWhat is behind everything drawn into it. Opaque black when left out. A transparent one lets whatever shows the picture be seen through the parts nothing covers.
keyoptionalstringThe name the picture is kept under, so a model can ask for it by name the way it asks for a loaded image. A new one of its own when left out.
Worth giving in a scene that restarts: the same name and size gets the same picture back instead of a new one each time.
TSpriteTextureSeestypenacatamalon
TSpriteTextureSees: 'inside' | 'scene'What a picture made by createSpriteTexture shows: a world of its own, or the one around it too.