v0.4.0のJavaScript・型定義・WASMを一組で使用します。SDKはマップの生成と検証までを提供し、エディタの表示・保存・実行位置との接続はホストが担当します。
生成する
npm install @stormcat-works/storm-lua-engine@0.4.0で導入します。@stormcat-works/storm-lua-engine/compilerのloadCompilerを初期化し、単一ソースはcompiler.minify(source, {sourceMap:true, sourceName:"controller.lua"})へ渡します。
複数ファイルではcompiler.build(project, {minify:true, sourceMap:true})、LifeBoatのinclude-once方式ではcompiler.buildLifeboat(project, {minify:true, sourceMap:true})を使用します。元moduleへの位置合成はSDKが行います。map内のファイル名は表示名であり、SDKがディスクからそのファイルを開くわけではありません。
コンパイラを初期化した後の基本操作は次のとおりです。
build({minify:false})が標準mapを返す従来動作は維持し、sourceMap:trueで詳細拡張も追加します。マップ有無で生成Luaの短縮結果は変わりません。
マップはゲームへ貼り付けるLuaとは別の成果物です。codeだけを実行し、mapはホスト側へ保管します。8192文字制限のLuaへマップを埋め込む必要はありません。
同じ組を検証・保存する
mapはSource Map v3形式のJSON文字列です。標準のsources、sourcesContent、names、mappingsに加え、x_stormへ詳細な由来・理由が入ります。
validateSourceMap(code,map)は、生成コード・原文snapshot・設定・mapの指紋、範囲・参照、標準mapと詳細情報の整合性を検証し、型付きのOptimizationMapを返します。読み込んだJSONに型アサーションを付けるだけで検証済みにしないでください。フィンガープリントは内容の整合性検査で、発行者を保証する署名ではありません。
details.producer.versionは生成したエンジン版、details.schemaVersionは独自形式の版で、v0.4.0では2です。Source Map本体のversion:3とは別です。独自に配信していた旧compiler.jsやcompiler_bg.wasmも、npmパッケージと同じ版へ更新します。古いWorkerやService Workerのキャッシュも残さないでください。
schema 2の詳細情報を読む
schema 2ではmapの容量を減らすため、字句短縮などの位置対応をtokensとtokenNamesのトークン表へ格納する場合があります。複数ソースやリネームしたトークンにも対応し、通常のorigins・mappingsとトークン表が混在するmapもあります。JSONのx_storm.mappingsだけを直接読んで全範囲が揃うと判断しないでください。
validateSourceMapは保存形式の整合性を検証した後、トークン表を展開し、正規化したOptimizationMapを返します。表示には返却されたdetails.mappingsとdetails.originsを使用してください。返却値のtokensとtokenNamesは空になります。標準Source Map v3の位置対応は、引き続き標準readerから利用できます。
標準の位置を引く
標準readerを利用するホストでは、npm install @jridgewell/trace-mappingなどでconsumerを追加できます。これはホストの任意の依存で、SDK自体の実行時依存ではありません。
position.sourceがnullなら、近い原文の行へ勝手に移動しません。標準readerの検索はマップにあるアンカーを使います。厳密なUnknown範囲・copy内部・複数の関連元・削除状況は、詳細情報も参照します。
理由と複数の関連元を表示する
details.mappingsは生成Lua上の非重複な範囲表です。start以上end未満の位置がその区間に属し、originはdetails.originsのindexです。origin:nullはUnknownであり、自動生成とは異なります。
理由は
codeとoperation、記録された場合のbasisとfactsを持ちます。根拠がnullの場合、表示側がパス名から判断値を推測しません。
例えば、通常のtolerant設定で2*3が6になった場合、生成6は元の式全体と定数評価の理由へ対応します。関数のインライン化では、定義側のリテラルをそのまま示しながら、呼び出し元の文脈も取得できます。exact/tolerantやパス設定が異なると、選ばれる変換も異なります。
詳細情報が示す範囲はUTF-8バイトの半開区間、JavaScript文字列のindexや一般的なエディタ位置はUTF-16です。日本語・絵文字を含むコードで単純に同じ数値として扱わないでください。検証済みのcopied区間は同一バイトのコピーなので内部位置を対応させられます。変換された式や広いgroupを文字単位で補間してはいけません。
Nodeで実行する例
optimized-source-map.mjsは、インストールしたSDKのWASMを読み、map生成・検証、標準位置、理由・関連元、インライン文脈、古いmapの拒否を確認します。npm install @stormcat-works/storm-lua-engine@0.4.0 @jridgewell/trace-mappingの後、同ファイルを保存してnode optimized-source-map.mjsで実行できます。Node 22.18以降のESMを使用します。コードからLuaを実行する例ではありません。
非短縮プロジェクトの実停止・ステップ・エラー位置を接続する例はsource-map.mjsです。こちらは元moduleをビルドしてVMへ明示loadし、実行結果も確認します。
ブラウザーとWorker
ブラウザーではコンパイラをホスト所有のmodule Workerへ置き、/compiler-workerのserveCompilerとCompilerWorkerClientで接続できます。await client.minify(source,{sourceMap:true})、await client.validateSourceMap(code,map)が対応します。Worker生成・終了と、同じ版のJS/WASMを配信する設定はホスト側です。
コンパイルと理由JSONの生成には追加の処理負荷がかかります。validateSourceMapもコンパイラ側へ依頼できるため、UIスレッドで大きなマップを繰り返し検証する必要はありません。得られた検証結果を同じ成果物IDに紐付けて使用します。
PlaygroundのSource Map例では、元コードと生成コードを双方向に選択し、理由・複数の候補・除去記録を確認できます。既存エディタにUIが自動で追加されるわけではありません。
実行位置とブレークポイント
VMのloadには生成codeと安定したチャンク名を渡します。ホストはそのチャンク名・実行世代と対応mapを保持し、元範囲から生成行の候補を取得してvm.setBreakpoints()へ設定します。停止したstack、ログ、エラーの生成位置を同じmapで元位置へ戻します。
マップを作成しても、VMが返す行の精度が列や命令位置へ自動的に増えるわけではありません。行しか分からない場合は、その生成行に対応する元位置を候補として示します。 1行に圧縮されたLuaでcolumn=0を任意に指定し、それを実際の失敗位置として表示しないでください。
削除された原文に実行箇所がない場合、近くの生成行へbreakpointを移しません。copy区間にコメントの位置があっても、そこが実行可能な停止箇所とは限りません。元変数の値・寿命、インライン化で消えた実frame、特定のloop反復や過去の実行状態は、この静的マップだけでは復元しません。
lintと前処理
analyze(project)は元moduleを直接解析します。lintのためだけに先にminifyする必要はありません。SDKのリンクやLifeBoat開発区間の除去を使う場合、対応するビルド経路が元位置を管理します。
ホストがSDKへ渡す前に独自の文字削除・連結などを行う場合、その前処理とエディタ原文の対応は別途必要です。前処理後の位置を元の編集バッファの位置とみなさないでください。
Compiler · API一覧 · Playground