null nil GriftSDK Activity Activity -- `state` is home | strolling | walking | at | unknown. A journey that GRIFT cuts into several walk segments is one -- walk here: `progress` runs 0 -> 1 across all of it, and `startsAt` / `endsAt` are its ends. -- The label says who decided: "plan" segments carry the agent's plan for that part of the day and who made it -- (GRIFT's model, its rules, or the agent's own outside agent); "rota" is working hours, not a choice; homes, walks -- home and strolls are not decisions. Outside the schedule the agent is unknown, never guessed. Pure Luau. local Types = require(script.Parent.Types) local Timeline = require(script.Parent.Timeline) local Format = require(script.Parent.Format) type Agent = Types.Agent type Segment = Types.Segment type Activity = Types.Activity local Activity = {} local function decidedByOf(agent: Agent): string? local d = agent.decision if not d then return nil end local by = d.byLabel or d.by if d.by == "agent" and d.model then return string.format("%s (%s)", tostring(by), d.model) end return by end -- the plan's own words for a slot, when the segment carries a plan local function whyOf(agent: Agent, seg: Segment): string? if not seg.slot or not agent.plan or not agent.plan.slots then return nil end local slot = (agent.plan.slots :: any)[seg.slot] if slot and slot.why and slot.why ~= "" then return slot.why end return nil end -- the label: what, where, and whether it was decided function Activity.label(act: Activity): string local decision: string if act.decision == "plan" then decision = "its plan for the " .. Format.slotName(act.slot) elseif act.decision == "rota" then decision = "working hours, not a choice" else decision = "not a decision" end if act.state == "home" then return "home · not a decision" elseif act.state == "strolling" then return "a walk round the block from home · not a decision" elseif act.state == "walking" then if act.place == "home" then return "walking home · not a decision" end return string.format("walking to %s · %s", act.placeName or "?", decision) elseif act.state == "at" then return string.format("at %s · %s", act.placeName or "?", decision) end return "unknown · no GRIFT schedule covers this moment" end function Activity.at(agent: Agent, ms: number, feed: Types.Feed?, hint: number?): Activity local places = if feed then feed.places else nil local schedule = agent.schedule or {} local seg, i = Timeline.segmentAt(schedule, ms, hint) if not seg or not i then local last = Timeline.lastSeen(schedule, ms) local act: Activity = { state = "unknown", place = if last then last.place else nil, placeName = if last and last.place then Format.placeName(places, last.place) else nil, label = "", endsAt = if last then last.t1 else nil, } local first = schedule[1] if not last and first and ms < first.t0 then act.label = "unknown · before this GRIFT schedule starts" elseif last then act.label = "unknown · past this GRIFT schedule (last seen: " .. (act.placeName or "?") .. ")" else act.label = "unknown · no GRIFT schedule" end return act end local s = seg :: Segment local state: string = if s.kind == "home" then "home" elseif s.kind == "stroll" then "strolling" elseif s.kind == "walk" then "walking" else "at" local act: Activity = { state = state :: any, place = s.place, placeName = if s.place then Format.placeName(places, s.place) else nil, decision = s.decision, slot = s.slot, role = s.role, startsAt = s.t0, endsAt = s.t1, segment = s, index = i, label = "", } if s.kind == "walk" then -- one journey across consecutive walk segments to the same place local first, last = i, i while first > 1 and schedule[first - 1].kind == "walk" and schedule[first - 1].place == s.place do first -= 1 end while last < #schedule and schedule[last + 1].kind == "walk" and schedule[last + 1].place == s.place do last += 1 end local t0, t1 = schedule[first].t0, schedule[last].t1 act.startsAt, act.endsAt = t0, t1 act.progress = if t1 > t0 then math.clamp((ms - t0) / (t1 - t0), 0, 1) else 1 act.from = schedule[first].from act.fromName = if act.from then Format.placeName(places, act.from) else nil elseif s.kind == "stroll" then act.progress = if s.t1 > s.t0 then math.clamp((ms - s.t0) / (s.t1 - s.t0), 0, 1) else 1 end if s.decision == "plan" then act.why = whyOf(agent, s) act.decidedBy = decidedByOf(agent) elseif s.decision == "rota" then act.why = whyOf(agent, s) end act.label = Activity.label(act) return act end return Activity ]]> Character 0 then model:ScaleTo(height / size) end return model, root, humanoid end -- GRIFT's own voxel body: head 0.50 m, torso 0.50 × 0.60 × 0.30, legs 0.70, shoulders 0.90 (scaled to `height`) local function buildBlocky(agent: any, height: number): (Model, BasePart, { [string]: Motor6D }) local k = height / 1.8 local function m(x: number): number return x * k end local skin, shirt = Theme.skinFor(agent.id), Theme.shirtFor(agent) local model = Instance.new("Model") local root = Instance.new("Part") root.Name = "HumanoidRootPart" root.Size = Vector3.new(m(0.5), m(0.6), m(0.3)) root.Transparency = 1 root.CanCollide = false root.CanTouch = false root.Anchored = true root.Parent = model local joints: { [string]: Motor6D } = {} local function limb(name: string, size: Vector3, colour: Color3, offset: CFrame, pivot: CFrame): Motor6D local p = Instance.new("Part") p.Name = name p.Size = size p.Color = colour p.Material = Enum.Material.SmoothPlastic p.CanCollide = false p.CanTouch = false p.Massless = true p.Parent = model local motor = Instance.new("Motor6D") motor.Name = name .. "Joint" motor.Part0 = root motor.Part1 = p motor.C0 = pivot motor.C1 = offset:Inverse() * pivot motor.Parent = root return motor end -- the root is the torso's centre, 1.0 m above the feet (legs 0.70 + hips 0.30) limb("Torso", Vector3.new(m(0.5), m(0.6), m(0.3)), shirt, CFrame.new(), CFrame.new()) limb("Head", Vector3.new(m(0.5), m(0.5), m(0.5)), skin, CFrame.new(0, m(0.55), 0), CFrame.new(0, m(0.3), 0)) joints.LeftArm = limb("LeftArm", Vector3.new(m(0.18), m(0.62), m(0.18)), skin, CFrame.new(-m(0.36), -m(0.02), 0), CFrame.new(-m(0.36), m(0.28), 0)) joints.RightArm = limb("RightArm", Vector3.new(m(0.18), m(0.62), m(0.18)), skin, CFrame.new(m(0.36), -m(0.02), 0), CFrame.new(m(0.36), m(0.28), 0)) joints.LeftLeg = limb("LeftLeg", Vector3.new(m(0.2), m(0.7), m(0.22)), Theme.TROUSERS, CFrame.new(-m(0.13), -m(0.65), 0), CFrame.new(-m(0.13), -m(0.3), 0)) joints.RightLeg = limb("RightLeg", Vector3.new(m(0.2), m(0.7), m(0.22)), Theme.TROUSERS, CFrame.new(m(0.13), -m(0.65), 0), CFrame.new(m(0.13), -m(0.3), 0)) limb("Hips", Vector3.new(m(0.5), m(0.3), m(0.3)), Theme.TROUSERS, CFrame.new(0, -m(0.45), 0), CFrame.new(0, -m(0.45), 0)) model.PrimaryPart = root return model, root, joints end function Character.build(agent: any, options: Options?) local opts = options or {} local height = opts.heightStuds or Character.HEIGHT_STUDS local want = opts.rig or "auto" local model, root, humanoid, joints = nil, nil, nil, nil local rig = "blocky" if want ~= "blocky" then model, root, humanoid = buildR15(agent, height) if model then rig = "r15" elseif want == "r15" then warn("[GriftSDK] an R15 avatar could not be built here; using the blocky body") end end if not model then model, root, joints = buildBlocky(agent, height) end local m = model :: Model m.Name = string.format("%s (GRIFT #%d)", tostring(agent.name), agent.id) m:SetAttribute("GriftId", agent.id) m:SetAttribute("GriftName", agent.name) m:SetAttribute("GriftKind", agent.kind) m:SetAttribute("GriftRig", rig) m:SetAttribute("GriftAppearance", "engine's choice: GRIFT stores no appearance") local parts: { BasePart } = {} local colours: { [BasePart]: Color3 } = {} for _, d in ipairs(m:GetDescendants()) do if d:IsA("BasePart") and d ~= root then table.insert(parts, d) colours[d] = d.Color end end local self = setmetatable({ Model = m, Root = root :: BasePart, Humanoid = humanoid, Rig = rig, Agent = agent, Nameplate = nil :: any, _joints = joints, _parts = parts, _colours = colours, _tracks = nil :: { [string]: AnimationTrack }?, _anim = "", _phase = 0, _grey = false, _yaw = nil :: CFrame?, _footToRoot = if humanoid then humanoid.HipHeight + (root :: BasePart).Size.Y / 2 else height * (1.0 / 1.8), }, Character) if humanoid then local animator = humanoid:FindFirstChildOfClass("Animator") or Instance.new("Animator") animator.Parent = humanoid local tracks: { [string]: AnimationTrack } = {} for key, id in pairs(Character.ANIMATIONS) do local anim = Instance.new("Animation") anim.AnimationId = id local ok, track = pcall(function() return (animator :: Animator):LoadAnimation(anim) end) if ok and track then track.Priority = Enum.AnimationPriority.Core track.Looped = true tracks[key] = track end end self._tracks = tracks end if opts.nameplate ~= false then local head = m:FindFirstChild("Head") self.Nameplate = Nameplate.new(agent, if head and head:IsA("BasePart") then head else root :: BasePart) self.Nameplate.Gui.Parent = m end if opts.parent then m.Parent = opts.parent end return self end -- stand the agent with its feet on `ground`, facing `facing` (turning smoothly over dt) function Character.PlaceAt(self: any, ground: Vector3, facing: Vector3?, dt: number?) local pos = ground + Vector3.new(0, self._footToRoot, 0) local target: CFrame if facing and Vector3.new(facing.X, 0, facing.Z).Magnitude > 1e-3 then target = CFrame.lookAt(pos, pos + Vector3.new(facing.X, 0, facing.Z)) elseif self._yaw then target = self._yaw.Rotation + pos else target = CFrame.new(pos) end local cf = target if self._yaw and dt then cf = (self._yaw.Rotation + pos):Lerp(target, math.clamp(dt * 10, 0, 1)) end self._yaw = cf self.Root.CFrame = cf end -- idle / walk / run by ground speed (studs per second); the blocky body swings its limbs by distance instead function Character.Animate(self: any, speed: number, dt: number) if self._tracks then local name, rate if speed < 0.5 then name, rate = "idle", 1 elseif speed < 11 then name, rate = "walk", math.clamp(speed / 8, 0.5, 2.2) else name, rate = "run", math.clamp(speed / 14.5, 0.6, 2.2) end if self._anim ~= name then for key, track in pairs(self._tracks) do if key == name then track:Play(0.2) else track:Stop(0.2) end end self._anim = name end local t = self._tracks[name] if t then t:AdjustSpeed(rate) end return end local joints = self._joints if not joints then return end if speed > 0.5 then self._phase += speed * dt / 2.6 else self._phase *= 0.85 end local swing = if speed > 0.5 then math.sin(self._phase) * 0.55 else 0 joints.LeftLeg.Transform = CFrame.Angles(swing, 0, 0) joints.RightLeg.Transform = CFrame.Angles(-swing, 0, 0) joints.LeftArm.Transform = CFrame.Angles(-swing * 0.8, 0, 0) joints.RightArm.Transform = CFrame.Angles(swing * 0.8, 0, 0) end -- grey: the agent is unknown at this moment (no schedule covers it); it stands where it was last seen function Character.SetGrey(self: any, grey: boolean) if self._grey == grey then return end self._grey = grey for _, p in ipairs(self._parts) do p.Color = if grey then Theme.GREY else (self._colours[p] or p.Color) end if self._tracks and grey then for _, track in pairs(self._tracks) do track:Stop(0.2) end self._anim = "" end if self.Nameplate then self.Nameplate:SetGrey(grey) end end function Character.Destroy(self: any) self.Model:Destroy() end return Character ]]> Client any)?, decode: ((body: string) -> any)?, now: (() -> number)?, scheduler: { spawn: (fn: () -> ()) -> (), wait: (seconds: number) -> () }?, log: ((message: string) -> ())?, } local Client = {} Client.__index = Client Client.MAX_BODY_BYTES = 4 * 1024 * 1024 Client.FEED_PATH = "/v1/feed" -- ---- defaults for Roblox (looked up only when used, so the module loads anywhere) ------------------------------ local function robloxHttp(request: { url: string, headers: { [string]: string } }): any local HttpService = (game :: any):GetService("HttpService") return HttpService:RequestAsync({ Url = request.url, Method = "GET", Headers = request.headers }) end local function robloxDecode(body: string): any return (game :: any):GetService("HttpService"):JSONDecode(body) end local function robloxScheduler() local t = (task :: any) return { spawn = function(fn: () -> ()) t.spawn(fn) end, wait = function(seconds: number) t.wait(seconds) end, } end -- what a Roblox HTTP failure means, in words a developer can act on local function explainHttpError(err: any): string local s = tostring(err) if string.find(s, "not enabled", 1, true) or string.find(s, "HttpEnabled", 1, true) then return "HTTP requests are off (Game Settings → Security → Allow HTTP Requests)" elseif string.find(s, "game server", 1, true) then return "HTTP runs only on the server: use Client.fromGateway in a Script and Replicator.subscribe on clients" elseif string.find(s, "ConnectFail", 1, true) or string.find(s, "Connect", 1, true) then return "could not connect to the gateway" elseif string.find(s, "Timedout", 1, true) or string.find(s, "Timeout", 1, true) then return "the gateway timed out" end return (string.gsub(s, "\n.*", "")) end -- a gateway base URL: https anywhere, plain http only to this machine (Studio tests); never credentials in the URL function Client.checkGatewayUrl(url: any): (string?, string?) if type(url) ~= "string" or #url > 300 then return nil, "the gateway URL must be a string" end local base = string.gsub(url, "/+$", "") if string.find(base, "[%s@?#]") then return nil, "the gateway URL may not hold spaces, credentials (@), a query or a fragment" end if string.match(base, "^https://[%w%-%.]+%.[%a%-]+[:%d]*[/%w%-%._~]*$") then return base, nil end if string.match(base, "^http://127%.0%.0%.1[:%d]*[/%w%-%._~]*$") or string.match(base, "^http://localhost[:%d]*[/%w%-%._~]*$") then return base, nil end return nil, "the gateway URL must be https://host[/path] (or http://127.0.0.1 / localhost for local tests)" end local function header(headers: any, name: string): string? if type(headers) ~= "table" then return nil end local want = string.lower(name) for k, v in pairs(headers) do if type(k) == "string" and string.lower(k) == want then return tostring(v) end end return nil end -- ---- construction ------------------------------------------------------------------------------------------------- function Client.new(options: Options) assert(type(options) == "table", "Client.new expects an options table") assert(options.recording ~= nil or options.gateway ~= nil, "Client.new needs a recording or a gateway") assert(not (options.recording ~= nil and options.gateway ~= nil), "Client.new takes a recording or a gateway, not both (use fallback)") local self = setmetatable({}, Client) self._options = options self._now = options.now or Clock.nowMs self._http = options.http or robloxHttp self._decode = options.decode or robloxDecode self._log = options.log or function(message: string) print("[GriftSDK] " .. message) end self._scheduler = options.scheduler self._pollSeconds = math.max(options.pollSeconds or 15, 5) self._staleAfterMs = math.max(options.staleAfterSeconds or 90, 10) * 1000 self._replayOptions = table.clone(options.replay or {}) self._feed = nil :: Feed? self._recording = nil :: Feed? self._byId = {} :: { [number]: Agent } self._hints = {} :: { [number]: number } self._etag = nil :: string? self._running = false self._failures = 0 self._lastMode = nil :: string? self._seenRows = nil :: { [string]: boolean }? self._status = { source = if options.gateway then "gateway" else "recording", lastOkAt = nil :: number?, lastError = nil :: string?, polls = 0, } if options.gateway then local base, err = Client.checkGatewayUrl(options.gateway) assert(base, err) self._gateway = base end self.Changed = Signal.new() -- (feed) a new feed was accepted (a recording's next replayed day counts) self.ProvenanceChanged = Signal.new() -- (view) the mode changed: RECORDED / LIVE / CACHED / NO DATA self.BusinessActivity = Signal.new() -- (businessId, rows) new ledger rows between two live feeds self.PlanChanged = Signal.new() -- (agentId, plan) a live feed shows a changed plan return self end function Client.fromRecording(recording: any, options: Options?) local o = table.clone(options or {}) :: Options o.recording = recording return Client.new(o) end function Client.fromGateway(url: string, options: Options?) local o = table.clone(options or {}) :: Options o.gateway = url return Client.new(o) end -- ---- recordings --------------------------------------------------------------------------------------------------- function Client._resolveRecording(self: any, rec: any): (Feed?, string?) if rec == nil then return nil, "no recording" end if typeof(rec) == "Instance" then if not (rec :: any):IsA("ModuleScript") then return nil, "the recording is not a ModuleScript" end rec = require(rec :: any) end if type(rec) == "string" then local ok, decoded = pcall(self._decode, rec) if not ok then return nil, "the recording is not JSON" end rec = decoded end if type(rec) ~= "table" then return nil, "the recording is not a feed" end local ok, err = Contract.validate(rec) if not ok then return nil, "the recording fails the contract: " .. tostring(err) end if rec.provenance.mode ~= "recorded" then return nil, "a recording must say provenance.mode = recorded" end return rec, nil end function Client._filter(self: any, feed: Feed): Feed local only = self._options.agents if not only then return feed end local keep: { [number]: boolean } = {} for _, id in ipairs(only) do keep[id] = true end local f = table.clone(feed) local agents = {} for _, a in ipairs(feed.agents) do if keep[a.id] then table.insert(agents, a) end end f.agents = agents return f end function Client._index(self: any) self._byId = {} self._hints = {} if self._feed then for _, a in ipairs(self._feed.agents) do self._byId[a.id] = a end end end function Client._emitProvenance(self: any) local view = self:GetProvenance() if view.mode ~= self._lastMode then self._lastMode = view.mode self.ProvenanceChanged:Fire(view) end end -- accept a feed that passed the contract: replay a recorded one onto today's clock, note what changed, publish function Client._accept(self: any, feed: Feed) local prev = self._feed local f = self:_filter(feed) if f.provenance.mode == "recorded" then self._recording = f if self._replayOptions.startCityHour and not self._replayOptions.startedAtMs then self._replayOptions.startedAtMs = self._now() end f = Replay.prepare(f, self._now(), self._replayOptions) elseif prev and prev.provenance.mode ~= "recorded" then self:_diff(prev, f) end self._feed = f self:_index() self.Changed:Fire(f) self:_emitProvenance() end local function rowKey(r: Types.LedgerRow): string return table.concat({ tostring(r.at), tostring(r.kind), tostring(r.ref), tostring(r.amount), tostring(r.line) }, "|") end local function planKey(p: Types.Plan?): string if not p or not p.slots then return "" end local parts = {} for _, slot in ipairs({ "aft", "night" }) do local s = (p.slots :: any)[slot] table.insert(parts, if s then table.concat({ tostring(s.choice), tostring(s.why), tostring(s.spend) }, "/") else "-") end return tostring(p.forDay) .. ":" .. table.concat(parts, ";") end -- what a new live feed shows that the last did not: new ledger rows, changed plans (never invented, only compared) function Client._diff(self: any, prev: Feed, f: Feed) local seen: { [string]: boolean } = {} for _, b in ipairs(prev.businesses) do for _, r in ipairs(b.activity) do seen[b.id .. "#" .. rowKey(r)] = true end end for _, b in ipairs(f.businesses) do local fresh = {} for _, r in ipairs(b.activity) do if not seen[b.id .. "#" .. rowKey(r)] then table.insert(fresh, r) end end if #fresh > 0 then self.BusinessActivity:Fire(b.id, fresh) end end local before: { [number]: string } = {} for _, a in ipairs(prev.agents) do before[a.id] = planKey(a.plan) end for _, a in ipairs(f.agents) do local was = before[a.id] if was ~= nil and was ~= planKey(a.plan) then self.PlanChanged:Fire(a.id, a.plan) end end end -- ---- the gateway -------------------------------------------------------------------------------------------------- function Client._fail(self: any, why: string): (boolean, string?) self._failures += 1 self._status.lastError = why if self._failures == 1 or self._failures % 10 == 0 then self._log("gateway: " .. why .. (if self._feed then " (keeping the last good feed)" else "")) end self:_emitProvenance() return false, why end -- one request now: GET {gateway}/v1/feed with If-None-Match function Client.Refresh(self: any): (boolean, string?) if not self._gateway then return false, "this client reads a recording, not a gateway" end local headers: { [string]: string } = {} if self._etag then headers["If-None-Match"] = self._etag end self._status.polls += 1 local ok, res = pcall(self._http, { url = self._gateway .. Client.FEED_PATH, headers = headers }) if not ok then return self:_fail(explainHttpError(res)) end if type(res) ~= "table" then return self:_fail("the HTTP layer returned nothing") end local code = tonumber(res.StatusCode) or 0 if code == 304 and self._feed then self._failures = 0 self._status.lastOkAt = self._now() self._status.lastError = nil self:_emitProvenance() return true, nil end if code == 200 then local body = res.Body if type(body) ~= "string" or #body == 0 then return self:_fail("the gateway answered with an empty body") end if #body > Client.MAX_BODY_BYTES then return self:_fail(string.format("the gateway's answer is %d bytes, over the %d limit", #body, Client.MAX_BODY_BYTES)) end local dok, decoded = pcall(self._decode, body) if not dok or type(decoded) ~= "table" then return self:_fail("the gateway did not answer with JSON") end local valid, why = Contract.validate(decoded) if not valid then return self:_fail("refused a feed that fails the contract: " .. tostring(why)) end self._etag = header(res.Headers, "etag") self._failures = 0 self._status.lastOkAt = self._now() self._status.lastError = nil self:_accept(decoded) return true, nil end if code == 429 then local after = tonumber(header(res.Headers, "retry-after") or "") self._retryAfter = if after then math.clamp(after, 1, 600) else nil return self:_fail("the gateway asked to slow down (429)") end return self:_fail("the gateway answered HTTP " .. tostring(code)) end -- seconds until the next poll: the interval, doubled per failure up to 5 minutes, or what a 429 asked for function Client._nextDelay(self: any): number if self._retryAfter then local d = self._retryAfter self._retryAfter = nil return d end if self._failures == 0 then return self._pollSeconds end return math.min(self._pollSeconds * 2 ^ math.min(self._failures - 1, 6), 300) end -- a recording: move to the next replayed day when this one ends function Client.Tick(self: any) if self._status.source == "recording" or (self._feed and self._feed.provenance.mode == "recorded") then local f = self._feed local untilMs = if f then Clock.parseIso(f.clock.validUntil) else nil if f and self._recording and untilMs and self._now() >= untilMs then self._feed = Replay.prepare(self._recording, self._now(), self._replayOptions) self:_index() self.Changed:Fire(self._feed) end end self:_emitProvenance() end function Client.Start(self: any) if self._running then return self end self._running = true local scheduler = self._scheduler or robloxScheduler() if self._status.source == "recording" then local rec, err = self:_resolveRecording(self._options.recording) assert(rec, "GriftSDK: " .. tostring(err)) self:_accept(rec) scheduler.spawn(function() while self._running do scheduler.wait(1) if self._running then self:Tick() end end end) return self end -- a gateway, with an optional recording shown until it first answers if self._options.fallback ~= nil then local rec, err = self:_resolveRecording(self._options.fallback) if rec then self:_accept(rec) else self._log("fallback recording not used: " .. tostring(err)) end end scheduler.spawn(function() while self._running do self:Refresh() local delay = self:_nextDelay() local waited = 0 while self._running and waited < delay do scheduler.wait(1) waited += 1 self:Tick() end end end) return self end function Client.Stop(self: any) self._running = false end -- ---- reading ------------------------------------------------------------------------------------------------------ function Client.GetFeed(self: any): Feed? return self._feed end function Client.GetAgents(self: any): { Agent } return if self._feed then self._feed.agents else {} end function Client.GetAgent(self: any, id: number): Agent? return self._byId[id] end function Client.GetBusiness(self: any, id: string): Types.Business? if not self._feed then return nil end for _, b in ipairs(self._feed.businesses) do if b.id == id then return b end end return nil end function Client.GetPlace(self: any, key: string): Types.Place? return if self._feed then self._feed.places[key] else nil end function Client.GetSource(self: any, id: string?): Types.Source? if not id or not self._feed then return nil end return self._feed.provenance.sources[id] end function Client.Now(self: any): number return self._now() end function Client.CityHour(self: any): number? if not self._feed then return nil end return Clock.cityHour(self._now(), self._feed.clock.shiftMs) end function Client.ActivityOf(self: any, id: number, ms: number?): Types.Activity? local agent = self._byId[id] if not agent then return nil end local act = Activity.at(agent, ms or self._now(), self._feed, self._hints[id]) if act.index then self._hints[id] = act.index end return act end function Client.GetProvenance(self: any): Types.ProvenanceView local status = { source = if self._feed and self._feed.provenance.mode == "recorded" and self._status.source == "gateway" and not self._status.lastOkAt then "recording" else self._status.source, lastOkAt = self._status.lastOkAt, lastError = self._status.lastError, staleAfterMs = self._staleAfterMs, } return Provenance.view(self._feed, status :: any, self._now()) end function Client.GetStatus(self: any) return { source = self._status.source, gateway = self._gateway, polls = self._status.polls, lastOkAt = self._status.lastOkAt, lastError = self._status.lastError, failures = self._failures, etag = self._etag, running = self._running, } end return Client ]]> Clock 06:00, so hours 0-6 belong to the day before (GRIFT writes them as 24-30). -- `shiftMs` is a replay's move of a recorded day onto today's clock (0 for live data). -- Pure Luau: in Roblox `Clock.nowMs()` is the server-synchronised time, so every client sees the same instant. local Clock = {} Clock.DAY_MS = 1800000 Clock.HOUR_MS = 75000 Clock.DAY_FROM = 6 function Clock.nowMs(): number local ws = (workspace :: any) if ws ~= nil then return math.floor(ws:GetServerTimeNow() * 1000) end return os.time() * 1000 end function Clock.dayIndex(ms: number, shiftMs: number?): number return (ms - (shiftMs or 0)) // Clock.DAY_MS end -- 0 <= hour < 24 function Clock.cityHour(ms: number, shiftMs: number?): number local m = (ms - (shiftMs or 0)) % Clock.DAY_MS return (m / Clock.DAY_MS) * 24 end -- the plan day an instant belongs to (06:00 -> 06:00) function Clock.planDayOf(ms: number, shiftMs: number?): number local d = Clock.dayIndex(ms, shiftMs) if Clock.cityHour(ms, shiftMs) < Clock.DAY_FROM then return d - 1 end return d end -- the hour within its plan day: 6 <= hour < 30 function Clock.planHour(ms: number, shiftMs: number?): number local h = Clock.cityHour(ms, shiftMs) if h < Clock.DAY_FROM then return h + 24 end return h end -- the real time of an hour of a plan day (hours 24-30 are the small hours after midnight) function Clock.msOf(planDay: number, hour: number, shiftMs: number?): number return planDay * Clock.DAY_MS + hour * Clock.HOUR_MS + (shiftMs or 0) end -- "21:46" (hours 24-30 wrap to 00-06) function Clock.format(hour: number): string local whole = math.floor(hour) local minutes = math.floor((hour - whole) * 60 + 1e-6) return string.format("%02d:%02d", whole % 24, minutes) end -- ---- calendar arithmetic (no DateTime, so the same code runs in tests) ------------------------------------------ local function daysFromCivil(y: number, m: number, d: number): number y = if m <= 2 then y - 1 else y local era = (if y >= 0 then y else y - 399) // 400 local yoe = y - era * 400 local mp = (m + 9) % 12 local doy = (153 * mp + 2) // 5 + d - 1 local doe = yoe * 365 + yoe // 4 - yoe // 100 + doy return era * 146097 + doe - 719468 end local function civilFromDays(z: number): (number, number, number) z += 719468 local era = (if z >= 0 then z else z - 146096) // 146097 local doe = z - era * 146097 local yoe = (doe - doe // 1460 + doe // 36524 - doe // 146096) // 365 local y = yoe + era * 400 local doy = doe - (365 * yoe + yoe // 4 - yoe // 100) local mp = (5 * doy + 2) // 153 local d = doy - (153 * mp + 2) // 5 + 1 local m = if mp < 10 then mp + 3 else mp - 9 return (if m <= 2 then y + 1 else y), m, d end -- "2026-11-08T23:25:52.224Z" -> epoch ms; nil for anything else (only UTC "Z" times are accepted) function Clock.parseIso(iso: any): number? if type(iso) ~= "string" then return nil end local y, mo, d, h, mi, s, frac = string.match(iso, "^(%d%d%d%d)%-(%d%d)%-(%d%d)T(%d%d):(%d%d):(%d%d)%.?(%d*)Z$") if not y then return nil end local ms = 0 if frac and #frac > 0 then ms = math.floor(tonumber(string.sub(frac .. "00", 1, 3)) :: number) end local days = daysFromCivil(tonumber(y) :: number, tonumber(mo) :: number, tonumber(d) :: number) return ((days * 24 + (tonumber(h) :: number)) * 60 + (tonumber(mi) :: number)) * 60000 + (tonumber(s) :: number) * 1000 + ms end function Clock.toIso(ms: number): string local whole = math.floor(ms) local days = whole // 86400000 local rest = whole - days * 86400000 local y, m, d = civilFromDays(days) local h = rest // 3600000 local mi = (rest // 60000) % 60 local s = (rest // 1000) % 60 local milli = rest % 1000 return string.format("%04d-%02d-%02dT%02d:%02d:%02d.%03dZ", y, m, d, h, mi, s, milli) end -- "23:25 UTC" function Clock.utcTime(ms: number?): string if not ms then return "time unknown" end local iso = Clock.toIso(ms) return string.sub(iso, 12, 16) .. " UTC" end -- "2026-11-08 23:25 UTC" function Clock.utcDateTime(ms: number?): string if not ms then return "time unknown" end local iso = Clock.toIso(ms) return string.sub(iso, 1, 10) .. " " .. string.sub(iso, 12, 16) .. " UTC" end -- "40 s", "3 min", "2 h", "3 d" function Clock.age(ms: number): string if ms < 0 then ms = 0 end if ms < 90000 then return string.format("%d s", ms // 1000) elseif ms < 90 * 60000 then return string.format("%d min", ms // 60000) elseif ms < 36 * 3600000 then return string.format("%d h", ms // 3600000) end return string.format("%d d", ms // 86400000) end return Clock ]]> Contract (true, nil) | (false, "agents[3].schedule[5]: t1 is before t0") -- It refuses another contract or an incompatible version, a clock that is not GRIFT's, unknown modes and decision -- tokens, schedules that are out of order or have gaps, places a schedule names but the feed does not define, and -- anything over the size limits (a defence against a broken or hostile gateway). Pure Luau. local Contract = {} Contract.NAME = "grift.agents.feed" Contract.VERSION = "0.1" -- this SDK reads 0.1.x Contract.LIMITS = { agents = 64, segments = 600, pathVertices = 4000, places = 128, businesses = 16, ledger = 400, records = 32, sources = 600, string = 8000, } local MODES = { live = true, cached = true, recorded = true } local SEGMENT_KINDS = { home = true, walk = true, at = true, stroll = true } local AGENT_KINDS = { native = true, outside = true, team = true, deployed = true } local PLACE_KINDS = { venue = true, work = true, home = true, stall = true, other = true } local STATUSES = { verified = true, failed = true, unchecked = true } local BASES = { live = true, recorded = true } -- the steps "verified" requires, by record kind. A step that could not run is JSON null, which arrives as an absent -- key, so a missing required step means "could not check" and can never be verified. Contract.REQUIRED_STEPS = { decision = { "leaf", "trace", "proof", "chain" }, cash = { "leaf", "proof", "chain" }, business = { "leaf", "proof", "chain" }, identity = { "owner", "agentWallet", "uri" }, } local function isNum(v: any): boolean return type(v) == "number" and v == v and v ~= math.huge and v ~= -math.huge end local function isInt(v: any): boolean return isNum(v) and math.floor(v) == v end local function isStr(v: any, limit: number?): boolean return type(v) == "string" and #v <= (limit or Contract.LIMITS.string) end local function optStr(v: any): boolean return v == nil or isStr(v) end local function isList(v: any): boolean return type(v) == "table" and (next(v) == nil or v[1] ~= nil) end -- "0.1.4" -> compatible with "0.1" function Contract.isCompatible(version: any): boolean if type(version) ~= "string" then return false end local major, minor = string.match(version, "^(%d+)%.(%d+)%.%d+$") local wantMajor, wantMinor = string.match(Contract.VERSION, "^(%d+)%.(%d+)$") if not major then return false end if major ~= wantMajor then return false end -- before 1.0 a minor version may break: read only our own minor if major == "0" then return minor == wantMinor end return (tonumber(minor) :: number) >= (tonumber(wantMinor) :: number) end local function checkVerification(v: any, path: string, kind: string?): string? if type(v) ~= "table" then return path .. ": verification missing" end if not STATUSES[v.status] then return path .. ".status: " .. tostring(v.status) end if not BASES[v.basis] then return path .. ".basis: " .. tostring(v.basis) end if type(v.steps) ~= "table" then return path .. ".steps missing" end local all, any = true, false for k, step in pairs(v.steps) do any = true if step ~= true and step ~= false then return path .. ".steps." .. tostring(k) .. ": not a boolean" end if step ~= true then all = false end end -- "verified" must mean every step ran and passed: every present step, and every step the kind requires if v.status == "verified" then if not any or not all then return path .. ": says verified but not every step passed" end local required = kind and Contract.REQUIRED_STEPS[kind] if required then for _, step in ipairs(required) do if v.steps[step] ~= true then return path .. ": says verified but not every step passed (" .. step .. ")" end end end end return nil end local function checkRecord(r: any, path: string): string? if type(r) ~= "table" or not isStr(r.kind, 64) then return path .. ": a record needs a kind" end if r.absent then if not optStr(r.why) then return path .. ".why" end return nil end if not isStr(r.contract, 64) or not isStr(r.root, 80) then return path .. ": a sealed record needs contract and root" end return checkVerification(r.verification, path .. ".verification", r.kind) end local function checkIdentity(id: any, path: string): string? if type(id) ~= "table" then return path .. ": identity missing" end if id.erc8004 ~= nil then local e = id.erc8004 if type(e) ~= "table" or not isInt(e.agentId) or not isStr(e.registry, 64) then return path .. ".erc8004: agentId and registry required" end return checkVerification(e.verification, path .. ".erc8004.verification", "identity") end return nil end local function checkSegment(s: any, path: string, places: { [string]: any }): string? if type(s) ~= "table" then return path .. ": not an object" end if not isNum(s.t0) or not isNum(s.t1) then return path .. ": t0 and t1 must be numbers" end if s.t1 < s.t0 then return path .. ": t1 is before t0" end if not SEGMENT_KINDS[s.kind] then return path .. ".kind: " .. tostring(s.kind) end if s.decision ~= nil and s.decision ~= "plan" and s.decision ~= "rota" then return path .. ".decision: " .. tostring(s.decision) end if s.place ~= nil and (type(s.place) ~= "string" or places[s.place] == nil) then return path .. ".place: " .. tostring(s.place) .. " is not in places" end if s.from ~= nil and (type(s.from) ~= "string" or places[s.from] == nil) then return path .. ".from: " .. tostring(s.from) .. " is not in places" end local sv = s.sv if sv ~= nil then if type(sv) ~= "table" then return path .. ".sv" end if sv.at ~= nil and (type(sv.at) ~= "table" or not isNum(sv.at[1]) or not isNum(sv.at[2])) then return path .. ".sv.at" end if sv.path ~= nil then if type(sv.path) ~= "table" or #sv.path < 2 or #sv.path > Contract.LIMITS.pathVertices then return path .. ".sv.path: 2.." .. Contract.LIMITS.pathVertices .. " vertices" end local prevT = -math.huge for k, v in ipairs(sv.path) do if type(v) ~= "table" or not isNum(v[1]) or not isNum(v[2]) or not isNum(v[3]) then return path .. ".sv.path[" .. k .. "]: [t, x, z] numbers" end if v[1] < prevT then return path .. ".sv.path[" .. k .. "]: time goes backwards" end prevT = v[1] end end end return nil end function Contract.validate(f: any): (boolean, string?) if type(f) ~= "table" then return false, "the feed is not an object" end if f.contract ~= Contract.NAME then return false, string.format("contract is %s, wanted %s", tostring(f.contract), Contract.NAME) end if not Contract.isCompatible(f.version) then return false, string.format("version %s cannot be read by this SDK (it reads %s.x)", tostring(f.version), Contract.VERSION) end local p = f.provenance if type(p) ~= "table" or not MODES[p.mode] then return false, "provenance.mode must be live, cached or recorded" end if not isStr(p.label, 400) then return false, "provenance.label missing" end if type(p.sources) ~= "table" then return false, "provenance.sources missing" end local nSources = 0 for _ in pairs(p.sources) do nSources += 1 end if nSources > Contract.LIMITS.sources then return false, "provenance.sources: too many" end if p.mode == "recorded" and type(p.recording) ~= "table" then return false, "provenance.recording: a recorded feed must say when it was recorded" end local c = f.clock if type(c) ~= "table" or c.dayMs ~= 1800000 or c.hourMs ~= 75000 then return false, "clock is not GRIFT's (dayMs 1800000, hourMs 75000)" end if not isNum(c.shiftMs) or not isInt(c.planDay) then return false, "clock.shiftMs and clock.planDay must be numbers" end if type(c.validFrom) ~= "string" or type(c.validUntil) ~= "string" then return false, "clock.validFrom and clock.validUntil are required" end local places = f.places if type(places) ~= "table" then return false, "places missing" end local nPlaces = 0 for key, place in pairs(places) do nPlaces += 1 if type(key) ~= "string" or type(place) ~= "table" or place.key ~= key or not isStr(place.name, 200) or not PLACE_KINDS[place.kind] then return false, "places." .. tostring(key) .. ": key, name and kind required" end end if nPlaces > Contract.LIMITS.places then return false, "places: too many" end if not isList(f.agents) or #f.agents > Contract.LIMITS.agents then return false, string.format("agents: a list of at most %d", Contract.LIMITS.agents) end local seen: { [number]: boolean } = {} for i, a in ipairs(f.agents) do local path = "agents[" .. i .. "]" if type(a) ~= "table" or not isInt(a.id) or not isStr(a.name, 200) or not AGENT_KINDS[a.kind] then return false, path .. ": id, name and kind required" end if seen[a.id] then return false, path .. ": agent " .. a.id .. " appears twice" end seen[a.id] = true local err = checkIdentity(a.identity, path .. ".identity") if err then return false, err end if not isList(a.records) or #a.records > Contract.LIMITS.records then return false, path .. ".records" end for k, r in ipairs(a.records) do err = checkRecord(r, path .. ".records[" .. k .. "]") if err then return false, err end end if a.plan ~= nil and (type(a.plan) ~= "table" or type(a.plan.slots) ~= "table") then return false, path .. ".plan.slots" end if not isList(a.schedule) or #a.schedule > Contract.LIMITS.segments then return false, path .. ".schedule: a list of at most " .. Contract.LIMITS.segments end local prevT1: number? = nil for k, s in ipairs(a.schedule) do local spath = path .. ".schedule[" .. k .. "]" err = checkSegment(s, spath, places) if err then return false, err end if prevT1 and math.abs(s.t0 - prevT1) > 1 then return false, spath .. ": not contiguous with the segment before" end prevT1 = s.t1 end end if not isList(f.businesses) or #f.businesses > Contract.LIMITS.businesses then return false, "businesses" end for i, b in ipairs(f.businesses) do local path = "businesses[" .. i .. "]" if type(b) ~= "table" or not isStr(b.id, 64) or not isStr(b.name, 200) then return false, path .. ": id and name required" end local err = checkIdentity(b.identity, path .. ".identity") if err then return false, err end if not isList(b.activity) or #b.activity > Contract.LIMITS.ledger or not isList(b.decisions) then return false, path .. ".activity / decisions" end if not isList(b.records) then return false, path .. ".records" end for k, r in ipairs(b.records) do err = checkRecord(r, path .. ".records[" .. k .. "]") if err then return false, err end end end if not isList(f.honesty) then return false, "honesty: the feed's rules are required" end return true, nil end return Contract ]]> Crowd max do table.remove(ids) end return ids end function Crowd._sync(self: any, feed: any) if not feed then return end local ids = self:_wanted(feed) if self._opts.autoLayout ~= false then local layout = table.clone(self._opts.layout or {}) layout.agents = ids self.Places:AutoLayout(feed, layout) end local keep: { [number]: boolean } = {} for _, id in ipairs(ids) do keep[id] = true if not self._puppets[id] then local agent = self.Source:GetAgent(id) if agent then local character = Character.build(agent, { rig = self._opts.rig, nameplate = self._opts.nameplates }) character.Model.Parent = self.Folder self._puppets[id] = Puppet.new(character, id, self.Source, self.Places, self._opts.puppet) self.AgentAdded:Fire(id, character.Model) end end end for id, puppet in pairs(self._puppets) do if not keep[id] then puppet.Character:Destroy() self._puppets[id] = nil self.AgentRemoved:Fire(id) end end end function Crowd.Step(self: any, dt: number) local now = self.Source:Now() for _, puppet in pairs(self._puppets) do puppet:Step(now, dt) end -- the data's label on every nameplate, twice a second if now - self._badgeAt > 500 then self._badgeAt = now local view = self.Source:GetProvenance() for _, puppet in pairs(self._puppets) do local plate = puppet.Character.Nameplate if plate then plate:SetBadge(view.label, view.tone) end end end end function Crowd.Start(self: any) if self._running then return self end self._running = true local folder = self._opts.parent or workspace:FindFirstChild("GriftAgents") if not folder then folder = Instance.new("Folder") folder.Name = "GriftAgents" folder.Parent = workspace end self.Folder = folder table.insert(self._conns, self.Source.Changed:Connect(function(feed) self:_sync(feed) end)) self:_sync(self.Source:GetFeed()) table.insert(self._conns, RunService.Heartbeat:Connect(function(dt) self:Step(dt) end)) return self end function Crowd.GetModel(self: any, agentId: number): Model? local p = self._puppets[agentId] return if p then p.Character.Model else nil end function Crowd.GetPuppet(self: any, agentId: number): any return self._puppets[agentId] end function Crowd.Stop(self: any, destroy: boolean?) self._running = false for _, c in ipairs(self._conns) do c:Disconnect() end self._conns = {} if destroy then for id, puppet in pairs(self._puppets) do puppet.Character:Destroy() self._puppets[id] = nil end self.Places:Destroy() end end return Crowd ]]> Format "$23,464.13" function Format.money(n: number?): string if type(n) ~= "number" or n ~= n then return "?" end local negative = n < 0 local cents = math.floor(math.abs(n) * 100 + 0.5) local whole = tostring(cents // 100) local grouped = string.reverse((string.gsub(string.reverse(whole), "(%d%d%d)", "%1,"))) if string.sub(grouped, 1, 1) == "," then grouped = string.sub(grouped, 2) end return (if negative then "-$" else "$") .. grouped .. string.format(".%02d", cents % 100) end -- a model call's cost: 1299 micro-dollars -> "$0.0013" function Format.micros(n: number?): string if type(n) ~= "number" then return "?" end if n == 0 then return "$0" end return string.format("$%.4f", n / 1e6) end -- "0x443869a4bECB269B6F06A9aFAcd4914b0d60CCf2" -> "0x4438…CCf2" function Format.address(a: string?): string if type(a) ~= "string" then return "none" end if #a <= 12 then return a end return string.sub(a, 1, 6) .. "…" .. string.sub(a, -4) end function Format.slotName(slot: string?): string if slot == "aft" then return "afternoon" elseif slot == "night" then return "night" elseif slot == "shift" then return "shift" end return tostring(slot or "?") end function Format.placeName(places: { [string]: any }?, key: string?): string if not key then return "?" end local p = places and places[key] if p and type(p.name) == "string" then return p.name end if key == "home" then return "home" end return key end -- cut a string to n characters with an ellipsis function Format.clip(s: string?, n: number): string if type(s) ~= "string" then return "" end if utf8.len(s) and (utf8.len(s) :: number) <= n then return s end local cut = utf8.offset(s, n) or (n + 1) return string.sub(s, 1, cut - 1) .. "…" end return Format ]]> Inspector ", ">") return str end local function verdict(v: any): (string, Color3) if not v then return "not checked", Theme.GREY end local steps = {} for _, k in ipairs(STEP_ORDER) do if v.steps and v.steps[k] ~= nil then table.insert(steps, (if v.steps[k] == true then "" elseif v.steps[k] == false then "✗ " else "? ") .. k) end end local how = table.concat(steps, " · ") if v.status == "verified" then return "✓ verified: " .. how, Theme.GREEN elseif v.status == "failed" then return "✗ failed: " .. how, Theme.RED end return "could not check: " .. how, Theme.AMBER end local function basisLine(v: any): string? if not v then return nil end if v.basis == "recorded" then return "recorded: the chain was read during the recording" .. (if v.chainReadAt then ", " .. Clock.utcDateTime(Clock.parseIso(v.chainReadAt)) else "") end return "checked by the gateway" .. (if v.checkedAt then " at " .. Clock.utcTime(Clock.parseIso(v.checkedAt)) else "") end -- ---- mounting ------------------------------------------------------------------------------------------------------ function Inspector.mount(source: any, options: Options?) assert(source and source.GetFeed, "Inspector.mount(source): a Client or a Replicator.subscribe() source") local opts = options or {} local player = Players.LocalPlayer assert(player, "Inspector.mount runs in a LocalScript") local parent = opts.parent or player:WaitForChild("PlayerGui") local width = opts.width or 400 local gui = Instance.new("ScreenGui") gui.Name = "GriftInspector" gui.ResetOnSpawn = false gui.ZIndexBehavior = Enum.ZIndexBehavior.Sibling gui.Parent = parent -- the badge: what the data is, and GRIFT's clock local badge = Instance.new("Frame") badge.Name = "Badge" badge.Position = UDim2.fromOffset(16, 16) badge.Size = UDim2.fromOffset(380, 0) badge.AutomaticSize = Enum.AutomaticSize.Y badge.BackgroundColor3 = Theme.PANEL badge.BackgroundTransparency = 0.1 badge.BorderSizePixel = 0 badge.Parent = gui local bc = Instance.new("UICorner") bc.CornerRadius = UDim.new(0, 8) bc.Parent = badge local bpad = Instance.new("UIPadding") bpad.PaddingLeft, bpad.PaddingRight, bpad.PaddingTop, bpad.PaddingBottom = UDim.new(0, 12), UDim.new(0, 12), UDim.new(0, 10), UDim.new(0, 10) bpad.Parent = badge local blist = Instance.new("UIListLayout") blist.Padding = UDim.new(0, 4) blist.SortOrder = Enum.SortOrder.LayoutOrder blist.Parent = badge local title = text(badge, "GRIFT", { Font = Theme.FONT_DISPLAY, TextSize = 22, TextColor3 = Theme.GOLD, LayoutOrder = 1 }) title.RichText = false local mode = text(badge, "", { Font = Theme.FONT_BOLD, TextSize = 14, LayoutOrder = 2 }) local clock = text(badge, "", { TextSize = 14, LayoutOrder = 3 }) text(badge, "click an agent, or a gold pad for its business", { TextSize = 12, TextColor3 = Theme.MUTED, LayoutOrder = 4 }) -- the panel local panel = Instance.new("Frame") panel.Name = "Panel" panel.AnchorPoint = Vector2.new(1, 0) panel.Position = UDim2.new(1, -16, 0, 16) panel.Size = UDim2.new(0, width, 1, -32) panel.BackgroundColor3 = Theme.PANEL panel.BackgroundTransparency = 0.06 panel.BorderSizePixel = 0 panel.Visible = false panel.Parent = gui local pc = Instance.new("UICorner") pc.CornerRadius = UDim.new(0, 8) pc.Parent = panel local ps = Instance.new("UIStroke") ps.Color = Theme.RULE ps.Parent = panel local close = Instance.new("TextButton") close.Name = "Close" close.AnchorPoint = Vector2.new(1, 0) close.Position = UDim2.new(1, -10, 0, 10) close.Size = UDim2.fromOffset(32, 32) close.BackgroundColor3 = Theme.PANEL_2 close.TextColor3 = Theme.CREAM close.Font = Theme.FONT_BOLD close.TextSize = 18 close.Text = "×" close.ZIndex = 3 close.Parent = panel local scroll = Instance.new("ScrollingFrame") scroll.Name = "Body" scroll.Position = UDim2.fromOffset(0, 8) scroll.Size = UDim2.new(1, 0, 1, -16) scroll.BackgroundTransparency = 1 scroll.BorderSizePixel = 0 scroll.ScrollBarThickness = 6 scroll.ScrollBarImageColor3 = Theme.RULE scroll.AutomaticCanvasSize = Enum.AutomaticSize.Y scroll.CanvasSize = UDim2.new() scroll.Parent = panel local spad = Instance.new("UIPadding") spad.PaddingLeft, spad.PaddingRight, spad.PaddingTop, spad.PaddingBottom = UDim.new(0, 16), UDim.new(0, 18), UDim.new(0, 8), UDim.new(0, 16) spad.Parent = scroll local slist = Instance.new("UIListLayout") slist.Padding = UDim.new(0, 5) slist.SortOrder = Enum.SortOrder.LayoutOrder slist.Parent = scroll local self = setmetatable({ Gui = gui, _source = source, _scroll = scroll, _panel = panel, _mode = mode, _clock = clock, _order = 0, _agent = nil :: number?, _business = nil :: string?, _now = nil :: TextLabel?, _highlight = nil :: Highlight?, _conns = {} :: { any }, _alive = true, }, Inspector) close.MouseButton1Click:Connect(function() self:Hide() end) table.insert(self._conns, source.Changed:Connect(function() self:_render() end)) if opts.clickToInspect ~= false then table.insert(self._conns, UserInputService.InputBegan:Connect(function(input, processed) if processed then return end if input.UserInputType == Enum.UserInputType.MouseButton1 or input.UserInputType == Enum.UserInputType.Touch then self:_pick(Vector2.new(input.Position.X, input.Position.Y)) end end)) end task.spawn(function() while self._alive do self:_tick() task.wait(0.5) end end) return self end -- ---- picking ------------------------------------------------------------------------------------------------------- function Inspector._pick(self: any, at: Vector2) local camera = workspace.CurrentCamera if not camera then return end local ray = camera:ViewportPointToRay(at.X, at.Y) local hit = workspace:Raycast(ray.Origin, ray.Direction * 2000) local inst: Instance? = if hit then hit.Instance else nil while inst and inst ~= workspace do local id = inst:GetAttribute("GriftId") if type(id) == "number" then self:Show(id) return end local business = inst:GetAttribute("GriftBusiness") if type(business) == "string" then self:ShowBusiness(business) return end inst = inst.Parent end end function Inspector._highlightModel(self: any, model: Instance?) if self._highlight then self._highlight:Destroy() self._highlight = nil end if model then local h = Instance.new("Highlight") h.FillTransparency = 1 h.OutlineColor = Theme.GOLD h.DepthMode = Enum.HighlightDepthMode.Occluded h.Adornee = model h.Parent = self.Gui self._highlight = h end end local function findAgentModel(id: number): Instance? for _, d in ipairs(workspace:GetDescendants()) do if d:IsA("Model") and d:GetAttribute("GriftId") == id then return d end end return nil end function Inspector.Show(self: any, agentId: number) self._agent = agentId self._business = nil self:_highlightModel(findAgentModel(agentId)) self:_render() end function Inspector.ShowBusiness(self: any, businessId: string) self._business = businessId self._agent = nil self:_highlightModel(nil) self:_render() end function Inspector.Hide(self: any) self._agent = nil self._business = nil self:_highlightModel(nil) self._panel.Visible = false end function Inspector.Destroy(self: any) self._alive = false for _, c in ipairs(self._conns) do c:Disconnect() end self.Gui:Destroy() end -- ---- content ------------------------------------------------------------------------------------------------------- function Inspector._clear(self: any) for _, c in ipairs(self._scroll:GetChildren()) do if c:IsA("GuiObject") then c:Destroy() end end self._order = 0 self._now = nil end function Inspector._line(self: any, s: string, props: { [string]: any }?): TextLabel self._order += 1 local p = props or {} p.LayoutOrder = self._order return text(self._scroll, s, p) end function Inspector._heading(self: any, s: string) self._order += 1 local spacer = Instance.new("Frame") spacer.BackgroundTransparency = 1 spacer.Size = UDim2.new(1, 0, 0, 6) spacer.LayoutOrder = self._order spacer.Parent = self._scroll self:_line(esc(s), { Font = Theme.FONT_DISPLAY, TextSize = 14, TextColor3 = Theme.GOLD }) end function Inspector._sourceLine(self: any, id: string?) local src = self._source:GetSource(id) if not src then return end local when = if src.fetchedAt then Clock.utcDateTime(Clock.parseIso(src.fetchedAt)) else "time unknown" self:_line(esc(src.url) .. " · " .. when .. " · " .. esc(src.status), { TextSize = 11, TextColor3 = Theme.MUTED }) end function Inspector._record(self: any, r: any) if r.absent then self:_line("" .. esc(r.kind) .. " · not sealed: " .. esc(r.why), { TextColor3 = Theme.MUTED }) self:_sourceLine(r.source) return end local v, colour = verdict(r.verification) self:_line("" .. esc(r.label or r.kind) .. "") self:_line(esc(v), { TextColor3 = colour, TextSize = 14 }) local basis = basisLine(r.verification) if basis then self:_line(esc(basis), { TextSize = 12, TextColor3 = Theme.MUTED }) end if r.kind == "cash" and r.data and r.data.cash then self:_line("sealed: " .. Format.money(r.data.cash) .. " city dollars", { TextSize = 14 }) elseif r.kind == "decision" and r.data then self:_line("sealed: " .. esc(r.data.kind) .. (if r.data.reason then " · " .. esc(r.data.reason) else ""), { TextSize = 14 }) elseif r.kind == "business" and r.data and r.data.salesMicros then self:_line(string.format("sealed: sales %s · orders %s", Format.money((tonumber(r.data.salesMicros) or 0) / 1e6), tostring(r.data.orders)), { TextSize = 14 }) end if r.links then if r.links.contract then self:_line("contract " .. esc(r.links.contract), { TextSize = 11, TextColor3 = Theme.MUTED }) end if r.links.tx then self:_line("tx " .. esc(r.links.tx), { TextSize = 11, TextColor3 = Theme.MUTED }) end end self:_sourceLine(r.source) end function Inspector._identity(self: any, identity: any) local e = identity and identity.erc8004 if e then self:_line(string.format("ERC-8004 agent #%d · registry %s", e.agentId, esc(Format.address(e.registry)))) self:_line("owner " .. esc(Format.address(e.owner)) .. " · agent wallet " .. esc(if e.agentWallet then Format.address(e.agentWallet) else "none"), { TextSize = 14 }) if e.line then self:_line(esc(e.line), { TextSize = 13, TextColor3 = Theme.MUTED }) end local v, colour = verdict(e.verification) self:_line(esc(v), { TextColor3 = colour, TextSize = 14 }) local basis = basisLine(e.verification) if basis then self:_line(esc(basis), { TextSize = 12, TextColor3 = Theme.MUTED }) end self:_line(esc(e.explorer), { TextSize = 11, TextColor3 = Theme.MUTED }) self:_sourceLine(e.source) end if identity and identity.key then self:_line("signing key " .. esc(Format.address(identity.key.address)) .. " · " .. esc(identity.key.note), { TextSize = 14 }) end if identity and not e then self:_line(esc(identity.none or identity.why or "no ERC-8004 identity"), { TextSize = 14, TextColor3 = Theme.MUTED }) end end function Inspector._renderAgent(self: any, agent: any) local feed = self._source:GetFeed() self:_line(esc(agent.name), { Font = Theme.FONT_DISPLAY, TextSize = 22, TextColor3 = Theme.GOLD }) local sub = { "GRIFT #" .. agent.id, agent.kindLabel } if agent.district then table.insert(sub, agent.district) end if agent.job and agent.job.name then table.insert(sub, agent.job.name) end self:_line(esc(table.concat(sub, " · ")), { TextColor3 = Theme.MUTED, TextSize = 14 }) self:_heading("NOW") self._now = self:_line("") self:_tickNow() self:_heading("TODAY'S PLAN") local plan = agent.plan if plan and plan.slots then for _, slot in ipairs({ "aft", "night" }) do local s = plan.slots[slot] if s then local where = Format.placeName(feed and feed.places, s.place) local tail = if s.decided then "" else " · working hours, not a choice" local spend = if s.spend and s.spend > 0 then " · up to " .. Format.money(s.spend) else "" self:_line(string.format("%s · %s%s%s", Format.slotName(slot), esc(where), tail, spend)) if s.why then self:_line("“" .. esc(s.why) .. "”", { TextSize = 14, TextColor3 = Theme.CREAM }) end end end self:_line("plan day " .. tostring(plan.forDay) .. (if plan.current then "" else " (not today's)"), { TextSize = 12, TextColor3 = Theme.MUTED }) self:_sourceLine(plan.source) else self:_line("no plan read", { TextColor3 = Theme.MUTED }) end self:_heading("DECIDED BY") local d = agent.decision if d then self:_line(esc(d.byLabel)) local bits = {} if d.model then table.insert(bits, "model " .. d.model) end if d.costMicros and d.costMicros > 0 then table.insert(bits, "cost " .. Format.micros(d.costMicros)) end if d.at then table.insert(bits, Clock.utcTime(Clock.parseIso(d.at))) end if d.outcome then table.insert(bits, d.outcome) end if #bits > 0 then self:_line(esc(table.concat(bits, " · ")), { TextSize = 14 }) end if d.note then self:_line(esc(d.note), { TextSize = 13, TextColor3 = Theme.MUTED }) end self:_sourceLine(d.source) else self:_line("not read yet", { TextColor3 = Theme.MUTED }) end if agent.runsOn then self:_line("runs on: " .. esc(agent.runsOn.model) .. " (" .. esc(agent.runsOn.note) .. ")", { TextSize = 14 }) end if agent.memory then self:_heading("MEMORY") self:_line(esc(table.concat(agent.memory.notes, " · "))) self:_line(esc(agent.memory.what), { TextSize = 12, TextColor3 = Theme.MUTED }) self:_sourceLine(agent.memory.source) end if agent.cash then self:_heading("MONEY") self:_line(Format.money(agent.cash.amount) .. " " .. esc(agent.cash.unit)) self:_sourceLine(agent.cash.source) end self:_heading("ON CHAIN · ROBINHOOD CHAIN 4663") if #agent.records == 0 then self:_line("nothing sealed for this agent in this feed", { TextColor3 = Theme.MUTED }) end for _, r in ipairs(agent.records) do self:_record(r) end self:_heading("IDENTITY") self:_identity(agent.identity) self:_heading("ABOUT THIS DATA") local view = self._source:GetProvenance() self:_line(esc(view.detail), { TextSize = 13, TextColor3 = Theme.MUTED }) self:_line("appearance, home and the route drawn here are this engine's; GRIFT stores none of them", { TextSize = 13, TextColor3 = Theme.MUTED }) end function Inspector._renderBusiness(self: any, b: any) self:_line(esc(b.name), { Font = Theme.FONT_DISPLAY, TextSize = 22, TextColor3 = Theme.GOLD }) self:_line("GRIFT business · place \"" .. esc(b.place) .. "\"", { TextColor3 = Theme.MUTED, TextSize = 14 }) local s = b.status self:_heading("STATUS") if s then local setBy = if s.setBy == "agent" then "its manager agent" elseif s.setBy == "rules" then "GRIFT's rules" else tostring(s.setBy) self:_line(string.format("%s · %s · price set by %s%s", if s.open then "OPEN" else "CLOSED", Format.money(s.price), esc(setBy), if s.rulePrice then " (the rules' price " .. Format.money(s.rulePrice) .. ")" else "")) if s.why then self:_line("“" .. esc(s.why) .. "”", { TextSize = 14 }) end self:_line(string.format("staff %s · stock %s · sold today %s · footfall today %s (city %s)", tostring(s.staff), tostring(s.stock), tostring(s.soldToday), tostring(s.footfallToday), tostring(s.cityFootfall)), { TextSize = 14 }) if s.agentStatus then self:_line("its shift agent: " .. esc(s.agentStatus), { TextSize = 14 }) end self:_sourceLine(s.source) end self:_heading("THE MANAGER'S DECISIONS") if #b.decisions == 0 then self:_line("none in this feed", { TextColor3 = Theme.MUTED }) end for i, row in ipairs(b.decisions) do if i > 6 then break end self:_line(string.format("%s · %s", esc(row.kind), esc(row.line)), { TextSize = 14 }) if row.fact then self:_line("↳ reacting to: " .. esc(row.fact), { TextSize = 13, TextColor3 = Theme.MUTED }) end end self:_heading("LATEST ON THE BOOKS") for i, row in ipairs(b.activity) do if i > 8 then break end self:_line(esc(row.line), { TextSize = 14 }) end self:_sourceLine(b.activitySource) self:_heading("SEALED ON CHAIN") for _, r in ipairs(b.records) do self:_record(r) end self:_heading("IDENTITY") self:_identity(b.identity) for _, note in ipairs(b.notes or {}) do self:_line(esc(note), { TextSize = 13, TextColor3 = Theme.MUTED }) end end function Inspector._render(self: any) self:_clear() if self._agent then local agent = self._source:GetAgent(self._agent) if agent then self:_renderAgent(agent) self._panel.Visible = true return end elseif self._business then local b = self._source:GetBusiness(self._business) if b then self:_renderBusiness(b) self._panel.Visible = true return end end self._panel.Visible = false end function Inspector._tickNow(self: any) if not self._agent or not self._now then return end local act = self._source:ActivityOf(self._agent) if not act then return end local lines = { "" .. esc(act.label) .. "" } if act.why then table.insert(lines, "“" .. esc(act.why) .. "”") end if act.decidedBy then table.insert(lines, "decided by " .. esc(act.decidedBy)) end local shift = (self._source:GetFeed() or {}).clock if act.endsAt and shift then table.insert(lines, "until " .. Clock.format(Clock.cityHour(act.endsAt, shift.shiftMs)) .. " city time") end self._now.Text = table.concat(lines, "\n") end function Inspector._tick(self: any) local view = self._source:GetProvenance() self._mode.Text = esc(view.label) self._mode.TextColor3 = Theme.tone(view.tone) local feed = self._source:GetFeed() if feed then local h = self._source:CityHour() self._clock.Text = string.format("San Verano %s · plan day %d · a city hour is 75 s", if h then Clock.format(h) else "?", feed.clock.planDay) else self._clock.Text = "no GRIFT data yet" end self:_tickNow() end return Inspector ]]> Nameplate (), SetBadge: (self: Nameplate, text: string, tone: string?) -> (), SetGrey: (self: Nameplate, grey: boolean) -> (), SetSelected: (self: Nameplate, selected: boolean) -> (), Destroy: (self: Nameplate) -> (), } local GLYPH = { outside = " ◇", team = " ◆", deployed = " ◇" } local function label(parent: Instance, props: { [string]: any }): TextLabel local l = Instance.new("TextLabel") l.BackgroundTransparency = 1 l.TextXAlignment = Enum.TextXAlignment.Left l.TextTruncate = Enum.TextTruncate.AtEnd for k, v in pairs(props) do (l :: any)[k] = v end l.Parent = parent return l end function Nameplate.new(agent: any, adornee: BasePart, options: { maxDistance: number? }?) local gui = Instance.new("BillboardGui") gui.Name = "GriftNameplate" gui.Size = UDim2.fromOffset(250, 58) gui.StudsOffsetWorldSpace = Vector3.new(0, 3.4, 0) gui.MaxDistance = (options and options.maxDistance) or 180 gui.LightInfluence = 0 gui.AlwaysOnTop = false gui.ResetOnSpawn = false gui.Adornee = adornee local bg = Instance.new("Frame") bg.Name = "Panel" bg.Size = UDim2.fromScale(1, 1) bg.BackgroundColor3 = Theme.PANEL bg.BackgroundTransparency = 0.2 bg.BorderSizePixel = 0 bg.Parent = gui local corner = Instance.new("UICorner") corner.CornerRadius = UDim.new(0, 6) corner.Parent = bg local stroke = Instance.new("UIStroke") stroke.Color = Theme.RULE stroke.Thickness = 1 stroke.Parent = bg local name = label(bg, { Name = "AgentName", Size = UDim2.new(1, -12, 0, 22), Position = UDim2.fromOffset(6, 2), Font = Theme.FONT_BOLD, TextSize = 17, TextColor3 = Theme.CREAM, Text = tostring(agent.name) .. (GLYPH[agent.kind] or ""), }) local status = label(bg, { Name = "Status", Size = UDim2.new(1, -12, 0, 16), Position = UDim2.fromOffset(6, 23), Font = Theme.FONT_BODY, TextSize = 12, TextColor3 = Theme.CREAM, TextTransparency = 0.15, Text = "", }) local badge = label(bg, { Name = "Badge", Size = UDim2.new(1, -12, 0, 14), Position = UDim2.fromOffset(6, 40), Font = Theme.FONT_BODY, TextSize = 11, TextColor3 = Theme.CYAN, Text = "", }) local self = setmetatable({ Gui = gui, _name = name, _status = status, _badge = badge, _stroke = stroke, _grey = false, _selected = false }, Nameplate) return self end function Nameplate.SetStatus(self: any, text: string) if self._status.Text ~= text then self._status.Text = text end end function Nameplate.SetBadge(self: any, text: string, tone: string?) if self._badge.Text ~= text then self._badge.Text = text end self._badge.TextColor3 = Theme.tone(tone) end function Nameplate._paint(self: any) self._name.TextColor3 = if self._selected then Theme.GOLD elseif self._grey then Theme.GREY else Theme.CREAM self._stroke.Color = if self._selected then Theme.GOLD else Theme.RULE end function Nameplate.SetGrey(self: any, grey: boolean) self._grey = grey self:_paint() end function Nameplate.SetSelected(self: any, selected: boolean) self._selected = selected self:_paint() end function Nameplate.Destroy(self: any) self.Gui:Destroy() end return Nameplate ]]> Places Provenance ProvenanceView { mode, badge, label, detail, tone, ageMs, expired } -- status = { source = "recording" | "gateway", lastOkAt = ms?, lastError = string?, staleAfterMs = ms } -- recorded a recording (bundled, or a gateway serving one): RECORDED, with when it was recorded -- live the gateway answered within staleAfterMs and the feed says GRIFT was read fresh -- cached the feed says GRIFT stopped answering, or the gateway has not answered for staleAfterMs: the last -- good data, with its age -- unavailable nothing to show yet -- `expired` is true past the feed's validUntil: schedules have ended and agents are unknown. Pure Luau. local Types = require(script.Parent.Types) local Clock = require(script.Parent.Clock) type Feed = Types.Feed type View = Types.ProvenanceView local Provenance = {} export type Status = { source: "recording" | "gateway", lastOkAt: number?, lastError: string?, staleAfterMs: number?, } function Provenance.view(feed: Feed?, status: Status, nowMs: number): View if not feed then return { mode = "unavailable", badge = "NO DATA", label = "no GRIFT data yet" .. (if status.lastError then " · " .. status.lastError else ""), detail = "Nothing has been read from a GRIFT gateway and no recording was given. Nothing is shown rather than anything made up.", tone = "grey", ageMs = nil, expired = false, } end local p = feed.provenance local untilMs = Clock.parseIso(feed.clock.validUntil) local expired = untilMs ~= nil and nowMs >= (untilMs :: number) local ended = if expired then " · schedule ended" else "" if p.mode == "recorded" then local rec = p.recording local at = if rec then Clock.parseIso(rec.capturedAt) else nil local replay = p.replay local how = if replay and replay.startCityHour then " · replayed from " .. Clock.format(replay.startCityHour) elseif replay then " · replayed" else "" return { mode = "recorded", badge = "RECORDED", label = "RECORDED · GRIFT " .. Clock.utcDateTime(at) .. how .. ended, detail = "Real GRIFT data recorded at " .. Clock.utcDateTime(at) .. " (plan day " .. tostring(rec and rec.planDay or feed.clock.planDay) .. ") and replayed. Not live: nothing here is happening in GRIFT now." .. (if replay then " " .. replay.note .. "." else ""), tone = "cyan", ageMs = if at then nowMs - (at :: number) else nil, expired = expired, } end local readAt = Clock.parseIso(p.lastGoodAt) local ageMs = if readAt then nowMs - (readAt :: number) else nil local staleAfter = status.staleAfterMs or 90000 local gatewaySilent = status.source == "gateway" and (status.lastOkAt == nil or nowMs - (status.lastOkAt :: number) > staleAfter) if p.mode == "live" and not gatewaySilent then return { mode = "live", badge = "LIVE", label = "LIVE · GRIFT read " .. (if ageMs then Clock.age(ageMs) .. " ago" else "just now") .. ended, detail = "Read from GRIFT through a read-only gateway. Agents' plans and decisions are GRIFT's own, as of the time shown.", tone = "gold", ageMs = ageMs, expired = expired, } end local why = if gatewaySilent then "gateway not answering" .. (if status.lastError then " (" .. status.lastError .. ")" else "") else "GRIFT not answering the gateway" return { mode = "cached", badge = "CACHED", label = "CACHED · last GRIFT read " .. (if ageMs then Clock.age(ageMs) .. " ago" else "time unknown") .. " · " .. why .. ended, detail = "The last good GRIFT data, kept as it was. No new plans, decisions or events are invented while the source is silent; schedules end where the day they were read for ends.", tone = "amber", ageMs = ageMs, expired = expired, } end return Provenance ]]> Puppet a point between -- your places -> the body. No physics, no pathfinding, no inference: what the agent does and when comes from GRIFT; -- only the drawing is the engine's, and the nameplate says which is which. -- -- Pace. GRIFT times a walk by San Verano's streets; your places are as far apart as you made them. With -- pace = "natural" (the default) the agent walks at walkSpeed and sets off so that it ARRIVES WHEN GRIFT SAYS -- (hurrying over GRIFT's whole window when that pace cannot make it); with pace = "grift" it always spreads the -- walk over GRIFT's whole window. -- With space = "sanverano" it ignores your places and follows GRIFT's own coordinates (metres -> studs), for worlds -- that rebuild San Verano. local Activity = require(script.Parent.Activity) local Timeline = require(script.Parent.Timeline) local Clock = require(script.Parent.Clock) local Puppet = {} Puppet.__index = Puppet export type Options = { pace: ("natural" | "grift")?, walkSpeed: number?, -- studs per second (default 9) strollRadius: number?, -- how far a walk round the block goes from home (default 12 studs) space: ("places" | "sanverano")?, sanVerano: { studsPerMetre: number?, origin: { number }?, groundY: number? }?, } function Puppet.new(character: any, agentId: number, source: any, places: any, options: Options?) local opts = options or {} return setmetatable({ Character = character, AgentId = agentId, _source = source, _places = places, _pace = opts.pace or "natural", _walk = opts.walkSpeed or 9, _stroll = opts.strollRadius or 12, _space = opts.space or "places", _sv = opts.sanVerano or {}, _hint = nil :: number?, _last = nil :: Vector3?, Activity = nil :: any, Status = "", }, Puppet) end local function flat(v: Vector3): Vector3 return Vector3.new(v.X, 0, v.Z) end -- the point for an activity in your places; returns position, facing, and the status words function Puppet._placeSpace(self: any, agent: any, act: any, now: number): (Vector3?, Vector3?, string) local places = self._places local id = agent.id if act.state == "home" then local p = places:Spot("home", id) return p, nil, act.label elseif act.state == "strolling" then local home = places:Spot("home", id) if not home then return nil, nil, act.label end -- out and back along a fixed heading (by id); GRIFT's own stroll goes a block or two along its streets local u = act.progress or 0 local d = if u < 0.5 then u * 2 else 2 - u * 2 local heading = (id * 1.618034 * 2 * math.pi) % (2 * math.pi) local dir = Vector3.new(math.cos(heading), 0, math.sin(heading)) local facing = if u < 0.5 then dir else -dir return home + dir * d * self._stroll, facing, act.label elseif act.state == "at" then local p = places:Spot(act.place, id) local center = places:Resolve(act.place, id) local facing = if p and center and flat(center - p).Magnitude > 0.1 then center - p else nil return p, facing, act.label elseif act.state == "walking" then local from = places:Spot(act.from or "home", id) local to = places:Spot(act.place, id) if not from or not to then return to or from, nil, act.label end local t0, t1 = act.startsAt :: number, act.endsAt :: number local window = math.max((t1 - t0) / 1000, 0.001) local dist = flat(to - from).Magnitude -- natural: walk at walkSpeed and set off just in time; a walk that cannot make it at that pace takes GRIFT's -- whole window (faster, and the body runs). Either way it arrives at t1, when GRIFT says it does. local depart = t0 if self._pace == "natural" then local need = dist / self._walk if need < window then depart = t1 - need * 1000 end end if now < depart then -- not yet: GRIFT has it on its way; in your (shorter) world it sets off later and still arrives on time local label = string.format("setting off for %s at %s · %s", act.placeName or "?", Clock.format(Clock.cityHour(depart, self._source:GetFeed().clock.shiftMs)), string.match(act.label, "· (.+)$") or "") return from, to - from, label end local u = math.clamp((now - depart) / math.max(t1 - depart, 1), 0, 1) return from:Lerp(to, u), to - from, act.label end return nil, nil, act.label end function Puppet._sanVeranoSpace(self: any, agent: any, act: any, now: number): (Vector3?, Vector3?, string) local sample = Timeline.sample(agent.schedule, now, self._hint) if not sample or not sample.x then return nil, nil, act.label end local spm = self._sv.studsPerMetre or 3 local origin = self._sv.origin or { 206, 20.35 } local y = self._sv.groundY or 0 local p = Vector3.new(((sample.x :: number) - origin[1]) * spm, y, ((sample.z :: number) - origin[2]) * spm) local facing = if self._last then p - self._last else nil return p, facing, act.label end function Puppet.Step(self: any, now: number, dt: number) local source = self._source local agent = source:GetAgent(self.AgentId) local character = self.Character if not agent then return end local act = Activity.at(agent, now, source:GetFeed(), self._hint) self._hint = act.index or self._hint self.Activity = act if act.state == "unknown" then -- frozen where last seen, grey, and saying so character:SetGrey(true) character:Animate(0, dt) self.Status = act.label if character.Nameplate then character.Nameplate:SetStatus(act.label) end if not self._last then local p = if self._space == "sanverano" then nil else self._places:Spot(act.place or "home", agent.id) if p then self._last = p character:PlaceAt(p, nil, dt) end end return end character:SetGrey(false) local pos, facing, status if self._space == "sanverano" then pos, facing, status = self:_sanVeranoSpace(agent, act, now) else pos, facing, status = self:_placeSpace(agent, act, now) end self.Status = status if character.Nameplate then character.Nameplate:SetStatus(status) end if not pos then return end local speed = if self._last and dt > 0 then flat(pos - self._last).Magnitude / dt else 0 character:PlaceAt(pos, facing, dt) character:Animate(speed, dt) self._last = pos end return Puppet ]]> Replay Replicator i do local b = string.byte(s, j + 1) if b >= 0x80 and b < 0xC0 then j -= 1 else break end end table.insert(out, string.sub(s, i, j)) i = j + 1 end return out end Replicator._chunks = chunks function Replicator.publish(client: any, options: { name: string?, parent: Instance? }?) local name = (options and options.name) or Replicator.NAME local parent = (options and options.parent) or ReplicatedStorage local folder = parent:FindFirstChild(name) if not folder then folder = Instance.new("Folder") folder.Name = name folder.Parent = parent end local f = folder :: Folder local version = 0 local function write(feed: any) if not feed then return end local json = HttpService:JSONEncode(feed) local parts = chunks(json, Replicator.CHUNK) for i, part in ipairs(parts) do local v = f:FindFirstChild("Chunk" .. i) :: StringValue? if not v then local nv = Instance.new("StringValue") nv.Name = "Chunk" .. i nv.Parent = f v = nv end (v :: StringValue).Value = part end local k = #parts + 1 while f:FindFirstChild("Chunk" .. k) do (f:FindFirstChild("Chunk" .. k) :: Instance):Destroy() k += 1 end version += 1 f:SetAttribute("Chunks", #parts) f:SetAttribute("Bytes", #json) f:SetAttribute("Version", version) -- last: clients read when this changes end local function stamp() local v = client:GetProvenance() f:SetAttribute("Mode", v.mode) f:SetAttribute("Badge", v.badge) f:SetAttribute("Label", v.label) f:SetAttribute("Detail", v.detail) f:SetAttribute("Tone", v.tone) f:SetAttribute("Expired", v.expired) f:SetAttribute("AgeMs", v.ageMs or -1) end local running = true local conns = { client.Changed:Connect(function(feed) write(feed) stamp() end), client.ProvenanceChanged:Connect(stamp), } write(client:GetFeed()) stamp() task.spawn(function() while running do task.wait(1) if running then stamp() end end end) return { Folder = f, Stop = function() running = false for _, c in ipairs(conns) do c:Disconnect() end end, } end -- ---- the client side: a read-only source with the Client's reading API ------------------------------------------- local Replica = {} Replica.__index = Replica function Replicator.subscribe(options: { name: string?, parent: Instance?, timeout: number? }?) local name = (options and options.name) or Replicator.NAME local parent = (options and options.parent) or ReplicatedStorage local folder = parent:WaitForChild(name, (options and options.timeout) or 30) :: Folder? assert(folder, "GriftSDK: no " .. name .. " in " .. parent:GetFullName() .. " (call Replicator.publish(client) in a server Script)") local self = setmetatable({ Folder = folder, Changed = Signal.new(), ProvenanceChanged = Signal.new(), _feed = nil :: any, _byId = {} :: { [number]: any }, _hints = {} :: { [number]: number }, _mode = nil :: string?, }, Replica) local function read(attempt: number) local n = folder:GetAttribute("Chunks") local bytes = folder:GetAttribute("Bytes") if type(n) ~= "number" or n < 1 then return end local parts = {} for i = 1, n do local v = folder:FindFirstChild("Chunk" .. i) if not v or not v:IsA("StringValue") then parts = nil :: any break end table.insert(parts, v.Value) end local json = if parts then table.concat(parts) else nil local ok, decoded = false, nil if json and #json == bytes then ok, decoded = pcall(function() return HttpService:JSONDecode(json :: string) end) end if not ok or type(decoded) ~= "table" then -- the chunks are still arriving: try again shortly if attempt < 20 then task.delay(0.25, read, attempt + 1) end return end local valid, why = Contract.validate(decoded) if not valid then warn("[GriftSDK] replicated feed refused: " .. tostring(why)) return end self._feed = decoded self._byId = {} self._hints = {} for _, a in ipairs(decoded.agents) do self._byId[a.id] = a end self.Changed:Fire(decoded) end folder:GetAttributeChangedSignal("Version"):Connect(function() read(1) end) folder:GetAttributeChangedSignal("Mode"):Connect(function() local view = self:GetProvenance() if view.mode ~= self._mode then self._mode = view.mode self.ProvenanceChanged:Fire(view) end end) read(1) return self end function Replica.GetFeed(self: any) return self._feed end function Replica.GetAgents(self: any) return if self._feed then self._feed.agents else {} end function Replica.GetAgent(self: any, id: number) return self._byId[id] end function Replica.GetBusiness(self: any, id: string) if not self._feed then return nil end for _, b in ipairs(self._feed.businesses) do if b.id == id then return b end end return nil end function Replica.GetPlace(self: any, key: string) return if self._feed then self._feed.places[key] else nil end function Replica.GetSource(self: any, id: string?) if not id or not self._feed then return nil end return self._feed.provenance.sources[id] end function Replica.Now(_self: any): number return Clock.nowMs() end function Replica.CityHour(self: any): number? if not self._feed then return nil end return Clock.cityHour(Clock.nowMs(), self._feed.clock.shiftMs) end function Replica.ActivityOf(self: any, id: number, ms: number?) local agent = self._byId[id] if not agent then return nil end local act = Activity.at(agent, ms or Clock.nowMs(), self._feed, self._hints[id]) if act.index then self._hints[id] = act.index end return act end -- the server's view of the data's provenance (it alone knows when the gateway last answered) function Replica.GetProvenance(self: any) local f = self.Folder local mode = f:GetAttribute("Mode") if type(mode) ~= "string" then return { mode = "unavailable", badge = "NO DATA", label = "waiting for the server's GRIFT data", detail = "", tone = "grey", expired = false } end local age = f:GetAttribute("AgeMs") return { mode = mode, badge = f:GetAttribute("Badge") or "", label = f:GetAttribute("Label") or "", detail = f:GetAttribute("Detail") or "", tone = f:GetAttribute("Tone") or "grey", expired = f:GetAttribute("Expired") == true, ageMs = if type(age) == "number" and age >= 0 then age else nil, } end return Replicator ]]> Signal () } export type Signal = { Connect: (self: Signal, fn: (...any) -> ()) -> Connection, Once: (self: Signal, fn: (...any) -> ()) -> Connection, Fire: (self: Signal, ...any) -> (), DisconnectAll: (self: Signal) -> (), } local Signal = {} Signal.__index = Signal local spawnHandler: (fn: (...any) -> (), ...any) -> () do local t = (task :: any) if t ~= nil and type(t.spawn) == "function" then spawnHandler = function(fn, ...) t.spawn(fn, ...) end else spawnHandler = function(fn, ...) local ok, err = pcall(fn, ...) if not ok then print("[GriftSDK] a signal handler failed: " .. tostring(err)) end end end end function Signal.new(): Signal return (setmetatable({ _handlers = {} }, Signal) :: any) :: Signal end function Signal.Connect(self: any, fn: (...any) -> ()): Connection assert(type(fn) == "function", "Signal:Connect expects a function") local handler = { fn = fn, connected = true } table.insert(self._handlers, handler) local connection = { Connected = true } function connection.Disconnect(c: any) if not handler.connected then return end handler.connected = false c.Connected = false local list = self._handlers for i = #list, 1, -1 do if list[i] == handler then table.remove(list, i) end end end return (connection :: any) :: Connection end function Signal.Once(self: any, fn: (...any) -> ()): Connection local connection: Connection connection = Signal.Connect(self, function(...) connection:Disconnect() fn(...) end) return connection end function Signal.Fire(self: any, ...: any) -- a copy, so a handler that connects or disconnects during Fire does not disturb this round local list = table.clone(self._handlers) for _, handler in ipairs(list) do if handler.connected then spawnHandler(handler.fn, ...) end end end function Signal.DisconnectAll(self: any) for _, handler in ipairs(self._handlers) do handler.connected = false end table.clear(self._handlers) end return Signal ]]> Theme Timeline that point; `path` -> the vertices bracketing ms, interpolated linearly -- lastSeen(schedule, ms) the latest segment that ended at or before ms (for an agent past its schedule) -- No segment covering an instant means the agent is UNKNOWN then: draw it where it was last seen, doing nothing new. local Types = require(script.Parent.Types) type Segment = Types.Segment local Timeline = {} export type Sample = { kind: string, place: string?, x: number?, z: number?, segment: Segment, index: number, } function Timeline.segmentAt(schedule: { Segment }, ms: number, hint: number?): (Segment?, number?) local n = #schedule if n == 0 then return nil, nil end -- try the hint and its neighbours first (an agent is usually in the segment it was in last frame) if hint and hint >= 1 and hint <= n then for i = hint, math.min(hint + 2, n) do local s = schedule[i] if ms >= s.t0 and ms < s.t1 then return s, i end end end -- binary search: segments are contiguous and ordered local lo, hi = 1, n while lo <= hi do local mid = (lo + hi) // 2 local s = schedule[mid] if ms < s.t0 then hi = mid - 1 elseif ms >= s.t1 then lo = mid + 1 else return s, mid end end return nil, nil end function Timeline.sample(schedule: { Segment }, ms: number, hint: number?): Sample? local s, i = Timeline.segmentAt(schedule, ms, hint) if not s or not i then return nil end local sv = s.sv if sv and sv.at then return { kind = s.kind, place = s.place, x = sv.at[1], z = sv.at[2], segment = s, index = i } end local p = if sv then sv.path else nil if not p or #p < 2 then return { kind = s.kind, place = s.place, x = nil, z = nil, segment = s, index = i } end local j = 2 while j < #p and p[j][1] < ms do j += 1 end local a, b = p[j - 1], p[j] local f = 1 if b[1] > a[1] then f = math.clamp((ms - a[1]) / (b[1] - a[1]), 0, 1) end return { kind = s.kind, place = s.place, x = a[2] + (b[2] - a[2]) * f, z = a[3] + (b[3] - a[3]) * f, segment = s, index = i } end function Timeline.lastSeen(schedule: { Segment }, ms: number): Segment? local best: Segment? = nil for _, s in ipairs(schedule) do if s.t1 <= ms and (best == nil or s.t1 > (best :: Segment).t1) then best = s end end return best end function Timeline.bounds(schedule: { Segment }): (number?, number?) if #schedule == 0 then return nil, nil end return schedule[1].t0, schedule[#schedule].t1 end return Timeline ]]> Types Recordings SanVerano_20261108