Skip to main content
このページは公開版v0.2.0に対応します。ソース・型定義・WASMを同じ版に揃えて使用してください。
IDE・シミュレータ・画像生成ツール・自動テストへLua実行を組み込む開発者向けのガイドです。エンジン自身を開発するための手順はCONTRIBUTINGに分離しています。

​
1. 必要な入口だけを選ぶ

ビークルとAddonの型・環境・生のWASMハンドルの検査を分離しています。createVm()という曖昧な入口はありません。ビークルにはcreateVehicle()、AddonにはcreateAddon()を使用してください。

​
2. インストールする

TypeScript／JavaScriptではnpm install @stormcat-works/storm-lua-engine@0.2.0を実行します。JS、型定義、実行用・描画専用・コンパイラ専用WASMを同梱しています。利用するだけならRustやEmscriptenは不要です。 オフライン環境ではGitHub Releasesのtarballを取得し、npm install ./stormcat-works-storm-lua-engine-0.2.0.tgzでインストールできます。 RustではアプリのCargo.tomlへ例えばstorm-lua-addon = { git = "https://github.com/Stormcat-Works/storm-lua-engine", tag = "v0.2.0" }を追加します。debuggerを使う場合はfeatures = ["debug"]を指定します。Lua実行クレートはvendored LuaのビルドにCコンパイラを使用します。描画専用クレートにLuaバックエンドは含まれません。 RustクレートはGit依存で配布します。描画だけなら同じGit URLとタグでstorm-screen-rasterを指定してください。ローカルで本体を開発する場合には、クローンしたクレートへのpath依存も使えます。

​
3. 初期化と実行

ブラウザではawait loadRuntime()で初期化します。以後のload、tick、drawは同じスレッド上で同期実行されます。bundler/WebViewでアセットURLを変更する場合はmoduleUrlとwasmUrlを渡すか、初期化済みEmscripten moduleをfromEmscripten(module)へ渡します。 Nodeではimport.meta.resolve('@stormcat-works/storm-lua-engine/wasm/storm_lua_wasm.wasm')でパッケージ内のWASMを解決し、読み込んだbytesをloadRuntime({ wasmBinary })へ渡します。ファイルの読み込みはNode側が担当します。 全体を試す場合は、Node利用例をインストール済みアプリへコピーしてnode node.mjsを実行します。ビークル制御、ホスト地図、Addonのサーバー関数、ログ、HTTPの手動返信、保存・復元まで含みます。合成した地図と手動返信は例のホストが明示提供するもので、エンジンの暗黙フォールバックではありません。 Rustの対応例はaddon_host.rsです。このリポジトリ内ではcargo run -p storm-lua-conformance --example addon_host --lockedで実行できます。consumerがconformanceクレートへ依存する必要はありません。

​
4. 結果とメモリを扱う

load／tick／draw／resumeはcompleted、suspended、missingを区別します。suspendedはデバッグ停止であり、コールバック終了ではありません。別のtickや設定更新を行わず、検査後にresume()してください。 Rustの失敗はResult、TSのエンジン失敗はEngineErrorで返します。JS側の不正な型・範囲はTypeError／RangeErrorの場合もあります。複数の失敗（Luaとログ配送など）が同時に起きた場合はAggregateErrorで両方を保持します。 vehicle.ioは320byteのI/Oへの借用ビューです。LuaやWASMで確保が起きた後はvehicle.ioを取り直します。vehicle.frame().pixelsは次のフレーム変更・reset・disposeまでの借用で、vehicle.frame().copy()は保持やWorker transfer用の所有コピーです。既に取得したTypedArrayを後から強制回収できる仕組みではありません。

​
5. 実行環境へ接続する

表示には任意のCanvas/GPU処理を使えます。/canvasのCanvasPresenterは、ホストが渡したcanvasへ明示的にコピーします。ループやWorkerは作りません。ブラウザ例とWorker例を参照してください。 未信頼LuaをUIスレッドで長時間動かすことは避け、必要ならWorkerへ分離します。Lua命令予算は長時間のホスト関数を中断する保証ではありません。使用後は必ずdispose()を呼びます。AddonのonDestroyも実行する場合は、その前にdestroy()を明示します。 次はAddonガイド、ホスト機能・ログガイド、API一覧から目的の項目へ進んでください。