meta data for this page

📚 World/Entity

Entity类是一个基础抽象类，绝大多数拥有网络同步、自定义实体控制的实例都继承此类。

基于基类和派生类的概念，所有继承自此类的实例均可调用本文属性及方法。

派生类及标准名称 说明
Character 角色类
Vehicle 载具类
Pickup 拾取物类
Checkpoint 检查点类
Model 模型对象类

📒 Property

📘 entity.Data

内置的自定义类型属性（建议使用基础类型），可供开发者自行使用，需要自行做好类型Type和生命周期处理。 

entity.Data = null; //any
let myData = {
    Name: "Tom"
};
 
entity.Data = myData;

📘 entity.UniqueID

获取当前实例当前场景唯一ID标识（>0），且数字不会重复。 

entity.UniqueID: int

📘 entity.Tag

设置当前实例的标签\记录文本，没有实际功能作用，仅供识别和分类，默认为空字符。 

entity.Tag = ""; //string

📘 entity.Group

设置当前实例的对象组，不同的继承子类有不同的意义。

Group == 0表示特殊通用组（默认值），如果需要实现同组的实例交互，请将双方Group设置成非0的任何相同的数字。 

entity.Group = 0; //int

📘 entity.Scale

设置当前实例的整体缩放尺寸，当前除Model类型特别处理外（Model.Scale），其他类型均基于节点进行缩放，没有过多缩放适配，因此可能部分行为（因为尺寸改变）不会按照预期执行。

注意：由于不同对象的实际模型尺寸可能不同，部分过于夸张的尺寸可能导致崩溃。

注意：除特别类型外，属性限制范围为0.01 ~ 5.0。 

entity.Scale = Vector(1, 1, 1); //Vector

📘 entity.Outline

设置当前实体对象描边效果开关（所有人可见模式）。

此属性修改不影响OutlineTarget功能，如果拥有玩家单独绑定时，此属性改变将不会优先生效。 

entity.Outline = false; //bool

📘 entity.OutlineColor

设置当前实体对象的描边效果颜色代码（所有人可见模式生效）。

默认支持三个颜色（0=白色；1=绿色；2=红色）。

此属性当某个玩家被设置OutlineTarget时，将不会再受到此处颜色改变影响。 

entity.OutlineColor = 0; //int

📒 Function

📘 entity.IsValid()

获取当前实例是否真实存在且有效，否则表示实例已经销毁，只是GC没有及时回收垃圾。

对于所有基于Entity的类型，建议判断是否有效时额外判断IsValid()，因为有时可能引用不为null，但实际上对象已经销毁（此时不应该再使用此对象，否则可能会引起异常）。 

function entity.IsValid(): bool
let chara = Character.Create(0, Vector(90, 1, 58), 0);
 
DLog(chara.IsValid()); //返回true，对象状态正常
 
chara.Remove(); //Remove Character
 
DLog(chara); //正常返回，实例虽然销毁，但引用仍然存在，不为null
DLog(chara.IsValid()); //返回false，因为已经被销毁了，不应该再使用了

📘 entity.GetType()

获取当前实例的类型名称（文本），标准文本参考本文顶部表格。

此功能可用来判断当前实例是何种类型（角色、载具等……）。 

function entity.GetType(): string

📘 entity.GetInstance()

获取当前实例（当前被继承的实例），通常只在Entity类检测使用，其他派生类返回的是自身实例。 

function entity.GetInstance(): Entity //返回：基类或派生类
let myCharacter = Character.Create(...);
myCharacter.GetInstance(); //返回：Character类，举一反三

📘 entity.IsSameGroup()

验证某个Entity或GroupID是否与当前实例匹配（相同）。

isForce：强制模式（只有两者Group相等且不为0（特殊组）返回true，否则不作强制非0判断） 

function entity.IsSameGroup( isForce: bool = true ): bool

📘 entity.OutlineTargetTo()

为某个玩家单独设置描边效果，优先权最高（无论是否Outline == true）。

通过此方法设定任意玩家后，相当于激活了白名单描边模式，只有在“白名单列表”里的玩家才会继续可见描边。

如果希望恢复所有人可见模式，需要确保没有任何玩家被单独设置描边，例如使用OutlineTargetOutAll()清除所有描边绑定。 

function entity.OutlineTargetTo( player: Player, color: int = 0 )
/*
	player：指定玩家实例
	color：颜色ID代码，可以为不同玩家设定不同的颜色
*/

📘 entity.OutlineTargetOut()

为某个玩家移除单独描边效果。

如果当前已经没有任何玩家被单独设置描边，则自动恢复所有人可见模式。 

function entity.OutlineTargetOut( player: Player )

📘 entity.OutlineTargetOutAll()

移除当前实体所有单独描边绑定，自动恢复到所有人可见模式。 

function entity.OutlineTargetOutAll()

📘 entity.GetOutlineTargetColor()

获取指定玩家单独描边绑定的颜色，如果不存在绑定则返回-1。 

function entity.GetOutlineTargetColor( player: Player ): int //返回：颜色ID代码

📘 entity.GetVisualRange()

获取实体相对于服务器主机&本地玩家的可见程度（距离流）。

此方法允许提交一个true参数，可用于立即刷新结果，通常可以忽略。

注意：此方法的服务器版本与客户端版本稍有不同，服务器版本下如果有任何玩家仍在范围内，则会始终返回true。

反之亦然，如果服务器版本下返回false，表示此实体当前没有在任何玩家的渲染流范围内。 

function entity.GetVisualRange( update: bool = false ): int
Index 说明
-1 不可见（停止渲染和处理复杂计算）
0 可见范围内（完全渲染及计算）
1 可见范围内，但距离较远