CustomNPC-Plus/update/abilities.md

# Abilities

---

The **Ability System** adds full combat abilities to CustomNPC+. Give NPCs powerful attacks with visual telegraphs, launch energy projectiles, set traps, chain abilities into combos, and let players unlock abilities of their own.

---

## How Abilities Work

Every ability follows a **phase-based flow**: **Wind-up** (charge with telegraphs/animations) → **Active** (fire, deal damage, apply effects) → **Dazed** (optional recovery if interrupted).

**Core Settings:** Cooldown (universal + per-ability), Targeting (Aggro/Self/AOE Self/AOE Target), Range (min/max), Lock Movement/Rotation per phase, Interruptible wind-up, Weight (NPC priority), Invulnerability per phase, Ignore I-Frames, Free on Cast, and Magic Damage (separate type with split ratios).

> Abilities can be configured on individual NPCs or saved as **global presets**.

---

## Melee Abilities

- **Slam** - Leap toward target, AOE on impact. Configurable radius, knockback, leap height. Air slams deal reduced damage
- **Heavy Hit** - Powerful single strike with bonus knockback and configurable hit delay
- **Cutter** - Slashing arc in a cone with configurable angle and reach

> All melee abilities support configurable damage, knockback, and potion effects on hit.

---

## Energy Projectiles

A full projectile system with a **Variant System** for patterns like dual-fire or barrages.

**Types:** Orb (homing spheres, dual-fire/barrage variants), Disc (spinning, optional boomerang, vertical/horizontal), Beam (sustained, Free Aim mode), Laser Shot (instant hitscan, no homing).

**Shared Settings:** Anchor Point (7 presets + custom offset), Display (colors, glow, transparency, size), Homing (toggle, turn rate, range), Combat (damage, knockback, AOE splash), Hit Type (Single/Pierce/Multi with max hit count), Lifespan (speed, max age, max distance), Size Interpolation, Proximity Alpha, and Explosions (configurable radius, toggleable block damage).

---

## Energy Barriers

Defensive constructs that block incoming attacks.

- **Dome** - Spherical barrier around the caster
- **Wall** - Flat panel with optional launch mode (fires forward dealing damage/knockback)
- **Shield** - Held panel following the caster's facing direction

**Properties:** HP/durability, melee vulnerability toggle, damage absorption (redirects caster damage to barrier), projectile reflection, ally/target filtering, custom position offsets.

---

## Defensive Abilities

- **Guard** - Reduces incoming damage by configurable %. Ends on duration or max hit count
- **Counter** - Absorbs attacks and counter-attacks. Flat or percentage-based counter damage with counter animation
- **Dodge** - Fully evades incoming attacks. Randomized dodge animations from up to 3 slots

---

## Movement Abilities

- **Charge** - Rush forward dealing damage in path. Configurable speed, hit width, knockback. Direction locks during wind-up
- **Dash** - Quick directional movement without damage. Supports directional key input
- **Teleport** - Instant relocate to target's position

---

## AOE Abilities

- **Shockwave** - AOE burst from caster with configurable radius and knockback
- **Sweeper** - Rotational sweep around caster. Can run alongside other abilities in chains
- **Vortex** - Pulling force dragging entities toward center while dealing damage

---

## Hazards & Traps

### Hazards

Persistent damaging zones with configurable damage interval, zone count (up to 20), shape (circle/square), height, and duration. Can affect caster.

**Visual Presets:** Default, Toxic, Inferno, Arcane, Electric, Frost.

### Traps

Proximity-triggered, sit dormant until an entity enters trigger radius. Configurable arm time, trigger count, cooldown, damage radius, knockback. Can be hidden until triggered.

**Presets:** Hidden, Venom (Poison), Explosive (Fire), Cursed (Weakness), Shock (Mining Fatigue), Snare (Slowness).

### Zone Visuals

Both have configurable ground fill, concentric rings, rotating borders, accents (static/swaying/flickering), lightning arcs, and particles with multiple motion types.

---

## Ability Effect

Support ability for buffs, debuffs, healing, and custom effects.

**Targeting:** Self or AOE Self (with Allies/Enemies/All filter based on Party/Faction).

**Applies:** Flat and percentage healing (instant or over time), vanilla potion effects, custom effects, and mod-registered effect actions.

**Built-in Variants:** Self Heal, Healing Aura, Poison Debuff.

---

## Custom Ability

Blank-slate ability for scripters with hooks: **Start**, **Execute**, **Tick** (with phase/count), **Complete**, **Toggle / Toggle Tick** (multi-state). Full telegraph control with all shapes. Supports instant and multi-state toggle modes.

---

## Burst System

Abilities fire **multiple times in rapid succession** as a single use.

- **Burst Amount** - Additional repetitions after initial cast
- **Burst Delay** - Ticks between each burst
- **Replay Animations** and **Overlap Mode** (previous entities persist during next burst)

> Available on most ability types including energy projectiles, melee, and movement abilities.

---

## Chained Abilities

Chain abilities into **sequential combos** with configurable delays between entries. Options: Wind-up All (simultaneous wind-up), Chain Cooldown, Chain Conditions (checked once for the whole chain).

**Concurrency:** Effect, Hazard, Trap, and Sweeper types can execute alongside the primary ability instead of waiting.

> Works with the ability hotbar and supports live previewing in the editor.

---

## Telegraph System

Visual ground indicators during wind-up that shift color before firing.

**Shapes:** Circle, Ring (donut), Line (rectangle), Cone (fan/wedge), Point, Square.

**Features:** ARGB color customization for telegraph and warning phases, entity-following or fixed position, proper ground/air height handling, saved as reusable presets.

---

## Animations & Sound

Per-phase animations (Wind-up, Active, Dazed) with optional animation-synced duration. Custom sound events for wind-up and active phases. Phase colors on the caster. Multiple animations can be registered under one common name.

---

## Effects & Conditions

### Potion Effects

Abilities can apply potion effects on hit with configurable type, duration, and amplifier (up to 255). Supports modded effects via manual potion IDs.

**Presets:** Fire, Slowness, Weakness, Poison, Wither, Blindness, Nausea, Hunger, Mining Fatigue.

### Conditions

Control when abilities can be used. Each checks **Caster**, **Target**, or **Both**:

- **HP Threshold** - Above/below/equal (flat or percentage)
- **Hit Count** - Times hit within a time window
- **Has Item** - Holding, wearing, or carrying a specific item
- **Quest Completed** - Player completed a specific quest
- **Has Effect** - Has a specific custom effect

---

## Player Abilities

### Ability Hotbar

12-slot bar accessed by holding **HUD Key** + **scroll wheel**. Shows icons with cooldown progress. Horizontal or vertical layout with 3, 5, or 7 visible slots. Configured via drag-and-drop in the CNPC+ Inventory Ability Tab, customized in the HUD Editor.

### Player Features

Unlock via scripting/commands, per-ability cooldowns, cancel on double-tap during wind-up, ability visibility toggle, proper state management (logout/dimension/death/respawn cleanup, movement suppression during locks), and flight safety.

---

## Scripting API

**Ability Events:** StartEvent, ExecuteEvent (both cancelable), InterruptEvent, CompleteEvent, HitEvent (cancelable, modifiable damage/knockback), TickEvent (phase + count), PlayerAbilityEvent.

**Energy Projectile Events:** Fired, Update, EntityImpact, BlockImpact, Expired.

**Ability Extender System:** Register custom lifecycle hooks (onAbilityStart, onAbilityTick, onAbilityComplete, onAbilityDamage) per ability. Scripts are instanced per use.

---

## Ability Preview

Live preview in the editor — test telegraphs, animations, projectiles, burst patterns, and chains on a dummy NPC with no world effects.

---

## Commands

- `/kam ability list|types|prebuilts` - List abilities, types, or built-ins
- `/kam ability info|delete|reload <name>` - View, delete, or reload abilities
- `/kam ability give|remove <player> <ability>` - Player ability management
- `/kam ability giveChain|removeChain <player> <chain>` - Chain management
- `/kam ability player` - Manage player abilities

---