XiRush Lua API 文档 v2.0

完整的 Lua 脚本 API 参考。脚本文件放置于 Lua/ 目录，由 XiRush 自动加载。内置高级模块：player、vehicle、world、network（含 trigger_script_event）、game（模型 / 世界模型 bypass）、fiber、script、task、notify、log、http、fs、json、memory、util；joaat、Vector3、script_global、script_local、script_function、script_patch 等与脚本内存相关的约定见 脚本内存 API 总览；NativeBuffer、dates 等见侧栏；界面为 ui；原生命名空间见 natives 文档。

生命周期钩子

在脚本中定义以下全局函数，XiRush 会在对应时机自动调用。渲染顺序约定：若本帧允许绘制 UI，先调用 gui_tick()；仅当该钩子不存在或成功执行完毕后，才会调用 on_present()。若 gui_tick 出错，本帧通常不会再进入 on_present，脚本可能被标记为异常。

on_load()

脚本加载后调用一次，用于初始化。

on_unload()

脚本卸载前调用，用于清理资源。

on_tick()

每帧调用（脚本线程），可安全调用 native。

gui_tick()

UI 绘制（渲染线程）。在此使用 ui 与 ImGuiEnum；需要 native 时用 fiber.run 切到脚本线程（参见示例 online.lua）。当脚本在 Lua 引擎中为「已启用」时，即使主菜单关闭也会调用本钩子（便于 F7 浮窗与 pushStyleColor 等样式生效）。

on_present()

渲染帧补充回调，在 gui_tick 之后调用；无 UI 时可放轻量逻辑。

on_key(key, is_up)

按键事件。key 为虚拟键码，is_up 表示抬起。

-- 相对 Lua\ 根：自定义子目录 + 配置文件名（详见 example.lua 顶部 XR_*）
local cfg_path = "data/my_script/settings.json"
local cfg = json.load(cfg_path) or { god_mode = false, speed = 1.0 }

function on_load()
    notify.info("Lua 根: " .. fs.dir() .. " 配置: " .. cfg_path)
end

function on_unload()
    json.save(cfg_path, cfg)
end

function on_tick()
    if cfg.god_mode then
        ENTITY.SET_ENTITY_INVINCIBLE(PLAYER.PLAYER_PED_ID(), true)
    end
end

function gui_tick()
    if ui.begin("我的窗口") then
        local changed, val = ui.checkbox("无敌模式", cfg.god_mode)
        if changed then cfg.god_mode = val end

        local sc, sv = ui.sliderFloat("速度倍率", cfg.speed, 0.1, 5.0)
        if sc then cfg.speed = sv end

        if ui.button("保存配置") then
            json.save("config.json", cfg)
            notify.info("配置已保存")
        end
    end
    ui["end"]()
end

示例脚本（点我下载）

下列脚本随 XiRush 提供，可直接打开对照写法与注释。

文件说明
example.lua综合演示：生命周期、fs/json/log/http/memory、NativeBuffer、script_*、Vector3、UI 等；默认 F6 开关面板（见脚本内按键处理）。
simple.lua新手向：script.create 多任务、fiber.run、network.is_in_session 等；F7 开关面板。
online.lua在线玩家列表示范：on_tick 刷新缓存 + gui_tick 只读缓存绘 UI；NativeBuffer + NETWORK 句柄、script_global 读等级、network.trigger_script_event、game.with_model_bypass；F7 开关。
task_cayo.lua佩里克岛实用示例：on_load、on_key、gui_tick，fiber.run 内 script_global/script_local、STATS+MISC、util.force_script_host、script_function、notify，文件级 joaat；请求虎鲸/冷却/主目标前置/分红/强制准备/直接完成任务/注册CEO等按钮；ui 折叠分区与 pushStyleColor 配色；F7 开关面板。

好友标签等场景若只需布尔结果，可优先使用封装 API util.is_friend(player_id)；若需自管句柄缓冲区，再使用 NativeBuffer（见 online.lua 中 is_friend 与本文 nativebuffer.html 示例）。

XiRush Lua — API 文档 v2.0