> For the complete documentation index, see [llms.txt](https://enchantedmobs.superiormc.cn/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://enchantedmobs.superiormc.cn/configs/info-of-abilities/projectiles.md).

# Projectile Abilities

Every registered ability on this page is documented as a complete reference entry. All entries also support the common ability fields from the [Abilities](https://enchantedmobs.superiormc.cn/configs/info-of-abilities.md) page.

## Registry keys on this page

* `launch_projectile`
* `shulker_bullet`
* `reflect_projectile`
* `ricochet_projectile`
* `homing_projectile`

***

## `launch_projectile`

**Purpose:** Spawns and configures one or more projectile entities from a living shooter.

**Context:** When `source` is present it selects the shooter; otherwise `target` selects the shooter. `TARGET` remains the aim target.

### Fields

| Field                 | Default | Description                                                          |
| --------------------- | ------- | -------------------------------------------------------------------- |
| `entity-type`         | `ARROW` | Spawnable Bukkit entity type implementing `Projectile`.              |
| `speed`               | `1.5`   | Launch speed.                                                        |
| `extra-y`             | `0`     | Additional Y component.                                              |
| `count`               | `1`     | Projectile count, minimum 1.                                         |
| `spread-degrees`      | `0`     | Maximum fan angle; projectiles are evenly distributed.               |
| `spawn-offset`        | `0`     | Forward offset from shooter eye.                                     |
| `damage`              | unset   | Ability-damage override stored on projectile.                        |
| `inherit-powers`      | `false` | Track projectile for projectile-tick/hit continuation.               |
| `fireball-yield`      | `1.0`   | Yield for explosive projectiles.                                     |
| `fireball-incendiary` | `true`  | Incendiary flag for fireballs.                                       |
| `potion-type`         | unset   | Base potion type for thrown potions.                                 |
| `potion`              | unset   | Single custom effect when `potion-effects` is absent.                |
| `duration`            | `100`   | Single custom-effect duration.                                       |
| `amplifier`           | `0`     | Single custom-effect amplifier.                                      |
| `potion-effects`      | unset   | Map of custom effects with optional potion, duration, and amplifier. |

### Example

```yaml
type: launch_projectile
source: SOURCE
entity-type: SPLASH_POTION
speed: 1.3
count: 3
spread-degrees: 12
inherit-powers: true
potion-effects:
  poison:
    potion: POISON
    duration: 100
    amplifier: 0
```

### Behavior and limits

* A living same-world target is aimed at; otherwise shooter look direction is used.
* Non-projectile spawn results are removed and shulker bullets receive the current target.
* `inherit-powers` captures owner, bow, consumable, hand, force, and exact inherited power IDs for continuation.

***

## `shulker_bullet`

**Purpose:** Compatibility alias of `launch_projectile`.

**Context:** Uses the same shooter selection, aim target, and fields as `launch_projectile`.

### Fields

| Field                 | Default | Description                                                          |
| --------------------- | ------- | -------------------------------------------------------------------- |
| `entity-type`         | `ARROW` | Normally set to `SHULKER_BULLET`.                                    |
| `speed`               | `1.5`   | Launch speed.                                                        |
| `extra-y`             | `0`     | Additional Y component.                                              |
| `count`               | `1`     | Projectile count, minimum 1.                                         |
| `spread-degrees`      | `0`     | Maximum fan angle; projectiles are evenly distributed.               |
| `spawn-offset`        | `0`     | Forward offset from shooter eye.                                     |
| `damage`              | unset   | Ability-damage override stored on projectile.                        |
| `inherit-powers`      | `false` | Track projectile for projectile-tick/hit continuation.               |
| `fireball-yield`      | `1.0`   | Yield for explosive projectiles.                                     |
| `fireball-incendiary` | `true`  | Incendiary flag for fireballs.                                       |
| `potion-type`         | unset   | Base potion type for thrown potions.                                 |
| `potion`              | unset   | Single custom effect when `potion-effects` is absent.                |
| `duration`            | `100`   | Single custom-effect duration.                                       |
| `amplifier`           | `0`     | Single custom-effect amplifier.                                      |
| `potion-effects`      | unset   | Map of custom effects with optional potion, duration, and amplifier. |

### Example

```yaml
type: shulker_bullet
entity-type: SHULKER_BULLET
target: SOURCE
speed: 1.2
```

### Behavior and limits

* The spawned shulker bullet automatically targets the current context target when available.
* All other behavior matches this repository's `launch_projectile` implementation.

***

## `reflect_projectile`

**Purpose:** Redirects the projectile from the current context back toward its attacker.

**Context:** `target` defaults to `SKILL` and must resolve to a projectile. `shooter` defaults to the power-owning mob (`OWNER`).

### Fields

| Field                      | Default | Description                                                               |
| -------------------------- | ------- | ------------------------------------------------------------------------- |
| `target`                   | `SKILL` | Entity selector for the projectile to reflect.                            |
| `shooter`                  | `OWNER` | New projectile shooter; also accepts `SOURCE`, `SKILL`, or `TARGET`.      |
| `velocity-multiplier`      | `1.0`   | Multiplier applied after reversing the incoming velocity.                 |
| `damage-multiplier`        | `1.0`   | Multiplier applied when the reflected projectile later deals damage.      |
| `reflection-cooldown`      | `0`     | Per-owner reflection cooldown in seconds.                                 |
| `minimum-velocity-squared` | `0.08`  | Velocities below this squared length use the fallback direction.          |
| `fallback-speed`           | `0.95`  | Speed used toward the original attacker for a near-stationary projectile. |
| `origin-distance`          | `0.55`  | Distance in front of the owner's eyes where the projectile is placed.     |
| `abilities`                | unset   | Nested abilities executed only after a successful reflection.             |

### Example

```yaml
type: reflect_projectile
target: SKILL
shooter: OWNER
random: 0.3
reflection-cooldown: 1.5
velocity-multiplier: 0.8
damage-multiplier: 0.65
abilities:
  effect:
    type: sound
    sound: ITEM_SHIELD_BLOCK
```

### Behavior and limits

* The current hit event is cancelled after reflection succeeds.
* Arrows are replaced with fresh reflected copies so their completed-impact state cannot make them fall; other projectile types are redirected in place.
* Entity type and payload data are preserved while ownership, position, velocity, and damage are updated.
* Existing projectile tracking is stopped so abilities belonging to the original shooter do not continue.
* A reflected projectile is marked and cannot be reflected by this ability again.
* Use nested standard `particle` and `sound` abilities for successful-reflection effects.

***

## `ricochet_projectile`

**Purpose:** Replaces an arrow that hits a block with a reflected copy moving away from the impacted face.

**Context:** Requires a block `ProjectileHitEvent` and an `AbstractArrow` in `SKILL`.

### Fields

| Field                           | Default  | Description                                                                            |
| ------------------------------- | -------- | -------------------------------------------------------------------------------------- |
| `maximum-ricochets`             | `1`      | Maximum bounces for one arrow, clamped to `0..12`.                                     |
| `speed-bonus-per-ricochet`      | `0.1`    | Fractional speed increase applied on every bounce.                                     |
| `damage-bonus-per-ricochet`     | `0`      | Flat damage accumulated on every bounce.                                               |
| `minimum-velocity-squared`      | `0.09`   | Minimum incoming squared speed required to bounce.                                     |
| `minimum-live-velocity-squared` | `0.0004` | Below this value, the arrow's facing direction is used.                                |
| `minimum-post-ricochet-speed`   | `0.45`   | Minimum speed before applying the speed bonus.                                         |
| `maximum-post-ricochet-speed`   | `1.5`    | Maximum final speed after applying the speed bonus.                                    |
| `maximum-ricochet-distance`     | `24`     | Maximum cumulative flight distance after each bounce; non-positive disables the limit. |
| `surface-offset`                | `0.22`   | Distance away from the impacted block face.                                            |
| `direction-offset`              | `0.14`   | Additional distance along the reflected direction.                                     |
| `abilities`                     | unset    | Nested abilities executed after a successful bounce.                                   |

### Example

```yaml
type: ricochet_projectile
maximum-ricochets: 2
speed-bonus-per-ricochet: 0.1
damage-bonus-per-ricochet: 1.0
abilities:
  spark:
    type: particle
    particle: ELECTRIC_SPARK
    count: 8
```

### Behavior and limits

* Arrow, spectral-arrow, potion, persistent-data, and scoreboard-tag state is copied to the replacement.
* Existing projectile tracking and its exact power IDs continue after the bounce.
* Nested standard `particle` and `sound` abilities provide bounce effects.
* Entity hits do not ricochet.

***

## `homing_projectile`

**Purpose:** Steers the current projectile toward a locked or newly selected living target.

**Context:** Requires `SKILL` to be a valid projectile; normally used on a projectile-tick trigger.

### Fields

| Field                   | Default | Description                                       |
| ----------------------- | ------- | ------------------------------------------------- |
| `radius`                | `16`    | Maximum target search/lock radius.                |
| `strength`              | `0.2`   | Steering blend, clamped `0.01..1`.                |
| `require-line-of-sight` | `false` | Require line of sight.                            |
| `max-angle`             | `360`   | Maximum cone half-angle around current heading.   |
| `lead`                  | `0`     | Target-motion prediction factor.                  |
| `max-ticks`             | `100`   | Maximum executions; non-positive disables expiry. |
| `remove-on-expire`      | `true`  | Remove projectile when expired.                   |
| `disable-gravity`       | `false` | Disable gravity while homing.                     |

### Example

```yaml
type: homing_projectile
radius: 24
strength: 0.18
max-angle: 90
lead: 0.5
max-ticks: 120
```

### Behavior and limits

* The projectile retains its previous valid target and rescans only when needed.
* Creative and spectator players are ignored.
* Target priority is existing lock, source mob target, then best nearby candidate.
* Expiry returns a cancellation request so projectile tracking can stop.

***
