-
-
Notifications
You must be signed in to change notification settings - Fork 414
Replace the Visual Effect system #8302
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Draft
sovdeeth
wants to merge
19
commits into
dev/feature
Choose a base branch
from
feature/particle-rework
base: dev/feature
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Draft
+3,403
−221
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
# 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
This was
linked to
issues
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.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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
offsetwhen 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, wherevelocity 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