RollbackHitbox

Server-authoritative rollback lag compensation for Roblox shooters. The server rewinds hitbox positions to the exact moment the client fired, then validates the shot using oriented bounding-box (OBB) math — no physics simulation, no ghost parts moved at runtime.

Installation

Roblox Studio — Download RollbackHitbox.rbxm from the latest release and drag it into ServerScriptService.

Rojo — Copy the RollbackHitbox/ folder into your project and reference it in your default.project.json:

"RollbackHitbox": {
    "$path": "path/to/RollbackHitbox"
}

Quick Start

1. Record snapshots every frame

local RollbackHitbox = require(path.to.RollbackHitbox)
local RunService = game:GetService("RunService")

RunService.Heartbeat:Connect(function()
    RollbackHitbox.RecordAll(workspace:GetServerTimeNow())
end)

2. Register characters on spawn

Players.PlayerAdded:Connect(function(player)
    player.CharacterAdded:Connect(function(character)
        character:WaitForChild("HumanoidRootPart")
        character:WaitForChild("Head")

        RollbackHitbox.AttachHitboxes(character)
        RollbackHitbox.RegisterCharacter(character)

        character:WaitForChild("Humanoid").Died:Once(function()
            RollbackHitbox.UnregisterCharacter(character)
            RollbackHitbox.RemoveHitboxes(character)
        end)
    end)
end)

3. Validate hits on the server

-- Inside your hit RemoteEvent handler
local isValid, isHeadshot, hitDistance = RollbackHitbox.ValidateHit(
    shooter,
    target.Character,
    shotOrigin,
    shotDirection,
    gunConfig.Range,
    gunConfig.MuzzleOffset,
    clientTimestamp
)

if isValid then
    local damage = isHeadshot and gunConfig.HeadDamage or gunConfig.Damage
    target.Character.Humanoid:TakeDamage(damage)
end

4. Send the timestamp from the client

local fireTimestamp = workspace:GetServerTimeNow()
-- ... raycast, effects ...
CombatRemotes.PlayerHit:FireServer(targetUserId, shotOrigin, shotDirection, fireTimestamp)

How it works

CLIENT fires
├─ Capture timestamp = workspace:GetServerTimeNow()
├─ Local raycast for instant visual feedback
└─ Send: origin, direction, timestamp → server

SERVER receives
├─ rewindAmount = clamp(serverNow - timestamp + buffer, 0, maxRewind)
├─ Retrieve shooter's rewound position  → validate origin distance
├─ Retrieve target's rewound hitboxes   → binary-search + lerp snapshot buffer
├─ Ray-OBB intersection on rewound positions
└─ Apply damage only if valid

Every server Heartbeat (~60 Hz), each registered character's hitbox CFrames are written into a circular buffer. GetInterpolatedSnapshot() binary-searches that buffer and lerps between the two bracketing entries — giving sub-frame accuracy without storing every frame.

API Reference

Hitbox lifecycle

Position history

export type PartHitbox = {
    cframe:  CFrame,   -- hitbox position at the rewound time
    size:    Vector3,  -- hitbox dimensions
    isHead:  boolean,  -- true = head, false = body
}

Hit validation

RollbackHitbox.ValidateHit(
    shooter:         Player,
    targetCharacter: Model,
    shotOrigin:      Vector3?,
    shotDirection:   Vector3?,
    gunRange:        number,
    muzzleOffset:    Vector3,
    clientTimestamp: number?
) → (isValid: boolean, isHeadshot: boolean, hitDistance: number?)

Returns: isValid, isHeadshot, hitDistance (studs to hit point — use for damage falloff).

Config

Edit Config.luau to tune the system for your game.

Security

What this protects against

• Hit teleportation — origin distance check bounds the shot to within reasonable range of the shooter's rewound position.
• Timestamp manipulation — clientTimestamp is clamped to [0, MAX_REWIND_SECONDS]; a client cannot claim an arbitrarily old position.
• Headshot spoofing — the server independently determines headshot vs. body-shot by which hitbox the rewound ray intersects.

What this does not protect against

• Fabricated shotDirection — direction is trusted. Add a server-side line-of-sight raycast for stronger guarantees.
• Aimbots — this system ensures the claimed shot is geometrically plausible, not that it was aimed by a human.

License

MIT