Assets & loading

Describes a sheet as a grid of frames, so many pictures can live in one image.

This is what lets a whole game draw with one texture: sprites sharing an image are drawn together, and every change of image costs the renderer a break in the batch. A sheet is also how a character is animated, since its frames are the same picture at different moments.

Nothing is loaded here and nothing is measured: a frame is a fraction of the image, so this works the instant it is written, whether or not the image has arrived.

As many colours as a palette may hold.

Two hundred and fifty-six, which is more than any machine of the era ever showed at once, and the ceiling exists because matching walks every colour for every pixel: a palette of ten thousand would be a frame that never finishes rather than an error anybody could see.

The format number a palette written today carries.

Reads a .palette, whatever state it is in.

Total and never throws, like every other document this engine reads: a palette is edited by hand and written by tools, so one bad colour drops that colour and keeps the rest. A palette that ends up with nothing in it is still a palette, and an effect matching against an empty one gives back what it was handed, which is the honest answer to "reduce this to no colours".

Reads a .particles file.

Normalizes as it reads, and names the file in every refusal. What it refuses is only what has no sensible answer: a kind of effect that is not one, a shape that is not one, a colour that is not a colour, a lifetime of zero. Everything else falls back to something an author would recognise, because an effect that loads slightly wrong can be seen and fixed, and one that does not load at all takes the scene with it.

The format number a .particles file written today carries.

Bumped only for a change an older reader could not survive. A new optional field does not bump it, because an older reader ignoring a field it has never heard of is the whole point of having optional fields.

Shows another frame of the sheet the sprite came from.

For a picture that changes without running: a chest that is open, a tile that is broken, a character facing another way. What moves through frames by itself is useSpriteAnimation, which is this called once per frame.

The one way to change frames, because what a sprite really carries is the window into its image: setting a frame number on the record would be a second truth that nothing reads.

Moves the sprite to its sheet's image too, so putting another sheet on a sprite and asking for a frame is all it takes to swap what it shows: walking to attacking, in two lines.

Does nothing to a sprite that came from no sheet, rather than throwing: asking a plain sprite to show frame 3 is a mistake worth ignoring, not worth stopping a game for.

Loads a sheet written as a file: the image, how it is cut into frames, and the named runs of frames over it.

The file-based twin of createSpriteAtlas. Slicing in code is fine while a sheet is used in one place; a file is what lets the same slicing be shared by everything that reads the sheet, and changed without touching any code, which is what an editor and an artist need.

Asking twice for the same sheet gives the same one back, already loaded, so scenes can help themselves without arranging anything between them.

What comes back can be used right away: sprites made from it show their frame when it arrives, and useLoader counts it like an image.

Loads a sound, and hands it back at once, still loading, for useSound to play.

It comes back straight away, empty, and fills itself in when the file arrives. Playing it before then does nothing, so nothing has to check whether it is ready. Asking twice for the same key gives the same sound, already loaded: load it once in a loading scene and use it in the level.

It can be watched with useLoader to show a loading bar.

This is also what opens the game's sound, so a game that never loads or plays anything never does.

Keeps count of what a scene is loading, for a loading bar or to wait before changing scene.

• useLoader([hero, tiles]): exactly those.
• useLoader(): everything this scene asks for with useLoadTexture, including what its body asks for after this line. Counted once the body is over.

The scene keeps drawing while it loads, so a loading bar made of sprites without a texture is on screen from the first frame. Must be called inside a scene body, like every hook.

A clarification: If you use useLoader() with no arguments, it will track all assets requested by the scene, including those requested after the call. If you use with a specific list of assets, it will only track those and ignore any others requested by the scene.

Loads a bitmap font: an image with the characters drawn in it, and a file saying where each one is.

You get the font back at once, still loading. Hand it to createText straight away: the text appears by itself when the font arrives, and useLoader counts it like any other asset.

Asking for the same font twice, in this scene or another, gives back the one already loaded.

Loads a model made somewhere else: something sculpted in Blender, bought in a pack, exported from anywhere that writes glTF.

Both kinds of the format are read, and you do not have to know which you have. One is a description in text with its numbers and pictures in files beside it, the other is all of it in a single file, and which you were given is an accident of the button somebody pressed. The file is asked, not its name.

You get the model back at once, still loading. Hand it to createModel straight away: it appears by itself when the file arrives, and useLoader counts it like any other asset.

A file is usually several pieces, each with its own colour or picture: a vehicle is a body, glass and tyres. All of them come, and createModel draws them as one thing you move with one placement.

Asking for the same model twice, in this scene or another, gives back the one already loaded, and its shapes are on the graphics card once however many of it you put in the world.

Loads a colour grading table.

Both shapes a table comes in are read here and end up the same: a .cube is text written by a grading tool, a strip is a picture of the same numbers, and which one you have is a fact about where it came from rather than about what it does.

Handed back at once and filled in when the file lands. Until then an effect grading with it shows the frame unchanged.

Loads a pack: boxes and scenes somebody made in another project, with everything they need.

A pack is a folder (what installing a .nacapack writes) and this reads it: its manifest, and the document of each box and scene it offers, with every picture and sound they use found inside the pack's folder, wherever you serve it. Hand it to createPack to place what it offers.

The input actions its scripts read are added to the game when it lands, if the game does not have them already. Its scripts are code, which a loader cannot bring: import the pack's <name>.pack.ts once and they are registered.

Handed back at once and filled in when it lands, like every other asset, and useLoader counts it. Asking for the same pack twice, in this scene or another, gives back the one already loaded.

Loads a set of colours for an effect to match a frame against.

Handed back at once and filled in when the file lands, like every other asset. Until then an effect matching against it shows the frame unchanged, so a palette that is slow to arrive costs you the palette and never the picture.

Loads an effect: what a puff of smoke or a shower of sparks is made of.

The file is the effect and it is shared: three torches in a level are one document, read once, with one picture behind it. Each of them is its own emitter with its own particles, its own clock and its own run of luck.

Handed back at once and filled in when it lands, like every other asset. Until then an emitter following it draws nothing, which is what lets a scene appear before its effects do.

Loads a shader written in a file, so an effect can live beside the game instead of inside it.

Hand what comes back to createMaterial({ effect }). It arrives still loading, and anything built on it draws with the built-in shader until it lands: a scene is never held up waiting for an effect, it simply gets the effect a moment late.

The file says which family it is for and what knobs it has, so the scene repeats neither.

A file ending in .shader is a shader drawn as nodes rather than written, and it is loaded the same way: it brings both languages with it, so it never takes a glslSrc.

Loads an image to draw with, and hands it back at once, still loading: a sprite made with it appears by itself when the file arrives, so nothing has to wait for it.

You can use this hook with a useLoader to track its loading progress.

A sound asset, returned by useLoadAudio the moment it is asked for.

It is born 'loading' with no length, and the loader fills it in place once the file has been fetched and decoded. Anything holding it (a useSound) sees the change with no re-wiring, which is why it is filled in rather than replaced.

Everything but buffer is plain data. buffer is the decoded sound inside the browser's audio engine: runtime only, and null until it is ready, exactly like gpu in a texture.

Another effect a particle sets off when it is born or when it dies: the sparks a firework leaves.

src is another .particles, relative to this one, never an effect written inline: a child is an effect like any other, made, looked at and used again like one.

A bitmap font, returned by useLoadFont the moment it is asked for.

It is born 'loading' and fills itself in once both its description and its image have arrived. Texts made with it draw nothing until then, and appear on their own when it is ready.

A bitmap font's description file, exactly as it is written on disk.

A model loaded from a file, and everything it takes to draw it.

You get it back at once, still loading, and the pieces appear in parts when the file arrives. Hand it to createModel straight away: what it shows turns up by itself.

One piece of a glTF file's tree, said with the engine's words: the shape a tool turns into a box when it brings a model in.

One drawable piece of a model: a shape and the surface it wears.

A model file is one piece surprisingly rarely. A vehicle is a body, glass and tyres; a character is skin, hair and clothes. Each of those is a piece here because each wears a different surface, and a surface is the thing that cannot be shared: merging them would mean choosing one picture for all of it.

Anything useLoader can track: the one field every asset record shares, so the loader never has to know whether it is looking at a texture, a sound or a font.

A sheet described by a file: the image, how it is cut, and the runs of frames over it.

It is a sheet and a load at once. Once it is 'ready' it is exactly what createSprite and useSpriteAnimation take, and until then it is something useLoader counts, like an image.

A pack, as useLoadPack hands it back: what it offers, ready to be placed with createPack.

It is a definition and not something in the world. It has no position and no state of its own, the same as a model file: each copy made from it with createPack has its own place and its own settings, and the pack is not changed by any of them.

Handed back at once, still loading, and filled in when its manifest and the documents it offers land. Until then boxes and scenes are empty.

How a batch of loads is doing, returned by useLoader. Plain data, updated in place as each asset settles, so a scene reads it in useUpdate to drive a progress bar or move on.

Where an asset is in its load. 'loading' from the moment it is asked for, then exactly one of 'ready' (usable) or 'error' (it will never be usable), and it never goes back.

A grading table, whatever shape its file had.

One layout, whichever it came from. A .cube is text and a strip is an image, but by the time anything downstream looks at it there is only the strip: N slices side by side, each N by N. Red runs across within a slice, green down it, and blue picks which slice. That is the layout every engine uses, so a table exported for another one drops straight in.

A palette asset, handed back the moment it is asked for and filled in when the file lands.

Its picture is one row of pixels, one per colour, which is how the card reads it: an effect asks how many there are and then for the nth, and neither question needs a second dimension.

A .palette file as it is written on disk.

Plain JSON, because a palette is the one part of this whole feature that is data rather than arithmetic: everything else the engine can work out, and these are colours somebody chose.

What reading a shader file got out of it.

The same shape whichever way the file was authored, so whatever learns to write shader files next plugs in here without anything downstream noticing.

How far an effect reaches: a box in the emitter's own space, centred where it says, because a fountain reaches up and dust reaches sideways.

Said, and not enforced. Nothing is stopped at its faces and nothing is left undrawn because of it: an effect that outgrows its box has the wrong box. It is here so a tool can draw it and a renderer could one day skip an effect that is nowhere near the screen. A flat effect leaves z at zero on both.

A .particles file, read, for whichever dimension it says it is.

The dimension is the file's and not the emitter's, because it decides what every other number in it means. An emitter is made for one of the two, and pointing it at the other is refused.

A flat .particles file, read: pixels, with +y down, like everything else in the plane.

Normalized as it is read, which is what lets everything downstream be a plain walk with no guards: the curves come out sorted with their t inside 0 to 1, a bare number has been widened into a range, and a range somebody wrote backwards has been turned round rather than refused.

A .particles file for three dimensions, read: world units, with +y up.

Everything but four fields reads as it does in the flat one. The four are the ones a dimension changes the meaning of: where they are born, which way they fly, which way they fall, and the kind that says so. Pixels and units differ by a factor of a hundred, so the two never share defaults.

A .particles file, on its way in or already here.

Kept apart from the emitter that follows it, and that split is the whole reason this type exists: three torches in a level are three emitters, each with its own particles, its own clock and its own stream of chance, all reading one document. Folding the two together is what makes three torches parse three files and upload three copies of the same picture.

Like a shader and unlike a texture, it keeps a list of who is waiting on it. A picture can be handed to a sprite and that is enough, because the sprite hands it straight to the card. An effect cannot: an emitter has to size its particles from the document, so when the bytes land they have to reach everything already built against them.

A tail drawn behind each particle, out of where it has just been.

It is more of the same particle and not a ribbon: copies of it, smaller and fainter towards the end, which is how a trail was drawn in that era and needs nothing the draw does not already have. length is in copies because that is what it costs: max × length more of them, set aside once.

A shader written in a file, on its way in or already here.

The file holds the hooks and the knobs and says which family it is for, so the scene that uses it repeats none of that. One file can be shared by any number of materials, and is fetched once.

It keeps a list of who is following it, which is the one thing that makes it unlike a texture. A texture is handed to a drawing and that is enough, because the drawing hands the texture straight to the card. A shader is not: the card compiles from the source, so when the bytes finally land they have to be poured into every material that was already built against it.

Something a shader file can be poured into once it lands.

The two kinds have almost nothing else in common, and they do not need to: a file knows only that whoever is waiting on it has somewhere to put a fragment hook, a vertex hook and a set of knobs.

How the surfaces of a loaded model are made to face.

One image holding many pictures in a grid, and the arithmetic to point at any of them.

A grid rather than a list of rectangles, because that is what a sprite sheet is and because it needs no pixel sizes: the frames are fractions of the image, so an atlas works from the moment it is described, before the image has even arrived.

Frames are numbered from 0, left to right and then top to bottom, the order a sheet is drawn in.

What createSpriteAtlas is asked for.

A texture asset, returned by useLoadTexture the moment it is asked for.

It is born 'loading' with no size, and the loader fills it in place once the image has been fetched, decoded and uploaded. Anything holding it (a sprite) sees the change on its next frame with no re-wiring, which is the whole reason it is mutated rather than replaced.

Everything but gpu is plain data. gpu is a handle into the renderer's memory: runtime only, meaningless to anyone but the backend that made it, and null until the upload.

What useLoadAtlas is asked for.

What useLoadAudio is asked for. Named fields rather than two bare strings, which would be too easy to swap.

Where a bitmap font comes from.

Where a model comes from, and how to read it.

What useLoadLut is asked for.

What useLoadPack is asked for.

What useLoadPalette is asked for.

What useLoadParticles is asked for.

What useLoadShader is asked for.

What useLoadTexture is asked for. Named fields rather than two positional strings, which would be too easy to swap.