Mob Configuration (Skills)

Skills

Introduction

All skills belong to the skills list in a mob's config file, and can be each other's delegate (child) given that the parent skill allows for it.

Much like other configs, the child properties of their respective blocks can be in any order, but understand that the form a skill appears in on this page is the convention. The convention for the ordering of the skills list itself is determined by the trigger, but more on that in its respective section.

Skills are defined in the type property of each skills member.

Unless part of Minecraft NBT or format strings, omit all of the parentheses, (), used in examples below.

This page refers to grouped/related skills, where they're part of the same topmost parent skill, as "abilities" for brevity.

Skill Triggers

One essential part of all skills is defining their triggers, i.e. the conditions under which they activate. It's defined by the trigger property that is, by convention, always the first property underneath a skill's type.

All skills need some kind of trigger, but not all skills need the trigger property; skills can be activated by other skills, some skills can be used as skill activators themselves (including their own). Because of this distinction, it defaults to null so if there's a skill that doesn't make use of an explicit trigger, you should leave the trigger property out of the skill's configuration.

This is an example of a skill with a trigger, which plays the thunder sound when the mob spawns:

  - type: mob.skill.play_sound
    trigger: SPAWN
    selector:
      type: mob.selector.self
    sound: { name: 'minecraft:entity.lightning_bolt.thunder', source: PLAYER, volume: 100.0, pitch: 1.0 }

The following is a list of all the currently available triggers:

SPAWN: A skill is executed when the mob spawns.
ATTACK: A skill is executed whenever the mob performs a melee attack, or collision in case of projectiles.
DAMAGED: A skill is executed whenever the mob takes damage.
DEATH: A skill is executed when the mob dies.
INTERACT: A skill is executed whenever the player interacts with the mob (by right-clicking).
TICK: A skill is executed 20 times per second.

Note: null is not a "legitimate" trigger, but the value an empty trigger resolves to in cases where you have skills without explicit triggers. You can define this in the config, but you should never in practice.

Convention

All skills in the list are sorted according to their trigger property; e.g. skills that execute on SPAWN are higher in the list than ATTACK, and so on, based on the above order. Outside of a couple of specific cosmetic skills, there is no special rule for sorting within each trigger category.

Skill Selectors

Most skills have a selector property that defines where or on whom the skill is executed. Each selector has a child type property, which determines what kind of selector it is and all the associated modifiers.

Self Selector

type: mob.selector.self

This targets the mob executing the skill. Has no additional properties.

Last Hit Selector

type: mob.selector.last_hit

This targets the last enemy on which the mob performed a melee attack, or collided with in case of a projectile. Has no additional properties.

Pathfinding Target Selector

type: mob.selector.pathfinding_target

This targets the current subject of the follow_entity goal. Has no additional properties.

Area Selector

type: mob.selector.entities_in_area
originSelector:
  type: mob.selector.self
range: 11
target: PLAYERS
validator:
  type: zombies.mob.validator.zombies_player
  states: [ zombies.player.state.alive ]
  blacklist: false

This targets entities in a given spherical area based on the criteria defined within the selector's modifiers, which are as follows:

originSelector: This defines where the center of the sphere is, from which specific entities will be searched. Accepts all the same selectors listed in this section, e.g. type: mob.selector.self to have the sphere originate from the mob itself.
range: This is the radius of the sphere. Accepts any double value. Defaults to -1 (unlimited).
target: This is used for optimizing entity search. It's optional but, instead of leaving it out, applying appropriate values is highly advised to aid server performance. Defaults to ENTITIES.

Accepted values are:
- ENTITIES: Everything that Minecraft considers an entity.
- LIVING_ENTITIES: Players and all entities that have pathfinding. Any entity type can be subject to pathfinding, including items, armor stands... but are only considered for this category if they include it.
- PLAYERS: Players only.
- ITEMS: Items only.
- EXPERIENCE_ORBS: Experience orbs only. You'd never use this one, but it exists.
validator: Skill validators
limit: The maximum number of entities that can be targeted. Accepts a whole number, and defaults to -1 (unlimited).
limitSelf: Whether this mob is exempt from targeting itself, in case that the selector deems it valid. Defaults to true (exempt).

LOS-Based Offset Selector

type: mob.selector.line_of_sight_offset
distance: 10
ignorePitch: true
ignoreYaw: false
delegate:
  (some delegate)

This selector offsets another (the delegate) based on the caster's line of sight.

distance: Double value; how many blocks away to offset from the direction the mob is looking in.
ignorePitch: Boolean; determines whether pitch (the head tilt of the mob) is considered, ignored if true. Defaults to false.
ignoreYaw: Boolean; determines whether yaw (the horizontal rotation of the mob's head) is considered, ignored if true. Defaults to false.

Group Selector

type: mob.selector.group
delegates: []

This is a 'meta' selector that does nothing on its own. It accepts a list of selectors that are combined as one for purposes of selecting targets based on multiple criteria.

Limiting

type: mob.selector.limiting
originSelector:
  type: mob.selector.self
delegate: {}
behavior: CLOSEST
amount: 10

This is a 'meta' selector that does nothing on its own. It's used to customize the targets (within reason) selected by selectors that have a limit property, where applicable.

originSelector: The "center" from which the behavior property is evaluated. May be different to the center used by its delegate selector.
delegate: The selector to impose the limit modification on.
behavior: The manner in which the targets are picked. Possible values are CLOSEST (closest targets to this skill's center), FARTHEST, and RANDOM (no pattern).
amount: The amount of targets to select. If it's under the delegate skill's limit, the latter will compensate for the rest using its own algorithm. If it's over the limit, some targets may end up being ignored.

Skill Validators

Validators carry out additional filtering in case of selectors, and are used by some skills to continually validate that their target is in an allowed state.

Whenever they're present, they take the form of:

validator:
  type: some.type
  (additional modifiers): (value)

Always Validate

type: mob.validator.always

Used in places where having a validator is mandatory, but you want one that always returns true. No modifiers.

Validate Distance

type: mob.validator.distance
distance: 10

The most common use of this validator is for mobs that shoot projectiles, to prevent them from shooting them at too long of a range. It has one modifier:

distance: Double value in blocks, measuring that the hit target is within a certain range.

Validate Line of Sight

type: mob.validator.line_of_sight

Used to validate that the executing mob has line of sight on the targets, where needed. No modifiers.

NOTE: In some applications, this is currently not working as intended.

Multiple Validators - AND, OR

type: mob.validator.and
validators: [ /validator1, /validator2 ]

While it still would be a child of the validator property, this doesn't function as a filter itself. Rather, it's a meta validator that is used to include multiple validators as part of the same filter -- and they all have to succeed in order for it to return true. It has one modifier:

validators: This is a list that stores all the validators that need to be chained together. For cleanliness, we recommend that you define these validators as Element paths and only include said paths in the list.

The OR version only needs one validator to succeed in order for it to return true.

type: mob.validator.or
validators: [ /validator1, /validator2 ]

Validate Mob Keys

type: mob.validator.mob_type
types: []
tags: []
blacklist: false

This validator is used when you need to target (or avoid targeting) a specific type of mob. Do not include it if it's empty.

types: List of mob keys for consideration. Though they don't have to be, they should always be prefixed with phantazm: for consistency purposes. Defaults to empty.
tags: List of mob tags for consideration. These don't target a single mob type, but rather a group of mob types (if applicable) based on whether they have a matching tag in their list. Defaults to empty.
blacklist: This toggles whether the types property is used as a blacklist instead of a whitelist. It defaults to false, meaning that the validator would look for entities that fit the types criteria (whitelist). If you change it to true, it will look for mobs that don't fit any of the criteria (blacklist).

Validate Player States

type: zombies.mob.validator.zombies_player
states: []
blacklist: false

In its baseline form, this validator ensures filtering of players that are part of a Zombies scene. It has two additional modifiers:

states: List of specific player states that you want to target, if you don't want to target everyone.

Accepted states are:
- zombies.player.state.alive: Targets alive players.
- zombies.player.state.knocked: Targets players that have been knocked down.
- zombies.player.state.dead: Targets dead players.
- zombies.player.state.quit: Targets players that quit the match.
blacklist: This toggles whether the states property is used as a blacklist instead of a whitelist. It defaults to false, meaning that the validator would look for entities that fit the states criteria (whitelist). If you change it to true, it will look for players that don't fit any of the criteria (blacklist).

Validate Player States - Common Configuration

This is a common config block that, for our purposes, must be used across all mob files except some projectiles.

alivePlayers:
  type: zombies.mob.validator.zombies_player
  states: [ zombies.player.state.alive ]
  blacklist: false

The reason why this is important is because all instances of mob.goal.follow_entity must filter for alive players only, regardless of what validators are required by other skills and goals. The path should also ideally be called alivePlayers everywhere for consistency between files. Add it right after the goals block.

Skills - Meta Skills

"Meta skills" are defined as having no effect on their own, but they act complementary to other skills.

Timer

type: mob.skill.timer
interval: 200
requiresActivation: true
resetOnActivation: true
exceedMobLifetime: true
repeat: 1
delegate:
  (another skill to be activated)

The timer skill is a versatile one, as it can be used to introduce delays in execution of skills in the same ability, establish a looping, continual execution of some skill from one arbitrary condition to another, and replace triggers in some circumstances because it runs independently of one (unless requiresActivation is set to true) and activates other skills.

Its modifiers are the following:

interval: Time between each repeat (delegate skill being activated). Its unit is a whole number in ticks that has no default so it has to be set every time.
requiresActivation: Boolean that toggles whether something else needs to activate the timer for it to count down. Defaults to false, meaning that the timer will count down since the mob spawns regardless of where it is, and is necessary to set to true in order to properly use triggers and timers as delegates of another.
resetOnActivation: Boolean that toggles whether the countdown is reset every time the skill is activated, without activating the delegate. Defaults to false (no), otherwise requiresActivation must be set to true as well.
exceedMobLifetime: Boolean that toggles whether the skill should continue repeating after a mob's death. Defaults to false (all repetitions end by force on the caster's death), but setting it to true won't work specifically in case of infinitely repeating timers. To introduce abilities that loop for the rest of the game, use the lingering skill with an infinite lifetime.
repeat: A whole number that represents how many times a timer can loop after being activated. Defaults to -1 (unlimited).
delegate: The skill that is activated at the end of each countdown. Accepts a single skill as a block (not a list).

Random Timer

type: mob.skill.random_timer
minInterval: 200
maxInterval: 250
requiresActivation: true
resetOnActivation: true
exceedMobLifetime: true
repeat: 1
delegate:
  (another skill to be activated)

This skill is largely the same as a regular timer, with one notable difference: the interval property no longer exists and is replaced by two additional ones.

minInterval: Minimum interval length that the skill can execute its delegate on, measured in whole numbers as ticks.
maxInterval Maximum interval length that the skill can execute its delegate on, measured in whole numbers as ticks. Must not be lower than minInterval.

Besides its structure, the key difference between a timer and a random timer is that the latter randomizes the interval, within each range, every time a new countdown begins. The main purpose of this is to introduce an offset to mobs that spawn at the same time, so that they don't execute an ability simultaneously and make it appear more natural.

If you find yourself in a situation where you want to set minInterval and maxInterval to the same number, use the normal timer instead.

Avoid using it too much and with too high of an interval range, as having some predictability is a good thing overall. Recommended usage for this skill is in varying cosmetic delegates to make them appear more "natural" instead of completely synchronized.

Random (Chance)

type: mob.skill.random
chance: 0.1
delegate:
  (skill that has a chance to activate)

This skill "rolls a die" on behalf of its delegate, not activating the latter if it fails.

Its modifiers are:

chance: The chance for the skill to activate its delegate. Accepts a double value between 0 and 1.
delegate: The skill that you want affected by RNG. Accepts a single skill as a block.

Random (Weighted Choice)

type: mob.skill.weighted_random
delegates: 
  - (skill 1)

  - (skill 2)
weights: [ 1, 1 ]

This is a version of the random skill that always executes one of its delegates, but each are given a different "weight", i.e. the bias towards that skill being activated compared to its peers. For example, a skill with weight 1 is 1/2 as likely to be executed than a skill with weight 2; the underlying function uses simple ratios to calculate this.

delegates: A list of skills to choose from. There must be at least one.
weights: A list of weights/bias, where each has to be a whole number. Each weight corresponds to the skill of the same index in above list.

Note: If the weight array exceeds the delegate array, the excess weights are ignored. If the delegate array exceeds the weight array, the excess skills get assigned a weight of 1.

Temporal

type: mob.skill.temporal
minDuration: 80
maxDuration: 80
delegate:
  (another skill to be activated)

The temporal skill is used to limit the duration length of certain skills that would otherwise last until the mob dies. It has no effect on most skills when passed into its delegate, but those that it affects are noted as such in their respective sections.

minDuration: Minimum length of the effect. Measured in ticks as whole numbers.
maxDuration: Maximum length of the effect. Measured in ticks as whole numbers, but can't be lower than minDuration.
delegate: The skill to limit the duration of.

The skill selects a random period of time within the given range. To force a set length (preferred), minDuration and maxDuration should have the same value.

Group

type: mob.skill.group
delegates:
  (another skill to be activated)

This skill is used as an "adapter" in situations where you want to assign multiple delegates to a skill that accepts only one. Its delegates field accepts a list of skills.

Don't use it for skills that already accept a list of delegates. weighted_random is an exception to this rule if you want multiple skills activated simultaneously when it selects a member of its list.

Don't use it in cases where there's only one delegate unless you plan to expand the ability later in development.

To prevent config duplication and desynchronization, it's highly preferred to use one timer with this skill as its delegate, instead of several concurrent timers that are all functionally the same.

Conditional

type: mob.skill.conditional
condition:
  (some condition)
delegate:
  (another skill to be activated)

The Conditional skills only activates its delegate if a certain condition is met (evaluated only when this skill is triggered). All the possible conditions are:

Conditional - Distance

type: mob.skill.condition.distance
originSelector:
  type: mob.selector.self
targetSelector:
  type: mob.selector.pathfinding_target
behavior: WITHIN
distance: 10
matchCount: 1
multiPointHandling: EXACTLY_N_MATCH

This condition evaluates whether the target(s) are inside or outside a certain range from the origin points, depending on its settings.

originSelector: A selector that chooses the origin(s) of the distance radius. Each origin point evaluates a sphere (based on distance) around itself, independent of each other.
targetSelector: This selector chooses entities or points to evaluate against the given distance radius, e.g. if the selected entity in above example is within a sphere with radius 10 of the casting mob, this will cause the conditional skill to execute its delegate. If it's outside of it (i.e. it's 11 blocks away), the evaluation has failed and the delegate is not executed.
behavior: This property determines whether the check is done inside or outside the distance sphere. Has two possible values: WITHIN and WITHOUT -- WITHIN is default, so it should be omitted from any skills that check within the range.

E.g. with the current setting (WITHIN) in the above example, the condition succeeds if the pathfinding target is found within <=10 blocks radius of the casting entity, but not >10. If it was inverted (WITHOUT), the condition fails (delegate is not executed) if the target is found within <=10 blocks, and succeeds if it's >10.
distance: This is the radius of the sphere against which the check is made, measured in blocks.

The following properties are only applicable in case where there are multiple origin points and should be omitted if there is only one, e.g. self selector as in the example; however, in this circumstance, it serves to illustrate the convention. This is because every origin point is independent and makes its separate evaluation, so you can further restrict the skill to only execute the delegate if a specific number of origin points passes the distance evaluation.

matchCount: Measured in the total amount of successful matches across all origin points, this property is used to perform an evaluation between the real total of successful matches and the expected total (value supplied to matchCount). The exact operation depends on the multiPointHandling field, e.g. if matchCount is set to 5, and the value passed to multiPointHandling is EXACTLY_N_MATCH, the condition must find exactly 5 successful matches in practice or else it won't execute the delegate.
multiPointHandling: The equality/inequality operation performed between the aforementioned figures for total. Possible values include:
- ANY_MATCH: To execute the delegate, at least one origin point must pass the evaluation. The value in matchCount is made obsolete.
  
  This is the default value, so if you plan on using default behavior, include neither this field nor matchCount.
- ALL_MATCH: To execute the delegate, all origin points must pass the evaluation. The value in matchCount is made obsolete, so that property must be omitted.
- EXACTLY_N_MATCH: To execute the delegate, the real amount of successes must be the same as the expected amount of successes.
- LT_N_MATCH: To execute the delegate, the real amount of successes must be less than the expected amount of successes.
- GT_N_MATCH: To execute the delegate, the real amount of successes must be greater than the expected amount of successes.

Conditional - Health

type: mob.skill.condition.health
selector:
  type: mob.selector.self
condition: LESS_THAN
amountType: PERCENTAGE
amount: 0.1

This condition replaced the removed own_health_conditional skill. It evaluates the current health of selected entities and executes the delegate if it passes.

condition: Not to be confused with the parent condition property, this is the boolean operator to use. Can be LESS_THAN (current health < amount), EQUAL_TO (current health = amount) or GREATER_THAN (current health > amount).
amountType: This determines whether the amount property represents a flat amount of health (10 HP in this example) or a percentage of the entity's maximum health. Specify FLAT for the former, but you don't need to specify PERCENTAGE for the latter because that's the value it defaults to. Note: When using PERCENTAGE, the amount passed in must be a decimal value between 0 and 1 to represent a percentage.
amount: This accepts a positive number with additional constraints depending on the amountType you set. This is the health (or value to derive it with) to evaluate against.

Lingering

type: mob.skill.lingering
selector: 
  type: mob.selector.self
targetSkills: 
  - (some skill)

  - (some skill)
lifetime: 100

This skill spawns an invisible armor stand that executes skills passed into it. Though an entity, it's effectively not part of the game in the sense that players can't interact with it, can't shoot it and is never considered as part of a round.

selector: The location(s) to spawn the armor stand on.
targetSkills: List of skills that the armor stand entity should use, with the exact same formatting rules as for a regular mob. Some features that usually apply to the caster, e.g. specific triggers, mob.selector.self, etc. will only be applied to the summoned entity and never the caster, i.e. mob.selector.self within these skills will always be the armor stand.
lifetime: How long the armor stand should last for. Expiry counts towards any DEATH triggers. Whole number in ticks, but set it to -1 if you want it to last infinitely (use with care).

Skills - Cosmetic Skills

"Cosmetic skills" either:

have a perceptible effect of some kind but do not have a direct one on gameplay, or
do have a direct effect on gameplay but only when it's caused by changing a player's GUI, without any other interactions that would result in such.

Send Message

type: mob.skill.send_message
message: <yellow>This is a <b>message</b> with <red><b>MiniMessage</b></red> formatting.</yellow>
selector:
  (some selector)

This skill sends a message in chat to all selected entities using the MiniMessage format.

message: The message in question. It does not need to be enclosed in quotes.
selector: The entities to whose chat the message is sent. For obvious reasons, the selector should look for players only — the skill has no effect on mobs.

Mob Healthbar

type: mob.skill.show_healthbar
bar: '<#6b6f80>[<healthbar:bar_component:|:color_start:#dd3e28:color_end:#34bf25:missing_color:gray>]</#6b6f80>'
barWidth: 20

This skill displays a healthbar (name) above a mob that dynamically updates with its health. The above example implementation is the standard used across our mob files; you can just copy-paste it from here.

All bosses should have it, and it depends on a case-by-case basis for other non-standard mobs. It overrides customName as the visible nametag.

Note: it does not need a trigger. Simply including it as-is in the root of skills will make it work.

bar: Enclosed in single quotes, this configures how the bar looks.

The MiniMessage color tags on the outside, <#6b6f80>, define the color of the entire frame which includes the square brackets at either end of the healthbar. healthbar: defines the start of a healthbar tag, bar_component:|: defines the string which a healthbar is made out of (a single character |, or pipe, by our convention), color_start:#dd3e28: is the color of the healthbar when it's full, color_end:#34bf25: is the "target color", and missing_color:gray colors the bar components that represent lost health.

With each bar lost, the starting color degrades, through the spectrum like a gradient, into the target color (the color that it would have when health is empty).
barWidth: This controls how many bar_components a healthbar is made out of. Accepts whole numbers.

Play Sound

type: mob.skill.play_sound
selector:
  (some selector)
sound: { name: 'minecraft:entity.zombie.hurt', source: HOSTILE, volume: 1.5, pitch: 1.0 }
broadcast: false

This skill plays a sound in two different ways depending on the state of the broadcast toggle.

selector: The selector is used to choose the origin of a sound effect.

If broadcast is set to false, only the selector's target will hear the sound. In this case, the selector should always aim for players since there's no point for mobs to have the sound played to them.

If broadcast is set to true, the sound is sent to everyone and players will hear it originate from the selector. Whether it's actually heard by them is dependent on the attenuation range.
sound: This defines a sound within curly braces.
- name: This property points to a Minecraft resource location for a certain sound, prefixed by minecraft:. The resource can be anything from here.
- source: This property controls what volume slider the sound will be a part of on players' clients.
- volume: The naming of this property is slightly misleading — as it's based on the property of same function and name in Minecraft, there's nothing we can do about it. It accepts a double value that is equal to 0 or above.
  
  Volume controls the actual volume up to the value of 1, which is default for most Minecraft sound effects, meaning that you can't make sounds louder other than through layering (i.e. firing multiple instances of the skill with the sound at the same time). Below 1, it only decreases it until its inaudible at 0.
  
  Above 1, it only affects attenuation (the drop-off range) where attenuation = volume x 16 blocks.
- pitch: This is a double value between 0.5 and 2 that controls the pitch of the sound. Values below 0.5 default to 0.5, and values above 2 default to 2.
  
  Values below 1 lower the pitch and slow down the sound. Values above 1 raise the pitch and speed up the sound.
broadcast: This is a boolean value that controls whether a sound is sent to everyone or not. It defaults to true (sent to everyone).

The following are valid values for source and when to use them:

MASTER: Never use this one. In order to turn off your effect, a player would have to mute Minecraft.
MUSIC: Never use this one, not even for musical compositions. A player should be able to turn off the OST independent of everything else.
RECORD: Use it for playing music discs and our homemade compositions.
WEATHER: This one is not a hard no, but it's extremely unlikely that you'll ever use it. Use it only if you have a very good reason to do so.
BLOCK: Use it for in-map interactions and some kinds of environmental obstacles. Sounds caused by interacting with a mob (through the INTERACT trigger) do not count as an "in-map interaction" for this purpose.
HOSTILE: The bulk of play_sound instances within mob configs will use this one. If it's produced by a hostile mob, it falls under this category.
NEUTRAL: Use it for sounds produced by non-hostile mobs if you include them.
AMBIENT: Use it for ambient sounds produced by the environment. Certain, "dynamic" environmental obstacles such as falling rocks don't count as ambience for this purpose. You are unlikely to use this one in mob configs; it's more suited towards round and map configs.
PLAYER: Use it for sounds that are produced by the players or effects afflicting them, e.g. the sound of one burning.
VOICE: Never use this one. Reserved for Narrator.

Particles

type: mob.skill.spawn_particle
selector:
  (some selector)
particle:
  type: particle.wrapper
  particle: block
  variantData:
    type: particle.variant_data.block
    block: minecraft:redstone_block
  distance: true
  offsetX: 0.0
  offsetY: 0.0
  offsetZ: 0.0
  data: 0.0
  particleCount: 60
bounds:
  origin:
    x: 0.0
    y: 1.0
    z: 0.0
  lengths:
    x: 0.0
    y: 0.0
    z: 0.0

This skill spawns a specified amount of a given particle at a location.

selector: The selector is used to choose the origin of the particle group that is then refined through other properties.
particle: This property houses the rest of the configuration as it pertains to the settings of a single particle.
- type: particle.wrapper is the only value you can use here. This property exists for internal purposes.
- particle: This is the ID of the particle you want to use. Can be anything from here.
  
  Exercise caution in picking particles -- are they appropriate for your case? Are they too visually obstructive for a player without reduced particle settings?
- variantData: This houses settings for particle variants where applicable.
  - type: Most particles would have particle.variant_data.none in this property, as most particles don't have special variants defined outside of their ID. However, block and block_marker particles do -- you must use particle.variant_data.block in order to customize which block to draw from, as that is not differentiated through particle IDs.
  - block: This property is only present if you are working with a block/block_marker particle and is otherwise omitted. It accepts any valid Minecraft block ID, complete with the minecraft: key -- for block_marker, only barrier and light will work.
- distance: If set to true, particles render at a 512 block visibility limit. If set to false, they render at 32.
- offsetX, offsetY, offsetZ: These properties add random variation for particle spread in whichever axis they correspond to. They accept a double value and the exact formula these variables are used in is not entirely understood. Defaults to 0 (no spread).
- data: The effect of this property is unknown, but is included in the config as it's part of the particle packet as defined by Minecraft. Accepts a double value, but should be kept as 0.
- particleCount: How many particles to spawn in defined bounds with each execution of this skill. Whole number.
bounds: Particles are either sent as a single point or along the perimeter of a (bounding) box, which then has spread variation. This property houses all the settings for it.
- origin: Has X, Y, Z coordinates as its child properties. This defines the origin offset of either the bounding box or the point from the selector. All default to 0.
  
  One quirk to be wary of is that if the selector chooses an entity, and all origin offset coordinates are 0, the particles will spawn on the entity's feet (lower bounds). Commonly, the Y value is set to 1 for this reason.
- lengths: Has X, Y, Z coordinates as its child properties. This defines the length of the particle box (if all are set to 0, then particles spawn on a point).
  
  If you want particles to show up in an area around an entity, you need to offset the origin as well. Otherwise, the box is not centered around the entity; one of its corners originates from it instead.

Potion

type: mob.skill.potion
selector:
  (some selector)
potion:
  effect: minecraft:poison
  amplifier: 1
  duration: 100
  flags: 6

This afflicts an entity with a potion effect. In Minestom, they don't have any function other than cosmetic (icons, GUI overlays, particles...) meaning that you would only apply them to a player most of the time, unless there is a situation where you'd want particles coming off a mob.

selector: The entity(es) to apply the effect to.
potion: The property whose children are used to customize the effect to apply.
- effect: The exact effect to inflict upon an entity. Can be anything from here.
- amplifier: The level of the effect. It should be a whole number in the range between 1 and 255 inclusive.
- duration: The duration of the effect. Whole number in ticks.
- flags: Bit flags used to combine certain possible cosmetic settings for a potion. For a layman, this means that you would add the numbers representing the settings you want in order to create combinations.
  - 1 turns on the 'ambient' effect (translucent particles as if they came from a beacon).
  - 2 turns on particles that come off an entity.
  - 4 enables (unmodified) clients to see the icon in their GUI.
  For example, to inflict an effect that has a player get an icon in their inventory and generate particles, but not the translucent kind, you would set the flags property to 6 (2 + 4). If you just want the icon, you would set it to 4, and so on.
In general, you shouldn't rely too much on the GUI-changing effects to add a difficulty/mechanic, like Darkness and Blindness, since any client-side effect can be easily bypassed with cheats.

Some potion effects have special conventions. These only apply if they're not an instance of a "map gimmick" nor a consequence of a cursed perk:

Weakness: Used to indicate debuffed fire rate.
Poison: Used to indicate the damage_over_time skill.
Wither: Used to indicate stunted regeneration.

Some potions have undesirable side effects to watch out for:

Nausea: Refreshing it doesn't just refresh its timer, but the whole "progression" of the swirling overlay starts anew.

Apply Fire

type: mob.skill.apply_fire
selector:
  (some selector)

This simple skill shrouds a given entity in fire, which has no effect on its own other than "decorating" an entity's model and, when used on players, covering their GUI with a fire overlay.

By default, it lasts until the end of the game. To force a limit on it, you must use it as a delegate of the temporal skill -- it's recommended to always do this when players are expected to be targeted.

Change Equipment

type: mob.skill.change_equipment
selector:
  (some selector)
equipment:
  - key: MAIN_HAND
    value: 
      material: minecraft:cobblestone

This skill changes an entity's equipment depending on the slot selected and whether the given item is supported by it.

selector: The entity or entities to target. Players are also accepted, but take care to adjust their armor attribute if it's not meant to be just cosmetic -- armor values are separate from armor in Minestom.
equipment: List of key/value pairs used in targeting and changing equipment slots.
- key: The equipment slot you want to change. Can be anything from here, and should ideally be in that order if multiple slots are being changed.
- value: The item to replace whatever is currently occupying that equipment slot.

Skills - Active Skills

"Active skills" are defined as having a direct effect on gameplay through means other than (just) changing a player's GUI.

Damage

type: mob.skill.damage
selector:
  (some selector)
amount: 4
damageType: damage.fire
knockback: 0.2
bypassArmor: true

The Damage skill is used to deal a flat amount of damage to all entities caught by the selector, regardless of their location relative to the caster.

selector: The entities to deal damage to.
amount: The amount of damage to deal to selected targets, where 1 is equivalent to a half-heart. Accepts a double value; you are allowed to deal damage that equals <1 half-heart in Minecraft, but it just won't display until the total "excess" equals half a heart or over.
damageType: What damage source, if any, an application of this skill should count towards. Part of the Damage API. Optional.
knockback: The amount of knockback to deal with each cast. The direction is the opposite of that towards the caster's position.
bypassArmor: A boolean determining whether the damage dealt should ignore an entity's armor or not. Defaults to false (the damage takes armor into account).

This skill is the primary way of dealing damage for a non-gun projectile, as those kinds of entities cannot have goal setters which renders melee damage useless. Like many other skills on such, it must be used in conjuction with an ATTACK trigger and a last hit selector to emulate the effect of a hit.

Radial Damage

type: mob.skill.radial_damage
selector:
  (some selector)
damage: 4
damageType: damage.fire
knockback: 0.2
bypassArmor: true
range: 3

This skill is similar to the above damage skill, with the key difference being that it implements a damage fall-off. Some properties are changed to enable that effect:

selector: While it will always select all given entities, it does not guarantee that those entities will receive damage. For this reason, it's recommended that any instances of the area selector should search within a range equal to or lower than the below range property.
range: This new property describes the possible radius around the caster that the skill can affect, measured as a double value in blocks. The center of the circle is always the caster, where the damage inflicted upon the selected targets is the highest which gradually lowers towards the outer edge of the area. Entities outside of the range won't be affected.

Damage Over Time

type: mob.skill.damage_over_time
selector:
  (some selector)
validator: /alivePlayers
damageAmount: 1
damageType: damage.fire
bypassArmor: true
damageInterval: 20
damageTime: 100
exceedMobLifetime: false
sound: { name: 'minecraft:entity.lightning_bolt.thunder', source: PLAYER, volume: 100.0, pitch: 1.0 }

In practice, this skill inflicts selected entities with a recurring damage skill. Despite that, some property names differ as the skill hasn't yet been ported to the new standard for configuration:

selector: The entities to deal damage to.
validator: When targeting players, you must include an additional validator (preferably the common alivePlayers validator) to prevent them from receiving damage in a state where it makes no sense to do so, such as when they're dead or knocked down.
damageAmount: Equivalent to amount in the damage skill.
bypassArmor: Equivalent to the property of the same name in damage.
damageInterval: The time between each recurrence of damage as a whole number in ticks.
damageTime: The period of time over which the target suffers from reocurring damage. Whole number in ticks.
exceedMobLifetime: Whether the skill should continue ticking if the mob dies. Defaults to true (false = skill ends when mob dies).
sound: The sound to play to just the target every time damage is dealt. Uses the same formatting as sound in play_sound. Defaults to null (no sound is played).

Heal

type: mob.skill.heal
selector: 
  type: mob.selector.self
amount: 1

This skill heals the targeted entities by a certain amount. Note: never use any of the damage skills with a negative value, as it still sends a damage packet.

selector: The entities to heal.
amount: The amount to heal selected entities with. Accepts a double value.

Leap

type: mob.skill.leap
selector:
  (some selector)
strength: 50
angle: 5

This skill enables the casting mob to emulate a jump towards the selected target.

selector: An entity to leap towards. This can actually target multiple entities, in which case the mob would instead jump towards the average point between all of the targeted entities.
strength: The speed of the jump, also affects lift-off to an extent. It accepts a double value, but the unit (used by our platform) is not entirely understood; from our own configuration, we have determined that the number must be fairly large to cause a visible change.
angle: The angle off the ground at which the leap is performed, using the caster as a reference point. Accepts a double value in degrees.

Push

type: mob.skill.push
selector:
  (some selector)
power: 24
vertical: 8

This skill is used to push the targets either to or away from the caster, which is always used as the focal point.

selectors: The entities affected by the push.
power: The speed of the horizontal push, using the same unit (double value) as the strength in the leap skill. If this is a positive value, it pushes the targets away from the caster; if it's negative, it pulls towards the caster instead.
vertical: The speed of the vertical push, where a positive value works against gravity, while a negative value adds towards it.

Avoid setting this property to 0 in a standard usage of this skill, as that would result in an awkward "sliding" effect and the entity being pushed could be stopped by obstacles of any height. Similarly, avoid setting it to a value that is too high as it can enable map exploits.

Spawn Mob

type: mob.skill.spawn_mob
selector:
  (some selector)
callback:
  type: zombies.mob.skill.spawn_mob.callback.add_to_round
identifier: phantazm:some_zombie
spawnAmount: 1
maxSpawn: 2
useLocalCount: false
offset: { x: 0.0, y: 0.0, z: 0.0 }

This skill spawns mobs of a given type that could either be part of the round or outside of it.

selector: This defines the location(s) on which the mobs could spawn.
callback: Depending on the type of callback passed in, this is used to add the mobs to the mob counter (or not).

Currently available mob callback types are:

type: zombies.mob.skill.spawn_mob.callback.add_to_round

The above adds all of the spawned mobs to the round and its mob counter, meaning that all spawned mobs must be killed in order to advance the round (unless the mobs' partOfRound is set to false);

type: mob.skill.spawn_mob.callback.none

The above doesn't add any of spawned mobs to the counter for the round, meaning that spawned mobs do not need to be killed to advance the round. However, those same mobs can't be interacted with, so do not use this for mobs that are part of the round but not the counter.

identifier: The Phantazm key of the entity you want to spawn. Do not use generic Minecraft mobs as they lack pathfinding of any kind, unless in exceptional circumstances where you want them as (killable) decoration. In that case, they should be used together with the none callback.
spawnAmount: How many mobs to spawn on each execution of this skill. Whole number.
maxSpawn: The maximum amount of alive mobs across all executions of this skill; the mobs that die are cleared from the internal counter and open spaces for more mobs to be spawned. This property can sometimes override spawnAmount, i.e. reduce it in circumstances where it'd exceed the total allowance of alive mobs, using a simple formula: actual spawn amount = maxSpawn - internal counter. Whole number.

Though doing otherwise wouldn't error because of the above mechanic, maxSpawn should be equal to or higher than spawnAmount for sake of consistency.
useLocalCount: Whether the internal counter is shared across every entity with the caster's key, or is unique to the casting entity. Defaults to false (shared across the caster's entity key).
offset: How displaced should the spawned mobs be from their caster. Accepts a relative X, Y, Z coordinate as doubles. Defaults to 0, 0, 0.

Note: the commas and spaces should be kept as in the example due to some limitations of YAML.

Shoot Projectile

type: mob.skill.shoot_projectile
selector:
  type: mob.selector.pathfinding_target
hitValidator:
  type: mob.validator.and
  validators: [ /alivePlayers, /distanceCheck ]
callback:
  type: mob.skill.spawn_mob.callback.none
entity: some_projectile
power: 1
spread: 0
gravity: false

This skill launches another entity as a projectile. While it can be used to launch other mobs as well, it's recommended to use an entity that's been specifically configured to exist as a projectile; especially since the entities die upon impact.

selector: This decides the target at which the caster should shoot. For this skill, you'd typically use the pathfinding target selector, so that the player that the mob is pathfinding to will be the one shot at. Recommended practice for ranged mobs.
hitValidator: This ensures that the entity the projectile impacted is valid. As with the melee attack goal, you'd want to use alivePlayers as one of the validators, which you may sometimes want to pair up with a distance check.

Line of sight validation currently doesn't work for this.
callback: This property uses the same callback system as spawn_mob above (which has a list of all callback types). For projectiles, you'd nearly always use none since, in most cases, adding them to the round would be anomalous behavior.
entity: The key of the entity to launch.
power: This takes an unknown unit expressed as a double value, and uses it to determine the speed with which the projectile sails through the air. Values below 1 tend to be slow, and values above 2 tend to be fast enough to sometimes cause issues with projectiles clipping through blocks.
spread: This determines whether the mob has a pinpoint accuracy on the target's current position (if spread is 0) or there's some variation in their aim. Takes a double value representing an unknown unit.
gravity: Boolean value that decides whether the projectile is bound to gravity (upward velocity drops off if true) or not. Defaults to false.

Attribute Modifying

type: mob.skill.attribute_modifying
selector:
  (some selector)
attribute: generic.movement_speed
amount: -0.1
attributeOperation: ADDITION
stage: zombies_game

This skill is used to modify an entity's attribute in some way. It can be either a generic Minecraft attribute or one provided by Phantazm, as long as it's applicable to your target, i.e. changing a "player's" horse.jump_strength has no effect. Read more about mob attributes here.

NOTE: By default, this skill's effect is permanent. While permanent changes can be desirable (highly not recommended for players), you must invoke it as a delegate of the temporal skill to set a time limit.

selector: The target(s) of this skill.
attribute: The attribute you want to change with the cast.
amount: A double value that can be either negative or positive. This is by how much the attribute will be changed for the duration of the skill -- the exact formula depends on the property below.
attributeOperation: This property determines the formula used in calculating the new attribute value. Possible settings include:
- ADDITION: The flat amount value will be added on top of the attribute's current value.
- MULTIPLY_BASE: attributeValue += attributeValue * amount, where attributeValue is a mob's default value for that attribute as defined in the configuration.
- MULTIPLY_TOTAL: attributeValue += attributeValue * amount, where attributeValue is a mob's current value for that attribute at the time of the skill's execution, with all ongoing attribute modifiers taken into account.
stage: In a Zombies game, you can only use zombies_game as a value for this property. This is to specify that the use case is appropriate for the minigame, because this skill is versatile and may have applications in other projects.

This property is unnecessary when the only targets are other mobs, and can be safely omitted in that case.