Pixels

Lays one picture over another, the way a sprite is drawn over a background: a transparent pixel of source leaves what was there, an opaque one replaces it, and one in between mixes the two.

It is how a sprite is put together from parts (a car from a body, wheels and a driver) or stamped many times over a bigger picture.

A copy of a picture that can be painted on without touching the original.

A new picture to paint on in code, transparent or filled with one colour: what to use instead of a <canvas> whenever a picture has to be generated rather than drawn.

Drawn art (characters, tiles, backgrounds) is made in a pixel-art editor and loaded with useLoadTexture. This is for the pictures nobody draws by hand: procedural variations, placeholders, noise and masks for a shader, a picture that changes while the game runs, or art made by an agent that has no image editor. A canvas only exists in a browser; this runs the same there, on the native runtime and in a test.

It lives in memory only: paint it with fillRect, drawLine, fillGradient and the rest, then make it a texture with createPixelTexture. It needs no game, so a build script or a test can make one too.

Turns a picture into a texture a sprite, a model's material or a shader shows like any image loaded from a file.

It is how a game turns a generated picture into something it can show, with no image file and no page: a procedural sky, a rock texture from noise for a model, a mask for a shader, a placeholder while the real art is drawn. Art someone drew is loaded with useLoadTexture instead. It works the same in the browser and on the native runtime, because nothing here draws with the page. Use it instead of a <canvas>: a canvas only exists in a browser.

The picture can be:

• One painted in code (createPixels). The texture is ready at once and keeps reading from the picture: paint on it again and call updatePixelTexture to show the change (a minimap filling in, a floor with a crater in it). paint, if given, is applied to it first.
• A drawn picture loaded to be processed (useLoadPixels). The texture comes back at once, still loading, the way one from useLoadTexture does, and whatever shows it appears when the file has arrived. paint then receives a copy of the picture, so the loaded one, shared by everyone who loaded the file, is never changed: a palette swap, a white silhouette for a hit, an outline.

Asked again for a key it already made at the same size, it gives that texture back with the new picture uploaded into it, so a scene that restarts does not pile up textures.

A scene document can name a texture made here but cannot carry it, since there is no file to fetch: make it again under the same key before loading the document.

Draws the outline of a circle, one pixel thick, with no gaps and no pixel drawn twice.

Draws a line one pixel thick between two points, with the stepped edge of the era and no smoothing: each pixel is either on the line or not.

Fills the picture with a checkerboard: the first texture every 3D scene is tried with, because it shows at a glance whether a surface is stretched, mirrored or seen from the wrong side.

Fills a circle. Its edge is stepped, one pixel or none, the way a circle drawn by hand on a grid looks, and it is exactly the edge drawCircle draws for the same radius.

Painted with a transparent colour, it cuts a round hole: the crater in a destructible floor.

Fills the picture with a gradient, smooth or cut into the flat bands of a sky from the era, with an ordered dither between the bands if you want it.

Fills the picture with smooth noise: clouds, rock, water, a height map for terrain, or a texture for a shader to read.

It tiles without a seam: the right edge runs on into the left one and the bottom into the top, so a model can repeat it (wrap: 'repeat') with no visible joins. For that, the blobs are fitted to a whole number across the picture, so scale is followed as closely as that allows.

Fills a rectangle with one colour, cut to the picture's edges.

Reads one pixel. Outside the picture it is fully transparent black.

Reading the picture is also how a game asks questions of it: whether a pixel of a destructible floor is still solid, which colour a minimap shows somewhere.

Works out every pixel again from what it is and where it is: for anything the other functions do not draw. A recolour, a shading by height, a pattern of your own.

Sets one pixel. Outside the picture it does nothing.

Replaces colours with others, exactly: every pixel that is one of the from colours, alpha included, becomes its to. Every other pixel is left alone.

It is the palette swap of the consoles of the era: one drawn enemy, and the red, blue and gold versions made from it, with no extra picture drawn. Swaps are worked out from the picture as it was, so swapping red for blue and blue for red at once trades them rather than turning both blue.

Shows what has been painted on a picture since its texture was made or last updated.

Only the part asked for is sent to the graphics card, so a game that changes a little of a big picture every frame (a crater, a revealed patch of map) passes region and stays cheap. Left out, the whole picture is sent.

Loads a drawn picture as pixels, to process it in code: a palette swap, a white silhouette for a hit, an outline, a collision mask taken from the drawing, a level read from an image.

To just show a drawn picture, use useLoadTexture: that is the normal way, and faster, because the picture goes straight to the graphics card. This is for when the game has to read or change the drawing first. It reads PNG files, decoded in plain JavaScript with no canvas, so it works the same in the browser and on the native runtime.

It hands back a record at once, still loading, the way every loader does; useLoader counts it. Give it straight to createPixelTexture with a function that changes it: the texture appears by itself when the file arrives, and the function works on a copy. Once status is 'ready', its pixels can be read as well (with getPixel) but not painted on: the picture is shared by every scene that loads the same file.

What fillGradient is asked for.

What fillNoise is asked for.

A picture file loaded as pixels, to process in code: what useLoadPixels hands back.

pixels is null until status is 'ready'. Read it as much as you like (a collision mask, a level drawn as an image); to change it, hand the record to createPixelTexture with a function, which paints on a copy. The picture is shared by everyone who loaded the same file, so painting on it directly would change it for all of them.

What createPixelTexture hands a picture to before uploading it: change it in place, or return a picture of your own.

A rectangle of a picture, in its pixels, from its top-left corner.

A picture held in memory, to paint on in code and then hand to createPixelTexture: the engine's replacement for drawing on a <canvas>, which only exists in a browser. Drawn art is loaded with useLoadTexture instead; this is for pictures that are generated.

Four bytes a pixel (red, green, blue, alpha, each 0 to 255), row after row, with row 0 at the top: the same way round as an image file and as the game's own y. Nothing in it touches the graphics card, the page or a game, so the same picture can be painted in a scene, in a test, in a build script or on the native runtime and comes out byte for byte the same.

data is yours to read and write directly when the painting functions are not enough; it is width × height × 4 long and never replaced.

What createPixelTexture is asked for.

What useLoadPixels is asked for.