meta data for this page

📚 World/Model

在《沙盘引擎》世界中，所有关于3D模型、物体实例均属于Model对象。

在此基础上，Model还分为静态、动态两种不同实例形态：

静态实例：通常由游戏地图生成的地图对象，这些对象通常只作为世界的建筑装饰及碰撞，不具有动态对象特性（不可通过脚本编辑）。

动态实例：由开发者在脚本中实时创建的Model.Create()对象，拥有动态对象特性（可通过脚本编辑）。

补充：静态实例默认不具备动态对象特性，如果部分静态对象有世界交互&脚本编辑等需求，可通过【地图编辑器】选中目标对象，属性界面勾选【动态对象】来强制动态实例（请确保脚本中可能用到，否则动态对象会相对占用更多性能）。

📒 Event

📘 OnModelDamage( model, damage, from, type, isImmunity )

当模型对象被攻击时调用，攻击检测应该优先考虑此事件。 

function OnModelDamage( model: Model, damage: int, from: Entity, type: int, isImmunity: bool, localHitPos: Vector )
/*
	model：触发实例
	damage：伤害值
	from：造成伤害的对象（可能null，例如碰撞）
	type：伤害类型
	isImmunity：是否免疫伤害（如果为true，则表示没有造成伤害，可能被Immunity\Group拦截了）
	localHitPos：受击位置的本地坐标
*/

📘 OnModelCollision( model, from )

当模型对象被其他实体对象碰撞时调用。 

function OnModelCollision( model: Mode, from: Entity )

📘 OnModelHealthChange( model, oldHealth, newHealth )

当模型对象血量发生改变时调用。

由于模型对象的特殊性，通常默认Health为0，所以很可能被攻击时不会调用此事件（因为默认值与最小值是0，数值没有发生改变）。

检测攻击应该优先考虑OnModelDamage()事件。

📒 Property

📘 model.ID

获取模型对象序列ID，每个实例ID是唯一的。

当之前的实例被销毁后，空闲的靠前ID将会被后续新实例重新使用（对于特殊情况，UUID是更合适的筛选选择）。

补充：部分游戏地图文件内置了一些【动态模型对象】，这将导致加载地图时直接生成【动态Model】，所以可能会出现“服务器任何Model.Create()代码都没写，但是ID不是从0开始”的情况，这是因为一些ID被提前使用了。 

model.ID: int

📘 model.UUID

获取模型对象UUID，这是由一串较长的字符串组成的全局唯一文本ID。 

model.UUID: string

📘 model.World

设置模型对象实例世界ID（不同世界将不可视\不可交互）。 

model.World = 0; //int

📘 model.Group

设置模型对象实例组，当前版本对于Model实例暂无功能意义。 

model.Group = 0; //int

📘 model.Tag

设置模型对象标签，此处的Model.Tag与基类Entity.Tag共用属性，并非单独的Tag属性。

此属性设置为非空值将会同步提交到TagList（可使用API遍历），空值（默认）不会进行提交。 

model.Tag = "";

📘 model.ModelID

获取（只读）对象的模型ID。 

model.ModelID: int

📘 model.Health

设置模型对象实例血量（仅有属性作用，没有受击及伤害效果，具体逻辑需要开发者自行编写），默认值与最小值为0。 

model.Health = 0; //int

📘 model.Flags

设置模型对象的Flags属性值（可叠加位Flag），参考《模型对象特殊属性》。 

model.Flags = 0; //int

📘 model.Immunity

设定模型对象的免疫属性（可叠加位Flag），设置为-1自动识别完全免疫（所有Flag相加后的结果）。 

model.Immunity = 0; //int
 
//可根据具体需求叠加属性
//示例：无视子弹和爆炸伤害，其他正常
model.Immunity = 2 + 4; //或直接设为6

📘 model.Pos

设置模型对象坐标。 

model.Pos = Vector(0, 0, 0);

📘 model.Angle

设置模型对象角度。 

model.Angle = 0.0; //float

📘 model.EulerAngle

设置模型对象欧拉角度。 

model.EulerAngle = Vector(0, 0, 0);

📘 model.Scale

设置模型对象3D尺寸缩放。 

model.Scale = Vector(1, 1, 1); //默认全部为1，无论尺寸是否内部缩放

📘 model.Color

设置模型对象特定颜色或覆盖颜色，如果需要修改透明度，应该使用model.Alpha。 

model.Color = Color(255, 255, 255);

📘 model.Alpha

设置模型对象实例透明度，默认为255。 

model.Alpha = 255; //int

📘 model.Collision

设置模型对象是否开启碰撞逻辑，默认为true。 

model.Collision = false; //bool

📘 model.Physics

设置模型对象物理模式开关，默认关闭，只有动态对象可以使用此属性。 

model.Physics = false; //bool

📘 model.Enum

设置模型对象的Enum属性值，不同类型的模型可能有不同的作用（或默认值）。 

model.Enum = 0; //int

📘 model.BoolValue

设置模型对象的BoolValue属性值，不同类型的模型可能有不同的作用（或默认值）。 

model.BoolValue = false; //bool

📘 model.StringValue

设置模型对象的StringValue属性值，不同类型的模型可能有不同的作用（或默认值）。 

model.StringValue = ""; //string

📘 model.Range

设置模型对象的Range属性值，不同类型的模型可能有不同的作用（或默认值）。 

model.Range = 0.0; //float

📘 model.Intensity

设置模型对象的Intensity属性值，不同类型的模型可能有不同的作用（或默认值）。 

model.Intensity = 0.0; //float

📘 model.BoundSize

获取模型原始尺寸计算值（类似面积），会随着对象缩放尺寸而改变。 

model.BoundSize: float //数字越大表示尺寸越大，根据内置标准的尺寸规范计算

📘 model.HasParent

获取模型是否拥有绑定的父物体或节点（只读）。 

model.HasParent: bool

📘 model.Emission

设置模型对象发光亮度倍数，默认为0.0（原始亮度），如果希望增加亮度（或者高光）至少需要修改数值>1，反之则表示降低亮度。

注意：这里的“高光”仅指亮度渲染效果，实际光源渲染与Light有区别，不会有真正的光源照射效果。 

model.Emission = 0.0; //float
model.Emission = 0.0; //Disable
model.Emission = 1.0; //Enable, but default(1*1=1)
model.Emission = 2.0; //Enable, brightness(1*2=2)

📒 Static Function

📘 Model.Create()

生成一个新的模型对象实例（由此生成的全部为动态对象）。 

function Model.Create( model: int, pos: Vector, angle: float|vector ): Model
//在0点坐标处，建立一个模型ID为0、角度为10的模型对象实例
let newModel = Model.Create(0, Vector(0, 0, 0), 10);
let newModel2 = Model.Create(0, Vector(0, 0, 0), Vector(0, 10, 0)); //角度参数不同，可传递更详细的欧拉角

📘 Model.CreateEffect()

此方法在V0.8+被弃用。

生成一个新的效果对象实例（粒子等）（由此生成的全部为动态对象），效果索引参考《世界资源实例汇总——粒子效果表格》。

不同索引代表的效果样式不同，效果周期可能是循环播放、单次播放等，由此代码生成的单次播放对象会在播放结束后自动销毁，但循环播放的对象永远不会，直到手动Remove()对象。

注意：此方法相当于Model.Create()的扩展快速方法，帮助开发者快速生成效果对象，其原理仍然基于Model类。

注意：此方法在内部基于Model+DynamicObject实现，因此有额外的性能开销。

如果不需要关于Model API的相关功能，建议优先使用World.CreateEffect() | Client.CreateEffect()生成效果对象实例。 

function Model.CreateEffect( effect: int, pos: Vector, angle: float|vector ): Model
//生成一个爆炸效果（仅有效果），没有爆炸伤害
CreateEffect(3, Vector(0, 0, 0));

📘 Model.Find()

寻找一个模型对象实例（通过ID），不存在则返回null。 

function Model.Find( id: int ): Model

📘 Model.FindByUUID()

寻找一个模型对象实例（通过UUID），不存在则返回null。 

function Model.FindByUUID( uuid: string ): Model

📘 Model.GetCount()

获取当前所有存在模型对象数量（不包括静态对象）。 

function Model.GetCount(): int

📘 Model.Get()

获取当前存在的指定索引模型对象，通常搭配GetCount()遍历使用。 

function Model.Get( index: int ): Model

📘 Model.GetTagCount()

获取当前所有满足Tag筛选的模型对象数量（所有Tag为xxx的模型对象数量）。 

function Model.GetTagCount( tag: string ): int

📘 Model.GetByTag()

获取当前所有满足Tag筛选的模型对象，通常搭配GetTagCount()遍历使用。 

function Model.GetByTag( tag: string, index: int = 0 ): Model

📘 Model.ExistModel()

判断指定模型Model是否存在引擎中（是否存在模型可被加载）。 

function Model.ExistModel( model: int ): bool

📒 Function

📘 model.Remove()

销毁当前模型对象实例。 

function model.Remove()

📘 model.Damage()

以标准方式攻击当前模型对象实例，有关Reason原因，请参考《世界资源实例汇总——伤害触发类型》。

注意：Model对象默认是没有受击逻辑的，即使血量为0也不会触发任何效果，此类内容需要开发者自行编写。 

function model.Damage( damage: int, from: Entity = null, reason: int = 0, localHitPos: Vector = Vector(0, 0, 0) )

📘 model.ExistFlag()

获取模型对象Flags是否已激活指定的Flag。 

function model.ExistFlag( flag: int ): bool

📘 model.AddForce()

增加一个当前对象的物理作用力，默认为本地坐标系（根据参数isLocal）。

注意：此方法只有【动态物体+激活物理Physics == true】的对象可使用。 

function model.AddForce( force: Vector, isLocal: bool = true )
let obj = Model.Create(...);
obj.AddForce( Vector(0, 3, 0) ); //对象立即向上冲刺一段距离(y)

📘 model.AddTurnForce()

增加一个当前对象的物理旋转力，默认为本地坐标系（根据参数isLocal）。

注意：此方法只有【动态物体+激活物理Physics == true】的对象可使用。 

function model.AddTurnForce( force: Vector, isLocal: bool = true )
let obj = Model.Create(...);
obj.AddTurnForce( Vector(0, 10, 0) ); //对象横向旋转

📘 model.MoveTo()

将当前模型对象过渡移动到目标位置。

（停止过渡：不填写任何参数，执行一次） 

function model.MoveTo( pos: Vector, time: float )

📘 model.RotateTo()

将当前模型对象过渡旋转到目标欧拉角。

（停止过渡：不填写任何参数，执行一次） 

function model.RotateTo( euler: Vector, time: float )

📘 model.ScaleTo()

将当前模型对象过渡缩放到目标尺寸。

（停止过渡：不填写任何参数，执行一次） 

function model.ScaleTo( scale: Vector, time: float )