---
description: >-
  This page explains how to configure particle shapes, animations, and
  interactions inside the plugin.
---

# Shape

### 🔷 `shapes`

All shape configurations are listed under the `shapes:` section. Each shape has its own unique name and configuration block.

```yaml
shapes:
  yourShapeName: # custom name
    ...
```

***

### ✅ Basic Properties

| Key        | Description                                                             |
| ---------- | ----------------------------------------------------------------------- |
| `enabled`  | Whether the shape is active (`true` or `false`).                        |
| `shape`    | The type of shape (All types can be found below the table).             |
| `location` | Where the shape appears in the world. Format: `world(x,y,z,yaw,pitch)`. |

**Shapes:** CIRCLE, SQUARE, HEXAGION, PENTAGON, OCTAGON

***

### ⚙️ `settings`

Customize how the shape appears.

```yaml
settings:
  radius: 5
  points: 50
  fill:
    use: false
    radius: 1
  view-distance: 30
  update-interval: 1
  angle:
    type: AROUND_CENTER
    value: 45
```

#### Settings Explained:

| Key               | Description                                                  |
| ----------------- | ------------------------------------------------------------ |
| `radius`          | Size of the shape (distance from center).                    |
| `points`          | Number of points used to draw the shape (higher = smoother). |
| `view-distance`   | Maximum distance from which players can see the shape.       |
| `update-interval` | How often the shape updates (in ticks, 20 ticks = 1 second). |

**Specific settings:**

{% tabs %}
{% tab title="Fill" %}
`use` -  Whether the shape is filled (`true`) or just an outline.\
`radius` - How much space to fill inside if `use` is true.\
\
**Example:**

```yaml
fill:  
  use: true
  radius: 1
```
{% endtab %}

{% tab title="Angle" %}
**Types:**\
**-** `AROUND_CENTER` - rotates around its center. (Default)\
\- `AROUND_X` - rotates about its X position.\
\- `AROUND_Y` - rotates about its Y position.\
\
`type` - How the shape is rotated. Find all available types above\
`value` - How many **degrees** to rotate the shape

```yaml
angle:  
  type: AROUND_CENTER 
  value: 45
```
{% endtab %}
{% endtabs %}

***

### 🎞️ `animation`

Controls how the shape moves.

```yaml
animation:
  type: ORIGINAL
  axis: VERTICAL_RIGHT
  direction: LEFT
  speed: 0.5
  tolerance:
    global: 0.5
  bounce:
    collision-gap: 1
```

#### Animation Types:

* `ORIGINAL` – Particles stand still, don't move
* `ROTATING` – Spins the shape.
* `PULSE` – Expands and contracts.
* `BOUNCE` – Two particles bounce inside the shape.
* `ORBITING` – Particles orbit around.
* `SPIRAL` – DNA-style spiral movement.

#### Common Animation Options:

| Key         | Description                                                                                                                  |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `axis`      | Direction of movement. All types can be found below the table.                                                               |
| `direction` | <p>The spin/movement direction: <code>LEFT</code>, <code>RIGHT</code>.<br>It is only used when the particles are moving.</p> |
| `speed`     | <p>Speed of the animation (0.5 is slow, 5 is fast).<br>It is only used when the particles are moving.</p>                    |

**Axis:**  HORIZONTAL\_RIGHT, VERTICAL\_LEFT, VERTICAL\_RIGHT, VERTICAL\_LEFT

### Setting individual animations

Each animation has its own settings. Animations that do not appear on this tab do not need any specific settings.

{% tabs %}
{% tab title="PULSE" %}
Type: `PULSE`

`min-radius` - Specifies the radius over which the animation will pulse, this parameter must always be smaller than the radius (in the settings section)

```yaml
pulse:
  min-radius: 3
```
{% endtab %}

{% tab title="BOUNCE" %}
Type: `BOUNCE`&#x20;

`collision-gap` - Determine how big the gap between the two particles will be at each bounce

```yaml
bounce:
 collision-gap: 2
```
{% endtab %}

{% tab title="SPIRAL" %}
Type: `SPIRAL`

max-height - How high will the spiral rise (in blocks). _Default value is 5_\
pitch-angle - What will be the angle of rotation of one particle. _Default value is 30_

```yaml
spiral:
  max-height: 4
  pitch-angle: 35
```
{% endtab %}

{% tab title="ORBITING" %}
Type: `ORBITING`

`count` - The number of particles that orbit along the shape at the same time.\
`wave-frequency` - How fast the particles pulse up and down (the wave's speed).\
`wave-amplitude` - How far the particles move when pulsing (the wave's height).

```yaml
orbiting:
  count: 2
  wave-frequency: 0.7
  wave-amplitude: 4
```
{% endtab %}
{% endtabs %}

***

### ✨ `particle`

```yaml
particle:
  type: FLAME
```

Instructions for setting up the particle are available [here](particle-display).

***

### 🚪 `enter`

```yaml
enter:
  success-actions:
    - message: '&a&lYou have entered the space!'
```

Triggered when a player **enters** the shape. Everything available about actions can be found [here](../setup/actions)

#### Conditons:

In the enter section you can also play with conditions

```yaml
enter:
  conditions:
    - permissions:
      - 'shape.enter'
  failure-actions:
    - message: '&cYou don''t have the required permissión you cannot enter the circle'
    - knockback: '2;0.1'
  success-actions:
  - message:
    - '&aYou entered the circle'
  - sound: ENTITY_EXPERIENCE_ORB_PICKUP;1;1
```

`conditions` – Requirements a player must meet to enter the shape (e.g. permissions).\
`success-actions` – Actions triggered when all conditions are met (e.g. messages, sounds).\
&#xNAN;**`failure-actions`** – Actions triggered when any condition is not met (e.g. knockback, warnings).

#### Tolerance:

You may have noticed that when you have the axis set to (`VERITCAL_LEFT,` `VERTICAL_RIGHT`) you don't always get actions, so I created a tolerance that solves this problem.

```yaml
tolerance:
  global: 0.5
```

Defines how close a player must be to the shape to trigger interactions (like entering). You can also use:

```yaml
tolerance:
  x: 0.5
  y: 1.0
  z: 0.3
```

To define separate tolerance for each direction.

***

`view-conditions`

Through this section you can set according to the conditions whether the player will see the shape or not

All available conditions can be found [here](../setup/conditions)

***

### 📝 Full Example

```yaml
shapes:
  test03: 
    enabled: true
    shape: CIRCLE  
    location: world(105,80,-75,19.8,118.8)
    settings:
      radius: 5
      points: 50
      fill: 
        use: false
        radius: 1
      view-distance: 30
      update-interval: 1
      angle: 
        type: AROUND_CENTER
        value: 45
    animation:
      type: BOUNCE
      axis: VERTICAL_RIGHT
      direction: LEFT
      speed: 0.5
      bounce:
        collision-gap: 1
    particle:
      type: FLAME
    enter:
      tolerance:
        global: 0.5
      success-actions:
      - message: '&a&lYou have entered the space!'
```
