meta data for this page

📚 World/Prop

Prop类是一个抽象数据结构，主要用于Prop背包物品及游戏道具相关功能使用。

此类下所有的属性均是以抽象概念为基础的，具体物品的逻辑实现由开发者自行编写（例如物品磨损、武器子弹数量等）。

修改Prop数据结构时需要注意，其本身是一个引用的结构类型，因此直接修改属性将无法生效，应该使用以下方法： 

let tempProp = XXX; //source
tempProp.Speed = 2;
XXX = tempProp; //set source to new

📒 Property

📘 prop.ID

获取物品ID（只读）。 

prop.ID: int

📘 prop.Model

获取物品对应模型ID（只读）。 

prop.Model: int

📘 prop.ChildModel

获取物品对应的子模型ID（只读）。

例如：投掷道具发生投掷效果时的对象模型ID。 

prop.ChildModel: int

📘 prop.UUID

获取物品场景唯一UUID（只读），可判断物品原始对象等，即使物品索引位置发生改变。 

prop.UUID: string

📘 prop.Name

获取物品注册名称，来源于配置文件（只读）。 

prop.Name: string

📘 prop.Tag

获取物品注册标签，来源于配置文件（只读）。 

prop.Tag: string

📘 prop.Amount

设置物品同类叠加数量，默认值为1，上限值根据Multiple决定（源于json配置）。

注意：如果物品数量<=0时将立即被回收，变换为默认空物品（ID0）。 

prop.Amount = 1; //int

📘 prop.Data

设置物品自定义属性（Any），绝大多数自定义扩展属性都由此实现。 

prop.Data = {}; //any
//实现一个武器子弹功能
let chara = Character.Create(...);
 
//两种方式相同，建议优先考虑第一种
[1] chara.SetProp(0, 3, 1, {Bullet: 1000});
[2] chara.SetProp(0, 3, 1);
	chara.Prop.Data.Bullet = 1000;
 
//子弹功能属性实现完成，下面实现【子弹检测逻辑】
function OnCharacterPropActionBefore( character, prop )
{
    if(prop.Data.Bullet != null)
    {
        if(prop.Data.Bullet > 0) prop.Data.Bullet --;
        else{
            //子弹不足
            return 0; //阻止武器继续使用
        }
    }
}

补充：尽管在JavaScript里允许使用例如chara.Prop.BulletXXX这种直接字段赋值的方式，但考虑到生命周期和GC的问题，建议优先使用示例中的推荐做法（prop.Data.XXX）。

📒 Value Property

Prop类在根类本身的基础上，额外提供一些与【游戏道具原始数据】同名映射的动态属性，此类属性可实现运行时动态修改物品数据（如伤害、范围、射速等），属性详细用途及介绍参考【游戏道具原始数据】。

注意：此部分仅支持Prop基础属性，例如高级Flags、Animation、Audio这些暂不支持运行时动态调整。

📘 prop.Damage

设置物品伤害值\基础伤害值属性。 

prop.Damage = 0; //int

📘 prop.DamageRange

设置物品伤害检测范围属性。 

prop.DamageRange = 0.8; //float

📘 prop.DamageShake

设置物品伤害检测范围偏移属性。 

prop.DamageShake = 1.0; //float

📘 prop.Distance

设置物品距离相关属性，通常情况下非特定类型物品（如：枪支）应该保持默认。 

prop.Distance = 0.0; //float

📘 prop.Direction

设置物品手持方向属性。 

prop.Direction = 2; //int

📘 prop.PreloadTime

设置物品切换武器冷却时间（无法使用时间）属性。 

prop.PreloadTime = 1.0; //float

📘 prop.Speed

设置物品动作\执行速度属性，此属性关键决定执行动作的速度，对于大多数物品来说，动作速度越快，同时间内能执行的次数越多（例如热武器射速）。 

prop.Speed = 1.0; //float

📘 prop.MoveSpeedMultiplier

设置物品移动速度影响倍数属性，这将直接影响角色手持物品时移动速度。 

prop.MoveSpeedMultiplier = 1.0; //float

📘 prop.Flags

获取物品枚举特性属性（位特性），建议只读（或不要直接使用）此属性，不要直接操作修改，除非知道自己在做什么。

补充：如果有修改需求，请使用Flags相关的Function方法。 

prop.Flags: int

📘 prop.Stack

设置物品最大叠加数量，默认值为1。

此属性主要用于实现高级背包系统，可能某些物品允许叠加存放（例如苹果），但武器这些属性复杂的物品，可能并不适合叠加存放。 

prop.Stack = 1; //int

📘 prop.Level

设置物品品质等级，默认值为0，限制范围0~4。

此属性主要用于实现高级背包系统，不同等级默认没有实际功能区别，此部分需要开发者自行扩展。 

prop.Level = 0;

📒 Static Function

📘 Prop.None()

创建空白道具实例结构。 

function Prop.None(): Prop

📘 Prop.Create()

创建新的道具实例结构。 

function Prop.Create( id: int, amount: int = 1, level: int = 0, data: any = null ): Prop

📘 Prop.SetSourceData()

设置指定游戏道具默认原始数据（重写），建议场景初始化时使用。

注意：此方法不会更新已生成的对象，除非手动运行prop.ResetData()。 

function Prop.SetSourceData( prop: int, keyPath: string, value: any )
SetSourceData(277, "Stack", 100); //set prop 277 stack to 100

📘 Prop.GetSourceData()

获取指定游戏道具最新数据，如果未被SetSourceData重写过，则返回原始数据。 

function Prop.GetSourceData( prop: int, keyPath: string ): any

📘 Prop.ResetSourceData()

重置指定游戏道具修改数据，恢复使用原始数据。

注意：此方法不会更新已生成的对象，除非手动运行prop.ResetData()。 

function Prop.ResetSourceData( prop: int )

📘 Prop.ResetAllSourceData()

重置全部游戏道具修改数据，恢复使用原始数据。

注意：此方法不会更新已生成的对象，除非手动运行prop.ResetData()。 

function Prop.ResetAllSourceData()

📒 Function

📘 prop.ExistFlag()

获取物品是否包含指定Flag特性。

关于Flag的增删查改参考《游戏道具扩展——Flag属性》。 

function prop.ExistFlag( flag: int ): bool

📘 prop.AddFlag()

给物品增加指定的Flag特性（如果是不允许动态增删的Flag或者已包含，则不会被增加）。 

function prop.AddFlag( flag: int )

📘 prop.RemoveFlag()

给物品移除指定的Flag特性（如果是不允许动态增删的Flag或者不包含，则不会被移除）。 

function prop.RemoveFlag( flag: int )

📘 prop.Equals()

判断另一物品是否等同于自身引用（是否为相同对象）。 

function prop.Equals( other: Prop )

📘 prop.ResetData()

重置当前物品的默认属性，通常用于SetSourceData()方法使用后的立即更新。 

function prop.ResetData()