mirror of
https://github.com/KAMKEEL/CustomNPC-Plus.git
synced 2026-11-11 10:17:34 +00:00
208 lines
8.2 KiB
Markdown
208 lines
8.2 KiB
Markdown
# 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
|
|
|
|
---
|