-
Notifications
You must be signed in to change notification settings - Fork 23
Home
Welcome to the soluna wiki! google translate this page into English
soluna 是一个基于 sokol 的 2D 游戏引擎。它以 Lua 为编程语言，整合了 ltask 作为多线程框架。sokol + lua 是其名字的由来。
soluna 目前支持 Windows/macOS/Linux/Web ，可以使用 luamake 构建各个平台的版本。在 Windows 平台，也可以使用 GNU Make 构建：默认使用 mingw 环境，可以用 make CC=cl 切换为 msvc 环境。
在构建完毕后，引擎所有相关代码和资源都会打包到一个执行文件中，没有额外的数据文件依赖。你也可以直接下载预编译版本。
执行引擎执行文件可以运行游戏。
游戏由若干 lua 代码文件和相关的资产文件（如数据、图片等）构成。可以是一个本地目录，也可以是一个 zip 包。引擎运行时，默认检查当前目录下是否有 main.zip ，若有则将其作为需要启动的游戏；若没有则将当前目录作为游戏所在地。也可以从命令行传入 zip 包文件名改变需要启动的游戏，或传入一个游戏环境文件指定游戏。
游戏环境指游戏运行的若干配置，其默认值在 src/data/settingdefault.dl 被打包到引擎执行文件中。可以在游戏包中放入一个环境文件 main.game 覆盖这些默认配置。或在命令行中指定游戏环境文件名。
也可以在命令行中通过 key=value 指定需要改写的配置项。
入口文件名是游戏启动时第一个被加载运行的 lua 代码文件。默认为 main.lua ，即引擎默认会在游戏包中查找名为 main.lua 的文件运行它。如果引擎在运行时找不到这个 entry （入口）文件，则会报告 Can't load entry main.lua 并退出。
如果命令行指定 soluna test/window.game 启动，则会以 test/window.game 为环境启动游戏（并将当前目录设定为 test）。因为在 test/window.game 中指定了 entry:window.lua ，所以 test/window.lua 就成为了游戏入口。
也可以通过命令行指定 soluna entry=test/window.lua 也可以以它为入口文件启动游戏。这里的命令行参数 entry=test/window.lua 指将 entry 的默认值 main.lua 修改为 test/window.lua
soluna.js 是一个 ES module，默认导出 createApp 工厂函数；页面侧需要用 import 或动态 import() 加载它，再显式传入 canvas、arguments、preRun 和 locateFile 等参数。
一个典型流程如下：
- 使用 soluna (Windows/macOS/Linux) 进行游戏开发。
- 将游戏源码 (lua) 打包成
main.zip。 - 在仓库根目录构建 wasm runtime：
luamake -compiler emcc
- 部署页面时，需要提供
soluna.js、soluna.wasm、main.zip。 - soluna wasm 使用了 pthread，因此页面必须启用跨源隔离（COOP/COEP）。具体要求可见 https://emscripten.org/docs/porting/pthreads.html#pthreads-support 。如果静态托管平台不方便直接配置响应头，也可以像示例站点一样使用
coi-serviceworker.min.js来补上隔离环境。
示例站点源码位于 website/ 目录，职责分为两部分：
-
luamake负责构建 wasm runtime，本体产物位于bin/emcc/<mode>/，包括soluna.js、soluna.wasm，以及可选的soluna.wasm.map。 -
website/scripts/prepare-runtime.mjs在 Astro 构建前把这些运行时文件复制到website/public/runtime/，同时打包asset/生成asset.zip。 - GitHub Pages workflow 会先执行
.github/actions/soluna，再把这些路径通过环境变量传给 Astro build，最后部署website/dist/。
如果你只是想运行站点，最直接的入口是：
luamake -compiler emcc
cd website
pnpm install
pnpm run dev更多细节可以参考仓库里的 website/README.zh-CN.md。
下面是一个最小示例。它会以 ES module 的方式加载 soluna.js，再把 main.zip 写入 memfs 后启动 soluna。
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Soluna Game</title>
<style>
body { margin: 0; background: #000; }
canvas { display: block; width: 100vw; height: 100vh; }
</style>
</head>
<body>
<canvas id="canvas" oncontextmenu="event.preventDefault()"></canvas>
<script type="module">
import createApp from './soluna.js';
async function fetchBytes(url) {
const response = await fetch(url);
if (!response.ok) {
throw new Error(`HTTP ${response.status} while fetching ${url}`);
}
return new Uint8Array(await response.arrayBuffer());
}
async function main() {
if (!window.crossOriginIsolated) {
throw new Error('Cross-origin isolation is required for pthread-enabled Soluna wasm.');
}
const canvas = document.getElementById('canvas');
const mainZip = await fetchBytes('./main.zip');
await createApp({
canvas,
arguments: ['zipfile=/data/main.zip'],
locateFile(path) {
return new URL(path, import.meta.url).toString();
},
preRun: [
function (module) {
module.FS_createPath('/', 'data', true, true);
module.FS.writeFile('/data/main.zip', mainZip, { canOwn: true });
},
],
print(text) {
console.log(text);
},
printErr(text) {
console.error(text);
},
onAbort(reason) {
console.error('Program aborted:', reason);
},
});
}
main().catch((error) => {
console.error(error);
});
</script>
</body>
</html>extlua 是 soluna 用来加载外部 C 模块的一套机制。
典型配置如下：
extlua_entry : extlua_init
extlua_preload : sample
这表示启动时会按 package.cpath 查找名为 sample 的外部模块，并以 extlua_init 作为入口函数加载它。
在非浏览器环境下，这个模块通常是一个动态库。
在 wasm 环境下，它通常编译为一个额外的 side module，因此部署时需要：
- 额外构建对应的 side module，例如
sample.wasm。 - 把它写入虚拟文件系统，比如
/data/sample.wasm。 - 在启动参数中追加
cpath=/data/?.wasm，这样require "ext.foobar"才能找到该模块。