Skip to main content

EliteScript

webapp_banner.jpg

EliteScript is a comprehensive scripting system for MagmaGuy's Plugins, providing advanced customization options for creating dynamic behaviors for bosses and other entities in Minecraft.

EliteScript or Lua?

EliteMobs has two scripting systems and both are fully supported. EliteScript is not deprecated.

  • EliteScript (this page and its siblings) — declarative YAML. Best when your power is "on this event, do these actions to these targets". Nothing here has been removed or superseded.
  • Lua powers — .lua files in the same powers folder. Best when you need variables, loops, random branching, per-boss state, or scheduled follow-ups. EliteMobs' own bundled powers are now written in Lua.

They are not rivals: Lua's context.script API is a thin wrapper around the EliteScript engine. When you write context.script:target({...}) or context.script:zone({...}) in Lua, the table you pass is handed to the exact same target/zone/relative-vector/particle code documented on these pages, so every field name below applies verbatim. Learning EliteScript is not wasted effort if you later move to Lua.

One practical consequence: if a .lua power and a .yml power share a base name, a boss's powers: list entry pointing at the .yml resolves to the .lua file. That is how the bundled powers were migrated without breaking existing boss configs.

Overview​

EliteScript allows server administrators to create complex, event-driven behaviors for custom bosses and mobs. The scripting system is built on five core components:

  • Events: Triggers that start script execution (damage, spawn, death, etc.)
  • Conditions: Requirements that must be met for actions to execute
  • Actions: The behaviors to perform (damage, teleport, spawn particles, etc.)
  • Targets: What entities or locations the actions affect
  • Zones: Defined areas in the world for targeting and detection
  • Cooldowns: Time restrictions to prevent script spam

Elite Scripts can be added as standalone power files or directly into custom boss configuration files.

Quick Start Example​

Here is a simple EliteScript that makes a boss strike lightning at players when damaged:

eliteScript:
  LightningStrike:
    Events:
    - EliteMobDamagedByPlayerEvent
    Actions:
    - action: STRIKE_LIGHTNING
      Target:
        targetType: DIRECT_TARGET
      repeatEvery: 20
      times: 3
    Cooldowns:
      local: 60
      global: 20

This script triggers when a player damages the boss, then strikes lightning at the player 3 times (once per second), with a 60-tick cooldown before it can trigger again.

Script Components​

EliteScript provides extensive customization through its component system. For detailed information about each component, see the following pages:

Core Components​

  • Events - 13 event types including damage, death, spawn, combat, and zone-based triggers
  • Actions - 35 action types for creating complex behaviors
  • Targets - 17 target types for selecting entities and locations
  • Conditions - Filtering and blocking conditions with multiple check types
  • Zones - 8 zone shapes (spheres, cylinders, cuboids, rays, cones, etc.)
  • Cooldowns - Local and global cooldown systems
  • Relative Vectors - Advanced positioning and movement

Common Use Cases​

EliteScript is commonly used for:

  • Phase-based boss fights: Different attack patterns at different health percentages
  • Arena mechanics: Zone-based damage, buffs, or spawns in specific areas
  • Custom attacks: Unique particle effects, projectiles, and area attacks
  • Environmental hazards: Periodic lightning, falling blocks, or fire
  • Interactive mechanics: Teleportation, mob spawning, and world modification
  • Player communication: Messages, titles, action bars, and boss bars
  • Conditional behaviors: Different actions based on player count, location, or boss state

Implementation​

Scripts can be implemented in two ways:

  1. Power Files: Create standalone .yml files in ~/plugins/EliteMobs/powers/
  2. Custom Boss Files: Add eliteScript: sections directly to custom boss configurations

For detailed instructions on creating powers and custom bosses, see:

Performance Considerations​

When creating scripts, keep these best practices in mind:

  • Use cooldowns to prevent performance issues from rapid-fire scripts
  • Zone-based events (ZoneEnterEvent, ZoneLeaveEvent) are computationally expensive - use small zones and appropriate cooldowns
  • Use filtering conditions to reduce unnecessary checks
  • Test scripts thoroughly before deploying to production servers

Next Steps​

To start creating your own EliteScripts:

  1. Review the Events page to understand what can trigger scripts
  2. Explore the Actions page to see what behaviors you can create
  3. Learn about Targets to control what your actions affect
  4. Study the examples in each component page
  5. Start with simple scripts and gradually add complexity