はじめに

aulua は、AviUtl ExEdit2（以下 AviUtl2 と言う）用の Lua スクリプトのビルドやインストールを支援する CLI ツールです。

AviUtl2では主に Lua を使ってアニメーション効果やカスタムオブジェクトなどのスクリプトを作成することができます。 Lua なのでテキストファイルを書くだけで AviUtl2 の機能を拡張でき手軽でよいのですが、開発中不満に感じる点がいくつかありました。

--select が長くなりすぎてつらい
--track の最大値、最小値、既定値、ステップの順番を忘れがち
シェーダーや@スクリプト（1ファイルに複数のスクリプトをまとめたもの）など開発中はファイルを分割しておいて、最後に1つのファイルに合体させたい
スクリプト冒頭に書いてあるバージョン表記など、外から値を指定したい
など

aulua はこのような不満を解消することを目的とします。

インストール

aulua は以下のいずれかの方法でインストールしてください。

WinGet からインストール

Windows 11 や Windows 10 の最新バージョンには WinGet が標準でインストールされているため、ターミナルで以下のコマンドを実行すればインストールできます。

winget install -e --id Karoterra.Aulua

Cargo でインストール

Rust がインストールされている場合は Cargo からインストールできます。

cargo install --locked aulua

Releases からダウンロード

Releases から最新版をダウンロードし、 aulua.exe （あるいは aulua）を PATH の通ったディレクトリに配置してください。

aulua-<version>-windows-x64.zip: Windows 用（例： aulua-v0.4.1-windows-x64.zip）
aulua-<version>-linux-x64.tar.gz: Linux 用（例： aulua-v0.4.1-linux-x64.tar.gz）

使い方

テンプレートをビルド

# aulua プロジェクトを初期化
aulua init hello-aviutl2-script

cd hello-aviutl2-script

# ビルド：デフォルトでは build ディレクトリに出力される
aulua build

手動セットアップ

aulua.yaml ファイルを作成する。
スクリプトソースを作成する。
aulua build を実行する。

コマンド

aulua で利用可能なコマンドは aulua help を実行すると確認できます。

aulua には以下のコマンドがあります。

aulua init — 指定したフォルダに aulua.yaml などいくつかのテンプレートを作成します。
aulua build — スクリプトファイルをビルドします。
aulua install — スクリプトファイルをインストールします。
aulua pack — au2pkg パッケージを作成します。
aulua schema — aulua.yaml のスキーマファイルを出力します。

aulua init

aulua を利用する際にはスクリプトファイルのソースのほかに aulua.yaml という名前の設定ファイルがプロジェクトごとに必要です。 init コマンドはこのようなテンプレートを生成してプロジェクトの開始をサポートします。

init コマンドは以下のように実行します。

aulua init

init コマンドを実行すると以下のファイルが生成されます。

project-dir/
├── .gitignore
├── .gitattributes
├── .editorconfig
├── aulua.yaml
└── script/
    ├── SampleAnimationEffect.anm2
    └── SampleShader.hlsl

aulua.yaml はプロジェクトの設定ファイルです。

スクリプトソースのサンプルとして SampleAnimationEffect.anm2, SampleShader.hlsl を出力しています。スクリプトソースは script/ ディレクトリに配置する必要はないので、プロジェクトの方針に合わせて src/ ディレクトリにしたり、 aulua.yaml と同じ場所に配置しても問題ありません。

.gitignore, .gitattributes, .editorconfig はお節介で出力しているファイルであり、 aulua の動作には必要ありません。

ディレクトリの指定

init コマンドを実行するとカレントディレクトリにテンプレートを生成しますが、出力先のディレクトリを指定することもできます。

aulua init path/to/dir

aulua build

build コマンドは aulua の一番主なコマンドです。 aulua.yaml の内容に応じてスクリプトソースからスクリプトファイルをビルドします。

build コマンドは以下のように実行します。

aulua build

ビルド出力先は aulua.yaml の build.out_dir で指定します。

コマンドは aulua.yaml と同じ場所で実行してください。

aulua install

install コマンドはビルドしたスクリプトファイルを所定のディレクトリにコピーします。

install コマンドは以下のように実行します。

aulua install

コピー先は aulua.yaml の install.out_dir で指定します。

コマンドは aulua.yaml と同じ場所で実行してください。

`--dry-run`

--dry-run オプションを指定するとファイルはコピーせず、どのファイルがどこにコピーされるかだけ表示します。

aulua install --dry-run

aulua pack

pack コマンドは au2pkg パッケージを生成します。

pack コマンドは以下のように実行します。

aulua pack

パッケージに関する設定は aulua.yaml の package セクションで指定します。

コマンドは aulua.yaml と同じ場所で実行してください。

aulua schema

schema コマンドは aulua.yaml のスキーマファイルを出力します。

schema コマンドは以下のように実行します。

aulua schema

デフォルトではカレントディレクトリに aulua.schema.json というファイル名で出力します。

`-o`, `--output`

出力先ファイルのパスは -o または --output で指定できます。

aulua schema -o path/to/file.json
aulua schema --output path/to/file.json

設定ファイル aulua.yaml

aulua ではプロジェクトの設定ファイルを aulua.yaml に記載します。以下は設定ファイルのサンプルです。

aulua.yaml

# yaml-language-server: $schema=https://raw.githubusercontent.com/karoterra/aviutl2-aulua/refs/heads/main/schema/aulua.schema.json

project:
  variables:
    VERSION: v1.0.0
    AUTHOR: karoterra

build:
  out_dir: build
  embed_search_dirs:
    - lib

install:
  out_dir: C:\ProgramData\aviutl2\Script\karoterra\

scripts:
  - name: 色覚シミュレーションKR.anm2
    sources:
      - path: script/色覚シミュレーションKR.in.anm2
        variables:
          INFO: 色覚シミュレーションKR for AviUtl2

  - name: "@MyEffect.anm2"
    sources:
      - path: scripts/EffectA.in.anm2
        label: EffectA
        variables:
          INFO: MyEffect (EffectA)
      - path: scripts/EffectB.in.anm2
        label: EffectB
        variables:
          INFO: MyEffect (EffectB)

project

プロジェクト全体に関する設定を指定します。

project:
  variables:
    VERSION: v1.0.0
    AUTHOR: karoterra

variables: プロジェクト全体で使用する変数を定義します。この変数はビルド時にスクリプトファイルに埋め込まれます（関連項目）。上記サンプルでは VERSION, AUTHOR という変数を定義していますが、変数の個数・名前は自由に指定可能です。ただし変数名に使える文字は英字（A-Za-z）、数字（0-9）、アンダーバー（_）です。

build

ビルドに関する設定を指定します。

build:
  out_dir: build
  embed_search_dirs:
    - lib

out_dir: build コマンドを実行した際のスクリプトファイル出力先ディレクトリを指定します。デフォルト値は build です。
embed_search_dirs: build コマンドのモジュール埋め込み処理の際に追加で参照するディレクトリを指定します。

install

インストールに関する設定を指定します。

install:
  out_dir: C:\ProgramData\aviutl2\Script\karoterra\

out_dir: install コマンドを実行した際のスクリプトファイル出力先ディレクトリを指定します。デフォルト値は %PROGRAMDATA%\aviutl2\Script です（%PROGRAMDATA% は環境変数）。

package

パッケージに関する設定を指定します。

package:
  id: karoterra.ColorVisionSimulation
  name: 色覚シミュレーションKR
  information: 色覚シミュレーションKR for AviUtl2 v{version}
  version: 1.0.0
  out_dir: build
  file_name: "{id}-v{version}.au2pkg.zip"
  script_sub_dir: "{id}"
  message:
    file: package.txt
  assets:
    - src: docs/README.md
      dest: Script/{id}/docs/README.md

id: パッケージの識別子を指定します。 package.ini に使用されます。
name: パッケージの名称を指定します。 package.ini に使用されます。
information: パッケージの情報を指定します。 package.ini に使用されます。
version: パッケージのバージョンを指定します。
out_dir: パッケージファイルの出力先ディレクトリを指定します省略時は build.out_dir と同じ値になります。
file_name: 出力されるパッケージファイルのファイル名を指定します。省略時は "{id}-v{version}.au2pkg.zip" （ version 指定時）または "{id}.au2pkg.zip" （ version 省略時）が使用されます。
script_sub_dir: ビルドしたスクリプトファイルを配置するディレクトリを指定します。 Script 直下に配置したい場合は空文字列を指定してください。省略時は "{id}" が使用されます。
message: package.txt に指定するテキストを指定します。ファイルを参照する場合は message.file にファイルのパスを指定してください。テキストを直接指定する場合は message.text に指定してください。
assets: ビルド出力結果以外にパッケージに含めたいファイルを指定します。 src にファイルのパスを、 dest にパッケージ内の配置先を指定してください。

information, file_name, script_sub_dir, assets[].dest では {...} 形式のテンプレートを使用可能です。

使用可能な変数:

id
name
version
project.variables の各キー

scripts

ビルド・インストールの対象となるスクリプトに関する設定を指定します。

scripts:
  - name: 色覚シミュレーションKR.anm2
    sources:
      - path: script/色覚シミュレーションKR.in.anm2
        variables:
          INFO: 色覚シミュレーションKR for AviUtl2

  - name: "@MyEffect.anm2"
    sources:
      - path: scripts/EffectA.in.anm2
        label: EffectA
        variables:
          INFO: MyEffect (EffectA)
      - path: scripts/EffectB.in.anm2
        label: EffectB
        variables:
          INFO: MyEffect (EffectB)

[].name: ビルド結果として出力されるスクリプトファイル名を指定します。
[].sources: スクリプトファイルのビルドに使用するソースを配列で指定します。
[].sources[].path: スクリプトソースのパスを指定します。 aulua.yaml からの相対パスで指定してください。
[].sources[].label: スクリプトに @ ラベルを付与します。省略した場合は付与されません。
[].sources[].variables: スクリプトソースで使用する変数を定義します。この変数はビルド時にスクリプトファイルに埋め込まれます（関連項目）。上記サンプルでは INFO という変数を定義していますが、変数の個数・名前は自由に指定可能です。ただし変数名に使える文字は英字（A-Za-z）、数字（0-9）、アンダーバー（_）です。 project.variables に同じ名前の変数が存在する場合は、スクリプトソースの変数の値が使用されます。

スキーマ

aulua.yaml のスキーマは schema コマンドで出力できます。またこちらのURLからも参照可能です。

例えば Visual Studio Code の YAML 拡張機能は

# yaml-language-server: $schema=https://raw.githubusercontent.com/karoterra/aviutl2-aulua/refs/heads/main/schema/aulua.schema.json

と先頭に書いてあるYAMLの構造が正しいか検証してくれたり、キーの候補を表示してくれます。

ビルド

この章では build コマンドで行われる処理について説明します。

ファイルの連結
インクルード
変数展開
UI設定
モジュール埋め込み

ファイルの連結

ビルド時にはスクリプトソースに対してインクルードや変数展開、UI定義の処理を行った後、スクリプトとしてビルド出力先にファイルを出力します。このとき、1つのスクリプトに対して複数のスクリプトソースが指定されている場合は順番に連結されます。

label を指定した場合は@ラベルが付与されます。

例

設定ファイル

aulua.yaml

scripts:
  - name: "@MyEffect.anm2"
    sources:
      - path: scripts/EffectA.in.anm2
        label: EffectA
      - path: scripts/EffectB.in.anm2
        label: EffectB

スクリプトソース

scripts/EffectA.in.anm2

-- EffectA.in.anm2

scripts/EffectB.in.anm2

-- EffectB.in.anm2

ビルド結果

@MyEffect.anm2

@EffectA
-- EffectA.in.anm2

@EffectB
-- EffectB.in.anm2

インクルード

スクリプトソースに ---$include "other_file.hlsl" のように書いた行はそのファイルの中身に置き換わります。

ファイルはスクリプトソースファイルからの相対パスで指定してください。

例

設定ファイル

aulua.yaml

scripts:
  - name: スクリプト.anm2
    sources:
      - path: スクリプトソース.anm2

スクリプトソース

スクリプトソース.anm2

--[[pixelshader@psmain:
---$include "シェーダー.hlsl"
]]

シェーダー.hlsl

float4 psmain(float4 pos : SV_Position) : SV_Target {
    return float4(1.0);
}

ビルド結果

スクリプト.anm2

--[[pixelshader@psmain:
float4 psmain(float4 pos : SV_Position) : SV_Target {
    return float4(1.0);
}

]]

変数展開

スクリプトソースに ${VAR_NAME} のように書いたところは、 aulua.yaml の variables で指定した文字列に置き換わります。

project と sources で同じ名前の変数が指定されている場合は sources の値が優先されます。未定義の変数がスクリプトソース内に見つかった場合は警告を表示します。

変数名

変数名に使用できる文字は以下の通りです。

英字（A-Za-z）
数字（0-9）
アンダーバー（_）

例

設定ファイル

aulua.yaml

project:
  variables:
    HOGE: ほげ
    FUGA: ふが

scripts:
  - name: スクリプト.anm2
    sources:
      - path: スクリプトソース.anm2
        variables:
          FUGA: フガ

スクリプトソース

スクリプトソース.anm2

-- HOGE: ${HOGE}
-- FUGA: ${FUGA}

ビルド結果

スクリプト.anm2

-- HOGE: ほげ
-- FUGA: フガ

UI設定

ユーザーに入力させる各種設定項目については以下のような変換を行います。

トラックバー

ビルド前

---$track:X速度
---min=-10
---max=10
---step=0.01
---zero_label=ストップ
---scale=0.1
local vx = 0

ビルド後

--track@vx:X速度,-10,10,0,0.01,ストップ,0.1

以下のように1行で書くこともできます。

ビルド前

---$track:X速度, min = -10, max = 10, step = 0.01, zero_label = ストップ, scale = 0.1
local vx = 0

ビルド後

--track@vx:X速度,-10,10,0,0.01,ストップ,0.1

step, zero_label, scale は省略可能です。

チェックボックス

ビルド前

---$check:重力
local grav = 0
---$check:速度
local speed = false
---$checksection:重力
local grav = false

ビルド後

--check@grav:重力,0
--check@speed:速度,false
--checksection@grav:重力,false

色

ビルド前

---$color:図形色
local col = 0xffffff

ビルド後

--color@col:図形色,0xffffff

ファイル選択

ビルド前

---$file:画像ファイル
local path = ""

ビルド後

--file@path:画像ファイル

フォルダ選択

ビルド前

---$folder:フォルダ
local path = ""

ビルド後

--folder@path:フォルダ

フォント

ビルド前

---$font:フォント名
local font = "MS UI Gothic"

ビルド後

--font@font:フォント名,MS UI Gothic

図形

ビルド前

---$figure:先端図形
local fig = "三角形"

ビルド後

--figure@fig:先端図形,三角形

リスト選択

ビルド前

---$select:装飾タイプ
---標準文字=0
---影付き文字=1
---影付き文字(薄)=2
---縁取り文字=3
---縁取り文字(細)=4
---縁取り文字(太)=5
---縁取り文字(角)=6
local deco = 0

ビルド後

--select@deco:装飾タイプ,標準文字=0,影付き文字=1,影付き文字(薄)=2,縁取り文字=3,縁取り文字(細)=4,縁取り文字(太)=5,縁取り文字(角)=6

テキスト

ビルド前

---$text:テキスト
local txt = "デフォルト文字\n次の行"
---$string:文字列
local str = "デフォルト文字"

ビルド後

--text@txt:テキスト,デフォルト文字\n次の行
--string@str:文字列,デフォルト文字

変数

ビルド前

---$value:数値
local num = 0
---$value:文字列
local text = "0"
---$value:配列
local table = {0,0,0}

ビルド後

--value@num:数値,0
--value@text:文字列,"0"
--value@table:配列,{0,0,0}

モジュール埋め込み

スクリプトソースに ---$embed と書いた次の行の require() は、Lua モジュールがスクリプトファイルに埋め込まれます。

埋め込む Lua モジュールはスクリプトソースと同じ場所から探します。ほかの場所にある Lua モジュールを参照できるようにするには build.embed_search_dirs を設定してください。

例

スクリプトソース

スクリプトソース.anm2

---$embed
local mylib = require("mylib")

mylib.lua

local M = {}
function M.add(x, y)
    return x + y
end
return M

ビルド結果

スクリプト.anm2

-- aulua embed: mylib
local function __aulua_embed_1__()
local M = {}
function M.add(x, y)
    return x + y
end
return M

end
local mylib = __aulua_embed_1__()

Keyboard shortcuts

aulua Documentation