Optimise your assets

A player waits for every byte that loads before the first playable frame. Aim to get that download under 50 MiB without making models, textures or sounds worse.

Before you start

A build that runs locally, and a browser with developer tools.
Node.js, for npx.
KTX-Software’s ktx tool on your path, if you compress textures to KTX2.

Measure what loads first

Open the game with the browser’s network panel open and the cache disabled. Note the bytes transferred when the first playable frame appears, then compare them with these sizes. The playtest run is the test browser OpenGame opens your game in when you submit it.

Size	What happens above it
50 MiB before the first playable frame	The playtest run at submit warns
50 MiB for the unpacked build	`opengame check` warns
250 MiB unpacked	The upload is refused
200 MiB zipped	The upload is refused
3,000 files	The upload is refused

Players stop waiting long before a build gets near the upload limits.

Compress models

Ship GLB, compressed. One way is glTF Transform:

npx @gltf-transform/cli optimize in.glb out.glb \
  --compress meshopt \
  --texture-compress ktx2

--texture-compress ktx2 needs the ktx tool. Three.js reads the result with GLTFLoader, MeshoptDecoder and KTX2Loader. The KTX2 transcoder is fetched while the game runs. Copy it into your build output so the game can load it from its own files:

basis=node_modules/three/examples/jsm/libs/basis
mkdir -p public/basis
cp "$basis"/basis_transcoder.* public/basis/

Vite copies public/ into the output. With another bundler, use the folder it copies through unchanged.

loaders.js

import { GLTFLoader } from
  "three/addons/loaders/GLTFLoader.js";
import { KTX2Loader } from
  "three/addons/loaders/KTX2Loader.js";
import { MeshoptDecoder } from
  "three/addons/libs/meshopt_decoder.module.js";

// A relative path, so the transcoder loads from
// the game's own upload.
const ktx2 = new KTX2Loader()
  .setTranscoderPath("./basis/")
  .detectSupport(renderer);

const loader = new GLTFLoader()
  .setKTX2Loader(ktx2)
  .setMeshoptDecoder(MeshoptDecoder);

const level = await loader.loadAsync(
  "./models/level.glb",
);

Before you compress:

Merge static meshes that share a material, to cut draw calls.
Budget triangles by how close the camera gets. A crate in the background does not need a hero character’s mesh.
Strip unused animation clips and morph targets.

Compress textures

Texture memory use can make a game stutter even when the files are small. A 4096 by 4096 PNG takes 64 MiB on the GPU however small the file is, and about 85 MiB once mipmaps are generated, which most engines do by default.

Use KTX2 (.ktx2): UASTC for base colour and normal maps, where artefacts show, and ETC1S for everything else.
Size each texture to how large it appears on screen. Most props never need more than 1024.
Load each texture URL once and share the result.

The image check cannot read .heic, .heif, .jxl, .psd. A build that contains one fails until you convert it. KTX1 (.ktx) is supported for BC1 to BC5, BC7, ASTC LDR and plain pixels. Convert other KTX1 formats to KTX2 or a common web format.

Compress audio

Stream music with an <audio> element or a media source. Decoding a whole track into memory costs several times its file size.
Encode short effects as Opus or AAC at the lowest bitrate where you cannot hear a difference, usually 96 to 128 kbps.
Delete sounds that no code plays. They are the cheapest bytes to cut.

Load the rest after the first frame

Load the menu, the first level and the player, call og.ready(), then fetch everything else while the player is busy:

main.js

import { og } from "@opengamehq/sdk";

await og.init();
await loadFirstLevel();
// The first playable frame is on screen.
og.ready();
// Not awaited, so play starts now.
loadOtherLevels();

Without og.ready(), time to playable is estimated from when the frame stops changing, which counts a loading screen against you.

Pack small files

We scan and hash each file on its own. Thousands of tiny JSON or sprite files are slower to check and slower to load. Pack them into one file, such as a sprite atlas or one JSON document, and split it in the game.

Test the smaller build

Measure the new build the same way, and check it before you deploy a new preview.

Rebuild the game.
Repeat the network measurement with the cache disabled, and compare the bytes before the first playable frame with your first number.
Play through and confirm that models, textures and sounds still look and sound right.
Run the local check:
opengame check . --build

Fix a problem

The build fails on an image format

The image check cannot read .heic, .heif, .jxl, .psd. Convert the file to KTX2 or a common web format, update the path that loads it, and run opengame check . --build again.

A compressed model loads locally but not in the preview

The transcoder or the model is missing from the upload, or its path does not match. Check that basis/ is in your build output, that the loader path is relative, and that the letter case matches the file on disk. Packaging covers missing files and runtime requests.

The local check warns about size

The unpacked build is over 50 MiB, which is a warning, not a failure. opengame check adds up every file, so only a smaller build clears it. Convert textures to KTX2, compress models and remove files the game never loads. Moving loads after og.ready() leaves this warning in place, but it lowers the download before the first playable frame, which is the number the playtest run at submit measures.

The game stutters after it loads

Look at texture memory first. Resize textures to their on-screen size and convert them to KTX2, which stays compressed on the GPU.

Start

Guides

Reference

Optimise your assets

Before you start

Measure what loads first

Compress models

Compress textures

Compress audio

Load the rest after the first frame

Pack small files

Test the smaller build

Fix a problem

Where next

Package your game

Update a live game

​Before you start

​Measure what loads first

​Compress models

​Compress textures

​Compress audio

​Load the rest after the first frame

​Pack small files

​Test the smaller build

​Fix a problem

​Where next

Package your game

Update a live game

Before you start

Measure what loads first

Compress models

Compress textures

Compress audio

Load the rest after the first frame

Pack small files

Test the smaller build

Fix a problem

Where next