What is a block event?
"Block event" is a term that's used on occasion in WatchFox, especially regarding rollback.
In short, a "block event" is an event that changes a block.
Now, how that's defined is where things get fuzzy and why this page exists.
For example, breaking a dirt block is clearly a block event. It represents a dirt block becoming an air block.
However, toggling a redstone lamp on / off isn't a block event.
Despite both events changing the ID of the block, the latter event doesn't change the block's "essence".
So what's the importance of all this?
Events that manipulate block state, and declare themselves as "block events" on event registration are added to a list maintained by WatchFox (and accessed by getBlockEvents()) that is used to determine whether a particular event should be rolled back or not.
That was a mouthful, so an example:
Say in a simplified system, we only had block_break and block_place events.
They both declare themselves as block events and in their RollbackAgents they both use getBlockEvents() in their getBlacklist() methods.
This means that any block_break events will be superseded if a block is placed in that spot.
It also means any block_place event will be superseded if the block is broken.
(It also handles the cases that might not be possible, but realize not all plugins log to WatchFox)
In a closed system like this, it's easy enough to see what's going on. But say we want to add block_transform.
Block_transform will change the state of a block, say transform dirt into gold.
We don't want rollback the dirt placement if someone else has already transformed it.
We also don't want to undo any block_places or block_breaks that also occurred. It also wouldn't be right to put a Goo block back if it was previously broken.
The solution to all this is for block events to register themselves as such and use getBlockEvents() (in the getBlacklist() method) as provided by the API.
A plugin attempting to rollback will be able to check that it's OK to do so, even if it has no idea what other plugins are being used. It also means that your block won't be modified by someone else if your event is a "block event".
Since all of this occurs on the assumption that events are correctly flagged, please remember to mark your events as necessary, and to use getBlockEvents() in your blacklist where appropriate.
Special considerations regarding the event blacklist
If your plugin has special effects that defy common physics, you can tailor this returned array, removing or adding your own events as necessary to achieve the correct results.
For example, pistons extending and retracting is *not* a block event (otherwise one could grief with pistons have them persistent by toggling them), however, they need to supersede each other, so their RollbackAgents concat the opposite event onto the array provided by getBlockEvents().
In the event excluding one your own events from the "blacklist" makes sense, you will have to build a new array. Do NOT set the String inside to null. This will be fixed in time, but it's broken as of now!
Links: Home | API Home | Tutorials | Searching | Event Naming | Block Events