wasm2usharp

A tool for converting WebAssembly to UdonSharp

Installation

You can download prebuilt binaries from the Releases page.

If you are using Cargo, you can install from Cargo.

cargo install wasm2usharp

How to use

Usage: wasm2usharp [OPTIONS] [INPUT]

Arguments:
  [INPUT]  Input file. If not provided or if this is `-` then stdin is used

Options:
  -o, --output <OUTPUT>        Where to place output. If not provided then stdout is used
  -n, --namespace <NAMESPACE>  Namespace to use for the generated class
      --test                   Convert to C# instead of UdonSharp for testing
  -h, --help                   Print help
  -V, --version                Print version

See examples for usage in a VRChat project.

In U#, you need to call w2us_init method first for initialization
Global variables, memory, and table exported by Wasm become public fields in U#, and functions exported by Wasm become public methods in U#
Imports in Wasm create public fields of type class_module_name for each module name in U#, and they are accessed by module_name.import_name in the converted code
The identifier _start in Wasm will be replaced by w2us_start after conversion to U#. This is to prevent a function named _start, which is an entry point in WASI, from being called unexpectedly, since it is treated as a Start event function in Udon.
Recursive calls to functions that are completed within Wasm are handled correctly, but if a function is recursively called by calling an external function from Wasm and then calling the Wasm function again from outside, the value of the local variable of the recursively called function may not be correct
Integer types in Wasm correspond to signed integer types in U#
If an output file name is specified in the command, the file name minus the extension is the class name in U#
In Wasm export/import names, non-alphanumeric characters are replaced by _, and if the first letter is a number or the same name as a C# keyword, it is prefixed with _

Supported Wasm proposals

Import/Export of Mutable Globals
Non-trapping float-to-int conversions
Sign-extension operators
Bulk memory operations (Only memory.copy and memory.fill instructions are supported)

日本語

WebAssemblyからUdonSharpへの変換ツール

インストール

Releasesのページから、ビルド済みのバイナリをダウンロードできます。

Cargoを使用している場合、Cargoからインストールすることができます。

cargo install wasm2usharp

使い方

Usage: wasm2usharp [OPTIONS] [INPUT]

Arguments:
  [INPUT]  入力ファイル。指定されない、または`-`の場合は標準入力が使用される

Options:
  -o, --output <OUTPUT>        出力先の場所。指定されない場合は標準出力が使用される
  -n, --namespace <NAMESPACE>  生成されるクラスに使用する名前空間
      --test                   テストのためにUdonSharpの代わりにC#へと変換する
  -h, --help                   ヘルプを出力
  -V, --version                バージョンを出力

VRChatプロジェクト内での使用例はexamplesを参照してください。

U#では初期化のために最初にw2us_initメソッドを呼ぶ必要がある
Wasmでエクスポートされたグローバル変数・メモリ・テーブルはU#ではpublicフィールドとなり、 Wasmでエクスポートされた関数はU#ではpublicメソッドとなる
Wasmでのインポートは、U#ではモジュール名ごとにclass_モジュール名型のpublicフィールドが作成され、変換されたコード内ではモジュール名.インポート名でアクセスされる
Wasmでの_startという識別子は、U#への変換後はw2us_startに置き換えられる。これは、WASIのエントリーポイントである_startという名前の関数は UdonではStartイベント関数として扱われるので、予期せず呼ばれるのを防ぐためである。
関数の再帰呼び出しは、Wasm内で完結する再帰呼び出しは正しく処理されるが、 Wasmから外部の関数を呼び出し、外部から再度Wasmの関数を呼び出すことで再帰呼び出しされる場合は、再帰呼び出しされる関数のローカル変数の値が正しくならない可能性がある
Wasmでの整数型はU#の符号付き整数型と対応する
コマンドで出力ファイル名を指定した場合は、そのファイル名から拡張子を除いた名前がU#のクラス名となる
Wasmのエクスポート・インポートの名前は、英数字以外の文字は_に置換され、先頭が数字の場合とC#のキーワードと同じ名前の場合は先頭に_が付与される

対応しているWasm proposal

Import/Export of Mutable Globals
Non-trapping float-to-int conversions
Sign-extension operators
Bulk memory operations (memory.copy命令とmemory.fill命令のみ対応)

wasm2usharp 0.2.2