把游戏搬上网Usagi引擎Web导出与itch.io发布完整教程【免费下载链接】usagiA simple 2D game engine for rapid prototyping with Lua, featuring live reload and cross-platform export; this repo is a mirror and development happens at: https://codeberg.org/brettchalupa/usagi项目地址: https://gitcode.com/gh_mirrors/usagi1/usagi做了一款用 Lua 写的像素小游戏想让全世界玩家在浏览器里直接玩到Usagi 引擎的 Web 导出功能可以让这件事变得异常简单。本文是一份面向新手的Usagi 引擎 Web 导出与 itch.io 发布完整教程从安装引擎、初始化项目开始到一条命令打包出网页版游戏最后用 butler 把游戏上传到 itch.io 上线全程无需接触繁琐的 HTML5 构建配置。作为专为快速原型而生的开源 2D 游戏引擎Usagi 将本地开发到网页发布的距离压缩到只需几分钟。Usagi引擎是什么为快速原型而生的2D游戏引擎Usagi 是一个用 Lua 编写游戏逻辑的轻量 2D 游戏引擎它的核心卖点有两个实时热重载和一键跨平台导出。开发时运行usagi dev改完代码保存即可看到效果游戏状态不会丢失发布时运行usagi export就能同时产出 Linux、macOS、Windows 和Web网页版四个平台的安装包。引擎内置了暂停菜单、音量调节、按键重映射、存档系统等实用功能无需自己造轮子。官方还提供了大量可以直接运行的示例项目例如 examples/snake/main.lua 的贪吃蛇以及 book/src/code/01-dodge-em-up/ 目录下从零搭建躲避小游戏的完整教学代码。准备工作安装Usagi引擎并初始化项目动手导出前先把 Usagi 装好。Linux 和 macOS 用户执行curl -fsSL https://usagiengine.com/install.sh | shWindows 用户在 PowerShell 中运行irm https://usagiengine.com/install.ps1 | iex安装脚本会自动校验 SHA-256 校验和并把usagi加入 PATH之后在任意终端就能使用。如果你喜欢用包管理器也可以尝试 Homebrew 安装。若想从源码构建可以 clone 仓库https://gitcode.com/gh_mirrors/usagi1/usagi后用cargo build --release编译。安装完成后用一条命令初始化新项目usagi init path/to/my_game它会生成一个带有_init()/_update(dt)/_draw(dt)三个标准回调的 main.lua 模板并附带 usagi.conf 配置文件开箱即可运行。你也可以直接用usagi dev打开任一官方示例开始体验。一条命令完成Usagi引擎Web导出这是本教程最核心的一步。在项目目录下执行usagi export path/to/my_gameUsagi 会默认导出全部平台产物Linux、macOS、Windows 的 zip 包一个可移植的.usagi包以及游戏名-web.zip网页版压缩包。如果你只想生成 Web 版本加一个--target参数即可usagi export path/to/my_game --target web解压 web 压缩包后可以看到三个关键文件index.html网页入口、usagi.js和usagi.wasm引擎运行时、game.usagi你的游戏数据。整个导出逻辑在 src/export.rs 中实现引擎先把游戏打包成 bundle再与网页模板融合成 zip整个过程无需任何额外配置。Web 版游戏是解压即服务unzip-and-serve你可以用任意静态服务器本地预览例如cd export python3 -m http.server 8080浏览器打开localhost:8080即可看到游戏在网页中运行。用shell.html定制你的网页外壳默认的index.html是一个极简黑底页面会自适应缩放画布保证游戏在任意窗口尺寸下都能以像素风格清晰显示。如果你想要自定义加载动画、页脚水印或嵌入统计代码可以写一个自己的网页外壳把文件命名为shell.html并放在main.lua同目录下usagi export会自动识别并采用它也可以用--web-shell PATH手动指定。参考实现位于 web/shell.html它演示了如何用 CSS 变量控制画布纵横比以及如何实现点击进入游戏的遮罩层——这些细节让游戏在 itch.io 的 iframe 里也有良好的全屏体验。项目还提供了 web/mock-itch.html 用于本地模拟 itch.io 的全屏环境发布前可以先用它测试。发布到itch.io的完整操作步骤网页版导出成功后接下来就是把游戏搬上 itch.io。第一步注册账号并创建游戏页面。打开 itch.io 注册登录点击右上角 Upload new project填写游戏名称、简介、标签并选择分类。第二步安装并登录 butler。butler 是 itch.io 官方的命令行上传工具。从 itch.io 官网下载对应平台的版本后在终端执行butler login登录你的账号。第三步用 butler 上传 Web 版游戏。在游戏项目页面选择 Upload file把export/游戏名-web.zip拖拽上传并在 Kind of upload 中选择HTML类型。网页版游戏无需填写任何特殊参数——但请务必勾选This file will be played in the browseritch.io 会自动把 zip 解压到 iframe 中运行。第四步配置页面并发布。为游戏设置封面图分辨率不低于 315x250、加上标签和详细描述然后点击 Save and view page你的网页版游戏就正式上线了之后每次更新用但同样的方式上传新 zip 并覆盖旧文件即可。团队项目还可以用但但 butler 的命令行形式做持续集成比如参考项目自带的 scripts/push_itch.rb 脚本思路把上传流程脚本化。Web游戏发布到itch.io的常见问题游戏在 iframe 里没有全屏按钮Usagi 的网页外壳已经内置了全屏适配逻辑画布会跟随 iframe 尺寸自动缩放itch.io 的全屏按钮即可正常使用。音频不播放或画面卡顿多数浏览器要求用户交互后才能播放声音Usagi 默认提供点击进入遮罩层点击后音频解锁属于正常机制。若画面卡顿检查网络与game.usagi体积考虑压缩图片和音频资源。游戏存档能否保留Usagi 支持通过_config()配置游戏 ID网页版存档会保存在浏览器本地存储中玩家下次打开仍能读取进度。发布后想更新版本直接重新导出 web zip 并覆盖上传即可itch.io 会保留原有页面地址和玩家评价。小结从usagi export到 butler 上传Usagi 引擎把把游戏搬上网这件事简化成了几步操作初始化项目 → 一条命令 Web 导出 → 拖拽上传 itch.io。不需要配置 Emscripten、不需要写服务器代码Lua 写好的游戏逻辑原封不动跑在浏览器里。如果你也想快速把作品分享给全世界不妨现在就打开官方示例体验一次完整的Usagi 引擎 Web 导出与 itch.io 发布流程吧【免费下载链接】usagiA simple 2D game engine for rapid prototyping with Lua, featuring live reload and cross-platform export; this repo is a mirror and development happens at: https://codeberg.org/brettchalupa/usagi项目地址: https://gitcode.com/gh_mirrors/usagi1/usagi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
