Conditions

A condition restricts when an objective’s progress is allowed to count. Conditions are optional. Without any, every qualifying action ticks the objective.

In reality, conditions are not special in themselves: they are just regular objective properties that have been abstracted out of objective-type-specific fields whenever I see these properties have the potential to apply to multiple current and future objective types. For example, instead of having all objective types have a TimeOfDay field that restricts progress to a certain time, the TimeOfDayCondition can be applied to any objective type to achieve the same effect with no additional implementation work needed from the objective type (even the ones that don’t exist yet!).

While any condition can be attached to any objective type, a condition only takes effect when the objective’s event actually provides the necessary data the condition needs. If it doesn’t, the condition is silently ignored and the objective progresses as if it weren’t there. The plugin won’t stop you from attaching conditions that don’t apply, so check that yours make sense for the objective. If a condition you attach isn’t working and you think it should, you can share it in the Discord server!

Attaching conditions

Conditions live in an objective’s conditions map. Progress ticks only when the objective’s main requirement AND every attached condition are met. For example, a Kill objective with a Time of Day condition only counts kills made at night.

{
  "type": "Kill",
  "amountRequired": 5,
  "entities": ["animal_bear"],
  "conditions": {
    "at_night": {
      "type": "TimeOfDay",
      "startTime": "20:00",
      "endTime": "06:00"
    }
  }
}

Each entry’s key is a unique id you choose. The web editor will generate one for you, but I recommend giving it a descriptive name so it’s easier to identify when debugging.

Combining conditions

Three logical conditions let you build more complex rules by nesting other conditions inside them. They can nest within each other to any depth.

And

Every nested condition must hold. Nested conditions go in a conditions map.

{ "type": "And", "conditions": { "a": { "...": "" }, "b": { "...": "" } } }

Or

At least one nested condition must hold.

{ "type": "Or", "conditions": { "a": { "...": "" }, "b": { "...": "" } } }

Not

Negates a single nested condition (note the singular condition key, not conditions).

{ "type": "Not", "condition": { "type": "Weapon", "weapon": ["bow.hunting"] } }

Note

Attaching several conditions directly to an objective already behaves like And: they must all hold. Reach for an explicit And/Or/Not when you need to mix all-of and any-of logic, or to negate a rule.

Overly flexible conditions

The flexibility that conditions give you is powerful. Perhaps it’s greatest feature is that it makes future objective types instantly augmentable and highly customizable from day one! However, this flexibility has one major drawback: in most cases, the plugin does not try to check that the combination of an objective type and one or more conditions actually makes sense. One of the most obvious example is the Weapon condition: although it can technically be attached to any objective type, it only really makes sense (and satisfies) for Kill, Damage, and Gather objectives. It doesn’t make sense for it to be attached to a Craft objective, because crafting never involves a weapon.

Got a condition you expected to work with a certain objective type but it didn’t? Share it in the Discord server! Some conditions (especially Weapon) need a bit more explicit wiring to work with certain objective types, and your feedback helps improve compatibility.

Condition types

Attack DistanceOnly count progress within a range of distance to the target.

BiomeOnly count progress while the player is in certain biomes.

Hit AreaOnly count progress when the hit lands in specific body areas.

Min Damage RatioOnly count progress when the player dealt a minimum share of the target's damage.

MonumentOnly count progress while the player is inside certain monuments.

Player ElevationOnly count progress while the player is above or below a certain height.

Player HealthOnly count progress while the player's health is within a range.

Player MountOnly count progress while the player is on certain mounts.

Player WearOnly count progress while the player is wearing (or not wearing) certain items.

Time of DayOnly count progress during a specific in-game time window.

WeaponOnly count progress when using specific weapons.