Skip to main content
These let you narrow what the ragebot does. Each returns a handle you can :Release() to undo, and is auto-released on script unload. Higher priority on filters and gates runs first. Among equal priority, registration order applies.

​
addTargetFilter

api.ragebot.addTargetFilter(
    fn: (player: Player, info: RagebotTargetFilterInfo) -> boolean,
    priority: number?
): RegistrationHandle
Called for each candidate. Return false to exclude them. Every filter has to pass.

​
addShotGate

api.ragebot.addShotGate(
    fn: (shot: RagebotShotGateInfo) -> boolean,
    priority: number?
): RegistrationHandle
Called right before each shot. Return false to block it. Every gate has to pass.

​
forceTarget

api.ragebot.forceTarget(
    player: Player | string | number,
    durationSec: number?
): ForceTargetHandle?
Only let ragebot target one player. Accepts a Player, a player name, or a UserId. Returns nil if no matching player is in the server. Without a duration, it stays until you :Release() the handle or your script unloads. Calling again replaces the previous force-target.

​
clearForcedTarget

api.ragebot.clearForcedTarget(): ()
Cancel any force-target.

​
clearInFlight

api.ragebot.clearInFlight(player: Player | string | number?): ()
Clear pending shot tracking for one player, or everyone if you omit player. Resets ragebot’s “already shot enough at this player” tracking so it can shoot them again sooner.

​
setStrafeOverride

api.ragebot.setStrafeOverride(
    fn: (strafe: RagebotStrafeInfo) -> (CFrame | Vector3)?,
    priority: number?
): RegistrationHandle
Rivals only. Replace where the ragebot strafe-displaces you each tick (build your own orbit / void spam). Runs each strafe tick with a RagebotStrafeInfo table. Return:
  • a CFrame to displace exactly there,
  • a Vector3 to displace to that position (auto-faces the target),
  • or nil to leave the current strafe untouched.
Non-finite results (NaN / inf) are ignored, so a bad return can’t break your character. Multiple overrides stack by priority: the highest priority runs last and has the final say. Only fires while Target Strafe is on and the bot has a target.

​
RagebotStrafeInfo

{
    cframe = CFrame.new(...),           -- the strafe CFrame so far (after the built-in orbit + higher-priority overrides)
    position = Vector3.new(...),        -- cframe.Position, for convenience
    targetPosition = Vector3.new(...),  -- the enemy you're orbiting (nil if unknown); a Vector3 return auto-faces this
    origin = Vector3.new(...),          -- your real HumanoidRootPart position this tick
    isVoid = false,                     -- true on the built-in void-spam tick (you can ignore it and do your own)
    distance = 20,                      -- the Strafe Distance slider
    height = 0,                         -- the Strafe Height slider
    dt = 0.0167,                        -- frame delta
    angle = 1.57,                       -- current built-in orbit angle (radians)
    player = somePlayer,                -- the target Player (nil if unknown)
    time = os.clock(),
}

​
RegistrationHandle

handle:Release()           -- undo the registration
handle:IsReleased()        -- true if already released
handle:GetPriority()       -- current priority

​
ForceTargetHandle

handle:Release()           -- stop forcing
handle:IsReleased()        -- true if already released
handle:GetPlayer()         -- the player being forced

​
Examples

-- Don't shoot friends
api.ragebot.addShotGate(function(shot)
    return shot.player == nil or shot.player.Name ~= "FriendName"
end)

-- Only rage a VIP for 5 seconds
local handle = api.ragebot.forceTarget("EnemyName", 5)
-- handle:Release() to cancel early

-- Custom void spam (Rivals): every ~0.1s flick to a far void position, else keep the default strafe
if api.ragebot.setStrafeOverride then
    local lastFlick = 0
    local voiding = false
    api.ragebot.setStrafeOverride(function(strafe)
        if strafe.time - lastFlick >= 0.1 then
            lastFlick = strafe.time
            voiding = not voiding
        end
        if voiding then
            -- huge position; the override keeps your facing toward the target
            return Vector3.new(1e6, strafe.position.Y, 1e6)
        end
        return nil -- keep the built-in orbit
    end)
end

-- Tight overhead orbit (Rivals): ignore the built-in shape, orbit a fixed radius above the enemy
if api.ragebot.setStrafeOverride then
    api.ragebot.setStrafeOverride(function(strafe)
        local t = strafe.targetPosition
        if not t then return nil end
        local r = 12
        return Vector3.new(
            t.X + math.cos(strafe.angle) * r,
            t.Y + 8,
            t.Z + math.sin(strafe.angle) * r
        )
    end, 10)
end