角色模块管理接口 `Actor`

具体函数名及描述如下:

序号	函数名	函数描述
1	GetItemId(...)	获取掉落物类型ID
2	GetDropItemNum(...)	获取掉落物品数量
3	SetTeam(...)	设置角色队伍
4	GetTeam(...)	获取角色队伍
5	AddHp(...)	增加角色当前生命值
6	GetMaxHP(...)	获取最大生命值
7	ShowNickName(...)	设置昵称显示
8	SetNickName(...)	设置角色昵称
9	GetNickName(...)	获取角色昵称
10	GetObjWorldId(...)	获取角色所在星球ID
11	IsPlayer(...)	检查对象是否为玩家
12	PlaySoundEffectById(...)	播放音效
13	StopSoundEffectById(...)	停止音效
14	PauseSoundEffectById(...)	暂停/恢复音效
15	RotateFaceToActor(...)	生物朝向目标
16	GetMotion(...)	获取对象移动速度
17	SetBeHurtTarget(...)	设置仇恨目标
18	GetActorFacade(...)	获取角色外观
19	CompareMainModel(...)	比较主模型外观
20	PlayBodyParticleById(...)	播放粒子特效
21	StopBodyEffectById(...)	停止粒子特效
22	SetBodyParticleTransform(...)	设置粒子特效变换
23	Jump(...)	对象跳跃
24	GetRidingActorObjId(...)	获取骑乘生物ID
25	GetFaceDirection(...)	获取对象朝向
26	TryMoveToActor(...)	对象移动到目标
27	SetFaceDirection(...)	设置对象朝向
28	KillSelf(...)	击败对象
29	SetAttr(...)	设置角色属性
30	IncreasesAttr(...)	增加角色属性值
31	GetAttr(...)	获取角色属性值
32	SetActorPermissions(...)	设置对象权限
33	GetActorPermissions(...)	获取对象权限
34	SetFaceYaw(...)	设置面向角度
35	GetFaceYaw(...)	获取面向角度
36	SetFacePitch(...)	设置仰望角度
37	GetFacePitch(...)	获取仰望角度
38	SetPosition(...)	设置角色位置
39	GetPosition(...)	获取对象位置
40	ChangeCustomModel(...)	改变对象外观
41	RecoverinitialModel(...)	恢复对象外观
42	ActorHurt(...)	对象造成伤害
43	SetImmuneType(...)	设置免疫伤害类型
44	ChangActorMoveType(...)	改变移动方式
45	GetActorMovementMode(...)	获取移动模式
46	GetBoundSzie(...)	获取模型大小
47	RandomFacadeID(...)	随机外观ID
48	GetObjType(...)	获取对象类型
49	TryMoveToPos(...)	移动对象到位置（寻路）
50	AppendSpeed(...)	附加速度
51	FindNearestBlock(...)	查找最近方块
52	GetEyeHeight(...)	获取角色眼睛高度
53	ClearActorWithId(...)	清除指定类型生物
54	IsExist(...)	对象是否存在
55	PlayAnim(...)	对象播放动作
56	PlayHandAnim(...)	对象手持播放动作
57	MountActor(...)	角色骑乘
58	DisMountActor(...)	角色取消骑乘
59	PickupActor(...)	角色举起角色
60	TryPickupActorForward(...)	尝试抓取前方对象
61	DropActor(...)	尝试投掷角色
62	EscapePickup(...)	尝试逃脱抓举
63	SetBtreeVarValue(...)	设置行为树变量
64	GetBtreeVarValue(...)	获取行为树变量
65	GetDropItemInstanceId(...)	获取掉落物实例ID
66	SetAblePick(...)	设置掉落物可拾取
67	GetEntityFacade(...)	获取实体类型外观
68	PickupItem(...)	角色拾取物品
69	GetPickupObjID(...)	获取举起行为中的角色ID
70	HasTags(...)	对象是否有标签
71	GetTags(...)	获取对象标签列表
72	AddTags(...)	添加标签
73	RemoveTags(...)	删除标签
74	ClearTags(...)	清空所有标签
75	PlayAnimByObj(...)	对象播放对象动作

GetItemId

参数及类型：
- objid:number 掉落物对象ID
返回值及类型：
- id:number 掉落物类型ID(失败返回nil)
该方法的其他说明：根据掉落物对象ID获取对应的物品类型ID
具体使用案例如下：

lua

    local itemId = Actor:GetItemId(objId)

GetDropItemNum

参数及类型：
- objid:number 掉落物对象ID
返回值及类型：
- num:number 掉落物品数量
该方法的其他说明：根据掉落物对象ID获取该掉落物的物品数量
具体使用案例如下：

lua

    local num = Actor:GetDropItemNum(objId)

SetTeam

参数及类型：
- objid:number 角色对象ID
- teamid:number 队伍ID(AbsoluteCampType)AbsoluteCampType
- bResetAttr:boolean 是否重置属性(仅玩家有效，默认false)
返回值及类型：
- bool:boolean 是否设置成功
该方法的其他说明：设置指定角色的队伍ID，可指定是否重置属性（仅对玩家有效）
具体使用案例如下：

lua

    -- 设置玩家为3队

    local team = AbsoluteCampType.Team3

    local result = Actor:SetTeam(playerId, team)

GetTeam

参数及类型：
- objid:number 角色对象ID
返回值及类型：
- id:number 队伍ID(失败返回nil)
该方法的其他说明：根据角色对象ID获取该角色所属的队伍ID
具体使用案例如下：

lua

    local curteam = Actor:GetTeam(playerId)

AddHp

参数及类型：
- objid:number 角色对象ID
- hp:number 血量值(hp>0增加血量,hp<0减少血量)
返回值及类型：
- bool:boolean 是否操作成功
该方法的其他说明：增加或减少指定角色的当前生命值，正数增加，负数减少
具体使用案例如下：

lua

    local playerId = Player:GetHostUin()

    local result = Actor:AddHp(playerId, 1)

GetMaxHP

参数及类型：
- objid:number 角色对象ID
返回值及类型：
- num:number 最大生命值(失败返回nil)
该方法的其他说明：获取指定角色的最大生命值，包括所有属性加成
具体使用案例如下：

lua

    local playerId = Player:GetHostUin()

    local maxhp = Actor:GetMaxHP(playerId)

    if maxhp and maxhp > 0 then

        print("获取成功")

    end

ShowNickName

参数及类型：
- objid:number 角色对象ID
- bshow:boolean 是否显示昵称
返回值及类型：
- bool:boolean 是否设置成功
该方法的其他说明：设置指定角色对象的昵称显示状态
具体使用案例如下：

lua

    local visible = false

    local result = Actor:ShowNickName(playerId, visible)

SetNickName

参数及类型：
- objid:number 角色对象ID
- nickname:string 昵称
返回值及类型：
- bool:boolean 是否设置成功
该方法的其他说明：设置指定角色的昵称，会自动过滤敏感词
具体使用案例如下：

lua

    local nickname = "昵称123"

    local result = Actor:SetNickName(playerId, nickname)

GetNickName

参数及类型：
- objid:number 角色对象ID
返回值及类型：
- name:string 角色昵称(失败返回nil)
该方法的其他说明：根据角色对象ID获取该角色的昵称，支持玩家和生物
具体使用案例如下：

lua

    -- 获取玩家昵称

    local name = Actor:GetNickName(playerId)

GetObjWorldId

参数及类型：
- objid:number 角色对象ID
返回值及类型：
- id:number 星球ID(失败返回-1)
该方法的其他说明：获取指定角色当前所在的星球ID
具体使用案例如下：

lua

    local worldId = Actor:GetObjWorldId(playerId)

IsPlayer

参数及类型：
- objid:number 对象ID
返回值及类型：
- bool:boolean 是否为玩家
该方法的其他说明：检测指定对象ID是否为玩家对象
具体使用案例如下：

lua

    local isPlayer = Actor:IsPlayer(objId)

PlaySoundEffectById

参数及类型：
- objid:number 角色对象ID
- soundId:number 声音ID
- volume:number 音量(0-100，实际会转换为0-1)
- pitch:number 音调(默认1.0)
- isLoop:boolean 是否循环播放(默认false)
返回值及类型：
- bool:boolean 是否播放成功
该方法的其他说明：在指定角色对象身上通过声音ID播放音效，支持设置音量、音调和循环播放
具体使用案例如下：

lua

     -- 对象上播放3d音效10379, 音量100, 音调1, 不循环

    local result = Actor:PlaySoundEffectById(playerId, 10379, 100, 1, false)

StopSoundEffectById

参数及类型：
- objid:number 角色对象ID
- soundId:number 声音ID
返回值及类型：
- bool:boolean 是否停止成功
该方法的其他说明：停止指定角色对象身上正在播放的音效
具体使用案例如下：

lua

    -- 停止播放3d音效10379

    local result3 = Actor:StopSoundEffectById(playerId, 10379)

PauseSoundEffectById

参数及类型：
- objid:number 角色对象ID
- soundId:number 声音ID(-1表示暂停所有音效)
- pause:boolean true暂停/false恢复
返回值及类型：
- bool:boolean 是否操作成功
该方法的其他说明：暂停或恢复指定角色对象身上正在播放的音效，支持暂停所有音效(soundId=-1)
具体使用案例如下：

lua

    --暂停播放3d音效10379

    local result2 = Actor:PauseSoundEffectById(playerId, 10379, true)

RotateFaceToActor

参数及类型：
- objid:number 生物对象ID
- targetid:number 目标生物对象ID
返回值及类型：
- bool:boolean 是否旋转成功
该方法的其他说明：使指定生物对象旋转朝向目标生物对象
具体使用案例如下：

lua

    local result = Actor:RotateFaceToActor(objId, playerId)

GetMotion

参数及类型：
- objid:number 对象ID
返回值及类型：
- x:number 运动速度X
- y:number 运动速度Y
- z:number 运动速度Z(未移动时速度为0)
该方法的其他说明：获取指定对象当前的移动速度，返回三个轴向的速度分量
具体使用案例如下：

lua

    local mx, my, mz = Actor:GetMotion(objId)

SetBeHurtTarget

参数及类型：
- objid:number 生物对象ID
- targetid:number 目标生物对象ID
返回值及类型：
- bool:boolean 是否设置成功
该方法的其他说明：设置指定生物对象的仇恨目标，用于AI战斗系统
具体使用案例如下：

lua

    local result = Actor:SetBeHurtTarget(objId, playerId)

GetActorFacade

参数及类型：
- objid:number 对象ID
- bhasequip:boolean 是否包含装备(默认false，仅玩家有效)
返回值及类型：
- facade:string 对象外观描述信息(失败返回nil)
该方法的其他说明：获取指定对象的外观描述信息，可设置是否包含装备信息（仅玩家有效，需要确保对象在场景中存在）
具体使用案例如下：

lua

    local playerId = Player:GetHostUin()

    Backpack:CreateItem(playerId, 12202, 1, BackpackType.Equip) -- 创建装备

    --附带装备信息目前只有玩家启用了模型组件才可以生效,并且用了带部件的商城坑位模型才生效,

    local includeequip = true

    local facade2 = Actor:GetActorFacade(playerId, includeequip)

CompareMainModel

参数及类型：
- facade1:string 外观类型1
- facade2:string 外观类型2
返回值及类型：
- bool:boolean 是否相等(参数错误返回false)
该方法的其他说明：比较两个主模型外观是否相等，通过外观描述信息进行对比
具体使用案例如下：

lua

    local sameResult = Actor:CompareMainModel("skin_259", "skin_259")

    local differentResult = Actor:CompareMainModel("skin_259", "skin_260")

PlayBodyParticleById

参数及类型：
- objid:number 生物对象ID
- particleId:number / string / table 粒子特效ID或ID数组
- ptme:number 时长(单位：秒)
- offset:table 偏移(默认{x=0,y=0,z=0})
- rot:table 旋转(默认{x=0,y=0,z=0})
- scale:table 缩放(默认{x=1,y=1,z=1})
返回值及类型：
- bool:boolean 是否播放成功
该方法的其他说明：在指定对象身上播放粒子特效，支持设置偏移、旋转和缩放，可批量播放多个特效
具体使用案例如下：

lua

    -- 对象上播放特效，特效id为1005，播放时间3秒，特效偏移y 2个方块位置，特效y旋转45，特效缩放为2倍

    local particleId = 1005

    local result = Actor:PlayBodyParticleById(objId, particleId, 3, {x = 0, y = 2, z = 0}, {x = 0, y = 45, z = 0}, {x = 2, y = 2, z = 2})

StopBodyEffectById

参数及类型：
- objid:number 生物对象ID
- particleId:number / string / table 粒子特效ID或ID数组
返回值及类型：
- bool:boolean 是否停止成功
该方法的其他说明：停止指定对象身上正在播放的粒子特效，支持单个或批量停止
具体使用案例如下：

lua

    local result = Actor:StopBodyEffectById(objId, particleId)

SetBodyParticleTransform

参数及类型：
- objid:number 生物对象ID
- particleId:number / string / table 粒子特效ID或ID数组
- offset:table 偏移(默认{x=0,y=0,z=0})
- rot:table 旋转(默认{x=0,y=0,z=0})
- scale:table 缩放(默认{x=1,y=1,z=1})
返回值及类型：
- bool:boolean 是否设置成功
该方法的其他说明：设置指定对象身上粒子特效的变换参数，包括偏移、旋转和缩放，支持批量设置
具体使用案例如下：

lua

    -- 修改对象上播放的特效，特效id为particleId，特效偏移y 3个方块位置，特效y旋转90，特效缩放为1.5倍

    local particleId = 1005

    local result = Actor:SetBodyParticleTransform(objId, particleId, {x = 0, y = 3, z = 0}, {x = 0, y = 90, z = 0}, {x = 1.5, y = 1.5, z = 1.5})

Jump

参数及类型：
- objid:number 对象ID
返回值及类型：
- bool:boolean 是否跳跃成功
该方法的其他说明：使指定玩家或生物对象执行一次跳跃动作
具体使用案例如下：

lua

    local result = Actor:Jump(objId)

GetRidingActorObjId

参数及类型：
- objid:number 角色对象ID
返回值及类型：
- id:number 生物对象ID(失败返回0)
该方法的其他说明：获取指定角色对象正在骑乘的生物对象ID
具体使用案例如下：

lua

    local ridingObjId = Actor:GetRidingActorObjId(playerId)

GetFaceDirection

参数及类型：
- objid:number 对象ID
返回值及类型：
- pos:table 轴向上的方向向量{x=number,y=number,z=number}(失败返回nil)
该方法的其他说明：获取指定对象当前的朝向方向，返回三个轴向的方向向量
具体使用案例如下：

lua

    local dir = Actor:GetFaceDirection(objId) -- 返回的是方向向量

TryMoveToActor

参数及类型：
- objid:number 执行动作的对象ID
- targetObjid:number 目标对象ID
- speed:number 移动速度
返回值及类型：
- bool:boolean 是否移动成功
该方法的其他说明：使指定对象向目标对象移动，可设置移动速度（注意：刚创建的对象需要加个等待时间）
具体使用案例如下：

lua

    -- 创建objId对象往玩家playerId走

    local result = Actor:TryMoveToActor(objId, playerId, 5)

SetFaceDirection

参数及类型：
- objid:number 对象ID
- x:number 轴向方向X
- y:number 轴向方向Y
- z:number 轴向方向Z
返回值及类型：
- bool:boolean 是否设置成功
该方法的其他说明：设置指定对象的朝向方向，通过三个轴向的方向向量控制
具体使用案例如下：

lua

        local x ,y,z = 0,0,1 -- 传入方向向量

        local result = Actor:SetFaceDirection(objId, x ,y,z)

KillSelf

参数及类型：
- objid:number 生物对象ID
返回值及类型：
- bool:boolean 是否击败成功
该方法的其他说明：击败指定生物对象，使其死亡
具体使用案例如下：

lua

    local result = Actor:KillSelf(objId)

SetAttr

参数及类型：
- objid:number 角色对象ID
- atttype:number 属性类型枚举(RoleAttr)RoleAttr
- val:number 属性值
返回值及类型：
- bool:boolean 是否设置成功
该方法的其他说明：设置指定角色对象的属性值，支持多种属性类型（血量、速度、体力等），属性改变会触发事件
具体使用案例如下：

lua

            -- attr 属性枚举 例如:RoleAttr.MaxHp

            local result = Actor:SetAttr(objId, attr, value)

IncreasesAttr

参数及类型：
- objid:number 角色对象ID
- atttype:number 属性类型枚举(RoleAttr)RoleAttr
- val:number 增加值
返回值及类型：
- bool:boolean 是否增加成功
该方法的其他说明：增加指定角色对象的属性值，在原有属性值基础上增加指定数值
具体使用案例如下：

lua

    local result = Actor:IncreasesAttr(playerId, RoleAttr.WalkSpeed, 1)

GetAttr

参数及类型：
- objid:number 角色对象ID
- atttype:number 属性类型枚举(RoleAttr)RoleAttr
返回值及类型：
- num:number 属性值(失败返回nil)
该方法的其他说明：获取指定角色对象的属性值，支持多种属性类型（血量、速度、体力等）
具体使用案例如下：

lua

            -- attr 属性枚举 例如:RoleAttr.MaxHp

            local attrValue = Actor:GetAttr(objId, attr)

SetActorPermissions

参数及类型：
- objid:number 对象ID
- ability:number 行为枚举(Ability)Ability
- switch:boolean 是否开启
返回值及类型：
- bool:boolean 是否设置成功
该方法的其他说明：设置指定对象的行为权限，控制对象的各种能力开关（推荐接口）
具体使用案例如下：

lua

        -- enableenum 是一个枚举值，例如:enableenum = Ability.EnableBeattacked

        local enablevalue = false

        local result = Actor:SetActorPermissions(objId, enableenum, enablevalue)

GetActorPermissions

参数及类型：
- objid:number 对象ID
- ability:number 行为枚举(Ability)Ability
返回值及类型：
- bool:boolean 权限开关状态
该方法的其他说明：获取指定对象的行为权限状态，查询对象的各种能力开关（推荐接口）
具体使用案例如下：

lua

        -- enableenum 是一个枚举值， 例如:enableenum = Ability.EnableBeattacked

        local state = Actor:GetActorPermissions(objId, enableenum)

SetFaceYaw

参数及类型：
- objid:number 生物对象ID
- yaw:number 面朝角度
返回值及类型：
- bool:boolean 是否设置成功
该方法的其他说明：设置指定生物对象的水平朝向角度（偏航角）
具体使用案例如下：

lua

    local setYaw = 90

    local result = Actor:SetFaceYaw(objId, setYaw)

GetFaceYaw

参数及类型：
- objid:number 生物对象ID
返回值及类型：
- num:number 面朝角度(失败返回nil)
该方法的其他说明：获取指定生物对象的水平朝向角度（偏航角）
具体使用案例如下：

lua

    local yaw = Actor:GetFaceYaw(objId)

SetFacePitch

参数及类型：
- objid:number 生物对象ID
- pitch:number 仰望角度
返回值及类型：
- bool:boolean 是否设置成功
该方法的其他说明：设置指定生物对象的垂直仰望角度（俯仰角）
具体使用案例如下：

lua

    local setPitch = 50

    local result = Actor:SetFacePitch(objId, setPitch)

GetFacePitch

参数及类型：
- objid:number 生物对象ID
返回值及类型：
- num:number 仰望角度(失败返回nil)
该方法的其他说明：获取指定生物对象的垂直仰望角度（俯仰角）
具体使用案例如下：

lua

    local pitch = Actor:GetFacePitch(objId)

SetPosition

参数及类型：
- objid:number 角色对象ID
- x:number 目标X坐标
- y:number 目标Y坐标
- z:number 目标Z坐标
返回值及类型：
- bool:boolean 是否设置成功
该方法的其他说明：设置指定角色对象的位置坐标，支持玩家和生物，坐标会自动转换为内部单位
具体使用案例如下：

lua

        local x, y, z = Actor:GetPosition(playerId)

        x, y, z = x + 10, y + 1, z + 10

        local result = Actor:SetPosition(objId, x, y, z)

GetPosition

参数及类型：
- objid:number 对象ID
返回值及类型：
- x:number 目标X坐标
- y:number 目标Y坐标
- z:number 目标Z坐标(失败返回nil)
该方法的其他说明：获取指定对象的位置坐标，返回三个轴向的坐标值，坐标会自动转换为外部单位
具体使用案例如下：

lua

        local x1, y1, z1 = Actor:GetPosition(objId)

ChangeCustomModel

参数及类型：
- objid:number 对象ID
- modleName:string 对象外观描述
返回值及类型：
- bool:boolean 是否改变成功
该方法的其他说明：改变指定对象的外观模型，支持多种模型类型（道具、生物、方块、实体等）
具体使用案例如下：

lua

    -- 改变对象外观为萤火虫

    local result = Actor:ChangeCustomModel(objId, "mob_3419")

RecoverinitialModel

参数及类型：
- objid:number 对象ID
返回值及类型：
- bool:boolean 是否恢复成功
该方法的其他说明：恢复指定对象到初始外观模型，清除自定义外观设置
具体使用案例如下：

lua

    local result = Actor:RecoverinitialModel(playerId)

ActorHurt

参数及类型：
- objid:number 攻击者对象ID
- targetid:number 目标对象ID
- damage:number 伤害值
- attacktype:number 伤害类型枚举(HurtType)HurtType
- ignoreResist:boolean 忽略伤害抵抗
- ignoreTriggerEvent:boolean 忽略触发伤害事件
返回值及类型：
- bool:boolean 是否造成伤害成功
该方法的其他说明：使指定对象对目标对象造成伤害，支持设置伤害类型、是否忽略伤害抵抗和触发事件
具体使用案例如下：

lua

    -- 玩家对生物造成近战伤害10点

    local result = Actor:ActorHurt(playerId, objId, 10, HurtType.Melee)

SetImmuneType

参数及类型：
- objid:number 对象ID
- immunetype:number 伤害类型枚举(HurtType，-1表示免疫所有伤害)HurtType
- isadd:boolean 是否开启免疫
返回值及类型：
- bool:boolean 是否设置成功
该方法的其他说明：设置指定对象对特定伤害类型的免疫状态，支持设置无敌状态（immunetype=-1）
具体使用案例如下：

lua

    -- 设置免疫爆炸伤害

    local result = Actor:SetImmuneType(objId, HurtType.Bomb, true)

    -- 设置免疫所有伤害

    Actor:SetImmuneType(objId, HurtType.All, true)

ChangActorMoveType

参数及类型：
- objid:number 对象ID
- moveMode:number 移动模式枚举(MoveType)MoveType
返回值及类型：
- bool:boolean 是否改变成功(角色没有对应能力时返回失败)
该方法的其他说明：改变指定对象的移动方式，支持行走、游泳、飞行等模式，如果角色没有对应能力则返回失败
具体使用案例如下：

lua

    local moveType = MoveType.Flying

    local result = Actor:ChangActorMoveType(objId, moveType)

GetActorMovementMode

参数及类型：
- objid:number 对象ID
返回值及类型：
- num:number 移动模式枚举(MoveType)(失败返回nil)
该方法的其他说明：获取指定角色对象当前的移动模式
具体使用案例如下：

lua

    local retmovetype = Actor:GetActorMovementMode(objId)

GetBoundSzie

参数及类型：
- objid:number 角色对象ID
返回值及类型：
- vec:table 模型大小{x=长,y=高,z=宽}(失败返回nil)
该方法的其他说明：获取指定角色对象的模型边界大小，返回长、高、宽三个维度的尺寸
具体使用案例如下：

lua

    local size = Actor:GetBoundSzie(objId)

RandomFacadeID

参数及类型：无
返回值及类型：
- id:string 随机外观ID(失败返回nil)
该方法的其他说明：从外观列表中随机获取一个外观ID字符串，包括生物、角色、装扮等类型
具体使用案例如下：

lua

    local facadeID = Actor:RandomFacadeID()

GetObjType

参数及类型：
- objid:number 对象ID
返回值及类型：
- itype:number 对象类型枚举(ObjType)(失败返回nil)
该方法的其他说明：获取指定对象的类型，判断对象是玩家、生物还是其他类型
具体使用案例如下：

lua

    local objType = Actor:GetObjType(objId)

TryMoveToPos

参数及类型：
- objid:number 角色对象ID
- x:number 目标X坐标
- y:number 目标Y坐标
- z:number 目标Z坐标
- cancontrol:boolean 是否能控制(默认true)
- bshowtip:boolean 是否显示提示(默认false)
返回值及类型：
- bool:boolean 是否移动成功
该方法的其他说明：尝试移动指定角色对象到目标位置，使用寻路算法，支持设置是否可控制和是否显示提示
具体使用案例如下：

lua

    local result = Actor:TryMoveToPos(objId, x + 10, y + 1, z, false, false)

AppendSpeed

参数及类型：
- objid:number 对象ID
- vx:number 轴向速度X
- vy:number 轴向速度Y
- vz:number 轴向速度Z
返回值及类型：
- bool:boolean 是否附加成功
该方法的其他说明：给指定对象附加一个速度，在三个轴向上叠加速度分量
具体使用案例如下：

lua

    -- 给对象增加个x轴20,y轴10,z轴0的移动速度

    local result = Actor:AppendSpeed(objId, 20, 10, 0)

FindNearestBlock

参数及类型：
- objid:number 对象ID
- blockid:number / string 查找的方块类型ID
- blockRange:number 查找范围(传1表示1格方块距离)
返回值及类型：
- x:number 方块坐标X
- y:number 方块坐标Y
- z:number 方块坐标Z(失败返回nil)
该方法的其他说明：在指定对象附近查找某个类型方块的最近位置，返回方块坐标
具体使用案例如下：

lua

    --查找玩家50格子内最近的草块（草块ID为100）

    local WorldId = Actor:GetObjWorldId(playerId)

    local blockType = 100

    if WorldId == 2 then--萌眼星

        blockType = 116

    elseif WorldId == 1 then --烈焰星

        blockType = 124

    end

    local block = Actor:FindNearestBlock(playerId, blockType, 50)

GetEyeHeight

参数及类型：
- objid:number 角色对象ID
返回值及类型：
- num:number 眼睛高度(失败返回nil)
该方法的其他说明：获取指定角色对象的眼睛高度，用于视线计算
具体使用案例如下：

lua

    local height = Actor:GetEyeHeight(objId)

ClearActorWithId

参数及类型：
- actorid:number / string 生物类型ID
- bkill:boolean 是否杀死生物(默认false，影响是否产生掉落物)
- worldId:number 星球ID(默认当前主机所在星球)
返回值及类型：
- bool:boolean 是否清除成功
该方法的其他说明：清除指定类型的所有生物，可设置是否杀死生物（影响是否产生掉落物）和指定星球
具体使用案例如下：

lua

    local worldId = Actor:GetObjWorldId(playerId)

    local result = Actor:ClearActorWithId(3400, false, worldId)

IsExist

参数及类型：
- objid:number 对象ID
返回值及类型：
- bool:boolean 是否存在
该方法的其他说明：检测指定对象是否存在且存活
具体使用案例如下：

lua

        local isExist = Actor:IsExist(objId)

PlayAnim

参数及类型：
- objid:number 对象ID
- animid:number / string 动作ID
- speed:number 播放速度
- loop:number / boolean 播放模式(AnimMode)或是否循环AnimMode
返回值及类型：
- bool:boolean 是否播放成功
该方法的其他说明：在指定对象身上播放动作，支持设置播放速度和循环模式，播放成功会触发事件
具体使用案例如下：

lua

    local result = Actor:PlayAnim(objId, 100101, 1, AnimMode.Default)

PlayHandAnim

参数及类型：
- objid:number 对象ID
- animid:number / string 动作ID
- speed:number 播放速度
- loop:number / boolean 播放模式(AnimMode)或是否循环AnimMode
返回值及类型：
- bool:boolean 是否播放成功
该方法的其他说明：在指定对象的手部播放动作，支持设置播放速度和循环模式
具体使用案例如下：

lua

    local result = Actor:PlayHandAnim(objId, 100100, 1, AnimMode.Once)

MountActor

参数及类型：
- objid:number 对象ID
- rideobjid:number 被骑乘对象ID
- isContrl:boolean 是否控制
- isCloseAI:boolean 是否关闭AI
返回值及类型：
- bool:boolean 是否骑乘成功
该方法的其他说明：使指定角色对象骑乘到目标对象上，支持设置是否控制和是否关闭AI
具体使用案例如下：

lua

    local result = Actor:MountActor(playerId, objId, true, true)

DisMountActor

参数及类型：
- objid:number 对象ID
返回值及类型：
- bool:boolean 是否取消成功
该方法的其他说明：使指定角色对象取消当前骑乘状态
具体使用案例如下：

lua

    local result2 = Actor:DisMountActor(playerId)

PickupActor

参数及类型： objidA:number:对象objidA,objidB:number:对象objidB
返回值及类型：
- bool:boolean 是否举起成功
该方法的其他说明：使角色A尝试举起角色B
具体使用案例如下：

lua

    --偏移量方块距离

    local offset = {

        x = 0,

        y = 1,

        z = 0,

    }

    --偏移量

    local rotate = {

        x = 0,

        y = 0,

        z = 0,

    }

    local result = Actor:PickupActor(playerId, objId, 100502, 100113, offset, rotate)

TryPickupActorForward

参数及类型：
- objid:number 角色对象ID
- distance:number 抓取距离
返回值及类型：
- bool:boolean 是否抓取成功
该方法的其他说明：尝试抓取指定角色前方指定距离内的对象，失败时会播放尝试举起动作
具体使用案例如下：

lua

    local result = Actor:TryPickupActorForward(playerId, 30)

DropActor

参数及类型：
- objid:number 投掷动作对象ID
- dir:table 投掷方向{x=number,y=number,z=number}
- isThrow:boolean 是否投掷
- speed:number 投掷速度
- hasInertance:boolean 是否有惯性
返回值及类型：
- bool:boolean 是否投掷成功
该方法的其他说明：尝试投掷指定角色对象，支持设置投掷方向、速度、是否投掷和是否有惯性
具体使用案例如下：

lua

    local result2 = Actor:DropActor(playerId, {x = 1, y = 2, z = 0}, true, 500, true)

EscapePickup

参数及类型：
- objid:number 被抓举的对象ID
返回值及类型：
- bool:boolean 是否逃脱成功
该方法的其他说明：使指定被抓举的对象尝试逃脱抓举状态
具体使用案例如下：

lua

    local result = Actor:EscapePickup(objId)

SetBtreeVarValue

参数及类型：
- objid:number 生物对象ID
- varid:string 变量ID
- val:any变量值
返回值及类型：
- bool:boolean 是否设置成功(组数据无法设置)
该方法的其他说明：设置指定生物对象行为树的变量值，组数据无法设置
具体使用案例如下：

lua

    local treeId = "7447781052440657655_1"

    Monster:ChangeAI(objId, treeId)

    local treevalue = 99

    local varid  = "7447781778290130679-23182_23712" --行为树中定义的黑板变量,需要确保生物对象有这个行为树和变量

    local result = Actor:SetBtreeVarValue(objId,varid, treevalue)

GetBtreeVarValue

参数及类型：
- objid:number 生物对象ID
- varid:string 变量ID
返回值及类型：
- val:any变量值(失败返回nil，组数据无法获取)
该方法的其他说明：获取指定生物对象行为树的变量值，组数据无法获取
具体使用案例如下：

lua

    local varid  = "7447781778290130679-23182_23712" --行为树中定义的黑板变量

    local value = Actor:GetBtreeVarValue(objId, varid)

GetDropItemInstanceId

参数及类型：
- objid:number 掉落物对象ID
返回值及类型：
- id:string 道具实例ID(失败返回nil)
该方法的其他说明：根据掉落物对象ID获取对应的道具实例ID
具体使用案例如下：

lua

        local result = Actor:GetDropItemInstanceId(objId)

SetAblePick

参数及类型：
- objid:number 掉落物对象ID
- able:boolean 是否可以拾取
返回值及类型：
- bool:boolean 是否设置成功
该方法的其他说明：设置指定掉落物对象是否可以被拾取
具体使用案例如下：

lua

        local result = Actor:SetAblePick(objId, false)

GetEntityFacade

参数及类型：
- prefab:string 实体类型名称
返回值及类型：
- facade:string 外观描述信息(失败返回nil)
该方法的其他说明：根据实体类型名称获取对应的外观描述信息，支持官方模板实体和自定义实体
具体使用案例如下：

lua

    --传入自定义实体prefabid

    local result = Actor:GetEntityFacade("s_7509852525127419914_23098")

PickupItem

参数及类型：
- objid:number 角色对象ID
- itemobjid:number 掉落物或投掷物对象ID
- bforcepickup:boolean 是否强制拾取(默认false)
返回值及类型：
- num:number 拾取数量(失败返回0)
该方法的其他说明：使指定角色对象拾取地上的掉落物或投掷物，支持强制拾取
具体使用案例如下：

lua

    local result = Actor:PickupItem(playerId, objId)

    if result then

        print("拾取掉落物成功 数量 = " ,result)

    end

GetPickupObjID

参数及类型：
- objid:number 角色对象ID
- roleType:number 角色类型(1=举起者CARRYING, 2=被举起者CARRIED)
返回值及类型：
- id:number 角色对象ID(失败返回0)
该方法的其他说明：获取指定角色举起的角色对象ID或被举起的角色对象ID
具体使用案例如下：

lua

        local result = Actor:GetPickupObjID(playerId, RolePickupType.Carrying)

HasTags

参数及类型：
- objid:number 对象ID
- tags:string / table 标签或标签数组
- mathcmode:number 匹配方式(MatchMode)MatchMode
- bexactmatch:boolean 每条标签是否精确匹配
返回值及类型：
- bool:boolean 是否具有标签
该方法的其他说明：检测指定对象是否具有指定标签，支持部分匹配方式和精确匹配
具体使用案例如下：

lua

    local result3 = Actor:HasTags(playerId, {"A.B.C", "A.D.E", "F.G.H" }, MatchMode.All, true)

    local result4 = Actor:HasTags(playerId, {"A.B.C", "D.E", "S.T.D" }, MatchMode.All, false)

    local result5 = Actor:HasTags(playerId, {"A.B.C", "B.C" }, MatchMode.Any, false)

    local result6 = Actor:HasTags(playerId, { "G.H" }, MatchMode.Any, false)

GetTags

参数及类型：
- objid:number 对象ID
返回值及类型：
- tags:table 标签数组(失败返回nil)
该方法的其他说明：获取指定对象的所有标签列表
具体使用案例如下：

lua

    local getTags = Actor:GetTags(playerId)

    if getTags then

        print("玩家定义中的标签：", getTags)

    end

AddTags

参数及类型：
- objid:number 对象ID
- tags:string / table 标签或标签数组(数值字母下划线组合)
- icount:number 引用计数(默认1)
返回值及类型：
- bool:boolean 是否添加成功
该方法的其他说明：为指定对象添加标签，支持批量添加，标签由数值、字母和下划线组合，支持引用计数
具体使用案例如下：

lua

    local tags = { "A.B.C", "A.D.E", "F.G.H" }

    local result2 = Actor:AddTags(playerId, tags, 1)

    if result2 then

        print("添加标签成功", result2)

    end

RemoveTags

参数及类型：
- objid:number 对象ID
- tags:string / table 标签或标签数组
- icount:number 引用计数(默认0，传0全部删除)
返回值及类型：
- bool:boolean 是否删除成功
该方法的其他说明：从指定对象删除标签，支持批量删除，引用计数为0时全部删除
具体使用案例如下：

lua

        local result = Actor:RemoveTags(playerId, tag, 1)

ClearTags

参数及类型：
- objid:number 对象ID
返回值及类型：
- bool:boolean 是否清空成功
该方法的其他说明：清空指定对象的所有标签
具体使用案例如下：

lua

    local result = Actor:ClearTags(playerId)

PlayAnimByObj

参数及类型：
- objidA:number 对象ID A
- objidB:number 对象ID B
- breplay:boolean 是否重新播放(默认false)
返回值及类型：
- bool:boolean 是否播放成功(仅玩家、生物、实体生效)
该方法的其他说明：使对象A播放对象B的动作，仅玩家、生物和实体生效，模型外观最好一致
具体使用案例如下：

lua

        local result = Actor:PlayAnimByObj(objId, playerId, true) -- objId对象跟随playerId播放动作

角色模块管理接口 Actor ​

GetItemId ​

GetDropItemNum ​

SetTeam ​

GetTeam ​

AddHp ​

GetMaxHP ​

ShowNickName ​

SetNickName ​

GetNickName ​

GetObjWorldId ​

IsPlayer ​

PlaySoundEffectById ​

StopSoundEffectById ​

PauseSoundEffectById ​

RotateFaceToActor ​

GetMotion ​

SetBeHurtTarget ​

GetActorFacade ​

CompareMainModel ​

PlayBodyParticleById ​

StopBodyEffectById ​

SetBodyParticleTransform ​

Jump ​

GetRidingActorObjId ​

GetFaceDirection ​

TryMoveToActor ​

SetFaceDirection ​

KillSelf ​

SetAttr ​

IncreasesAttr ​

GetAttr ​

SetActorPermissions ​

GetActorPermissions ​

SetFaceYaw ​

GetFaceYaw ​

SetFacePitch ​

GetFacePitch ​

SetPosition ​

GetPosition ​

ChangeCustomModel ​

RecoverinitialModel ​

ActorHurt ​

SetImmuneType ​

ChangActorMoveType ​

GetActorMovementMode ​

GetBoundSzie ​

RandomFacadeID ​

GetObjType ​

TryMoveToPos ​

AppendSpeed ​

FindNearestBlock ​

GetEyeHeight ​

ClearActorWithId ​

IsExist ​

PlayAnim ​

PlayHandAnim ​

MountActor ​

DisMountActor ​

PickupActor ​

TryPickupActorForward ​

DropActor ​

EscapePickup ​

SetBtreeVarValue ​

GetBtreeVarValue ​

GetDropItemInstanceId ​

SetAblePick ​

GetEntityFacade ​

PickupItem ​

GetPickupObjID ​

HasTags ​

GetTags ​

AddTags ​

RemoveTags ​

ClearTags ​

PlayAnimByObj ​