cluaupp 1.0.0 → 1.4.0

package/runtime/Keep/Engine.luau

@@ -0,0 +1,211 @@
+--!strict
+-- Kernel bridge for CL++ Server/Client. Path tokens, Keep Store, Data,
+-- tagged-buffer replication, and Spark stay Luau — CL++ 0.3.2 cannot express
+-- type functions, metatable path tokens, or rawset overlays.
+
+local RunService = game:GetService("RunService")
+
+local Path = require(script.Parent.Path)
+local Data = require(script.Parent.Data)
+local Enums = require(script.Parent.Enums)
+local EnumModule = require(script.Parent.Enum)
+local Store = require(script.Parent.Store)
+local Trade = require(script.Parent.Trade)
+local ReplicatorModule = require(script.Parent.Replicator)
+local Spark = require(script.Parent.Parent.Spark)
+
+local Engine = {}
+
+Engine.Path = Path
+Engine.Data = Data
+Engine.ProfileStore = Store
+Engine.Store = Store
+Engine.Trade = Trade
+Engine.Enums = Enums
+Engine.Enum = EnumModule
+Engine.Signal = Spark
+Engine.Spark = Spark
+Engine.Replicator = if RunService:IsServer() then ReplicatorModule.Server else ReplicatorModule.Client
+
+function Engine:mapNew()
+	return {}
+end
+
+function Engine:mapSet(map: any, key: any, value: any)
+	if map then
+		map[key] = value
+	end
+end
+
+function Engine:mapGet(map: any, key: any): any
+	if map == nil then
+		return nil
+	end
+	return map[key]
+end
+
+function Engine:mapClear(map: any, key: any)
+	if map then
+		map[key] = nil
+	end
+end
+
+function Engine:createTemplatePaths(tmpl: any)
+	return Path.createTemplatePaths(tmpl)
+end
+
+function Engine:rootToken()
+	return Path.rootToken()
+end
+
+function Engine:toKey(path: any): string
+	return Path.toKey(path)
+end
+
+function Engine:parentPath(path: any)
+	return Path.parent(path)
+end
+
+function Engine:emptyPath()
+	return {}
+end
+
+function Engine:dataNew(initial: any, writable: boolean, strictPaths: boolean?, autoCreate: boolean?, tmpl: any)
+	return Data.new(initial, writable, {
+		StrictPaths = if strictPaths ~= nil then strictPaths else true,
+		AutoCreateMissingTables = if autoCreate ~= nil then autoCreate else false,
+		Template = if tmpl ~= nil then tmpl else initial,
+	})
+end
+
+function Engine:applySet(data: any, path: any, value: any)
+	Data._applySet(data, path, value)
+end
+
+function Engine:applyArrayInsert(data: any, path: any, value: any, index: number?)
+	Data._applyArrayInsert(data, path, value, index)
+end
+
+function Engine:applyArrayRemove(data: any, path: any, index: number)
+	Data._applyArrayRemove(data, path, index)
+end
+
+function Engine:applyTransientSet(data: any, path: any, value: any)
+	Data._applyTransientSet(data, path, value)
+end
+
+function Engine:applyTransientArrayInsert(data: any, path: any, value: any, index: number?)
+	Data._applyTransientArrayInsert(data, path, value, index)
+end
+
+function Engine:applyTransientArrayRemove(data: any, path: any, index: number)
+	Data._applyTransientArrayRemove(data, path, index)
+end
+
+function Engine:applyTransientClear(data: any, path: any)
+	Data._applyTransientClear(data, path)
+end
+
+function Engine:profileStoreNew(storeName: string, tmpl: any)
+	return Store.New(storeName, tmpl)
+end
+
+function Engine:startSession(store: any, key: string, player: Player, players: Players)
+	local profile = store:StartSessionAsync(key, {
+		Cancel = function()
+			return player.Parent ~= players
+		end,
+	})
+	if profile then
+		profile:AddUserId(player.UserId)
+		Trade.Ensure(profile.Data)
+		profile:MessageHandler(function(message, processed)
+			Trade.HandleMessage(profile, message, processed)
+		end)
+	end
+	return profile
+end
+
+function Engine:abortActiveTrade(profile: any)
+	Trade.AbortIfActive(profile)
+end
+
+function Engine:signalNew()
+	return Spark.new()
+end
+
+function Engine:isExcluded(excluded: { [string]: boolean }?, path: any): boolean
+	if not path or #path == 0 then
+		return false
+	end
+	if not excluded then
+		return false
+	end
+	for i = 1, #path do
+		local prefix = table.create(i)
+		for j = 1, i do
+			prefix[j] = path[j]
+		end
+		if excluded[Path.toKey(prefix)] then
+			return true
+		end
+	end
+	return false
+end
+
+function Engine:buildSnapshot(excluded: { [string]: boolean }?, value: any, prefix: any): any
+	local path = prefix or {}
+	if Engine:isExcluded(excluded, path) then
+		return nil
+	end
+	if type(value) ~= "table" then
+		return value
+	end
+	local out = {}
+	for k, v in value do
+		local newPath = table.clone(path)
+		newPath[#newPath + 1] = k
+		if not Engine:isExcluded(excluded, newPath) then
+			out[k] = Engine:buildSnapshot(excluded, v, newPath)
+		end
+	end
+	return out
+end
+
+function Engine:watchData(data: any, player: Player, ready: { [Player]: boolean }, excluded: { [string]: boolean })
+	return data.Changed:Connect(function(action, path, ...)
+		if not ready[player] then
+			return
+		end
+		if Engine:isExcluded(excluded, path) then
+			return
+		end
+		Engine.Replicator:Send(player, action, path, ...)
+	end)
+end
+
+function Engine:replicatorOn(action: string, handler: any)
+	Engine.Replicator:On(action, handler)
+end
+
+function Engine:replicatorNotifyReady()
+	Engine.Replicator:NotifyReady()
+end
+
+function Engine:replicatorSend(player: Player, action: string, path: any, ...)
+	Engine.Replicator:Send(player, action, path, ...)
+end
+
+function Engine:replicatorGetBufferStats(player: Player?)
+	return Engine.Replicator:GetBufferStats(player)
+end
+
+function Engine:replicatorForgetPlayer(player: Player)
+	Engine.Replicator:ForgetPlayer(player)
+end
+
+function Engine:replicatorDestroy()
+	Engine.Replicator:Destroy()
+end
+
+return Engine

package/runtime/Keep/Replicator.luau

@@ -0,0 +1,298 @@
+--!native
+--!optimize 2
+--!strict
+-- Keep replicator — tagged buffers (Ready / Snapshot / Delta). No JSON, no QuickNet.
+
+local RunService = game:GetService("RunService")
+local Spark = require(script.Parent.Parent.Spark)
+local Ward = require(script.Parent.Parent.Ward)
+
+local TAG = {
+	Ready = 1,
+	Snapshot = 2,
+	Delta = 3,
+	Init = 4,
+	Set = 5,
+	ArrayInsert = 6,
+	ArrayRemove = 7,
+	TransientSet = 8,
+}
+
+local ACTION_TAG = {
+	i = TAG.Init,
+	s = TAG.Set,
+	ai = TAG.ArrayInsert,
+	ar = TAG.ArrayRemove,
+	ts = TAG.TransientSet,
+	ready = TAG.Ready,
+	snapshot = TAG.Snapshot,
+	delta = TAG.Delta,
+}
+
+local TAG_ACTION = {}
+for name, id in ACTION_TAG do
+	TAG_ACTION[id] = name
+end
+
+local TYPE = { Nil = 0, Bool = 1, Number = 2, String = 3, Table = 4 }
+
+local function grow(buf: buffer, need: number): buffer
+	if buffer.len(buf) >= need then
+		return buf
+	end
+	local nextBuf = buffer.create(math.max(need, buffer.len(buf) * 2))
+	buffer.copy(nextBuf, 0, buf, 0, buffer.len(buf))
+	return nextBuf
+end
+
+local function writeString(buf: buffer, cursor: number, text: string): (buffer, number)
+	buf = grow(buf, cursor + 2 + #text)
+	buffer.writeu16(buf, cursor, #text)
+	buffer.writestring(buf, cursor + 2, text)
+	return buf, cursor + 2 + #text
+end
+
+local function readString(buf: buffer, cursor: number): (string, number)
+	local length = buffer.readu16(buf, cursor)
+	return buffer.readstring(buf, cursor + 2, length), cursor + 2 + length
+end
+
+local writeValue: (buffer, number, any) -> (buffer, number)
+local readValue: (buffer, number) -> (any, number)
+
+writeValue = function(buf: buffer, cursor: number, value: any): (buffer, number)
+	local kind = typeof(value)
+	buf = grow(buf, cursor + 16)
+	if value == nil then
+		buffer.writeu8(buf, cursor, TYPE.Nil)
+		return buf, cursor + 1
+	end
+	if kind == "boolean" then
+		buffer.writeu8(buf, cursor, TYPE.Bool)
+		buffer.writeu8(buf, cursor + 1, if value then 1 else 0)
+		return buf, cursor + 2
+	end
+	if kind == "number" then
+		buffer.writeu8(buf, cursor, TYPE.Number)
+		buffer.writef64(buf, cursor + 1, value)
+		return buf, cursor + 9
+	end
+	if kind == "string" then
+		buffer.writeu8(buf, cursor, TYPE.String)
+		return writeString(buf, cursor + 1, value)
+	end
+	if kind == "table" then
+		buffer.writeu8(buf, cursor, TYPE.Table)
+		cursor += 1
+		local count = 0
+		for _ in value do
+			count += 1
+		end
+		buf = grow(buf, cursor + 2)
+		buffer.writeu16(buf, cursor, count)
+		cursor += 2
+		for key, item in value do
+			buf, cursor = writeValue(buf, cursor, key)
+			buf, cursor = writeValue(buf, cursor, item)
+		end
+		return buf, cursor
+	end
+	buffer.writeu8(buf, cursor, TYPE.Nil)
+	return buf, cursor + 1
+end
+
+readValue = function(buf: buffer, cursor: number): (any, number)
+	local kind = buffer.readu8(buf, cursor)
+	cursor += 1
+	if kind == TYPE.Nil then
+		return nil, cursor
+	end
+	if kind == TYPE.Bool then
+		return buffer.readu8(buf, cursor) == 1, cursor + 1
+	end
+	if kind == TYPE.Number then
+		return buffer.readf64(buf, cursor), cursor + 8
+	end
+	if kind == TYPE.String then
+		return readString(buf, cursor)
+	end
+	if kind == TYPE.Table then
+		local count = buffer.readu16(buf, cursor)
+		cursor += 2
+		local out = {}
+		for _ = 1, count do
+			local key
+			key, cursor = readValue(buf, cursor)
+			local item
+			item, cursor = readValue(buf, cursor)
+			out[key] = item
+		end
+		return out, cursor
+	end
+	return nil, cursor
+end
+
+local function pack(action: string, path: any, payload: { any }): buffer
+	local buf = buffer.create(64)
+	buffer.writeu8(buf, 0, ACTION_TAG[action] or TAG.Delta)
+	local cursor = 1
+	buf, cursor = writeValue(buf, cursor, path)
+	buf, cursor = writeValue(buf, cursor, payload)
+	local trimmed = buffer.create(cursor)
+	buffer.copy(trimmed, 0, buf, 0, cursor)
+	return trimmed
+end
+
+local function unpackPacket(buf: buffer): (string, any, { any })
+	local tag = buffer.readu8(buf, 0)
+	local path
+	local cursor
+	path, cursor = readValue(buf, 1)
+	local payload
+	payload, cursor = readValue(buf, cursor)
+	return TAG_ACTION[tag] or "s", path, if typeof(payload) == "table" then payload else { payload }
+end
+
+local function folder(): Folder
+	local rs = game:GetService("ReplicatedStorage")
+	local existing = rs:FindFirstChild("KeepNet")
+	if existing and existing:IsA("Folder") then
+		return existing
+	end
+	local created = Instance.new("Folder")
+	created.Name = "KeepNet"
+	created.Parent = rs
+	local reliable = Instance.new("RemoteEvent")
+	reliable.Name = "Reliable"
+	reliable.Parent = created
+	return created
+end
+
+local net = folder()
+local remote = net:WaitForChild("Reliable") :: RemoteEvent
+
+local function emptyStats()
+	return {
+		Bytes = 0,
+		Messages = 0,
+		LastPacketBytes = 0,
+		LastUtilization = 0,
+		TotalBytes = 0,
+		TotalMessages = 0,
+		ByPlayer = {},
+	}
+end
+
+local Server = {
+	OnReady = Spark.new(),
+	BufferChanged = Spark.new(),
+	_stats = emptyStats(),
+	_handlers = {} :: { [string]: (...any) -> () },
+	_ready = {} :: { [Player]: boolean },
+}
+
+local Client = {
+	OnReady = Spark.new(),
+	BufferChanged = Spark.new(),
+	_stats = emptyStats(),
+	_handlers = {} :: { [string]: (...any) -> () },
+}
+
+if RunService:IsServer() then
+	remote.OnServerEvent:Connect(function(player: Player, packed: buffer?)
+		if typeof(packed) ~= "buffer" then
+			Ward.Strike(player, "keep:type")
+			return
+		end
+		if not Ward.Packet(player, buffer.len(packed), 256) then
+			return
+		end
+		if not Ward.Allow(player, "keep", 4, 8) then
+			return
+		end
+		local ok, action = pcall(unpackPacket, packed)
+		if not ok or action ~= "ready" then
+			Ward.Strike(player, "keep:action")
+			return
+		end
+		if Server._ready[player] then
+			return
+		end
+		Server._ready[player] = true
+		Server.OnReady:Fire(player)
+	end)
+
+	function Server:On(action: string, handler: (...any) -> ())
+		self._handlers[action] = handler
+	end
+
+	function Server:Send(player: Player, action: string, path: any, ...)
+		local payload = table.pack(...)
+		local packed = pack(action, path, payload)
+		local bytes = buffer.len(packed)
+		local byPlayer = self._stats.ByPlayer[player]
+		if not byPlayer then
+			byPlayer = emptyStats()
+			self._stats.ByPlayer[player] = byPlayer
+		end
+		byPlayer.Bytes += bytes
+		byPlayer.Messages += 1
+		byPlayer.LastPacketBytes = bytes
+		byPlayer.LastUtilization = math.clamp(bytes / 1024, 0, 1)
+		self._stats.TotalBytes += bytes
+		self._stats.TotalMessages += 1
+		self._stats.LastPacketBytes = bytes
+		remote:FireClient(player, packed)
+	end
+
+	function Server:GetBufferStats(player: Player?)
+		if player then
+			return self._stats.ByPlayer[player]
+		end
+		return self._stats
+	end
+
+	function Server:ForgetPlayer(player: Player)
+		self._stats.ByPlayer[player] = nil
+		self._ready[player] = nil
+	end
+
+	function Server:Destroy()
+		Server.OnReady:Destroy()
+		Server.BufferChanged:Destroy()
+	end
+else
+	function Client:On(action: string, handler: (...any) -> ())
+		self._handlers[action] = handler
+	end
+
+	function Client:NotifyReady()
+		remote:FireServer(pack("ready", {}, {}))
+	end
+
+	remote.OnClientEvent:Connect(function(packed: buffer)
+		local action, path, payload = unpackPacket(packed)
+		Client._stats.LastPacketBytes = buffer.len(packed)
+		Client._stats.Bytes += Client._stats.LastPacketBytes
+		Client._stats.Messages += 1
+		Client.BufferChanged:Fire(Client._stats)
+		local handler = Client._handlers[action]
+		if handler then
+			handler(path, table.unpack(payload, 1, payload.n or #payload))
+		end
+		if action == "ready" or action == "i" then
+			Client.OnReady:Fire()
+		end
+	end)
+
+	function Client:GetBufferStats()
+		return Client._stats
+	end
+
+	function Client:Destroy()
+		Client.OnReady:Destroy()
+		Client.BufferChanged:Destroy()
+	end
+end
+
+return { Server = Server, Client = Client, TAG = TAG }