脚本内存 API 总览

本页说明与 GTA 脚本全局/局部变量、字节补丁、向量与 joaat 相关的一组 Lua API。它们与按任意地址读写的 memory 模块用途不同：此处面向游戏脚本虚拟机里的 global/local 等。

下列 script_global / script_local / script_function / script_patch 及与 NativeBuffer 搭配的本机调用，会触及游戏脚本或本机状态，须在脚本线程中执行。从 gui_tick、on_present 触发请用 fiber.run(function() ... end)，或写在 on_tick、script.create 回调里（joaat、Vector3 纯运算除外）。

包含哪些 API

名称	在 Lua 中的形态	说明
`joaat(str)`	全局函数	字符串 → 无符号 32 位哈希；详见 joaat。
`Vector3`	类型（可 `Vector3.new(...)`）	三维向量与运算；详见 Vector3。
`script_global`	类型	`script_global.new(index)` 及一系列读/写/位/地址方法；详见 script_global。
`script_local`	类型 + 表上的函数	`script_local.new(...)`、`script_local.is_thread_running(...)`；实例方法见 script_local。
`script_patch`	类型 + 表上的函数	`script_patch.add(...)` 返回补丁对象；`:enable` / `:disable`。详见 script_patch。
`script_function`	表上的函数	`script_function.call(opts)`、`script_function.find_pc(opts)`：按特征在脚本内定位并调用入口。详见 script_function。
`NativeBuffer`	类型	给需要缓冲区的 native 传参；见 NativeBuffer（与 global/local 搭配使用时常用）。

`script_id`（脚本是谁）

凡参数叫 script_id 的接口（例如 script_local.new、script_patch.add），都按下表识别目标脚本：

传入类型	含义
`string`	脚本名，会与 `joaat("脚本名")` 得到的结果一致后再去匹配运行中的脚本。
整数 / number	视为已经算好的脚本哈希（可直接使用你从其它工具或文档得到的数值）。

如何找到脚本线程

在当前的脚本线程列表里查找与上一步哈希一致、且仍处于可访问状态的线程（已结束的不参与）。

script_local.new 若找不到对应线程，或该线程没有可用的局部栈，会返回 nil。

`script_local` 的索引与 `:at`

index 表示目标脚本局部变量槽的编号，与常见脚本工具里看到的 local 编号一致。:at(offset) 不带第二参数时，在当前槽基础上平移 offset 个槽；带 size 时与 script_global:at 使用相同的「基址 + 1 + 下标 × 步长」规则，详见 script_local · :at。

`script_global:set_string` 注意

写入时最多写入「字符串长度 + 1」个字节（多出来的一个是结尾的 \0）。不会替你扩大缓冲区；若目标槽实际能容纳的字节不够，可能破坏相邻数据。请只在确认大小时使用。

`script_patch.add` 的 `bytes` 表

补丁字节来自表里每一项的值，收集顺序与 Lua 表的遍历顺序一致。为得到确定的字节顺序，请写成从 1 开始的连续数组，例如 { 0x2D, 0x01, 0x00 }，不要使用依赖哈希键顺序的写法。

`script_patch` 与生命周期

补丁对象不再被任何变量引用、被 Lua 回收时，会自动关闭对应补丁（与手动 :disable() 效果类似）。仍建议在逻辑结束时主动 :disable() 或释放引用，避免长时间悬挂。

`script_global` 方法一览

逐项说明与参数表见 script_global 页面。

:at · :get_int · :get_uint · :get_float · :get_bool · :get_string · :set_int · :set_uint · :set_float · :set_bool · :set_string · :set_bit · :clear_bit · :is_bit_set · :set_bits · :clear_bits · :get_address

`script_local` 方法一览

与 script_global 对齐，含字符串读写。逐项说明见 script_local。

:at · :valid · :get_int · :get_uint · :get_float · :get_bool · :get_string · :set_int · :set_uint · :set_float · :set_bool · :set_string · :set_bit · :clear_bit · :is_bit_set · :set_bits · :clear_bits · :get_address

script_global · script_local · script_function · script_patch · Vector3 · joaat · NativeBuffer