API手册

CLASS

AIBasicCommand

AI基础命令类型

Ability

技能

AbilityKey

技能编号

AbilityLimitation

技能使用限制

AbilitySlot

技能槽位

AbilityStyleKey

技能控件样式编号

Achievement

自定义成就

AnimKey

动画编号

AnimationStyleKey

动效样式编号

Archive

自定义存档

ArchiveType

存档类型

BagSlotStyleKey

物品格样式编号

BattleShopKey

商店

BindType

绑定类型

Bool

布尔值

BtnStyleKey

按钮样式编号

BuffState

状态

CameraBindMode

相机绑定模式

CameraProjectionType

相机投影类型

CameraPropertyType

相机属性预设

CameraShakeType

屏幕震动类型

Camp

阵营

CampID

阵营ID

Character

角色

CharacterKey

角色编号

ChessType

麻将/扑克花色

CollisionLimitType

碰撞限制枚举

Color

颜色

Creature

生物

CreatureKey

生物编号

CustomTriggerSpace

触发区域

CustomTriggerSpaceKey

触发区域编号

DamageSchema

伤害方案

DecorationKey

装饰物编号

Dict

字典

DirectionType

方向枚举

E3DLayer

场景UI实例

E3DLayerKey

场景UI预设

EAnimationState

UI动画状态

EBagSlot

UI物品槽位节点

EButton

UI按钮节点

EEffectNode

UI动效节点

EImage

UI图片节点

EInputField

UI输入节点

ELabel

UI文本节点

ENode

UI节点

EProgressbar

UI进度条节点

ETypeMeta

None

EmojiKey

气泡表情编号

Equipment

物品

EquipmentKey

物品编号

EquipmentSlot

物品槽位

EquipmentSlotType

物品槽位类型

Fixed

定点数

FontKey

字体key

FriendshipType

好友关系

Function

函数

ImageKey

图片编号

InputStyleKey

输入框样式编号

Int

整型

InteractBtnID

交互按钮编号

InteractBtnType

交互按钮类型

JointAssistantKey

关节预设编号

JointAssistantProperty

关节属性

LabelStyleKey

文本样式编号

LevelKey

关卡编号

LifeEntity

生命体

List

列表

ListAIBasicCommand

AI基础命令类型列表

ListFixed

定点数列表

ListStr

字符串列表

ListUnitType

单位类型列表

ListVector3

向量列表

ModelSocket

部位

Modifier

效果

ModifierKey

效果编号

MontageKey

剧情动画编号

MoveMode

AI移动模式

Obstacle

组件

ObstacleKey

组件编号

PaintArea

染色区域

PathID

路径ID

PathPointID

路点ID

PatrolType

AI巡逻类型

PlaneType

拖动平面

Point3

坐标点

ProgressBarStyleKey

条形进度条样式编号

ProgressTimerStyleKey

环形进度条样式编号

Quaternion

四元数

Role

玩家

RoleID

玩家ID

SfxID

特效ID

SfxKey

特效编号

SheetID

表格

Skeleton

骨骼

SkyBoxBackground

天空盒背景

SkyBoxGradualType

天空盒渐变类型

SoundID

音效ID

SoundKey

音效编号

Str

字符串

Timer

计时器

Timestamp

时间戳

TriggerSpaceKey

逻辑体编号

UIPreset

UIPreset

UgcCommodity

道具

UgcGoods

商品

Unit

单位

UnitGroupKey

组件组编号

UnitID

单位ID

UnitKey

单位编号

UnitType

单位类型

ValueType

值类型

Vector3

向量

Vehicle

载具

VehicleKey

单位编号(载具)

WindFieldShapeType

风场形状

ENUM

UnitType 单位类型

CREATURE 4 生物

CUSTOMTRIGGERSPACE 8 触发区域

CHARACTER 128 角色

OBSTACLE 256 组件

TRIGGERSPACE 512 逻辑体

DECORATION 1024 装饰物

EQUIPMENT 32768 物品

ValueType 值类型

AIBasicCommand AIBasicCommand AI基础命令类型

Ability Ability 技能

AbilityAnchorID AbilityAnchorID 技能锚点ID

AbilityIndex AbilityIndex 技能槽位(内部)

AbilityKey AbilityKey 技能编号

AbilityLimitation AbilityLimitation 技能使用限制

AbilityPointerType AbilityPointerType 技能指示器类型

AbilitySlot AbilitySlot 技能槽位

AbilityStyleKey AbilityStyleKey 技能控件样式编号

Achievement Achievement 自定义成就

Actor Actor Actor

AnimKey AnimKey 动画编号

AnimationStyleKey AnimationStyleKey 动效样式编号

Archive Archive 自定义存档

ArchiveType ArchiveType 存档类型

BagSlotStyleKey BagSlotStyleKey 物品格样式编号

BattleShopKey BattleShopKey 商店

BindType BindType 绑定类型

Bool Bool 布尔值

BtnStyleKey BtnStyleKey 按钮样式编号

BuffState BuffState 状态

CameraBindMode CameraBindMode 相机绑定模式

CameraDragType CameraDragType 相机拖动类型

CameraProjectionType CameraProjectionType 相机投影类型

CameraPropertyType CameraPropertyType 相机属性预设

CameraShakeCurve CameraShakeCurve 屏幕震动曲线

CameraShakeType CameraShakeType 屏幕震动类型

Camp Camp 阵营

CampID CampID 阵营ID

CampRelationType CampRelationType 阵营关系类型

Character Character 角色

CharacterID CharacterID 角色ID

CharacterKey CharacterKey 角色编号

ChessType ChessType 麻将/扑克花色

CollisionLimitType CollisionLimitType 碰撞限制枚举

Color Color 颜色

Creature Creature 生物

CreatureID CreatureID 生物ID

CreatureKey CreatureKey 生物编号

CustomTriggerSpace CustomTriggerSpace 触发区域

CustomTriggerSpaceID CustomTriggerSpaceID 触发区域ID

CustomTriggerSpaceKey CustomTriggerSpaceKey 触发区域编号

Damage Damage 伤害

DamageSchema DamageSchema 伤害方案

Decoration Decoration 装饰物

DecorationKey DecorationKey 装饰物编号

DirectionType DirectionType 方向枚举

DynamicTextID DynamicTextID 动态文字ID

E3DLayer E3DLayer 场景UI实例

E3DLayerKey E3DLayerKey 场景UI预设

EAnimationState EAnimationState UI动画状态

EBagSlot EBagSlot UI物品槽位节点

EButton EButton UI按钮节点

ECanvas ECanvas UI画布节点

EEffectNode EEffectNode UI动效节点

EImage EImage UI图片节点

EInputField EInputField UI输入节点

ELabel ELabel UI文本节点

ENode ENode UI节点

ENodeTouchEventType ENodeTouchEventType 界面交互事件类型

EProgressbar EProgressbar UI进度条节点

EmojiKey EmojiKey 气泡表情编号

Equipment Equipment 物品

EquipmentID EquipmentID 物品ID

EquipmentKey EquipmentKey 物品编号

EquipmentSlot EquipmentSlot 物品槽位

EquipmentSlotType EquipmentSlotType 物品槽位类型

EquipmentType EquipmentType 物品类型

FaceExpressionKey FaceExpressionKey 面部表情编号

FaceStatusKey FaceStatusKey 动态表情key

FashionKey FashionKey 时装编号

Fixed Fixed 定点数

FontKey FontKey 字体key

FriendshipType FriendshipType 好友关系

GameResult GameResult 游戏结局

HpBarDisplayMode HpBarDisplayMode 血条显示模式

ImageKey ImageKey 图片编号

InputStyleKey InputStyleKey 输入框样式编号

Int Int 整型

InteractBtnID InteractBtnID 交互按钮编号

InteractBtnType InteractBtnType 交互按钮类型

JointAssistant JointAssistant 关节

JointAssistantKey JointAssistantKey 关节预设编号

JointAssistantProperty JointAssistantProperty 关节属性

JointAssistantType JointAssistantType 关节类型

LabelStyleKey LabelStyleKey 文本样式编号

LevelKey LevelKey 关卡编号

LifeEntity LifeEntity 生命体

LifeEntityKey LifeEntityKey 生命体编号

ListAIBasicCommand ListAIBasicCommand AI基础命令类型列表

ListAbility ListAbility 技能列表

ListAbilityAnchorID ListAbilityAnchorID 技能锚点ID列表

ListAbilityIndex ListAbilityIndex 技能槽位(内部)列表

ListAbilityKey ListAbilityKey 技能编号列表

ListAbilityLimitation ListAbilityLimitation 技能使用限制列表

ListAbilityPointerType ListAbilityPointerType 技能指示器类型列表

ListAbilitySlot ListAbilitySlot 技能槽位列表

ListAbilityStyleKey ListAbilityStyleKey 技能控件样式编号列表

ListAchievement ListAchievement 自定义成就列表

ListActor ListActor Actor列表

ListAnimKey ListAnimKey 动画编号列表

ListAnimationStyleKey ListAnimationStyleKey 动效样式编号列表

ListArchive ListArchive 自定义存档列表

ListArchiveType ListArchiveType 存档类型列表

ListBagSlotStyleKey ListBagSlotStyleKey 物品格样式编号列表

ListBattleShopKey ListBattleShopKey 商店列表

ListBindType ListBindType 绑定类型列表

ListBool ListBool 布尔值列表

ListBtnStyleKey ListBtnStyleKey 按钮样式编号列表

ListBuffState ListBuffState 状态列表

ListCameraBindMode ListCameraBindMode 相机绑定模式列表

ListCameraDragType ListCameraDragType 相机拖动类型列表

ListCameraProjectionType ListCameraProjectionType 相机投影类型列表

ListCameraPropertyType ListCameraPropertyType 相机属性预设列表

ListCameraShakeCurve ListCameraShakeCurve 屏幕震动曲线列表

ListCameraShakeType ListCameraShakeType 屏幕震动类型列表

ListCamp ListCamp 阵营列表

ListCampID ListCampID 阵营ID列表

ListCampRelationType ListCampRelationType 阵营关系类型列表

ListCharacter ListCharacter 角色列表

ListCharacterID ListCharacterID 角色ID列表

ListCharacterKey ListCharacterKey 角色编号列表

ListChessType ListChessType 麻将/扑克花色列表

ListCollisionLimitType ListCollisionLimitType 碰撞限制枚举列表

ListColor ListColor 颜色列表

ListCreature ListCreature 生物列表

ListCreatureID ListCreatureID 生物ID列表

ListCreatureKey ListCreatureKey 生物编号列表

ListCustomTriggerSpace ListCustomTriggerSpace 触发区域列表

ListCustomTriggerSpaceID ListCustomTriggerSpaceID 触发区域ID列表

ListCustomTriggerSpaceKey ListCustomTriggerSpaceKey 触发区域编号列表

ListDamage ListDamage 伤害列表

ListDamageSchema ListDamageSchema 伤害方案列表

ListDecoration ListDecoration 装饰物列表

ListDecorationKey ListDecorationKey 装饰物编号列表

ListDirectionType ListDirectionType 方向枚举列表

ListDynamicTextID ListDynamicTextID 动态文字ID列表

ListE3DLayer ListE3DLayer 场景UI实例列表

ListE3DLayerKey ListE3DLayerKey 场景UI预设列表

ListEAnimationState ListEAnimationState UI动画状态列表

ListEBagSlot ListEBagSlot UI物品槽位节点列表

ListEButton ListEButton UI按钮节点列表

ListECanvas ListECanvas UI画布节点列表

ListEEffectNode ListEEffectNode UI动效节点列表

ListEImage ListEImage UI图片节点列表

ListEInputField ListEInputField UI输入节点列表

ListELabel ListELabel UI文本节点列表

ListENode ListENode UI节点列表

ListENodeTouchEventType ListENodeTouchEventType 界面交互事件类型列表

ListEProgressbar ListEProgressbar UI进度条节点列表

ListEmojiKey ListEmojiKey 气泡表情编号列表

ListEquipment ListEquipment 物品列表

ListEquipmentID ListEquipmentID 物品ID列表

ListEquipmentKey ListEquipmentKey 物品编号列表

ListEquipmentSlot ListEquipmentSlot 物品槽位列表

ListEquipmentSlotType ListEquipmentSlotType 物品槽位类型列表

ListEquipmentType ListEquipmentType 物品类型列表

ListFaceExpressionKey ListFaceExpressionKey 面部表情编号列表

ListFaceStatusKey ListFaceStatusKey 动态表情key列表

ListFashionKey ListFashionKey 时装编号列表

ListFixed ListFixed 定点数列表

ListFontKey ListFontKey 字体key列表

ListFriendshipType ListFriendshipType 好友关系列表

ListGameResult ListGameResult 游戏结局列表

ListHpBarDisplayMode ListHpBarDisplayMode 血条显示模式列表

ListImageKey ListImageKey 图片编号列表

ListInputStyleKey ListInputStyleKey 输入框样式编号列表

ListInt ListInt 整型列表

ListInteractBtnID ListInteractBtnID 交互按钮编号列表

ListInteractBtnType ListInteractBtnType 交互按钮类型列表

ListJointAssistant ListJointAssistant 关节列表

ListJointAssistantKey ListJointAssistantKey 关节预设编号列表

ListJointAssistantProperty ListJointAssistantProperty 关节属性列表

ListJointAssistantType ListJointAssistantType 关节类型列表

ListLabelStyleKey ListLabelStyleKey 文本样式编号列表

ListLevelKey ListLevelKey 关卡编号列表

ListLifeEntity ListLifeEntity 生命体列表

ListLifeEntityKey ListLifeEntityKey 生命体编号列表

ListModelSocket ListModelSocket 部位列表

ListModifier ListModifier 效果列表

ListModifierKey ListModifierKey 效果编号列表

ListMontageKey ListMontageKey 剧情动画编号列表

ListMoveMode ListMoveMode AI移动模式列表

ListObstacle ListObstacle 组件列表

ListObstacleID ListObstacleID 组件ID列表

ListObstacleKey ListObstacleKey 组件编号列表

ListOrientationType ListOrientationType 方位枚举列表

ListPaintArea ListPaintArea 染色区域列表

ListPathID ListPathID 路径ID列表

ListPathPointID ListPathPointID 路点ID列表

ListPatrolType ListPatrolType AI巡逻类型列表

ListPlaneType ListPlaneType 拖动平面列表

ListProgressBarStyleKey ListProgressBarStyleKey 条形进度条样式编号列表

ListProgressTimerStyleKey ListProgressTimerStyleKey 环形进度条样式编号列表

ListQuaternion ListQuaternion 四元数列表

ListRigidBodyType ListRigidBodyType 物理类型列表

ListRole ListRole 玩家列表

ListRoleID ListRoleID 玩家ID列表

ListSfxID ListSfxID 特效ID列表

ListSfxKey ListSfxKey 特效编号列表

ListSheetID ListSheetID 表格列表

ListSkeleton ListSkeleton 骨骼列表

ListSkyBoxBackground ListSkyBoxBackground 天空盒背景列表

ListSkyBoxGradualType ListSkyBoxGradualType 天空盒渐变类型列表

ListSound3DKey ListSound3DKey 3D音效编号列表

ListSoundID ListSoundID 音效ID列表

ListSoundKey ListSoundKey 音效编号列表

ListStr ListStr 字符串列表

ListTimer ListTimer 计时器列表

ListTimestamp ListTimestamp 时间戳列表

ListTrigger ListTrigger 触发器列表

ListTriggerSpace ListTriggerSpace 逻辑体列表

ListTriggerSpaceEventType ListTriggerSpaceEventType 触发区域类型列表

ListTriggerSpaceID ListTriggerSpaceID 逻辑体ID列表

ListTriggerSpaceKey ListTriggerSpaceKey 逻辑体编号列表

ListUIPreset ListUIPreset UIPreset列表

ListUIPresetNode ListUIPresetNode UI预设节点列表

ListUgcCommodity ListUgcCommodity 道具列表

ListUgcGoods ListUgcGoods 商品列表

ListUnit ListUnit 单位列表

ListUnitGroup ListUnitGroup 物理组件组列表

ListUnitGroupKey ListUnitGroupKey 组件组编号列表

ListUnitID ListUnitID 单位ID列表

ListUnitKey ListUnitKey 单位编号列表

ListUnitType ListUnitType 单位类型列表

ListValueType ListValueType 值类型列表

ListVector3 ListVector3 向量列表

ListVehicle ListVehicle 载具列表

ListVehicleKey ListVehicleKey 单位编号(载具)列表

ListWindFieldShapeType ListWindFieldShapeType 风场形状列表

ModelSocket ModelSocket 部位

Modifier Modifier 效果

ModifierKey ModifierKey 效果编号

MontageKey MontageKey 剧情动画编号

MoveMode MoveMode AI移动模式

Obstacle Obstacle 组件

ObstacleID ObstacleID 组件ID

ObstacleKey ObstacleKey 组件编号

OrientationType OrientationType 方位枚举

PaintArea PaintArea 染色区域

PathID PathID 路径ID

PathPointID PathPointID 路点ID

PatrolType PatrolType AI巡逻类型

PlaneType PlaneType 拖动平面

ProgressBarStyleKey ProgressBarStyleKey 条形进度条样式编号

ProgressTimerStyleKey ProgressTimerStyleKey 环形进度条样式编号

Quaternion Quaternion 四元数

RigidBodyType RigidBodyType 物理类型

Role Role 玩家

RoleID RoleID 玩家ID

SfxID SfxID 特效ID

SfxKey SfxKey 特效编号

SheetID SheetID 表格

Skeleton Skeleton 骨骼

SkyBoxBackground SkyBoxBackground 天空盒背景

SkyBoxGradualType SkyBoxGradualType 天空盒渐变类型

Sound3DKey Sound3DKey 3D音效编号

SoundID SoundID 音效ID

SoundKey SoundKey 音效编号

Str Str 字符串

Timer Timer 计时器

Timestamp Timestamp 时间戳

Trigger Trigger 触发器

TriggerSpace TriggerSpace 逻辑体

TriggerSpaceEventType TriggerSpaceEventType 触发区域类型

TriggerSpaceID TriggerSpaceID 逻辑体ID

TriggerSpaceKey TriggerSpaceKey 逻辑体编号

UIPreset UIPreset UIPreset

UIPresetNode UIPresetNode UI预设节点

UgcCommodity UgcCommodity 道具

UgcGoods UgcGoods 商品

Unit Unit 单位

UnitGroup UnitGroup 物理组件组

UnitGroupKey UnitGroupKey 组件组编号

UnitID UnitID 单位ID

UnitKey UnitKey 单位编号

UnitType UnitType 单位类型

ValueType ValueType 值类型

Vector3 Vector3 向量

Vehicle Vehicle 载具

VehicleKey VehicleKey 单位编号(载具)

WindFieldShapeType WindFieldShapeType 风场形状

ArchiveType 存档类型

Bool Bool 布尔值

Fixed Fixed 定点数

Int Int 整型

SheetID SheetID 表格

Str Str 字符串

Timestamp Timestamp 时间戳

JointAssistantKey 关节预设编号

SPRING 3400000 SPRING

ROPE 3400001 ROPE

SLIDER 3400002 SLIDER

HINGE 3400003 HINGE

BALL_SOCKET 3400004 BALL_SOCKET

D6 3400005 D6

FIXED 3400006 FIXED

ModelSocket 部位

socket_abdomen socket_abdomen 腹部

socket_belly socket_belly 鱼腹

socket_body socket_body 身体

socket_calf_l socket_calf_l 左小腿

socket_calf_r socket_calf_r 右小腿

socket_chest socket_chest 胸部

socket_claw_l socket_claw_l 左钳

socket_claw_r socket_claw_r 右钳

socket_eye_l socket_eye_l 左眼

socket_eye_r socket_eye_r 右眼

socket_fin_back socket_fin_back 背后鳍

socket_fin_dorsal socket_fin_dorsal 背鳍

socket_fin_l socket_fin_l 左鳍

socket_fin_lb socket_fin_lb 左后鳍

socket_fin_r socket_fin_r 右鳍

socket_fin_rb socket_fin_rb 右后鳍

socket_fin_tail socket_fin_tail 尾鳍

socket_fin_ventral socket_fin_ventral 腹鳍

socket_fin_ventral_l socket_fin_ventral_l 左腹鳍

socket_fin_ventral_r socket_fin_ventral_r 右腹鳍

socket_foot_l socket_foot_l 左脚

socket_foot_lb socket_foot_lb 左后脚

socket_foot_lf socket_foot_lf 左前脚

socket_foot_lm socket_foot_lm 左中脚

socket_foot_r socket_foot_r 右脚

socket_foot_rb socket_foot_rb 右后脚

socket_foot_rf socket_foot_rf 右前脚

socket_foot_rm socket_foot_rm 右中脚

socket_forearm_l socket_forearm_l 左臂

socket_forearm_r socket_forearm_r 右臂

socket_hand_l socket_hand_l 左手

socket_hand_r socket_hand_r 右手

socket_head socket_head 头部

socket_lowerarm_l socket_lowerarm_l 左小臂

socket_lowerarm_r socket_lowerarm_r 右小臂

socket_lowerlimb_lb socket_lowerlimb_lb 左后下肢

socket_lowerlimb_lf socket_lowerlimb_lf 左前下肢

socket_lowerlimb_rb socket_lowerlimb_rb 右后下肢

socket_lowerlimb_rf socket_lowerlimb_rf 右前下肢

socket_mouth socket_mouth 鱼嘴

socket_origin socket_origin 底面中心点

socket_tail socket_tail 尾巴

socket_tail_end socket_tail_end 尾巴末端

socket_thigh_l socket_thigh_l 左大腿

socket_thigh_r socket_thigh_r 右大腿

socket_torso_b socket_torso_b 躯干后部

socket_torso_f socket_torso_f 躯干前部

socket_upperarm_l socket_upperarm_l 左大臂

socket_upperarm_r socket_upperarm_r 右大臂

socket_upperlimb_lb socket_upperlimb_lb 左后上肢

socket_upperlimb_lf socket_upperlimb_lf 左前上肢

socket_upperlimb_rb socket_upperlimb_rb 右后上肢

socket_upperlimb_rf socket_upperlimb_rf 右前上肢

socket_weapon_l socket_weapon_l 左手武器

socket_weapon_r socket_weapon_r 右手武器

ColorPaintAreaType 染色区域

AREA_1 1 染色区域1

AREA_2 2 染色区域2

AREA_3 3 染色区域3

AREA_4 4 染色区域4

LuaAPI

LuaAPI.ability_register_creation_handler

描述: 注册技能创建回调

LuaAPI.ability_register_creation_handler(_ability_key, _callback)

参数列表:

参数	类型	说明
_ability_key	AbilityKey	技能编号
_callback	Function	回调

示例:

-- 注册技能创建回调：技能单位诞生时自动附加处理逻辑
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 150001 为技能预设ID，回调参数为创建出的单位对象
    LuaAPI.ability_register_creation_handler(150001, function(unit)
        if unit then
            -- 技能单位生成后打印日志，确认回调触发
            LuaAPI.log("技能单位已创建", 0)
        end
    end)
end)

LuaAPI.ability_unregister_creation_handler

描述: 注销技能创建回调

LuaAPI.ability_unregister_creation_handler(_ability_key)

参数列表:

参数	类型	说明
_ability_key	AbilityKey	技能编号

示例:

-- 注销技能创建回调：先注册监听，一段时间后停止监听
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 注册技能创建回调
    LuaAPI.ability_register_creation_handler(150001, function(unit)
        if unit then
            LuaAPI.log("技能单位已创建", 0)
        end
    end)

    -- 10 秒后注销该回调，停止后续监听
    LuaAPI.call_delay_time(10.0, function()
        LuaAPI.ability_unregister_creation_handler(150001)
    end)
end)

LuaAPI.call_delay_frame

描述: 延迟调用函数（按帧数）

LuaAPI.call_delay_frame(_interval, _callback)

参数列表:

参数	类型	说明
_interval	Int	间隔帧数
_callback	Function	回调

示例:

-- 延迟 30 帧（约 1 秒）执行，适合帧精确的演出/结算逻辑
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    -- 30 帧后提示玩家，回调内再次判空防御
    LuaAPI.call_delay_frame(30, function()
        if role then
            role.show_tips("30帧后执行完成", 2.0)
        end
    end)
end)

LuaAPI.call_delay_time

描述: 延迟调用函数（按时间）

LuaAPI.call_delay_time(_interval, _callback)

参数列表:

参数	类型	说明
_interval	Fixed	间隔时间（秒）
_callback	Function	回调

示例:

-- 延迟 3 秒执行：倒计时结束后的结算提示
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    -- 3 秒后执行，回调内再次判空防御
    LuaAPI.call_delay_time(3.0, function()
        if role then
            role.show_tips("3秒倒计时结束", 2.0)
        end
    end)
end)

LuaAPI.dispatch_flush

描述: 执行所有已添加并行任务

LuaAPI.dispatch_flush()

示例:

-- 游戏初始化：批量任务加入后统一执行
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 初始化 4 个并行任务槽位
    LuaAPI.dispatch_init(4)

    -- 添加多个并行任务（按线程分发）
    LuaAPI.dispatch_queue(1, "calc_damage", { target = "boss" })
    LuaAPI.dispatch_queue(2, "calc_damage", { target = "soldier" })

    -- 统一执行所有已添加的并行任务
    LuaAPI.dispatch_flush()
end)

LuaAPI.dispatch_init

描述: 初始化并行数

LuaAPI.dispatch_init(_count)

参数列表:

参数	类型	说明
_count	Int	并行数

示例:

-- 游戏初始化：按需初始化并行任务数
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 初始化 4 路并行计算（数值按地图规模调整）
    LuaAPI.dispatch_init(4)

    -- 初始化后可调用 dispatch_queue 添加任务
    LuaAPI.dispatch_queue(1, "batch_process_units", { process_type = "damage_calc" })

    -- 添加完毕后调用 dispatch_flush 统一执行
end)

LuaAPI.dispatch_queue

描述: 添加并行任务

LuaAPI.dispatch_queue(_i, _name, _args)

参数列表:

参数	类型	说明
_i	Int	线程ID
_name	Str	函数名
_args	Dict	参数

返回值:

• 类型: Int
• 说明: 任务ID

示例:

-- 游戏初始化：添加并行计算任务
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 初始化并行任务槽位
    LuaAPI.dispatch_init(4)

    -- 添加任务：线程 1 执行 batch_process_units，参数为技能结算
    local task_id = LuaAPI.dispatch_queue(1, "batch_process_units", {
        process_type = "damage_calc",
    })

    -- task_id 可用于后续任务管理（如需取消或查询）
end)

LuaAPI.enable_developer_mode

描述: 启用开发者模式

LuaAPI.enable_developer_mode()

返回值:

• 类型: Bool
• 说明: 是否启用成功

示例:

-- 游戏初始化：开启开发者模式
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 开启后输出调试信息，便于联调排错
    local ok = LuaAPI.enable_developer_mode()
    if ok then
        -- 开发者模式已生效
    end
end)

LuaAPI.enable_error_interruption_mode

描述: 启用错误中断模式

LuaAPI.enable_error_interruption_mode(_enable)

参数列表:

参数	类型	说明
_enable	Bool	是否启用

示例:

-- 游戏初始化：开启错误中断模式便于调试
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 开启后脚本运行出错会立即中断，并打印错误位置
    LuaAPI.enable_error_interruption_mode(true)

    -- 调试完成后可调用 enable_error_interruption_mode(false) 关闭
    -- 正式上线前建议关闭，避免错误中断影响玩家体验
end)

LuaAPI.get_component_list

描述: 获取子部件列表（慢）

LuaAPI.get_component_list(_obj)

参数列表:

参数	类型	说明
_obj	Unit	单位

返回值:

• 类型: ListStr
• 说明: 组件名称列表

示例:

-- 查询单位子部件列表：查找角色身上的"头部"子部件（接口较慢，避免频繁调用）
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    local character = role.get_ctrl_unit()
    local parts = LuaAPI.get_component_list(character)
    for _, part_name in ipairs(parts) do
        if part_name == "头部" then
            print("找到头部子部件")
            break
        end
    end
end)

LuaAPI.get_current_unit

描述: 获取当前单位

LuaAPI.get_current_unit()

返回值:

• 类型: Unit
• 说明: 当前单位

示例:

-- 获取当前单位：在单位事件回调中拿到触发回调的单位
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    local character = role.get_ctrl_unit()
    -- 单位销毁回调中，用 get_current_unit 拿到被销毁的单位
    LuaAPI.unit_register_trigger_event(character, { EVENT.SPEC_LIFEENTITY_DIE }, function()
        local unit = LuaAPI.get_current_unit()
        if unit then
            print("单位销毁: " .. tostring(unit.get_id()))
        end
    end)
end)

LuaAPI.get_dispatch_count

描述: 获取并行数

LuaAPI.get_dispatch_count()

返回值:

• 类型: Int
• 说明: 并行数

示例:

-- 查询并行数：读取当前逻辑帧的并行任务数，用于调试输出
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 并行数为引擎内部调度信息，通常只用于性能调试
    local count = LuaAPI.get_dispatch_count()
    print("当前并行数: " .. tostring(count))
end)

LuaAPI.get_global_var

描述: 获取全局变量

LuaAPI.get_global_var(_var_name)

参数列表:

参数	类型	说明
_var_name	Str	变量名

返回值:

• 类型: ETypeMeta
• 说明: 变量

示例:

-- 读取全局变量：跨脚本共享"关卡难度"配置
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- "level_difficulty" 需由其他脚本先写入
    local value = LuaAPI.get_global_var("level_difficulty")
    if value == nil then
        -- 全局变量未初始化时使用默认难度
        print("难度未设置，使用默认值")
    else
        print("当前关卡难度: " .. tostring(value))
    end
end)

LuaAPI.get_unit_id

描述: 获得单位的ID

LuaAPI.get_unit_id(_unit)

参数列表:

参数	类型	说明
_unit	Unit	单位

返回值:

• 类型: Int
• 说明: 单位ID

示例:

-- 获取单位 ID：常用于注册触发器空间进出事件
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local area_id = GameAPI.get_unit_id_by_name("选择区域")
    if area_id then
        -- 注册进入该区域的触发器
        LuaAPI.global_register_trigger_event(
            { EVENT.ANY_LIFEENTITY_TRIGGER_SPACE, Enums.TriggerSpaceEventType.ENTER, area_id },
            function(_, _, data)
                local character = data.event_unit
                local role = character and character.get_role()
                if role then
                    role.show_tips("进入选择区域", 2.0)
                end
            end)
    end
end)

LuaAPI.get_value_type

描述: 获取变量类型

LuaAPI.get_value_type(_value)

参数列表:

参数	类型	说明
_value	ETypeMeta	变量

返回值:

• 类型: Str
• 说明: 类型

示例:

-- 查询变量类型：根据全局变量的类型做不同处理
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local value = LuaAPI.get_global_var("player_count")
    if value == nil then return end

    -- 返回类型字符串，如 "int"、"fixed"、"str"、"bool" 等
    local value_type = LuaAPI.get_value_type(value)
    if value_type == "int" then
        print("全局变量为整数类型")
    elseif value_type == "fixed" then
        print("全局变量为定点数类型")
    else
        print("全局变量类型: " .. tostring(value_type))
    end
end)

LuaAPI.global_register_custom_event

描述: 注册全局自定义事件监听

LuaAPI.global_register_custom_event(_event_name, _callback)

参数列表:

参数	类型	说明
_event_name	Str	自定义事件名
_callback	Function	回调

返回值:

• 类型: Int
• 说明: 注册ID

示例:

-- 注册自定义事件：UI 按钮点击等业务分发（配合 global_send_custom_event 使用）
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    LuaAPI.global_register_custom_event("点击购买", function(_, _, data)
        local role = data.role
        if role then
            role.show_tips("点击了购买按钮", 2.0)
        end
    end)
end)

LuaAPI.global_register_trigger_event

描述: 注册全局触发器

LuaAPI.global_register_trigger_event(_event_desc, _callback)

参数列表:

参数	类型	说明
_event_desc	List	事件名及注册参数
_callback	Function	回调

返回值:

• 类型: Int
• 说明: 注册ID

示例:

-- 游戏初始化时注册全局事件：遍历角色，按角色 ID 注册个性化事件
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local all_roles = GameAPI.get_all_valid_roles()
    for _, role in ipairs(all_roles) do
        -- 注册该角色的购买成功事件（事件描述带角色 ID 参数）
        LuaAPI.global_register_trigger_event({ EVENT.SPEC_ROLE_PURCHASE_GOODS, role.get_roleid() }, function(_, _, data)
            role.show_tips("购买成功，商品ID: " .. tostring(data.goods_id), 2.0)
        end)
    end
end)

LuaAPI.global_send_custom_event

描述: 发送全局自定义事件

LuaAPI.global_send_custom_event(_event_name, _data)

参数列表:

参数	类型	说明
_event_name	Str	自定义事件名
_data	Dict	附带参数

示例:

-- 向全局发送自定义事件并携带数据（接收方用 global_register_custom_event 监听）
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    LuaAPI.global_send_custom_event("player_joined", {
        role = role,
        player_name = "蛋仔玩家",
        join_time = GameAPI.get_timestamp()
    })
end)

LuaAPI.global_unregister_custom_event

描述: 注销全局自定义事件监听

LuaAPI.global_unregister_custom_event(_id)

参数列表:

参数	类型	说明
_id	Int	注册ID

示例:

-- 反注册自定义事件（注册返回 ID，用于注销）
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 注册自定义事件
    local event_id = LuaAPI.global_register_custom_event("提示", function(_, _, data)
        local role = data.role
        if role then
            role.show_tips(tostring(data.text), 2.0)
        end
    end)

    -- 30 秒后注销该事件
    LuaAPI.call_delay_time(30.0, function()
        if event_id then
            LuaAPI.global_unregister_custom_event(event_id)
        end
    end)
end)

LuaAPI.global_unregister_trigger_event

描述: 注销全局触发器

LuaAPI.global_unregister_trigger_event(_id)

参数列表:

参数	类型	说明
_id	Int	注册ID

示例:

-- 注册全局事件后按需反注册（事件注册返回 ID，用于反注册）
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 注册周期定时器：每 1 秒执行一次
    local timer_id = LuaAPI.global_register_trigger_event({ EVENT.REPEAT_TIMEOUT, 1.0 }, function()
        -- 每秒刷新的逻辑
    end)

    -- 10 秒后停止该定时器
    LuaAPI.call_delay_time(10.0, function()
        if timer_id then
            LuaAPI.global_unregister_trigger_event(timer_id)
        end
    end)
end)

LuaAPI.has_component

描述: 是否含有指定子部件

LuaAPI.has_component(_object, _name)

参数列表:

参数	类型	说明
_object	Unit	单位
_name	Str	组件名

返回值:

• 类型: Bool
• 说明: 是否含有指定子组件

示例:

-- 游戏初始化：判断角色模型是否挂载指定子部件
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end

    -- 检查是否含有名为"头饰"的子部件（部件名见模型配置）
    if LuaAPI.has_component(unit, "头饰") then
        -- 有头饰：可执行对应的换装逻辑
    end
end)

LuaAPI.log

描述: 输出日志（Lua）

LuaAPI.log(_content, _log_level)

参数列表:

参数	类型	说明
_content	Str	日志内容
_log_level	Int	日志级别

示例:

-- 打印日志（调试用，_log_level 0=普通 1=警告 2=错误）
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if role then
        LuaAPI.log("玩家进入: " .. tostring(role.get_roleid()), 0)
    end
end)

LuaAPI.modifier_register_creation_handler

描述: 注册效果创建回调

LuaAPI.modifier_register_creation_handler(_modifier_key, _callback)

参数列表:

参数	类型	说明
_modifier_key	ModifierKey	效果编号
_callback	Function	回调

示例:

-- 注册效果创建回调：效果（灼烧/冰冻等）挂载时做附加处理
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 600001 为效果预设ID，回调参数为被挂载效果的单位对象
    LuaAPI.modifier_register_creation_handler(600001, function(unit)
        if unit then
            -- 效果挂载后打印日志，确认回调触发
            LuaAPI.log("效果已挂载到单位", 0)
        end
    end)
end)

LuaAPI.modifier_unregister_creation_handler

描述: 注销效果创建回调

LuaAPI.modifier_unregister_creation_handler(_modifier_key)

参数列表:

参数	类型	说明
_modifier_key	ModifierKey	效果编号

示例:

-- 注销效果创建回调：先注册监听，一段时间后停止监听
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 注册效果创建回调
    LuaAPI.modifier_register_creation_handler(600001, function(unit)
        if unit then
            LuaAPI.log("效果已挂载到单位", 0)
        end
    end)

    -- 30 秒后注销该回调
    LuaAPI.call_delay_time(30.0, function()
        LuaAPI.modifier_unregister_creation_handler(600001)
    end)
end)

LuaAPI.query_ui_node

描述: 查询UI单位（慢）

LuaAPI.query_ui_node(_name)

参数列表:

参数	类型	说明
_name	Str	名字

返回值:

• 类型: ENode
• 说明: UI名称

示例:

-- 查询 UI 节点：按名字查找编辑器中摆放的节点（慢，建议缓存复用）
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    -- 按名字查询 UI 节点（名字需与编辑器中的节点名一致）
    local node = LuaAPI.query_ui_node("提示文本")
    if not node then
        role.show_tips("未找到节点", 2.0)
        return
    end

    -- 查询到节点后按需操作（此处演示存在性判断与打印）
    print("找到节点: " .. tostring(node))
end)

LuaAPI.query_ui_nodes

描述: 批量查询UI单位（慢）

LuaAPI.query_ui_nodes(_name_list)

参数列表:

参数	类型	说明
_name_list	ListStr	名字列表

返回值:

• 类型: ListENode
• 说明: UI名称列表

示例:

-- 批量查询 UI 节点：一次查出多个节点，统一处理
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    -- 批量查询（名字列表需与编辑器中的节点名一致）
    local nodes = LuaAPI.query_ui_nodes({ "提示文本", "奖励面板" })
    for _, node in ipairs(nodes) do
        if node then
            -- 节点存在，按需操作（此处演示打印）
            print("找到节点: " .. tostring(node))
        end
    end
end)

LuaAPI.query_unit

描述: 查询组件单位（慢）

LuaAPI.query_unit(_name)

参数列表:

参数	类型	说明
_name	Str	名字

返回值:

• 类型: Unit
• 说明: 组件

示例:

-- 按名字查询场景中的单位（需在 GAME_INIT 后调用）
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local tile = LuaAPI.query_unit("地块1")
    if tile then
        local key = tile.get_key()
        local pos = tile.get_position()
        print("地块 key:", key)
    end
end)

LuaAPI.query_units

描述: 批量查询单位（按名称）

LuaAPI.query_units(_name_list)

参数列表:

参数	类型	说明
_name_list	ListStr	名字列表

返回值:

• 类型: ListUnit
• 说明: 组件列表

示例:

-- 按名称批量查询单位：确认两个 NPC 是否都存在于场景中
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 批量查询 NPC队长 / NPC守卫
    local units = LuaAPI.query_units({ "NPC队长", "NPC守卫" })
    for _, unit in ipairs(units) do
        -- 对每个查询结果判空，避免空引用
        if unit then
            LuaAPI.log("找到目标单位", 0)
        end
    end
end)

LuaAPI.query_units_by_type

描述: 批量查询单位（按类型、预设）

LuaAPI.query_units_by_type(_unit_type, _unit_eid)

参数列表:

参数	类型	说明
_unit_type	UnitType	单位类型
_unit_eid	Int	预设ID

返回值:

• 类型: ListUnit
• 说明: 组件

示例:

-- 按类型+预设ID批量查询单位：查询场景中所有 100001 角色类单位
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- Enums.UnitType.CHARACTER 角色类型，100001 为预设ID
    local units = LuaAPI.query_units_by_type(Enums.UnitType.CHARACTER, 100001)
    for _, unit in ipairs(units) do
        -- 逐个判空后打印，确认查询结果
        if unit then
            LuaAPI.log("查询到角色单位", 0)
        end
    end
end)

LuaAPI.rand

描述: 生成随机数

LuaAPI.rand()

返回值:

• 类型: Int
• 说明: 随机数

示例:

-- 生成 [0,1) 随机数，用于随机延迟/随机偏移（联机自动同步随机种子）
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    -- 用随机数计算 0~2 秒的随机延迟，错峰执行
    local delay = LuaAPI.rand() * 2.0
    LuaAPI.call_delay_time(delay, function()
        if role then
            role.show_tips("随机延迟后触发", 1.0)
        end
    end)
end)

LuaAPI.set_deadloop_check_enabled

描述: 启用死循环检测

LuaAPI.set_deadloop_check_enabled(_enable, _max_instruction_count)

参数列表:

参数	类型	说明
_enable	Bool	启用
_max_instruction_count	Int	最大指令数限制

返回值:

• 类型: Bool
• 说明: 是否启用成功

示例:

-- 游戏初始化：开启死循环检测
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 开启死循环检测，单帧最大执行 100000 条指令
    local ok = LuaAPI.set_deadloop_check_enabled(true, 100000)
    if ok then
        -- 检测已生效：死循环会被强制中断并报错
    end
end)

LuaAPI.set_tick_handler

描述: 设置帧前帧后回调

LuaAPI.set_tick_handler(_pre_handler, _post_handler)

参数列表:

参数	类型	说明
_pre_handler	Function	帧前回调
_post_handler	Function	帧后回调

示例:

-- 游戏初始化时设置帧回调：每帧前执行更新逻辑（官方模板图写法）
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local function on_pre_tick()
        -- 每帧更新逻辑（移动、计时、AI 等）
        -- 示例：打印角色数量，实际项目中在此编写业务逻辑
        print("tick roles: " .. tostring(#GameAPI.get_all_valid_roles()))
    end

    -- 帧前回调 + 帧后回调（无需求可传 nil）
    LuaAPI.set_tick_handler(on_pre_tick, nil)
end)

LuaAPI.unit_register_creation_handler

描述: 注册单位创建回调

LuaAPI.unit_register_creation_handler(_unit_type, _unit_eid, _callback)

参数列表:

参数	类型	说明
_unit_type	UnitType	单位类型
_unit_eid	Int	预设ID
_callback	Function	回调

示例:

-- 注册单位创建回调：监听指定类型/预置的单位被创建
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 监听障碍物类、指定预置 key 的单位创建
    LuaAPI.unit_register_creation_handler(Enums.UnitType.OBSTACLE, 100001, function(unit)
        local unit_id = LuaAPI.get_unit_id(unit)
        LuaAPI.log("新单位创建: " .. tostring(unit_id), 0)
    end)
end)

LuaAPI.unit_register_custom_event

描述: 注册单位自定义事件监听

LuaAPI.unit_register_custom_event(_unit, _event_name, _callback)

参数列表:

参数	类型	说明
_unit	Unit	单位
_event_name	Str	自定义事件名
_callback	Function	回调

返回值:

• 类型: Int
• 说明: 注册ID

示例:

-- 注册单位自定义事件：监听发送给该单位的事件（配合 unit_send_custom_event）
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    -- 监听角色单位收到的"获得道具"事件
    LuaAPI.unit_register_custom_event(role.get_ctrl_unit(), "获得道具", function()
        -- 延迟 5 帧后刷新背包
        LuaAPI.call_delay_frame(5, function()
            role.show_tips("获得新道具", 2.0)
        end)
    end)
end)

LuaAPI.unit_register_trigger_event

描述: 注册单位触发器

LuaAPI.unit_register_trigger_event(_unit, _event_desc, _callback)

参数列表:

参数	类型	说明
_unit	Unit	单位
_event_desc	List	事件名及注册参数
_callback	Function	回调

返回值:

• 类型: Int
• 说明: 触发器ID

示例:

-- 监听角色举起物体事件：物体变半透明并关闭物理
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    local character = role.get_ctrl_unit()
    LuaAPI.unit_register_trigger_event(character, { EVENT.SPEC_LIFEENTITY_LIFT_BEGAN }, function(_, _, data)
        local lifted = data.lifted_unit
        if lifted then
            lifted.set_physics_active(false)
        end
    end)
end)

LuaAPI.unit_send_custom_event

描述: 发送单位自定义事件

LuaAPI.unit_send_custom_event(_unit, _event_name, _data)

参数列表:

参数	类型	说明
_unit	Unit	单位
_event_name	Str	自定义事件名
_data	Dict	附带参数

示例:

-- 向指定单位发送自定义事件（接收方用 unit_register_custom_event 监听）
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    -- 通知该角色的角色单位购买道具
    LuaAPI.unit_send_custom_event(role.get_ctrl_unit(), "购买道具", {
        role = role,
        price = 100,
    })
end)

LuaAPI.unit_unregister_creation_handler

描述: 注销单位创建回调

LuaAPI.unit_unregister_creation_handler(_unit_type, _unit_eid)

参数列表:

参数	类型	说明
_unit_type	UnitType	单位类型
_unit_eid	Int	预设ID

示例:

-- 注销单位创建回调：先注册监听，再解除防止重复处理
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 注册 100001 角色的创建回调
    LuaAPI.register_unit_creation_handler(Enums.UnitType.CHARACTER, 100001, function(unit)
        if unit then
            LuaAPI.log("单位创建回调触发", 0)
        end
    end)

    -- 立即注销，示例中不再需要监听该类型单位
    LuaAPI.unit_unregister_creation_handler(Enums.UnitType.CHARACTER, 100001)
end)

LuaAPI.unit_unregister_custom_event

描述: 注销单位自定义事件监听

LuaAPI.unit_unregister_custom_event(_unit, _id)

参数列表:

参数	类型	说明
_unit	Unit	单位
_id	Int	注册ID

示例:

-- 注销单位自定义事件监听：先注册再注销，形成完整生命周期
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    -- 注册自定义事件监听（事件名需与发送方一致），保存注册 ID
    local reg_id = LuaAPI.unit_register_custom_event(role.get_ctrl_unit(), "custom_event_1", function(event_name, actor, data)
        if role then
            role.show_tips("收到自定义事件", 1.0)
        end
    end)

    -- 注销该监听（注销参数为注册 ID），后续不再接收该事件
    LuaAPI.unit_unregister_custom_event(role.get_ctrl_unit(), reg_id)
end)

LuaAPI.unit_unregister_trigger_event

描述: 注销单位触发器

LuaAPI.unit_unregister_trigger_event(_unit, _id)

参数列表:

参数	类型	说明
_unit	Unit	单位
_id	Int	注册ID

示例:

-- 注册单位事件后按需反注册（清理时避免事件泄漏）
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    local character = role.get_ctrl_unit()
    -- 注册举起事件，返回事件 ID
    local lift_id = LuaAPI.unit_register_trigger_event(character, { EVENT.SPEC_LIFEENTITY_LIFT_BEGAN }, function(_, _, data)
        -- 举起处理
    end)

    -- 5 秒后停止监听
    LuaAPI.call_delay_time(5.0, function()
        if lift_id then
            LuaAPI.unit_unregister_trigger_event(character, lift_id)
        end
    end)
end)

GlobalAPI

GlobalAPI.add_kill_broadcast

描述: 添加击杀播报

GlobalAPI.add_kill_broadcast(_kill_char, _dead_char, _duration)

参数列表:

参数	类型	说明
_kill_char	Character	击杀角色
_dead_char	Character	死亡角色
_duration	Fixed	持续时间

示例:

-- 添加击杀播报：角色击败 NPC 后展示击杀信息
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    -- 角色控制的单位（Character 类型）
    local character = role.get_ctrl_unit()
    -- NPC 角色单位（Character 类型，名称在场景中配置）
    local npc = LuaAPI.query_unit("NPC队长")
    if character and npc then
        -- 击杀播报持续展示 3 秒
        GlobalAPI.add_kill_broadcast(character, npc, 3.0)
    end
end)

GlobalAPI.set_render_color

描述: 改变色彩滤镜

GlobalAPI.set_render_color(_hue, _brightness, _saturation, _contrast, _amount, _mid_tones, _mid_tones_power, _shadows, _shadows_power, _highlight, _highlight_power, _duration)

参数列表:

参数	类型	说明
_hue	Fixed	色相
_brightness	Fixed	明度
_saturation	Fixed	饱和度
_contrast	Fixed	对比度
_amount	Fixed	整体偏色程度
_mid_tones	Color	中灰偏色
_mid_tones_power	Fixed	中灰偏色程度
_shadows	Color	暗部偏色
_shadows_power	Fixed	暗部偏色程度
_highlight	Color	亮部偏色
_highlight_power	Fixed	亮部偏色程度
_duration	Fixed	变换时长

示例:

-- 改变色彩滤镜：叠加红色色调营造受击氛围
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 定义中间调/阴影/高光的色调颜色（RGBA）
    local red = GlobalAPI.str_to_color("ff0000")
    -- 1 秒内过渡到目标滤镜（hue/brightness/saturation/contrast/amount）
    GlobalAPI.set_render_color(0.0, 1.0, 1.0, 1.0, 1.0, red, 1.0, red, 1.0, red, 1.0, 1.0)
end)

GlobalAPI.debug

描述: Debug窗口打印日志

GlobalAPI.debug(_content)

参数列表:

参数	类型	说明
_content	Str	内容

示例:

-- Debug 窗口打印日志：调试阶段输出关键信息
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local roles = GameAPI.get_all_valid_roles()
    for _, role in ipairs(roles) do
        if not GlobalAPI.is_none(role) then
            -- 输出每个角色初始化完成的调试日志
            GlobalAPI.debug("角色 " .. tostring(role.get_roleid()) .. " 初始化完成")
        end
    end
end)

GlobalAPI.destroy_sfx

描述: 销毁特效

GlobalAPI.destroy_sfx(_sfx_id, _fade_out)

参数列表:

参数	类型	说明
_sfx_id	SfxID	特效ID
_fade_out	Bool	是否淡出

示例:

-- 销毁特效（切换外观/装备时清理旧特效，带淡出）
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    local sfx_id = GameAPI.play_sfx_by_key(700001, role.get_ctrl_unit().get_position(), math.Quaternion(0, 0, 0, 1), 1.0, -1.0, 1.0, true)
    -- 5 秒后淡出销毁
    LuaAPI.call_delay_time(5.0, function()
        if sfx_id then
            GlobalAPI.destroy_sfx(sfx_id, true)
        end
    end)
end)

GlobalAPI.error

描述: Debug窗口打印错误日志

GlobalAPI.error(_content)

参数列表:

参数	类型	说明
_content	Str	内容

示例:

-- Debug 窗口打印错误日志：用于异常分支提示
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 查找场景中的目标单位（名称需在场景中配置）
    local target = LuaAPI.query_unit("目标怪")
    if not target then
        -- 找不到目标时输出错误日志并中止后续逻辑
        GlobalAPI.error("未找到名为 目标怪 的单位，请检查场景命名")
        return
    end
    GlobalAPI.debug("找到目标单位")
end)

GlobalAPI.get_point_to_line_perpendicular_point

描述: 获取点到直线的垂线交点

GlobalAPI.get_point_to_line_perpendicular_point(_point_1, _point_2, _point_3)

参数列表:

参数	类型	说明
_point_1	Vector3	点1
_point_2	Vector3	点2
_point_3	Vector3	点3

返回值:

• 类型: Vector3
• 说明: 交点坐标

示例:

-- 计算点到直线的垂足（用于求角色到路径的最短距离）
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 直线由 point_1、point_2 两点确定，point_3 为直线外一点
    local point_1 = math.Vector3(0, 0, 0)
    local point_2 = math.Vector3(10, 0, 0)
    local point_3 = math.Vector3(5, 0, 5)
    local foot = GlobalAPI.get_point_to_line_perpendicular_point(point_1, point_2, point_3)
    if foot then
        GlobalAPI.debug("垂足坐标：" .. tostring(foot.x) .. ", " .. tostring(foot.z))
    else
        GlobalAPI.warning("垂足计算失败")
    end
end)

GlobalAPI.get_lines_intersection_point_on_plane

描述: 获取两条直线在指定平面的交点

GlobalAPI.get_lines_intersection_point_on_plane(_point_1, _point_2, _point_3, _point_4, _value, _plane_type)

参数列表:

参数	类型	说明
_point_1	Vector3	点1
_point_2	Vector3	点2
_point_3	Vector3	点3
_point_4	Vector3	点4
_value	Fixed	校正值
_plane_type	PlaneType	平面

返回值:

• 类型: Vector3
• 说明: 交点坐标

示例:

-- 计算两条直线在 XZ 平面上的交点（用于弹道/路径预判）
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 直线 1 由 A、B 两点确定，直线 2 由 C、D 两点确定
    local point_a = math.Vector3(0, 0, 0)
    local point_b = math.Vector3(10, 0, 10)
    local point_c = math.Vector3(0, 0, 10)
    local point_d = math.Vector3(10, 0, 0)
    -- 在 XZ 平面求交点，1.0 为计算容差参数
    local cross = GlobalAPI.get_lines_intersection_point_on_plane(point_a, point_b, point_c, point_d, 1.0, Enums.PlaneType.XZ_PLANE)
    if cross then
        GlobalAPI.debug("交点坐标：" .. tostring(cross.x) .. ", " .. tostring(cross.z))
    else
        GlobalAPI.debug("两直线在 XZ 平面无交点")
    end
end)

GlobalAPI.get_vector_projection

描述: 获取向量投影

GlobalAPI.get_vector_projection(_vec, _direction)

参数列表:

参数	类型	说明
_vec	Vector3	向量
_direction	Vector3	投影方向

返回值:

• 类型: Vector3
• 说明: 投影后向量

示例:

-- 计算向量在指定方向上的投影（用于移动分量拆分）
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 原向量与目标方向（均按单位向量使用）
    local vec = math.Vector3(3, 4, 0)
    local direction = math.Vector3(1, 0, 0)
    local proj = GlobalAPI.get_vector_projection(vec, direction)
    if proj then
        GlobalAPI.debug("投影向量：" .. tostring(proj.x) .. ", " .. tostring(proj.y))
    else
        GlobalAPI.warning("投影计算失败")
    end
end)

GlobalAPI.str_contains

描述: 是否含有子字符串

GlobalAPI.str_contains(_str1, _str2)

参数列表:

参数	类型	说明
_str1	Str	父字符串
_str2	Str	子字符串

返回值:

• 类型: Bool
• 说明: 布尔值

示例:

-- 字符串包含判断：常用于名称/标签匹配
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local name = "怪物_精英"
    if GlobalAPI.str_contains(name, "精英") then
        LuaAPI.log("检测到精英怪", 0)
    end
end)

GlobalAPI.is_none

描述: 判断对象是否为空

GlobalAPI.is_none(_obj)

参数列表:

参数	类型	说明
_obj	Unit	对象

返回值:

• 类型: Bool
• 说明: 是否为空

示例:

-- 判断单位对象是否为空（单位销毁后引用会失效）
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    -- 单位失效时走降级分支
    if GlobalAPI.is_none(unit) then
        GlobalAPI.debug("角色控制单位已失效")
    else
        GlobalAPI.debug("角色控制单位有效")
    end
end)

GlobalAPI.is_not_none

描述: 判断对象是否为空

GlobalAPI.is_not_none(_obj)

参数列表:

参数	类型	说明
_obj	Unit	对象

返回值:

• 类型: Bool
• 说明: 是否不为空

示例:

-- 判断单位对象是否有效（取反语义，便于正向分支）
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    -- 单位有效时才执行后续交互逻辑
    if GlobalAPI.is_not_none(unit) then
        GlobalAPI.debug("单位存在，可进行交互")
    end
end)

GlobalAPI.mute_sfx_sound

描述: 去除特效的音效

GlobalAPI.mute_sfx_sound(_sfx_id)

参数列表:

参数	类型	说明
_sfx_id	SfxID	特效ID

示例:

-- 去除特效音效：播放特效后静音（只保留画面表现）
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 播放特效并拿到特效 id（700001 为特效 key）
    local sfx_id = GameAPI.play_sfx_by_key(700001, math.Vector3(0, 0, 0), math.Quaternion(0, 0, 0), 1.0, 3.0, 1.0, true)
    if sfx_id then
        -- 去掉该特效自带的音效，避免与场景音效叠加
        GlobalAPI.mute_sfx_sound(sfx_id)
    end
end)

GlobalAPI.set_sfx_orientation

描述: 设置特效旋转

GlobalAPI.set_sfx_orientation(_sfx_id, _orientation)

参数列表:

参数	类型	说明
_sfx_id	SfxID	特效ID
_orientation	Quaternion	旋转

示例:

-- 设置特效旋转：让特效朝向指定方向
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local pos = role.get_ctrl_unit().get_position()
    -- 在角色位置播放特效并拿到特效 id
    local sfx_id = GameAPI.play_sfx_by_key(700001, pos, math.Quaternion(0, 0, 0), 1.0, 3.0, 1.0, true)
    if sfx_id then
        -- 绕 Y 轴旋转 90 度（弧度制：pi / 2）
        GlobalAPI.set_sfx_orientation(sfx_id, math.Quaternion(0, 1.5707963, 0))
    end
end)

GlobalAPI.set_sfx_position

描述: 设置特效坐标

GlobalAPI.set_sfx_position(_sfx_id, _pos)

参数列表:

参数	类型	说明
_sfx_id	SfxID	特效ID
_pos	Vector3	位置

示例:

-- 设置特效坐标：把特效移动到角色头顶上方
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local pos = role.get_ctrl_unit().get_position()
    -- 在角色位置播放特效并拿到特效 id
    local sfx_id = GameAPI.play_sfx_by_key(700001, pos, math.Quaternion(0, 0, 0), 1.0, 3.0, 1.0, true)
    if sfx_id then
        -- 将特效移到角色位置上方 3 米处
        GlobalAPI.set_sfx_position(sfx_id, math.Vector3(pos.x, pos.y + 3.0, pos.z))
    end
end)

GlobalAPI.set_sfx_rate

描述: 设置特效播放速率

GlobalAPI.set_sfx_rate(_sfx_id, _rate)

参数列表:

参数	类型	说明
_sfx_id	SfxID	特效ID
_rate	Fixed	播放速率

示例:

-- 设置特效播放速率：慢速播放营造慢动作效果
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 在世界原点播放特效并拿到特效 id
    local sfx_id = GameAPI.play_sfx_by_key(700001, math.Vector3(0, 0, 0), math.Quaternion(0, 0, 0), 1.0, 3.0, 1.0, true)
    if sfx_id then
        -- 以 0.5 倍速慢速播放特效
        GlobalAPI.set_sfx_rate(sfx_id, 0.5)
    end
end)

GlobalAPI.set_sfx_scale

描述: 设置特效缩放

GlobalAPI.set_sfx_scale(_sfx_id, _scale)

参数列表:

参数	类型	说明
_sfx_id	SfxID	特效ID
_scale	Vector3	缩放

示例:

-- 设置特效缩放（放大/缩小已播放的特效实例）
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    local sfx_id = GameAPI.play_sfx_by_key(700001, role.get_ctrl_unit().get_position(), math.Quaternion(0, 0, 0, 1), 1.0, -1.0, 1.0, true)
    if sfx_id then
        GlobalAPI.set_sfx_scale(sfx_id, math.Vector3(0.3, 5, 0.3))
    end
end)

GlobalAPI.set_sfx_visible

描述: 设置特效是否可见

GlobalAPI.set_sfx_visible(_sfx_id, _visible)

参数列表:

参数	类型	说明
_sfx_id	SfxID	特效ID
_visible	Bool	是否可见

示例:

-- 控制特效显隐（隐藏/显示某个实例特效）
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    local sfx_id = GameAPI.play_sfx_by_key(700001, role.get_ctrl_unit().get_position(), math.Quaternion(0, 0, 0, 1), 1.0, -1.0, 1.0, true)
    -- 2 秒后隐藏特效
    LuaAPI.call_delay_time(2.0, function()
        if sfx_id then
            GlobalAPI.set_sfx_visible(sfx_id, false)
        end
    end)
end)

GlobalAPI.show_message_marquee

描述: 跑马灯信息

GlobalAPI.show_message_marquee(_content)

参数列表:

参数	类型	说明
_content	Str	字符串

示例:

-- 跑马灯信息：全屏滚动公告类消息
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 游戏开局广播一条跑马灯公告（所有玩家可见）
    GlobalAPI.show_message_marquee("欢迎来到本张地图！")
end)

GlobalAPI.warning

描述: Debug窗口打印警告日志

GlobalAPI.warning(_content)

参数列表:

参数	类型	说明
_content	Str	内容

示例:

-- Debug 窗口打印警告日志：非致命但需关注的分支
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 查找场景中的 BOSS 单位（名称需在场景中配置）
    local target = LuaAPI.query_unit("BOSS")
    if not target then
        -- 缺少 BOSS 单位时输出警告，提示玩法不会触发
        GlobalAPI.warning("未找到 BOSS 单位，BOSS 玩法不会触发")
    else
        GlobalAPI.debug("BOSS 单位已就位")
    end
end)

GlobalAPI.set_direct_light

描述: 修改直接光参数

GlobalAPI.set_direct_light(_param_dict, _duration)

参数列表:

参数	类型	说明
_param_dict	Dict	切换参数
_duration	Fixed	持续时间

示例:

-- 修改直接光参数：模拟黄昏光照效果
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 2 秒内将直接光过渡到黄昏参数（含环境光与 Bloom 配置）
    -- 注意：颜色为有序数组 {R, G, B}（0-255），不支持 r/g/b 键值表
    GlobalAPI.set_direct_light({
        intensity = 2.0,                        -- 光照强度
        color = {255, 200, 120},                -- 光照颜色 RGB
        pitch = 30.0,                           -- 俯仰角（太阳高度角）
        yaw = 200.0,                            -- 偏航角（太阳方向角）
        -- 环境光参数
        env_light_intensity = 0.6,              -- 环境光强度
        env_light_color = {200, 180, 160},      -- 环境光颜色 RGB
        -- Bloom 效果参数
        skylight_bloom_cube = 1,                -- Bloom 立方体
        skylight_bloom_exposure_scale = 1.0,    -- 曝光缩放
        skylight_bloom_threshold = 0.8,         -- Bloom 阈值
        skylight_bloom_intensity = 0.5,         -- Bloom 强度
        skylight_bloom_width = 0.3              -- Bloom 宽度
    }, 2.0)
end)

GlobalAPI.set_skybox_texture

描述: 改变天空盒贴图

GlobalAPI.set_skybox_texture(_texture_key, _change_type, _duration)

参数列表:

参数	类型	说明
_texture_key	SkyBoxBackground	天空盒背景
_change_type	SkyBoxGradualType	切换方式
_duration	Fixed	持续时间

示例:

-- 切换天空盒贴图（天气系统：白天/夜晚/雨雪切换）
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 渐变切换天空盒（GRADUAL_CHANGE 渐变，3 秒过渡）
    GlobalAPI.set_skybox_texture(100001, Enums.SkyBoxGradualType.GRADUAL_CHANGE, 3.0)
end)

GlobalAPI.set_skyfog

描述: 改变天空雾效

GlobalAPI.set_skyfog(_param_dict, _duration)

参数列表:

参数	类型	说明
_param_dict	Dict	切换参数
_duration	Fixed	变换时长

示例:

-- 设置天空雾效（天气系统：夜晚降雾/白天散雾）
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local fog_param = {
        atmosphericfog_color = 0x979797,      -- 大气雾颜色(0xRRGGBB)
        atmosphericfog_intensity = 2.0,       -- 大气雾浓度
    }
    GlobalAPI.set_skyfog(fog_param, 3.0)
end)

GlobalAPI.show_tips

描述: 游戏内飘字信息

GlobalAPI.show_tips(_content, _duration)

参数列表:

参数	类型	说明
_content	Str	字符串
_duration	Fixed	时长

示例:

-- 游戏内飘字信息：向所有玩家展示提示
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 飘字提示持续 2 秒（所有玩家可见）
    GlobalAPI.show_tips("欢迎进入游戏！", 2.0)
end)

GameAPI

GameAPI.add_pathpoint

描述: 为游戏全局添加路点（路径）

GameAPI.add_pathpoint(_path_id, _index, _point_id)

参数列表:

参数	类型	说明
_path_id	PathID	路径
_index	Int	路点索引
_point_id	PathPointID	路点

示例:

-- 游戏初始化：为 NPC 巡逻路径动态补充路点
-- 注意：10001/20001 为示意路径与路点编号，需替换为地图中实际配置的路径数据
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 路径与路点编号均来自策划配置表
    local path_id = 10001   -- 巡逻路径
    local point_id = 20001  -- 新增路点

    -- 把路点挂到路径的第 1 个索引处（索引从 1 开始）
    GameAPI.add_pathpoint(path_id, 1, point_id)

    -- 后续可用 get_pathpoint_by_index 读取该路点用于寻路
end)

GameAPI.apply_editable_image_to_unit

描述: 将可编辑图片应用为单位模型贴图

apply_editable_image_to_unit(_unit: Unit, _image_key: ImageKey) -> void

参数列表:

参数	类型	说明
_unit	Unit	Unit
_image_key	ImageKey	ImageKey

示例:

-- 把可编辑图片应用到角色模型上作为贴图（如换装贴图）
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local character = role.get_ctrl_unit()
    if not character then return end

    -- 创建 512x512 可编辑图片，并应用为角色模型贴图
    local image = GameAPI.create_editable_image(512.0, 512.0)
    if image then
        GameAPI.apply_editable_image_to_unit(character, image)
    end
end)

GameAPI.blit_editable_image

描述: 将可编辑图片内容拷贝到另一张可编辑图片

blit_editable_image(_src_image_key: ImageKey, _dst_image_key: ImageKey) -> void

参数列表:

参数	类型	说明
_src_image_key	ImageKey	ImageKey
_dst_image_key	ImageKey	ImageKey

示例:

-- 将源图片内容整体拷贝到目标图片（如复制贴图到公告板）
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 创建源图 512x512 与目标图 256x256
    local src = GameAPI.create_editable_image(512.0, 512.0)
    local dst = GameAPI.create_editable_image(256.0, 256.0)
    if src and dst then
        GameAPI.blit_editable_image(src, dst)
    end
end)

GameAPI.clear_editable_image

描述: 清空可编辑图片(填充透明)

clear_editable_image(_image_key: ImageKey) -> void

参数列表:

参数	类型	说明
_image_key	ImageKey	ImageKey

示例:

-- 清空可编辑图片（填充透明），用于重置画板内容
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 创建画板后立刻清空，作为全新画布使用
    local image = GameAPI.create_editable_image(512.0, 512.0)
    if image then
        GameAPI.clear_editable_image(image)
    end
end)

GameAPI.create_editable_image

描述: 创建可编辑图片

create_editable_image(_width: Fixed, _height: Fixed) -> ImageKey

参数列表:

参数	类型	说明
_width	Fixed	Fixed
_height	Fixed	Fixed

返回值:

• 类型: ImageKey

示例:

-- 创建一张可编辑图片，后续可填充颜色或进行笔刷绘制
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 创建 512x512 画布
    local image = GameAPI.create_editable_image(512.0, 512.0)
    if image then
        -- 用纯色填充示意画布可用
        GameAPI.fill_editable_image(image, GlobalAPI.str_to_color("ff0000"))
    end
end)

GameAPI.create_fixed_joint

描述: 创建硬连接关节

create_fixed_joint(_unit1: Unit, _unit2: Unit) -> void

参数列表:

参数	类型	说明
_unit1	Unit	Unit
_unit2	Unit	Unit

示例:

-- 把两个场景单位用硬连接关节焊死（如箱子和平台连成一体）
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local unit_a = LuaAPI.query_unit("木箱A")
    local unit_b = LuaAPI.query_unit("木箱B")
    if not unit_a or not unit_b then return end

    -- 创建硬连接关节，两者相对位置固定
    GameAPI.create_fixed_joint(unit_a, unit_b)
end)

GameAPI.deal_damage

描述: 造成伤害

GameAPI.deal_damage(_dst, _dmg, _src, _schema, _data)

参数列表:

参数	类型	说明
_dst	LifeEntity	目标单位
_dmg	Fixed	伤害
_src	Unit	伤害来源
_schema	DamageSchema	伤害类型
_data	Dict	参数

示例:

-- 范围伤害闭环：对角色周围 5 米内的"怪物"标签生物造成伤害
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local character = role.get_ctrl_unit()
    if not character then return end

    -- 查询周围生物，命中后造成 200 点伤害
    local targets = GameAPI.get_creatures_in_sphere(role.get_ctrl_unit().get_position(), 5.0)
    for _, target in ipairs(targets) do
        if target.has_tag("怪物") then
            GameAPI.deal_damage(target, 200.0, character, 1, {
                show_damage_tips = true,   -- 飘伤害数字
                damage_tag = "fire",       -- 伤害标签，可配合受击事件
            })
        end
    end
end)

GameAPI.destroy_editable_image

描述: 销毁可编辑图片

destroy_editable_image(_image_key: ImageKey) -> void

参数列表:

参数	类型	说明
_image_key	ImageKey	ImageKey

示例:

-- 销毁不再使用的可编辑图片，及时释放贴图资源
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 创建后立即销毁，演示资源释放流程
    local image = GameAPI.create_editable_image(256.0, 256.0)
    if image then
        GameAPI.destroy_editable_image(image)
    end
end)

GameAPI.destroy_eui_node

描述: 销毁界面节点

destroy_eui_node(_node: ENode) -> void

参数列表:

参数	类型	说明
_node	ENode	ENode

示例:

-- 销毁界面节点：动态创建的节点用完后回收
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    -- 创建场景 UI 图层与一个文本节点
    local layer = GameAPI.create_scene_ui_at_point(120001, role.get_ctrl_unit().get_position(), -1.0)
    if not layer then return end
    local label = GameAPI.create_eui_label_at_position(180001, layer, 0.0, 0.0, 200.0, 40.0, "label_临时", "临时提示")
    if not label then return end

    -- 2 秒后销毁该节点，仅保留图层
    LuaAPI.call_delay_time(2.0, function()
        if label then
            GameAPI.destroy_eui_node(label)
            label = nil
        end
    end)
end)

GameAPI.destroy_unit_with_children

描述: 销毁单位，可选是否销毁子组件

GameAPI.destroy_unit_with_children(_unit, _destroy_children)

参数列表:

参数	类型	说明
_unit	Unit	单位
_destroy_children	Bool	是否销毁子组件

示例:

-- 销毁单位及其子单位（生成物批量清理）
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local monster = LuaAPI.query_unit("怪物")
    if monster then
        GameAPI.destroy_unit_with_children(monster, true)
    end
end)

GameAPI.clear_sheet

描述: 清空表

GameAPI.clear_sheet(_sheet_id)

参数列表:

参数	类型	说明
_sheet_id	SheetID	表格

示例:

-- 游戏初始化：清空临时表，开始新一轮数据统计
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 创建表格并添加一列
    local sheet = GameAPI.create_sheet()
    if not sheet then return end
    GameAPI.add_sheet_column(sheet, "key_001", "Int")

    -- 清空表中所有数据（列结构保留，可继续写入）
    GameAPI.clear_sheet(sheet)

    -- 清空后可重新写入新一轮数据
end)

GameAPI.add_sheet_column

描述: 表添加列

GameAPI.add_sheet_column(_sheet_id, _key, _type_name)

参数列表:

参数	类型	说明
_sheet_id	SheetID	表格
_key	Str	列名
_type_name	Str	类型

示例:

-- 游戏初始化：创建多维表并添加"血量"列
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 创建一张临时表，用于运行时数据记录
    local sheet = GameAPI.create_sheet()
    if not sheet then return end

    -- 添加列：列名为 key_001，类型为 Int（整数）
    GameAPI.add_sheet_column(sheet, "key_001", "Int")

    -- 添加列后可用 set_sheet_cell_value 写入数据
end)

GameAPI.copy_sheet

描述: 复制表

GameAPI.copy_sheet(_sheet_id)

参数列表:

参数	类型	说明
_sheet_id	SheetID	表格

返回值:

• 类型: SheetID
• 说明: 表格

示例:

-- 游戏初始化：复制表格用于存档快照
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 创建一张运行时数据表
    local sheet = GameAPI.create_sheet()
    if not sheet then return end

    -- 复制表：返回新的 SheetID，与原表互不影响
    local snapshot = GameAPI.copy_sheet(sheet)
    if snapshot then
        -- 快照表与原表数据一致，可用于数据对比/备份
    end
end)

GameAPI.copy_vehicle

描述: 复制载具

GameAPI.copy_vehicle(_vehicle, _pos, _direction, _role)

参数列表:

参数	类型	说明
_vehicle	Vehicle	载具
_pos	Point3	位置
_direction	Point3	朝向
_role	Role	所属玩家

返回值:

• 类型: Vehicle
• 说明: 创建出的载具

示例:

-- 复制载具：在角色面前生成一辆与原型完全相同的新载具
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    -- 先创建一辆原型载具（500001 为载具预设ID）
    local vehicle = GameAPI.create_vehicle(500001, role.get_ctrl_unit().get_position(), math.Vector3(0, 0, 1), role)
    if not vehicle then return end

    -- 在原型前方 3 米处复制一辆，方向保持一致
    local clone = GameAPI.copy_vehicle(vehicle, role.get_ctrl_unit().get_position() + math.Vector3(0, 0, 3), math.Vector3(0, 0, 1), role)
    if clone then
        role.show_tips("载具复制成功", 2.0)
    end
end)

GameAPI.create_sheet

描述: 创建表

GameAPI.create_sheet()

返回值:

• 类型: SheetID
• 说明: 表格

示例:

-- 游戏初始化：创建运行时数据表
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 创建一张空表，返回表格编号（SheetID）
    local sheet = GameAPI.create_sheet()
    if not sheet then return end

    -- 添加列后即可使用 set/get_sheet_cell_value 读写
    GameAPI.add_sheet_column(sheet, "key_001", "Int")
end)

GameAPI.create_constant_wind_field

描述: 创建一个固定风场单位

GameAPI.create_constant_wind_field(_pos, _wind_type, _wind_range, _duration)

参数列表:

参数	类型	说明
_pos	Point3	位置
_wind_type	WindFieldShapeType	形状
_wind_range	Fixed	范围
_duration	Fixed	持续时间

示例:

-- 游戏初始化：在角色脚下生成一个固定风场
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    -- 以角色所在位置为中心，创建长方体风场
    GameAPI.create_constant_wind_field(
        role.get_ctrl_unit().get_position(),                   -- 风场中心位置
        Enums.WindFieldShapeType.CONICAL,      -- 风场形状（锥形）
        5.0,                                   -- 风场范围
        10.0                                   -- 持续时间（秒），结束后自动消失
    )
end)

GameAPI.create_creature_fixed_scale

描述: 创建一个生物

GameAPI.create_creature_fixed_scale(_u_key, _pos, _rotation, _scale_ratio, _role)

参数列表:

参数	类型	说明
_u_key	UnitKey	单位编号
_pos	Point3	位置
_rotation	Quaternion	旋转
_scale_ratio	Fixed	缩放大小
_role	Role	所属玩家

返回值:

• 类型: Creature
• 说明: 创建出的生物

示例:

-- 创建生物（固定缩放比例创建，如放大 1.5 倍）
-- 注意：100001 为示意预设 key，需替换为地图中实际配置的生物预设 ID
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    local creature = GameAPI.create_creature_fixed_scale(
        100001,                          -- 生物预置 key
        role.get_ctrl_unit().get_position(),             -- 位置
        math.Quaternion(0, 0, 0),        -- 旋转
        1.5,                             -- 缩放比例
        role                             -- 所属角色
    )
    if creature then
        creature.set_physics_active(true)
    end
end)

GameAPI.create_customtriggerspace

描述: 创建一个触发区域

GameAPI.create_customtriggerspace(_u_key, _pos, _rotation, _scale, _role)

参数列表:

参数	类型	说明
_u_key	CustomTriggerSpaceKey	触发区域编号
_pos	Vector3	位置
_rotation	Quaternion	旋转
_scale	Vector3	缩放
_role	Role	所属玩家

返回值:

• 类型: CustomTriggerSpace
• 说明: 创建出的触发区域

示例:

-- 创建自定义触发器空间（可变形区域），角色进入触发事件
-- 注意：100001 为示意预设 key，需替换为地图中实际配置的触发器空间预设 ID
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    local area = GameAPI.create_customtriggerspace(
        100001,                      -- 触发器预置 key
        math.Vector3(0, 0, 0),       -- 位置
        math.Quaternion(0, 0, 0),    -- 旋转
        math.Vector3(500, 3, 500),   -- 缩放（区域大小）
        role                         -- 所属角色
    )
    if not area then return end

    -- 注册角色进入区域的触发器（模板图同款写法）
    LuaAPI.global_register_trigger_event(
        { EVENT.ANY_LIFEENTITY_TRIGGER_SPACE, Enums.TriggerSpaceEventType.ENTER, LuaAPI.get_unit_id(area) },
        function(_, _, data)
            local character = data.event_unit
            if character and character.get_role() then
                character.get_role().show_tips("进入死亡区域", 2.0)
            end
        end)
end)

GameAPI.create_decoration

描述: 创建一个装饰物

GameAPI.create_decoration(_u_key, _pos, _rotation, _scale, _parent)

参数列表:

参数	类型	说明
_u_key	DecorationKey	单位编号
_pos	Vector3	位置
_rotation	Quaternion	旋转
_scale	Vector3	缩放
_parent	Unit	绑定对象

返回值:

• 类型: Decoration
• 说明: 创建的装饰物

示例:

-- 创建装饰物（场景点缀/拯救成功特效等）
-- 注意：100001 为示意预设 key，需替换为地图中实际配置的装饰物预设 ID
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    GameAPI.create_decoration(
        100001,                          -- 装饰物预置 key
        math.Vector3(0, 0, 0),           -- 位置
        math.Quaternion(0, 0, 0),        -- 旋转
        math.Vector3(1, 1, 1),           -- 缩放
        nil                              -- 父单位（nil 为独立装饰）
    )
end)

GameAPI.create_equipment

描述: 创建物品到坐标点

GameAPI.create_equipment(_equipment_eid, _pos)

参数列表:

参数	类型	说明
_equipment_eid	EquipmentKey	物品编号
_pos	Point3	位置

返回值:

• 类型: Equipment
• 说明: 物品

示例:

-- 在角色脚边创建一件武器物品，并直接装入已装备槽位
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local character = role.get_ctrl_unit()
    if not character then return end

    -- 创建武器（400001 为物品/武器预设ID），随后装入 1 号装备槽
    local weapon = GameAPI.create_equipment(400001, character.get_position())
    if weapon then
        character.swap_equipment_slot(weapon, Enums.EquipmentSlotType.EQUIPPED, 1)
        role.show_tips("装备成功", 2.0)
    end
end)

GameAPI.create_scene_ui_at_point

描述: 创建场景界面到坐标点

GameAPI.create_scene_ui_at_point(_layer_key, _pos, _duration)

参数列表:

参数	类型	说明
_layer_key	E3DLayerKey	场景界面预设编号
_pos	Point3	坐标点
_duration	Fixed	持续事件

返回值:

• 类型: E3DLayer
• 说明: 场景界面

示例:

-- 在场景中创建 UI 图层，并获取其中的控件
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    -- 创建场景 UI 图层（120001 为样式 key，-1 表示常驻不销毁）
    local layer = GameAPI.create_scene_ui_at_point(120001, role.get_ctrl_unit().get_position(), -1.0)
    if not layer then return end

    -- 获取图层中的控件（名字在 UI 配置中定义）
    local bar = GameAPI.get_eui_node_at_scene_ui(layer, "进度条")
    if bar then
        -- 初始化进度（进度条节点通过 Role 接口设置当前值）
        role.set_progressbar_current(bar, 50)
    end
end)

GameAPI.create_eui_ability_at_position

描述: 创建技能控件

GameAPI.create_eui_ability_at_position(_ability_style_key, _parent, _x, _y, _width, _height, _show_when_empty, _show_name, _name)

参数列表:

参数	类型	说明
_ability_style_key	AbilityStyleKey	技能预设编号
_parent	ENode	父节点
_x	Fixed	X
_y	Fixed	Y
_width	Fixed	宽
_height	Fixed	高
_show_when_empty	Bool	未关联技能时显示
_show_name	Bool	显示技能名称
_name	Str	名称

返回值:

• 类型: EButton
• 说明: 技能控件

示例:

-- 创建技能控件：在角色头顶展示技能图标
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    -- 第一步：创建场景 UI 图层（120001 为图层样式 key）
    local layer = GameAPI.create_scene_ui_at_point(120001, role.get_ctrl_unit().get_position(), -1.0)
    if not layer then return end

    -- 第二步：在图层上创建技能控件（230001 为技能样式 key）
    local ability = GameAPI.create_eui_ability_at_position(230001, layer, 0.0, 0.0, 100.0, 100.0, true, true, "技能_冲击波")
    if not ability then return end

    -- 第三步：操作控件（对当前角色显示技能图标）
    role.set_node_visible(ability, true)
end)

GameAPI.create_eui_effect_at_position

描述: 创建动效节点

GameAPI.create_eui_effect_at_position(_animation_style_key, _parent, _x, _y, _width, _height, _is_loop, _name)

参数列表:

参数	类型	说明
_animation_style_key	AnimationStyleKey	动效预设编号
_parent	ENode	父节点
_x	Fixed	X
_y	Fixed	Y
_width	Fixed	宽
_height	Fixed	高
_is_loop	Bool	循环播放
_name	Str	名称

返回值:

• 类型: EEffectNode
• 说明: 动效节点

示例:

-- 创建动效节点：播放循环火焰特效，挂在场景 UI 图层上
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    -- 创建场景 UI 图层
    local layer = GameAPI.create_scene_ui_at_point(120001, role.get_ctrl_unit().get_position(), -1.0)
    if not layer then return end

    -- 创建动效节点（230001 为动效样式 key，true 表示循环播放）
    local fx = GameAPI.create_eui_effect_at_position(230001, layer, 0.0, 0.0, 150.0, 150.0, true, "fx_篝火")
    if fx then
        -- 动效创建后自动开始播放，无需额外启动
        role.show_tips("火焰特效已播放", 2.0)
    end
end)

GameAPI.create_eui_bagslot_at_position

描述: 创建物品格控件

GameAPI.create_eui_bagslot_at_position(_parent, _x, _y, _width, _height, _bag_slot_style_key, _name)

参数列表:

参数	类型	说明
_parent	ENode	父节点
_x	Fixed	X
_y	Fixed	Y
_width	Fixed	宽
_height	Fixed	高
_bag_slot_style_key	BagSlotStyleKey	物品格预设编号
_name	Str	名称

返回值:

• 类型: EBagSlot
• 说明: 物品格控件

示例:

-- 创建物品格控件：展示背包道具，格内为空时自动显示占位底图
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    -- 创建场景 UI 图层
    local layer = GameAPI.create_scene_ui_at_point(120001, role.get_ctrl_unit().get_position(), -1.0)
    if not layer then return end

    -- 创建物品格控件（240001 为物品格样式 key；参数顺序：父节点、坐标、尺寸、样式、名称）
    local slot = GameAPI.create_eui_bagslot_at_position(layer, 0.0, 0.0, 80.0, 80.0, 240001, "背包格_1")
    if slot then
        role.show_tips("物品格已创建", 2.0)
    end
end)

GameAPI.create_eui_button_at_position

描述: 创建按钮节点

GameAPI.create_eui_button_at_position(_btn_style_key, _parent, _x, _y, _width, _height, _name)

参数列表:

参数	类型	说明
_btn_style_key	BtnStyleKey	按钮预设编号
_parent	ENode	父节点
_x	Fixed	X
_y	Fixed	Y
_width	Fixed	宽
_height	Fixed	高
_name	Str	名称

返回值:

• 类型: ENode
• 说明: 按钮节点

示例:

-- 创建按钮节点：场景中的"打开商店"按钮
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    -- 创建场景 UI 图层
    local layer = GameAPI.create_scene_ui_at_point(120001, role.get_ctrl_unit().get_position(), -1.0)
    if not layer then return end

    -- 创建按钮（160001 为按钮样式 key）
    local btn = GameAPI.create_eui_button_at_position(160001, layer, 0.0, 0.0, 200.0, 80.0, "btn_商店")
    if not btn then return end

    -- 操作控件：默认显示按钮，供玩家点击
    role.set_node_visible(btn, true)
end)

GameAPI.create_eui_clipping_at_position

描述: 创建遮罩节点

GameAPI.create_eui_clipping_at_position(_parent, _x, _y, _width, _height, _name, _clipping_path)

参数列表:

参数	类型	说明
_parent	ENode	父节点
_x	Fixed	X
_y	Fixed	Y
_width	Fixed	宽
_height	Fixed	高
_name	Str	名称
_clipping_path	ImageKey	蒙版图片ID

返回值:

• 类型: ENode
• 说明: 遮罩节点

示例:

-- 创建遮罩节点：裁剪子节点显示区域，实现头像圆形裁剪
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    -- 创建场景 UI 图层
    local layer = GameAPI.create_scene_ui_at_point(120001, role.get_ctrl_unit().get_position(), -1.0)
    if not layer then return end

    -- 创建遮罩节点（最后一个参数 170001 为裁剪路径图片 key）
    local clip = GameAPI.create_eui_clipping_at_position(layer, 0.0, 0.0, 100.0, 100.0, "clip_头像", 170001)
    if not clip then return end

    -- 在遮罩内创建头像底图，超出圆形部分将被裁剪
    local icon = GameAPI.create_eui_image_at_position(170001, clip, 0.0, 0.0, 100.0, 100.0, "img_头像")
    role.set_node_visible(icon, true)
end)

GameAPI.create_eui_image_at_position

描述: 创建图片节点

GameAPI.create_eui_image_at_position(_image_key, _parent, _x, _y, _width, _height, _name)

参数列表:

参数	类型	说明
_image_key	ImageKey	图片预设编号
_parent	ENode	父节点
_x	Fixed	X
_y	Fixed	Y
_width	Fixed	宽
_height	Fixed	高
_name	Str	名称

返回值:

• 类型: EImage
• 说明: 图片节点

示例:

-- 创建图片节点：角色头顶显示"新手"称号底图
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    -- 创建场景 UI 图层
    local layer = GameAPI.create_scene_ui_at_point(120001, role.get_ctrl_unit().get_position(), -1.0)
    if not layer then return end

    -- 创建图片节点（170001 为图片样式 key）
    local icon = GameAPI.create_eui_image_at_position(170001, layer, 0.0, 0.0, 200.0, 60.0, "img_称号底图")
    if not icon then return end

    -- 运行时替换图片纹理（16208 为策划配置的图片 key）
    role.set_image_texture_by_key_with_auto_resize(icon, 16208, false)
end)

GameAPI.create_eui_input_at_position

描述: 创建输入框节点

GameAPI.create_eui_input_at_position(_input_style_key, _parent, _x, _y, _width, _height, _name, _text)

参数列表:

参数	类型	说明
_input_style_key	InputStyleKey	输入框预设编号
_parent	ENode	父节点
_x	Fixed	X
_y	Fixed	Y
_width	Fixed	宽
_height	Fixed	高
_name	Str	名称
_text	Str	默认文本

返回值:

• 类型: ENode
• 说明: 输入框节点

示例:

-- 创建输入框节点：玩家可在其中输入昵称
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    -- 创建场景 UI 图层
    local layer = GameAPI.create_scene_ui_at_point(120001, role.get_ctrl_unit().get_position(), -1.0)
    if not layer then return end

    -- 创建输入框（190001 为输入框样式 key，最后一个参数为默认文本）
    local input = GameAPI.create_eui_input_at_position(190001, layer, 0.0, 0.0, 300.0, 60.0, "input_昵称", "请输入昵称")
    if input then
        role.show_tips("昵称输入框已创建", 2.0)
    end
end)

GameAPI.create_eui_label_at_position

描述: 创建文本节点

GameAPI.create_eui_label_at_position(_label_style_key, _parent, _x, _y, _width, _height, _name, _text)

参数列表:

参数	类型	说明
_label_style_key	LabelStyleKey	文本预设编号
_parent	ENode	父节点
_x	Fixed	X
_y	Fixed	Y
_width	Fixed	宽
_height	Fixed	高
_name	Str	名称
_text	Str	文本内容

返回值:

• 类型: ENode
• 说明: 文本节点

示例:

-- 创建文本节点：在场景中展示信息（创建→配置→收尾的完整闭环）
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    -- 创建场景 UI 图层
    local layer = GameAPI.create_scene_ui_at_point(120001, role.get_ctrl_unit().get_position(), -1.0)
    if not layer then return end

    -- 在图层上创建文本标签（180001 为标签样式 key，文本在创建时设定）
    local label = GameAPI.create_eui_label_at_position(180001, layer, 0.0, 0.0, 200.0, 40.0, "label_血量", "100/100")
    if not label then return end

    -- 动态节点返回 ENode（如 r10002），文本在创建时确定；
    -- 后续可对节点做通用配置（此处演示水平居中 50%）
    GameAPI.set_eui_node_horizontal_auto_center(label, true, true, 50.0)
end)

GameAPI.create_eui_listview_at_position

描述: 创建列表节点

GameAPI.create_eui_listview_at_position(_parent, _x, _y, _width, _height, _name)

参数列表:

参数	类型	说明
_parent	ENode	父节点
_x	Fixed	X
_y	Fixed	Y
_width	Fixed	宽
_height	Fixed	高
_name	Str	名称

返回值:

• 类型: ENode
• 说明: 列表节点

示例:

-- 创建列表节点：作为道具列表容器，后续可往里挂子节点
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    -- 创建场景 UI 图层
    local layer = GameAPI.create_scene_ui_at_point(120001, role.get_ctrl_unit().get_position(), -1.0)
    if not layer then return end

    -- 创建列表节点（无样式 key，直接指定尺寸）
    local list = GameAPI.create_eui_listview_at_position(layer, 0.0, 0.0, 400.0, 300.0, "list_道具")
    if not list then return end

    -- 在列表内挂一个标题，验证父子关系
    local title = GameAPI.create_eui_label_at_position(180001, list, 0.0, 0.0, 200.0, 30.0, "label_列表标题", "道具列表")
    role.set_node_visible(title, true)
end)

GameAPI.create_eui_progresstimer_at_position

描述: 创建环形进度条节点

GameAPI.create_eui_progresstimer_at_position(_progress_timer_style_key, _parent, _x, _y, _width, _height, _name)

参数列表:

参数	类型	说明
_progress_timer_style_key	ProgressTimerStyleKey	环形进度条预设编号
_parent	ENode	父节点
_x	Fixed	X
_y	Fixed	Y
_width	Fixed	宽
_height	Fixed	高
_name	Str	名称

返回值:

• 类型: ENode
• 说明: 环形进度条节点

示例:

-- 创建环形进度条：展示技能冷却倒计时
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    -- 创建场景 UI 图层
    local layer = GameAPI.create_scene_ui_at_point(120001, role.get_ctrl_unit().get_position(), -1.0)
    if not layer then return end

    -- 创建环形进度条（220001 为环形进度样式 key）
    local ring = GameAPI.create_eui_progresstimer_at_position(220001, layer, 0.0, 0.0, 80.0, 80.0, "ring_技能CD")
    if ring then
        -- 环形进度条数值为 0~1，具体更新方法名以 EggyAPI 文档为准，此处仅示意创建成功
        role.show_tips("技能CD环已创建", 2.0)
    end
end)

GameAPI.create_eui_progress_at_position

描述: 创建条形进度条节点

GameAPI.create_eui_progress_at_position(_progress_bar_style_key, _parent, _x, _y, _width, _height, _name)

参数列表:

参数	类型	说明
_progress_bar_style_key	ProgressBarStyleKey	条形进度条预设编号
_parent	ENode	父节点
_x	Fixed	X
_y	Fixed	Y
_width	Fixed	宽
_height	Fixed	高
_name	Str	名称

返回值:

• 类型: ENode
• 说明: 进度条节点

示例:

-- 创建条形进度条：展示角色当前血量百分比
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    -- 创建场景 UI 图层
    local layer = GameAPI.create_scene_ui_at_point(120001, role.get_ctrl_unit().get_position(), -1.0)
    if not layer then return end

    -- 创建条形进度条（210001 为进度条样式 key）
    local bar = GameAPI.create_eui_progress_at_position(210001, layer, 0.0, 0.0, 200.0, 30.0, "bar_血量")
    if not bar then return end

    -- 设置进度值（0~100）
    role.set_progressbar_current(bar, 75)
end)

GameAPI.create_joint_assistant

描述: 创建关节助手

GameAPI.create_joint_assistant(_unit_key, _unit1, _unit2)

参数列表:

参数	类型	说明
_unit_key	JointAssistantKey	关节助手类型
_unit1	Unit	连接主体
_unit2	Unit	连接目标

返回值:

• 类型: JointAssistant
• 说明: 创建出的关节助手

示例:

-- 创建辅助关节：将两个单位固定连接（如动态搭建的焊接）
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local box = LuaAPI.query_unit("木箱")
    if role and box then
        local joint = GameAPI.create_joint_assistant(
            Enums.JointAssistantKey.FIXED,   -- 关节类型（固定）
            role.get_ctrl_unit(),            -- 单位1
            box                              -- 单位2
        )
        -- 标记关节，方便后续按标记清理
        joint.set_kv_by_type(Enums.ValueType.Bool, "isDynamicStick", true)
    end
end)

GameAPI.create_life_entity

描述: 创建一个生命体

GameAPI.create_life_entity(_unit_key, _pos, _rotation, _scale_ratio, _role)

参数列表:

参数	类型	说明
_unit_key	UnitKey	单位编号
_pos	Point3	位置
_rotation	Quaternion	旋转
_scale_ratio	Fixed	缩放大小
_role	Role	所属玩家

返回值:

• 类型: LifeEntity
• 说明: 创建出的生命体

示例:

-- 在角色前方创建一个生命体（如可交互 NPC），并归属于该角色
-- 注意：100001 为示意预设 key，需替换为地图中实际配置的生命体预设 ID
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    -- 在角色前方 2 米处创建 100001 生命体，缩放 1.0 倍、无旋转
    local life = GameAPI.create_life_entity(100001, role.get_ctrl_unit().get_position() + math.Vector3(0, 0, 2), math.Quaternion(0, 0, 0), 1.0, role)
    if life then
        role.show_tips("生命体创建成功", 2.0)
    end
end)

GameAPI.create_obstacle

描述: 创建一个组件

GameAPI.create_obstacle(_u_key, _pos, _rotation, _scale, _role)

参数列表:

参数	类型	说明
_u_key	UnitKey	组件编号
_pos	Vector3	位置
_rotation	Quaternion	旋转
_scale	Vector3	缩放
_role	Role	所属玩家

返回值:

• 类型: Obstacle
• 说明: 创建的组件

示例:

-- 创建障碍物（预置 key 来自策划配置，可作为建造/预览指示器）
-- 注意：200001 为示意预设 key，需替换为地图中实际配置的障碍物预设 ID
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    local preview = GameAPI.create_obstacle(
        100001,                       -- 障碍物预置 key
        math.Vector3(0, 0, 0),        -- 位置
        math.Quaternion(0, 0, 0),     -- 旋转
        math.Vector3(0.5, 0.5, 0.5),  -- 缩放
        role                          -- 所属角色
    )
end)

GameAPI.create_obstacle_with_anim

描述: 带动效创建组件

GameAPI.create_obstacle_with_anim(_anim_type, _u_key, _pos, _duration, _intensity, _role, _rotation, _scale)

参数列表:

参数	类型	说明
_anim_type	Int	动效类型
_u_key	ObstacleKey	组件编号
_pos	Point3	创建坐标
_duration	Fixed	动画时长
_intensity	Fixed	效果系数
_role	Role	所属玩家
_rotation	Quaternion	旋转
_scale	Vector3	缩放

返回值:

• 类型: Obstacle
• 说明: 创建出的组件

示例:

-- 带动效创建组件：生成时播放出场动画（1 为通用生成动效）
-- 注意：200001 为示意预设 key，需替换为地图中实际配置的组件预设 ID
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    -- 在角色面前 3 米处创建 200001 组件，动效持续 1 秒、强度 1
    local obstacle = GameAPI.create_obstacle_with_anim(1, 200001, role.get_ctrl_unit().get_position() + math.Vector3(0, 0, 3), 1.0, 1.0, role, math.Quaternion(0, 0, 0), math.Vector3(1, 1, 1))
    if obstacle then
        role.show_tips("动效组件已生成", 2.0)
    end
end)

GameAPI.create_sfx_with_socket

描述: 播放特效并绑定

GameAPI.create_sfx_with_socket(_sfx_key, _unit, _socket_name, _scale, _duration, _bind_type)

参数列表:

参数	类型	说明
_sfx_key	SfxKey	特效编号
_unit	Unit	起点单位
_socket_name	ModelSocket	起点节点
_scale	Fixed	缩放
_duration	Fixed	持续时间
_bind_type	BindType	绑定方式

返回值:

• 类型: SfxID
• 说明: 特效ID

示例:

-- 在单位挂点上创建特效（如使用物品时的光效），绑定单位跟随移动
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    GameAPI.create_sfx_with_socket(
        700001,                                   -- 特效 key
        role.get_ctrl_unit(),                     -- 挂载单位
        Enums.ModelSocket.socket_origin,          -- 挂点
        1.0,                                      -- 缩放
        3.0,                                      -- 持续时间（秒）
        Enums.BindType.BIND_TYPE_DEFAULT          -- 绑定方式
    )
end)

GameAPI.create_sfx_with_socket_offset

描述: 播放特效并绑定

GameAPI.create_sfx_with_socket_offset(_sfx_key, _unit, _socket_name, _offset, _rot, _scale, _duration, _bind_type)

参数列表:

参数	类型	说明
_sfx_key	SfxKey	特效编号
_unit	Unit	起点单位
_socket_name	ModelSocket	起点节点
_offset	Vector3	偏移
_rot	Quaternion	旋转
_scale	Fixed	缩放
_duration	Fixed	持续时间
_bind_type	BindType	绑定方式

返回值:

• 类型: SfxID
• 说明: 特效ID

示例:

-- 在单位挂点偏移位置创建特效（如武器附魔光效）
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    GameAPI.create_sfx_with_socket_offset(
        700001,                                   -- 特效 key
        role.get_ctrl_unit(),                     -- 挂载单位
        Enums.ModelSocket.socket_origin,          -- 挂点
        math.Vector3(0, 0.5, 0),                  -- 相对挂点偏移
        math.Quaternion(0, 0, 0),                 -- 旋转
        1.0,                                      -- 缩放
        3.0,                                      -- 持续时间
        Enums.BindType.BIND_TYPE_DEFAULT          -- 绑定方式
    )
end)

GameAPI.create_triggerspace

描述: 创建一个逻辑体

GameAPI.create_triggerspace(_u_key, _pos, _rotation, _scale, _role)

参数列表:

参数	类型	说明
_u_key	TriggerSpaceKey	逻辑体编号
_pos	Vector3	位置
_rotation	Quaternion	旋转
_scale	Vector3	缩放
_role	Role	所属玩家

返回值:

• 类型: TriggerSpace
• 说明: 创建的逻辑体

示例:

-- 创建普通触发器空间（不可变形）
-- 注意：100001 为示意预设 key，需替换为地图中实际配置的触发器空间预设 ID
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    GameAPI.create_triggerspace(
        100001,                      -- 触发器预置 key
        math.Vector3(0, 0, 0),       -- 位置
        math.Quaternion(0, 0, 0),    -- 旋转
        math.Vector3(10, 3, 10),     -- 缩放（区域大小）
        role                         -- 所属角色
    )
end)

GameAPI.create_unit_group

描述: 创建一个组件组

GameAPI.create_unit_group(_unit_group_id, _pos, _root_quaternion, _role, _use_center_offset)

参数列表:

参数	类型	说明
_unit_group_id	UnitGroupKey	单位编号
_pos	Point3	位置
_root_quaternion	Quaternion	旋转
_role	Role	所属玩家
_use_center_offset	Bool	应用原点偏移

返回值:

• 类型: UnitGroup
• 说明: 创建出的单位

示例:

-- 创建单位组并遍历子对象（如换装区域的组合体）
-- 注意：100001 为示意预设 key，需替换为地图中实际配置的单位组预设 ID
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    local area = GameAPI.create_unit_group(
        100001,                          -- 单位组预置 key
        math.Vector3(0, 0, 0),           -- 位置
        math.Quaternion(0, 0, 0),        -- 旋转
        role,                            -- 所属角色
        false                            -- 是否使用中心偏移
    )
    if not area then return end

    -- 遍历子对象做初始化
    for _, child in ipairs(area.get_children()) do
        child.set_physics_active(true)
    end
end)

GameAPI.create_unit_with_scale

描述: 创建一个缩放单位

GameAPI.create_unit_with_scale(_u_key, _pos, _rotation, _scale)

参数列表:

参数	类型	说明
_u_key	UnitKey	单位编号
_pos	Point3	位置
_rotation	Quaternion	旋转
_scale	Vector3	缩放

返回值:

• 类型: Unit
• 说明: 创建出的单位

示例:

-- 创建带缩放的单位（无主单位），常用于一次性装饰物/方块
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    -- 在角色前方 2 米处创建放大 2 倍的 100001 单位
    local unit = GameAPI.create_unit_with_scale(100001, role.get_ctrl_unit().get_position() + math.Vector3(0, 0, 2), math.Quaternion(0, 0, 0), math.Vector3(2, 2, 2))
    if unit then
        role.show_tips("缩放单位创建成功", 2.0)
    end
end)

GameAPI.create_vehicle

描述: 创建载具

GameAPI.create_vehicle(_vehicle_key, _pos, _direction, _role)

参数列表:

参数	类型	说明
_vehicle_key	VehicleKey	载具编号
_pos	Point3	位置
_direction	Point3	朝向
_role	Role	所属玩家

返回值:

• 类型: Vehicle
• 说明: 载具

示例:

-- 在角色面前创建一辆载具（500001 为载具预设ID），生成后提示上车
-- 注意：500001 为示意预设 key，需替换为地图中实际配置的载具预设 ID
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    -- 载具朝向为正前方，生成在角色前方 3 米处
    local vehicle = GameAPI.create_vehicle(500001, role.get_ctrl_unit().get_position() + math.Vector3(0, 0, 3), math.Vector3(0, 0, 1), role)
    if vehicle then
        role.show_tips("载具已生成", 2.0)
    end
end)

GameAPI.fill_editable_image

描述: 用纯色填充可编辑图片

fill_editable_image(_image_key: ImageKey, _color: Color) -> void

参数列表:

参数	类型	说明
_image_key	ImageKey	ImageKey
_color	Color	Color

示例:

-- 用纯色填充可编辑图片，作为小地图/标签的底图
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 创建 128x128 画布并填充半透明白色底
    local image = GameAPI.create_editable_image(128.0, 128.0)
    if image then
        GameAPI.fill_editable_image(image, GlobalAPI.str_to_color("ffffff"))
    end
end)

GameAPI.get_table_sit_roles

描述: 获取座椅上玩家列表

get_table_sit_roles(_unit: Obstacle) -> ListRole

参数列表:

参数	类型	说明
_unit	Obstacle	Obstacle

返回值:

• 类型: ListRole

示例:

-- 查询坐在餐桌上的玩家列表，逐个给出提示
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local table_unit = LuaAPI.query_unit("餐桌")
    if not table_unit then return end

    -- 获取座椅上玩家列表并逐个提示
    local roles = GameAPI.get_table_sit_roles(table_unit)
    for _, role in ipairs(roles) do
        role.show_tips("你坐在了桌子上", 2.0)
    end
end)

GameAPI.paint_brush_world

描述: 在单位模型表面绘制一笔球形笔刷(世界坐标)

paint_brush_world(_unit: Unit, _image_key: ImageKey, _point: Vector3, _radius: Fixed, _color: Color) -> void

参数列表:

参数	类型	说明
_unit	Unit	Unit
_image_key	ImageKey	ImageKey
_point	Vector3	Vector3
_radius	Fixed	Fixed
_color	Color	Color

示例:

-- 在角色模型表面绘制一笔红色球形笔刷（世界坐标）
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local character = role.get_ctrl_unit()
    if not character then return end

    -- 创建画布并应用为模型贴图，再在头顶位置刷一笔
    local image = GameAPI.create_editable_image(512.0, 512.0)
    if image then
        GameAPI.apply_editable_image_to_unit(character, image)
        GameAPI.paint_brush_world(character, image, math.Vector3(0.0, 1.0, 0.0), 0.1, GlobalAPI.str_to_color("ff0000"))
    end
end)

GameAPI.register_geometry_ring2

描述: 注册一个几何体：圆环2（可变形，新版本）

register_geometry_ring2(_radius: Fixed, _cross_radius: Fixed, _segment: Int, _cross_segment: Int, _angle: Fixed, _easy_physics: Bool, _preconf: Dict) -> Str

参数列表:

参数	类型	说明
_radius	Fixed	Fixed
_cross_radius	Fixed	Fixed
_segment	Int	Int
_cross_segment	Int	Int
_angle	Fixed	Fixed
_easy_physics	Bool	Bool
_preconf	Dict	Dict

返回值:

• 类型: Str

示例:

-- 注册新版圆环几何体（环形管道状），用于传送门边框
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 半径 2 米、管径 0.5 米、12x8 分段，开启简易物理
    local geometry_path = GameAPI.register_geometry_ring2(2.0, 0.5, 12, 8, 90.0, true, {})
    if geometry_path and geometry_path ~= "" then
        LuaAPI.log("圆环2几何体注册成功", 0)
    end
end)

GameAPI.remove_pathpoint

描述: 从游戏全局移除指定路点

GameAPI.remove_pathpoint(_path_id, _index)

参数列表:

参数	类型	说明
_path_id	PathID	路径
_index	Int	路点索引

示例:

-- 游戏初始化：移除路径上不再需要的路点
-- 注意：路径与路点编号为示意值，需替换为地图中实际配置的路径数据
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 路径与索引信息来自策划配置
    local path_id = 10001   -- 巡逻路径
    local index = 1         -- 待移除的路点索引

    -- 移除后寻路会绕开该路点，NPC 巡逻路线随之变化
    GameAPI.remove_pathpoint(path_id, index)
end)

GameAPI.destroy_scene_ui

描述: 销毁场景界面

GameAPI.destroy_scene_ui(_layer)

参数列表:

参数	类型	说明
_layer	E3DLayer	场景界面

示例:

-- 销毁场景界面：倒计时结束后清理 UI 图层的收尾流程
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    -- 创建场景 UI 图层（-1.0 表示使用默认缩放）
    local layer = GameAPI.create_scene_ui_at_point(120001, role.get_ctrl_unit().get_position(), -1.0)
    if not layer then return end

    -- 5 秒后销毁图层，并置空引用防止重复销毁
    LuaAPI.call_delay_time(5.0, function()
        if layer then
            GameAPI.destroy_scene_ui(layer)
            layer = nil
        end
    end)
end)

GameAPI.destroy_obstacle_with_anim

描述: 带动效销毁组件

GameAPI.destroy_obstacle_with_anim(_anim_type, _obstacle, _duration, _intensity)

参数列表:

参数	类型	说明
_anim_type	Int	动效类型
_obstacle	Obstacle	目标组件
_duration	Fixed	动画时长
_intensity	Fixed	效果系数

示例:

-- 带动效销毁组件：先创建障碍物，再以动画效果销毁
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    -- 在角色前方 2 米处创建 200001 障碍物
    local obstacle = GameAPI.create_obstacle(200001, role.get_ctrl_unit().get_position() + math.Vector3(0, 0, 2), math.Quaternion(0, 0, 0), math.Vector3(1, 1, 1), role)
    if obstacle then
        -- 以 1 号动效、持续 1 秒、强度 1 销毁
        GameAPI.destroy_obstacle_with_anim(1, obstacle, 1.0, 1.0)
    end
end)

GameAPI.destroy_unit

描述: 销毁单位

GameAPI.destroy_unit(_unit)

参数列表:

参数	类型	说明
_unit	Unit	单位

示例:

-- 销毁单位：先反注册事件再销毁（清理顺序很重要）
local function remove_monster(unit, trigger_id)
    if not unit then return end
    if trigger_id then
        LuaAPI.unit_unregister_trigger_event(unit, trigger_id)
    end
    GameAPI.destroy_unit(unit)
end

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local monster = LuaAPI.query_unit("怪物")
    if monster then
        remove_monster(monster, nil)
    end
end)

GameAPI.game_end

描述: 游戏结束

GameAPI.game_end()

示例:

-- 游戏初始化：计时结束或条件达成时主动结束游戏
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 模拟一局游戏时长：30 秒后进入结算
    local game_duration = 30.0

    -- 倒计时结束后由服务器统一结束本局
    LuaAPI.call_delay_time(game_duration, function()
        -- 结束当前游戏并进入结算流程
        GameAPI.game_end()
    end)
end)

GameAPI.get_achievement_target

描述: 获取成就目标进度

GameAPI.get_achievement_target(_event_id)

参数列表:

参数	类型	说明
_event_id	Achievement	成就

返回值:

• 类型: Int
• 说明: 成就进度

示例:

-- 读取成就目标进度，用于成就界面展示
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 1 为成就编号（Achievement，可在成就配置中查看）
    local target = GameAPI.get_achievement_target(1)
    if target then
        GlobalAPI.show_tips("成就进度：" .. tostring(target), 2.0)
    else
        GlobalAPI.debug("成就 1 暂无目标进度")
    end
end)

GameAPI.get_all_characters

描述: 获取所有角色

GameAPI.get_all_characters()

返回值:

• 类型: ListCharacter
• 说明: 角色列表

示例:

-- 全量枚举角色：统计当前存活角色数量并广播
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local alive_count = 0
    local all_characters = GameAPI.get_all_characters()
    for _, character in ipairs(all_characters) do
        -- 按剩余血量判断角色是否存活
        if character.get_hp() > 0.0 then
            alive_count = alive_count + 1
        end
    end
    -- 把统计结果广播给所有玩家（示例用途）
    for _, role in ipairs(GameAPI.get_all_valid_roles()) do
        role.show_tips("当前存活角色: " .. tostring(alive_count), 2.0)
    end
end)

GameAPI.get_all_creatures

描述: 获取所有生物

GameAPI.get_all_creatures()

返回值:

• 类型: ListCreature
• 说明: 生物列表

示例:

-- 全量枚举生物：对全场带"怪物"标签的目标施加伤害
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    local creatures = GameAPI.get_all_creatures()
    for _, creature in ipairs(creatures) do
        -- 只处理怪物标签的生物，跳过友军与宠物
        if creature.has_tag("怪物") then
            GameAPI.deal_damage(creature, 50.0, role, 1, { show_damage_tips = false })
        end
    end
end)

GameAPI.get_all_customtriggerspaces

描述: 获取所有触发区域

GameAPI.get_all_customtriggerspaces()

返回值:

• 类型: ListCustomTriggerSpace
• 说明: 触发区域列表

示例:

-- 全量枚举自定义触发区域：按名称找到目标区域并检测玩家是否在内
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local character = role.get_ctrl_unit()

    local spaces = GameAPI.get_all_customtriggerspaces()
    for _, space in ipairs(spaces) do
        -- 只关注名为"危险区"的触发区域
        if space.get_name() == "危险区" then
            if GameAPI.is_point_in_customtriggerspace(character.get_position(), space) then
                role.show_tips("你已进入危险区！", 2.0)
            end
        end
    end
end)

GameAPI.get_all_equipments

描述: 获取所有物品

GameAPI.get_all_equipments()

返回值:

• 类型: ListEquipment
• 说明: 物品列表

示例:

-- 全量枚举物品：清理场景中指定编号的掉落物
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local target_key = 310101 -- 需要清理的物品编号
    local equipments = GameAPI.get_all_equipments()
    for _, equipment in ipairs(equipments) do
        if equipment.get_key() == target_key then
            GameAPI.destroy_unit(equipment)
        end
    end
end)

GameAPI.get_all_equipment_keys_in_shop

描述: 获取物品商店中的所有物品编号

GameAPI.get_all_equipment_keys_in_shop(_battle_shop_key)

参数列表:

参数	类型	说明
_battle_shop_key	BattleShopKey	物品商店编号

返回值:

• 类型: ListEquipmentKey
• 说明: 物品编号列表

示例:

-- 枚举商店物品：检查指定物品是否在当前商店在售
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 310001 为战斗商店 key，可替换为策划配置的商店编号
    local keys = GameAPI.get_all_equipment_keys_in_shop(310001)
    local target_key = 310101 -- 目标物品编号
    local found = false
    for _, key in ipairs(keys) do
        if key == target_key then
            found = true
            break
        end
    end
    -- 把在售结果提示给所有玩家
    for _, role in ipairs(GameAPI.get_all_valid_roles()) do
        role.show_tips(found and "目标物品在售" or "目标物品已下架", 2.0)
    end
end)

GameAPI.get_all_lifientities

描述: 获取所有生命体

GameAPI.get_all_lifientities()

返回值:

• 类型: ListLifeEntity
• 说明: 生命体列表

示例:

-- 全量枚举生命体：为指定预设编号的生命体打上精英标记
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local entities = GameAPI.get_all_lifientities()
    for _, entity in ipairs(entities) do
        -- 100002 为精英怪预设编号，可替换为策划配置
        if entity.get_key() == 100002 then
            entity.set_kv_by_type(Enums.ValueType.Bool, "is_elite", true)
        end
    end
end)

GameAPI.get_all_obstacles

描述: 获取所有组件

GameAPI.get_all_obstacles()

返回值:

• 类型: ListObstacle
• 说明: 组件列表

示例:

-- 全量枚举组件：摧毁所有带"可破坏"标签的障碍物
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local obstacles = GameAPI.get_all_obstacles()
    for _, obstacle in ipairs(obstacles) do
        if obstacle.has_tag("可破坏") then
            GameAPI.destroy_unit(obstacle)
        end
    end
end)

GameAPI.get_all_roles

描述: 获取所有玩家

GameAPI.get_all_roles()

返回值:

• 类型: ListRole
• 说明: 玩家

示例:

-- 全量枚举玩家：为所有玩家弹出开局提示
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local all_roles = GameAPI.get_all_roles()
    for _, role in ipairs(all_roles) do
        role.show_tips("欢迎进入地图，3 秒后开始战斗！", 3.0)
    end
end)

GameAPI.get_all_valid_roles

描述: 获取游戏中所有有效玩家

GameAPI.get_all_valid_roles()

返回值:

• 类型: ListRole
• 说明: 玩家列表

示例:

-- 遍历所有有效角色，为每个角色创建初始数据
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local player_data = {}
    for _, role in ipairs(GameAPI.get_all_valid_roles()) do
        local role_id = role.get_roleid()
        player_data[role_id] = { gold = 10 }
        role.show_tips("欢迎进入游戏", 2.0)
    end
end)

GameAPI.get_all_online_roles

描述: 获取所有在线玩家

GameAPI.get_all_online_roles()

返回值:

• 类型: ListRole
• 说明: 玩家列表

示例:

-- 遍历所有在线角色：统一设置单位可见性
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local water = LuaAPI.query_unit("水")
    local ice = LuaAPI.query_unit("冰")
    for _, role in ipairs(GameAPI.get_all_online_roles()) do
        role.set_unit_visible(water, true)
        role.set_unit_visible(ice, false)
    end
end)

GameAPI.get_all_triggerspaces

描述: 获取所有逻辑体

GameAPI.get_all_triggerspaces()

返回值:

• 类型: ListTriggerSpace
• 说明: 逻辑体列表

示例:

-- 全量枚举触发器空间：为每个触发区域注册角色进入事件
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local spaces = GameAPI.get_all_triggerspaces()
    for _, space in ipairs(spaces) do
        -- 以单位 ID 为参数注册进入事件
        LuaAPI.global_register_trigger_event(
            { EVENT.ANY_LIFEENTITY_TRIGGER_SPACE, Enums.TriggerSpaceEventType.ENTER, space.get_id() },
            function(_, _, data)
                local character = data.event_unit
                local role = character and character.get_role()
                if role then
                    role.show_tips("进入区域!", 1.0)
                end
            end
        )
    end
end)

GameAPI.get_characters_in_aabb

描述: 获取矩形区域内的角色

GameAPI.get_characters_in_aabb(_center, _length, _height, _width)

参数列表:

参数	类型	说明
_center	Point3	中心点
_length	Fixed	长
_height	Fixed	高
_width	Fixed	宽

返回值:

• 类型: ListCharacter
• 说明: 角色列表

示例:

-- AABB 范围查询角色：区域内的角色统一处理
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local characters = GameAPI.get_characters_in_aabb(math.Vector3(0, 0, 0), 20.0, 20.0, 20.0)
    for _, char in ipairs(characters) do
        local role = char.get_role()
        if role then
            role.show_tips("你进入了区域", 2.0)
        end
    end
end)

GameAPI.get_characters_in_cylinder

描述: 获取圆柱区域内的角色

GameAPI.get_characters_in_cylinder(_bottom_center, _radius, _height)

参数列表:

参数	类型	说明
_bottom_center	Point3	底部中心
_radius	Fixed	半径
_height	Fixed	高度

返回值:

• 类型: ListCharacter
• 说明: 角色列表

示例:

-- 圆柱范围查询角色：检测周围 10 米内是否有其他角色
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    local character = role.get_ctrl_unit()
    local pos = character.get_position()
    -- 以角色为底面圆心，半径 10 米、高 5 米的圆柱区域
    local characters = GameAPI.get_characters_in_cylinder(pos, 10.0, 5.0)
    for _, other in ipairs(characters) do
        -- 跳过自己，只提示附近的其他角色
        if other ~= character then
            role.show_tips("附近有其他角色！", 2.0)
            break
        end
    end
end)

GameAPI.get_characters_in_sphere

描述: 获取圆形区域内的角色

GameAPI.get_characters_in_sphere(_center, _radius)

参数列表:

参数	类型	说明
_center	Point3	中心点
_radius	Fixed	半径

返回值:

• 类型: ListCharacter
• 说明: 角色列表

示例:

-- 球范围查询角色：治疗范围内的友方角色
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    local characters = GameAPI.get_characters_in_sphere(role.get_ctrl_unit().get_position(), 5.0)
    for _, char in ipairs(characters) do
        local other = char.get_role()
        if other and other ~= role then
            char.change_hp(100.0)
        end
    end
end)

GameAPI.get_driving_vehicle

描述: 获取角色当前骑乘的载具

GameAPI.get_driving_vehicle(_character)

参数列表:

参数	类型	说明
_character	Character	角色

返回值:

• 类型: Vehicle
• 说明: 载具

示例:

-- 查询角色骑乘的载具：检测 NPC 是否正在驾驶载具
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 通过场景单位名查询 NPC 角色（Character 继承自 LifeEntity，代表NPC角色单位）
    local npc = LuaAPI.query_unit("NPC队长")
    if not npc then return end

    local vehicle = GameAPI.get_driving_vehicle(npc)
    if vehicle then
        -- 记录载具 ID，供后续下车/销毁逻辑使用
        print("NPC 正在驾驶载具，载具ID: " .. tostring(vehicle.get_id()))
    else
        print("NPC 当前未骑乘坐骑")
    end
end)

GameAPI.get_sheet_col_count

描述: 获取表列数

GameAPI.get_sheet_col_count(_sheet_id)

参数列表:

参数	类型	说明
_sheet_id	SheetID	多维表

返回值:

• 类型: Int
• 说明: 长度

示例:

-- 游戏初始化：检查表格列数是否满足需求
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local sheet = GameAPI.create_sheet()
    if not sheet then return end
    GameAPI.add_sheet_column(sheet, "key_001", "Int")

    -- 获取当前列数，用于校验表格结构
    local col_count = GameAPI.get_sheet_col_count(sheet)
    if col_count < 1 then
        -- 列数不足时重新初始化表格
    end
end)

GameAPI.get_sheet_row_count

描述: 获取表行数

GameAPI.get_sheet_row_count(_sheet_id)

参数列表:

参数	类型	说明
_sheet_id	SheetID	多维表

返回值:

• 类型: Int
• 说明: 长度

示例:

-- 游戏初始化：统计表格行数判断是否已有数据
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local sheet = GameAPI.create_sheet()
    if not sheet then return end
    GameAPI.add_sheet_column(sheet, "key_001", "Int")

    -- 行数为 0 表示表格为空，可执行初始化填充
    local row_count = GameAPI.get_sheet_row_count(sheet)
    if row_count == 0 then
        -- 首次进入：写入初始数据
    end
end)

GameAPI.get_creatures_by_key

描述: 获取指定编号的逻辑体列表

GameAPI.get_creatures_by_key(_creature_key)

参数列表:

参数	类型	说明
_creature_key	CreatureKey	生物编号

返回值:

• 类型: ListCreature
• 说明: 生物列表

示例:

-- 按编号查询生物：给全场所有"100001 号"生物打上减速标记
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    -- 100001 为生物预设编号，可替换为策划配置
    local creatures = GameAPI.get_creatures_by_key(100001)
    for _, creature in ipairs(creatures) do
        -- 减速标记由技能/移动系统读取，实现全图同类生物统一减速
        creature.set_kv_by_type(Enums.ValueType.Bool, "is_slow", true)
    end
end)

GameAPI.get_creatures_in_aabb

描述: 获取矩形区域内的生物

GameAPI.get_creatures_in_aabb(_center, _length, _height, _width)

参数列表:

参数	类型	说明
_center	Point3	中心点
_length	Fixed	长
_height	Fixed	高
_width	Fixed	宽

返回值:

• 类型: ListCreature
• 说明: 角色列表

示例:

-- AABB 范围查询生物：大范围获取所有生物并处理
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    local creatures = GameAPI.get_creatures_in_aabb(math.Vector3(0, 0, 0), 1000.0, 1000.0, 1000.0)
    for _, creature in ipairs(creatures) do
        if creature.has_tag("怪物") then
            GameAPI.deal_damage(creature, 100.0, role, 1, { show_damage_tips = true })
        end
    end
end)

GameAPI.get_creatures_in_annulus

描述: 获取圆环区域内的生物

GameAPI.get_creatures_in_annulus(_center, _radius1, _radius2, _height)

参数列表:

参数	类型	说明
_center	Point3	中心点
_radius1	Fixed	内径
_radius2	Fixed	外径
_height	Fixed	高度

返回值:

• 类型: ListCreature
• 说明: 生物列表

示例:

-- 圆环范围查询生物：监测 10~15 米环形警戒圈内的怪物
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    local pos = role.get_ctrl_unit().get_position()
    -- 内半径 10 米、外半径 15 米、高 5 米的圆环区域
    local creatures = GameAPI.get_creatures_in_annulus(pos, 10.0, 15.0, 5.0)
    local count = 0
    for _, creature in ipairs(creatures) do
        if creature.has_tag("怪物") then
            count = count + 1
        end
    end
    if count > 0 then
        role.show_tips("警戒圈内有 " .. tostring(count) .. " 只怪物！", 2.0)
    end
end)

GameAPI.get_creatures_in_cylinder

描述: 获取圆柱区域内的生物

GameAPI.get_creatures_in_cylinder(_bottom_center, _radius, _height)

参数列表:

参数	类型	说明
_bottom_center	Point3	底部中心
_radius	Fixed	半径
_height	Fixed	高度

返回值:

• 类型: ListCreature
• 说明: 生物列表

示例:

-- 圆柱范围查询生物：找周围 50 米内最近的怪物
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    local monsters = GameAPI.get_creatures_in_cylinder(role.get_ctrl_unit().get_position(), 50.0, 10.0)
    local nearest = nil
    local min_dist = math.huge
    for _, monster in ipairs(monsters) do
        if monster.has_tag("怪物") then
            local dist = (monster.get_position() - role.get_ctrl_unit().get_position()):length()
            if dist < min_dist then
                min_dist = dist
                nearest = monster
            end
        end
    end
    if nearest then
        GameAPI.deal_damage(nearest, 100.0, role, 1, { show_damage_tips = true })
    end
end)

GameAPI.get_creatures_in_sector

描述: 获取扇形区域内的生物

GameAPI.get_creatures_in_sector(_center, _face_dir, _central_angle, _radius, _height)

参数列表:

参数	类型	说明
_center	Point3	起始点
_face_dir	Fixed	角度朝向
_central_angle	Fixed	广角
_radius	Fixed	半径
_height	Fixed	高度

返回值:

• 类型: ListCreature
• 说明: 生物列表

示例:

-- 扇形范围查询生物：前方扇形视野内的敌人
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    -- 朝向角度 0 度 + 90 度夹角 + 半径 10 + 高度 5 的扇形
    -- （_face_dir 为角度制朝向，可改为角色实时朝向）
    local creatures = GameAPI.get_creatures_in_sector(
        role.get_ctrl_unit().get_position(),
        0.0,
        90.0,
        10.0,
        5.0
    )
    for _, creature in ipairs(creatures) do
        if creature.has_tag("怪物") then
            GameAPI.deal_damage(creature, 150.0, role, 1, { show_damage_tips = true })
        end
    end
end)

GameAPI.get_creatures_in_sphere

描述: 获取圆形区域内的生物

GameAPI.get_creatures_in_sphere(_center, _radius)

参数列表:

参数	类型	说明
_center	Point3	中心点
_radius	Fixed	半径

返回值:

• 类型: ListCreature
• 说明: 生物列表

示例:

-- 范围查询生物：以角色为中心 15 米，对"怪物"标签的目标造成伤害
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    local pos = role.get_ctrl_unit().get_position()
    local creatures = GameAPI.get_creatures_in_sphere(pos, 15.0)
    for _, creature in ipairs(creatures) do
        if creature.has_tag("怪物") then
            GameAPI.deal_damage(creature, 300.0, role, 1, { show_damage_tips = true })
        end
    end
end)

GameAPI.get_env_time

描述: 获取环境时间

GameAPI.get_env_time()

返回值:

• 类型: Fixed
• 说明: 当前环境时刻

示例:

-- 获取环境时间：常用于生成唯一标识或环境时间判断
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local env_time = GameAPI.get_env_time()
    LuaAPI.log("当前环境时间: " .. tostring(env_time), 0)
end)

GameAPI.get_customtriggerspaces_by_key

描述: 获取指定预设的触发区域列表

GameAPI.get_customtriggerspaces_by_key(_key)

参数列表:

参数	类型	说明
_key	CustomTriggerSpaceKey	触发区域编号

返回值:

• 类型: ListCustomTriggerSpace
• 说明: 触发区域列表

示例:

-- 按预设编号查询触发区域：找到安全区并检测玩家是否在其中
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local character = role.get_ctrl_unit()

    -- 110001 为触发区域预设编号，可替换为策划配置
    local spaces = GameAPI.get_customtriggerspaces_by_key(110001)
    for _, space in ipairs(spaces) do
        if GameAPI.is_point_in_customtriggerspace(character.get_position(), space) then
            role.show_tips("你处于安全区内", 2.0)
            break
        end
    end
end)

GameAPI.get_customtriggerspaces_in_raycast

描述: 获取射线检测到的触发区域列表

GameAPI.get_customtriggerspaces_in_raycast(_start_pos, _end_pos)

参数列表:

参数	类型	说明
_start_pos	Point3	起始点
_end_pos	Point3	终点

返回值:

• 类型: ListCustomTriggerSpace
• 说明: 触发区域列表

示例:

-- 射线查询触发区域：从角色身前 1 米到前方 20 米做射线检测
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    local character = role.get_ctrl_unit()
    local pos = character.get_position()
    local dir = character.get_direction()
    -- 起点取身前 1 米，终点取面朝方向 20 米
    local spaces = GameAPI.get_customtriggerspaces_in_raycast(pos + dir * 1.0, pos + dir * 20.0)
    for _, space in ipairs(spaces) do
        -- 命中后打印区域名称，供触发逻辑使用
        print("射线命中触发区域: " .. tostring(space.get_name()))
    end
end)

GameAPI.get_first_customtriggerspace_in_raycast

描述: 获取射线检测到的触发区域

GameAPI.get_first_customtriggerspace_in_raycast(_start_pos, _end_pos)

参数列表:

参数	类型	说明
_start_pos	Point3	起始点
_end_pos	Point3	终点

返回值:

• 类型: CustomTriggerSpace
• 说明: 触发区域

示例:

-- 射线查询首个触发区域：获取命中的第一个区域并打印名称
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    local character = role.get_ctrl_unit()
    local pos = character.get_position()
    local dir = character.get_direction()
    local space = GameAPI.get_first_customtriggerspace_in_raycast(pos, pos + dir * 20.0)
    -- 可能未命中任何区域，需判空
    if space then
        print("命中首个触发区域: " .. tostring(space.get_name()))
    end
end)

GameAPI.get_day

描述: 获取时间戳转化后的日期数

GameAPI.get_day(_timestamp)

参数列表:

参数	类型	说明
_timestamp	Timestamp	时间戳

返回值:

• 类型: Int
• 说明: 日

示例:

-- 把时间戳换算为 年/月/日，用于每日登录奖励等刷新逻辑
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 取当前时间戳并拆分日期
    local ts = GameAPI.get_timestamp()
    local year = GameAPI.get_year(ts)
    local month = GameAPI.get_month(ts)
    local day = GameAPI.get_day(ts)
    LuaAPI.log(string.format("当前日期: %d-%d-%d", year, month, day), 0)
end)

GameAPI.get_timestamp_diff

描述: 获取时间戳秒差

GameAPI.get_timestamp_diff(_timestamp_1, _timestamp_2)

参数列表:

参数	类型	说明
_timestamp_1	Timestamp	时间戳1
_timestamp_2	Timestamp	时间戳2

返回值:

• 类型: Int
• 说明: 秒差

示例:

-- 计算时间戳秒差：实现技能冷却倒计时判断
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local last_cast_time = GameAPI.get_timestamp() -- 记录上次施法时间
    local cooldown = 10 -- 冷却时长（秒）

    -- 3 秒后模拟一次施法后的冷却判断
    LuaAPI.call_delay_time(3.0, function()
        local elapsed = GameAPI.get_timestamp_diff(GameAPI.get_timestamp(), last_cast_time)
        if elapsed >= cooldown then
            print("冷却已结束，可以再次施法")
        else
            print("冷却剩余 " .. tostring(cooldown - elapsed) .. " 秒")
        end
    end)
end)

GameAPI.get_eui_node_at_scene_ui

描述: 获取场景界面中的控件

GameAPI.get_eui_node_at_scene_ui(_layer, _node_id)

参数列表:

参数	类型	说明
_layer	E3DLayer	场景界面
_node_id	ENode	界面节点

返回值:

• 类型: ENode
• 说明: 场景界面节点

示例:

-- 获取场景界面中的控件：图层创建后按节点名取回其中摆放的控件
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    -- 创建场景 UI 图层（120001 为图层样式 key）
    local layer = GameAPI.create_scene_ui_at_point(120001, role.get_ctrl_unit().get_position(), -1.0)
    if not layer then return end

    -- 先按名字查到节点，再取回图层中的对应控件（正式地图中多用 UINodes["xxx"] 编辑器节点）
    local node = LuaAPI.query_ui_node("血量文本")
    if not node then return end
    local hp_label = GameAPI.get_eui_node_at_scene_ui(layer, node)
    if hp_label then
        -- 对取回的控件设置文本
        role.set_label_text(hp_label, "100/100")
    end
end)

GameAPI.get_eui_children

描述: 获取UI节点的所有子UI节点

GameAPI.get_eui_children(_node)

参数列表:

参数	类型	说明
_node	ENode	UI节点

返回值:

• 类型: ListENode
• 说明: 子UI节点列表

示例:

-- 获取所有子节点：遍历面板下全部子节点，统一设置可见
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    -- 创建场景 UI 图层
    local layer = GameAPI.create_scene_ui_at_point(120001, role.get_ctrl_unit().get_position(), -1.0)
    if not layer then return end

    -- 父节点下挂两个子节点
    local img = GameAPI.create_eui_image_at_position(170001, layer, 0.0, 0.0, 300.0, 120.0, "img_面板")
    GameAPI.create_eui_label_at_position(180001, img, 0.0, 0.0, 100.0, 30.0, "label_标题", "标题")
    GameAPI.create_eui_image_at_position(170001, img, 0.0, 0.0, 50.0, 50.0, "img_图标")

    -- 获取全部子节点并逐个显示
    local children = GameAPI.get_eui_children(img)
    for _, node in ipairs(children) do
        role.set_node_visible(node, true)
    end
end)

GameAPI.get_eui_child_by_name

描述: 根据名字获取UI节点的子UI节点

GameAPI.get_eui_child_by_name(_node, _name)

参数列表:

参数	类型	说明
_node	ENode	UI节点
_name	Str	名字

返回值:

• 类型: ENode
• 说明: 子UI节点

示例:

-- 按名字获取子节点：在图片节点下挂子节点后，用名字取回并修改
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    -- 创建场景 UI 图层
    local layer = GameAPI.create_scene_ui_at_point(120001, role.get_ctrl_unit().get_position(), -1.0)
    if not layer then return end

    -- 父节点 + 命名子节点
    local img = GameAPI.create_eui_image_at_position(170001, layer, 0.0, 0.0, 200.0, 80.0, "img_面板")
    GameAPI.create_eui_label_at_position(180001, img, 0.0, 0.0, 100.0, 30.0, "label_金币", "金币:0")

    -- 按名字取回子节点
    local coin = GameAPI.get_eui_child_by_name(img, "label_金币")
    if coin then
        -- 动态节点仅支持 ENode 通用操作（此处演示存在性判断）
        print("取回子节点: " .. tostring(coin))
    end
end)

GameAPI.get_hour

描述: 获取时间戳转化后的小时数

GameAPI.get_hour(_timestamp)

参数列表:

参数	类型	说明
_timestamp	Timestamp	时间戳

返回值:

• 类型: Int
• 说明: 时

示例:

-- 时间戳转小时：实现"夜晚商店不营业"的时段判断
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local hour = GameAPI.get_hour(GameAPI.get_timestamp())
    -- 22 点到次日 6 点视为夜晚时段
    if hour >= 22 or hour < 6 then
        for _, role in ipairs(GameAPI.get_all_valid_roles()) do
            role.show_tips("夜晚商店打烊，白天再来吧！", 2.0)
        end
    end
end)

GameAPI.get_lifeentities_in_aabb

描述: 获取矩形区域内的生命体

GameAPI.get_lifeentities_in_aabb(_center, _length, _height, _width)

参数列表:

参数	类型	说明
_center	Point3	中心点
_length	Fixed	长
_height	Fixed	高
_width	Fixed	宽

返回值:

• 类型: ListLifeEntity
• 说明: 生命体列表

示例:

-- 矩形范围查询生命体：检测 8x3x8 区域内的精英怪并打标记
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    local center = role.get_ctrl_unit().get_position()
    -- 以角色为中心，长 8、高 3、宽 8 的矩形区域
    local entities = GameAPI.get_lifeentities_in_aabb(center, 8.0, 3.0, 8.0)
    for _, entity in ipairs(entities) do
        if entity.get_key() == 100002 then -- 精英怪预设编号
            entity.set_kv_by_type(Enums.ValueType.Bool, "is_elite", true)
        end
    end
end)

GameAPI.get_lifeentities_in_cylinder

描述: 获取圆柱区域内的生命体

GameAPI.get_lifeentities_in_cylinder(_bottom_center, _radius, _height)

参数列表:

参数	类型	说明
_bottom_center	Point3	底部中心
_radius	Fixed	半径
_height	Fixed	高度

返回值:

• 类型: ListLifeEntity
• 说明: 生命体列表

示例:

-- 圆柱范围查询生命体：统计周围 5 米内所有生命体数量
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    local pos = role.get_ctrl_unit().get_position()
    -- 以角色为底面圆心，半径 5 米、高 3 米的圆柱区域
    local entities = GameAPI.get_lifeentities_in_cylinder(pos, 5.0, 3.0)
    if #entities > 0 then
        role.show_tips("周围有 " .. tostring(#entities) .. " 个生命体", 1.5)
    end
end)

GameAPI.get_lifeentities_in_sphere

描述: 获取圆形区域内的生命体

GameAPI.get_lifeentities_in_sphere(_center, _radius)

参数列表:

参数	类型	说明
_center	Point3	中心点
_radius	Fixed	半径

返回值:

• 类型: ListLifeEntity
• 说明: 生命体列表

示例:

-- 球形范围查询生命体：找出范围内血量最低的生命体
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    local pos = role.get_ctrl_unit().get_position()
    local entities = GameAPI.get_lifeentities_in_sphere(pos, 15.0)
    local lowest = nil
    for _, entity in ipairs(entities) do
        -- 记录范围内血量最低的生命体
        if not lowest or entity.get_hp() < lowest.get_hp() then
            lowest = entity
        end
    end
    if lowest then
        print("范围内血量最低的生命体ID: " .. tostring(lowest.get_id()))
    end
end)

GameAPI.get_map_rating_score

描述: 获取地图当前评分

GameAPI.get_map_rating_score()

返回值:

• 类型: Fixed
• 说明: 当前评分

示例:

-- 读取地图评分，用于结算界面展示
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 返回当前地图的评分（Fixed）
    local score = GameAPI.get_map_rating_score()
    if score then
        GlobalAPI.show_tips("当前地图评分：" .. tostring(score), 2.0)
    else
        GlobalAPI.debug("暂未生成地图评分")
    end
end)

GameAPI.get_map_characters

描述: 获取所有地图角色

GameAPI.get_map_characters()

返回值:

• 类型: ListCharacter
• 说明: 角色列表

示例:

-- 枚举地图角色：统计地图上未绑定玩家的 NPC 数量
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local characters = GameAPI.get_map_characters()
    local npc_count = 0
    for _, character in ipairs(characters) do
        -- 没有绑定玩家控制的角色视为 NPC
        if not character.get_role() then
            npc_count = npc_count + 1
        end
    end
    print("地图NPC数量: " .. tostring(npc_count))
end)

GameAPI.is_env_time_running_enabled

描述: 获取环境时间是否自动流逝

GameAPI.is_env_time_running_enabled()

返回值:

• 类型: Bool
• 说明: 是否自动流逝

示例:

-- 查询环境时间是否在自动流逝，决定是否需手动驱动昼夜
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 自动流逝开启时无需手动更新时间
    if GameAPI.is_env_time_running_enabled() then
        LuaAPI.log("环境时间自动流逝中", 0)
    else
        LuaAPI.log("环境时间静止，需手动设置", 0)
    end
end)

GameAPI.get_env_time_ratio

描述: 获取环境时间流逝速率

GameAPI.get_env_time_ratio()

返回值:

• 类型: Fixed
• 说明: 流逝速率

示例:

-- 查询环境时间流逝速率：判断当前昼夜循环是否被加速
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 正常速率为 1.0，大于 1.0 表示时间在加速流逝
    local ratio = GameAPI.get_env_time_ratio()
    if ratio > 1.0 then
        print("环境时间正在加速流逝，速率: " .. tostring(ratio))
    else
        print("环境时间正常流逝")
    end
end)

GameAPI.get_minute

描述: 获取时间戳转化后的分钟数

GameAPI.get_minute(_timestamp)

参数列表:

参数	类型	说明
_timestamp	Timestamp	时间戳

返回值:

• 类型: Int
• 说明: 分

示例:

-- 时间戳转分钟：判断当前是否为整点（用于整点活动）
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local minute = GameAPI.get_minute(GameAPI.get_timestamp())
    -- 分钟数为 0 表示恰好整点
    if minute == 0 then
        for _, role in ipairs(GameAPI.get_all_valid_roles()) do
            role.show_tips("整点活动开启！", 2.0)
        end
    end
end)

GameAPI.get_month

描述: 获取时间戳转化后的月份数

GameAPI.get_month(_timestamp)

参数列表:

参数	类型	说明
_timestamp	Timestamp	时间戳

返回值:

• 类型: Int
• 说明: 月

示例:

-- 从时间戳解析月份（配合 get_timestamp 使用）
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local ts = GameAPI.get_timestamp()
    local month = GameAPI.get_month(ts)
    LuaAPI.log("当前月份: " .. tostring(month), 0)
end)

GameAPI.get_obstacles_by_key

描述: 获取指定编号的组件列表

GameAPI.get_obstacles_by_key(_key)

参数列表:

参数	类型	说明
_key	ObstacleKey	组件编号

返回值:

• 类型: ListObstacle
• 说明: 组件列表

示例:

-- 按编号查询组件：找出场景中所有"200001 号"箱子并统一开启物理
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 200001 为组件预设编号，可替换为策划配置
    local obstacles = GameAPI.get_obstacles_by_key(200001)
    for _, obstacle in ipairs(obstacles) do
        obstacle.set_physics_active(true)
    end
end)

GameAPI.get_obstacles_in_aabb

描述: 获取矩形区域内的组件

GameAPI.get_obstacles_in_aabb(_center, _length, _height, _width)

参数列表:

参数	类型	说明
_center	Point3	中心点
_length	Fixed	长
_height	Fixed	高
_width	Fixed	宽

返回值:

• 类型: ListObstacle
• 说明: 角色列表

示例:

-- AABB 范围查询障碍物：以角色为中心 5.5*5.5*5.5，销毁可破坏障碍
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    local center = role.get_ctrl_unit().get_position()
    local obstacles = GameAPI.get_obstacles_in_aabb(center, 5.5, 5.5, 5.5)
    for _, obstacle in ipairs(obstacles) do
        if obstacle.has_tag("可破坏") then
            GameAPI.destroy_unit(obstacle)
        end
    end
end)

GameAPI.get_obstacles_in_annulus

描述: 获取圆环区域内的组件

GameAPI.get_obstacles_in_annulus(_center, _radius1, _radius2, _height)

参数列表:

参数	类型	说明
_center	Point3	中心点
_radius1	Fixed	内径
_radius2	Fixed	外径
_height	Fixed	高度

返回值:

• 类型: ListObstacle
• 说明: 组件列表

示例:

-- 圆环范围查询组件：清理 8~12 米环形区域内的可破坏障碍物
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    local pos = role.get_ctrl_unit().get_position()
    -- 内半径 8 米、外半径 12 米、高 4 米的圆环区域
    local obstacles = GameAPI.get_obstacles_in_annulus(pos, 8.0, 12.0, 4.0)
    for _, obstacle in ipairs(obstacles) do
        if obstacle.has_tag("可破坏") then
            GameAPI.destroy_unit(obstacle)
        end
    end
end)

GameAPI.get_obstacles_in_cylinder

描述: 获取圆柱区域内的组件

GameAPI.get_obstacles_in_cylinder(_bottom_center, _radius, _height)

参数列表:

参数	类型	说明
_bottom_center	Point3	底部中心
_radius	Fixed	半径
_height	Fixed	高度

返回值:

• 类型: ListObstacle
• 说明: 组件列表

示例:

-- 圆柱范围查询组件：检测脚下圆柱区域内的障碍物
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    local pos = role.get_ctrl_unit().get_position()
    -- 以角色为底面圆心，半径 3 米、高 1 米的圆柱（检测脚下障碍）
    local obstacles = GameAPI.get_obstacles_in_cylinder(pos, 3.0, 1.0)
    for _, obstacle in ipairs(obstacles) do
        print("脚下障碍物ID: " .. tostring(obstacle.get_id()))
    end
end)

GameAPI.get_obstacles_by_raycast

描述: 获取射线检测到的组件列表

GameAPI.get_obstacles_by_raycast(_start_pos, _end_pos)

参数列表:

参数	类型	说明
_start_pos	Point3	起始点
_end_pos	Point3	终点

返回值:

• 类型: ListObstacle
• 说明: 组件列表

示例:

-- 射线检测障碍物列表：返回路径上所有障碍
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    local obstacles = GameAPI.get_obstacles_by_raycast(
        role.get_ctrl_unit().get_position(),
        role.get_ctrl_unit().get_position() + math.Vector3(0, 0, 20)
    )
    for _, obstacle in ipairs(obstacles) do
        if obstacle.has_tag("可破坏") then
            GameAPI.destroy_unit(obstacle)
        end
    end
end)

GameAPI.get_obstacles_in_sector

描述: 获取扇形区域内的组件

GameAPI.get_obstacles_in_sector(_center, _face_dir, _central_angle, _radius, _height)

参数列表:

参数	类型	说明
_center	Point3	起始点
_face_dir	Fixed	角度朝向
_central_angle	Fixed	广角
_radius	Fixed	半径
_height	Fixed	高度

返回值:

• 类型: ListObstacle
• 说明: 组件列表

示例:

-- 扇形范围查询组件：检测面朝方向 60° 扇形内的可破坏障碍物
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    local pos = role.get_ctrl_unit().get_position()
    -- 面朝方向角 0.0（弧度）、扇形中心角 60.0（角度）、半径 8 米、高 3 米
    local obstacles = GameAPI.get_obstacles_in_sector(pos, 0.0, 60.0, 8.0, 3.0)
    local count = 0
    for _, obstacle in ipairs(obstacles) do
        if obstacle.has_tag("可破坏") then
            count = count + 1
        end
    end
    if count > 0 then
        print("扇形区域内可破坏组件数量: " .. tostring(count))
    end
end)

GameAPI.get_obstacles_in_sphere

描述: 获取圆形区域内的组件

GameAPI.get_obstacles_in_sphere(_center, _radius)

参数列表:

参数	类型	说明
_center	Point3	中心点
_radius	Fixed	半径

返回值:

• 类型: ListObstacle
• 说明: 组件列表

示例:

-- 球范围查询障碍物：爆炸波及范围内可破坏障碍
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    local obstacles = GameAPI.get_obstacles_in_sphere(role.get_ctrl_unit().get_position(), 8.0)
    for _, obstacle in ipairs(obstacles) do
        if obstacle.has_tag("可破坏") then
            GameAPI.destroy_unit(obstacle)
        end
    end
end)

GameAPI.get_obstacle_by_raycast

描述: 获取射线检测到的组件

GameAPI.get_obstacle_by_raycast(_start_pos, _end_pos)

参数列表:

参数	类型	说明
_start_pos	Point3	起始点
_end_pos	Point3	终点

返回值:

• 类型: Obstacle
• 说明: 组件

示例:

-- 射线检测首个障碍物：瞄准/拾取判定
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    local obstacle = GameAPI.get_obstacle_by_raycast(
        role.get_ctrl_unit().get_position(),
        role.get_ctrl_unit().get_position() + math.Vector3(0, 0, 5)
    )
    if obstacle then
        role.show_tips("瞄准了障碍物", 2.0)
    end
end)

GameAPI.get_vector3s_from_path

描述: 获取路径向量数组

GameAPI.get_vector3s_from_path(_path_id)

参数列表:

参数	类型	说明
_path_id	PathID	路径

返回值:

• 类型: ListVector3
• 说明: 向量数组

示例:

-- 获取路径点数组，并用调试线段把整条路径可视化
-- 注意：10001 为示意路径 ID，需替换为地图中实际配置的路径
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 10001 为场景中配置的路径ID
    local points = GameAPI.get_vector3s_from_path(10001)
    if not points or #points < 2 then return end

    -- 依次连接相邻路径点，绘制绿色调试线
    for i = 1, #points - 1 do
        DebugAPI.draw_line(points[i], points[i + 1], GlobalAPI.str_to_color("00ff00"), 3.0)
    end
end)

GameAPI.random_color

描述: 获取随机颜色

GameAPI.random_color()

返回值:

• 类型: Color
• 说明: 颜色

示例:

-- 生成随机颜色并填充到可编辑图片，作为随机礼盒的底图颜色
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 随机生成一个颜色
    local color = GameAPI.random_color()

    -- 创建 64x64 可编辑图片并填充该随机色
    local image = GameAPI.create_editable_image(64.0, 64.0)
    if image then
        GameAPI.fill_editable_image(image, color)
    end
end)

GameAPI.get_pathpoint_by_index

描述: 获取路径中的路点向量

GameAPI.get_pathpoint_by_index(_path_id, _index)

参数列表:

参数	类型	说明
_path_id	PathID	路径
_index	Int	路点索引

返回值:

• 类型: Vector3
• 说明: 向量

示例:

-- 按索引查询路径路点：读取路径起点用于巡逻起点判定
-- 注意：10001 为示意路径 ID，需替换为地图中实际配置的路径
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local path_id = 10001 -- 路径 ID，可替换为策划配置
    -- 读取路径上第 1 个路点作为起点（索引从 1 开始）
    local start_point = GameAPI.get_pathpoint_by_index(path_id, 1)
    if start_point then
        print("路径起点: " .. tostring(start_point.x) .. "," .. tostring(start_point.z))
    end
end)

GameAPI.get_role_friendship_value

描述: 获取玩家亲密度

GameAPI.get_role_friendship_value(_role_1, _role_2)

参数列表:

参数	类型	说明
_role_1	Role	玩家1
_role_2	Role	玩家2

返回值:

• 类型: Int
• 说明: 亲密度

示例:

-- 查询两名玩家之间的亲密度数值，用于好友系统展示
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local roles = GameAPI.get_all_valid_roles()
    local role_1 = roles[1]
    local role_2 = roles[2]
    if not role_1 or not role_2 then return end

    -- 获取两名玩家之间的亲密度
    local value = GameAPI.get_role_friendship_value(role_1, role_2)
    role_1.show_tips("与好友亲密度: " .. tostring(value), 2.0)
end)

GameAPI.is_role_friendship_type_match

描述: 玩家亲密关系是否符合

GameAPI.is_role_friendship_type_match(_role_1, _role_2, _friendship_type)

参数列表:

参数	类型	说明
_role_1	Role	玩家1
_role_2	Role	玩家2
_friendship_type	FriendshipType	亲密关系

返回值:

• 类型: Bool
• 说明: 是否符合

示例:

-- 判断两名玩家是否满足指定亲密关系（好友）
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local roles = GameAPI.get_all_valid_roles()
    local role_1 = roles[1]
    local role_2 = roles[2]
    if not role_1 or not role_2 then return end

    -- 是否为好友关系
    if GameAPI.is_role_friendship_type_match(role_1, role_2, Enums.FriendshipType.FRIEND) then
        role_1.show_tips("你们是好友", 2.0)
    end
end)

GameAPI.get_party_roles

描述: 获取组队中玩家列表

GameAPI.get_party_roles(_party_id)

参数列表:

参数	类型	说明
_party_id	Str	组队Id

返回值:

• 类型: ListRole
• 说明: 玩家列表

示例:

-- 查询组队玩家：根据队伍 ID 获取队伍成员并广播集结提示
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- "id_001" 为队伍 ID，实际由组队系统下发
    local party_roles = GameAPI.get_party_roles("id_001")
    for _, role in ipairs(party_roles) do
        role.show_tips("队伍集结完成，准备出发！", 2.0)
    end
end)

GameAPI.get_second

描述: 获取时间戳转化后的秒数

GameAPI.get_second(_timestamp)

参数列表:

参数	类型	说明
_timestamp	Timestamp	时间戳

返回值:

• 类型: Int
• 说明: 秒

示例:

-- 时间戳转秒：与小时/分钟组合实现"HH:MM:SS"显示
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local now = GameAPI.get_timestamp()
    local hour = GameAPI.get_hour(now)
    local minute = GameAPI.get_minute(now)
    local second = GameAPI.get_second(now)
    -- 组合成当前时刻并显示给所有玩家
    local text = tostring(hour) .. ":" .. tostring(minute) .. ":" .. tostring(second)
    for _, role in ipairs(GameAPI.get_all_valid_roles()) do
        role.show_tips("当前时间 " .. text, 2.0)
    end
end)

GameAPI.get_timestamp

描述: 获取当前时间戳

GameAPI.get_timestamp()

返回值:

• 类型: Timestamp
• 说明: 时间戳

示例:

-- 获取时间戳：记录开始时间，配合周期事件判断超时
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local start_time = GameAPI.get_timestamp()

    -- 每 0.2 秒检查一次是否超时（30 秒上限）
    local timer_id = LuaAPI.global_register_trigger_event({ EVENT.REPEAT_TIMEOUT, 0.2 }, function()
        if GameAPI.get_timestamp() - start_time >= 30.0 then
            LuaAPI.log("任务超时", 1)
            LuaAPI.global_unregister_trigger_event(timer_id)
        end
    end)
end)

GameAPI.get_timestamp_by_time

描述: 获取时间戳

GameAPI.get_timestamp_by_time(_year, _month, _day, _hour, _minute, _second)

参数列表:

参数	类型	说明
_year	Int	年
_month	Int	月
_day	Int	日
_hour	Int	时
_minute	Int	分
_second	Int	秒

返回值:

• 类型: Timestamp
• 说明: 时间戳

示例:

-- 指定时间转时间戳：计算活动开启前的剩余秒数
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 活动开启时间：2026 年 8 月 25 日 12 点（可替换为策划配置）
    local activity_ts = GameAPI.get_timestamp_by_time(2026, 8, 25, 12, 0, 0)
    local now = GameAPI.get_timestamp()
    local remain = GameAPI.get_timestamp_diff(activity_ts, now)
    if remain > 0 then
        for _, role in ipairs(GameAPI.get_all_valid_roles()) do
            role.show_tips("活动还有 " .. tostring(remain) .. " 秒开启", 2.0)
        end
    end
end)

GameAPI.get_triggerspaces_by_key

描述: 获取指定编号的逻辑体列表

GameAPI.get_triggerspaces_by_key(_key)

参数列表:

参数	类型	说明
_key	TriggerSpaceKey	逻辑体编号

返回值:

• 类型: ListTriggerSpace
• 说明: 逻辑体列表

示例:

-- 按编号查询触发器空间：遍历所有"900001 号"传送点并打印位置
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 900001 为触发器空间预设编号，可替换为策划配置
    local spaces = GameAPI.get_triggerspaces_by_key(900001)
    for _, space in ipairs(spaces) do
        -- 打印每个传送点位置，供传送逻辑使用
        local pos = space.get_position()
        print("传送点位置: " .. tostring(pos.x) .. "," .. tostring(pos.z))
    end
end)

GameAPI.get_joint_assistants

描述: 获取组件上的所有关节

GameAPI.get_joint_assistants(_unit)

参数列表:

参数	类型	说明
_unit	Unit	目标单位

返回值:

• 类型: ListJointAssistant
• 说明: 关节列表

示例:

-- 获取单位上的所有辅助关节，按标记清理
local function remove_stick_joints(unit)
    for _, joint in ipairs(GameAPI.get_joint_assistants(unit)) do
        if joint.has_kv("isDynamicStick") then
            GameAPI.destroy_unit(joint)
        end
    end
end

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if role then
        remove_stick_joints(role.get_ctrl_unit())
    end
end)

GameAPI.get_weekday

描述: 获取时间戳转化后的星期数

GameAPI.get_weekday(_timestamp)

参数列表:

参数	类型	说明
_timestamp	Timestamp	时间戳

返回值:

• 类型: Int
• 说明: 星期

示例:

-- 时间戳转星期：周末开启双倍奖励活动
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 返回 1~7，对应周一~周日
    local weekday = GameAPI.get_weekday(GameAPI.get_timestamp())
    if weekday >= 6 then -- 周六、周日
        for _, role in ipairs(GameAPI.get_all_valid_roles()) do
            role.show_tips("周末双倍奖励开启！", 2.0)
        end
    end
end)

GameAPI.get_year

描述: 获取时间戳转化后的年数

GameAPI.get_year(_timestamp)

参数列表:

参数	类型	说明
_timestamp	Timestamp	时间戳

返回值:

• 类型: Int
• 说明: 年

示例:

-- 从时间戳解析年份
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local ts = GameAPI.get_timestamp()
    local year = GameAPI.get_year(ts)
    LuaAPI.log("当前年份: " .. tostring(year), 0)
end)

GameAPI.random_int

描述: 随机整数

GameAPI.random_int(_min_value, _max_value)

参数列表:

参数	类型	说明
_min_value	Int	最小值
_max_value	Int	最大值

返回值:

• 类型: Int
• 说明: 整数

示例:

-- 从奖励列表中随机抽取一项，并提示玩家抽奖结果
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    -- 奖励列表，随机抽取一个下标（闭区间 [1, #rewards]）
    local rewards = { "金币", "钻石", "皮肤碎片" }
    local index = GameAPI.random_int(1, #rewards)
    role.show_tips("抽中奖励: " .. rewards[index], 2.0)
end)

GameAPI.is_point_in_customtriggerspace

描述: 坐标点是否在触发区域内

GameAPI.is_point_in_customtriggerspace(_point, _custom_trigger_space)

参数列表:

参数	类型	说明
_point	Point3	坐标点
_custom_trigger_space	CustomTriggerSpace	触发区域

返回值:

• 类型: Bool
• 说明: 是否在触发区域内

示例:

-- 判断点是否在自定义触发器空间内（区域判定）
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    local area = GameAPI.create_customtriggerspace(
        100001, math.Vector3(0, 0, 0), math.Quaternion(0, 0, 0), math.Vector3(10, 10, 10), role)
    if GameAPI.is_point_in_customtriggerspace(role.get_ctrl_unit().get_position(), area) then
        role.show_tips("角色在区域内", 2.0)
    end
end)

GameAPI.is_archives_enabled

描述: 是否开启存档

GameAPI.is_archives_enabled()

返回值:

• 类型: Bool
• 说明: 是否开启

示例:

-- 游戏初始化：判断存档功能是否开启
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 存档开启时才执行存档相关逻辑
    if GameAPI.is_archives_enabled() then
        -- 存档已开启：可安全调用 request_archive 等接口
        GameAPI.request_archive()
    else
        -- 存档未开启：跳过存档逻辑
    end
end)

GameAPI.load_level

描述: 跳转关卡

GameAPI.load_level(_level_key)

参数列表:

参数	类型	说明
_level_key	LevelKey	关卡编号

示例:

-- 游戏初始化：玩家达成条件后跳转到指定关卡
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 关卡编号来自策划配置（290001 为示例关卡）
    local next_level = "290001"

    -- 模拟 5 秒后自动跳关（实际应在胜利结算后调用）
    LuaAPI.call_delay_time(5.0, function()
        -- 跳转关卡：加载目标关卡并开始新一局
        GameAPI.load_level(next_level)
    end)
end)

GameAPI.get_montage_duration

描述: 获取剧情时长

GameAPI.get_montage_duration(_montage_id)

参数列表:

参数	类型	说明
_montage_id	MontageKey	剧情动画编号

返回值:

• 类型: Fixed
• 说明: 时长

示例:

-- 查询剧情时长：播放剧情前拿到总时长，驱动跳过倒计时
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 260001 为剧情编号，可替换为策划配置
    local duration = GameAPI.get_montage_duration("260001")
    if duration and duration > 0.0 then
        -- 记录剧情总时长，供剧情系统做跳过/结束判定
        print("剧情总时长: " .. tostring(duration) .. " 秒")
    end
end)

GameAPI.play_link_sfx

描述: 播放连线特效

GameAPI.play_link_sfx(_sfx_key, _unit, _from_socket_name, _target_unit, _target_socket_name, _duration)

参数列表:

参数	类型	说明
_sfx_key	SfxKey	特效编号
_unit	Unit	起点单位
_from_socket_name	Str	起点节点
_target_unit	Unit	终点单位
_target_socket_name	Str	终点节点
_duration	Fixed	持续时间

返回值:

• 类型: SfxID
• 说明: 特效ID

示例:

-- 播放链接特效：连接两个单位的挂点（如钓鱼线/牵引线）
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local target = LuaAPI.query_unit("鱼")
    if role and target then
        local line_id = GameAPI.play_link_sfx(
            1237,                                        -- 特效 key
            role.get_ctrl_unit(),                        -- 起始单位
            "Socket_1",                                  -- 起始挂点
            target,                                      -- 目标单位
            "Socket_1",                                  -- 目标挂点
            -1.0                                         -- 持续时间（-1 常驻）
        )
    end
end)

GameAPI.play_sfx_by_key

描述: 播放特效

GameAPI.play_sfx_by_key(_sfx_key, _pos, _rot, _scale, _duration, _rate, _with_sound)

参数列表:

参数	类型	说明
_sfx_key	SfxKey	特效编号
_pos	Point3	位置
_rot	Quaternion	旋转
_scale	Fixed	缩放
_duration	Fixed	持续时间
_rate	Fixed	播放速率
_with_sound	Bool	是否播放音效

返回值:

• 类型: SfxID
• 说明: 特效ID

示例:

-- 在角色位置播放音效，返回实例 ID，3 秒后销毁（完整音效生命周期）
local role = GameAPI.get_all_valid_roles()[1]
if role then
    local pos = role.get_ctrl_unit().get_position()
    local sfx_id = GameAPI.play_sfx_by_key(700001, pos, math.Quaternion(0, 0, 0, 1), 1.0, 3.0, 1.0, true)
    LuaAPI.call_delay_time(3.0, function()
        if sfx_id then
            GlobalAPI.destroy_sfx(sfx_id)
        end
    end)
end

GameAPI.get_pathpoint_by_id

描述: 获取路点坐标

GameAPI.get_pathpoint_by_id(_point_id)

参数列表:

参数	类型	说明
_point_id	PathPointID	路点

返回值:

• 类型: Point3
• 说明: 坐标

示例:

-- 按 ID 查询路点：获取巡逻路点并让 NPC 前往
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local npc = LuaAPI.query_unit("巡逻NPC")
    if not npc then return end

    -- 20001 为路点 ID，可替换为策划配置的路点编号
    local point = GameAPI.get_pathpoint_by_id(20001)
    if point then
        npc.force_start_move(point, 1.0)
    end
end)

GameAPI.get_role

描述: 玩家ID获取玩家

GameAPI.get_role(_role_id)

参数列表:

参数	类型	说明
_role_id	RoleID	玩家ID

返回值:

• 类型: Role
• 说明: 玩家

示例:

-- 通过角色ID反查玩家对象，常用于跨事件传递角色ID后的恢复
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    -- 先取玩家ID，再通过 ID 反查玩家对象
    local role_id = role.get_roleid()
    local target = GameAPI.get_role(role_id)
    if target then
        target.show_tips("通过ID成功找回玩家", 2.0)
    end
end)

GameAPI.request_archive

描述: 上传所有玩家存档

request_archive() -> ArchiveUploadState

返回值:

• 类型: ArchiveUploadState

示例:

-- 游戏初始化：结算前主动上传所有玩家存档
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 存档功能开启时才上传
    if not GameAPI.is_archives_enabled() then return end

    -- 上传所有玩家存档，返回上传状态（ArchiveUploadState）
    local state = GameAPI.request_archive()
    -- 可按需根据 state 判断上传结果（如等待上传/上传中/成功）
end)

GameAPI.set_all_scene_ui_visible

描述: 设置所有场景界面显示状态

GameAPI.set_all_scene_ui_visible(_role, _visible)

参数列表:

参数	类型	说明
_role	Role	玩家
_visible	Bool	点击关闭属性

示例:

-- 设置所有场景界面显示状态：开局统一显示，进入战斗后统一隐藏
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 遍历所有有效角色，统一控制其场景界面显隐
    local all_roles = GameAPI.get_all_valid_roles()
    for _, role in ipairs(all_roles) do
        GameAPI.set_all_scene_ui_visible(role, true)
    end

    -- 稍后（如进入战斗阶段）再统一隐藏
    LuaAPI.call_delay_time(3.0, function()
        for _, role in ipairs(all_roles) do
            GameAPI.set_all_scene_ui_visible(role, false)
        end
    end)
end)

GameAPI.enable_collision_between_unit_and_prefab

描述: 设置单位与预设是否能发生碰撞

GameAPI.enable_collision_between_unit_and_prefab(_unit, _unit_eid, _enable)

参数列表:

参数	类型	说明
_unit	Unit	单位
_unit_eid	UnitKey	单位编号
_enable	Bool	是否碰撞

示例:

-- 控制单位与某类预置的碰撞（怪物死亡后不再阻挡同类）
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local monster = LuaAPI.query_unit("怪物")
    if monster then
        -- 关闭与所有生物预置的碰撞
        GameAPI.enable_collision_between_unit_and_prefab(monster, 100001, false)
    end
end)

GameAPI.enable_collision_between_units

描述: 设置两个单位是否能碰撞

GameAPI.enable_collision_between_units(_unit_1, _unit_2, _enable)

参数列表:

参数	类型	说明
_unit_1	Unit	单位1
_unit_2	Unit	单位2
_enable	Bool	是否碰撞

示例:

-- 控制两个单位之间的碰撞（怪物死亡后关闭碰撞，不阻挡玩家）
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local monster = LuaAPI.query_unit("怪物")
    if role and monster then
        GameAPI.enable_collision_between_units(role.get_ctrl_unit(), monster, false)
    end
end)

GameAPI.set_equipment_remaining_stock_count

描述: 设置物品商店物品剩余库存

GameAPI.set_equipment_remaining_stock_count(_battle_shop_key, _equipment_key, _cur_stock_count)

参数列表:

参数	类型	说明
_battle_shop_key	BattleShopKey	物品商店编号
_equipment_key	EquipmentKey	物品编号
_cur_stock_count	Int	剩余库存

示例:

-- 游戏初始化：重置商店物品剩余库存
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 商店编号与物品编号均来自策划配置
    local shop_key = 310001       -- 物品商店
    local equipment_key = 400001  -- 物品

    -- 新回合开始，将剩余库存补满为 3
    GameAPI.set_equipment_remaining_stock_count(shop_key, equipment_key, 3)
end)

GameAPI.set_equipment_max_stock_count

描述: 设置物品商店物品最大库存

GameAPI.set_equipment_max_stock_count(_battle_shop_key, _equipment_key, _max_stock_count)

参数列表:

参数	类型	说明
_battle_shop_key	BattleShopKey	物品商店编号
_equipment_key	EquipmentKey	物品编号
_max_stock_count	Int	最大库存

示例:

-- 游戏初始化：配置物品商店的库存上限
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 商店编号与物品编号均来自策划配置
    local shop_key = 310001       -- 物品商店
    local equipment_key = 400001  -- 物品

    -- 设置该物品在商店中的最大库存为 3
    GameAPI.set_equipment_max_stock_count(shop_key, equipment_key, 3)
end)

GameAPI.set_scene_ui_visible

描述: 设置场景界面的显隐

GameAPI.set_scene_ui_visible(_layer, _role, _visible)

参数列表:

参数	类型	说明
_layer	E3DLayer	场景界面
_role	Role	玩家
_visible	Bool	显隐

示例:

-- 按角色控制场景 UI 显隐（常用于 3D 称号/名牌等单角色 UI）
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local layer = GameAPI.create_scene_ui_at_point(120001, math.Vector3(0, 0, 0), -1.0)
    for _, role in ipairs(GameAPI.get_all_valid_roles()) do
        -- 只给当前角色显示
        GameAPI.set_scene_ui_visible(layer, role, true)
    end
end)

GameAPI.set_scene_ui_position

描述: 设置场景界面位置

GameAPI.set_scene_ui_position(_role, _layer, _position)

参数列表:

参数	类型	说明
_role	Role	玩家
_layer	E3DLayer	场景界面
_position	Point3	坐标点

示例:

-- 设置场景界面位置：将图层移动到角色头顶上方 2 米处
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    -- 创建场景 UI 图层
    local layer = GameAPI.create_scene_ui_at_point(120001, role.get_ctrl_unit().get_position(), -1.0)
    if not layer then return end

    -- 将图层移动到角色头顶上方 2 米处
    local pos = role.get_ctrl_unit().get_position() + math.Vector3(0, 2, 0)
    GameAPI.set_scene_ui_position(role, layer, pos)

    -- 收尾：3 秒后随图层销毁
    LuaAPI.call_delay_time(3.0, function()
        if layer then
            GameAPI.destroy_scene_ui(layer)
            layer = nil
        end
    end)
end)

GameAPI.set_eui_node_auto_adaption

描述: 设置节点屏幕自适应配置，顺序为：左 右 上 下。（开启百分比时，值的单位是百分比）

GameAPI.set_eui_node_auto_adaption(_node, _left_enable, _left_is_percent, _left_value, _right_enable, _right_is_percent, _right_value, _top_enable, _top_is_percent, _top_value, _bottom_enable, _bottom_is_percent, _bottom_value)

参数列表:

参数	类型	说明
_node	ENode	节点
_left_enable	Bool	启用左侧
_left_is_percent	Bool	启用百分比
_left_value	Fixed	值
_right_enable	Bool	启用右侧
_right_is_percent	Bool	启用百分比
_right_value	Fixed	值
_top_enable	Bool	启用上侧
_top_is_percent	Bool	启用百分比
_top_value	Fixed	值
_bottom_enable	Bool	启用下侧
_bottom_is_percent	Bool	启用百分比
_bottom_value	Fixed	值

示例:

-- 节点屏幕自适应：让图片四边贴合屏幕边缘（左右各贴 5%，上下各贴 3%）
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    -- 创建场景 UI 图层与图片节点
    local layer = GameAPI.create_scene_ui_at_point(120001, role.get_ctrl_unit().get_position(), -1.0)
    if not layer then return end
    local img = GameAPI.create_eui_image_at_position(170001, layer, 0.0, 0.0, 200.0, 100.0, "img_边框")
    if not img then return end

    -- 依次设置 左/右/上/下 四边自适应（参数：开关、是否百分比、偏移值）
    GameAPI.set_eui_node_auto_adaption(img,
        true, true, 5.0,   -- 左侧距父节点 5%
        true, true, 5.0,   -- 右侧距父节点 5%
        true, true, 3.0,   -- 上侧距父节点 3%
        true, true, 3.0)   -- 下侧距父节点 3%
end)

GameAPI.set_eui_node_auto_center

描述: 设置节点屏幕居中配置，顺序为：水平 垂直。（开启百分比时，值的单位是百分比）

GameAPI.set_eui_node_auto_center(_node, _horizontal_center, _horizontal_is_percent, _horizontal_value, _vertical_center, _vertical_is_percent, _vertical_value)

参数列表:

参数	类型	说明
_node	ENode	节点
_horizontal_center	Bool	启用水平居中
_horizontal_is_percent	Bool	启用百分比
_horizontal_value	Fixed	值
_vertical_center	Bool	启用垂直居中
_vertical_is_percent	Bool	启用百分比
_vertical_value	Fixed	值

示例:

-- 节点屏幕居中：让图片节点在父节点内水平垂直居中
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    -- 创建场景 UI 图层与图片节点
    local layer = GameAPI.create_scene_ui_at_point(120001, role.get_ctrl_unit().get_position(), -1.0)
    if not layer then return end
    local img = GameAPI.create_eui_image_at_position(170001, layer, 0.0, 0.0, 200.0, 100.0, "img_居中")
    if not img then return end

    -- 水平、垂直同时居中，偏移 0
    GameAPI.set_eui_node_auto_center(img, true, false, 0.0, true, false, 0.0)
end)

GameAPI.set_eui_node_bottom_auto_adaption

描述: 设置节点下侧屏幕自适应配置

GameAPI.set_eui_node_bottom_auto_adaption(_node, _enable, _is_percent, _value)

参数列表:

参数	类型	说明
_node	ENode	节点
_enable	Bool	启用下侧
_is_percent	Bool	启用百分比
_value	Fixed	值

示例:

-- 设置 EUI 节点底部自适应（UI 布局适配）
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    local node = LuaAPI.query_ui_node("技能栏")
    if node then
        -- 底部偏移 50 像素
        GameAPI.set_eui_node_bottom_auto_adaption(node, true, false, 50.0)
    end
end)

GameAPI.set_eui_node_horizontal_auto_center

描述: 设置节点水平居中配置。（开启百分比时，值的单位是百分比）

GameAPI.set_eui_node_horizontal_auto_center(_node, _enable, _is_percent, _value)

参数列表:

参数	类型	说明
_node	ENode	节点
_enable	Bool	启用水平居中
_is_percent	Bool	启用百分比
_value	Fixed	值

示例:

-- 节点水平居中：让提示图片始终水平居中显示
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    -- 创建场景 UI 图层与图片节点
    local layer = GameAPI.create_scene_ui_at_point(120001, role.get_ctrl_unit().get_position(), -1.0)
    if not layer then return end
    local img = GameAPI.create_eui_image_at_position(170001, layer, 0.0, 0.0, 200.0, 60.0, "img_提示")
    if not img then return end

    -- 水平居中（非百分比模式，偏移 0）
    GameAPI.set_eui_node_horizontal_auto_center(img, true, false, 0.0)
end)

GameAPI.set_eui_node_left_auto_adaption

描述: 设置节点左侧屏幕自适应配置。（开启百分比时，值的单位是百分比）

GameAPI.set_eui_node_left_auto_adaption(_node, _enable, _is_percent, _value)

参数列表:

参数	类型	说明
_node	ENode	节点
_enable	Bool	启用左侧
_is_percent	Bool	启用百分比
_value	Fixed	值

示例:

-- 节点左侧自适应：让血条图片的左边贴住父节点左边缘
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    -- 创建场景 UI 图层与图片节点
    local layer = GameAPI.create_scene_ui_at_point(120001, role.get_ctrl_unit().get_position(), -1.0)
    if not layer then return end
    local bar = GameAPI.create_eui_image_at_position(170001, layer, 0.0, 0.0, 300.0, 40.0, "img_血条")
    if not bar then return end

    -- 左侧与父节点左侧边界重合（偏移 0）
    GameAPI.set_eui_node_left_auto_adaption(bar, true, false, 0.0)
end)

GameAPI.set_eui_node_right_auto_adaption

描述: 设置节点右侧屏幕自适应配置

GameAPI.set_eui_node_right_auto_adaption(_node, _enable, _is_percent, _value)

参数列表:

参数	类型	说明
_node	ENode	节点
_enable	Bool	启用右侧
_is_percent	Bool	启用百分比
_value	Fixed	值

示例:

-- 节点右侧自适应：让按钮图片的右边贴住父节点右边缘
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    -- 创建场景 UI 图层与图片节点
    local layer = GameAPI.create_scene_ui_at_point(120001, role.get_ctrl_unit().get_position(), -1.0)
    if not layer then return end
    local btn_bg = GameAPI.create_eui_image_at_position(170001, layer, 0.0, 0.0, 200.0, 80.0, "img_按钮底")
    if not btn_bg then return end

    -- 右侧与父节点右侧边界重合（偏移 0）
    GameAPI.set_eui_node_right_auto_adaption(btn_bg, true, false, 0.0)
end)

GameAPI.set_eui_node_top_auto_adaption

描述: 设置节点上侧屏幕自适应配置

GameAPI.set_eui_node_top_auto_adaption(_node, _enable, _is_percent, _value)

参数列表:

参数	类型	说明
_node	ENode	节点
_enable	Bool	启用上侧
_is_percent	Bool	启用百分比
_value	Fixed	值

示例:

-- 节点上侧自适应：让标题图片贴住父节点顶部
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    -- 创建场景 UI 图层与图片节点
    local layer = GameAPI.create_scene_ui_at_point(120001, role.get_ctrl_unit().get_position(), -1.0)
    if not layer then return end
    local title = GameAPI.create_eui_image_at_position(170001, layer, 0.0, 0.0, 300.0, 50.0, "img_标题")
    if not title then return end

    -- 上侧与父节点上侧边界重合（偏移 0）
    GameAPI.set_eui_node_top_auto_adaption(title, true, false, 0.0)
end)

GameAPI.set_eui_node_vertical_auto_center

描述: 设置节点垂直居中配置。（开启百分比时，值的单位是百分比）

GameAPI.set_eui_node_vertical_auto_center(_node, _enable, _is_percent, _value)

参数列表:

参数	类型	说明
_node	ENode	节点
_enable	Bool	启用垂直居中
_is_percent	Bool	启用百分比
_value	Fixed	值

示例:

-- 节点垂直居中：让提示图片始终垂直居中显示
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    -- 创建场景 UI 图层与图片节点
    local layer = GameAPI.create_scene_ui_at_point(120001, role.get_ctrl_unit().get_position(), -1.0)
    if not layer then return end
    local img = GameAPI.create_eui_image_at_position(170001, layer, 0.0, 0.0, 200.0, 60.0, "img_提示")
    if not img then return end

    -- 垂直居中（非百分比模式，偏移 0）
    GameAPI.set_eui_node_vertical_auto_center(img, true, false, 0.0)
end)

GameAPI.set_global_wind_enabled

描述: 设置全局风场开关

GameAPI.set_global_wind_enabled(_bool_value)

参数列表:

参数	类型	说明
_bool_value	Bool	是否开启

示例:

-- 游戏初始化：进入"狂风关卡"时开启全局风场
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 开启全局风场，角色会受到持续风力影响
    GameAPI.set_global_wind_enabled(true)

    -- 示例：10 秒后关闭风场
    LuaAPI.call_delay_time(10.0, function()
        GameAPI.set_global_wind_enabled(false)
    end)
end)

GameAPI.set_global_wind_force

描述: 设置全局风场方向力

GameAPI.set_global_wind_force(_x_value, _y_value)

参数列表:

参数	类型	说明
_x_value	Fixed	X方向力
_y_value	Fixed	Y方向力

示例:

-- 游戏初始化：设置全局风场的推挤方向与力度
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 先开启全局风场
    GameAPI.set_global_wind_enabled(true)

    -- 注意：方向力为 0 时风场不产生推挤效果
    -- 设置风场方向力：X 方向 1.0，Y 方向 0.5（向右上方吹）
    GameAPI.set_global_wind_force(1.0, 0.5)
end)

GameAPI.set_global_wind_frequency

描述: 设置全局风场频率

GameAPI.set_global_wind_frequency(_fixed_value)

参数列表:

参数	类型	说明
_fixed_value	Fixed	频率

示例:

-- 游戏初始化：调整全局风场的吹拂频率
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 开启全局风场
    GameAPI.set_global_wind_enabled(true)

    -- 频率越大风力变化越快，可配合 force 制造强风效果
    -- 频率 2.0：风场脉冲节奏更快，受力起伏更明显
    GameAPI.set_global_wind_frequency(2.0)
end)

GameAPI.set_env_time_running_enabled

描述: 设置环境时间是否自动流逝

GameAPI.set_env_time_running_enabled(_enabled)

参数列表:

参数	类型	说明
_enabled	Bool	是否自动流逝

示例:

-- 游戏初始化：暂停环境时间自动流逝
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 暂停昼夜自动切换，便于固定光照进行演出
    GameAPI.set_env_time_running_enabled(false)

    -- 示例：5 秒后恢复自动流逝
    LuaAPI.call_delay_time(5.0, function()
        GameAPI.set_env_time_running_enabled(true)
    end)
end)

GameAPI.set_env_time

描述: 设置环境时间

GameAPI.set_env_time(_target_time, _duration, _direction)

参数列表:

参数	类型	说明
_target_time	Fixed	目标时刻
_duration	Fixed	过渡时间
_direction	Bool	是否正向

示例:

-- 游戏初始化：进入"正午"机关时强制切换环境时间
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 目标时刻 12.0（0~24 小时制），2 秒内过渡
    local target_time = 12.0
    local duration = 2.0

    -- 正向推移到正午（第三个参数 true 表示时间正向流动）
    GameAPI.set_env_time(target_time, duration, true)
end)

GameAPI.set_env_time_ratio

描述: 设置环境时间流逝速度

GameAPI.set_env_time_ratio(_time_ratio)

参数列表:

参数	类型	说明
_time_ratio	Fixed	流逝速度

示例:

-- 游戏初始化：白天加速、夜晚恢复的环境节奏控制
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 设置时间流逝速度为 2 倍（1.0 为正常速度）
    GameAPI.set_env_time_ratio(2.0)

    -- 示例：10 秒后恢复为正常流逝速度
    LuaAPI.call_delay_time(10.0, function()
        GameAPI.set_env_time_ratio(1.0)
    end)
end)

GameAPI.stop_dynamic_text

描述: 停止跳字

stop_dynamic_text(_text_id: DynamicTextID) -> void

参数列表:

参数	类型	说明
_text_id	DynamicTextID	DynamicTextID

示例:

-- 停止跳字：伤害飘字播放 1 秒后提前终止
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    -- 在角色头顶播放伤害跳字并保存ID
    local text_id = role.show_dynamic_text("伤害: -100", math.Vector3(0, 2, 0), GlobalAPI.str_to_color("ff0000"), 2.0, 0)
    if text_id then
        -- 1 秒后主动停止跳字
        LuaAPI.call_delay_time(1.0, function()
            GameAPI.stop_dynamic_text(text_id)
        end)
    end
end)

GameAPI.stop_sound

描述: 停止播放音效

GameAPI.stop_sound(_assigned_id)

参数列表:

参数	类型	说明
_assigned_id	SoundID	音效ID

示例:

-- 播放一段 3D 音效，5 秒后主动停止（管理长音效生命周期）
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    -- 播放 3D 音效并保存实例ID（5129 为音效配置ID）
    local sound_id = GameAPI.play_3d_sound(role.get_ctrl_unit().get_position(), 5129, -1.0, 100.0)
    if sound_id then
        -- 5 秒后停止该音效
        LuaAPI.call_delay_time(5.0, function()
            GameAPI.stop_sound(sound_id)
        end)
    end
end)

GameAPI.get_unit

描述: 获取单位

GameAPI.get_unit(_unit_id)

参数列表:

参数	类型	说明
_unit_id	UnitID	单位ID

返回值:

• 类型: Unit
• 说明: 单位

示例:

-- 按单位 ID 获取单位对象（ID 可由 get_unit_id 获得）
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local target = LuaAPI.query_unit("怪物")
    if target then
        local unit_id = LuaAPI.get_unit_id(target)
        local unit = GameAPI.get_unit(unit_id)
        if unit then
            unit.set_physics_active(true)
        end
    end
end)

GameAPI.ability_prefab_get_desc

描述: 获取技能预设描述

GameAPI.ability_prefab_get_desc(_ability_id)

参数列表:

参数	类型	说明
_ability_id	AbilityKey	技能编号

返回值:

• 类型: Str
• 说明: 技能描述

示例:

-- 读取技能预设描述，用于技能选择界面展示
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 150001 为技能预设 key（可在编辑器技能配置中查看）
    local desc = GameAPI.ability_prefab_get_desc(150001)
    if desc and desc ~= "" then
        -- 描述非空时展示给玩家
        GlobalAPI.show_tips("技能说明：" .. desc, 2.0)
    else
        -- 未配置描述时输出调试日志，便于排查
        GlobalAPI.debug("技能 150001 未配置描述")
    end
end)

GameAPI.ability_prefab_get_kv_by_type

描述: 获取技能预设的自定义值

GameAPI.ability_prefab_get_kv_by_type(_value_type, _key, _prop)

参数列表:

参数	类型	说明
_value_type	ValueType	值类型
_key	AbilityKey	技能编号
_prop	Str	名称

返回值:

• 类型: ETypeMeta
• 说明: 自定义值

示例:

-- 读取技能预设自定义值：技能冷却时间
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 从技能预设 100001 中读取 Fixed 类型的 "cd" 自定义值（单位：秒）
    local cd = GameAPI.ability_prefab_get_kv_by_type(Enums.ValueType.Fixed, 100001, "cd")
    if cd then
        -- 冷却值存在时展示给玩家
        GlobalAPI.show_tips("技能冷却：" .. tostring(cd) .. " 秒", 2.0)
    else
        GlobalAPI.warning("技能 100001 未配置 cd 自定义值")
    end
end)

GameAPI.ability_prefab_get_name

描述: 获取技能预设名称

GameAPI.ability_prefab_get_name(_ability_id)

参数列表:

参数	类型	说明
_ability_id	AbilityKey	技能编号

返回值:

• 类型: Str
• 说明: 技能名称

示例:

-- 读取技能预设名称，用于技能栏按钮文本
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 150001 为技能预设 key
    local name = GameAPI.ability_prefab_get_name(150001)
    if name and name ~= "" then
        GlobalAPI.show_tips("获得技能：" .. name, 2.0)
    else
        -- 名称缺失时降级展示默认文案
        GlobalAPI.debug("技能 150001 未配置名称")
    end
end)

GameAPI.ability_prefab_get_prop_by_type

描述: 获取技能预设的属性

GameAPI.ability_prefab_get_prop_by_type(_value_type, _key, _prop)

参数列表:

参数	类型	说明
_value_type	ValueType	值类型
_key	AbilityKey	技能编号
_prop	Str	名称

返回值:

• 类型: ETypeMeta
• 说明: 属性值

示例:

-- 读取技能预设属性（编辑器通用属性面板中的配置）
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 读取 Int 类型的 "max_level" 属性，判断技能可升级次数
    local max_level = GameAPI.ability_prefab_get_prop_by_type(Enums.ValueType.Int, 150001, "max_level")
    if max_level then
        GlobalAPI.debug("技能最大等级：" .. tostring(max_level))
    else
        GlobalAPI.warning("技能 150001 未配置 max_level 属性")
    end
end)

GameAPI.ability_prefab_has_kv

描述: 技能预设是否存在自定义值

GameAPI.ability_prefab_has_kv(_ability_key, _prop)

参数列表:

参数	类型	说明
_ability_key	AbilityKey	技能编号
_prop	Str	名称

返回值:

• 类型: Bool
• 说明: 是否存在

示例:

-- 先判断技能预设是否配置了自定义值，再决定是否读取
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 仅在存在 "cd" 自定义值时读取，避免拿到无效数据
    if GameAPI.ability_prefab_has_kv(150001, "cd") then
        local cd = GameAPI.ability_prefab_get_kv_by_type(Enums.ValueType.Fixed, 150001, "cd")
        GlobalAPI.debug("技能 cd：" .. tostring(cd))
    else
        GlobalAPI.debug("技能 150001 未配置 cd，使用默认冷却")
    end
end)

GameAPI.create_obstacle_by_geometry

描述: 创建一个组件（自定义几何）

GameAPI.create_obstacle_by_geometry(_u_key, _pos, _rotation, _scale, _role, _geometry_path, _mat_path, _sel_skin)

参数列表:

参数	类型	说明
_u_key	UnitKey	组件编号
_pos	Vector3	位置
_rotation	Quaternion	旋转
_scale	Vector3	缩放
_role	Role	所属玩家
_geometry_path	Str	自定义几何体路径
_mat_path	Str	覆盖材质路径
_sel_skin	Int	材质编号（与材质路径二选一)

返回值:

• 类型: Obstacle
• 说明: 创建的组件

示例:

-- 使用自定义几何/材质资源创建可碰撞组件（路径在资源面板中配置）
-- 注意：res/geometry/box 为示意素材路径，需替换为资源面板中实际配置的几何/材质资源
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    -- 创建带自定义几何的组件，指定几何与材质路径、皮肤编号 1
    local obstacle = GameAPI.create_obstacle_by_geometry(100001, role.get_ctrl_unit().get_position(), math.Quaternion(0, 0, 0), math.Vector3(1, 1, 1), role, "res/geometry/box", "res/mat/wood", 1)
    if obstacle then
        role.show_tips("自定义几何组件创建成功", 2.0)
    end
end)

GameAPI.create_obstacle_from_geometry

描述: 创建一个组件（自定义几何）

GameAPI.create_obstacle_from_geometry(_u_key, _pos, _rotation, _scale, _role, _geometry_path)

参数列表:

参数	类型	说明
_u_key	UnitKey	组件编号
_pos	Vector3	位置
_rotation	Quaternion	旋转
_scale	Vector3	缩放
_role	Role	所属玩家
_geometry_path	Str	自定义几何体路径

返回值:

• 类型: Obstacle
• 说明: 创建的组件

示例:

-- 从已注册的几何体创建场景组件：注册方块几何后直接生成
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    -- 先注册边长 1 米的方块几何体，拿到几何路径字符串
    local geometry_path = GameAPI.register_geometry_box(1.0, 0.0, 0, true, {})
    if not geometry_path then return end

    -- 用该路径创建组件（几何与材质同源于注册结果）
    local obstacle = GameAPI.create_obstacle_from_geometry(100001, role.get_ctrl_unit().get_position(), math.Quaternion(0, 0, 0), math.Vector3(1, 1, 1), role, geometry_path)
    if obstacle then
        role.show_tips("几何组件创建成功", 2.0)
    end
end)

GameAPI.creature_prefab_get_kv_by_type

描述: 获取生物预设的自定义值

GameAPI.creature_prefab_get_kv_by_type(_value_type, _key, _prop)

参数列表:

参数	类型	说明
_value_type	ValueType	值类型
_key	CreatureKey	生物编号
_prop	Str	名称

返回值:

• 类型: ETypeMeta
• 说明: 自定义值

示例:

-- 获取生物预置的自定义值（读取策划配置的 KV）
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local max_hp = GameAPI.creature_prefab_get_kv_by_type(Enums.ValueType.Fixed, 100001, "max_hp")
    LuaAPI.log("生物最大血量: " .. tostring(max_hp), 0)
end)

GameAPI.creature_prefab_get_prop_by_type

描述: 获取生物预设的属性

GameAPI.creature_prefab_get_prop_by_type(_value_type, _key, _prop)

参数列表:

参数	类型	说明
_value_type	ValueType	值类型
_key	CreatureKey	生物编号
_prop	Str	名称

返回值:

• 类型: ETypeMeta
• 说明: 属性值

示例:

-- 读取生物预设属性：怪物血量上限
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 100001 为生物预设 key，读取 Int 类型的 "max_hp" 属性
    local max_hp = GameAPI.creature_prefab_get_prop_by_type(Enums.ValueType.Int, 100001, "max_hp")
    if max_hp then
        GlobalAPI.debug("怪物预设最大血量：" .. tostring(max_hp))
    else
        GlobalAPI.warning("生物预设 100001 未配置 max_hp 属性")
    end
end)

GameAPI.creature_prefab_has_kv

描述: 生物预设是否存在自定义值

GameAPI.creature_prefab_has_kv(_unit_key, _prop)

参数列表:

参数	类型	说明
_unit_key	CreatureKey	生物编号
_prop	Str	名称

返回值:

• 类型: Bool
• 说明: 是否存在

示例:

-- 判断生物预设是否存在自定义值，例如是否可驯服
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 存在 "可驯服" 标记时才读取具体值
    if GameAPI.creature_prefab_has_kv(100001, "可驯服") then
        local tame = GameAPI.creature_prefab_get_kv_by_type(Enums.ValueType.Bool, 100001, "可驯服")
        GlobalAPI.debug("该生物可驯服：" .. tostring(tame))
    else
        GlobalAPI.debug("生物 100001 未配置可驯服标记")
    end
end)

GameAPI.customtriggerspace_prefab_get_kv_by_type

描述: 获取触发区域预设的自定义值

GameAPI.customtriggerspace_prefab_get_kv_by_type(_value_type, _key, _prop)

参数列表:

参数	类型	说明
_value_type	ValueType	值类型
_key	CustomTriggerSpaceKey	逻辑体编号
_prop	Str	名称

返回值:

• 类型: ETypeMeta
• 说明: 自定义值

示例:

-- 读取触发区域预设的自定义值：区域半径
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 110001 为触发区域预设 key，读取 Fixed 类型的 "radius"
    local radius = GameAPI.customtriggerspace_prefab_get_kv_by_type(Enums.ValueType.Fixed, 110001, "radius")
    if radius then
        GlobalAPI.debug("触发区域半径：" .. tostring(radius))
    else
        GlobalAPI.warning("触发区域 110001 未配置 radius")
    end
end)

GameAPI.customtriggerspace_prefab_get_prop_by_type

描述: 获取触发区域预设的属性

GameAPI.customtriggerspace_prefab_get_prop_by_type(_value_type, _key, _prop)

参数列表:

参数	类型	说明
_value_type	ValueType	值类型
_key	CustomTriggerSpaceKey	逻辑体编号
_prop	Str	名称

返回值:

• 类型: ETypeMeta
• 说明: 属性值

示例:

-- 读取触发区域预设属性，用于玩法参数校验
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 读取 Fixed 类型的 "duration" 属性（区域有效时长）
    local duration = GameAPI.customtriggerspace_prefab_get_prop_by_type(Enums.ValueType.Fixed, 110001, "duration")
    if duration then
        GlobalAPI.debug("触发区域持续时间：" .. tostring(duration))
    else
        GlobalAPI.debug("触发区域 110001 未配置 duration，使用默认值")
    end
end)

GameAPI.customtriggerspace_prefab_has_kv

描述: 触发区域预设是否存在自定义值

GameAPI.customtriggerspace_prefab_has_kv(_key, _prop)

参数列表:

参数	类型	说明
_key	CustomTriggerSpaceKey	触发区域编号
_prop	Str	名称

返回值:

• 类型: Bool
• 说明: 是否存在

示例:

-- 判断触发区域预设是否配置了自定义值（如危险标记）
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 存在 "is_danger" 标记时按危险区域处理
    if GameAPI.customtriggerspace_prefab_has_kv(110001, "is_danger") then
        GlobalAPI.debug("该触发区域为危险区域")
    else
        GlobalAPI.debug("该触发区域为安全区域")
    end
end)

GameAPI.decoration_prefab_get_kv_by_type

描述: 获取装饰物预设的自定义值

GameAPI.decoration_prefab_get_kv_by_type(_value_type, _key, _prop)

参数列表:

参数	类型	说明
_value_type	ValueType	值类型
_key	DecorationKey	装饰物编号
_prop	Str	名称

返回值:

• 类型: ETypeMeta
• 说明: 自定义值

示例:

-- 读取装饰物预设的自定义缩放，用于摆放时对齐
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 200001 为装饰物预设 key，读取 Vector3 类型的 "scale"
    local scale = GameAPI.decoration_prefab_get_kv_by_type(Enums.ValueType.Vector3, 200001, "scale")
    if scale then
        -- 按预设缩放输出调试信息
        GlobalAPI.debug("装饰物缩放：" .. tostring(scale.x) .. ", " .. tostring(scale.y) .. ", " .. tostring(scale.z))
    else
        GlobalAPI.debug("装饰物 200001 未配置 scale，使用默认缩放")
    end
end)

GameAPI.decoration_prefab_has_kv

描述: 装饰物预设是否存在自定义值

GameAPI.decoration_prefab_has_kv(_decoration_key, _prop)

参数列表:

参数	类型	说明
_decoration_key	DecorationKey	装饰物编号
_prop	Str	名称

返回值:

• 类型: Bool
• 说明: 是否存在

示例:

-- 判断装饰物预设是否可交互，决定是否播放提示
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 存在 "可交互" 标记时向玩家提示
    if GameAPI.decoration_prefab_has_kv(200001, "可交互") then
        GlobalAPI.show_tips("该装饰物可交互", 2.0)
    else
        GlobalAPI.debug("装饰物 200001 不可交互")
    end
end)

GameAPI.delay_destroy_vehicle

描述: 删除载具

GameAPI.delay_destroy_vehicle(_unit)

参数列表:

参数	类型	说明
_unit	Vehicle	载具

示例:

-- 延迟销毁载具：创建载具并立即进入回收流程
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    -- 创建载具（500001 为载具预设ID）
    local vehicle = GameAPI.create_vehicle(500001, role.get_ctrl_unit().get_position() + math.Vector3(0, 0, 3), math.Vector3(0, 0, 1), role)
    if vehicle then
        -- 触发延迟销毁，引擎会在合适时机移除载具
        GameAPI.delay_destroy_vehicle(vehicle)
        role.show_tips("载具已回收", 2.0)
    end
end)

GameAPI.eggy_team_add_bind_creature

描述: (蛋仔小队专用）绑定生物到角色

GameAPI.eggy_team_add_bind_creature(_char, _creature, _pos)

参数列表:

参数	类型	说明
_char	Character	角色
_creature	Creature	生物
_pos	Vector3	相对位置

示例:

-- 蛋仔小队专用：把一只生物绑定到 NPC 角色身边，形成跟随队列
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local npc = LuaAPI.query_unit("NPC队长")  -- Character 继承自 LifeEntity，代表NPC角色单位
    if not npc then return end

    -- 创建一只生物（100001）并绑定到 NPC，偏移 (0,0,1)
    local creature = GameAPI.create_creature_fixed_scale(100001, npc.get_position(), math.Quaternion(0, 0, 0), 1.0, role)
    if creature then
        GameAPI.eggy_team_add_bind_creature(npc, creature, math.Vector3(0, 0, 1))
    end
end)

GameAPI.eggy_team_remove_bind_creature

描述: (蛋仔小队专用）移除绑定生物到角色

GameAPI.eggy_team_remove_bind_creature(_char, _creature)

参数列表:

参数	类型	说明
_char	Character	角色
_creature	Creature	生物

示例:

-- 蛋仔小队专用：解除生物与 NPC 角色的绑定关系
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local npc = LuaAPI.query_unit("NPC队长")  -- Character 继承自 LifeEntity，代表NPC角色单位
    if not npc then return end

    -- 先绑定一只生物，再演示解除绑定
    local creature = GameAPI.create_creature_fixed_scale(100001, npc.get_position(), math.Quaternion(0, 0, 0), 1.0, role)
    if creature then
        GameAPI.eggy_team_add_bind_creature(npc, creature, math.Vector3(0, 0, 1))
        GameAPI.eggy_team_remove_bind_creature(npc, creature)
    end
end)

GameAPI.eggy_team_set_surround_follower_angle

描述: (蛋仔小队专用）设置队形旋转角度

GameAPI.eggy_team_set_surround_follower_angle(_char, _degree)

参数列表:

参数	类型	说明
_char	Character	角色
_degree	Fixed	角度

示例:

-- 蛋仔小队专用：设置环绕队形的整体旋转角度（单位：度）
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local npc = LuaAPI.query_unit("NPC队长")  -- Character 继承自 LifeEntity，代表NPC角色单位
    if not npc then return end

    -- 将环绕队形整体旋转 30 度
    GameAPI.eggy_team_set_surround_follower_angle(npc, 30.0)
end)

GameAPI.eggy_team_set_surround_follower_enable_rot

描述: (蛋仔小队专用）设置队形是否跟随旋转

GameAPI.eggy_team_set_surround_follower_enable_rot(_char, _enable)

参数列表:

参数	类型	说明
_char	Character	角色
_enable	Bool	开关

示例:

-- 蛋仔小队专用：开启/关闭队形跟随角色朝向旋转
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local npc = LuaAPI.query_unit("NPC队长")  -- Character 继承自 LifeEntity，代表NPC角色单位
    if not npc then return end

    -- 开启跟随旋转，环绕生物随角色转向
    GameAPI.eggy_team_set_surround_follower_enable_rot(npc, true)
end)

GameAPI.eggy_team_set_surround_follower_speed

描述: (蛋仔小队专用）设置绑定跟随速度

GameAPI.eggy_team_set_surround_follower_speed(_char, _speed)

参数列表:

参数	类型	说明
_char	Character	角色
_speed	Fixed	衰减速度

示例:

-- 蛋仔小队专用：调整绑定生物跟随角色的移动速度
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local npc = LuaAPI.query_unit("NPC队长")  -- Character 继承自 LifeEntity，代表NPC角色单位
    if not npc then return end

    -- 速度倍率设为 1.5，加快跟随队列合拢
    GameAPI.eggy_team_set_surround_follower_speed(npc, 1.5)
end)

GameAPI.enable_physics_ccd

描述: 开启/关闭物理CCD

GameAPI.enable_physics_ccd(_enable)

参数列表:

参数	类型	说明
_enable	Bool	开关

示例:

-- 开启连续碰撞检测（高速移动物体防穿透，代价是更高开销）
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 全场景开启 CCD，防止高速物体穿透墙体
    GameAPI.enable_physics_ccd(true)
end)

GameAPI.equipment_prefab_get_kv_by_type

描述: 获取物品预设的自定义值

GameAPI.equipment_prefab_get_kv_by_type(_value_type, _key, _prop)

参数列表:

参数	类型	说明
_value_type	ValueType	值类型
_key	EquipmentKey	物品编号
_prop	Str	名称

返回值:

• 类型: ETypeMeta
• 说明: 自定义值

示例:

-- 读取物品预设的攻击力自定义值，用于属性预览
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 400001 为物品预设 key，读取 Fixed 类型的 "attack"
    local atk = GameAPI.equipment_prefab_get_kv_by_type(Enums.ValueType.Fixed, 400001, "attack")
    if atk then
        GlobalAPI.debug("物品攻击力：" .. tostring(atk))
    else
        GlobalAPI.debug("物品 400001 未配置 attack")
    end
end)

GameAPI.equipment_prefab_has_kv

描述: 物品预设是否存在自定义值

GameAPI.equipment_prefab_has_kv(_equipment_key, _prop)

参数列表:

参数	类型	说明
_equipment_key	EquipmentKey	物品编号
_prop	Str	名称

返回值:

• 类型: Bool
• 说明: 是否存在

示例:

-- 判断物品预设是否配置了自定义值（如是否可堆叠）
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 存在 "可堆叠" 标记时按堆叠物品处理
    if GameAPI.equipment_prefab_has_kv(400001, "可堆叠") then
        GlobalAPI.debug("该物品可堆叠")
    else
        GlobalAPI.debug("该物品不可堆叠")
    end
end)

GameAPI.get_all_camps

描述: 获取所有阵营

GameAPI.get_all_camps()

返回值:

• 类型: ListCamp
• 说明: 阵营列表

示例:

-- 获取所有阵营并逐个打印，用于阵营系统调试
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 返回当前地图配置的所有阵营列表
    local camps = GameAPI.get_all_camps()
    if camps then
        for _, camp in ipairs(camps) do
            GlobalAPI.debug("阵营：" .. tostring(camp))
        end
    else
        GlobalAPI.debug("当前地图未配置阵营")
    end
end)

GameAPI.get_camp

描述: 获取阵营

GameAPI.get_camp(_camp_id)

参数列表:

参数	类型	说明
_camp_id	CampID	阵营ID

返回值:

• 类型: Camp
• 说明: 阵营

示例:

-- 获取阵营对象（阵营关系判断/阵营信息查询）
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local camp = GameAPI.get_camp(1)
    if camp then
        LuaAPI.log("阵营名称: " .. tostring(camp.get_name()), 0)
    end
end)

GameAPI.get_camp_relation

描述: 获取阵营关系

GameAPI.get_camp_relation(_camp1, _camp2)

参数列表:

参数	类型	说明
_camp1	Camp	阵营
_camp2	Camp	阵营

返回值:

• 类型: CampRelationType
• 说明: 阵营关系

示例:

-- 检查两个阵营的关系（敌对/友好），用于友伤判断
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 先通过阵营编号获取阵营对象（1、2 为编辑器中的阵营序号）
    local camp_1 = GameAPI.get_camp(1)
    local camp_2 = GameAPI.get_camp(2)
    if camp_1 and camp_2 then
        local relation = GameAPI.get_camp_relation(camp_1, camp_2)
        GlobalAPI.debug("阵营 1 与阵营 2 的关系：" .. tostring(relation))
    else
        GlobalAPI.debug("阵营未配置完整")
    end
end)

GameAPI.get_eui_child_by_index

描述: 根据索引获取UI节点的子UI节点

GameAPI.get_eui_child_by_index(_node, _index)

参数列表:

参数	类型	说明
_node	ENode	UI节点
_index	Int	索引

返回值:

• 类型: ENode
• 说明: 子UI节点

示例:

-- 按索引获取子节点：在图片节点下创建子节点后，通过索引取回操作
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    -- 创建场景 UI 图层
    local layer = GameAPI.create_scene_ui_at_point(120001, role.get_ctrl_unit().get_position(), -1.0)
    if not layer then return end

    -- 创建父节点，并挂一个文本子节点
    local img = GameAPI.create_eui_image_at_position(170001, layer, 0.0, 0.0, 200.0, 80.0, "img_面板")
    local child = GameAPI.create_eui_label_at_position(180001, img, 0.0, 0.0, 100.0, 30.0, "label_标题", "标题")
    if not child then return end

    -- 按索引取回子节点（子节点从 1 开始编号）
    local got = GameAPI.get_eui_child_by_index(img, 1)
    if got then
        -- 动态节点仅支持 ENode 通用操作（此处演示存在性判断）
        print("取回子节点: " .. tostring(got))
    end
end)

GameAPI.get_eui_children_count

描述: 获取UI节点的子UI节点数量

GameAPI.get_eui_children_count(_node)

参数列表:

参数	类型	说明
_node	ENode	UI节点

返回值:

• 类型: Int
• 说明: 数量

示例:

-- 获取子节点数量：创建容器后校验子节点挂载个数
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    -- 创建场景 UI 图层
    local layer = GameAPI.create_scene_ui_at_point(120001, role.get_ctrl_unit().get_position(), -1.0)
    if not layer then return end

    -- 父节点下挂两个子节点
    local img = GameAPI.create_eui_image_at_position(170001, layer, 0.0, 0.0, 300.0, 120.0, "img_面板")
    GameAPI.create_eui_label_at_position(180001, img, 0.0, 0.0, 100.0, 30.0, "label_标题", "标题")
    GameAPI.create_eui_label_at_position(180001, img, 0.0, 0.0, 100.0, 30.0, "label_副标题", "副标题")

    -- 获取子节点数量并提示
    local count = GameAPI.get_eui_children_count(img)
    role.show_tips("子节点数量: " .. tostring(count), 2.0)
end)

GameAPI.get_goods_list

描述: 获取付费商品信息列表

GameAPI.get_goods_list()

返回值:

• 类型: List
• 说明: 商品列表

示例:

-- 获取商店商品列表：按名称建立索引，供购买逻辑查询
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local goods = {}
    for _, good in ipairs(GameAPI.get_goods_list()) do
        goods[good.name] = good
    end
    -- 按名称查询商品
    local love_gold = goods["爱心金币"]
    if love_gold then
        LuaAPI.log("商品ID: " .. tostring(love_gold.goodsId), 0)
    end
end)

GameAPI.get_play_env

描述: 获取当前游玩环境

GameAPI.get_play_env()

返回值:

• 类型: Int
• 说明: 游玩环境（PlayEnvType: 0单人试玩 1多人试玩 2正式游玩）

示例:

-- 获取当前游玩环境，按环境编号走不同逻辑
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 返回当前游玩环境编号（含义见玩法文档）
    local env = GameAPI.get_play_env()
    if env then
        GlobalAPI.debug("当前游玩环境编号：" .. tostring(env))
    else
        GlobalAPI.warning("获取游玩环境失败")
    end
end)

GameAPI.get_sheet_cell_value

描述: 获取表格值

GameAPI.get_sheet_cell_value(_value_type, _sheet_id, _key1, _key2)

参数列表:

参数	类型	说明
_value_type	ValueType	值类型
_sheet_id	SheetID	表格
_key1	Int	行索引
_key2	Str	列索引

返回值:

• 类型: ETypeMeta
• 说明: 自定义值

示例:

-- 游戏初始化：从表格读取玩家分数
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local sheet = GameAPI.create_sheet()
    if not sheet then return end

    -- 表格须先声明列，再写入/读取
    GameAPI.add_sheet_column(sheet, "key_001", "Int")
    GameAPI.set_sheet_cell_value(Enums.ValueType.Int, sheet, 1, "key_001", 100)

    -- 读取第 1 行 key_001 列的整数
    local score = GameAPI.get_sheet_cell_value(
        Enums.ValueType.Int,   -- 值类型（整数）
        sheet,                 -- 表格编号
        1,                     -- 行索引
        "key_001"              -- 列索引
    )
    -- score 为 ETypeMeta，按声明类型（此处为 Int）取值使用
    if score then
        LuaAPI.log("读取分数: " .. tostring(score), 0)
    end
end)

GameAPI.get_unit_id_by_name

描述: 获取单位ID

GameAPI.get_unit_id_by_name(_name)

参数列表:

参数	类型	说明
_name	Str	单位名称

返回值:

• 类型: UnitID
• 说明: 单位ID

示例:

-- 按名称查询单位 ID：注册进入该触发区域的监听事件
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- "传送门区域" 为场景中的单位名，可替换为实际单位名
    local unit_id = GameAPI.get_unit_id_by_name("传送门区域")
    if not unit_id then return end

    -- 以单位 ID 为参数注册"角色进入"事件
    LuaAPI.global_register_trigger_event(
        { EVENT.ANY_LIFEENTITY_TRIGGER_SPACE, Enums.TriggerSpaceEventType.ENTER, unit_id },
        function(_, _, data)
            local character = data.event_unit
            if character then
                print("有生命体进入了触发区域")
            end
        end
    )
end)

GameAPI.has_global_kv

描述: 是否有全局变量

GameAPI.has_global_kv(_var_name)

参数列表:

参数	类型	说明
_var_name	Str	变量名称

返回值:

• 类型: Bool
• 说明: 是否含有全局变量

示例:

-- 判断全局变量是否存在，用于关卡进度恢复等存档判断
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- "关卡进度" 为策划配置的全局变量名
    if GameAPI.has_global_kv("关卡进度") then
        LuaAPI.log("存在全局变量：关卡进度", 0)
    else
        LuaAPI.log("全局变量不存在，走首次开局流程", 0)
    end
end)

GameAPI.modifier_prefab_get_desc

描述: 获取效果预设描述

GameAPI.modifier_prefab_get_desc(_modifier_key)

参数列表:

参数	类型	说明
_modifier_key	ModifierKey	效果编号

返回值:

• 类型: Str
• 说明: 效果描述

示例:

-- 读取效果预设描述，用于 BUFF 图标悬浮说明
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 600001 为效果预设 key
    local desc = GameAPI.modifier_prefab_get_desc(600001)
    if desc and desc ~= "" then
        GlobalAPI.show_tips("效果说明：" .. desc, 2.0)
    else
        GlobalAPI.debug("效果 600001 未配置描述")
    end
end)

GameAPI.modifier_prefab_get_kv_by_type

描述: 获取效果预设的自定义值

GameAPI.modifier_prefab_get_kv_by_type(_value_type, _key, _prop)

参数列表:

参数	类型	说明
_value_type	ValueType	值类型
_key	ModifierKey	效果编号
_prop	Str	名称

返回值:

• 类型: ETypeMeta
• 说明: 自定义值

示例:

-- 读取效果预设自定义值：移动速度加成
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 从效果预设 300001 中读取 Fixed 类型的 "move_speed"
    local speed = GameAPI.modifier_prefab_get_kv_by_type(Enums.ValueType.Fixed, 300001, "move_speed")
    if speed then
        GlobalAPI.debug("移速加成：" .. tostring(speed))
    else
        GlobalAPI.debug("效果 300001 未配置 move_speed")
    end
end)

GameAPI.modifier_prefab_get_name

描述: 获取效果预设名称

GameAPI.modifier_prefab_get_name(_modifier_key)

参数列表:

参数	类型	说明
_modifier_key	ModifierKey	效果编号

返回值:

• 类型: Str
• 说明: 效果名称

示例:

-- 读取效果预设名称，用于 BUFF 栏展示
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 600001 为效果预设 key
    local name = GameAPI.modifier_prefab_get_name(600001)
    if name and name ~= "" then
        GlobalAPI.debug("获得效果：" .. name)
    else
        GlobalAPI.debug("效果 600001 未配置名称")
    end
end)

GameAPI.modifier_prefab_get_prop_by_type

描述: 获取效果预设的属性

GameAPI.modifier_prefab_get_prop_by_type(_value_type, _key, _prop)

参数列表:

参数	类型	说明
_value_type	ValueType	值类型
_key	ModifierKey	效果编号
_prop	Str	名称

返回值:

• 类型: ETypeMeta
• 说明: 属性值

示例:

-- 读取效果预设属性，例如持续时间
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 读取 Fixed 类型的 "duration" 属性（效果持续秒数）
    local duration = GameAPI.modifier_prefab_get_prop_by_type(Enums.ValueType.Fixed, 600001, "duration")
    if duration then
        GlobalAPI.debug("效果持续时间：" .. tostring(duration))
    else
        GlobalAPI.warning("效果 600001 未配置 duration 属性")
    end
end)

GameAPI.modifier_prefab_has_kv

描述: 效果预设是否存在自定义值

GameAPI.modifier_prefab_has_kv(_modifier_key, _prop)

参数列表:

参数	类型	说明
_modifier_key	ModifierKey	效果编号
_prop	Str	名称

返回值:

• 类型: Bool
• 说明: 是否存在

示例:

-- 判断效果预设是否配置了自定义值（如是否可叠加）
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 存在 "stackable" 标记时按可叠加效果处理
    if GameAPI.modifier_prefab_has_kv(600001, "stackable") then
        GlobalAPI.debug("该效果可叠加")
    else
        GlobalAPI.debug("该效果不可叠加")
    end
end)

GameAPI.obstacle_prefab_get_kv_by_type

描述: 获取组件预设的自定义值

GameAPI.obstacle_prefab_get_kv_by_type(_value_type, _key, _prop)

参数列表:

参数	类型	说明
_value_type	ValueType	值类型
_key	ObstacleKey	组件编号
_prop	Str	名称

返回值:

• 类型: ETypeMeta
• 说明: 自定义值

示例:

-- 获取障碍物预置的自定义值（读取策划配置的 KV）
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local offset = GameAPI.obstacle_prefab_get_kv_by_type(Enums.ValueType.Vector3, 100001, "build_offset")
    if offset then
        LuaAPI.log("建造偏移: " .. tostring(offset), 0)
    end
end)

GameAPI.obstacle_prefab_get_prop_by_type

描述: 获取组件预设的属性

GameAPI.obstacle_prefab_get_prop_by_type(_value_type, _key, _prop)

参数列表:

参数	类型	说明
_value_type	ValueType	值类型
_key	ObstacleKey	组件编号
_prop	Str	名称

返回值:

• 类型: ETypeMeta
• 说明: 属性值

示例:

-- 读取组件预设属性，如墙体高度
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 200001 为组件预设 key，读取 Fixed 类型的 "height"
    local height = GameAPI.obstacle_prefab_get_prop_by_type(Enums.ValueType.Fixed, 200001, "height")
    if height then
        GlobalAPI.debug("组件高度：" .. tostring(height))
    else
        GlobalAPI.warning("组件 200001 未配置 height 属性")
    end
end)

GameAPI.obstacle_prefab_has_kv

描述: 组件预设是否存在自定义值

GameAPI.obstacle_prefab_has_kv(_key, _prop)

参数列表:

参数	类型	说明
_key	ObstacleKey	组件编号
_prop	Str	名称

返回值:

• 类型: Bool
• 说明: 是否存在

示例:

-- 判断组件预设是否存在自定义值（如是否可破坏）
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 存在 "可破坏" 标记时按可破坏组件处理
    if GameAPI.obstacle_prefab_has_kv(200001, "可破坏") then
        GlobalAPI.debug("该组件可被破坏")
    else
        GlobalAPI.debug("该组件不可破坏")
    end
end)

GameAPI.play_3d_sound

描述: 单位开始播放3d音效

GameAPI.play_3d_sound(_position, _sound_key, _duration, _volume)

参数列表:

参数	类型	说明
_position	Point3	发声位置
_sound_key	SoundKey	声音编号
_duration	Fixed	持续时间
_volume	Fixed	音量

返回值:

• 类型: SoundID
• 说明: 音效ID

示例:

-- 在位置播放 3D 音效（带距离衰减），持续 3 秒
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    GameAPI.play_3d_sound(role.get_ctrl_unit().get_position(), 5129, 3.0, 100.0)
end)

GameAPI.raycast_test

描述: 物理射线检测

GameAPI.raycast_test(_start_pos, _end_pos, _collision_mask, _find_closest, _callback)

参数列表:

参数	类型	说明
_start_pos	Point3	起点
_end_pos	Point3	终点
_collision_mask	Int	碰撞掩码
_find_closest	Bool	检测最近碰撞
_callback	Function	碰撞回调（返回True停止后续回调）

示例:

-- 从角色头顶向正下方发射射线，检测脚下是否有地面
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    -- 射线起点为头顶上方，终点向下 10 米；mask=1 为场景碰撞层
    local start_pos = role.get_ctrl_unit().get_position() + math.Vector3(0, 2.0, 0)
    GameAPI.raycast_test(start_pos, start_pos - math.Vector3(0, 10.0, 0), 1, true, function(hit_unit)
        -- 回调中判空，命中后提示
        if hit_unit then
            role.show_tips("检测到脚下有物体", 1.0)
        end
    end)
end)

GameAPI.raycast_unit

描述: 查询射线检测到的单位碰撞信息

GameAPI.raycast_unit(_start_pos, _end_pos, _include_unit_types, _raycast_handler)

参数列表:

参数	类型	说明
_start_pos	Point3	起始点
_end_pos	Point3	终点
_include_unit_types	ListUnitType	包含的单位类型
_raycast_handler	Function	碰撞回调

示例:

-- 射线检测：从角色位置向前方打射线，检测障碍物
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    local start_pos = role.get_ctrl_unit().get_position()
    GameAPI.raycast_unit(
        start_pos,
        start_pos + math.Vector3(0, 0, 10),
        { Enums.UnitType.OBSTACLE },
        function(unit, point, normal)
            if unit then
                role.show_tips("命中障碍物", 2.0)
            end
        end)
end)

GameAPI.register_geometry_box

描述: 注册一个几何体：方块（可变形）

GameAPI.register_geometry_box(_size, _chamfer_radius, _chamfer_level, _use_box_collider, _preconf)

参数列表:

参数	类型	说明
_size	Fixed	边长
_chamfer_radius	Fixed	倒角半径
_chamfer_level	Int	倒角阶数（0~3）
_use_box_collider	Bool	精简物理（高性能）
_preconf	Dict	扩展配置（预留 ）

返回值:

• 类型: Str
• 说明: 几何体路径，用于create_obstacle_from_geometry

示例:

-- 注册一个可复用的方块几何体，返回路径字符串供创建组件使用
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 边长 1 米、无倒角、使用盒子碰撞体
    local geometry_path = GameAPI.register_geometry_box(1.0, 0.0, 0, true, {})
    if geometry_path and geometry_path ~= "" then
        LuaAPI.log("方块几何体注册成功: " .. geometry_path, 0)
    end
end)

GameAPI.register_geometry_frustum

描述: 注册一个几何体：圆台（可变形）

GameAPI.register_geometry_frustum(_height, _inner_radius, _outer_radius, _inner_poly_count, _outer_poly_count, _chamfer_radius, _angle, _layer, _bend, _preconf)

参数列表:

参数	类型	说明
_height	Fixed	高度
_inner_radius	Fixed	上径
_outer_radius	Fixed	下径，需大于上径
_inner_poly_count	Int	上多边形边数（6~15）
_outer_poly_count	Int	下多边形边数（6~15），需大于等于上多边形边数
_chamfer_radius	Fixed	倒角半径
_angle	Fixed	角度
_layer	Int	分段数
_bend	Fixed	弯曲度
_preconf	Dict	扩展配置（预留 ）

返回值:

• 类型: Str
• 说明: 几何体路径，用于create_obstacle_from_geometry

示例:

-- 注册圆台几何体（可变形），用于锥形区域或柱状外观
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 高 1 米、内径 0.5 米、外径 1 米，内外各 8 边形；无倒角、角度 90（注意 angle 不能为 0）
    local geometry_path = GameAPI.register_geometry_frustum(1.0, 0.5, 1.0, 8, 8, 0.0, 90.0, 1, 0.0, {})
    if geometry_path and geometry_path ~= "" then
        LuaAPI.log("圆台几何体注册成功", 0)
    end
end)

GameAPI.register_geometry_ring

描述: 注册一个几何体：圆环（可变形）

GameAPI.register_geometry_ring(_height, _inner_radius, _outer_radius, _inner_poly_count, _outer_poly_count, _chamfer_radius, _angle, _preconf)

参数列表:

参数	类型	说明
_height	Fixed	高度
_inner_radius	Fixed	内径
_outer_radius	Fixed	外径，需大于内径
_inner_poly_count	Int	内多边形边数（3~15）
_outer_poly_count	Int	外多边形边数（3~15），需大于等于内多边形边数
_chamfer_radius	Fixed	倒角半径
_angle	Fixed	角度
_preconf	Dict	扩展配置（预留 ）

返回值:

• 类型: Str
• 说明: 几何体路径，用于create_obstacle_from_geometry

示例:

-- 注册圆环几何体（可变形），用于传送门/光环类组件外观
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 高 0.2 米、内径 0.8 米、外径 1 米，内外各 12 边形；无倒角、角度 90（注意 angle 不能为 0）
    local geometry_path = GameAPI.register_geometry_ring(0.2, 0.8, 1.0, 12, 12, 0.0, 90.0, {})
    if geometry_path and geometry_path ~= "" then
        LuaAPI.log("圆环几何体注册成功", 0)
    end
end)

GameAPI.register_geometry_spline

描述: 注册一个几何体：自定义曲线/曲面

GameAPI.register_geometry_spline(_is_rope, _pos_list, _normal_list, _radius_list, _dist_precision, _normal_precision, _depth, _preconf)

参数列表:

参数	类型	说明
_is_rope	Bool	是否为曲线
_pos_list	ListVector3	点列表
_normal_list	ListVector3	法线列表
_radius_list	ListFixed	半径列表
_dist_precision	Fixed	位移精度
_normal_precision	Fixed	法线精度
_depth	Fixed	厚度（仅用于曲面）
_preconf	Dict	扩展配置（预留 ）

返回值:

• 类型: Str
• 说明: 几何体路径，用于create_obstacle_from_geometry

示例:

-- 注册自定义曲线几何体（绳索模式），支持半径渐变
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 绳索模式：路径 3 个点，法线朝上，半径从 0.1 渐变到 0.2 再收回
    local pos_list = { math.Vector3(0, 0, 0), math.Vector3(2, 0, 0), math.Vector3(4, 0, 0) }
    local normal_list = { math.Vector3(0, 1, 0), math.Vector3(0, 1, 0), math.Vector3(0, 1, 0) }
    local radius_list = { 0.1, 0.2, 0.1 }
    local geometry_path = GameAPI.register_geometry_spline(true, pos_list, normal_list, radius_list, 0.1, 0.1, 0.1, {})
    if geometry_path and geometry_path ~= "" then
        LuaAPI.log("绳索几何体注册成功", 0)
    end
end)

GameAPI.set_life_entity_survival_scene_boundary

描述: 设置生命体存活场景边界大小

GameAPI.set_life_entity_survival_scene_boundary(_x, _y, _z)

参数列表:

参数	类型	说明
_x	Fixed	矩形边界长度
_y	Fixed	矩形边界高度
_z	Fixed	矩形边界宽度

示例:

-- 设置生命体（角色/生物）存活场景边界，超出即判定死亡
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 以地图原点为中心，划定 1000 x 1000 x 1000 的存活范围
    GameAPI.set_life_entity_survival_scene_boundary(1000.0, 1000.0, 1000.0)
    LuaAPI.log("生命体存活边界已设置", 0)
end)

GameAPI.set_sheet_cell_value

描述: 设置表格值

GameAPI.set_sheet_cell_value(_value_type, _sheet_id, _key1, _key2, _val)

参数列表:

参数	类型	说明
_value_type	ValueType	值类型
_sheet_id	SheetID	表格
_key1	Int	行索引
_key2	Str	列索引
_val	ETypeMeta	自定义值

示例:

-- 游戏初始化：向表格写入玩家分数
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local sheet = GameAPI.create_sheet()
    if not sheet then return end
    GameAPI.add_sheet_column(sheet, "key_001", "Int")

    -- 写入第 1 行 key_001 列的整数值 100
    GameAPI.set_sheet_cell_value(
        Enums.ValueType.Int,   -- 值类型（整数）
        sheet,                 -- 表格编号
        1,                     -- 行索引
        "key_001",             -- 列索引
        100                    -- 写入的值（与值类型匹配）
    )
end)

GameAPI.set_unit_survival_scene_boundary

描述: 设置组件存活场景边界大小

GameAPI.set_unit_survival_scene_boundary(_x, _y, _z)

参数列表:

参数	类型	说明
_x	Fixed	矩形边界长度
_y	Fixed	矩形边界高度
_z	Fixed	矩形边界宽度

示例:

-- 设置单位存活场景边界（超出边界后单位死亡/回收）
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 水平 1000，垂直 1000 的存活边界
    GameAPI.set_unit_survival_scene_boundary(1000.0, 1000.0, 1000.0)
end)

GameAPI.sweep_test

描述: 物理扫描检测

GameAPI.sweep_test(_body_unit, _test_dir, _max_dist, _collision_mask, _find_closest, _callback)

参数列表:

参数	类型	说明
_body_unit	Unit	探测单位
_test_dir	Vector3	探测方向
_max_dist	Fixed	最大距离
_collision_mask	Int	碰撞掩码
_find_closest	Bool	检测最近碰撞
_callback	Function	碰撞回调（返回True停止后续回调）

示例:

-- 以角色为扫描体向正下方扫描，检测是否有落脚点
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    -- 沿 Y 轴负方向扫描 3 米；mask=1 为场景碰撞层
    GameAPI.sweep_test(role.get_ctrl_unit(), math.Vector3(0, -1, 0), 3.0, 1, true, function(hit_unit)
        -- 回调中判空，命中后提示
        if hit_unit then
            role.show_tips("下方有地面，可以落脚", 1.0)
        end
    end)
end)

GameAPI.triggerspace_prefab_get_kv_by_type

描述: 获取逻辑体预设的自定义值

GameAPI.triggerspace_prefab_get_kv_by_type(_value_type, _key, _prop)

参数列表:

参数	类型	说明
_value_type	ValueType	值类型
_key	TriggerSpaceKey	逻辑体编号
_prop	Str	名称

返回值:

• 类型: ETypeMeta
• 说明: 自定义值

示例:

-- 读取逻辑体预设的自定义值，如触发半径
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 900001 为逻辑体预设 key，读取 Fixed 类型的 "radius"
    local radius = GameAPI.triggerspace_prefab_get_kv_by_type(Enums.ValueType.Fixed, 900001, "radius")
    if radius then
        GlobalAPI.debug("逻辑体半径：" .. tostring(radius))
    else
        GlobalAPI.debug("逻辑体 900001 未配置 radius")
    end
end)

GameAPI.triggerspace_prefab_get_prop_by_type

描述: 获取逻辑体预设的属性

GameAPI.triggerspace_prefab_get_prop_by_type(_value_type, _key, _prop)

参数列表:

参数	类型	说明
_value_type	ValueType	值类型
_key	TriggerSpaceKey	逻辑体编号
_prop	Str	名称

返回值:

• 类型: ETypeMeta
• 说明: 属性值

示例:

-- 读取逻辑体预设属性，用于初始化逻辑体参数
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 读取 Fixed 类型的 "interval" 属性（触发间隔秒数）
    local interval = GameAPI.triggerspace_prefab_get_prop_by_type(Enums.ValueType.Fixed, 900001, "interval")
    if interval then
        GlobalAPI.debug("触发间隔：" .. tostring(interval))
    else
        GlobalAPI.debug("逻辑体 900001 未配置 interval")
    end
end)

GameAPI.triggerspace_prefab_has_kv

描述: 逻辑体预设是否存在自定义值

GameAPI.triggerspace_prefab_has_kv(_key, _prop)

参数列表:

参数	类型	说明
_key	TriggerSpaceKey	逻辑体编号
_prop	Str	名称

返回值:

• 类型: Bool
• 说明: 是否存在

示例:

-- 判断逻辑体预设是否配置了自定义值（如是否需要钥匙）
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 存在 "need_key" 标记时按需要钥匙触发处理
    if GameAPI.triggerspace_prefab_has_kv(900001, "need_key") then
        GlobalAPI.debug("该逻辑体需要钥匙触发")
    else
        GlobalAPI.debug("该逻辑体无需钥匙")
    end
end)

单位API

Ability.enter_cd

描述: 技能激活冷却

Ability.enter_cd()

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local ability = unit.add_ability_to_slot(1, 150001, {}, {})
    if not ability then return end
    ability.enter_cd()
end)```

### Ability.add_state_to_target

**描述:** 技能给单位添加状态

```lua
Ability.add_state_to_target(_unit, _state_id)

参数列表:

参数	类型	说明
_unit	Unit	对象
_state_id	BuffState	状态

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local ability = unit.add_ability_to_slot(1, 150001, {}, {})
    if not ability then return end
    ability.add_state_to_target(role, Enums.BuffState.BUFF_FORBID_MOVE)
end)```

### Ability.change_affect_radius

**描述:** 修改技能作用半径

```lua
Ability.change_affect_radius(_delta_affect_radius)

参数列表:

参数	类型	说明
_delta_affect_radius	Fixed	修改技能作用半径

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local ability = unit.add_ability_to_slot(1, 150001, {}, {})
    if not ability then return end
    ability.change_affect_radius(1.0)
end)```

### Ability.change_affect_width

**描述:** 修改技能作用宽度

```lua
Ability.change_affect_width(_delta_affect_width)

参数列表:

参数	类型	说明
_delta_affect_width	Fixed	修改技能作用宽度

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local ability = unit.add_ability_to_slot(1, 150001, {}, {})
    if not ability then return end
    ability.change_affect_width(1.0)
end)```

### Ability.change_max_release_distance

**描述:** 修改技能施法距离

```lua
Ability.change_max_release_distance(_delta_level)

参数列表:

参数	类型	说明
_delta_level	Fixed	修改技能施法距离

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local ability = unit.add_ability_to_slot(1, 150001, {}, {})
    if not ability then return end
    ability.change_max_release_distance(1.0)
end)```

### Ability.downgrade_ability_level

**描述:** 降级技能等级

```lua
Ability.downgrade_ability_level(_delta_level)

参数列表:

参数	类型	说明
_delta_level	Int	降低的技能等级

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local ability = unit.add_ability_to_slot(1, 150001, {}, {})
    if not ability then return end
    ability.downgrade_ability_level(1)
end)```

### Ability.get_affect_radius

**描述:** 获取技能的作用半径

```lua
Ability.get_affect_radius()

返回值:

• 类型: Fixed
• 说明: 施法距离

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local ability = unit.add_ability_to_slot(1, 150001, {}, {})
    if not ability then return end
    local result = ability.get_affect_radius()
end)```

### Ability.get_affect_width

**描述:** 获取技能的作用宽度

```lua
Ability.get_affect_width()

返回值:

• 类型: Fixed
• 说明: 施法距离

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local ability = unit.add_ability_to_slot(1, 150001, {}, {})
    if not ability then return end
    local result = ability.get_affect_width()
end)```

### Ability.get_charge_time

**描述:** 获取技能充能时间

```lua
Ability.get_charge_time()

返回值:

• 类型: Fixed
• 说明: 充能时间

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local ability = unit.add_ability_to_slot(1, 150001, {}, {})
    if not ability then return end
    local result = ability.get_charge_time()
end)```

### Ability.get_ability_level

**描述:** 获取技能的等级

```lua
Ability.get_ability_level()

返回值:

• 类型: Int
• 说明: 技能等级

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local ability = unit.add_ability_to_slot(1, 150001, {}, {})
    if not ability then return end
    local result = ability.get_ability_level()
end)```

### Ability.get_ability_max_level

**描述:** 获取技能的最大等级

```lua
Ability.get_ability_max_level()

返回值:

• 类型: Int
• 说明: 技能最大等级

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local ability = unit.add_ability_to_slot(1, 150001, {}, {})
    if not ability then return end
    local result = ability.get_ability_max_level()
end)```

### Ability.get_max_release_distance

**描述:** 获取技能的施法距离

```lua
Ability.get_max_release_distance()

返回值:

• 类型: Fixed
• 说明: 施法距离

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local ability = unit.add_ability_to_slot(1, 150001, {}, {})
    if not ability then return end
    local result = ability.get_max_release_distance()
end)```

### Ability.upgrade_ability_level

**描述:** 增加技能等级

```lua
Ability.upgrade_ability_level(_delta_level)

参数列表:

参数	类型	说明
_delta_level	Int	增加的技能等级

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local ability = unit.add_ability_to_slot(1, 150001, {}, {})
    if not ability then return end
    ability.upgrade_ability_level(1)
end)```

### Ability.set_affect_radius

**描述:** 设置技能的作用半径

```lua
Ability.set_affect_radius(_new_affect_radius)

参数列表:

参数	类型	说明
_new_affect_radius	Fixed	作用半径

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local ability = unit.add_ability_to_slot(1, 150001, {}, {})
    if not ability then return end
    ability.set_affect_radius(1.0)
end)```

### Ability.set_affect_width

**描述:** 设置技能的作用宽度

```lua
Ability.set_affect_width(_new_affect_width)

参数列表:

参数	类型	说明
_new_affect_width	Fixed	作用宽度

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local ability = unit.add_ability_to_slot(1, 150001, {}, {})
    if not ability then return end
    ability.set_affect_width(1.0)
end)```

### Ability.set_ability_level

**描述:** 设置技能等级

```lua
Ability.set_ability_level(_new_level)

参数列表:

参数	类型	说明
_new_level	Int	技能等级

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local ability = unit.add_ability_to_slot(1, 150001, {}, {})
    if not ability then return end
    ability.set_ability_level(1)
end)```

### Ability.set_ability_max_level

**描述:** 设置技能最大等级

```lua
Ability.set_ability_max_level(_new_max_level)

参数列表:

参数	类型	说明
_new_max_level	Int	技能最大等级

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local ability = unit.add_ability_to_slot(1, 150001, {}, {})
    if not ability then return end
    ability.set_ability_max_level(1)
end)```

### Ability.set_max_release_distance

**描述:** 设置技能的施法距离

```lua
Ability.set_max_release_distance(_new_max_release_distance)

参数列表:

参数	类型	说明
_new_max_release_distance	Fixed	施法距离

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local ability = unit.add_ability_to_slot(1, 150001, {}, {})
    if not ability then return end
    ability.set_max_release_distance(1.0)
end)```

### Ability.begin_cast

**描述:** 技能开始释放

```lua
Ability.begin_cast(_dir_info, _target_point, _target_unit)

参数列表:

参数	类型	说明
_dir_info	Vector3	方向
_target_point	Point3	坐标点
_target_unit	Unit	目标单位

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local ability = unit.add_ability_to_slot(1, 150001, {}, {})
    if not ability then return end
    ability.begin_cast(math.Vector3(0, 0, 0), math.Vector3(0, 0, 0), role)
end)```

### Ability.get_cur_release_num

**描述:** 获取技能当前使用次数

```lua
Ability.get_cur_release_num()

返回值:

• 类型: Int
• 说明: 使用次数

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local ability = unit.add_ability_to_slot(1, 150001, {}, {})
    if not ability then return end
    local result = ability.get_cur_release_num()
end)```

### Ability.get_max_release_num

**描述:** 获取技能最大使用次数

```lua
Ability.get_max_release_num()

返回值:

• 类型: Int
• 说明: 最大使用次数

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local ability = unit.add_ability_to_slot(1, 150001, {}, {})
    if not ability then return end
    local result = ability.get_max_release_num()
end)```

### Ability.remove_state_to_target

**描述:** 技能给单位移除状态

```lua
Ability.remove_state_to_target(_unit, _state_id)

参数列表:

参数	类型	说明
_unit	Unit	对象
_state_id	BuffState	状态

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local ability = unit.add_ability_to_slot(1, 150001, {}, {})
    if not ability then return end
    ability.remove_state_to_target(role, Enums.BuffState.BUFF_FORBID_MOVE)
end)```

### AbilityComp.reset_ability_cd

**描述:** 重置指定槽位技能CD

```lua
AbilityComp.reset_ability_cd(_ability_index)

参数列表:

参数	类型	说明
_ability_index	AbilitySlot	技能槽位

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local ability_slot = 1  -- AbilitySlot 是槽位整数索引
    unit.reset_ability_cd(ability_slot)
end)```

### ItemBox.add_ability

**描述:** 添加道具箱刷新技能

```lua
ItemBox.add_ability(_ability_key, _weight)

参数列表:

参数	类型	说明
_ability_key	AbilityKey	技能编号
_weight	Int	权重

示例:

-- 向道具箱放入技能（itemBox 为场景中配置的道具箱单位）
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 道具箱单位需在场景中配置（此处按名字查询，不存在则跳过）
    local itemBox = LuaAPI.query_unit("道具箱")
    if not itemBox then return end

    itemBox.add_ability(150001, 1)
end)```

### Role.add_achievement_progress

**描述:** 增加成就进度

```lua
Role.add_achievement_progress(_event_id, _add_count)

参数列表:

参数	类型	说明
_event_id	Achievement	成就
_add_count	Int	成就进度

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local achievement = 1  -- Achievement 是成就编号（integer）
    role.add_achievement_progress(achievement, 1)
end)```

### BuffStateComp.add_state

**描述:** 为对象添加状态

```lua
BuffStateComp.add_state(_state_id)

参数列表:

参数	类型	说明
_state_id	BuffState	状态

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    unit.add_state(Enums.BuffState.BUFF_FORBID_MOVE)
end)```

### Unit.add_child

**描述:** 添加子单位

```lua
Unit.add_child(_unit)

参数列表:

参数	类型	说明
_unit	Unit	子单位

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    unit.add_child(unit)
end)```

### Equipment.change_current_stack_size

**描述:** 增加/减少物品当前堆叠数

```lua
Equipment.change_current_stack_size(_num)

参数列表:

参数	类型	说明
_num	Int	堆叠数

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local equipment = GameAPI.create_equipment(400001, math.Vector3(0,0,0))
    if not equipment then return end
    equipment.change_current_stack_size(1)
end)```

### Equipment.change_max_stack_size

**描述:** 增加/减少物品最大堆叠数

```lua
Equipment.change_max_stack_size(_num)

参数列表:

参数	类型	说明
_num	Int	堆叠数

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local equipment = GameAPI.create_equipment(400001, math.Vector3(0,0,0))
    if not equipment then return end
    equipment.change_max_stack_size(1)
end)```

### AbilityComp.add_prop_ability

**描述:** 添加道具技能

```lua
AbilityComp.add_prop_ability(_ability_id, _kv_args, _kv_types)

参数列表:

参数	类型	说明
_ability_id	AbilityKey	技能编号
_kv_args	Dict	自定义参数值
_kv_types	Dict	自定义参数类型

返回值:

• 类型: Ability
• 说明: 添加上的技能

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local ability_with_params = unit.add_prop_ability(150002, {
        damage = 100.0,           -- 伤害值
        cooldown = 5.0,           -- 冷却时间（秒）
        range = 10.0,             -- 施法范围
        level = 3,                -- 技能等级
        is_passive = false        -- 是否被动技能
    }, {
        damage = "Fixed",         -- 伤害值类型
        cooldown = "Fixed",       -- 冷却时间类型
        range = "Fixed",          -- 施法范围类型
        level = "Int",            -- 技能等级类型
        is_passive = "Bool"       -- 是否被动技能类型
    })
end)```

### ModifierComp.add_modifier_by_key

**描述:** 添加效果

```lua
ModifierComp.add_modifier_by_key(_modifier_id, _params_dict)

参数列表:

参数	类型	说明
_modifier_id	ModifierKey	效果编号
_params_dict	Dict	额外参数

返回值:

• 类型: Modifier
• 说明: 效果对象

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local modifier_with_params = unit.add_modifier_by_key(600002, {
        source_unit = role,         -- 效果来源单位（此处用玩家自身）
        duration = 10.0,            -- 持续时间（秒）
        owner_ability = nil         -- 所属技能对象（无则传 nil）
    })
end)```

### Modifier.add_duration

**描述:** 增加效果的持续时间

```lua
Modifier.add_duration(_add_time)

参数列表:

参数	类型	说明
_add_time	Fixed	增加时间

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local modifier = unit.add_modifier_by_key(600001, {})
    if not modifier then return end
    modifier.add_duration(1.0)
end)```

### Modifier.add_stack_count

**描述:** 增加效果层数

```lua
Modifier.add_stack_count(_stack_count_add)

参数列表:

参数	类型	说明
_stack_count_add	Int	层数

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local modifier = unit.add_modifier_by_key(600001, {})
    if not modifier then return end
    modifier.add_stack_count(1)
end)```

### AbilityComp.add_ability_to_slot

**描述:** 添加向技能槽位添加UGC技能能

```lua
AbilityComp.add_ability_to_slot(_ability_index, _ability_id, _kv_args, _kv_types)

参数列表:

参数	类型	说明
_ability_index	AbilitySlot	技能槽位
_ability_id	AbilityKey	技能编号
_kv_args	Dict	自定义参数值
_kv_types	Dict	自定义参数类型

返回值:

• 类型: Ability
• 说明: 添加上的技能

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local ability_slot = 1  -- AbilitySlot 是槽位整数索引（1~N）
    local ability_with_params = unit.add_ability_to_slot(ability_slot, 150002, {
        damage = 200.0,           -- 技能伤害
        cooldown = 8.0,           -- 冷却时间（秒）
        range = 15.0,             -- 施法范围
        level = 5,                -- 初始等级
        can_crit = true           -- 是否可暴击
    }, {
        damage = "Fixed",
        cooldown = "Fixed",
        range = "Fixed",
        level = "Int",
        can_crit = "Bool"
    })
end)```

### LifeEntity.ai_command_alert

**描述:** 控制AI执行警戒命令

```lua
LifeEntity.ai_command_alert(_tagert_pos, _target_dir, _dalay_time, _reject_time, _move_mode)

参数列表:

参数	类型	说明
_tagert_pos	Vector3	目标
_target_dir	Vector3	朝向
_dalay_time	Fixed	延迟
_reject_time	Fixed	厌恶时间
_move_mode	MoveMode	移动方式

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- NPC单位，AI行为的执行者
    if not npc then return end
    npc.ai_command_alert(math.Vector3(0, 0, 0), math.Vector3(0, 0, 0), 1.0, 1.0, Enums.MoveMode.DEFAULT)
end)```

### LifeEntity.ai_command_follow

**描述:** 控制AI执行跟随命令

```lua
LifeEntity.ai_command_follow(_target_unit, _follow_dis, _tolerate_dis, _reject_time, _move_mode)

参数列表:

参数	类型	说明
_target_unit	Unit	目标
_follow_dis	Fixed	距离
_tolerate_dis	Fixed	容忍距离
_reject_time	Fixed	厌恶时间
_move_mode	MoveMode	移动方式

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- NPC单位，AI行为的执行者
    if not npc then return end
    npc.ai_command_follow(role, 1.0, 1.0, 1.0, Enums.MoveMode.DEFAULT)
end)```

### LifeEntity.ai_command_imitate

**描述:** 控制AI执行模仿命令

```lua
LifeEntity.ai_command_imitate(_target_unit, _delay, _disable_actions)

参数列表:

参数	类型	说明
_target_unit	Character	目标
_delay	Fixed	延迟
_disable_actions	ListAIBasicCommand	屏蔽操作

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- NPC单位，AI行为的执行者
    if not npc then return end
    npc.ai_command_imitate(npc, 1.0, {Enums.AIBasicCommand.MOVE})
end)```

### LifeEntity.ai_command_jump

**描述:** 控制AI跳跃

```lua
LifeEntity.ai_command_jump()

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- NPC单位，AI行为的执行者
    if not npc then return end
    npc.ai_command_jump()
end)```

### LifeEntity.ai_command_lift

**描述:** 控制AI举起/扔下/投掷

```lua
LifeEntity.ai_command_lift()

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- NPC单位，AI行为的执行者
    if not npc then return end
    npc.ai_command_lift()
end)```

### LifeEntity.ai_command_patrol

**描述:** 控制AI执行巡逻命令

```lua
LifeEntity.ai_command_patrol(_waypoint, _reject_time, _round_mode, _move_mode)

参数列表:

参数	类型	说明
_waypoint	ListVector3	路径
_reject_time	Fixed	厌恶时间
_round_mode	PatrolType	往返模式
_move_mode	MoveMode	移动方式

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- NPC单位，AI行为的执行者
    if not npc then return end
    npc.ai_command_patrol({math.Vector3(0, 0, 0), math.Vector3(1, 0, 0)}, 1.0, Enums.PatrolType.LOOP, Enums.MoveMode.DEFAULT)
end)```

### LifeEntity.ai_command_pick_up_equipment

**描述:** 控制AI拾取物品

```lua
LifeEntity.ai_command_pick_up_equipment(_target_equipment, _move_mode, _reject_time)

参数列表:

参数	类型	说明
_target_equipment	Equipment	拾取物品
_move_mode	MoveMode	移动方式
_reject_time	Fixed	厌恶时间

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- NPC单位，AI行为的执行者
    if not npc then return end
    local equipment = GameAPI.create_equipment(400001, math.Vector3(0,0,0))
    if not equipment then return end
    npc.ai_command_pick_up_equipment(equipment, Enums.MoveMode.DEFAULT, 1.0)
end)```

### LifeEntity.ai_command_roll

**描述:** 控制AI滚动

```lua
LifeEntity.ai_command_roll()

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- NPC单位，AI行为的执行者
    if not npc then return end
    npc.ai_command_roll()
end)```

### LifeEntity.ai_command_rush

**描述:** 控制AI前扑

```lua
LifeEntity.ai_command_rush()

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- NPC单位，AI行为的执行者
    if not npc then return end
    npc.ai_command_rush()
end)```

### LifeEntity.ai_command_start_move

**描述:** 控制AI单位移动

```lua
LifeEntity.ai_command_start_move(_direction, _t)

参数列表:

参数	类型	说明
_direction	Vector3	方向
_t	Fixed	时间

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- NPC单位，AI行为的执行者
    if not npc then return end
    npc.ai_command_start_move(math.Vector3(0, 0, 0), 1.0)
end)```

### LifeEntity.ai_command_stop_move

**描述:** 控制AI单位停止移动

```lua
LifeEntity.ai_command_stop_move(_duration)

参数列表:

参数	类型	说明
_duration	Fixed	时间

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- NPC单位，AI行为的执行者
    if not npc then return end
    npc.ai_command_stop_move(1.0)
end)```

### LifeEntity.set_ai_move_threshold

**描述:** 设置寻路阈值

```lua
LifeEntity.set_ai_move_threshold(_threshold)

参数列表:

参数	类型	说明
_threshold	Fixed	距离

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- NPC单位，AI行为的执行者
    if not npc then return end
    npc.set_ai_move_threshold(1.0)
end)```

### Unit.apply_force

**描述:** 对单位施加外力

```lua
Unit.apply_force(_force)

参数列表:

参数	类型	说明
_force	Vector3	力

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    unit.apply_force(math.Vector3(0, 0, 0))
end)```

### Ability.break_accumulate

**描述:** 打断蓄力

```lua
Ability.break_accumulate()

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local ability = unit.add_ability_to_slot(1, 150001, {}, {})
    if not ability then return end
    ability.break_accumulate()
end)```

### Ability.break_cast

**描述:** 打断技能施法

```lua
Ability.break_cast()

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local ability = unit.add_ability_to_slot(1, 150001, {}, {})
    if not ability then return end
    ability.break_cast()
end)```

### Camp.set_camp_score

**描述:** 设置阵营积分

```lua
Camp.set_camp_score(_score)

参数列表:

参数	类型	说明
_score	Int	积分

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local camp = GameAPI.get_camp(1)
    if not camp then return end
    camp.set_camp_score(1)
end)```

### LifeComp.is_infinite_reborn

**描述:** 是否无限复活

```lua
LifeComp.is_infinite_reborn()

返回值:

• 类型: Bool
• 说明: 是否无限复活

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = unit.is_infinite_reborn()
end)```

### LifeComp.can_reborn

**描述:** 生物是否可以复活

```lua
LifeComp.can_reborn()

返回值:

• 类型: Bool
• 说明: 是否可以复活

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = unit.can_reborn()
end)```

### Character.set_character_prefab

**描述:** 改变角色预设

```lua
Character.set_character_prefab(_c_key, _reset_prop, _reset_trigger_system, _reset_model)

参数列表:

参数	类型	说明
_c_key	CharacterKey	角色预设
_reset_prop	Bool	重置属性
_reset_trigger_system	Bool	重置蛋码
_reset_model	Bool	重置外观

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- Character 继承自 LifeEntity，代表NPC角色单位
    if not npc then return end
    npc.set_character_prefab(100001, true, true, true)
end)```

### Unit.set_paint_area_color

**描述:** 改变组件颜色

```lua
Unit.set_paint_area_color(_paint_area, _color)

参数列表:

参数	类型	说明
_paint_area	PaintArea	染色区域
_color	Color	颜色

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    unit.set_paint_area_color(Enums.ColorPaintAreaType.AREA_1, GlobalAPI.str_to_color("ff0000"))
end)```

### LifeComp.set_auto_reborn_enabled

**描述:** 设置自动复活

```lua
LifeComp.set_auto_reborn_enabled(_auto_reborn)

参数列表:

参数	类型	说明
_auto_reborn	Bool	是否自动复活

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    unit.set_auto_reborn_enabled(true)
end)```

### AbilityComp.break_ability_accumulate

**描述:** 打断技能蓄力

```lua
AbilityComp.break_ability_accumulate()

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    unit.break_ability_accumulate()
end)```

### AbilityComp.interrupt_ability

**描述:** 打断技能施法

```lua
AbilityComp.interrupt_ability()

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    unit.interrupt_ability()
end)```

### Character.set_socket_model

**描述:** 修改角色指定外观部位为自定义模型

```lua
Character.set_socket_model(_model_socket, _creature, _creature_model_socket)

参数列表:

参数	类型	说明
_model_socket	ModelSocket	外观部位
_creature	Creature	生物
_creature_model_socket	ModelSocket	外观部位

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- Character 继承自 LifeEntity，代表NPC角色单位
    if not npc then return end
    local creature = GameAPI.create_creature_fixed_scale(100001, math.Vector3(0,0,0), math.Quaternion(0,0,0), 1.0, GameAPI.get_all_valid_roles()[1])
    if not creature then return end
    npc.set_socket_model(Enums.ModelSocket.socket_body, creature, Enums.ModelSocket.socket_body)
end)```

### LifeEntity.set_model_by_creature

**描述:** 根据生物设置模型

```lua
LifeEntity.set_model_by_creature(_creature, _include_custom_model, _inherit_scale, _inherit_capsule_size)

参数列表:

参数	类型	说明
_creature	Creature	生物
_include_custom_model	Bool	是否包含自定义形象
_inherit_scale	Bool	是否继承缩放
_inherit_capsule_size	Bool	是否继承胶囊体尺寸

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- NPC单位，AI行为的执行者
    if not npc then return end
    local creature = GameAPI.create_creature_fixed_scale(100001, math.Vector3(0,0,0), math.Quaternion(0,0,0), 1.0, GameAPI.get_all_valid_roles()[1])
    if not creature then return end
    npc.set_model_by_creature(creature, true, true, true)
end)```

### Character.lift

**描述:** 命令角色抓举

```lua
Character.lift()

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- Character 继承自 LifeEntity，代表NPC角色单位
    if not npc then return end
    npc.lift()
end)```

### Character.start_move_to_pos

**描述:** 命令角色移动到坐标点

```lua
Character.start_move_to_pos(_target_pos, _duration)

参数列表:

参数	类型	说明
_target_pos	Point3	坐标点
_duration	Fixed	持续时间

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- Character 继承自 LifeEntity，代表NPC角色单位
    if not npc then return end
    npc.start_move_to_pos(math.Vector3(0, 0, 0), 1.0)
end)```

### Character.fling_rush

**描述:** 命令角色前扑

```lua
Character.fling_rush()

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- Character 继承自 LifeEntity，代表NPC角色单位
    if not npc then return end
    npc.fling_rush()
end)```

### AbilityComp.destroy_ability

**描述:** 销毁技能

```lua
AbilityComp.destroy_ability(_ability)

参数列表:

参数	类型	说明
_ability	Ability	技能对象

返回值:

• 类型: Bool
• 说明: 是否成功移除

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end

    local ability = unit.add_ability_to_slot(1, 150001, {}, {})
    if ability then
        unit.destroy_ability(ability)
    end
end)```

### LifeComp.die

**描述:** 使生物死亡

```lua
LifeComp.die(_dmg_unit)

参数列表:

参数	类型	说明
_dmg_unit	Unit	伤害来源

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end

    unit.die(role)
end)```

### LifeEntity.try_enter_vehicle

**描述:** 生命体尝试上载具

```lua
LifeEntity.try_enter_vehicle(_vehicle)

参数列表:

参数	类型	说明
_vehicle	Vehicle	载具

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- NPC单位，AI行为的执行者
    if not npc then return end
    local vehicle = GameAPI.create_vehicle(500001, math.Vector3(0,0,0), math.Vector3(0,0,1), nil)
    if not vehicle then return end
    npc.try_enter_vehicle(vehicle)
end)```

### LifeEntity.try_exit_vehicle

**描述:** 生命体尝试下载具

```lua
LifeEntity.try_exit_vehicle()

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- NPC单位，AI行为的执行者
    if not npc then return end
    npc.try_exit_vehicle()
end)```

### AttrComp.get_attr_base_extra_fixed

**描述:** 获取属性的基础加成值(复杂模式)

```lua
AttrComp.get_attr_base_extra_fixed(_key)

参数列表:

参数	类型	说明
_key	Str	属性名

返回值:

• 类型: Fixed
• 说明: 基础加成值

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = unit.get_attr_base_extra_fixed("key_001")
end)```

### AttrComp.get_attr_bonus_fixed

**描述:** 获取属性的额外固定值(复杂模式)

```lua
AttrComp.get_attr_bonus_fixed(_key)

参数列表:

参数	类型	说明
_key	Str	属性名

返回值:

• 类型: Fixed
• 说明: 额外固定值

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = unit.get_attr_bonus_fixed("key_001")
end)```

### AttrComp.get_attr_ratio_fixed

**描述:** 获取属性的倍率值(复杂模式)

```lua
AttrComp.get_attr_ratio_fixed(_key)

参数列表:

参数	类型	说明
_key	Str	属性名

返回值:

• 类型: Fixed
• 说明: 倍率值

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = unit.get_attr_ratio_fixed("key_001")
end)```

### AttrComp.get_attr_raw_fixed

**描述:** 获取属性的基础值(复杂模式)

```lua
AttrComp.get_attr_raw_fixed(_key)

参数列表:

参数	类型	说明
_key	Str	属性名

返回值:

• 类型: Fixed
• 说明: 基础值

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = unit.get_attr_raw_fixed("key_001")
end)```

### LifeComp.set_infinite_reborn_enabled

**描述:** 设置无限复活

```lua
LifeComp.set_infinite_reborn_enabled(_enable_reborn)

参数列表:

参数	类型	说明
_enable_reborn	Bool	是否无限复活

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    unit.set_infinite_reborn_enabled(true)
end)```

### LifeEntity.is_ghost_mode

**描述:** 生命体是否进入魂蛋模式

```lua
LifeEntity.is_ghost_mode()

返回值:

• 类型: Bool
• 说明: 是否处于魂蛋模式

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- NPC单位，AI行为的执行者
    if not npc then return end
    local result = npc.is_ghost_mode()
end)```

### Unit.get_local_offset_position

**描述:** 获取单位局部偏移位置

```lua
Unit.get_local_offset_position(_offset)

参数列表:

参数	类型	说明
_offset	Vector3	偏移向量

返回值:

• 类型: Point3
• 说明: 偏移位置

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local result = unit.get_local_offset_position(math.Vector3(0, 0, 0))
end)```

### LifeComp.reborn

**描述:** 使生物复活

```lua
LifeComp.reborn(_immediate)

参数列表:

参数	类型	说明
_immediate	Bool	立即复活

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    unit.reborn(true)
end)```

### LifeComp.set_reborn_time

**描述:** 设置复活时间

```lua
LifeComp.set_reborn_time(_reborn_time)

参数列表:

参数	类型	说明
_reborn_time	Fixed	复活时间

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    unit.set_reborn_time(1.0)
end)```

### LifeEntity.reset_model

**描述:** 还原模型变化

```lua
LifeEntity.reset_model()

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- NPC单位，AI行为的执行者
    if not npc then return end
    npc.reset_model()
end)```

### Character.reset_target_socket_model

**描述:** 还原角色指定外观部位变化

```lua
Character.reset_target_socket_model(_model_socket)

参数列表:

参数	类型	说明
_model_socket	ModelSocket	外观部位

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- Character 继承自 LifeEntity，代表NPC角色单位
    if not npc then return end
    npc.reset_target_socket_model(Enums.ModelSocket.socket_body)
end)```

### ModifierComp.destroy_modifier

**描述:** 销毁效果

```lua
ModifierComp.destroy_modifier(_modifier)

参数列表:

参数	类型	说明
_modifier	Modifier	效果对象

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end

    local modifier = unit.add_modifier_by_key(600001, {})
    unit.destroy_modifier(modifier)
end)```

### AbilityComp.set_ability_to_slot

**描述:** 替换技能槽位(UGC槽位)

```lua
AbilityComp.set_ability_to_slot(_ability, _ability_index)

参数列表:

参数	类型	说明
_ability	Ability	技能对象
_ability_index	AbilitySlot	技能槽位

返回值:

• 类型: Ability
• 说明: 被替换的旧技能

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end

    local ability = unit.add_ability_to_slot(1, 150001, {}, {})
    local ability_slot = 1  -- AbilitySlot 是槽位整数索引
    if ability then
        unit.set_ability_to_slot(ability, ability_slot)
    end
end)```

### LifeEntity.set_direction

**描述:** 设置生命实体的朝向

```lua
LifeEntity.set_direction(_face_dir)

参数列表:

参数	类型	说明
_face_dir	Vector3	方向

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- NPC单位，AI行为的执行者
    if not npc then return end
    npc.set_direction(math.Vector3(0, 0, 0))
end)```

### MoveStatusComp.start_face_lock_target

**描述:** 开始锁定面向目标

```lua
MoveStatusComp.start_face_lock_target(_target_unit, _time)

参数列表:

参数	类型	说明
_target_unit	Unit	锁定对象
_time	Fixed	持续时间

示例:

-- 让角色面朝锁定目标单位（锁定期间面向目标，1 秒后解除）
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end

    -- 目标为场景中的单位（如 NPC），comp 方法直接挂在单位对象上调用
    local target = LuaAPI.query_unit("NPC队长")
    if target then
        unit.start_face_lock_target(target, 1.0)
    end
end)```

### MoveStatusComp.stop_face_lock_target

**描述:** 结束锁定面向目标

```lua
MoveStatusComp.stop_face_lock_target()

示例:

-- 解除角色的面朝锁定（需先 start_face_lock_target）
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end

    unit.stop_face_lock_target()
end)```

### CharacterComp.start_forced_move

**描述:** 开始强制位移

```lua
CharacterComp.start_forced_move(_vel, _duration, _enable_phy)

参数列表:

参数	类型	说明
_vel	Vector3	移动速度
_duration	Fixed	持续时间
_enable_phy	Bool	是否保留物理

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    unit.start_forced_move(math.Vector3(0, 0, 0), 1.0, true)
end)```

### AttrComp.change_attr_bonus_fixed

**描述:** 改变属性的额外固定值(复杂模式)

```lua
AttrComp.change_attr_bonus_fixed(_key, _value)

参数列表:

参数	类型	说明
_key	Str	属性名
_value	Fixed	额外固定值

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    unit.change_attr_bonus_fixed("key_001", 1.0)
end)```

### AttrComp.change_attr_ratio_fixed

**描述:** 改变属性的倍率值(复杂模式)

```lua
AttrComp.change_attr_ratio_fixed(_key, _value)

参数列表:

参数	类型	说明
_key	Str	属性名
_value	Fixed	倍率值

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    unit.change_attr_ratio_fixed("key_001", 1.0)
end)```

### AttrComp.change_attr_raw_fixed

**描述:** 改变属性的基础值(复杂模式)

```lua
AttrComp.change_attr_raw_fixed(_key, _value)

参数列表:

参数	类型	说明
_key	Str	属性名
_value	Fixed	基础值

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    unit.change_attr_raw_fixed("key_001", 1.0)
end)```

### CharacterComp.stop_forced_move

**描述:** 退出当前强制位移

```lua
CharacterComp.stop_forced_move()

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    unit.stop_forced_move()
end)```

### LiftComp.lift_unit

**描述:** 举起单位

```lua
LiftComp.lift_unit(_unit)

参数列表:

参数	类型	说明
_unit	Unit	被抓举单位

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end

    unit.lift_unit(role)
end)```

### BuffStateComp.clear_state

**描述:** 清空对象身上所有状态

```lua
BuffStateComp.clear_state(_state_id)

参数列表:

参数	类型	说明
_state_id	BuffState	状态

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    unit.clear_state(Enums.BuffState.BUFF_FORBID_MOVE)
end)```

### KVBase.clear_kv

**描述:** 清空自定义值

```lua
KVBase.clear_kv()

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    unit.clear_kv()
end)```

### EquipmentComp.clear_selected_equipment_slot

**描述:** 清除单位物品格选中状态

```lua
EquipmentComp.clear_selected_equipment_slot()

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    unit.clear_selected_equipment_slot()
end)```

### KVBase.clear_tag

**描述:** 清空标签

```lua
KVBase.clear_tag()

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    unit.clear_tag()
end)```

### Role.consume_commodity

**描述:** 消耗玩家指定数量道具

```lua
Role.consume_commodity(_commodity_id, _num)

参数列表:

参数	类型	说明
_commodity_id	UgcCommodity	道具
_num	Int	数量

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local ugc_commodity_id = 1001  -- 商品 ID（示意值，需替换为实际配置）
    role.consume_commodity(ugc_commodity_id, 1)
end)```

### EquipmentComp.create_equipment_to_slot

**描述:** 创建物品到指定类型槽位

```lua
EquipmentComp.create_equipment_to_slot(_key, _slot_type)

参数列表:

参数	类型	说明
_key	EquipmentKey	物品编号
_slot_type	EquipmentSlotType	槽位类型

返回值:

• 类型: Equipment
• 说明: 创建的物品

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = unit.create_equipment_to_slot(400001, Enums.EquipmentSlotType.EQUIPPED)
end)```

### SceneUI.create_scene_ui_bind_unit

**描述:** 创建场景界面绑定到单位

```lua
SceneUI.create_scene_ui_bind_unit(_layer_key, _socket_name, _offset_pos, _duration, _bind_event, _inherit_visible)

参数列表:

参数	类型	说明
_layer_key	E3DLayerKey	场景界面预设编号
_socket_name	ModelSocket	绑定位置
_offset_pos	Point3	偏移位置
_duration	Fixed	持续时间
_bind_event	Bool	事件是否指向绑定者
_inherit_visible	Bool	是否跟随组件显隐

返回值:

• 类型: E3DLayer
• 说明: 场景界面

示例:

-- 在单位上创建跟随移动的场景 UI（SceneUI 方法挂在单位实例上）
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end

    local result = unit.create_scene_ui_bind_unit(120001, Enums.ModelSocket.socket_body, math.Vector3(0, 0, 0), 1.0, true, true)
end)```

### DisplayComp.add_banned_anim

**描述:** 临时屏蔽部分动画的播放

```lua
DisplayComp.add_banned_anim(_anim_name)

参数列表:

参数	类型	说明
_anim_name	Str	动画名

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    unit.add_banned_anim("平凡蛋0")
end)```

### Unit.apply_impact_force

**描述:** 施加冲击力

```lua
Unit.apply_impact_force(_force, _max_speed, _force_lost_control, _lost_ctrl_time)

参数列表:

参数	类型	说明
_force	Vector3	力
_max_speed	Fixed	击飞最大速度
_force_lost_control	Bool	是否击飞
_lost_ctrl_time	Fixed	击飞失控时间

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    unit.apply_impact_force(math.Vector3(0, 0, 0), 1.0, true, 1.0)
end)```

### LifeEntity.set_model_by_character

**描述:** 根据角色设置模型

```lua
LifeEntity.set_model_by_character(_character, _include_ugc_model, _inherit_scale, _inherit_capsule_size)

参数列表:

参数	类型	说明
_character	Character	角色
_include_ugc_model	Bool	是否包含自定义形象
_inherit_scale	Bool	是否继承缩放
_inherit_capsule_size	Bool	是否继承胶囊体尺寸

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- NPC单位，AI行为的执行者
    if not npc then return end
    npc.set_model_by_character(npc, true, true, true)
end)```

### OwnerComp.change_owner

**描述:** 修改所属玩家

```lua
OwnerComp.change_owner(_role)

参数列表:

参数	类型	说明
_role	Role	所属玩家

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    -- OwnerComp 挂在生物/触发器空间上（非角色）：创建生物（100001 为示意 key）
    local pet = GameAPI.create_creature_fixed_scale(100001, role.get_ctrl_unit().get_position(), math.Quaternion(0, 0, 0), 1.0, role)
    if not pet then return end

    pet.change_owner(role)
end)```

### DisplayComp.clear_banned_anim

**描述:** 清除动画屏蔽

```lua
DisplayComp.clear_banned_anim()

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    unit.clear_banned_anim()
end)```

### Unit.get_name

**描述:** 获取单位名称

```lua
Unit.get_name()

返回值:

• 类型: Str
• 说明: 名称

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local result = unit.get_name()
end)```

### CharacterComp.get_scale_ratio

**描述:** 获取缩放倍率

```lua
CharacterComp.get_scale_ratio()

返回值:

• 类型: Fixed
• 说明: 缩放倍率

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = unit.get_scale_ratio()
end)```

### Unit.hide_bubble_msg

**描述:** 关闭气泡信息

```lua
Unit.hide_bubble_msg()

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    unit.hide_bubble_msg()
end)```

### DisplayComp.play_body_anim_by_id

**描述:** 播放全身动画

```lua
DisplayComp.play_body_anim_by_id(_anim_id, _start_time, _play_time, _is_loop)

参数列表:

参数	类型	说明
_anim_id	AnimKey	动画编号
_start_time	Fixed	开始时间
_play_time	Fixed	持续时间
_is_loop	Bool	是否循环

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    unit.play_body_anim_by_id(250001, 1.0, 1.0, true)
end)```

### Unit.play_emoji

**描述:** 单位发送表情

```lua
Unit.play_emoji(_emoji_key)

参数列表:

参数	类型	说明
_emoji_key	EmojiKey	表情编号

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    unit.play_emoji(270001)
end)```

### DisplayComp.play_upper_anim_by_id

**描述:** 播放上半身动画

```lua
DisplayComp.play_upper_anim_by_id(_anim_id, _start_time, _play_time, _is_loop)

参数列表:

参数	类型	说明
_anim_id	AnimKey	动画编号
_start_time	Fixed	开始时间
_play_time	Fixed	持续时间
_is_loop	Bool	是否循环

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    unit.play_upper_anim_by_id(250001, 1.0, 1.0, true)
end)```

### DisplayComp.remove_banned_anim

**描述:** 解除部分动画的播放屏蔽

```lua
DisplayComp.remove_banned_anim(_anim_name)

参数列表:

参数	类型	说明
_anim_name	Str	动画名

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    unit.remove_banned_anim("平凡蛋0")
end)```

### DisplayComp.set_anim_rate

**描述:** 设置播放速率

```lua
DisplayComp.set_anim_rate(_anim_rate)

参数列表:

参数	类型	说明
_anim_rate	Fixed	播放速率

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    unit.set_anim_rate(1.0)
end)```

### Creature.set_draggable

**描述:** 设置生物是否可拖动

```lua
Creature.set_draggable(_enable)

参数列表:

参数	类型	说明
_enable	Bool	是否可拖动

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local creature = GameAPI.create_creature_fixed_scale(100001, math.Vector3(0,0,0), math.Quaternion(0,0,0), 1.0, GameAPI.get_all_valid_roles()[1])
    if not creature then return end
    creature.set_draggable(true)
end)```

### Creature.set_name

**描述:** 设置生物的显示名称

```lua
Creature.set_name(_name)

参数列表:

参数	类型	说明
_name	Str	显示名称

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local creature = GameAPI.create_creature_fixed_scale(100001, math.Vector3(0,0,0), math.Quaternion(0,0,0), 1.0, GameAPI.get_all_valid_roles()[1])
    if not creature then return end
    creature.set_name("平凡蛋0")
end)```

### Creature.set_name_visible

**描述:** 设置生物是否显示名称

```lua
Creature.set_name_visible(_visible)

参数列表:

参数	类型	说明
_visible	Bool	是否显示名称

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local creature = GameAPI.create_creature_fixed_scale(100001, math.Vector3(0,0,0), math.Quaternion(0,0,0), 1.0, GameAPI.get_all_valid_roles()[1])
    if not creature then return end
    creature.set_name_visible(true)
end)```

### Creature.set_dragged_plane_type

**描述:** 设置生物拖动平面

```lua
Creature.set_dragged_plane_type(_value)

参数列表:

参数	类型	说明
_value	PlaneType	拖动平面

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local creature = GameAPI.create_creature_fixed_scale(100001, math.Vector3(0,0,0), math.Quaternion(0,0,0), 1.0, GameAPI.get_all_valid_roles()[1])
    if not creature then return end
    creature.set_dragged_plane_type(Enums.PlaneType.XZ_PLANE)
end)```

### Creature.set_touchable

**描述:** 设置生物是否可点击

```lua
Creature.set_touchable(_enable)

参数列表:

参数	类型	说明
_enable	Bool	是否可点击

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local creature = GameAPI.create_creature_fixed_scale(100001, math.Vector3(0,0,0), math.Quaternion(0,0,0), 1.0, GameAPI.get_all_valid_roles()[1])
    if not creature then return end
    creature.set_touchable(true)
end)```

### Unit.show_bubble_msg

**描述:** 发送气泡信息

```lua
Unit.show_bubble_msg(_show_msg, _show_time, _max_dis, _offset)

参数列表:

参数	类型	说明
_show_msg	Str	气泡信息
_show_time	Fixed	持续时间
_max_dis	Fixed	隐藏距离
_offset	Vector3	偏移

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    unit.show_bubble_msg("消息内容", 1.0, 1.0, math.Vector3(0, 0, 0))
end)```

### DisplayComp.stop_anim

**描述:** 停止播放动画

```lua
DisplayComp.stop_anim()

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    unit.stop_anim()
end)```

### DisplayComp.stop_play_body_anim

**描述:** 停止播放全身动画

```lua
DisplayComp.stop_play_body_anim()

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    unit.stop_play_body_anim()
end)```

### DisplayComp.stop_play_body_anim_by_id

**描述:** 停止播放全身动画）

```lua
DisplayComp.stop_play_body_anim_by_id(_anim_id)

参数列表:

参数	类型	说明
_anim_id	AnimKey	动画编号

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    unit.stop_play_body_anim_by_id(250001)
end)```

### DisplayComp.stop_play_upper_anim

**描述:** 停止播放上半身动画

```lua
DisplayComp.stop_play_upper_anim()

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    unit.stop_play_upper_anim()
end)```

### DisplayComp.stop_play_upper_anim_by_id

**描述:** 停止播放上半身动画

```lua
DisplayComp.stop_play_upper_anim_by_id(_anim_id)

参数列表:

参数	类型	说明
_anim_id	AnimKey	动画编号

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    unit.stop_play_upper_anim_by_id(250001)
end)```

### Equipment.destroy_equipment

**描述:** 删除物品

```lua
Equipment.destroy_equipment()

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local equipment = GameAPI.create_equipment(400001, math.Vector3(0,0,0))
    if not equipment then return end
    equipment.destroy_equipment()
end)```

### ExprDeviceComp.disable_expr_device_by_name

**描述:** 通过名称禁用表现器

```lua
ExprDeviceComp.disable_expr_device_by_name(_name)

参数列表:

参数	类型	说明
_name	Str	名称

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    -- 表达式设备挂在触发器空间/障碍物上（非角色）：创建触发器空间（100001 为示意 key）
    local space = GameAPI.create_triggerspace(100001, role.get_ctrl_unit().get_position(), math.Quaternion(0, 0, 0), math.Vector3(10, 10, 10), role)
    if not space then return end
    space.disable_expr_device_by_name("平凡蛋0")
end)```

### Unit.disable_interact

**描述:** 禁用单位互动

```lua
Unit.disable_interact()

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    unit.disable_interact()
end)```

### Unit.disable_motor

**描述:** 禁用运动器

```lua
Unit.disable_motor(_index)

参数列表:

参数	类型	说明
_index	Int	索引

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    unit.disable_motor(1)
end)```

### DebugAPI.draw_line

**描述:** 绘制线段（调试）

```lua
DebugAPI.draw_line(_start_pos, _end_pos, _color, _duration)

参数列表:

参数	类型	说明
_start_pos	Vector3	起点
_end_pos	Vector3	终点
_color	Color	颜色
_duration	Fixed	时长

示例:

-- 调试：在场景中绘制一条红色线段，持续 3 秒后自动消失（用于验证移动轨迹）
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    -- 从角色头顶指向正前方 2 米处，绘制调试线
    local start_pos = role.get_ctrl_unit().get_position() + math.Vector3(0, 1.0, 0)
    local end_pos = start_pos + math.Vector3(0, 0, 2.0)
    DebugAPI.draw_line(start_pos, end_pos, GlobalAPI.str_to_color("ff0000"), 3.0)
end)

DebugAPI.draw_text

描述: 绘制文本（调试）

DebugAPI.draw_text(_pos, _text)

参数列表:

参数	类型	说明
_pos	Vector3	位置
_text	Str	文本

示例:

-- 调试：在角色头顶绘制调试文本，便于临时观察坐标信息
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    -- 显示角色当前位置（文本会跟随坐标显示在场景中）
    local pos = role.get_ctrl_unit().get_position()
    DebugAPI.draw_text(pos, string.format("玩家坐标: (%.1f, %.1f, %.1f)", pos.x, pos.y, pos.z))
end)

ExprDeviceComp.enable_expr_device_by_name

描述: 通过名称激活表现器

ExprDeviceComp.enable_expr_device_by_name(_name)

参数列表:

参数	类型	说明
_name	Str	名称

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    -- 表达式设备挂在触发器空间/障碍物上（非角色）：创建触发器空间（100001 为示意 key）
    local space = GameAPI.create_triggerspace(100001, role.get_ctrl_unit().get_position(), math.Quaternion(0, 0, 0), math.Vector3(10, 10, 10), role)
    if not space then return end
    space.enable_expr_device_by_name("平凡蛋0")
end)```

### Unit.enable_interact

**描述:** 激活单位互动

```lua
Unit.enable_interact()

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    unit.enable_interact()
end)```

### Unit.enable_motor

**描述:** 激活运动器

```lua
Unit.enable_motor(_index)

参数列表:

参数	类型	说明
_index	Int	索引

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    unit.enable_motor(1)
end)```

### AbilityComp.get_abilities

**描述:** 获取单位所有技能

```lua
AbilityComp.get_abilities()

返回值:

• 类型: ListAbility
• 说明: 技能对象

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = unit.get_abilities()
end)```

### AbilityComp.get_ability_list

**描述:** 获取单位所有技能

```lua
AbilityComp.get_ability_list()

返回值:

• 类型: ListAbility
• 说明: 技能列表

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = unit.get_ability_list()
end)```

### Ability.get_accumulate_ratio

**描述:** 获取技能蓄力百分比

```lua
Ability.get_accumulate_ratio()

返回值:

• 类型: Fixed
• 说明: 技能蓄力百分比

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local ability = unit.add_ability_to_slot(1, 150001, {}, {})
    if not ability then return end
    local result = ability.get_accumulate_ratio()
end)```

### Ability.get_affect_character_list

**描述:** 获取技能可以作用的角色列表

```lua
Ability.get_affect_character_list(_height, _use_fixed_release_point)

参数列表:

参数	类型	说明
_height	Fixed	高度差
_use_fixed_release_point	Bool	施法点是否固定

返回值:

• 类型: ListCharacter
• 说明: 可以影响的角色列表

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local ability = unit.add_ability_to_slot(1, 150001, {}, {})
    if not ability then return end
    local result = ability.get_affect_character_list(1.0, true)
end)```

### Ability.get_affect_creature_list

**描述:** 获取技能可以作用的生物列表

```lua
Ability.get_affect_creature_list(_height, _use_fixed_release_point)

参数列表:

参数	类型	说明
_height	Fixed	高度差
_use_fixed_release_point	Bool	施法点是否固定

返回值:

• 类型: ListCreature
• 说明: 可以影响的生物列表

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local ability = unit.add_ability_to_slot(1, 150001, {}, {})
    if not ability then return end
    local result = ability.get_affect_creature_list(1.0, true)
end)```

### Ability.get_affect_lifeentity_list

**描述:** 获取技能可以作用的生命体列表

```lua
Ability.get_affect_lifeentity_list(_height, _use_fixed_release_point)

参数列表:

参数	类型	说明
_height	Fixed	高度差
_use_fixed_release_point	Bool	施法点是否固定

返回值:

• 类型: ListLifeEntity
• 说明: 可以影响的生命体列表

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local ability = unit.add_ability_to_slot(1, 150001, {}, {})
    if not ability then return end
    local result = ability.get_affect_lifeentity_list(1.0, true)
end)```

### Ability.get_affect_obstacle_list

**描述:** 获取技能可以作用的组件列表

```lua
Ability.get_affect_obstacle_list(_height, _use_fixed_release_point)

参数列表:

参数	类型	说明
_height	Fixed	高度差
_use_fixed_release_point	Bool	施法点是否固定

返回值:

• 类型: ListObstacle
• 说明: 可以影响的组件列表

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local ability = unit.add_ability_to_slot(1, 150001, {}, {})
    if not ability then return end
    local result = ability.get_affect_obstacle_list(1.0, true)
end)```

### Ability.get_cd_time

**描述:** 获取技能冷却时间

```lua
Ability.get_cd_time()

返回值:

• 类型: Fixed
• 说明: 技能冷却时间

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local ability = unit.add_ability_to_slot(1, 150001, {}, {})
    if not ability then return end
    local result = ability.get_cd_time()
end)```

### Ability.get_left_charge_time

**描述:** 获取技能剩余充能时间

```lua
Ability.get_left_charge_time()

返回值:

• 类型: Fixed
• 说明: 剩余充能时间

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local ability = unit.add_ability_to_slot(1, 150001, {}, {})
    if not ability then return end
    local result = ability.get_left_charge_time()
end)```

### Ability.get_desc

**描述:** 获取技能描述

```lua
Ability.get_desc()

返回值:

• 类型: Str
• 说明: 技能描述

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local ability = unit.add_ability_to_slot(1, 150001, {}, {})
    if not ability then return end
    local result = ability.get_desc()
end)```

### Ability.get_pointer_type

**描述:** 获取技能指示器类型

```lua
Ability.get_pointer_type()

返回值:

• 类型: AbilityPointerType
• 说明: 指示器类型

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local ability = unit.add_ability_to_slot(1, 150001, {}, {})
    if not ability then return end
    local result = ability.get_pointer_type()
end)```

### Ability.get_key

**描述:** 获取技能编号

```lua
Ability.get_key()

返回值:

• 类型: AbilityKey
• 说明: 技能编号

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local ability = unit.add_ability_to_slot(1, 150001, {}, {})
    if not ability then return end
    local result = ability.get_key()
end)```

### Ability.get_left_cd_time

**描述:** 获取技能剩余冷却时间

```lua
Ability.get_left_cd_time()

返回值:

• 类型: Fixed
• 说明: 剩余冷却时间

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local ability = unit.add_ability_to_slot(1, 150001, {}, {})
    if not ability then return end
    local result = ability.get_left_cd_time()
end)```

### Ability.is_limitation_enabled

**描述:** 获取技能使用限制是否激活

```lua
Ability.is_limitation_enabled(_limit)

参数列表:

参数	类型	说明
_limit	AbilityLimitation	使用限制

返回值:

• 类型: Bool
• 说明: 是否激活

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local ability = unit.add_ability_to_slot(1, 150001, {}, {})
    if not ability then return end
    local result = ability.is_limitation_enabled(Enums.AbilityLimitation.NONE)
end)```

### Ability.get_lock_target_char

**描述:** 获取技能锁定角色

```lua
Ability.get_lock_target_char()

返回值:

• 类型: Character
• 说明: 角色

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local ability = unit.add_ability_to_slot(1, 150001, {}, {})
    if not ability then return end
    local result = ability.get_lock_target_char()
end)```

### Ability.get_lock_target_creature

**描述:** 获取技能锁定生物

```lua
Ability.get_lock_target_creature()

返回值:

• 类型: Creature
• 说明: 生物

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local ability = unit.add_ability_to_slot(1, 150001, {}, {})
    if not ability then return end
    local result = ability.get_lock_target_creature()
end)```

### Ability.get_lock_target

**描述:** 获取技能锁定目标

```lua
Ability.get_lock_target()

返回值:

• 类型: LifeEntity
• 说明: 获取技能锁定目标

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local ability = unit.add_ability_to_slot(1, 150001, {}, {})
    if not ability then return end
    local result = ability.get_lock_target()
end)```

### Ability.get_lock_obstacle

**描述:** 获取技能锁定目标

```lua
Ability.get_lock_obstacle()

返回值:

• 类型: Obstacle
• 说明: 获取技能锁定目标

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local ability = unit.add_ability_to_slot(1, 150001, {}, {})
    if not ability then return end
    local result = ability.get_lock_obstacle()
end)```

### Ability.get_name

**描述:** 获取技能名称

```lua
Ability.get_name()

返回值:

• 类型: Str
• 说明: 技能名称

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local ability = unit.add_ability_to_slot(1, 150001, {}, {})
    if not ability then return end
    local result = ability.get_name()
end)```

### Ability.get_owner

**描述:** 获取技能拥有者

```lua
Ability.get_owner()

返回值:

• 类型: LifeEntity
• 说明: 技能拥有者

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local ability = unit.add_ability_to_slot(1, 150001, {}, {})
    if not ability then return end
    local result = ability.get_owner()
end)```

### Ability.get_owner_character

**描述:** 获取技能拥有角色

```lua
Ability.get_owner_character()

返回值:

• 类型: Character
• 说明: 角色

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local ability = unit.add_ability_to_slot(1, 150001, {}, {})
    if not ability then return end
    local result = ability.get_owner_character()
end)```

### Ability.get_owner_creature

**描述:** 获取技能拥有生物

```lua
Ability.get_owner_creature()

返回值:

• 类型: Creature
• 说明: 生物

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local ability = unit.add_ability_to_slot(1, 150001, {}, {})
    if not ability then return end
    local result = ability.get_owner_creature()
end)```

### Ability.get_owner_equipment

**描述:** 获取拥有技能的物品

```lua
Ability.get_owner_equipment()

返回值:

• 类型: Equipment
• 说明: 技能拥有者

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local ability = unit.add_ability_to_slot(1, 150001, {}, {})
    if not ability then return end
    local result = ability.get_owner_equipment()
end)```

### Ability.get_release_direction

**描述:** 获取技能释放方向

```lua
Ability.get_release_direction()

返回值:

• 类型: Vector3
• 说明: 方向

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local ability = unit.add_ability_to_slot(1, 150001, {}, {})
    if not ability then return end
    local result = ability.get_release_direction()
end)```

### Ability.get_release_direction_list

**描述:** 获取技能复数释放方向

```lua
Ability.get_release_direction_list()

返回值:

• 类型: ListVector3
• 说明: 方向

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local ability = unit.add_ability_to_slot(1, 150001, {}, {})
    if not ability then return end
    local result = ability.get_release_direction_list()
end)```

### Ability.get_release_point

**描述:** 获取技能释放坐标点

```lua
Ability.get_release_point()

返回值:

• 类型: Point3
• 说明: 坐标点

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local ability = unit.add_ability_to_slot(1, 150001, {}, {})
    if not ability then return end
    local result = ability.get_release_point()
end)```

### Ability.get_release_point_list

**描述:** 获取技能复数释放坐标点

```lua
Ability.get_release_point_list()

返回值:

• 类型: ListPoint3
• 说明: 坐标点

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local ability = unit.add_ability_to_slot(1, 150001, {}, {})
    if not ability then return end
    local result = ability.get_release_point_list()
end)```

### Ability.get_ability_slot

**描述:** 获取技能所在槽位

```lua
Ability.get_ability_slot()

返回值:

• 类型: AbilitySlot
• 说明: 技能槽位

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local ability = unit.add_ability_to_slot(1, 150001, {}, {})
    if not ability then return end
    local result = ability.get_ability_slot()
end)```

### Role.get_achievement_progress

**描述:** 获取成就进度

```lua
Role.get_achievement_progress(_event_id)

参数列表:

参数	类型	说明
_event_id	Achievement	成就

返回值:

• 类型: Int
• 说明: 成就进度

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local achievement = 1  -- Achievement 是成就编号（integer）
    local result = role.get_achievement_progress(achievement)
end)```

### Obstacle.get_billboard_text

**描述:** 获取公告板文本内容

```lua
Obstacle.get_billboard_text()

返回值:

• 类型: Str
• 说明: 公告板内容

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local obstacle = GameAPI.create_obstacle(200001, math.Vector3(0,0,0), math.Quaternion(0,0,0), math.Vector3(1,1,1), nil)
    if not obstacle then return end
    local result = obstacle.get_billboard_text()
end)```

### Obstacle.get_billboard_font_size

**描述:** 获取公告板文本字体大小

```lua
Obstacle.get_billboard_font_size()

返回值:

• 类型: Int
• 说明: 公告板字体大小

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local obstacle = GameAPI.create_obstacle(200001, math.Vector3(0,0,0), math.Quaternion(0,0,0), math.Vector3(1,1,1), nil)
    if not obstacle then return end
    local result = obstacle.get_billboard_font_size()
end)```

### BuffStateComp.get_state_count

**描述:** 获取限制状态计数

```lua
BuffStateComp.get_state_count(_state_id)

参数列表:

参数	类型	说明
_state_id	BuffState	状态

返回值:

• 类型: Int
• 说明: 状态计数

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = unit.get_state_count(Enums.BuffState.BUFF_FORBID_MOVE)
end)```

### BuffStateComp.get_state_list

**描述:** 获取所有限制状态

```lua
BuffStateComp.get_state_list()

返回值:

• 类型: ListBuffState
• 说明: 状态列表

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = unit.get_state_list()
end)```

### Role.get_camera_direction

**描述:** 获取玩家相机的朝向(需要开启玩家相机旋转同步)

```lua
Role.get_camera_direction()

返回值:

• 类型: Vector3
• 说明: 相机朝向

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = role.get_camera_direction()
end)```

### Camp.get_name

**描述:** 获取阵营名称

```lua
Camp.get_name()

返回值:

• 类型: Str
• 说明: 名称

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local camp = GameAPI.get_camp(1)
    if not camp then return end
    local result = camp.get_name()
end)```

### Character.get_climb_obstacle

**描述:** 获取角色攀爬的组件

```lua
Character.get_climb_obstacle()

返回值:

• 类型: Obstacle
• 说明: 攀爬的组件

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- Character 继承自 LifeEntity，代表NPC角色单位
    if not npc then return end
    local result = npc.get_climb_obstacle()
end)```

### Unit.get_parent

**描述:** 获取父单位

```lua
Unit.get_parent()

返回值:

• 类型: Unit
• 说明: 单位

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local result = unit.get_parent()
end)```

### Character.get_ability_point

**描述:** 获取技能点

```lua
Character.get_ability_point()

返回值:

• 类型: Int
• 说明: 技能点

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- Character 继承自 LifeEntity，代表NPC角色单位
    if not npc then return end
    local result = npc.get_ability_point()
end)```

### Obstacle.get_chess_rank

**描述:** 获取牌数(对象只能为麻将/扑克)

```lua
Obstacle.get_chess_rank()

返回值:

• 类型: Int
• 说明: 牌数

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local obstacle = GameAPI.create_obstacle(200001, math.Vector3(0,0,0), math.Quaternion(0,0,0), math.Vector3(1,1,1), nil)
    if not obstacle then return end
    local result = obstacle.get_chess_rank()
end)```

### Obstacle.get_chess_type

**描述:** 获取牌名(对象只能为麻将/扑克)

```lua
Obstacle.get_chess_type()

返回值:

• 类型: ChessType
• 说明: 牌名

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local obstacle = GameAPI.create_obstacle(200001, math.Vector3(0,0,0), math.Quaternion(0,0,0), math.Vector3(1,1,1), nil)
    if not obstacle then return end
    local result = obstacle.get_chess_type()
end)```

### Unit.get_child_customtriggerspaces

**描述:** 获得所有子触发区域单位

```lua
Unit.get_child_customtriggerspaces()

返回值:

• 类型: ListCustomTriggerSpace
• 说明: 触发区域列表

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local result = unit.get_child_customtriggerspaces()
end)```

### Unit.get_child_obstacles

**描述:** 获得所有子物理组件单位

```lua
Unit.get_child_obstacles()

返回值:

• 类型: ListObstacle
• 说明: 组件列表

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local result = unit.get_child_obstacles()
end)```

### Unit.get_children

**描述:** 获得所有子单位

```lua
Unit.get_children()

返回值:

• 类型: ListUnit
• 说明: 单位列表

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local result = unit.get_children()
end)```

### Creature.get_name

**描述:** 获取生物名称

```lua
Creature.get_name()

返回值:

• 类型: Str
• 说明: 生物名称

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local creature = GameAPI.create_creature_fixed_scale(100001, math.Vector3(0,0,0), math.Quaternion(0,0,0), 1.0, GameAPI.get_all_valid_roles()[1])
    if not creature then return end
    local result = creature.get_name()
end)```

### Character.get_ctrl_role

**描述:** 获取控制角色的玩家

```lua
Character.get_ctrl_role()

返回值:

• 类型: Role
• 说明: 玩家

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- Character 继承自 LifeEntity，代表NPC角色单位
    if not npc then return end
    local result = npc.get_ctrl_role()
end)```

### Role.get_ctrl_unit

**描述:** 获取控制单位

```lua
Role.get_ctrl_unit()

返回值:

• 类型: Character
• 说明: 单位

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = role.get_ctrl_unit()
end)```

### CustomTriggerSpace.random_point

**描述:** 获取触发区域内的随机坐标

```lua
CustomTriggerSpace.random_point()

返回值:

• 类型: Vector3
• 说明: 坐标

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local cts = GameAPI.create_customtriggerspace(110001, math.Vector3(0,0,0), math.Quaternion(0,0,0), math.Vector3(1,1,1), nil)
    if not cts then return end
    local result = cts.random_point()
end)```

### Equipment.is_auto_picking

**描述:** 获取物品是否自动拾取

```lua
Equipment.is_auto_picking()

返回值:

• 类型: Bool
• 说明: 是否自动拾取

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local equipment = GameAPI.create_equipment(400001, math.Vector3(0,0,0))
    if not equipment then return end
    local result = equipment.is_auto_picking()
end)```

### Equipment.is_auto_using

**描述:** 获取物品是否自动使用

```lua
Equipment.is_auto_using()

返回值:

• 类型: Bool
• 说明: 是否自动使用

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local equipment = GameAPI.create_equipment(400001, math.Vector3(0,0,0))
    if not equipment then return end
    local result = equipment.is_auto_using()
end)```

### Equipment.can_drop

**描述:** 获取物品能否丢弃

```lua
Equipment.can_drop()

返回值:

• 类型: Bool
• 说明: 能否丢弃

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local equipment = GameAPI.create_equipment(400001, math.Vector3(0,0,0))
    if not equipment then return end
    local result = equipment.can_drop()
end)```

### Equipment.get_current_stack_num

**描述:** 获取物品当前堆叠层数

```lua
Equipment.get_current_stack_num()

返回值:

• 类型: Int
• 说明: 当前堆叠层数

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local equipment = GameAPI.create_equipment(400001, math.Vector3(0,0,0))
    if not equipment then return end
    local result = equipment.get_current_stack_num()
end)```

### Equipment.get_desc

**描述:** 获取物品描述

```lua
Equipment.get_desc()

返回值:

• 类型: Str
• 说明: 物品描述

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local equipment = GameAPI.create_equipment(400001, math.Vector3(0,0,0))
    if not equipment then return end
    local result = equipment.get_desc()
end)```

### Equipment.get_price

**描述:** 获取物品的抵押价格

```lua
Equipment.get_price(_res_type)

参数列表:

参数	类型	说明
_res_type	Str	货币类型

返回值:

• 类型: Int
• 说明: 卖价

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local equipment = GameAPI.create_equipment(400001, math.Vector3(0,0,0))
    if not equipment then return end
    local result = equipment.get_price("示例字符串")
end)```

### Equipment.has_owner

**描述:** 物品是否被持有

```lua
Equipment.has_owner()

返回值:

• 类型: Bool
• 说明: 是否被持有

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local equipment = GameAPI.create_equipment(400001, math.Vector3(0,0,0))
    if not equipment then return end
    local result = equipment.has_owner()
end)```

### Equipment.get_key

**描述:** 获取物品的物品编号

```lua
Equipment.get_key()

返回值:

• 类型: EquipmentKey
• 说明: 物品编号

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local equipment = GameAPI.create_equipment(400001, math.Vector3(0,0,0))
    if not equipment then return end
    local result = equipment.get_key()
end)```

### EquipmentComp.get_equipment_list_by_slot_type

**描述:** 获取持有的物品列表

```lua
EquipmentComp.get_equipment_list_by_slot_type(_slot_type)

参数列表:

参数	类型	说明
_slot_type	EquipmentSlotType	槽位类型

返回值:

• 类型: ListEquipment
• 说明: 物品

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = unit.get_equipment_list_by_slot_type(Enums.EquipmentSlotType.EQUIPPED)
end)```

### EquipmentComp.get_equipment_max_count

**描述:** 获取最大可持有的物品数量

```lua
EquipmentComp.get_equipment_max_count(_slot_type)

参数列表:

参数	类型	说明
_slot_type	EquipmentSlotType	槽位类型

返回值:

• 类型: Int
• 说明: 数量

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = unit.get_equipment_max_count(Enums.EquipmentSlotType.EQUIPPED)
end)```

### Equipment.get_max_stack_num

**描述:** 获取物品最大堆叠层数

```lua
Equipment.get_max_stack_num()

返回值:

• 类型: Int
• 说明: 最大堆叠层数

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local equipment = GameAPI.create_equipment(400001, math.Vector3(0,0,0))
    if not equipment then return end
    local result = equipment.get_max_stack_num()
end)```

### Equipment.get_name

**描述:** 获取物品名称

```lua
Equipment.get_name()

返回值:

• 类型: Str
• 说明: 物品名称

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local equipment = GameAPI.create_equipment(400001, math.Vector3(0,0,0))
    if not equipment then return end
    local result = equipment.get_name()
end)```

### Equipment.get_owner_character

**描述:** 获取持有物品的角色

```lua
Equipment.get_owner_character()

返回值:

• 类型: Character
• 说明: 角色

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local equipment = GameAPI.create_equipment(400001, math.Vector3(0,0,0))
    if not equipment then return end
    local result = equipment.get_owner_character()
end)```

### Equipment.get_owner_creature

**描述:** 获取持有物品的生物

```lua
Equipment.get_owner_creature()

返回值:

• 类型: Creature
• 说明: 生物

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local equipment = GameAPI.create_equipment(400001, math.Vector3(0,0,0))
    if not equipment then return end
    local result = equipment.get_owner_creature()
end)```

### Equipment.get_position

**描述:** 获取物品位置

```lua
Equipment.get_position()

返回值:

• 类型: Point3
• 说明: 物品位置

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local equipment = GameAPI.create_equipment(400001, math.Vector3(0,0,0))
    if not equipment then return end
    local result = equipment.get_position()
end)```

### Equipment.get_unit

**描述:** 获取物品单位

```lua
Equipment.get_unit()

返回值:

• 类型: Obstacle
• 说明: 物品单位

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local equipment = GameAPI.create_equipment(400001, math.Vector3(0,0,0))
    if not equipment then return end
    local result = equipment.get_unit()
end)```

### Equipment.get_equipment_slot

**描述:** 获取物品所在槽位

```lua
Equipment.get_equipment_slot()

返回值:

• 类型: EquipmentSlot
• 说明: 槽位

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local equipment = GameAPI.create_equipment(400001, math.Vector3(0,0,0))
    if not equipment then return end
    local result = equipment.get_equipment_slot()
end)```

### Equipment.get_slot_type

**描述:** 获取物品所在槽位类型

```lua
Equipment.get_slot_type()

返回值:

• 类型: EquipmentSlotType
• 说明: 槽位类型

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local equipment = GameAPI.create_equipment(400001, math.Vector3(0,0,0))
    if not equipment then return end
    local result = equipment.get_slot_type()
end)```

### Equipment.get_equipment_type

**描述:** 获取物品的物品类型

```lua
Equipment.get_equipment_type()

返回值:

• 类型: EquipmentType
• 说明: 物品类型

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local equipment = GameAPI.create_equipment(400001, math.Vector3(0,0,0))
    if not equipment then return end
    local result = equipment.get_equipment_type()
end)```

### LifeEntity.get_direction

**描述:** 获取生命实体的朝向

```lua
LifeEntity.get_direction()

返回值:

• 类型: Vector3
• 说明: 方向

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- NPC单位，AI行为的执行者
    if not npc then return end
    local result = npc.get_direction()
end)```

### UnitInteractVolumeComp.get_interact_id

**描述:** 获取单位互动按钮ID

```lua
UnitInteractVolumeComp.get_interact_id(_interact_index, _interact_btn_type)

参数列表:

参数	类型	说明
_interact_index	Int	互动索引
_interact_btn_type	InteractBtnType	互动按钮类型

返回值:

• 类型: InteractBtnID
• 说明: 互动按钮ID

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = unit.get_interact_id(1, Enums.InteractBtnType.OFFICIAL)
end)```

### Ability.is_in_cd

**描述:** 技能是否在冷却中

```lua
Ability.is_in_cd()

返回值:

• 类型: Bool
• 说明: 剩余冷却时间

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local ability = unit.add_ability_to_slot(1, 150001, {}, {})
    if not ability then return end
    local result = ability.is_in_cd()
end)```

### Ability.is_in_charge

**描述:** 技能是否在充能中

```lua
Ability.is_in_charge()

返回值:

• 类型: Bool
• 说明: 技能是否在充能中

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local ability = unit.add_ability_to_slot(1, 150001, {}, {})
    if not ability then return end
    local result = ability.is_in_charge()
end)```

### JointAssistantComp.get_joint_assistant_primary_obstacle

**描述:** 获取关节组件主体

```lua
JointAssistantComp.get_joint_assistant_primary_obstacle()

返回值:

• 类型: Character
• 说明: 关节组件主体

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    -- 关节辅助方法挂在关节单位上：取角色身上的第一个辅助关节
    local joints = GameAPI.get_joint_assistants(role.get_ctrl_unit())
    local joint = joints and joints[1]
    if not joint then return end
    local result = joint.get_joint_assistant_primary_obstacle()
end)```

### JointAssistantComp.get_joint_assistant_target_obstacle

**描述:** 获取关节组件目标

```lua
JointAssistantComp.get_joint_assistant_target_obstacle()

返回值:

• 类型: Character
• 说明: 关节组件目标

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    -- 关节辅助方法挂在关节单位上：取角色身上的第一个辅助关节
    local joints = GameAPI.get_joint_assistants(role.get_ctrl_unit())
    local joint = joints and joints[1]
    if not joint then return end
    local result = joint.get_joint_assistant_target_obstacle()
end)```

### JointAssistantComp.get_joint_assistant_type

**描述:** 获取关节组件类型

```lua
JointAssistantComp.get_joint_assistant_type()

返回值:

• 类型: JointAssistantType
• 说明: 关节类型

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    -- 关节辅助方法挂在关节单位上：取角色身上的第一个辅助关节
    local joints = GameAPI.get_joint_assistants(role.get_ctrl_unit())
    local joint = joints and joints[1]
    if not joint then return end
    local result = joint.get_joint_assistant_type()
end)```

### LifeEntity.get_hpbar_scale_x

**描述:** 获取生命体血条宽度缩放

```lua
LifeEntity.get_hpbar_scale_x()

返回值:

• 类型: Fixed
• 说明: 宽度缩放

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- NPC单位，AI行为的执行者
    if not npc then return end
    local result = npc.get_hpbar_scale_x()
end)```

### LifeEntity.get_hpbar_scale_y

**描述:** 获取生命体血条高度缩放

```lua
LifeEntity.get_hpbar_scale_y()

返回值:

• 类型: Fixed
• 说明: 高度缩放

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- NPC单位，AI行为的执行者
    if not npc then return end
    local result = npc.get_hpbar_scale_y()
end)```

### LifeEntity.get_lifted_lifeentity

**描述:** 获取指定生命体当前抓举的生命体

```lua
LifeEntity.get_lifted_lifeentity()

返回值:

• 类型: LifeEntity
• 说明: 被抓举的生命体

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- NPC单位，AI行为的执行者
    if not npc then return end
    local result = npc.get_lifted_lifeentity()
end)```

### LifeEntity.get_lifted_obstacle

**描述:** 获取指定生命体当前抓举的组件

```lua
LifeEntity.get_lifted_obstacle()

返回值:

• 类型: Obstacle
• 说明: 被抓举的组件

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- NPC单位，AI行为的执行者
    if not npc then return end
    local result = npc.get_lifted_obstacle()
end)```

### LiftComp.get_lift_cooldown

**描述:** 获取举起冷却时间

```lua
LiftComp.get_lift_cooldown()

返回值:

• 类型: Fixed
• 说明: 实数

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = unit.get_lift_cooldown()
end)```

### LiftComp.get_lift_remaining_cooldown

**描述:** 获取举起剩余冷却时间

```lua
LiftComp.get_lift_remaining_cooldown()

返回值:

• 类型: Fixed
• 说明: 实数

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = unit.get_lift_remaining_cooldown()
end)```

### Unit.get_linear_velocity

**描述:** 获取单位线速度

```lua
Unit.get_linear_velocity()

返回值:

• 类型: Vector3
• 说明: 线速度

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local result = unit.get_linear_velocity()
end)```

### Unit.get_local_direction

**描述:** 获取单位本地坐标系下的方向

```lua
Unit.get_local_direction(_direction_type)

参数列表:

参数	类型	说明
_direction_type	DirectionType	方向

返回值:

• 类型: Vector3
• 说明: 向量

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local result = unit.get_local_direction(Enums.DirectionType.FORWARD)
end)```

### Unit.get_local_quaternion

**描述:** 获取单位本地坐标系下的旋转角

```lua
Unit.get_local_quaternion(_direction_type)

参数列表:

参数	类型	说明
_direction_type	DirectionType	方向

返回值:

• 类型: Quaternion
• 说明: Quaternion

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local result = unit.get_local_quaternion(Enums.DirectionType.FORWARD)
end)```

### Modifier.get_max_stack_count

**描述:** 获取效果的最大层数

```lua
Modifier.get_max_stack_count()

返回值:

• 类型: Str
• 说明: 层数

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local modifier = unit.add_modifier_by_key(600001, {})
    if not modifier then return end
    local result = modifier.get_max_stack_count()
end)```

### ModifierComp.get_modifier_by_modifier_key

**描述:** 获取单位效果

```lua
ModifierComp.get_modifier_by_modifier_key(_modifier_id)

参数列表:

参数	类型	说明
_modifier_id	ModifierKey	效果ID

返回值:

• 类型: Modifier
• 说明: 效果对象

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = unit.get_modifier_by_modifier_key(600001)
end)```

### ModifierComp.get_modifiers

**描述:** 获取单位所有效果

```lua
ModifierComp.get_modifiers()

返回值:

• 类型: ListModifier
• 说明: 效果

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = unit.get_modifiers()
end)```

### Modifier.get_desc

**描述:** 获取效果描述

```lua
Modifier.get_desc()

返回值:

• 类型: Str
• 说明: 效果描述

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local modifier = unit.add_modifier_by_key(600001, {})
    if not modifier then return end
    local result = modifier.get_desc()
end)```

### Modifier.get_key

**描述:** 获得效果编号

```lua
Modifier.get_key()

返回值:

• 类型: ModifierKey
• 说明: 效果编号

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local modifier = unit.add_modifier_by_key(600001, {})
    if not modifier then return end
    local result = modifier.get_key()
end)```

### Modifier.get_name

**描述:** 获取效果名称

```lua
Modifier.get_name()

返回值:

• 类型: Str
• 说明: 效果名称

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local modifier = unit.add_modifier_by_key(600001, {})
    if not modifier then return end
    local result = modifier.get_name()
end)```

### Modifier.get_owner_unit

**描述:** 获取效果携带者

```lua
Modifier.get_owner_unit()

返回值:

• 类型: Unit
• 说明: 效果携带者

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local modifier = unit.add_modifier_by_key(600001, {})
    if not modifier then return end
    local result = modifier.get_owner_unit()
end)```

### Modifier.get_owner_ability

**描述:** 获取所属技能

```lua
Modifier.get_owner_ability()

返回值:

• 类型: Ability
• 说明: 所属技能

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local modifier = unit.add_modifier_by_key(600001, {})
    if not modifier then return end
    local result = modifier.get_owner_ability()
end)```

### Modifier.get_owner_character

**描述:** 获取效果携带角色

```lua
Modifier.get_owner_character()

返回值:

• 类型: Character
• 说明: 角色

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local modifier = unit.add_modifier_by_key(600001, {})
    if not modifier then return end
    local result = modifier.get_owner_character()
end)```

### Modifier.get_owner_creature

**描述:** 获取效果携带生物

```lua
Modifier.get_owner_creature()

返回值:

• 类型: Creature
• 说明: 生物

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local modifier = unit.add_modifier_by_key(600001, {})
    if not modifier then return end
    local result = modifier.get_owner_creature()
end)```

### Modifier.get_owner_life_entity

**描述:** 获取携带效果的生命体

```lua
Modifier.get_owner_life_entity()

返回值:

• 类型: LifeEntity
• 说明: 生命体

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local modifier = unit.add_modifier_by_key(600001, {})
    if not modifier then return end
    local result = modifier.get_owner_life_entity()
end)```

### Modifier.get_remain_duration

**描述:** 获取效果剩余持续时间

```lua
Modifier.get_remain_duration()

返回值:

• 类型: Fixed
• 说明: 剩余持续时间

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local modifier = unit.add_modifier_by_key(600001, {})
    if not modifier then return end
    local result = modifier.get_remain_duration()
end)```

### Obstacle.get_bound_equipment

**描述:** 返回绑定的物品

```lua
Obstacle.get_bound_equipment()

返回值:

• 类型: Equipment
• 说明: 物品

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local obstacle = GameAPI.create_obstacle(200001, math.Vector3(0,0,0), math.Quaternion(0,0,0), math.Vector3(1,1,1), nil)
    if not obstacle then return end
    local result = obstacle.get_bound_equipment()
end)```

### Obstacle.get_name

**描述:** 获取组件的名称

```lua
Obstacle.get_name()

返回值:

• 类型: Str
• 说明: 名称

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local obstacle = GameAPI.create_obstacle(200001, math.Vector3(0,0,0), math.Quaternion(0,0,0), math.Vector3(1,1,1), nil)
    if not obstacle then return end
    local result = obstacle.get_name()
end)```

### OwnerComp.get_owner_role

**描述:** 获取所属玩家

```lua
OwnerComp.get_owner_role()

返回值:

• 类型: Role
• 说明: 所属玩家

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    -- OwnerComp 挂在生物/触发器空间上（非角色）：创建生物（100001 为示意 key）
    local pet = GameAPI.create_creature_fixed_scale(100001, role.get_ctrl_unit().get_position(), math.Quaternion(0, 0, 0), 1.0, role)
    if not pet then return end
    local result = pet.get_owner_role()
end)```

### Role.get_camera_rotation

**描述:** 获取玩家相机的旋转(需要开启玩家相机旋转同步)

```lua
Role.get_camera_rotation()

返回值:

• 类型: Quaternion
• 说明: 相机旋转

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = role.get_camera_rotation()
end)```

### Role.get_head_icon

**描述:** 获取玩家头像

```lua
Role.get_head_icon()

返回值:

• 类型: ImageKey
• 说明: 玩家头像

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = role.get_head_icon()
end)```

### Camp.get_roles

**描述:** 获取阵营内玩家列表

```lua
Camp.get_roles()

返回值:

• 类型: ListRole
• 说明: 玩家列表

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local camp = GameAPI.get_camp(1)
    if not camp then return end
    local result = camp.get_roles()
end)```

### Role.get_map_total_cost

**描述:** 获取玩家在当前地图累计花费

```lua
Role.get_map_total_cost()

返回值:

• 类型: Fixed
• 说明: 累计花费

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = role.get_map_total_cost()
end)```

### Role.get_name

**描述:** 获取玩家昵称

```lua
Role.get_name()

返回值:

• 类型: Str
• 说明: 名字

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = role.get_name()
end)```

### Role.get_party_id

**描述:** 获取玩家蛋仔岛组队Id

```lua
Role.get_party_id()

返回值:

• 类型: Str
• 说明: 队伍Id

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = role.get_party_id()
end)```

### Role.get_voice_volume

**描述:** 获取语音音量

```lua
Role.get_voice_volume()

返回值:

• 类型: Fixed
• 说明: 语音音量

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = role.get_voice_volume()
end)```

### RollComp.get_roll_remaining_cooldown

**描述:** 获取滚动剩余冷却时间

```lua
RollComp.get_roll_remaining_cooldown()

返回值:

• 类型: Fixed
• 说明: 剩余冷却时间

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = unit.get_roll_remaining_cooldown()
end)```

### RushComp.get_rush_remaining_cooldown

**描述:** 获取飞扑剩余冷却时间

```lua
RushComp.get_rush_remaining_cooldown()

返回值:

• 类型: Fixed
• 说明: 剩余冷却时间

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = unit.get_rush_remaining_cooldown()
end)```

### EquipmentComp.get_selected_equipment

**描述:** 获取当前选中的物品

```lua
EquipmentComp.get_selected_equipment()

返回值:

• 类型: Equipment
• 说明: 物品

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = unit.get_selected_equipment()
end)```

### EquipmentComp.get_equipment_by_slot

**描述:** 获取身上的物品

```lua
EquipmentComp.get_equipment_by_slot(_slot_type, _slot_index)

参数列表:

参数	类型	说明
_slot_type	EquipmentSlotType	槽位类型
_slot_index	Int	槽位索引

返回值:

• 类型: Equipment
• 说明: 物品

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = unit.get_equipment_by_slot(Enums.EquipmentSlotType.EQUIPPED, 1)
end)```

### Modifier.get_stack_count

**描述:** 获取效果当前层数

```lua
Modifier.get_stack_count()

返回值:

• 类型: Str
• 说明: 层数

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local modifier = unit.add_modifier_by_key(600001, {})
    if not modifier then return end
    local result = modifier.get_stack_count()
end)```

### AbilityComp.get_ability_by_slot

**描述:** 获取对应槽位技能

```lua
AbilityComp.get_ability_by_slot(_ability_slot)

参数列表:

参数	类型	说明
_ability_slot	AbilitySlot	技能槽位

返回值:

• 类型: Ability
• 说明: 技能对象

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local ability_slot = 1  -- AbilitySlot 是槽位整数索引
    local result = unit.get_ability_by_slot(ability_slot)
end)```

### EquipmentComp.get_equipment_list

**描述:** 获取角色/生物持有的物品预设列表

```lua
EquipmentComp.get_equipment_list(_equipment_key, _exclude_equipped, _exclude_bag)

参数列表:

参数	类型	说明
_equipment_key	EquipmentKey	物品类型
_exclude_equipped	Bool	不搜索物品栏
_exclude_bag	Bool	不搜索背包栏

返回值:

• 类型: ListEquipment
• 说明: 物品列表

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = unit.get_equipment_list(400001, true, true)
end)```

### Actor.get_id

**描述:** 获取单位ID

```lua
Actor.get_id()

返回值:

• 类型: UnitID
• 说明: 单位ID

示例:

-- 获取单位 ID（Actor 方法挂在单位实例上）
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end

    local result = unit.get_id()
end)```

### Unit.get_key

**描述:** 获取单位编号

```lua
Unit.get_key()

返回值:

• 类型: UnitKey
• 说明: 单位编号

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local result = unit.get_key()
end)```

### Unit.get_orientation

**描述:** 获得单位旋转

```lua
Unit.get_orientation()

返回值:

• 类型: Quaternion
• 说明: 旋转

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local result = unit.get_orientation()
end)```

### Unit.get_position

**描述:** 获取单位坐标

```lua
Unit.get_position()

返回值:

• 类型: Vector3
• 说明: 坐标

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local result = unit.get_position()
end)```

### Unit.get_rigid_body_type

**描述:** 获取受力类型

```lua
Unit.get_rigid_body_type()

返回值:

• 类型: RigidBodyType
• 说明: 受力类型

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local result = unit.get_rigid_body_type()
end)```

### Unit.get_scale

**描述:** 获得单位缩放

```lua
Unit.get_scale()

返回值:

• 类型: Vector3
• 说明: 缩放

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local result = unit.get_scale()
end)```

### Unit.get_unit_type

**描述:** 获取单位类型

```lua
Unit.get_unit_type()

返回值:

• 类型: UnitType
• 说明: 单位类型

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local result = unit.get_unit_type()
end)```

### TriggerSpace.get_virtual_light_brightness

**描述:** 获取光源亮度

```lua
TriggerSpace.get_virtual_light_brightness()

返回值:

• 类型: Fixed
• 说明: 亮度

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local ts = GameAPI.create_triggerspace(900001, math.Vector3(0,0,0), math.Quaternion(0,0,0), math.Vector3(1,1,1), nil)
    if not ts then return end
    local result = ts.get_virtual_light_brightness()
end)```

### KVBase.has_kv

**描述:** 是否有自定义值

```lua
KVBase.has_kv(_key)

参数列表:

参数	类型	说明
_key	Str	名称

返回值:

• 类型: Bool
• 说明: 是否有自定义值

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = unit.has_kv("key_001")
end)```

### KVBase.has_tag

**描述:** 是否有标签

```lua
KVBase.has_tag(_tag)

参数列表:

参数	类型	说明
_tag	Str	标签

返回值:

• 类型: Bool
• 说明: 是否有标签

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = unit.has_tag("enemy")
end)```

### Character.increase_ability_point

**描述:** 增加技能点

```lua
Character.increase_ability_point(_increase)

参数列表:

参数	类型	说明
_increase	Int	技能点

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- Character 继承自 LifeEntity，代表NPC角色单位
    if not npc then return end
    npc.increase_ability_point(1)
end)```

### Camp.get_camp_score

**描述:** 获取阵营积分

```lua
Camp.get_camp_score()

返回值:

• 类型: Int
• 说明: 积分

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local camp = GameAPI.get_camp(1)
    if not camp then return end
    local result = camp.get_camp_score()
end)```

### Role.get_score

**描述:** 获取玩家积分

```lua
Role.get_score()

返回值:

• 类型: Int
• 说明: 积分

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = role.get_score()
end)```

### LifeComp.is_die_status

**描述:** 是否处于死亡状态

```lua
LifeComp.is_die_status()

返回值:

• 类型: Bool
• 说明: 是否处于死亡

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = unit.is_die_status()
end)```

### Unit.is_model_visible

**描述:** 单位模型是否可见

```lua
Unit.is_model_visible()

返回值:

• 类型: Bool
• 说明: 是否隐藏

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local result = unit.is_model_visible()
end)```

### Unit.is_physics_active

**描述:** 单位物理是否生效

```lua
Unit.is_physics_active()

返回值:

• 类型: Bool
• 说明: 是否物理生效

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local result = unit.is_physics_active()
end)```

### LifeEntity.is_draggable

**描述:** 获取生命体是否可拖动

```lua
LifeEntity.is_draggable()

返回值:

• 类型: Bool
• 说明: 是否可拖动

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- NPC单位，AI行为的执行者
    if not npc then return end
    local result = npc.is_draggable()
end)```

### LifeEntity.is_touchable

**描述:** 获取生命体是否可点击

```lua
LifeEntity.is_touchable()

返回值:

• 类型: Bool
• 说明: 是否可点击

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- NPC单位，AI行为的执行者
    if not npc then return end
    local result = npc.is_touchable()
end)```

### MoveStatusComp.is_fling_status

**描述:** 前是否处于滚动状态

```lua
MoveStatusComp.is_fling_status()

返回值:

• 类型: Bool
• 说明: 是否滚动

示例:

-- 判断角色当前是否处于被击飞状态
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end

    -- comp 方法直接挂在单位对象上调用
    local flinging = unit.is_fling_status()
    LuaAPI.log("被击飞状态: " .. tostring(flinging), 0)
end)```

### CharacterComp.is_forced_moving

**描述:** 是否正在强制位移

```lua
CharacterComp.is_forced_moving()

返回值:

• 类型: Bool
• 说明: 是否正在强制位移

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = unit.is_forced_moving()
end)```

### ModifierComp.has_modifier_by_key

**描述:** 是否拥有指定编号的效果

```lua
ModifierComp.has_modifier_by_key(_modifier_key)

参数列表:

参数	类型	说明
_modifier_key	ModifierKey	效果编号

返回值:

• 类型: Bool
• 说明: 是否拥有

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = unit.has_modifier_by_key(600001)
end)```

### LiftComp.is_lift_status

**描述:** 是否处于抓举状态

```lua
LiftComp.is_lift_status()

返回值:

• 类型: Bool
• 说明: 是否抓举

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = unit.is_lift_status()
end)```

### LiftedComp.is_lifted_status

**描述:** 是否处于被抓举

```lua
LiftedComp.is_lifted_status()

返回值:

• 类型: Bool
• 说明: 是否被抓举

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = unit.is_lifted_status()
end)```

### MoveStatusComp.is_lost_control_status

**描述:** 判断移动状态是否处于失控状态

```lua
MoveStatusComp.is_lost_control_status()

返回值:

• 类型: Bool
• 说明: 是否失控

示例:

-- 判断角色当前是否处于失控状态（如被眩晕/击退期间）
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end

    local lost = unit.is_lost_control_status()
    LuaAPI.log("失控状态: " .. tostring(lost), 0)
end)```

### Obstacle.is_draggable

**描述:** 获取组件是否可拖动

```lua
Obstacle.is_draggable()

返回值:

• 类型: Bool
• 说明: 是否可拖动

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local obstacle = GameAPI.create_obstacle(200001, math.Vector3(0,0,0), math.Quaternion(0,0,0), math.Vector3(1,1,1), nil)
    if not obstacle then return end
    local result = obstacle.is_draggable()
end)```

### Obstacle.is_touchable

**描述:** 获取组件是否可点击

```lua
Obstacle.is_touchable()

返回值:

• 类型: Bool
• 说明: 是否可点击

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local obstacle = GameAPI.create_obstacle(200001, math.Vector3(0,0,0), math.Quaternion(0,0,0), math.Vector3(1,1,1), nil)
    if not obstacle then return end
    local result = obstacle.is_touchable()
end)```

### JumpComp.is_on_ground

**描述:** 是否位于地面

```lua
JumpComp.is_on_ground()

返回值:

• 类型: Bool
• 说明: 是否位于地面

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = unit.is_on_ground()
end)```

### Role.is_gallery_vip

**描述:** 是否是乐园会员

```lua
Role.is_gallery_vip()

返回值:

• 类型: Bool
• 说明: 是否是乐园会员

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = role.is_gallery_vip()
end)```

### Role.has_commodity

**描述:** 玩家是否拥有道具

```lua
Role.has_commodity(_commodity_id)

参数列表:

参数	类型	说明
_commodity_id	UgcCommodity	道具

返回值:

• 类型: Bool
• 说明: 是否拥有道具

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local ugc_commodity_id = 1001  -- 商品 ID（示意值，需替换为实际配置）
    local result = role.has_commodity(ugc_commodity_id)
end)```

### Role.has_saved_archive

**描述:** 玩家是否记录过存档

```lua
Role.has_saved_archive()

返回值:

• 类型: Bool
• 说明: 是否记录过存档

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = role.has_saved_archive()
end)```

### Role.is_map_liked

**描述:** 是否点赞本地图

```lua
Role.is_map_liked()

返回值:

• 类型: Bool
• 说明: 是否点赞

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = role.is_map_liked()
end)```

### Role.is_lost

**描述:** 玩家是否失败

```lua
Role.is_lost()

返回值:

• 类型: Bool
• 说明: 玩家是否失败

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = role.is_lost()
end)```

### Role.is_online

**描述:** 玩家是否在线

```lua
Role.is_online()

返回值:

• 类型: Bool
• 说明: 是否在线

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = role.is_online()
end)```

### Role.is_map_favorited

**描述:** 是否收藏本地图

```lua
Role.is_map_favorited()

返回值:

• 类型: Bool
• 说明: 是否收藏

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = role.is_map_favorited()
end)```

### Role.is_subscribed_map_author

**描述:** 玩家是否订阅地图作者

```lua
Role.is_subscribed_map_author()

返回值:

• 类型: Bool
• 说明: 是否订阅

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = role.is_subscribed_map_author()
end)```

### Role.is_pass_premium_vip

**描述:** 是否是派对手册进阶会员

```lua
Role.is_pass_premium_vip()

返回值:

• 类型: Bool
• 说明: 是否是派对手册进阶会员

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = role.is_pass_premium_vip()
end)```

### Role.is_won

**描述:** 玩家是否胜利

```lua
Role.is_won()

返回值:

• 类型: Bool
• 说明: 玩家是否胜利

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = role.is_won()
end)```

### Unit.is_in_customtriggerspace

**描述:** 单位是否在触发区域内

```lua
Unit.is_in_customtriggerspace(_custom_trigger_space, _consider_mask)

参数列表:

参数	类型	说明
_custom_trigger_space	CustomTriggerSpace	触发区域
_consider_mask	Bool	考虑掩码

返回值:

• 类型: Bool
• 说明: 是否在触发区域内

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local cts = GameAPI.create_customtriggerspace(110001, math.Vector3(0,0,0), math.Quaternion(0,0,0), math.Vector3(1,1,1), nil)
    if not cts then return end
    local result = unit.is_in_customtriggerspace(cts, true)
end)```

### Unit.is_valid_ability_target

**描述:** 判断单位是否满足作为技能释放目标的条件

```lua
Unit.is_valid_ability_target(_ability)

参数列表:

参数	类型	说明
_ability	Ability	对应技能

返回值:

• 类型: Bool
• 说明: 目标是否满足条件

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local ability = unit.add_ability_to_slot(1, 150001, {}, {})
    if not ability then return end
    local result = unit.is_valid_ability_target(ability)
end)```

### Role.get_last_archive_timestamp

**描述:** 获取玩家上次存档时间

```lua
Role.get_last_archive_timestamp()

返回值:

• 类型: Timestamp
• 说明: 时间戳

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = role.get_last_archive_timestamp()
end)```

### LevelComp.gain_exp

**描述:** 获得经验

```lua
LevelComp.gain_exp(_killed_exp)

参数列表:

参数	类型	说明
_killed_exp	Fixed	经验值

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    unit.gain_exp(1.0)
end)```

### LevelComp.get_exp

**描述:** 获取当前经验值

```lua
LevelComp.get_exp()

返回值:

• 类型: Fixed
• 说明: 经验值

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = unit.get_exp()
end)```

### LevelComp.get_killed_exp

**描述:** 获取击杀经验点

```lua
LevelComp.get_killed_exp()

返回值:

• 类型: Fixed
• 说明: 击杀经验值

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = unit.get_killed_exp()
end)```

### LevelComp.get_level

**描述:** 获得当前等级

```lua
LevelComp.get_level()

返回值:

• 类型: Int
• 说明: 当前等级

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = unit.get_level()
end)```

### LevelComp.level_up

**描述:** 升级

```lua
LevelComp.level_up()

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    unit.level_up()
end)```

### LevelComp.set_killed_exp

**描述:** 设置击杀经验点

```lua
LevelComp.set_killed_exp(_killed_exp)

参数列表:

参数	类型	说明
_killed_exp	Fixed	击杀经验值

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    unit.set_killed_exp(1.0)
end)```

### LifeEntity.start_move_by_direction

**描述:** 命令生命体移动

```lua
LifeEntity.start_move_by_direction(_direction, _duration)

参数列表:

参数	类型	说明
_direction	Vector3	移动方向
_duration	Fixed	持续时间

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- NPC单位，AI行为的执行者
    if not npc then return end
    npc.start_move_by_direction(math.Vector3(0, 0, 0), 1.0)
end)```

### LifeEntity.start_move_to_pos_with_threshold

**描述:** 命令生命体移动到坐标点

```lua
LifeEntity.start_move_to_pos_with_threshold(_target_pos, _duration, _threshold)

参数列表:

参数	类型	说明
_target_pos	Point3	目标点
_duration	Fixed	持续时间
_threshold	Fixed	容错距离

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- NPC单位，AI行为的执行者
    if not npc then return end
    npc.start_move_to_pos_with_threshold(math.Vector3(0, 0, 0), 1.0, 1.0)
end)```

### EquipmentComp.consume_equipment

**描述:** 消耗物品

```lua
EquipmentComp.consume_equipment(_equipment_key, _consume_num)

参数列表:

参数	类型	说明
_equipment_key	EquipmentKey	物品编号
_consume_num	Int	消耗数量

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    unit.consume_equipment(400001, 1)
end)```

### LifeEntity.get_hard_punch_threshold

**描述:** 获取生命体大力击倒阈值

```lua
LifeEntity.get_hard_punch_threshold()

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- NPC单位，AI行为的执行者
    if not npc then return end
    npc.get_hard_punch_threshold()
end)```

### LifeEntity.get_owner

**描述:** 获取生命体控制玩家

```lua
LifeEntity.get_owner()

返回值:

• 类型: Role
• 说明: 控制玩家

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- NPC单位，AI行为的执行者
    if not npc then return end
    local result = npc.get_owner()
end)```

### LifeEntity.get_punch_threshold

**描述:** 获取生命体击倒阈值

```lua
LifeEntity.get_punch_threshold()

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- NPC单位，AI行为的执行者
    if not npc then return end
    npc.get_punch_threshold()
end)```

### LifeEntity.activate_multi_animation

**描述:** 发起双人动作

```lua
LifeEntity.activate_multi_animation(_anim_id, _acceptor_type)

参数列表:

参数	类型	说明
_anim_id	AnimKey	动作编号
_acceptor_type	UnitType	接收方类型

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- NPC单位，AI行为的执行者
    if not npc then return end
    npc.activate_multi_animation(250001, Enums.UnitType.CHARACTER)
end)```

### LifeEntity.interrupt_multi_animation

**描述:** 打断双人动作

```lua
LifeEntity.interrupt_multi_animation()

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- NPC单位，AI行为的执行者
    if not npc then return end
    npc.interrupt_multi_animation()
end)```

### Unit.is_character

**描述:** 是否为角色

```lua
Unit.is_character()

返回值:

• 类型: Bool
• 说明: 是否为角色

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local result = unit.is_character()
end)```

### LifeEntity.is_jumping

**描述:** 生命体是否在跳跃中

```lua
LifeEntity.is_jumping()

返回值:

• 类型: Bool
• 说明: 是否在跳跃中

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- NPC单位，AI行为的执行者
    if not npc then return end
    local result = npc.is_jumping()
end)```

### LifeEntity.is_moving

**描述:** 生命体是否在移动中

```lua
LifeEntity.is_moving()

返回值:

• 类型: Bool
• 说明: 是否在移动中

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- NPC单位，AI行为的执行者
    if not npc then return end
    local result = npc.is_moving()
end)```

### LifeEntity.is_rushing

**描述:** 生命体是否在飞扑中

```lua
LifeEntity.is_rushing()

返回值:

• 类型: Bool
• 说明: 是否在飞扑中

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- NPC单位，AI行为的执行者
    if not npc then return end
    local result = npc.is_rushing()
end)```

### LifeEntity.swap_equipment_slot

**描述:** 交换物品槽位

```lua
LifeEntity.swap_equipment_slot(_equipment, _slot_type, _slot)

参数列表:

参数	类型	说明
_equipment	Equipment	物品
_slot_type	EquipmentSlotType	槽位类型
_slot	EquipmentSlot	槽位

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- NPC单位，AI行为的执行者
    if not npc then return end
    local equipment = GameAPI.create_equipment(400001, math.Vector3(0,0,0))
    if not equipment then return end
    local eq_slot = 1  -- EquipmentSlot 是槽位整数索引
    npc.swap_equipment_slot(equipment, Enums.EquipmentSlotType.EQUIPPED, eq_slot)
end)```

### Unit.play_emoji_with_offset

**描述:** 发送气泡表情

```lua
Unit.play_emoji_with_offset(_emoji_key, _show_time, _offset)

参数列表:

参数	类型	说明
_emoji_key	EmojiKey	表情
_show_time	Fixed	持续时间
_offset	Vector3	偏移

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    unit.play_emoji_with_offset(270001, 1.0, math.Vector3(0, 0, 0))
end)```

### LifeEntity.play_face_expression

**描述:** 播放面部表情

```lua
LifeEntity.play_face_expression(_emoji_key, _show_time)

参数列表:

参数	类型	说明
_emoji_key	EmojiKey	表情
_show_time	Fixed	持续时间

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- NPC单位，AI行为的执行者
    if not npc then return end
    npc.play_face_expression(270001, 1.0)
end)```

### LifeEntity.set_multi_animation_acceptor_type

**描述:** 设置可接受的双人动作类型

```lua
LifeEntity.set_multi_animation_acceptor_type(_acceptor_type)

参数列表:

参数	类型	说明
_acceptor_type	UnitType	可接受类型

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- NPC单位，AI行为的执行者
    if not npc then return end
    npc.set_multi_animation_acceptor_type(Enums.UnitType.CHARACTER)
end)```

### LifeEntity.set_multi_animation_acceptor_enabled

**描述:** 设置可接受双人动作邀请

```lua
LifeEntity.set_multi_animation_acceptor_enabled(_enable)

参数列表:

参数	类型	说明
_enable	Bool	是否可接受

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- NPC单位，AI行为的执行者
    if not npc then return end
    npc.set_multi_animation_acceptor_enabled(true)
end)```

### LifeEntity.set_hard_punch_threshold

**描述:** 设置生命体大力击倒阈值

```lua
LifeEntity.set_hard_punch_threshold(_punch_threshold)

参数列表:

参数	类型	说明
_punch_threshold	Fixed	击倒阈值

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- NPC单位，AI行为的执行者
    if not npc then return end
    npc.set_hard_punch_threshold(1.0)
end)```

### LifeEntity.set_punch_threshold

**描述:** 设置生命体击倒阈值

```lua
LifeEntity.set_punch_threshold(_punch_threshold)

参数列表:

参数	类型	说明
_punch_threshold	Fixed	击倒阈值

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- NPC单位，AI行为的执行者
    if not npc then return end
    npc.set_punch_threshold(1.0)
end)```

### LifeEntity.set_skeleton_offset

**描述:** 修改骨骼偏移

```lua
LifeEntity.set_skeleton_offset(_skeleton, _offset)

参数列表:

参数	类型	说明
_skeleton	Skeleton	骨骼
_offset	Vector3	偏移量

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- NPC单位，AI行为的执行者
    if not npc then return end
    -- 注意：skeleton 对象的获取依赖具体配置/模型数据，示例仅演示调用方式
    local skeleton = nil
    if not skeleton then return end
    npc.set_skeleton_offset(skeleton, math.Vector3(0, 0, 0))
end)```

### LifeEntity.set_skeleton_scale

**描述:** 修改骨骼缩放

```lua
LifeEntity.set_skeleton_scale(_skeleton, _scale)

参数列表:

参数	类型	说明
_skeleton	Skeleton	骨骼
_scale	Vector3	缩放比例

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- NPC单位，AI行为的执行者
    if not npc then return end
    -- 注意：skeleton 对象的获取依赖具体配置/模型数据，示例仅演示调用方式
    local skeleton = nil
    if not skeleton then return end
    npc.set_skeleton_scale(skeleton, math.Vector3(0, 0, 0))
end)```

### Modifier.change_shield_value

**描述:** 修改护盾值

```lua
Modifier.change_shield_value(_shield_value)

参数列表:

参数	类型	说明
_shield_value	Fixed	属性值

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local modifier = unit.add_modifier_by_key(600001, {})
    if not modifier then return end
    modifier.change_shield_value(1.0)
end)```

### Modifier.get_shield_value

**描述:** 获取护盾值

```lua
Modifier.get_shield_value()

返回值:

• 类型: Fixed
• 说明: 属性值

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local modifier = unit.add_modifier_by_key(600001, {})
    if not modifier then return end
    local result = modifier.get_shield_value()
end)```

### Modifier.set_shield_value

**描述:** 设置护盾值

```lua
Modifier.set_shield_value(_shield_value)

参数列表:

参数	类型	说明
_shield_value	Fixed	属性值

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local modifier = unit.add_modifier_by_key(600001, {})
    if not modifier then return end
    modifier.set_shield_value(1.0)
end)```

### Equipment.move_to_slot

**描述:** 移动物品到指定槽位

```lua
Equipment.move_to_slot(_slot_type, _slot)

参数列表:

参数	类型	说明
_slot_type	EquipmentSlotType	槽位类型
_slot	Int	槽位

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local equipment = GameAPI.create_equipment(400001, math.Vector3(0,0,0))
    if not equipment then return end
    equipment.move_to_slot(Enums.EquipmentSlotType.EQUIPPED, 1)
end)```

### Unit.add_circle_motor

**描述:** 添加圆周运动

```lua
Unit.add_circle_motor(_vel, _time, _is_local)

参数列表:

参数	类型	说明
_vel	Vector3	角速度
_time	Fixed	时间
_is_local	Bool	是否局部空间

返回值:

• 类型: Int
• 说明: 索引

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local result = unit.add_circle_motor(math.Vector3(0, 0, 0), 1.0, true)
end)```

### Unit.add_linear_motor

**描述:** 添加直线运动

```lua
Unit.add_linear_motor(_vel, _time, _is_local)

参数列表:

参数	类型	说明
_vel	Vector3	线速度
_time	Fixed	时间
_is_local	Bool	是否局部空间

返回值:

• 类型: Int
• 说明: 索引

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local result = unit.add_linear_motor(math.Vector3(0, 0, 0), 1.0, true)
end)```

### Unit.add_surround_motor

**描述:** 添加环绕运动

```lua
Unit.add_surround_motor(_follow_target, _ang_vel, _time, _follow_rotate)

参数列表:

参数	类型	说明
_follow_target	Unit	环绕目标
_ang_vel	Vector3	角速度
_time	Fixed	时间
_follow_rotate	Bool	是否跟随旋转

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    unit.add_surround_motor(unit, math.Vector3(0, 0, 0), 1.0, true)
end)```

### Unit.remove_surround_motor

**描述:** 停止环绕运动

```lua
Unit.remove_surround_motor()

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    unit.remove_surround_motor()
end)```

### Unit.get_angular_velocity

**描述:** 获取单位角速度

```lua
Unit.get_angular_velocity()

返回值:

• 类型: Vector3
• 说明: 角速度

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local result = unit.get_angular_velocity()
end)```

### Unit.is_dynamic

**描述:** 组件是否为受力物体

```lua
Unit.is_dynamic()

返回值:

• 类型: Bool
• 说明: 是否为受力物体

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local result = unit.is_dynamic()
end)```

### Unit.model_play_animation

**描述:** 模型播放动画

```lua
Unit.model_play_animation(_anim_name, _start_time, _is_loop, _play_speed)

参数列表:

参数	类型	说明
_anim_name	Str	动画名
_start_time	Fixed	开始时间
_is_loop	Bool	是否循环
_play_speed	Fixed	播放速度

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    unit.model_play_animation("平凡蛋0", 1.0, true, 1.0)
end)```

### Unit.set_angular_velocity

**描述:** 改变单位角速度

```lua
Unit.set_angular_velocity(_vel)

参数列表:

参数	类型	说明
_vel	Vector3	角速度

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    unit.set_angular_velocity(math.Vector3(0, 0, 0))
end)```

### Obstacle.set_draggable

**描述:** 设置组件是否可拖动

```lua
Obstacle.set_draggable(_enabled)

参数列表:

参数	类型	说明
_enabled	Bool	是否可拖动

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local obstacle = GameAPI.create_obstacle(200001, math.Vector3(0,0,0), math.Quaternion(0,0,0), math.Vector3(1,1,1), nil)
    if not obstacle then return end
    obstacle.set_draggable(true)
end)```

### Ability.play_countdown_ui

**描述:** 播放倒计时ui效果

```lua
Ability.play_countdown_ui(_time)

参数列表:

参数	类型	说明
_time	Fixed	持续时间

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local ability = unit.add_ability_to_slot(1, 150001, {}, {})
    if not ability then return end
    ability.play_countdown_ui(1.0)
end)```

### Role.play_screen_sfx

**描述:** 播放屏幕特效

```lua
Role.play_screen_sfx(_sfx_key, _duration, _rate)

参数列表:

参数	类型	说明
_sfx_key	SfxKey	特效编号
_duration	Fixed	持续时间
_rate	Fixed	播放速率

返回值:

• 类型: SfxID
• 说明: 特效ID

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = role.play_screen_sfx(700001, 1.0, 1.0)
end)```

### Unit.play_sound_with_dis_and_attenuation

**描述:** 单位开始播放声音

```lua
Unit.play_sound_with_dis_and_attenuation(_event_id, _vis_dis, _sound_attenuation_curve)

参数列表:

参数	类型	说明
_event_id	SoundKey	声音编号
_vis_dis	Fixed	音效传播距离
_sound_attenuation_curve	Str	衰减曲线

返回值:

• 类型: SoundID
• 说明: 音效ID

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local result = unit.play_sound_with_dis_and_attenuation(800001, 1.0, "示例字符串")
end)```

### AbilityComp.remove_ability_by_key

**描述:** 根据技能编号移除技能

```lua
AbilityComp.remove_ability_by_key(_ability_key)

参数列表:

参数	类型	说明
_ability_key	AbilityKey	技能编号

返回值:

• 类型: Bool
• 说明: 是否成功移除

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = unit.remove_ability_by_key(150001)
end)```

### ItemBox.remove_ability

**描述:** 移除道具箱刷新技能

```lua
ItemBox.remove_ability(_ability_key)

参数列表:

参数	类型	说明
_ability_key	AbilityKey	技能编号

示例:

-- 从道具箱移除技能（itemBox 为场景中配置的道具箱单位）
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 道具箱单位需在场景中配置（此处按名字查询，不存在则跳过）
    local itemBox = LuaAPI.query_unit("道具箱")
    if not itemBox then return end

    itemBox.remove_ability(150001)
end)```

### DisplayComp.unbind_model

**描述:** 移除绑定模型

```lua
DisplayComp.unbind_model(_bind_id)

参数列表:

参数	类型	说明
_bind_id	Str	绑定ID

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    unit.unbind_model("id_001")
end)```

### BuffStateComp.remove_state

**描述:** 从对象移除指定状态

```lua
BuffStateComp.remove_state(_state_id)

参数列表:

参数	类型	说明
_state_id	BuffState	状态

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    unit.remove_state(Enums.BuffState.BUFF_FORBID_MOVE)
end)```

### Unit.remove_from_parent

**描述:** 从父节点移除

```lua
Unit.remove_from_parent()

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    unit.remove_from_parent()
end)```

### KVBase.remove_kv

**描述:** 移除自定义值

```lua
KVBase.remove_kv(_key)

参数列表:

参数	类型	说明
_key	Str	名称

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    unit.remove_kv("key_001")
end)```

### ModifierComp.remove_modifier_by_key

**描述:** 移除效果

```lua
ModifierComp.remove_modifier_by_key(_modifier_id)

参数列表:

参数	类型	说明
_modifier_id	ModifierKey	效果编号

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    unit.remove_modifier_by_key(600001)
end)```

### KVBase.remove_tag

**描述:** 移除标签

```lua
KVBase.remove_tag(_tag)

参数列表:

参数	类型	说明
_tag	Str	标签

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    unit.remove_tag("enemy")
end)```

### AbilityComp.remove_ability

**描述:** 移除槽位上的技能

```lua
AbilityComp.remove_ability(_ability_slot)

参数列表:

参数	类型	说明
_ability_slot	AbilitySlot	技能槽位

返回值:

• 类型: Bool
• 说明: 是否成功移除

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local ability_slot = 1  -- AbilitySlot 是槽位整数索引
    local result = unit.remove_ability(ability_slot)
end)```

### Role.reset_camera

**描述:** 重置玩家相机

```lua
Role.reset_camera(_reset_angle, _reset_bind, _reset_point, _reset_prop_pitch)

参数列表:

参数	类型	说明
_reset_angle	Bool	重置相机角度
_reset_bind	Bool	重置相机模式
_reset_point	Bool	重置相机相对于焦点的位置
_reset_prop_pitch	Bool	重置俯仰角范围

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    role.reset_camera(true, true, true, true)
end)```

### Obstacle.reset_collision_limit

**描述:** 重置组件碰撞限制

```lua
Obstacle.reset_collision_limit(_limit_type)

参数列表:

参数	类型	说明
_limit_type	CollisionLimitType	碰撞限制类型

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local obstacle = GameAPI.create_obstacle(200001, math.Vector3(0,0,0), math.Quaternion(0,0,0), math.Vector3(1,1,1), nil)
    if not obstacle then return end
    obstacle.reset_collision_limit(Enums.CollisionLimitType.NONE)
end)```

### Role.show_dynamic_text

**描述:** 在指定坐标显示动态字

```lua
Role.show_dynamic_text(_text, _pos, _color, _duration, _anim_type)

参数列表:

参数	类型	说明
_text	Str	文本
_pos	Point3	坐标
_color	Color	颜色
_duration	Fixed	持续时间
_anim_type	Int	类型（0静态1动态）

返回值:

• 类型: DynamicTextID
• 说明: 动态文字ID

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = role.show_dynamic_text("示例文本", math.Vector3(0, 0, 0), GlobalAPI.str_to_color("ff0000"), 1.0, 1)
end)```

### Role.add_score

**描述:** 增加玩家积分

```lua
Role.add_score(_add_score)

参数列表:

参数	类型	说明
_add_score	Int	积分

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    role.add_score(1)
end)```

### Role.get_camp

**描述:** 获取玩家阵营

```lua
Role.get_camp()

返回值:

• 类型: Camp
• 说明: 阵营

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = role.get_camp()
end)```

### Role.enter_watch_mode

**描述:** 玩家进入观战

```lua
Role.enter_watch_mode(_camp_limit, _exit_visible)

参数列表:

参数	类型	说明
_camp_limit	Bool	是否限制阵营观战
_exit_visible	Bool	是否支持手动退出

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    role.enter_watch_mode(true, true)
end)```

### Role.exit_watch_mode

**描述:** 玩家退出观战

```lua
Role.exit_watch_mode()

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    role.exit_watch_mode()
end)```

### Role.get_commodity_count

**描述:** 玩家拥有道具数量

```lua
Role.get_commodity_count(_commodity_id)

参数列表:

参数	类型	说明
_commodity_id	UgcCommodity	道具

返回值:

• 类型: Int
• 说明: 拥有道具数量

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local ugc_commodity_id = 1001  -- 商品 ID（示意值，需替换为实际配置）
    local result = role.get_commodity_count(ugc_commodity_id)
end)```

### Role.is_achievement_completed

**描述:** 成就是否完成

```lua
Role.is_achievement_completed(_event_id)

参数列表:

参数	类型	说明
_event_id	Achievement	成就

返回值:

• 类型: Bool
• 说明: 是否完成

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local achievement = 1  -- Achievement 是成就编号（integer）
    local result = role.is_achievement_completed(achievement)
end)```

### Role.is_watch_mode

**描述:** 玩家进入观战

```lua
Role.is_watch_mode()

返回值:

• 类型: Bool
• 说明: 是否处于观战模式

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = role.is_watch_mode()
end)```

### Role.play_2d_sound_with_params

**描述:** 玩家播放2D音效

```lua
Role.play_2d_sound_with_params(_event_id, _duration, _volume, _speed)

参数列表:

参数	类型	说明
_event_id	SoundID	音效ID
_duration	Fixed	持续时间
_volume	Fixed	音量
_speed	Fixed	播放速度

返回值:

• 类型: SoundID
• 说明: 音效ID

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    -- 播放 3D 音效获取实例 ID（5129 为音效配置 ID），供后续停止/管理使用
    local sound_id = GameAPI.play_3d_sound(unit.get_position(), 5129, -1.0, 100.0)
    local result = role.play_2d_sound_with_params(sound_id, 1.0, 1.0, 1.0)
end)```

### Role.pause_camera_motor

**描述:** 暂停玩家相机运动

```lua
Role.pause_camera_motor()

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    role.pause_camera_motor()
end)```

### Role.play_advertisement_with_event

**描述:** 播放广告

```lua
Role.play_advertisement_with_event(_success_event, _fail_event, _ad_tag, _success_data, _fail_data)

参数列表:

参数	类型	说明
_success_event	Str	成功事件
_fail_event	Str	失败事件
_ad_tag	Str	广告标签
_success_data	Dict	成功附带参数
_fail_data	Dict	失败附带参数

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    -- 带附加参数的用法：成功/失败时附带额外数据到事件回调
    role.play_advertisement_with_event(
        "ad_success_event",      -- 成功事件名
        "ad_fail_event",         -- 失败事件名
        "enemy",                 -- 广告标签
        {                        -- 成功附带参数 (success_data)
            reward_type = "gold",
            reward_amount = 100,
            bonus_exp = 50
        },
        {                        -- 失败附带参数 (fail_data)
            error_code = 1001,
            retry_count = 3,
            fail_reason = "network_timeout"
        }
    )
end)```

### Role.play_ui_effect

**描述:** 播放界面动效

```lua
Role.play_ui_effect(_effect_node)

参数列表:

参数	类型	说明
_effect_node	EEffectNode	UI动效

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    role.play_ui_effect(LuaAPI.query_ui_node("特效节点"))
end)```

### Role.play_montage

**描述:** 播放指定剧情动画

```lua
Role.play_montage(_montage_key, _start_time, _play_to_end, _play_time)

参数列表:

参数	类型	说明
_montage_key	MontageKey	剧情动画编号
_start_time	Fixed	起始时间
_play_to_end	Bool	是否播完
_play_time	Fixed	播放时长

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    role.play_montage("260001", 1.0, true, 1.0)
end)```

### Role.reset_animation

**描述:** 重置界面动画

```lua
Role.reset_animation(_node)

参数列表:

参数	类型	说明
_node	ENode	UI节点

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local node = LuaAPI.query_ui_node("panel_main")
    if not node then return end
    role.reset_animation(node)
end)```

### Role.resume_camera_motor

**描述:** 恢复玩家相机运动

```lua
Role.resume_camera_motor()

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    role.resume_camera_motor()
end)```

### Role.send_track_data_change

**描述:** 发送埋点数据变化

```lua
Role.send_track_data_change(_track_data_key, _change_num)

参数列表:

参数	类型	说明
_track_data_key	Str	埋点key
_change_num	Int	数据变化

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    role.send_track_data_change("key_001", 1)
end)```

### Role.set_bagslot_related_lifeentity

**描述:** 设置物品格关联生命体

```lua
Role.set_bagslot_related_lifeentity(_bag_slot, _life_entity)

参数列表:

参数	类型	说明
_bag_slot	EBagSlot	UI物品格
_life_entity	LifeEntity	生命体

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- NPC单位，AI行为的执行者
    if not npc then return end
    local bag_slot_node = LuaAPI.query_ui_node("bag_slot_node")  -- bag_slot_node 节点需在 UI 中配置
    if not bag_slot_node then return end
    role.set_bagslot_related_lifeentity(bag_slot_node, npc)
end)```

### Role.set_battle_shop_visible

**描述:** 设置玩家商店显示

```lua
Role.set_battle_shop_visible(_battle_shop_id, _visible)

参数列表:

参数	类型	说明
_battle_shop_id	BattleShopKey	商店
_visible	Bool	显示/隐藏

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    role.set_battle_shop_visible(310001, true)
end)```

### Role.set_blind_corner

**描述:** 玩家设置暗角

```lua
Role.set_blind_corner(_enable, _strength, _color)

参数列表:

参数	类型	说明
_enable	Bool	启用
_strength	Fixed	强度
_color	Color	颜色

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    role.set_blind_corner(true, 1.0, GlobalAPI.str_to_color("ff0000"))
end)```

### Role.set_button_enabled

**描述:** 设置按钮控件的状态

```lua
Role.set_button_enabled(_button, _enabled)

参数列表:

参数	类型	说明
_button	EButton	UI按钮
_enabled	Bool	状态

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local btn_node = LuaAPI.query_ui_node("btn_示例")  -- 按钮节点需在 UI 中配置
    if not btn_node then return end
    role.set_button_enabled(btn_node, true)
end)```

### Role.set_button_font_size

**描述:** 设置UI按钮节点文字字号

```lua
Role.set_button_font_size(_key, _font_size)

参数列表:

参数	类型	说明
_key	EButton	UI按钮节点
_font_size	Fixed	字号

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local btn_node = LuaAPI.query_ui_node("btn_示例")  -- 按钮节点需在 UI 中配置
    if not btn_node then return end
    role.set_button_font_size(btn_node, 1.0)
end)```

### Role.set_button_normal_image

**描述:** 设置UI按钮节点常态图片

```lua
Role.set_button_normal_image(_button, _image_key)

参数列表:

参数	类型	说明
_button	EButton	UI按钮节点
_image_key	ImageKey	图片

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local btn_node = LuaAPI.query_ui_node("btn_示例")  -- 按钮节点需在 UI 中配置
    if not btn_node then return end
    role.set_button_normal_image(btn_node, 170001)
end)```

### Role.set_button_pressed_image

**描述:** 设置UI按钮节点按下图片

```lua
Role.set_button_pressed_image(_button, _image_key)

参数列表:

参数	类型	说明
_button	EButton	UI按钮节点
_image_key	ImageKey	图片

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local btn_node = LuaAPI.query_ui_node("btn_示例")  -- 按钮节点需在 UI 中配置
    if not btn_node then return end
    role.set_button_pressed_image(btn_node, 170001)
end)```

### Role.set_button_text

**描述:** 设置UI按钮节点文本

```lua
Role.set_button_text(_button, _text)

参数列表:

参数	类型	说明
_button	EButton	UI按钮节点
_text	Str	文本

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local btn_node = LuaAPI.query_ui_node("btn_示例")  -- 按钮节点需在 UI 中配置
    if not btn_node then return end
    role.set_button_text(btn_node, "示例文本")
end)```

### Role.set_button_text_color

**描述:** 设置UI按钮节点文字颜色

```lua
Role.set_button_text_color(_button, _text_color)

参数列表:

参数	类型	说明
_button	EButton	UI按钮节点
_text_color	Color	颜色

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local btn_node = LuaAPI.query_ui_node("btn_node")  -- btn_node 节点需在 UI 中配置
    if not btn_node then return end
    role.set_button_text_color(btn_node, GlobalAPI.str_to_color("ff0000"))
end)```

### Role.set_gyroscope_control_unit

**描述:** 设置玩家陀螺仪控制组件

```lua
Role.set_gyroscope_control_unit(_is_control, _unit)

参数列表:

参数	类型	说明
_is_control	Bool	是否由陀螺仪控制
_unit	Unit	单位

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end

    role.set_gyroscope_control_unit(true, role.get_ctrl_unit())
end)```

### Role.set_image_color

**描述:** 设置UI图片颜色

```lua
Role.set_image_color(_image, _image_color, _transition_time)

参数列表:

参数	类型	说明
_image	EImage	UI图片节点
_image_color	Color	颜色
_transition_time	Fixed	变化时间

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local img_node = LuaAPI.query_ui_node("img_node")  -- img_node 节点需在 UI 中配置
    if not img_node then return end
    role.set_image_color(img_node, GlobalAPI.str_to_color("ff0000"), 1.0)
end)```

### Role.set_image_texture_by_key_with_auto_resize

**描述:** 设置UI图片节点图片

```lua
Role.set_image_texture_by_key_with_auto_resize(_image, _image_key, _reset_size)

参数列表:

参数	类型	说明
_image	EImage	UI图片节点
_image_key	ImageKey	图片
_reset_size	Bool	是否重置大小

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local img_node = LuaAPI.query_ui_node("img_node")  -- img_node 节点需在 UI 中配置
    if not img_node then return end
    role.set_image_texture_by_key_with_auto_resize(img_node, 170001, true)
end)```

### Role.set_input_field_text

**描述:** 设置UI输入节点文本

```lua
Role.set_input_field_text(_input_field, _text)

参数列表:

参数	类型	说明
_input_field	EInputField	UI输入节点
_text	Str	文本

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local input_node = LuaAPI.query_ui_node("input_node")  -- input_node 节点需在 UI 中配置
    if not input_node then return end
    role.set_input_field_text(input_node, "示例文本")
end)```

### Role.set_label_background_color

**描述:** 设置UI文本节点背景颜色

```lua
Role.set_label_background_color(_label, _color, _transition_time)

参数列表:

参数	类型	说明
_label	ELabel	UI文本节点
_color	Color	颜色
_transition_time	Fixed	变化时间

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local lbl_node = LuaAPI.query_ui_node("lbl_node")  -- lbl_node 节点需在 UI 中配置
    if not lbl_node then return end
    role.set_label_background_color(lbl_node, GlobalAPI.str_to_color("ff0000"), 1.0)
end)```

### Role.set_label_background_opacity

**描述:** 设置UI文本节点背景不透明度

```lua
Role.set_label_background_opacity(_label, _opacity, _transition_time)

参数列表:

参数	类型	说明
_label	ELabel	UI文本节点
_opacity	Fixed	不透明度
_transition_time	Fixed	变化时间

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local lbl_node = LuaAPI.query_ui_node("lbl_node")  -- lbl_node 节点需在 UI 中配置
    if not lbl_node then return end
    role.set_label_background_opacity(lbl_node, 1.0, 1.0)
end)```

### Role.set_label_color

**描述:** 设置UI文本节点的字体颜色

```lua
Role.set_label_color(_label, _color, _transition_time)

参数列表:

参数	类型	说明
_label	ELabel	UI文本节点
_color	Color	颜色
_transition_time	Fixed	变化时间

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local lbl_node = LuaAPI.query_ui_node("lbl_node")  -- lbl_node 节点需在 UI 中配置
    if not lbl_node then return end
    role.set_label_color(lbl_node, GlobalAPI.str_to_color("ff0000"), 1.0)
end)```

### Role.set_label_font

**描述:** 设置UI文本节点字体

```lua
Role.set_label_font(_label, _font_key)

参数列表:

参数	类型	说明
_label	ELabel	UI文本节点
_font_key	FontKey	字体key

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local lbl_node = LuaAPI.query_ui_node("lbl_node")  -- lbl_node 节点需在 UI 中配置
    if not lbl_node then return end
    role.set_label_font(lbl_node, 280001)
end)```

### Role.set_label_font_size

**描述:** 设置UI文本节点的字体大小

```lua
Role.set_label_font_size(_label, _font_size, _transition_time)

参数列表:

参数	类型	说明
_label	ELabel	UI文本节点
_font_size	Int	字号
_transition_time	Fixed	变化时间

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local lbl_node = LuaAPI.query_ui_node("lbl_node")  -- lbl_node 节点需在 UI 中配置
    if not lbl_node then return end
    role.set_label_font_size(lbl_node, 1, 1.0)
end)```

### Role.set_label_outline_color

**描述:** 设置UI文本节点的描边颜色

```lua
Role.set_label_outline_color(_label, _color)

参数列表:

参数	类型	说明
_label	ELabel	UI文本节点
_color	Color	描边颜色

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local lbl_node = LuaAPI.query_ui_node("lbl_node")  -- lbl_node 节点需在 UI 中配置
    if not lbl_node then return end
    role.set_label_outline_color(lbl_node, GlobalAPI.str_to_color("ff0000"))
end)```

### Role.set_label_outline_enabled

**描述:** 设置UI文本节点的描边是否开启

```lua
Role.set_label_outline_enabled(_label, _enable)

参数列表:

参数	类型	说明
_label	ELabel	UI文本节点
_enable	Bool	是否开启描边

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local lbl_node = LuaAPI.query_ui_node("lbl_node")  -- lbl_node 节点需在 UI 中配置
    if not lbl_node then return end
    role.set_label_outline_enabled(lbl_node, true)
end)```

### Role.set_label_outline_opacity

**描述:** 设置UI文本节点的描边不透明度

```lua
Role.set_label_outline_opacity(_label, _opacity)

参数列表:

参数	类型	说明
_label	ELabel	UI文本节点
_opacity	Fixed	描边不透明度

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local lbl_node = LuaAPI.query_ui_node("lbl_node")  -- lbl_node 节点需在 UI 中配置
    if not lbl_node then return end
    role.set_label_outline_opacity(lbl_node, 1.0)
end)```

### Role.set_label_outline_width

**描述:** 设置UI文本节点的描边大小

```lua
Role.set_label_outline_width(_label, _width)

参数列表:

参数	类型	说明
_label	ELabel	UI文本节点
_width	Fixed	描边大小

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local lbl_node = LuaAPI.query_ui_node("lbl_node")  -- lbl_node 节点需在 UI 中配置
    if not lbl_node then return end
    role.set_label_outline_width(lbl_node, 1.0)
end)```

### Role.set_label_shadow_color

**描述:** 设置UI文本节点的阴影颜色

```lua
Role.set_label_shadow_color(_label, _color)

参数列表:

参数	类型	说明
_label	ELabel	UI文本节点
_color	Color	阴影颜色

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local lbl_node = LuaAPI.query_ui_node("lbl_node")  -- lbl_node 节点需在 UI 中配置
    if not lbl_node then return end
    role.set_label_shadow_color(lbl_node, GlobalAPI.str_to_color("ff0000"))
end)```

### Role.set_label_shadow_enabled

**描述:** 设置UI文本节点的阴影是否开启

```lua
Role.set_label_shadow_enabled(_label, _enable)

参数列表:

参数	类型	说明
_label	ELabel	UI文本节点
_enable	Bool	是否开启阴影

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local lbl_node = LuaAPI.query_ui_node("lbl_node")  -- lbl_node 节点需在 UI 中配置
    if not lbl_node then return end
    role.set_label_shadow_enabled(lbl_node, true)
end)```

### Role.set_label_shadow_x_offset

**描述:** 设置UI文本节点的阴影x偏移

```lua
Role.set_label_shadow_x_offset(_label, _offset)

参数列表:

参数	类型	说明
_label	ELabel	UI文本节点
_offset	Fixed	x方向偏移

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local lbl_node = LuaAPI.query_ui_node("lbl_node")  -- lbl_node 节点需在 UI 中配置
    if not lbl_node then return end
    role.set_label_shadow_x_offset(lbl_node, 1.0)
end)```

### Role.set_label_shadow_y_offset

**描述:** 设置UI文本节点的阴影y偏移

```lua
Role.set_label_shadow_y_offset(_label, _offset)

参数列表:

参数	类型	说明
_label	ELabel	UI文本节点
_offset	Fixed	y方向偏移

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local lbl_node = LuaAPI.query_ui_node("lbl_node")  -- lbl_node 节点需在 UI 中配置
    if not lbl_node then return end
    role.set_label_shadow_y_offset(lbl_node, 1.0)
end)```

### Role.set_label_text

**描述:** 设置UI文本节点的文本

```lua
Role.set_label_text(_label, _text)

参数列表:

参数	类型	说明
_label	ELabel	UI文本节点
_text	Str	文本

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local lbl_node = LuaAPI.query_ui_node("lbl_node")  -- lbl_node 节点需在 UI 中配置
    if not lbl_node then return end
    role.set_label_text(lbl_node, "示例文本")
end)```

### Role.set_camera_rotation_sync_enabled

**描述:** 设置是否开启玩家相机旋转同步

```lua
Role.set_camera_rotation_sync_enabled(_enabled)

参数列表:

参数	类型	说明
_enabled	Bool	是否同步

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    role.set_camera_rotation_sync_enabled(true)
end)```

### Role.set_gyroscope_sync_enabled

**描述:** 设置监听陀螺仪信息

```lua
Role.set_gyroscope_sync_enabled(_enabled)

参数列表:

参数	类型	说明
_enabled	Bool	是否监听

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    role.set_gyroscope_sync_enabled(true)
end)```

### Role.set_name_visible

**描述:** 设置玩家昵称可见性

```lua
Role.set_name_visible(_visible)

参数列表:

参数	类型	说明
_visible	Bool	是否可见

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    role.set_name_visible(true)
end)```

### Role.set_animation_state

**描述:** 设置节点动画状态

```lua
Role.set_animation_state(_node, _animation_name, _state)

参数列表:

参数	类型	说明
_node	ENode	UI节点
_animation_name	Str	动画名称
_state	EAnimationState	状态

示例:

-- 播放 UI 节点动画（如面板打开/关闭动画）
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end

    -- 查询 UI 节点并播放动画（节点名需与编辑器配置一致）
    local node = LuaAPI.query_ui_node("panel_main")
    if node then
        role.set_animation_state(node, "打开", 1)  -- 状态为整数枚举（1=Idle）
    end
end)```

### Role.set_node_touch_enabled

**描述:** 设置UI节点交互开关

```lua
Role.set_node_touch_enabled(_node, _touch_enabled)

参数列表:

参数	类型	说明
_node	ENode	UI节点
_touch_enabled	Bool	交互开关

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local node = LuaAPI.query_ui_node("panel_main")
    if not node then return end
    role.set_node_touch_enabled(node, true)
end)```

### Role.set_node_visible

**描述:** 设置UI节点可见性

```lua
Role.set_node_visible(_node, _visible)

参数列表:

参数	类型	说明
_node	ENode	UI节点
_visible	Bool	可见性

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local node = LuaAPI.query_ui_node("panel_main")
    if not node then return end
    role.set_node_visible(node, true)
end)```

### Role.set_progressbar_current

**描述:** 设置UI进度条节点进度

```lua
Role.set_progressbar_current(_progress_bar, _current)

参数列表:

参数	类型	说明
_progress_bar	EProgressbar	UI进度条节点
_current	Int	进度

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local progress_node = LuaAPI.query_ui_node("progress_node")  -- progress_node 节点需在 UI 中配置
    if not progress_node then return end
    role.set_progressbar_current(progress_node, 1)
end)```

### Role.set_progressbar_max

**描述:** 设置UI进度条节点最大进度

```lua
Role.set_progressbar_max(_progress_bar, _max)

参数列表:

参数	类型	说明
_progress_bar	EProgressbar	UI进度条节点
_max	Int	最大进度

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local progress_node = LuaAPI.query_ui_node("progress_node")  -- progress_node 节点需在 UI 中配置
    if not progress_node then return end
    role.set_progressbar_max(progress_node, 1)
end)```

### Role.set_progressbar_min

**描述:** 设置UI进度条节点最小进度

```lua
Role.set_progressbar_min(_progress_bar, _min)

参数列表:

参数	类型	说明
_progress_bar	EProgressbar	UI进度条节点
_min	Int	最小进度

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local progress_node = LuaAPI.query_ui_node("progress_node")  -- progress_node 节点需在 UI 中配置
    if not progress_node then return end
    role.set_progressbar_min(progress_node, 1)
end)```

### Role.set_progressbar_transition

**描述:** 设置UI进度条节点过渡

```lua
Role.set_progressbar_transition(_progress_bar, _current, _transition_time)

参数列表:

参数	类型	说明
_progress_bar	EProgressbar	UI进度条节点
_current	Int	进度
_transition_time	Fixed	过渡时间

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local progress_node = LuaAPI.query_ui_node("progress_node")  -- progress_node 节点需在 UI 中配置
    if not progress_node then return end
    role.set_progressbar_transition(progress_node, 1, 1.0)
end)```

### Role.set_score

**描述:** 设置玩家积分

```lua
Role.set_score(_score)

参数列表:

参数	类型	说明
_score	Int	积分

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    role.set_score(1)
end)```

### Role.set_goods_panel_visible

**描述:** 设置付费道具商店可见性

```lua
Role.set_goods_panel_visible(_visible)

参数列表:

参数	类型	说明
_visible	Bool	可见性

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    role.set_goods_panel_visible(true)
end)```

### Role.set_goods_visible

**描述:** 设置付费商品可见性

```lua
Role.set_goods_visible(_goods_key, _visible)

参数列表:

参数	类型	说明
_goods_key	UgcGoods	商品
_visible	Bool	可见性

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local ugc_goods = "goods_1001"  -- 商品 key（示意值，需替换为实际配置）
    role.set_goods_visible(ugc_goods, true)
end)```

### Role.set_ui_opacity

**描述:** 设置UI节点不透明度

```lua
Role.set_ui_opacity(_node, _opacity)

参数列表:

参数	类型	说明
_node	ENode	UI节点
_opacity	Fixed	不透明度

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local node = LuaAPI.query_ui_node("panel_main")
    if not node then return end
    role.set_ui_opacity(node, 1.0)
end)```

### Role.set_uipreset_visible

**描述:** 设置原生界面可见性

```lua
Role.set_uipreset_visible(_ui, _visible)

参数列表:

参数	类型	说明
_ui	UIPreset	ui预设
_visible	Bool	是否可见

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    -- 注意：ui_preset 对象的获取依赖具体配置/模型数据，示例仅演示调用方式
    local ui_preset = nil
    if not ui_preset then return end
    role.set_uipreset_visible(ui_preset, true)
end)```

### Role.disable_unit_fresnel

**描述:** 关闭单位菲尼尔效果

```lua
Role.disable_unit_fresnel(_unit)

参数列表:

参数	类型	说明
_unit	Unit	单位

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end

    role.disable_unit_fresnel(role.get_ctrl_unit())
end)```

### Role.disable_unit_mask

**描述:** 关闭单位蒙版

```lua
Role.disable_unit_mask(_unit)

参数列表:

参数	类型	说明
_unit	Unit	单位

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end

    role.disable_unit_mask(role.get_ctrl_unit())
end)```

### Role.disable_unit_outline

**描述:** 关闭单位描边

```lua
Role.disable_unit_outline(_unit)

参数列表:

参数	类型	说明
_unit	Unit	单位

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    role.disable_unit_outline(role.get_ctrl_unit())
end)```

### Role.set_unit_fresnel_gradual

**描述:** 设置单位菲尼尔效果

```lua
Role.set_unit_fresnel_gradual(_unit, _fresnel_scale, _color, _intensity, _duration)

参数列表:

参数	类型	说明
_unit	Unit	单位
_fresnel_scale	Fixed	菲尼尔系数
_color	Color	颜色
_intensity	Int	强度
_duration	Fixed	用时

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end

    role.set_unit_fresnel_gradual(role.get_ctrl_unit(), 1.0, GlobalAPI.str_to_color("ff0000"), 1, 1.0)
end)```

### Role.set_unit_visible

**描述:** 设置单位对玩家可见性

```lua
Role.set_unit_visible(_unit, _is_visible, _affect_children)

参数列表:

参数	类型	说明
_unit	Unit	单位
_is_visible	Bool	是否显示
_affect_children	Bool	是否影响绑定的子组件

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end

    role.set_unit_visible(role.get_ctrl_unit(), true, true)
end)```

### Role.set_voice_volume_sync_enabled

**描述:** 设置是否开启语音音量同步

```lua
Role.set_voice_volume_sync_enabled(_enabled)

参数列表:

参数	类型	说明
_enabled	Bool	是否同步

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    role.set_voice_volume_sync_enabled(true)
end)```

### Role.shake_camera

**描述:** 设置玩家屏幕震动

```lua
Role.shake_camera(_shake_type, _shake_max_amplitude, _shake_time, _shake_source, _shake_frequency, _shake_time_decay, _shake_effect_scope, _shake_undamped_scope, _shake_distance_decay)

参数列表:

参数	类型	说明
_shake_type	CameraShakeType	震动方向
_shake_max_amplitude	Fixed	震幅
_shake_time	Fixed	震动时间
_shake_source	Unit	震源
_shake_frequency	Fixed	频率
_shake_time_decay	Fixed	时间衰减
_shake_effect_scope	Fixed	生效范围
_shake_undamped_scope	Fixed	不衰减范围
_shake_distance_decay	Fixed	距离衰减

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end

    role.shake_camera(Enums.CameraShakeType.FRONT_AND_BACK, 1.0, 1.0, role, 1.0, 1.0, 1.0, 1.0, 1.0)
end)```

### Role.show_bag_panel

**描述:** 设置玩家的背包界面显隐

```lua
Role.show_bag_panel(_visible)

参数列表:

参数	类型	说明
_visible	Bool	是否显示

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    role.show_bag_panel(true)
end)```

### Role.show_like_panel

**描述:** 显示点赞界面

```lua
Role.show_like_panel()

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    role.show_like_panel()
end)```

### Role.show_map_share_panel

**描述:** 指定玩家显示地图分享界面

```lua
Role.show_map_share_panel()

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    role.show_map_share_panel()
end)```

### Role.show_ultimate_ability_panel

**描述:** 显示玩家决战技选择界面

```lua
Role.show_ultimate_ability_panel(_keep_time)

参数列表:

参数	类型	说明
_keep_time	Int	时间

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    role.show_ultimate_ability_panel(1)
end)```

### Role.skip_current_montage

**描述:** 跳过剧情动画

```lua
Role.skip_current_montage(_has_black_screen)

参数列表:

参数	类型	说明
_has_black_screen	Bool	是否有跳过黑幕

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    role.skip_current_montage(true)
end)```

### Role.start_vibration

**描述:** 开始手机震动

```lua
Role.start_vibration(_vibrate_type, _vibrate_count, _vibrate_interval)

参数列表:

参数	类型	说明
_vibrate_type	Int	震动模式
_vibrate_count	Int	震动次数
_vibrate_interval	Fixed	震动间隔

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    role.start_vibration(1, 1, 1.0)
end)```

### Role.stop_2d_sound

**描述:** 对指定单位停止2D声音

```lua
Role.stop_2d_sound(_sound_instance_id)

参数列表:

参数	类型	说明
_sound_instance_id	SoundID	音效ID

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    -- 播放 3D 音效获取实例 ID（5129 为音效配置 ID），供后续停止/管理使用
    local sound_id = GameAPI.play_3d_sound(unit.get_position(), 5129, -1.0, 100.0)
    role.stop_2d_sound(sound_id)
end)```

### Role.stop_ui_effect

**描述:** 停止界面动效

```lua
Role.stop_ui_effect(_effect_node)

参数列表:

参数	类型	说明
_effect_node	EEffectNode	UI动效

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    role.stop_ui_effect(LuaAPI.query_ui_node("特效节点"))
end)```

### Role.stop_camera_motor

**描述:** 停止玩家相机运动

```lua
Role.stop_camera_motor()

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    role.stop_camera_motor()
end)```

### Role.unbind_label_text

**描述:** UI文本节点解除属性

```lua
Role.unbind_label_text(_label)

参数列表:

参数	类型	说明
_label	ELabel	UI文本节点

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local lbl_node = LuaAPI.query_ui_node("lbl_node")  -- lbl_node 节点需在 UI 中配置
    if not lbl_node then return end
    role.unbind_label_text(lbl_node)
end)```

### Role.unbind_progressbar_current

**描述:** 为UI进度条节点当前进度解绑属性

```lua
Role.unbind_progressbar_current(_progress_bar)

参数列表:

参数	类型	说明
_progress_bar	EProgressbar	UI进度条节点

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local progress_node = LuaAPI.query_ui_node("progress_node")  -- progress_node 节点需在 UI 中配置
    if not progress_node then return end
    role.unbind_progressbar_current(progress_node)
end)```

### Role.unbind_progressbar_max

**描述:** UI进度条节点最大进度解绑属性

```lua
Role.unbind_progressbar_max(_progress_bar)

参数列表:

参数	类型	说明
_progress_bar	EProgressbar	UI进度条节点

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local progress_node = LuaAPI.query_ui_node("progress_node")  -- progress_node 节点需在 UI 中配置
    if not progress_node then return end
    role.unbind_progressbar_max(progress_node)
end)```

### Ability.set_left_charge_time

**描述:** 设置技能剩余充能

```lua
Ability.set_left_charge_time(_cd_time)

参数列表:

参数	类型	说明
_cd_time	Fixed	充能时间

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local ability = unit.add_ability_to_slot(1, 150001, {}, {})
    if not ability then return end
    ability.set_left_charge_time(1.0)
end)```

### Ability.set_left_cd_time

**描述:** 设置技能剩余冷却

```lua
Ability.set_left_cd_time(_cd_time)

参数列表:

参数	类型	说明
_cd_time	Fixed	冷却时间

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local ability = unit.add_ability_to_slot(1, 150001, {}, {})
    if not ability then return end
    ability.set_left_cd_time(1.0)
end)```

### Ability.set_max_release_num

**描述:** 设置技能最大使用次数

```lua
Ability.set_max_release_num(_release_num_max)

参数列表:

参数	类型	说明
_release_num_max	Int	最大使用次数

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local ability = unit.add_ability_to_slot(1, 150001, {}, {})
    if not ability then return end
    ability.set_max_release_num(1)
end)```

### Ability.set_cur_release_num

**描述:** 设置技能当前使用次数

```lua
Ability.set_cur_release_num(_release_num)

参数列表:

参数	类型	说明
_release_num	Int	使用次数

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local ability = unit.add_ability_to_slot(1, 150001, {}, {})
    if not ability then return end
    ability.set_cur_release_num(1)
end)```

### Role.set_achievement_progress

**描述:** 设置成就进度

```lua
Role.set_achievement_progress(_event_id, _count)

参数列表:

参数	类型	说明
_event_id	Achievement	成就
_count	Int	成就进度

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local achievement = 1  -- Achievement 是成就编号（integer）
    role.set_achievement_progress(achievement, 1)
end)```

### Character.set_aim_move_enabled

**描述:** 开关角色靶向移动

```lua
Character.set_aim_move_enabled(_enable)

参数列表:

参数	类型	说明
_enable	Bool	开关

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- Character 继承自 LifeEntity，代表NPC角色单位
    if not npc then return end
    npc.set_aim_move_enabled(true)
end)```

### Obstacle.set_billboard_text

**描述:** 设置公告板文本内容

```lua
Obstacle.set_billboard_text(_content)

参数列表:

参数	类型	说明
_content	Str	文本内容

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local obstacle = GameAPI.create_obstacle(200001, math.Vector3(0,0,0), math.Quaternion(0,0,0), math.Vector3(1,1,1), nil)
    if not obstacle then return end
    obstacle.set_billboard_text("示例内容")
end)```

### Obstacle.set_billboard_text_color

**描述:** 设置公告板文本颜色

```lua
Obstacle.set_billboard_text_color(_color, _gradient_color_1, _gradient_color_2, _gradient_color_3, _gradient_color_4)

参数列表:

参数	类型	说明
_color	Color	文本颜色
_gradient_color_1	Color	渐变色1
_gradient_color_2	Color	渐变色2
_gradient_color_3	Color	渐变色3
_gradient_color_4	Color	渐变色4

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local obstacle = GameAPI.create_obstacle(200001, math.Vector3(0,0,0), math.Quaternion(0,0,0), math.Vector3(1,1,1), nil)
    if not obstacle then return end
    obstacle.set_billboard_text_color(GlobalAPI.str_to_color("ff0000"), GlobalAPI.str_to_color("ff0000"), GlobalAPI.str_to_color("ff0000"), GlobalAPI.str_to_color("ff0000"), GlobalAPI.str_to_color("ff0000"))
end)```

### Obstacle.set_billboard_font_size

**描述:** 设置公告板文本字体大小

```lua
Obstacle.set_billboard_font_size(_font_size)

参数列表:

参数	类型	说明
_font_size	Int	字体大小

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local obstacle = GameAPI.create_obstacle(200001, math.Vector3(0,0,0), math.Quaternion(0,0,0), math.Vector3(1,1,1), nil)
    if not obstacle then return end
    obstacle.set_billboard_font_size(1)
end)```

### Character.set_voice_enabled

**描述:** 设置角色配音是否生效

```lua
Character.set_voice_enabled(_enabled)

参数列表:

参数	类型	说明
_enabled	Bool	是否启用

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- Character 继承自 LifeEntity，代表NPC角色单位
    if not npc then return end
    npc.set_voice_enabled(true)
end)```

### Character.set_climb_enabled

**描述:** 设置角色是否开启攀爬

```lua
Character.set_climb_enabled(_enable)

参数列表:

参数	类型	说明
_enable	Bool	是否开启攀爬

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- Character 继承自 LifeEntity，代表NPC角色单位
    if not npc then return end
    npc.set_climb_enabled(true)
end)```

### Character.set_climb_max_angle

**描述:** 设置角色攀爬的最大角度

```lua
Character.set_climb_max_angle(_angle)

参数列表:

参数	类型	说明
_angle	Fixed	角度

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- Character 继承自 LifeEntity，代表NPC角色单位
    if not npc then return end
    npc.set_climb_max_angle(1.0)
end)```

### Character.set_climb_speed

**描述:** 设置角色攀爬速度

```lua
Character.set_climb_speed(_speed)

参数列表:

参数	类型	说明
_speed	Fixed	攀爬速度

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- Character 继承自 LifeEntity，代表NPC角色单位
    if not npc then return end
    npc.set_climb_speed(1.0)
end)```

### Character.set_climb_min_angle

**描述:** 设置角色攀爬的最小角度

```lua
Character.set_climb_min_angle(_angle)

参数列表:

参数	类型	说明
_angle	Fixed	角度

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- Character 继承自 LifeEntity，代表NPC角色单位
    if not npc then return end
    npc.set_climb_min_angle(1.0)
end)```

### LifeEntity.set_mass_bar_visible

**描述:** 设置质量条是否显示

```lua
LifeEntity.set_mass_bar_visible(_visible)

参数列表:

参数	类型	说明
_visible	Bool	是否显示

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- NPC单位，AI行为的执行者
    if not npc then return end
    npc.set_mass_bar_visible(true)
end)```

### Unit.set_scale

**描述:** 设置单位缩放

```lua
Unit.set_scale(_scale, _time)

参数列表:

参数	类型	说明
_scale	Fixed	缩放
_time	Fixed	时间

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    unit.set_scale(2.0, 1.0)
end)```

### Obstacle.set_chess_type_and_rank

**描述:** 设置牌面(对象只能为麻将/扑克)

```lua
Obstacle.set_chess_type_and_rank(_card_type, _card_rank)

参数列表:

参数	类型	说明
_card_type	ChessType	牌名
_card_rank	Int	牌数

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local obstacle = GameAPI.create_obstacle(200001, math.Vector3(0,0,0), math.Quaternion(0,0,0), math.Vector3(1,1,1), nil)
    if not obstacle then return end
    obstacle.set_chess_type_and_rank(Enums.ChessType.SPADE, 1)
end)```

### Equipment.set_auto_aim_enabled

**描述:** 设置枪械自动瞄准

```lua
Equipment.set_auto_aim_enabled(_is_auto_aim)

参数列表:

参数	类型	说明
_is_auto_aim	Bool	是否自动瞄准

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local equipment = GameAPI.create_equipment(400001, math.Vector3(0,0,0))
    if not equipment then return end
    equipment.set_auto_aim_enabled(true)
end)```

### Equipment.set_auto_fire_enabled

**描述:** 设置枪械自动开火

```lua
Equipment.set_auto_fire_enabled(_is_auto_fire)

参数列表:

参数	类型	说明
_is_auto_fire	Bool	是否自动开火

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local equipment = GameAPI.create_equipment(400001, math.Vector3(0,0,0))
    if not equipment then return end
    equipment.set_auto_fire_enabled(true)
end)```

### Equipment.set_current_stack_num

**描述:** 设置物品当前堆叠数

```lua
Equipment.set_current_stack_num(_num)

参数列表:

参数	类型	说明
_num	Int	堆叠数

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local equipment = GameAPI.create_equipment(400001, math.Vector3(0,0,0))
    if not equipment then return end
    equipment.set_current_stack_num(1)
end)```

### Equipment.set_desc

**描述:** 设置物品的描述

```lua
Equipment.set_desc(_desc)

参数列表:

参数	类型	说明
_desc	Str	描述

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local equipment = GameAPI.create_equipment(400001, math.Vector3(0,0,0))
    if not equipment then return end
    equipment.set_desc("示例字符串")
end)```

### Equipment.set_droppable

**描述:** 设置物品能否丢弃

```lua
Equipment.set_droppable(_droppable)

参数列表:

参数	类型	说明
_droppable	Bool	能否丢弃

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local equipment = GameAPI.create_equipment(400001, math.Vector3(0,0,0))
    if not equipment then return end
    equipment.set_droppable(true)
end)```

### Equipment.set_price

**描述:** 设置物品的抵押价格

```lua
Equipment.set_price(_res_type, _price)

参数列表:

参数	类型	说明
_res_type	Str	货币类型
_price	Int	卖价

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local equipment = GameAPI.create_equipment(400001, math.Vector3(0,0,0))
    if not equipment then return end
    equipment.set_price("示例字符串", 1)
end)```

### Equipment.set_charge_cost_free

**描述:** 设置物品充能无消耗

```lua
Equipment.set_charge_cost_free(_is_free)

参数列表:

参数	类型	说明
_is_free	Bool	是否无消耗

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local equipment = GameAPI.create_equipment(400001, math.Vector3(0,0,0))
    if not equipment then return end
    equipment.set_charge_cost_free(true)
end)```

### Equipment.set_icon

**描述:** 设置物品的图标

```lua
Equipment.set_icon(_icon_key)

参数列表:

参数	类型	说明
_icon_key	ImageKey	图标

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local equipment = GameAPI.create_equipment(400001, math.Vector3(0,0,0))
    if not equipment then return end
    equipment.set_icon(170001)
end)```

### Equipment.set_max_stack_num

**描述:** 设置物品最大堆叠数

```lua
Equipment.set_max_stack_num(_num)

参数列表:

参数	类型	说明
_num	Int	堆叠数

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local equipment = GameAPI.create_equipment(400001, math.Vector3(0,0,0))
    if not equipment then return end
    equipment.set_max_stack_num(1)
end)```

### Equipment.set_name

**描述:** 设置物品的名称

```lua
Equipment.set_name(_name)

参数列表:

参数	类型	说明
_name	Str	名称

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local equipment = GameAPI.create_equipment(400001, math.Vector3(0,0,0))
    if not equipment then return end
    equipment.set_name("平凡蛋0")
end)```

### Equipment.set_saleable

**描述:** 设置物品能否出售

```lua
Equipment.set_saleable(_saleable)

参数列表:

参数	类型	说明
_saleable	Bool	能否出售

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local equipment = GameAPI.create_equipment(400001, math.Vector3(0,0,0))
    if not equipment then return end
    equipment.set_saleable(true)
end)```

### Equipment.start_charge

**描述:** 使物品开始充能

```lua
Equipment.start_charge()

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local equipment = GameAPI.create_equipment(400001, math.Vector3(0,0,0))
    if not equipment then return end
    equipment.start_charge()
end)```

### Equipment.set_usable

**描述:** 设置物品能否使用

```lua
Equipment.set_usable(_usable)

参数列表:

参数	类型	说明
_usable	Bool	能否使用

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local equipment = GameAPI.create_equipment(400001, math.Vector3(0,0,0))
    if not equipment then return end
    equipment.set_usable(true)
end)```

### UnitInteractVolumeComp.set_interact_button_icon

**描述:** 设置单位互动按钮图标

```lua
UnitInteractVolumeComp.set_interact_button_icon(_interact_id, _icon)

参数列表:

参数	类型	说明
_interact_id	InteractBtnID	互动按钮ID
_icon	ImageKey	互动按钮图标

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    unit.set_interact_button_icon(1, 170001)
end)```

### UnitInteractVolumeComp.set_interact_button_text

**描述:** 设置单位互动按钮文本

```lua
UnitInteractVolumeComp.set_interact_button_text(_interact_id, _text)

参数列表:

参数	类型	说明
_interact_id	InteractBtnID	互动按钮ID
_text	Str	互动按钮文本

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    unit.set_interact_button_text(1, "示例文本")
end)```

### UnitInteractVolumeComp.set_interact_enabled

**描述:** 设置单位互动是否启用

```lua
UnitInteractVolumeComp.set_interact_enabled(_enable)

参数列表:

参数	类型	说明
_enable	Bool	是否启用

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    unit.set_interact_enabled(true)
end)```

### UnitInteractVolumeComp.set_interact_enabled_by_index

**描述:** 设置单位互动是否启用(索引)

```lua
UnitInteractVolumeComp.set_interact_enabled_by_index(_interact_index, _enable)

参数列表:

参数	类型	说明
_interact_index	Int	互动索引
_enable	Bool	是否启用

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    unit.set_interact_enabled_by_index(1, true)
end)```

### JointAssistantComp.set_joint_assistant_enabled

**描述:** 设置关节组件的启用状态

```lua
JointAssistantComp.set_joint_assistant_enabled(_enable)

参数列表:

参数	类型	说明
_enable	Bool	开关

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    -- 关节辅助方法挂在关节单位上：取角色身上的第一个辅助关节
    local joints = GameAPI.get_joint_assistants(role.get_ctrl_unit())
    local joint = joints and joints[1]
    if not joint then return end
    joint.set_joint_assistant_enabled(true)
end)```

### JointAssistantComp.set_joint_assistant_property

**描述:** 设置关节组件属性

```lua
JointAssistantComp.set_joint_assistant_property(_property_type, _value)

参数列表:

参数	类型	说明
_property_type	JointAssistantProperty	属性
_value	Fixed	值

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    -- 关节辅助方法挂在关节单位上：取角色身上的第一个辅助关节
    local joints = GameAPI.get_joint_assistants(role.get_ctrl_unit())
    local joint = joints and joints[1]
    if not joint then return end
    joint.set_joint_assistant_property(Enums.JointAssistantProperty.STIFFNESS, 1.0)
end)```

### JointAssistantComp.set_joint_assistant_visible

**描述:** 设置关节组件可见性

```lua
JointAssistantComp.set_joint_assistant_visible(_visible)

参数列表:

参数	类型	说明
_visible	Bool	可见性

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    -- 关节辅助方法挂在关节单位上：取角色身上的第一个辅助关节
    local joints = GameAPI.get_joint_assistants(role.get_ctrl_unit())
    local joint = joints and joints[1]
    if not joint then return end
    joint.set_joint_assistant_visible(true)
end)```

### LifeEntity.set_hpbar_scale

**描述:** 设置生命体血条缩放

```lua
LifeEntity.set_hpbar_scale(_hpbar_scale_x, _hpbar_scale_y)

参数列表:

参数	类型	说明
_hpbar_scale_x	Fixed	宽度缩放
_hpbar_scale_y	Fixed	高度缩放

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- NPC单位，AI行为的执行者
    if not npc then return end
    npc.set_hpbar_scale(1.0, 1.0)
end)```

### LiftComp.set_lift_cooldown

**描述:** 设置举起冷却时间

```lua
LiftComp.set_lift_cooldown(_cd_time)

参数列表:

参数	类型	说明
_cd_time	Fixed	时间

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    unit.set_lift_cooldown(1.0)
end)```

### LiftComp.set_lift_remaining_cooldown

**描述:** 设置举起剩余冷却时间

```lua
LiftComp.set_lift_remaining_cooldown(_time)

参数列表:

参数	类型	说明
_time	Fixed	时间

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    unit.set_lift_remaining_cooldown(1.0)
end)```

### Obstacle.set_ranklist_score

**描述:** 设置场景排行榜分数

```lua
Obstacle.set_ranklist_score(_role, _score)

参数列表:

参数	类型	说明
_role	Role	玩家
_score	Int	分数

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local obstacle = GameAPI.create_obstacle(200001, math.Vector3(0,0,0), math.Quaternion(0,0,0), math.Vector3(1,1,1), nil)
    if not obstacle then return end
    obstacle.set_ranklist_score(role, 1)
end)```

### Unit.set_model_visible

**描述:** 设置单位模型是否可见

```lua
Unit.set_model_visible(_v)

参数列表:

参数	类型	说明
_v	Bool	是否可见

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    unit.set_model_visible(true)
end)```

### Unit.set_physics_active

**描述:** 设置单位物理是否生效

```lua
Unit.set_physics_active(_is_active)

参数列表:

参数	类型	说明
_is_active	Bool	是否生效

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    unit.set_physics_active(true)
end)```

### Modifier.set_remain_duration

**描述:** 设置效果剩余时间

```lua
Modifier.set_remain_duration(_remain_duration)

参数列表:

参数	类型	说明
_remain_duration	Fixed	剩余持续时间

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local modifier = unit.add_modifier_by_key(600001, {})
    if not modifier then return end
    modifier.set_remain_duration(1.0)
end)```

### Obstacle.set_climbable

**描述:** 设置组件是否可攀爬

```lua
Obstacle.set_climbable(_enable)

参数列表:

参数	类型	说明
_enable	Bool	是否可攀爬

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local obstacle = GameAPI.create_obstacle(200001, math.Vector3(0,0,0), math.Quaternion(0,0,0), math.Vector3(1,1,1), nil)
    if not obstacle then return end
    obstacle.set_climbable(true)
end)```

### Role.set_role_ctrl_enabled

**描述:** 设置玩家控制开启/关闭

```lua
Role.set_role_ctrl_enabled(_enable)

参数列表:

参数	类型	说明
_enable	Bool	开启/关闭

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    role.set_role_ctrl_enabled(true)
end)```

### Role.set_archive_point

**描述:** 设置存档点坐标

```lua
Role.set_archive_point(_position, _priority, _direction)

参数列表:

参数	类型	说明
_position	Point3	坐标
_priority	Int	复活优先级
_direction	Vector3	朝向

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    role.set_archive_point(math.Vector3(0, 0, 0), 1, math.Vector3(0, 0, 0))
end)```

### RollComp.set_roll_remaining_cooldown

**描述:** 设置滚动剩余冷却时间

```lua
RollComp.set_roll_remaining_cooldown(_remaining_time)

参数列表:

参数	类型	说明
_remaining_time	Fixed	剩余冷却时间

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    unit.set_roll_remaining_cooldown(1.0)
end)```

### RushComp.set_rush_remaining_cooldown

**描述:** 设置飞扑剩余冷却时间

```lua
RushComp.set_rush_remaining_cooldown(_time)

参数列表:

参数	类型	说明
_time	Fixed	时间

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    unit.set_rush_remaining_cooldown(1.0)
end)```

### LifeEntity.set_search_enemy_focus_target

**描述:** 设置搜敌集火目标

```lua
LifeEntity.set_search_enemy_focus_target(_target)

参数列表:

参数	类型	说明
_target	Unit	目标

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- NPC单位，AI行为的执行者
    if not npc then return end
    npc.set_search_enemy_focus_target(role)
end)```

### EquipmentComp.select_equipment_slot

**描述:** 设置单位选中物品格

```lua
EquipmentComp.select_equipment_slot(_slot_type, _slot_index)

参数列表:

参数	类型	说明
_slot_type	EquipmentSlotType	槽位类型
_slot_index	Int	槽位索引

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    unit.select_equipment_slot(Enums.EquipmentSlotType.EQUIPPED, 1)
end)```

### Modifier.set_stack_count

**描述:** 设置效果层数

```lua
Modifier.set_stack_count(_stack_count_add)

参数列表:

参数	类型	说明
_stack_count_add	Int	层数

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local modifier = unit.add_modifier_by_key(600001, {})
    if not modifier then return end
    modifier.set_stack_count(1)
end)```

### KVBase.add_tag

**描述:** 添加标签

```lua
KVBase.add_tag(_tag)

参数列表:

参数	类型	说明
_tag	Str	标签

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    unit.add_tag("enemy")
end)```

### Role.set_unit_fresnel

**描述:** 设置单位菲尼尔效果

```lua
Role.set_unit_fresnel(_unit, _fresnel_scale, _color, _intensity)

参数列表:

参数	类型	说明
_unit	Unit	单位
_fresnel_scale	Fixed	菲尼尔系数
_color	Color	颜色
_intensity	Int	强度

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end

    role.set_unit_fresnel(role.get_ctrl_unit(), 1.0, GlobalAPI.str_to_color("ff0000"), 1)
end)```

### LifeEntity.set_max_yaw_speed

**描述:** 设置单位每秒最大旋转速度

```lua
LifeEntity.set_max_yaw_speed(_limit_yaw_speed)

参数列表:

参数	类型	说明
_limit_yaw_speed	Fixed	yaw值改变速度

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- NPC单位，AI行为的执行者
    if not npc then return end
    npc.set_max_yaw_speed(1.0)
end)```

### Role.set_unit_mask

**描述:** 设置单位蒙版

```lua
Role.set_unit_mask(_unit, _color)

参数列表:

参数	类型	说明
_unit	Unit	单位
_color	Color	颜色

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end

    role.set_unit_mask(role.get_ctrl_unit(), GlobalAPI.str_to_color("ff0000"))
end)```

### Unit.set_mirror_reflect_enabled

**描述:** 开关镜面反射

```lua
Unit.set_mirror_reflect_enabled(_enable)

参数列表:

参数	类型	说明
_enable	Bool	是否启用

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    unit.set_mirror_reflect_enabled(true)
end)```

### LifeEntity.disable_yaw_speed_limit

**描述:** 关闭单位最大旋转速度限制

```lua
LifeEntity.disable_yaw_speed_limit()

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- NPC单位，AI行为的执行者
    if not npc then return end
    npc.disable_yaw_speed_limit()
end)```

### Unit.set_orientation

**描述:** 设置单位旋转

```lua
Unit.set_orientation(_rot)

参数列表:

参数	类型	说明
_rot	Quaternion	旋转

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    unit.set_orientation(math.Quaternion(0, 0, 0))
end)```

### Role.set_unit_outline

**描述:** 设置单位描边

```lua
Role.set_unit_outline(_unit, _width, _color)

参数列表:

参数	类型	说明
_unit	Unit	单位
_width	Int	粗细
_color	Color	颜色

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end

    role.set_unit_outline(role.get_ctrl_unit(), 1, GlobalAPI.str_to_color("ff0000"))
end)```

### Unit.set_position

**描述:** 重置单位坐标

```lua
Unit.set_position(_pos)

参数列表:

参数	类型	说明
_pos	Vector3	坐标

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    unit.set_position(math.Vector3(0, 0, 0))
end)```

### Role.set_unit_see_through_enabled

**描述:** 设置单位穿透显示

```lua
Role.set_unit_see_through_enabled(_unit, _enabled)

参数列表:

参数	类型	说明
_unit	Unit	单位
_enabled	Bool	是否穿透显示

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end

    role.set_unit_see_through_enabled(role.get_ctrl_unit(), true)
end)```

### TriggerSpace.set_virtual_light_brightness

**描述:** 设置光源亮度

```lua
TriggerSpace.set_virtual_light_brightness(_brightness)

参数列表:

参数	类型	说明
_brightness	Fixed	亮度

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local ts = GameAPI.create_triggerspace(900001, math.Vector3(0,0,0), math.Quaternion(0,0,0), math.Vector3(1,1,1), nil)
    if not ts then return end
    ts.set_virtual_light_brightness(1.0)
end)```

### Role.show_goods_purchase_panel

**描述:** 玩家显示指定商品购买界面

```lua
Role.show_goods_purchase_panel(_raw_goods_id, _show_time)

参数列表:

参数	类型	说明
_raw_goods_id	UgcGoods	商品
_show_time	Fixed	显示时间

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local ugc_goods = "goods_1001"  -- 商品 key（示意值，需替换为实际配置）
    role.show_goods_purchase_panel(ugc_goods, 1.0)
end)```

### LifeEntity.start_ai

**描述:** 激活AI

```lua
LifeEntity.start_ai()

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- NPC单位，AI行为的执行者
    if not npc then return end
    npc.start_ai()
end)```

### LifeEntity.stop_ai

**描述:** 暂停AI

```lua
LifeEntity.stop_ai()

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- NPC单位，AI行为的执行者
    if not npc then return end
    npc.stop_ai()
end)```

### Unit.model_stop_animation

**描述:** 模型停止动画

```lua
Unit.model_stop_animation()

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    unit.model_stop_animation()
end)```

### Unit.stop_sound

**描述:** 单位停止播放声音

```lua
Unit.stop_sound(_lres_id)

参数列表:

参数	类型	说明
_lres_id	SoundID	音效ID

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    -- 播放 3D 音效获取实例 ID（5129 为音效配置 ID），供后续停止/管理使用
    local sound_id = GameAPI.play_3d_sound(unit.get_position(), 5129, -1.0, 100.0)
    unit.stop_sound(sound_id)
end)```

### DisplayComp.bind_model

**描述:** 添加绑定模型

```lua
DisplayComp.bind_model(_model_id, _socket, _offset, _rot, _scale)

参数列表:

参数	类型	说明
_model_id	UnitKey	单位编号
_socket	ModelSocket	挂点
_offset	Point3	偏移
_rot	Quaternion	旋转
_scale	Vector3	缩放

返回值:

• 类型: Str
• 说明: 绑定ID

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = unit.bind_model(100001, Enums.ModelSocket.socket_body, math.Vector3(0, 0, 0), math.Quaternion(0, 0, 0), math.Vector3(0, 0, 0))
end)```

### DisplayComp.bind_model_by_unit

**描述:** 添加绑定模型

```lua
DisplayComp.bind_model_by_unit(_unit, _socket, _offset, _rot)

参数列表:

参数	类型	说明
_unit	Unit	单位
_socket	ModelSocket	挂点
_offset	Point3	偏移
_rot	Quaternion	旋转

返回值:

• 类型: Str
• 说明: 绑定ID

示例:

-- 绑定目标单位模型到自身挂点（需场景中存在目标单位）
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end

    -- 绑定目标单位模型（需场景中存在目标单位）
    local target = LuaAPI.query_unit("NPC队长")
    if target then
        local result = unit.bind_model_by_unit(target, Enums.ModelSocket.socket_body, math.Vector3(0, 0, 0), math.Quaternion(0, 0, 0))
    end
end)```

### Unit.disable_gravity

**描述:** 关闭重力影响

```lua
Unit.disable_gravity()

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    unit.disable_gravity()
end)```

### Unit.enable_gravity

**描述:** 开启重力影响

```lua
Unit.enable_gravity()

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    unit.enable_gravity()
end)```

### LiftedComp.is_lifted_enabled

**描述:** 获取是否可抓举

```lua
LiftedComp.is_lifted_enabled()

返回值:

• 类型: Bool
• 说明: 是否可抓举

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = unit.is_lifted_enabled()
end)```

### Unit.get_max_linear_velocity

**描述:** 获取单位最大线速度

```lua
Unit.get_max_linear_velocity()

返回值:

• 类型: Fixed
• 说明: 线速度

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local result = unit.get_max_linear_velocity()
end)```

### Unit.recover_max_linear_velocity

**描述:** 恢复单位最大线速度

```lua
Unit.recover_max_linear_velocity()

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    unit.recover_max_linear_velocity()
end)```

### LiftedComp.set_custom_thrown_force

**描述:** 设置自定义投掷力量

```lua
LiftedComp.set_custom_thrown_force(_force)

参数列表:

参数	类型	说明
_force	Fixed	力量

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    unit.set_custom_thrown_force(1.0)
end)```

### LiftedComp.set_custom_thrown_force_enabled

**描述:** 设置是否自定义投掷力量

```lua
LiftedComp.set_custom_thrown_force_enabled(_enable)

参数列表:

参数	类型	说明
_enable	Bool	是否自定义

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    unit.set_custom_thrown_force_enabled(true)
end)```

### LiftedComp.set_lifted_enabled

**描述:** 设置是否可抓举

```lua
LiftedComp.set_lifted_enabled(_enable)

参数列表:

参数	类型	说明
_enable	Bool	是否可被抓举

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    unit.set_lifted_enabled(true)
end)```

### Unit.set_linear_velocity

**描述:** 改变单位线速度

```lua
Unit.set_linear_velocity(_vel)

参数列表:

参数	类型	说明
_vel	Vector3	线速度

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    unit.set_linear_velocity(math.Vector3(0, 0, 0))
end)```

### Unit.set_max_linear_velocity

**描述:** 设置单位最大线速度

```lua
Unit.set_max_linear_velocity(_velocity)

参数列表:

参数	类型	说明
_velocity	Fixed	线速度

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    unit.set_max_linear_velocity(1.0)
end)```

### VehicleComp.reset

**描述:** 载具复位

```lua
VehicleComp.reset()

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    -- 示例需要载具对象：创建一辆载具（500001 为示意 key，需替换为实际配置）
    local vehicle = GameAPI.create_vehicle(500001, unit.get_position(), math.Vector3(0, 0, 1), role)
    if not vehicle then return end
    vehicle.reset()
end)```

### VehicleComp.start_move_by_direction

**描述:** 使载具往某个方向移动一段时间

```lua
VehicleComp.start_move_by_direction(_direction, _duration)

参数列表:

参数	类型	说明
_direction	Vector3	方向
_duration	Fixed	持续时间

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    -- 示例需要载具对象：创建一辆载具（500001 为示意 key，需替换为实际配置）
    local vehicle = GameAPI.create_vehicle(500001, unit.get_position(), math.Vector3(0, 0, 1), role)
    if not vehicle then return end
    vehicle.start_move_by_direction(math.Vector3(0, 0, 0), 1.0)
end)```

### VehicleComp.stop_move

**描述:** 使载具停止移动

```lua
VehicleComp.stop_move()

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    -- 示例需要载具对象：创建一辆载具（500001 为示意 key，需替换为实际配置）
    local vehicle = GameAPI.create_vehicle(500001, unit.get_position(), math.Vector3(0, 0, 1), role)
    if not vehicle then return end
    vehicle.stop_move()
end)```

### Role.start_level_vote

**描述:** 发起进入关卡投票

```lua
Role.start_level_vote(_level_key)

参数列表:

参数	类型	说明
_level_key	LevelKey	关卡编号

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    role.start_level_vote("290001")
end)```

### AbilityComp.cast_ability_by_ability_slot_and_direction

**描述:** 控制角色对目标方向释放指定槽位技能

```lua
AbilityComp.cast_ability_by_ability_slot_and_direction(_direction, _ability_slot, _duration)

参数列表:

参数	类型	说明
_direction	Vector3	方向
_ability_slot	AbilitySlot	技能槽位
_duration	Fixed	时间

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local ability_slot = 1  -- AbilitySlot 是槽位整数索引
    unit.cast_ability_by_ability_slot_and_direction(math.Vector3(0, 0, 0), ability_slot, 1.0)
end)```

### AbilityComp.cast_ability_by_ability_slot_and_position

**描述:** 控制角色对目标坐标释放指定槽位技能

```lua
AbilityComp.cast_ability_by_ability_slot_and_position(_position, _ability_slot, _duration)

参数列表:

参数	类型	说明
_position	Point3	坐标
_ability_slot	AbilitySlot	技能槽位
_duration	Fixed	时间

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local ability_slot = 1  -- AbilitySlot 是槽位整数索引
    unit.cast_ability_by_ability_slot_and_position(math.Vector3(0, 0, 0), ability_slot, 1.0)
end)```

### AbilityComp.cast_ability_by_ability_slot_and_target

**描述:** 控制角色对目标单位释放指定槽位技能

```lua
AbilityComp.cast_ability_by_ability_slot_and_target(_target, _ability_slot, _duration)

参数列表:

参数	类型	说明
_target	LifeEntity	目标
_ability_slot	AbilitySlot	技能槽位
_duration	Fixed	时间

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- NPC单位，AI行为的执行者
    local ability_slot = 1  -- AbilitySlot 是槽位整数索引
    unit.cast_ability_by_ability_slot_and_target(npc, ability_slot, 1.0)
end)```

### AbilityComp.cast_ability_by_direction

**描述:** 控制角色对指定方向执行释放指定预设技能

```lua
AbilityComp.cast_ability_by_direction(_ability_key, _duration, _direction, _ability_slot)

参数列表:

参数	类型	说明
_ability_key	AbilityKey	技能编号
_duration	Fixed	时间
_direction	Vector3	方向
_ability_slot	AbilitySlot	技能槽位

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local ability_slot = 1  -- AbilitySlot 是槽位整数索引
    unit.cast_ability_by_direction(150001, 1.0, math.Vector3(0, 0, 0), ability_slot)
end)```

### AbilityComp.cast_ability_by_position

**描述:** 控制角色对指定坐标执行释放预设技能

```lua
AbilityComp.cast_ability_by_position(_ability_key, _duration, _position, _ability_slot)

参数列表:

参数	类型	说明
_ability_key	AbilityKey	技能编号
_duration	Fixed	时间
_position	Point3	坐标
_ability_slot	AbilitySlot	技能槽位

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local ability_slot = 1  -- AbilitySlot 是槽位整数索引
    unit.cast_ability_by_position(150001, 1.0, math.Vector3(0, 0, 0), ability_slot)
end)```

### AbilityComp.cast_ability_by_target

**描述:** 控制角色对指定目标执行释放指定预设技能

```lua
AbilityComp.cast_ability_by_target(_ability_key, _duration, _target, _ability_slot)

参数列表:

参数	类型	说明
_ability_key	AbilityKey	技能编号
_duration	Fixed	时间
_target	LifeEntity	目标
_ability_slot	AbilitySlot	技能槽位

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- NPC单位，AI行为的执行者
    local ability_slot = 1  -- AbilitySlot 是槽位整数索引
    unit.cast_ability_by_target(150001, 1.0, npc, ability_slot)
end)```

### AbilityComp.get_prop_ability

**描述:** 获取道具技能

```lua
AbilityComp.get_prop_ability()

返回值:

• 类型: Ability
• 说明: 技能对象

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = unit.get_prop_ability()
end)```

### AbilityComp.remove_prop_ability

**描述:** 移除道具技能

```lua
AbilityComp.remove_prop_ability()

返回值:

• 类型: Bool
• 说明: 是否成功移除

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = unit.remove_prop_ability()
end)```

### AbilityComp.set_ability_enabled_on_vehicle

**描述:** 设置是否能在载具上使用用技能

```lua
AbilityComp.set_ability_enabled_on_vehicle(_enable)

参数列表:

参数	类型	说明
_enable	Bool	是否能用技能

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    unit.set_ability_enabled_on_vehicle(true)
end)```

### AttrComp.get_attr_by_type

**描述:** 获取属性

```lua
AttrComp.get_attr_by_type(_value_type, _key)

参数列表:

参数	类型	说明
_value_type	ValueType	值类型
_key	Str	属性名

返回值:

• 类型: ETypeMeta
• 说明: 属性值

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = unit.get_attr_by_type(Enums.ValueType.Int, "key_001")
end)```

### AttrComp.set_attr_bonus_fixed

**描述:** 设置属性的额外固定值(复杂模式)

```lua
AttrComp.set_attr_bonus_fixed(_key, _value)

参数列表:

参数	类型	说明
_key	Str	属性名
_value	Fixed	额外固定值

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    unit.set_attr_bonus_fixed("key_001", 1.0)
end)```

### AttrComp.set_attr_by_type

**描述:** 设置属性

```lua
AttrComp.set_attr_by_type(_value_type, _key, _val)

参数列表:

参数	类型	说明
_value_type	ValueType	值类型
_key	Str	属性名
_val	ETypeMeta	属性值

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    unit.set_attr_by_type(Enums.ValueType.Int, "key_001", nil --[[ETypeMeta]])
end)```

### AttrComp.set_attr_ratio_fixed

**描述:** 设置属性的倍率值(复杂模式)

```lua
AttrComp.set_attr_ratio_fixed(_key, _value)

参数列表:

参数	类型	说明
_key	Str	属性名
_value	Fixed	倍率值

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    unit.set_attr_ratio_fixed("key_001", 1.0)
end)```

### AttrComp.set_attr_raw_fixed

**描述:** 设置属性的基础值(复杂模式)

```lua
AttrComp.set_attr_raw_fixed(_key, _value)

参数列表:

参数	类型	说明
_key	Str	属性名
_value	Fixed	基础值

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    unit.set_attr_raw_fixed("key_001", 1.0)
end)```

### Camp.change_camp_score

**描述:** 改变阵营积分

```lua
Camp.change_camp_score(_add_score)

参数列表:

参数	类型	说明
_add_score	Int	变化积分

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local camp = GameAPI.get_camp(1)
    if not camp then return end
    camp.change_camp_score(1)
end)```

### Character.change_custom_model_by_creature

**描述:** 根据生物修改角色所有外观部位自定义模型

```lua
Character.change_custom_model_by_creature(_creature)

参数列表:

参数	类型	说明
_creature	Creature	生物

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- Character 继承自 LifeEntity，代表NPC角色单位
    if not npc then return end
    local creature = GameAPI.create_creature_fixed_scale(100001, math.Vector3(0,0,0), math.Quaternion(0,0,0), 1.0, GameAPI.get_all_valid_roles()[1])
    if not creature then return end
    npc.change_custom_model_by_creature(creature)
end)```

### Character.change_custom_model_by_creature_key

**描述:** 根据生物预设修改角色所有外观部位自定义模型

```lua
Character.change_custom_model_by_creature_key(_creature_key)

参数列表:

参数	类型	说明
_creature_key	CreatureKey	生物编号

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- Character 继承自 LifeEntity，代表NPC角色单位
    if not npc then return end
    npc.change_custom_model_by_creature_key(100001)
end)```

### Character.get_joystick_direction

**描述:** 获取角色原始输入前进方向

```lua
Character.get_joystick_direction()

返回值:

• 类型: Vector3
• 说明: 摇杆控制前进方向

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- Character 继承自 LifeEntity，代表NPC角色单位
    if not npc then return end
    local result = npc.get_joystick_direction()
end)```

### Character.set_socket_model_by_creature_key

**描述:** 修改角色指定外观部位为自定义模型

```lua
Character.set_socket_model_by_creature_key(_model_socket, _creature_key, _creature_model_socket)

参数列表:

参数	类型	说明
_model_socket	ModelSocket	外观部位
_creature_key	CreatureKey	生物编号
_creature_model_socket	ModelSocket	外观部位

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- Character 继承自 LifeEntity，代表NPC角色单位
    if not npc then return end
    npc.set_socket_model_by_creature_key(Enums.ModelSocket.socket_body, 100001, Enums.ModelSocket.socket_body)
end)```

### Creature.force_start_move

**描述:** 命令生物移动

```lua
Creature.force_start_move(_direction, _t)

参数列表:

参数	类型	说明
_direction	Vector3	方向
_t	Fixed	时间

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local creature = GameAPI.create_creature_fixed_scale(100001, math.Vector3(0,0,0), math.Quaternion(0,0,0), 1.0, GameAPI.get_all_valid_roles()[1])
    if not creature then return end
    creature.force_start_move(math.Vector3(0, 0, 0), 1.0)
end)```

### Creature.force_stop_move

**描述:** 命令生物停止移动

```lua
Creature.force_stop_move()

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local creature = GameAPI.create_creature_fixed_scale(100001, math.Vector3(0,0,0), math.Quaternion(0,0,0), 1.0, GameAPI.get_all_valid_roles()[1])
    if not creature then return end
    creature.force_stop_move()
end)```

### Creature.reset_target_socket_model

**描述:** 还原生物指定外观部位变化

```lua
Creature.reset_target_socket_model(_model_socket)

参数列表:

参数	类型	说明
_model_socket	ModelSocket	外观部位

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local creature = GameAPI.create_creature_fixed_scale(100001, math.Vector3(0,0,0), math.Quaternion(0,0,0), 1.0, GameAPI.get_all_valid_roles()[1])
    if not creature then return end
    creature.reset_target_socket_model(Enums.ModelSocket.socket_body)
end)```

### Creature.set_socket_model

**描述:** 修改生物指定外观部位为自定义模型

```lua
Creature.set_socket_model(_model_socket, _creature, _creature_model_socket)

参数列表:

参数	类型	说明
_model_socket	ModelSocket	外观部位
_creature	Creature	生物
_creature_model_socket	ModelSocket	外观部位

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local creature = GameAPI.create_creature_fixed_scale(100001, math.Vector3(0,0,0), math.Quaternion(0,0,0), 1.0, GameAPI.get_all_valid_roles()[1])
    if not creature then return end
    creature.set_socket_model(Enums.ModelSocket.socket_body, creature, Enums.ModelSocket.socket_body)
end)```

### Creature.set_socket_model_by_creature_key

**描述:** 修改生物指定外观部位为自定义模型

```lua
Creature.set_socket_model_by_creature_key(_model_socket, _creature_key, _creature_model_socket)

参数列表:

参数	类型	说明
_model_socket	ModelSocket	外观部位
_creature_key	CreatureKey	生物编号
_creature_model_socket	ModelSocket	外观部位

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local creature = GameAPI.create_creature_fixed_scale(100001, math.Vector3(0,0,0), math.Quaternion(0,0,0), 1.0, GameAPI.get_all_valid_roles()[1])
    if not creature then return end
    creature.set_socket_model_by_creature_key(Enums.ModelSocket.socket_body, 100001, Enums.ModelSocket.socket_body)
end)```

### DisplayComp.force_play_animation_by_anim_key

**描述:** 强制播放动画

```lua
DisplayComp.force_play_animation_by_anim_key(_anim_key, _start_time, _play_time, _play_rate, _is_loop)

参数列表:

参数	类型	说明
_anim_key	AnimKey	动画编号
_start_time	Fixed	开始时间
_play_time	Fixed	持续时间
_play_rate	Fixed	播放速率
_is_loop	Bool	是否循环

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    unit.force_play_animation_by_anim_key(250001, 1.0, 1.0, 1.0, true)
end)```

### Equipment.drop

**描述:** 物品被丢弃

```lua
Equipment.drop()

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local equipment = GameAPI.create_equipment(400001, math.Vector3(0,0,0))
    if not equipment then return end
    equipment.drop()
end)```

### EquipmentComp.set_equipment_max_count

**描述:** 修改最大可持有的物品数量

```lua
EquipmentComp.set_equipment_max_count(_slot_type, _slot_num)

参数列表:

参数	类型	说明
_slot_type	EquipmentSlotType	槽位类型
_slot_num	Int	数量

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    unit.set_equipment_max_count(Enums.EquipmentSlotType.EQUIPPED, 1)
end)```

### ItemBox.add_equipment

**描述:** 添加物品箱刷新预设

```lua
ItemBox.add_equipment(_key, _weight)

参数列表:

参数	类型	说明
_key	EquipmentKey	物品编号
_weight	Int	权重

示例:

-- 向道具箱放入装备（itemBox 为场景中配置的道具箱单位）
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 道具箱单位需在场景中配置（此处按名字查询，不存在则跳过）
    local itemBox = LuaAPI.query_unit("道具箱")
    if not itemBox then return end

    itemBox.add_equipment(400001, 1)
end)```

### ItemBox.remove_equipment

**描述:** 移除物品箱刷新预设

```lua
ItemBox.remove_equipment(_key)

参数列表:

参数	类型	说明
_key	EquipmentKey	物品编号

示例:

-- 从道具箱移除装备（itemBox 为场景中配置的道具箱单位）
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    -- 道具箱单位需在场景中配置（此处按名字查询，不存在则跳过）
    local itemBox = LuaAPI.query_unit("道具箱")
    if not itemBox then return end

    itemBox.remove_equipment(400001)
end)```

### JumpComp.get_multi_jump_remaining_cooldown

**描述:** 获取多段跳剩余冷却

```lua
JumpComp.get_multi_jump_remaining_cooldown()

返回值:

• 类型: Fixed
• 说明: 冷却时间

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = unit.get_multi_jump_remaining_cooldown()
end)```

### JumpComp.set_multi_jump_remaining_cooldown

**描述:** 设置多段跳剩余冷却

```lua
JumpComp.set_multi_jump_remaining_cooldown(_cd)

参数列表:

参数	类型	说明
_cd	Fixed	冷却时间

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    unit.set_multi_jump_remaining_cooldown(1.0)
end)```

### KVBase.get_kv_by_type

**描述:** 获取自定义值

```lua
KVBase.get_kv_by_type(_value_type, _key)

参数列表:

参数	类型	说明
_value_type	ValueType	值类型
_key	Str	名称

返回值:

• 类型: ETypeMeta
• 说明: 自定义值

示例:

-- 按类型读取单位自定义值（先确认存在再读取）
LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end

    -- 先确认存在再读取，避免读取不存在的键
    if unit.has_kv("key_001") then
        local result = unit.get_kv_by_type(Enums.ValueType.Int, "key_001")
    end
end)```

### KVBase.set_kv_by_type

**描述:** 设置自定义值

```lua
KVBase.set_kv_by_type(_value_type, _key, _val)

参数列表:

参数	类型	说明
_value_type	ValueType	值类型
_key	Str	名称
_val	ETypeMeta	自定义值

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    unit.set_kv_by_type(Enums.ValueType.Int, "key_001", nil --[[ETypeMeta]])
end)```

### LifeComp.change_hp

**描述:** 改变健康值

```lua
LifeComp.change_hp(_value)

参数列表:

参数	类型	说明
_value	Fixed	改变健康值

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    unit.change_hp(1.0)
end)```

### LifeComp.get_hp

**描述:** 获取健康值

```lua
LifeComp.get_hp()

返回值:

• 类型: Fixed
• 说明: 健康值

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = unit.get_hp()
end)```

### LifeComp.get_hp_max

**描述:** 获取最大健康值

```lua
LifeComp.get_hp_max()

返回值:

• 类型: Fixed
• 说明: 最大健康值

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = unit.get_hp_max()
end)```

### LifeComp.get_life

**描述:** 获取当前命数

```lua
LifeComp.get_life()

返回值:

• 类型: Int
• 说明: 当前命数

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = unit.get_life()
end)```

### LifeComp.get_life_max

**描述:** 获取最大命数

```lua
LifeComp.get_life_max()

返回值:

• 类型: Int
• 说明: 当前命数

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = unit.get_life_max()
end)```

### LifeComp.set_hp_max

**描述:** 设置最大健康值

```lua
LifeComp.set_hp_max(_value)

参数列表:

参数	类型	说明
_value	Fixed	最大健康值

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    unit.set_hp_max(1.0)
end)```

### LifeComp.set_life_count

**描述:** 改变当前命数

```lua
LifeComp.set_life_count(_value)

参数列表:

参数	类型	说明
_value	Int	当前命数

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    unit.set_life_count(1)
end)```

### LifeComp.set_life_max

**描述:** 改变最大命数

```lua
LifeComp.set_life_max(_value)

参数列表:

参数	类型	说明
_value	Int	最大命数

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    unit.set_life_max(1)
end)```

### LifeComp.set_reborn_in_place

**描述:** 设置是否原地复活

```lua
LifeComp.set_reborn_in_place(_reborn_in_place, _reset_camera)

参数列表:

参数	类型	说明
_reborn_in_place	Bool	是否原地复活
_reset_camera	Bool	是否重置相机

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    unit.set_reborn_in_place(true, true)
end)```

### LifeEntity.ai_command_chase_with_ability

**描述:** 控制AI执行追击行为(技能)

```lua
LifeEntity.ai_command_chase_with_ability(_target, _chase_range, _reject_time, _action_distance, _ability_key, _move_mode, _action_count)

参数列表:

参数	类型	说明
_target	Unit	目标
_chase_range	Fixed	追击范围
_reject_time	Fixed	厌恶时间
_action_distance	Fixed	反应距离
_ability_key	AbilityKey	反应行为
_move_mode	MoveMode	移动方式
_action_count	Int	追击次数

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- NPC单位，AI行为的执行者
    if not npc then return end
    npc.ai_command_chase_with_ability(role, 1.0, 1.0, 1.0, 150001, Enums.MoveMode.DEFAULT, 1)
end)```

### LifeEntity.ai_command_chase_with_action

**描述:** 控制AI执行追击行为(命令)

```lua
LifeEntity.ai_command_chase_with_action(_target, _chase_range, _reject_time, _action_distance, _action_mode, _move_mode, _action_count)

参数列表:

参数	类型	说明
_target	Unit	目标
_chase_range	Fixed	追击范围
_reject_time	Fixed	厌恶时间
_action_distance	Fixed	反应距离
_action_mode	AIBasicCommand	反应行为
_move_mode	MoveMode	移动方式
_action_count	Int	追击次数

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- NPC单位，AI行为的执行者
    if not npc then return end
    npc.ai_command_chase_with_action(role, 1.0, 1.0, 1.0, Enums.AIBasicCommand.MOVE, Enums.MoveMode.DEFAULT, 1)
end)```

### LifeEntity.ai_command_chase_with_equipment

**描述:** 控制AI执行追击行为(物品)

```lua
LifeEntity.ai_command_chase_with_equipment(_target, _chase_range, _reject_time, _action_distance, _equipment_key, _move_mode, _action_count)

参数列表:

参数	类型	说明
_target	Unit	目标
_chase_range	Fixed	追击范围
_reject_time	Fixed	厌恶时间
_action_distance	Fixed	反应距离
_equipment_key	EquipmentKey	反应行为
_move_mode	MoveMode	移动方式
_action_count	Int	追击次数

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- NPC单位，AI行为的执行者
    if not npc then return end
    npc.ai_command_chase_with_equipment(role, 1.0, 1.0, 1.0, 400001, Enums.MoveMode.DEFAULT, 1)
end)```

### LifeEntity.ai_command_start_move_high_priority

**描述:** 控制AI执行高优先级寻路命令

```lua
LifeEntity.ai_command_start_move_high_priority(_target_position, _duration, _threshold)

参数列表:

参数	类型	说明
_target_position	ListVector3	坐标
_duration	Fixed	持续时间
_threshold	Fixed	距离阈值

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- NPC单位，AI行为的执行者
    if not npc then return end
    npc.ai_command_start_move_high_priority({math.Vector3(0, 0, 0), math.Vector3(1, 0, 0)}, 1.0, 1.0)
end)```

### LifeEntity.jump

**描述:** 命令角色跳跃

```lua
LifeEntity.jump()

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- NPC单位，AI行为的执行者
    if not npc then return end
    npc.jump()
end)```

### LifeEntity.set_model_by_creature_key

**描述:** 根据生物预设设置模型

```lua
LifeEntity.set_model_by_creature_key(_creature_key, _include_custom_model, _inherit_scale, _inherit_capsule_size)

参数列表:

参数	类型	说明
_creature_key	CreatureKey	生物编号
_include_custom_model	Bool	是否包含自定义形象
_inherit_scale	Bool	是否继承缩放
_inherit_capsule_size	Bool	是否继承胶囊体

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- NPC单位，AI行为的执行者
    if not npc then return end
    npc.set_model_by_creature_key(100001, true, true, true)
end)```

### LifeEntity.set_search_enemy_priority_value_by_tag

**描述:** 设置搜敌优先级值by标签

```lua
LifeEntity.set_search_enemy_priority_value_by_tag(_tag, _priority)

参数列表:

参数	类型	说明
_tag	Str	标签
_priority	Int	优先级

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- NPC单位，AI行为的执行者
    if not npc then return end
    npc.set_search_enemy_priority_value_by_tag("enemy", 1)
end)```

### LifeEntity.set_search_enemy_priority_value_by_unit

**描述:** 设置搜敌优先级值by单位实体

```lua
LifeEntity.set_search_enemy_priority_value_by_unit(_unit, _priority)

参数列表:

参数	类型	说明
_unit	Unit	单位实体
_priority	Int	优先级

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- NPC单位，AI行为的执行者
    if not npc then return end
    npc.set_search_enemy_priority_value_by_unit(role, 1)
end)```

### LifeEntity.set_search_enemy_priority_value_by_unit_key

**描述:** 设置搜敌优先级值by预设编号

```lua
LifeEntity.set_search_enemy_priority_value_by_unit_key(_unit_key, _priority)

参数列表:

参数	类型	说明
_unit_key	CreatureKey	预设编号
_priority	Int	优先级

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- NPC单位，AI行为的执行者
    if not npc then return end
    npc.set_search_enemy_priority_value_by_unit_key(100001, 1)
end)```

### LifeEntity.set_search_enemy_priority_value_by_unit_type

**描述:** 设置搜敌优先级值by单位类型

```lua
LifeEntity.set_search_enemy_priority_value_by_unit_type(_unit_prefab_type, _priority)

参数列表:

参数	类型	说明
_unit_prefab_type	UnitType	单位类型
_priority	Int	优先级

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local npc = LuaAPI.query_unit("平凡蛋0")  -- NPC单位，AI行为的执行者
    if not npc then return end
    npc.set_search_enemy_priority_value_by_unit_type(Enums.UnitType.CHARACTER, 1)
end)```

### Modifier.get_releaser_unit

**描述:** 获取效果释放者

```lua
Modifier.get_releaser_unit()

返回值:

• 类型: Unit
• 说明: 效果释放者

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local modifier = unit.add_modifier_by_key(600001, {})
    if not modifier then return end
    local result = modifier.get_releaser_unit()
end)```

### ModifierComp.add_modifier

**描述:** 添加效果

```lua
ModifierComp.add_modifier(_modifier_id)

参数列表:

参数	类型	说明
_modifier_id	ModifierKey	效果编号

返回值:

• 类型: Modifier
• 说明: 是否添加成功

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = unit.add_modifier(600001)
end)```

### Obstacle.set_collision_count_limit

**描述:** 设置组件碰撞次数限制

```lua
Obstacle.set_collision_count_limit(_limit_type, _value)

参数列表:

参数	类型	说明
_limit_type	CollisionLimitType	碰撞限制类型
_value	Int	值

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local obstacle = GameAPI.create_obstacle(200001, math.Vector3(0,0,0), math.Quaternion(0,0,0), math.Vector3(1,1,1), nil)
    if not obstacle then return end
    obstacle.set_collision_count_limit(Enums.CollisionLimitType.NONE, 1)
end)```

### Obstacle.set_collision_interval_limit

**描述:** 设置组件碰撞间隔限制

```lua
Obstacle.set_collision_interval_limit(_limit_type, _value)

参数列表:

参数	类型	说明
_limit_type	CollisionLimitType	碰撞限制类型
_value	Fixed	值

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local obstacle = GameAPI.create_obstacle(200001, math.Vector3(0,0,0), math.Quaternion(0,0,0), math.Vector3(1,1,1), nil)
    if not obstacle then return end
    obstacle.set_collision_interval_limit(Enums.CollisionLimitType.NONE, 1.0)
end)```

### Role.game_lose_and_show_result_panel

**描述:** 玩家游戏失败并显示失败界面

```lua
Role.game_lose_and_show_result_panel()

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    role.game_lose_and_show_result_panel()
end)```

### Role.game_win_and_show_result_panel

**描述:** 玩家游戏胜利并显示胜利界面

```lua
Role.game_win_and_show_result_panel()

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    role.game_win_and_show_result_panel()
end)```

### Role.get_archive_by_type

**描述:** 获取存档值

```lua
Role.get_archive_by_type(_archive_type, _key)

参数列表:

参数	类型	说明
_archive_type	ArchiveType	存档类型
_key	Archive	存档

返回值:

• 类型: ETypeMeta
• 说明: 存档值

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local archive = 1  -- Archive 是存档编号（integer）
    local result = role.get_archive_by_type(Enums.ArchiveType.Int, archive)
end)```

### Role.get_archive_sheetid

**描述:** 获取表格存档

```lua
Role.get_archive_sheetid(_key)

参数列表:

参数	类型	说明
_key	Archive	存档

返回值:

• 类型: SheetID
• 说明: 表格id

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local archive = 1  -- Archive 是存档编号（integer）
    local result = role.get_archive_sheetid(archive)
end)```

### Role.get_game_result

**描述:** 获取玩家游戏结果

```lua
Role.get_game_result()

返回值:

• 类型: GameResult
• 说明: 游戏结局

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = role.get_game_result()
end)```

### Role.get_roleid

**描述:** 获取玩家ID

```lua
Role.get_roleid()

返回值:

• 类型: RoleID
• 说明: 玩家ID

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = role.get_roleid()
end)```

### Role.lose

**描述:** 玩家游戏失败

```lua
Role.lose()

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    role.lose()
end)```

### Role.send_ui_custom_event

**描述:** 发送UI自定义消息

```lua
Role.send_ui_custom_event(_event_name, _data)

参数列表:

参数	类型	说明
_event_name	Str	自定义事件名
_data	Dict	附带参数

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    role.send_ui_custom_event("自定义事件", { -- 自定义参数
        weapon_id = 1001
    })
end)```

### Role.set_archive_by_type

**描述:** 设置存档值

```lua
Role.set_archive_by_type(_archive_type, _key, _val)

参数列表:

参数	类型	说明
_archive_type	ArchiveType	存档类型
_key	Archive	存档
_val	ETypeMeta	存档值

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local archive = 1  -- Archive 是存档编号（integer）
    role.set_archive_by_type(Enums.ArchiveType.Int, archive, archive)
end)```

### Role.set_archive_sheetid

**描述:** 设置表格存档

```lua
Role.set_archive_sheetid(_key, _val)

参数列表:

参数	类型	说明
_key	Archive	存档
_val	SheetID	表格id

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local archive = 1  -- Archive 是存档编号（integer）
    local sheet = GameAPI.create_sheet()
    if not sheet then return end
    role.set_archive_sheetid(archive, sheet)
end)```

### Role.set_camera_bind_mode

**描述:** 设置玩家相机的模式

```lua
Role.set_camera_bind_mode(_mode)

参数列表:

参数	类型	说明
_mode	CameraBindMode	模式

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    role.set_camera_bind_mode(Enums.CameraBindMode.DEFAULT)
end)```

### Role.set_camera_draggable

**描述:** 设置玩家相机是否可拖动

```lua
Role.set_camera_draggable(_draggable)

参数列表:

参数	类型	说明
_draggable	Bool	可拖动

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    role.set_camera_draggable(true)
end)```

### Role.set_camera_gyroscope_control_enabled

**描述:** 设置玩家陀螺仪控制镜头

```lua
Role.set_camera_gyroscope_control_enabled(_is_control)

参数列表:

参数	类型	说明
_is_control	Bool	陀螺仪控制

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    role.set_camera_gyroscope_control_enabled(true)
end)```

### Role.set_camera_lock_position

**描述:** 设置玩家相机的绑定坐标

```lua
Role.set_camera_lock_position(_pos)

参数列表:

参数	类型	说明
_pos	Point3	点

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    role.set_camera_lock_position(math.Vector3(0, 0, 0))
end)```

### Role.set_camera_projection_type

**描述:** 设置玩家相机的投影类型

```lua
Role.set_camera_projection_type(_projection_type)

参数列表:

参数	类型	说明
_projection_type	CameraProjectionType	投影类型

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    role.set_camera_projection_type(Enums.CameraProjectionType.PERSPECTIVE)
end)```

### Role.set_camera_property

**描述:** 设置玩家相机的属性

```lua
Role.set_camera_property(_property, _value)

参数列表:

参数	类型	说明
_property	CameraPropertyType	属性
_value	Fixed	值

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    role.set_camera_property(Enums.CameraPropertyType.TRACK_MODE_PITCH, 1.0)
end)```

### Role.set_camera_rotation_by_direction

**描述:** 设置玩家相机面向指定朝向

```lua
Role.set_camera_rotation_by_direction(_target_dir, _duration)

参数列表:

参数	类型	说明
_target_dir	Vector3	目标方向
_duration	Fixed	用时

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    role.set_camera_rotation_by_direction(math.Vector3(0, 0, 0), 1.0)
end)```

### Role.set_image_texture_with_auto_resize

**描述:** 设置UI图片节点图片

```lua
Role.set_image_texture_with_auto_resize(_image, _image_path, _reset_size)

参数列表:

参数	类型	说明
_image	EImage	UI图片节点
_image_path	Str	图片
_reset_size	Bool	是否重置大小

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local img_node = LuaAPI.query_ui_node("img_node")  -- img_node 节点需在 UI 中配置
    if not img_node then return end
    role.set_image_texture_with_auto_resize(img_node, "res/path", true)
end)```

### Role.show_tips

**描述:** 玩家显示飘字信息

```lua
Role.show_tips(_content, _duration)

参数列表:

参数	类型	说明
_content	Str	字符串
_duration	Fixed	时长

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    role.show_tips("示例内容", 1.0)
end)```

### Role.stop_montage

**描述:** 结束指定剧情动画

```lua
Role.stop_montage(_montage_key, _has_black_screen)

参数列表:

参数	类型	说明
_montage_key	MontageKey	剧情动画编号
_has_black_screen	Bool	是否有跳过黑幕

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    role.stop_montage("260001", true)
end)```

### Role.win

**描述:** 玩家胜利

```lua
Role.win()

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    if not unit then return end
    role.win()
end)```

### RollComp.get_roll_cooldown

**描述:** 获取滚动冷却时间

```lua
RollComp.get_roll_cooldown()

返回值:

• 类型: Fixed
• 说明: 冷却时间

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = unit.get_roll_cooldown()
end)```

### RollComp.set_roll_cooldown

**描述:** 设置滚动冷却时间

```lua
RollComp.set_roll_cooldown(_time)

参数列表:

参数	类型	说明
_time	Fixed	时间

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    unit.set_roll_cooldown(1.0)
end)```

### RushComp.get_rush_cooldown

**描述:** 获取飞扑冷却时间

```lua
RushComp.get_rush_cooldown()

返回值:

• 类型: Fixed
• 说明: 冷却时间

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local result = unit.get_rush_cooldown()
end)```

### RushComp.set_rush_cooldown

**描述:** 设置飞扑冷却时间

```lua
RushComp.set_rush_cooldown(_time)

参数列表:

参数	类型	说明
_time	Fixed	时间

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    unit.set_rush_cooldown(1.0)
end)```

### TriggerSystem.has_timer

**描述:** 判断计时器是否存在

```lua
TriggerSystem.has_timer(_timer)

参数列表:

参数	类型	说明
_timer	Timer	计时器

返回值:

• 类型: Bool
• 说明: 是否存在

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    local timer = nil  -- Timer 对象需由引擎事件回调提供
    local result = TriggerSystem.has_timer(timer)
end)```

### Unit.apply_force_at_local_point

**描述:** 对单位施加外力（局部坐标）

```lua
Unit.apply_force_at_local_point(_force, _local_point)

参数列表:

参数	类型	说明
_force	Vector3	力
_local_point	Point3	局部坐标点

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    unit.apply_force_at_local_point(math.Vector3(0, 0, 0), math.Vector3(0, 0, 0))
end)```

### Unit.apply_force_at_world_point

**描述:** 对单位施加外力（世界坐标）

```lua
Unit.apply_force_at_world_point(_force, _world_point)

参数列表:

参数	类型	说明
_force	Vector3	力
_world_point	Point3	世界坐标点

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    unit.apply_force_at_world_point(math.Vector3(0, 0, 0), math.Vector3(0, 0, 0))
end)```

### Unit.apply_torque

**描述:** 对单位施加扭矩

```lua
Unit.apply_torque(_torque)

参数列表:

参数	类型	说明
_torque	Vector3	扭矩

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    unit.apply_torque(math.Vector3(0, 0, 0))
end)```

### Unit.disable_unit_ccd

**描述:** 关闭单位CCD

```lua
Unit.disable_unit_ccd()

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    unit.disable_unit_ccd()
end)```

### Unit.enable_unit_ccd

**描述:** 开启单位CCD

```lua
Unit.enable_unit_ccd()

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    unit.enable_unit_ccd()
end)```

### Unit.get_camp

**描述:** 获取单位所属阵营

```lua
Unit.get_camp()

返回值:

• 类型: Camp
• 说明: 阵营

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local result = unit.get_camp()
end)```

### Unit.get_camp_id

**描述:** 获取单位所属阵营id

```lua
Unit.get_camp_id()

返回值:

• 类型: CampID
• 说明: 阵营ID

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local result = unit.get_camp_id()
end)```

### Unit.get_child_by_name

**描述:** 根据单位编号获取子组件

```lua
Unit.get_child_by_name(_name)

参数列表:

参数	类型	说明
_name	Str	子单位名称

返回值:

• 类型: Unit
• 说明: 单位

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local result = unit.get_child_by_name("平凡蛋0")
end)```

### Unit.get_current_mass

**描述:** 获取当前质量

```lua
Unit.get_current_mass()

返回值:

• 类型: Fixed
• 说明: 质量

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local result = unit.get_current_mass()
end)```

### Unit.get_current_mass_center

**描述:** 获取当前质心位置（局部坐标）

```lua
Unit.get_current_mass_center()

返回值:

• 类型: Vector3
• 说明: 质心位置

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local result = unit.get_current_mass_center()
end)```

### Unit.get_role

**描述:** 获取单位所属玩家

```lua
Unit.get_role()

返回值:

• 类型: Role
• 说明: 所属玩家

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local result = unit.get_role()
end)```

### Unit.get_role_id

**描述:** 获取单位所属玩家ID

```lua
Unit.get_role_id()

返回值:

• 类型: RoleID
• 说明: 玩家ID

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local result = unit.get_role_id()
end)```

### Unit.is_creature

**描述:** 是否为生物

```lua
Unit.is_creature()

返回值:

• 类型: Bool
• 说明: 是否为生物

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local result = unit.is_creature()
end)```

### Unit.is_dynamic_body

**描述:** 是受力物体

```lua
Unit.is_dynamic_body()

返回值:

• 类型: Bool
• 说明: 是否受力物体

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local result = unit.is_dynamic_body()
end)```

### Unit.is_kinematic_body

**描述:** 是动力学物体

```lua
Unit.is_kinematic_body()

返回值:

• 类型: Bool
• 说明: 是否动力学物体

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local result = unit.is_kinematic_body()
end)```

### Unit.is_static_body

**描述:** 是静态物体

```lua
Unit.is_static_body()

返回值:

• 类型: Bool
• 说明: 是否静态物体

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local result = unit.is_static_body()
end)```

### Unit.play_3d_sound

**描述:** 单位开始播放3d音效

```lua
Unit.play_3d_sound(_sound_key, _duration, _volume)

参数列表:

参数	类型	说明
_sound_key	SoundKey	声音编号
_duration	Fixed	持续时间
_volume	Fixed	音量

返回值:

• 类型: SoundID
• 说明: 音效ID

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    local result = unit.play_3d_sound(800001, 1.0, 1.0)
end)```

### Unit.set_acc_motor_init_velocity

**描述:** 设置加速运动初速度并重置

```lua
Unit.set_acc_motor_init_velocity(_index, _init_vel)

参数列表:

参数	类型	说明
_index	Int	索引
_init_vel	Vector3	初速度

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    unit.set_acc_motor_init_velocity(1, math.Vector3(0, 0, 0))
end)```

### Unit.set_aircraft_tick_handler

**描述:** 飞行器自定义

```lua
Unit.set_aircraft_tick_handler(_handler)

参数列表:

参数	类型	说明
_handler	Function	飞行核心函数

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    unit.set_aircraft_tick_handler(function() end)
end)```

### Unit.set_current_mass

**描述:** 设置当前质量

```lua
Unit.set_current_mass(_mass)

参数列表:

参数	类型	说明
_mass	Fixed	质量

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    unit.set_current_mass(1.0)
end)```

### Unit.set_current_mass_center

**描述:** 设置当前质心位置（局部坐标）

```lua
Unit.set_current_mass_center(_center)

参数列表:

参数	类型	说明
_center	Vector3	质心位置

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    unit.set_current_mass_center(math.Vector3(0, 0, 0))
end)```

### Unit.set_linear_motor_velocity

**描述:** 设置直线运动速度

```lua
Unit.set_linear_motor_velocity(_index, _vel, _is_local)

参数列表:

参数	类型	说明
_index	Int	索引
_vel	Vector3	线速度
_is_local	Bool	是否局部空间

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    unit.set_linear_motor_velocity(1, math.Vector3(0, 0, 0), true)
end)```

### Unit.set_orientation_smooth

**描述:** 设置单位旋转（带平滑）

```lua
Unit.set_orientation_smooth(_rot)

参数列表:

参数	类型	说明
_rot	Quaternion	旋转

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    unit.set_orientation_smooth(math.Quaternion(0, 0, 0))
end)```

### Unit.set_position_smooth

**描述:** 重置单位坐标（带平滑）

```lua
Unit.set_position_smooth(_pos)

参数列表:

参数	类型	说明
_pos	Vector3	坐标

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    unit.set_position_smooth(math.Vector3(0, 0, 0))
end)```

### Unit.set_world_scale

**描述:** 设置单位世界空间下的缩放

```lua
Unit.set_world_scale(_scale)

参数列表:

参数	类型	说明
_scale	Vector3	缩放

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    local unit = role.get_ctrl_unit()
    unit.set_world_scale(math.Vector3(0, 0, 0))
end)```

### UnitInteractVolumeComp.set_interact_button_text_by_index

**描述:** 设置单位互动按钮文本

```lua
UnitInteractVolumeComp.set_interact_button_text_by_index(_interact_index, _text)

参数列表:

参数	类型	说明
_interact_index	Int	互动索引
_text	Str	互动按钮文本

示例:

LuaAPI.global_register_trigger_event({ EVENT.GAME_INIT }, function()
    local role = GameAPI.get_all_valid_roles()[1]
    if not role then return end
    local unit = role.get_ctrl_unit()
    if not unit then return end
    unit.set_interact_button_text_by_index(1, "示例文本")
end)```

## EVENT

### ABILITY_BULLET_HIT
子弹命中

事件主体 Ability 技能

事件携带参数 ability Ability 触发事件的技能
事件携带参数 unit Unit 技能拥有者
事件携带参数 target_unit Unit 目标对象
事件携带参数 dmg Fixed 伤害值

### ABILITY_SWITCH_IN
技能切入

事件主体 Ability 技能

事件携带参数 ability Ability 触发事件的技能
事件携带参数 unit Unit 技能拥有者
事件携带参数 switch_out_ability Ability 切换前的技能

### ABILITY_SWITCH_OUT
技能切出

事件主体 Ability 技能

事件携带参数 ability Ability 触发事件的技能
事件携带参数 unit Unit 技能拥有者
事件携带参数 switch_in_ability Ability 切换后的技能

### ABILITY_ACCUMULATE_BEGIN
技能蓄力阶段开始

事件主体 Ability 技能

事件携带参数 ability Ability 触发事件的技能
事件携带参数 unit Unit 技能拥有者

### ABILITY_ACCUMULATE_INTERRUPT
技能蓄力阶段被打断

事件主体 Ability 技能

事件携带参数 ability Ability 触发事件的技能
事件携带参数 unit Unit 技能拥有者

### ABILITY_ACCUMULATE_END
技能蓄力阶段结束

事件主体 Ability 技能

事件携带参数 ability Ability 触发事件的技能
事件携带参数 unit Unit 技能拥有者

### ABILITY_CAST_BEGIN
技能施法阶段开始

事件主体 Ability 技能

事件携带参数 ability Ability 触发事件的技能
事件携带参数 unit Unit 技能拥有者

### ABILITY_CAST_BREAK
技能施法阶段被打断

事件主体 Ability 技能

事件携带参数 ability Ability 触发事件的技能
事件携带参数 unit Unit 技能拥有者

### ABILITY_CAST_END
技能施法阶段结束

事件主体 Ability 技能

事件携带参数 ability Ability 触发事件的技能
事件携带参数 unit Unit 技能拥有者

### ABILITY_CD_END
技能冷却完成

事件主体 Ability 技能

事件携带参数 ability Ability 触发技能
事件携带参数 unit Unit 技能拥有者

### ABILITY_CHARGE_END
技能充能完成

事件主体 Ability 技能

事件携带参数 ability Ability 触发技能
事件携带参数 unit Unit 技能拥有者

### ABILITY_DOWNGRADE
技能降级

事件主体 Ability 技能

事件携带参数 ability Ability 触发事件的技能

### ABILITY_REMOVE
失去技能

事件主体 Ability 技能

事件携带参数 ability Ability 触发事件的技能
事件携带参数 unit Unit 技能拥有者

### ABILITY_ADD
获得技能

事件主体 Ability 技能

事件携带参数 ability Ability 触发事件的技能
事件携带参数 unit Unit 技能拥有者

### ABILITY_UPGRADE
技能升级

事件主体 Ability 技能

事件携带参数 ability Ability 触发事件的技能
事件携带参数 unit Unit 技能拥有者

### ANY_CAMP_SCORE_UPDATE
阵营积分变化

事件主体 Global 全局触发器

事件携带参数 camp Camp 触发阵营
事件携带参数 old_camp_score Int 得分前积分
事件携带参数 new_camp_score Int 得分后积分

### ANY_CUSTOMTRIGGERSPACE_CREATE
任意触发区域创建

事件主体 Global 全局触发器

事件携带参数 unit CustomTriggerSpace 被创建的触发区域

### ANY_CUSTOMTRIGGERSPACE_DESTROY
任意触发区域销毁

事件主体 Global 全局触发器

事件携带参数 unit CustomTriggerSpace 被销毁的触发区域

### ANY_EQUIPMENT_CHANGE_SLOT
任意物品位置发生变化

事件主体 Global 全局触发器

事件携带参数 equipment Equipment 触发事件的物品
事件携带参数 owner LifeEntity 持有者
事件携带参数 old_slot_type EquipmentSlotType 旧槽位类型
事件携带参数 old_index Int 旧槽位索引
事件携带参数 new_slot_type EquipmentSlotType 新槽位类型
事件携带参数 new_index Int 新槽位索引

### ANY_EQUIPMENT_TRIGGER_SPACE
任意物品进出区域事件

事件主体 Global 全局触发器

注册参数 trigger_event_type TriggerSpaceEventType 触发类型
注册参数 customtriggerspace_id CustomTriggerSpaceID 触发区域ID

事件携带参数 event_unit Equipment 触发物品
事件携带参数 event_unit_id EquipmentID TRIGGER_EQUIPMENT_ID
事件携带参数 trigger_event_type TriggerSpaceEventType 触发类型
事件携带参数 trigger_zone_id CustomTriggerSpaceID 触发区域ID
事件携带参数 trigger_zone CustomTriggerSpace 事件触发区域

### ANY_LIFEENTITY_TRIGGER_SPACE
任意生命体进出区域事件

事件主体 Global 全局触发器

注册参数 trigger_event_type TriggerSpaceEventType 触发类型
注册参数 trigger_zone_id CustomTriggerSpaceID 触发区域ID

事件携带参数 event_unit LifeEntity 触发角色/生物
事件携带参数 event_unit_id UnitID 触发角色/生物ID
事件携带参数 trigger_event_type TriggerSpaceEventType 触发类型
事件携带参数 trigger_zone_id CustomTriggerSpaceID 触发区域ID
事件携带参数 trigger_zone CustomTriggerSpace 事件触发区域

### ANY_OBSTACLE_CREATE
任意组件创建

事件主体 Global 全局触发器

事件携带参数 unit Obstacle 被创建的组件

### ANY_OBSTACLE_DESTROY
任意组件销毁

事件主体 Global 全局触发器

事件携带参数 unit Obstacle 被销毁的组件

### ANY_OBSTACLE_LIFTED_BEGAN
任意组件被举起

事件主体 Global 全局触发器

事件携带参数 lift_unit Unit 抓举者
事件携带参数 lifted_unit Obstacle 被抓举者

### ANY_OBSTACLE_LIFTED_ENDED
任意组件被放下

事件主体 Global 全局触发器

事件携带参数 lift_unit Unit 抓举者
事件携带参数 lifted_unit Obstacle 被抓举者

### ANY_OBSTACLE_TRIGGER_SPACE
任意组件进出触发区域

事件主体 Global 全局触发器

注册参数 trigger_event_type TriggerSpaceEventType 触发类型
注册参数 trigger_zone_id CustomTriggerSpaceID 触发区域ID

事件携带参数 event_unit Obstacle 触发组件
事件携带参数 event_unit_id ObstacleID 触发组件ID
事件携带参数 trigger_event_type TriggerSpaceEventType 触发类型
事件携带参数 trigger_zone_id CustomTriggerSpaceID 触发区域ID
事件携带参数 trigger_zone CustomTriggerSpace 事件触发区域

### ANY_ROLE_SCORE_UPDATE
玩家积分变化

事件主体 Global 全局触发器

事件携带参数 role Role 触发玩家
事件携带参数 old_role_score Int 得分前积分
事件携带参数 new_role_score Int 得分后积分

### ANY_TRIGGERSPACE_CREATE
任意逻辑体创建

事件主体 Global 全局触发器

事件携带参数 unit TriggerSpace 被创建的逻辑体

### ANY_TRIGGERSPACE_DESTROY
任意逻辑体销毁

事件主体 Global 全局触发器

事件携带参数 unit TriggerSpace 被销毁的逻辑体

### CUSTOM_EVENT
自定义事件

事件主体 Default 多类型

注册参数 name Str 自定义事件

### ENV_TIME_REACHED
环境时间到达指定时刻

事件主体 Global 全局触发器

注册参数 target_time Fixed TARGET_MAP_TIME

### GAME_END
游戏结束

事件主体 Global 全局触发器

### GAME_INIT
游戏初始化

事件主体 Global 全局触发器

### LEVEL_BEGIN
进入关卡

事件主体 Default 多类型

事件携带参数 level_key LevelKey 当前关卡

### LEVEL_END
离开关卡

事件主体 Default 多类型

事件携带参数 level_key LevelKey 当前关卡

### MODIFIER_OBTAIN
获得效果

事件主体 Modifier 效果

事件携带参数 from_unit_id UnitID 效果来源单位ID
事件携带参数 modifier Modifier 触发效果
事件携带参数 unit Unit 效果拥有者

### MODIFIER_REOBTAIN
覆盖效果

事件主体 Modifier 效果

事件携带参数 modifier Modifier 触发效果
事件携带参数 unit Unit 效果拥有者

### MODIFIER_STACK_COUNT_CHANGE
效果层数变化

事件主体 Modifier 效果

事件携带参数 stack_count_change Int 变化层数
事件携带参数 modifier Modifier 触发效果
事件携带参数 unit Unit 效果拥有者

### ON_MONTAGE_BEGIN
剧情动画开始播放事件

事件主体 Default 多类型

事件携带参数 play_role Role PLAY_MONTAGE_ROLE
事件携带参数 montage_id MontageKey 触发的剧情动画

### ON_MONTAGE_END
剧情动画结束播放事件

事件主体 Default 多类型

事件携带参数 play_role Role PLAY_MONTAGE_ROLE
事件携带参数 montage_id MontageKey 触发的剧情动画

### ON_PLAYER_TAKE_PHOTO
玩家拍照

事件主体 Global 全局触发器

事件携带参数 role Role 触发玩家

### REPEAT_TIMEOUT
周期性计时器超时

事件主体 Default 多类型

注册参数 delay Fixed 延时

### ON_SKY_ENV_CHANGE
天空环境变化

事件主体 Global 全局触发器

### SPEC_CHARACTER_SELECT_EQUIPMENT_SLOT
指定角色选中物品格

事件主体 Character 角色

注册参数 event_unit Character 触发角色
注册参数 slot_type EquipmentSlotType 物品格类型
注册参数 slot_index Int EQUIPMENT_SLOT_INDEX

事件携带参数 event_unit Character 触发角色

### SPEC_COMMODITY_BRING_INTO_GAME
指定UGC物品被带入游戏

事件主体 Default 多类型

注册参数 commodity_id UgcCommodity SPEC_UGC_COMMODITY

事件携带参数 camp_role_owner Role 携带道具的玩家

### SPEC_COMMODITY_PURCHASE
指定UGC物品购买事件

事件主体 Default 多类型

注册参数 commodity_id UgcCommodity SPEC_UGC_COMMODITY

事件携带参数 commodity_id UgcCommodity SPEC_UGC_COMMODITY
事件携带参数 purchase_role Role 购买道具的玩家

### SPEC_LIFEENTITY_INTERACTED
指定生物互动按钮被按下

事件主体 Creature 生物

事件携带参数 interact_lifeentity LifeEntity 互动触发者
事件携带参数 interact_unit Creature 互动目标
事件携带参数 interact_id InteractBtnID 互动按钮

### SPEC_CUSTOMTRIGGERSPACE_DESTROY
指定触发区域销毁

事件主体 CustomTriggerSpace 触发区域

### SPEC_EQUIPMENT_CHANGE_SLOT
指定物品位置发生变化

事件主体 Equipment 物品

事件携带参数 equipment Equipment 当前物品
事件携带参数 owner LifeEntity 持有者
事件携带参数 old_slot_type EquipmentSlotType 旧槽位类型
事件携带参数 old_index Int 旧槽位索引
事件携带参数 new_slot_type EquipmentSlotType 新槽位类型
事件携带参数 new_index Int 新槽位索引

### SPEC_EQUIPMENT_DESTROY
指定物品销毁事件

事件主体 Equipment 物品

事件携带参数 equipment Equipment 当前物品

### SPEC_EQUIPMENT_ENTER_CHAR_SLOT
指定物品进入角色栏位

事件主体 Equipment 物品

注册参数 equipment Equipment 当前物品
注册参数 slot_type EquipmentSlotType 物品格类型

事件携带参数 equipment Equipment 当前物品
事件携带参数 slot_type EquipmentSlotType 物品格类型
事件携带参数 owner Character 触发事件的角色

### SPEC_EQUIPMENT_LEAVE_CHAR_SLOT
指定物品离开角色栏位

事件主体 Equipment 物品

注册参数 equipment Equipment 当前物品
注册参数 slot_type EquipmentSlotType 物品格类型

事件携带参数 equipment Equipment 当前物品
事件携带参数 slot_type EquipmentSlotType 物品格类型
事件携带参数 owner Character 触发事件的角色

### SPEC_EQUIPMENT_LOST
指定物品被失去

事件主体 Equipment 物品

事件携带参数 equipment Equipment 当前物品
事件携带参数 owner LifeEntity 持有者
事件携带参数 slot_type EquipmentSlotType 物品槽位类型
事件携带参数 slot_index Int 物品槽位索引

### SPEC_EQUIPMENT_OBTAIN
指定物品被获得

事件主体 Equipment 物品

事件携带参数 equipment Equipment 当前物品
事件携带参数 owner LifeEntity 持有者
事件携带参数 count Int 获得数量

### SPEC_EQUIPMENT_SELECT
指定物品被选中

事件主体 Equipment 物品

事件携带参数 equipment Equipment 当前物品

### SPEC_EQUIPMENT_STACK_NUM_CHANGE
指定物品堆叠层数变化

事件主体 Equipment 物品

事件携带参数 equipment Equipment 当前物品
事件携带参数 variation Int 变化层数

### SPEC_EQUIPMENT_SWAP_SLOT
指定物品发生位置交换

事件主体 Equipment 物品

事件携带参数 equipment Equipment 当前物品

### SPEC_EQUIPMENT_UNSELECT
指定物品被取消选中

事件主体 Equipment 物品

事件携带参数 equipment Equipment 当前物品

### SPEC_EQUIPMENT_USE
指定物品被使用

事件主体 Equipment 物品

事件携带参数 equipment Equipment 当前物品

### SPEC_LIFEENTITY_ABILITY_DOWNGRADE
指定生命体技能降级

事件主体 LifeEntity 生命体

事件携带参数 unit LifeEntity 技能拥有者
事件携带参数 ability Ability 触发技能

### SPEC_LIFEENTITY_ABILITY_OBTAIN
指定生命体获得技能

事件主体 LifeEntity 生命体

事件携带参数 unit LifeEntity 技能拥有者
事件携带参数 ability Ability 触发技能

### SPEC_LIFEENTITY_ABILITY_REMOVE
指定生命体失去技能

事件主体 LifeEntity 生命体

事件携带参数 unit LifeEntity 技能拥有者
事件携带参数 ability Ability 触发技能

### SPEC_LIFEENTITY_ABILITY_UPGRADE
指定生命体技能升级

事件主体 LifeEntity 生命体

事件携带参数 unit LifeEntity 技能拥有者
事件携带参数 ability Ability 触发技能

### SPEC_LIFEENTITY_CHANGE_PREFAB_AFTER
指定生命体切换预设后

事件主体 LifeEntity 生命体

事件携带参数 unit LifeEntity 切换预设的角色/生物

### SPEC_LIFEENTITY_CHANGE_PREFAB_BEFORE
指定生命体切换预设前

事件主体 LifeEntity 生命体

事件携带参数 unit LifeEntity 切换预设的角色/生物

### SPEC_LIFEENTITY_CONTACT_BEGIN
指定生命体发生碰撞开始

事件主体 LifeEntity 生命体

事件携带参数 unit1 LifeEntity 碰撞者
事件携带参数 unit2 Unit 被碰撞者

### SPEC_LIFEENTITY_CONTACT_END
指定生命体发生碰撞结束

事件主体 LifeEntity 生命体

事件携带参数 unit1 LifeEntity 碰撞者
事件携带参数 unit2 Unit 被碰撞者

### SPEC_LIFEENTITY_DEFEAT
指定生命体击败其他生命体

事件主体 LifeEntity 生命体

事件携带参数 dmg_unit LifeEntity 伤害来源
事件携带参数 die_unit LifeEntity 被击败者

### SPEC_LIFEENTITY_DESTROY
指定生命体被销毁

事件主体 LifeEntity 生命体

### SPEC_LIFEENTITY_DIE
指定生命体被击败

事件主体 LifeEntity 生命体

事件携带参数 die_unit LifeEntity 被击败者
事件携带参数 dmg_unit LifeEntity 伤害来源

### SPEC_LIFEENTITY_DIE_BEFORE
指定生命体被击败前

事件主体 LifeEntity 生命体

事件携带参数 unit LifeEntity 被击败者
事件携带参数 dmg_unit Unit 伤害来源

### SPEC_LIFEENTITY_DMGED_AFTER
指定生命体受到伤害后

事件主体 LifeEntity 生命体

事件携带参数 _dmg_schema DamageSchema DAMAGE_TYPE
事件携带参数 _src Unit 伤害来源
事件携带参数 _dst LifeEntity 伤害目标
事件携带参数 _dmg Damage DAMAGE_OBJ

### SPEC_LIFEENTITY_DMGED_BEFORE
指定生命体受到伤害前

事件主体 LifeEntity 生命体

事件携带参数 _dmg_schema DamageSchema DAMAGE_TYPE
事件携带参数 _src Unit 伤害来源
事件携带参数 _dst LifeEntity 伤害目标
事件携带参数 _dmg Damage DAMAGE_OBJ

### SPEC_LIFEENTITY_DMG_AFTER
指定生命体造成伤害后

事件主体 LifeEntity 生命体

事件携带参数 _dmg_schema DamageSchema DAMAGE_TYPE
事件携带参数 _src LifeEntity 伤害来源
事件携带参数 _dst LifeEntity 伤害目标
事件携带参数 _dmg Damage DAMAGE_OBJ

### SPEC_LIFEENTITY_DMG_BEFORE
指定生命体造成伤害前

事件主体 LifeEntity 生命体

事件携带参数 _dmg_schema DamageSchema DAMAGE_TYPE
事件携带参数 _src LifeEntity 伤害来源
事件携带参数 _dst LifeEntity 伤害目标
事件携带参数 _dmg Damage DAMAGE_OBJ

### SPEC_LIFEENTITY_ENTER_VEHICLE
指定生命体上载具

事件主体 LifeEntity 生命体

事件携带参数 unit LifeEntity 触发角色/生物

### SPEC_LIFEENTITY_EQUIPMENT_SLOT_CHANGE
指定生命体持有物品槽位发生变化

事件主体 LifeEntity 生命体

事件携带参数 equipment Equipment 触发物品
事件携带参数 old_slot_type EquipmentSlotType 旧槽位类型
事件携带参数 old_index Int 旧槽位索引
事件携带参数 new_slot_type EquipmentSlotType 新槽位类型
事件携带参数 new_index Int 新槽位索引

### SPEC_LIFEENTITY_EXIT_VEHICLE
指定生命体下载具

事件主体 LifeEntity 生命体

事件携带参数 unit LifeEntity 触发角色/生物

### SPEC_LIFEENTITY_GAIN_EXP
生命体获得经验

事件主体 LifeEntity 生命体

事件携带参数 unit LifeEntity 获得者
事件携带参数 exp Fixed 经验值

### SPEC_LIFEENTITY_GET_ITEMBOX
指定生命体获得道具箱

事件主体 LifeEntity 生命体

事件携带参数 life_entity LifeEntity 获得道具的角色/生物

### SPEC_LIFEENTITY_JUMP
指定生命体跳跃

事件主体 LifeEntity 生命体

事件携带参数 unit LifeEntity 跳跃者

### SPEC_LIFEENTITY_LEVEL_UP
生命体升级

事件主体 LifeEntity 生命体

事件携带参数 unit LifeEntity 获得者
事件携带参数 level Int 当前等级

### SPEC_LIFEENTITY_LIFTED_BEGIN
指定生命体被其他单位举起

事件主体 LifeEntity 生命体

事件携带参数 lift_unit Unit 抓举者
事件携带参数 lifted_unit LifeEntity 被抓举者

### SPEC_LIFEENTITY_LIFTED_END
指定生命体被其他单位放下

事件主体 LifeEntity 生命体

事件携带参数 lift_unit Unit 抓举者
事件携带参数 lifted_unit LifeEntity 被抓举者

### SPEC_LIFEENTITY_LIFT_BEGIN
指定生命体举起其他单位

事件主体 LifeEntity 生命体

事件携带参数 lift_unit LifeEntity 抓举者
事件携带参数 lifted_unit Unit 被抓举者

### SPEC_LIFEENTITY_LIFT_END
指定生命体放下其他单位

事件主体 LifeEntity 生命体

事件携带参数 lift_unit LifeEntity 抓举者
事件携带参数 lifted_unit Unit 被抓举者

### SPEC_LIFEENTITY_MOVE_BEGIN
指定生命体移动开始

事件主体 LifeEntity 生命体

事件携带参数 unit LifeEntity 获得者

### SPEC_LIFEENTITY_MOVE_END
指定生命体移动结束

事件主体 LifeEntity 生命体

事件携带参数 unit LifeEntity 获得者

### SPEC_LIFEENTITY_REBORN
指定生命体复活

事件主体 LifeEntity 生命体

事件携带参数 unit LifeEntity 复活者

### SPEC_LIFEENTITY_RELEASE_ABILITY
指定生命体释放技能

事件主体 LifeEntity 生命体

事件携带参数 unit LifeEntity 触发角色/生物
事件携带参数 ability Ability 触发事件的技能

### SPEC_LIFEENTITY_ROLL_BEGIN
指定生命体滚动开始

事件主体 LifeEntity 生命体

事件携带参数 unit LifeEntity 滚动者

### SPEC_LIFEENTITY_ROLL_END
指定生命体滚动结束

事件主体 LifeEntity 生命体

事件携带参数 unit LifeEntity 滚动者

### SPEC_LIFEENTITY_RUSH
指定生命体前扑

事件主体 LifeEntity 生命体

事件携带参数 unit LifeEntity 前扑者
事件携带参数 dir Vector3 前扑方向

### SPEC_LIFEENTITY_START_LIFT
指定生命体抓举

事件主体 LifeEntity 生命体

事件携带参数 unit LifeEntity 抓举者
事件携带参数 dir Vector3 抓举方向

### MODIFIER_LOSS
失去效果

事件主体 Modifier 效果

事件携带参数 modifier Modifier 触发效果
事件携带参数 unit Unit 效果拥有者

### SPEC_OBSTACLE_LIFTED_BEGAN
指定组件发生碰撞开始

事件主体 Obstacle 组件

事件携带参数 unit1 Obstacle 碰撞者
事件携带参数 unit2 Unit 被碰撞者
事件携带参数 contact_pos Vector3 碰撞位置

### SPEC_OBSTACLE_CONTACT_END
指定组件发生碰撞结束

事件主体 Obstacle 组件

事件携带参数 unit1 Obstacle 碰撞者
事件携带参数 unit2 Unit 被碰撞者

### SPEC_OBSTACLE_DESTROY
指定组件销毁

事件主体 Obstacle 组件

### SPEC_OBSTACLE_INTERACTED
指定组件互动按钮被按下

事件主体 Obstacle 组件

事件携带参数 interact_lifeentity LifeEntity 互动触发者
事件携带参数 interact_unit Obstacle 互动目标
事件携带参数 interact_id InteractBtnID 互动按钮

### SPEC_OBSTACLE_LIFTED_BEGIN
指定组件被举起

事件主体 Obstacle 组件

事件携带参数 lift_unit Unit 抓举者
事件携带参数 lifted_unit Obstacle 被抓举者

### SPEC_OBSTACLE_LIFTED_ENDED
指定组件被放下

事件主体 Obstacle 组件

事件携带参数 lift_unit Unit 抓举者
事件携带参数 lifted_unit Obstacle 被抓举者

### SPEC_OBSTACLE_ON_DAMAGED
指定组件受到伤害

事件主体 Obstacle 组件

事件携带参数 src Unit 伤害来源
事件携带参数 src_ability Ability 来源技能
事件携带参数 damage Fixed 伤害值

### SPEC_OBSTACLE_TOUCH_BEGIN
指定组件被点击开始

事件主体 Obstacle 组件

事件携带参数 touch_unit Role TOUCH_ROLE
事件携带参数 touched_unit Obstacle 被点击的物体
事件携带参数 touch_pos Vector3 TOUCH_START_POS

### SPEC_OBSTACLE_TOUCH_END
指定组件被点击结束

事件主体 Obstacle 组件

事件携带参数 touch_unit Role TOUCH_ROLE
事件携带参数 touched_unit Obstacle 被点击的物体
事件携带参数 touch_pos Vector3 松开位置

### SPEC_ROLE_ACHIEVEMENT_COMPLETE
指定玩家完成自定义成就

事件主体 Global 全局触发器

注册参数 role RoleID 目标玩家

事件携带参数 role Role 目标玩家
事件携带参数 achieve_id Achievement TARGET_ACHIEVE

### SPEC_ROLE_ACHIEVEMENT_REWARD_GAIN
指定玩家领取成就奖励

事件主体 Global 全局触发器

注册参数 role RoleID 目标玩家
注册参数 achievement Achievement TARGET_ACHIEVE

事件携带参数 role Role 目标玩家
事件携带参数 achieve_id Achievement TARGET_ACHIEVE

### SPEC_ROLE_CAMP_CHANGE
指定玩家阵营发生变化

事件主体 Global 全局触发器

注册参数 role RoleID 目标玩家

事件携带参数 role Role 目标玩家
事件携带参数 camp_before_change Camp 变化前的阵营
事件携带参数 camp_after_change Camp 变化后的阵营

### SPEC_ROLE_EXIT_GAME
指定玩家离开游戏

事件主体 Global 全局触发器

注册参数 role Role 目标玩家

事件携带参数 role Role 目标玩家

### SPEC_ROLE_GAME_LOSE
指定玩家游戏失败

事件主体 Global 全局触发器

注册参数 role RoleID 目标玩家

事件携带参数 role Role 目标玩家

### SPEC_ROLE_GAME_WIN
指定玩家游戏胜利

事件主体 Global 全局触发器

注册参数 role RoleID 目标玩家

事件携带参数 role Role 目标玩家

### SPEC_ROLE_PURCHASE_GOODS
指定玩家成功购买商品

事件主体 Global 全局触发器

注册参数 role Role 目标玩家

事件携带参数 role Role 目标玩家
事件携带参数 goods_id UgcGoods TARGET_GOODS

### SPEC_ROLE_VOICE_VOLUME_CHANGE
语音音量变化事件

事件主体 Default 多类型

注册参数 role Role 目标玩家

事件携带参数 voice_volume Fixed ECA_PARA_VOICE_VOLUME

### SPEC_TRIGGERSPACE_DESTROY
指定逻辑体销毁

事件主体 TriggerSpace 逻辑体

### SPEC_COMMODITY_CONSUME
指定UGC物品消费事件

事件主体 Default 多类型

注册参数 commodity_id UgcCommodity SPEC_UGC_COMMODITY

事件携带参数 commodity_id UgcCommodity SPEC_UGC_COMMODITY
事件携带参数 consume_num Int 使用道具的数量
事件携带参数 consume_role Role 使用道具的玩家

### TIMEOUT
计时器超时

事件主体 Default 多类型

注册参数 delay Fixed 延时

### UI_CUSTOM_EVENT
UI自定义事件(附带玩家)

事件主体 Default 多类型

注册参数 name Str 自定义事件

事件携带参数 role_id RoleID 触发事件的玩家ID
事件携带参数 role Role 触发事件的玩家
事件携带参数 eui_node_id ENode 触发事件的界面控件

### TRACK_BULLET_HIT
追踪弹道命中

事件主体 Default 多类型

注册参数 tag Str TAG

事件携带参数 target_unit Unit 追踪目标
事件携带参数 from_unit Unit 子弹来源

### TRACK_BULLET_REACH_POSITION
追踪弹道到达目标点

事件主体 Default 多类型

注册参数 tag Str TAG

事件携带参数 target_point Vector3 到达目标
事件携带参数 from_unit Unit 子弹来源