Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

🧰How to use asset compiler

The Asset Compiler turns your source files under assets/ into smaller baked files the player actually loads. Your scenes, prefabs, and TypeScript keep pointing at the original names (foo.png, bar.glb). The engine remaps those logical @project/... paths to the baked copies at runtime.

That is why you still write @project/assets/textures/foo.png in code after compression. See Project code fundamentals.

What it is doing

Source files stay in assets/. The compiler writes baked output into .dist/ (build output — gitignored, restored by compiling). A manifest at .dist/.genesys/baked-assets.json maps each logical source path to its baked target.

The engine documents those remaps as, for example, PNG → KTX2 (GPU texture container) and WAV → OGG. Only @project/ paths are remapped. @engine/ assets pass through unchanged.

The runtime can load KTX2 textures and GLB meshes that use Draco or Meshopt. You do not change those loaders; they are already in the engine.

Why this helps
What you would pay without it

Smaller files in .dist/

Play, upload, and browser download send full-resolution PNG/WAV/GLB

GPU-friendly textures

The GPU would expand huge PNG/JPEG in memory

Scenes keep working

You would otherwise retarget every material and loadTexture call after each compress

Compile on Play runs this pass before Play mode starts. First play after a big import is slower; later plays skip work that is already baked. Processing time follows how many assets changed and how large they are.

Settings live in Project Settings in the editor. They are stored on disk in <Name>.genesys-project under assetCompiler. Prefer the editor. Do not treat that JSON as something to hand-edit unless you know why.

Typical assetCompiler fields:

Field
Role

enabled

Compiler is on

compileOnPlay

Run the bake before Play

textureCompression

enabled, quality, maxSize (longest edge in pixels), and which of png / jpeg / webp to process

meshCompression

enabled and level for geometry in GLB

audioCompression

enabled, quality, and which of wav / flac / aiff / ogg / aac / m4a to process

A real project can cap textures at maxSize 1024 with quality medium — that is a setting, not a universal default. Match cap and quality to how close the player sees the surface.

Set it up in the editor

1

Open Project Settings

Select the menu button in the top-left corner of Sandbox Studio, then choose Project Settings.

2

Enable the Asset Compiler

Find Asset Compiler and enable it. That turns on the bake described above and exposes the texture, mesh, and audio options.

3

Enable Compile on Play

Turn on Compile on Play to process the enabled compilation and compression tasks whenever you press Play. Play mode starts after this processing is complete.

NOTE: Entering Play mode may take longer when Compile on Play is enabled. Processing time depends on the number and size of the project's assets.

4

Choose the assets to compress

Enable the compression options that match the asset types used by the project.

Texture compression

Processes image textures (PNG, JPEG, WebP). Caps resolution with maxSize and writes a baked texture (engine remap example: .png → .ktx2). Use it for 2K/4K maps that do not need full source resolution in Play.

Mesh compression

Shrinks 3D geometry inside GLB files. Use it when a model is denser than its on-screen size needs.

Audio compression

Processes large or lightly compressed sources such as WAV (engine remap example: .wav → .ogg). Skip already-small files if quality is already at the floor you want.

TIP: Match asset detail to how players experience it. A distant object, small screen element, or background sound may not need the largest available source asset.

5

Test the optimized project

Press Play and allow the compiler to finish. Check that textures remain clear, models retain their intended shape and detail, and audio quality remains suitable during normal gameplay.

6

Refine assets that lose quality

If an asset no longer meets the project's visual or audio requirements, revisit its source file or compression settings and test again. Keep only the level of detail the player can meaningfully see or hear.

NOTE: Optimization is a balance between file size and quality. Review the compiled result in Play mode rather than judging source-file resolution alone.

What You've Done

The project compiles selected assets when entering Play (if Compile on Play is on) and remaps @project/ loads to the baked files in .dist/. Source files in assets/ stay the originals. Continue testing as assets change so size and quality stay appropriate. Import path: Assets & asset generation.

Last updated

Was this helpful?