Game_Memory指针如何穿越新旧DLL?odin-raylib-hot-reload-game-template热重载状态保持机制深度解析

原创2026-11-13 10:06:411,983 阅读

Game_Memory指针如何穿越新旧DLL?odin-raylib-hot-reload-game-template热重载状态保持机制深度解析

odin-raylib-hot-reload-game-template 是一个为 Odin + Raylib 游戏预先配置好热重载(Hot Reloading)的开源游戏模板:游戏运行时只需重新编译并替换 game.dll,而一个名为 Game_Memory 的结构体指针让所有游戏状态——玩家位置、纹理、运行标志——无需重启进程即可完整保留。这篇文章带你彻底搞懂这套"指针穿越新旧 DLL"的机制。

一、先看懂架构:一个常驻宿主 + 一个可替换的游戏 DLL

热重载的核心思路是把"游戏代码"和"游戏进程"拆成两部分:

组成部分 文件位置 职责 热重载时是否变化
宿主进程 game_hot_reload.exe source/main_hot_reload/main_hot_reload.odin 加载 DLL、监控文件变化、转交状态指针 ❌ 常驻不动
游戏 DLL game.dll source/game.odin 你的全部游戏逻辑(更新、渲染、初始化) ✅ 每次保存后重新编译

整个流程非常简单:

  1. 运行 build_hot_reload.bat(Linux/macOS 用 build_hot_reload.sh),生成 game_hot_reload.exe 和 build/hot_reload/game.dll;
  2. 启动 game_hot_reload.exe 并让它保持运行;
  3. 修改 source/game.odin 中的游戏代码并保存;
  4. 再次运行构建脚本——它只重新编译 game.dll,宿主 exe 保持不变;
  5. 运行中的 exe 检测到 DLL 文件时间戳变化,自动卸载旧逻辑、加载新逻辑,并沿用同一个 Game_Memory 指针。

💡 脚本通过 tasklist(Windows)/ pgrep(Linux/macOS)检测 exe 是否在运行:在运行就跳过 exe 编译,直接触发热重载,整个过程不到一秒。

二、状态的"单一事实来源":Game_Memory 结构体

一切状态保持都围绕 source/game.odin 中这个小小的结构体展开:

Game_Memory :: struct {
    player_pos: rl.Vector2,
    player_texture: rl.Texture,
    some_number: int,
    run: bool,
}

g: ^Game_Memory

关键点在于:g 是一个指针,它指向的数据由 game_init 通过 g = new(Game_Memory) 分配在进程的堆上,而不是 DLL 自身的模块内存里。

这正是整个机制的灵魂——exe 和 DLL 运行在同一个进程、共享同一块地址空间。DLL 被卸载再换新的,堆上的那块内存依然活着,指针依然有效。只要新 DLL 拿回同一个指针,玩家的位置、分数、纹理就全部"无缝续上"。

game_init :: proc() {
    g = new(Game_Memory)
    g^ = Game_Memory {
        run = true,
        some_number = 100,
        player_texture = rl.LoadTexture("assets/round_cat.png"),
    }
    game_hot_reloaded(g)
}

见 source/game.odin。注意最后一行:初始化完成后立即调用 game_hot_reloaded(g) 把指针"登记"——首次启动也走一遍和热重载相同的接管流程,代码路径完全统一。

三、指针穿越三步曲:交棒、转交、接管

宿主进程如何知道 DLL 里藏着哪些函数?答案是 Game_API 结构体 + 动态符号解析。见 source/main_hot_reload/main_hot_reload.odin:

Game_API :: struct {
    lib: dynlib.Library,
    init: proc(),
    update: proc(),
    memory: proc() -> rawptr,
    memory_size: proc() -> int,
    hot_reloaded: proc(mem: rawptr),
    // ...
}

加载时调用 dynlib.initialize_symbols(&api, game_dll_name, "game_", "lib")(L74),它按"字段名 + game_ 前缀"的规则自动把 DLL 里的导出函数(game_init、game_update、game_memory……)一一绑定到结构体字段上。你往 DLL 里新增一个 @(export) 函数、再在 Game_API 里加一个同名字段,接口就扩展好了,无需手写任何绑定代码。

第 1 步:旧 DLL 交棒

每帧循环中,宿主比较 game.dll 的最后修改时间(main_hot_reload.odin),发现变化就触发重载。首先向旧 DLL 要状态:

game_memory := game_api.memory()

对应的就是 game.odin 里的 game_memory :: proc() -> rawptr { return g }——把全局指针以 rawptr(裸指针)形式交出去。此时旧 DLL 还没有被卸载,指针当然有效。

第 2 步:主程序校验并转交

紧接着是一次关键的安全检查(main_hot_reload.odin):

force_restart = force_restart || game_api.memory_size() != new_game_api.memory_size()

新旧两个 DLL 各自返回 size_of(Game_Memory)。如果你在结构体里加了字段导致大小变化,继续用旧指针写新布局必然内存越界,于是宿主直接走"完整重启"路径(等价于关掉再打开游戏)。大小一致时,才执行真正的热重载四连:

append(&old_game_apis, game_api)       // ① 旧 DLL 暂不卸载,继续留在内存里
game_memory := game_api.memory()      // ② 从旧 DLL 取出状态指针
game_api = new_game_api               // ③ 切换到新 DLL
game_api.hot_reloaded(game_memory)    // ④ 把指针交给新 DLL 接管

第 3 步:新 DLL 接管

新 DLL 内部的 g 是个刚被初始化为 nil 的全新全局变量,game_hot_reloaded 一行代码完成"穿越":

game_hot_reloaded :: proc(mem: rawptr) {
    g = (^Game_Memory)(mem)
}

从这一帧开始,新代码里所有的 g.player_pos、g.run 读写的都是旧 DLL 留下的那块内存——代码是新的,状态是旧的,游戏从未中断。

⌨️ 两个快捷键(见 game.odin):F5 强制立即热重载;F6 强制完整重启(清空状态、重新 game_init)。

四、三重安全护栏:为什么它不会"重载出一堆 bug"

护栏 位置 防什么
结构体大小校验 main_hot_reload.odin Game_Memory 布局变了却用旧指针,导致内存越界崩溃
Tracking 分配器 main_hot_reload.odin 每帧检查 bad_free 与内存泄漏,出错会打印并暂停,防止错误被"热重载吞掉"
DLL 副本加载 main_hot_reload.odin Windows 会锁定已加载的 DLL,直接加载 game.dll 会导致编译器无法覆盖写入。所以每次重载先把 DLL 复制成 game_1.dll、game_2.dll… 再加载副本

还有一个容易被忽略的细节:热重载时旧 DLL 并不卸载,而是被追加进 old_game_apis 列表留着(L161 的注释解释了原因——DLL 模块里可能还存着字符串字面量等只读数据)。旧 DLL 只在完整重启或游戏退出时才统一 dynlib.unload_library 释放。配合 build_hot_reload.bat 中为每次编译生成独立 PDB 名的技巧,热重载状态下依然可以挂上调试器单步调试新代码。

五、新手上手:5 分钟体验热重载

:: Windows(macOS / Linux 请用 build_hot_reload.sh)
build_hot_reload.bat
game_hot_reload.exe
  1. 运行 build_hot_reload.bat,生成根目录的 game_hot_reload.exe 和 build/hot_reload/game.dll(要求 Odin 编译器在 PATH 中);
  2. 双击启动游戏,按住 W/A/S/D 移动小猫;
  3. 打开 source/game.odin,把 rl.ClearBackground(rl.BLACK) 改成 rl.BLUE 并保存;
  4. 重新运行 build_hot_reload.bat,屏幕瞬间变蓝——而小猫还停在原地,some_number 计数也没有归零。

就这么简单。发布版本则完全不用关心这套机制:运行 build_release.bat 时,source/main_release/main_release.odin 把 game 当普通 Odin 包直接编进 exe,没有 DLL、没有热重载,产物干净利落。

六、常见问题 FAQ

问:DLL 里的其他全局变量会保留吗? 默认不会——新 DLL 的所有全局变量都会重新初始化为零值。game.odin 的注释给出了官方建议:把所有需要保留的全局状态放进 Game_Memory,其他全局变量都做成指向 g 内部成员的指针,在 game_hot_reloaded 里一并接管。

问:热重载会破坏窗口吗? 不会。窗口由宿主 exe 的 rl.InitWindow(经 game_init_window)创建,DLL 重载不触碰窗口,只有完整重启才走 game_shutdown_window。

问:Web 构建支持热重载吗? 不支持。source/main_web/main_web.odin 走的是 Emscripten/WASM 路线,没有 DLL 的概念,因此 Web 构建是纯 release 模式。

总结

odin-raylib-hot-reload-game-template 的热重载状态保持机制,本质上只做了三件事:

  • 状态集中:全部可变状态收敛到堆上的 Game_Memory 结构体;
  • 进程隔离:游戏代码装进可整体替换的 game.dll,宿主 exe 常驻负责"换件";
  • 指针转交:旧 DLL 用 game_memory 交出裸指针 → 宿主校验 size_of 大小 → 新 DLL 用 game_hot_reloaded 原样接回。

配合大小校验、Tracking 分配器和 DLL 副本加载三重护栏,这套机制在几行代码的代价下实现了"改完即生效、状态零丢失"的开发体验——这正是它在 Odin + Raylib 游戏开发中如此好用的原因。

登录后查看全文
odin-raylib-hot-reload-game-template