Lua API 完整参考
163 个函数，29 个分类，
163 个函数，29 个分类，
一份可以直接检索的完整清单
这里是 脚本指南 的完整版——每一个 gt.* 接口按功能分类列出签名与简要说明，方便按需查阅。想先看快速上手和示例代码，请回到脚本指南。
01核心输入
统一输入 API · 鼠标 / 键盘旧版 API · 驱动级操作 · 虚拟手柄 — 共 46 个函数统一输入 API（推荐）
- gt.set_input_mode(mode)设置全局输入模式：auto/driver/virtual
- gt.get_input_mode()获取当前输入模式
- gt.set_block_mode(mode)设置热键阻断模式：block/passthrough
- gt.get_block_mode()获取当前阻断模式
- gt.key(key, action, driver)统一按键，支持 press/down/up
- gt.click(button, action, driver)统一鼠标点击，支持 click/down/up
- gt.move(x, y, relative, driver)统一鼠标移动，支持绝对/相对
- gt.clear_mouse_moves()清空待执行的相对鼠标移动
- gt.get_cursor_shape()获取当前鼠标光标特征码
- gt.start_cursor_shape_monitor(...)异步监控光标特征码，写入共享变量
- gt.stop_cursor_shape_monitor(name)停止指定光标特征码监控
- gt.get_cursor_shape_monitor(name)读取光标特征码监控状态
- gt.set_interval(name, ms, cb)注册后台定时回调，不阻塞主循环
- gt.clear_interval(name)停止后台定时回调
- gt.start_async_callback(...)启动独立 Lua 状态异步回调代码块
- gt.stop_async_callback(name)停止指定异步回调代码块
- gt.get_async_callback_status(name)读取异步回调状态（运行/次数/错误）
- gt.scroll(direction, amount, driver)滚轮滚动
- gt.combo(key1, key2, ...)组合键，如 Ctrl+C
- gt.text(text)输入文本
驱动级操作
- gt.driver_enabled()检查驱动级是否启用
- gt.get_driver_type()获取当前驱动后端：nc/kminput/logitech/dd
- gt.set_driver_type(type)切换驱动后端，返回是否成功和当前后端
- gt.driver_key_press(key)驱动级按键
- gt.driver_key_down(key)驱动级按键按下
- gt.driver_key_up(key)驱动级按键释放
- gt.driver_mouse_move(x, y)驱动级绝对移动
- gt.driver_mouse_move_relative(dx, dy)驱动级相对移动，常用于压枪脚本
- gt.driver_mouse_click(button)驱动级鼠标点击
鼠标操作（旧版 API）
- gt.mouse_move(x, y)绝对移动鼠标
- gt.mouse_move_relative(dx, dy)相对移动鼠标
- gt.mouse_move_smooth(x, y, ms)平滑移动鼠标（带缓动）
- gt.mouse_get_pos()获取鼠标位置
- gt.mouse_click(button)鼠标点击
- gt.mouse_down(button)鼠标按下（不释放）
- gt.mouse_up(button)鼠标释放
- gt.mouse_scroll(direction, amount)滚轮滚动
键盘操作（旧版 API）
- gt.key_press(key)按键（按下并释放）
- gt.key_down(key)按键按下（不释放）
- gt.key_up(key)按键释放
- gt.key_combo(key1, key2, ...)组合键
- gt.type_text(text)输入文本（支持中文）
虚拟手柄 API
- gt.gamepad_available()检查虚拟手柄是否可用
- gt.gamepad_button(name, action)发送虚拟手柄按键 down/up
- gt.gamepad_press(name, hold_ms)虚拟手柄按下并释放
- gt.gamepad_reset()重置虚拟手柄所有按键状态
02热键与宏
热键绑定 · 进程限制 · 宏调用 / 宏库 · 设备动作 · 主控热键 · 动作注册 — 共 35 个函数热键绑定
- gt.bind_hotkey(hotkey, cb)绑定热键（单次执行）
- gt.bind_hotkey_loop(hotkey, cb, ms)绑定热键循环（Toggle 模式）
- gt.toggle_hotkey_loop(hotkey)手动切换热键循环状态
- gt.stop_hotkey_loop(hotkey)停止指定热键循环
- gt.stop_all_loops()停止所有循环
- gt.is_loop_running(hotkey)检查循环是否运行中
- gt.unbind_hotkey(hotkey)解除热键绑定
- gt.is_key_pressed(key)检查按键是否按下
进程限制热键
- gt.set_hotkey_process(hotkey, ...)设置热键只在指定进程生效
- gt.clear_hotkey_process(hotkey)清除热键进程限制
- gt.get_hotkey_process(hotkey)获取热键进程限制列表
- gt.get_foreground_process()获取当前前台进程名（小写）
宏调用
- gt.run_macro(hotkey)运行 GUI 绑定的宏，按执行模式自动处理
- gt.stop_macro(hotkey)停止宏执行（用于 loop/hold 模式）
- gt.list_macros()列出所有可用宏
- gt.has_macro(hotkey)检查宏是否存在
- gt.get_macro_info(hotkey)获取宏详细信息（动作数/阻断/模式）
宏库 API
- gt.run_macro_by_name(name)按名称运行宏库中的宏
- gt.stop_macro_by_name(name)停止宏库中正在循环的宏
- gt.list_macro_library()列出宏库中所有宏名称
- gt.has_macro_by_name(name)检查宏库中宏是否存在
- gt.get_macro_library_info(name)获取宏库宏详细信息
设备动作 API
- gt.list_device_bindings(kind)列出当前设备动作（keyboard/mouse/gamepad）
- gt.has_device_binding(kind, target)检查指定设备动作是否存在
- gt.run_device_binding(kind, target)立即执行设备动作（读取最新配置）
主控热键 API
- gt.register_hotkey(hotkey)注册主控热键
- gt.enable_hotkey_right_click(en)设置热键按下时是否联动右键
- gt.is_hotkey_right_click_enabled()获取热键右键开关状态
- gt.toggle_scripts()切换脚本开关状态
- gt.enable_scripts()启用脚本执行
- gt.disable_scripts()禁用脚本执行
- gt.is_scripts_enabled()检查脚本是否启用
动作注册 API
- gt.register_hotkey_actions(...)注册热键动作序列，支持 once/loop/hold
- gt.unregister_hotkey_script(hotkey)注销热键脚本
- gt.set_mouse_skill_interval(btn, ms)设置鼠标技能循环间隔
03视觉与识别
取色识别 · 截图 · 图像识别 · 识别控制 — 共 16 个函数取色识别
- gt.get_pixel_color(x, y)获取指定坐标像素颜色
- gt.check_color(x, y, r, g, b, tol)检查颜色是否匹配
- gt.check_colors(points)检查多个颜色点是否全部匹配
- gt.check_saved_colors(name)按取色配置名或原始点数据检测
- gt.find_color(x,y,w,h,r,g,b,tol,step)区域内查找颜色，返回匹配坐标
- gt.find_color_region(region, ...)用 {x,y,width,height} 表查找颜色
图像识别
- gt.find_image(template_path, region)在屏幕上搜索本地图像文件
- gt.find_saved_image(name, region)按识图配置名查找，支持缩放范围
- gt.image_match(path,x,y,w,h,threshold)指定区域图像匹配，返回置信度
截图功能
- gt.screenshot(x, y, w, h, filename)截图保存为 PNG 文件
- gt.screenshot_base64(x, y, w, h)截图返回 Base64 编码
图像 / 颜色识别控制
- gt.start_image_recognition(ids)启动图像识别（不传则启动全部已启用）
- gt.stop_image_recognition()停止所有图像识别
- gt.get_image_recognition_status()获取图像识别运行状态
- gt.pick_color(x, y)获取指定坐标颜色（r,g,b,hex）
- gt.get_color_recognition_status()获取取色识别状态（运行/配置数量）
04系统、窗口与设置
系统函数 · 全局设置 · 屏幕与进程 · 鼠标锁定 · 右键锁定 · 开关控制 — 共 37 个函数系统函数
- gt.get_screen_size()获取屏幕分辨率（逻辑坐标）
- gt.get_active_window()获取当前活动窗口标题
- gt.get_foreground_window_rect()获取前台窗口位置和大小
- gt.highlight_rect(x,y,w,h,dur,color)显示屏幕高亮框（点击穿透）
- gt.hide_highlight()隐藏所有屏幕高亮框
- gt.log(message)输出普通日志
- gt.debug(message)输出调试日志（需开启调试模式）
- gt.reminder(text, duration)显示 GUI 提醒通知，1000–30000ms
- gt.schedule_reminder(text, delay, dur)设置延迟后显示的定时提醒
- gt.speak(text, voice)立即播报文本
- gt.set_voice(voice)设置默认语音
- gt.get_voice()获取当前默认语音
- gt.list_voices()列出可用语音
- gt.msgbox(title, message)显示消息框
- gt.get_time()获取当前时间戳（毫秒）
- gt.is_captcha_input_active()检查打码输入是否正独占键鼠
全局设置 API
- gt.get_global_settings()获取当前全局设置快照（全部字段）
- gt.update_global_settings(patch)更新全局设置并立即生效
- gt.get_trigger_key()获取全局宏开关键
- gt.set_trigger_key(key)设置或清除全局宏开关键
- gt.set_apex_config(sens, zoom)设置 Apex 灵敏度配置（压枪修正）
- gt.get_apex_modifier()获取 Apex 灵敏度修正系数
屏幕与进程 API
- gt.get_screen_dpi(x, y)获取屏幕 DPI 缩放，可按坐标定位显示器
- gt.set_excluded_processes(list)设置排除进程列表
- gt.get_excluded_processes()获取排除进程列表
鼠标锁定位置 API
- gt.set_lock_offset(x, y)设置鼠标锁定位置偏移（相对屏幕中心）
- gt.get_lock_offset()获取当前锁定位置偏移
- gt.reset_lock_offset()重置锁定位置偏移为 (0,0)
- gt.set_override(config)设置 Lua 覆盖态：偏移/居中/右键锁定
- gt.reset_override()重置 Lua 覆盖态为默认值
右键锁定 API
- gt.lock_right_click()锁定右键
- gt.unlock_right_click()解锁右键
- gt.is_right_click_locked()获取右键锁定状态
开关控制 API
- gt.enable_wasd_switch(en)开启/关闭 WASD 长按开关（超 200ms）
- gt.is_wasd_switch_enabled()获取 WASD 开关状态
- gt.enable_driver_key(en)开启/关闭驱动级按键
- gt.is_driver_key_enabled()获取驱动级按键状态
05手柄与准星
手柄控制 · 准星覆盖层 — 共 13 个函数手柄控制 API
- gt.get_gamepad_status()获取手柄连接状态（数量/消息）
- gt.set_gamepad_vibration(en, intensity)设置手柄震动强度（0.0–1.0）
- gt.set_gamepad_deadzone(dz, index)设置手柄摇杆死区（0.0–1.0）
准星覆盖层 API
- gt.crosshair_show()显示准星覆盖层
- gt.crosshair_hide()隐藏准星覆盖层
- gt.crosshair_toggle()切换准星显示状态
- gt.crosshair_config(type,color,size,thk)一次性设置准星配置
- gt.crosshair_get_config()获取当前准星配置
- gt.crosshair_type(type)设置类型：dot/cross/cross-gap/circle
- gt.crosshair_color(color)设置准星颜色（十六进制）
- gt.crosshair_size(size)设置准星大小（1–200）
- gt.crosshair_offset(x, y)设置相对屏幕中心的位置偏移
- gt.crosshair_fixed(enabled)设置准星是否固定在偏移位置
06延时、共享变量与录制
延时函数 · 多脚本共享变量 · 录制功能 · 定时任务中心 — 共 16 个函数延时函数
- gt.sleep(ms)延时指定毫秒（支持小数）
- gt.sleep_random(min, max)随机延时
- gt.loop(count, interval, cb)同步循环调用；count=0 直到脚本停止
多脚本共享变量
- gt.shared_set(key, value)设置共享变量，传 nil 等同删除
- gt.shared_get(key, default)读取共享变量，可提供默认值
- gt.shared_delete(key)删除共享变量
- gt.shared_clear(prefix)按前缀清空；不传清空全部
- gt.shared_incr(key, delta)原子递增共享数值
录制功能 API
- gt.start_recording(real_delay, delay)开始录制键鼠操作
- gt.stop_recording()停止录制并返回动作序列
- gt.get_recording_status()获取录制状态（是否录制中/数量）
- gt.clear_recording()清空录制的动作列表
定时任务中心 API
- gt.list_timer_tasks()列出定时任务中心里的任务
- gt.save_timer_task(task)创建或更新定时任务
- gt.delete_timer_task(task_id)删除指定定时任务
- gt.execute_timer_task(task_id)立即执行指定定时任务