Skip to content

Particle Configuration

Jump to bottom
OpticFusion1 edited this page Feb 28, 2023 · 1 revision

Overview

This section of the wiki provides information on how to properly configure particle groups in /plugins/Aurora/particles/.

Example particle group configs

NOTE: All particle configs will have different required values in properties depending on the shape set in particle.particleType. You should use these configs below as templates if you wish to create new particle groups depending on its shape.

General particle configuration

{
  "name": "Example Particle",
  "enabled": true,
  "spawning": {
    "biomes": [
      "PLAINS",
      "PRESENT: SHORE"
    ],
    "spawnDistance": 10.0,
    "randMultiplier": 0.5,
    "relativePlayerPosition": false,
    "minY": 80.0,
    "maxY": 100.0,
    "shuffleLocations": true
  },
  "particle": {
    "particleName": "FLAME",
    "particleType": "CUBE",
    "maxCount": 8,
    "enableLighting": false
  },
  "properties": {
    (You should set this based on the shape defined in particle.particleType)
    (Refer to the templates for each shape below)
  }
}
  • name - Unique string to identify your particle config
  • enabled - Boolean to toggle whether your particle is enabled
  • spawning.biomes - Array of Spigot biomes your particle will be shown in
    • Biome presents are supported in Aurora 1.2.0 and above
    • ALL is supported in Aurora 2.3 and above
  • spawning.spawnDistance - Double for the minimum distance between shapes Aurora will spawn from the same config
  • spawning.randMultiplier - Double for how far the location calculation of spawning.spawnDistance should deviate from its actual value
    • Should be between 0 (0%) and 1.0 (100%)
  • spawning.relativePlayerPosition - Boolean to toggle whether spawning.minY and spawning.maxY should be heights relative to the current player or fixed values
  • spawning.minY - Double for the minimum y-coordinate the particle will spawn at
  • spawning.maxY - Double for the maximum y-coordinate the particle will spawn at
  • spawning.shuffleLocations - Boolean to toggle whether calculated particle-spawn locations in the internal list should be randomised
    particle.particleName - Spigot particle the shape should be made of
  • particle.particleType - Aurora particle shape
    • Can be
      • POINT
      • LINE
      • CUBE
      • RING
      • CIRCLE
      • SPHERE
      • WAVE
  • particle.maxCount - Integer for the maximum number of shapes from the same config that can appear at any one time per player
  • particle.enableLighting - Boolean to toggle whether lighting should be set at particle-spawn locations
    • It is recommended to disable this as lighting may not update correctly when a chunk is unloaded, leaving "ghost" light sources
    • Only enable if your particle cannot be seen in the dark, or if spawning.minY is above 100
  • properties - Configuration section depending on particle.particleType

Point particle type

  "properties": {
    "update": 5,
    "duration": 20
  }
  • properties.update - Integer for how often the server should update the particle in ticks
    • It is recommended to set this value above 5 for non-moving shapes to avoid unnecessary server lag and FPS drops for clients as most particles will stay for a few ticks even if not updated
    • For moving particles with LINE or WAVE particle types, this value determines how fast the shape travels (smaller = faster)
      • You should use the properties.rate parameter to change the speed of particles while keeping properties.update large for better performance
  • properties.duration - Long (integer) of the duration each particle in a shape should should stay for

Line particle type

  "properties": {
    "rate": 0.5,
    "update": 1,
    "duration": 1
  }
  • properties.rate - Double for the distance between each individual particle inside a shape
    • It is recommended to set this value between 0.2 and 0.5 for optimal performance and nice-looking shapes
    • For larger shapes like SPHEREs with a large radius, it is recommended to keep this value large to avoid server lag by spawning fewer particles in the shape
    • For moving particles with LINE or WAVE particle types, this value determines how fast the shape travels (larger = faster)
      • You should use the properties.rate parameter to change the speed of particles while keeping properties.update large for better performance

Cube particle type

  "properties": {
    "length": 3.0,
    "rate": 0.5,
    "update": 5,
    "duration": 200,
    "rotationAngle": 50.0,
    "rotationAxis": "x"
  }
  • properties.length - Double for length of a cuboid object
  • properties.rotationAngle - Double for angle the object should be rotated by
  • properties.rotationAxis - Character for axis the object should be rotated in. Can be x, y or z

Ring particle type

  "properties": {
    "radius": 2.0,
    "rate": 0.3,
    "update": 5,
    "duration": 70,
    "rotationAngle": -35.0,
    "rotationAxis": "x"
  }
  • properties.radius - Double for radius of a circular object

Circle particle type

  "properties": {
    "radius": 1.5,
    "rate": 0.3,
    "update": 5,
    "duration": 100,
    "rotationAngle": 35.0,
    "rotationAxis": "x"
  }

Sphere particle type

  "properties": {
    "radius": 1.0,
    "rate": 0.2,
    "update": 5,
    "duration": 150
  }

Wave particle type

  "properties": {
    "rate": 0.5,
    "update": 1,
    "duration": 5,
    "waveCycles": 6.0,
    "waveAmplitude": 3.0,
    "rotationAngle": 50.0,
    "rotationAxis": "x"
  }
  • properties.waveCycles - Double for how many complete cycles the wave should consist of
  • properties.waveAmplitude - Double for the maximum height in blocks of each wave relative to its midpoint

Value randomisation

As of Aurora 1.2.0, value randomisation is supported in all subnodes of the properties node. What this means is that all values under properties will support the array datatype in addition to their original types. Using the cube particle type as example,

  "properties": {
    "length": 3.0,
    ...

can be changed to

  "properties": {
    "length": [2.0, 5.0]
    ...

so that all newly spawned cubes will have a random length parameter between 2.0 and 5.0. Here are a few notes when using the randomise feature:

  • Only arrays with the following structure [min, max] will be accepted by the plugin
  • Elements in the array must still obey the original datatype of the variable (see properties)
    • For example, if the original datatype is an integer, both array values must be integers as well
  • For properties.rotationAxis, arrays of any type will not be accepted
    • Using ["x", "y"] or ["x", "y", "z"] will result in a parsing error
    • To randomise this variable, use the character "r" instead
  • This feature is only supported in Aurora 1.2.0 and above

Troubleshooting

If your particle group does not show ingame even after you have reloaded the plugin, check for errors in the console. There should be a debug message before the error letting you know which particle file(s) are faulty and should be modified or removed.

Bad JSON formatting

All particle configs are stored as .json files. It is highly recommended to use a json parser to check for any JSON parsing errors before you load the file.

Incorrect config values

You may be omitting required parameters for your particle group config. Note that each particle type in particle.particleType can have differing configuration nodes in properties. For example, the CUBE particle type will have the LENGTH parameter while the SPHERE particle type will have the RADIUS parameter instead. For a more detailed breakdown of each particle type, refer to the example configs.

Other

If there are no errors in the console but you still do not see the particle group you have configured, it may be due to either of the following:

  • You have not reloaded the particle config with /aurora reload
  • You are using an incorrect biome name in spawning.biomes
  • You are using an incorrect particle name in particle.particleName. Names are version-dependent, so make sure to use the correct one for your server version
  • You have ambient particles disabled server-side. Make sure you have the permission node aurora.view and use the command /aurora toggle on
  • You have particles disabled client-side. Make sure to enable them in Options -> Video Settings -> Particles: All

Aurora

Configuration

Support

Clone this wiki locally