Skip to main content
The Particles addon lets you attach fully custom particle effects to any portal. You write a particle pack — a YAML script that controls when, where, and how particles spawn — and reference it by filename in the portal’s config. Multiple packs can run on the same portal at the same time. For those who prefer a visual approach, a web-based Particles Editor lets you build packs without writing raw YAML.
If your for loop condition is never false (an infinite loop), it will crash the server. Always double-check the middle condition of every loop before deploying.

​
Setup

1

Create the ParticlePacks folder

Create the directory ./plugins/Dimensions/ParticlePacks/ if it does not already exist.
2

Create your particle pack file

Inside ParticlePacks/, create a new .yml file — for example, circle.yml. This file contains your particle script.
3

Reference the pack in your portal config

Open your portal’s .yml file and add the Particles addon block. Use the filename without the .yml extension:
Addon:
  Particles:
    - 'circle'
You can list multiple packs to run them simultaneously.

​
Particle Pack Structure

A particle pack has two main sections: the start block (initialization) and the body (particle behavior).

​
The start Block

The start block runs once when the pack loads. Use it to declare variables and set the execution frequency. 
start:
  - 'frequency = 20'   # How often (in ticks) the body runs. 20 ticks = 1 second.
  - 'amount = 50'
  - 'radius = 4'
The default frequency is 20 ticks (once per second). You only need to include frequency if you want a different interval. Variables must be numbers — integers or decimals.

​
The Body: portal and tile

The body splits into two sections depending on the reference point for your particles:
SectionReference Point
portalThe center of the portal
tileEach individual portal block
Within each section, you choose how the code runs:
KeywordBehaviour
playRuns its commands once per frequency tick
forRuns its commands in a loop, similar to a C-style for loop
# Run something once per tick for the entire portal center
portal:
  play:
    - 'play FLAME locX locY locZ 5 0.3 0.3 0.3'

# Run a loop for every portal block
tile:
  for:
    i=0;i<10;i=i+1:
      run0:
        - 'play SMOKE_NORMAL locX locY locZ 1 0 0 0'

​
For Loop Syntax

A for loop key has three parts separated by ;:
  1. Initializer — sets the starting value of the counter variable (i=0)
  2. Condition — the loop runs while this is true (i<amount)
  3. Increment — applied after each iteration (i=i+1)
For loops can be nested — any child key that is itself a valid loop will run inside the parent loop.

​
Available Commands

Use these commands inside play or run blocks:
CommandDescription
debug <text>Prints a variable value to the console. Does not perform operations — save results to a variable first.
play <type> <x> <y> <z> <count> <offsetX> <offsetY> <offsetZ> [DustOptions(Color(R,G,B),size)]Spawns particles. DustOptions only applies to REDSTONE particles.
Find the full list of particle type names in the Spigot Particle Javadocs.

​
Built-In Variables

Dimensions automatically provides these variables in every pack. Their values depend on which section they are used in:
VariableDescription
locXX coordinate of the reference point (portal center or individual block)
locYY coordinate of the reference point
locZZ coordinate of the reference point
portalHeightHeight of the portal in blocks
portalWidthWidth of the portal in blocks

​
Math Support

Variable expressions support standard math operations as well as trigonometric functions. You can use sin(), cos(), and other expressions directly in variable assignments: 
- 'angle = i * increment'
- 'x = locX + (radius * cos(angle))'
- 'z = locZ + (radius * sin(angle))'

​
Example: Circle Particle Pack

This complete example creates a glowing green circle around the portal center every second. 
start:
  - 'amount = 50'
  - 'radius = 4'
  - 'increment = (2 * 3.14) / amount'
  - 'frequency = 20'
portal:
  for:
    i=0;i<amount;i=i+1:
      run0:
        - 'angle = i * increment'
        - 'x = locX + (radius * cos(angle))'
        - 'z = locZ + (radius * sin(angle))'
        - 'play REDSTONE x locY z 3 0 0 0 DustOptions(Color(0,255,0),2)'
Save this as circle.yml in your ParticlePacks/ folder, then add 'circle' to the portal’s Particles list.

​
Particles Editor

The Particles Editor is a browser-based visual tool that simulates particle packs so you can preview effects before deploying them to your server. Build your pack by clicking through an Explorer panel rather than writing raw YAML, then export the result and drop it in your ParticlePacks/ folder.
Access the Particles Editor at https://astaspasta.alwaysdata.net/. Note that the portal inside the editor cannot be rotated yet, so all particles will appear on the same Z axis in the preview — they render correctly in-game.

​
Editor Workflow

1

Add start variables

Click start in the Explorer panel. Select Variable in the Assets window, then click Add. Rename each tempVariable entry and set its value, then click Save.
2

Add a for loop

Click portal → for in the Explorer, then select For loop from Assets. Configure the initializer, condition, and increment fields.
3

Add commands to the runnable

Inside the loop, add Variable entries for computed values (angle, x, z) and a Particle entry for the play command.
4

Preview and export

Click Run to preview the particle effect. When satisfied, export the YAML and save it to your ParticlePacks/ folder.