### Complete Possession Setup for Nextbot

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/api-reference/possession-system.md

This snippet demonstrates a full possession setup for a custom Nextbot entity. It includes enabling possession, setting a custom prompt, defining a lock-on bone, and implementing core possession functions like view control and target locking.

```lua
-- In Nextbot entity file
ENT.Type = "nextbot"
ENT.Base = "drgbase_nextbot"
ENT.PrintName = "Controlled Bot"
ENT.PossessionEnabled = true
ENT.PossessionPrompt = true
ENT.DrGBase_LockOnBone = "head"

function ENT:Initialize()
    self:SetModel("models/custom.mdl")
    self._viewMode = 0
    self._lockedTarget = NULL
end

function ENT:PossessorView()
    if self._viewMode == 0 then
        -- First person (eyes)
        return self:GetPos() + self:GetUp() * 60
    else
        -- Third person
        return self:GetPos() + self:GetUp() * 80 - self:GetForward() * 100
    end
end

function ENT:CycleViewPresets()
    self._viewMode = (self._viewMode + 1) % 2
end

function ENT:PossessionGetLockedOn()
    if IsValid(self._lockedTarget) then
        return self._lockedTarget
    end
    return NULL
end

function ENT:PossessionFetchLockOn()
    local closest = NULL
    local closestDist = 3000
    for _, ent in ipairs(ents.GetAll()) do
        if DrGBase.IsTarget(ent) then
            local dist = self:Distance(ent)
            if dist < closestDist then
                closest = ent
                closestDist = dist
            end
        end
    end
    return closest
end

function ENT:PossessionLockOn(ent)
    self._lockedTarget = ent
end

function ENT:IsPossessionEnabled()
    return true  -- Always allowed
end
```

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

### Example Usage of Player.DrG_NetCallback

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/api-reference/player-meta.md

This example demonstrates how to use Player.DrG_NetCallback to request player data. It specifies the callback name 'get_player_data', provides a function to print the response, and includes an extra argument.

```lua
ply:DrG_NetCallback("get_player_data", function(response)
    print("Got response: " .. response)
end, extra_arg)
```

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

### Get Luminosity

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/api-reference/player-meta.md

Gets the player's ambient light level. On the server, it returns a stored value; on the client, it calculates from the eye position. Includes an example for checking darkness.

```lua
function Player:DrG_Luminosity()
local brightness = ply:DrG_Luminosity()
if brightness < 0.3 then
    print("Player in darkness")
end
```

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

### Network Callback Example

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/README.md

Demonstrates how to define and use network callbacks for custom data synchronization between server and client using `net.DrG_DefineCallback` and `net.DrG_UseCallback`.

```APIDOC
## Network Callback Example

### Description
This example shows how to set up and use custom network callbacks for sending and receiving data between the server and client. `net.DrG_DefineCallback` is used on the server to register a callback, and `net.DrG_UseCallback` is used on either side to invoke a registered callback and receive its return value.

### Method
- `net.DrG_DefineCallback(name, callbackFunction)`
- `net.DrG_UseCallback(name, callbackFunction, ...)`

### Parameters
#### `net.DrG_DefineCallback` (Server-side)
- **name** (string) - Required - The unique name for the callback.
- **callbackFunction** (function) - Required - The function to execute when the callback is invoked. It receives the invoking player as the first argument, followed by any arguments passed via `net.DrG_UseCallback`.

#### `net.DrG_UseCallback` (Client or Server-side)
- **name** (string) - Required - The name of the callback to invoke.
- **callbackFunction** (function) - Required - A function to handle the return value from the server-side callback.
- **...** (any) - Optional - Arguments to pass to the server-side callback function.

### Request Example
```lua
-- Server: Define callback
net.DrG_DefineCallback("GetPlayerPos", function(ply, target)
    if IsValid(target) then
        return target:GetPos()
    end
end)

-- Client: Request data
net.DrG_UseCallback("GetPlayerPos", function(pos)
    print("Target at: " .. tostring(pos))
end, targetEnt)
```
```

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

### Network Callback Example

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/README.md

Demonstrates defining a server-side network callback to retrieve player position and using it from the client to request and print the target's position.

```lua
-- Server: Define callback
net.DrG_DefineCallback("GetPlayerPos", function(ply, target)
    if IsValid(target) then
        return target:GetPos()
    end
end)

-- Client: Request data
net.DrG_UseCallback("GetPlayerPos", function(pos)
    print("Target at: " .. tostring(pos))
end, targetEnt)
```

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

### Nextbot Entity Configuration Example

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/configuration.md

This Lua snippet demonstrates how to configure a Nextbot entity by setting its properties like PrintName, Category, Models, and possession-related options.

```lua
ENT.Type = "nextbot"
ENT.Base = "drgbase_nextbot"
ENT.PrintName = "Combine Soldier"
ENT.Category = "DrGBase"
ENT.Spawnable = true
ENT.AdminOnly = false

ENT.Models = {
    "models/combine_soldier.mdl",
    "models/combine_soldier_prisonguard.mdl"
}
ENT.OnSpawnSounds = {"npc/combine_soldier/vo/reinforcement.wav"}
ENT.OnDeathSounds = {"npc/combine_soldier/pain1.wav"}

ENT.PossessionEnabled = true
ENT.PossessionPrompt = true
ENT.UseWeapons = true
ENT.AcceptPlayerWeapons = true
ENT.DrGBase_LockOnBone = "head"
```

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

### Selection System: Get Selected Entities

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/README.md

Iterates through entities selected by the player for a specific purpose, like 'paint'.

```lua
-- Get selected entities
for ent in ply:DrG_SelectedEntities("paint") do
    -- Process entity
end
```

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

### Initiate Nextbot Possession

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/api-reference/possession-system.md

Call this function to start the possession of a Nextbot by a player. This function is typically called from a context menu. It handles various side effects like disabling player movement and blocking damage.

```lua
function ENT:Possess(ply)
-- ...
end

-- Example usage:
local success = nextbot:Possess(ply)
if success then
    print(ply:GetName() .. " possessed " .. nextbot:GetClass())
end
```

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

### Visualize Debug Traces and Trajectories

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/configuration.md

Provides examples for enabling and visualizing debug traces and ballistic trajectories using their respective ConVars. The values set determine the duration for which these visualizations will be active.

```lua
-- Enable trace visualization for 10 seconds
RunConsoleCommand("drgbase_debug_traces", "10")

-- Show ballistic prediction lines
RunConsoleCommand("drgbase_debug_trajectories", "5")
```

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

### Get linked double door

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/api-reference/misc-utilities.md

Retrieves the partner door if the current door entity is part of a double door setup. Returns NULL if the door is single.

```lua
function Door:GetDouble()

-- Returns: Entity - Partner door, or NULL if single door
```

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

### Get Factions

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/api-reference/player-meta.md

Retrieves an array of all faction names the player is currently a member of. Includes an example of iterating through the returned factions.

```lua
function Player:DrG_GetFactions()
local factions = ply:DrG_GetFactions()
for i, faction in ipairs(factions) do
    print(faction)
end
```

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

### Nextbot Template Configuration

Source: https://github.com/dragoteryx/drgbase/wiki/Nextbot-template-file

This is the main configuration table for a Nextbot. It defines various properties such as appearance, stats, AI behavior, locomotion, animations, and more. Ensure DrGBase is installed before using this template.

```lua
if not DrGBase then return end -- return if DrGBase isn't installed
ENT.Base = "drgbase_nextbot" -- DO NOT TOUCH (obviously)

-- Misc --
ENT.PrintName = "Template"
ENT.Category = "Other"
ENT.Models = {"models/Kleiner.mdl"}
ENT.Skins = {0}
ENT.ModelScale = 1
ENT.CollisionBounds = Vector(10, 10, 72)
ENT.BloodColor = BLOOD_COLOR_RED
ENT.RagdollOnDeath = true

-- Stats --
ENT.SpawnHealth = 100
ENT.HealthRegen = 0
ENT.MinPhysDamage = 10
ENT.MinFallDamage = 10

-- Sounds --
ENT.OnSpawnSounds = {}
ENT.OnIdleSounds = {}
ENT.IdleSoundDelay = 2
ENT.ClientIdleSounds = false
ENT.OnDamageSounds = {}
ENT.DamageSoundDelay = 0.25
ENT.OnDeathSounds = {}
ENT.OnDownedSounds = {}
ENT.Footsteps = {}

-- AI --
ENT.Omniscient = false
ENT.SpotDuration = 30
ENT.RangeAttackRange = 0
ENT.MeleeAttackRange = 50
ENT.ReachEnemyRange = 50
ENT.AvoidEnemyRange = 0

-- Relationships --
ENT.Factions = {}
ENT.Frightening = false
ENT.AllyDamageTolerance = 0.33
ENT.AfraidDamageTolerance = 0.33
ENT.NeutralDamageTolerance = 0.33

-- Locomotion --
ENT.Acceleration = 1000
ENT.Deceleration = 1000
ENT.JumpHeight = 50
ENT.StepHeight = 20
ENT.MaxYawRate = 250
ENT.DeathDropHeight = 200

-- Animations --
ENT.WalkAnimation = ACT_WALK
ENT.WalkAnimRate = 1
ENT.RunAnimation = ACT_RUN
ENT.RunAnimRate = 1
ENT.IdleAnimation = ACT_IDLE
ENT.IdleAnimRate = 1
ENT.JumpAnimation = ACT_JUMP
ENT.JumpAnimRate = 1

-- Movements --
ENT.UseWalkframes = false
ENT.WalkSpeed = 100
ENT.RunSpeed = 200

-- Climbing --
ENT.ClimbLedges = false
ENT.ClimbLedgesMaxHeight = math.huge
ENT.ClimbLedgesMinHeight = 0
ENT.LedgeDetectionDistance = 20
ENT.ClimbProps = false
ENT.ClimbLadders = false
ENT.ClimbLaddersUp = true
ENT.LaddersUpDistance = 20
ENT.ClimbLaddersUpMaxHeight = math.huge
ENT.ClimbLaddersUpMinHeight = 0
ENT.ClimbLaddersDown = false
ENT.LaddersDownDistance = 20
ENT.ClimbLaddersDownMaxHeight = math.huge
ENT.ClimbLaddersDownMinHeight = 0
ENT.ClimbSpeed = 60
ENT.ClimbUpAnimation = ACT_CLIMB_UP
ENT.ClimbDownAnimation = ACT_CLIMB_DOWN
ENT.ClimbAnimRate = 1
ENT.ClimbOffset = Vector(0, 0, 0)

-- Detection --
ENT.EyeBone = ""
ENT.EyeOffset = Vector(0, 0, 0)
ENT.EyeAngle = Angle(0, 0, 0)
ENT.SightFOV = 150
ENT.SightRange = 15000
ENT.MinLuminosity = 0
ENT.MaxLuminosity = 1
ENT.HearingCoefficient = 1

-- Weapons --
ENT.UseWeapons = false
ENT.Weapons = {}
ENT.WeaponAccuracy = 1
ENT.WeaponAttachment = "Anim_Attachment_RH"
ENT.DropWeaponOnDeath = false
ENT.AcceptPlayerWeapons = true

-- Possession --
ENT.PossessionEnabled = false
ENT.PossessionPrompt = true
ENT.PossessionCrosshair = false
ENT.PossessionMovement = POSSESSION_MOVE_1DIR
ENT.PossessionViews = {}
ENT.PossessionBinds = {}
```

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

### Patrol Between Nodes using Nodegraph

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/api-reference/nodegraph-navigation.md

An example of an entity patrolling between nodes in the navigation graph. It collects nearby nodes and moves between them sequentially.

```lua
function ENT:Initialize()
    self._patrolNodes = {}
    local graph = DrGBase.GetNodegraph()
    
    -- Collect nodes near spawn point
    local spawnPos = self:GetPos()
    for i, node in ipairs(graph) do
        if node:Distance(spawnPos) < 5000 then
            table.insert(self._patrolNodes, node)
        end
    end
    
    self._patrolIndex = 1
end

function ENT:Think()
    if #self._patrolNodes == 0 then return end
    
    local current = self._patrolNodes[self._patrolIndex]
    self:GetMovement():SetGoalPosition(current:GetPos())
    
    if self:GetPos():Distance(current:GetPos()) < 200 then
        self._patrolIndex = (self._patrolIndex % #self._patrolNodes) + 1
    end
end
```

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

### Visualize Ballistic Trajectory Path

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/api-reference/misc-utilities.md

Visualizes a ballistic trajectory path. Requires start position, direction, duration, and a color callback function. Optional parameters include depth testing and range data.

```lua
function debugoverlay.DrG_Trajectory(
    startPos, direction, duration, colorCallback, 
    noDepthTest, rangeData
)
```

```lua
{
    from = number, 
    to = number, 
    ballistic = bool 
}
```

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

### Add Undo Entry

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/api-reference/player-meta.md

Creates an undo entry for a specific entity, allowing for custom undo text. Includes an example of creating a physics prop and adding an undo entry for its spawn.

```lua
function Player:DrG_AddUndo(ent, type, text)
local prop = ents.Create("prop_physics")
prop:Spawn()
ply:DrG_AddUndo(prop, "SpawnProp", "Spawned custom prop")
```

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

### Get Luminosity Tracking Value

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/api-reference/possession-system.md

Retrieves the current luminosity value (0-1 range) for the player. This is used for Nextbots to perceive environmental lighting.

```lua
local brightness = ply:DrG_Luminosity()  -- 0-1 range
```

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

### Get Table of Selected Entities for Toolgun Mode

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/api-reference/player-meta.md

Retrieves a table mapping selected entities to true for a given toolgun mode. If no mode is specified, it defaults to the current tool mode.

```lua
function Player:DrG_GetSelectionTable(mode)
-- Function body not provided in source
end
```

```lua
local selected = ply:DrG_GetSelectionTable("paint")
for ent, _ in pairs(selected) do
    print(ent:GetClass() .. " is selected")
end
```

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

### Get and Set AI Radius ConVar

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/configuration.md

Demonstrates how to retrieve the current value of the drgbase_ai_radius ConVar and how to set a new value. Use GetConVar for reading and RunConsoleCommand for writing.

```lua
-- Get value
local radius = GetConVar("drgbase_ai_radius"):GetFloat()

-- Set value
RunConsoleCommand("drgbase_ai_radius", "5000")
```

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

### Player.DrG_GetSelectedEntities

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/api-reference/player-meta.md

Gets array of all selected entities.

```APIDOC
## Player.DrG_GetSelectedEntities

### Description
Gets array of all selected entities.

### Returns
table - Array of Entity objects

### Example
```lua
local selected = ply:DrG_GetSelectedEntities()
print("Selected: " .. #selected .. " entities")
```
```

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

### Player.DrG_Possessing

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/api-reference/player-meta.md

Gets the entity being possessed by the player.

```APIDOC
## Player.DrG_Possessing

### Description
Gets the entity being possessed by the player.

### Returns
Entity - Possessed NextBot, or invalid entity if not possessing

### Example
```lua
if ply:DrG_IsPossessing() then
    local nextbot = ply:DrG_Possessing()
    print("Possessing: " .. nextbot:GetClass())
end
```
```

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

### Recommended Development Server Configuration

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/configuration.md

This Lua snippet provides recommended ConVar settings for a development server to facilitate testing and debugging of DrGBase features.

```lua
-- dev_server_config.lua
sv_cheats 1
drgbase_debug_traces 10
drgbase_debug_trajectories 5
drgbase_multiplier_health 0.5  -- Make testing faster
drgbase_precache_models 1
drgbase_precache_sounds 1
```

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

### Player.DrG_GetSelectionTable

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/api-reference/player-meta.md

Gets table of selected entities for toolgun mode.

```APIDOC
## Player.DrG_GetSelectionTable

### Description
Gets table of selected entities for toolgun mode.

### Parameters
#### Path Parameters
- **mode** (string) - Optional - Tool mode name. If nil, uses current tool mode

### Returns
table - Maps entities to true if selected

### Example
```lua
local selected = ply:DrG_GetSelectionTable("paint")
for ent, _ in pairs(selected) do
    print(ent:GetClass() .. " is selected")
end
```
```

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

### Cycle Through Nextbot Camera Views

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/api-reference/possession-system.md

Implement this method to allow cycling through different camera views (e.g., first-person, third-person) when the player presses the possession view key.

```lua
function ENT:CycleViewPresets()
-- ...
end

-- Example implementation:
function ENT:CycleViewPresets()
    self._viewMode = (self._viewMode or 0) + 1
    if self._viewMode > 2 then self._viewMode = 0 end
end
```

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

### Enable Possession for Nextbot

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/README.md

Configure a Nextbot to be possessable by players. Set possession to enabled, prompt the player, and define a bone for lock-on targeting. Implement custom logic for possession and dispossession.

```lua
ENT.PossessionEnabled = true
ENT.PossessionPrompt = true
ENT.DrGBase_LockOnBone = "head"

function ENT:Possess(ply)
    -- Custom logic
    return true
end

function ENT:Dispossess()
    -- Cleanup
end

function ENT:PossessorView()
    return self:GetPos() + self:GetUp() * 60
end
```

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

### Player.DrG_Luminosity

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/api-reference/player-meta.md

Gets the player's ambient light level (brightness).

```APIDOC
## Player.DrG_Luminosity

### Description
Gets the player's ambient light level (brightness). On the server, this returns a stored value from a client update. On the client, it calculates the light level from the render.GetLightColor() at the eye position.

### Method
`Player:DrG_Luminosity()`

### Returns
- **number** - The light level, clamped between 0 and 1.

### Example
```lua
local brightness = ply:DrG_Luminosity()
if brightness < 0.3 then
    print("Player in darkness")
end
```
```

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

### Simple Waypoint System using Nodegraph

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/api-reference/nodegraph-navigation.md

Implements a simple waypoint system for an entity using the nodegraph for pathfinding. It finds the nearest node, calculates a path using A*, and follows the waypoints.

```lua
-- Get nearest node in navigation graph
function ENT:GetNearestWaypoint()
    return DrGBase.ClosestNode(self:GetPos())
end

-- Find path to target using nodegraph
function ENT:FindNodePath(target)
    local path, success = DrGBase.NodegraphAstar(
        self:GetPos(), 
        target:GetPos()
    )
    return path, success
end

-- Follow waypoint path
function ENT:FollowWaypoints(waypoints)
    if not waypoints or #waypoints == 0 then return end
    
    self.CurrentWaypoint = self.CurrentWaypoint or 1
    local waypoint = waypoints[self.CurrentWaypoint]
    
    if not waypoint then return end
    
    self:GetMovement():Run()
    self:GetMovement():SetGoalPosition(waypoint)
    
    if self:GetPos():Distance(waypoint) < 100 then
        self.CurrentWaypoint = self.CurrentWaypoint + 1
    end
end

-- Think hook
function ENT:Think()
    if not self._targetPath then
        local target = self:GetTarget()
        if target then
            self._targetPath, _ = self:FindNodePath(target)
        end
    end
    
    if self._targetPath then
        self:FollowWaypoints(self._targetPath)
    end
end
```

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

### Get Node Position

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/api-reference/nodegraph-navigation.md

Retrieves the world position of a nodegraph node.

```lua
function Node:GetPos()
-- ...
end
```

```lua
local pos = node:GetPos()
ent:SetPos(pos)
```

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

### util.DrG_TraceHullRadial

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/api-reference/utility-modules.md

Performs hull traces in a circular pattern around a starting point.

```APIDOC
## util.DrG_TraceHullRadial

### Description
Traces physics hulls in a circular pattern, similar to `DrG_TraceLineRadial` but for hulls. It casts multiple hull traces at a specified distance and precision.

### Parameters
#### Arguments
- **dist** (number) - Required - The distance from the origin for the radial traces.
- **precision** (number) - Required - The number of rays to cast in the circular pattern.
- **data** (table) - Required - Trace data, must include a `start` position.

### Returns
- table - An array of hull trace results, sorted by distance.
```

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

### Pathfind with A* Algorithm

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/api-reference/nodegraph-navigation.md

Performs pathfinding between two positions using the A* algorithm. It automatically finds nearest nodes, follows connections, and can optionally use a custom heuristic callback.

```lua
function DrGBase.NodegraphAstar(pos, goal, callback)
-- ...
end
```

```lua
local path, success = DrGBase.NodegraphAstar(start, goal)
if success then
    print("Path found with " .. #path .. " waypoints")
    for i, waypoint in ipairs(path) do
        print(i, waypoint:ToString())
    end
else
    print("No path available")
end
```

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

### util.DrG_TraceLineRadial

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/api-reference/utility-modules.md

Performs line traces in a circular pattern around a starting point.

```APIDOC
## util.DrG_TraceLineRadial

### Description
Traces lines in a circular pattern originating from a specified distance and precision. This is useful for detecting multiple targets or obstacles in a radial area.

### Parameters
#### Arguments
- **dist** (number) - Required - The distance from the origin for the radial traces.
- **precision** (number) - Required - The number of rays to cast in the circular pattern.
- **data** (table) - Required - Trace data, must include a `start` position.

### Returns
- table - An array of trace results, sorted by distance.
```

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

### Configure Default Footstep Sounds

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/api-reference/nextbot-api.md

Assigns pre-configured footstep sounds to material types for Nextbot entities. Use this to define sounds for various surfaces.

```lua
DrGBase.DefaultFootsteps[MAT_TYPE] = {
    "sound1.wav",
    "sound2.wav",
    -- ...
}
```

```lua
-- Use default footsteps for Nextbot
function ENT:FootstepSound()
    local mat = util.GetSurfaceIndex(self:GetLastSurfaceMaterial())
    local sounds = DrGBase.DefaultFootsteps[mat] or DrGBase.DefaultFootsteps[MAT_FLESH]
    if sounds then
        self:EmitSound(table.Random(sounds))
    end
end
```

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

### Spawning NPCs and Setting Custom Properties

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/configuration.md

This Lua snippet shows how to spawn an NPC using Spawn_NPC and how to set custom entity properties like health and damage multipliers after spawning.

```lua
local ent = Spawn_NPC(player, class_name, weapon_name)

ent.CustomHealth = 150
ent.CustomDamageMultiplier = 0.8
ent.DrGBase_Target = false  -- Don't target this one
```

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

### Get Door Speed

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/api-reference/misc-utilities.md

Retrieves the movement speed of a door. Returns -1 if the speed is invalid.

```lua
function Door:GetSpeed()

```

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

### Get Directly Connected Nodes

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/api-reference/nodegraph-navigation.md

Retrieves an array of all nodes that are directly linked to the current node.

```lua
function Node:GetLinked()
-- ...
end
```

```lua
local neighbors = node:GetLinked()
for i, neighbor in ipairs(neighbors) do
    print("Connected to node " .. neighbor:GetID())
end
```

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

### Basic Nextbot Registration

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/README.md

Demonstrates how to register a new Nextbot entity with the DrGBase framework using `DrGBase.AddNextbot`.

```APIDOC
## Basic Nextbot Registration

### Description
Registers a new Nextbot entity with the DrGBase framework. This involves defining the entity's properties and then calling `DrGBase.AddNextbot`.

### Method
`DrGBase.AddNextbot(entityTable)`

### Parameters
#### Entity Table
- **entityTable** (table) - Required - A table containing the entity's properties such as `Type`, `Base`, `PrintName`, `Category`, and `Models`.

### Request Example
```lua
-- Define entity
ENT.Type = "nextbot"
ENT.Base = "drgbase_nextbot"
ENT.PrintName = "My Nextbot"
ENT.Category = "DrGBase"
ENT.Models = {"models/mymodel.mdl"}

-- Register with framework
DrGBase.AddNextbot(ENT)
```
```

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

### Get Node ID

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/api-reference/nodegraph-navigation.md

Retrieves the unique identifier for a nodegraph node. The ID is a 1-based number.

```lua
function Node:GetID()
-- ...
end
```

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

### Get Entity Cooldown

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/api-reference/misc-utilities.md

Retrieves the remaining cooldown time for a specified cooldown name. Returns 0 if not on cooldown.

```lua
function Entity:GetCooldown(name)

```

```lua
if ent:GetCooldown("attack") > 0 then
    print("Still attacking")
end

```

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

### Include All Lua Files in a Folder

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/api-reference/drgbase-core.md

Use DrGBase.IncludeFolder to load all .lua files within a specified folder. This is a non-recursive inclusion.

```lua
DrGBase.IncludeFolder("drgbase/modules")
```

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

### Door:GetDouble

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/api-reference/misc-utilities.md

Gets the linked double door for a door entity, returning NULL if it's a single door.

```APIDOC
## Door:GetDouble

### Description
Gets linked double door (if exists).

### Function Signature
```lua
function Door:GetDouble()
```

### Returns
- Entity - Partner door, or NULL if single door

### Example
```lua
local partnerDoor = door:GetDouble()
if IsValid(partnerDoor) then
    print("This is a double door.")
else
    print("This is a single door.")
end
```
```

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

### DrGBase.CreateProjectile

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/api-reference/nextbot-api.md

Creates a default projectile entity with custom behavior, allowing for custom models and callback functions for various events.

```APIDOC
## DrGBase.CreateProjectile

### Description
Creates a default projectile entity with custom behavior, allowing for custom models and callback functions for various events.

### Function Signature
```lua
function DrGBase.CreateProjectile(model, binds)
```

### Parameters
#### model (string or table) - Required
Model path or array of model paths for the projectile.

#### binds (table) - Optional
Callback function table for custom behavior. Available keys: `Init`, `Think`, `Contact`, `Use`, `DealtDamage`, `TakeDamage`, `Remove`.

### Returns
Entity - proj_drg_default entity, or NULL on failure

### Example
```lua
local proj = DrGBase.CreateProjectile("models/weapons/w_slam.mdl", {
    Init = function(self)
        self:SetPos(owner:GetShootPos())
        self:SetVelocity(owner:GetForward() * 1000)
    end,
    Contact = function(self, data)
        self:Explode()
    end
})
```
```

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

### Nextbot.CycleViewPresets

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/api-reference/possession-system.md

Cycles through available camera positions for possession view. This method should be defined within the Nextbot entity's script.

```APIDOC
## Nextbot.CycleViewPresets

### Description
Cycles through available camera positions for possession view. This function must be defined within the entity's script.

### Method
```lua
function ENT:CycleViewPresets()
```

### Called by
- Player pressing `drgbase_possession_view` key.

### Should
- Toggle between different camera views (first-person, third-person, etc.).

### Example
```lua
function ENT:CycleViewPresets()
    self._viewMode = (self._viewMode or 0) + 1
    if self._viewMode > 2 then self._viewMode = 0 end
end
```
```

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

### Simple Line Trace

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/README.md

Performs a simple line trace from an entity's position in its forward direction.

```lua
-- Simple line trace
local trace = ent:DrG_TraceLine(ent:GetForward() * 1000)
```

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

### Nextbot.PossessionGetLockedOn

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/api-reference/possession-system.md

Gets the current lock-on target for the Nextbot. This method should be defined within the Nextbot entity's script.

```APIDOC
## Nextbot.PossessionGetLockedOn

### Description
Gets the current lock-on target for the Nextbot. This function must be defined within the entity's script.

### Method
```lua
function ENT:PossessionGetLockedOn()
```

### Returns
- Entity - The currently locked target, or an invalid entity if none is selected.

### Called by
- Possession view system to adjust aim.

### Example
```lua
function ENT:PossessionGetLockedOn()
    return self._lockedTarget or NULL
end
```
```

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

### DrGBase.ClosestNode

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/api-reference/nodegraph-navigation.md

Finds the closest node in the navigation graph to a given position. This is useful for starting pathfinding or determining the nearest waypoint.

```APIDOC
## DrGBase.ClosestNode

### Description
Gets the nearest node in the navigation graph to a given position.

### Method
```lua
DrGBase.ClosestNode(pos)
```

### Parameters
#### Path Parameters
- **pos** (Vector) - Required - The position to find the closest node to.

### Returns
- **Node** - The closest node in the navigation graph.
```

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

### Enable Possession

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/README.md

Configures an entity to enable player possession, including setting prompt behavior, lock-on bones, and custom `Possess`, `Dispossess`, and `PossessorView` functions.

```APIDOC
## Enable Possession

### Description
Enables and customizes the player possession mechanics for an entity. This includes setting whether possession is enabled, if a prompt is shown, the bone to lock onto for aiming, and defining custom logic for when a player possesses, dispossesses, or for the possessor's view.

### Method
- `ENT.Possess(ply)`
- `ENT.Dispossess()`
- `ENT.PossessorView()`

### Parameters
- **ENT.PossessionEnabled** (boolean) - Required - Set to `true` to enable possession.
- **ENT.PossessionPrompt** (boolean) - Optional - If `true`, a prompt will be shown to players.
- **ENT.DrGBase_LockOnBone** (string) - Optional - The bone name to use for lock-on targeting during possession.
- **ply** (Player) - Parameter for `ENT.Possess` function.

### Request Example
```lua
ENT.PossessionEnabled = true
ENT.PossessionPrompt = true
ENT.DrGBase_LockOnBone = "head"

function ENT:Possess(ply)
    -- Custom logic
    return true
end

function ENT:Dispossess()
    -- Cleanup
end

function ENT:PossessorView()
    return self:GetPos() + self:GetUp() * 60
end
```
```

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

### Get the Entity Being Possessed by Player

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/api-reference/player-meta.md

Retrieves the entity that the player is currently possessing. Returns an invalid entity if the player is not possessing anything.

```lua
function Player:DrG_Possessing()
-- Function body not provided in source
end
```

```lua
if ply:DrG_IsPossessing() then
    local nextbot = ply:DrG_Possessing()
    print("Possessing: " .. nextbot:GetClass())
end
```

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

### Perform a Trace Hull from Entity Origin

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/api-reference/entity-meta.md

Performs a trace hull (physics box) in a specified direction. Uses the entity's collision bounds as the hull size and supports step height adjustments for Nextbots. Returns a trace result table.

```lua
function Entity:DrG_TraceHull(vec, data)
```

**Returns:** trace result table

**Example:**
```lua
-- Trace with step height adjustment for Nextbot
local trace = ent:DrG_TraceHull(Vector(0, 0, -200), {step = true})
local groundPos = trace.HitPos
```
```

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

### Required Nextbot Methods for Possession

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/api-reference/possession-system.md

These methods must be implemented in a Nextbot entity to enable possession. They handle enabling possession, defining prompts, and managing the possession lifecycle.

```lua
ENT.PossessionEnabled = true
ENT.PossessionPrompt = true

-- Possess/dispossess
function ENT:Possess(ply)
function ENT:Dispossess()

-- View management
function ENT:PossessorView()
function ENT:CycleViewPresets()

-- Lock-on (optional)
function ENT:PossessionGetLockedOn()
function ENT:PossessionFetchLockOn()
function ENT:PossessionLockOn(ent)

-- Movement (optional)
function ENT:IsPossessionEnabled()

```

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

### Get Node Type

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/api-reference/nodegraph-navigation.md

Retrieves the type code of a nodegraph node. Node types include ground, air, climbable, and water.

```lua
function Node:GetType()
-- ...
end
```

```lua
local nodeType = node:GetType()
if nodeType == NODE_TYPE_WATER then
    print("Water node")
end
```

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

### Get All Spawned Nextbots

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/api-reference/nextbot-api.md

Retrieves an array of all currently spawned Nextbot entities. Useful for iterating and performing actions on active Nextbots.

```lua
function DrGBase.GetNextbots()
```
```

```lua
local nextbots = DrGBase.GetNextbots()
for i, nextbot in ipairs(nextbots) do
    print(nextbot:GetClass())
end
```

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

### DrGBase.IncludeFiles

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/api-reference/drgbase-core.md

Includes multiple Lua files and returns a table mapping file paths to their respective include results.

```APIDOC
## DrGBase.IncludeFiles

### Description
Includes multiple files and returns table of results.

### Method
```lua
function DrGBase.IncludeFiles(fileNames)
```

### Parameters
#### Parameters
- **fileNames** (table) - Required - Array of file paths

### Returns
Table mapping file paths to include results

### Example
```lua
local results = DrGBase.IncludeFiles({
    "drgbase/misc.lua",
    "drgbase/particles.lua"
})
```
```

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

### Direction Enumeration (Client-Only)

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/types.md

Direction constants for client-side rendering. Available on CLIENT only.

```lua
D_ER = 0  -- Error direction
D_HT = 1  -- Height direction
D_FR = 2  -- Front direction
D_LI = 3  -- Light direction
D_NU = 4  -- Null/none direction
```

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

### Get Spawnmenu Category Icon

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/api-reference/misc-utilities.md

Retrieves the icon material path for a given spawnmenu category name. Returns nil if the category does not exist.

```lua
function DrGBase.GetIcon(name)
```

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

### DrGBase.IncludeFolder

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/api-reference/drgbase-core.md

Recursively includes all .lua files in a specified folder (non-recursive). Returns a table mapping file paths to include results.

```APIDOC
## DrGBase.IncludeFolder

### Description
Recursively includes all .lua files in a folder (non-recursive).

### Method
```lua
function DrGBase.IncludeFolder(folder)
```

### Parameters
#### Parameters
- **folder** (string) - Required - Folder path relative to LUA

### Returns
Table mapping file paths to include results

### Example
```lua
DrGBase.IncludeFolder("drgbase/modules")
```
```

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

### Get the Possessed Nextbot Entity

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/api-reference/possession-system.md

Retrieve the Nextbot entity that the player is currently possessing. Returns an invalid entity if the player is not possessing anything.

```lua
function Player:DrG_Possessing()
-- ...
end
```

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

### DrGBase.IncludeFile

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/api-reference/drgbase-core.md

Includes a single Lua file, respecting server/client conventions (sv_, cl_ prefix). It handles conditional inclusion based on the environment.

```APIDOC
## DrGBase.IncludeFile

### Description
Includes a single Lua file, respecting server/client conventions (sv_, cl_ prefix).

### Method
```lua
function DrGBase.IncludeFile(fileName)
```

### Parameters
#### Parameters
- **fileName** (string) - Required - Path to file relative to LUA folder

### Behavior
- Files prefixed `sv_` only include on SERVER
- Files prefixed `cl_` only include on CLIENT  
- Other files are added to client with `AddCSLuaFile()` then included

### Returns
Result of `include()` call

### Example
```lua
DrGBase.IncludeFile("drgbase/modules/timer.lua")
DrGBase.IncludeFile("sv_entities.lua")  -- Server-only
DrGBase.IncludeFile("cl_ui.lua")        -- Client-only
```
```

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

### Get Current Lock-on Target

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/api-reference/possession-system.md

Implement this method to return the entity currently targeted for lock-on. This is used by the possession view system to adjust aim.

```lua
function ENT:PossessionGetLockedOn()
-- ...
end

-- Example implementation:
function ENT:PossessionGetLockedOn()
    return self._lockedTarget or NULL
end
```

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

### Timer Management: Repeating Timer

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/README.md

Creates a repeating timer with flexible control over interval and stopping conditions.

```lua
-- Repeating timer with flexible control
ent:DrG_LoopTimer(0.5, function(self, counter) 
    if counter > 100 then return false end  -- Stop
    if counter % 5 == 0 then return 2 end   -- Slower interval
end, 0)
```

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

### table.DrG_Unpack

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/api-reference/utility-modules.md

Unpacks elements from a table as variadic return values. It allows specifying the number of elements to unpack and a starting index, preserving nil values.

```APIDOC
## table.DrG_Unpack

### Description
Unpacks table elements as variadic return values. Preserves nil values using an explicit size.

### Function Signature
```lua
function table.DrG_Unpack(tbl, size, i)
```

### Parameters
#### Path Parameters
- **tbl** (table) - Required - Table to unpack
- **size** (number) - Required - Number of elements to unpack
- **i** (number) - Optional - Starting index (defaults to 1)

### Returns
- **Variadic** - Unpacked values from tbl[i] to tbl[size]

### Example
```lua
local args = {1, 2, nil, 4}
local a, b, c, d = table.DrG_Unpack(args, 4)
-- a=1, b=2, c=nil, d=4
```
```

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

### Get Array of All Selected Entities

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/api-reference/player-meta.md

Returns an array containing all entities currently selected by the player. This function is useful for obtaining a direct list of selected entities.

```lua
function Player:DrG_GetSelectedEntities(mode)
-- Function body not provided in source
end
```

```lua
local selected = ply:DrG_GetSelectedEntities()
print("Selected: " .. #selected .. " entities")
```

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

### Create a spawner entity instance

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/api-reference/misc-utilities.md

Creates an instance of a spawner entity at a specified position, capable of spawning given entities within a radius. Allows for specifying spawn quantity and the spawner's own class. This function is server-only.

```lua
function DrGBase.CreateSpawner(pos, tospawn, radius, quantity, class)

local spawner = DrGBase.CreateSpawner(
    Vector(0, 0, 0),
    {["npc_custom"] = 5, ["prop_physics"] = 3},
    500,
    8,
    "spwn_drg_default"
)

if IsValid(spawner) then
    spawner:SetRadius(500)
    spawner:SetQuantity(8)
end
```

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

### Vector Data Structure

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/types.md

Represents a 3D vector with normalized direction, horizontal component, magnitude, and pitch. Use this to get vector data from a Vector object.

```lua
{
    normal = Vector,    -- Normalized direction
    forward = Vector,   -- Horizontal component (XY)
    length = number,    -- Magnitude
    pitch = number,     -- Vertical angle in degrees
}
```

```lua
local dir = Vector(100, 0, 50)
local data = dir:DrG_Data()
print("Launch angle: " .. data.pitch)
```

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

### Find Path in Nodegraph

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/README.md

Finds a path using A* algorithm and sets movement goals for an NPC.

```lua
local path, success = DrGBase.NodegraphAstar(
    npc:GetPos(),
    targetPos
)

if success then
    for i, waypoint in ipairs(path) do
        -- Follow waypoints in order
        npc:GetMovement():SetGoalPosition(waypoint)
    end
end
```

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

### Include Single Lua File

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/api-reference/drgbase-core.md

Use DrGBase.IncludeFile to load a single Lua file. It handles server/client specific prefixes (sv_, cl_) and client-side file registration.

```lua
DrGBase.IncludeFile("drgbase/modules/timer.lua")
```

```lua
DrGBase.IncludeFile("sv_entities.lua")  -- Server-only
```

```lua
DrGBase.IncludeFile("cl_ui.lua")        -- Client-only
```

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

### Bind Possession Keys

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/configuration.md

Shows how to bind specific keys to DrGBase possession actions like viewing presets, exiting possession, and toggling lock-on. These bindings are typically set in a client's autoexec file or via a concommand.

```lua
-- In client autoexec or set via concommand
bind v "drgbase_possession_view"
bind e "drgbase_possession_exit"
bind l "drgbase_possession_lockon"
```

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

### Add Nextbot Mixins

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/api-reference/nextbot-api.md

Internal function to add Nextbot hooks and compatibility methods for server-side operations. No return value.

```lua
function DrGBase.AddNextbotMixins(ENT)
```

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

### Join Multiple Factions

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/api-reference/player-meta.md

Adds a player to multiple factions simultaneously by providing an array of faction names.

```lua
function Player:DrG_JoinFactions(factions)
```

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

### Selection System: Smart Entity Selection

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/README.md

Uses a 'clever' selection method to select an entity for a given purpose.

```lua
-- Smart selection
ply:DrG_CleverEntitySelect(ent, "paint")
```

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

### Get Complete Nodegraph

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/api-reference/nodegraph-navigation.md

Retrieves the entire nodegraph for the current map. This function is server-only and loads data from the map's .ain file, parsing the Half-Life navigation graph format.

```lua
function DrGBase.GetNodegraph()
-- ...
end
```

```lua
local nodegraph = DrGBase.GetNodegraph()
print("Total nodes: " .. #nodegraph)
for id, node in ipairs(nodegraph) do
    print(id, node:GetPos())
end
```

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

### Entity.NetCallback

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/api-reference/networking.md

Sends a callback request from the server to a specific player, allowing the player to respond. The response is then processed by a provided callback function on the server.

```APIDOC
## Entity.NetCallback

### Description
Sends a callback request from the server to a specific player, allowing the player to respond. The response is then processed by a provided callback function on the server.

### Method
Server-to-Client Callback

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```lua
ent:NetCallback("GetViewDistance", function(self, distance)
    self:SetMaxViewDistance(distance)
end, ply)
```

### Response
#### Success Response
- **boolean**: Indicates success or failure of sending the callback request.

#### Response Example
None explicitly provided, returns a boolean.
```

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

### Create Dynamic Light Attached to Entity

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/api-reference/entity-meta.md

Use this function to create a dynamic light attached to an entity. You can customize color, radius, brightness, style, and attachment point.

```lua
function Entity:DrG_DynamicLight(color, radius, brightness, style, attachment)
end
```

```lua
ent:DrG_DynamicLight(
    Color(255, 100, 0),  -- Orange
    2000,                 -- Distance
    2,                    -- Brightness
    "z",                  -- Flickering style
    "eyes"                -- Attachment
)
```

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

### Wrap an entity with special handling

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/api-reference/misc-utilities.md

Creates a specialized wrapper object for an entity, providing object-oriented methods. It offers specific handling for Door entities, returning a Door wrapper with additional methods like Open and SetSpeed.

```lua
function Entity:DrG_Wrap()

if ent:DrG_IsDoor() then
    local door = ent:DrG_Wrap()
    door:Open()
    door:SetSpeed(100)
end
```

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

### Register Nextbot Entity Type

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/api-reference/nextbot-api.md

Registers a Nextbot entity with the system and spawnmenu. Requires ENT.PrintName and ENT.Category fields. Optionally configure models, sounds, and spawn restrictions.

```lua
function DrGBase.AddNextbot(ENT)
```
```

```lua
-- In entity file
ENT.Type = "nextbot"
ENT.Base = "drgbase_nextbot"
ENT.PrintName = "Custom Nextbot"
ENT.Category = "DrGBase"
ENT.Models = {"models/custom.mdl"}

function ENT:Initialize()
    -- ...
end

-- In registration file
DrGBase.AddNextbot(ENT)
```

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

### Basic Nextbot Registration

Source: https://github.com/dragoteryx/drgbase/blob/master/_autodocs/README.md

Register a new Nextbot entity with the DrGBase framework. Ensure the ENT.Type is set to 'nextbot' and ENT.Base to 'drgbase_nextbot'.

```lua
-- Define entity
ENT.Type = "nextbot"
ENT.Base = "drgbase_nextbot"
ENT.PrintName = "My Nextbot"
ENT.Category = "DrGBase"
ENT.Models = {"models/mymodel.mdl"}

-- Register with framework
DrGBase.AddNextbot(ENT)
```