Materials

Reads a shader file: comments that say what it is, and plain shader code that says what it does.

The header is read from the whole file, deliberately outside the language halves. What the file is for and what knobs it has are one fact about the file, and a fact written twice is two facts that can drift apart.

A file stays valid code in its own language, so an editor colours it and a card could compile it with the engine's own preamble in front. That is the point of a comment-based header: nothing here invents a format that only this engine can open.

Reads a shader file with the reader its extension asks for: a .shader is a graph of nodes, as JSON, and anything else is WGSL with a header. Both give the same shape, so nothing after this knows which it was.

It is the loader's own reader, open to tools: an editor that lets a material pick a shader needs the knobs it declares, whichever of the two ways it was written.

The two ways to call createMaterial: which kind of material comes back follows from shader, so a model's material can only be handed to a model and a sprite's only to a sprite.

A surface, a shader, or both, that one or many things can be drawn with.

Two shapes and not one with half its fields unused, because a field that means nothing half the time is a field that lies. Which one you have is written on shader, so asking narrows it.

A material is an atomic value: nothing caches it and nothing looks it up by name. Two things share one by being handed the same one.

What createMaterial is asked for. shader decides which of the two you are making.

Which family of built-in shader a material plugs into, and so what its hooks are handed.

'sprite2d' is handed a colour already sampled and already tinted, and the flat square's place on it. 'mesh3d' is handed a surface and everything the light knew about it, and may also move the corner before any of that happens. 'post' is handed the finished frame.

A screen-wide effect takes the same hooks as a sprite, on purpose: a CRT over one sprite and a CRT over the whole picture are the same arithmetic, so they should be the same file.

The shader half of what a material can be asked for, which both kinds share.

Writing the source here is the quick way in, for an effect that lives with the scene that uses it. effect is the other way: a file, which several scenes can share and which an editor can open. Giving both is a contradiction, and the file wins.

A material for models: a surface, and optionally a shader over it.

Here the surface is the material's, because that is what a hundred crates want to share. They are one shape and one surface and a hundred placements, and a colour per crate would be a parameter nobody asked for.

That is the other half of the split: in three dimensions the material owns the look, in two the object does.

What createMaterial is asked for when the material is for models.

Everything about the surface is optional and defaults to a plain matt white one, so a material that only carries an effect says only that.

What both kinds of material have: a shader of your own, and the knobs on it.

All four sources are null on a material that only describes a surface, which is every material a game has until it asks for an effect.

A material for flat things: a shader and nothing else.

The picture and the colour are not here, and that is the design. A sprite carries its own, and carries them per sprite: they travel in the instance buffer next to its place and its size, so a thousand sprites in one draw can be a thousand different colours. Putting the colour on something shared would mean one of these per sprite to vary it, which is the opposite of what a material is for. A sprite keeps its own texture and its own tint, and its material is only the effect over the top.

What createMaterial is asked for when the material is for flat things.

There is nothing here about a picture or a colour, because those belong to the sprite. This is the effect and its knobs, and nothing else.

What a model's picture does past its edge.

A model's corners may ask for any part of the plane, not only the picture's own square: a ladder of UVs from 0 to 20 across a field is how one small patch of grass covers a whole hillside, and it is how nearly every level of the era was textured. 'repeat' tiles the picture, 'mirror' tiles it flipped every other time so its seams meet themselves, and 'clamp' stretches its last row and column outwards.

Repeating is the default for a model, as it is in glTF. A sprite and a map never repeat: they read one frame of a sheet, and the next frame over is not theirs to show.

What kind each of those parameters is.

Worked out once from the shape of the first values it was given, and fixed from then on: how the numbers are laid out in memory depends on it, and the shader has already been compiled against that layout.

What kind a material's own parameter may be: one number, or two, three or four of them.

A small set on purpose. It covers what an effect is actually tuned with (a strength, a count, a colour, an offset) and leaves out matrices and lists, which bring alignment rules that are all cost and no use here. The one matrix a drawing needs is the one that puts it on screen, and that already travels with the drawing rather than with its surface.

A material's own parameters, by name. One number, or a list of two to four.

Change one and the next frame shows it: the card is handed these again every draw, so animating a strength is an assignment and nothing else.