> For the complete documentation index, see [llms.txt](https://studio-docs.sandbox.game/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://studio-docs.sandbox.game/the-editor/how-to-use-asset-compiler.md).

# 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](/best-practices/project-code-fundamentals.md).

{% embed url="<https://youtu.be/3eMSs1fJcy0?si=INqsSsAkun3BBJ1x>" %}

## 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

{% stepper %}
{% step %}

## Open Project Settings

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

{% step %}

## 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.
{% endstep %}

{% step %}

## 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.

{% hint style="info" %}
*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.*
{% endhint %}
{% endstep %}

{% step %}

## 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.

{% hint style="info" %}
*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.*
{% endhint %}
{% endstep %}

{% step %}

## 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.
{% endstep %}

{% step %}

## 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.

{% hint style="info" %}
*NOTE: Optimization is a balance between file size and quality. Review the compiled result in Play mode rather than judging source-file resolution alone.*
{% endhint %}
{% endstep %}
{% endstepper %}

## 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](/the-editor/assets-and-asset-generation.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://studio-docs.sandbox.game/the-editor/how-to-use-asset-compiler.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.