PARAMETER REFERENCE

Scripting Settings

Lua 5.4スクリプトによるプロシージャルなアニメーション制御を設定します。

通常の2D / 3D / Liteプリセットでは、Inspectorの Page で Scripting を選択すると表示されるページです。専用のMug Typography Scriptingプリセットでは、同じ設定が**Global Settings ページ内**に表示されます。機能の概要と作例は「Luaスクリプトで動かす（Scripting）」を参照してください。

NOTE

Mug Typography Scriptingプリセット Character SettingsとPart Settingsを省略し、最大512文字・1024パーツをLuaから制御する用途に特化したプリセットです。Global設定と3DのCamera設定は利用できますが、Character / Part選択モード、Copy / Paste、文字・パーツを対象とするRandomizeは表示されません。

Inspectorでの表示

通常プリセットではPageをScriptingへ切り替えて設定します。専用のMug Typography Scriptingプリセットでは、同じScriptingグループが**Global Settings ページ内に常時表示**されます。

パラメーター

パラメーター	説明	デフォルト
Script Status	通常時はプラグイン本体が対応するAPIレベルを表示します（読み取り専用）。スクリプトの`@api_level`が対応レベルを超える場合は必要なAPIレベルと本体の対応レベルを表示して実行を停止し、`@input` 行に構文エラーがある場合は `Input line <N>: ...` の形式でエラー内容を表示します。	`API Level 15`
Script Enabled	レンダリング時にScript TextのLuaスクリプトを実行します。通常は時間依存として評価します。`@time_independent`を宣言すると、条件が変わらないフレームで描画結果を再利用できます（詳細）。アニメーション非対応。	OFF
Script Text	実行するLua 5.4スクリプト本文（複数行）。`OnPreLayout(ctx)` / `OnLayout(ctx)` / `OnPath(ctx)` を定義します。アニメーション非対応。	`OnLayout` の雛形
Copy Script	Script Textの内容をOSのクリップボードへコピーします。MT Simや外部エディタへ戻すときに使用します。	-
Paste Script	OSのクリップボードにあるテキストでScript Textを置き換えます。ホストのUndoで元に戻せます。	-

TIP

スクリプトの開発はVSCode拡張で Script Text 欄は完成したスクリプトを貼り付けるための欄で、コード補完などの編集機能はありません。スクリプトの作成やデバッグには配布ZIP同梱のVSCode拡張「Mug Typography Scripting Simulator」（MT Sim）またはオンラインシミュレーターを使い、Copy Script とプラグイン側の Paste Script で貼り付けるのが便利です。

スクリプトから制御できるもの

コールバック	書き込み先
`OnPreLayout`	`ctx.global`（テキスト・フォントサイズ・字送り・行間・整列・縦書き・位置・回転・スケール・塗り・グラデーション・ストローク・影など）、`ctx.camera`（3D / Scriptingプリセット）、`ctx.shapes:declare`、`ctx.shape_cameras:declare`、`ctx.glyphs:declare`
`OnLayout`	`ctx.chars[index]` / `ctx.parts[index]` / `ctx.shapes[index]`（位置・回転・スケール・ピボット・個別色・個別ストローク・個別影・3D姿勢、図形のパス編集）、`ctx.shape_cameras[index]`、`ctx.bounding_box`、`ctx.output`（Write On）
`OnPath`	`ctx.paths`から選択したパーツや図形の輪郭パス

読み取り専用の情報として ctx.time（秒）、ctx.frame、ctx.timeline（クリップ長・進捗）、ctx.font、ctx.meta（APIレベル・プリセット能力・上限値）、文字・パーツの geometry（実測ジオメトリ）が利用できます。完全な仕様は「Luaスクリプティング APIリファレンス」を参照してください。

Inspectorから値を渡す（Script Inputs）

スクリプト側で @input を宣言すると、Script Inputsグループに入力欄が現れ、スクリプトを書き換えずにInspectorから値を調整できます。読み取りは ctx.inputs から行います。

lua

-- @input number 1 "Amplitude" default=15.0
-- @input boolean 1 "Enable Glow" default=true

種類	数	Inspector表示	初期値
数値	14個	`Number 1` 〜 `Number 14`（スライダー範囲 `0.0〜3.0`、直接入力 `±1000000.0`）	`0.0`
カラー	8個	`Color 1` 〜 `Color 8`	白`#ffffff`
テキスト	4個	`Text 1` 〜 `Text 4`	空
真偽値（チェックボックス）	8個	`Boolean 1` 〜 `Boolean 8`	OFF

数値・カラー・テキスト・真偽値のすべてのスロットにキーフレームを設定できます。宣言した欄だけが表示され、@input が1つも無いスクリプトではグループ自体が隠れます。

グループ内の Reset Inputs を押すと、現在のスクリプトが宣言しているすべての入力が宣言された初期値へ戻ります。

スクリプトを差し替えたときは、新しく増えた欄と初期値が変わった欄にだけ初期値が入り、設定済みの値とキーフレームは保持されます。宣言の書式と制限は「Luaスクリプティング APIリファレンス」を参照してください。

時間非依存の宣言と描画結果の再利用

Inspectorの値が同じなら、時刻が変わっても同じ結果になるスクリプトには、ヘッダーに -- @time_independent を追加できます。値は指定しません。たとえば、入力した角度で文字を段階的に回転させる静的な配置に使えます。

lua

-- @MugTypography
-- @time_independent
-- @input number 1 "Angle Step" default=5.0

function OnLayout(ctx)
    for index, character in mt.each_char(ctx) do
        character.rotation = (index - 1) * ctx.inputs.numbers[1]
    end
end

宣言はファイル1行目から始まる連続した -- コメント内に置き、空行・字下げされた行・本文・--[[ ブロックコメントより前に記述してください。省略時は時間依存として扱います。

宣言があり、他の時間依存エフェクトが動作していなければ、Inspector値・スクリプト本文・描画サイズなどが変わらずキャッシュが有効な間は、前回の文字描画結果を再利用します。再利用するフレームではLuaの実行と文字の再描画を省略します。入力映像への合成はそのフレームの映像を使います。このスクリプトはホストへの時間依存通知からも除外されます。

@input を含むInspector値がキーフレームで変われば再描画するため、Inspector側のアニメーションとは併用できます。スクリプトの変更、キャッシュの消失、Pulseなど別の時間依存エフェクトがある場合も再描画の対象です。

WARNING

時間で動くスクリプトには宣言しないでください これは作者が結果の時間非依存性を保証する宣言で、自動判定ではありません。ctx.time・ctx.frame・ctx.timeline、呼び出し回数や外部状態などで結果が変わるスクリプトには設定しないでください。誤って設定すると、前の描画結果が使われてアニメーションが止まる場合があります。判断できない場合は省略してください。

MT Simは宣言を読み取りますが、プレビューではフレーム評価を継続します。再利用時の挙動はプラグイン本体でも確認してください。

Edit Pageでの使用上の注意

Generatorプリセットでは、クリップの分割や0フレームより前への拡張に制限があります。

これらの操作を行うと、DaVinci Resolveから正しい時間情報が渡されず、ctx.timeを使うアニメーションが崩れる場合があります。

操作を避けるか、Adjustment Clip（調整クリップ）へFilters側のMug Typographyプリセットを適用してください。

エラー時の挙動と実行制限

ホストでスクリプトのロードまたはコールバックが失敗すると、そのフレームは描画されません。失敗までに行われた変更のロールバックは保証されませんが、未完了の結果が描画に使われることはありません。次のフレームはホスト由来の値から再評価されます。

失敗箇所	結果
スクリプトロード	そのスクリプトを実行せず、フレームを描画しない
`OnPreLayout`	後続コールバックを実行せず、描画しない
`OnLayout`	`OnPath`を実行せず、描画しない
`OnPath`	描画しない

暴走防止のため、1コールバック呼び出しあたり 5,000,000命令、メモリ 128MiB の上限があります。メモリは必要な分だけ確保されます。上限を超えたコールバックはエラーとして扱われ、そのフレームは描画されません。

WARNING

制限事項

スクリプトが書き込んだ値はそのフレームの描画にのみ使われ、Inspectorやキーフレームへは書き戻されません
モーフアニメーションの実行中（To Textによる変形中）はスクリプトのコールバックはスキップされます
外部 .lua ファイルの読み込みには対応していません

Inspectorでの表示 ​

パラメーター ​

スクリプトから制御できるもの ​

Inspectorから値を渡す（Script Inputs） ​

時間非依存の宣言と描画結果の再利用 ​

Edit Pageでの使用上の注意 ​

エラー時の挙動と実行制限 ​