Rework Potions

[APickledWalrus]

Problem

Potions syntax in Skript is confusing, duplicated, and fails to follow vanilla behavior. Support for numerous properties of potion effects/potion effects types are missing.

Solution

This pull request aims to completely rework (and reimagine) how potions can be used with Skript. The primary goals of this rework were as follows:

• Introduce a Potions Module that makes use of the latest API
• Follow behavior that ensures potions work just as they do in vanilla
• Implement full support for all potions-related API
• Reduce the complexity of syntaxes (both in duplication and length)
• Create syntax (especially changers) that make potions easy to use
  • The goal is to not simply implement the API, but implement it in a way that blends seamless with Skript's style

I believe this rework has now achieved these goals, and the breaking changes are well worth the benefits.

Obtaining Potion Effects

Just as before, potion effects can be obtained through syntax like:

set {_potions::*} to the potion effects of the player

However, it is now also possible to obtain specific potion effects:

set {_speed} to the player's speed effect

Potion Creation

Potions are currently buildable using an Expression or an Effect. What properties are available in each is not consistent. For this rework, the potion syntax has been condensed into an Expression (Section) for building potions:

apply an ambient potion effect of speed of tier 5 to the player for 15 seconds:
	hide the particles
	hide the icon

The potion effect has been replaced with an effect for applying potion effects. It does have the ability to override the duration as this enables nicer syntax: apply speed to the player for 15 seconds rather than apply potion effect of speed for 15 seconds to the player

Potion Modification

The six primary properties of potion effects are supported: type, duration, amplifier, ambient, particles, and icon.
All of these properties may be modified in the builder (see above).

It is also now possible to modify existing potion effects:

set the amplifier of {_potion} to 5
apply {_potion} to {_entity}

More impressively, it is now possible to modify potion effects that are actively applied to entities and items:

set the duration of the player's active speed effect to 5 minutes
set the amplifier of the player's slowness effect to 10
make the potion effects of the player's tool infinite

Hidden Effects

Full support for hidden effects has been implemented too. Hidden effects allow a player to have multiple effects of the same type. For example, if a player has speed 1 for 30 seconds, and is then affected by speed 2 for 15 seconds, after those 15 seconds, the player will have 15 seconds of speed 1 remaining.

Support for obtaining these effects has been implemented:

set {_effects::*} to the player's potion effects # only active effects
set {_effects::*} to the player's active effects # only active effects
set {_effects::*} to the player's hidden effects # only hidden effects
set {_effects::*} to the player's active and hidden effects # all effects

Just as with active effects, hidden effects support being changed too! How they work with changers is specific, so I'll cover the behavior below:

# clears active AND hidden effects
clear the player's speed effect
clear the player's potion effects
# otherwise, use active/hidden/both to specify

# modifies ONLY active effects
add 5 minutes to the player's speed effect
remove 5 minutes from the player's speed effect
# otherwise, use active/hidden/both to specify

Comparisons

Support for more lenient comparisons has been implemented too:

player has speed 10 # checks type, amplifier
player has a potion effect of speed for 30 seconds # checks type, duration

CondCompare (e.g. x is y) can be used for exact comparisons.

These comparisons are also used for removals:

remove speed 10 from the player's potion effects # removed effects must match type, amplifier
remove potion effect of speed for 30 seconds from the player's potion effects # removed effects must match type, duration

Other Changes

... more to come!

Testing Completed

Added potion module.sk which includes extensive testing of all syntax.

Supporting Information

There are multiple breaking changes included in these changes:

---

Completes: #4178
Related: none

[APickledWalrus]

Marking as a draft again as more in-depth changes are now planned

[TheLimeGlass]

I don't agree with PotionEffectType to PotionEffect as a converter because you can simply do [new] potion effect of %potioneffecttype% currently to return a basic potion.

What converter you would need is PotionEffect to PotionEffectType.

[APickledWalrus]

I've now pushed my major changes that have been sitting locally for a while now. This PR depends on #4573, so there is currently some temporary stuff going on to register the potion stuff.

[APickledWalrus]

This pull request is finally ready to review! There are some minor fixes/changes I need to make, but the core of the rework is ready. I'll also be updating the description with more information early next week.

[sovdeeth]

surface level pass

[sovdeeth]

CondContains conflicts? %inventories% (has|have) %itemtypes%

[APickledWalrus]

CondContains has an earlier priority, so I think this should be okay? I can't think of a great syntax here, and I'd like to avoid something like player has potion potion effect of speed... type hints (once widely available) would resolve any issues like this. The optional active keyword exists for dealing with conflicts in the meantime - which is the approach I think we should prefer to take for these situations

[Efnilite]

potion of pickle 😋

[Efnilite]

could this be a nested class to avoid indentation hell

[APickledWalrus]

II might prefer to keep them together, but if you really think the indentation is too much

[erenkarakal]

just some small documentation stuff