meta data for this page
  •  

📚 差别

这里会显示出您选择的修订版和当前版本之间的差别。

到此差别页面的链接

两侧同时换到之前的修订记录前一修订版
后一修订版		前一修订版
scripting:world:character [2023/08/11 22:26] – bibiboxsscripting:world:character [2025/06/02 14:43] (当前版本) – wpr
行 4: 行 4:
 ## Event ## Event
  
 +### OnCharacterSpawn( character, isCreate )
  
-### OnCharacterPropIdle( character, prop, state )+> 当角色**被生成、被调用`Respawn()`**时触发。 
 +>  
 +> **注意：如果此时调用`character.Owner`将始终返回`null`，因为玩家绑定角色不可能在`OnCharacterSpawn`前绑定。**
  
-> 当角色手中道具`Idle`状态（bool）切换时调用。 + 
-> + 
-> 通常表示正常未使用状态（true）及其他任何被占用状态`Focus\Action\Reload`（false）。+### OnCharacterDeath( character, reason ) 
 + 
 +> 当角色**死亡状态**时触发，**有关`Reason`原因，请参考[《世界资源实例汇总——伤害触发类型》](reference/instances)**，例如通过代码`character.Kill()`则`reason == 0`。 
 + 
 +```javascript 
 +function OnCharacterDeath( character: Character, reason: int ) 
 +``` 
 + 
 + 
 + 
 +### OnCharacterKill( killer, character, reason ) 
 + 
 +> 当角色**被其他角色杀死**时触发，**有关`Reason`原因，请参考[《世界资源实例汇总——伤害触发类型》](reference/instances)**。
 > >
 +> 等待此事件执行完毕后，随后仍然会触发`OnCharacterDeath()`事件。
 +
 +```javascript
 +function OnCharacterKill( killer: Character, character: Character, reason: int )
 +```
 +
 +
 +
 +### OnCharacterPropChange( character, oldProp, newProp )
 +
 +> 当角色手中道具（ID）发生更换时调用。
 +
 +```javascript
 +function OnCharacterPropChange( character: Character, oldProp: Prop, newProp: Prop )
 +```
  
  
行 16: 行 46:
 ### OnCharacterPropFocus( character, prop, state ) ### OnCharacterPropFocus( character, prop, state )
  
-> 当角色手中道具`Focus`状态（bool）切换时调用。 +> 当角色手中道具`HasFocus`状态（bool）切换时调用。
-> +
-> 通常表示开始聚焦（true）及聚焦结束（false）。+
 > >
 +> **说明：表示开始\正在聚焦（true）及聚焦结束（false）。**
  
 +```javascript
 +function OnCharacterPropFocus( character: Character, prop: Prop, state: bool ) 
 +```
  
  
-### OnCharacterPropAction( character, prop, state )  
  
-> 当角色手中道具`Action`状态（bool）切换时调用。 +### OnCharacterPropAction( character, prop, hitPos )  
-> + 
-> 通常表示开始使用（true）及使用结束（false）。+> 当角色手中道具**每次被使用一次**时调用（例如：每次挥拳、开枪等）。
 > >
 +> **注意：`hitPos`参数表示当前物品最终造成伤害的位置，但投掷类物品等无法确定最终位置，所以此处将只返回起点位置。
  
 +[note2]
  
 +补充：如果`character.CanAction == false`，此事件将会在角色尝试发起攻击后立即触发（仅单次触发，即使是连续攻击道具），但不会发起攻击。
  
-### OnCharacterPropReload( character, prop, state )+[/note]
  
-> 当角色手中道具`Reload`状态（bool）切换时调用。 +```javascript 
-> +function OnCharacterPropAction( character: Character, prop: Prop, hitPos: Vector )  
-> 通常表示开始Reload（true）及重载结束（false）。+``` 
 + 
 + 
 + 
 +### OnCharacterOutGround( character ) 
 + 
 +> 当角色**离开地面**时触发。 
 + 
 + 
 + 
 +### OnCharacterFallGround( character ) 
 + 
 +> 当角色**回到\接触地面**时触发，可用`character.FlyTime`获取持续离地时间。 
 + 
 + 
 + 
 +### OnCharacterDamage( character, damage, from, type, isImmunity, localHitPos ) 
 + 
 +> 当角色**被尝试造成任何伤害**时调用，如果造成伤害，会在`OnCharacterHealthChange()`之后调用。
 > >
 +> **有关伤害类型Type，请参考[《世界资源实例汇总——伤害触发类型》](reference/instances)。**
 +
 +```javascript
 +function OnCharacterDamage( character: Character, damage: int, from: Entity, type: int, isImmunity: bool )
 +/*
 + character：角色实例
 + damage：伤害值
 + from：造成伤害的对象（可能null，例如碰撞）
 + type：伤害类型
 + isImmunity：是否免疫伤害（如果为true，则表示没有造成伤害，可能被Immunity\Group拦截了）
 + localHitPos：受击位置的本地坐标
 +*/
 +```
 +
 +
 +
 +### OnCharacterHealthChange( character, oldHealth, newHealth )
 +
 +> 当角色**血量发生任何改变**时触发。
 +
 +
 +
 +### OnCharacterArmourChange( character, oldArmour, newArmour )
 +
 +> 当角色**护甲值发生任何改变**时触发。
 +
 +
 +
 +### OnCharacterBaseState( character, baseState )
 +
 +> 当角色**基础状态发生改变**时触发（例如：站立、行走、跳跃、驾驶、乘坐、死亡等），**状态索引参考[《世界资源实例汇总——角色基础状态》](reference/instances)**。
 +
 +
 +
 +### OnCharacterFrozenState( character, isFrozen )
 +
 +> 当角色**冻结属性`Frozen`发生改变**时触发。
 +
 +
 +
 +### OnCharacterSwimmingState( character, isSwimming )
 +
 +> 当角色**游泳属性`IsSwimming`发生改变**时触发。
 +
 +
 +
 +### OnCharacterAnimPlayed( character, anim, loop )
 +
 +> 当角色**开始播放自定义动作**时触发（通过`character.SetAnim()`）。
 +
 +```javascript
 +function OnCharacterAnimPlayed( character: Character, anim: int, loop: bool )
 +```
 +
 +
 +
 +### OnCharacterAnimStopped( character, anim, loop )
 +
 +> 当角色**停止播放自定义动作**时触发（主动停止或播放结束）。
 +
 +```javascript
 +function OnCharacterAnimStopped( character: Character, anim: int, loop: bool )
 +```
 +
 +
  
  
 ### ==Vehicle交互事件== ### ==Vehicle交互事件==
  
-> 有关角色与拾取物的交互行为，具体内容请访问[Vehicle文档](scripting/world/vehicle)查看。+> 有关角色与载具的交互行为，具体内容请访问[Vehicle文档](scripting/world/vehicle)查看。
  
  
行 49: 行 166:
  
 > 有关角色与拾取物的交互行为，具体内容请访问[Pickup文档](scripting/world/pickup)查看。 > 有关角色与拾取物的交互行为，具体内容请访问[Pickup文档](scripting/world/pickup)查看。
 +
 +
  
 ## Property ## Property
行 66: 行 185:
 ### character.UUID ### character.UUID
  
-> 获取角色UUID，这是由一串较长的字符串组成的全局唯一**文本ID**。+> 获取角色UUID，这是由一串较长的字符串组成的全局唯一**文本ID**（实例化时自动赋值，非持久化数据）。
  
 ```javascript ```javascript
 character.UUID: string character.UUID: string
 +```
 +
 +
 +
 +### character.Name
 +
 +> 设置或获取角色名称（默认为空字符），长度限制最多`16`。
 +>
 +> 即使有玩家（`Owner`）正在控制当前角色，也并不会返回玩家名称。
 +
 +```javascript
 +character.Name = ""; //string
 ``` ```
  
行 80: 行 211:
 ```javascript ```javascript
 character.Pos = Vector(0, 0, 0); character.Pos = Vector(0, 0, 0);
 +```
 +
 +
 +
 +### character.Forward
 +
 +> 获取角色正前方向量。
 +
 +```javascript
 +character.Forward: Vector
 ``` ```
  
行 92: 行 233:
 ```javascript ```javascript
 character.World = 0; //int character.World = 0; //int
 +```
 +
 +
 +
 +### character.Group
 +
 +> 设置角色**实例组**（这是一个Entity基类通用属性）。
 +>
 +> 相同组的角色及对象无法造成伤害，默认值`0`表示特殊组（无免伤和分组机制）。
 +
 +```javascript
 +character.Group = 0; //int
 +```
 +
 +
 +
 +### character.Owner
 +
 +> 获取（只读）控制当前角色的玩家对象（`Player`），如果不存在则返回`null`。
 +
 +```javascript
 +character.Owner; //Player
 +```
 +
 +
 +
 +### character.Type
 +
 +> 获取（只读）角色**生物种类**（例如：人类、僵尸、猪牛羊、其他动物等），具体种类参考[《世界资源实例汇总——角色生物表格》](reference/instances)。
 +
 +```javascript
 +character.Type; //int
 +```
 +
 +
 +
 +### character.AnimalType
 +
 +> 获取（只读）角色**生物类型**（例如：人形角色、地面生物、飞行生物、海洋生物等），具体类型参考[《世界资源实例汇总》](reference/instances)。
 +
 +```javascript
 +character.AnimalType; //int
 +```
 +
 +
 +
 +### character.Alpha
 +
 +> 设置角色透明度（0~255），默认值是`255`。
 +>
 +> **注意：此方法不会修改手持物品透明度（`character.PropAlpha`）。`**
 +
 +```javascript
 +character.Alpha = 255; //int
 ``` ```
  
行 108: 行 303:
 ### character.EulerAngle ### character.EulerAngle
  
-> 设置角色欧拉角度。 +> 获取角色欧拉角度，通常使用`character.Angle`。 
-> + 
-> 根据引擎角色机制，修改除Y轴外其他角度时，常规情况下，`X\Z轴`会在短时间内自动Lerp重置到`0.0`（类似不倒翁）。+```javascript 
 +character.EulerAngle: Vector 
 +``` 
 + 
 + 
 + 
 +### character.HAngle 
 + 
 +> 设置角色本地偏移角度（水平），可模拟【Q|E】侧身等行为。 
 + 
 +```javascript 
 +character.HAngle = 0.0; //float 
 +``` 
 + 
 + 
 + 
 +### character.VAngle 
 + 
 +> 设置角色本地偏移角度（前后），可模拟前后侧身等行为。
  
 ```javascript ```javascript
-character.EulerAngle = Vector(0, 0, 0);+character.VAngle = 0.0; //float
 ``` ```
  
行 128: 行 341:
  
  
-### character.TriggerDistance+### character.DefaultHealth
  
-> 设置角色触发检测范围，此属性将影响`character.GetTrigger()`相关检测距离，默认是`1.0`。+> 获取角色默认血量。
  
 ```javascript ```javascript
-character.TriggerDistance = 1.0; //float+character.DefaultHealth: int 
 +``` 
 + 
 + 
 + 
 +### character.Armour 
 + 
 +> 设置角色护甲值（额外血量），默认为`0`，如果被攻击时**护甲>=0**则优先扣除护甲。 
 +> 
 +> 此属性与`Health`机制基本相同，适合有【额外生命值、护甲值】需求时使用。 
 + 
 +```javascript 
 +character.Armour = 100; 
 +``` 
 + 
 + 
 + 
 +### character.BaseDamage 
 + 
 +> 设置角色基础攻击伤害值（手中无物品时攻击，可理解为拳头攻击力）。 
 +> 
 +> **属性默认值根据角色不同有所差异。** 
 + 
 +```javascript 
 +character.BaseDamage = 0; //from character defaultValue 
 +``` 
 + 
 + 
 + 
 +### character.DamageMultiplier 
 + 
 +> 设定角色受损（被攻击）伤害倍数，默认为`1.0`。 
 + 
 +```javascript 
 +character.DamageMultiplier = 1.0; //float 
 +``` 
 + 
 + 
 + 
 +### character.BodyHeight 
 + 
 +> 获取角色身体高度（本地偏移量），不同的角色类型可能有不同高度，通常为头部偏高一点的位置。 
 +>  
 +> 扩展：可能用于获取头顶`Bubble`显示的高度。 
 + 
 +```javascript 
 +character.BodyHeight: float 
 +``` 
 + 
 + 
 + 
 +### character.FocusPos 
 + 
 +> 设置或读取角色焦点坐标，如果目标角色已被玩家实时控制，则修改是没有意义的（除非角色静止状态）。 
 +> 
 +> 焦点坐标指的是角色目前正在关注的位置（及方向），被玩家控制时也表示玩家鼠标的世界位置。 
 + 
 +```javascript 
 +character.FocusPos = Vector(0, 0, 0); 
 +``` 
 + 
 + 
 + 
 +### character.AISurface 
 + 
 +> 为当前角色开关独立寻路范围组件，开启后可解决`Player+Stream`范围限制的问题，并且以当前对象自身作为寻路范围中心点，此属性默认关闭。 
 +> 
 +> **注意：玩家控制的角色不需要且无法开启，因为`Player`本身就存在寻路范围组件。==此属性每开启一个会对服务器主机性能产生一些影响，因此仍然建议AI寻路尽可能符合Stream规范，在特别需求的情况下，可以开启少数对象的此属性。==** 
 + 
 +```javascript 
 +character.AISurface = false; 
 +``` 
 + 
 + 
 + 
 +### character.AITarget 
 + 
 +> 为当前角色设置一个AI目标**对象**，详情参考[《CharacterAI》文档](developer/extend/character_ai)。 
 +> 
 +> **注意：当前属性被设置成为`null`的值后，属性`AITargetPos`将被设置为`default`，==两种Target属性只能同时存在一个==。** 
 + 
 +```javascript 
 +character.AITarget = null; //Entity 
 +``` 
 + 
 + 
 + 
 +### character.AITargetPos 
 + 
 +> 为当前角色设置一个AI目标**坐标**，详情参考[《CharacterAI》文档](developer/extend/character_ai)。 
 +> 
 +> **注意：当前属性被设置成为`null`的值后，属性`AITargetPos`将被设置为`VECTOR_NULL`（常量，表示无意义\空坐标），==两种Target属性只能同时存在一个==。** 
 + 
 +```javascript 
 +character.AITargetPos = VECTOR_NULL; //Vector
 ``` ```
  
行 140: 行 447:
 ### character.AIState ### character.AIState
  
-> 为当前角色设置一个AI状态（性格），详情参考[《CharacterAI》文档](scripting/extend/character_ai)。+> 为当前角色设置一个AI状态（行为\性格），详情参考[《CharacterAI》文档](developer/extend/character_ai)。
  
 ```javascript ```javascript
行 150: 行 457:
 ### character.AIMoveState ### character.AIMoveState
  
-> 为当前角色设置一个AI移动行为状态（自动\行走\奔跑），详情参考[《CharacterAI》文档](scripting/extend/character_ai)。+> 为当前角色设置一个AI移动行为状态（自动\行走\奔跑），详情参考[《CharacterAI》文档](developer/extend/character_ai)。
  
 ```javascript ```javascript
 character.AIMoveState = 0; //Enum character.AIMoveState = 0; //Enum
 +```
 +
 +
 +
 +### character.AIDistance
 +
 +> 为当前角色设置一个AI距离属性（不同AI状态有不同的意义），详情参考[《CharacterAI》文档](developer/extend/character_ai)。
 +
 +```javascript
 +character.AIDistance = 32; //float
 ``` ```
  
行 168: 行 485:
 //让玩家离开载具 //让玩家离开载具
 character.Vehicle = null; //等同于调用了character.Eject() character.Vehicle = null; //等同于调用了character.Eject()
 +```
 +
 +
 +
 +### character.VehicleSlot
 +
 +> 获取当前玩家所在载具乘客位置（如果不存在乘坐载具，则返回-1）。
 +>
 +> **顺序：0（驾驶位）、1+（乘客位置）。**
 +
 +```javascript
 +character.VehicleSlot: int
 +```
 +
 +
 +
 +### character.Gravity
 +
 +> 设置角色自身**额外物理重力**，默认值`0.0`。
 +>
 +> 此属性越高角色物理越向上，例如设置为`0.1`获得持续向上推力。
 +
 +```javascript
 +character.Gravity = 0.0;
 ``` ```
  
行 174: 行 515:
 ### character.Skin ### character.Skin
  
-> 设置角色皮肤贴图，内置ID参考[《世界资源实例汇总》](reference/instances)。+> 设置角色皮肤\贴图，内置ID参考[《世界资源实例汇总》](reference/instances)，设置为`-1`可请求一个随机皮肤（如存在）。 
 + 
 +```javascript 
 +character.Skin = 0; 
 +``` 
 + 
 + 
 + 
 +### character.Speed 
 + 
 +> 设置角色**移动速度**。
 > >
-> *注意：需自行确保皮肤贴图及ID正确，理论上人类也可以穿上**动物或外部导入皮肤**（如存在），但同时也会导致贴图异常。* 
  
 ```javascript ```javascript
-character.Skin = 0；+character.Speed = 1; //此数值根据Character不同类型默认值而定，不是固定的 
 +``` 
 + 
 + 
 + 
 +### character.SpeedMultiplier 
 + 
 +> 设置角色**移动速度**倍数，默认为`1.0`。 
 + 
 +```javascript 
 +character.SpeedMultiplier = 1.0; 
 +``` 
 + 
 + 
 + 
 +### character.AdditionSpeed 
 + 
 +> 设置角色**附加状态移动速度**，默认情况下此速度应该比`character.Speed`速度更快（奔跑）。 
 +> 
 +> 此属性也可以举一反三，根据需求更改比`character.Speed`速度更慢，以实现走路\静步的效果。 
 + 
 +```javascript 
 +character.AdditionSpeed = 1; //此数值根据Character不同类型默认值而定，不是固定的 
 +``` 
 + 
 + 
 + 
 +### character.AdditionSpeedMultiplier 
 + 
 +> 设置角色**附加状态移动速度**倍数，默认为`1.0`。 
 + 
 +```javascript 
 +character.AdditionSpeedMultiplier = 1.0; 
 +``` 
 + 
 + 
 + 
 +### character.SwimMultiplier 
 + 
 +> 设置角色**游泳速度**倍数（相对于`character.Speed`），默认为`0.6`。 
 + 
 +```javascript 
 +character.SwimMultiplier= 0.3; 
 +``` 
 + 
 + 
 + 
 +### character.CrouchMultiplier 
 + 
 +> 设置角色**蹲下速度**倍数（相对于`character.Speed`），默认为`0.8`。 
 + 
 +```javascript 
 +character.CrouchMultiplier = 0.8; 
 +``` 
 + 
 + 
 + 
 +### character.JumpMultiplier 
 + 
 +> 设置角色**跳跃高度**倍数，默认为`1.0`。 
 + 
 +```javascript 
 +character.JumpMultiplier = 1.0; 
 +``` 
 + 
 + 
 + 
 +### character.ActionContinue 
 + 
 +> 获取（只读）角色**单次行为（Action）次数**（例如：连发武器的单次攻击连续次数、按下一次鼠标后Action次数）。 
 + 
 +```javascript 
 +character.ActionContinue; //int 
 +``` 
 + 
 + 
 + 
 +### character.IsAI 
 + 
 +> 获取角色是否为NPC（AI）。 
 + 
 +```javascript 
 +character.IsAI: bool 
 +``` 
 + 
 + 
 + 
 +### character.IsPlayer 
 + 
 +> 获取角色是否为玩家控制的角色。 
 + 
 +```javascript 
 +character.IsPlayer: bool
 ``` ```
  
行 200: 行 642:
 ```javascript ```javascript
 character.IsSwimming: bool character.IsSwimming: bool
 +```
 +
 +
 +
 +### character.IsCrouch
 +
 +> 设置角色蹲下状态，通常仅为NPC角色设置属性，更多情况下是只读取的。
 +
 +```javascript
 +character.IsCrouch = false; //bool
 ``` ```
  
行 210: 行 662:
 ```javascript ```javascript
 character.IsInWater: bool character.IsInWater: bool
 +```
 +
 +
 +
 +### character.IsOnFire
 +
 +> 获取角色是否正在被燃烧。
 +
 +```javascript
 +character.IsOnFire: bool
 ``` ```
  
行 230: 行 692:
 ```javascript ```javascript
 character.IsPassenger: bool character.IsPassenger: bool
 +```
 +
 +
 +
 +### character.IsExtend
 +
 +> 获取角色是否为**扩展型角色**（拥有高级骨骼的角色，可使用道具、工具、武器等）。
 +>
 +> 通常情况下，人形角色均为扩展型，多数动物为非扩展型（因为动物通常**无法正常动作**持有\使用道具和武器等）。
 +
 +```javascript
 +character.IsExtend: bool
 +```
 +
 +
 +
 +### character.Color
 +
 +[note3]
 +此属性当前是过时的，等待新版API同步。
 +[/note]
 +
 +> 设置角色的**主要颜色**，此属性主要用于人形角色。
 +>
 +> 在人形角色实例修改时，将会修改目标角色的**肤色**（例如：肤色、褐色皮肤、僵尸色皮肤等）。
 +>
 +> 在其他角色实例修改时，可能修改为整体叠加颜色。
 +>
 +> 通常情况下，人形角色均为扩展型，多数动物为非扩展型（因为动物通常**无法正常动作**持有\使用道具和武器等）。
 +
 +```javascript
 +character.Color = Color(255, 204, 153);
 +```
 +
 +
 +
 +### character.Immunity
 +
 +> 设定角色的[免疫属性](reference/instances "免疫属性")（可叠加位Flag），设置为`-1`自动识别完全免疫（所有Flag相加后的结果）。
 +
 +```javascript
 +character.Immunity = 0; //int
 +
 +//可根据具体需求叠加属性
 +//示例：无视子弹和爆炸伤害，其他正常
 +character.Immunity = 2 + 4; //或直接设为6
 +```
 +
 +
 +
 +### character.HasAction
 +
 +> 获取\设置角色是否为**开始\正在行动**。
 +>
 +> 这是一个抽象概念，简单理解相当于让此角色**”按住左键“**（对于已被玩家控制的角色，此选项是只读意义的）。
 +
 +```javascript
 +character.HasAction = false; //bool
 +```
 +
 +
 +
 +### character.FrozenAction
 +
 +> 设置角色**锁定行动开关`HasAction`**，当功能被锁定后，除引擎内置强制事件外（例如：角色死亡），无法修改`HasAction`属性（即使手持物品）。
 +> 
 +> 注意：如果希望控制Action执行，可能要找的是`character.CanAction`，而非此方法。
 +
 +```javascript
 +character.FrozenAction = false; //bool
 +```
 +
 +
 +
 +### character.HasFocus
 +
 +> 获取\设置角色是否为**开始\正在聚焦**。
 +>
 +> 这是一个抽象概念，简单理解相当于让此角色**”按住右键“**（对于已被玩家控制的角色，此选项是只读意义的）。
 +
 +```javascript
 +character.HasFocus = false; //bool
 +```
 +
 +
 +
 +### character.FrozenFocus
 +
 +> 设置角色**锁定聚焦开关`HasFocus`**，当功能被锁定后，除引擎内置强制事件外（例如：角色死亡），无法修改`HasFocus`属性（即使手持物品）。
 +
 +```javascript
 +character.FrozenFocus = false; //bool
 +```
 +
 +
 +
 +### character.FocusMode
 +
 +> 设置角色**专注聚焦模式开关**，此属性开启后角色将始终保持**（仅）聚焦动作**，此功能更适合用于第一人称游戏使用。
 +
 +[note2]
 +
 +注意：此模式不会强制锁定`HasFocus`，同时也不会修改默认移动速度，仅强制**锁定聚焦动作**。
 +
 +[/note]
 +
 +```javascript
 +character.FocusMode = false; //bool
 +```
 +
 +
 +
 +### character.StandAction
 +
 +> 设置角色**强制站立Action开关**，当属性开启后，角色在Action时将被强制设为站立状态**（禁止移动攻击）**，此属性默认关闭。
 +> 
 +> 扩展引导：当角色手持道具发生改变时，检测`Prop.ID`是否为希望站立攻击的道具，并`if | else`激活&取消此属性。
 +
 +```javascript
 +character.StandAction = false; //bool
 +```
 +
 +
 +
 +### character.DriveAction
 +
 +> 设置角色**载具驾驶&乘坐Action开关**，当属性开启后，角色乘坐载具时可进行Action或射击，此属性默认开启。
 +>
 +> **注意：角色在乘坐载具攻击时，不会对自身载具造成伤害（不包括爆炸类道具）。**
 +
 +```javascript
 +character.DriveAction = true; //bool
 +```
 +
 +
 +
 +### character.CanAction
 +
 +> 设置角色是否可以发起攻击，默认为`true`。
 +>
 +> 扩展引导：此方法可用于实现武器子弹不足时无法射击等功能。
 +
 +[note2]
 +
 +注意：此属性被设置为`false`后仍然会触发`OnCharacterPropAction`（仅单次触发，即使是连续攻击道具），因此可提前判断`character.CanAction`作不同条件处理。
 +
 +[/note]
 +
 +```javascript
 +character.CanAction = true;
 +```
 +
 +
 +
 +### character.CanSwim
 +
 +> 设置角色是否可以游泳，默认为`true`，当前版本只有僵尸等少数角色默认`false`。
 +>
 +> **注意：此属性将控制角色是否会被淹死，以及可能的AI控制逻辑。**
 +
 +```javascript
 +character.CanSwim = true;
 +```
 +
 +
 +
 +### character.Shadow
 +
 +> 设置角色阴影开关，默认开启`true`。
 +>
 +
 +```javascript
 +character.Shadow = true;
 +```
 +
 +
 +
 +### character.Frozen
 +
 +> 设置角色冻结状态，冻结后将无法移动、驾驶等操作（被动操作除外）。
 +
 +```javascript
 +character.Frozen = false;
 +```
 +
 +
 +
 +### character.FlyMode
 +
 +> 设置角色飞行模式（不是一种手机模式），角色将可以进行飞天移动。
 +>
 +> **注意：当角色死亡、乘坐或离开载具，将自动取消飞行模式，同时无法激活。**
 +
 +[note2]
 +如果目标角色是NPC，则将寻路模式改为飞天移动，同时将直奔目标方向移动（忽略碰撞）。
 +[/note]
 +
 +```javascript
 +character.FlyMode = false;
 +```
 +
 +
 +
 +### character.FlyTime
 +
 +> 获取角色飞行\离开地面持续时间。
 +>
 +> 此属性从角色开始离地起计算，下次落地时清零。
 +>
 +> **举一反三：根据此属性可实现飞行时间、落地时间判定等功能。**
 +
 +```javascript
 +character.FlyTime: float
 +```
 +
 +
 +
 +### character.SidelingControl
 +
 +> 设置角色侧身控制开关（允许玩家`Q|E`向左右侧身，适合于射击等玩法），默认`true`。
 +
 +```javascript
 +character.SidelingControl: bool
 ``` ```
  
行 280: 行 965:
 ```javascript ```javascript
 character.CheckpointTime: float character.CheckpointTime: float
 +```
 +
 +
 +
 +### character.Prop
 +
 +> 获取角色当前正在使用的**[Prop物品对象](scripting/world/prop)**，此属性无法直接赋值（例如无法`prop = null`，同时也不应该new或赋值其他对象），但可以修改其内部属性。
 +>
 +> **正确操作角色Prop背包的方法是使用`character.SetProp()`，切换角色物品槽的方法是使用`character.PropSlot`，而不是直接修改此属性。**
 +
 +```javascript
 +character.Prop: Prop
 +```
 +
 +
 +
 +### character.PropSlot
 +
 +> 设置角色当前正在使用的物品槽，默认为`0`，**修改此属性是“切换背包物品”的正确方法**。
 +
 +```javascript
 +character.PropSlot = 0; //0~PropCount
 +```
 +
 +
 +
 +### character.PropCount
 +
 +> 设置角色当前背包物品槽最大数量（可理解为背包格子数量），默认为`0`。
 +>
 +> **通常情况下，如果想开始为一个角色创建背包系统，应该首先确保PropCount设置为合适的数量，或考虑使用`AddProp()`方法动态调整。**
 +
 +```javascript
 +character.PropCount = 0;
 +```
 +
 +
 +
 +### character.PropAlpha
 +
 +> 设置**角色手持物品**透明度，默认值是`255`。
 +
 +```javascript
 +character.PropAlpha = 255;
 ``` ```
  
行 289: 行 1018:
  
 > 生成一个新的角色实例，`Type`类型样式参考[《世界资源实例汇总》](reference/instances)。 > 生成一个新的角色实例，`Type`类型样式参考[《世界资源实例汇总》](reference/instances)。
 +>
 +> 如果`Type`参数填写`-1`，则表示生成一个随机类型的角色（随机生物）。
  
 ```javascript ```javascript
-function Character.Create( type: int, pos: Vector, angle: float = 0 ): Character+function Character.Create( type: int, pos: Vector, angle: float = 0, skin: number ): Character
 ``` ```
  
行 298: 行 1029:
 Character.Create(0, Vector(0, 0, 0), 0); Character.Create(0, Vector(0, 0, 0), 0);
 ``` ```
 +
 +- **`type`：**生物类型
 +- **`pos`：**坐标位置
 +- **`angle`：**角度
 +- **`skin`：**皮肤ID（人形角色更多使用）
 +- **`randomStyle`：**是否随机样式（执行`character.RandomStyle()`）
  
  
行 321: 行 1058:
  
  
-### Character.FindByIndex()+### Character.GetCount()
  
-> 寻找一个角色实例（通过索引），不存在则返回`null`。+> 获取当前所有存在角色数量。
  
 ```javascript ```javascript
-function Character.FindByIndex( index: int ): Character+function Character.GetCount(): int
 ``` ```
  
  
  
-### Character.GetCount()+### Character.Get()
  
-> 获取当前所有存在角色数量。+> 获取当前存在的指定索引角色，通常搭配`GetCount()`遍历使用。
  
 ```javascript ```javascript
-function Character.GetCount(): int+function Character.Get( index: int ): Character
 ``` ```
  
行 343: 行 1080:
 ## Function ## Function
  
-### character.AIMove()+### character.Remove()
  
 +> 销毁当前角色实例。
 +
 +```javascript
 +function character.Remove()
 +```
 +
 +
 +
 +### character.Damage()
 +
 +> 以标准方式攻击当前角色实例，**有关`Reason`原因，请参考[《世界资源实例汇总——伤害触发类型》](reference/instances)**。
 +> 
 +> **注意：此方法受到`GameRule("character_damagemultiplier")`规则影响（默认值`0.5`，因此`character.Damage(50)`则只会受到25伤害），如果希望直接改变血量，请考虑使用`character.Health`属性直接赋值。**
 +
 +```javascript
 +function character.Damage( damage: int, from: Entity = null, reason: int = 0, localHitPos: Vector = Vector(0, 0, 0) )
 +```
 +
 +
 +
 +### character.RandomStyle()
 +
 +> 随机当前角色样式（配色`character.Color1 | characterColor2`）。
 +>
 +> 此方法主要用于**人形角色**，对于其他类型角色更多是模型随机叠加颜色。
 +
 +```javascript
 +function character.RandomStyle()
 +```
 +
 +
 +
 +### character.Action()
 +
 +> 使当前角色立即执行一次`Action`行为（例如：手中有武器，立即攻击一次）。
 +
 +```javascript
 +function character.Action()
 +```
 +
 +
 +
 +### character.Jump()
 +
 +> 使当前角色立即执行一次`Jump`跳跃行为，因为连续跳跃间隔及其他冻结等限制，跳跃指令并非每次都执行成功。
 +
 +```javascript
 +function character.Jump( multiple: float = 1.0 )
 +```
 +
 +
 +
 +### character.AddForce()
 +
 +> 增加一个当前对象的物理作用力，默认为本地坐标系（根据参数`isLocal`）。
 +>
 +> 在飞行`FlyMode`等**逻辑冲突**模式下，此方法不会生效。
 +
 +```javascript
 +function character.AddForce( force: Vector, isLocal: bool = true )
 +```
 +
 +```javascript
 +let npc = character.Create(...);
 +npc.AddForce( Vector(0, 3, 0) ); //角色立即向上冲刺一段距离(y)
 +```
 +
 +
 +
 +### character.AIMove()
 +> **==此方法已被取消，请使用`AITarget`属性等方式AI寻路。==**
 +>
 > 让角色AI寻路到某个坐标，如果角色不在任何Stream范围内，或者无法到达指定位置，将会返回`false`。 > 让角色AI寻路到某个坐标，如果角色不在任何Stream范围内，或者无法到达指定位置，将会返回`false`。
 > >
行 358: 行 1167:
     DLog("NPC到达了目标位置");     DLog("NPC到达了目标位置");
 }); });
 +```
 +
 +
 +
 +### character.Recover()
 +
 +> 恢复当前角色（恢复最大血量），如果角色已经死亡则自动调用`character.Respawn()`。
 +
 +```javascript
 +function character.Recover()
 ``` ```
  
行 370: 行 1189:
 ```javascript ```javascript
 function character.Kill() function character.Kill()
 +```
 +
 +
 +
 +### character.Fire()
 +
 +> 开始燃烧当前角色。
 +> 
 +> 如果参数`time < 0`则表示持续燃烧。
 +
 +```javascript
 +function character.Fire( time: float )
 +```
 +
 +
 +
 +### character.FireOver()
 +
 +> 停止燃烧当前角色。
 +
 +```javascript
 +function character.FireOver()
 ``` ```
  
行 376: 行 1217:
 ### character.Respawn() ### character.Respawn()
  
-> 复活当前角色。+> 复活并重置当前角色。
  
 ```javascript ```javascript
行 386: 行 1227:
 ### character.Eject() ### character.Eject()
  
-> 让角色离开当前载具，如没有驾驶\乘坐载具则无效果。+> 使角色离开当前载具，如没有驾驶\乘坐载具则无效果。
 > >
 > 也可以使用`character.Vehicle = null`有相同的效果。 > 也可以使用`character.Vehicle = null`有相同的效果。
行 398: 行 1239:
 ### character.SetVehicle() ### character.SetVehicle()
  
-> 让角色进入一辆载具的某个位置（使用载具）。+> 使角色进入一辆载具的某个驾驶\乘客位置，`Slot=0`为驾驶位。
 > >
 > 此方法和`Vehicle.SetOccupant`作用相同。 > 此方法和`Vehicle.SetOccupant`作用相同。
行 404: 行 1245:
  
 ```javascript ```javascript
-function character.SetVehicle( vehicle: Vehicle, slot: int ): bool+function character.SetVehicle( vehicle: Vehicle, slot: int ): bool //是否进入成功
 ``` ```
  
  
  
-### character.GetTriggerCount()+### character.EnterVehicle()
  
-> 获取角色范围触发实例数量，此功能可获取某个角色`character.TriggerDistance`范围内的实例数量。+> 使角色进入一辆载具的**自动靠前位置**（优先顺序：驾驶位>乘客位1>乘客位2>乘客位N+1）。
 > >
-> 实体通常包括：角色、载具、拾取物、检查点等。 
  
 ```javascript ```javascript
-function character.GetTriggerCount(): int+function character.EnterVehicle( vehicle: Vehicle ): bool //是否进入成功
 ``` ```
  
  
  
-### character.GetTrigger()+### character.ResetProp()
  
-> 获取角色范围触发实例（根据索引），此功能可获取某个角色`character.TriggerDistance`范围内的实例对象。+> 重置\刷新当前角色正在使用的物品对象，通常情况下不需要调用此方法。
  
 ```javascript ```javascript
-function character.GetTrigger( index: int ): Entity+function character.ResetProp()
 ``` ```
 +
 +
 +
 +### character.SetProp()
 +
 +> 设置当前角色指定物品槽的物品对象，**使用此功能是“设置背包物品”的正确方法**。
  
 ```javascript ```javascript
-//遍历某个角色范围内所有实例对象，可用于扩展上车、拾取物品、使用等操作 +function character.SetProp( slot: int, id: int, amount: int = 1, data: any = null )
-for(let i=0;i<character.GetTriggerCount();i++) +
-{ +
-    let target = character.GetTrigger(i); +
-    DLog("trigger[" + i + "]: " + target.GetType()); +
-}+
 ``` ```
 +
 +```javascript
 +//在物品槽索引3的位置，设置为ID10物品x1，同时为其设定自定义属性Test = 1.0
 +character.PropCount = 10; //提前设置好背包格子数量，否则会错误
 +character.SetProp(3, 10, 1, {Test: 1.0});
 +```
 +
 +
 +
 +### character.GetProp()
 +
 +> 获取当前角色指定物品槽的物品对象，**使用此功能是“获取指定背包槽物品”的正确方法**。
 +>
 +> **对于角色实例来说，获取的物品对象永远不会为`null`，指定槽不存在时会返回默认物品（相当于透明的拳头，ID`0`）。**
 +>
 +> **注意：`Prop`是一个扩展类型，具体属性参考[【World/Prop】](scripting/world/prop)。**
 +
 +```javascript
 +function character.GetProp( slot: int ): Prop
 +```
 +
 +
 +
 +### character.AddProp()
 +
 +> 尝试为当前角色**加入物品对象**到物品槽，**使用此功能是“加入背包物品”的正确方法**。
 +
 +```javascript
 +function character.AddProp( id: int, amount: int = 1, data: any = null, forceAll: bool = false, autoSize = false ): int
 +```
 +
 +- **id：**物品ID
 +- **amount：**物品数量
 +- **data：**物品自定义属性
 +- **forceAll：**是否强制必须全部装下（开启此参数后，如果amount > 1，只有剩余背包能全部装下物品时才正常加入到背包，否则不放置任何）
 +- **autoSize：**是否自动填充背包PropCount（如果背包大小已经不能满足本次加入），否则背包溢出时可能无法加入到背包
 +- **[return]：**正常加入（返回0），非强制且无法全部放入（返回剩余闲置数量），未成功加入任何（返回-1）
 +
 +
 +
 +### character.AppendProp()
 +
 +> 尝试为当前角色**加入物品对象**到**==单独==物品槽**，与`AddProp()`的区别是：此方法无论前提条件，只使用**最新的1个**物品槽（不判断是否能完全放下，如果有叠加溢出，只会赋值数量到最大值）。
 +
 +```javascript
 +function character.AppendProp( id: int, amount: int = 1, data: any = null, autoSize = false ): int
 +```
 +
 +- **id：**物品ID
 +- **amount：**物品数量
 +- **data：**物品自定义属性
 +- **autoSize：**是否自动填充背包PropCount（背包全部已满，尝试自动增加1格背包）
 +- **[return]：**正常加入（返回0），非强制且无法全部放入（返回剩余闲置数量），未成功加入任何（返回-1）
 +
 +
 +
 +### character.SetAnim()
 +
 +> 设置\播放一段当前角色的**自定义动作**（例如：挥手、躺下、坐下等），详细动作ID参考[《世界资源实例汇总》](reference/instances)。
 +>
 +> **注意：如果希望主动停止\中断播放动作，使用默认参数即可（`character.SetAnim(-1)`）。**
 +
 +```javascript
 +function character.SetAnim( anim: int = -1, loop: bool = false )
 +```
 +
 +- **anim：**播放动作ID（-1表示停止播放）
 +- **loop：**是否循环播放（直到主动停止播放）
 +
 +
 +
 +### character.SetRemodel()
 +
 +> 绑定角色**重写模型对象**。
 +>
 +> 此方法允许将当前角色替换为一个`Model`对象，与`SetNodeExtend(0)`不同的是，此方法会将模型变为真正意义上的角色，并且继承碰撞及伤害。
 +>
 +> 重写模型对象同时只能绑定一个，如果有新的对象被绑定则会解绑旧对象。
 +>
 +> **（参数设置为`null`可解除绑定）**
 +
 +```javascript
 +function character.SetRemodel( model: Model )
 +```
 +
 +
 +
 +### character.GetRemodel()
 +
 +> 获取角色**重写模型对象**。
 +
 +```javascript
 +function character.GetRemodel(): Model
 +```
 +
 +
 +
 +### character.SetNodeExtend()
 +
 +> 绑定一个模型对象（`Model`）到角色指定节点位置（原点本地坐标），通过此功能可实现很多扩展操作，==**此功能更多只适用于人形角色**==。
 +>
 +> **注意：同一个节点位置下，同时最多只能存在一个模型对象，如果有上个对象则会解除上次绑定（并非销毁模型对象）。**
 +>
 +> **补充：当模型对象被绑定后，想要【读写】位置、角度、缩放（`Pos | Angle | Scale`）等信息时，坐标空间默认为【本地空间】而不是“世界空间”。**
 +
 +[note2]
 +**注意：父子节点之间不会产生物理碰撞。**
 +[/note]
 +
 +```javascript
 +function character.SetNodeExtend( node: int, model: Model )
 +```
 +
 +- **node：**角色节点位置（索引）
 +- **model：**要绑定的模型对象（可为`null`，相当于解除绑定）
 +
 +```javascript
 +//给玩家【手中的物体】附加一个红色的射灯（类似：红外线瞄准灯光）
 +let chara = xxxxx;
 +
 +let model = Model.Create(1, chara.Pos);
 +character.SetNodeExtend(2, model);
 +model.Enum = 1;
 +model.Color = Color(255, 0, 0);
 +model.Range = 40;
 +model.Intensity = 2;
 +```
 +
 +| 节点位置（Node） | 说明                       |
 +| ---------------- | -------------------------- |
 +| -1 | 角色自身节点（不受动作影响） |
 +| 0                | 头部（支持动物角色）                       |
 +| 1                | 身体（支持动物角色）                      |
 +| 3                | 手持物品位置（Prop）                   |
 +| 4                | 左手位置                   |
 +| 5                | 右手位置                   |
 +| 6                | 左脚位置                   |
 +| 7                | 右脚位置                   |
 +
 +
 +
 +### character.RemoveNodeExtend()
 +
 +> 解除绑定一个角色节点位置的模型对象（`Model`）。
 +>
 +> **注意：解除绑定并不会销毁模型对象，只是将其解除与角色的绑定及位置同步关系。**
 +
 +```javascript
 +function character.RemoveNodeExtend( node: int )
 +```
 +
 +- **node：**角色节点位置（索引）
 +
 +
 +
 +### character.GetNodeExtend()
 +
 +> 获取角色指定节点位置绑定的模型对象（`Model`），如果不存在绑定则返回`null`。
 +
 +```javascript
 +function character.GetNodeExtend( node: int ): Model
 +```
 +
 +- **node：**角色节点位置（索引）
 +
 +
 +
 +### character.GetNodeExtendPos()
 +
 +> 获取角色指定节点位置的当前世界坐标，如果不存在节点则返回`Vector(0, 0, 0)`。
 +
 +```javascript
 +function character.GetNodeExtendPos( node: int, isLocal: bool = false ): Vector
 +```
 +
 +- **node：**角色节点位置（索引）
 +- **isLocal：**是否获取本地空间结果
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
  
  
 </markdown> </markdown>