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.

Some of the syntaxes will likely be replaced by type properties in 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
@skriptlang-automation skriptlang-automation bot added the needs reviews A PR that needs additional reviews label Dec 9, 2025
@sovdeeth sovdeeth moved this from In Progress to In Review in 2.14 Releases Dec 13, 2025
Copy link
Member

@APickledWalrus APickledWalrus left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This look really good! Most of my comments are around formatting/code tweaks. The design itself looks fantastic.

Copy link
Member

@APickledWalrus APickledWalrus left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just a few minor things. I think just using Origin (or directly importing ModuleOrigin) for the register methods should be okay.

@github-project-automation github-project-automation bot moved this from In Review to Awaiting Merge in 2.14 Releases Dec 30, 2025
@skriptlang-automation skriptlang-automation bot added feature-ready A PR/issue that has been approved, tested and can be merged/closed in the next feature version. and removed needs reviews A PR that needs additional reviews labels Dec 30, 2025
@sovdeeth sovdeeth merged commit f7e2932 into dev/feature Dec 31, 2025
10 checks passed
@skriptlang-automation skriptlang-automation bot added the completed The issue has been fully resolved and the change will be in the next Skript update. label Dec 31, 2025
@github-project-automation github-project-automation bot moved this from Awaiting Merge to Done - Awaiting Release in 2.14 Releases Dec 31, 2025
@skriptlang-automation skriptlang-automation bot removed the feature-ready A PR/issue that has been approved, tested and can be merged/closed in the next feature version. label Dec 31, 2025
@APickledWalrus APickledWalrus moved this from Done - Awaiting Release to Done - Released in 2.14 Releases Jan 2, 2026
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.) completed The issue has been fully resolved and the change will be in the next Skript update. 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: Done - Released

5 participants