Storm Lua Engine

StormworksのビークルLuaとAddon Luaを、アプリケーションに組み込むためのWASM SDK。

このパッケージはLua 5.3の実行基盤、Stormworks向けのCPU描画、同梱フォント、デバッガ、Vehicleコンパイラ、型定義を含みます。実際のワールド、地形データ、UI、ネットワーク通信は利用するアプリケーションが担当します。

インストール

npm install @stormcat-works/[email protected]

WASMと型定義は同梱済みです。利用時にRustやEmscriptenをインストールする必要はありません。

入口を選ぶ

| 目的 | 入口 | |---|---| | ビークルLua | loadRuntime() → engine.createVehicle(options) | | Addon Lua | loadRuntime() → engine.createAddon(options) | | 描画のみ | /rasterのloadRaster() → createRaster(width, height) | | 解析・リンク・minify | /compilerのloadCompiler() | | コンパイラWorker接続 | /compiler-worker。Workerの生成・終了はホストが管理 | | Canvas表示 | /canvasのCanvasPresenter |

ビークルはload(source)、tick()、draw(width, height)で駆動します。Compositeはvehicle.ioのFloat32Array/Uint8Arrayから読み書きし、画素はvehicle.frame().pixelsで借用、copy()で所有します。メモリ拡張後はビューを取り直してください。

Addonはload(source)、start()、tick(gameTicks)、dispatch(callback, args)で駆動します。g_savedataはsavedata()で取得し、encodeSavedata／decodeSavedataで携帯可能な形式にします。復元は新しいAddonのnewWorld:falseとsavedata、またはreload(checkpoint)を使用します。AddonにはComposite I/Oやdrawメソッドはありません。

ホスト機能をつなぐ

createVehicle({ mapProvider })でdrawMap用の同期地図rendererを指定できます。返す値は正確にwidth×height×4のRGBA bytes。未指定の地形を架空画像で代用しません。

createAddon({ server: { getPlayers: () => [playerTable] } })のように必要なserver関数を登録します。戻り値は常に結果の配列です。Lua integerにはbigint、floatにはnumber、byte stringにはUint8Array、テーブルにはluaTableまたは明示的なentry listを使用します。同期queryへPromiseを返すことはできません。

debug.logはgame/extendedで利用でき、printはextended専用です。onLog(record)は公開関数を追加せず、ログをコンソールやIDEへ接続します。recordはsourceとbytesを持ち、Luaの実行が戻った後に配送されます。手動処理にはdrainLogRecords／flushLogsもあります。

HTTPはdrainHttpRequestsからhostへ渡され、hostが実通信を行ってからhttpReply(token, bytes)またはcancelHttp(token)を呼びます。自動で外部へ通信しません。

ロードと破棄

ブラウザはawait loadRuntime()、NodeではWASMを明示的に読みloadRuntime({ wasmBinary })を使用します。WASMのexport pathは@stormcat-works/storm-lua-engine/wasm/storm_lua_wasm.wasm。独自bundlerやWebViewではmoduleUrl／wasmUrlまたはfromEmscripten(module)でアセットを接続します。

load/tick/draw/start/resumeはcompleted/suspended/missingを返し、エラーはEngineErrorなどの例外です。停止中は次のcallbackを重ねず、debuggerで確認してresumeします。使用後は必ずdispose。AddonのonDestroyも呼びたい場合は先にdestroyを明示してください。

配布とライセンス

npm registryまたはGitHub Releasesのtarballからインストールできます。runtime npm依存はありません。ブラウザごとの制約、全server APIのホスト実装、ゲームのsave XML直接互換は含まれません。

利用者向けの正本はdocs.makkii.jpです。契約・検証・Node/Rustの実行例はソースリポジトリに残します。MIT License。描画構成要素と外部依存の権利表示は同梱のSCREEN_COMPONENTS_LICENSE、THIRD_PARTY_LICENSES.txt、TOOLCHAIN_LICENSES.txt、RUST_STD_LICENSES.htmlを参照してください。

名前付きソースと再初期化

v0.2.0のrequireLoaderはextended専用です。ホストが同期で{source,name}を供給し、SDKが同じVMの継続で実行します。include-onceで戻り値を捨てる方式であり、Lua標準のmodule requireや静的buildとは別です。任意ファイルアクセスや再入は許可しません。

Vehicleのloadは別チャンクの追加実行です。resetは正常完了した全loadを再実行し、required modulesのキャッシュも再作成します。Addonのloadは初回だけとし、開発用モジュールはrequireLoader経由で利用します。詳しくはソース読み込みを参照してください。

最適化後のソースマップ（v0.3.0）

/compilerのloadCompiler()から、compiler.minify(source, {sourceMap:true, sourceName:'controller.lua'})を呼びます。成功時のcodeとmapを一組で保存し、compiler.validateSourceMap(code,map)で検証済みのOptimizationMapを取得してください。標準Source Map v3と、最適化理由・関連元・inline文脈・削除記録を持つx_stormが同じmap JSONに入ります。

build(project,{minify:true,sourceMap:true})とbuildLifeboat、CompilerWorkerClientも対応します。通常のminifyはmapを明示指定したときだけ詳細追跡します。mapなしと生成Luaは同じで、mapを8192文字制限のLuaへ埋め込む必要はありません。

標準readerによる表示、UTF-8バイト範囲とエディタのUTF-16位置の変換、結果の保存、VMの生成行との接続はホストが担当します。SDK更新だけで既存エディタの画面やブレークポイントが自動的に元位置へ切り替わるわけではありません。実行環境が行しか返さない場合は列を推測せず候補を表示してください。

マップには原文全文と固定化した設定を含みます。共有先を確認し、生成後のLuaに別の編集・minify・前置きを加えた古いmapは使わないでください。詳細な利用方法とNodeの実行例はSource Mapガイドにあります。