Jolt 中的 raylib 示例

# b12n-raylib-jlt — Jolt 编写的 raylib 示例 源地址：https://raylib-jlt.b12n.app/ 75个用**Jolt**编写的**raylib**示例——原生 Clojure 运行于 Chez Scheme 上，无需 JVM。它们通过`jolt.ffi`直接调用真实`libraylib`的 C ABI：无封装库，无代码生成，无 C 垫片。 ## 为何有趣 raylib 各处都按**值传递**结构体，而 Chez 的`foreign-procedure`无法实现。此处并非通过 C 垫片绕开限制——而是根据每个结构体在 ABI 上实际大小和内容，给予其应有的处理。三个事实驱动着绑定层的每个独特决策： - #### Color → 打包的 :uint `Color`由4个`u8`组成，占4字节，而全整型4字节结构体通过一个通用寄存器传递——与`uint32`完全一致。因此每次绘制调用都直接传递整型颜色，根本不进行结构体编排。 - #### Camera2D / Camera3D → 指针传递 超过16字节的复合结构在 AArch64 上**间接传递**——调用者需分配副本并传递其地址。因此24字节的`Camera2D`和44字节的`Camera3D`在本地内存中构建，并绑定为`\[:pointer\]`。**这仅适用于 AArch64**，指南明确说明这一点而非假装跨平台。 - #### Vector2 / Vector3 → rlgl 立即模式 小型**浮点**结构体通过浮点寄存器传递，指针技巧无法覆盖。因此按值接受`Vector2`或`Vector3`的几何图形，改用 rlgl 的标量立即模式绘制——使用`rlVertex3f`、`rlColor4ub`及嵌套变换的矩阵栈。 ## 整体结构 ```mermaid flowchart LR subgraph ex["75个示例命名空间"] e["pong · boids · tetris<br/>camera-3d · penrose-tiling · ..."] end subgraph shared["net.b12n.raylib-jlt.raylib — 共享层"] kw["关键词参数绘图 API<br/>text! · rect! · circle! · cube!"] fb["jolt.ffi/defcfn 绑定<br/>位置参数，镜像 C"] kw --> fb end lib["系统库 libraylib<br/>运行时动态加载，C ABI"] e --> kw fb -->|"Color 作为打包的 :uint"| lib fb -->|"Camera2D/3D 通过指针"| lib fb -->|"rlgl 标量立即模式"| lib ``` 每个示例都是构建于该共享层之上的小型命名空间。新增一个示例仅需触及四个位置——源命名空间、`deps.edn`别名、`check.clj`的 require 以及`bb.edn`注册表条目。 ## 内容概述 #### 统一绑定层 所有 FFI 绑定、关键词参数绘图 API 和命名调色板均位于单个命名空间中。示例保持足够小巧，可一次性阅读。 #### Clojure 风格，非 C 风格 `\ (rl/circle\! :x 400 :y 225 :radius 50 :color rl/MAROON\ )`——边界处使用位置绑定，上层包装关键词参数。 #### 无需显示器即可验证 `RAYLIB_APP_AUTO_QUIT_MS`通过定时器关闭窗口，`RAYLIB_APP_SHOT`将帧转储为 PNG——因此窗口示例可无人值守自证有效。 #### 覆盖全部75个示例的编译门禁 `bb check`以无头方式 require 每个示例命名空间。无需窗口，无需 JVM，一次即可捕获整个套件中失效的绑定。 #### clj-kondo 适配 FFI 钩子将每个`defcfn`重写为等效的`defn`，使调用点获得参数数量和返回类型检查，而非产生约500个误报。 #### 不止 raylib 两个时钟示例调用原生**libc**的`time()`/`localtime()`，直接从本地内存读取`struct tm`。`jolt.ffi`与 raylib 无关。 ## 快速开始 ```bash bb lib:check # 检查系统是否为当前 OS/架构安装了原生 libraylib？ bb lib:install # ...通过 brew / pacman / apt / dnf / zypper / apk 安装 bb info # 所有示例的分组速查表 bb tetris # 运行单个示例（打开窗口） bb run-all 10 # 演示轮播：每个示例运行10秒 bb check # 无头编译检查全部75个，无需窗口 ``` 需要`jolt`（经 v0.7.16 测试）和系统级`libraylib`。Babashka (https://babashka.org/) 可选，但能为每个示例提供友好任务；若无，每个示例需通过`joltc -M:`运行。 采用 zlib/libpng 许可证发布——与 raylib 本身相同。