Expression (Data Type)

A String holding a maths expression. Any field documented as accepting an expression also accepts a plain number.

Where expressions work

Operators

Functions

Constants: pi and e.

Random functions

Random generators

Bound variables

Variables are resolved when the expression is compiled and read live from the entity each time it is evaluated. If there is no entity where the expression is evaluated (such as chance in a block action), entity variables read 0.

Reading the surroundings

biome_temperature, brightness and the light levels turn the world into numbers, so a power can scale smoothly instead of switching between a ladder of conditioned copies. Feed one into a Resource a step at a time and the power ramps up and down instead of jumping at a biome border. This heat resource drifts toward 50 − 25 × temperature (30 in plains, 0 in a desert, 50 on snowy plains and 68 on frozen peaks) by at most one point a tick:

{
  "type": "apoli:action_over_time",
  "interval": 1,
  "entity_action": {
    "type": "apoli:modify_resource",
    "resource": "example:heat",
    "modifier": {
      "operation": "add_base_early",
      "value": "clamp(round(50 - 25 * biome_temperature) - value, -1, 1)"
    }
  }
}

value is the resource's current value, so the step always goes toward the target and stops once it arrives. Anything else can then read example:heat, such as an attribute modifier, a damage multiplier or a HUD bar.

The same idea lifts the dark. This apoli:night_vision fades in as the light fades out, so the world never looks darker than a dim evening:

{
  "type": "apoli:night_vision",
  "strength": "clamp((0.5 - brightness) * 1.6, 0, 0.8)"
}

Actor and target

In a bi-entity context (any bi-entity action or condition), a bare variable reads the actor, the entity the power belongs to. Add the target_ prefix to read the other side instead, and actor_ is an explicit way to write the default:

{
  "type": "apoli:damage",
  "damage_type": "player_attack",
  "amount": "5 + ((max_health - health) * 0.35)"
}

As a bi-entity action, that deals more damage the more health the actor is missing. "target_max_health - target_health" would read the victim instead.

The binding covers the whole bi-entity action, including anything nested inside it. An apoli:actor_action wrapping an apoli:modify_resource can still read target_health, and a bare variable inside an apoli:target_action reads the target, because that is the entity in scope there, while actor_ still reaches back to the actor.

Outside a bi-entity context there is no second entity, so target_ and actor_ both fall back to the one entity in scope. The prefixes work on the plain variables above, not on resource IDs, so use target_resource(...) and actor_resource(...) for those. That matters when an apoli:target_action runs an action that takes coordinates, such as apoli:teleport. A bare my_pack:aim_x there reads the target's resource, which is 0 if the target doesn't have it, so write actor_resource(my_pack:aim_x) to read the number the caster stored.

Inside a damage modifier

The amount of an Attribute Modifier on apoli:modify_damage_dealt, apoli:modify_damage_taken and apoli:modify_projectile_damage is an expression, and it is bound the same way: a bare variable reads the power holder, actor_ reads the attacker and target_ reads the entity being hit. resource(...) reads the holder's resource, and actor_resource(...) and target_resource(...) reach the other side.

So on a modify_damage_dealt, health is the attacker's health and target_health is the victim's. This one hits for exactly as much health as the attacker has:

{
    "type": "apoli:modify_damage_dealt",
    "modifier": {
        "operation": "set_total",
        "amount": "health"
    }
}

"amount": "target_health" would hit for exactly the victim's remaining health. nbt[...] follows the same rule: nbt[Health] is the holder, and nbt[target, Health] is the other side.

Functions that take an ID

A few functions take a bare namespace:path ID as their first argument. Any other arguments are ordinary expressions.

With the Origins mod installed, five more are registered:

Origins also registers the plain variables origin_count (the number of layers with an origin that isn't empty) and is_swapped (1 while any layer is swapped).

Birdsong adds five voice chat variables, such as voice_loudness and voice_speaking. Without Birdsong, Apoli still accepts those five names and reads them as 0.

Unknown variable names, unknown functions and any other syntax error are an error when the pack loads. The power (or other JSON file) containing the expression fails to parse, and the error message names the expression and the position of the problem. Apoli has one compiled expression engine and no fallback evaluator.

Reading a table resource

An apoli:resource with a size above 1 stores several values. Index it with square brackets:

{
  "type": "apoli:add_velocity",
  "x": "example:pos[0]",
  "y": "example:pos[1]",
  "z": "example:pos[2]"
}

The index is a full expression, so it can be worked out. example:table_size gives the slot count, and resource_contains(example:table, 5) searches the whole table. A reference without an index reads slot 0.

Reading a resource's bounds

Adding _max or _min to a resource ID reads that resource's limit instead of its current value:

{
  "type": "apoli:change_resource",
  "resource": "example:mana",
  "change": "example:mana_max / 10",
  "operation": "add"
}

The limit is evaluated at the same moment as the expression around it, so a resource whose max is itself an expression ("max": "20 + 5 * xp_level") reports its current ceiling, not an old one.

If there is no resource power at the ID without the suffix, the name is treated as an ordinary resource ID, so a resource really called example:mana_max still resolves to its own value. Lookups of limits nest up to 8 deep, and beyond that they read 0, which stops a loop (a max that refers to its own _max) from hanging the server.

Enchantment levels

enchantment[...] reads the level of an enchantment on the entity's gear:

{
  "type": "apoli:heal",
  "amount": "10 + enchantment[minecraft:mending, weapon.mainhand, sum]"
}

The arguments, separated by commas:

Everything after the ID is optional and can come in either order, so enchantment[minecraft:mending, weapon.mainhand], enchantment[minecraft:protection, armor, max] and enchantment[minecraft:feather_falling] all work. On a single slot, sum and max give the same number.

An enchantment that isn't installed reads 0 instead of failing to load, so an expression can mention an enchantment from another mod. Hotbar, inventory and ender chest slots only read players, and on any other entity they read 0. In a bi-entity context, target_enchantment[...] and actor_enchantment[...] read the target's and the actor's gear, like the target_ and actor_ variables.

Durability

durability[...] reads how many more uses the item in a slot has before it breaks: its maximum durability minus the damage it has taken.

{
  "type": "apoli:modify_damage_dealt",
  "modifier": {
    "operation": "add_base_late",
    "value": "if(durability[weapon.mainhand] > 0 && durability[weapon.mainhand] < 20, 4, 0)"
  }
}

This adds 4 damage while the held weapon has fewer than 20 uses left.

The one argument is an Item Slot, such as weapon.mainhand, armor.head or hotbar.0. An empty slot or an item without durability reads 0, and an unbreakable item reads the durability it would have. Hotbar, inventory and ender chest slots only read players. In a bi-entity context, target_durability[...] and actor_durability[...] read the target's and the actor's items.

Attributes

attribute[...] reads one of the entity's attributes, the same numbers the /attribute command reports:

{
  "type": "apoli:heal",
  "amount": "attribute[minecraft:generic.max_health] - attribute[minecraft:generic.max_health, base]"
}

This heals by however much extra max health the entity's modifiers give it.

The arguments, separated by commas:

So attribute[minecraft:generic.armor], attribute[minecraft:generic.movement_speed, base], attribute[minecraft:generic.max_health, max] and attribute[minecraft:generic.attack_damage, modifier, example:sharp_claws] are all valid. An entity that doesn't have the attribute at all, such as an entity that isn't alive or a mob the attribute isn't registered for, reads 0 for get, base and modifier.

Modifier IDs are written the way /attribute takes them on your version: namespace:path on 1.21.1 and a UUID on 1.20.1.

An attribute ID that doesn't exist is a load error that names the expression, so a typo shows up in the log instead of reading 0 without a word. In a bi-entity context, target_attribute[...] and actor_attribute[...] read the target's and the actor's attributes, like the target_ and actor_ variables.

Reading NBT

nbt[...] reads a number out of NBT data, the same way /data get does. data[...] is another name for it.

{
  "type": "apoli:modify_resource",
  "resource": "example:ammo",
  "modifier": {
    "operation": "set_total",
    "amount": "nbt[Inventory[{id:\"minecraft:arrow\"}].count, sum]"
  }
}

The arguments, separated by commas:

So nbt[Health], nbt[Inventory[].count, sum], nbt[weapon.mainhand, components."minecraft:damage"], nbt[storage, example:vars, counter] and nbt[block, x, y - 1, z, Items[].count, sum] are all valid. The value is read the way /data get reports it: a number as itself, a string as its length, a list or compound as how many entries it holds, and a path that matches nothing as 0.

The paths are whatever /data get shows on your version of the game, so item data lives under components on 1.21.1 and under tag on 1.20.1.

NaN policy

If an expression comes out as NaN or ±Infinity, for example from dividing by zero or sqrt(-1), Apoli uses 0 instead. Use if() for an explicit fallback: if(max_health > 0, health / max_health, 1).