> 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/what-json-files-are.md). # What JSON files are in Sandbox Studio Your project folder is full of files that end in `.json`. That can look like “code.” It is not. **JSON** is structured text: names and values the editor and engine read as settings. Sandbox Studio saves many assets that way so a prefab, material, or animation graph can live on disk and be pointed at from the scene. You do not need to learn JSON syntax to build a game. You need to know **which** files are assets, **which** the editor owns, and when to leave a file alone. ## Asset vs scene vs code | Kind | Examples | What it is | | ---------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------ | | Asset JSON | `.prefab.json`, `.material.json`, `.vfx.json`, `.animconfig.json` | Definitions under `assets/`. Nodes and code point at them with `@project/assets/...` | | Scene | `.genesys-scene` | The open level. The editor owns it | | Project settings | `.genesys-project` | Default scene, Asset Compiler options, and related project fields | | Game code | `src/*.ts` | TypeScript you write. Not JSON | Two nodes can share one asset file. Change the asset; every node that still points at it updates (unless that copy overrode a field). {% hint style="info" %} *NOTE: Do not hand-edit `.genesys-scene` files. Change the open scene in the Inspector, or ask the agent through* [*Sandbox Studio MCP*](/working-efficiently-with-ai/set-up-and-use-sandbox-studio-mcp.md)*.* {% endhint %} ## Files you will see often | File ending | Job | Open / edit with | | ------------------------ | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `.prefab.json` | Reusable node tree | Double-click the asset or a placed instance. [How to Set Up a Prefab](/the-editor/how-to-set-up-a-prefab.md) | | `.material.json` | Surface override for a mesh | Material asset in the Inspector. [How to set up materials](/the-editor/how-to-set-up-materials.md) | | `.vfx.json` | Particle definition | VFX Editor (double-click). Place a VFX Node to play it. [How to set up VFX](/the-editor/how-to-set-up-vfx.md) | | `.animconfig.json` | Animation states and transitions | Model Viewer / animation config. [Create an Animation State Machine](/the-editor/create-an-animation-state-machine.md) | | `.skeleton-profile.json` | Bone names mapped to roles for retarget | Next to a character when clip skeletons differ. [How to import a rigged character and animation clips](/the-editor/how-to-import-a-rigged-character-and-animation-clips.md) | | `.navmsettings.json` | Navmesh bake settings next to a scene | Prefer MCP / agent nav tools. [How to set collision and navmesh on mesh models](/the-editor/how-to-set-collision-and-navmesh-on-mesh-models.md) | | `.genesys-project` | Project-wide settings | **Project Settings** (menu top-left). Prefer the UI over hand edits | | `package.json` | Package manager project file | Leave it alone unless you know why | Older projects may still have `.anim.json`. Convert those to `.animconfig.json` before following current animation docs. Binary and media files (`.glb`, `.png`, `.wav`) are not JSON. Paths in code and materials still use the logical name (for example `.png` or `.wav`). The [Asset Compiler](/the-editor/how-to-use-asset-compiler.md) can bake smaller copies for Play. ## When to open a JSON file Prefer the Studio UI for that asset type first. Hand-edit only when a how-to says it is allowed. Prefab JSON can be inspected or edited; class names must stay `ENGINE.ClassName` for engine types and `GAME.ClassName` for your `@ENGINE.GameClass()` types. Materials: use the Inspector — do not rewrite `.material.json` by hand. Full path and class rules: [Project code fundamentals](/best-practices/project-code-fundamentals.md). Never hand-edit: * `src/auto-imports.ts` and `src/game-data.ts` (generated on `pnpm build`) * `.genesys-scene` as your main way to place content ## Practical guidance * In the Assets panel, read the **ending** of the filename to know what the file is for. * Select a node in the scene and read path fields (`modelUrl`, `vfxPath`, `configUrl`, `prefabPath`, **Model Material**) to see which file it uses. * Ask the agent to change assets through the editor or MCP. Do not paste a whole scene file into chat for the agent to rewrite. * Keep `@project/assets/...` paths fully written. Do not build paths by joining strings. ## Common mistakes | What went wrong | What to do | | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | Treated every `.json` as code to rewrite | Open the matching editor (prefab, material, VFX, anim config) | | Created a `.vfx.json` and expected it in the viewport | Add a VFX Node and set `vfxPath` | | Hand-edited the scene file after a Git conflict | Pick a side in Git, reopen in Studio, rebuild missing pieces in the editor. [Daily Git workflow](/source-control/daily-git-workflow.md) | | Edited `auto-imports.ts` so a class would “register” | Put the class in your own `src/` file and run `pnpm build` | | Pointed materials at a baked `.ktx2` path | Keep the logical `.png` / `.jpg` path | ## What You've Done You can tell asset JSON from scenes, project settings, and TypeScript, and you know which UI owns each common file type. Next: [What the AI puts in your scene](/the-editor/what-the-ai-puts-in-your-scene.md), [What physics and Rapier mean in Sandbox Studio](/the-editor/what-physics-and-rapier-mean.md), or [What Three.js means in Sandbox Studio](/the-editor/what-threejs-means.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/what-json-files-are.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.