读懂游戏主循环:odin-raylib-hot-reload-game-template中game.odin结构与Game_Memory状态入门指南
读懂游戏主循环: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
两个设计点值得新手记住:
- 所有可变状态都塞进一个 struct:玩家位置、纹理、计数器、运行标志,没有散落各处。
- 全局只保存一个指针
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)。重载的关键三步是:
- 调用旧 DLL 的 game_memory,拿到
g指针; - 加载新版
game.dll; - 调用新 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
- 运行
build_hot_reload.bat(macOS / Linux 用build_hot_reload.sh,需将odin加入 PATH),生成可执行文件和game.dll; - 启动
game_hot_reload并保持运行; - 修改 source/game.odin,例如把
rl.ClearBackground(rl.BLACK)改成蓝色,保存; - 再次运行构建脚本——它会重新编译
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 当成你的游乐场,改一改移动速度、换一张纹理、加一个计数器,配合热重载秒级生效——这就是这个模板想给你的开发体验。祝玩得开心!