读懂游戏主循环:odin-raylib-hot-reload-game-template中game.odin结构与Game_Memory状态入门指南

原创2026-11-13 23:48:171,833 阅读

读懂游戏主循环:odin-raylib-hot-reload-game-template中game.odin结构与Game_Memory状态入门指南

odin-raylib-hot-reload-game-template 是一个开箱即用的 Odin + Raylib 游戏模板,最大亮点是内置热重载(Hot Reloading):修改游戏代码并重新编译后,正在运行的游戏会自动加载新逻辑,而游戏状态原封不动地保留。本文以 source/game.odin 为线索,带你读懂游戏主循环如何运转,以及 Game_Memory 状态结构为什么是热重载的核心。🎮

一、先认识项目结构:模板目录布局一览

整个模板非常精简,核心就三块:游戏代码、运行入口、构建脚本。

odin-raylib-hot-reload-game-template/
├── assets/                  # 游戏资源(纹理等),会打进发布包
│   └── round_cat.png
├── source/                  # 全部游戏源码
│   ├── game.odin            # 游戏核心代码(热重载的目标)
│   ├── utils.odin           # 跨平台文件读写封装
│   ├── main_hot_reload/     # 热重载入口(动态加载 game.dll)
│   ├── main_release/        # 发布版入口(普通可执行文件)
│   └── main_web/            # Web(WASM)入口
├── build_hot_reload.bat / .sh   # 热重载构建脚本
├── build_release.bat / .sh      # 发布版构建脚本
├── build_debug.bat / .sh        # 可调试构建脚本
└── build_web.bat / .sh          # Web 构建脚本

支持 Windows、macOS、Linux 和 Web 四个平台,编辑器方面对 Sublime Text、VS Code 和 RAD Debugger 都有专门说明(见 README.md)。

二、游戏主循环原理:初始化 → 更新 → 渲染 → 退出

所有游戏的主循环几乎都是同一个经典模式。以最简洁的发布版入口 main_release.odin 为例,主流程只有寥寥几行:

game.game_init_window()   // 1. 打开窗口
game.game_init()          // 2. 初始化游戏状态

for game.game_should_run() {
    game.game_update()    // 3. 每帧:更新逻辑 + 渲染
}

game.game_shutdown()          // 4. 释放状态内存
game.game_shutdown_window()   // 5. 关闭窗口

这个循环就是"游戏主循环"的全部骨架:窗口就绪 → 状态就绪 → 每帧更新并绘制 → 条件不满足时退出 → 清理资源。读懂了这个骨架,任何 Raylib 项目的运行流程你都能秒懂。✨

三、拆解 game.odin:主循环背后的核心文件

source/game.odin 是玩家真正要改的文件。它导出了一组以 game_ 为前缀的 proc(函数),各入口(包括热重载执行文件)都靠这些名字调用游戏逻辑:

导出 proc 职责 调用时机
game_init_window 创建游戏窗口(1280x720、可缩放、VSync) 启动时一次
game_init 分配并初始化 Game_Memory,加载资源 窗口就绪后一次
game_update 每帧调用 update() 处理输入 + draw() 渲染 每帧一次
game_should_run 判断是否继续循环(窗口关闭 / ESC 键) 每帧检查
game_shutdown 释放状态内存 循环结束后
game_shutdown_window 关闭窗口 最后执行

文件内部的逻辑组织也很清晰:

  • update(L62-L85):读取 WASD / 方向键输入,归一化后按帧时间移动玩家,并按 ESC 退出;
  • draw(L87-L107):用世界相机绘制玩家纹理,再用 UI 相机绘制调试文字;
  • game_camera / ui_camera(L45-L60):返回两个 Camera2D,实现"游戏世界"与"固定 UI"的分层渲染。

小提示:每个导出 proc 上的 @(export) 注解,是为了让热重载执行文件在 game.dll 里按 game_ 前缀找到这些符号(见 main_hot_reload.odin 的注释)。

四、Game_Memory 入门:游戏状态为什么要集中存放

打开 game.odin 最显眼的位置就是全局状态结构:

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

g: ^Game_Memory

两个设计点值得新手记住:

  1. 所有可变状态都塞进一个 struct:玩家位置、纹理、计数器、运行标志,没有散落各处。
  2. 全局只保存一个指针 g:指向堆上分配的那个 Game_Memory(在 game_init 中 new 出来)。

这正是为热重载埋下的伏笔——代码可以被换掉,但指针指向的那块状态内存不能丢。

五、热重载原理:Game_Memory 如何"续命"

运行 build_hot_reload.bat(Windows)或 build_hot_reload.sh 后,会生成两个东西:

  • 根目录下的 game_hot_reload 可执行文件(宿主,负责主循环);
  • build/hot_reload/game.dll(真正编译自 source/ 的游戏逻辑,热重载目标)。

宿主在主循环里做的事很简单:每帧检查 game.dll 的修改时间,发现文件变了就触发重载(main_hot_reload.odin)。重载的关键三步是:

  1. 调用旧 DLL 的 game_memory,拿到 g 指针;
  2. 加载新版 game.dll;
  3. 调用新 DLL 的 game_hot_reloaded,把同一根指针塞回去。

于是新代码"接管"了旧状态:玩家位置、纹理、计数器全部原样保留,游戏不重启、不重读资源,实现毫秒级热重载。⚡

两个边界情况也处理得很贴心:

  • 如果 Game_Memory 大小变了(新旧 DLL 的 game_memory_size 不一致),说明旧状态布局已不可用,宿主机回退为完整重启(重新 init);
  • 游戏内可按 F5(game_force_reload)强制保留状态重载,按 F6(game_force_restart)强制完整重启,方便随时验证两种路径。

六、三种运行入口对比:release、hot reload 与 web

同一个 game.odin,三种入口,三种运行方式:

入口 构建脚本 特点
main_release/ build_release.bat / .sh 普通可执行文件,game 包按普通 Odin 包编译,无热重载,用于发布
main_hot_reload/ build_hot_reload.bat / .sh 宿主 + game.dll 分离,支持热重载,仅用于开发
main_web/ build_web.bat / .sh 经 Emscripten 编译为 WASM 跑在浏览器,无热重载;通过 main_update 每帧驱动 game_update

值得注意的小细节:game_should_run 中用 when ODIN_OS != .JS 跳过了浏览器下的窗口关闭检测,因为该调用在 Web 端带有 16ms 睡眠,会拖慢帧率。跨平台分支就写在同一份游戏代码里,这正是 Odin 条件编译的便利之处。

七、动手跑起来:最快热重载体验步骤

git clone https://gitcode.com/gh_mirrors/od/odin-raylib-hot-reload-game-template
cd odin-raylib-hot-reload-game-template
  1. 运行 build_hot_reload.bat(macOS / Linux 用 build_hot_reload.sh,需将 odin 加入 PATH),生成可执行文件和 game.dll;
  2. 启动 game_hot_reload 并保持运行;
  3. 修改 source/game.odin,例如把 rl.ClearBackground(rl.BLACK) 改成蓝色,保存;
  4. 再次运行构建脚本——它会重新编译 game.dll(若游戏正在运行则跳过重编 exe),游戏立刻自动重载新逻辑,而玩家位置等状态保持不变。

如果你用 Sublime Text,直接打开 project.sublime-project,按 F7 即可编译 / 热重载;VS Code 用户则可在"运行和调试"侧栏选择 Run Hot Reload 启动,改完代码按 Ctrl + Shift + B 重建即可(详见 README.md)。🔧

八、小结:新手记住这三点就够了

  • 主循环骨架:init_window → init → for should_run { update } → shutdown,三种入口都遵循同一套生命周期 proc;
  • 状态集中化:所有可变状态放进 Game_Memory,全局只留指针 g,这是热重载的前提;
  • 热重载本质:宿主保留旧内存,把指针交给新 DLL 的 game_hot_reloaded,状态不丢、代码常新。

把 source/game.odin 当成你的游乐场,改一改移动速度、换一张纹理、加一个计数器,配合热重载秒级生效——这就是这个模板想给你的开发体验。祝玩得开心!

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