Trigger system for entities leaving/entering a region

[Z0rdak]

Description

To handle players entering and leaving regions, a trigger-like system (optimal with events) would be handy.

Beside other things, this system would allow it to display the region name or other messages to the player when entering/leaving a region. It also could be extended to execute commands or do other things.

Player tracking around regions

To implement triggers for entering and leaving a region, the position of players relative to regions needs to be tracked.

This system needs to be configurable to be adaptable to different server enviroments to limit the impact on CPU cycles spend on tracking the players.

There will be 3 player tracking caches. They will track players with their distance to nearby regions.

Cache 1 - Players within 100 Block radius around any region, refreshed every 100 ticks Cache 2 - Players within 50 Block radius around any region, refreshed every 40 ticks Cache 3 - Players within 25 Block radius around any region, refreshed every 20 ticks

Map<Player, <List<TrackedRegion>> trackingCache

The Block and tick numbers are just an example and will be configurable. The travel speed of players (Blocks/tick) needs to be considered here.

• Entering a region is defined as the prevBlockPosbeing outside a region boundary and the currentBlockPosbeing inside a region.
• Leaving a region is defined as the prevBlockPosbeing inside a region boundary and the currentBlockPosbeing outside a region.

Additional thoughs

• Pausing the tracking of a player when he/she is afk would improve the performance
• Teleporting inside/near to regions needs to be considered (updating cache accordingly)
• Only consider active dimensions for caching
• Only consider loaded chunks for caching
• Cache 1-3 for each dimension
• For simplicity and easier cache management, the cache would only exists in memory. On server restart, the cache would need to be populated again with each joining player -> Hooking into PlayerJoinServer event

Map<ResourceKey<Level>, TrackingCache> trackingCachesPerDim Where TrackingCache would be an abstraction over the three different caches for a dimension.

API

Triggers will create an event which is fired for other mods to hook into.

These events will also be used by YAWP itself to implement the trigger action handling.

Events:

void PlayerLeave(Player player, IProtectedRegion region);
void PlayerEnter(Player player, IProtectedRegion region);
void EntityLeave(Entity entity, IProtectedRegion region);
void EntityEnter(Entity entity, IProtectedRegion region);

RegionAPI:

• Set<Player> GetPlayersInRegion(IProtectedRegion region);

Trigger types

There are two types of Trigger: PlayerTrigger and EntityTrigger

With three different TriggerConditions: Enter, Leave, Both

• A region can have multiple triggers for each of these types.
• A trigger can invoke an action/actions.
• Triggers can be modified with filters
• Triggers can be activated and deactivated for easier managemen.

PlayerTrigger

Only triggers when a player enter or leaves a region. Can be modified by a filter.

The filter allows for filtering for players within a certain group.

EntityTrigger

Triggers when a entity enter or leaves a region. Can be modified by a filter.

The filter allows filtering for a specific EntityType, Name or Tag of the Entity.

Actions

An action is a defined command which will be executed when a trigger is activated. Examples for (predefined) triggers are:

• displaying a text
• sending a message to a player
• changing the gamemode
• executing a command (very general and covers the above-mentioned ones, but they are there for convenience)
• log event to console
• ...

• Actions have an order, they are executed in this order to ensure consistency. The order is determined by an integer.
• Actions can be activated and deactivated for easier managemen.

Command-Syntax

The syntax could be the following (here for local regions):

• /wp trigger <dim> <region> add trigger <player|entity> <leave|enter|both> <trigger-name> [filter]

• /wp trigger <dim> <region> remove trigger <trigger-name>

• /wp trigger <dim> <region> enable trigger <trigger-name>

• /wp trigger <dim> <region> disable trigger <trigger-name>

• /wp trigger <dim> <region> list trigger

• /wp trigger <dim> <region> list actions <trigger-name>

• /wp trigger <dim> <region> add action <trigger-name> exec <cmd> <order>

• /wp trigger <dim> <region> add action <trigger-name> title <title> <subtitle> <order>

• /wp trigger <dim> <region> add action <trigger-name> msg <msg> <order>

• /wp trigger <dim> <region> add action <trigger-name>... ... <order>

• /wp trigger <dim> <region> order action <trigger-name> <order>

• /wp trigger <dim> <region> enable action <orderPos>

• /wp trigger <dim> <region> disable action <orderPos>

• /wp trigger <dim> <region> remove action <orderPos>

For easier management a pagination for trigger and actions should be considered.

Triggers are only applicable for Local Regions and Dimensional Regions

[Z0rdak]

Suggestion from Discord: Trigger for playing music when entering region

[Z0rdak]

Updated Feature description