> 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/performance-and-optimization.md). # Performance & optimization Measure first, then cut scene cost, then compress. The engine already has the tools; this page is the order to use them. Phone-specific testing and touch controls are on [Mobile development](/the-editor/mobile-development.md). ## Measure Watch FPS in the editor viewport while the game runs. If the number drops when you look at a busy area, that view is the problem — not a guess about file size. Open the profiler from the lightning or heartbeat control next to FPS. Capture the slow moment, download the JSON, and give that file to the agent with what you were doing. Full steps: [How to use the profiler](/the-editor/how-to-use-the-profiler.md). ## After FPS, check the scene A kitbashed level can be slow with small textures. Walk this list in the same view that dropped FPS, then bake assets. | Cost | What to do | Details | | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Physics on dressing | A dragged `.glb` starts physics **on** (`convexHull`, `BlockAll`). Turn physics **off** on cards, banners, and distant backdrops. Use `boundingBox` when a hull is heavier than the shape needs. | [How to set collision and navmesh on mesh models](/the-editor/how-to-set-collision-and-navmesh-on-mesh-models.md), [What physics and Rapier mean](/the-editor/what-physics-and-rapier-mean.md) | | Shadow maps | Keep **Cast Shadow** on **one** directional light. Leave it **off** on point and spot fills. Lower **Shadow map size** if the silhouette is still too expensive. Turn **Cast Shadow** off on small props. | [How to set up a light](/the-editor/how-to-set-up-a-light.md), [How to use shadow](/the-editor/how-to-use-shadow.md) | | Post-processing | Tone mapping and anti-aliasing start on. Bloom, ambient occlusion, and depth of field start off. If Play stutters after you enable a stack, turn effects off one at a time. Lower AO resolution scale before raising quality. Leave outline and screen-space reflections off unless you need them. | [How to use post processing](/the-editor/how-to-use-post-processing.md) | | Particles | On weather and looping emitters, lower **Particles Per Cycle** and lifetime. Two VFX Nodes can share one `.vfx.json`. | [How to set up VFX](/the-editor/how-to-set-up-vfx.md) | | Local lights | Unshadowed point lights still light nearby meshes. Tighten **Distance** and **Decay**. Do not add a second directional light for fill. | [How to set up a light](/the-editor/how-to-set-up-a-light.md) | Then turn on the Asset Compiler (next section). Do not retarget materials to `.ktx2` by hand. ## Compress Turn on the Asset Compiler in Project Settings so Play and upload use baked files in `.dist/`, not full-resolution sources. Texture `maxSize` is the resolution cap (longest edge, in pixels). One shipping project sets `maxSize` to **1024** with texture, mesh, and audio compression on — use that as a starting cap, then check Play. How the bake remaps `@project/` paths: [How to use asset compiler](/the-editor/how-to-use-asset-compiler.md). There is no separate documented poly-count or mid-range-mobile FPS target on this page. Use the FPS readout and a device check on [Preview a Game on Mobile](/the-editor/preview-a-game-on-mobile.md). ## Generate low poly When a generation tool offers a low-poly mode, turn it on before you import. Fewer triangles, same silhouette, less work for the GPU. 1. Open that tool's generation settings. 2. Enable the low-poly option.

Generation settings with Low Poly enabled

## Audit asset resources After substantial periods of development request a report from the agent to identify memory and space savings in your project. 1. Input the following request: "List all asset resources, including file sizes and texture dimensions in the project in chart." 2. Review the agent output for high-impact files. ## Execute optimizations Tell the agent to resize and compress high-impact assets to reduce project memory footprint. 1. Resize oversized texture files. 2. For audio, turn on **Audio compression** in the Asset Compiler (Project Settings) rather than converting source files. Keep logical paths such as `.wav` in code. The compiler remaps them at bake time. Do not retarget `@project/` paths to `.ogg` by hand. 3. Compress video files based on agent recommendations. Then let the Asset Compiler bake those files for Play. Do not retarget materials to `.ktx2` by hand. ## Shadows and repeated meshes Shadows are a GPU cost. The table above is the first pass. Full Inspector fields: [How to use shadow](/the-editor/how-to-use-shadow.md). Many copies of the **same** `.glb` can stay as separate Model Mesh Nodes. They share the file. That is normal kitbash. See [How to kitbash a level from mesh models](/the-editor/how-to-kitbash-a-level-from-mesh-models.md). Dozens or hundreds of the same small prop (grass, rocks, coins) should be one instanced node, not one Model Mesh Node per copy. Full steps: [How to instance repeated meshes](/the-editor/how-to-instance-repeated-meshes.md). Painting foliage onto a floor is on [Mobile development](/the-editor/mobile-development.md). ## What You've Done You can read FPS, walk physics / shadows / post / particles / lights before blaming file size, then cap and bake assets and cut duplicate-mesh cost. Next, confirm the same view on a phone preview or a draft link. --- # 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/performance-and-optimization.md?ask=&goal= ``` `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.