Elite Script Relative Vectors

What they are for

Relative vectors are vectors that are relative to a specific but dynamic location.

For example, to pull a player towards a moving boss, calculate a vector from the player's location to the boss's location. A fixed vector cannot follow their changing positions.

Relative vectors can aim projectiles, launch falling blocks and set facing directions. As relative offsets, they can position a reinforcement beyond a player or extend a ray past its target.

Usage Context

Relative vectors are used in action contexts with the YAML key RelativeVector:. This includes actions like:

• SUMMON_ENTITY - Sets the velocity (movement direction and speed) of the spawned entity
• SUMMON_REINFORCEMENT - Sets the velocity of the spawned reinforcement
• SPAWN_PARTICLE - Supplies the particle movement vector under each individual particles: entry; the action-level field is not used for this
• PUSH - Sets the push velocity
• SPAWN_FALLING_BLOCK - Sets the falling block velocity
• SET_FACING - Sets the direction an entity faces

Other actions parse a valid RelativeVector: block but do not use it. These key names are case-insensitive, so particle entries accept both RelativeVector: and relativeVector:. Target-type values retain their documented uppercase spelling.

For velocity actions, RelativeVector takes precedence over vValue; the two are not added together. PUSH calculates one vector for all selected entities and applies it one tick later. SET_FACING also calculates one direction for all selected entities.

For target contexts (modifying target positions), use relativeOffset: inside a target block such as Target, FinalTarget, Target2 or FinalTarget2. An action-level relativeOffset: logs Failed to read key relativeOffset .... It takes effect only when the action has no Target block, because the default SELF target then reads target keys from the action itself. See the relative-offset section below.

How do vectors work?

If you don't know or don't remember what vectors are or how they work, you can think of vectors as arrows that point from one point to another point.

As such, one of the properties of vectors is their length. This length is important; in the case of arrows, this length is the speed at which an arrow is shot, in the case of trying to get offset points from a specific location it is the distance from that point. Things farther away will have greater vector lengths, and closer things will have shorter lengths.

For some mechanics, you will probably not want to rely on how far apart two points are, as you just want to get a direction. Fortunately you are able to use vector normalization, which guarantees that the direction is preserved but changes the length to be 1.0. You can then use multipliers to easily modify the vector until you are satisfied with the offset that it provides or the velocity it gives.

Properties

Value	Details	Mandatory?	Default value
SourceTarget	Target at the point from which the vector will start from	✅	none
DestinationTarget	Target at the end point for the vector	✅	none
normalize	Sets if the vector should be normalized	❌	false
multiplier	Multiplies the vector's length. You can randomize this value by using ~. Example: 1.0~2.5.	❌	1.0
offset	Allows inserting a manual fixed offset to this offset. You can randomize this value by using ~. Example: 0~5,0~2,0~10.	❌	0,0,0

Randomization

Both multiplier and offset support randomization using the tilde (~) delimiter:

• For multiplier: Use format min~max (e.g., 1.0~2.5). This example samples from 1.0 up to, but not including, 2.5.
• For offset: Use format x1~x2,y1~y2,z1~z2 (e.g., 0~5,0~2,0~10). Each component (X, Y, Z) is randomized independently.

Values are sampled each time the vector is calculated. Randomized offset components use the same min up to, but not including, max rule.

Example

eliteScript:
  ShootChicken:
    Events:
    - EliteMobDamagedByPlayerEvent
    Actions:
    - action: SUMMON_ENTITY
      sValue: CHICKEN
      Target:
        targetType: SELF
      RelativeVector:
        SourceTarget:
          targetType: SELF
        DestinationTarget:
          targetType: DIRECT_TARGET
        normalize: true
        multiplier: 2.0

Launches a chicken from the boss towards the attacking player.

---

eliteScript:
  ShootArrow:
    Events:
    - EliteMobDamagedByPlayerEvent
    Actions:
    - action: SUMMON_ENTITY
      sValue: ARROW
      Target:
        targetType: SELF
      RelativeVector:
        SourceTarget:
          targetType: SELF
        DestinationTarget:
          targetType: DIRECT_TARGET
        normalize: true
        multiplier: 2.0

Launches an arrow towards the attacking player. For projectile entities with a living boss, SUMMON_ENTITY uses the boss's projectile launcher, so the projectile originates from the boss even if the action's Target specifies another location.

---

eliteScript:
  SpawnReinforcement:
    Events:
    - EliteMobDamagedByPlayerEvent
    Actions:
    - action: SUMMON_ENTITY
      sValue: ZOMBIE
      Target:
        targetType: DIRECT_TARGET
        relativeOffset:
          SourceTarget:
            targetType: SELF
          DestinationTarget:
            targetType: DIRECT_TARGET
          normalize: true
          multiplier: 2.0

Spawns a vanilla zombie two blocks beyond the player along the boss-to-player line. This is not an EliteMobs reinforcement despite the script's name. relativeOffset belongs inside Target: it changes the spawn position, not velocity. The direction uses the full three-dimensional line, not the player's facing direction, and this offset performs no ground or collision search.

---

eliteScript:
  Example:
    Events:
    - EliteMobDamagedByPlayerEvent
    Zone:
      Shape: SPHERE
      target:
        targetType: SELF_SPAWN
        offset: 0,0,0
        track: false
      filter: PLAYER
      radius: 6
    Actions:
    - action: SPAWN_PARTICLE
      repeatEvery: 38
      times: 5
      Target:
        targetType: ZONE_FULL
        track: false
        coverage: 0.9
      particles:
      - particle: FLAME
        RelativeVector:
          SourceTarget:
            targetType: ACTION_TARGET
            track: true
          DestinationTarget:
            targetType: SELF_SPAWN
            offset: 0,-0.5,0
        speed: 0.05

Creates repeated bursts of inward-moving flames within a sphere around the spawn location. The zone itself does not shrink.

How it works:

• The zone supplies geometric points inside a six-block sphere. filter: PLAYER affects entity selection, not the particle locations used here.
• coverage: 0.9 gives each generated point about a 90% chance of being selected. The action's track: false caches that selection for this run's repeats.
• Each particle's vector points from its spawn position (ACTION_TARGET) to half a block below the boss's spawn position (SELF_SPAWN with offset: 0,-0.5,0).
• The vector is calculated when each particle is spawned. ACTION_TARGET directly uses the supplied action location; its nested track setting does not steer particles already in flight.
• A relative particle vector overrides x, y, z and forces particle amount to zero for directional emission. speed is still passed to Bukkit, and the particle type determines the resulting motion.
• The action runs five times, 38 ticks apart, unless its scheduled work is cancelled. Each qualifying hit starts another run because this example has no cooldown.

Order of operations

The order of operations when applying the properties goes as follows:

Vector calculation -> normalize -> multiplier -> offset

Technical Notes

Vector Normalization: For a nonzero vector, normalization preserves direction and sets its length to 1.0 before the multiplier and offset are applied.

Negative Multipliers: The multiplier can be negative to reverse the direction of the vector. For example, a multiplier of -1.0 will point in the opposite direction.

Offset Coordinates: The offset is applied in world coordinates, not relative to the vector direction. It is added after all other calculations.

World Validation: The source and destination targets must be in the same world. If they are in different worlds, a zero vector (0, 0, 0) is returned, which may cause actions to fail or behave unexpectedly.

Missing Targets: An empty resolved source or destination collection returns a zero vector before the multiplier and offset are applied. This includes a DIRECT_TARGET endpoint when the event has no direct target. A missing SourceTarget or DestinationTarget block still causes an error.

If valid source and destination positions coincide, the vector has zero length. normalize: true leaves it at zero, so only the relative vector's own offset remains. When a target resolves to several positions, the relative vector uses the first resolved position, with no nearest-target guarantee. Use a single target such as DIRECT_TARGET when direction must be unambiguous.

ACTION_TARGET: This uses a location supplied by the action and bypasses the nested target's offset, relativeOffset and track settings. For particles it is the particle position; for entity/falling-block spawning it is the requested spawn position; for reinforcement velocity it is the spawned reinforcement's position. For PUSH and SET_FACING it is the boss's location, not each selected entity. In a target's relativeOffset, it is the location being offset, after that target's plain offset.

Velocity vs Position Context: In action contexts like SUMMON_ENTITY, RelativeVector sets the velocity (movement) of the entity. In target contexts, relativeOffset sets a position offset (location adjustment). The same underlying system is used, but the interpretation differs based on context.

Apply relativeOffset to a target such as SELF, SELF_SPAWN, DIRECT_TARGET, LOCATION or LOCATIONS, including when it defines a zone's origin or endpoint. On ZONE_FULL / ZONE_BORDER it shifts each sampled zone location. It has no effect on LANDING_LOCATION or INHERIT_SCRIPT_TARGET. See the target offset rules.

Elite Script Relative Offset

What Are They For?

Relative offsets function similarly to relative vectors, but with the goal being of adding flexibility to offsets. They allow you to adjust positions dynamically when scripting, making it easier to fine-tune target positions or effects based on context.

How Do Relative Offsets Work?

Relative offsets are additive, meaning whatever the offset resolves to will be added to the base value (such as a location or vector).

Let’s break down an example:

You have a ray zone:

• Target 1 is SELF (the boss).
• Target 2 is DIRECT_TARGET, the player supplied by the event.

Assume the player is eight blocks away, both positions are in the same world, and no other offsets apply. Use SELF as the relative offset's SourceTarget and DIRECT_TARGET as its DestinationTarget, then attach that relativeOffset to Target2. These examples describe the endpoint distance; rendered ray points also depend on the ray settings.

Now let’s apply a relative offset:

Case 1: normalize = false, multiplier = 1

• The original distance is 8.
• Offset value becomes 8 × 1 = 8.
• Final ray length: 8 + 8 = 16.

The ray will pass through the player and continue for 8 additional blocks.

Case 2: normalize = false, multiplier = 2

• Offset value becomes 8 × 2 = 16.
• Final ray length: 8 + 16 = 24.

Case 3: normalize = true, multiplier = 1

• The distance is normalized to 1.
• Offset value becomes 1 × 1 = 1.
• Final ray length: 8 + 1 = 9.

Case 4: normalize = true, multiplier = 2

• Offset value becomes 1 × 2 = 2.
• Final ray length: 8 + 2 = 10.

Summary

• normalize = false uses the actual distance between the targets.
• normalize = true starts from length 1 for a valid nonzero vector.
• The offset is always added to the original value.
• A zero multiplier removes the calculated displacement only if it is finite. The relative vector's own offset is still added afterwards, and the target's ordinary offset remains separate. To disable the relative offset, remove its block.

This system allows you to easily extend or shrink distances dynamically when building more complex skill logic in EliteMobs scripting.

Properties

Value	Details	Mandatory?	Default value
SourceTarget	Target at the point from which the vector will start from	✅	none
DestinationTarget	Target at the end point for the vector	✅	none
normalize	Sets if the vector should be normalized	❌	false
multiplier	Multiplies the vector's length. You can randomize this value by using ~. Example: 1.0~2.5.	❌	1.0
offset	Adds a fixed vector after normalize and multiplier are applied. You can randomize this value by using ~. Example: 0~5,0~2,0~10.	❌	0,0,0

relativeOffset and RelativeVector are parsed by the exact same code, so both accept the same five keys.

Example

eliteScript:
  MakeStaticRay:
    Events:
    - EliteMobDamagedByPlayerEvent
    Zone:
      shape: STATIC_RAY
      Target:
        targetType: SELF
        offset: 0,1,0
      Target2:
        targetType: DIRECT_TARGET
        offset: 0,1,0
        relativeOffset:
          sourceTarget:
            targetType: SELF
          destinationTarget:
            targetType: DIRECT_TARGET
          multiplier: 5
          normalize: true
    Actions:
    - action: SPAWN_PARTICLE
      Target:
        targetType: ZONE_FULL
      particles:
      - particle: ELECTRIC_SPARK
        amount: 1
      repeatEvery: 1
      times: 400

This creates a ray whose endpoint extends five blocks beyond the player along the boss-to-player line. The ordinary offsets raise both endpoints one block above their feet; this is not an automatic entity-center calculation. STATIC_RAY names the shape, not a frozen target snapshot: with the default track: true, this action recalculates its targets on repeats. Set the action's Target.track: false to cache the generated ray locations for a fixed display. The example requests 400 runs one tick apart, and each qualifying hit can start another run.

Note: Even though this example uses relative offset on a zone, keep in mind that relative offsets are not limited to zones, they can be applied to other targets as well.