Galatrix Docs

Appearance

Rendering: WebGPU and WebGL 2 ​

Galatrix draws with one of two browser graphics APIs. Which one you get is decided per session, and for most creators the only thing it changes is a rule about shaders — everything else in the editor behaves the same either way.

The two backends ​

WebGL 2WebGPU
Available inevery browser that runs Galatrixrecent Chrome, Edge, Safari, and Firefox on most desktops
Shader languageGLSLWGSL
Used forthe default on galatrix.comavailable to anyone who picks it

WebGPU is the newer API. It gives the browser a much closer view of what the graphics card is actually being asked to do, which can show up as steadier frame pacing on scenes with a lot going on. It is not the default today: on the kind of scenes games here are built from — many separate objects rather than a few large ones — WebGL 2 measured faster, so that is what a player gets unless they ask otherwise.

Which one a player gets ​

Players run WebGL 2 by default, and can switch to WebGPU in Settings, Display, Graphics, Graphics backend. There are two choices there because there are two backends; the setting takes effect on the next game they open.

That choice is a request rather than a switch. It loses to all of:

  • a device that does not grant WebGPU. Some machines expose the API and then refuse to hand out a graphics adapter, so Galatrix asks for a real one before committing, and quietly uses WebGL 2 when the answer is no.
  • a game that cannot render on WebGPU. If a map carries a shader with no WebGPU version, the session switches to WebGL 2 when the map loads, and switches back for the next game.
  • a creator who set the Render API to WebGL 2 in Game Settings.

So nothing a player picks can leave them looking at a game that will not draw.

Which one you are on right now ​

The Profiler says, at the end of the counters line: WebGL 2 or WebGPU. It is worth checking before comparing two performance readings, because a number from one backend does not mean the same thing as a number from the other.

To try a game on the other backend without changing your setting, add ?renderer=webgpu or ?renderer=webgl2 to the URL. That overrides everything, including the content check, which is what makes it useful for working out whether a rendering problem is backend-specific.

What this means for shaders ​

This is the part that needs you.

Every other asset in a map — models, textures, sounds, particles, terrain, tilemaps, the whole UI system — is drawn by the engine, and the engine already speaks both languages. Shaders are the exception, because a shader is source code you wrote, and the two APIs do not read the same language.

One shader, two sources ​

You do not make two shaders. A shader asset holds both versions of the same effect:

fragmentSourceGLSL, what the Shader Editor's main tab shows. Used by WebGL 2.
wgslSourceWGSL, what the WebGPU tab shows. Used by WebGPU.

One asset, one name, one set of uniforms, one entry in your project. Whichever backend is running picks the source it can read. Uniform values, textures and the Inspector fields are shared, so changing a colour changes it on both.

A shader that moves vertices has the same arrangement for the vertex stage: vertexSource in GLSL, wgslVertexSource in WGSL.

Writing the second one ​

The Custom shaders guide has the full contract — what the function looks like, what the engine will hand it, how textures and uniforms bind. The short version is that the WGSL side is one function whose parameters are matched by name, so you declare only what you use:

glsl
// GLSL
uniform float uTime;
varying vec2 vUv;
void main() {
  float ring = sin(length(vUv - 0.5) * 20.0 - uTime * 3.0) * 0.5 + 0.5;
  gl_FragColor = vec4(vec3(ring), 1.0);
}
wgsl
// WGSL — the same effect
fn gxShade(uv: vec2<f32>, time: f32) -> vec4<f32> {
  let ring = sin(length(uv - vec2<f32>(0.5, 0.5)) * 20.0 - time * 3.0) * 0.5 + 0.5;
  return vec4<f32>(vec3<f32>(ring, ring, ring), 1.0);
}

The WebGPU tab compiles what you type against your browser's own WebGPU and underlines mistakes with your line numbers, so you find them while writing rather than at publish time. The dot beside the tab turns green when it compiles.

Both kits ship WebGPU versions for every shader they contain, so opening one is the quickest way to see the shape of a real example. If you built on a kit shader without editing it, you already have both versions — Galatrix adopts the kit's WebGPU version for you when the project loads.

Publishing does not need both ​

A GLSL-only shader publishes. WebGL 2 is what players run, so GLSL is the language of the backend your game will actually be drawn with, and a WebGPU version is something to add when you want it rather than a condition of shipping.

What it costs is small and worth knowing: a player who has switched themselves to WebGPU gets moved back to WebGL 2 for your game, because it cannot be drawn on the API they picked. The publish dialog names any shader without a WebGPU version so you can decide, and publishes either way.

Standalone builds work the same way. An exported build ships one backend by design, so a GLSL-only shader in one is nobody's problem but yours.

Common questions ​

Do I have to learn WGSL to make a game? No. Almost nothing needs a hand-written shader — materials, lighting, post effects from the kits, and everything the editor builds already work on both. This only comes up if you write shader code yourself.

Will my old project still open? Yes. Shaders that came from a kit pick up their WebGPU versions automatically the next time the project loads, as long as you have not edited them. Ones you wrote or edited keep exactly what you wrote, and are listed by name when you try to publish.

Why was my edited kit shader not updated? Because the kit's WebGPU version describes the kit's code, not yours. Pairing it with GLSL you have since changed would draw two different effects on the two backends, and you would only ever see one of them. Your shader keeps your GLSL, and needs a WebGPU version written for it.

Does WebGPU look different? It should not. The same effect written twice is the same effect, and the built-in materials, lighting and post effects are matched between the two. If something looks different on one backend, that is a bug worth reporting.

See also ​