版本：最新版 - a1.156.0 ⚖️

基础实体

Entity 是所有类的基础母版，所有这些实体都共享本页面中所描述的方法和事件。

👪Base Class

This is a Base Class, an abstract definition that shares common methods and events with it's child classes. You cannot spawn it, and you cannot call anything on the Base Class name itself. Use any class that inherits it.

Classes that share methods and events from this Base Class: Billboard, Blueprint, Cable, Canvas, Character, CharacterSimple, Decal, Gizmo, Grenade, InstancedStaticMesh, Light, Melee, Particle, Player, Prop, SceneCapture, StaticMesh, Sound, TextRender, Text3D, Trigger, VehicleWheeled, VehicleWater, Weapon, WebUI, Widget, Widget3D.

🗿 静态函数

Returns	Name	Description
table of Base Entity	`GetAll`	返回一个包含调用此方法的类中所有实体的表
Base Entity	`GetByIndex`	返回该类中指定索引处的特定实体
integer	`GetCount`	返回该类当前存在的实体数量
table of table	`GetInheritedClasses`	获取使用继承系统创建的、直接继承自该类的所有子类列表
iterator	`GetPairs`	返回一个包含该类所有实体的迭代器，用于 `pairs()` 循环
table or nil	`GetParentClass`	如果该类是使用继承系统创建的，则获取其父类
table	`Inherit`	使用继承系统继承此类
boolean	`IsChildOf`	如果该类是使用继承系统创建的，检查此类是否为另一个类的子类
function	`Subscribe`	为该类的所有实体订阅一个事件
function	`SubscribeRemote`	订阅从服务器调用的自定义远程事件
	`Unsubscribe`	退订此包内该类中此事件的所有回调，或者仅取消传入的特定回调

Moderate

`GetAll`

返回一个包含调用此方法的类中所有实体的表

local ret = <AnyEntityClass>.GetAll()

Returns

Type	Description
table of Base Entity	包含所有实体的表副本

Optimal

`GetByIndex`

返回该类中指定索引处的特定实体

local ret = <AnyEntityClass>.GetByIndex(index)

Parameters

Type	Parameter	Default	Description
integer	`index`	Required parameter	实体的索引

Returns

Type	Description
Base Entity	该索引处的实体

Optimal

`GetCount`

返回该类当前存在的实体数量

local ret = <AnyEntityClass>.GetCount()

Returns

Type	Description
integer	该类的实体数量

Moderate

`GetInheritedClasses`

获取使用继承系统创建的、直接继承自该类的所有子类列表

local ret = <AnyEntityClass>.GetInheritedClasses(recursively?)

Parameters

Type	Parameter	Default	Description
boolean	`recursively?`	`false`	是否返回所有层级的继承子类

Returns

Type	Description
table of table	所有子类表

Optimal

`GetPairs`

返回一个包含该类所有实体的迭代器，用于 pairs() 循环。这是一个比 GetAll() 性能更高的方法，因为它直接返回访问实体的迭代器，而不是创建并返回实体表副本。

注：在 GetPairs() 循环内部销毁实体会导致可迭代对象在执行过程中改变大小。如果你需要进行循环并销毁操作，请使用 GetAll()。

local ret = <AnyEntityClass>.GetPairs()

Returns

Type	Description
iterator	包含该类所有实体的迭代器

Optimal

`GetParentClass`

如果该类是使用继承系统创建的，则获取其父类

local ret = <AnyEntityClass>.GetParentClass()

Returns

Type	Description
table or nil	父类

Slow

`Inherit`

使用继承系统继承此类

local class = <AnyEntityClass>.Inherit(name, custom_values?)

Parameters

Type	Parameter	Default	Description
string	`name`	Required parameter	新类的名称
table	`custom_values?`	`{}`	一个可选的表，包含要在继承的类表中设置的自定义值

Returns

Type	Description
table	新类的表

Optimal

`IsChildOf`

如果该类是使用继承系统创建的，检查此类是否为另一个类的子类

local ret = <AnyEntityClass>.IsChildOf(class)

Parameters

Type	Parameter	Default	Description
table	`class`	Required parameter	要检查的另一个类

Returns

Type	Description
boolean	通过 <a href='/docs/core-concepts/scripting/inheriting-classes'>继承系统</a> 创建的此类是否为另一个类的子类

Optimal

`Subscribe`

为该类的所有实体订阅一个事件

local ret = <AnyEntityClass>.Subscribe(event_name, callback)

Parameters

Type	Parameter	Default	Description
string	`event_name`	Required parameter	要订阅的事件名称
function	`callback`	Required parameter	触发事件时要调用的函数

Returns

Type	Description
function	传进来的回调函数（如果你的回调是匿名函数，这对于以后退订很有用）

Optimal

`SubscribeRemote`

订阅从服务器调用的自定义远程事件

local ret = <AnyEntityClass>.SubscribeRemote(event_name, callback)

Parameters

Type	Parameter	Default	Description
string	`event_name`	Required parameter	要订阅的事件名称
function	`callback`	Required parameter	触发事件时要调用的函数

Returns

Type	Description
function	传入的回调函数（如果回调函数是匿名函数，则便于日后取消订阅）

Optimal

`Unsubscribe`

退订此包内该类中此事件的所有回调，或者仅取消传入的特定回调

<AnyEntityClass>.Unsubscribe(event_name, callback?)

Parameters

Type	Parameter	Default	Description
string	`event_name`	Required parameter	要退订的事件名称
function	`callback?`	`nil`	可选，要退订的特定回调函数

🦠 函数

Returns	Name	Description
	`BroadcastRemoteEvent`	直接在此实体上向所有玩家调用自定义远程事件
	`BroadcastRemoteInRadiusEvent`	直接针对此实体调用自定义远程事件，并将该事件传递给半径范围内的所有玩家
	`CallRemoteEvent`	直接在此实体上向特定玩家调用自定义远程事件
	`CallRemoteEvent`	直接在此实体上调用自定义远程事件
	`CallRemotePlayersEvent`	直接在此实体上调用自定义远程事件，并将事件传递给玩家列表
	`Destroy`	销毁该实体
	`FinishSpawn`	如果此实体是以延迟 `spawn_mode` 生成的，则完成生成过程并将该实体发送至客户端
table of string	`GetAllValuesKeys`	获取所有存储值的键名列表
table	`GetClass`	获取该实体的类
integer	`GetID`	获取该实体的全网通用网络 ID（在客户端和服务器上相同）
any	`GetValue`	获取此实体上存储在给定键处的值
boolean	`HasAuthority`	获取本地上下文是否对此实体拥有主控（如果由客户端生成则为 true，由服务器生成则为 false）
boolean	`IsA`	递归检查此实体是否继承自某个类
boolean	`IsBeingDestroyed`	如果该实体正在被销毁，则返回 true
boolean	`IsSpawned`	获取此实体是否已完成生成
boolean	`IsValid`	如果该实体有效（即未被销毁且指向一个有效的实体），则返回 true
	`SetSpawnMode`	从继承类的构造函数中覆盖此实体完成生成的时间点
	`SetValue`	在此实体中设置一个值
function	`Subscribe`	在这个特定实体上订阅一个事件
function	`SubscribeRemote`	在这个特定实体上订阅一个从服务器调用的自定义远程事件
	`Unsubscribe`	退订此包内该实体中此事件的所有回调，或者仅取消传入的特定回调

Moderate

`BroadcastRemoteEvent`

直接在此实体上向所有玩家调用自定义远程事件

🆕Updated Function

This method was recently updated in ver. 1.139. See the Compatibility Versions page for more information.

my_entity:BroadcastRemoteEvent(event_name, reliability?, args...?)

Parameters

Type	Parameter	Default	Description
string	`event_name`	Required parameter	用于触发事件的事件名称
Reliability	`reliability?`	`Reliability.Reliable`	网络可靠性规则
any	`args...?`	`nil`	传递给事件的参数

Moderate

`BroadcastRemoteInRadiusEvent`

直接针对此实体调用自定义远程事件，并将该事件传递给半径范围内的所有玩家

my_entity:BroadcastRemoteInRadiusEvent(event_name, radius, reliability?, args...?)

Parameters

Type	Parameter	Default	Description
string	`event_name`	Required parameter	用于触发事件的事件名称
float	`radius`	Required parameter	发送此事件的半径
Reliability	`reliability?`	`Reliability.Reliable`	网络可靠性规则
any	`args...?`	`nil`	传递给事件的参数

Moderate

`CallRemoteEvent`

直接在此实体上向特定玩家调用自定义远程事件

🆕Updated Function

This method was recently updated in ver. 1.139. See the Compatibility Versions page for more information.

my_entity:CallRemoteEvent(event_name, player, reliability?, args...?)

Parameters

Type	Parameter	Default	Description
string	`event_name`	Required parameter	用于触发事件的事件名称
Player	`player`	Required parameter	接收此事件的远程玩家
Reliability	`reliability?`	`Reliability.Reliable`	网络可靠性规则
any	`args...?`	`nil`	传递给事件的参数

Moderate

`CallRemoteEvent`

直接在此实体上调用自定义远程事件

🆕Updated Function

This method was recently updated in ver. 1.139. See the Compatibility Versions page for more information.

my_entity:CallRemoteEvent(event_name, reliability?, args...?)

Parameters

Type	Parameter	Default	Description
string	`event_name`	Required parameter	用于触发事件的事件名称
Reliability	`reliability?`	`Reliability.Reliable`	网络可靠性规则
any	`args...?`	`nil`	传递给事件的参数

Moderate

`CallRemotePlayersEvent`

直接在此实体上调用自定义远程事件，并将事件传递给玩家列表

my_entity:CallRemotePlayersEvent(event_name, players, reliability?, args...?)

Parameters

Type	Parameter	Default	Description
string	`event_name`	Required parameter	用于触发事件的事件名称
table of Player	`players`	Required parameter	发送该事件的目标远程玩家列表
Reliability	`reliability?`	`Reliability.Reliable`	网络可靠性规则
any	`args...?`	`nil`	传递给事件的参数

Moderate

`Destroy`

销毁该实体

my_entity:Destroy()

Moderate

`FinishSpawn`

如果实体是以 SpawnMode.AfterConstructor 或 SpawnMode.Manual 生成的，则完成生成过程并将实体发送至客户端。请在配置完实体后调用此函数以提高生成效率。

注：对于通过 SpawnMode.AfterConstructor 构造的继承类实体，会在其构造函数返回时自动完成生成。

my_entity:FinishSpawn()

Moderate

`GetAllValuesKeys`

获取所有存储值的键名列表

local ret = my_entity:GetAllValuesKeys()

Returns

Type	Description
table of string	包含所有存储值键名的列表

`GetClass`

获取该实体的类

local class = my_entity:GetClass()

Returns

Type	Description
table	此实体的类

Optimal

`GetID`

获取该实体的全网通用网络 ID（在客户端和服务器上相同）

local id = my_entity:GetID()

Returns

Type	Description
integer	此实体的通用网络 ID

Optimal

`GetValue`

获取此实体上存储在给定键处的值。请参考实体值获取更多信息

local value = my_entity:GetValue(key, fallback)

Parameters

Type	Parameter	Default	Description
string	`key`	Required parameter	键
any	`fallback`	Required parameter	如果键不存在时的备用值

Returns

Type	Description
any	指定键的值，若键不存在则返回回退值

`HasAuthority`

获取本地上下文是否对此实体拥有主控（如果由客户端生成则为 true，由服务器生成则为 false）

local ret = my_entity:HasAuthority()

Returns

Type	Description
boolean	如果由客户端生成则为 true，由服务器生成则为 false

Moderate

`IsA`

递归检查此实体是否继承自某个类

local ret = my_entity:IsA(class)

Parameters

Type	Parameter	Default	Description
table	`class`	Required parameter	类

Returns

Type	Description
boolean	此实体是否属于该类或继承自该类

Optimal

`IsBeingDestroyed`

如果该实体正在被销毁，则返回 true。
你可以在诸如 Drop 的事件中检查此状态，以判断一个可拾取物是否是因为即将被销毁而被丢弃

local ret = my_entity:IsBeingDestroyed()

Returns

Type	Description
boolean	此实体是否正在被销毁

Optimal

`IsSpawned`

获取此实体是否已完成生成。

以延迟 SpawnMode 生成的实体仅会在调用 FinishSpawn() 后或继承类构造函数返回时才完成生成，其他模式下生成的实体会立即完成生成。

local ret = my_entity:IsSpawned()

Returns

Type	Description
boolean	实体是否已完成生成

Optimal

`IsValid`

如果该实体有效（即未被销毁且指向一个有效的实体），则返回 true

local is_valid = my_entity:IsValid()

Returns

Type	Description
boolean	此实体是否有效

Optimal

`SetSpawnMode`

从继承类的构造函数中覆盖此实体完成生成的时间点。

仅接受 SpawnMode.AfterConstructor 和 SpawnMode.Manual，且仅在该实体尚未完成生成时生效。

my_entity:SetSpawnMode(spawn_mode)

Parameters

Type	Parameter	Default	Description
SpawnMode	`spawn_mode`	Required parameter	仅接受 `SpawnMode.AfterConstructor` 和 `SpawnMode.Manual`

Optimal

`SetValue`

在此实体中设置一个值，该值可以被任何包访问（如果是从服务器调用，则可以跨客户端选择性同步）

请参考实体值进一步了解

my_entity:SetValue(key, value, sync_on_clients?)

Parameters

Type	Parameter	Default	Description
string	`key`	Required parameter	键
any	`value`	Required parameter	要设置的值，可以是任何可序列化类型（函数除外）
boolean	`sync_on_clients?`	`false`	服务器端参数，如果启用，将此值与所有客户端同步

`Subscribe`

在这个特定实体上订阅一个事件

local ret = my_entity:Subscribe(event_name, callback)

Parameters

Type	Parameter	Default	Description
string	`event_name`	Required parameter	要订阅的事件名称
function	`callback`	Required parameter	触发事件时要调用的函数

Returns

Type	Description
function	传入的回调函数（如果回调函数是匿名函数，则便于日后取消订阅）

Optimal

`SubscribeRemote`

在这个特定实体上订阅一个从服务器调用的自定义远程事件

local ret = my_entity:SubscribeRemote(event_name, callback)

Parameters

Type	Parameter	Default	Description
string	`event_name`	Required parameter	要订阅的事件名称
function	`callback`	Required parameter	触发事件时要调用的函数

Returns

Type	Description
function	传入的回调函数（如果回调函数是匿名函数，则便于日后取消订阅）

Optimal

`Unsubscribe`

退订此包内该实体中此事件的所有回调，或者仅取消传入的特定回调

my_entity:Unsubscribe(event_name, callback?)

Parameters

Type	Parameter	Default	Description
string	`event_name`	Required parameter	要退订的事件名称
function	`callback?`	`nil`	可选，要退订的特定回调函数

🚀 事件

	Name	Description
	`ClassRegister`	当使用继承系统注册一个新类时触发
	`Destroy`	当实体被销毁时触发
	`Spawn`	当实体被生成/创建时触发
	`ValueChange`	当实体通过 `:SetValue()` 改变了值时触发

`ClassRegister`

当使用继承系统注册一个新类时触发

<AnyEntityClass>.Subscribe("ClassRegister", function(class)
	-- ClassRegister was called
end)

Arguments

Type	Argument	Description
table	`class`	被继承的类

`Destroy`

当实体被销毁时触发

<AnyEntityClass>.Subscribe("Destroy", function(self)
	-- Destroy was called
end)

Arguments

Type	Argument	Description
Base Entity	`self`	被销毁的实体

`Spawn`

当实体被生成/创建时触发

<AnyEntityClass>.Subscribe("Spawn", function(self)
	-- Spawn was called
end)

Arguments

Type	Argument	Description
Base Entity	`self`	被生成的实体

`ValueChange`

当实体通过 :SetValue() 改变了值时触发

<AnyEntityClass>.Subscribe("ValueChange", function(self, key, value)
	-- ValueChange was called
end)

Arguments

Type	Argument	Description
Base Entity	`self`	值刚刚发生改变的实体
string	`key`	所使用的键
any	`value`	被设置的新值

🗿 静态函数​

GetAll​

Returns

GetByIndex​

Parameters

Returns

GetCount​

Returns

GetInheritedClasses​

Parameters

Returns

GetPairs​

Returns

GetParentClass​

Returns

Inherit​

Parameters

Returns

IsChildOf​

Parameters

Returns

Subscribe​

Parameters

Returns

SubscribeRemote​

Parameters

Returns

Unsubscribe​

Parameters

🦠 函数​

BroadcastRemoteEvent​

Parameters

BroadcastRemoteInRadiusEvent​

Parameters

CallRemoteEvent​

Parameters

CallRemoteEvent​

Parameters

CallRemotePlayersEvent​

Parameters

Destroy​

FinishSpawn​

GetAllValuesKeys​

Returns

GetClass​

Returns

GetID​

Returns

GetValue​

Parameters

Returns

HasAuthority​

Returns

IsA​

Parameters

Returns

IsBeingDestroyed​

Returns

IsSpawned​

Returns

IsValid​

Returns

SetSpawnMode​

Parameters

SetValue​

Parameters

Subscribe​

Parameters

Returns

SubscribeRemote​

Parameters

Returns

Unsubscribe​

Parameters

🚀 事件​

ClassRegister​

Arguments

Destroy​

Arguments

Spawn​

🗿 静态函数

`GetAll`

`GetByIndex`

`GetCount`

`GetInheritedClasses`

`GetPairs`

`GetParentClass`

`Inherit`

`IsChildOf`

`Subscribe`

`SubscribeRemote`

`Unsubscribe`

🦠 函数

`BroadcastRemoteEvent`

`BroadcastRemoteInRadiusEvent`

`CallRemoteEvent`

`CallRemoteEvent`

`CallRemotePlayersEvent`

`Destroy`

`FinishSpawn`

`GetAllValuesKeys`

`GetClass`

`GetID`

`GetValue`

`HasAuthority`

`IsA`

`IsBeingDestroyed`

`IsSpawned`

`IsValid`

`SetSpawnMode`

`SetValue`

`Subscribe`

`SubscribeRemote`

`Unsubscribe`

🚀 事件

`ClassRegister`

`Destroy`

`Spawn`

`ValueChange`