cluaupp 0.1.0

package/runtime/Chrono/Shared/Ticker.luau

@@ -0,0 +1,112 @@
+const RunService = game:GetService("RunService")
+const Ticker = {}
+
+--//TODO: this should be in server since client don't use it, maybe move later
+
+const function popSwap(t, item, index)
+	const lastIndex = #t
+	if index ~= lastIndex then
+		const lastItem = t[lastIndex]
+		t[index] = lastItem
+		lastItem._tickerIndex = index
+	end
+	t[lastIndex] = nil
+end
+
+const Types = require(script.Parent.Types)
+const Warn = require(script.Parent.Warn)
+type Entity = Types.Entity
+type Ticker = Types.Ticker
+
+local GlobalTick = 0
+
+function Ticker._IncrementGlobalTick()
+	GlobalTick += 1
+end
+
+function Ticker.GetGlobalTick()
+	return GlobalTick
+end
+
+function Ticker.new(config: Types.EntityConfig): Ticker
+	const ticker = {
+		tickedHalf = false,
+		tickHalfRate = config.TICK_RATE * 2,
+		tickRate = config.TICK_RATE,
+		lastTicked = 0,
+		tickedFrame = 0,
+		objects = {},
+		callbacks = {},
+		config = config,
+		dt = 0,
+		halfdt = 0,
+	}
+	return ticker
+end
+
+function Ticker.AddCallback(ticker: Ticker, callback: (ticker: Ticker, dt: number) -> ())
+	table.insert(ticker.callbacks, callback)
+end
+
+function Ticker.RemoveCallback(ticker: Ticker, callback: (ticker: Ticker, dt: number) -> ())
+	const index = table.find(ticker.callbacks, callback)
+	if index then
+		table.remove(ticker.callbacks, index)
+	end
+end
+
+function Ticker.Add(ticker: Ticker, object: Entity)
+	table.insert(ticker.objects, object)
+	object._ticker = ticker
+	object._tickerIndex = #ticker.objects
+end
+
+function Ticker.Remove(ticker: Ticker, object: Entity)
+	const index = object._tickerIndex
+	if not index then
+		Warn.low("Ticker.remove called on object not in ticker", object.id)
+		return
+	end
+
+	popSwap(ticker.objects :: any, object, index)
+
+	object._ticker = nil
+	object._tickerIndex = nil
+end
+
+function Ticker.move(object: Entity, newTicker: Ticker)
+	const oldTicker = object._ticker
+	if oldTicker then
+		Ticker.Remove(oldTicker, object)
+	end
+	Ticker.Add(newTicker, object)
+end
+
+function Ticker.CheckUpdate(ticker: Ticker): boolean
+	const difference = os.clock() - ticker.lastTicked
+
+	if difference >= ticker.tickRate then
+		ticker.lastTicked = os.clock()
+		ticker.tickedFrame = GlobalTick
+		ticker.tickedHalf = not ticker.tickedHalf
+
+		if ticker.tickedHalf then
+			ticker.halfdt = difference + ticker.dt
+		else
+			ticker.halfdt = difference
+		end
+
+		ticker.dt = difference
+		if #ticker.callbacks > 0 then
+			for _, callback in ticker.callbacks do
+				callback(ticker, difference)
+			end
+		end
+
+		return true
+	end
+
+	return false
+end
+
+return Ticker

package/runtime/Chrono/Shared/Types.luau

@@ -0,0 +1,247 @@
+export type SnapshotData<Value = CFrame, Velocity = Vector3> = {
+	t: number,
+	value: Value,
+	velocity: Velocity,
+}
+
+--// FX is the function template for the events.
+export type Signal<fx, T...> = {
+	Fire: (self: any, T...) -> (),
+	DisconnectAll: (self: any) -> (),
+	Event: Event<fx, T...>,
+}
+
+export type ClientEntitiesStats = {
+	id: number,
+	entity: Entity,
+	networkOwner: Player?,
+	isCharacter: boolean,
+	config: string,
+	lastReceivedTime: number?,
+	lastReplicatedTime: number?,
+
+	averageLatency: number?,
+	targetTime: number?,
+	deviation: number?,
+	bufferedTime: number?,
+	currentPosition: Vector3?,
+	snapshots: {
+		t: number,
+		value: CFrame,
+	},
+}
+
+export type ServerEntitiesStats = {
+	id: number,
+	isPaused: boolean,
+	networkOwner: Player?,
+	isCharacter: boolean,
+	config: string,
+	tickRate: number?,
+	lastTicked: number?,
+	lastPosition: Vector3,
+	modelType: string?,
+}
+export type Connection = {
+	Disconnect: (self: any) -> (),
+	Connected: boolean,
+	_binCleanup: () -> (),
+}
+
+export type Event<fx, T...> = {
+	Connect: (self: any, FN: fx, defer: boolean?) -> Connection,
+	Once: (self: any, FN: fx, defer: boolean?) -> Connection,
+	Wait: (self: any, defer: boolean?) -> T...,
+	_binCleanup: () -> (),
+}
+
+export type Snapshot<Value, Velocity> = {
+	cache: { SnapshotData<Value, Velocity> },
+	head: number,
+	count: number,
+	lockedTime: number,
+	Lerp: (p0: Vector3, p1: Vector3, v0: Velocity, v1: Velocity, t: number, dt: number) -> Vector3,
+
+	Push: (self: Snapshot<Value, Velocity>, t: number, value: Value, velocity: Velocity) -> (),
+	PushWithCheck: (
+		self: Snapshot<Value, Velocity>,
+		t: number,
+		value: Value,
+		velocity: Velocity,
+		tickrate: number
+	) -> (),
+
+	GetLatest: (self: Snapshot<Value, Velocity>) -> SnapshotData<Value, Velocity>?,
+	GetAt: (self: Snapshot<Value, Velocity>, t: number, bypassLock: boolean?) -> Value?,
+	Clear: (self: Snapshot<Value, Velocity>) -> (),
+}
+
+export type PlayerEntityHolder = {
+	PLAYER: Player,
+	HALF: { Entity },
+	NORMAL: { Entity },
+	_TEMP_HALF: { Entity },
+	_TEMP_NORMAL: { Entity },
+	REPLICATED: { [Entity]: true },
+	EntityAdded: Signal<(Entity) -> (), Entity>,
+	EntityRemoving: Signal<(Entity) -> (), Entity>,
+}
+
+export type MODEL_REPLICATION_MODE = "NATIVE" | "NATIVE_WITH_LOCK" | "CUSTOM"
+export type EntityConfig = {
+	NAME: string,
+	TICKER: Ticker?,
+	CLIENT_CLOCK: {
+		NORMAL: ClientClock?,
+		HALF: ClientClock?,
+	}?,
+
+	BUFFER: number,
+	TICK_RATE: number,
+	FULL_ROTATION: boolean?, -- defaults to false
+	AUTO_UPDATE_POSITION: boolean?, -- defaults to true
+	STORE_SNAPSHOTS: boolean?, -- defaults to false
+	MODEL_REPLICATION_MODE: MODEL_REPLICATION_MODE?,
+	NORMAL_TICK_DISTANCE: number?,
+	HALF_TICK_DISTANCE: number?,
+	CUSTOM_INTERPOLATION: boolean?,
+	ASSEMBLY_ROOT_PART_CHECK: boolean?,
+	ATTACH_MODEL_META_DATA: boolean?, -- defaults to true
+	UpdateBuffer: (self: EntityConfig, buffer: number) -> ()?,
+}
+
+export type EntityConfigInput = {
+	BUFFER: number,
+	TICK_RATE: number,
+	FULL_ROTATION: boolean?,
+	AUTO_UPDATE_POSITION: boolean?, -- If false have to manually call Entity.push
+	STORE_SNAPSHOTS: boolean?, -- Should snapshots be stored on the server. Excludes client owned
+	MODEL_REPLICATION_MODE: MODEL_REPLICATION_MODE?,
+	ASSEMBLY_ROOT_PART_CHECK: boolean?, -- If true, will check if the primary part is the root part of the model or inside the model.
+
+	NORMAL_TICK_DISTANCE: number?,
+	HALF_TICK_DISTANCE: number?,
+	CUSTOM_INTERPOLATION: boolean?,
+	ATTACH_MODEL_META_DATA: boolean?, -- if explicitly false then chrono will not attach meta data. See shared/ModelHelper
+	-- Might consider giving a config level replication rules instead of just entity
+}
+
+export type Ticker = {
+	tickedHalf: boolean,
+	tickRate: number,
+	tickHalfRate: number,
+	lastTicked: number,
+	tickedFrame: number,
+	objects: { Entity },
+	callbacks: { (ticker: Ticker, dt: number) -> () },
+	config: EntityConfig,
+	dt: number,
+	halfdt: number,
+}
+
+export type InterpolationBuffer = {
+	init: boolean,
+	averageLatency: number,
+	deviation: number,
+	lastLatency: number,
+	clientClock: ClientClock,
+}
+
+export type ClientClock = {
+	name: string,
+	lastClockAt: number?,
+	lastClockDuration: number,
+	renderAt: number?,
+	tickRate: number,
+	_baseTickRate: number,
+	_owner: Player?,
+	buffer: InterpolationBuffer?,
+	bufferConst: number?,
+
+	Clear: (self: ClientClock) -> (),
+	GetTargetRenderTime: (self: ClientClock) -> number,
+	GetEstimatedServerTime: (self: ClientClock) -> number,
+	OnSnapShot: (self: ClientClock, currentTime: number) -> (),
+	Refresh: (self: ClientClock, currentTime: number) -> boolean,
+	SetTickRate: (self: ClientClock, tickRate: number) -> (),
+	UpdateBuffer: (self: ClientClock, time: number?) -> (),
+	Destroy: (self: ClientClock) -> (),
+}
+
+export type ReplicationRule = {}
+
+export type EntityReceivePacket = {
+	id: number,
+	_player: Player?,
+	networkOwner: Player?,
+	time: number,
+	cframe: CFrame,
+	config: string?,
+	model: string | Model | BasePart?,
+	paused: boolean?,
+	isHalfTicked: boolean?,
+	_data: any,
+	mountParentId: number?,
+	mountOffset: CFrame?,
+	broadPhase: vector?,
+	_modelMetaData: string?,
+	_lockedCFReplication: boolean?,
+}
+
+export type Entity = {
+	--Client
+	-- this is for non server owned
+	_clockBuffer: number?,
+	_clientClock: ClientClock?,
+	_modelMetaData: string?,
+	broadPhase: vector?,
+	interpolation: boolean,
+	_outofBroadPhaseTick: number?,
+	_teleport: number?,
+	--Server
+	autoUpdatePosition: boolean,
+	replicationRules: { ReplicationRule }?,
+	_ticker: Ticker?,
+	_tickerIndex: number?,
+
+	--NetworkOwner
+	isContextOwner: boolean,
+	networkOwner: Player?,
+	_player: Player?,
+	_cfLockFailed: boolean?,
+
+	snapshot: Snapshot<CFrame, Vector3>?,
+	latestCFrame: CFrame?,
+	latestTime: number?,
+
+	isHalfTicked: boolean?,
+	id: number,
+	entityConfig: EntityConfig, -- defaults to DEFAULT config
+	modelString: string?,
+	model: Model | BasePart?,
+	paused: boolean,
+
+	modelReplicationMode: "NATIVE" | "CUSTOM"?,
+
+	lastCheckedCFrame: CFrame?,
+
+	lastReplicatedTime: number?,
+	arriveFrame: number?, -- This is only for client owned on the server
+	lastClientClock: number?,
+
+	cframeBuffer: buffer?,
+	registered: boolean,
+	destroyed: boolean,
+
+	_lockedCFReplication: boolean?,
+	_data: any,
+	_changes: { { string | any } }?,
+	_events: { [string]: Signal<any, any> }?,
+	_lastId: number?,
+	_chronoPrimary: string?,
+
+	mountParentId: number?,
+	mountOffset: CFrame?,
+}
+
+return nil

package/runtime/Chrono/Shared/Warn.luau

@@ -0,0 +1,33 @@
+const Config = require(script.Parent.Config)
+
+type level = Config.WarningLevels
+
+const function checkLevel(level: level): boolean
+	const levels: { [level]: number } = {
+		NONE = 0,
+		LOW = 1,
+		MEDIUM = 2,
+		HIGH = 3,
+	}
+	const currentLevel = levels[Config._GetConfig("WARNING_SEVERITY") :: level] or 0
+	if currentLevel == 0 then
+		return false
+	end
+	const checkAgainst = levels[level] or 0
+	return currentLevel <= checkAgainst
+end
+
+return (
+	setmetatable({}, {
+		__index = function(_, level: level)
+			if not checkLevel(level:upper()) then
+				return function() end
+			end
+			return warn
+		end,
+	}) :: any
+) :: {
+	low: (...any) -> (),
+	medium: (...any) -> (),
+	high: (...any) -> (),
+}

package/runtime/Chrono/Shared/_CUSTOM_MODEL_REP/init.model.json

@@ -0,0 +1,3 @@
+{
+    "ClassName": "Model"
+}

package/runtime/Chrono/_impl/Client/ClientClock.luau

@@ -0,0 +1,202 @@
+const RunService = game:GetService("RunService")
+
+const Warn = require(script.Parent.Parent.Shared.Warn)
+const Config = require(script.Parent.Parent.Shared.Config)
+const Types = require(script.Parent.Parent.Shared.Types)
+const BufferTracker = require(script.Parent.InterpolationBuffer)
+
+const ClientClocks = {}
+const _ServerOwnedClocks = {}
+
+const function GetBuffer(clientClock: Types.ClientClock): number
+	if clientClock.buffer then
+		return BufferTracker.GetBuffer(clientClock.buffer, clientClock.tickRate)
+	else
+		return clientClock.bufferConst or 0
+	end
+end
+
+const function Clear(clientClock: Types.ClientClock)
+	clientClock.lastClockAt = nil
+	clientClock.lastClockDuration = 0
+	clientClock.renderAt = nil
+
+	if clientClock.buffer then
+		clientClock.buffer.init = false
+	end
+end
+
+const function GetTargetRenderTime(clientClock: Types.ClientClock): number
+	if not clientClock.renderAt then
+		Warn.low("ClientClock: Render time not yet established for", clientClock.name)
+		return 0
+	end
+
+	return clientClock.renderAt
+end
+
+const function GetEstimatedServerTime(clientClock: Types.ClientClock): number
+	if not clientClock.lastClockAt then
+		Warn.low("ClientClock: Estimated server time not yet established for", clientClock.name)
+		return 0
+	end
+
+	return clientClock.lastClockAt + (os.clock() - clientClock.lastClockDuration)
+end
+
+const function CheckHasLastClockAt(clientClock: Types.ClientClock, sendTime: number)
+	if not clientClock.lastClockAt then
+		clientClock.lastClockAt = sendTime
+		clientClock.lastClockDuration = os.clock()
+		clientClock.renderAt = nil
+	end
+end
+
+const function Refresh(clientClock: Types.ClientClock, currentSendTime: number): boolean
+	if not clientClock.lastClockAt then
+		CheckHasLastClockAt(clientClock, currentSendTime)
+		return false
+	end
+
+	if currentSendTime > clientClock.lastClockAt then
+		clientClock.lastClockAt = currentSendTime
+		clientClock.lastClockDuration = os.clock()
+		return true
+	end
+
+	return false
+end
+
+const function OnSnapShot(clientClock: Types.ClientClock, currentSendTime: number)
+	if not clientClock.lastClockAt then
+		CheckHasLastClockAt(clientClock, currentSendTime)
+		return
+	end
+
+	if clientClock.buffer then
+		BufferTracker.Register(clientClock.buffer, currentSendTime)
+	end
+
+	if Refresh(clientClock, currentSendTime) and not clientClock.renderAt then
+		clientClock.renderAt = currentSendTime - GetBuffer(clientClock)
+	end
+end
+
+const function SetTickRate(clientClock: Types.ClientClock, tickRate: number)
+	if clientClock.tickRate == tickRate then
+		return
+	end
+	clientClock.tickRate = tickRate
+	--//Do something here maybe?
+end
+
+const function Destroy(clientClock: Types.ClientClock)
+	ClientClocks[clientClock] = nil
+	if _ServerOwnedClocks[clientClock] then
+		_ServerOwnedClocks[clientClock] = nil
+	end
+end
+
+const function Update(clientClock: Types.ClientClock, dt: number)
+	const now = os.clock()
+	const delay = GetBuffer(clientClock)
+	if not clientClock.lastClockAt then
+		return
+	end
+	const estimatedServerTime = clientClock.lastClockAt + (now - clientClock.lastClockDuration)
+	local renderAt = (clientClock.renderAt or (estimatedServerTime - delay)) + dt
+
+	const renderTimeError = delay - (estimatedServerTime - renderAt)
+
+	if math.abs(renderTimeError) > 0.1 then
+		renderAt = estimatedServerTime - delay
+	elseif renderTimeError > 0.01 then
+		renderAt = math.max(estimatedServerTime - delay, renderAt - 0.1 * dt)
+	elseif renderTimeError < -0.01 then
+		renderAt = math.min(estimatedServerTime - delay, renderAt + 0.1 * dt)
+	end
+
+	clientClock.renderAt = renderAt
+end
+
+const function UpdateBuffer(clientClock: Types.ClientClock, buffer: number?)
+	buffer = if buffer and buffer <= 0 then nil else buffer
+	const currentBuffer = clientClock.bufferConst
+	if currentBuffer == buffer then
+		return
+	end
+	if not buffer then
+		if not clientClock.buffer then
+			clientClock.buffer = BufferTracker.new(clientClock)
+		end
+	else
+		clientClock.buffer = nil
+	end
+	clientClock.bufferConst = buffer
+	clientClock.renderAt = nil
+end
+
+const function new(tickRate: number, name: string, bufferNumber: number?, networkOwner: Player?): Types.ClientClock
+	bufferNumber = if bufferNumber and bufferNumber <= 0 then nil else bufferNumber
+	const self: Types.ClientClock = {
+		name = name,
+		lastClockAt = nil,
+		lastClockDuration = 0,
+		renderAt = nil,
+		tickRate = tickRate,
+		_baseTickRate = tickRate,
+		_owner = networkOwner,
+		buffer = nil,
+		bufferConst = bufferNumber,
+
+		OnSnapShot = OnSnapShot,
+		Refresh = Refresh,
+		GetEstimatedServerTime = GetEstimatedServerTime,
+		GetTargetRenderTime = GetTargetRenderTime,
+		Clear = Clear,
+		SetTickRate = SetTickRate,
+		UpdateBuffer = UpdateBuffer,
+		Destroy = Destroy,
+	}
+	if not bufferNumber then
+		self.buffer = BufferTracker.new(self)
+	end
+
+	if not networkOwner then
+		_ServerOwnedClocks[self] = true
+	end
+
+	ClientClocks[self] = true
+	return self
+end
+
+const function UpdateAll(dt: number)
+	for clientClock, _ in ClientClocks do
+		Update(clientClock, dt)
+	end
+end
+
+Config._WaitForLock(function()
+	if RunService:IsServer() then
+		return
+	end
+	for name, config in Config._EntityConfigs do
+		const clientClocks = config.CLIENT_CLOCK
+		if not clientClocks then
+			Warn.high("Entity Config", name, "is missing client clocks")
+			return
+		end
+		clientClocks.NORMAL = new(config.TICK_RATE, name .. "_NORMAL", config.BUFFER)
+		if config.HALF_TICK_DISTANCE < math.huge then
+			clientClocks.HALF = new(config.TICK_RATE * 2, name .. "_HALF", config.BUFFER)
+		end
+	end
+end)
+
+return {
+	_getBuffer = GetBuffer,
+	new = new,
+	clientClocks = ClientClocks,
+	serverOwnedClocks = _ServerOwnedClocks,
+	UpdateAll = UpdateAll,
+}

package/runtime/Chrono/_impl/Client/InterpolationBuffer.luau

@@ -0,0 +1,74 @@
+const Warn = require(script.Parent.Parent.Shared.Warn)
+const Config = require(script.Parent.Parent.Shared.Config)
+const Types = require(script.Parent.Parent.Shared.Types)
+
+local MIN_BUFFER
+local MAX_BUFFER
+const ALPHA = 0.1
+
+Config._WaitForLock(function()
+	MIN_BUFFER = Config._GetConfig("MIN_BUFFER")
+	MAX_BUFFER = Config._GetConfig("MAX_BUFFER")
+end)
+const Buffer = {}
+
+function Buffer.new(clientClock: Types.ClientClock)
+	return {
+		init = false,
+		averageLatency = 0,
+		deviation = 0,
+		lastLatency = 0,
+
+		clientClock = clientClock,
+	}
+end
+
+function Buffer.Register(data: Types.InterpolationBuffer, time: number)
+	const clientClock = data.clientClock
+	const clientNow = clientClock:GetEstimatedServerTime()
+	const latency = clientNow - time
+
+	if math.abs(latency) > 1 then
+		clientClock:Clear()
+		Warn.low(data.clientClock.name, ` latency too high, cleared cache to repredict in case of error:! {latency}`)
+	end
+
+	if not data.init then
+		--using the difference between current and last latency, i could smooth out the deviation (the variation in latency, which correlates to packet loss)
+		--this is using statistics https://en.wikipedia.org/wiki/Moving_average
+		data.averageLatency = latency
+		data.deviation = 0
+		data.lastLatency = latency
+		data.init = true
+		return
+	end
+
+	if data.lastLatency then
+		const delta = math.abs(latency - data.lastLatency)
+		--deviation is essentially jitter, and we calculate that using RFC 3550 jitter estimation
+		--see: https://tech.ebu.ch/docs/tech/tech3337.pdf
+		data.deviation = data.deviation + (delta - data.deviation) * ALPHA
+	end
+
+	data.averageLatency = data.averageLatency + (latency - data.averageLatency) * ALPHA
+	data.lastLatency = latency
+end
+
+function Buffer.GetBuffer(data: Types.InterpolationBuffer, tickRate: number)
+	if not data then
+		return MIN_BUFFER
+	end
+
+	const deviationMargin = data.deviation * 2
+	const rawBuffer = tickRate + deviationMargin
+
+	local buffer = if rawBuffer < MIN_BUFFER then MIN_BUFFER + (MIN_BUFFER - rawBuffer) * 0.2 else rawBuffer
+	if buffer > MAX_BUFFER then
+		Warn.low(`Interpolation buffer exceeded max! Was {buffer}, clamped to {MAX_BUFFER} for`, data.clientClock.name)
+		buffer = MAX_BUFFER
+	end
+
+	return buffer
+end
+
+return Buffer