菜单与 HUD 绘制 API

插件菜单

samp.ui.menu.register(page)

需要 ui.menu。注册页面，或替换相同 ID 的页面，无返回值。大多数页面或控件 校验失败会被忽略，而不是抛出错误。

samp.ui.menu.register({
    id = "main",
    title = "示例",
    controls = {
        { type = "switch", id = "enabled", title = "启用", value = true }
    }
})

页面字段	类型	约束
id	string	必填、非空，最长 64 字节。
title	string	必填、非空，最长 128 字节。
controls	array	最多 32 个控件，同一页面中的 ID 必须唯一。

每个插件最多注册 8 个页面。每个控件都必须提供 type、最长 64 字节的 id 和最长 128 字节的 title。

控件类型	附加字段
section	无。
text	text: string，可为空，最长 512 字节。
button	无；点击后产生控件变化事件。
switch	必填 value: boolean。
slider	min=0、max=1、step=0.1、value=min；均为有限数且绝对值不超过 1,000,000；max > min、step > 0，value 会被钳制。
choice	value: string；options 含 1–32 个唯一 { value, label }；value 必须匹配一个选项；value 最长 512 字节，label 最长 128。
text_input	value=""、placeholder=""、max_length=512；最大长度是 1..512 的整数，value 不得超长。

修改控件会触发 ui.control_changed，字段见事件回调参数。

HUD 调用阶段

所有 samp.draw 函数均需要 ui.draw，并且只能在 draw.hud 回调中同步调用。 每个插件每帧最多排队 512 条绘制命令。除 world_to_screen 外均无返回值。

颜色使用 0xAARRGGBB ARGB 整数。normalized=true 时坐标范围是 0..1， 否则使用屏幕坐标。普通坐标必须有限且绝对值不超过 100,000。

samp.draw.text(options)

字段	默认值	约束
x、y	0	坐标。
text	—	必填字符串，最长 1,024 字节。
size	16	有限，>0 且 <=512。
color	0xFFFFFFFF	ARGB。
normalized	false	布尔值。

samp.draw.line(options)

字段为 x1=0、y1=0、x2=0、y2=0、color=0xFFFFFFFF、 thickness=1（>0..100）和 normalized=false。

samp.draw.rect(options)

与 line 相同，另有 filled=false。即使填充，thickness 也必须有效。

samp.draw.circle(options)

字段为 x=0、y=0、radius=1、color=0xFFFFFFFF、filled=false、 thickness=1（>0..100）和 normalized=false。radius 必须为正且不超过 100,000；归一化模式下不得超过 1。

samp.draw.progress_bar(options)

字段为 x1=0、y1=0、x2=0、y2=0、value=0、 color=0xFFFFFFFF、background_color=0x66000000 和 normalized=false。要求 x2 > x1、y2 > y1，value 范围为 0..1。

samp.draw.image(options)

字段	默认值	约束
x1、y1、x2、y2	0	x2 > x1、y2 > y1。
resource	—	必填的包内安全相对路径，最长 256 字节。
alpha	1	有限 0..1。
normalized	false	布尔值。

支持 PNG、WebP、JPEG、JPG。源文件最大 16 MiB，解码尺寸最大 1024×1024。 每个插件最多缓存 16 张图和 16 MiB 解码数据；整个运行环境上限 64 MiB； 每帧最多开始加载一张未缓存图片。

samp.draw.world_to_screen(position)

接收 Vector3。游戏不可用或点无法投影到镜头前方时返回 nil，否则返回：

{ x = number, y = number, depth = number, width = number, height = number }