Skip to main content

Rollback

The snapshot store half of Hindsight. Reachable via World.rollback.

Owns both the writer (capture) and the readers (queryRay, characterPoseAt). When held by a World, the writer fans out to every simulation actor; the reader queries the main-thread store.

The auto-capture helpers (autoCapturePlayers, autoCaptureCharacters, autoCaptureCharacter) are server-only opt-ins. Each registers a "source" of characters with the proxy; the proxy runs a single PostSimulation hook that walks every registered source, builds one merged CharacterPoses table, and pushes it. Mixing helpers is safe — all sources contribute to the same snapshot per tick.

Functions​

capture​

This item only works when running on the server. Server
</>
Rollback:capture(
time: number,--

Server time the snapshot represents. Typically workspace:GetServerTimeNow().

poses: CharacterPoses--

Map of character Model → CharacterPose.

) → ()

Pushes a snapshot of every character's current pose. Fans out to every simulation actor in addition to the main-thread store. Characters whose parts length doesn't match the configured rig are silently dropped.

Most consumers should use one of the autoCapture* helpers instead of calling this directly.

clear​

</>
Rollback:clear() → ()

Drops every retained snapshot from both the main-thread store and every simulation actor. Use on round transitions when "now" and "earlier" should not bracket the boundary.

queryRay​

</>
Rollback:queryRay(
time: number,--

Server time at which to evaluate the snapshot.

origin: Vector3,--

World-space ray origin.

direction: Vector3,--

Unit ray direction. Must be normalized.

length: number,--

Maximum scan distance in studs.

filter: Filter?,--

Optional skip predicate. Requires caster if provided.

caster: Caster?,--

The Caster argument forwarded to filter.

extra: Extra?--

Extra table forwarded to filter.

) → RollbackHit?--

First character whose per-part OBB the ray intersects, or nil.

Ray query against the snapshot at time. Brackets time between two snapshots, interpolates each character's pose, runs a voxel broadphase + AABB midphase, then OBB narrowphase per part. Returns the first hit encountered — Hindsight does not aggregate multi-character hits in a single query.

Returns nil if time is outside the retained snapshot window, or every candidate was filtered, or the ray missed.

characterPoseAt​

</>
Rollback:characterPoseAt(
time: number,--

Server time at which to evaluate the snapshot.

character: Model--

The character to retrieve.

) → {[string]: CFrame}?--

Part-name → interpolated CFrame, or nil if the snapshot doesn't bracket time for this character.

Interpolated pose of a single character at a past time. Useful for debug rendering (e.g. "where was this player when the server saw the shot?") and for building custom hit shapes the standard queryRay doesn't cover.

autoCapturePlayers​

This item only works when running on the server. Server
</>
Rollback:autoCapturePlayers() → () → ()--

Disconnect function. Call it to remove this source.

Registers a pose source that walks Players:GetPlayers() every PostSimulation and pushes each player's .Character into the snapshot. Skips dead, parentless, or rig-incompatible characters.

The first auto-capture registration on a world starts a shared PostSimulation hook; the last disconnect stops it. Server-only — asserts on the client. 

local stop = world.rollback:autoCapturePlayers()
-- later:
stop()

autoCaptureCharacters​

This item only works when running on the server. Server
</>
Rollback:autoCaptureCharacters(
folder: Instance--

Container whose immediate Model children should be captured.

) → () → ()--

Disconnect function. Call it to remove this source.

Registers a pose source that walks folder:GetChildren() every PostSimulation. Use this when both players and NPCs live under one container — typically workspace.Characters — so a single registration covers everyone. Skips non-Model children, dead Humanoids, and rig-incompatible characters.

Server-only.

autoCaptureCharacter​

This item only works when running on the server. Server
</>
Rollback:autoCaptureCharacter(
character: Model--

The Model to capture each tick.

) → () → ()--

Disconnect function. Call it to remove this source.

Registers a pose source for one specific Model. Useful for boss enemies, scripted NPCs, or any character that lives outside the main characters container. Stops contributing automatically once the character is dead or reparented to nil, but the source itself stays registered until the disconnect runs.

Server-only.

Show raw api
{
    "functions": [
        {
            "name": "capture",
            "desc": "Pushes a snapshot of every character's current pose. Fans out to every\nsimulation actor in addition to the main-thread store. Characters whose\n`parts` length doesn't match the configured rig are silently dropped.\n\nMost consumers should use one of the [`autoCapture*`](#autoCapturePlayers)\nhelpers instead of calling this directly.",
            "params": [
                {
                    "name": "time",
                    "desc": "Server time the snapshot represents. Typically `workspace:GetServerTimeNow()`.",
                    "lua_type": "number"
                },
                {
                    "name": "poses",
                    "desc": "Map of character `Model` → [`CharacterPose`](Hindsight#CharacterPose).",
                    "lua_type": "CharacterPoses"
                }
            ],
            "returns": [],
            "function_type": "method",
            "realm": [
                "Server"
            ],
            "source": {
                "line": 171,
                "path": "src/World.lua"
            }
        },
        {
            "name": "clear",
            "desc": "Drops every retained snapshot from both the main-thread store and every\nsimulation actor. Use on round transitions when \"now\" and \"earlier\" should\nnot bracket the boundary.",
            "params": [],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 195,
                "path": "src/World.lua"
            }
        },
        {
            "name": "queryRay",
            "desc": "Ray query against the snapshot at `time`. Brackets `time` between two\nsnapshots, interpolates each character's pose, runs a voxel broadphase +\nAABB midphase, then OBB narrowphase per part. Returns the **first** hit\nencountered — Hindsight does not aggregate multi-character hits in a\nsingle query.\n\nReturns `nil` if `time` is outside the retained snapshot window, or every\ncandidate was filtered, or the ray missed.",
            "params": [
                {
                    "name": "time",
                    "desc": "Server time at which to evaluate the snapshot.",
                    "lua_type": "number"
                },
                {
                    "name": "origin",
                    "desc": "World-space ray origin.",
                    "lua_type": "Vector3"
                },
                {
                    "name": "direction",
                    "desc": "Unit ray direction. Must be normalized.",
                    "lua_type": "Vector3"
                },
                {
                    "name": "length",
                    "desc": "Maximum scan distance in studs.",
                    "lua_type": "number"
                },
                {
                    "name": "filter",
                    "desc": "Optional skip predicate. Requires `caster` if provided.",
                    "lua_type": "Filter?"
                },
                {
                    "name": "caster",
                    "desc": "The Caster argument forwarded to `filter`.",
                    "lua_type": "Caster?"
                },
                {
                    "name": "extra",
                    "desc": "Extra table forwarded to `filter`.",
                    "lua_type": "Extra?"
                }
            ],
            "returns": [
                {
                    "desc": "First character whose per-part OBB the ray intersects, or `nil`.",
                    "lua_type": "RollbackHit?"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 221,
                "path": "src/World.lua"
            }
        },
        {
            "name": "characterPoseAt",
            "desc": "Interpolated pose of a single character at a past time. Useful for debug\nrendering (e.g. \"where was this player when the server saw the shot?\")\nand for building custom hit shapes the standard `queryRay` doesn't cover.",
            "params": [
                {
                    "name": "time",
                    "desc": "Server time at which to evaluate the snapshot.",
                    "lua_type": "number"
                },
                {
                    "name": "character",
                    "desc": "The character to retrieve.",
                    "lua_type": "Model"
                }
            ],
            "returns": [
                {
                    "desc": "Part-name → interpolated CFrame, or `nil` if the snapshot doesn't bracket `time` for this character.",
                    "lua_type": "{ [string]: CFrame }?"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 245,
                "path": "src/World.lua"
            }
        },
        {
            "name": "autoCapturePlayers",
            "desc": "Registers a pose source that walks `Players:GetPlayers()` every\n`PostSimulation` and pushes each player's `.Character` into the snapshot.\nSkips dead, parentless, or rig-incompatible characters.\n\nThe first auto-capture registration on a world starts a shared\n`PostSimulation` hook; the last disconnect stops it. Server-only — asserts\non the client.\n\n```lua\nlocal stop = world.rollback:autoCapturePlayers()\n-- later:\nstop()\n```",
            "params": [],
            "returns": [
                {
                    "desc": "Disconnect function. Call it to remove this source.",
                    "lua_type": "() -> ()"
                }
            ],
            "function_type": "method",
            "realm": [
                "Server"
            ],
            "source": {
                "line": 302,
                "path": "src/World.lua"
            }
        },
        {
            "name": "autoCaptureCharacters",
            "desc": "Registers a pose source that walks `folder:GetChildren()` every\n`PostSimulation`. Use this when both players and NPCs live under one\ncontainer — typically `workspace.Characters` — so a single registration\ncovers everyone. Skips non-Model children, dead Humanoids, and\nrig-incompatible characters.\n\nServer-only.",
            "params": [
                {
                    "name": "folder",
                    "desc": "Container whose immediate Model children should be captured.",
                    "lua_type": "Instance"
                }
            ],
            "returns": [
                {
                    "desc": "Disconnect function. Call it to remove this source.",
                    "lua_type": "() -> ()"
                }
            ],
            "function_type": "method",
            "realm": [
                "Server"
            ],
            "source": {
                "line": 333,
                "path": "src/World.lua"
            }
        },
        {
            "name": "autoCaptureCharacter",
            "desc": "Registers a pose source for one specific Model. Useful for boss enemies,\nscripted NPCs, or any character that lives outside the main characters\ncontainer. Stops contributing automatically once the character is dead or\nreparented to `nil`, but the source itself stays registered until the\ndisconnect runs.\n\nServer-only.",
            "params": [
                {
                    "name": "character",
                    "desc": "The Model to capture each tick.",
                    "lua_type": "Model"
                }
            ],
            "returns": [
                {
                    "desc": "Disconnect function. Call it to remove this source.",
                    "lua_type": "() -> ()"
                }
            ],
            "function_type": "method",
            "realm": [
                "Server"
            ],
            "source": {
                "line": 363,
                "path": "src/World.lua"
            }
        }
    ],
    "properties": [],
    "types": [],
    "name": "Rollback",
    "desc": "The snapshot store half of Hindsight. Reachable via [`World.rollback`](World#rollback).\n\nOwns both the **writer** ([`capture`](#capture)) and the **readers**\n([`queryRay`](#queryRay), [`characterPoseAt`](#characterPoseAt)). When held\nby a World, the writer fans out to every simulation actor; the reader\nqueries the main-thread store.\n\nThe auto-capture helpers ([`autoCapturePlayers`](#autoCapturePlayers),\n[`autoCaptureCharacters`](#autoCaptureCharacters),\n[`autoCaptureCharacter`](#autoCaptureCharacter)) are server-only opt-ins.\nEach registers a \"source\" of characters with the proxy; the proxy runs a\nsingle `PostSimulation` hook that walks every registered source, builds one\nmerged [`CharacterPoses`](Hindsight#CharacterPoses) table, and pushes it.\nMixing helpers is safe — all sources contribute to the same snapshot per\ntick.",
    "source": {
        "line": 55,
        "path": "src/World.lua"
    }
}