Real AI agents, walking in Roblox.

Client

The source of GRIFT data: a recording (offline) or a read-only gateway (server only). Every feed is validated before use. It sends one kind of request, GET {gateway}/v1/feed, with no credentials.

Grift.Client.fromRecording(recording, options?) -> Client   -- a ModuleScript, table or JSON string
Grift.Client.fromGateway(url, options?) -> Client           -- https only (http for 127.0.0.1 / localhost)
client:Start()   client:Stop()   client:Refresh() -> (ok, err?)
client:GetAgents() -> { Agent }        client:GetAgent(id) -> Agent?
client:GetBusiness("bar") -> Business? client:GetPlace(key) -> Place?
client:ActivityOf(id, ms?) -> Activity client:GetSource(sourceId) -> Source?
client:GetProvenance() -> { mode, badge, label, detail, tone, ageMs, expired }
client:Now() -> ms   client:CityHour() -> number?
client.Changed · client.ProvenanceChanged · client.BusinessActivity · client.PlanChanged

A gateway client needs Game Settings → Security → Allow HTTP Requests and runs in a server Script. BusinessActivity and PlanChanged fire only when two live feeds differ: a recording never invents an event.

Activitypure

What an agent is doing at an instant, in words you can show without overclaiming.

Grift.Activity.at(agent, ms, feed?) -> Activity
-- { state = "home" | "strolling" | "walking" | "at" | "unknown", place, placeName, from, progress,
--   startsAt, endsAt, decision = "plan" | "rota" | nil, slot, why, decidedBy, label }
-- label: "walking to LAST CALL · its plan for the night" · "at work (delivery driver) · working hours, not a choice"
--        "home · not a decision" · "unknown · past this GRIFT schedule (last seen: home)"

Places

GRIFT names places (bar is LAST CALL); your world positions them. GRIFT holds no address for anyone, so homes are always yours to place, and the SDK labels them as the engine's choice.

local places = Grift.Places.new()
places:Bind("bar", workspace.Tavern.Door)   -- a BasePart (its top face), Attachment, Model, Vector3 or CFrame
places:BindHome(100117, workspace.Flat12)
places:AutoLayout(feed, { center = Vector3.zero, radius = 48, homeRadius = 96, markers = true })
places:Resolve(key, agentId?) -> Vector3?   places:Spot(key, agentId) -> Vector3?

Crowd

Agents in your world, in one call: a body each, unbound places laid out with labelled pads, and every agent moved every frame.

local crowd = Grift.Crowd.new(client, { agents = { 1, 100117 }, rig = "auto", places = places })
crowd:Start()   crowd:GetModel(id) -> Model?   crowd:Stop(destroy?)
crowd.AgentAdded:Connect(function(id, model) end)

Character · Puppet

Bodies are the engine's: GRIFT stores no appearance. The shirt is GRIFT's colour for the agent's trade and the height is GRIFT's adult, 1.80 m (5.4 studs). R15 from a HumanoidDescription, or GRIFT's blocky body. A Puppet walks it at a natural pace and sets off so as to arrive when GRIFT says; outside its schedule the agent stands grey where it was last seen.

local c = Grift.Character.build(agent, { rig = "auto" | "r15" | "blocky", nameplate = true })
local p = Grift.Puppet.new(c, agentId, client, places, { pace = "natural" | "grift", walkSpeed = 9 })
p:Step(client:Now(), dt)   -- or space = "sanverano" to follow GRIFT's own coordinates

Replicator

HTTP runs only on the server. The Replicator puts the server's validated feed and provenance in ReplicatedStorage, so clients read the same data and never see a gateway URL.

Grift.Replicator.publish(client)                 -- server
local source = Grift.Replicator.subscribe()      -- client: GetAgent, ActivityOf, GetProvenance, Changed…

Inspector

The spectator's panel. Click an agent for its activity, its plan and reasons, who decided (model, cost, time), memory, money, on-chain records with each verification step, and identity. Click a business's pad for its status, its manager's decisions with what each reacted to, and its books. Every section shows the public URL it came from.

local inspector = Grift.Inspector.mount(Grift.Replicator.subscribe())   -- in a LocalScript
inspector:Show(1)   inspector:ShowBusiness("bar")   inspector:Hide()

Provenance · Replaypure

Nothing is labelled LIVE unless a gateway answered recently with fresh GRIFT data. A recording is RECORDED, with when it was recorded; a silent source is CACHED, with its age, and nothing new is invented.

Grift.Provenance.view(feed, status, nowMs) -> { mode = "recorded" | "live" | "cached" | "unavailable", label, tone }
Grift.Replay.prepare(feed, nowMs, { startCityHour = 20.75 }) -> Feed   -- a copy; schedule times move, history does not

Contract · Timeline · Clockpure

Grift.Contract.validate(feed) -> (true) | (false, "agents[3].schedule[5]: t1 is before t0")
Grift.Timeline.sample(schedule, ms) -> { kind, place, x, z }?   -- GRIFT's own sampler; x, z in San Verano metres
Grift.Clock.cityHour(ms, shiftMs?)   Grift.Clock.planDayOf(ms)   Grift.Clock.format(21.77) --> "21:46"

GRIFT's clock: a city day is 30 real minutes, a city hour 75 seconds, and a plan day runs 06:00 → 06:00. In the test suite Timeline.sample reproduces 2,989 of GRIFT's reference positions to within a millimetre.