-
Notifications
You must be signed in to change notification settings - Fork 11
Flags
FoxGuard has a bunch of flags that are associated with various events. When an event occurs, FoxGuard produces a set of flags that combine to form a unique description of that event. The key point here is that for every event, there are multiple flags that are fired in a set. Handlers sort these sets using "matcher" sets. It is worth noting that flags in a flag set are unordered, and any apparent order is for organization's sake. However this is just within a flag set. If there are multiple flag sets involved, then the order will matter in between the sets.
Below is a list of flags, and approximately what they represent.
| Identifier | Description |
|---|---|
| root | All events have the root flag (with a single exception) |
| buff | Describes something that is not normal minecraft behavior, but when allowed, adds something. (e.g. invincibility.) |
| debuff | Describes something that is normal minecraft behavior (normally allowed), but can prevented when denied. (e.g. breaking blocks.) |
| interact | When a player clicks on something. |
| primary | When the player clicks using the primary mouse button. |
| secondary | When the player clicks using the secondary mouse button. |
| block | Describes events involving blocks. |
| change | When blocks are changed. |
| place | When blocks are placed. (New block ID) |
| break | When blocks are broken. (Changes to block ID of air) |
| modify | When blocks are modified. (Same block ID, different data) |
| decay | When blocks decay. (Whatever SpongeAPI means by that. Probably leaves and MAYBE fire.) |
| grow | When blocks grow. (Like crops and stuff) |
| post | Describes events in which a combination of various changes are packed into one event. (Pistons behave this way for example.) |
| explosion | Describes explosion events. |
| damage | Describes events where the the source cause is doing damage to an entity. |
| kill | Describes events where damage would kill the target |
| ignite* | Describes events where an entity is being lit on fire |
| spawn | Describes events where an entity is being spawned |
| entity | Describes events where a target entity is involved |
| living | When said target entity is living. |
| mob | When said target living entity is a mob. (Capable of AI) |
| passive | When said target mob is not aggressive (Like cows) |
| hostile | When said target mob is aggressive. (Like zombies) |
| human | When said target mob is a human. (Fake player created through SpongeAPI) |
| player | When said target living entity is a real player. (Which means they are not a mob) |
| hanging | When said target entity (non-living) is hangable. This includes pictures, item frames, and lead posts. |
| pass | When a player tries to pass in and out of a handler's area of effect. |
| enter | When the player enters said area. |
| exit | When the player exits said area. |
| invincible | Describes whether the source player should be invincible to incoming damage. This is a buff. |
| undying | Describes whether the source player should be immune to death. This is also a buff. |
Flags with a * next to them are in the code, but don't do anything YET. They will do stuff soon.
- Flag sets that contain the buff flag will default to deny if handlers return passthrough.
- Likewise, flag sets that contain the debuff flag will default to allow if handlers return passthrough.
Below is a list of events, and what flag sets they produce. Each event group will have a base set of flags that all events in that group will have. They may then have variable flags in addition to the base flags to differentiate between events.
- Words without any marks are flags.
- Words in angle brackets are groups. They are described below the format.
- The question mark prefix "?" is used to denote optional flags or groups.
- Parentheses are used to denote local (unnamed) groups.
- The pipe symbol "|" is used to denote an OR relationship within a group.
- Sometimes the same flag can appear twice due to the use of optionals. Just disregard the second instance.
This group of events is fired when blocks in the world are changed somehow.
Format: root debuff block change <type>
type: place | break | modify | decay | grow | post
Examples:
- A player mines a block:
root debuff block change break - A lever is flipped:
root debuff block change modify - Water turns lava into obsidian:
root debuff block change place
This event is fired when an explosion occurs.
Format: root debuff block change explosion
These events are fired when a source (Often a player) does damage to another entity.
Format: <base> ?(kill living) <type>
base: root debuff damage entity
type: ?(living ?(player | (mob (passive | hostile | human)) | hanging)
Entity types are a bit more complicated, so the above format might seem confusing. Here is a breakdown of what it all means.
The entity being referred to in this event is the entity receiving the damage. This damage is either dealt by the environment if it is a passive event (no player cause), or it is being dealt by a player (The player whose permission is in question). We are checking the permission of the source, not the target. The entity flags are describing the target. Just keep that in mind.
We already know that the target is an entity. If the entity is living (has a health bar and can die) then the living flag is added. Then they can additionally be either a player or a mob, but not both. If they are one or the other, their corresponding flags are added as well. Finally, if they are a mob, they must either be passive, hostile, or a human (fake player created through SpongeAPI). The corresponding flag is then added on.
Finally there's the kill flag. If the flag set fired for the damage event isn't cancelled (denied) AND the damage that is being dealt to the entity would kill it, the flag set is fired again with an additional kill flag. If this flag set is then denied, the target entity will appear to take damage and receive knockback, but will be left with half a heart of health. It is also worth noting that only living entities can be killed.
What this means is that if you cancel all damage events, nothing would happen (When I say nothing, I mean nothing. Damage side effects like knockback are cancelled as well), but if you only cancelled damage events that contained the kill flag, everything would continue taking damage, but would never die. (For those of you who play League of Legends, think Kindred or Tryndamere ultimate.)
Examples:
- Player punches a pig:
root debuff damage entity living mob passive - Player shoots an arrow at another player:
root debuff damage entity living player - Player strikes a zombie and is about to kill it:
root debuff damage kill entity living mob hostile
These flags control whether the source player should take damage.
Format: root buff invincible ?undying
The invincibility flags are related to the damage event, with the difference being the source and target. These flags describe now whether the source should take damage, not the target, as there is no target. The source is the player whose permission is being checked. This is a buff.
If the flag is denied, AND the damage would kill the player, the flag set is fired again with the undying flag.
This behaves exactly the same as the kill flag in the event above.
If the difference between invincible and damage is still confusing to you, think of it this way:
damage is when you punch something.
invincible is when something punches you.
These events are fired for when a player clicks on a block.
Format: root debuff interact block (primary | secondary)
Should be pretty simple. primary refers to the primary mouse button, which is usually the left mouse button. It's the button you use to break blocks. Likewise, secondary refers to the secondary mouse button, which is usually the right mouse button. It is also the button you use to place blocks.
These events are fired for when a player clicks on an entity.
Format: root debuff interact entity <type> (primary | secondary)
type: ?(living ?(player | (mob (passive | hostile | human)) | hanging)
Works the same way as the block interaction events, but with entities instead. See the damage event for details on entity type flags.
FoxGuard allows control over the entering and leaving of areas.
Format: root debuff pass (enter | exit)
Player movement needs a bit of explanation. These flags are fired when a player enters or leaves a handler's area of effect. The area of effect for a handler is defined as the combined area of all the regions the handler is linked to. This makes it so that if a handler is linked to two or more adjacent regions, walking between those regions does not fire anything. If a player simultaneously leaves a handler and enters a different handler in the same tick, FoxGuard uses the handler's priorities to figure out whether the player should be allowed to move or not.
Sometimes the best way to get the hang of things is to have a few working examples. Here are some flag sets that do common things that you can add to your handlers:
- Deny PVP:
player damage =deny - Prevent building and breaking blocks:
block place =denyandblock break =deny - Stop building, breaking, use of doors, levers, and most things:
block change =deny - Stop players messing with anything at all:
block =deny - Keep players out:
enter =deny - Make players immortal:
undying =allow - Make players invulnerable:
invincible =true - Prevent explosions:
explosion =deny(This must be given to the group assigned to the Passive handler. It's a bug.) - Cancel mob spawning:
spawn mob =deny(This must be given to the group assigned to the Passive handler.)