Hindsight

A generalized hit-detection and lag-compensated rollback library for Roblox gun systems.

Docs: https://realencryptal.github.io/Hindsight/ Writeup: https://www.encryptal.dev/devlog/hindsight

Hindsight provides three primitives:

1. Projectile simulation — a server-authoritative, parallelized projectile engine with penetration, ricochet, and snapshot-based hit detection. Same shape as a casting library, but every wiring decision (actors, containers, projectile definitions, rig hitboxes) is supplied by the caller through code.
2. Hitscan — a single-frame, lag-compensated ray resolver. Reuses the same ProjectileDefinition and callback wiring as the projectile path; full ricochet and penetration parity. Runs on the main thread.
3. Standalone rollback — the snapshot system is exposed on its own. Query a ray, retrieve a character's interpolated pose, or build melee / ability checks on top of it without touching the cast path.

Install

# wally.toml
[dependencies]
Hindsight = "realencryptal/hindsight@^0.2"

Quick reference

local Hindsight = require(ReplicatedStorage.Hindsight)

local world = Hindsight.createWorld({
    actorContainer    = ServerScriptService,
    visualsContainer  = workspace.Bullets, -- optional
    definitionsModule = ReplicatedStorage.Shared.Definitions,
    threads           = 16,
    rollback          = { ... },
    penetration       = { ... },
})

world.rollback:autoCapturePlayers()

world:cast({
    caster    = player,
    type      = "Bullet",
    origin    = origin,
    direction = direction,
    timestamp = workspace:GetServerTimeNow(),
})

-- Single-frame hitscan (server-side: lag-compensated; client-side: world-only):
world:hitscan({
    caster    = player,
    type      = "Laser",
    origin    = origin,
    direction = direction,
    timestamp = workspace:GetServerTimeNow(),
})

-- Standalone rollback query (server-only):
local hit = world.rollback:queryRay(timestamp, origin, direction, 500)

Documentation

• Getting started — end-to-end setup in under five minutes
• Concepts — how the snapshot model, actor pool, and definitions fit together
• Wiring server and client — what your scripts need to do
• Defining projectiles — the definitions module
• Standalone rollback — using snapshots without projectiles
• Configuration reference — every WorldConfig knob
• API reference — generated from source

A complete working server + client lives in example/.

License

MIT