Variable System

What Are Variables?

Variables are dynamic values that change based on the situation. They let you:

• Scale effects with enchant level

• React to damage dealt

• Use random values consistently

• Reference positions and entities

• Perform calculations

---

Using Variables

Variables are written with curly braces: {variable_name}

# Use in damage
damage: "{level} * 50"

# Use in text
text: "&c+{damage} Damage!"

# Use in calculations
amount: "100 + {level} * 10"

Variables work in:

• Damage/amount fields

• Text/messages

• Math expressions

• Position offsets

---

Built-in Variables

These variables are automatically available in every action:

Player Variables

{player} - Player's name

message: "{player} activated an enchant!"

{player_pos} - Player's current location

position: "{player_pos}"

{player_x}, {player_y}, {player_z} - Player's coordinates

position: "{player_x}, {player_y} + 5, {player_z}"

{player_yaw} - Player's horizontal rotation (0-360)

# Advanced: calculate direction-based effects

{player_pitch} - Player's vertical rotation (-90 to 90)

# Advanced: detect if looking up/down

---

Enchant Variables

{level} - Current enchant level

damage: "{level} * 100"
amplifier: "{level} - 1"
amount: "{level} * 50"

---

Combat Variables

{damage} - Damage dealt (HIT_MOB trigger only)

# Give currency based on damage
amount: "{damage} * 0.5"

# Show damage number
text: "&c-{damage}"

{target_mob} - Target mob's entity ID

entity: "{target_mob}"

{target_pos} - Target mob's location

position: "{target_pos}"

{target_x}, {target_y}, {target_z} - Target coordinates

position: "{target_x}, {target_y} + 2, {target_z}"

---

Trigger Variables

{trigger_pos} - Where the enchant was activated

position: "{trigger_pos}"

This could be:

• Hit location (HIT_MOB)

• Death location (MOB_DEATH)

• Player location (PASSIVE)

{trigger_x}, {trigger_y}, {trigger_z} - Trigger coordinates

# Spawn 5 blocks above hit location
position: "{trigger_x}, {trigger_y} + 5, {trigger_z}"

---

Loop Variables

{iteration} - Current loop iteration (loops only)

type: "loop"
iterations: 5
tick-interval: 10
actions:
  1:
    type: "particle-effect"
    particle: "FLAME"
    position: "{forward:{iteration}}"  # 0, 1, 2, 3, 4 blocks
    count: 10

The iteration variable starts at 0:

• First loop: {iteration} = 0

• Second loop: {iteration} = 1

• Third loop: {iteration} = 2

• etc.

---

Custom Variables

Create your own variables with the set-variable action:

Basic Usage

actions:
  1:
    type: "set-variable"
    name: "my_value"
    value: "100"
  2:
    type: "damage-area"
    damage: "{my_value}"

Why Use Custom Variables?

Problem: You want to show the same random value in multiple places.

actions:
  1:
    type: "add-currency"
    currency: "money"
    amount: "%phantomdungeons_math_random_50_200%"  # Random value 1
  2:
    type: "hologram"
    text: "&a+%phantomdungeons_math_random_50_200% Money"  # Random value 2 (different!)
    position: "{target_pos}"

The hologram will show a different random number than what was given/

actions:
  1:
    type: "set-variable"
    name: "reward"
    value: "%phantomdungeons_math_random_50_200%"  # Generate once
  2:
    type: "add-currency"
    currency: "money"
    amount: "{reward}"  # Use same value
  3:
    type: "hologram"
    text: "&a+{reward} Money"  # Shows same value!
    position: "{target_pos}"

Entity References

Store entity IDs for later use:

actions:
  1:
    type: "spawn-entity"
    entity-type: "ARROW"
    reference: "my_arrow"  # Creates {my_arrow} variable
    position: "{trigger_pos}"
  2:
    type: "delay"
    ticks: 40
  3:
    type: "explosion"
    position: "{my_arrow:position}"  # Use arrow's position
  4:
    type: "remove-entity"
    reference: "my_arrow"

---

Math Expressions

Variables support mathematical operations:

Operators

• + Addition

• - Subtraction

• * Multiplication

• / Division

• () Parentheses

Examples

Simple scaling:

damage: "{level} * 100"
# Level 1: 100
# Level 5: 500
# Level 10: 1000

Add base + scaling:

damage: "50 + {level} * 10"
# Level 1: 60
# Level 5: 100
# Level 10: 150

Percentage of damage:

amount: "{damage} * 0.5"
# 100 damage: 50 currency
# 500 damage: 250 currency

Complex formula:

damage: "({level} * 50) + ({damage} * 0.2)"

Amplifier calculation:

amplifier: "{level} - 1"
# Level 1: amplifier 0 (Effect I)
# Level 2: amplifier 1 (Effect II)
# Level 3: amplifier 2 (Effect III)

Conditional math:

# More damage at higher levels
damage: "{level} < 5 then 100 else 200"

---

Placeholder Support

You can use PlaceholderAPI placeholders as variables.

Random Numbers

amount: "%phantomdungeons_math_random_50_200%"

Generates random number between 50-200 each time.

Format Numbers

text: "&a+%phantomdungeons_math_format_abbrev_{amount}%"

Formats large numbers (1500 → 1.5k, 1000000 → 1M)

Player Stats

amount: "%phantomdungeons_currency_balance_money% * 0.01"

Give 1% of player's current money.

Combining

Mix variables and placeholders:

actions:
  1:
    type: "set-variable"
    name: "bonus"
    value: "%phantomdungeons_math_random_50_150% + {level} * 10"
  2:
    type: "add-currency"
    currency: "souls"
    amount: "{bonus}"
  3:
    type: "hologram"
    text: "&5+%phantomdungeons_math_format_abbrev_{bonus}% Souls"
    position: "{target_pos}"

---

Position Variables

Variables work in positions too:

Basic Position Variables

position: "{trigger_pos}"
position: "{player_pos}"
position: "{target_pos}"

Math in Positions

Add offsets:

position: "{trigger_pos} + 0, 5, 0"  # 5 blocks up
position: "{player_pos} - 2, 0, 2"   # 2 blocks offset

With variables:

position: "{target_x}, {target_y} + 10, {target_z}"

Entity Positions

Reference spawned entities:

position: "{my_arrow:position}"
position: "{projectile:position}"

---

---

Troubleshooting

Variable Not Resolving

Problem: Variable shows as {my_var} instead of value

1

Check spelling

Ensure the variable name matches exactly where it's set and where it's used.

2

Ensure it's set before use

Variables must be created with set-variable (or be built-in) before being referenced.

Wrong Value

Problem: Variable has unexpected value

1

Debug hologram

Add a hologram to display the value:

type: "hologram"
text: "Debug: {my_var}"
position: "{player_pos}"

2

Check math expression syntax

Look for misplaced operators or parentheses.

3

Verify placeholder resolution

If using placeholders, confirm they resolve as expected.

Math Not Calculating

Problem: {level} * 100 shows as text, not calculated

1

Field support

Ensure the field supports expressions (damage, amount, etc.).

2

Check for syntax errors

Confirm there are no stray quotes or invalid characters.

3

Use set-variable for complex math

type: "set-variable"
name: "result"
value: "{level} * 100"

Then reference {result} where needed.

---