Skip to main content
このページはv0.4.0に対応します。0.1.0にはCompiler SDKは含まれません。対応するソース・型定義・WASMを同じ版で使用してください。

操作の選択

いずれもLuaを実行しません。ファイルを読み込んだり、VMを作ったり、ゲームのtickを進めたりする処理も含みません。passMetadata()の件数と登録パス総数は同じではありません。 minify、通常のbuild、analyzeの対象はVehicleです。target: "addon"は拒否します。Addonの非短縮リンクには専用のbuildAddonを使用します。Addon最適化と全server APIの解析は提供しません。

論理プロジェクト

プロジェクトはentry、modules、任意のambientを持ちます。modulesは論理モジュール名からLuaソースへの対応表です。例えば、{entry:"main", modules:{main:"local m=require('util') return m.value", util:"return {value=7}"}}です。 ファイルパス、保存、監視、エディタの未保存バッファはホスト側が管理します。単一ソースを短縮するだけなら、プロジェクトを作る必要はありません。 ambientは名前空間ごとに、注入可能なモジュールや実行環境専用の定義を指定します。非短縮リンクと最適化ビルドは、同じモジュール構造・注入規則を使用します。

Rustから使用する

解析はstorm_lua_analysis::analyze(&project, &options)、プロジェクトビルドはstorm_lua_build::build(&project, &options)、単一ソースはstorm_lua_build::minify(source, &options)です。 これらは同期的で、ファイルシステムやLua VMを必要としません。通常のホストは上位APIを使い、明示的な候補処理が必要な場合だけstorm-lua-minifyを参照します。ASTを直接作る低レベル利用者は、ノードIDと構造の契約を守る必要があります。 Nativeの実行例は、2モジュールをビルドし、生成物を明示的にVehicleへロードして出力を確認します。利用アプリがconformanceクレートへ依存する必要はありません。

TypeScriptから使用する

@stormcat-works/storm-lua-engine/compilerからloadCompilerをimportし、await loadCompiler()でコンパイラだけを初期化します。このサブパスをimportしただけではWASMをロードせず、初期化しても実行系・描画系のWASMは読み込みません。 単一ソースにはcompiler.minify(source, {target:"vehicle", numericMode:"exact", zeroCostNewlines:false})を使います。複数ソースには、非短縮のcompiler.build(project, {minify:false})、またはcompiler.build(project, {minify:true, targetSize:8192})を使います。編集中の診断はcompiler.analyze(project)として分離します。 Nodeでは選択したWASMファイルをホスト側で読み込み、wasmBinaryとして渡せます。ブラウザでは既定の同梱アセット、wasmUrl、またはbytesを指定します。moduleUrlは信頼した生成JSアダプタの場所です。wasmUrlとwasmBinaryは同時に指定しません。 初期化後の処理は同期的です。ブラウザではホストが作ったWorkerから呼び、UIやシミュレーションと分離します。/compiler-workerのCompilerWorkerClientとserveCompilerは通信を共有するためのアダプタです。Workerを自動で作らず、終了・中断はホストが決めます。環境ガイドを参照してください。

出力と適用条件

コンパイル成功と目標文字数達成は別です。ok、diagnostics、code、size、search.targetMetを確認し、ホストが表示・保存・エクスポートの可否を判断します。文字数未達を構文エラーへ置き換えることはありません。 v0.4.0では、Luaのロード時にエラーとなるソースを最適化で受理可能な形に変換せず、コンパイル時に拒否します。非vararg関数内の...など、旧版で受理されていた入力もエラーになる場合があります。再帰的な構文解析の深さが128段、構文木の深さが256段を超えるソースも、Native/WASMの両方で構文診断を返します。 numericMode: "exact"と"tolerant"は数値変換の契約です。mode:"safe"を指定することとexactを指定することは同義ではありません。assumptions、disabledPasses、propertyModeなどの結果も確認してください。 v0.4.0では、数値リテラル・Luaのbyte文字列・評価順序・スコープなどで意味が変わる問題を修正しました。安全に適用できる条件に絞ったため、短縮後の文字数が以前より増える場合があります。 非短縮ビルドは従来どおり標準Source Mapを返します。最適化後もsourceMap:trueを指定すると、元ファイルや名前、トークン、式などに対応付けるSource Map v3と、x_storm.schemaVersion: 2の理由・関連元を取得できます。codeとmapを同じビルドの組で保存してください。手順はSource Mapガイドにあります。 通常のminifyは詳細mapを明示的に有効にした場合だけ由来情報を生成します。mapはゲームへ渡すLuaとは別のホスト側成果物で、Luaの文字数に加えません。消えた元変数値・フレーム・実列の復元を自動的に行うものではありません。 targetSizeを指定すると、目標内の候補が見つかった後も、実行速度を重視した候補の探索を続けます。目標なしの最高圧縮とは区別してください。 targetSize未達の場合は、同じ意味論・パス設定で最大限探索した場合と同じ生成Luaを返します。目標なしのsearchMode:"fast"は候補数を制限します。時間を指定して探索を打ち切るAPIではありません。

環境と動的参照

既定の環境はgameです。既知の不在機能への依存は、編集時の解析では警告、単一・複数ソースの生成ではエラーになります。nil/typeによる存在確認や、自分で定義した同名ローカルは名前だけで拒否しません。 ソースに代入がない外部グローバルは勝手に改名・nil化しません。_ENVへのアクセス・再束縛、extended環境、ホスト関数の置換を使うコードは、識別子・リテラル・トークン順序・行位置を保持する字句短縮を行います。 この経路ではconservative-minificationとsearch.mode:"lexical"を返し、property固定化やAST最適化は行いません。目標文字数を超えても危険な変換へ切り替えません。 開発用のrequireLoaderと、コンパイラの静的リンクは別の仕組みです。ビルドがruntimeのホストローダーを呼び出すことはありません。読み込み方式の違いはrequireと複数チャンクにまとめています。

廃止設定

general-expression-factoring、repeated-expression-factoring、scalar-vector-loop-synthesis、redundant-nil-fallback-eliminationは削除済みです。未知または廃止されたパスIDは、true/falseのどちらでもunknown-optimization-passになります。数値モードによる正当な除外とは別の扱いです。 実行可能なconsumerと適合性試験はSDKリポジトリで管理します。利用者向けの手順はこのサイトを正本とし、コード内部の実装仕様・テスト記録とは分離しています。

Addonの非短縮ビルド

compiler.buildAddon(project, {environment: "game", metadataTag: "studio"})で、literalなincludeを一つの読みやすいLuaへリンクします。Vehicleの最適化・property特殊化・8192文字目標は使用しません。minifyやtargetSizeの指定はエラーです。返り値を捨てるinclude-once方式であり、通常の値返却型モジュール方式と区別します。 metadataTagは、指定した先頭行を持つ先頭のlong commentだけを除去します。通常のbuildとbuildLifeboatでも指定できます。元のbyte位置・改行を保持し、mapのsourcesContentには元metadataを含めます。ゲームへ提出するLuaの出力と、元ソース入りmapを共有するかどうかは別々に判断してください。 v0.4.0では、metadataTag・minify:false・sourceMap:trueを同時に指定した通常ビルドまたはLifeBoatビルドで、map検証に失敗する不具合も修正しました。 Addonのgame環境ではselectを提供しません。自分で定義した関数とnil/typeによる存在検査は維持し、開発用途にはextendedを明示できます。