API指引
本手册将 API 按功能系统进行划分,每个系统下再细分其相关的类型、枚举和 API,便于查阅和理解。
1. 单位与对象系统
相关类型
Unit(单位)、UnitID、UnitKey、UnitTypeLifeEntity(生命体)、Creature(生物)、Character(角色)、Obstacle(组件)、Equipment(物品)、Modifier(效果)- 相关列表类型如
ListUnit、ListLifeEntity、ListCreature、ListCharacter、ListObstacle、ListEquipment、ListModifier等
相关枚举
UnitType单位类型RigidBodyType物理类型BuffState状态EquipmentType物品类型EquipmentSlotType物品槽位类型MoveModeAI移动模式PatrolTypeAI巡逻类型
主要API
- 单位创建与销毁
GameAPI.create_unit_with_scale(_u_key, _pos, _rotation, _scale):创建单位,支持自定义缩放。GameAPI.destroy_unit(_unit):销毁指定单位。GameAPI.create_creature、GameAPI.create_life_entity、GameAPI.create_obstacle:分别创建生物、生命体、组件。
- 单位属性与状态
Unit.get_position()/Unit.set_position(_pos):获取/设置单位坐标。Unit.get_orientation()/Unit.set_orientation(_rot):获取/设置单位旋转。Unit.get_linear_velocity()/Unit.set_linear_velocity(_vel):获取/设置线速度。Unit.get_rigid_body_type():获取物理类型(静态/动力学/受力)。Unit.get_unit_type():获取单位类型(生物/角色/组件等)。
- 单位层级与子组件
Unit.add_child(_unit):添加子单位。Unit.get_children():获取所有子单位。LuaAPI.get_component_list(_obj):获取单位的子组件名称列表。
- 单位交互与物理
Unit.apply_force(_force):对单位施加力。Unit.apply_impact_force(_force, _max_speed, _force_lost_control, _lost_ctrl_time):施加冲击力并可设置击飞。Unit.enable_gravity()/Unit.disable_gravity():开启/关闭重力。Unit.enable_interact()/Unit.disable_interact():开启/关闭单位交互。
- 单位状态与属性管理
AttrComp.get_attr_by_type(_value_type, _key):获取单位属性。AttrComp.set_attr_by_type(_value_type, _key, _val):设置单位属性。BuffStateComp.add_state(_state_id)/BuffStateComp.remove_state(_state_id):添加/移除单位状态。
- 单位音效与特效
Unit.play_3d_sound(_sound_key, _duration, _volume):播放3D音效。Unit.play_emoji(_emoji_key):单位发送表情。Unit.show_bubble_msg(_show_msg, _show_time, _max_dis):显示气泡信息。
2. 技能与战斗系统
相关类型
Ability(技能)、AbilityKey、AbilitySlot- 技能相关列表类型如
ListAbility、ListAbilityKey、ListAbilitySlot
相关枚举
BuffState技能状态AbilitySlot技能槽位
主要API
- 技能释放与管理
Ability.begin_cast(_dir_info, _target_point, _target_unit):开始释放技能。Ability.break_cast()/Ability.break_accumulate():打断技能施法/蓄力。Ability.enter_cd():技能进入冷却。Ability.is_in_cd()/Ability.is_in_charge():判断技能是否在冷却/充能中。
- 技能属性与信息
Ability.get_name()/Ability.get_desc():获取技能名称/描述。Ability.get_cd_time()/Ability.get_left_cd_time():获取技能冷却时间/剩余冷却时间。Ability.get_accumulate_ratio():获取蓄力百分比。Ability.get_owner()/Ability.get_owner_character()/Ability.get_owner_creature():获取技能拥有者。
- 技能槽位与增删
AbilityComp.add_ability_to_slot(_ability_index, _ability_id, _kv_args, _kv_types):向槽位添加技能。AbilityComp.remove_ability(_ability_slot)/AbilityComp.remove_ability_by_key(_ability_key):移除技能。AbilityComp.get_abilities():获取单位所有技能。
- 技能与单位状态交互
Ability.add_state_to_target(_unit, _state_id)/Ability.remove_state_to_target(_unit, _state_id):技能为单位添加/移除状态。Ability.play_countdown_ui(_time):播放技能倒计时UI。
3. 触发与事件系统
相关类型
TriggerSpace(逻辑体)、CustomTriggerSpace(自定义触发区域)、TriggerSpaceKey、CustomTriggerSpaceKey- 相关列表类型如
ListTriggerSpace、ListCustomTriggerSpace
相关枚举
TriggerSpaceEventType触发区域类型
主要API
- 触发器注册与事件分发
LuaAPI.global_register_trigger_event(_event_desc, _callback):注册全局触发器。LuaAPI.unit_register_trigger_event(_unit, _event_desc, _callback):注册单位触发器。LuaAPI.global_send_custom_event(_event_name, _data)/LuaAPI.unit_send_custom_event(_unit, _event_name, _data):发送全局/单位自定义事件。LuaAPI.global_unregister_trigger_event(_id)/LuaAPI.unit_unregister_trigger_event(_unit, _id):注销触发器。
- 触发区域与逻辑体管理
GameAPI.create_triggerspace(_u_key, _pos, _rotation, _scale, _role):创建逻辑体。GameAPI.create_customtriggerspace(_u_key, _pos, _rotation, _scale, _role):创建自定义触发区域。CustomTriggerSpace.random_point():获取触发区域内的随机坐标。
- 事件类型
- 包含技能、单位、组件、生命体、物品、角色、全局等多种事件(如
ABILITY_CAST_BEGIN、ANY_OBSTACLE_CREATE、SPEC_LIFEENTITY_DIE等),支持自定义事件和UI事件。
- 包含技能、单位、组件、生命体、物品、角色、全局等多种事件(如
4. UI与交互系统
相关类型
EButton、EImage、ELabel、ENode、EProgressbar等 UI 节点类型- 相关列表类型如
ListEButton、ListEImage、ListELabel、ListENode、ListEProgressbar
主要API
- UI节点查询与操作
LuaAPI.query_ui_node(_name)/LuaAPI.query_ui_nodes(_name_list):查询单个/批量UI节点。Role.set_button_text(_button, _text):设置按钮文本。Role.set_label_color(_label, _color, _transition_time):设置文本颜色。Role.set_node_visible(_node, _visible)/Role.set_ui_opacity(_node, _opacity):设置节点可见性/透明度。Role.set_progressbar_current(_progress_bar, _current)/Role.set_progressbar_max(_progress_bar, _max):设置进度条进度。
- UI交互与反馈
Role.show_tips(_content, _duration):显示飘字提示。Role.set_node_touch_enabled(_node, _touch_enabled):设置节点交互开关。Role.show_goods_purchase_panel(_raw_goods_id, _show_time):显示商品购买界面。
5. 场景与相机系统
相关类型
CameraBindMode、CameraPropertyType、SkyBoxBackground、SkyBoxGradualType、Color、Vector3、Point3、Quaternion
相关枚举
CameraBindMode相机绑定模式CameraPropertyType相机属性预设SkyBoxGradualType天空盒渐变类型
主要API
- 相机控制
GlobalAPI.set_camera_bind_mode(_role, _mode):设置相机绑定模式。GlobalAPI.set_camera_follow_unit(_role, _unit, _follow_rotation):相机跟随单位。GlobalAPI.set_camera_property(_role, _property, _value):设置相机属性(如距离、视场角、俯仰角等)。Role.reset_camera(_reset_angle, _reset_bind, _reset_point, _reset_prop_pitch):重置相机。
- 场景与光照
GlobalAPI.set_skybox_texture(_texture_id, _change_type, _duration):切换天空盒。GlobalAPI.set_direct_light(_param_dict, _duration):设置场景光照参数。GameAPI.set_life_entity_survival_scene_boundary(_x, _y, _z)/GameAPI.set_unit_survival_scene_boundary(_x, _y, _z):设置单位/生命体的场景边界。
6. 音效与特效系统
相关类型
SfxID、SfxKey、SoundID、SoundKey
主要API
- 特效播放与管理
GameAPI.play_sfx_by_key(_sfx_key, _pos, _rot, _scale, _duration, _rate, _with_sound):播放特效。GlobalAPI.bind_sfx_to_unit(_sfx_id, _unit, _socket_name, _pos, _bind_type):将特效绑定到单位。GlobalAPI.set_sfx_position(_sfx_id, _pos)/GlobalAPI.set_sfx_orientation(_sfx_id, _orientation):设置特效位置/旋转。GlobalAPI.set_sfx_visible(_sfx_id, _visible):设置特效可见性。GlobalAPI.destroy_sfx(_sfx_id, _fade_out):销毁特效。
- 音效播放与管理
GameAPI.play_3d_sound(_position, _sound_key, _duration, _volume):播放3D音效。GameAPI.stop_sound(_assigned_id)/Unit.stop_sound(_lres_id):停止音效。
7. 存档与成就系统
相关类型
Archive、ArchiveType、Achievement
主要API
- 存档管理
Role.get_archive_by_type(_archive_type, _key)/Role.set_archive_by_type(_archive_type, _key, _val):获取/设置存档值。
- 成就管理
Role.get_achievement_progress(_event_id)/Role.set_achievement_progress(_event_id, _count):获取/设置成就进度。Role.add_achievement_progress(_event_id, _add_count):增加成就进度。Role.is_achievement_completed(_event_id):判断成就是否完成。
8. 通用与工具API
相关类型
Dict、List、Str、Int、Bool、Fixed、Timer、Timestamp
主要API
- 日志与调试
LuaAPI.log(_content)/GlobalAPI.debug(_content)/GlobalAPI.error(_content)/GlobalAPI.warning(_content):日志输出。
- 随机数与模块
LuaAPI.rand()/GameAPI.random_int(_min_value, _max_value)/GameAPI.random_color():生成随机数/颜色。LuaAPI.require(_name):加载脚本模块。
- 全局变量与时间
LuaAPI.get_global_var(_var_name)/GameAPI.has_global_kv(_var_name):获取/判断全局变量。GameAPI.get_day(_timestamp)、GameAPI.get_hour(_timestamp)、GameAPI.get_year(_timestamp)等:时间戳转日期/时间。
9. 事件(EVENT)
主要事件类型
- 技能事件:如
ABILITY_BULLET_HIT、ABILITY_CAST_BEGIN、ABILITY_UPGRADE等,涵盖技能释放、冷却、升级、命中等。 - 单位/组件/生命体/物品/角色相关事件:如
SPEC_LIFEENTITY_CREATE、SPEC_OBSTACLE_CREATE、SPEC_EQUIPMENT_ENTER_CHAR_SLOT等,涵盖对象的创建、销毁、交互、移动、复活等。 - 全局与自定义事件:如
GAME_END、GAME_INIT、CUSTOM_EVENT、UI_CUSTOM_EVENT,支持自定义扩展。 - 计时器与周期性事件:如
TIMEOUT、REPEAT_TIMEOUT,用于定时与周期性逻辑。
如需某一功能系统下的详细API说明,可进一步指定系统名称。
