ZBase

https://github.com/zippy6666/zbase2
Admin
ZBase is a Garry's Mod addon framework that provides base classes and utilities for creating NPCs,...
Tokens:12,400
Snippets:36
Trust Score:6.4
Update:7 months ago
Show doc for...
Tokens:
Raw
### Configure Melee Attacks in Lua

Source: https://context7.com/zippy6666/zbase2/llms.txt

Configures the built-in melee attack system for ZBase NPCs. This includes setting attack animations, speed, distance, cooldown, damage values, and defining callbacks for attack start and damage application. It allows for customization of damage force and visual effects on players.

```lua
-- lua/zbase/entities/melee_monster/init.lua
local NPC = FindZBaseTable(debug.getinfo(1,'S'))

-- Enable base melee attack system
NPC.BaseMeleeAttack = true

-- Melee attack configuration
NPC.MeleeAttackAnimations = {ACT_MELEE_ATTACK1, ACT_MELEE_ATTACK2}
NPC.MeleeAttackAnimationSpeed = 1.2
NPC.MeleeAttackDistance = 60      -- Distance to initiate attack
NPC.MeleeAttackCooldown = {1, 2}  -- Random cooldown between attacks
NPC.MeleeAttackFaceEnemy = true
NPC.MeleeAttackTurnSpeed = 20

-- Damage configuration
NPC.MeleeDamage = {15, 25}        -- Random damage in range
NPC.MeleeDamage_Distance = 80     -- Damage reach distance
NPC.MeleeDamage_Angle = 90        -- Damage cone angle
NPC.MeleeDamage_Delay = 0.5       -- Delay before damage applies
NPC.MeleeDamage_Type = DMG_SLASH
NPC.MeleeDamage_Sound = "ZBase.Melee1"
NPC.MeleeDamage_AffectProps = true

-- Callback when melee attack starts
function NPC:OnMelee()
    self:EmitSound("npc/zombie/claw_strike1.wav")
end

-- Custom damage force applied to victims
function NPC:MeleeDamageForce(dmgData)
    return {forward=300, up=150, right=0, randomness=50}
end

-- Callback when melee damage is dealt
function NPC:OnMeleeAttackDamage(hitEnts)
    for _, ent in ipairs(hitEnts) do
        if ent:IsPlayer() then
            ent:ScreenFade(SCREENFADE.IN, Color(255, 0, 0, 50), 0.3, 0)
        end
    end
end
```

--------------------------------

### ZBase Faction Management (Lua)

Source: https://context7.com/zippy6666/zbase2/llms.txt

Functions to set, get, and manage relationships between entities. Supports setting factions for NPCs and players, retrieving current factions, and defining specific entity relationships (hostile, friendly, etc.).

```lua
-- Faction management
ZBaseSetFaction(entity, "combine")  -- Set entity faction
ZBaseSetFaction(player, "ally")     -- Works on players too

local faction = ZBaseGetFaction(entity)  -- Get current faction

-- Change relationship between specific entities
ZBaseSetRelationship(ent1, ent2, D_HT)  -- D_HT, D_FR, D_LI, D_NU
```

--------------------------------

### Global API Functions

Source: https://context7.com/zippy6666/zbase2/llms.txt

Global functions for spawning NPCs, managing factions, controlling NPC movement, and creating visual/audio effects.

```APIDOC
## Global API Functions

### Description
Provides global functions for spawning ZBase NPCs, managing entity factions, controlling NPC movement, and creating various visual and audio effects.

### Methods

#### `ZBaseSpawnZBaseNPC(class, position, surface_normal, weapon, spawn_flags)`
Spawns a ZBase NPC.

- **class** (string) - The ZBase NPC class name.
- **position** (Vector) - The spawn position.
- **surface_normal** (Vector) - The surface normal at the spawn point.
- **weapon** (string) - The weapon to spawn with ("default" uses NPC's defined weapons).
- **spawn_flags** (number) - Bitwise spawn flags (e.g., `SF_NPC_LONG_RANGE`, `SF_NPC_FADE_CORPSE`).

#### `ZBaseSetFaction(entity, faction_name)`
Sets the faction of an entity.

- **entity** (entity) - The entity to set the faction for.
- **faction_name** (string) - The name of the faction (e.g., "combine", "ally").

#### `ZBaseGetFaction(entity)`
Gets the current faction of an entity.

- **entity** (entity) - The entity to get the faction for.

#### `ZBaseSetRelationship(ent1, ent2, relationship)`
Sets the relationship between two entities.

- **ent1** (entity) - The first entity.
- **ent2** (entity) - The second entity.
- **relationship** (number) - The relationship type (e.g., `D_HT` (Hate), `D_FR` (Friend), `D_LI` (Like), `D_NU` (Neutral)).

#### `ZBaseMove(npc, position)`
Commands an NPC to move to a position (works without nav mesh).

- **npc** (entity) - The NPC to move.
- **position** (Vector) - The target position.

#### `ZBaseMoveJump(npc, position)`
Commands an NPC to jump to a position.

- **npc** (entity) - The NPC to move.
- **position** (Vector) - The target position.

#### `ZBaseMoveEnd(npc)`
Cancels any active NPC movement.

- **npc** (entity) - The NPC to stop.

#### `ZBaseMoveIsActive(npc)`
Checks if an NPC is currently moving.

- **npc** (entity) - The NPC to check.

#### `ZBaseMuzzleFlash(entity, type, attachmentNum)`
Creates a muzzle flash effect on an entity.

- **entity** (entity) - The entity to attach the muzzle flash to.
- **type** (number) - The type of muzzle flash (e.g., 1 for normal, 5 for AR2, 7 for large).
- **attachmentNum** (number) - The attachment number on the entity's model.

#### `ZBaseMuzzleFlashAtPos(pos, ang, type)`
Creates a muzzle flash effect at a specific position and angle.

- **pos** (Vector) - The position of the muzzle flash.
- **ang** (Angle) - The angle of the muzzle flash.
- **type** (number) - The type of muzzle flash.

#### `ZBaseMuzzleLight(pos, radius, brightness, color, decay)`
Creates a dynamic light effect, often used for muzzle flashes.

- **pos** (Vector) - The position of the light.
- **radius** (number) - The radius of the light.
- **brightness** (number) - The brightness of the light.
- **color** (string) - The color of the light in "R G B" format (e.g., "255 150 50").
- **decay** (number) - The light decay rate.

#### `ZBaseAddGlowingEye(id, model_path, skin, bone_name, offset, scale, color)`
Adds a glowing eye effect to a model.

- **id** (string) - A unique identifier for this effect.
- **model_path** (string) - Path to the model file.
- **skin** (number | boolean) - The skin index to apply the effect to, or false for all skins.
- **bone_name** (string) - The name of the bone to attach the eye to.
- **offset** (Vector) - The offset from the bone.
- **scale** (number) - The scale of the eye effect.
- **color** (Color) - The color of the glowing eye.

#### `ZBaseCreateVoiceSounds(name, sound_files)`
Pre-caches a set of voice sound files for an NPC.

- **name** (string) - A base name for the sound set.
- **sound_files** (table) - A list of sound file paths.

#### `ZBaseAddCaption(entity, text, duration, size, position)`
Adds a caption to the screen or associated with an entity.

- **entity** (entity | nil) - The entity to associate the caption with, or nil for a screen caption.
- **text** (string) - The caption text.
- **duration** (number) - The duration the caption should be displayed.
- **size** (number) - The font size of the caption.
- **position** (Vector) - The world position for the caption (if entity is nil).

### Request Example (Spawning and Faction)
```lua
local npc = ZBaseSpawnZBaseNPC(
    "zb_combine_soldier",
    Vector(0, 0, 100),
    Vector(0, 0, 1),
    "default",
    bit.bor(SF_NPC_LONG_RANGE, SF_NPC_FADE_CORPSE)
)

if IsValid(npc) then
    npc:SetAngles(Angle(0, 180, 0))
    ZBaseSetFaction(npc, "ally")
end

-- Faction management
ZBaseSetFaction(entity, "combine")
local faction = ZBaseGetFaction(entity)
ZBaseSetRelationship(ent1, ent2, D_HT)
```

### Request Example (Movement and Effects)
```lua
-- NPC movement
ZBaseMove(npc, Vector(500, 200, 0))
ZBaseMoveJump(npc, Vector(100, 100, 200))
ZBaseMoveEnd(npc)
if ZBaseMoveIsActive(npc) then print("Still moving") end

-- Visual effects
ZBaseMuzzleFlash(entity, 1, attachmentNum)
ZBaseMuzzleFlashAtPos(pos, ang, 5)
ZBaseMuzzleLight(pos, 2, 256, "255 150 50", 0.1)

-- Glowing eyes
ZBaseAddGlowingEye(
    "my_eye",
    "models/monster.mdl",
    false,
    "ValveBiped.Bip01_Head1",
    Vector(2, -3, 0),
    0.5,
    Color(255, 0, 0)
)

-- Sound utilities
ZBaseCreateVoiceSounds("MyNPC.Alert", {
    "npc/myguy/alert1.wav",
    "npc/myguy/alert2.wav"
})

-- Captions
ZBaseAddCaption(nil, "Enemy spotted!", 2, 75, npc:GetPos())
```

### Response (General)
- **entity**: Returns the spawned NPC entity for `ZBaseSpawnZBaseNPC`.
- **boolean**: Returns true or false for check functions like `ZBaseMoveIsActive`.
- **string**: Returns the faction name for `ZBaseGetFaction`.
- **nil**: Returned when operations fail or no entity is found.
```

--------------------------------

### Configure NPC Sounds and Animation Events (Lua)

Source: https://context7.com/zippy6666/zbase2/llms.txt

Sets up various NPC sounds including alert, idle, pain, and death sounds, along with footstep configurations. Hooks into animation events for custom actions like melee attacks and projectile firing.

```lua
-- lua/zbase/entities/vocal_npc/shared.lua
local NPC = FindZBaseTable(debug.getinfo(1,'S'))

-- Sound configuration (use sound scripts for pitch/level control)
NPC.MuteDefaultVoice = true
NPC.MuteAllDefaultSoundEmittions = false

NPC.AlertSounds = "MyNPC.Alert"
NPC.IdleSounds = "MyNPC.Idle"
NPC.Idle_HasEnemy_Sounds = "MyNPC.Combat"
NPC.PainSounds = "MyNPC.Pain"
NPC.DeathSounds = "MyNPC.Death"
NPC.KilledEnemySounds = "MyNPC.Victory"
NPC.LostEnemySounds = "MyNPC.SearchEnemy"
NPC.SeeDangerSounds = "MyNPC.Danger"
NPC.SeeGrenadeSounds = "MyNPC.Grenade"
NPC.AllyDeathSounds = "MyNPC.AllyDown"
NPC.OnMeleeSounds = "MyNPC.Melee"
NPC.OnRangeSounds = "MyNPC.Fire"
NPC.OnGrenadeSounds = "MyNPC.ThrowGrenade"
NPC.FollowPlayerSounds = "MyNPC.Following"
NPC.UnfollowPlayerSounds = "MyNPC.Stopping"

-- Footstep sounds
NPC.FootStepSounds = "MyNPC.Step"
NPC.FootStepSoundDelay_Walk = 0.5
NPC.FootStepSoundDelay_Run = 0.25

-- Sound cooldowns and chances
NPC.IdleSoundCooldown = {5, 10}
NPC.IdleSounds_HasEnemyCooldown = {3, 6}
NPC.PainSoundCooldown = {0.5, 1.5}
NPC.AlertSoundCooldown = {8, 12}
NPC.IdleSound_Chance = 2  -- 1/2 chance
NPC.OnMeleeSound_Chance = 1  -- Always play

-- lua/zbase/entities/vocal_npc/init.lua
local NPC = FindZBaseTable(debug.getinfo(1,'S'))

function NPC:CustomInitialize()
    -- Register animation events for melee damage timing
    self:AddAnimationEvent("attack_slash", 12, 1)
    self:AddAnimationEvent("attack_slash", 24, 2)
end

-- Handle LUA animation events
function NPC:HandleLUAAnimationEvent(seq, ev)
    if ev == 1 then
        -- First hit of combo
        self:MeleeAttackDamage()
        self:EmitSound("MyNPC.Hit1")
    elseif ev == 2 then
        -- Second hit of combo
        self:MeleeAttackDamage()
        self:EmitSound("MyNPC.Hit2")
    end
end

-- SNPC animation events (engine events)
function NPC:SNPCHandleAnimEvent(event, eventTime, cycle, type, option)
    if event == AE_NPC_LEFTFOOT or event == AE_NPC_RIGHTFOOT then
        self:EmitFootStepSound()
    elseif event == 5 then  -- Custom event
        self:RangeAttackProjectile()
    end
end

-- Sound filtering/modification
function NPC:BeforeEmitSound(sndData, sndVarName)
    -- Replace alert sound when low health
    if sndVarName == "AlertSounds" and self:Health() < 30 then
        return "MyNPC.AlertWounded"
    end

    -- Prevent sound in certain conditions
    if self.IsSilenced then
        return false
    end
end

```

--------------------------------

### Implement SNPC Server Logic and AI (Lua)

Source: https://context7.com/zippy6666/zbase2/llms.txt

Contains server-side logic for an SNPC, including custom initialization, think functions, schedule selection, and hurt event handling. It demonstrates adding animation events, managing custom cooldowns, implementing melee attacks, and defining AI behavior for combat and patrolling using ZBase schedules.

```lua
-- lua/zbase/entities/my_snpc/init.lua
local NPC = FindZBaseTable(debug.getinfo(1,'S'))

-- Set model variations
NPC.Models = {"models/monster/variant1.mdl", "models/monster/variant2.mdl"}

-- Override spawn flags
NPC.SpawnFlagTbl = {SF_NPC_LONG_RANGE}

-- Called when NPC is created
function NPC:CustomInitialize()
    -- Add custom animation events
    self:AddAnimationEvent("idle_angry", 15, 1)  -- seq, frame, event_id

    -- Set up custom variables
    self.CustomCooldown = CurTime()
end

-- Called every think tick
function NPC:CustomThink()
    local enemy = self:GetEnemy()

    if IsValid(enemy) and self.CustomCooldown < CurTime() then
        -- Custom logic when enemy is valid
        if self:ZBaseDist(enemy, {within=200}) then
            self:MeleeAttack()
            self.CustomCooldown = CurTime() + 2
        end
    end
end

-- SNPC schedule selection (determines AI behavior)
function NPC:SNPCSelectSchedule(iNPCState)
    local enemy = self:GetEnemy()

    if IsValid(enemy) then
        -- Chase the enemy using ZBase's advanced chase
        return ZSched.CombatChase
    else
        -- Patrol when idle
        if self.CanPatrol then
            return SCHED_PATROL_WALK
        end
        return SCHED_IDLE_STAND
    end
end

-- Called when SNPC takes damage
function NPC:SNPCOnHurt(dmginfo)
    if not IsValid(self:GetEnemy()) then
        -- Face the direction damage came from
        self:FaceHurtPos(dmginfo)
    end
end

```

--------------------------------

### Sound Utilities: Creating Voice Sounds (Lua)

Source: https://context7.com/zippy6666/zbase2/llms.txt

Defines a set of sound files to be used for a specific NPC voice event. This allows for randomized playback of different sound variations for events like alerts or taunts.

```lua
-- Sound utilities
ZBaseCreateVoiceSounds("MyNPC.Alert", {
    "npc/myguy/alert1.wav",
    "npc/myguy/alert2.wav"
})
```

--------------------------------

### Configure Flying SNPC Behavior (Lua)

Source: https://context7.com/zippy6666/zbase2/llms.txt

This snippet defines configuration for flying NPCs, including their class, name, category, and inheritance. It specifies flight parameters such as ground distance, facing behavior, movement speed, acceleration, and gravity gun resistance. Dependencies include the ZBase framework.

```lua
-- lua/zbase/entities/flying_npc/shared.lua
local NPC = FindZBaseTable(debug.getinfo(1,'S'))

NPC.Class = "npc_zbase_snpc"
NPC.Name = "Flying Monster"
NPC.Category = "My Addon: Aerial"
NPC.Inherit = "npc_zbase"

-- Flying SNPC type
NPC.SNPCType = ZBASE_SNPCTYPE_FLY

-- Flight configuration
NPC.Fly_DistanceFromGround = 150      -- Maintain this height
NPC.Fly_DistanceFromGround_IgnoreWhenMelee = true  -- Dive for melee
NPC.Fly_FaceEnemy = true              -- Always face enemy
NPC.Fly_MoveSpeed = 300               -- Base flight speed
NPC.Fly_Accelerate = 20               -- Acceleration rate
NPC.Fly_Decelerate = 15               -- Deceleration rate
NPC.Fly_GravGunPuntForceMult = 0.5    -- Gravity gun resistance

-- lua/zbase/entities/flying_npc/init.lua
local NPC = FindZBaseTable(debug.getinfo(1,'S'))

-- Custom flight velocity calculation
function NPC:SNPCFlyVelocity(destDirection, currentSpeed)
    local enemy = self:GetEnemy()

    -- Strafe around enemy while attacking
    if IsValid(enemy) and self:SeeEne() then
        local toEnemy = (enemy:GetPos() - self:GetPos()):GetNormalized()
        local strafeDir = toEnemy:Cross(Vector(0, 0, 1))

        -- Alternate strafe direction
        if CurTime() % 4 < 2 then
            strafeDir = -strafeDir
        end

        -- Mix destination with strafe
        destDirection = (destDirection + strafeDir * 0.5):GetNormalized()
    end

    -- Bobbing motion
    local bob = math.sin(CurTime() * 2) * 20

    return destDirection * currentSpeed + Vector(0, 0, bob)
end

-- SNPC schedule for flying NPCs
function NPC:SNPCSelectSchedule(iNPCState)
    local enemy = self:GetEnemy()

    if IsValid(enemy) then
        -- Use aerial chase schedule
        return ZSched.CombatChase
    else
        -- Hover in place
        return SCHED_IDLE_STAND
    end
end

```

--------------------------------

### Create Basic ZBase NPC Configuration (Lua)

Source: https://context7.com/zippy6666/zbase2/llms.txt

Defines the properties and configuration for a basic ZBase NPC. It specifies the base engine class, display name, spawn menu category, weapons, inheritance, author, combat stats, faction, movement capabilities, and item drops on death. This configuration is stored in a shared.lua file.

```lua
-- lua/zbase/entities/my_custom_npc/shared.lua
local NPC = FindZBaseTable(debug.getinfo(1,'S'))

-- Basic NPC configuration
NPC.Class = "npc_combine_s"  -- Base engine class to use
NPC.Name = "Custom Soldier"   -- Display name in spawn menu
NPC.Category = "My Addon: Soldiers"  -- Spawn menu category
NPC.Weapons = {"weapon_ar2", "weapon_smg1"}  -- Random weapon selection
NPC.Inherit = "npc_zbase"    -- Always inherit from npc_zbase
NPC.Author = "Your Name"

-- Health and combat
NPC.StartHealth = 100
NPC.SightDistance = 4096
NPC.SightAngle = 180
NPC.WeaponProficiency = WEAPON_PROFICIENCY_VERY_GOOD
NPC.MaxShootDistance = 3000

-- Faction system (NPCs with same faction are allies)
-- Built-in: "combine", "ally", "zombie", "antlion", "none", "neutral"
NPC.ZBaseStartFaction = "combine"

-- Movement
NPC.CanPatrol = true
NPC.CanJump = true
NPC.MoveSpeedMultiplier = 1.0

-- Item drops on death
NPC.ItemDrops = {
    ["item_healthvial"] = {chance=2, max=1},  -- 1/2 chance, max 1
    ["item_ammo_smg1"] = {chance=3, max=2}    -- 1/3 chance, max 2
}
NPC.ItemDrops_TotalMax = 3

```

--------------------------------

### Spawning ZBase NPCs (Lua)

Source: https://context7.com/zippy6666/zbase2/llms.txt

Programmatically spawns a ZBase NPC with specified class, position, orientation, weapon, and spawn flags. Includes basic post-spawn manipulation like setting angles and factions.

```lua
-- Spawning ZBase NPCs programmatically
local npc = ZBaseSpawnZBaseNPC(
    "zb_combine_soldier",           -- ZBase NPC class
    Vector(0, 0, 100),              -- Position
    Vector(0, 0, 1),                -- Surface normal
    "default",                      -- Weapon ("default" uses NPC's defined weapons)
    bit.bor(SF_NPC_LONG_RANGE, SF_NPC_FADE_CORPSE)  -- Spawn flags
)

if IsValid(npc) then
    npc:SetAngles(Angle(0, 180, 0))
    ZBaseSetFaction(npc, "ally")
end
```

--------------------------------

### Configure NPC Armor and Damage Scaling (Lua)

Source: https://context7.com/zippy6666/zbase2/llms.txt

Defines NPC armor properties like hitgroup armor, penetration chance, and damage scaling for various damage types. Includes custom logic for headshots, fall damage immunity, and armor hit behavior.

```lua
-- lua/zbase/entities/armored_npc/shared.lua
local NPC = FindZBaseTable(debug.getinfo(1,'S'))

-- Armor configuration by hitgroup
NPC.HasArmor = {
    [HITGROUP_GENERIC] = false,
    [HITGROUP_HEAD] = true,     -- Armored helmet
    [HITGROUP_CHEST] = true,    -- Armored chest
    [HITGROUP_STOMACH] = true,
    [HITGROUP_LEFTARM] = false,
    [HITGROUP_RIGHTARM] = false,
    [HITGROUP_LEFTLEG] = false,
    [HITGROUP_RIGHTLEG] = false,
    [HITGROUP_GEAR] = false,
}

NPC.ArmorPenChance = 3           -- 1/3 chance to penetrate
NPC.ArmorAlwaysPenDamage = 50    -- Always pen if damage > 50
NPC.ArmorPenDamageMult = 1.5     -- Damage multiplier on penetration
NPC.ArmorHitSpark = true         -- Spark effect on armor hit

-- Damage type scaling
NPC.DamageScaling = {
    [DMG_BULLET] = 0.8,     -- 20% bullet resistance
    [DMG_BLAST] = 1.5,      -- 50% extra blast damage
    [DMG_BURN] = 0.5,       -- Fire resistance
    [DMG_SHOCK] = 2.0,      -- Weak to electricity
}
NPC.PhysDamageScale = 0.5  -- Reduced prop damage

-- Custom damage handling
function NPC:CustomTakeDamage(dmginfo, hitGroup)
    -- Headshot multiplier
    if hitGroup == HITGROUP_HEAD then
        dmginfo:ScaleDamage(2.0)
    end

    -- Immune to fall damage
    if dmginfo:IsDamageType(DMG_FALL) then
        dmginfo:ScaleDamage(0)
    end
end

-- Custom armor hit behavior
function NPC:HitArmor(dmginfo, hitGroup)
    if not (dmginfo:IsDamageType(DMG_BULLET) or dmginfo:IsDamageType(DMG_BUCKSHOT)) then
        return
    end

    -- Always penetrate chest armor from behind
    local attackDir = dmginfo:GetDamageForce():GetNormalized()
    if attackDir:Dot(self:GetForward()) > 0.5 and hitGroup == HITGROUP_CHEST then
        dmginfo:ScaleDamage(2)  -- Backstab bonus
        return
    end

    -- Standard armor deflect with spark
    if math.random(1, self.ArmorPenChance) ~= 1 then
        self:EmitSound("ZBase.Ricochet")
        dmginfo:ScaleDamage(0)
    end
end

```

--------------------------------

### Configure NPC Death, Ragdoll, and Gibbing Behavior (Lua)

Source: https://context7.com/zippy6666/zbase2/llms.txt

This snippet configures how NPCs die, including death animations, ragdoll physics, and gibbing behavior. It allows customization of animation choices, ragdoll properties, and conditions for gibbing based on damage type and amount. Dependencies include the ZBase framework.

```lua
-- lua/zbase/entities/dying_npc/shared.lua
local NPC = FindZBaseTable(debug.getinfo(1,'S'))

-- Death animations
NPC.DeathAnimations = {ACT_DIESIMPLE, ACT_DIEBACKWARD, ACT_DIEFORWARD}
NPC.DeathAnimationSpeed = 1.0
NPC.DeathAnimationChance = 2  -- 1/2 chance for death animation
NPC.DeathAnimation_StopAttackingMe = true  -- NPCs stop attacking during death anim
NPC.DeathAnimationDuration = 1.5  -- false = use animation length

-- Ragdoll settings
NPC.HasDeathRagdoll = true
NPC.RagdollApplyForce = true
NPC.RagdollModel = ""  -- Empty = use NPC's model
NPC.DissolveRagdoll = true  -- Dissolve on dissolve damage
NPC.AddNoDissolveFlag = true  -- Prevent instant AR2 dissolve

-- lua/zbase/entities/dying_npc/init.lua
local NPC = FindZBaseTable(debug.getinfo(1,'S'))

-- Called to determine if NPC should gib
function NPC:ShouldGib(dmginfo, hitGroup)
    -- Gib on explosive damage over threshold
    if dmginfo:GetDamage() > 100 and dmginfo:IsExplosionDamage() then
        -- Spawn gibs
        self:CreateGib("models/gibs/antlion_gib_small_1.mdl", {
            offset = Vector(0, 0, 40),
            DontBleed = false
        })
        self:CreateGib("models/gibs/antlion_gib_small_2.mdl", {
            offset = Vector(10, 0, 30)
        })
        self:CreateGib("models/gibs/antlion_gib_small_3.mdl", {
            offset = Vector(-10, 0, 30)
        })

        -- Explosion effect
        local effectdata = EffectData()
        effectdata:SetOrigin(self:WorldSpaceCenter())
        util.Effect("BloodImpact", effectdata)

        return true  -- Return true to skip ragdoll
    end

    return false  -- Normal death
end

-- Called after death
function NPC:CustomOnDeath(dmginfo, hitGroup, ragdoll)
    if IsValid(ragdoll) then
        -- Set ragdoll on fire if killed by fire
        if dmginfo:IsDamageType(DMG_BURN) then
            ragdoll:Ignite(10, 0)
        end

        -- Apply extra force
        for i = 0, ragdoll:GetPhysicsObjectCount() - 1 do
            local phys = ragdoll:GetPhysicsObjectNum(i)
            if IsValid(phys) then
                phys:ApplyForceCenter(dmginfo:GetDamageForce() * 2)
            end
        end
    end
end

```

--------------------------------

### Create Custom SNPC Configuration (Lua)

Source: https://context7.com/zippy6666/zbase2/llms.txt

Configures a fully custom Scripted NPC (SNPC) using the `npc_zbase_snpc` class. This allows for unique AI and behavior control. It includes settings for SNPC type (walk/fly), turning speed, NPC classification, behavior when unable to reach an enemy, chase distance, model, health, and pose parameters for aiming.

```lua
-- lua/zbase/entities/my_snpc/shared.lua
local NPC = FindZBaseTable(debug.getinfo(1,'S'))

NPC.Class = "npc_zbase_snpc"  -- Use SNPC base class
NPC.Name = "Custom Monster"
NPC.Category = "My Addon: Monsters"
NPC.Inherit = "npc_zbase"
NPC.Author = "Your Name"

-- SNPC-specific settings
NPC.SNPCType = ZBASE_SNPCTYPE_WALK  -- or ZBASE_SNPCTYPE_FLY
NPC.m_fMaxYawSpeed = 15  -- Turn speed
NPC.m_iClass = CLASS_ZOMBIE  -- NPC classification

-- Can't reach enemy behavior
NPC.CantReachEnemyBehaviour = ZBASE_CANTREACHENEMY_HIDE
-- Options: ZBASE_CANTREACHENEMY_HIDE, ZBASE_CANTREACHENEMY_FACE

NPC.ChaseMinDistance = 50  -- Stop chasing when this close

-- Model and appearance
NPC.Models = {"models/zombie/fast.mdl"}
NPC.StartHealth = 150

-- Enable pose parameters for aiming
NPC.LookPoseParams = true
NPC.LookPoseParamNames = {
    Pitch = {"aim_pitch"},
    Yaw = {"aim_yaw"}
}

```

--------------------------------

### Visual Effects: Muzzle Flashes and Lights (Lua)

Source: https://context7.com/zippy6666/zbase2/llms.txt

Functions to create muzzle flashes at an entity's attachment point or a specific position and angle. Also includes a function to create a dynamic light source, useful for effects like explosions or weapon fire.

```lua
-- Visual effects
ZBaseMuzzleFlash(entity, 1, attachmentNum)  -- 1=normal, 5=AR2, 7=large
ZBaseMuzzleFlashAtPos(pos, ang, 5)  -- Muzzle flash at position
ZBaseMuzzleLight(pos, 2, 256, "255 150 50", 0.1)  -- Dynamic light
```

--------------------------------

### Caption Display (Lua)

Source: https://context7.com/zippy6666/zbase2/llms.txt

Adds a text caption to the screen, optionally tied to a specific entity's position. Useful for displaying game messages, objective updates, or NPC dialogue.

```lua
-- Captions
ZBaseAddCaption(nil, "Enemy spotted!", 2, 75, npc:GetPos())
```

--------------------------------

### NPC Ally Detection and Interaction (Lua)

Source: https://context7.com/zippy6666/zbase2/llms.txt

Functions to find nearby allies, the nearest ally, and iterate through allies within a radius. Also includes a function to check if a given entity is an ally.

```lua
-- Ally detection
function NPC:ExampleAllyFunctions()
    -- Get all allies within radius
    local allies = self:GetNearbyAllies(1000)
    for _, ally in ipairs(allies) do
        ally:SetSchedule(SCHED_TAKE_COVER_FROM_ENEMY)
    end

    -- Get nearest ally
    local nearestAlly = self:GetNearestAlly(500)
    if IsValid(nearestAlly) then
        -- Heal nearest ally
    end

    -- Optimized ally iteration
    self:IterateNearbyAllies(1000, function(ally)
        ally:SetNPCState(NPC_STATE_ALERT)
    end)

    -- Check if entity is allied
    if self:IsAlly(someEntity) then
        print("This is an ally!")
    end
end
```

--------------------------------

### NPC Animation Control and Checks (Lua)

Source: https://context7.com/zippy6666/zbase2/llms.txt

Functions for playing, stopping, and checking NPC animations. Includes options for speed, duration, transitions, and callbacks. Also covers distance checks, facing checks, and visibility/movement status.

```lua
-- Animation playback with options
function NPC:ExampleAnimations()
    -- Basic animation
    self:PlayAnimation(ACT_MELEE_ATTACK1, true)  -- true = face enemy

    -- Animation with options
    self:PlayAnimation("attack_combo", false, {
        speedMult = 1.5,           -- Animation speed multiplier
        duration = 2.0,            -- Force duration
        isGesture = true,          -- Play as gesture layer
        face = targetEntity,       -- Face this entity/position
        faceSpeed = 10,            -- Face turn speed
        noTransitions = true,      -- Skip transition animations
        onFinishFunc = function()  -- Callback when done
            print("Animation finished!")
        end
    })

    -- Stop current animation
    self:StopCurrentAnimation()

    -- Check if busy
    if self:BusyPlayingAnimation() then
        return
    end
end

-- Distance and facing checks
function NPC:ExampleChecks()
    local enemy = self:GetEnemy()

    -- Check if enemy is within range
    if self:ZBaseDist(enemy, {within=500}) then
        print("Enemy is close!")
    end

    -- Check if enemy is at least X away but within Y
    if self:ZBaseDist(enemy, {within=1000, away=200}) then
        print("Enemy is in attack range")
    end

    -- Check if facing enemy (22.5 degree tolerance default)
    if self:IsFacing(enemy) then
        print("Facing the enemy")
    end

    -- Check with custom angle tolerance
    if self:IsFacing(enemy, 45) then
        print("Roughly facing enemy")
    end

    -- Check visibility (optimized)
    if self:SeeEne() then
        print("Can see enemy")
    end

    -- Check if moving (optimized)
    if self:IsMoving_Cheap() then
        print("Currently moving")
    end
end
```

--------------------------------

### NPC Movement without Nav Mesh (Lua)

Source: https://context7.com/zippy6666/zbase2/llms.txt

Provides functions for moving NPCs to specific positions, including jumping, and cancelling movement. Includes a check to see if an NPC is currently actively moving.

```lua
-- NPC movement (works without nav mesh)
ZBaseMove(npc, Vector(500, 200, 0))  -- Move to position
ZBaseMoveJump(npc, Vector(100, 100, 200))  -- Jump to position
ZBaseMoveEnd(npc)  -- Cancel movement
if ZBaseMoveIsActive(npc) then print("Still moving") end
```

--------------------------------

### NPC Utility Functions

Source: https://context7.com/zippy6666/zbase2/llms.txt

Functions for controlling NPC animations, performing distance and facing checks, and managing ally interactions.

```APIDOC
## NPC Utility Functions

### Description
Provides functions for NPC animation playback, distance and facing checks, and ally detection.

### Methods

#### `NPC:PlayAnimation(animation_name, face_enemy, options)`
Plays an animation on the NPC.

- **animation_name** (string | number) - The name or ACT constant of the animation.
- **face_enemy** (boolean) - If true, the NPC will face the enemy.
- **options** (table, optional) - A table of animation options:
    - **speedMult** (number) - Animation speed multiplier.
    - **duration** (number) - Forced duration of the animation.
    - **isGesture** (boolean) - Play as a gesture layer.
    - **face** (entity | vector) - Entity or position to face.
    - **faceSpeed** (number) - Speed at which the NPC turns to face.
    - **noTransitions** (boolean) - Skip transition animations.
    - **onFinishFunc** (function) - Callback function when the animation finishes.

#### `NPC:StopCurrentAnimation()`
Stops the currently playing animation.

#### `NPC:BusyPlayingAnimation()`
Returns true if the NPC is currently playing an animation.

#### `NPC:GetEnemy()`
Returns the NPC's current enemy entity.

#### `NPC:ZBaseDist(entity, options)`
Checks the distance to an entity with specified options.

- **entity** (entity) - The target entity.
- **options** (table) - Distance check options:
    - **within** (number) - Maximum distance.
    - **away** (number) - Minimum distance.

#### `NPC:IsFacing(entity, angle_tolerance)`
Checks if the NPC is facing the target entity.

- **entity** (entity) - The target entity.
- **angle_tolerance** (number, optional) - Custom angle tolerance in degrees (default is 22.5).

#### `NPC:SeeEne()`
Optimized check to see if the NPC can see its enemy.

#### `NPC:IsMoving_Cheap()`
Optimized check to see if the NPC is currently moving.

#### `NPC:GetNearbyAllies(radius)`
Returns a table of all allies within the specified radius.

- **radius** (number) - The search radius.

#### `NPC:GetNearestAlly(radius)`
Returns the nearest ally within the specified radius, or nil if none are found.

- **radius** (number) - The search radius.

#### `NPC:IterateNearbyAllies(radius, callback)`
Iterates through all nearby allies and calls the callback function for each.

- **radius** (number) - The search radius.
- **callback** (function) - The function to call for each ally. It receives the ally entity as an argument.

#### `NPC:IsAlly(entity)`
Checks if the given entity is an ally.

- **entity** (entity) - The entity to check.

### Request Example (Animation)
```lua
-- Basic animation
npc:PlayAnimation(ACT_MELEE_ATTACK1, true)

-- Animation with options
pc:PlayAnimation("attack_combo", false, {
    speedMult = 1.5,
    duration = 2.0,
    isGesture = true,
    face = targetEntity,
    faceSpeed = 10,
    noTransitions = true,
    onFinishFunc = function()
        print("Animation finished!")
    end
})

-- Stop current animation
pc:StopCurrentAnimation()

-- Check if busy
if npc:BusyPlayingAnimation() then
    return
end
```

### Request Example (Checks)
```lua
local enemy = npc:GetEnemy()

-- Check if enemy is within range
if npc:ZBaseDist(enemy, {within=500}) then
    print("Enemy is close!")
end

-- Check if enemy is at least X away but within Y
if npc:ZBaseDist(enemy, {within=1000, away=200}) then
    print("Enemy is in attack range")
end

-- Check if facing enemy (22.5 degree tolerance default)
if npc:IsFacing(enemy) then
    print("Facing the enemy")
end

-- Check with custom angle tolerance
if npc:IsFacing(enemy, 45) then
    print("Roughly facing enemy")
end

-- Check visibility (optimized)
if npc:SeeEne() then
    print("Can see enemy")
end

-- Check if moving (optimized)
if npc:IsMoving_Cheap() then
    print("Currently moving")
end
```

### Request Example (Ally Functions)
```lua
-- Get all allies within radius
local allies = npc:GetNearbyAllies(1000)
for _, ally in ipairs(allies) do
    ally:SetSchedule(SCHED_TAKE_COVER_FROM_ENEMY)
end

-- Get nearest ally
local nearestAlly = npc:GetNearestAlly(500)
if IsValid(nearestAlly) then
    -- Heal nearest ally
end

-- Optimized ally iteration
pc:IterateNearbyAllies(1000, function(ally)
    ally:SetNPCState(NPC_STATE_ALERT)
end)

-- Check if entity is allied
if npc:IsAlly(someEntity) then
    print("This is an ally!")
end
```

### Response (General)
- **boolean**: Returns true or false for check functions.
- **entity**: Returns an entity for `GetEnemy`, `GetNearestAlly`.
- **table**: Returns a table of entities for `GetNearbyAllies`.
- **nil**: Returned when no entity is found or an operation fails.
```

--------------------------------

### Create Custom Projectile Entity with ZBase

Source: https://context7.com/zippy6666/zbase2/llms.txt

Defines a custom projectile entity inheriting from 'zb_projectile'. It allows for customizable models, physics properties, hit behaviors, and post-spawn effects like glowing lights and particle trails. The 'OnHit' and 'OnKill' functions handle interactions with entities and the environment, including damage, sound, and visual effects.

```lua
-- lua/entities/my_projectile.lua
AddCSLuaFile()

ENT.Base = "zb_projectile"
ENT.Type = "anim"
ENT.PrintName = "Energy Ball"
ENT.IsZBaseProjectile = true

-- Projectile configuration
ENT.Model = "models/effects/combineball.mdl"
ENT.Invisible = false
ENT.StartHealth = false        -- false = indestructible
ENT.Gravity = false            -- Float in air
ENT.GravityGun_Pickup = true
ENT.GravityGun_Punt = true

-- Direct hit damage
ENT.OnHitDamage = 25
ENT.OnHitDamageType = DMG_SHOCK
ENT.Damage_Disorient = true    -- Deafen players on hit

-- Called after projectile spawns
function ENT:PostInit()
    if SERVER then
        -- Add glowing effect
        local glow = ents.Create("light_dynamic")
        glow:SetKeyValue("brightness", "3")
        glow:SetKeyValue("distance", "300")
        glow:SetPos(self:WorldSpaceCenter())
        glow:SetParent(self)
        glow:Fire("Color", "100 150 255")
        glow:Spawn()
        glow:Activate()
        glow:Fire("TurnOn", "", 0)
        self:DeleteOnRemove(glow)

        -- Trail particle
        ParticleEffectAttach("vortigaunt_beam", PATTACH_ABSORIGIN_FOLLOW, self, 0)
    end
end

-- Called when projectile hits something
function ENT:OnHit(ent, data)
    -- Bounce off world geometry
    if data.HitEntity == game.GetWorld() then
        -- Let physics handle bounce
        return
    end

    -- Die on entity hit
    self:Die()
end

-- Called when projectile is destroyed
function ENT:OnKill(dmginfo)
    -- Explosion damage
    self:ProjectileBlastDamage(50, DMG_SHOCK, 200, 500)

    -- Effects
    self:EmitSound("weapons/physcannon/energy_disintegrate5.wav")
    ParticleEffect("cball_explode", self:WorldSpaceCenter(), AngleRand())
    util.ScreenShake(self:WorldSpaceCenter(), 5, 200, 0.5, 300)
end

-- Physics object setup
function ENT:PhysInit(phys)
    phys:SetMass(1)
    phys:SetDamping(0, 0)
    phys:SetMaterial("gmod_bouncy")
end

```

--------------------------------

### Configure Range Attacks in Lua

Source: https://context7.com/zippy6666/zbase2/llms.txt

Configures the base range attack system for ZBase NPCs, enabling projectile-based attacks. It allows customization of attack animations, distance, cooldown, and projectile properties like delay, speed, and inaccuracy. Includes an option for custom projectile spawning and callbacks for attack initiation.

```lua
-- lua/zbase/entities/ranged_npc/init.lua
local NPC = FindZBaseTable(debug.getinfo(1,'S'))

-- Enable base range attack system
NPC.BaseRangeAttack = true

-- Range attack configuration
NPC.RangeAttackAnimations = {ACT_RANGE_ATTACK1}
NPC.RangeAttackAnimationSpeed = 1.0
NPC.RangeAttackDistance = {200, 1500}  -- Min/max attack distance
NPC.RangeAttackCooldown = {2, 4}       -- Cooldown range
NPC.RangeAttackFaceEnemy = true
NPC.RangeAttackTurnSpeed = 12
NPC.RangeAttackSuppressEnemy = true    -- Fire at last known position

-- Projectile configuration
NPC.RangeProjectile_Delay = 0.8              -- Delay before projectile spawns
NPC.RangeProjectile_Attachment = "muzzle"    -- Spawn attachment point
NPC.RangeProjectile_Speed = 1500
NPC.RangeProjectile_Inaccuracy = 2           -- Spread (0 = perfect)
NPC.RangeProjectile_Offset = {forward=10, up=0, right=0}

-- Custom projectile spawning (override default behavior)
function NPC:RangeAttackProjectile()
    local startPos = self:Projectile_SpawnPos()

    -- Create custom projectile
    local proj = ents.Create("zb_projectile")
    proj:SetPos(startPos)
    proj:SetAngles(self:GetAngles())
    proj:SetOwner(self)
    proj:Spawn()

    -- Apply velocity
    local velocity = self:RangeAttackProjectileVelocity()
    local phys = proj:GetPhysicsObject()
    if IsValid(phys) then
        phys:SetVelocity(velocity)
    else
        proj:SetVelocity(velocity)
    end

    -- Play muzzle flash effect
    local attNum = self:LookupAttachment("muzzle")
    ZBaseMuzzleFlash(self, 5, attNum)
end

-- Callback when range attack starts
function NPC:OnRangeAttack()
    self:EmitSound("weapons/ar2/fire1.wav")
end
```
Tokens:
Raw