cluaupp 1.0.0 → 1.3.0

package/examples/game/libs/Chrono/_impl/Shared/Entity.luau

@@ -0,0 +1,1016 @@
+const Entity = {}
+
+const Players = game:GetService("Players")
+const RunService = game:GetService("RunService")
+const Types = require(script.Parent.Types)
+const Config = require(script.Parent.Config)
+const Snapshot = require(script.Parent.Snapshots)
+const InterpolationMath = require(script.Parent.InterpolationMath)
+const ClientClock = require(script.Parent.Parent.Client.ClientClock)
+const Holder = require(script.Parent.Holder)
+const Signal = require(script.Parent.Signal)
+const Events = require(script.Parent.Events)
+const ModelHelper = require(script.Parent.ModelHelper)
+const Warn = require(script.Parent.Warn)
+const VelocityAt = InterpolationMath.VelocityAt
+
+const Changes = {}
+
+const clientOwned = Holder._clientOwned
+const IS_SERVER = RunService:IsServer()
+const LOCAL_PLAYER = if IS_SERVER then nil else Players.LocalPlayer
+
+const CHRONO_PRIMARY = "__CHRONO_PRIMARY"
+
+const CENTER_PART = Instance.new("Part")
+CENTER_PART.Size = Vector3.new(0.1, 0.1, 0.1)
+CENTER_PART.Name = "__CHRONO_CENTER"
+CENTER_PART.Anchored = true
+CENTER_PART.Transparency = 1
+CENTER_PART.CanCollide = false
+CENTER_PART.CanTouch = false
+CENTER_PART.CanQuery = false
+
+type Entity = Types.Entity
+
+local READY = false
+
+Config._WaitForLock(function()
+	READY = true
+end)
+
+const function SafeDestroy(instance: Instance?)
+	if instance then
+		pcall(function()
+			instance:Destroy()
+		end)
+	end
+end
+
+const function SafeSetNetworkOwner(part: BasePart, player: Player?)
+	pcall(function()
+		part:SetNetworkOwner(player)
+	end)
+end
+
+const function GetPart(self: Types.Entity): BasePart?
+	const model = self.model
+	if not model then
+		return nil
+	end
+	if model:IsA("BasePart") then
+		return model
+	end
+	if model:IsA("Model") then
+		const chronoPrimary = self._chronoPrimary
+		if chronoPrimary then
+			const primary = model:FindFirstChild(chronoPrimary)
+			if primary and primary:IsA("BasePart") then
+				return primary
+			else
+				Warn.low(
+					`Chrono primary part {chronoPrimary} not found or not a BasePart in model {model:GetFullName()} for entity id {self.id}. Falling back to default PrimaryPart.`
+				)
+			end
+		end
+		const primaryPart = model.PrimaryPart
+		if primaryPart then
+			return primaryPart
+		end
+	end
+	return nil
+end
+
+const function GetRootPart(entity: Entity): BasePart?
+	const primaryPart = Entity.GetPrimaryPart(entity)
+
+	if not primaryPart then
+		return
+	end
+
+	if IS_SERVER and entity._lockedCFReplication then
+		const locker = primaryPart:FindFirstChild("__CHRONO_LOCKER")
+
+		if not locker then
+			return
+		end
+		const lockerPart = locker:FindFirstChildWhichIsA("BasePart")
+		if not lockerPart or not lockerPart:IsA("BasePart") then
+			return primaryPart
+		end
+
+		return lockerPart
+	else
+		return primaryPart
+	end
+end
+
+const function LockCFReplication(part: BasePart?): BasePart?
+	if not part then
+		return
+	end
+	const initCF = part.CFrame
+	const previousLocker = part:FindFirstChild("__CHRONO_LOCKER")
+	if previousLocker then
+		const weld = previousLocker:FindFirstChild("__CHRONO_WELD") :: Motor6D
+		if weld then
+			weld.Part1 = part
+			part.CFrame = initCF
+			return weld.Part0
+		else
+			SafeDestroy(previousLocker)
+		end
+	end
+
+	const camera = Instance.new("Camera", part)
+	camera.Archivable = false
+	camera.Name = "__CHRONO_LOCKER"
+	const weld = Instance.new("Weld", camera)
+	weld.Name = "__CHRONO_WELD"
+	const locker = Instance.new("Part")
+	locker.CustomPhysicalProperties = PhysicalProperties.new(0.0001, 0, 0, 0, 0)
+	locker.Name = "__CHRONO_LOCKER_PART"
+	locker.Parent = camera
+	locker.CanCollide = false
+	locker.CanQuery = false
+	locker.CanTouch = false
+	locker.Transparency = if IS_SERVER then 0 else 1
+	locker.Color = Color3.new(1, 0, 0)
+	locker.Massless = false
+	locker.RootPriority = 127
+	locker.Size = Vector3.zero
+	--locker.Anchored = true
+	weld.Part0 = locker
+	weld.Part1 = part
+	part.CFrame = initCF
+	return locker
+end
+
+const function SetPartCFrame(entity, cframe: CFrame)
+	const part = GetRootPart(entity)
+	if part then
+		part.CFrame = cframe
+	end
+end
+
+const function UnlockCFReplication(part: BasePart?)
+	if not part then
+		return
+	end
+	const cf = part.CFrame
+	const locker = part:FindFirstChild("__CHRONO_LOCKER")
+	if locker then
+		-- local weld = locker:FindFirstChild("__CHRONO_WELD") :: Motor6D
+		-- if weld then
+		-- 	weld.Part1 = nil
+		-- else
+		-- 	SafeDestroy(locker)
+		-- end
+		--Safer overall to just destroy and recreate
+		locker:Destroy()
+		part.CFrame = cf
+	end
+end
+
+const function SetValue(entity: Entity, key: string, value: any, bypass: boolean?, specialValue: any)
+	if not bypass and entity[key] == value then
+		return
+	end
+	entity[key] = value
+	if not IS_SERVER then
+		return
+	end
+	if not Changes[entity] then
+		Changes[entity] = {}
+	end
+	Changes[entity][key] = specialValue or value or false
+end
+
+const function FireEvent(entity: Entity, eventName: string, ...: any)
+	const events = entity._events
+	if not events then
+		return
+	end
+	const signal = events[eventName]
+	if signal then
+		signal:Fire(entity, ...)
+	end
+end
+
+-- If buffer is given then it will create a client clock for the entity as well.
+const function SetClock(self: Entity, buffer: number | false?)
+	if self._clientClock then
+		self._clientClock:Destroy()
+		self._clientClock = nil
+	end
+	if buffer == false then
+		self._clockBuffer = nil
+		buffer = nil
+	end
+	buffer = buffer or self._clockBuffer
+	self._clockBuffer = buffer
+	const entityBuffer = buffer or self.entityConfig.BUFFER or 0
+	if self.networkOwner or buffer then
+		const networkOwner = self.networkOwner
+		self._clientClock = ClientClock.new(
+			self.entityConfig.TICK_RATE,
+			`Entity id: {self.id} plr: {networkOwner and networkOwner.Name or "SERVER"}`,
+			entityBuffer,
+			networkOwner
+		)
+	end
+end
+
+const function CheckNetworkOwner(self: Entity, prev: Player?)
+	self.isContextOwner = self.networkOwner == LOCAL_PLAYER
+	const isSameOwner = self.networkOwner == prev
+	if not isSameOwner then
+		self.latestTime = 0
+		self.lastClientClock = 0
+	end
+	if IS_SERVER then
+		const part = GetPart(self)
+		if part then
+			const locked = self._lockedCFReplication
+
+			if locked then
+				UnlockCFReplication(part)
+			end
+			SafeSetNetworkOwner(part, self.networkOwner)
+			if locked then
+				LockCFReplication(part)
+				const root = GetRootPart(self)
+				if root then
+					SafeSetNetworkOwner(root, self.networkOwner)
+					root.Anchored = not isSameOwner
+				end
+			end
+		end
+
+		if self.isContextOwner and not self.entityConfig.STORE_SNAPSHOTS then
+			self.snapshot = nil
+		elseif not self.snapshot then
+			self.snapshot = Snapshot(InterpolationMath.Hermite)
+		end
+	else
+		const locked = self._lockedCFReplication
+
+		if locked and self.isContextOwner then
+			const part = GetPart(self)
+			if part then
+				LockCFReplication(part)
+				self._cfLockFailed = nil
+			else
+				self._cfLockFailed = true
+			end
+			if self._player then
+				UnlockCFReplication(part)
+			end
+		end
+	end
+
+	if isSameOwner then
+		return
+	elseif self.snapshot then
+		self.snapshot:Clear()
+	end
+
+	if not IS_SERVER then
+		SetClock(self)
+	end
+
+	FireEvent(self, "NetworkOwnerChanged", self.networkOwner, prev)
+
+	if prev then
+		const ownedEntities = clientOwned[prev]
+
+		if ownedEntities then
+			ownedEntities[self] = nil
+
+			Events._Signals.PlayerOwnedRemoved:Fire(prev, self)
+		end
+	end
+	if self.networkOwner then
+		const ownedEntities = clientOwned[self.networkOwner]
+
+		if not ownedEntities then
+			return
+		end
+		ownedEntities[self] = true
+
+		Events._Signals.PlayerOwnedAdded:Fire(self.networkOwner, self)
+	end
+end
+
+function Entity.SyncOwnerShip(self: Entity)
+	CheckNetworkOwner(self, self.networkOwner)
+end
+
+const function CheckModelReplicationMode(entity: Entity, mode: Types.MODEL_REPLICATION_MODE?): "NATIVE" | "CUSTOM"
+	if not mode then
+		mode = entity.modelReplicationMode
+	end
+	if not mode then
+		const config = entity.entityConfig
+		mode = config.MODEL_REPLICATION_MODE
+	end
+	mode = (mode :: any):upper()
+	if mode ~= "NATIVE" and mode ~= "CUSTOM" and mode ~= "NATIVE_WITH_LOCK" then
+		Warn.medium(`Invalid model replication mode {mode} for entity id {entity.id}, defaulting to NATIVE`)
+		mode = "NATIVE"
+	end
+	entity._lockedCFReplication = false
+	if mode == "NATIVE_WITH_LOCK" then
+		mode = "NATIVE"
+		entity._lockedCFReplication = true
+	end
+	return mode :: any
+end
+
+const function SetModel(
+	self: Entity,
+	model: Model | BasePart | string?,
+	modelReplicationMode: Types.MODEL_REPLICATION_MODE?,
+	noDestroy: boolean?
+): ()
+	const wasCustom = self.modelReplicationMode == "CUSTOM"
+
+	if IS_SERVER then
+		if self.modelReplicationMode == "NATIVE" and self._lockedCFReplication then
+			const part = GetPart(self)
+			self._lockedCFReplication = false
+			UnlockCFReplication(part)
+		end
+		if not noDestroy then
+			SafeDestroy(self.model)
+		end
+		self.model = nil
+	elseif not IS_SERVER and wasCustom then
+		SafeDestroy(self.model)
+		self.model = nil
+	elseif not IS_SERVER and self._lockedCFReplication then
+		const part = GetPart(self)
+		self._lockedCFReplication = false
+		UnlockCFReplication(part)
+	end
+	local modelString
+	if type(model) == "string" then
+		modelString = model
+		model = Config._GetEntityModel(model :: string)
+		if model then
+			model = (model :: any):Clone()
+		end
+
+		if model then
+			(model :: any).Parent = workspace
+		end
+	end
+	const _model: Model? = model :: any
+	const broadPhase = Config._GetBroadPhase(modelString :: string)
+
+	const replicationMode: "NATIVE" | "CUSTOM" = CheckModelReplicationMode(self, modelReplicationMode)
+	self.modelString = modelString
+	self.model = _model
+
+	if IS_SERVER or not self.broadPhase then
+		self.broadPhase = broadPhase
+	end
+
+	if _model then
+		if replicationMode == "CUSTOM" then
+			_model.Parent = Holder.GetEntityStorageInstance()
+		end
+
+		const chronoPrimary = _model:GetAttribute(CHRONO_PRIMARY)
+		if chronoPrimary and type(chronoPrimary) == "string" then
+			self._chronoPrimary = chronoPrimary
+		end
+	end
+
+	self.modelReplicationMode = replicationMode
+
+	const primaryPart = GetPart(self)
+	if _model and not primaryPart then
+		const warn = IS_SERVER and Warn.high or Warn.low
+		warn(`{_model:GetFullName()} must have a PrimaryPart set for things like autoReplication and movement.`)
+	elseif _model and not _model.Archivable then
+		Warn.low(
+			`{_model:GetFullName()} is not Archivable. It is recommended to set Archivable to true for entity models to prevent potential issues when cloning. Archivable has been set to true automatically.`
+		)
+		_model.Archivable = true
+	end
+
+	if not primaryPart then
+		return
+	end
+
+	const initCFrame = primaryPart.CFrame
+
+	if not self.latestCFrame then
+		Entity.SetCFrame(self, initCFrame or primaryPart.CFrame)
+	end
+	if self.latestCFrame then
+		primaryPart.CFrame = self.latestCFrame
+	end
+
+	self.modelReplicationMode = Entity.GetModelReplicationType(self) :: any
+	if self.modelReplicationMode == "NATIVE_WITH_LOCK" then
+		self._lockedCFReplication = true
+		self.modelReplicationMode = "NATIVE"
+	end
+	if not IS_SERVER and not self.isContextOwner and (replicationMode == "CUSTOM" or self._lockedCFReplication) then
+		primaryPart.Anchored = true
+	end
+end
+
+function Entity._new(
+	entityConfig: string?,
+	model: Model | BasePart | string?,
+	modelReplicationMode: Types.MODEL_REPLICATION_MODE?,
+	initCFrame: CFrame?
+): Entity
+	local config = Config._GetEntityType(entityConfig)
+	if not config then
+		Warn.medium(`Entity config {entityConfig} not found. Using DEFAULT config.`)
+		config = Config._GetEntityType("DEFAULT")
+	end
+
+	-- If the model doesn't exist and there's no init cframe then it won't be able to find a starting cframe
+	if initCFrame == nil and typeof(model) == "string" then
+		const _model = Config._GetEntityModel(model :: string)
+		if _model == false then
+			Warn.medium(`Entity's model doesn't exist, initCFrame is required. DEFAULTING to CFrame.new(0, 0, 0)`)
+			initCFrame = CFrame.new(0, 0, 0)
+		end
+	end
+
+	const self: Entity = {
+		id = -1,
+
+		registered = false,
+		autoUpdatePosition = config.AUTO_UPDATE_POSITION ~= false,
+		isContextOwner = false,
+		networkOwner = nil,
+		latestCFrame = initCFrame,
+		paused = false,
+
+		entityConfig = config,
+		destroyed = false,
+
+		interpolation = not IS_SERVER and true,
+	}
+
+	if LOCAL_PLAYER then
+		self.snapshot = Snapshot(InterpolationMath.Hermite)
+	end
+	SetModel(self, model, modelReplicationMode)
+	CheckNetworkOwner(self, nil)
+
+	return self
+end
+
+--[=[
+	Creates a new Entity instance and registers.
+
+	@param entityConfig The entity configuration name to use. Defaults to "DEFAULT" if not provided or invalid.
+	@param model The model to use for the entity. Can be a Model, BasePart, or a string representing a registered model name.
+	@param modelReplicationMode The model replication mode to use. Will default of the entity config if not provided.
+	@param initCFrame The initial CFrame for the entity. Optional.
+
+	@return The newly created Entity instance.
+]=]
+function Entity.new(
+	entityConfig: string?,
+	model: Model | BasePart | string?,
+	modelReplicationMode: Types.MODEL_REPLICATION_MODE?,
+	initCFrame: CFrame?
+): Entity
+	if not READY then
+		error("Entity.new cannot be called until Chrono.Start() is called.")
+	end
+	const self = Entity._new(entityConfig, model, modelReplicationMode, initCFrame)
+	Holder.RegisterEntity(self)
+	return self
+end
+
+--[=[
+	Sets the model for the entity.
+
+	@param model The model to set for the entity. Can be a Model, BasePart, or a string representing a registered model name.
+	@param modelReplicationMode The model replication mode to use. Will default to the last used mode or the entity config if not provided.
+	@param noDestroy If true, will not destroy the previous model. Defaults to false.
+]=]
+function Entity.SetModel(
+	self: Entity,
+	model: Model | BasePart | string?,
+	modelReplicationMode: Types.MODEL_REPLICATION_MODE?,
+	noDestroy: boolean?
+)
+	const old = self.model
+	SetModel(self, model, modelReplicationMode, noDestroy)
+	if IS_SERVER then
+		const toReplicate, metaData = ModelHelper.ReadyModelFromRep(self, nil)
+		SetValue(self, "model", self.model, true, toReplicate or false)
+		SetValue(self, "_modelMetaData", metaData, true, metaData)
+		CheckNetworkOwner(self, self.networkOwner)
+	end
+	FireEvent(self, "ModelChanged", self.model, old)
+end
+
+Entity._FireEvent = FireEvent
+
+const function GetEvent(self: Entity, eventName: string): Types.Event<any>
+	if not self._events then
+		self._events = {}
+	end
+	const events = self._events :: { [string]: Types.Signal<any, any> }
+	if not events[eventName] then
+		events[eventName] = Signal.new()
+	end
+	return events[eventName].Event
+end
+
+--[=[
+	Sets the entity configuration for the entity.
+
+	@param entityConfig The entity configuration name to set.
+]=]
+function Entity.SetConfig(self: Entity, entityConfig: string)
+	local config = Config._GetEntityType(entityConfig)
+	if not config then
+		Warn.medium(`Entity config {entityConfig} not found. Using Default config.`)
+		config = Config._GetEntityType("DEFAULT")
+	end
+	SetValue(self, "entityConfig", config, false, config.NAME)
+	if not IS_SERVER then
+		SetClock(self)
+	end
+end
+
+--[=[
+	Sets the client clock buffer for the entity. 
+
+	@param buffer? The buffer to set for the client clock. If nil, will use the entity config's buffer. 
+]=]
+function Entity.SetClockBuffer(self: Entity, buffer: number?)
+	if IS_SERVER then
+		error("SetClockBuffer can only be called on the client")
+	end
+	SetClock(self, buffer ~= nil and buffer or false)
+end
+
+--[=[
+	Sets the broad phase vector for the entity.
+
+	@param broadPhase The broad phase vector to set.
+]=]
+function Entity.SetBroadPhase(self: Entity, broadPhase: vector?)
+	SetValue(self, "broadPhase", broadPhase)
+end
+
+--[=[
+	Gets the user associated data with the entity.
+
+	@return The data associated with the entity.
+]=]
+function Entity.GetData(self: Entity): any
+	return self._data
+end
+
+--[=[
+	Gets the model associated with the entity.
+
+	@return The model associated with the entity.
+]=]
+function Entity.GetModel(self: Entity): Model | BasePart?
+	return self.model
+end
+
+--[=[
+	Sets the user associated data with the entity.
+
+	@param data The data to associate with the entity.
+]=]
+function Entity.SetData(self: Entity, data: any)
+	SetValue(self, "_data", data, true)
+	FireEvent(self, "DataChanged", data)
+end
+
+function Entity._SetTickMode(self: Entity, isHalfTicked: boolean?)
+	if self.isHalfTicked == isHalfTicked then
+		return
+	end
+	if not self.isContextOwner then
+		SetValue(self, "isHalfTicked", isHalfTicked)
+	else
+		self.isHalfTicked = isHalfTicked
+	end
+	FireEvent(self, "TickChanged", isHalfTicked == nil and "NONE" or if isHalfTicked then "HALF" else "NORMAL")
+end
+
+--[=[
+	Clears the mount of the entity.
+]=]
+function Entity.ClearMount(self: Entity)
+	if not IS_SERVER then
+		error("ClearMount can only be called on the server")
+	end
+	if not self.mountParentId then
+		return
+	end
+
+	SetValue(self, "mountParentId", nil)
+	SetValue(self, "mountOffset", nil)
+	Events._Signals.EntityMountChanged:Fire(self, nil)
+end
+
+--[=[
+	Sets the mount of the entity.
+
+	@param parent The parent entity to mount to. If nil, will clear the mount.
+	@param offset The CFrame offset from the parent entity.
+]=]
+function Entity.SetMount(self: Entity, parent: Entity?, offset: CFrame?)
+	if not IS_SERVER then
+		error("SetMount can only be called on the server")
+	end
+
+	if parent == nil then
+		return Entity.ClearMount(self)
+	end
+
+	if self == parent then
+		Warn.medium("An entity cannot mount itself")
+		return
+	end
+
+	if not parent.id then
+		Warn.high("Parent entity must be registered before mounting")
+		return
+	end
+
+	SetValue(self, "mountParentId", parent.id)
+	SetValue(self, "mountOffset", offset)
+	Events._Signals.EntityMountChanged:Fire(self, parent.id)
+end
+
+Entity["设置网络主控玩家"] = function(self: Entity, player: Player?)
+	if player ~= self.networkOwner then
+		const prev = self.networkOwner
+		SetValue(self, "networkOwner", player)
+		CheckNetworkOwner(self, prev)
+		Entity.Clear(self)
+	end
+	self.lastCheckedCFrame = nil
+	if not IS_SERVER and self.modelReplicationMode == "CUSTOM" then
+		const primaryPart = Entity.GetPrimaryPart(self)
+		if primaryPart then
+			primaryPart.Anchored = not self.isContextOwner
+		end
+	end
+end
+
+--[=[
+	Sets the network owner of the entity. Does nothing if called on the client.
+
+	@param player The player to set as the network owner. If nil, will clear the network owner.
+]=]
+function Entity.SetNetworkOwner(self: Entity, player: Player?)
+	if IS_SERVER and player ~= self.networkOwner then
+		Entity["设置网络主控玩家"](self, player)
+		SetValue(self, "isHalfTicked", self.isHalfTicked, true)
+	elseif not IS_SERVER then
+		error("SetNetworkOwner can only be called on the server")
+	end
+end
+
+--[=[
+	Clears the entity's snapshot and latest CFrame/time.
+]=]
+function Entity.Clear(self: Entity)
+	const snapshot = self.snapshot
+	-- self.latestCFrame = nil --< this line
+	self.latestTime = nil
+	self.lastClientClock = nil
+	if snapshot then
+		snapshot:Clear()
+	end
+end
+
+--[=[
+	Pauses replication for the entity.
+]=]
+function Entity.PauseReplication(self: Entity)
+	SetValue(self, "paused", true)
+end
+
+--[=[
+	Resumes replication for the entity.
+]=]
+function Entity.ResumeReplication(self: Entity)
+	SetValue(self, "paused", false)
+end
+
+--[=[
+	Pushes a new CFrame value into the entity's snapshot.
+
+	@param time The time associated with the CFrame value.
+	@param value The CFrame value to push.
+	@param velocity Optional velocity to push with the snapshot. If not provided, will be calculated based on the latest snapshot value.
+
+	@return Whether the pushed value is the newest.
+]=]
+function Entity.Push(self: Entity, time: number, value: CFrame, velocity: Vector3?): boolean
+	const snapshot = self.snapshot
+	const newer = not self.latestTime or time > self.latestTime
+	if newer then
+		self.latestTime = time
+		self.latestCFrame = value
+	end
+	if snapshot then
+		const latest = snapshot:GetLatest()
+		if not IS_SERVER and newer and latest and time - latest.t < 5 and not self.isContextOwner then
+			const targetTime = Entity.GetTargetRenderTime(self)
+			if math.abs(targetTime - latest.t) > 5 then
+				snapshot:Clear()
+				Warn.low(`Clearing Snapshot due to large time difference`)
+			end
+		end
+		local tickrate = self.entityConfig.TICK_RATE
+		if self.isHalfTicked then
+			tickrate = tickrate * 2
+		end
+		snapshot:PushWithCheck(
+			time,
+			value,
+			velocity or VelocityAt(snapshot:GetLatest(), time, value, tickrate),
+			tickrate
+		)
+	end
+	FireEvent(self, "PushedSnapShot", time, value, newer)
+	return newer
+end
+
+--[=[
+	Gets the CFrame value at a specific time from the entity's snapshot.
+
+	@param time The time to get the CFrame value for.
+
+	@return The CFrame value at the specified time, or the latest CFrame if no snapshot exists.
+]=]
+function Entity.GetAt(self: Entity, time: number): CFrame?
+	const snapshot = self.snapshot
+	if snapshot then
+		return snapshot:GetAt(time)
+	else
+		return self.latestCFrame
+	end
+end
+
+--[=[
+	Gets the target render time from the entity's client clock.
+
+	@return The target render time.
+]=]
+function Entity.GetTargetRenderTime(self: Entity): number
+	local renderCache = self._clientClock
+
+	if not renderCache then
+		const RenderCaches = self.entityConfig.CLIENT_CLOCK
+		if not RenderCaches then
+			return -1
+		end
+		renderCache = self.isHalfTicked and RenderCaches.HALF or RenderCaches.NORMAL
+	end
+	if not renderCache then
+		return -1
+	end
+	return renderCache:GetTargetRenderTime()
+end
+
+--[=[
+	Sets whether the entity should auto update its position to the model's primary part CFrame.
+
+	@param autoUpdate Whether to auto update the entity's position.
+]=]
+function Entity.SetAutoUpdatePos(self: Entity, autoUpdate: boolean)
+	SetValue(self, "autoUpdatePos", autoUpdate)
+end
+
+--[=[
+	Gets the current CFrame of the entity.
+
+	@return The current CFrame of the entity.
+]=]
+function Entity.GetCFrame(self: Entity): CFrame?
+	const part = GetPart(self)
+	return self.latestCFrame or (part and part.CFrame)
+end
+
+--[=[
+	Sets the current CFrame of the entity and locks the snapshot to the new time.
+
+	@param cframe The CFrame to set for the entity.
+]=]
+function Entity.SetCFrame(self: Entity, cframe: CFrame)
+	const latestTime = (self.latestTime or 0) + 0.00002
+	if Config.FLAGS.SET_CFRAME_FIX then
+		if IS_SERVER or self.networkOwner then
+			self._teleport = os.clock()
+		end
+		if not IS_SERVER and not self.isContextOwner then
+			Entity.Clear(self)
+		end
+	end
+	if self.snapshot and Config.FLAGS.FIX_TELEPORT_JITTER then
+		self.snapshot.lockedTime = latestTime
+	end
+	Entity.Push(self, latestTime, cframe)
+	SetValue(self, "latestCFrame", cframe, true)
+
+	if self.isContextOwner or not IS_SERVER then
+		SetPartCFrame(self, cframe)
+	end
+end
+
+--[=[
+	Gets the primary part of the entity's model. If the model is a BasePart, returns the model itself.
+
+	@return The primary part of the entity's model, or nil if no model or primary part exists.
+]=]
+function Entity.GetPrimaryPart(self: Entity): BasePart?
+	if self.model then
+		return GetPart(self)
+	end
+	return nil
+end
+
+--[=[
+	Locks the native server CFrame replication for the entity.
+
+	Only works if the entity's model replication mode is "NATIVE".
+
+	Throws an error if called on the client or if the model replication mode is not "NATIVE".
+]=]
+function Entity.LockNativeServerCFrameReplication(self: Entity)
+	if IS_SERVER then
+		if self.modelReplicationMode ~= "NATIVE" then
+			error("LockNativeServerCFrameReplication can only be called on NATIVE model replication mode entities")
+		end
+		if self._lockedCFReplication then
+			return
+		end
+		SetValue(self, "_lockedCFReplication", true)
+
+		CheckNetworkOwner(self, self.networkOwner)
+
+		FireEvent(self, "LockChanged", true)
+	else
+		error("LockNativeServerCFrameReplication can only be called on the server")
+	end
+end
+
+--[=[
+	Unlocks the native server CFrame replication for the entity.
+
+	Only works if the entity's model replication mode is "NATIVE".
+
+	Throws an error if called on the client or if the model replication mode is not "NATIVE".
+]=]
+function Entity.UnlockNativeServerCFrameReplication(self: Entity)
+	if IS_SERVER then
+		if self.modelReplicationMode ~= "NATIVE" then
+			error("LockNativeServerCFrameReplication can only be called on NATIVE model replication mode entities")
+		end
+		if not self._lockedCFReplication then
+			return
+		end
+		SetValue(self, "_lockedCFReplication", false)
+		const part = GetPart(self)
+		UnlockCFReplication(part)
+		CheckNetworkOwner(self, self.networkOwner)
+		FireEvent(self, "LockChanged", false)
+	else
+		error("LockNativeServerCFrameReplication can only be called on the server")
+	end
+end
+
+--[=[
+	Returns the current model replication type of the entity, which can be "NATIVE", "CUSTOM", or "NATIVE_WITH_LOCK".
+
+]=]
+function Entity.GetModelReplicationType(self: Entity): "NATIVE" | "CUSTOM" | "NATIVE_WITH_LOCK"
+	local mode = self.modelReplicationMode
+
+	if not mode then
+		mode = self.entityConfig.MODEL_REPLICATION_MODE
+	end
+	if mode == "CUSTOM" then
+		return "CUSTOM"
+	end
+	if self._lockedCFReplication then
+		return "NATIVE_WITH_LOCK"
+	end
+	return "NATIVE"
+end
+
+--[=[
+	Destroys the entity, unregistering it and cleaning up resources.
+]=]
+function Entity.Destroy(self: Entity)
+	self.destroyed = true
+	FireEvent(self, "Destroying")
+	Holder.UnregisterEntity(self)
+	if self._clientClock then
+		self._clientClock:Destroy()
+	end
+
+	if not IS_SERVER then
+		const modeType = self.modelReplicationMode
+		const primaryPat = GetPart(self)
+		if modeType == "CUSTOM" then
+			SafeDestroy(self.model)
+		elseif primaryPat then
+			if self._lockedCFReplication then
+				UnlockCFReplication(primaryPat)
+			end
+			primaryPat.CFrame = CFrame.new(0, 1000000, 0)
+		end
+	else
+		SafeDestroy(self.model)
+	end
+
+	for eventName, signal: Types.Signal<any> in (self._events or {}) :: any do
+		signal:DisconnectAll()
+	end
+	self.model = nil
+	--//TODO: add more
+end
+
+--[=[
+	Gets the event signal for the specified event name.
+
+	@param eventName The name of the event to get.
+
+	@return The event signal associated with the specified event name.
+]=]
+Entity.GetEvent = (GetEvent :: any) :: ((
+	self: Entity,
+	eventName: "Destroying"
+) -> Types.Event<(entity: Entity) -> (), Entity>) & ((
+	self: Entity,
+	eventName: "NetworkOwnerChanged"
+) -> Types.Event<(entity: Entity, newOwner: Player?, prevOwner: Player?) -> (), Entity, Player?, Player?>) & ((
+	self: Entity,
+	eventName: "PushedSnapShot"
+) -> Types.Event<
+	(entity: Entity, time: number, value: CFrame, isNewest: boolean) -> (),
+	Entity,
+	number,
+	CFrame,
+	boolean
+>) & ((
+	self: Entity,
+	eventName: "TickChanged"
+) -> Types.Event<(entity: Entity, newTickType: "NONE" | "HALF" | "NORMAL") -> (), Entity, string>) & ((
+	self: Entity,
+	eventName: "DataChanged"
+) -> Types.Event<(entity: Entity, data: any) -> (), Entity, any>) & ((
+	self: Entity,
+	eventName: "Ticked"
+) -> Types.Event<(entity: Entity, dt: number) -> (), Entity, number>) & ((
+	self: Entity,
+	eventName: "ModelChanged"
+) -> Types.Event<
+	(entity: Entity, newModel: Model | BasePart?, oldModel: Model | BasePart?) -> (),
+	Entity,
+	Model | BasePart?,
+	Model | BasePart?
+>) & ((
+	self: Entity,
+	eventName: "LockChanged"
+) -> Types.Event<(entity: Entity, isLocked: boolean) -> (), Entity, boolean>)
+
+Players.PlayerAdded:Connect(function(player)
+	clientOwned[player] = {}
+end)
+
+if Players.LocalPlayer then
+	clientOwned[Players.LocalPlayer] = {}
+end
+
+Players.PlayerRemoving:Connect(function(player)
+	clientOwned[player] = nil
+end)
+
+Events._Signals["请不要使用_内部_设置值_拜托谢谢_嗨_这个名字有点长_好吧_再见_算了_这个确实被用了_因为递归错误_而我懒得去解决_所以这是一个能用的_创可贴式修复_好吧"].Event:Connect(
+	SetValue
+)
+Entity._Changes = Changes
+Entity._GetPart = GetPart
+Entity._SetPartCFrame = SetPartCFrame
+Entity._GetRootPart = GetRootPart
+Entity._LockPartPhysicsReplication = LockCFReplication
+Entity._UnlockPartPhysicsReplication = UnlockCFReplication
+Entity._UpdateClockBuffer = SetClock
+return Entity