Add customisability for surface index dust particles

[SilverDorian46]

Jumping off, landing on the top, or sliding down the side of a Platform will make dust particles appear. In vanilla, the same dust particles are used for every surface index except the Glitch one (used in sci-fi tiles), which uses different particles. This is tied to surface index, instead of tile type as one would likely expect, but that does mean it applies across every sort of Platform.

These additions allow mappers to define their own dust particle types for use with their tilesets. As this is tied to surface indices, the sound attribute will still be required, and it is recommended to set its value greater than the range that is already defined (50 is a good number to start from). The new attributes for Tileset are as follows:

• soundParam: Makes this surface index play a different sound, by setting the "surface_index" parameter to the value. For example, setting a value of "40" makes it play the Glitch sound. The purpose of this is to make new surface indices play already existing sounds without having to set up a different event for them. This is also useful in cases where a different event is used with the soundPath attribute.
• dustParticles: Assigns a dust particle type for this surface index. This links to an element of the same name as the value, defined as a child node of a DustParticles element. The setup for that will be explained below.

After defining the Tileset elements with dustParticles, mappers will need to create a new separate element on the same level (should be a direct child of Data) named DustParticles. This will hold child elements that each represent a particle type. The name of each child element is linked to by the respective dustParticles attribute in a Tileset, allowing for reuse. The attributes for child elements of DustParticles are as follows:

• copy: By default, dust particle types copy from ParticleTypes.Dust. However, if this attribute is defined, the value indicates which particle type to copy from. An element of the same name as the value must be defined before this element. Exceptions include the preset values Dust and SparkyDust, which makes the particle type copy from ParticleTypes.Dust and ParticleTypes.SparkyDust respectively. Note that SparkyDust itself copies from Dust, albeit with its own values. This input is case-insensitive.
• sourceChooser: Provides a set of textures for each particle of this type to randomly choose from. In the same way as defining an animation, this looks for numbered textures in a given path. The value is the path to those textures, relative to the Gameplay atlas. For particle types copying from Dust (by default), the value is equivalent to "particles/smoke", and for those copying from SparkyDust, "particles/zappySmoke".
• color: Gives this particle type a colour through a hexadecimal value. Particle types copying from Dust (by default) have the value of "ffffff", while those copying from SparkyDust have the value of "5be1cd".
• color2: Gives this particle type a secondary colour through a hexadecimal value. By default, the value is "ffffff", but particle types copying from SparkyDust have the value of "aafab6".
• colorMode: Defines how the colours of this particle type are handled. This accepts one of four values (case-insensitive): "Static", "Choose", "Blink", and "Fade". The default value is "Static", but particle types copying from SparkyDust have the value of "Blink".
  • "Static" sets the particle colour to color.
  • "Choose" randomly chooses between color and color2 for each particle.
  • "Blink" swaps the particle colour between color and color2 every tenth of a second.
  • "Fade" makes the particle colour fade from color to color2 from start to end of life.
• wallSlideOffsetX: When the player slides down a wall, the position of the emitted particles differs depending on the particle type. The vanilla code checks for whether the particle is of type ParticleTypes.Dust, and if so, it is offset by 5 pixels in the X-axis from the player's center, otherwise it is offset by 2 pixels. As a result, the Dust particles are emitted further into the wall than the SparkyDust particles. This attribute allows setting a number of pixels in the X-axis relative to the player's center, to customise how far into the wall to emit the particles.

On the side of Everest, we create the dictionaries SurfaceIndex.IndexToSoundParam and SurfaceIndex.IndexToDustParticles to add the soundParam and dust particle type definitions into respectively, as well as the dictionary SurfaceIndex.DustParticlesToWallSlideOffsetX for the particle offsets while sliding down a wall.

• We patch Player and NPC methods to include a check using our SurfaceIndex.GetSoundParamFromIndex method, working alongside SurfaceIndex.GetPathFromIndex, to modify the value to which the "sound_index" audio parameter is set, with the original value as a fallback.
• We also introduce two new patches to the Player class.
  • DustParticleFromSurfaceIndex now uses our SurfaceIndex.GetDustParticleTypeFromIndex at the start to check if the index has a defined dust particle type. If the check passes, that particle type is returned, and if it fails, the rest of the method is run.
  • CreateWallSlideParticles now uses a patch method to try to retrieve a value from the SurfaceIndex.DustParticlesToWallSlideOffsetX dictionary. If no value is retrieved, or if the particle is not a custom dust particle type, then it falls back to the original assignment.

As always, feedback on the implementation, as well as additional testing and any changes to suggest, would be appreciated.

---

Resolves: #748

[microlith57]

• good idea, thanks for implementing this!
• not so keen on the idea of defining custom particletypes in the tileset xml; there really ought to be eg. a ParticleTypes.xml for that specific purpose
• would it be possible for modded entities to choose to have a custom particle type per entity? eg. a block with an instance field Color dustColor for the dust created when climbing / landing on that block
  • maybe this could be a component with a callback?

[SilverDorian46]

• good idea, thanks for implementing this!

• not so keen on the idea of defining custom particletypes in the tileset xml; there really ought to be eg. a ParticleTypes.xml for that specific purpose

• would it be possible for modded entities to choose to have a custom particle type per entity? eg. a block with an instance field Color dustColor for the dust created when climbing / landing on that block

  • maybe this could be a component with a callback?

I think so, but I'll figure it out later when I get to it.
For the time being though, I'm preparing a separate commit for just a few other things to be merged in advance while this gets sorted out

[SnipUndercover]

@SilverDorian46 Any updates on this PR?

[SilverDorian46]

@SilverDorian46 Any updates on this PR?

not really

[SnipUndercover]

Considering this isn't finished yet, I think the PR should be changed to a draft, would you agree?

[SnipUndercover]

Due to a lack of activity, we decided to close this PR. Please reopen the PR or make a new one if this feature will be picked up again in the future.