> 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-set-up-vfx.md).

# How to set up VFX

A visual effect is a **resource**, then a **node**. Create a `.vfx.json` definition, edit it in the VFX Editor, then place a **VFX Node** in the scene that points at that file.

When the agent adds fire, sparks, or rain, it is doing those two things. Select the node and read `vfxPath` to see which definition it uses.

This is not the View menu. **Show VFX** only previews effects that are already in the scene. See [How to Turn On Grid VFX and Skybox](/the-editor/how-to-turn-on-grid-vfx-and-skybox.md).

## Definition vs VFX Node

| Thing          | What it is                                           | How you get one                                              |
| -------------- | ---------------------------------------------------- | ------------------------------------------------------------ |
| VFX definition | A `.vfx.json` file (`ENGINE.VFXDefinition`)          | Asset panel → right-click → **New Resource** → VFX           |
| VFX Node       | A scene node (`ENGINE.VFXNode`) that plays that file | Outliner plus → Component → **VFX Node**, then set `vfxPath` |

Two VFX Nodes can share one definition. Edit `fire.vfx.json` and every node that points at it updates.

The file can live anywhere under `assets/`. Convention is `assets/VFX/`.

{% hint style="info" %}
*NOTE: A new definition is white circular particles moving up. It is not fire until you change colour, size, and maps. The filename does not change how it looks.*
{% endhint %}

{% stepper %}
{% step %}

## Create the VFX resource

In the Asset panel, right-click an empty area, select **New Resource**, then VFX. Name it, for example `fire`.

The editor writes a `.vfx.json`. Example: `@project/assets/models/fire.vfx.json`.
{% endstep %}

{% step %}

## Open the VFX Editor

Double-click the `.vfx.json`. A preview viewport opens with a **Restart** control, and two tabs:

| Tab           | Job                                                                                      |
| ------------- | ---------------------------------------------------------------------------------------- |
| **Particles** | How each particle looks (shape, blend, billboard, fade, gravity, optional alpha texture) |
| **Emitters**  | How they spawn (loop, duration, count, lifetime, size, speed, direction)                 |

A new file starts with **Particles (1)** and **Emitters (1)**. The emitter’s **Particle System** field points at Particle System 0.
{% endstep %}

{% step %}

## Configure the emitter

On **Emitters**, select Emitter 0. These are the fields a new definition ships with:

* **Loop** — on for a torch or weather; off for a one-shot hit
* **Duration** — length of one emission cycle, in seconds
* **Delay** — wait before the first cycle
* **Spawn Mode** — `time` (stream) or `burst` (all at once)
* **Particles Per Cycle** — how many spawn in that cycle
* **Particle Lifetime**, **Size**, and **Speed** — each a min and max range

Press **Restart** in the preview after you change a value.
{% endstep %}

{% step %}

## Place a VFX Node in the scene

Return to the scene. Select the plus button in the Outliner, choose Component, and add **VFX Node**.

Select the node. Set `vfxPath` to the definition, for example `@project/assets/models/fire.vfx.json`.

`autoStart` is on by default. The effect plays in Play mode without extra wiring.
{% endstep %}

{% step %}

## Show VFX in the editor

If the scene looks empty, open **View** and enable **Show VFX**. That toggle does not create the effect. It only draws VFX Nodes while you edit.

Move the node like any other object. Placement lives on the node, not on the `.vfx.json`.
{% endstep %}
{% endstepper %}

## When to use VFX

* **Looping local effect** (torch, steam, campfire) — Loop on, spawn mode `time`, parent the VFX Node to the prop or put both in a prefab.
* **One-shot impact** (hit sparks, explosion puff) — Loop off, spawn mode `burst`. Start it from gameplay when the hit happens.
* **Weather** (rain, snow) — a large looping emitter. Keep particle counts in check; see [Performance & optimization](/the-editor/performance-and-optimization.md).

Same setup more than twice → save the VFX Node (and its parent) as a prefab. See [How to Set Up a Prefab](/the-editor/how-to-set-up-a-prefab.md).

## Common mistakes

| What went wrong                                                       | What to do                                                                                                                     |
| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| Created a `.vfx.json` and nothing appeared in the scene               | The definition is not a scene object. Add a **VFX Node** and set `vfxPath`.                                                    |
| Turned on Show VFX and still saw nothing                              | There is no VFX Node yet, or `vfxPath` is empty. Show VFX only previews placed nodes.                                          |
| Expected a Shader or a material to make particles                     | Particles are a VFX definition. Materials go on meshes. See [How to set up materials](/the-editor/how-to-set-up-materials.md). |
| Dropped a gif or sprite sheet into `VFX/` and treated it as an effect | Those are textures or sequences. A playable effect is a `.vfx.json` plus a VFX Node.                                           |

## What You've Done

You can create a VFX definition, edit particles and emitters, and play it in the scene with a VFX Node. Next: wrap a finished torch or pickup in a [prefab](/the-editor/how-to-set-up-a-prefab.md), [set up sound](/the-editor/how-to-set-up-sound.md) on the same object, or [show VFX in the editor view](/the-editor/how-to-turn-on-grid-vfx-and-skybox.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-set-up-vfx.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.