Roblox Npcs

--!strict
--[[
    NPCPathFollower.lua
    A strict, Humanoid-based path follower with cleanup.

    Usage:
        local NPCPathFollower = require(path.to.NPCPathFollower)
        local humanoid = npcModel:WaitForChild("Humanoid") :: Humanoid
        local follower = NPCPathFollower.new(humanoid)
        follower:follow(targetPosition)
        follower:stop()
        follower:Destroy()
]]

local PathfindingService = game:GetService("PathfindingService")

export type PathWaypoint = {
    Position: Vector3,
    Action: Enum.PathWaypointAction,
    Label: string,
}

export type NPCPathFollowerOptions = {
    agentRadius: number?,
    agentHeight: number?,
    agentCanJump: boolean?,
    agentCanClimb: boolean?,
    waypointSpacing: number?,
    costs: {[string]: number}?,
    calculationSecondsTimeout: number?,
    moveToTimeout: number?,
    moveToRetryDelay: number?,
    maxMoveFailures: number?,
    customActionHandlers: {[string]: (humanoid: Humanoid, waypoint: PathWaypoint, follower: NPCPathFollower) -> ()}?,
}

export type NPCPathFollower = {
    humanoid: Humanoid,
    options: NPCPathFollowerOptions,
    agentRadius: number,
    agentHeight: number,
    agentCanJump: boolean,
    agentCanClimb: boolean,
    waypointSpacing: number,
    costs: {[string]: number},
    calculationSecondsTimeout: number,
    moveToTimeout: number,
    moveToRetryDelay: number,
    maxMoveFailures: number,
    customActionHandlers: {[string]: (humanoid: Humanoid, waypoint: PathWaypoint, follower: NPCPathFollower) -> ()},

    path: any,
    waypoints: {PathWaypoint},
    currentIndex: number,
    blockedConnection: RBXScriptConnection?,
    reachedConnection: RBXScriptConnection?,
    diedConnection: RBXScriptConnection?,
    moveToTimeoutThread: thread?,
    recomputeThread: thread?,
    running: boolean,
    moveFailCount: number,
}

local NPCPathFollower = {}
NPCPathFollower.__index = NPCPathFollower

function NPCPathFollower.new(humanoid: Humanoid, options: NPCPathFollowerOptions?): NPCPathFollower
    local self = setmetatable({}, NPCPathFollower) :: NPCPathFollower
    self.humanoid = humanoid
    self.options = options or {}

    self.agentRadius = self.options.agentRadius or 2
    self.agentHeight = self.options.agentHeight or 5
    self.agentCanJump = self.options.agentCanJump ~= false
    self.agentCanClimb = self.options.agentCanClimb or false
    self.waypointSpacing = self.options.waypointSpacing or 4
    self.costs = self.options.costs or {}
    self.calculationSecondsTimeout = self.options.calculationSecondsTimeout or 1
    self.moveToTimeout = self.options.moveToTimeout or 6
    self.moveToRetryDelay = self.options.moveToRetryDelay or 0.2
    self.maxMoveFailures = self.options.maxMoveFailures or 3
    self.customActionHandlers = self.options.customActionHandlers or {}

    self.path = nil
    self.waypoints = {}
    self.currentIndex = 1
    self.blockedConnection = nil
    self.reachedConnection = nil
    self.diedConnection = nil
    self.moveToTimeoutThread = nil
    self.recomputeThread = nil
    self.running = false
    self.moveFailCount = 0

    self.diedConnection = humanoid.Died:Connect(function()
        self:stop()
    end)

    return self
end

function NPCPathFollower:createPath(): any
    local path = PathfindingService:CreatePath({
        AgentRadius = self.agentRadius,
        AgentHeight = self.agentHeight,
        AgentCanJump = self.agentCanJump,
        AgentCanClimb = self.agentCanClimb,
        WaypointSpacing = self.waypointSpacing,
        Costs = self.costs,
    })
    path.CalculationSecondsTimeout = self.calculationSecondsTimeout
    return path
end

function NPCPathFollower:_disconnectReached()
    if self.reachedConnection then
        self.reachedConnection:Disconnect()
        self.reachedConnection = nil
    end
end

function NPCPathFollower:_cancelMoveToTimeout()
    if self.moveToTimeoutThread then
        task.cancel(self.moveToTimeoutThread)
        self.moveToTimeoutThread = nil
    end
end

function NPCPathFollower:_cancelRecompute()
    if self.recomputeThread then
        task.cancel(self.recomputeThread)
        self.recomputeThread = nil
    end
end

function NPCPathFollower:_cleanupPathConnections()
    self:_cancelRecompute()
    if self.blockedConnection then
        self.blockedConnection:Disconnect()
        self.blockedConnection = nil
    end
    self:_disconnectReached()
    self:_cancelMoveToTimeout()
end

function NPCPathFollower:follow(targetPosition: Vector3)
    if self.humanoid.Health <= 0 then
        return
    end

    self:stop()
    self.running = true
    self.moveFailCount = 0
    self:computeAndMove(targetPosition)
end

function NPCPathFollower:computeAndMove(targetPosition: Vector3)
    if not self.running or self.humanoid.Health <= 0 then
        self:stop()
        return
    end

    self:_cleanupPathConnections()
    self.path = self:createPath()

    local character = self.humanoid.Parent
    if not character then
        self:stop()
        return
    end
    local rootPart = character:FindFirstChild("HumanoidRootPart") :: BasePart?
    if not rootPart then
        self:stop()
        return
    end

    local success, err = pcall(function()
        self.path:ComputeAsync(rootPart.Position, targetPosition)
    end)

    if not success or self.path.Status ~= Enum.PathStatus.Success then
        warn("NPCPathFollower failed:", err or self.path.Status)
        self:stop()
        return
    end

    self.waypoints = self.path:GetWaypoints()
    self.currentIndex = 1
    self.moveFailCount = 0

    self.blockedConnection = self.path.Blocked:Connect(function(blockedIndex: number)
        if not self.running or self.humanoid.Health <= 0 then
            return
        end
        if blockedIndex >= self.currentIndex then
            self:_cancelRecompute()
            self.recomputeThread = task.delay(0, function()
                self.recomputeThread = nil
                if self.running then
                    self:computeAndMove(targetPosition)
                end
            end)
        end
    end)

    self:moveToNextWaypoint()
end

function NPCPathFollower:moveToNextWaypoint()
    if not self.running or self.humanoid.Health <= 0 then
        self:stop()
        return
    end

    if self.currentIndex > #self.waypoints then
        self:stop()
        return
    end

    local waypoint = self.waypoints[self.currentIndex]

    self:_disconnectReached()
    self:_cancelMoveToTimeout()

    if waypoint.Label ~= "" then
        local handler = self.customActionHandlers[waypoint.Label]
        if handler then
            handler(self.humanoid, waypoint, self)
        end
    end

    if waypoint.Action == Enum.PathWaypointAction.Jump then
        self.humanoid:ChangeState(Enum.HumanoidStateType.Jumping)
    elseif waypoint.Action == Enum.PathWaypointAction.Climb then
        -- Climbing truss parts is handled automatically by the Humanoid.
    end

    self.humanoid:MoveTo(waypoint.Position)

    self.moveToTimeoutThread = task.delay(self.moveToTimeout, function()
        self:_onMoveToTimeout()
    end)

    self.reachedConnection = self.humanoid.MoveToFinished:Connect(function(reached: boolean)
        self:_cancelMoveToTimeout()
        if not self.running then
            return
        end
        if self.humanoid.Health <= 0 then
            self:stop()
            return
        end

        if reached then
            self.moveFailCount = 0
            self.currentIndex += 1
            self:moveToNextWaypoint()
        else
            self.moveFailCount += 1
            if self.moveFailCount > self.maxMoveFailures then
                warn("NPCPathFollower: MoveTo failed too many times, stopping.")
                self:stop()
                return
            end
            task.delay(self.moveToRetryDelay, function()
                if self.running then
                    self:moveToNextWaypoint()
                end
            end)
        end
    end)
end

function NPCPathFollower:_onMoveToTimeout()
    if not self.running or self.humanoid.Health <= 0 then
        self:stop()
        return
    end

    self:_disconnectReached()
    self.moveFailCount += 1
    if self.moveFailCount > self.maxMoveFailures then
        warn("NPCPathFollower: MoveTo timed out too many times, stopping.")
        self:stop()
        return
    end

    task.delay(self.moveToRetryDelay, function()
        if self.running then
            self:moveToNextWaypoint()
        end
    end)
end

function NPCPathFollower:stop()
    self.running = false
    self:_cleanupPathConnections()

    local rootPart = self.humanoid.RootPart
    if rootPart then
        self.humanoid:MoveTo(rootPart.Position)
    else
        self.humanoid:Move(Vector3.zero)
    end
end

function NPCPathFollower:Destroy()
    self:stop()
    if self.diedConnection then
        self.diedConnection:Disconnect()
        self.diedConnection = nil
    end
end

return NPCPathFollower

--!strict
--[[
    PathfindingUtility.lua
    Helpers for throttled recomputation and waypoint formatting.

    Usage:
        local util = require(path.to.PathfindingUtility)
        local shouldRecompute, newPos, newTime = util.throttleRecompute(
            target.Position, lastPos, 0.5, 5, lastTime
        )
        print(util.formatWaypoint(waypoint))
]]

local PathfindingUtility = {}

function PathfindingUtility.throttleRecompute(
    currentPosition: Vector3,
    lastPosition: Vector3?,
    interval: number,
    minDistance: number,
    lastTime: number?
): (boolean, Vector3?, number?)
    local now = time()
    if lastTime and (now - lastTime) < interval then
        return false, lastPosition, lastTime
    end
    if lastPosition and (currentPosition - lastPosition).Magnitude < minDistance then
        return false, lastPosition, lastTime
    end
    return true, currentPosition, now
end

function PathfindingUtility.formatWaypoint(waypoint: {Position: Vector3, Action: any, Label: string}?): string
    if not waypoint then
        return "Waypoint(nil)"
    end
    return string.format("Waypoint(%s, %s, %s)",
        tostring(waypoint.Position),
        tostring(waypoint.Action),
        tostring(waypoint.Label)
    )
end

return PathfindingUtility

--!strict
--[[
    PatrolBehavior.lua
    A simple state machine: Idle → Patrol → Chase → Attack → Return.

    Usage:
        local PatrolBehavior = require(path.to.PatrolBehavior)
        local NPCPathFollower = require(path.to.NPCPathFollower)

        local behavior = PatrolBehavior.new(npcModel, {
            patrolPoints = {
                workspace:WaitForChild("PatrolA").Position,
                workspace:WaitForChild("PatrolB").Position,
            },
            detectionRange = 30,
            attackRange = 5,
            chaseTimeout = 10,
            recomputeInterval = 0.5,
            recomputeMinDistance = 4,
            attackCooldown = 1,
        })
        behavior:start()
        behavior:Destroy()
]]

local Players = game:GetService("Players")
local RunService = game:GetService("RunService")

local PatrolBehavior = {}
PatrolBehavior.__index = PatrolBehavior

function PatrolBehavior.new(model: Model, config: {[string]: any}?)
    local self = setmetatable({}, PatrolBehavior) :: any
    self.model = model
    self.humanoid = model:WaitForChild("Humanoid") :: Humanoid
    self.rootPart = model:WaitForChild("HumanoidRootPart") :: BasePart
    self.config = config or {}

    self.patrolPoints = self.config.patrolPoints or {}
    self.detectionRange = self.config.detectionRange or 30
    self.attackRange = self.config.attackRange or 5
    self.chaseTimeout = self.config.chaseTimeout or 10
    self.recomputeInterval = self.config.recomputeInterval or 0.5
    self.recomputeMinDistance = self.config.recomputeMinDistance or 4
    self.attackCooldown = self.config.attackCooldown or 1

    self.state = "Idle"
    self.patrolIndex = 1
    self.target = nil
    self.chaseTimer = 0
    self.follower = nil
    self.connection = nil
    self.destroyed = false
    self.lastRecomputeTime = 0
    self.lastRecomputePosition = nil
    self.lastAttackTime = 0

    self.humanoid.Died:Connect(function()
        self:Destroy()
    end)

    return self
end

function PatrolBehavior:start()
    if self.destroyed then return end
    if self.connection then return end

    self.connection = RunService.Heartbeat:Connect(function(dt: number)
        self:tick(dt)
    end)

    if #self.patrolPoints == 0 then
        self:setState("Idle")
    else
        self:setState("Patrol")
    end
end

function PatrolBehavior:stop()
    if self.connection then
        self.connection:Disconnect()
        self.connection = nil
    end
    if self.follower then
        self.follower:stop()
        self.follower = nil
    end
end

function PatrolBehavior:Destroy()
    if self.destroyed then return end
    self.destroyed = true
    self:stop()
    self.model = nil
    self.humanoid = nil
    self.rootPart = nil
    self.target = nil
end

function PatrolBehavior:setState(newState: string)
    self.state = newState
    if newState == "Patrol" then
        self.target = nil
        self:nextPatrolPoint()
    elseif newState == "Idle" then
        self.target = nil
        self.humanoid:Move(Vector3.zero)
        if self.follower then
            self.follower:stop()
            self.follower = nil
        end
    elseif newState == "Chase" then
        self.lastRecomputeTime = 0
        self.lastRecomputePosition = nil
        self.chaseTimer = 0
    elseif newState == "Return" then
        self.target = nil
        self.lastRecomputeTime = 0
        self.lastRecomputePosition = nil
    end
end

function PatrolBehavior:nextPatrolPoint()
    if #self.patrolPoints == 0 then return end
    self.patrolIndex = (self.patrolIndex % #self.patrolPoints) + 1
    self:moveTo(self.patrolPoints[self.patrolIndex])
end

function PatrolBehavior:moveTo(position: Vector3)
    if self.destroyed then return end
    if not self.follower then
        local NPCPathFollower = require(script.Parent.NPCPathFollower)
        self.follower = NPCPathFollower.new(self.humanoid)
    end
    self.follower:follow(position)
    self.lastRecomputeTime = time()
    self.lastRecomputePosition = position
end

function PatrolBehavior:findTarget(): Model?
    local closest: Model? = nil
    local closestDist = self.detectionRange

    local characters = {}
    for _, player in ipairs(Players:GetPlayers()) do
        if player.Character then
            table.insert(characters, player.Character)
        end
    end
    if #characters == 0 then
        return nil
    end

    local params = OverlapParams.new()
    params.FilterDescendantsInstances = characters
    params.FilterType = Enum.RaycastFilterType.Whitelist
    params.MaxParts = 100

    local parts = workspace:GetPartBoundsInRadius(self.rootPart.Position, self.detectionRange, params)
    for _, part in ipairs(parts) do
        local character = part:FindFirstAncestorOfClass("Model")
        if not character or character == self.model then
            continue
        end
        local hrp = character:FindFirstChild("HumanoidRootPart") :: BasePart?
        local humanoid = character:FindFirstChild("Humanoid") :: Humanoid?
        if hrp and humanoid and humanoid.Health > 0 then
            local dist = (hrp.Position - self.rootPart.Position).Magnitude
            if dist < closestDist then
                closestDist = dist
                closest = character
            end
        end
    end

    return closest
end

function PatrolBehavior:shouldRecompute(position: Vector3): boolean
    local now = time()
    if (now - self.lastRecomputeTime) < self.recomputeInterval then
        return false
    end
    if self.lastRecomputePosition and (position - self.lastRecomputePosition).Magnitude < self.recomputeMinDistance then
        return false
    end
    return true
end

function PatrolBehavior:tick(dt: number)
    if self.destroyed then return end
    if self.humanoid.Health <= 0 then
        self:Destroy()
        return
    end

    if self.state == "Patrol" or self.state == "Idle" then
        local target = self:findTarget()
        if target then
            self.target = target
            self:setState("Chase")
            return
        elseif self.state == "Patrol" and self.follower and not self.follower.running then
            self:nextPatrolPoint()
        end
    elseif self.state == "Chase" then
        if not self.target or not self.target:IsDescendantOf(workspace) then
            self:setState("Return")
            return
        end
        local hrp = self.target:FindFirstChild("HumanoidRootPart") :: BasePart?
        if not hrp then
            self:setState("Return")
            return
        end

        local dist = (hrp.Position - self.rootPart.Position).Magnitude
        if dist <= self.attackRange then
            self:setState("Attack")
            return
        end

        self.chaseTimer += dt
        if self.chaseTimer >= self.chaseTimeout then
            self:setState("Return")
            return
        end

        if self:shouldRecompute(hrp.Position) then
            self:moveTo(hrp.Position)
        end
    elseif self.state == "Attack" then
        if not self.target or not self.target:IsDescendantOf(workspace) then
            self:setState("Return")
            return
        end
        local hrp = self.target:FindFirstChild("HumanoidRootPart") :: BasePart?
        if not hrp then
            self:setState("Return")
            return
        end

        local dist = (hrp.Position - self.rootPart.Position).Magnitude
        if dist > self.attackRange then
            self:setState("Chase")
            return
        end

        local now = time()
        if now - self.lastAttackTime >= self.attackCooldown then
            self.lastAttackTime = now
            -- trigger server-side attack logic
        end
    elseif self.state == "Return" then
        self.target = nil
        if #self.patrolPoints == 0 then
            self:setState("Idle")
            return
        end
        local returnPos = self.patrolPoints[self.patrolIndex]
        if self:shouldRecompute(returnPos) then
            self:moveTo(returnPos)
        end
        if self.follower and not self.follower.running then
            self:setState("Patrol")
        end
    end
end

return PatrolBehavior