# ⚔️ CustomNPC+ 1.11 - Abilities ⚔️ --- The **Ability Update** introduces a full combat ability system to CNPC+! Give your NPCs powerful attacks with **visual telegraphs**, launch **energy projectiles** that home in on targets, and let players unlock abilities of their own! --- ## How Abilities Work 🎯 Every ability follows a **phase-based execution flow** that gives combat a readable, strategic feel. **Phases:** - **Wind-up** - The ability charges. Telegraphs appear, animations play, and observant players can react - **Active** - The ability fires. Damage is dealt, projectiles launch, effects apply - **Dazed** - Optional recovery state if the ability is interrupted during wind-up **Core Configuration:** - **Cooldown** - Time before the ability can be used again - **Targeting Mode** - Aggro Target, Self, AOE on Self, or AOE on Target - **Range** - Configurable min and max range for activation - **Lock Movement** - Lock the caster's movement, rotation, or both during any phase - **Interruptible** - Allow damage to interrupt wind-up and force a dazed state - **Weight** - Priority weighting for NPC random ability selection > Abilities support both **inline configuration** on individual NPCs and **global presets** that update everywhere when edited. --- ## Melee Abilities 🗡️ Close-range attacks that hit hard and punish positioning. - **Slam** - Leap toward the target in an arc, dealing AOE damage on impact. Configurable radius, knockback, and leap height - **Heavy Hit** - A single powerful melee strike with bonus knockback - **Cutter** - A slashing arc attack in a cone. Configurable angle and reach - **Shockwave** - An AOE burst radiating outward from the caster > All melee abilities support configurable **damage**, **knockback**, and **potion effects** on hit. --- ## Energy Projectiles ✨ A brand new projectile system built from the ground up with full visual customization. ### Orbs Homing energy spheres that track their target through the air. - **Orb** - A single homing projectile - **Dual Orb** - Fires two orbs simultaneously - **Orb Barrage** - Fires a volley of orbs in rapid sequence ### Discs Flat spinning projectiles with optional **boomerang** behavior. - **Disc** - A single spinning disc with configurable radius and thickness - **Dual Disc** - Fires two discs simultaneously ### Beams Sustained energy beams that connect the caster to their target. - **Beam** - A homing beam with configurable width and head size. Locks the caster in place during channeling - **Dual Beam** - Fires two beams simultaneously ### Laser Shot An **instant-fire** projectile with configurable width and speed. No homing — pure aim. ### Projectile A standard projectile using classic Minecraft physics for a more traditional ranged attack. ### Energy Configuration Every energy projectile shares a **modular data system** for deep customization: - **Anchor Point** - Choose where the projectile spawns: Right Hand, Left Hand, Front, Center, Chest, or Above Head - **Display** - Set core color, edge color, glow effect, transparency, and size - **Homing** - Toggle homing, adjust turn rate and max tracking range - **Combat** - Damage, knockback, vertical knockback, hit cooldown, and optional AOE splash - **Lifespan** - Projectile speed, max age, and max travel distance --- ## Movement Abilities 💨 Abilities that reposition the caster in combat. - **Charge** - Rush forward in a line, damaging all entities in the path. Configurable speed, hit width, and knockback - **Dash** - A quick directional movement without dealing damage - **Teleport** - Instantly relocate to the target's position > **Charge** locks direction during wind-up, so the telegraph accurately shows the attack path. --- ## AOE Abilities 🌀 Area control abilities that dominate space. - **Sweeper** - A wide rotational sweep attack around the caster with configurable radius and rotation speed - **Vortex** - Creates a pulling force that drags nearby entities toward the center while dealing damage --- ## Telegraph System 📍 **Telegraphs** are visual ground indicators that warn players before an ability lands. They appear during the wind-up phase and disappear when the ability fires. **Shapes:** - **Circle** - Filled circle with configurable radius - **Ring** - Donut shape with inner and outer radius - **Line** - Rectangle along the attack direction - **Cone** - Fan/wedge shape with configurable angle - **Point** - Single point indicator **Features:** - **Color Customization** - Set ARGB colors for both the telegraph and its warning phase - **Warning Phase** - Color shifts in the final ticks before the ability fires - **Entity Tracking** - Telegraphs can follow a moving entity or stay at a fixed position - **Smooth Interpolation** - Position updates are interpolated for clean visuals > Telegraphs are saved as **reusable presets** and can be shared across multiple abilities. --- ## Animations & Sound 🎬 Abilities integrate directly with the animation and sound systems. - **Wind-up Animation** - Plays during the charging phase - **Active Animation** - Plays when the ability fires - **Animation Sync** - Optionally sync wind-up duration to match animation length exactly - **Sound Events** - Assign custom sounds to both wind-up and active phases - **Phase Colors** - Visual color feedback on the caster during wind-up and active > Many ability types include **built-in animation names** that work automatically when matching animations exist. --- ## Effects & Conditions ⚡ ### Potion Effects Abilities can apply **potion effects** to any entity they hit. Each effect has configurable type, duration, and amplifier. **Available Effects:** Slowness, Weakness, Poison, Wither, Blindness, Nausea, Hunger, Mining Fatigue ### Conditions Abilities support a **condition system** that controls when they can be used. Conditions are evaluated before execution and can require specific target states, ranges, or custom predicates. --- ## Player Abilities 🧑 Players can unlock and use abilities too! - **Unlock System** - Players receive abilities via scripting or commands - **Ability Selection** - Choose one ability at a time from your unlocked list - **Universal Cooldown** - Shared cooldown across all player abilities --- ## Scripting API 📜 Full scripting support for ability lifecycle events: - **StartEvent** *(Cancelable)* - Fired when wind-up begins - **ExecuteEvent** *(Cancelable)* - Fired when the ability activates - **InterruptEvent** - Fired when wind-up is interrupted by damage - **CompleteEvent** - Fired when the ability finishes - **HitEvent** *(Cancelable)* - Fired on each entity hit. Damage and knockback values can be modified - **TickEvent** - Fired every tick with current phase and tick count > Scripts can cancel, modify damage, and react to every phase of ability execution. --- ## Ability Preview 🔎 The ability editor includes a **live preview system**. Test your telegraph shapes, animations, and projectile visuals directly in the GUI on a dummy NPC — no world effects applied. --- ## Ability Commands 💬 - `/kam ability list` - List all custom abilities - `/kam ability types` - List all registered ability types - `/kam ability info ` - View ability details - `/kam ability delete ` - Delete a custom ability - `/kam ability reload` - Reload abilities from disk ---