Skip to content

Conversation

@sovdeeth
Copy link
Member

@sovdeeth sovdeeth commented Nov 30, 2025

Problem

Visual effects were on their last legs. The increase in particles requiring data and constant changes in what effects/particles existed meant that visual effects was not up to date, had problems with serializing values, was lacking functionality, and was horribly documented. Users were nearly always using SkBee's or skript-particle's particle syntaxes instead, as they featured fully functional syntax for setting offsets, data, and were reliable.

Solution

This PR separates visual effects into three categories: Game Effects (Effect.class), Entity Effects (EntityEffect.class), and Particle Effects (Particle.class, ParticleBuilder.class).

Game Effects.

Game effects are rather powerful effects to display particles, play sounds, or both at once. They make it easy to replicate existing ingame effects, like waxing, dispenser activations, turtle eggs cracking, and more. Very little changes from visual effects except that effects that do not require data are automatically supported, while data-requiring effects have a specific expression with documented patterns. This should alleviate the lack of docs for visual effects, who depended entirely on lang file entries for patterns and therefore were not documented.

Entity Effects

Entity effects do not require data and are therefore much simpler than game or particle effects. This PR mostly maintains the system from Visual Effect, though modernised with EnumClassInfo. The separation into its own classinfo, though, allows better parse time type checking and ensures entity effects aren't played at locations and are instead played at acceptable entities.

Particle Effects

Particle effects are the most complex and required the most work. Simple particle effects without data are now parsed via an EnumClassInfo and the data-requiring ones are registered in an expression like game effects. The particle system is now backed by a new ParticleEffect class, though, which extends Paper's ParticleBuilder class to provide storage of type, data, offset, speed, count, recipients, and more. This allows Skript to provide an easy to use and powerful particle api to addons without each needing its own wrapper class.

Since particles vary in behavior depending on count being 0 or 1+, ParticleEffect provides an ease of use function to set the particle distribution (the behavior of offset when count is 1+) which sets count to 1 if it is 0. You can also check whether it is in distribution mode. For behavior when count is 0, child classes of DirectionalEffect, ScalableEffect, and more exist to provide api to handle their behaviors, such as setting velocity or scale. These likewise set count to 0 if it is not already 0. This behavior is mirrored in the syntax, where velocity of {particle} is not set if count > 0, and setting it will set count to 0. This should provide the most intuitive and natural experience for the user, as setting the velocity will ensure the offset is treated as velocity, while setting the distribution will likewise ensure the offset is a distribution.

Drawing

Drawing all three effect types is handled through a single EffDrawEffect syntax which provides the extra options for each. This will likely be changed to a type property syntax in the future.

Testing Completed

EffDrawEffect.sk

Supporting Information

A helper class was added to yggsdrasil to aid in registering serializers for external classes without classinfos.

Documentation is not finished.

Miscellaneous behavior for particles has not been documented. More can be seen here: https://docs.papermc.io/paper/dev/particles/#miscellaneous-behaviors

Some of the syntaxes will likely be replaced by type properties in this or a later PR.

Significant breaking changes as Visual Effects will be removed and patterns will change for nearly all effects.


Completes: #8157 #7932 #5702 #5146 #4196
Related: none

sovdeeth and others added 15 commits February 23, 2024 22:56
# Conflicts:
#	src/main/java/ch/njol/util/VectorMath.java
#	src/main/resources/lang/default.lang
now i have to go through every one, check what it really does, and update its name accordingly
fun
use particle builder as a base class
separate child impls for properties like directional
add expressions for offset/speed/scale/distribution/velocitty/count
velocity/scale and distribution automatically change count as supported
add serialization for particle datas (required a helper class in yggsdrasil)
better particle info registration for particles with data
@sovdeeth sovdeeth added enhancement Feature request, an issue about something that could be improved, or a PR improving something. feature Pull request adding a new feature. breaking changes Pull or feature requests that contain breaking changes (API, syntax, etc.) labels Nov 30, 2025
@sovdeeth sovdeeth moved this to In Progress in 2.14 Releases Nov 30, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

breaking changes Pull or feature requests that contain breaking changes (API, syntax, etc.) enhancement Feature request, an issue about something that could be improved, or a PR improving something. feature Pull request adding a new feature.

Projects

Status: In Progress

3 participants