actions config

⚙️ Actions Config

Actions in Divinity are powerful, logic-based blocks that execute when triggered by specific events — like hitting an enemy, using a skill, or socketing an item. They are used across modules like Arrows, Runes, and more.

This system is provided by Codex, which powers all custom actions, conditions, targets, and triggers.

---

🧩 Basic Structure

Here’s what a typical actions config section looks like (from modules/arrows/items/snowball_explosive.yml):

on-hit-actions:
  default:
    target-selectors:
      near:
        - '[RADIUS] ~distance: 5; ~attackable: true; ~party-member: false;'
      self:
        - '[SELF]'
    conditions:
      list: [ ]
      actions-on-fail: 'null'
    action-executors:
      - '[PARTICLE_SIMPLE] ~name: EXPLOSION_LARGE; ~offset: 2,2,2; ~speed: 0.1; ~amount: 50; ~target: self;'
      - '[SOUND] ~name: ENTITY_GENERIC_EXPLODE; ~target: all;'
      - '[DAMAGE] ~amount: -50%; ~target: near;'

---

🔄 Sections Explained

🏹 target-selectors

Defines which entities the actions should affect. Each line includes a selector type (like [RADIUS], [SELF]) and parameter options.

Example:

[RADIUS] ~distance: 5; ~attackable: true;

✅ conditions

Optional checks before actions execute. If list: contains entries, all must pass. If they fail, actions-on-fail: is run instead.

🚀 action-executors

The actual effects to run — particle visuals, sounds, damage, buffs, messages, etc.

Example:

[DAMAGE] ~amount: -50%; ~target: near;

---

🔧 Common Action Types

Below are just a few supported executors (IActionType):

Type	What It Does
DAMAGE	Deal damage to targets
HEALTH	Heal or harm health directly
PARTICLE_SIMPLE	Show a particle effect
SOUND	Play a sound
COMMAND_PLAYER	Force player to run command
COMMAND_CONSOLE	Run a server-side command
TITLES	Show titles to player
ACTION_BAR	Show an action bar message
GOTO	Jump to another section

Each action has its own valid parameters like ~amount:, ~target:, ~name:, ~speed:, and ~delay:.

---

🧠 Example Use Cases

• A rune that explodes on fail, plays a sound, and shows a title.
• A ranged arrow that damages nearby enemies, with particles and sounds.
• A socketing station that shows success/failure effects.

---

🗂 Where to Find Actions

• Inside each module's config folder (e.g. runes/settings.yml, arrows/items/)
• Sections like on-hit-actions, on-fly-actions, actions-complete, actions-error

---

🛠️ Tips

• Parameters are prefixed with ~, and multiple are separated by ;.
• Brackets [] around selector types (e.g. [SELF]) are required.
• Delays can be added via ~delay: 20 (in ticks).