191 lines
11 KiB
Markdown
191 lines
11 KiB
Markdown
# Scarpet events system
|
|
|
|
Provides the ability to execute specific function whenever an event occurs. The functions to be registered need to
|
|
conform with the arguments to the event specification. When loading module functions, each function that starts
|
|
with `__on_...` and has the required arguments, will be bound automatically. In case of player specific modules,
|
|
all player action events will be directed to the appropriate player space, and all tick events will be executed in
|
|
the global context, so its not a good idea to mix these two, so use either of these, or use commands to call tick
|
|
events directly, or handle player specific data inside an app.
|
|
|
|
Most events strive to report right before they take an effect in the game. The purpose of that is that this give a choice
|
|
for the programmer to handle them right away (as it happens, potentially affect the course of action by changing the
|
|
environment right before it), or decide to handle it after by scheduling another call for the end of the tick. Or both -
|
|
partially handle the event before it happens and handle the rest after. While in some cases this may lead to programmers
|
|
confusion (like handling the respawn event still referring to player's original position and dimension), but gives much
|
|
more control over these events.
|
|
|
|
## Event list
|
|
|
|
Here is a list of events that are handled by scarpet. This list includes prefixes for function names, allowing apps
|
|
to autoload them, but you can always add any function to any event (using `/script event` command)
|
|
if it accepts required number of parameters.
|
|
|
|
## Global events
|
|
|
|
Handling global events is only allowed in apps with `'global'` scope. With the default scope (`'player'`) you
|
|
simply wouldn't know which player to hook up this event to. All other events can be handled by any app type.
|
|
|
|
### `__on_tick()`
|
|
Event triggers at the beginning of each tick, located in the overworld. You can use `in_dimension()`
|
|
to access other dimensions from there.
|
|
|
|
### `__on_tick_nether()` (Deprecated)
|
|
Duplicate of `tick`, just automatically located in the nether.
|
|
|
|
### `__on_tick_ender()` (Deprecated)
|
|
Duplicate of `tick`, just automatically located in the end.
|
|
|
|
### `__on_chunk_generated(x,z)`
|
|
Called right after a chunk at a given coordinate is full generated. `x` and `z` correspond
|
|
to the lowest x and z coords in the chunk. Event may (or may not) work with Optifine installed
|
|
at the same time.
|
|
|
|
### `__on_lightning(block, mode)`
|
|
Triggered right after a lightning strikes. Lightning entity as well as potential horseman trap would
|
|
already be spawned at that point. `mode` is `true` if the lightning did cause a trap to spawn.
|
|
|
|
### `__on_carpet_rule_changes(rule, new_value)`
|
|
Triggered when a Carpet rule is changed. It includes extension rules, which will be namespaced as `namespace:rule`.
|
|
|
|
## Player events
|
|
|
|
These are triggered with a player context. For apps with a 'player' scope, they trigger once for the appropriate
|
|
player. In apps with `global` scope they trigger once for all players.
|
|
|
|
### `__on_player_uses_item(player, item_tuple, hand)`
|
|
Triggers with a right click action. Event is triggered right after a server receives the packet, before the
|
|
game manages to do anything about it. Event triggers when player starts eating food, or starts drawing a bow.
|
|
Use `player_finishes_using_item`, or `player_releases_item` to capture the end of these events.
|
|
|
|
Event is not triggered when a player places a block, for that use
|
|
`player_right_clicks_block` or `player_places_block` event.
|
|
|
|
### `__on_player_releases_item(player, item_tuple, hand)`
|
|
Player stops right-click-holding on an item that can be held. This event is a result of a client request.
|
|
Example events that may cause it to happen is releasing a bow. The event is triggered after the game processes
|
|
the request, however the `item_tuple` is provided representing the item that the player started with. You can use that and
|
|
compare with the currently held item for a delta.
|
|
|
|
### `__on_player_finishes_using_item(player, item_tuple, hand))`
|
|
Player using of an item is done. This is controlled server side and is responsible for such events as finishing
|
|
eating. The event is triggered after confirming that the action is valid, and sending the feedback back
|
|
to the client, but before triggering it and its effects in game.
|
|
|
|
### `__on_player_clicks_block(player, block, face)`
|
|
Representing left-click attack on a block, usually signifying start of breaking of a block. Triggers right after the server
|
|
receives a client packet, before anything happens on the server side.
|
|
|
|
|
|
### `__on_player_breaks_block(player, block)`
|
|
Called when player breaks a block, right before any changes to the world are done, but the decision is made to remove the block.
|
|
|
|
### `__on_player_right_clicks_block(player, item_tuple, hand, block, face, hitvec)`
|
|
Called when player right clicks on a block with anything, or interacts with a block. This event is triggered right
|
|
before other interaction events, like `'player_interacts_with_block'` or `'player_places_block'`.
|
|
|
|
### `__on_player_interacts_with_block(player, hand, block, face, hitvec)`
|
|
Called when player successfully interacted with a block, which resulted in activation of said block,
|
|
right after this happened.
|
|
|
|
### `__on_player_places_block(player, item_tuple, hand, block)`
|
|
Triggered when player places a block, after block is placed in the world, but before scoreboard is triggered or player inventory
|
|
adjusted.
|
|
|
|
### `__on_player_interacts_with_entity(player, entity, hand)`
|
|
Triggered when player right clicks (interacts) with an entity, even if the entity has no vanilla interaction with the player or
|
|
the item they are holding. The event is invoked after receiving a packet from the client, before anything happens server side
|
|
with that interaction
|
|
|
|
### `__on_player_collides_with_entity(player, entity)`
|
|
Triggered every time a player - entity collisions are calculated, before effects of collisions are applied in the game.
|
|
Useful not only when colliding with living entities, but also to intercept items or XP orbs before they have an effect
|
|
on the player.
|
|
|
|
### `__on_player_chooses_recipe(player, recipe, full_stack)`
|
|
Triggered when a player clicks a recipe in the crafting window from the crafting book, after server received
|
|
a client request, but before any items are moved from its inventory to the crafting menu.
|
|
|
|
### `__on_player_switches_slot(player, from, to)`
|
|
Triggered when a player changes their selected hotbar slot. Applied right after the server receives the message to switch
|
|
the slot.
|
|
|
|
### `__on_player_swaps_hands(player)`
|
|
Triggered when a player sends a command to swap their offhand item. Executed before the effect is applied on the server.
|
|
|
|
### `__on_player_attacks_entity(player, entity)`
|
|
Triggered when a player attacks entity, right before it happens server side.
|
|
|
|
### `__on_player_takes_damage(player, amount, source, source_entity)`
|
|
Triggered when a player is taking damage. Event is executed right after potential absorbtion was applied and before
|
|
the actual damage is applied to the player.
|
|
|
|
### `__on_player_deals_damage(player, amount, entity)`
|
|
Triggered when a player deals damage to another entity. Its applied in the same moment as `player_takes_damage` if both
|
|
sides of the event are players, and similar for all other entities, just their absorbtion is taken twice, just noone ever
|
|
notices that ¯\_(ツ)_/¯
|
|
|
|
### `__on_player_dies(player)`
|
|
Triggered when a player dies. Player is already dead, so don't revive them then. Event applied before broadcasting messages
|
|
about players death and applying external effects (like mob anger etc).
|
|
|
|
### `__on_player_respawns(player)`
|
|
Triggered when a player respawns. This includes spawning after death, or landing in the overworld after leaving the end.
|
|
When the event is handled, a player is still in its previous location and dimension - will be repositioned right after.
|
|
|
|
|
|
### `__on_player_changes_dimension(player, from_pos, from_dimension, to_pos, to_dimension)`
|
|
Called when a player moves from one dimension to another. Event is handled still when the player is in its previous
|
|
dimension and position.
|
|
|
|
`player_changes_dimension` returns `null` as `to_pos` when player goes back to the overworld from the end
|
|
, since the respawn location of the player is not controlled by the teleport, or a player can still see the end credits. After
|
|
the player is eligible to respawn in the overworld, `player_respawns` will be triggered.
|
|
|
|
### `__on_player_rides(player, forward, strafe, jumping, sneaking)`
|
|
Triggers when a server receives movement controls when riding vehicles. Its handled before the effects are applied
|
|
server side.
|
|
|
|
### `__on_player_jumps(player)`
|
|
Triggered when a game receives a jump input from the client, and the player is considered standing on the ground.
|
|
|
|
|
|
### `__on_player_deploys_elytra(player)`
|
|
Triggered when a server receives a request to deploy elytra, regardless if the flight was agreed upon server side..
|
|
|
|
### `__on_player_wakes_up(player)`
|
|
Player wakes up from the bed mid sleep, but not when it is kicked out of bed because it finished sleeping.
|
|
|
|
### `__on_player_starts_sneaking(player)`
|
|
### `__on_player_stops_sneaking(player)`
|
|
### `__on_player_starts_sprinting(player)`
|
|
### `__on_player_stops_sprinting(player)`
|
|
Four events triggered when player controls for sneaking and sprinting toggle.
|
|
|
|
### `__on_player_drops_item(player)`
|
|
### `__on_player_drops_stack(player)`
|
|
Triggered when the game receives the request from a player to drop one item or full stack from its inventory.
|
|
Event happens before anything is changed server side.
|
|
|
|
### `__on_player_picks_up_item(player, item)`
|
|
Triggered AFTER a player successfully ingested an item in its inventory. Item represents the total stack of items
|
|
ingested by the player. The exact position of these items is unknown as technically these
|
|
items could be spread all across the inventory.
|
|
|
|
### `__on_player_connects(player)`
|
|
Triggered when the player has successfully logged in and was placed in the gaem.
|
|
|
|
### `__on_player_disconnects(player, reason)`
|
|
Triggered when a player sends a disconnect package or is forcefully disconnected from the server.
|
|
|
|
### `__on_statistic(player, category, event, value)`
|
|
Triggered when a player statistic changes. Doesn't notify on periodic an rhythmic events, i.e.
|
|
`time_since_death`, `time_since_rest`, and `played_one_minute` since these are triggered every tick. Event
|
|
is handled before scoreboard values for these statistics are changed.
|
|
|
|
### `/script event` command
|
|
|
|
used to display current events and bounded functions. use `add_to` ro register new event, or `remove_from` to
|
|
unbind a specific function from an event. Function to be bounded to an event needs to have the same number of
|
|
parameters as the action is attempting to bind to (see list above). All calls in modules loaded via `/script load`
|
|
that have functions listed above will be automatically bounded and unbounded when script is unloaded.
|