cluaupp 0.2.3 → 1.3.0

package/templates/game/libs/Chrono/Client/Receiver.luau

@@ -0,0 +1,395 @@
+const RunService = game:GetService("RunService")
+const Players = game:GetService("Players")
+const Shared = script.Parent.Parent.Shared
+
+const Warn = require(Shared.Warn)
+const Entity = require(Shared.Entity)
+const Events = require(Shared.Events)
+const Holder = require(Shared.Holder)
+const ModelHelper = require(Shared.ModelHelper)
+const Types = require(Shared.Types)
+const ClockUnwrap = require(Shared.ClockUnwrap)
+const Stats = require(Shared.Stats).CLIENT
+const ClientClock = require(script.Parent.ClientClock)
+
+local BytesReceived = 0
+local NewPerSec = 0
+local RemovedPerSec = 0
+local ChangesPerSec = 0
+
+const SetTickMode = Entity._SetTickMode
+
+const UnreliableEvent = Shared.Remotes.Replicate
+const ReliableEvent = Shared.Remotes.ReplicateFull
+const HeartbeatRemote = Shared.Remotes.Heartbeat
+const ClientClockRelayRemote = Shared.Remotes.ClientClockRelay
+
+const ServerWrap = ClockUnwrap.new()
+const ClientOwnedWrap: ClockUnwrap.Store = {}
+
+const TickerHeaderBytes = 4 + 1
+const FULL_BYTES = 4 * 3 + 2 * 3
+const YAW_BYTES = 4 * 3 + 2
+
+const TAU = 2 * math.pi
+
+const function UnmapRotation(u16: number): number
+	return (u16 / 65535) * TAU - math.pi
+end
+
+const function ReadTickerHeader(b: buffer, index: number): (number, boolean, boolean)
+	const lastTicked = ClockUnwrap.unwrap(ServerWrap, buffer.readu32(b, index))
+	const packed = buffer.readu8(b, index + 4)
+
+	const isHalfTickRate = bit32.band(packed, 1) == 1
+	const isFull = bit32.band(packed, 2) == 2
+
+	return lastTicked, isFull, isHalfTickRate
+end
+
+const function DeserializeFull(b: buffer, index: number): CFrame
+	const x = buffer.readf32(b, index)
+	index += 4
+	const y = buffer.readf32(b, index)
+	index += 4
+	const z = buffer.readf32(b, index)
+	index += 4
+
+	const rx = UnmapRotation(buffer.readu16(b, index))
+	index += 2
+	const ry = UnmapRotation(buffer.readu16(b, index))
+	index += 2
+	const rz = UnmapRotation(buffer.readu16(b, index))
+	index += 2
+
+	return CFrame.new(x, y, z) * CFrame.fromOrientation(rx, ry, rz)
+end
+
+const function DeserializeYaw(b: buffer, index: number): CFrame
+	const x = buffer.readf32(b, index)
+	index += 4
+	const y = buffer.readf32(b, index)
+	index += 4
+	const z = buffer.readf32(b, index)
+	index += 4
+
+	const ry = UnmapRotation(buffer.readu16(b, index))
+	index += 2
+
+	return CFrame.new(x, y, z) * CFrame.fromOrientation(0, ry, 0)
+end
+
+const function HandleRemoved(id: number)
+	const entity = Holder.GetEntityFromId(id)
+	if entity then
+		Entity.Destroy(entity)
+		return
+	end
+	Warn.high("Tried to remove non existent entity with id", id)
+end
+
+const function SetMountId(entity: Types.Entity, mountParentId: number?)
+	entity.mountParentId = mountParentId
+	Events._Signals.EntityMountChanged:Fire(entity, mountParentId)
+end
+
+const function SetMountOffset(entity: Types.Entity, mountOffset: CFrame?)
+	entity.mountOffset = mountOffset or CFrame.identity
+end
+
+const ValueChanges = {
+	networkOwner = Entity["设置网络主控玩家"],
+	isHalfTicked = SetTickMode,
+	_data = Entity.SetData,
+	entityConfig = Entity.SetConfig,
+	autoUpdatePos = Entity.SetAutoUpdatePos,
+	mountParentId = SetMountId,
+	mountOffset = SetMountOffset,
+	broadPhase = Entity.SetBroadPhase,
+}
+
+const function HandleChanges(changes: { id: number, data: { { any } } })
+	const entity = Holder.GetEntityFromId(changes.id)
+	if not entity then
+		return
+	end
+	local hasMetadata
+	local modelData
+	for _, pair in changes.data do
+		const key = pair[1]
+		const value = pair[2]
+
+		const handler = ValueChanges[key]
+		if handler then
+			handler(entity, value)
+		elseif key == "latestCFrame" then
+			Entity.SetCFrame(entity, value)
+		elseif key == "_modelMetaData" then
+			hasMetadata = value
+		elseif key == "model" then
+			modelData = value
+		elseif key == "_player" then
+			if value then
+				Holder.SetAsCharacter(value, entity)
+			else
+				Holder.RemovePlayerCharacter(entity)
+			end
+		elseif key == "paused" then
+			if value then
+				Entity.PauseReplication(entity)
+			else
+				Entity.ResumeReplication(entity)
+			end
+		elseif key == "_lockedCFReplication" then
+			entity._lockedCFReplication = value
+			if not value then
+				const part = Entity._GetPart(entity)
+				if part then
+					Entity._UnlockPartPhysicsReplication(part)
+				end
+			else
+				Entity.SyncOwnerShip(entity)
+			end
+		else
+			Warn.high("Unhandled entity change key:", key)
+		end
+	end
+
+	if modelData ~= nil then
+		const model, modelType = ModelHelper.CreateModelFromData(modelData)
+		Entity.SetModel(entity, model, modelType :: any)
+		entity._modelMetaData = hasMetadata
+	end
+end
+
+const function HandleNewEntity(data: Types.EntityReceivePacket)
+	const model, modelType = ModelHelper.CreateModelFromData(data.model)
+	const entity = Entity._new(data.config, model, modelType, data.cframe)
+
+	entity.id = data.id
+	entity._player = data._player
+	entity._modelMetaData = data._modelMetaData
+	entity.paused = data.paused or false
+	entity.isHalfTicked = data.isHalfTicked
+	entity._data = data._data
+	entity.mountParentId = data.mountParentId
+	entity.mountOffset = data.mountOffset or CFrame.identity
+	entity.broadPhase = data.broadPhase or entity.broadPhase
+	entity._lockedCFReplication = data._lockedCFReplication or false
+
+	Entity.Push(entity, data.time, data.cframe)
+
+	Entity["设置网络主控玩家"](entity, data.networkOwner)
+	SetTickMode(entity, data.isHalfTicked)
+	Holder.RegisterEntity(entity)
+end
+
+const function PushCFrameFor(
+	id: number,
+	clientOwned: boolean,
+	cframe: CFrame,
+	time: number,
+	isHalfTick: boolean,
+	teleport: boolean?
+): boolean
+	const entity = Holder.GetEntityFromId(id)
+	if not entity then
+		Warn.high("Received update for non existent entity with id", id)
+		return false
+	end
+
+	const withinTeleportThreshold = entity._teleport and os.clock() - entity._teleport < 0.5
+	if withinTeleportThreshold then
+		if teleport then
+			entity._teleport = nil
+		else
+			return false
+		end
+	end
+
+	if clientOwned then
+		const renderCache = entity._clientClock
+		if renderCache then
+			if isHalfTick then
+				renderCache:SetTickRate(renderCache._baseTickRate * 2)
+			else
+				renderCache:SetTickRate(renderCache._baseTickRate)
+			end
+			renderCache:OnSnapShot(time)
+		end
+	else
+		const renderCaches = entity.entityConfig.CLIENT_CLOCK
+		if renderCaches then
+			const renderCache = isHalfTick and renderCaches.HALF or renderCaches.NORMAL
+			if renderCache then
+				renderCache:OnSnapShot(time)
+			end
+		end
+	end
+
+	if entity.isHalfTicked ~= isHalfTick then
+		SetTickMode(entity, isHalfTick)
+	end
+	entity.isHalfTicked = isHalfTick
+
+	Entity.Push(entity, time, cframe)
+	return true
+end
+
+const function HandleClientOwned(b: buffer)
+	BytesReceived += buffer.len(b)
+	const bLen = buffer.len(b)
+	local index = 0
+
+	while index < bLen do
+		const rawTime = buffer.readu32(b, index)
+		index += 4
+		const length = buffer.readu8(b, index)
+		index += 1
+		for i = 1, length do
+			const id = buffer.readu16(b, index)
+			index += 2
+			const packed = buffer.readu8(b, index)
+			index += 1
+			const isFull = bit32.band(packed, 1) == 1
+			const isHalfTickRate = bit32.band(packed, 2) == 2
+			const teleport = bit32.band(packed, 4) == 4
+			local cf: CFrame
+			if isFull then
+				cf = DeserializeFull(b, index)
+				index += FULL_BYTES
+			else
+				cf = DeserializeYaw(b, index)
+				index += YAW_BYTES
+			end
+			const entity = Holder.GetEntityFromId(id)
+			if not entity then
+				Warn.medium("Received update for non existent entity with id", id)
+				continue
+			end
+			-- Unwrap in the source player's frame (delta-based, offset-0). Shares state with
+			-- this player's other entity packets + the clock relay.
+			const time = ClockUnwrap.unwrapFor(ClientOwnedWrap, entity.networkOwner or "__unknown", rawTime)
+			PushCFrameFor(id, true, cf, time, isHalfTickRate, teleport)
+		end
+	end
+end
+
+const function HandleServerOwned(b: buffer)
+	const bLen = buffer.len(b)
+	BytesReceived += bLen
+	local index = 0
+	while index < bLen do
+		const lastTicked, isFull, isHalfTickRate = ReadTickerHeader(b, index)
+		index += TickerHeaderBytes
+		const length = buffer.readu8(b, index)
+		index += 1
+		for i = 1, length do
+			const id = buffer.readu16(b, index)
+			index += 2
+			local cframe
+			if isFull then
+				cframe = DeserializeFull(b, index)
+				index += FULL_BYTES
+			else
+				cframe = DeserializeYaw(b, index)
+				index += YAW_BYTES
+			end
+			PushCFrameFor(id, false, cframe, lastTicked, isHalfTickRate)
+		end
+	end
+end
+
+const function HandleUnreliable(id: string, data: buffer)
+	if id == "X" then -- Server Owned
+		HandleServerOwned(data)
+	elseif id == "O" then -- Client Owned
+		HandleClientOwned(data)
+	else
+		Warn.high("Unknown unreliable replicate id", id)
+	end
+end
+
+const function HandleReliable(newEntities: {}, removedEntities: { number }, entityChanges: { any })
+	--RunService.PreAnimation:Wait() -- was encountering an issues where instances were not replicated prob was streaming endabled?
+	if removedEntities then
+		for _, id in removedEntities do
+			HandleRemoved(id)
+		end
+		RemovedPerSec += #removedEntities
+	end
+
+	if newEntities then
+		for _, data: any in newEntities do
+			HandleNewEntity(data)
+		end
+		NewPerSec += #newEntities
+	end
+
+	if entityChanges then
+		for _, changeData in entityChanges do
+			HandleChanges(changeData)
+		end
+		ChangesPerSec += #entityChanges
+	end
+end
+
+UnreliableEvent.OnClientEvent:Connect(HandleUnreliable)
+ReliableEvent.OnClientEvent:Connect(HandleReliable)
+
+HeartbeatRemote.OnClientEvent:Connect(function(time: number)
+	-- Reduce the full-precision server time into the same offset-0 frame as the buffered
+	-- server-owned headers, otherwise the two feeds would disagree and freeze the clock.
+	const unwrapped = ClockUnwrap.unwrap(ServerWrap, ClockUnwrap.quantize(time))
+	for clock in ClientClock.serverOwnedClocks do
+		-- Refresh, not OnSnapShot: keep the clock fresh without feeding the heartbeat
+		-- cadence into the interpolation buffer's jitter estimate.
+		clock:Refresh(unwrapped)
+	end
+end)
+
+-- Client-clock relay: reseats each source to the server's authoritative wrap offset so every
+-- receiver agrees on the source's epoch regardless of join time. max() avoids regressing a wrap
+-- this client already witnessed between relays.
+ClientClockRelayRemote.OnClientEvent:Connect(function(list: { { player: Player, raw: number, offset: number } })
+	if type(list) ~= "table" then
+		return
+	end
+	for _, entry in list do
+		const player = entry.player
+		const raw = entry.raw
+		const offset = entry.offset
+		if player and type(raw) == "number" and type(offset) == "number" then
+			local state = ClientOwnedWrap[player]
+			if not state then
+				state = ClockUnwrap.new()
+				ClientOwnedWrap[player] = state
+			end
+			state.lastRaw = raw
+			state.offset = math.max(state.offset, offset)
+		end
+	end
+end)
+
+Players.PlayerRemoving:Connect(function(player)
+	ClientOwnedWrap[player] = nil
+end)
+
+local lastByteCheckTime = 0
+RunService.Heartbeat:Connect(function()
+	if os.clock() - lastByteCheckTime > 1 then
+		if not Stats._PAUSE then
+			Stats.BYTES_RECEIVED_PER_SEC = BytesReceived
+			Stats.NEW_ENTITIES_PER_SEC = NewPerSec
+			Stats.ENTITY_CHANGES_PER_SEC = ChangesPerSec
+			Stats.ENTITY_REMOVALS_PER_SEC = RemovedPerSec
+		end
+		NewPerSec = 0
+		RemovedPerSec = 0
+		ChangesPerSec = 0
+		BytesReceived = 0
+		lastByteCheckTime = os.clock()
+	end
+end)
+
+return nil

package/templates/game/libs/Chrono/Client/Replicate.luau

@@ -0,0 +1,333 @@
+const Shared = script.Parent.Parent.Shared
+
+const RunService = game:GetService("RunService")
+
+const Ticker = require(Shared.Ticker)
+const Warn = require(Shared.Warn)
+const StatsALL = require(script.Parent.Parent.Shared.Stats)
+const ApplyMounts = require(script.Parent.Parent.Shared.ApplyMounts)
+const RenderCache = require(script.Parent.ClientClock)
+const ModelResolver = require(script.Parent.ModelResolver)
+const Entity = require(Shared.Entity)
+const Holder = require(Shared.Holder)
+const Config = require(Shared.Config)
+const Types = require(Shared.Types)
+const Sender = require(script.Parent.Sender)
+const Stats = require(Shared.Stats).CLIENT
+
+const CLIENT_CLOCK_SYNC_RATE = 15 -- should be fine having lower then server
+require(script.Parent.Player)
+require(script.Parent.Receiver)
+
+const idMap = Holder.idMap
+
+local FrustumLookVector = vector.create(0, 0, -1)
+local FrustumRightVector = vector.create(1, 0, 0)
+local FrustumUpVector = vector.create(0, 1, 0)
+local FrustumPosition = vector.create(0, 0, 0)
+local TanHorizontal = 0
+local TanVertical = 0
+
+const function PrepareFrustumCheck()
+	const cframe: CFrame = workspace.CurrentCamera.CFrame
+	FrustumLookVector = cframe.LookVector :: any
+	FrustumRightVector = cframe.RightVector :: any
+	FrustumUpVector = cframe.UpVector :: any
+
+	FrustumPosition = cframe.Position :: any
+
+	const cam = workspace.CurrentCamera
+	const halfFov = math.rad(cam.FieldOfView / 2)
+	const aspectRatio = cam.ViewportSize.X / cam.ViewportSize.Y
+	TanHorizontal = math.tan(halfFov) * aspectRatio
+	TanVertical = math.tan(halfFov)
+end
+
+const function CheckPointInFrustum(pos: vector)
+	const diff = pos - FrustumPosition
+
+	const magnitude = vector.magnitude(diff)
+
+	if magnitude == 0 then
+		return true
+	end
+
+	const forwardDis = vector.dot(diff, FrustumLookVector)
+
+	const forwardDot = forwardDis / magnitude
+	if forwardDot < 0 then
+		return false
+	end
+	if forwardDis < 1 then
+		return true
+	end
+	const unit = diff / magnitude
+	const rightDot = vector.dot(unit, FrustumRightVector)
+
+	if math.abs(rightDot) > forwardDot * TanHorizontal then
+		return false
+	end
+
+	const upDot = vector.dot(unit, FrustumUpVector)
+	if math.abs(upDot) > forwardDot * TanVertical then
+		return false
+	end
+	return true
+end
+
+const function CheckBroadPhaseInFrustum(center: vector, size: vector)
+	if size == vector.zero then
+		return CheckPointInFrustum(center)
+	end
+	const halfSize = size * 0.5
+	const halfX = halfSize.x
+	const halfY = halfSize.y
+	const halfZ = halfSize.z
+	const negX = -halfX
+	const negY = -halfY
+	const negZ = -halfZ
+
+	return CheckPointInFrustum(center + vector.create(halfX, halfY, halfZ))
+		or CheckPointInFrustum(center + vector.create(negX, halfY, halfZ))
+		or CheckPointInFrustum(center + vector.create(halfX, negY, halfZ))
+		or CheckPointInFrustum(center + vector.create(negX, negY, halfZ))
+		or CheckPointInFrustum(center + vector.create(halfX, halfY, negZ))
+		or CheckPointInFrustum(center + vector.create(negX, halfY, negZ))
+		or CheckPointInFrustum(center + vector.create(halfX, negY, negZ))
+		or CheckPointInFrustum(center + vector.create(negX, negY, negZ))
+end
+const Ticks = 4
+local OutOfBroadPhaseTick = 0
+local CurrentTick = 0
+local TotalInterpolationTime = 0
+local AmtInterpolations = 0
+
+local CheckedThisFrame = 0
+local TotalCulled = 0
+local MovedThisFrame = 0
+
+const function Interpolate(entity: Types.Entity)
+	const config = entity.entityConfig
+	if not entity.interpolation or config.CUSTOM_INTERPOLATION then
+		return
+	end
+	const primaryPart = Entity.GetPrimaryPart(entity)
+
+	if not primaryPart then
+		return
+	end
+
+	if entity.isContextOwner then
+		return
+	end
+
+	if config.ASSEMBLY_ROOT_PART_CHECK then
+		if primaryPart.AssemblyRootPart ~= primaryPart then
+			Warn.low(
+				"Primary part for entity "
+					.. entity.id
+					.. " is not the assembly root part. Skipping interpolation for this entity."
+			)
+			return
+		end
+	end
+
+	const currentEntityTick = entity._outofBroadPhaseTick
+	if currentEntityTick and currentEntityTick ~= CurrentTick then
+		return
+	end
+
+	const snapshot = entity.snapshot
+	if not snapshot then
+		Warn.medium("No snapshot for entity", entity)
+		return
+	end
+	CheckedThisFrame += 1
+	debug.profilebegin("Get Render CFrame")
+	const targetTime = Entity.GetTargetRenderTime(entity)
+	const targetCFrame = snapshot:GetAt(targetTime)
+	debug.profileend()
+	if not targetCFrame then
+		return
+	end
+	const broadPhase: vector? = entity.broadPhase
+
+	if broadPhase then
+		const toCheck = targetCFrame :: any
+		const lastCheckedCFrame = entity.lastCheckedCFrame
+		debug.profilebegin("Prepare Frustum")
+		const passed = CheckBroadPhaseInFrustum(toCheck.Position, broadPhase)
+		debug.profileend()
+		if not passed then
+			if lastCheckedCFrame and lastCheckedCFrame.Position ~= toCheck.Position then
+				debug.profilebegin("Check Last CFrame")
+				const passLast = CheckBroadPhaseInFrustum(lastCheckedCFrame.Position :: any, broadPhase)
+				debug.profileend()
+				if not passLast then
+					TotalCulled += 1
+					return
+				end
+			else
+				if not lastCheckedCFrame then
+					entity.lastCheckedCFrame = toCheck
+				end
+				if not entity._outofBroadPhaseTick then
+					entity._outofBroadPhaseTick = OutOfBroadPhaseTick
+					OutOfBroadPhaseTick += 1
+					if OutOfBroadPhaseTick % Ticks == 0 then
+						OutOfBroadPhaseTick = 0
+					end
+				end
+				TotalCulled += 1
+				return
+			end
+		end
+		entity.lastCheckedCFrame = nil
+		entity._outofBroadPhaseTick = nil
+	end
+	debug.profilebegin("Set CFrame")
+	if targetCFrame == targetCFrame then
+		primaryPart.CFrame = targetCFrame
+	end
+	MovedThisFrame += 1
+	debug.profileend()
+end
+
+const function updateEntityStats()
+	if not StatsALL.SERVER._SHOULD_REPLICATE or Stats._PAUSE then
+		return
+	end
+	const entities = {}
+	for _, entity in idMap do
+		const id = entity.id
+		const config = entity.entityConfig
+		const configName = config and config.NAME or "DEFAULT"
+		const networkOwner = entity.networkOwner
+		const isCharacter = entity._player ~= nil
+
+		const lastRecvTime = entity.latestTime or 0
+		const lastReplicatedTime = entity.lastReplicatedTime or 0
+
+		local renderCache = entity._clientClock
+
+		if not renderCache then
+			const RenderCaches = entity.entityConfig.CLIENT_CLOCK
+			if RenderCaches then
+				renderCache = entity.isHalfTicked and RenderCaches.HALF or RenderCaches.NORMAL
+			end
+		end
+
+		local targetRender = 0
+		local averageLatency = 0
+		local deviation = 0
+		local bufferedTime = 0
+
+		if renderCache then
+			targetRender = renderCache:GetTargetRenderTime()
+			const interpolationBuff = renderCache.buffer
+			if interpolationBuff then
+				averageLatency = interpolationBuff.averageLatency
+				deviation = interpolationBuff.deviation
+			end
+			bufferedTime = RenderCache._getBuffer(renderCache)
+		end
+		const primaryPart = Entity.GetPrimaryPart(entity)
+		const snapshot = entity.snapshot
+		const currentPosition = primaryPart and primaryPart.Position
+		const snapshots = {}
+		if snapshot then
+			for _, snap in snapshot.cache do
+				table.insert(snapshots, { t = snap.t, value = snap.value, velocity = snap.velocity })
+			end
+			table.sort(snapshots, function(a, b)
+				return a.t > b.t
+			end)
+		end
+		const data = {
+			id = id,
+			entity = entity,
+			networkOwner = networkOwner,
+			isCharacter = isCharacter,
+			config = configName,
+			lastReceivedTime = lastRecvTime,
+			lastReplicatedTime = lastReplicatedTime,
+			targetTime = targetRender,
+			averageLatency = averageLatency,
+			deviation = deviation,
+			bufferedTime = bufferedTime,
+			currentPosition = currentPosition,
+			snapshots = snapshots,
+		}
+		table.insert(entities, data)
+	end
+	Stats.CLIENT_ENTITIES = entities
+end
+Config._WaitForLock(function()
+	RunService.Heartbeat:Connect(function(deltaTime: number)
+		CurrentTick += 1
+		if CurrentTick % Ticks == 0 then -- Runs every 4 frames at 60hz this is 15hz
+			Stats.TOTAL_ENTITIES_CULLED = TotalCulled
+			TotalCulled = 0
+			CurrentTick = 0
+		end
+		RenderCache.UpdateAll(deltaTime)
+		debug.profilebegin("Prepare Frustum Check")
+		PrepareFrustumCheck()
+		debug.profileend()
+		local total = 0
+		const startTime = os.clock()
+		debug.profilebegin("Interpolate Entities")
+		for _, entity in idMap do
+			ModelResolver(entity)
+			if entity.destroyed or entity.paused then
+				continue
+			end
+			if entity.mountParentId then
+				continue
+			end
+			total += 1
+			Interpolate(entity)
+		end
+		debug.profileend()
+		const endTime = os.clock()
+		debug.profilebegin("Update Entity Stats")
+		updateEntityStats()
+		debug.profileend()
+		TotalInterpolationTime += (endTime - startTime)
+		AmtInterpolations += 1
+
+		ApplyMounts()
+		if not Stats._PAUSE then
+			Stats.TOTAL_CLIENT_ENTITIES_CHECKED_THIS_FRAME = total
+			Stats.ENTITIES_MOVED_THIS_FRAME = MovedThisFrame
+			Stats.TOTAL_CLIENT_ENTITIES = total
+			Stats.AVG_INTERPOLATION_TIME_MS = (TotalInterpolationTime / AmtInterpolations) * 1000
+		end
+		MovedThisFrame = 0
+		CheckedThisFrame = 0
+		if AmtInterpolations > 60 then
+			TotalInterpolationTime = 0
+			AmtInterpolations = 0
+		end
+		Sender.Update()
+		Ticker._IncrementGlobalTick()
+	end)
+	-- Client clock heartbeat: sends the FULL os.clock so the server can seat this client's wrap
+	-- epoch directly (remotes serialize numbers as f64 anyway, so it's the same bytes as a u32).
+	-- Keeps the server's view fresh + correct even for a still (macro/auto-click) player that
+	-- sends no entity packets. See ClockUnwrap.
+	const ClientHeartbeatRemote = Shared.Remotes.ClientHeartbeat
+	ClientHeartbeatRemote:FireServer(os.clock()) -- seed on join
+	local clientHeartbeatAcc = 0
+	RunService.Heartbeat:Connect(function(dt: number)
+		clientHeartbeatAcc += dt
+		if clientHeartbeatAcc >= CLIENT_CLOCK_SYNC_RATE then
+			clientHeartbeatAcc = 0
+			ClientHeartbeatRemote:FireServer(os.clock())
+		end
+	end)
+
+	Shared.Remotes.ClientLoaded:FireServer()
+end)
+
+return nil