Mug Typography

日本語

English

日本語

English

Appearance

LUA SCRIPTING NEW

スクリプトで文字を動かす

波打ち、ランダム散らし、物理風の動きなど、キーフレームでは作りにくいアニメーションを短いスクリプトで実現。付属のVSCode用シミュレーターを使えば、DaVinci Resolveを起動せずに開発・プレビューできます。

  • 毎フレームをコードで制御
  • VSCodeシミュレーター付属
  • 豊富なサンプルスクリプト
使い方を見る設定リファレンス
Luaスクリプトで制御された文字アニメーション

使い方 ​

通常の2D / 3D / Liteプリセットでは、次の手順で有効にします。

  1. Page を Scripting にします。
  2. Script Enabled を ON にします。
  3. Script Text にLuaスクリプトを入力するか、Paste Script でクリップボードから貼り付けます。

Mug Typography Scriptingプリセットでは、Scriptingグループが Global Settings ページ内に表示されるため、Pageの切り替えは不要です。このプリセットはCharacter SettingsとPart Settingsを省略して最大512文字・1024パーツを扱え、個々の文字・パーツはLuaから制御します。Inspectorでの個別編集とLuaを併用したい場合は、通常のプリセットを使用してください。

たとえば次のスクリプトだけで、全文字がそれぞれ位相をずらしながら揺れ続けます（offset_x / offset_y は 0.5 が元の位置を表すため、元の値に加算します）。

lua
function OnLayout(ctx)
    for index, character in mt.each_char(ctx) do
        character.rotation = character.rotation + math.sin(ctx.time * 2.0 + index * 0.4) * 15.0
        character.offset_y = character.offset_y + math.sin(ctx.time * 3.0 + index * 0.7) * 0.02
    end
end

スクリプトはInspectorの値を毎フレーム上書きする形で動作します。キーフレームや他の機能（デフォーム、Write On、3Dなど）とそのまま併用できます。

時間に依存しない静的な配置や装飾では、-- @time_independent を宣言すると、値が変わらないフレームでLuaの実行と文字の再描画を省略できます。上の例は ctx.time で動くため、宣言を追加しないでください。条件と静的な使用例は「時間非依存の宣言と描画結果の再利用」を参照してください。

3つのコールバック ​

スクリプトには最大3つの関数を定義できます。必要な関数だけを書けば動作します。

コールバック実行タイミング主な用途
OnPreLayout(ctx)文字を並べる前（毎フレーム）テキスト内容・字送り・整列・全体色・カメラの変更、図形やカスタムグリフの宣言
OnLayout(ctx)文字を並べた後（毎フレーム）1文字ごと・パーツごと・図形ごとの位置、回転、スケール、色などの変更
OnPath(ctx)OnLayout の後（毎フレーム）ctx.paths で選んだパーツや図形の輪郭をカスタムパスに差し替え

まず OnPreLayout でテキスト全体の条件を決め、その条件で並んだ文字やパーツを OnLayout で個別に動かす、という2段階の流れになっています。そのため、文字数や改行が変わる処理（タイプライター演出など）は OnPreLayout に書き、各文字やパーツを動かす処理は OnLayout に書きます。

mt.* には、文字・パーツを順番に処理する mt.each_char / mt.each_part、数値計算（mt.clamp / mt.lerp / mt.remap）、イージング（mt.ease.*）、色変換（mt.color.*）、タイムライン制御（mt.timeline.*）、SVGパス構築（mt.svg_path）などの補助関数が揃っています。

図形（シェイプ）とカスタムグリフを描く ​

スクリプトからは、文字を動かすだけでなく、任意のベクター図形やSVGパスを描画できます。用途に合わせて3つの方法が用意されています。

方法特徴と主な用途
図形（ctx.shapes）本文のレイアウトとは独立して配置できる図形です。文字数・パーツ数の上限を消費せず、本文の背面（layer = "back"）や前面（layer = "front"）に座布団、飾り枠、背景アニメーション、パーティクルなどを重ねられます。図形どうしの親子関係（parent）や、本文カメラとは独立した3Dカメラ（ctx.shape_cameras）にも対応しています。
カスタムグリフ（ctx.glyphs）独自のパスに文字幅（advance_x / advance_y）を持たせ、1文字としてテキスト内に埋め込む機能です。文中にアイコンを混ぜたり、表の罫線や接続線を描いたりする用途に向いています。
輪郭の差し替え（ctx.paths）OnPath で既存の文字パーツの輪郭（path）を直接書き換える機能です。特定の文字やパーツを別の形に変形させたいときに使います。

パスデータは、SVGのパス文字列を読み込む mt.svg_path や、直線・ベジェ曲線をコードで組み立てる mt.drawing_path で作成できます。詳しい仕様は APIリファレンス を参照してください。

VSCodeシミュレーター（MT Sim） ​

配布ZIPの scripting-simulator/ フォルダには、VSCode拡張「Mug Typography Scripting Simulator」（MT Sim）が同梱されています。DaVinci Resolve を起動しなくても、VSCode 上だけでスクリプトの作成とプレビューができます。

  • インストール: VSCodeの拡張機能ビューで「Install from VSIX...」を選び、同梱の .vsix ファイルを指定します。
  • 起動: .lua ファイルを開き、エディタ右上のプレビューアイコンかコマンドパレットの「Mug Typography Scripting Simulator」を実行します。ファイルを保存するとその場でプレビューが更新されます。
  • プラグインへコピー: パネル上部の Copy Script でスクリプトをコピーし、プラグインの Paste Script で Script Text へ貼り付けます。
  • 編集支援: ctx.* や mt.* の入力補完とホバー説明が表示され、各コールバックで書き込み可能なフィールドだけが候補に出ます。
  • シーン再現: タイムライン再生、フォント変更、文字・パーツ単位のInspector、計算後の値一覧、3Dカメラのプレビューに対応しています。

NOTE

APIレベルとプラグインの対応 すべての機能を使うには、最新のプラグインを使用してください。新しいAPIを使ったサンプルやスクリプトは、古いプラグインでは動作しません。現在のプラグインのAPI Levelは15です。

VSCode拡張は、同じ配布ZIPに入っているプラグインと組み合わせて使ってください。

オンラインシミュレーターは最新のAPIに対応しているため、プラグインの更新を促す案内を表示します。更新したことを確認するまで、案内は表示され続けます。

WARNING

シミュレーターは近似プレビューです MT Simのレイアウトと描画はプラグイン本体の近似です。グラデーションの補間や投影後のストローク品質などは簡略化されているため、最終的な仕上がりは必ずMug Typography本体で確認してください。

ブラウザで試す ​

インストール不要で、ブラウザからそのまま試せるオンラインシミュレーター ↗も公開しています。VSCode拡張版と同じ編集支援・サンプル集を備え、ちょっとした動作確認やAPIの学習に手軽に使えます。

作品をギャラリーに公開する ​

作ったアニメーションは、オンラインシミュレーターのギャラリーに公開できます。公開された作品はサンプルブラウザの コミュニティに並び、誰でもカードから開いてスクリプトを読んだり、自分の制作の出発点にしたりできます。

投稿はギャラリーリポジトリ ↗から受け付けています（シミュレーターのメニューの Submit to Gallery からも開けます）。必要なファイルと手順はリポジトリのREADMEを参照してください。

AIにスクリプトを書いてもらう ​

Luaを書いたことがなくても、AIに作りたい動きを伝えればスクリプトを生成できます。利用環境に合わせて2つの方法があります。

  • 方法A：Mug Typography MCP を使う（推奨） - Claude Desktop、Codex、Cursor、VS Code、Gemini CLI、Antigravity をお使いの場合は、「AIに演出づくりを任せる（Mug Typography MCP）」を入れると、AIが自分で仕様を調べ、スクリプトの動作確認まで自動で行います（仕様書の添付は不要です）。
  • 方法B：チャットAIに仕様書ファイルを渡す - ブラウザ版のChatGPTやClaudeなど、MCPに対応していないチャットAIを使う場合は、以下の手順でAI向けの仕様書ファイル（lua_api_for_ai.md）を先に読み込ませます。これを省くと、存在しない関数を使ったり、単位や向きを取り違えたスクリプトが返ってきます。

チャットAIに仕様書を渡す手順 ​

  1. 仕様書を読み込ませる。 新しいチャットを開き、配布ZIPに同梱されている 次のファイルを添付して、「このAPI仕様書を読んでください」と伝えます。

    text
    scripting-simulator/docs/lua_api_for_ai.md

    ファイルを添付できないAIの場合は、テキストエディタで開いて全文を貼り付けてください。 Web上のファイルを読み取れるAIであれば、次のURLを渡す方法もあります （読み取りに対応していないAIも多いため、まずは添付をおすすめします）。

    text
    https://mug-typography.muglab3.com/lua_api_for_ai.md

  2. 読み込めたか確認する。 仕様書は大きなファイルのため、AIによっては 添付が読まれないことがあります。続けて次のように聞いてください。

    mt.stagger の引数を、単位も含めて教えてください。

    time（秒）、index（1始まり）、delay（秒）、duration（秒）と 答えられれば、正しく読み込めています。答えられない場合は後述の対処を行ってください。

  3. 作りたいアニメーションを指示する。 日本語で構いません。具体的に伝えるほど 意図に近いものが返ってきます。

    文字が1つずつ下から跳ね上がって登場し、最後に全体がゆっくり揺れるアニメーションを作ってください。

    3D操作を一切使わない作品なら、「2D専用として作って」「2D限定にして」と明記できます。対応したAIは、3D対応のScriptingプリセットでも2D描画経路を使う指定（-- @2d）をスクリプトへ追加します。3D投影処理を省けるため描画速度の向上が期待できますが、CameraやGlobalなどの3D Inspector設定とキーフレームはすべて無効になります。あとから3D操作を加える可能性がある場合は、2D専用にしないでください。

  4. 返ってきたコードをコピーし、Script Text に貼り付けるか、 Paste Script で読み込みます。

  5. 思った動きと違う場合は、そのまま伝えて修正してもらいます。 「跳ね上がりをもっと強く」「揺れは不要」のように、続けて指示できます。オンラインシミュレーターのメニューから AIプレビュー画像… を開くと、指定した再生範囲（またはクリップ全体）の複数フレームを並べた1枚のPNG画像をコピー・保存してAIチャットに添付でき、実際の見た目をAIに見せながら調整してもらえます。

うまくいかないときは ​

手順2の確認に答えられない、存在しない関数が使われる、単位や向きが明らかにおかしい これらはすべて仕様書が読まれていないサインです。次の順に試してください。

  1. 新しいチャットを開いて添付し直す。 会話が長くなると、最初に添付した内容が 参照されにくくなります。仕様書を読ませた直後に指示するのが最も確実です。
  2. 添付ではなく全文を貼り付ける。 テキストエディタで仕様書を開き、 全選択してチャット欄に貼り付けます。添付より確実に読み込まれます。
  3. 別のAIを試す。 手元のPCで動かす小型のAIでは、仕様書が大きすぎて 読み込めないことがあります。

TIP

動作確認はシミュレーターが便利です MT Simやオンラインシミュレーターに貼り付けると、エラーメッセージと行番号を一覧で確認してそのままコピーできるため、それをAIに伝えるとスムーズに修正してもらえます。

サンプルとAPIリファレンス ​

配布ZIPの scripting-simulator/samples/ に、そのまま使えるLuaサンプルが多数入っています。

  • reference/ - 基本モデルと各APIの使い方をジャンル別に学べる短い学習用サンプル
  • showcase/ - タイプライター、バウンス登場、ネオン、背景・図形演出、3Dカメラワークなど完成品のアニメーション集
  • diagnostics/ - 環境・APIの内部動作確認用スクリプト

reference/ もジャンルごとに分かれており、基礎・実行の流れ（RBS）、時間・アニメーション（RTM）、テキスト・レイアウト（RLY）、色・質感・描画（RAP）、パス・カスタムグリフ・図形（RPT）、乱数・ノイズ（RRN）、3D・カメラ（RCM）を目的別に確認できます。

シミュレーターのサンプルブラウザでは、ジャンル別の一覧やキーワード検索（サンプルID・ジャンル名・API名）からサンプルを探せます。

  • プレビューを再生: 編集中のスクリプトを上書きせずに、その場でサンプルのアニメーションを再生して動きを確かめられます。
  • エディタで開く: 選んだサンプルをエディタに読み込み、そのまま改造したり中身を読んだりできます。
  • Scripting Check: メニューから実行すると、編集中スクリプトを変えずに Scripting 機能の動作診断を行えます。

APIの詳しい仕様は「Luaスクリプティング APIリファレンス」を参照してください（オフライン用の同じドキュメントが配布ZIPの scripting-simulator/docs/ にも入っています）。

パラメーターの詳細と制限事項は「スクリプティング設定 (Scripting Settings)」を参照してください。