静态类型 · LLVM 原生编译 · Windows
MoonLang
语法与用法手册
本手册面向使用这门语言写代码的人:从声明一个变量,到编出一个能被 C/C++ 直接 调用的 DLL,按顺序读一遍即可上手,也可以用左边的目录检索具体条目。
前八章是语言本身:词法、类型、变量、运算符、控制流、函数。§9 到 §13 讲怎么把代码 组织起来 —— 类、容器、JSON、内存、模块。§14 到 §16 是与外部交互:调 DLL、做 GUI,以及内置函数速查。 §17 是限制与陷阱清单,§18 是几段完整可编译运行的示例,§19 讲原生系统编程和 Windows DLL。
手册中每一条规则都对照编译器实现核对过,示例均已编译运行。语言在 2026-08 收了一次口:try/catch、继承、
静态方法、默认参数都已经能用;出错要么是带行号的编译错误,要么是可以 catch 的运行时错误
(退出码 3),不再有静默返回零值的情况。
01快速开始
# hello.moons
func greet(name: string) -> string:
return "你好, " + name + "!"
end
let who: string = "世界"
print(greet(who))gtc hello.moons -o hello.exe
hello.exe三条最容易踩的入门规则:
- 所有变量必须写类型,
let x: int = 42;没有类型推断。 - 一个文件只能用一种块风格:要么全
:…end,要么全{…},混用直接报Cannot mix { } and : end block styles。 - 顶层语句就是 main:写在文件顶层的语句按出现顺序执行,不需要
main();定义了func main()时,需要在文件末尾写一行main()调用它。
02编译器 gtc
gtc <source.gt> [options]| 选项 | 作用 |
|---|---|
-o <file> | 输出文件名 |
-r, --run | 编译完立刻运行 |
-I <dir> | 追加模块搜索目录,可重复(-I<dir> 连写也行) |
--resources <files> | 逗号分隔,把文件打进 exe,运行时用 moon:// 访问(LZ77 + AES-256-CTR 保险库) |
--resources-file <f> | 同上,但清单从文件读 |
--icon <file> | 把 .ico 打成 exe 图标 |
--manifest <file> | 嵌入 Windows 应用清单(要管理员权限、DPI 感知时用) |
--version-json <f> | 从 Wails 的 build/windows/info.json 生成版本资源 |
--dll | 编成 DLL,导出所有 export func |
--native-dll | 编成原生 ABI DLL,直接导出 export native func,可定义 dllmain |
--static-crt | 静态链接 CRT,目标机不用装 VCRUNTIME140 / MSVCP140 |
--emit-ir / --emit-bc / --emit-obj | 输出 LLVM IR / bitcode / 目标文件 |
--emit-layout-json <file> | 只输出 C 聚合体的大小、对齐和字段偏移,不再链接最终程序 |
-h --help · -v --version | 帮助 / 版本 |
源码后缀 .gt(推荐)或 .moons(兼容)。
程序运行时没被 catch 的错误在 stderr 打 运行时错误: 第 N 行: …,退出码 3(§7.7)。
gtc app.moons -o app.exe --static-crt --icon assets\app.ico --resources dist\index.html,dist\app.js
gtc lib.moons -o lib.dll --dll
gtc core.gt -o core_x64.dll --native-dll --static-crt
gtc core.gt --emit-layout-json core_layout.json
gtc src\main.moons -o out.exe -I src -I vendor03词法:注释 / 字面量 / 关键字
3.1 注释
只有 # 开头到行尾一种。没有块注释。
# 这是注释
let x: int = 1 # 行尾注释3.2 数字字面量
let a: int = 42
let hex: int = 0xFF # 十六进制
let bin: int = 0b1010 # 二进制
let oct: int = 0o755 # 八进制
let f: float = 3.14
let e: float = 1.5e-3 # 指数(带 e/E 即为 float)
let mask: u64 = 0xffffffffffffffff as u64int 是 64 位有符号,float 是 double。无符号字面量可以写满 64 位;
超过 i64 正数范围时需要显式写 as u64。
3.3 字符串字面量
单引号双引号等价;三引号(""" 或 ''')是多行字符串,内容原样保留、不处理转义。
let s1: string = "双引号"
let s2: string = '单引号'
let html: string = """
<!DOCTYPE html>
<html><body>直接写 HTML,不用转义引号</body></html>
"""转义字符:\n \t \r \\ \" \' \0。
其它 \x 一律原样保留 x(例如 "\d" 得到 d,不是报错)。
JSON 字符串写在源码里要自己转义:
let raw: string = "{\"msg\":\"hi\",\"n\":10}"3.3.1 字符串按 UTF-8 字符计数(str_* 扩展函数按字节)
核心操作全部按字符(中文 / emoji 各算一个),和 for-in 一个口径;
只有 str_len / str_sub / str_code 这些扩展内置保留字节口径:
| 写法 | 口径 | "你好ab" 的结果 |
|---|---|---|
len(s) / s.length | 字符 | 4 |
s[i](支持负下标) | 字符,返回 1 个字符的 string | s[0] → 你,s[-1] → b |
substring(s, start, count) | 字符;负 start 从尾部数;越界只截断 | substring(s, 1, 2) → 好a,substring(s, -2, 2) → ab |
for ch in s | 字符 | 你 好 a b 四次 |
str_len(s) / str_sub(s, a, n) | 字节 | str_len → 8 |
s[i] 越界是运行时错误(字符串下标越界:下标 5,长度 3,可 catch,未捕获退出码 3);
substring 越界只截断、不报错。
3.4 关键字
let const int float bool string list dict void any
if elif else while for in to end
true false null and or not
func function return break continue
try catch throw switch case default
class extends self super new static
export extern global native dynamic required
cstruct cunion cfunc unsafe dllmain noexcept noalloc thread_local
import from as另有两个上下文关键字:go(§8.9,语句开头、后面紧跟标识符 / self / func)和
select(§8.10,语句开头、后面紧跟 :)。协程同步对象的类型名 chan Mutex
WaitGroup Once AtomicInt 不能再当类名。
其中 int float bool string list dict any
在值的位置可以当普通标识符用(类型只出现在 : / -> / as / <…> 之后,语法上分得开):
let list: list<int> = [1, 2, 3] # 变量就叫 list,合法
let dict: dict<string, int> = {"a": 1}
print(int("12") + 1) # 内置转换函数3.5 语句分隔
换行就是语句结束,; 可选。! 单独出现是词法错误 —— 逻辑取反写 not,不等写 !=。
3.6 块风格
# 冒号风格(推荐,本仓库全部示例都用这个)
if x > 0:
print("正")
end
# 大括号风格
if x > 0 {
print("正")
}一个文件里只能选一种,第一次遇到的那种就定死了。
04类型系统
4.1 基本类型
| 类型 | 说明 | 底层 |
|---|---|---|
int | 64 位有符号整数 | i64 |
float | 双精度浮点 | double |
bool | 布尔 | i1 |
string | UTF-8 字符串 | i8* |
void | 无返回值(只用于返回类型位置) | void |
any | 动态值(json_decode 的树),带引用计数 | 指针 |
原生函数、cstruct 和原生 DLL 里还能用定宽标量:
| 类型 | 说明 |
|---|---|
i8/u8 i16/u16 i32/u32 i64/u64 | 精确位宽的有符号 / 无符号整数 |
isize / usize | 与目标机器指针等宽的整数 |
f32 / f64 | 单精度 / 双精度浮点 |
托管代码使用 int / float 即可;要和 C ABI、共享内存或 Win32 结构逐字节对齐时,改用定宽类型。
4.2 复合类型
| 写法 | 说明 |
|---|---|
list<T> | 有序列表,T 可以是任意类型(含 list<...> / dict<...> / 类) |
dict<string, V> | 字典,键只能是 string,值任意 |
ClassName | 用 class 定义的结构体 / 对象 |
bytes | 二进制安全的字节缓冲(§20.1);string 遇 0 截断,文件块 / 网络包 / 帧数据用它 |
chan<T> / Mutex / WaitGroup / Once / AtomicInt | 协程同步对象(§8.10) |
func(T1, T2) -> R | 函数类型(用于变量、参数、回调) |
ptr<T> | 裸指针;ptr<void> 表示无类型地址 |
carray<T, N> | 内联固定数组,长度是编译期常量 |
volatile<T> | 每次访问都真的生成 load / store 的字段或变量 |
atomic<T> | 用 atomic_* 读写的整数、bool 或指针存储 |
cfunc<abi>(T1, T2) -> R | C ABI 函数指针 / 回调 |
CStructName | cstruct / cunion 定义的固定布局聚合体 |
let xs: list<int> = [1, 2, 3]
let m: dict<string, float> = {"rate": 0.05}
let grid: list<list<int>> = [[1, 2], [3]]
let cb: func(string) -> string = handler
let nothing: func() -> void = tickdict<int, int> 是类型错误(键必须 string,和 JSON 对象对齐)。
4.3 没有类型推断
所有 let / const / 参数 / 字段都必须写类型注解。函数省略 -> T 时默认 void。
4.4 隐式转换矩阵(赋值与传参时自动插入)
| 从 | 到 | 实现 |
|---|---|---|
any | string / int / float | 运行时转换函数 |
int | float | 数值提升(SIToFP) |
float | int | 截断(FPToSI) |
int | string | static_int_to_string |
float | string | static_float_to_string |
let t: int = time()
let tStr: string = t # int → string,不用写 str(t)
let f: float = 3.9
let n: int = f # → 3(截断)
let args: any = json_decode(argsJson)
let name: string = args[0] # any → string装箱 / 拆箱(any ⇄ 具体类型)不在上面这张表里,由代码生成单独处理,
支持 int / float / bool / string / 类对象 / list<任意> / dict<string, 任意> 递归:
let v: any = 5 # 自动装箱
let mixed: list<any> = [1, "two", 3.0]
let flag: bool = someAny # any → bool4.5 容器严格不变
list<int> 的变量不能当 list<float> 用(赋值、传参、return 都一样)——
代码生成不做逐元素转换。只有字面量走"按期望类型逐项转换"的通道:
func first(xs: list<float>) -> float: return xs[0] end
let ints: list<int> = [1]
print(first(ints)) # ✗ 编译错误:list<int> 不兼容 list<float>
print(first([1, 2])) # ✓ 字面量按期望元素类型建表
let ws: list<float> = [1, 2, 3] # ✓ 元素逐个转成 float
let d: dict<string, float> = {"a": 1} # ✓ 同理[1, 2.5] 这种混写会推成 list<float>。
4.6 显式转换
int(x) float(x) str(x) bool(x) type(x)str(list / dict / 对象)输出 JSON 文本;str(true)是"true"。bool(x):int/float 非 0;string 非空且不是"0"/"false"/"no"/"off";list 非空;对象非空;any 按运行时类型。type(x)返回静态类型名("int"/"list<int>"…);any按运行时返回"null"/"int"/"float"/"string"/"bool"/"list"/"dict"。expr as T:数值之间效果同int()/float()(2.9 as int→2);类之间是带运行时检查的向下转型(§9.6)。"12" as int不做解析:它把字符串的指针值当成整数,编译期不报错,结果是个无意义的大数。 字符串转数字用int("12")/float("2.5")(解析失败返回 0)。
05变量与常量
let x: int = 42
const MAX: int = 1000 # const 不可再赋值
let name: string = "moon"
x = x + 1 # 赋值
x += 1 # 复合赋值:+= -= *= /= %=(脱糖成 x = x + 1)- 类型注解和初值都是必须的:
let x: int少了=会报Expected '=' after type annotation。 - 作用域:块级。
if/for/while/ 函数体各自一层,循环变量只在循环里可见。 - 顶层
let/const是全局。
赋值目标可以是变量、下标、成员:
x = 1
xs[0] = 9
d["k"] = 3
obj.field = "v"5.1 全局与字段里的字符串自动"钉住"
内置函数返回的字符串(2026-11 起还有 + 拼接、数字转字符串的结果)保存在一个有界环形缓冲里(按线程分片,每片 2048 条 / 2MB,超了回收最旧的)。
编译器往顶层 let/const 和类字段存字符串时会自动调
static_str_store 复制一份长期持有的拷贝,所以:
let root: string = app_data_dir("MyApp") # 跑一整天也不会变空串,不用 str_keep
class Store:
let path: string # new Store(x) / self.path = x 同样钉住
end局部变量和参数不复制:它们拿着的临时字符串由环形缓冲钉住(§12「临时字符串」),用着的时候不会被回收。已有的 str_keep(...) 调用留着也无害。
5.2 原生线程局部变量
thread_local let reentry_guard: u32 = 0thread_local let 只能写在顶层,类型是 POD / 原生类型,初值只能是字面量。
每个线程一份,可用于 hook 的重入守卫;普通顶层 let 还是全部线程共用一份。
06运算符与优先级
从低到高(源码里就是 parseOr → parseAnd → … → parsePostfix 这条链):
| 级别 | 运算符 | 结合 | 说明 |
|---|---|---|---|
| 1 | or | 左 | 两边必须 bool |
| 2 | and | 左 | 两边必须 bool |
| 3 | | | 左 | 按位或,两边 int |
| 4 | ^ | 左 | 按位异或 |
| 5 | & | 左 | 按位与 |
| 6 | == != | 左 | |
| 7 | < <= > >= | 左 | |
| 8 | << >> | 左 | 比比较紧、比 + - 松:1 << 2 + 1 是 8 |
| 9 | + - | 左 | + 任一边是 string 即为字符串拼接 |
| 10 | * / % | 左 | |
| 11 | ** | 右 | 幂,结果永远是 float |
| 12 | -x not x ~x | 右 | 一元 |
| 13 | f(...) a[i] o.m x as T | 左 | 后缀 |
+任一边是 string 就是拼接,另一边是 int / float / bool / any / list / dict / 对象时 自动转成文本(数字按str()口径,bool 是true/false,容器和 any 是 JSON 文本):print("n=" + n) # n=3 print(n + "=n") # 3=n print("ok=" + ok + " xs=" + xs) # ok=true xs=[1, 2] let s: string = "a" + 1 + "b" + 2.0 # a1b2- 逻辑运算只接受
bool:if x:(x 是 int)不合法,写if x != 0:。 - 位运算只接受
int。比较:数值、string、bool 可比。 - 没有
++/--,没有三元?:。
07控制流
7.1 if / elif / else
if score >= 90:
print("A")
elif score >= 60:
print("B")
else:
print("C")
end7.2 while
let i: int = 0
while i < 10:
if i == 5:
break
end
i += 1
end7.3 for 数值区间
for i = 0 to 5: # i = 0,1,2,3,4 —— 上界【不含】
print(i)
end条件是 i < end,步长固定为 1,循环变量类型固定 int。要倒着走或换步长,用 while。
7.4 for-in(按被遍历的类型分别实现)
| 可迭代对象 | 循环变量拿到 |
|---|---|
list<T> | 元素,类型 T |
string | 按 UTF-8 字符(中文 / emoji 各算一个)的 string |
dict<string, T> | 键,类型 string |
any | 数组元素(null 当空数组);运行时若不是数组 → 报错退出码 3 |
for n in names: print(n) end
for ch in "你好ab": print(ch) end # 你 / 好 / a / b
for k in stock: print(k + "=" + str(stock[k])) end
for v in json_decode("[1,2,3]"): print(v) end7.5 break / continue
只在 while / for 里有效。
7.6 switch / case / default
switch code:
case 0:
print("ok")
case 1, 2:
print("retry")
default:
print("fail")
endcase 值可以是任意表达式:整数、浮点、字符串、bool、变量都行
(switch 脱糖成逐个 == 比较,不再要求整型常量);一个 case 可以列多个值;
没有 fallthrough,每个 case 执行完直接跳出。
switch mode:
case "hunt":
return "HUNT"
case "idle", "rest":
return "IDLE"
default:
return "OTHER"
end返回路径分析只把带 default 的 switch 当"所有分支都终结"(不证明 true/false 穷尽),
所以非 void 函数里 switch 每个 case 都 return 而没有 default,仍会报"不是所有路径都有 return"。
7.7 try / catch / throw
func boom(n: int) -> int:
if n > 2:
throw "too big: " + n
end
return n * 10
end
try:
print(boom(5))
catch e:
print("caught [" + e + "]") # caught [too big: 5]
endthrow 表达式:值任意类型,进 catch 时统一转成 string(throw 42→"42",throw 1.5→"1.5")。throw必须带值。catch e:必须写变量名,e的类型固定是string。没有finally,没有按类型分派的多段 catch。- 错误跨函数传播:抛出点一路展开到最近的
try;try 体里return正常工作;可以嵌套,catch 里再throw就交给外层;匿名函数里抛的错由调用它的地方 catch。 - 运行时错误走同一套机制,全部可 catch:
| 触发 | 消息 |
|---|---|
整数 / % 除零 | 整数除以零 |
| 列表下标越界(读 / 写) | 列表下标越界:下标 7,长度 3 |
| 字符串下标越界 | 字符串下标越界:下标 5,长度 3 |
pop 空列表 | pop 空列表 |
null 对象读字段 / 调方法 | 访问空对象的字段 'n' / 访问空对象的方法 'get' |
for-in 的 any 不是数组 | for-in 遍历的 any 值不是数组(实际是 dict) |
as 向下转型失败 | 对象不是 Rect(实际是 Circle),as 转换失败 |
没人 catch 的错误:stderr 打 运行时错误: 第 N 行: <消息>,进程退出码 3(--dll 里不杀宿主,见 §8.8)。
内置函数自己的失败仍按返回值约定报(bool 成功位、-1、空串、json_last_error()),不抛。
08函数
8.1 声明
func add(a: int, b: int) -> int:
return a + b
end
func log_it(msg: string) -> void: # 省略 -> void 也一样
print(msg)
end
func nothing(): # 没写返回类型 = void
print("hi")
end- 参数必须写类型;返回类型省略即
void。function是func的同义词。 - 参数默认值:
func f(a: int, b: int = 2)。默认值只能是字面量(数字 / 字符串 /true/false/null/ 空的[]{}), 带默认值的参数必须排在末尾(f(a: int = 1, b: int)是编译错误)。默认值在调用点填入。方法、静态方法同样支持。 - 实参个数编译期检查:
函数 'f' 需要 1 到 2 个参数,这里传了 3 个。 - 非 void 函数每条路径都必须 return,否则编译错误
函数 'f' 声明返回 int,但不是所有路径都有 return。 判定:if要每个分支(含else)都终结;switch要有default且每个分支终结;while true体内有 return 算终结;普通while/for不算(可能一次都不进)。 void函数return 5是编译错误(void 函数不能 return 值)。
同一个块里,终结语句后面再跟任何语句是编译错误(行号指向那条多余的语句):
此处代码永远执行不到:return 已经结束了这个块。要临时屏蔽一段代码请注释掉它
范围只限同一块:if 两个分支都 return、if 之后再写语句是合法的(有汇合块)。
break / continue 写在循环外面同样是编译错误(break 只能写在 while / for 循环里)。
8.2 顶层提升:不用"先定义后使用"
顶层的 class / func / extern / let / const
在任何语句执行前先登记一遍(类型检查和代码生成各一遍),效果等于 Go 的包级作用域:
func a() -> int:
return b() + 1 # b 写在后面,没问题
end
func b() -> int:
return 41
end唯一保留顺序的是顶层语句的执行。一条顶层语句读一个还没执行到声明的全局是编译错误:
print(later) # ✗ 变量 'later' 在它的声明之前就被顶层语句读了
let later: int = 1
func show() -> void:
print(later) # ✓ 函数体里随便读
end8.3 匿名函数(带语句体)
let f: func(int) -> int = func(n: int) -> int:
let total: int = 0
for i = 0 to n:
total = total + i
end
return total
end
print(f(5)) # 10
thread_start("worker", func(name: string) -> string:
log_line("started " + name)
return ""
end)8.4 单表达式 lambda
let inc: func(int) -> int = (x: int) => x + 18.5 没有闭包
匿名函数只看得到自己的参数、顶层全局、顶层函数和类。捕获外层局部变量会报
匿名函数不能捕获外层局部变量 'x'。要共享状态就放到顶层 let。
8.6 方法当回调
接收者是顶层 let 出来的对象时,obj.method 可以直接当函数值传
(编译器合成一个转发函数):
let router: Router = new Router(...)
gui_expose_async_win(win, "api", router.dispatch)
thread_start("m", sink.take)局部对象的方法不行(那需要闭包),会报"只有全局对象的方法能当值用"。
8.7 函数类型的变量可以直接调用
func run_cb(cb: func(string) -> string, arg: string) -> string:
return cb(arg)
end8.8 export(配合 --dll)
# lib.moons —— gtc lib.moons -o lib.dll --dll
let base: int = 100
print("lib init")
export func lib_add(a: int, b: int) -> int:
return a + b + base
end
export func lib_risky(n: int) -> int:
if n < 0:
throw "negative not allowed: " + n
end
return n * 2
endexport func成为 DLL 导出符号;参数 / 返回类型用标量(int / float / bool / string / void),宿主用extern "lib.dll" func …声明后直接调(§14)。- 顶层语句只跑一次:第一次调用任一导出函数时惰性执行;宿主也可以先调 DLL 自带导出的
gt_init()主动初始化。 - 导出函数里没人 catch 的
throw/ 运行时错误不会杀掉宿主:这次调用返回零值(0/0.0/false/""), 错误文本存起来,宿主用 DLL 自带导出的gt_last_error()取(形如第 32 行: negative not allowed: -1;没出过错是空串)。
export func 走的是托管 ABI。要让 C/C++、Win32 或别的语言按 C 的规矩直接调,
得换成 export native <abi> ... func,用 --native-dll 编:
export native system unsafe noexcept noalloc func add(a: i32, b: i32) -> i32:
return a + b
end原生导出没有 gt_init() / gt_last_error() 这套包装,完整规则见 §19。
8.9 go:协程
func fetch(id: int, url: string) -> void:
let body: string = http_get(url)
log_line("done " + str(id))
end
go fetch(1, "https://example.com/a") # 立刻返回,fetch 在另一条协程里跑
go fetch(2, "https://example.com/b")
go worker.run(7) # 方法也行,方法里可以 go self.step()
go func(id: int) -> void: # 也可以直接跟匿名函数,最后的括号里是实参
log_line("inline " + str(id))
end(3)
func blink(times: int) -> void:
for i = 0 to times:
sleep_ms(500) # 协程里的 sleep 不占线程:挂起自己,到点再接着跑
end
end
for i = 0 to 100000:
go blink(10) # 十万条同时活着,工作线程还是十几条
end和 Go 的 go 一个意思:这次调用放到一条新协程里并发执行,当前代码不等它,返回值丢弃。
协程是什么:一条有自己的栈的纤程,由少量工作线程轮着跑(M:N 调度,线程数默认等于 CPU 核数,至少 4)。
栈只预留 1MB 地址空间,用到哪页才占哪页内存,所以协程很便宜:实测一百万条协程同时在 sleep_ms,
12 条工作线程,提交内存约 1.7GB,起完 0.3 秒。
规则
- 实参在
go这一行求值(含隐式转换、默认参数)。字符串实参自动钉一份拷贝,any 加一次引用, 调用结束后释放;对象 / list / dict 是引用,两边是同一个,并发改要自己留意(和 Go 一样,没有自动加锁)。 - 后面可以跟自己定义的函数、方法(全局对象、局部对象、
self都行)、函数类型的变量; 不能直接跟内置函数(包一层自己的函数),不能用在native函数里。 go是上下文关键字,只有「go后面紧跟标识符或self」才算,照样能当变量名。- 协程里未捕获的运行时错误和主线程一样,退出码 3。
挂起和阻塞
| 协程里做的事 | 发生什么 |
|---|---|
sleep_ms(n) | 挂起这条协程、让出线程,到点后由任意一条空闲工作线程接着跑(醒来可能换了线程) |
go_yield() | 让出一下,排到就绪队列末尾 |
http_get / http_post_json / http_request / http_download | 编译器自动包了 go_block_enter() / go_block_leave():进去前先拿一个阻塞名额(共 256 个,满了这条协程挂起排队,不占线程),再让调度器补一条线程。所以一百万条协程各发一个请求不会把线程撑爆,同时在途最多 256 个 |
自己 extern 的慢函数、读大文件 | 手动在前后写 go_block_enter() / go_block_leave(),效果同上 |
| 其它阻塞调用(没包的) | 占住一条工作线程。调度器发现就绪的协程没人接、线程都卡着,就自动加线程(上限 512,闲 30 秒回收),所以一条协程卡住不连累别的 |
| 等 chan / Mutex / WaitGroup / Once(§8.10) | 挂起协程,不占线程 |
| 纯计算、不 sleep 也不 yield | 一直占着那条线程(没有抢占)。别的协程由其它线程跑,不会卡死,但想公平就自己 go_yield() |
go_lock_thread():把协程钉在线程上
对应 Go 的 runtime.LockOSThread。协程醒来会换线程,所以用了“认线程”的东西的协程要调 go_lock_thread(),从此它一直在同一条线程上
(它 sleep_ms 就是真的睡这条线程,线程归它独占,调度器会补线程),用完可以 go_unlock_thread() 放开:
thread_local let的变量;- Win32 互斥量 / 临界区拿着的时候要
sleep_ms(这些锁认线程,换了线程放不掉;改用 §8.10 的Mutex就没这个问题); - COM 对象、窗口消息、
GetLastError这类线程专属状态。
内置
| 函数 | 说明 |
|---|---|
go_active() | 还没跑完的协程数(排队 + 在跑 + 在睡),退出前等后台收尾时用 |
go_workers() | 调度器现在有几条工作线程 |
go_yield() | 让出一下;不在协程里就是让出时间片 |
go_lock_thread() / go_unlock_thread() | 钉在当前线程上 / 解除。只在一小段里用线程专属的东西时,前后各调一次就行;不在协程里调没有效果 |
go_stack_mb(n) | 之后新起的协程栈最多能长到 n MB(1..1024,默认 1)。栈是用多少占多少内存,这只是上限;要深递归的协程起之前调大 |
go_block_enter() / go_block_leave() | 见上表 |
sleep_ms 不在协程里(主线程、thread_start 的线程、回调线程)还是普通的睡。要按名字叫停的长循环仍可以用
thread_start / thread_stop,或者给协程传一个标志 / 一条通道进去。协程之间传数据、等结果、加锁见 §8.10。
8.10 协程之间:chan、select、Mutex、WaitGroup、Once、AtomicInt
协程之间传数据、等结果、保护共享状态用这一节的东西。它们都认协程:等的时候挂起协程、让出线程;
不在协程里用(主线程、thread_start 的线程)也行,那时等就是睡这条线程。
func worker(jobs: chan<string>, results: chan<int>, wg: WaitGroup) -> void:
for url in jobs: # 一直收,通道关闭并取空就结束
results.send(str_len(http_get(url, "{}")))
end
wg.done()
end
let jobs: chan<string> = chan(16) # 带 16 格缓冲;chan() 是无缓冲(发的人等到有人收)
let results: chan<int> = chan(16)
let wg: WaitGroup = wait_group()
wg.add(4)
for i = 0 to 4:
go worker(jobs, results, wg)
end
for i = 0 to 100:
jobs.send("https://example.com/" + str(i))
end
jobs.close() # 不再发了:收的那边 for-in 自己结束
go func(wg: WaitGroup, results: chan<int>) -> void: # go 后面直接跟匿名函数(没有闭包,要用的从实参传)
wg.wait()
results.close()
end(wg, results)
let total: int = 0
for size in results:
total = total + size
endchan<T>
let c: chan<T> = chan(容量),元素类型由接它的变量定,可以是任何类型(字符串在通道里有自己的拷贝)。
| 写法 | 说明 |
|---|---|
c.send(v) | 发。缓冲满了 / 无缓冲时没人收就等。向已关闭的通道发是运行时错误 |
c.recv() | 收。没有就等。通道关闭并取空之后返回零值(0 / "" / null) |
c.try_send(v) | 能立刻发出去就发并返回 true,否则 false,不等 |
for v in c: | 一直收到通道关闭并取空 |
c.close() | 关闭:不能再发,已经在缓冲里的还能收完;等着收的人都被叫醒 |
c.len() / c.cap() / c.closed() | 缓冲里有几个 / 容量 / 关了没有 |
c.free() | 这门语言没有 GC:长期运行的程序里不再用的通道要自己还(没人等在上面时) |
select
几个通道操作里等先就绪的那一个;同时就绪随机挑一个。
let msg: string = ""
select:
case msg = inbox.recv(): # 收,值放进已经声明的变量;不要值就写 case inbox.recv():
handle(msg)
case outbox.send(reply): # 发
log_line("sent")
case after(500): # 都没就绪就等 500 毫秒;和 default 只能有一个
log_line("timeout")
end
select:
case msg = inbox.recv():
handle(msg)
default: # 都没就绪就马上走这里:不等的收 / 发就这么写
log_line("nothing yet")
endselect 里的 break / continue 作用于外层的循环(和 switch 一样),所以 while true: 里套 select 可以直接 break 出循环。
Mutex / WaitGroup / Once / AtomicInt
- Mutex:
let mu: Mutex = mutex()。mu.lock()/mu.unlock()/mu.try_lock()(拿到返回true)/mu.waiting()(几个在排队)。 先到先得;拿着锁可以sleep_ms、可以换线程(它不认线程,和 Win32 互斥量不一样),不可重入(同一条协程连 lock 两次会把自己等死)。 - WaitGroup:
let wg: WaitGroup = wait_group()。wg.add(n)登记 n 件事,每件做完wg.done(),wg.wait()等到全部做完。wg.count()还剩几件。add要在go之前调(在新协程里才add的话,wait可能先跑到)。 - Once:
let init: Once = once()。init.run(f):f是不带参数的函数,全程只会被执行一次;同时调的其它协程等它执行完再返回。init.done()执行过没有。 - AtomicInt:
let hits: AtomicInt = atomic_int(0)。hits.add(n)(返回加完的值)/hits.get()/hits.set(v)/hits.cas(旧, 新)(当前值等于旧值才换,返回换没换成)。不用锁的计数器。
这几种对象都是引用(传给函数、放进 class 字段、放进全局都是同一个),都有 .free()。Mutex / WaitGroup / Once / AtomicInt / chan
是类型名,chan / mutex / wait_group / once / atomic_int 是构造函数(自己定义了同名函数或变量的以自己的为准);select 是上下文关键字。
native 函数里不能用。
没有闭包(匿名函数要用的东西从实参传);没有抢占(纯计算的协程要自己 go_yield());recv 没有 v, ok 两个返回值
(用 for v in c 或 c.closed());网络 I/O 是“阻塞调用 + 名额”而不是内核异步(见 §8.9);没有竞态检测;没有 GC(对象、通道自己 free)。
09类 / 结构体
9.1 定义
class Counter:
let base: int
let name: string
let tags: list<string>
func bump(step: int) -> int:
return self.base + step
end
static func describe() -> string:
return "a counter"
end
end- 字段:
let 名字: 类型 [= 默认值] ["json键"] - 方法:
func 名字(参数) -> 返回类型: … end,体内用self.字段 - 静态方法
static func:通过类名调用Counter.describe(),体内没有self(用了报错);可以当值传(run(Counter.describe));子类继承父类的静态方法。 不能通过实例调(c.describe()报'describe' 是 static func,要用类名调用:Counter.describe())。 - 没有静态字段:
static let是解析错误(类没有静态字段),类级别的共享状态用顶层let。 - 类名本身不是值:
let x: C = C是编译错误(类名 'C' 不能当值用)。
9.2 JSON 标签
字段类型后面跟一个字符串字面量,就是它在 JSON 里的键名;不写则用字段名:
class Config:
let message: string "msg"
let count: int "n"
end
print(json_encode(new Config("hello", 42))) # {"n": 42, "msg": "hello"}输出格式是 "键": 值(冒号后一个空格)。键的顺序不保证是声明顺序(走的是内部哈希表,每个类都不一样),
别拿字符串比较去断言 JSON,解析后按键取。
9.3 构造与访问
let c: Counter = new Counter(10, "a", ["x"])
print(c.bump(5)) # 15
c.base = 20 # 字段可写
print(c.name)new ClassName(...)的参数顺序与字段声明顺序一致;有继承时先父类字段、再自己的(§9.6)。- 字段默认值:
let step: int = 10这种字段可以在new时省略,只能从末尾开始省(带默认值的字段必须排在该类字段的最后;默认值只能是字面量)。个数不对是编译错误。 new出来的对象在堆上,不自动回收(见 §12)。
class Timer:
let name: string
let step: int = 10 # 带默认值的字段放最后
let label: string = "t"
end
let t1: Timer = new Timer("a") # step=10, label="t"
let t2: Timer = new Timer("a", 100) # label="t"
let t3: Timer = new Timer("a", 100, "x")9.4 嵌套结构体
字段类型是另一个 class 就是嵌套,层数不限,json_encode / json_decode 递归处理:
class Geo:
let lat: float
let lng: float
end
class Address:
let city: string
let geo: Geo
end
class User:
let name: string
let addr: Address
end
let u: User = new User("Alice", new Address("Beijing", new Geo(39.9, 116.4)))
print(u.addr.geo.lat)
print(json_encode(u))
# {"name": "Alice", "addr": {"city": "Beijing", "geo": {"lat": 39.9, "lng": 116.4}}}(键序不保证)构造要自底向上:先 new 内层,再作为参数传给外层。
9.5 对象和容器是引用,不是值
class 对象、list、dict 传参和赋值都只拷指针;改一处,所有别名都看得见。
只有标量(int / float / bool)和字符串是按值走的。
对 null 对象读字段 / 调方法是运行时错误(访问空对象的字段 'n',可 catch,未捕获退出码 3),不再静默读零值。
9.6 继承
class Shape:
let name: string
let scale: float = 1.0
func area() -> float:
return 0.0
end
func describe() -> string:
return self.name + " area=" + self.area()
end
static func kind() -> string:
return "shape"
end
end
class Rect extends Shape:
let w: float
let h: float
func area() -> float: # 覆盖
return self.w * self.h * self.scale # 父类字段直接 self.
end
end
class Square extends Rect:
let tag: string = "sq"
func describe() -> string:
return "[" + self.tag + "] " + super.describe() # 调父类版本
end
end
let r: Rect = new Rect("rect", 2.0, 3.0, 4.0) # 先父类字段(name, scale),再自己的(w, h)
print(r.describe()) # rect area=24
let shapes: list<Shape> = [new Shape("blank"), r, new Square("square", 1.0, 2.0, 2.0)]
for s in shapes:
print(s.describe()) # 按对象的真实类型分派(虚表)
end
let base: Shape = shapes[2]
print(type(base)) # Square —— type() 报真实类
let sq: Square = base as Square # 向下转型,运行时检查
print(Rect.kind()) # 静态方法也继承
obj_free(base) # 通过父类指针释放,按真实类型释放- 单继承。
extends的父类必须已定义(类 B 的父类 'A' 没有定义);继承链成环是编译错误。 - 子类不能重新声明父类已有的字段(
类 B 重复声明了父类 A 已有的字段 'n');覆盖方法签名必须一致(覆盖父类 A 的方法 'f' 时签名必须一致)。 - 方法调用一律按真实类型分派;
super.method(...)调父类的那个版本。super只能接方法,父类字段直接self.x。 - 向上转型自动(
let s: Shape = rect、放进list<Shape>、传给Shape形参)。 向下转型写x as Sub:运行时检查,不是那个类(或其子类)就是运行时错误对象不是 Rect(实际是 Circle),as 转换失败(可 catch);两个无关的类之间as是编译错误。 json_encode带上继承来的字段;json_decode到子类同样填父类字段。
9.7 C ABI 固定布局结构体 / 联合体
class 定义的是 Moon 对象,带隐藏字段和虚表。要和 C 结构、共享内存、Win32 消息
或者 PE 头逐字节对齐,用 cstruct / cunion:
cstruct Header pack(1):
kind: u8
length: u32
end
cunion NumberBits:
integer: u64
floating: f64
bytes: carray<u8, 8>
end这两种类型没有隐藏字段、没有虚表,也没有自动释放,字段按声明顺序排列。pack(N) 压
字段的对齐,align(N) 定整个聚合体的对齐,可以一起写。详见 §19.3。
10容器:list 与 dict
10.1 list
元素类型任意,运行时按元素类型选三种槽位之一:
| 元素类型 | 槽位 |
|---|---|
int / bool | i64(bool 存 0/1,读出来还是 bool) |
float | double |
string / 类对象 / any / list<...> / dict<...> | 指针 |
let names: list<string> = []
append(names, "alpha")
append(names, "beta")
names[0] = "ALPHA"
print(len(names)) # 2
print(names[0])
print(names[-1]) # 负下标从尾部数:beta
for n in names: print(n) end
print(json_encode(names))
let grid: list<list<int>> = [[1, 2], [3]]
print(grid[1][0]) # 3读写都是:列表下标越界:下标 7,长度 3,可 catch,未捕获退出码 3;pop 空列表同样报错。
负下标按 len + i 折算,折算后仍越界照样报。
list 相关内置:append pop slice sort reverse
len range list_free,参数类型在类型检查阶段就查
(append(list<int>, "x") 是编译错误,sort(list<Item>) 也是 ——
sort 只支持 list<int> / list<float> / list<string>)。
list<string> 拥有它的元素:append / xs[i] = s /
字面量 / 解码 都会复制一份归列表,xs[i] 读到的是借用指针(列表活着就有效)。
10.2 dict
键只能是 string,值可以是任意类型:
let stock: dict<string, Item> = {}
stock["pen"] = new Item("pen", 3) # 覆盖同名键时旧对象被释放
let groups: dict<string, list<int>> = {"a": [1, 2], "b": []}
append(groups["b"], 7)
let meta: dict<string, any> = {}
meta["x"] = json_decode("[1, 2]") # any 值 retain;覆盖 / dict_free 时 release
let nested: dict<string, dict<string, int>> = {"a": {"x": 1}}
print(len(stock))
for k in stock: print(k) end # 遍历键
print(json_encode(stock))
dict_free(stock)字面量的值、d[k] = v 的值都按声明的值类型转换(dict<string, float> 里放整数字面量没问题)。
11any 与 JSON
11.1 json_decode / json_encode
let args: any = json_decode("[1, 2, 3]")
let first: int = args[0] # any 下标仍是 any,赋值时自动转
value_free(args)
let out: dict<string, string> = {"message": "hi"}
return json_encode(out)json_encode 能编:标量、list<任意>、dict<string, 任意>、
类对象(字段可任意嵌套)、any。
11.2 直接解到具体类型
let x: T = json_decode(s),T 可以是类、list<T>、
dict<string, T>、标量,递归嵌套:
class Item:
let name: string
let qty: int
let ok: bool
end
class Order:
let id: string
let items: list<Item>
let tags: list<string>
end
let items: list<Item> = json_decode("[{\"name\":\"x\",\"qty\":7,\"ok\":true}]")
print(items[0].name)
let o: Order = new Order("o-1", items, ["a", "b"])
let s: string = json_encode(o)
let back: Order = json_decode(s)
print(back.items[0].qty)这一行会在转换完之后自动释放中间那棵 any 树,不用手写 value_free。
赋值 / 实参 / return / new / append 里直接解到具体类型的也一样。
11.3 any 的所有权:引用计数
- 存进变量 / 全局 / 字段 /
list<any>元素 → retain;普通赋值覆盖旧值 → release 旧值。 value_free(x)是 release,计数归零才真正销毁(递归 release 子节点)。a[0]/a["k"]返回的是借用指针,不改计数;存进变量才持有。- 别名要各自 free。
let raw: any = json_decode("[\"alive\"]")
let alias: any = raw
value_free(raw)
print(alias) # ["alive"],alias 还持有一份
let child: any = alias[0]
value_free(alias)
print(child) # "alive"
value_free(child) # 现在全部归零直接写在 print(...) / str() / json_encode() / bool() /
type() / len() 参数位置的 json_decode(...) 临时值用完自动释放。
pop(list<any>) 把引用交给调用方,自己要 free 一次。
value_live_count() 返回活着的节点数(测试里用来确认归零)。
11.4 null 与严格解析
null是独立的值:type(x)是"null",print出null, 转 int/float/string 是0/0.0/""。json_decode("[1, null, 2]")长度是 3,下标不错位。- 非法 JSON 一律返回
null,原因用json_last_error()取:"JSON 解析失败(偏移 N):…"。缺逗号 / 缺括号 / 前导 0 / 非法转义 / 顶层后有垃圾 / 未转义控制字符 / 孤立代理项都算错误。 - 字符串支持
\uXXXX(含代理对 → UTF-8)、\b\f\/; 编码时控制字符输出\u00XX,NaN / Inf 输出null;超出 int64 的整数退化成 float。 - 解析失败后再解到结构体:所有字段零值 / 空串,不崩。
11.5 any 的其它用法
for v in anyValue: … end # 必须是数组
print(len(anyValue))
print(anyValue) # 打印 JSON 文本
let v: any = 5 # 自动装箱
let mixed: list<any> = [1, "two", 3.0]11.6 纯字符串 JSON 工具(不建 any 树)
只取或只改少量字段时更直接,全部在 §16 的表里:json_get_str/int/float/bool
(带默认值,path 支持 "a.b[2].c")、json_has json_len
json_sub json_idx json_key_at、
json_set_str/int/float/bool/raw、json_merge json_valid json_quote。
12内存管理
这个语言没有 GC,也没有作用域析构。规则如下:
| 东西 | 谁管 |
|---|---|
| 字符串字面量 | 编译期保险库,永久 |
新造出来的字符串:+ 拼接、数字 / 布尔转字符串、s[i]、substring、内置函数 / str() / join / trim / replace / pop 的返回值 | 有界环形缓冲,自动回收最旧的(见下面「临时字符串」) |
| 存进全局 / 类字段 / 容器的字符串 | 自动复制一份长期持有(str_store),旧拷贝进入 32MB 的有界回收区 |
局部字符串变量 / 参数 / 循环变量 / catch 变量 | 拿着期间钉住不回收,函数返回时松开;不需要也不能手动释放 |
new 出来的对象 | 不回收,要么当单例复用,要么显式 obj_free |
json_decode 的 any 树 | 引用计数,value_free |
| list / dict | 显式 list_free / dict_free |
释放函数(都是类型化析构,空指针安全):
obj_free(o) # 按字段类型递归:字符串还给 str_store、嵌套对象/列表/dict/any 递归,再 free 对象
list_free(xs) # 元素按类型逐个释放(含 string),再释放容器
list_drop(xs) # 只释放容器:元素指向的对象 / 列表 / 字典不动(字符串元素是容器自己的拷贝,一并释放)
dict_free(d) # 值按类型递归释放,再释放字典
value_free(v) # any 的 release重建列表的写法要配 list_drop(2026-11 加)。这门语言里"从列表里去掉几个"通常写成"建一份新的、把要留的搬过去":
func prune() -> void:
let next: list<Device> = []
for d in devices:
if d.attached:
append(next, d)
end
end
let old: list<Device> = devices
devices = next
list_drop(old) # 旧容器还回去;里面的 Device 已经在 next 里了,不能动
end不写最后一行,每跑一次就留下一个旧容器(定时跑的话一天几万个)。这里不能用 list_free:它会把元素对象一起释放,
next 里拿着的就成了野指针。别的协程可能还拿着旧列表的时候(写时复制的全局表)两个都不能调,只能留着。
查这类泄漏:编译和运行都带环境变量 MOONS_MEM_SITES=1,然后隔一段时间取两次 mem_sites(100)
([["函数名:行号", 活着的个数], …],列表 / 字典 / 对象各是哪一行造的),只增不减的那几行就是。
平时不带这个变量,编译器不生成登记调用,没有开销。heap_histogram(40) 是更粗的一层:进程堆里各种大小的块各有多少。
诊断计数(压力测试里卡"循环 N 次后计数不涨"):
print(heap_live_count()) # new / 解码出来的对象数
print(value_live_count()) # 活着的 any 节点数
print(str_ring_stat(0)) # 活着的临时字符串份数(1 = 字节数,3 = 累计回收的份数)临时字符串(2026-11 起)
以前 "a" + b、"n=" + n、s[i] 的结果是 malloc 了就不管,永不回收:循环里拼字符串的程序内存只涨不降
(一个每秒拼几千次的桌面程序,开一天多出几百 MB)。现在它们和内置函数的返回值一样进有界环形缓冲,
写法不用改:
func worker(name: string) -> void:
let prefix: string = "[" + name + "] " # 局部变量拿着:钉住,这个函数跑多久它活多久
while not should_stop():
log(prefix + "tick " + now_ms()) # 中间结果:这条语句用完就可以回收
sleep_ms(10)
end
end规则:
- 局部变量、参数、循环变量、
catch变量拿着的字符串钉住不回收;换成别的值或者函数返回时松开。 - 表达式的中间结果(
("a" + b) + f()、g(a + b, f())、传给内置函数的实参)在这条语句结束前不回收, 哪怕后面的调用跑了很久、造了很多字符串。 - 全局变量、类字段、列表 / 字典元素、通道里的字符串、
go的实参各有自己的拷贝,和缓冲无关。 - 没有任何东西拿着的字符串,至少留 5 秒;之后缓冲满了从最旧的回收,没满的话放到 30 秒也回收。每条线程最新的几份任何时候都不回收。缓冲按线程分片(每条线程一片, 每片 2048 条 / 2MB),几条线程同时拼字符串不抢同一把锁。
- 唯一要注意的:把字符串的地址交给编译器看不见的地方长期保存(原生结构体的指针字段、DLL 那边存起来的
const char*)。以前拼接结果永不回收所以碰巧没事,现在要先存进全局 / 字段再交出去,或者自己拷一份。cstr("…")只收字面量,不受影响。
str_ring_limits(条数, 字节数, 最短保留毫秒, 涂不涂) 只给测试用;不改程序也可以用环境变量
MOONS_STR_RING=8,0,200,1 让任何一个程序在这种条件下跑自己的测试。
长跑的服务:要么复用对象,要么在每个请求结束时显式释放。
13模块系统
13.1 import
源码根 = 入口文件(传给 gtc 的那个 .gt / .moons)所在目录。
不带 ./ 的路径按这个顺序找:
- 源码根
- 命令行显式给出的每个
-I <dir> <源码根>/.moonlang/packages%USERPROFILE%/.moonlang/packages<gtc.exe 所在目录>/packages(发行版标准包)- 导入者自己所在目录(老写法回退)
以 ./ 或 ../ 开头的路径只相对导入者所在目录。每个基目录下依次试:
<spec>.gt、<spec>.moons、<spec>/mod.gt、
<spec>/mod.moons、<spec>(写全扩展名)、<spec>/ 是目录 →
目录即包,按文件名顺序加载目录下全部 *.gt / *.moons;同名时 .gt 优先。
import "internal/storage/store" # 根相对(推荐,任何文件里写法都一样)
import "./reply" # 显式相对本文件
import "internal/engine" # 目录即包:internal/engine/*.moons 全部
import "reply" # 老写法(相对本文件),仍可用
import "sys/windows" # 从编译器 packages 目录加载标准包命名空间是扁平的:import "internal/storage/store" 之后直接写
Store,不是 store.Store。所以模块之间不能重名(按 Go 那种"包名当前缀"的习惯起名)。
循环导入不报错(第二次见到就跳过)。找不到模块时报错会列出试过的每个位置。
13.2 from … import(可选写法)
from "pkg/util" import helper, other as alias
from "pkg/util" import *因为命名空间本来就是扁平的,实际效果和 import "pkg/util" 一样。
13.3 global
global counter, total声明"这些名字指的是全局",用于消歧义。
14extern:调用 DLL
14.1 动态惰性绑定(托管模式)
extern "user32.dll" func MessageBoxA(hwnd: int, text: string, caption: string, type: int) -> int
extern "kernel32.dll" func GetTickCount() -> int as ticks
MessageBoxA(0, "hello", "title", 0)
print(ticks())- 语法:
extern "库名" func 符号(参数: 类型, …) -> 返回类型 [as 本地名] - 没有函数体,编译器生成一个惰性绑定的真函数:第一次调用时
LoadLibrary+GetProcAddress并缓存结果。 - 解析失败不崩,返回零值(可选依赖没装时,比崩在调用点好查);失败原因写在日志里。
- 参数 / 返回类型只能用标量:
int/float/bool/string/void。 as 本地名用于符号名与希望使用的名字不同时(或避免和内置函数重名)。- 可以显式写成
extern dynamic "user32.dll" ...;不写dynamic时也是这个模式。 - 库名或 ABI 后面加
required,解析失败就地 trap,不再返回零值。
14.2 原生直接链接
extern native "kernel32.lib" system required func CreateThread(
attributes: ptr<void>, stack_size: usize,
entry: cfunc<system>(ptr<void>) -> u32, parameter: ptr<void>,
flags: u32, thread_id: ptr<u32>) -> ptr<void>
extern native "user32.lib" cdecl required func wsprintfA(
output: ptr<u8>, format: ptr<u8>, ...) -> i32extern native "库名" [abi] [required] func 符号(参数...) -> 返回类型 [as 本地名]extern native把符号直接交给链接器,Win32、CRT、静态库、导入库都用这种方式;没有LoadLibrary包装,也不会找不到就返回零值。- 库或符号缺了,链接期就报出来。
required在这里只是显式标明它是硬依赖,直接链接本身已经是硬依赖。 - ABI 可写
c、cdecl、system、stdcall、fastcall、thiscall、vectorcall。 - 原生类型、函数指针和 C 可变参数
...只有extern native能用。 - Windows x64 上这几种约定最后都是同一个平台 ABI;保留拼写便于阅读,也便于将来用于区分调用约定的目标平台。
15GUI 与前后端桥
WebView2 窗口 + JS 调后端。核心流程:
let ok: bool = gui_init()
if not ok:
print("GUI init failed")
end
let opts: dict<string, int> = {"frameless": 1, "center": 1}
let winId: int = gui_create("我的应用", 680, 560, opts)
# 注册后端方法:JS 里 await MoonGUI.call("greet", ["世界"])
func greet(argsJson: string) -> string:
let args: any = json_decode(argsJson)
let name: string = args[0]
value_free(args)
let out: dict<string, string> = {"message": "你好, " + name + "!"}
return json_encode(out)
end
gui_expose("greet", greet)
# 接收前端 MoonGUI.send() 的消息
func on_message(win: int, msg: string) -> void:
if msg == "close":
gui_quit()
end
end
gui_on_message_win(winId, on_message)
gui_load_html_win(winId, "<html>…</html>")
gui_show_win(winId, 1)
gui_run()gui_expose 的处理函数签名固定是 func(string) -> string ——
参数是 JSON 数组字符串,返回 JSON 字符串。
15.1 内嵌 HTML 不暴露明文
gui_load_html_win_xor(winId, """
<!DOCTYPE html>
<html><body>…</body></html>
""")第二个参数必须是字符串字面量(传变量不报错,但这条调用会被静默丢弃):编译期把内容打进和 --resources 同一套保险库
(LZ77 + AES-256-CTR,密钥由每次编译现掷的 seed 派生),运行时再解开加载 ——
用记事本打开 exe 看不到 HTML 源码。名字里的 "xor" 是历史遗留,第三个参数已忽略。
15.2 异步调用
gui_expose_async_win(winId, "api", handler) 注册的处理函数跑在别的线程上,
用 gui_current_call_id() 拿 callId,处理完
gui_call_resolve(winId, callId, 结果JSON)。推事件用
gui_publish(事件名, JSON) / gui_publish_win(winId, 事件名, JSON)。
16内置函数速查
输入函数名的任意片段,下面的表格和名称块会随之筛选,只保留匹配项。
16.1 核心内置
| 函数 | 签名 | 说明 |
|---|---|---|
print(a, b, …) | (任意…) -> void | 多个参数之间一个空格,末尾换行;print() 只换行;list/dict/对象/any 打 JSON |
len(x) | (list|string|dict|any) -> int | 长度;string 按字符。s.length / xs.length 等价(dict 上别用 .length,见 §17) |
str(x) int(x) float(x) bool(x) | (值) -> T | 转换,见 §4.6 |
type(x) | (值) -> string | 类型名 |
abs(x) | 同参数类型 | |
sqrt(x) pow(a,b) | -> float | |
min(a,b) max(a,b) | 同第一个参数类型 | |
time() | -> int | Unix 秒 |
sleep(n) | -> void | |
input() | -> string | 读一行 |
range(n) / range(a,b) | -> list<int> | |
append(xs, v) | -> void | 元素类型编译期检查 |
pop(xs) | -> T | 弹出并返回最后一个 |
slice(xs, a, b) | -> list<T> | 新列表,Python 风格负下标 |
sort(xs) reverse(xs) | -> list<T> | 原地,返回自身;sort 只支持 int/float/string |
split(s, sep) | -> list<string> | |
join(xs, sep) | (list<string>, string) -> string | |
substring(s, start, count) trim(s) replace(s, from, to) | -> string | substring 按字符、负 start 从尾数、越界截断 |
json_encode(x) | -> string | |
json_decode(s) | -> any | |
value_free(v) list_free(xs) list_drop(xs) dict_free(d) obj_free(o) | -> void | 见 §12 |
value_get_index(v,i) value_get_key(v,k) | -> any | 显式取子节点 |
value_to_string(v) value_to_int(v) value_to_float(v) | -> string/int/float | 显式转换 |
at_str(v,i) at_int(v,i) at_float(v,i) | -> string/int/float | 取下标并转换,一步 |
value_live_count() heap_live_count() json_last_error() | 诊断 |
GUI 核心
16.2 扩展内置
扩展内置只用标量签名(int / float / bool / string / void;c 表示回调,
签名固定 func(string) -> string)。复杂结构一律走 JSON 字符串。
命名约定:脚本里叫 foo,运行时实现叫 static_foo。
下表"签名"列用 参数 -> 返回,类型缩写:
i=int f=float b=bool s=string v=void c=回调。
字符串
| 函数 | 签名 | 说明 |
|---|---|---|
str_len(s) | s -> i | |
str_sub(s, start, count) | sii -> s | |
str_find(s, needle, from) | ssi -> i | 找不到返回 -1 |
str_rfind(s, needle) | ss -> i | |
str_replace(s, from, to) | sss -> s | 全部替换 |
str_lower(s) str_upper(s) str_trim(s) | s -> s | |
str_starts(s, p) str_ends(s, p) str_contains(s, p) | ss -> b | |
str_split(s, sep) | ss -> s | 返回 JSON 数组字符串 |
str_join(jsonArray, sep) | ss -> s | |
str_repeat(s, n) | si -> s | |
str_pad_left(s, width, pad) | sis -> s | |
str_code(s, i) | si -> i | 第 i 个字节 |
str_from_code(c) | i -> s | |
str_fmt_int(v, width) | ii -> s | 左补 0 |
str_fmt_float(v, digits) | fi -> s | |
str_json_escape(s) | s -> s | |
str_parse_int(s) | s -> i | |
str_parse_float(s) | s -> f | |
str_equal_fold(a, b) | ss -> b | 忽略大小写比较 |
str_keep(s) | s -> s | 换成永不回收的一份(全局/字段现在自动做,一般不用) |
res_read(path) | s -> s | 读嵌进 exe 的资源(内存里是密文,按需解一份) |
JSON(纯字符串操作)
| 函数 | 签名 | 说明 |
|---|---|---|
json_get_str(json, path, def) | sss -> s | path 支持 "a.b[2].c",缺就回落默认值 |
json_get_int(json, path, def) | ssi -> i | |
json_get_float(json, path, def) | ssf -> f | |
json_get_bool(json, path, def) | ssb -> b | |
json_has(json, path) | ss -> b | |
json_len(json, path) | ss -> i | 数组长度 / 对象键数 |
json_sub(json, path) | ss -> s | 取子树,仍是 JSON |
json_idx(json, path, i) | ssi -> s | 第 i 个元素的子 JSON |
json_key_at(json, path, i) | ssi -> s | 对象的第 i 个键名 |
json_set_str json_set_int json_set_float json_set_bool | (json, key, v) -> s | 返回新 JSON(顶层对象) |
json_set_raw(json, key, raw) | sss -> s | 值原样嵌入,用于放数组/对象 |
json_merge(a, b) | ss -> s | 后者覆盖前者(顶层) |
json_valid(s) | s -> b | |
json_quote(s) | s -> s | 文本 → 带引号的 JSON 字面量(注入 JS 时用) |
json_last_error() | -> s | |
value_live_count() heap_live_count() | -> i | |
mem_sites(n) | i -> s | 活着的列表 / 字典 / 对象各是哪一行造的,JSON [["函数:行", 个数], …];编译和运行都要 MOONS_MEM_SITES=1 |
heap_histogram(n) | i -> s | 进程堆里各种大小的块各有多少,JSON {"blocks":…,"bytes":…,"sizes":[[大小, 块数], …]} |
str_ring_stat(what) | i -> i | 临时字符串缓冲:0 活着的份数,1 字节数,2 队里的记录数,3 累计回收的份数 |
str_ring_pins(s) | s -> i | 这份字符串被几个局部变量拿着;不是缓冲里的回 -1(测试用) |
str_ring_limits(items, bytes, minAgeMs, poison) | iiii -> v | 测试用:调小每片预算 / 最短保留时间、回收前涂掉内容;0 = 不改 |
文件与目录
| 函数 | 签名 | 说明 |
|---|---|---|
file_read(p) | s -> s | |
file_write(p, data) file_append(p, data) | ss -> b | |
file_append_base64(p, b64) | ss -> i | 追加二进制;返回写入字节数,负数=失败 |
file_read_base64(p) | s -> s | 二进制读成 base64 |
file_head_hex(p, n) | si -> s | 头 N 字节的十六进制(认魔数) |
file_exists(p) file_delete(p) | s -> b | |
file_size(p) file_mtime(p) | s -> i | |
file_move(src, dst) file_copy(src, dst) | ss -> b | move 跨卷退化成复制+删除 |
dir_create(p) | s -> b | 递归建 |
dir_list(p) | s -> s | JSON 数组 |
dir_delete(p) | s -> b | 递归删;不跟随 junction,拒绝盘符根 |
path_has_reparse(p) | s -> b | 路径上有没有 junction/symlink |
path_join(a, b) path_base(p) path_dir(p) | -> s | |
app_data_dir(name) | s -> s | %AppData%\<name>,自动建 |
exe_path() exe_dir() temp_dir() | -> s |
时间
| 函数 | 签名 | 说明 |
|---|---|---|
now_ms() | -> i | Unix 毫秒 |
tick_ms() | -> i | 单调时钟,只能做差 |
now_str(fmt) | s -> s | 本地时间,fmt 见 strftime |
ms_to_str(ms, fmt) | is -> s | |
sleep_ms(n) | i -> v |
摘要与编码
| 函数 | 签名 |
|---|---|
sha256_hex(s) | s -> s |
hmac_sha256_hex(key, msg) | ss -> s |
base64_encode(s) base64_decode(s) url_encode(s) | s -> s |
uuid_str() | -> s |
rand_int(a, b) | ii -> i |
rand_hex(n) | i -> s |
HTTP 客户端
| 函数 | 签名 | 说明 |
|---|---|---|
http_request(method, url, headersJson, body) | ssss -> s | |
http_get(url, headersJson) | ss -> s | |
http_get_timeout(url, headersJson, ms) | ssi -> s | |
http_post_json(url, headersJson, body) | sss -> s | |
http_download(url, headersJson, dst, name) | ssss -> i | |
remote_request(method, path, queryJson, bodyJson, encrypted, token) | ssssbs -> s | |
remote_configure(base, clientType, capabilities, entitlementModel) | ssss -> v | |
remote_async(…, outPath) | ssssbss -> b | |
verify_p256(pubkeyHex, data, sigHex) | sss -> i | |
sha256_of_file(p) | s -> s | |
unwrap_component(binPath, dstPath) | ss -> i | |
set_component_dir(p) | s -> i |
线程
| 函数 | 签名 | 说明 |
|---|---|---|
thread_start(name, cb) | sc -> b | cb 是 func(string) -> string 的循环体 |
thread_stop(name) | s -> v | 只置停止标志,不等线程退出 |
thread_running(name) | s -> b | |
thread_should_stop(name) | s -> b | 循环体每拍查一次 |
go_active() | -> i | 还没跑完的协程数(排队 + 在跑 + 在睡),见 §8.9 |
go_workers() | -> i | 协程调度器现在有几条工作线程 |
go_yield() | -> v | 让出一下,别的协程先跑 |
go_lock_thread() / go_unlock_thread() | -> v | 钉在当前线程上 / 解除,见 §8.9 |
go_stack_mb(n) / go_block_enter() / go_block_leave() | -> v | 协程栈上限 / 阻塞调用前后,见 §8.9 |
chan(n) / mutex() / wait_group() / once() / atomic_int(v) | 协程同步对象的构造函数,方法见 §8.10 |
本地 HTTP 服务器
| 函数 | 签名 | 说明 |
|---|---|---|
http_server_start(port, handler) | ic -> i | port 传 0 = 随机;返回实际端口 |
http_publish(event, json) | ss -> v | 推给所有 SSE 连接 |
http_publish_to(winId, event, json) | sss -> v | 定向 |
http_file_root(urlPrefix, dir) | ss -> v | GET/HEAD 由运行时直接供,带 Range |
http_static_add(urlPath, contentType, content) | sss -> v | |
video_frame_arm(sessionId, x, y, w, h) | siiii -> i | |
video_frame_stop(sessionId) | s -> i | 之后回 410 |
video_frame_clear() | -> v | 会话作废,回 404 |
数据库(SQLite)
| 函数 | 签名 | 说明 |
|---|---|---|
db_open(handle, path) | ss -> b | |
db_close(handle) | s -> v | |
db_ready(handle) | s -> b | |
db_exec(handle, sql, paramsJson) | sss -> s | {ok,changes,lastInsertId} |
db_query(handle, sql, paramsJson) | sss -> s | [{列:值}] |
db_query_value(handle, sql, params, def) | ssss -> s | 第一行第一列 |
db_error() db_version() | -> s |
系统
| 函数 | 签名 | 说明 |
|---|---|---|
app_exit(code) | i -> v | 立刻结束进程(不析构、不等别的线程)。界面程序 gui_run() 返回后收完尾用它退出 |
machine_id() | -> s | |
os_env(name) | s -> s | |
credential_pair_sha256(targetA, targetB, context) | sss -> s | 从 Windows 通用凭据读取两份值,返回 SHA256(valueA:valueB:context);凭据明文不进入脚本层,失败返回空串 |
open_url(url) | s -> b | |
clipboard_set(s) clipboard_get() | s -> b / -> s | |
is_admin() | -> b | |
single_instance(name) | s -> b | 拿到锁返回 true |
log_init(path) log_line(s) log_path() | - | 每次启动清空 |
process_exists(name) | s -> b | |
proc_run(exe, args, waitMs) | ssi -> i | 目标要管理员时回退 ShellExecuteEx |
reg_read(root, subkey, name) | sss -> s | 读不到回空串 |
reg_write(root, subkey, name, v) | ssss -> b | REG_SZ |
reg_write_int(root, subkey, name, v) | sssi -> b | REG_DWORD |
reg_delete_key(root, subkey) | ss -> b | 连子键一起删 |
shell_create_shortcut(lnk, target, args, workdir, icon, desc) | ssssss -> b | |
shell_folder(which) | s -> s | desktop/programs/startmenu/localappdata/appdata/programfiles |
shell_pick_folder(title, initDir) | ss -> s | |
resource_extract(moonPath, dstFile) | ss -> b | |
arg_count() arg_at(i) | -> i / i -> s | 命令行参数(0 是程序自己) |
screen_size() | -> s | {"w":..,"h":..} |
screen_monitor_at(x, y) | ii -> s | {"monitor":{..},"work":{..},"dpi":..} |
窗口 / 热键 / 光标
| 函数 | 签名 | 说明 |
|---|---|---|
win_find(titleSub, className) | ss -> i | 返回 hwnd |
win_title(hwnd) | i -> s | |
win_rect(hwnd) | i -> s | {"x":..,"y":..,"w":..,"h":..} |
win_foreground() | -> i | |
win_maximized(hwnd) win_minimized(hwnd) | i -> b | |
win_screen_to_client(hwnd, x, y) | iii -> s | |
cursor_visible() | -> b | |
hotkey_register(id, "f9") | is -> b | |
hotkey_clear() | -> v | |
hotkey_poll() | -> i | 触发的 id,没有则 0(轮询,不是回调) |
GUI 窗口扩展
托盘
tray_on_event 的回调收
{"event":"left|right|double","x":..,"y":..};tray_add(tooltip) 用 exe 自己的图标。
16.3 原生系统内置
这一组只在 native / unsafe 里用,编出来是 LLVM 指令、编译期常量或者一次 CRT 调用,不经过托管运行时:
| 函数 | 说明 |
|---|---|
cstr("literal") / wstr("literal") | 零结尾的 ptr<u8> / ptr<u16> 字面量指针 |
size_of(value) / align_of(value) | 静态类型大小 / 对齐,编译期常量 |
memory_copy / memory_set | 字节复制 / 填充 |
memory_compare / memory_find_byte | 字节比较 / 查找 |
atomic_load atomic_store atomic_exchange | seq_cst 原子读、写、交换 |
atomic_compare_exchange | 原子比较交换 |
atomic_fetch_add/sub/and/or/xor | 原子读改写,返回修改前的值 |
atomic_fence() | seq_cst 全栅栏 |
compile_stamp() | 每次编译随机一个 u32,同一次编译内保持一致 |
数学内置 abs、sqrt、pow、min、max、
sin、cos、tan、atan、atan2、floor、
ceil、round、is_finite 在原生函数里也有原生实现,不需要回到运行时。
17限制与陷阱清单
这一章把现在还会出问题的地方集中在一处,分三档:会导致代码生成失败的、不报错但需要自行 留意的、以及设计上就是这样的硬限制。
早先那批"类型检查放行、代码生成阶段才失败"的问题(字符串拼数字、任意值 case、终结语句后有代码、
漏 return、除零、空对象、下标越界、字节/字符口径、循环外 break、print 分隔符)
现在要么是带行号的编译错误,要么是可 catch 的运行时错误,不在这张表里,清单见 §7.7。
17.1 会导致代码生成失败的(报错信息不直观,但行号准确)
| # | 触发 | 怎么办 |
|---|---|---|
| A | d.length(在 dict 上用 .length) | 用 len(d) |
17.2 不报错,但需要自行留意
| # | 行为 | 怎么办 |
|---|---|---|
| C | 整数溢出静默回绕(两补码) | 自己判范围 |
| D | json_encode 的键序不是声明顺序(内部哈希表顺序,每个类都不同) | 别用字符串比较断言 JSON;解析后按键取 |
| E | substring 越界只截断,不像 s[i] 那样报错 | 要严格就先 len() 判 |
| F | int("zz") 解析失败返回 0,不报错 | 先自己校验,或用 str_parse_int |
| G | 字符串 as int / as float 不解析,拿到的是指针值 | 用 int(s) / float(s) |
17.3 设计上的硬限制
| # | 限制 | 怎么办 |
|---|---|---|
| 1 | 没有闭包:匿名函数不能捕获外层局部 | 共享状态放顶层 let |
| 2 | 只有全局对象的方法能当回调 | 接收者用顶层 let |
| 3 | 块风格不能混用 | 全文件统一 :/end 或 {/} |
| 4 | 容器变量严格不变:list<int> ≠ list<float> | 传字面量,或建对的类型 |
| 5 | dict 键必须是 string | 数字键自己 str() |
| 6 | 顶层语句不能读还没执行到声明的全局 | 挪到函数体里,或调整顺序 |
| 7 | 模块命名空间扁平,跨模块不能重名 | 名字带包前缀 |
| 8 | 对象 / list / dict 是引用:传参和赋值都是别名,改一处全看得见 | 要副本自己逐字段建 |
| 9 | 对象不自动回收(new 在堆上) | 单例复用,或请求结束 obj_free |
| 10 | any 别名要各自 value_free | 每个持有者各自 free 一次 |
| 11 | for i = a to b 上界不含 b | 要含就写 b + 1 |
| 12 | << >> 比 + - 松、比比较紧:1 << 2 + 1 是 8 | 拿不准就加括号 |
| 13 | ** 结果永远是 float | 要 int 结果自己 int(...) |
| 14 | 逻辑运算只接受 bool | if n != 0: 而不是 if n: |
| 15 | ! 不是运算符 | 取反用 not |
| 16 | 没有块注释,只有 # | |
| 17 | 默认值只能是字面量,且只能放在参数表 / 字段表末尾 | 复杂默认值在函数体里判 |
| 18 | catch e 的 e 固定是 string;没有 finally、没有多段 catch;throw 必须带值 | 需要分类就在消息里带前缀 |
| 19 | super 只能接方法,没有 super.字段 | 父类字段直接 self.x |
| 20 | 没有静态字段(static let 是解析错误) | 顶层 let |
| 21 | 单继承;子类不能重声明父类字段;覆盖签名必须一致 | |
| 22 | switch 不做穷尽性证明:非 void 函数里每个 case 都 return 也要有 default | 加 default |
| 23 | gui_load_html_win_xor 第二参必须是字符串字面量 | 传变量不报错,但整条调用会被丢掉,什么都不加载 |
| 24 | 内置函数返回的字符串保存在有界环形缓冲里 | 存进全局 / 字段会自动钉住;不要在局部长时间持有 |
| 25 | 裸指针解引用、取地址、指针转换 / 排序、原生数组下标只能在 unsafe | 给函数加 unsafe,或使用最小 unsafe: ... end 块 |
| 26 | native 不能调用托管函数,也不能使用托管值 | 边界只传 C ABI 类型;复杂数据传指针 + 长度 |
| 27 | noexcept / noalloc 编译器真会查 | 调用链里不许出现会抛错 / 会分配的调用 |
| 28 | dllmain 只能有一个且签名固定 | (ptr<void>, u32, ptr<void>) -> bool/i32,必须 unsafe noexcept noalloc |
| 29 | cstruct / cunion 没有方法、继承、隐藏字段和自动释放 | 按 C POD 管理资源生命周期 |
| 30 | atomic<T> 只支持整数、bool 或指针,当前顺序固定 seq_cst | 不能自选 relaxed/acquire/release |
| 31 | 原生回调没有闭包 | 用 thread_local、共享状态或 ptr<void> 参数传上下文 |
18完整示例
18.1 结构体 + 嵌套 JSON 往返
class Geo:
let lat: float
let lng: float
end
class Address:
let city: string
let street: string
let geo: Geo
end
class User:
let name: string
let age: int
let addr: Address
end
class ApiResponse:
let code: int
let message: string "msg"
let data: User
end
func main() -> void:
# 自底向上构造
let geo: Geo = new Geo(39.9, 116.4)
let addr: Address = new Address("Beijing", "Chaoyang Rd", geo)
let user: User = new User("Alice", 28, addr)
let resp: ApiResponse = new ApiResponse(0, "ok", user)
print(json_encode(resp))
# {"code": 0, "msg": "ok", "data": {"name": "Alice", "age": 28,
# "addr": {"city": "Beijing", "street": "Chaoyang Rd", "geo": {"lat": 39.9, "lng": 116.4}}}}
# (键序不保证)
# 反序列化(自动释放中间的 any 树)
let raw: string = "{\"code\":0,\"msg\":\"success\",\"data\":{\"name\":\"Bob\",\"age\":30,\"addr\":{\"city\":\"Shanghai\",\"street\":\"Nanjing Rd\",\"geo\":{\"lat\":31.2,\"lng\":121.5}}}}"
let back: ApiResponse = json_decode(raw)
print(back.message)
print(back.data.addr.geo.lat)
end
main()18.2 容器与释放
class Item:
let name: string
let qty: int
end
let base: int = heap_live_count()
let stock: dict<string, Item> = {}
stock["pen"] = new Item("pen", 3)
stock["ink"] = new Item("ink", 9)
print(stock["ink"].qty) # 9
let groups: dict<string, list<int>> = {"a": [1, 2], "b": []}
append(groups["b"], 7)
print(groups["a"][1] + groups["b"][0]) # 9
let names: list<string> = []
append(names, "alpha")
append(names, "beta")
print(join(names, ",")) # alpha,beta
print(names[-1]) # beta
dict_free(stock)
dict_free(groups)
list_free(names)
print(heap_live_count() - base) # 018.3 GUI 后端接口
class GreetResponse:
let message: string
end
func greet(argsJson: string) -> string:
let args: any = json_decode(argsJson)
let name: string = args[0]
value_free(args)
return json_encode(new GreetResponse("你好, " + name + "!"))
end
let ok: bool = gui_init()
if not ok:
print("GUI init failed")
app_exit(1)
end
let opts: dict<string, int> = {"frameless": 1, "center": 1}
let winId: int = gui_create("MoonLang GUI", 680, 560, opts)
gui_expose("greet", greet)
gui_load_html_win_xor(winId, """
<!DOCTYPE html>
<html><head><meta charset="utf-8"></head>
<body>
<button onclick="go()">打招呼</button><pre id="out"></pre>
<script>
async function go() {
const r = await MoonGUI.call("greet", ["世界"]);
document.getElementById("out").textContent = JSON.stringify(r);
}
</script>
</body></html>
""")
gui_show_win(winId, 1)
gui_run()
gui_quit()18.4 模块与回调
# src/main.moons
import "internal/storage/store" # 从源码根解析
import "./helpers" # 相对本文件
let store: Store = new Store(app_data_dir("MyApp"))
func worker(name: string) -> string:
while not thread_should_stop(name):
store.tick()
sleep_ms(200)
end
return ""
end
thread_start("ticker", worker)
thread_start("inline", func(name: string) -> string:
log_line("inline thread " + name)
return ""
end)19原生系统编程与 Windows DLL
前面 18 章讲的是托管部分:字符串、list、any 的生命周期由运行时管。这一章是另一半,写给 C ABI 写的 —— 编出的 DLL 由 C/C++、注入器或 Windows 直接加载,中间不需要再写一层 C++。
两部分共用同一个编译器和同一套语法,边界只有一条:原生一侧的类型必须是固定布局,不涉及 引用计数、异常和运行时。
19.1 编译原生 DLL
gtc.exe core.gt --native-dll --static-crt -o core_x64.dll--native-dll:生成直接导出的 Windows DLL,可包含一个自定义DllMain。--static-crt:静态链接 CRT,部署时不依赖目标机的 VCRUNTIME / MSVCP DLL。--emit-layout-json layout.json:只输出 C 聚合体的布局,不链接 DLL。DLL 和布局是两种产物,都需要时分别编译两次。- 后缀写
.gt,旧的.moons也支持。
export native system unsafe noexcept noalloc func add(a: i32, b: i32) -> i32:
return a + b
end
dllmain system unsafe noexcept noalloc func on_dll_event(
module: ptr<void>, reason: u32, reserved: ptr<void>) -> bool:
return true
endexport native 导出的就是原符号名,中间没有托管包装。调用约定 c、cdecl、
system、stdcall、fastcall、thiscall、vectorcall 都支持;
Windows x64 上它们最后都是同一个平台 ABI。
19.2 native、unsafe、noexcept、noalloc 与 dllmain
[export] native [abi] [unsafe] [noexcept] [noalloc] func name(...) -> T
dllmain [abi] unsafe noexcept noalloc func name(ptr<void>, u32, ptr<void>) -> bool这几个修饰符编译器会真的检查:
native:函数体内只能使用原生 ABI 类型,只能调用另一个native、extern native或cfunc,不能访问托管运行时。unsafe:允许取地址&x、解引用*p、p->field、指针运算 / 转换和原生数组下标;非原生函数里也能写unsafe: ... end,缩小作用范围。noexcept:整条调用链中不得出现可能抛异常的调用。noalloc:同样,不得出现可能做托管分配的调用。dllmain:一个程序最多一个,必须unsafe noexcept noalloc,参数固定(ptr<void>, u32, ptr<void>),返回bool或i32。
所以 DllMain、hook、系统回调里不会冒出惰性初始化、托管分配或者异常展开 —— 在 loader lock
里做这三件事,是死锁和随机崩溃的常见来源。
19.3 C 结构体、联合体和固定数组
cstruct Header pack(1):
kind: u8
length: u32
end
cstruct SharedState align(8):
state: volatile<i32>
sequence: atomic<u32>
headers: carray<Header, 64>
end
cunion Bits:
integer: u64
floating: f64
bytes: carray<u8, 8>
end- 字段就按声明顺序排,没有对象头、没有隐藏的引用计数、没有虚表,尾巴上也不挂元数据。
pack(N)限制字段最大对齐;align(N)设置聚合体对齐;二者可同时写。N 必须是 1~4096 的 2 次幂。cunion的所有字段从偏移 0 开始,大小按最大字段和聚合体对齐计算。carray<T, N>是原地放 N 个 T,不会退化成指针,照样用a[i]读写。size_of(value)/align_of(value)只看值的静态类型,根本不去读 value。
export native system unsafe noexcept noalloc func header_size() -> usize:
let header: Header = null
return size_of(header)
end与 C 头文件对接时,padding 不要靠目测:用 --emit-layout-json 输出一份,size / align / offset 逐项核对。
19.4 裸指针、字段和内存
native system unsafe noexcept noalloc func advance(base: ptr<u32>, index: usize) -> u32:
let slot: ptr<u32> = base + index # 按 u32 元素移动
*slot = *slot + 1
return *slot
end
native system unsafe noexcept noalloc func sum_point(point: ptr<WIN_POINT>) -> i32:
return point->x + point->y
end&value/&value.field/&array[i]取地址,*pointer读或写。p + n/p - n按目标元素大小缩放,不是按字节;同类型指针相减得到相差的元素数。- 指针和
null可以直接比相等;比大小、指针与整数互转要在unsafe里显式as。 - 需要按字节偏移时先转成
ptr<u8>,偏移后再转回ptr<T>。
memory_copy(destination, source, byte_count)
memory_set(destination, byte_value, byte_count)
let order: i32 = memory_compare(left, right, byte_count)
let hit: ptr<u8> = memory_find_byte(memory, byte_value, byte_count)memory_compare / memory_find_byte 走的是 CRT 优化过的实现,分块扫描内存时性能足够。
扫大片地址之前先用 VirtualQuery 把不可读的页筛掉,再分给几个 CreateThread 线程;
未经筛选直接解引用会访问到不可读的页面。
19.5 volatile、原子操作和共享内存偏移
cstruct SharedControl align(8):
ready: volatile<u32>
candidate_count: atomic<u32>
generation: atomic<u64>
end
export native system unsafe noexcept noalloc func set_candidate_count(
mapping_base: ptr<u8>, offset: usize, value: u32) -> void:
let control: ptr<SharedControl> = (mapping_base + offset) as ptr<SharedControl>
atomic_store(&control->candidate_count, value)
endvolatile<T> 只保证每次访问都真的生成一条 load / store,用于会被外部修改的字段。它不是同步原语;跨线程、跨模块的同步得用 atomic<T>:
atomic_load, atomic_store, atomic_exchange, atomic_compare_exchange
atomic_fetch_add, atomic_fetch_sub, atomic_fetch_and, atomic_fetch_or
atomic_fetch_xor, atomic_fence原子操作眼下一律是顺序一致(seq_cst)。atomic<T> 支持整数、bool 和指针,地址得满足对应
类型的自然对齐。每线程独立的原生状态用 thread_local let guard: u32 = 0。“共享内存基址 + 固定偏移 +
C 布局字段 + 原子读写”到这里就能直接表达,不需要在 C++ 里为每个字段单独写 getter / setter。
19.6 C 函数指针、回调、IAT 与虚表
extern native "kernel32.lib" system required func CreateThread(
attributes: ptr<void>, stack_size: usize,
entry: cfunc<system>(ptr<void>) -> u32, parameter: ptr<void>,
flags: u32, thread_id: ptr<u32>) -> ptr<void>
native system unsafe noexcept noalloc func worker(parameter: ptr<void>) -> u32:
return 0
end
export native system unsafe noexcept noalloc func start_worker() -> ptr<void>:
let callback: cfunc<system>(ptr<void>) -> u32 = worker
return CreateThread(null, 0, callback, null, 0, null)
endcfunc<abi>(...) -> R 是一个写明了 ABI 的裸函数指针。GetProcAddress 的返回值、
IAT 槽里的地址、COM / DirectInput 虚表里的槽位,在 unsafe 里转成匹配的 cfunc 后即可直接调用:
let raw: ptr<void> = GetProcAddress(module, cstr("GetCurrentProcessId"))
let get_pid: cfunc<system>() -> u32 = raw as cfunc<system>() -> u32
let pid: u32 = get_pid()没有针对某个游戏或 DirectInput 的专用 hook 关键字。替换 IAT 槽、替换虚表项、安装跳板都由几件现成的事组合完成:
VirtualProtect 改页保护、指针读写落地址、cfunc 定 ABI、FlushInstructionCache 收尾。
每一步都是显式的,换成任意 C 接口同样适用。回调没有闭包,上下文通过 ptr<void> 参数传入。
19.7 sys/windows 标准包
import "sys/windows"
export native system unsafe noexcept noalloc func cursor_x() -> i32:
let point: WIN_POINT = null
if GetCursorPos(&point) == 0:
return -1
end
return point.x
end导入后直接使用。命名空间是扁平的(§13.1),结构体和常量统一带 WIN_ 前缀以避免重名。现在包里有:
WIN_POINT、WIN_RECT、WIN_MSG、WIN_RAWINPUT*等消息和原始输入布局;WIN_MEMORY_BASIC_INFORMATION、WIN_SYSTEM_INFO、WIN_MODULEENTRY32W;- DOS / NT / PE 头与 import descriptor / thunk 等 IAT 遍历结构;
- 共享内存、虚拟内存、进程内存、线程、模块枚举、消息泵、Raw Input、焦点和光标等 Kernel32 / User32 API。
包源码在 packages/sys/windows/mod.gt,发行版里是 dist/packages/sys/windows/mod.gt。
里面只有布局和 API 声明,不会自行创建线程或安装 hook。CloseHandle、UnmapViewOfFile、
恢复内存保护等操作由调用代码负责。
19.8 编译期命名戳
compile_stamp() 返回一个 u32,每次编译随机换一个,同一次编译内的所有调用返回同一个值。
可用于给共享内存名、事件名、互斥体名带上版本:一个 DLL 里所有导出使用同一代号,重编一次就换一代,新旧两版不会互相干扰。
20二进制、网络与多媒体
2026-11 加的一组能力,为的是能用这门语言直接写「远程桌面 / 屏幕墙 / 文件传输」这一类程序:
二进制安全的缓冲类型 bytes,内置的 UDP / TCP / WebSocket,屏幕采集加视频编码,键鼠捕获,
以及界面上的拖文件、全屏、执行 JS。此前这些要么做不了(string 遇 0 截断,装不了二进制),
要么只能在 native 函数里对着 Win32 手写。
20.1 bytes:二进制缓冲
string 是以 0 结尾的 C 串,文件块、网络包、视频帧、密文里只要有一个 0 字节就被截断。
bytes 是一块带长度的缓冲,里面可以是任何字节:
let b: bytes = bytes(8) # 8 个字节,全 0
b[0] = 0x41 # 下标读写,值是 0..255(写入只留低 8 位)
b[1] += 5
print(len(b), b[0], b.hex()) # 8 65 4105000000000000
let packet: bytes = bytes(0) # 空缓冲,往后接
packet.push(0x01)
packet.append_str("hello")
packet.resize(packet.len() + 4)
packet.put_u32be(6, 1234) # 网络序整数
print(packet.u32be(6), packet.str(1, 5))
let copy: bytes = packet.slice(1, 5) # 新的一份
print(copy.text()) # hello
copy.free()
packet.free()
b.free()bytes是类型名,bytes(n)是构造函数(自己定义了叫bytes的变量 / 函数以自己的为准)。- 和
chan一样是引用:传参、放进类字段、放进list<bytes>都是同一个缓冲;没有 GC,用完自己free()。 热路径上复用同一个缓冲(收包、取帧的内置都是「写进你给的 bytes」),不要每次新建。 b[i]、带偏移的方法越界,或者句柄是null/ 已经free过,是运行时错误(可catch,没人接退出码 3):bytes 越界:偏移 10,长度 1,缓冲长度 10。free之后再用不会崩,会报bytes 是空的(null),或者已经 free 过了。- bytes 本身不加锁:两条协程同时改同一个缓冲要自己用
Mutex。 - 要 bytes 的参数传了别的类型(或反过来)是编译错误,不会拿整数当指针读。可以为空的 bytes 参数传
null。
方法:
| 写法 | 说明 |
|---|---|
b.len() / len(b) / b.cap() | 长度 / 已分配的容量 |
b.valid() | 句柄能不能用(不是 null、没 free 过) |
b[i] / b.get(i) / b.set(i, v) | 第 i 个字节 |
b.resize(n) | 改长度;变长的部分清 0;容量只涨不缩 |
b.reserve(n) / b.clear() | 预留容量 / 长度归 0(容量留着,复用缓冲时用) |
b.fill(偏移, 长度, 值) | 填同一个字节 |
b.slice(偏移, 长度) | 拷出一份新的 bytes |
b.copy(目标偏移, 源, 源偏移, 长度) | 从另一个 bytes 拷进来(放不下是错误;两段可以重叠) |
b.append(源, 源偏移, 长度) / b.push(v) / b.append_str(s) | 接在尾部,自动变长 |
b.equals(另一个) | 内容相同(比较时间不随内容变,可以拿来比 MAC) |
b.find(要找的, 从哪开始) | 位置,没有是 -1 |
b.u8/i8/u16/i16/u32/i32/u64(偏移) | 读整数,小端 |
b.u16be/u32be/u64be(偏移) | 读整数,大端(网络序) |
b.put_u8/put_u16/put_u32/put_u64(偏移, 值)、put_u16be/put_u32be/put_u64be | 写整数 |
b.f32/f64(偏移)、b.put_f32/put_f64(偏移, 值) | 浮点(小端) |
b.str(偏移, 长度) / b.text() | 当 UTF-8 文本取出来(遇到 0 字节到那里为止) |
b.put_str(偏移, s) | 把文本的字节写进去,返回写了多少(放不下是错误) |
b.hex() / b.base64() | 小写 hex / 标准 base64 |
b.ptr() | 数据区的地址(int),交给 extern / native 函数用;resize / append / free 之后作废 |
b.free() | 还掉 |
不挂在对象上的:
| 函数 | 说明 |
|---|---|
bytes_from_str(s) | 文本的字节(不含结尾的 0) |
bytes_from_hex(s) / bytes_from_base64(s) | 解码;不合法返回长度 0 的 bytes。base64 标准 / URL 安全字母表都认,有没有 = 都行 |
bytes_from_ptr(地址, 长度) | 从原生内存拷一份 |
20.2 二进制文件
let data: bytes = file_read_bytes("C:\\a.bin") # 整个读进来;读不到是长度 0
file_write_bytes("C:\\b.bin", data)
file_append_bytes("C:\\b.bin", data)
let f: int = file_open("C:\\big.iso", "r") # "r" 只读 / "w" 新建或清空 / "rw" 读写不清空 / "a" 追加
let chunk: bytes = bytes(0)
let offset: int = 0
while true:
let got: int = file_read_at(f, offset, chunk, 65536) # chunk 的长度变成实际读到的
if got <= 0:
break
end
offset = offset + got
end
file_close(f)| 函数 | 说明 |
|---|---|
file_open(路径, 模式) | 文件 id(> 0),打不开是 0 |
file_read_at(f, 偏移, 缓冲, 最多读多少) | 读到的字节数,文件尾 0,出错 -1。不动文件指针,几条协程可以同时读同一个文件的不同位置 |
file_write_at(f, 偏移, 缓冲, 缓冲偏移, 长度) | 写了多少,出错 -1。偏移传负数 = 接在文件尾 |
file_length(f) / file_truncate(f, 长度) / file_flush(f) / file_close(f) |
20.3 摘要、随机数、AES-GCM、ECDH
全部二进制安全,底下是 Windows CNG。
let digest: bytes = crypto_sha256(bytes_from_str("abc"))
print(digest.hex()) # ba7816bf…
let key: bytes = crypto_random(32) # 密码学安全的随机字节
let cipher: int = cipher_new(key) # AES-GCM,key 16 / 24 / 32 字节
let nonce: bytes = bytes(12) # 同一把 key 下 nonce 绝不能重复(用计数器)
let plain: bytes = bytes_from_str("attack at dawn")
let box: bytes = bytes(0)
let n: int = cipher_seal(cipher, nonce, null, plain, 0, plain.len(), box, 0) # box = 密文 + 16 字节标签
let back: bytes = bytes(0)
let m: int = cipher_open(cipher, nonce, null, box, 0, n, back, 0) # 标签对不上返回 -1| 函数 | 说明 | ||||
|---|---|---|---|---|---|
crypto_sha256(b) / crypto_sha1(b) | 32 / 20 字节 | ||||
crypto_hmac_sha256(key, 数据) | 32 字节(hmac_sha256_hex 的 key 是 C 串,二进制 key 用这个) | ||||
crypto_random(n) | n 个随机字节 | ||||
cipher_new(key) / cipher_free(c) | 加密对象 id,失败 0。同一个对象可以反复用、多条协程一起用 | ||||
cipher_seal(c, nonce, aad, 输入, 输入偏移, 长度, 输出, 输出偏移) | 加密,输出不够长会自己变长;返回写了多少(长度 + 16),失败 -1。aad 是只认证不加密的附加数据,可以 null。输入输出可以是同一个缓冲 | ||||
cipher_open(…同上…) | 解密并校验,返回明文长度;被改过 / key / nonce / aad 不对返回 -1 | ||||
ecdh_new() / ecdh_public(k) / ecdh_shared(k, 对方公钥) / ecdh_free(k) | P-256 临时密钥交换。公钥 65 字节(`04 | X | Y,和 Go crypto/ecdh` 同一种);共享密钥 = SHA-256(共享点的 X),32 字节;对方公钥不合法返回长度 0 |
20.4 UDP / TCP
socket 在脚本里是一个整数 id(UDP、TCP、监听、WebSocket 共用一个编号空间)。会等的调用
(recv / accept / connect / tcp_send)在协程里和 http_* 一样:编译器自动包上
go_block_enter / go_block_leave,卡住的是这条协程,不连累别的。另一条协程 sock_close,
卡在里面的调用马上返回。
# UDP
let u: int = udp_open("", 0) # ("" = 所有网卡, 0 = 系统分配端口)
let packet: bytes = bytes_from_str("ping")
udp_send(u, "192.168.1.20", 9000, packet, 0, packet.len())
let inbox: bytes = bytes(0)
let n: int = udp_recv(u, inbox, 1000) # 数据报长度;超时 -1;socket 已关 -2
if n >= 0:
print(udp_from_ip(u), udp_from_port(u), inbox.text())
end
# TCP
let listener: int = tcp_listen("127.0.0.1", 0)
print(sock_local_port(listener))
let conn: int = tcp_accept(listener, 5000) # 连接 id;超时 0;监听已关 -1
let out: int = tcp_connect("example.com", 80, 3000)
tcp_send(out, packet, 0, packet.len()) # 全部发完才返回
let got: int = tcp_recv(out, inbox, 4096, 3000) # n > 0;对方关闭 0;超时 -1;出错 -2
tcp_recv_exact(out, inbox, 4, 3000) # 收满 4 字节才返回(定长帧头用它)
sock_close(out)| 函数 | 说明 |
|---|---|
udp_open(绑定IP, 端口) | id,失败 0。只做 IPv4 |
udp_send(sock, ip, 端口, 缓冲, 偏移, 长度) | 发出的字节数,失败 -1。不会等,不占阻塞名额 |
udp_recv(sock, 缓冲, 超时毫秒) | 超时传负数一直等、0 不等。缓冲的长度变成数据报长度 |
udp_from_ip(sock) / udp_from_port(sock) | 这个 socket 上一个收到的数据报是谁发的 |
tcp_listen(绑定IP, 端口) / tcp_accept(监听, 超时) | |
tcp_connect(主机, 端口, 超时) | 主机可以是域名。id,失败 0 |
tcp_send(连接, 缓冲, 偏移, 长度) | 返回长度,失败 -1 |
tcp_recv(连接, 缓冲, 最多多少, 超时) / tcp_recv_exact(连接, 缓冲, n, 超时) | 缓冲的长度变成实际收到的 |
sock_close(id) | 任何种类的 id 都行 |
sock_local_port(id) / sock_local_ip(id) / sock_peer_ip(id) / sock_peer_port(id) | |
sock_set_nodelay(id, 开关) / sock_set_buffers(id, 接收, 发送) | TCP 默认已经关了 Nagle;缓冲大小传 ≤ 0 的那一项不改 |
net_resolve(域名) / net_local_ips() | 第一个 IPv4(失败空串)/ 本机网卡的 IPv4 列表(JSON 数组) |
net_error() | 这条线程上一次失败的原因 |
tcp_recv_exact 超时返回时已经读到的那一部分就丢了,帧边界对不上:把它的超时当成「对方死了」用,
不要拿短超时来轮询;要随时能停,就让另一条协程 sock_close。
两台都在路由器后面的机器要直连(UDP 打洞),见 20.9:那边建好的连接同样用 tcp_send / tcp_recv /
tcp_recv_exact / sock_close。
20.5 WebSocket
服务端(RFC 6455)和客户端(ws://、wss://)都是内置的,收发都是整条消息(分片、ping/pong、
关闭握手运行时自己处理)。
let server: int = ws_listen("127.0.0.1", 0)
let conn: int = ws_accept(server, 5000) # 握手完成的连接;超时 0;已关 -1
print(ws_path(conn), ws_header(conn, "Origin")) # "/feed?token=…"
let msg: bytes = bytes(0)
let n: int = ws_recv(conn, msg, 1000) # 消息长度;超时 -1;已关 -2
if n >= 0 and ws_recv_text(conn):
ws_send_text(conn, "echo: " + msg.text())
end
ws_send(conn, msg, 0, msg.len()) # 二进制消息
ws_close(conn)
let client: int = ws_connect("wss://example.com/feed", "{\"Authorization\":\"Bearer x\"}", 5000)- 同一条连接可以多条协程一起发(每条连接一把发送锁,帧不会搅在一起)。
- 本机回环上的 WebSocket 谁都连得上(浏览器里任何网页都能连
ws://127.0.0.1):握手之后自己用ws_path里的令牌和ws_header(conn, "Origin")校验,不对就ws_close。 - 这是宿主给 WebView2 页面送大块二进制(画面帧)的路:MoonGUI 桥只能过字符串。
20.6 屏幕流:采集 + 编码
let stream: int = screen_stream_open("{\"width\":1280,\"height\":720,\"fps\":30}")
let frame: bytes = bytes(0)
while running:
let n: int = screen_stream_read(stream, frame, 200) # 一帧编好的数据;画面没变 0;流已关 -1
if n > 0:
let key: bool = (screen_stream_flags(stream) & 1) != 0
send(frame, n, key, screen_stream_width(stream), screen_stream_height(stream))
end
end
screen_stream_close(stream)- 采集(DXGI 桌面复制,不行退 GDI)、缩放、转色、编码都在流自己的线程上;
read只是取编好的帧, 可以在任何协程里调。消费慢了采集自动降速(不丢已经编好的帧 —— H.264 的帧间依赖不允许丢)。 - H.264 输出是 Annex-B,每个关键帧前面都带 SPS / PPS:浏览器的 WebCodecs
VideoDecoder(不带description)可以从任意一个关键帧开始解。画面没变不出帧。 - 同一台显示器可以同时开几个不同分辨率的流(采集是共用的)。
- 编码用系统自带的 H.264 软件编码器(Media Foundation,运行时才加载 —— 没装媒体功能包的 N 版 Windows 上程序照常启动,只是
openH.264 会失败,可以改用"codec":"jpeg")。码率由运行时自己逐帧控制,set改bitrate下一帧就生效;码率给得远低于画面需要时会降帧率来守住码率。 - 显卡管线和硬件编码器(2026-11-15):DXGI 采集到的帧先留在显卡上,缩放 + 转色在显卡上做(D3D11 视频处理器),只把缩好的 NV12 读回内存 —— 不再把整帧读回来(4K 屏那一步要十来毫秒,以前 60 帧都到不了)。
帧率高(
fps>= 50)或者画面比 1080p 大时,默认改用显卡的硬件编码器(NVENC / Quick Sync / AMF,Media Foundation 的硬件 MFT,喂取分在两条线程上):实测 4K 屏缩到 1080p,120 帧档 119.9 帧、144 帧档 143 帧,720p 240 帧档 230 帧;原始 4K 60 帧档从 27 帧到 54 帧。 用不上的情况自动走原来的路,不用上层管:要 JPEG / 要把光标画进画面 / 显卡没有视频处理器(虚拟机)/ 退到了 GDI → 读回整帧在内存里做;硬件编码器建不出来或中途出错 → 换软件编码器接着编(下一帧是关键帧),这个编码器在本进程里不再用。 实际帧率不会超过显示器的刷新率(桌面复制是跟着刷新走的)。info里的pipeline(gpu/cpu)和hardware(true/false)说明现在走的是哪条路。- 硬件编码器默认用 CBR:实测 NVIDIA 的 MFT 只有 CBR 下运行中
set的bitrate才生效(别的码控模式要重建编码器才认)。rc明说了别的模式时不走「自动」的硬件编码器(hardware:true仍然可以强制)。 - 「自动」跟着帧率走:开的时候帧率低(软件编码器),运行中只把
fps从 50 以下改到 50 以上时会换成硬件编码器(出一个关键帧);之后只改码率不会再重建。反过来从高帧率降下来不换回去。
- 硬件编码器默认用 CBR:实测 NVIDIA 的 MFT 只有 CBR 下运行中
- 先认机器再定参数:
screen_stream_info(-1)不看任何流,返回这台机器的情况 ——{"cores":12,"gpu":"nvidia","gpuName":"NVIDIA GeForce RTX 3080","integrated":false,"vramMb":10240, "hardware":true,"encoder":"NVIDIA H.264 Encoder MFT","gpus":[...],"encoders":[...]}gpu是带着显示器的那块真显卡的厂商(nvidia/amd/intel/other;none= 只有软件渲染,云电脑和没装显卡驱动的虚拟机就是这样),integrated是不是核显(按厂商和名字认:Intel 除了 Arc A / B 系列都是,AMD 名字里带 Graphics 的是),hardware是有没有能用的硬件 H.264 编码器(出过错被拉黑的不算)。 没有显卡 / 没有硬件编码器的机器,高帧率只能靠处理器硬编,上层应该据此把帧率和分辨率的上限降下来。第一次调用要枚举显卡和编码器(几十到一两百毫秒),别放在每帧都走的路上。 - 画面停下来之后,如果最后一帧是码率吃紧时编的,流会再出几帧把清晰度补上,然后才安静。
- 和截图 / 找图那套内置同进程用时:一个进程里每台显示器只能有一个桌面复制。先截过图再开流,流会退到 GDI 采集(慢,约 40 ms 一帧)。两样都要用的程序,先开流再截图。
- 画面旋转过的显示器走 GDI;软件光标的显示器(部分虚拟显示器)光标本来就在画面里,
cursor关不掉。 - NVIDIA 显卡(2026-11-16):采集用的 D3D11 设备带着「驱动别起自己的线程」的标志建(
D3D11_CREATE_DEVICE_PREVENT_INTERNAL_THREADING_OPTIMIZATIONS)。照默认的建法,它的驱动每处理 110 帧左右就在进程堆里多留一块 33KB 的内存、一直不还(60 帧的流一小时 60MB,帧率越高越快;RTX 3080、驱动 32.0.16.1088 上量的),带上这个标志就没有,帧率和每帧耗时不变。别家的显卡照原样建。
选项(open 和 set 共用,set 只改给出的键):
| 键 | 说明 |
|---|---|
monitor | 显示器序号(screen_monitors() 的顺序,主屏是 0) |
codec | "h264"(默认)/ "jpeg" |
width / height | 画面装进这个框里,等比缩小不放大;0 = 原始分辨率 |
fps | 1–240,默认 30 |
bitrate | kbps;不给按分辨率和帧率定(30 帧及以下 1080p ≈ 4000;更高的帧率按 (fps / 30)^0.6 往上给) |
hardware | 硬件编码器:"auto"(默认:fps >= 50 或比 1080p 大才用)/ true(能用就用)/ false(不用)。用不了自动换软件的 |
gpu | 只在 open 时看:false = 不用显卡管线,读回整帧在内存里缩放转色(排查某块显卡的问题用) |
quality | JPEG 质量 1–100 |
gop | 两个关键帧之间最多隔几秒,1–3600,默认 10(静止画面也会按这个间隔出关键帧;传输可靠、接收方会自己要关键帧时给大一点) |
cursor | 把系统光标画进画面,默认不画 |
profile | "baseline" / "main"(默认)/ "high" |
backend | "auto"(默认)/ "dxgi" / "gdi" |
key | 只给 set:true = 下一帧强制关键帧 |
set 里只要出现 width / height / monitor / codec / hardware 这几个键就会重建编码器(值没变也重建,下一帧是关键帧且 flags 的 bit1 置位):只想改码率 / 帧率时别带上它们。
| 函数 | 说明 |
|---|---|
screen_monitors() | JSON 数组 [{index,x,y,w,h,primary,name}],物理像素 |
screen_stream_open(选项JSON) | 流 id,失败 0(原因:screen_stream_info(0)) |
screen_stream_read(流, 缓冲, 超时) | 见上 |
screen_stream_flags(流) | 上一帧:bit0 关键帧,bit1 分辨率 / 编码配置变了(解码器要重新配置;流的第一帧不置) |
screen_stream_width/height/ts(流) | 上一帧的宽 / 高 / 采集时刻(毫秒,单调) |
screen_stream_set(流, 选项JSON) | 运行中改码率、帧率、尺寸;改尺寸 / 显示器 / 编码会重建编码器,下一帧是关键帧 |
screen_stream_info(流) | JSON 状态:codec backend encoder pipeline(gpu / cpu)hardware srcW srcH w h fps bitrate qp frames keyframes dropped bytes avgCaptureMs avgConvertMs avgEncodeMs lastError |
screen_stream_info(0) | 上一次 open 失败的原因(lastError) |
screen_stream_info(-1) | 这台机器的情况:cores gpu gpuName integrated vramMb hardware encoder gpus encoders(见上) |
screen_stream_close(流) | 卡在 read 里的调用立刻返回 -1 |
20.7 键鼠捕获与光标形状
低级钩子,远程控制的控制端用:页面的 keydown 拿不到 Win 键、Alt+Tab,也拦不住它们在本机生效; 3D 游戏转视角要的是鼠标位移而不是坐标。
input_capture_start("{\"keyboard\":true,\"mouse\":true}")
input_capture_set("{\"swallowKeys\":true,\"hwnd\":" + str(gui_win_hwnd(win)) + ",\"releaseKeys\":[17,18,16]}")
let events: bytes = bytes(0)
while running:
let count: int = input_capture_read(events, 200) # 事件个数;没有 0;没在捕获 -1
for i = 0 to count:
let at: int = i * 16
let kind: int = events[at] # 1 键盘 2 相对位移 3 鼠标键 4 滚轮 5 横向滚轮 6 绝对位置 7 被解除
let down: bool = (events[at + 1] & 1) != 0
let code: int = events.u16(at + 2) # 虚拟键码 / 鼠标键号
let a: int = events.i32(at + 4) # 扫描码 / dx / 滚轮增量 / x
let b: int = events.i32(at + 8) # dy / y
end
end
input_capture_stop()input_capture_set 的键(只改给出的):
| 键 | 说明 |
|---|---|
swallowKeys | 接管键盘:按键不再交给本机程序,改为上报 |
swallowMouse | 接管鼠标按键 / 滚轮 / 移动 |
relative | 相对模式:光标留在原地,上报位移(3D 视角) |
hwnd | 只在这个窗口在前台时才接管;它到了后台自动解除并上报一个 kind = 7 |
releaseKeys | 同时按下就解除接管的组合键(通用虚拟键码数组,[17,18,16] = Ctrl + Alt + Shift) |
只在接管条件成立时才上报按键;没在接管时钩子原样放行、什么都不记。
| 函数 | 说明 |
|---|---|
cursor_state() | {"x","y","visible","handle"}:光标位置和形状句柄(句柄变了才需要重新取图) |
cursor_image(缓冲) | 当前光标画成 BGRA(自上而下,直通 alpha)写进缓冲,返回 {"ok","handle","w","h","hotX","hotY"} |
20.8 界面补充
- 拖文件进窗口:
gui_create的选项加"fileDrop": 1。页面收到的是普通的 HTML5dragenter/dragover/drop;要本地路径时在页面里调await MoonGUI.filePaths(event.dataTransfer.files),得到和文件一一对应的路径数组(拿不到的是空串)。<input type="file">选出来的 File 对象同样能换。不开这个选项时,无边框窗口不接受拖放(和以前一样)。 - 全屏:
gui_set_fullscreen(winId, true/false)铺满窗口所在的显示器,关掉回到原来的位置和大小 (原来是最大化就回到最大化);gui_is_fullscreen(winId)。任意线程可调。 - 执行 JS:
gui_eval_win(winId, "脚本"),不取返回值(要结果让页面自己MoonGUI.call回来)。任意线程可调。 - 无边框窗口在第一帧画出来之前就
gui_show_win(win, 0)藏起来(开机自启只进托盘),之后再显示是正常的不透明窗口。
20.9 rudp:UDP 打洞 + 可靠字节流
两台各在自己路由器(NAT)后面的机器想直连,TCP 连不进去,要靠 UDP 打洞:两边用同一个 UDP 端口同时往对方的公网地址发包,
各自的路由器就都放行了。打通之后 UDP 本身不可靠、不保序,所以上面还要有一层重传、排序、流控和拥塞控制。
rudp_* 把这两件事做在运行时里:建好的连接直接当 TCP 连接用(tcp_send / tcp_recv /
tcp_recv_exact / sock_close),按 TCP 写的上层代码不用区分承载。
let sock: int = rudp_open("", 0) # 一个 UDP socket + 它的收发线程
# ① 向会合服务探测自己的公网地址(裸数据报,协议自己定)
let probe: bytes = bytes_from_str("whoami")
rudp_raw_send(sock, "203.0.113.5", 3478, probe, 0, probe.len())
let reply: bytes = bytes(0)
let n: int = rudp_raw_recv(sock, reply, 2000) # 长度;超时 0;socket 已关 -1
print(rudp_raw_from_ip(sock), rudp_raw_from_port(sock), reply.text())
# ② 经会合服务和对方交换:conv(会话号)、key、各自的候选地址(公网的 + 局域网的)
# ③ 两端同时打洞
let conn: int = rudp_connect(sock, "00112233aabbccdd", key,
"[\"198.51.100.7:40123\",\"192.168.1.20:40123\"]", 8000)
if conn > 0:
tcp_send(conn, packet, 0, packet.len()) # 之后和 TCP 连接一样用
tcp_recv_exact(conn, inbox, 4, 3000)
print(sock_peer_ip(conn), sock_peer_port(conn), rudp_info(conn))
sock_close(conn)
else:
use_tcp_relay() # 打不通:走服务器中继兜底
end
rudp_close(sock)rudp 管什么、不管什么
- 打洞的前提是两端各自知道对方的公网地址(NAT 映射出来的
ip:端口)。这个地址本机自己看不到,要靠一个两边都连得上的第三方服务器看到之后再转告。rudp 不管这一步(不带会合 / 信令服务,也不做 STUN),只提供rudp_raw_send/rudp_raw_recv让你在同一个 socket 上自己做探测 —— 必须是同一个 socket:NAT 的映射是跟着本地端口走的,探测用的端口和之后打洞用的端口要是同一个。 - 对称型 NAT 打不通。这种 NAT 给每个不同的目的地址分配不同的外部端口,会合服务看到的端口不是对方打过来时要用的端口(企业网、部分运营商的移动网络是这种;一头对称、另一头不是时有机会 —— rudp 会从对方的握手包里学到它实际出来的地址 —— 两头都对称不行)。UDP 被整个封掉的网络也一样。所以一定要留 TCP 兜底(服务器中继):
rudp_connect返回 0 就走中继。 - rudp 负责:打洞建立、可靠、有序、流控、拥塞控制、防伪造。不加密(每个包带 MAC,没有 key 的人伪造不了、也改不了,但内容是明文)—— 加密由上层自己做。
建立连接
rudp_connect要两端同时调(同时打开):各自往对方所有候选地址每 150ms 发一轮握手包;收到对方校验通过的握手包就回应;谁收到「带着自己这一次的随机数」的回应,谁就确认了一次往返,连接建立。候选里可以有不通的,先通的那条路胜出,对端地址就锁在那上面。两边不用掐得很准,只要在对方的timeoutMs之内调就行。- 头几轮握手包用很小的 TTL(2、3、4、6、9,间隔 60ms;之后才是正常的包、150ms 一轮):这几个包走得出自己这边的路由器、到不了对方,两边的路由器先各自记下「这条路是里面主动发起的」。不这样的话,对方的包要是先到,有些路由器(Linux 内核的那一类)会给这边随后发出去的包换一个源端口,对方照着会合时看到的端口等,永远等不到。同一个局域网里的候选地址不受影响(中间没有路由器),第一轮就通。
- IPv4 + IPv6 双栈:
rudp_open("", 端口)开的 socket 两种地址共用一个端口(这台机器开不了 IPv6 就只有 IPv4;绑了具体 IPv4 地址的 socket 也只有 IPv4)。候选地址里 IPv6 写成"[240e::1]:端口"。IPv6 没有地址转换,端口就是对方本机的端口;家用路由器对 IPv6 只有一道「出去过才放进来」的防火墙,两边各自往对方的公网 IPv6 发握手包就通 —— IPv4 那边是对称型 NAT 也不碍事。本机的公网 IPv6 地址在rudp_info(sock)的v6里(JSON 数组,最多 6 个,系统往外发包默认用的临时地址排前面),由会合协议转告对方。 - 期限内没建立时,
net_error()里有一句握手走到哪一步的话:发了多少握手包、收到对方的没有、从哪来的、对方有没有收到这边的(收到了对方的、对方却没收到这边的 = 这边出去的包到不了对方:对称型 NAT / 多线路出口)。 conv是 16 个十六进制字符(8 字节会话号),key是 32 字节,两端相同;都应当是会合时现生成的(crypto_random),一次会话一换。candidates是 JSON 数组["ip:端口", …],最多 16 个(多的不用);传"[]"表示不知道对方地址、只等对方打过来。timeoutMs≤ 0 按 10 秒。- key 不一样的两端建不起来;校验不过的握手包不回应。同一个 socket 上同一个 conv 只能有一条连接(旧的那条
sock_close并且收尾完了才能再连 —— 重连最好换一个 conv);一个 socket 上可以同时有很多条不同 conv 的连接。一头的程序重启了、另一头的旧连接还没断(最多 15 秒才判死)的时候,用旧 conv 重连是连不上的。
连接当 TCP 用
| 函数 | 在 rudp 连接上 |
|---|---|
tcp_send(连接, 缓冲, 偏移, 长度) | 全部进了发送缓冲才返回长度;缓冲满了就卡住(背压);失败 -1 |
tcp_recv(连接, 缓冲, 最多多少, 超时) | n > 0;对方已关且数据读完 0;超时 -1;本端已关 / 连接断了 -2 |
tcp_recv_exact(连接, 缓冲, n, 超时) | 同 TCP:凑不齐超时返回 -1,已经到的留在缓冲里 |
sock_close(连接) | 立刻返回;没发完的数据和关闭包在后台接着送,对端读完缓冲后 tcp_recv 返回 0 |
sock_peer_ip / sock_peer_port | 握手通过的那个地址(对方换了地址会跟着变) |
sock_local_port / sock_local_ip | 所在 socket 的 |
sock_set_nodelay / sock_set_buffers | 空操作,返回 true |
返回值、超时、被另一条协程 sock_close 打断时的表现和真的 TCP 连接逐条一致。只有一处更严格:对方关闭之后,TCP 的头一两次 tcp_send 还会成功(数据进了内核缓冲),rudp 是马上返回 -1。
传输的行为
- 背压:发送缓冲的上限是 2 × 拥塞窗口(32KB ~ 4MB),算的是还没送到对方的字节。路越慢缓冲越小,
tcp_send卡得越早 —— 上层拿「send 卡住」当信号降码率。接收端未读数据上限 4MB,满了对方就停发。两头都不会无限缓冲。 - 丢包恢复:选择确认 + 按时间判定丢包(比「对方已经收到的更新的包」发得早、过了一个往返还没确认就重传),最后一个包丢了有尾部探测,都不行才是 RTO(100ms ~ 4s,指数退避)。每个包载荷最多 1200 字节(整个 IP 包不超过 1276 字节,不依赖路径 MTU 探测)。
- 拥塞控制:慢启动(初始 32 个包),之后每个往返加一个包(一直没有拥塞信号时越加越快)。拥塞信号是丢包、或者往返时间比最小值高出 max(1/4, 5ms) 以上(瓶颈那里在排队);出信号时窗口收到「测到的送达速率 × 最小往返时间」(不低于 4 个包、一次最多降三成),而不是简单减半 —— 随机丢包几乎不改变送达速率,所以零星丢包基本不降速;排了队的那部分被拿掉,延迟不会跟着路由器的缓冲区涨上去。随机丢包率是 p 时窗口大致稳在 1/p 个包上下(1% 约一百个包,10% 二十来个包)。连着三次降了窗口排队时间也不见短(路变长了,或者是别的流在排队),就以当前的往返时间为新基准,10 秒内只看丢包。
- 保活:空闲时每秒一个探测包(也用来量往返时间);15 秒收不到对方任何合法的包就判定连接断了,读返回 -2、写返回 -1。
- 对方换地址(路由器重新分配了端口):收到校验通过而且比之前都新的包来自新地址,对端地址就换过去,连接不断。空闲的连接靠每秒的探测包发现,最多断一秒多。
- 防伪造:每个包带 8 字节 MAC(HMAC-SHA256 截断,密钥由
key和两端这一次连接的随机数派生,两个方向各一把)。校验不过的包直接丢、不回应;重放的旧包被包号窗口挡掉;上一次连接抓到的包这一次用不了。
回环上实测(损伤用 rudp_debug 造,数字每次跑会有一两成的出入):
| 条件 | 结果 |
|---|---|
| 30MB 单向,无损伤 | 约 60 MB/s,最长停顿 1 ~ 2ms |
| 30MB 单向,2% 丢包 | 约 55 MB/s,最长停顿 3 ~ 4ms(双向同时各 30MB:约 36 ~ 40 MB/s,十几毫秒) |
| 30MB 单向,10% 丢包 + 5% 乱序 + 1% 重复 + 30ms 单向延迟 | 约 0.35 MB/s(2.8 Mbps),最长停顿 0.25 ~ 0.5 秒 |
| 单向延迟 25ms:不丢包 / 0.1% 丢包 / 1% 丢包 | 约 290 / 210 / 25 ~ 45 Mbps |
| 4Mbps 的瓶颈、单向延迟 20ms、一直喂满,瓶颈的队列能排 500ms | 吞吐 3.8 Mbps;在瓶颈那里排队的时间中位 8ms、最大 22ms(没有把队列排满) |
| 同上,队列只有 20ms | 吞吐 3.8 Mbps,重传 1% |
| 每 10ms 一条 100 字节的小消息,反方向 2Mbps,单向延迟 20ms 不丢包 | 送达延迟 p50 20.6ms / p99 21.3ms / 最大 21.8ms |
| 同上,再加 5% 丢包 | p50 20.7ms / p90 62ms / p99 84 ~ 120ms / 最大 130 ~ 180ms |
丢了的包要等一个多往返才补上,排在它后面的消息跟着等 —— 这是有序流的代价,换成 TCP 只会更久。
裸数据报和连接共用一个 socket
- 收到的数据报,首字节是
0x47、长度够一个包头、而且第 2 ~ 9 字节(conv)对得上这个 socket 上某条连接的,是连接包;其它的都进 raw 队列,由rudp_raw_recv取(队列最多 256 个 / 1MB,满了丢新的;空数据报收不到)。 - 所以对方先开始打洞、这边还没调
rudp_connect的那一小段时间里,对方的握手包(45 字节、0x47开头)会从rudp_raw_recv出来;连接关掉 20 秒之后迟到的包也是。会合协议收到不认识的数据报丢掉就行(自己的数据报最好别用0x47开头,省得分辨)。
其它
- 线程:每个
rudp_open的 socket 有一条自己的收发线程(收包、定时重传、保活)。rudp_connect、rudp_raw_recv、rudp_close和连接上的tcp_*一样在协程里不连累别的协程;另一条协程sock_close/rudp_close,卡在里面的调用马上返回。 rudp_close(sock)关 socket 和上面所有连接(连接的 id 一并作废)。上面的连接有数据或关闭包还没送到的,最多等半秒;到点还没送完的,对端读到的是 -2(连接被重置)而不是「正常关闭」。sock_close(sock)效果一样,但它不在阻塞名单里 —— 协程里关 socket 用rudp_close,免得这半秒占着调度线程。- 单独
sock_close(连接)之后,没发完的数据由 socket 的收发线程接着送:只要对方还在收就一直送(3 秒没有进展放弃,总共不超过 60 秒)。所以「发完最后一条消息马上关连接」是安全的,前提是 socket 还开着。 - 一个 socket 上几百条连接以内没问题(定时器是逐条扫的)。两端的
rudp版本要一致(握手包里有版本号,不一致建不起来;2026-11-15 加的双栈和小 TTL 没有改包格式,和之前的版本互通)。
| 函数 | 说明 |
|---|---|
rudp_open(绑定IP, 端口) | socket id,失败 0。"" = 所有网卡,端口 0 = 系统分配 |
rudp_local_port(sock) | 本地端口(和 sock_local_port 一样) |
rudp_raw_send(sock, ip, 端口, 缓冲, 偏移, 长度) | 发一个裸数据报,成功 true。ip 是数字地址,IPv4 / IPv6 都行 |
rudp_raw_recv(sock, 缓冲, 超时) | 长度(> 0);超时 0;socket 已关 -1。超时传负数一直等 |
rudp_raw_from_ip(sock) / rudp_raw_from_port(sock) | 上一次 rudp_raw_recv 的来源(只记 IPv4 的;IPv6 来的是 "" / 0) |
rudp_connect(sock, conv, key, 候选地址JSON, 超时) | 连接 id,期限内没建立返回 0(原因 net_error()) |
rudp_info(id) | JSON。连接:state(open / closing / peer_closed / reset / dead)、peer、rtt / rttMin / rto(毫秒)、cwnd、inflight、unacked(还没被对方确认的字节,含没发出去的)、sendBuffered / sendLimit、recvBuffered、rate(送达速率,字节 / 秒)、sentPackets / sentBytes / recvPackets / recvBytes / retransPackets / retransBytes / lostPackets、badMac / replayed、rtos / tailProbes / congestionEvents / migrations 等。socket:port、dual(是不是 IPv4 + IPv6 双栈)、v6(本机现在能用的公网 IPv6 地址,JSON 数组)、connections、rawQueued 和收发计数。无效 id 返回 {} |
rudp_debug(sock, 选项JSON) | 测试用:给这个 socket 发出去的包(连接包和裸数据报都算)造损伤,{"loss":0.05,"dup":0.01,"reorder":0.05,"delayMs":30,"jitterMs":10};每次调用整个替换,"{}" 关掉。要双向都坏就两头都设。抖动不打乱先后,乱序是把选中的包多压 2 ~ 10ms。另有 "rateKbps":4000,"queueMs":200:一条这么宽的瓶颈链路,队列排满 queueMs 的量就丢 —— 看拥塞控制用 |
rudp_close(sock) | 见上。sock_close 也能关 |
官网 moon-lang.com · 下载编译器 · 成功案例 · 用 MoonLang 开发的软件:8dks.com
Copyright (c) 2026 greenteng.com