対象APIレベル: 15
ctxは、Mug Typographyが各コールバックへ渡すコンテキストです。現在時刻、Canvas情報、 全体設定、生成された文字・パーツなど、そのフレームの処理に必要な情報が含まれます。
利用できるフィールドと書き込み権限はコールバックによって異なります。本書では、最初に コールバックごとの利用可否を一覧にしたあと、ctxのフィールドを順に説明します。 コールバックの実行順序と用途は コールバックの概要を参照してください。
1. ctxのフィールド一覧
ctx直下のフィールド自体は読み取り専用で、別の値へ置き換えることはできません。 ただし、ctx.globalやctx.chars[index]などの内部には、コールバックに応じて変更できる フィールドがあります。○はそのコールバックで参照できることを表します。
| フィールド | 型 | OnPreLayout | OnLayout | OnPath | 内容 |
|---|---|---|---|---|---|
ctx.time | number | ○ | ○ | ○ | クリップ先頭を0とする現在時刻（秒、§1.1） |
ctx.frame | number | ○ | ○ | ○ | クリップ先頭を0とするフレーム番号。サブフレームを含む場合があります（§1.1） |
ctx.fps | number | ○ | ○ | ○ | フレームレート（§1.1） |
ctx.canvas | table | ○ | ○ | ○ | Canvasとプロジェクトの画素情報（§1.2） |
ctx.fonts | string[] | ○ | ○ | ○ | global.font_nameへ設定できるフォント名の1始まり配列（§1.3） |
ctx.timeline | table | ○ | ○ | ○ | クリップの時間範囲と現在進行度（§1.4） |
ctx.font | table | - | ○ | ○ | 使用中フォントのメトリクス（寸法情報、§1.5） |
ctx.text | string | ○ | ○ | - | 廃止予定のテキスト参照（§1.6） |
ctx.char_count | integer | - | ○ | ○ | 有効な本文の文字数。図形は数えません（§1.6） |
ctx.part_count | integer | - | ○ | ○ | 有効な本文のパーツ数。図形は数えません（§1.6） |
ctx.shape_count | integer | - | ○ | ○ | 宣言された図形の数（§1.17） |
ctx.meta | table | ○ | ○ | ○ | APIバージョンと機能情報（§1.7） |
ctx.inputs | table | ○ | ○ | ○ | Inspectorで設定したスクリプト入力（§1.16） |
ctx.global | table | ○ | ○ | ○ | 全体設定。OnPreLayoutで変更でき、以降は読み取り専用です（§1.8） |
ctx.camera | table | ○ | ○ | ○ | カメラ設定。OnPreLayoutで変更でき、以降は読み取り専用です（§1.9） |
ctx.chars | table[] | - | ○ | ○ | 生成された本文の文字の1始まり配列（§1.10） |
ctx.parts | table[] | - | ○ | ○ | 生成された本文のパーツの1始まり配列（§1.11） |
ctx.bounding_box | table | - | ○ | ○ | バウンディングボックスの描画設定（§1.12） |
ctx.output | table | - | ○ | ○ | 出力フィルタと描画順の設定（§1.13） |
ctx.paths | table | - | - | ○ | パーツのパスを取得・編集するためのコンテキスト（§1.14） |
ctx.glyphs | table | ○ | - | - | カスタムグリフを宣言するためのコンテキスト（§1.15） |
ctx.shapes | table | ○ | ○ | ○ | 図形を宣言し、番号で参照するためのコンテキスト（§1.17） |
ctx.shape_cameras | table | ○ | ○ | - | 図形を映すカメラを宣言し、番号で動かすためのコンテキスト（§1.17） |
1.1 ctx.time / ctx.frame / ctx.fps
現在の評価位置をクリップ先頭基準で表します。ctx.timeは秒、ctx.frameはフレーム単位です。 ctx.frameにはサブフレームが含まれる場合があるため、整数とは限りません。ctx.fpsは 1秒あたりのフレーム数です。
1.2 ctx.canvas
Canvasとプロジェクトの画素情報です。すべて読み取り専用です。
| フィールド | 型 | 単位 | 内容 |
|---|---|---|---|
width / height | number | px | Canvasの幅と高さ |
aspect_ratio | number | - | Canvasの幅を高さで割った値（width / height） |
pixel_aspect_ratio | number | - | ホストプロジェクトのピクセルアスペクト比 |
1.3 ctx.fonts
ホストが認識しているインストール済みフォントの名前を格納した、読み取り専用の1始まり配列です。 内容はホストUIのFontリストと同じで、OnPreLayoutでは要素をctx.global.font_nameへ 設定できます。
配列の要素や要素数は変更できません。
1.4 ctx.timeline
| フィールド | 型 | 単位 | 内容 |
|---|---|---|---|
available | boolean | - | 有限なクリップ範囲を取得できたか |
start_frame / end_frame | number | frame | 範囲の始端／終端（クリップローカル。始端は常に0） |
duration_frames | number | frame | end_frame - start_frame |
duration_seconds | number | second | 秒に換算した長さ |
progress | number | 0-1 | 0-1にクランプされた現在位置 |
クリップ範囲
クリップ範囲は、トリムや前後の引き伸ばしを含むタイムライン上の実範囲です。 ctx.time / ctx.frame / ctx.timelineには、クリップ先頭を0とした同じ時間軸の値が 渡されます。フィルタとして映像クリップに適用した場合も、そのクリップの範囲に追従します。
availableがfalseのときは他の値が0になるため、フォールバックを用意してください。
NOTE
ジェネレータ運用での前方引き伸ばしの制限: ジェネレータクリップ（入力未接続）の前方を タイムライン上で引き伸ばした場合、その区間はホストが先頭フレームの静止画として扱うため、 スクリプト時間は引き伸ばし境界まで進みません（イントロが先頭姿で静止して見えます）。 尺を変えたい場合は引き伸ばしではなくジェネレータクリップ自体の長さを変更してください。 フィルタ運用にはこの制限はありません。
時間軸の設計ルール（アンカー × 速度）
アニメーションの時間設計は「①どこに固定するか（アンカー）」と「②どの速さで進めるか（速度）」の 2軸で決めます。**速度の既定は実秒（ctx.time ベース）**で、クリップ長に比例させる progress を 使ってよいのは後述の「全体スパン型」だけです。
| パターン | アンカー | 書き方 |
|---|---|---|
| イントロ（登場） | クリップ先頭 | ctx.time をそのまま使う（実秒）。イントロ＋アウトロ一括なら mt.timeline.intro_outro_seconds(§10.9) |
| アウトロ（退場） | クリップ終端 | mt.timeline.remaining(ctx)（終端までの残り実秒。§10.9） |
| タイプライター・stagger・ばね等 | クリップ先頭 | ctx.time（実秒。1文字あたり○秒など物理速度で指定） |
| 全体スパン型（尺いっぱいのドリフト・スイープ・リビール） | クリップ全体 | progress（尺が伸びたら動きも伸びるのが期待動作） |
トランジションを progress の割合で書くと、尺を伸ばしたときにフェードやタイピングが スローモーション化して破綻します。アウトロも本質は「終端に揃えること」であって速度を尺に 比例させることではないため、終端アンカーの実秒で書きます。
-- NG: typing speed changes when the clip length changes
local visible = math.floor(mt.timeline.progress(ctx) * ctx.char_count)
-- OK: constant 0.08s per character regardless of clip length
local visible = math.floor(ctx.time / 0.08)
-- OK: outro fade over the last 0.5s, anchored to the clip end
local fade = mt.clamp(mt.timeline.remaining(ctx) / 0.5, 0.0, 1.0)
-- OK: 0.8s intro + 0.5s outro at fixed real-time speed
-- (compressed automatically only when the clip is shorter)
local intro, outro = mt.timeline.intro_outro_seconds(ctx, 0.8, 0.5)1.5 ctx.font - 使用中フォントの寸法情報
レイアウト生成後に確定した、使用中フォントのメトリクス（寸法情報）です。
| フィールド | 型 | 単位 | 内容 |
|---|---|---|---|
em_size | number | canvas 高さ比 | 変形前の1emの大きさ |
ascent | number | canvas 高さ比 | ベースラインから上方向のアセント |
descent | number | canvas 高さ比 | ベースラインから下方向のディセント（正値。下向きの量として表す） |
line_height | number | canvas 高さ比 | 行の高さ |
units_per_em | number | フォント設計単位 | フォントの em 正方形の設計単位数 |
NOTE
画面上の最終サイズは scale 系フィールドの積で予測できます(2Dプリセット限定)。 フォントサイズはホストが内部で canvas.height に対する固定比率として計算しているため、 canvas解像度が変わっても同じ比率を保ちます。この基準サイズに character.scale × character.stretch_x/y・part.scale・ctx.global.scale × ctx.global.stretch_x/y を 掛け合わせたものが、2Dプリセットでは実際の画面上サイズと一致します(すべて乗算で 合成される変形だからです)。
3Dプリセットではこの積は近似にしかなりません。 カメラ投影が奥行き（z、 yaw/pitchによる見かけの奥行き変化、カメラの perspective / zoom を含む)に応じた 遠近除算を行うため、画面上サイズは奥行きに対して非線形に変化し、傾いた文字は 頂点ごとに歪みが生じて単一の倍率では表せません。ctx.fontとcharacter.geometry は投影前の値であり、投影後の画面上サイズはOnLayoutから取得できません。
1.6 ctx.text / ctx.char_count / ctx.part_count
ctx.textは廃止予定です。現在のテキストを参照するときはctx.global.textを使い、 書き換えるときはOnPreLayoutでctx.global.textへ代入してください。
ctx.char_countとctx.part_countは、それぞれレイアウト生成後の有効な本文の文字数とパーツ数を 表します。図形（§1.17）は数えず、ctx.shape_countで数えます。テキストやフォントを変更すると、シェイプ結果に応じて値も変わります。
1.7 ctx.meta
| フィールド | 型 | 単位 | 内容 |
|---|---|---|---|
ctx.meta.api_level | integer | - | Lua API互換レベル |
ctx.meta.plugin_version | string | - | 実行中のプラグインバージョン（表示用） |
ctx.meta.capabilities | table | - | 現在利用できる機能の情報。読み取り専用 |
ctx.meta.capabilities.has_3d | boolean | - | 3D Projectionが現在のプリセットで有効か |
ctx.meta.limits | table | - | このインスタンスに適用される上限値。読み取り専用 |
ctx.meta.limits.max_characters | integer | - | このインスタンスで扱える最大文字数 |
ctx.meta.limits.max_parts | integer | - | このインスタンスで扱える最大パーツ数 |
ctx.meta.limits.max_shapes | integer | - | このインスタンスで扱える最大図形数。図形は文字・パーツの上限を使わないため、全プリセット共通です |
ctx.meta.instance_seed | integer | - | このインスタンス固有の安定した乱数シード（0以上2^31-1以下）。同一インスタンスでは生存期間中ずっと同じ値、別インスタンスでは別の値になります |
機能の判定
機能の有無はctx.meta.api_level >= 必要レベルとcapabilitiesで判定します。 has_3dがfalseでもCameraおよびyaw / pitch / zへの代入はエラーになりませんが、 描画には反映されません。
instance_seedの用途
instance_seedをmt.randomのseedに使うと、同じスクリプトでもインスタンスごとに 異なる乱数列になります。
1.8 ctx.global
| フィールド | 型 | 単位 | 内容 |
|---|---|---|---|
text | string | - | UTF-8テキスト。変更すると再シェイプし、文字・パーツ数を再生成します |
font_name | string | - | フォントファミリー名（ctx.fontsのいずれか）。変更すると使用フォントを変更して再シェイプします |
tracking | number | em | 各文字の後方送りに加算する文字送り。1.0は1 emです |
line_spacing | number | 倍率 | 行／縦書き列の送り |
vertical | boolean | - | trueで縦書きにし、シェイプと配置方向を変更します |
single_part_glyph | boolean | - | trueでフォントグリフを1パーツ化し、半透明の輪郭交差部分が濃くなることと内部の縁取りを防ぎます。カスタムグリフ・カラー絵文字は対象外です。OnPreLayoutで変更するとレイアウトを再生成します。毎フレームInspectorの値から初期化されます（APIレベル15）。 |
h_align | string | - | 水平アラインメント。left / center / right |
v_align | string | - | 垂直アラインメント。top / center / bottom / baseline |
margins | number[] | em | 各文字の後方送り。trackingと同じ単位です |
emoji | table | - | 絵文字の配置とフォントの設定（下表） |
position_x / position_y | number | canvas正規化座標 | 全体位置。0.5が中央で、Xは右、Yは上が正です |
rotation | number | degree | 2D全体回転。正（+）で右回り（時計回り）、負（-）で左回り（反時計回り）です |
yaw / pitch | number | degree | 3D全体姿勢。3Dプリセットのみ描画に反映されます。yawは正（+）で右端が手前へ、pitchは正（+）で上端が手前へ回転します |
scale | number | 倍率 | 全体均等スケール。書き込み時に最小0.0001へクランプされます |
stretch_x / stretch_y | number | 倍率 | 全体非均等スケール。scaleと異なり正の下限はなく、0や負値も受理されます |
pivot_x / pivot_y | number | canvas正規化変位 | 全体変形のピボット。0.5で変位量0になり、大きいほどglobal.positionから右／上へ移動します |
opacity | number | 0-1 | 全体の不透明度。既定値は1.0です。範囲外の値はホストが描画直前に0-1へクランプします。塗り・グラデーション・ストローク・シャドウ・バウンディングボックスすべてに、色が決まった後のアルファとして乗算されます（fill.useの判定には関与しません。use / opacity / fill.transparent の役割を参照してください）。ホスト側にキーフレームパラメータは存在せず、スクリプトからのみ書き込めます |
fill | table | - | 全体塗り設定（下表） |
gradient | table | - | グラデーション設定（下表） |
stroke | table | - | 全体ストローク設定（下表） |
shadow | table | - | 全体シャドウ設定（下表） |
texture | table | - | 全体テクスチャ設定（下表） |
blur | table | - | 全体の文字そのもののぼかし設定（下表） |
Inspectorの本文に入力した \n・<br>・<br/>・<br /> は、OnPreLayout より前に実際の改行文字（LF）へ変換されます。CRLFもLFになります。\\n と \<br> は文字としての \n と <br> になります。ctx.textも同じ解釈済みテキストを参照します。
OnPreLayoutで代入したテキストは改行表記を再解釈しません。Luaでは "A\nB" または複数行文字列で実際の改行を作り、文字としての \n は "A\\nB" と書いてください。カスタムグリフの宣言・挿入後に文字配列を生成し、改行自体は ctx.chars に含めません。
ctx.global.margins
インデックスと計算
marginsは、レイアウト順の文字番号をキーとする1始まりの配列です。この番号は、 あとでctx.charsに付くindexと同じです。margins[i]はi番目の文字の後ろの送りへ、 trackingと合わせてem単位で加算されます。
(margins[i] + tracking) * designUnitsPerEm配列形式
キーは1以上の整数、値は数値にしてください。非整数キー、文字列キー、0以下のキー、数値以外の値はエラーになります。 途中の番号を省略しても構いません。省略した番号は0（余白なし）として扱われるため、margins[2]だけの代入や { [2] = 0.5 }のようなテーブルも有効で、margins[1]は0になります。
OnPreLayoutのctx.global.marginsはctx.meta.limits.max_characters個の要素を持ちます。そのため #ctx.global.marginsは文字数ではありません。この上限を超える番号はどの文字にも届かないため、エラーにならず 無視されます。
文字数
OnPreLayoutではctx.char_countが未定義です。utf8.len(ctx.global.text)で得られるのは UTF-8コードポイント数であり、結合文字、合字、書記素クラスタなどにより、シェイプ後の 文字数と一致しない場合があります。正確な個数が必要な処理はOnLayoutで行ってください。
サブオブジェクトのマージ
ctx.global.shadow = { enabled = true, distance = 0.8 }のようにテーブル全体を代入すると、 フィールドごとにマージされます。省略したフィールドは現在値を維持します。
ctx.global.fill
NOTE
color型
colorはr（赤）、g（緑）、b（青）、a（アルファ）を持つテーブルです。 各フィールドは0-1のnumberで、a = 0は完全な透明、a = 1は完全な不透明を表します。
フィールドへ直接代入できるほか、テーブル全体を代入するときは変更するフィールドだけを 記載できます。省略したフィールドは現在値を維持します。
ctx.global.fill.color.r = 1.0
ctx.global.fill.color = { a = 0.5 }r / g / b / a以外のフィールドや、number以外の値はエラーになります。
| フィールド | 型 | 単位 | 内容 |
|---|---|---|---|
color | color | RGBA 0-1 | 全体の塗り色。グラデーションの始端色も兼ねます |
transparent | boolean | - | trueにすると、ストロークや効果を残して塗りを非表示にします |
chars[index].fill.useがfalseの文字にはfill.colorが使われます。 パーツまで含めた継承順は「継承の仕組み」を 参照してください。
ctx.global.gradient
| フィールド | 型 | 単位 | 内容 |
|---|---|---|---|
color_space | string | - | グラデーション／Crayonモード。値は下記の列挙値です |
end_color | color | RGBA 0-1 | グラデーション終端色 |
midpoint | number | 0-1 | 色補間の中点 |
angle | number | degree | グラデーション方向。0度で左から右に進み、正（+）で右回り（時計回り）に回転 |
start_position / end_position | number | 変形後の全体範囲に対する相対位置 | グラデーション区間。標準は0.0〜1.0です。詳しくはグラデーションの範囲と向きを参照してください |
gradient.color_space の値:
noneokhsvokhsloklablinear_rgboklch_short- API Level 11。OKLCHの短い色相経路。oklch_long- API Level 11。OKLCHの長い色相経路。crayon
ctx.global.texture
塗りに重ねるマテリアル（質感）です。p1〜p4 はマテリアル共通の汎用コントロールで、意味は選んだ type によって変わります。
| フィールド | 型 | 単位 | 内容 |
|---|---|---|---|
use | boolean | - | 継承したテクスチャの代わりに自身のテクスチャを使うか。ctx.global では無視され、ctx.chars[i] / ctx.parts[i] でのみ意味を持ちます |
type | string | - | マテリアルの種類。値は下記の列挙値です |
p1 | number | 素材による | 第1コントロール |
p2 | number | 素材による | 第2コントロール |
p3 | number | 素材による | 第3コントロール |
p4 | number | 素材による | 第4コントロール |
p5 | number | 素材による | 第5コントロール。halftone・halftone_diamond・colored_pencil・prism_foil・iridescent・metallic だけが読みます。halftone 系では Fade の向きを度で表し（0 で下へ向かって濃くなる）、colored_pencil では光が来る画面上の方向を度で表します（0 が右、90 が下）。prism_foil ではタイルの並ぶ向きを度で表します（0 でパーツの x 軸方向）。iridescent では膜厚のムラを 0〜1 で表します（0 で一様な膜）。metallic ではヘアラインの角度を度で表します（0 でパーツの x 軸方向）。ほかの素材は無視します。初期値は 0（API レベル 14） |
color | color | RGBA 0-1 | マテリアルが塗りの上に加えるものの色。stained_glass では鉛線、glitter では金属片、stripe では縞、halftone では点、prism_foil では箔（白で銀）、それ以外では光の色です。白の場合、光はマテリアルのまま、鉛線は白になります（iridescent は無視します） |
texture.type の値と、p1〜p4 の意味:
type | p1 | p2 | p3 | p4 |
|---|---|---|---|---|
none | - | - | - | - |
water_droplet | 厚み | 丸み | 光沢 | 光の角度 |
air_cushion | 膨らみ | 圧着幅 | 皺 | 光の角度 |
glitter | フレークサイズ | 光る粒の割合 | 粒の量 | 光の角度 |
iridescent | 膜厚 | 色相幅 | 強度 | 光の角度 |
faceted | 面の数 | 面取りの深さ | 磨き | 光の角度 |
stained_glass | ガラス片の大きさ | 鉛線の太さ | 色相幅 | Glow |
metallic | 磨き | 起伏 | 反射コントラスト | 光の角度 |
metallic_2 | 磨き | 起伏 | 露出 | 光の角度 |
stripe | 縞の密度（本数） | 縞の太さ | 縞の濃さ | 縞の向き（度） |
colored_pencil | 白い線の密度 | 白い線の長さ | 光の強さ | 線の向き（度） |
halftone・halftone_diamond | 点の密度（個数） | 点の大きさ | 減衰の強さ | 格子の向き（度） |
prism_foil | タイルの大きさ | 虹色の量 | 箔の濃さ | 光の角度（画面上の度） |
Flake Amount は全体の粒の量です。0 で粒とグローなし、1 で最大密度になります。色相幅は従来の Hue Range 1.0 相当で固定です。
光る粒には白寄りの芯と柔らかなグローが付きます。グローは文字の輪郭内に描かれ、Highlight Ratio で光る粒とともに増減します。
p1〜p4 はいずれも汎用スロットで、範囲も単位もマテリアルが決めます。多くは 0〜1 ですが、たとえば光の角度は度で読まれます。マテリアルは受け取った値を自身が扱える範囲へ丸めてから使うため（角度のように一周するものは繰り返し、上限があるものは端で止まります）、範囲外の値を書いても保存値やキーフレームは書き換えられません。
テクスチャは全体・文字・パートの3段で継承されます。ctx.chars[i].texture / ctx.parts[i].texture に use = true を設定すると、その要素だけ別のマテリアルに差し替えられます。文字やパート側はホストのパラメータを持たないスクリプト専用の値のため、スクリプトが設定しない限り常に未使用として読み取られます。
ctx.global.blur
文字そのもの（塗り・グラデーション・テクスチャ・ストローク・クレヨン）をまとめてぼかします。シャドウはこの設定ではぼけません。シャドウには専用の shadow.blur_x / blur_y があります。バウンディングボックスはぼけません。
| フィールド | 型 | 単位 | 内容 |
|---|---|---|---|
use | boolean | - | 継承した値の代わりに、この要素自身のぼかしを使うかどうか。use を持たない ctx.global では無視され、ctx.chars[i] / ctx.parts[i] でのみ意味を持ちます |
amount_x | number | em | 水平方向のぼかし（ガウスのσ）。1.0 = 1 em。0 で水平方向の縁はぼけません。書き込み時は 0〜10 に丸められます |
amount_y | number | em | 垂直方向のぼかし。単位と範囲は amount_x と同じです |
glow | number | - | グローの強さ。ぼかした文字を明るく持ち上げて発光させ、色が飽和した芯は白に近づきます。0 でグローなし。文字がぼけていないときは効果がありません。書き込み時は 0〜10 に丸められます |
ぼかしはパーツ自身の空間で、canvasの軸方向に測るため、shadow.distance と同じくパーツの拡縮・stretch・遠近に追従します。ぼかしは、全体・文字・パーツの3段で継承されます。ctx.chars[i].blur / ctx.parts[i].blur で use = true にすると、その要素だけ自身のぼかしを使います。文字とパーツの値はスクリプト専用（ホスト側パラメータの裏付けなし）のため、スクリプトが設定するまでは常に未使用で、継承する値と同じ値として読み取られます。シャドウのぼかしはシャドウ色と同じ shadow.use に従うため、1つのパーツのぼかしだけを上書きするには継承した色を書き戻します。その色は mt.shadow.resolve(ctx, target, { level = "character" }) が返します。
ctx.global.stroke
| フィールド | 型 | 単位 | 内容 |
|---|---|---|---|
width | number | em（1.0 = フォントサイズ 1 em。描画時に fontSize を掛ける） | ストロークの太さ |
gap | number | em（1.0 = フォントサイズ 1 em） | 塗りとストロークの間隔 |
color | color | RGBA 0-1 | ストローク色 |
outer_width | number | em（1.0 = フォントサイズ 1 em） | Inner Strokeの外側に隣接するOuter Strokeの太さ。width > 0のときだけ有効 |
outer_color | color | RGBA 0-1 | Outer Strokeの色 |
order | string | - | 塗りとストロークの重なり順。fill_over_stroke / stroke_over_fill / fill_over_stroke_per_character |
join | string | - | ストローク角の接続方式。miter_clip / round / bevel / miter_round / miter_bevel |
miter_limit | number | 倍率 | 鋭いmiter角の最大長 |
fill_over_stroke_per_characterはfill_over_strokeと同じ重なり（塗りがストロークの上）を、 文字ごとに完結させて描画します。描画順で同じ文字番号が連続する範囲ごとに全パスを終えてから 次の範囲へ進むため、各文字が自分のストロークを自分の塗りで隠した状態で完成します。 文字を重ねたとき、後続の文字のストロークが先行する文字の塗りの上に乗ることがありません。 文字番号による並べ替えは行わないため、描画順がA A B Aなら3つの範囲になります。 Gapがある場合、その消去はその範囲の内側だけに閉じ込められ、先行文字を削りません。 3D投影が有効なフレームは、orderの指定に関わらず常にこの文字単位描画になります。 Crayonは従来どおり通常描画の後にまとめて描かれるため、この設定の対象外です。
シミュレータのCanvasプレビューはorderの合成を再現しません。 選択・保存・スクリプトからの読み書きは動作しますが、 重なりの最終的な見え方はプラグイン本体の描画結果で確認してください。
chars[index].stroke.useがfalseの文字には、上記の全体ストローク設定が使われます。 パーツまで含めた継承順は「継承の仕組み」を 参照してください。
ctx.global.shadow
NOTE
このシャドウは、文字・パーツと同じ形状を distance/angle の位置へオフセットしたコピーで、 blur_x/blur_y でぼかせます（どちらも既定値は 0 で、輪郭が鮮明なままです）。サイズは 本体と常に等倍のため、distance = 0 でぼかしも無い場合は本体テキストの真後ろに完全一致で重なり、 見た目にはシャドウが全く見えません（縮小されて透けて見える、といった挙動にはなりません）。
| フィールド | 型 | 単位 | 内容 |
|---|---|---|---|
enabled | boolean | - | 全体シャドウの有効状態 |
distance | number | em | シャドウ距離。1.0 = 1 em。パーツ自身の空間で測るため、拡縮・stretch・回転・遠近があってもシャドウは文字から同じ距離に見える。angle で決めた方向は canvas 上で固定される。正で angle 方向へ遠ざかる。書き込み時の上限は10.0 |
angle | number | degree | シャドウ方向。0度で右方向、正（+）で右回り（時計回り）に回転（90度で真下方向） |
blur_x / blur_y | number | em | シャドウのぼかし（ガウスのσ）。1.0 = 1 em。書き込み時は 0〜10 に丸められます |
glow | number | - | グローの強さ。ぼかしたシャドウを明るく持ち上げて発光させ、色が飽和した芯は白に近づきます。0 でグローなし。シャドウがぼけていないときは効果がありません。書き込み時は 0〜10 に丸められます |
color | color | RGBA 0-1 | シャドウ色 |
chars[index].shadow.useがfalseの文字にはshadow.colorが使われます。 パーツまで含めた継承順は「継承の仕組み」を 参照してください。
WARNING
シャドウを有効にすると描画負荷が増え、レンダリング性能が低下します。 特に高解像度や複雑なテキストでは影響が大きくなるため、必要な場合だけ使用してください。
グラデーションが塗るのは、文字・パーツのfill.useがどちらもfalseの部分だけです。 fill.useがtrueの個別色はグラデーションより優先され、単色になります。 fill.useとopacityの段階分けは 「継承の仕組み」を参照してください。
ctx.global.emoji
ホストのText Settings内「Emoji」グループに対応します。OnPreLayoutで書き換えられ、OnLayout・OnPathでは読み取りのみです。
| フィールド | 型 | 単位 | 内容 |
|---|---|---|---|
offset_x / offset_y | number | em（1.0 = フォントサイズ 1 em） | フォントが置く位置からの絵文字のずらし量。Yは上が正です。文字送りは変わりません |
scale | number | 倍率 | 本文の何倍のフォントサイズで絵文字を組むか。文字送りも一緒に変わります。書き込み時に最小0.001へクランプされます |
use_custom_font | boolean | - | trueでfont_nameのフォントを使います。falseならシステムの絵文字フォント（Windows: Segoe UI Emoji、macOS: Apple Color Emoji）です |
font_name | string | - | カスタム絵文字フォント（ctx.fontsのいずれか）。use_custom_fontがfalseの間は値を保持したまま無視されます。見つからない名前はシステムの絵文字フォントになります |
use_outline | boolean | - | trueでカスタムフォントの輪郭から絵文字を描きます。use_custom_fontがtrueのときだけ効きます |
WARNING
どの値も、変えるとレイアウトを作り直します（変形中の絵文字は画像も作り直します）。 フレームごとに変化させると描画が大きく遅くなるため、固定値で使ってください。
use_outlineが効いている絵文字は通常の文字として扱われ、塗り色・グラデーション・テクスチャ・ストローク・シャドウが本文と同じように効きます。 輪郭を持たないグリフ（カラー専用のグリフなど）は、パーツを持たない文字になり何も描かれません。
シミュレータは絵文字を簡易表示します。絵文字のシーケンスを1文字1パーツにまとめ、offset_x / offset_y / scaleで配置し、ブラウザの絵文字フォントで描きます。 カスタム絵文字フォントの読み込みやuse_outlineの輪郭描画は行わず、3Dプリセットでは絵文字の四角だけを表示します。最終的な見た目はプラグイン本体で確認してください。
1.9 ctx.camera
3Dプリセットのカメラです。2Dプリセットでも代入はエラーになりませんが、描画に反映されるのは 3Dプリセットだけです。
| フィールド | 型 | 単位 | 内容 |
|---|---|---|---|
target_x / target_y | number | canvas正規化座標 | カメラ注視点。Xは右、Yは上が正です。注視点が動くとオブジェクトは逆方向に動いて見えます |
yaw / pitch | number | degree | カメラの旋回。yawは正（+）でカメラが右に回り込み、pitchは正（+）で上に回り込む（見下ろす） |
perspective | number | - | カメラ距離／遠近感を表す強度。内部でカメラ距離distancePx = f(perspective) * canvas.heightに写像されます（fは強度から距離係数への単調写像で、大きいほどカメラが近づき遠近が強くなります）。0〜1に丸められます。カメラのどの項目も有限である必要があり、NaN・infを書くとエラーです |
zoom | number | 倍率 | 投影拡大率。書き込み時に最小0.001へクランプされます |
lens_shift_x / lens_shift_y | number | canvas比率 | 主点移動。lens_shift_xの正（+）で全体が右、lens_shift_yの正（+）で全体が上にシフト |
1.10 ctx.chars[index]
ctx.charsはLua標準どおり1始まりの配列です。テキストやフォントが変わると、 文字数と各要素のindexも変わります。
fill / stroke / shadowのuseがfalseの場合は非表示になるのではなく、 グローバル値を継承します。詳しくは 「継承の仕組み」を参照してください。
| フィールド | 型 | 単位 | 内容 |
|---|---|---|---|
index | integer | - | 1始まりの文字index。読み取り専用 |
text | string | - | この文字クラスタの元テキスト。読み取り専用 |
part_start / part_count | integer | - | 所有パーツの先頭グローバルindex（1始まり）と個数。読み取り専用 |
line_index | integer | - | 属する行の1始まりindex。読み取り専用 |
geometry | table | - | 変形前の配置情報（下記）。読み取り専用 |
offset_x / offset_y | number | canvas正規化変位 | 文字の移動量。0.5で変位量0になり、大きいほど右／上へ移動します |
pivot_x / pivot_y | number | canvas正規化変位 | 文字変形の支点。0.5で自然中心になり、大きいほど右／上へ移動します |
scale | number | 倍率 | 均等スケール。書き込み時に最小0.001へクランプされます |
stretch_x / stretch_y | number | 倍率 | 非均等スケール。scaleと異なり正の下限はなく、0や負値も受理されます |
rotation | number | degree | 2D回転。正（+）が時計回り（右回り）、負（-）が反時計回り（左回り）です |
z | number | canvas高さ比 | 奥行き。正（+）で奥（カメラから遠ざかる）方向、負（-）で手前（カメラに近づく）方向です。3Dプリセットのみ描画に反映されます |
yaw / pitch | number | degree | 3D個別回転。yawは正（+）で右端が手前へ、pitchは正（+）で上端が手前へ回転します。3Dプリセットのみ描画に反映されます |
opacity | number | 0-1 | この文字の不透明度。既定値は1.0で、範囲外の値はホストが描画直前にクランプします。ctx.global.opacityと乗算されます（fill.useの判定には関与しません。役割分担を参照してください） |
z_index | number | - | 図形（ctx.shapes）専用の描画順の値です。本文の文字では無視されます（書き込みは受理されますが、描画順に影響しません） |
fill | table | - | 個別塗り（下表） |
stroke | table | - | 個別ストローク（下表） |
shadow | table | - | 個別シャドウ色（下表） |
texture | table | - | 個別テクスチャ。ctx.global.texture と同じ構造に use が付きます |
blur | table | - | 文字の個別ぼかし。ctx.global.blur と同じ構造に use が付きます |
chars[index].fill
| フィールド | 型 | 単位 | 内容 |
|---|---|---|---|
use | boolean | - | trueならfill.colorを使います |
color | color | RGBA 0-1 | useがtrueのときに使う個別色 |
chars[index].stroke
| フィールド | 型 | 単位 | 内容 |
|---|---|---|---|
use | boolean | - | trueならInner / Outerを含む個別ストローク設定を使います |
width | number | em（1.0 = フォントサイズ 1 em） | useがtrueのとき |
gap | number | em（1.0 = フォントサイズ 1 em） | useがtrueのとき |
color | color | RGBA 0-1 | useがtrueのとき |
outer_width | number | em（1.0 = フォントサイズ 1 em） | Inner Strokeの外側に隣接するOuter Strokeの太さ。width > 0のときだけ有効 |
outer_color | color | RGBA 0-1 | Outer Strokeの色 |
chars[index].shadow
| フィールド | 型 | 単位 | 内容 |
|---|---|---|---|
use | boolean | - | trueならshadow.color、blur_x、blur_y、glowを使います |
color | color | RGBA 0-1 | useがtrueのときに使う個別色 |
blur_x / blur_y | number | em | useがtrueのときに使うシャドウの個別ぼかし。設定するまでは継承した値が読み取れます。書き込み時は 0〜10 に丸められます |
glow | number | - | useがtrueのときに使うシャドウの個別グローの強さ。設定するまでは継承した値が読み取れます。書き込み時は 0〜10 に丸められます |
サブオブジェクトへのテーブル全体代入は、§1.8と同じマージ規則です。
chars[index].geometry
文字のスクリプト変形、Deform、3D投影より前のレイアウトを表します。
位置と寸法はcanvas正規化です。内部画素座標からは Xを0.5 + px/width、Yを0.5 - px/heightとして変換します。
| フィールド | 型 | 単位 | 内容 |
|---|---|---|---|
canvas_origin_x / canvas_origin_y | number | canvas 正規化位置 | 組版原点（横書き: セル左端 × ベースラインに相当する placement origin） |
vertical_origin_x / vertical_origin_y | number | canvas 正規化位置 | 縦組み原点（列中心軸 × セル上端） |
bounds_center_x / bounds_center_y | number | canvas 正規化位置 | 変形前の文字輪郭が占める範囲（ink bounds）の中心 |
bounds_width | number | canvas 幅比 | ink bounds の幅 / canvas 幅 |
bounds_height | number | canvas 高さ比 | ink bounds の高さ / canvas 高さ |
advance_x | number | canvas 幅比 | フォントの水平送り（px）/ canvas 幅。tracking / margins を含まない |
advance_y | number | canvas 高さ比 | フォントの垂直送り（px）/ canvas 高さ（符号反転して Y-up）。下方向送りは負。tracking / margins を含まない |
スペースなど輪郭を持たない文字は ink bounds が潰れるため、代わりにフォント定義の文字セルを 返します。組版の流れ方向（横書きならX、縦書きならY）はその文字自身の送りが幅・高さになり、 交差軸はセルの高さ（横書き）／列幅（縦書き）になります。これにより、スペースの bounds_center_y が隣の文字より半セル下にずれることはありません。
1.11 ctx.parts[index]
ctx.partsはLua標準どおり1始まりの配列です。indexは文字ごとの番号ではなく、 フレーム全体を通したパーツ番号です。テキストやフォントが変わると、パーツ数と各要素の indexも変わります。
| フィールド | 型 | 単位 | 内容 |
|---|---|---|---|
index | integer | - | 1始まりのグローバルパーツindex。読み取り専用 |
character_index | integer | - | 所有文字の1始まりindex。読み取り専用 |
index_in_character | integer | - | 文字内での1始まりパーツindex。読み取り専用 |
geometry | table | - | 変形前の配置情報（下表）。読み取り専用 |
offset_x / offset_y | number | canvas正規化変位 | パーツの移動量。0.5で変位量0になり、大きいほど右／上へ移動します |
pivot_x / pivot_y | number | canvas正規化変位 | パーツ変形の支点。0.5で自然位置になり、大きいほど右／上へ移動します |
scale | number | 倍率 | 均等スケール。書き込み時に最小0.001へクランプされます |
rotation | number | degree | 2D回転。正（+）が時計回り（右回り）、負（-）が反時計回り（左回り）です |
stretch_x / stretch_y | number | 倍率 | 非均等スケール。scaleと異なり正の下限はなく、0や負値も受理されます |
z | number | canvas高さ比 | 奥行き。正（+）で奥（カメラから遠ざかる）方向、負（-）で手前（カメラに近づく）方向です。3Dプリセットのみ描画に反映されます |
yaw / pitch | number | degree | パーツ個別の3D回転。パーツpivotを中心に、所有文字の回転済み空間の内側で適用されます。yawは正（+）で右端が手前へ、pitchは正（+）で上端が手前へ回転します。3Dプリセットのみ描画に反映されます |
opacity | number | 0-1 | このパーツの不透明度。既定値は1.0で、範囲外の値はホストが描画直前にクランプします。所有文字のopacity（さらにctx.global.opacity）と乗算されます（fill.useの判定には関与しません。役割分担を参照してください） |
fill | table | - | use / colorを持つ個別塗り。文字のfillと同じ構造で、useがtrueならcolorを採用します |
stroke | table | - | use / width / gap / color / outer_width / outer_colorを持つ個別ストローク。文字のstrokeと同じ構造で、useがtrueなら個別値を採用します |
shadow | table | - | use / colorを持つ個別シャドウ色。文字のshadowと同じ構造で、useがtrueならcolorを採用します |
texture | table | - | 個別テクスチャ。文字のtextureと同じ構造で、useがtrueならそのマテリアルを採用します |
blur | table | - | 文字の個別ぼかし。文字のblurと同じ構造で、useがtrueならamount_x / amount_y / glowを採用します |
文字からの継承
パーツの塗り・ストローク・シャドウは、それぞれのuseによって次のように決まります。
| パーツの設定 | use = false | use = true |
|---|---|---|
fill | 所有文字の段階で選ばれた塗りを継承します | パーツのfill.colorを使います |
stroke | 所有文字の段階で選ばれたInner / Outer設定を継承します | パーツのstroke設定を使います |
shadow | 所有文字の段階で選ばれたshadow.colorを継承します | パーツのshadow.colorを使います |
所有文字でもuse = falseの場合は、さらにctx.globalの設定まで遡ります。詳しくは 「継承の仕組み」を参照してください。
インスペクタにない個別設定
パーツのstrokeとshadowにはインスペクタ上のパラメータがなく、初期状態は 未使用／既定値です。スクリプトでuseをtrueにすると、設定した個別値が優先されます。
yaw / pitchもインスペクタにはなく、初期値は0です。所有文字の回転とは独立しており、 文字の回転空間内で追加の回転として適用されます。
parts[index].geometry
スクリプト変形、Deform、3D投影より前のレイアウトを表します。Yは上が正です。
| フィールド | 型 | 単位 | 内容 |
|---|---|---|---|
local_center_x / local_center_y | number | canvas 軸比の変位 | 所有文字の変形前の輪郭範囲（ink bounds）の中心を原点としたパーツ中心。中立オフセットなし（0が文字中心上）。Y成分はY-up |
canvas_center_x / canvas_center_y | number | canvas 正規化位置 | パーツ自然位置（レイアウト後の中心）の canvas 座標 |
bounds_center_x / bounds_center_y | number | canvas 正規化位置 | 変形前のパーツ輪郭が占める範囲（ink bounds）の中心 |
bounds_width / bounds_height | number | 各 canvas 軸比 | ink bounds の幅・高さ |
1.12 ctx.bounding_box
InspectorでOFFのBBをスクリプトから有効化するときは、各辺・線幅・余白・色・塗り・opacity・cap・offsetなど、演出に必要な設定を明示してください。本体はOFFのBBについて現在のInspector値を読み込まないため、これらのフィールドをスタイルの初期値として参照しないでください。
基準矩形
2Dの基準矩形はGlobal回転前の変換済みFill境界を囲み、本文と同じGlobal回転を適用します。3Dではglobal layout plane上で組み立てて投影します。 その外側へmarginを加え、fillとstrokeをそれぞれ独立したoffsetでずらして描画します。
寸法の基準
次の寸法系フィールドはfontSizeに対する百分率です （描画: value * fontSizePx / 100。100.0 = fontSizeと同じ長さです）。
| フィールド | 型 | 単位 | 内容 |
|---|---|---|---|
enabled | boolean | - | 枠の描画を有効にする |
draw_top / draw_bottom / draw_left / draw_right | boolean | - | 各辺のストロークを描くか |
color | color | RGBA 0-1 | 枠線色 |
width | number | fontSize 百分率 | 枠線の太さ |
fill_enabled | boolean | - | 枠内塗りを有効にする |
fill_color | color | RGBA 0-1 | 枠内塗り色（アルファに fill_opacity を乗算） |
fill_opacity | number | 0-1 | 枠内塗りの不透明度乗数 |
start_cap / end_cap | string | 下記列挙 | 開いたパス端のキャップ |
margin_x / margin_y | number | fontSize 百分率 | テキスト bounds 外側への余白（各辺に加算） |
corner_radius | number | fontSize 百分率 | 四辺すべて有効時の角丸半径（矩形の半分で上限） |
fill_offset_x / fill_offset_y | number | fontSize 百分率 | 塗り矩形の平行移動 |
stroke_offset_x / stroke_offset_y | number | fontSize 百分率 | 枠線の平行移動（塗りと独立） |
start_cap / end_cap の値: butt / square / round / round_rev / triangle / triangle_rev
1.13 ctx.output
OnLayoutで読み書きする出力フィルタ・描画順制御です。Separation系のみ読み取り専用です。
| フィールド | 型 | 単位 | 内容 |
|---|---|---|---|
separation_enabled | boolean | - | Separation出力が有効か。読み取り専用 |
render_mode | string | - | 現在の出力スロット。default / separation_1 / separation_2。読み取り専用 |
targets_1 / targets_2 | string | - | 各Separation出力に割り当てられたターゲット指定文字列。読み取り専用 |
write_on_mode | string | - | Write-onの単位。characterまたはpart |
write_on_start | number | 0-1 | 表示区間の始端（正規化進行度） |
write_on_end | number | 0-1 | 表示区間の終端。start = 0かつend = 1のときフィルタなし（全表示） |
reorder_parts | boolean | - | trueのときパーツの描画順・reveal順を書き順（stroke order）にします。単一パーツ文字では見た目に影響しません |
manual_order_enabled | boolean | - | trueのときmanual_order_textでreveal / 描画順を上書きします |
manual_order_text | string | - | 手動順の指定（下記構文） |
force_disable_3d_projection | boolean | - | trueのとき、そのフレームの3D投影を最終的に無効化します。既定値はfalse（API Level 7） |
2D専用スクリプト
ctx.output.force_disable_3d_projection = trueを指定すると、プリセットが3D対応でも2D描画経路を使用します。Camera、Global、Character、Partに対するインスペクタ設定とキーフレームを含め、すべての3D操作が無視されます。現在の3D値が偶然ニュートラルであることを理由に設定せず、作品を2D専用にすることが明確な場合にだけ使用してください。
function OnLayout(ctx)
-- This effect intentionally guarantees 2D output.
ctx.output.force_disable_3d_projection = true
endWrite-on
表示対象は、単位ごとの1始まりの順位が[startLimit, endLimit]に入る要素に限られます。
startLimit = floor(write_on_start * N) + 1
endLimit = ceil(write_on_end * N)Nはwrite_on_mode == "character"のとき文字数、"part"のときパーツ数です。
順位の取り方:
| mode | 既定の順位 | manual_order_enabled 時 | reorder_parts のみ |
|---|---|---|---|
character | レイアウト順の文字 index（1..N） | 文字レベルの manual reveal 順 | 文字順位はレイアウト順のまま |
part | ctx.parts[index].index（1..N） | パーツの manual reveal 順 | stroke order の reveal 順 |
manual_order_text 構文
トークンの解釈
トークンはカンマまたは空白で区切ります。無効なトークンは無視され、同じパーツを 複数回指定した場合は最初の指定だけが採用されます。
| トークン | 意味 |
|---|---|
c<n> / C<n> | 1 始まり文字 n。その文字の全パーツを、当時のパーツ順（reorder_parts が true なら stroke order、false ならレイアウト順）で展開 |
p<n> / P<n> | 1 始まりグローバルパーツ n |
<n> | プレフィックス無し。パーツ index として解釈 |
<a>-<b> | 両端を含む範囲。両端は同じ種別（文字同士またはパーツ同士）。片方だけプレフィックスがある場合は他方に種別を継承。展開は昇順 |
例: "3,1,2"（パーツ 3→1→2）、"c1-c3"（文字 1〜3）、"p2-p5"（パーツ 2〜5）。
順序への反映
指定された要素は指定順で先頭へ移動します。未指定パーツは非表示にならず、 基準順序での相対順を保って後ろへ続きます。
順序は未変形のレイアウトと指定文字列から決まり、アニメーション後の空間位置から フレームごとに再計算されません。write_on_start/endは表示範囲を決め、 manual orderは要素の順序だけを変更します。
2Dの描画順にはmanual orderがそのまま適用されます。3Dでは各パーツの奥行きを優先し、 奥行きが同じパーツをmanual order、stroke order、レイアウト順の優先順位で並べます。 Write-onのreveal順は2D／3Dとも常にmanual orderに従います。
1.14 ctx.paths
ctx.pathsは対象を遅延取得するため、取得しなかったパーツのパスはLua側へコピーされません。ctx.pathsはOnPathの呼び出しの間だけ有効です。変数に保存して、あとの呼び出しで使うとエラーになります。
| フィールド | 型 | 単位 | 内容 |
|---|---|---|---|
units_per_em | number | path unit/em | パス座標のスケール。常に1000 |
part(index) | function | - | 1始まりの通しパーツ番号から1パーツを取得。存在しなければnil |
character(index) | function | - | 1始まりの文字番号が所有する全パーツを、通しパーツ番号順の配列で取得 |
select(selector) | function | - | 選択書式に一致するパーツを、通しパーツ番号順の配列で取得 |
shape(number) | function | - | 1始まりの図形番号の図形が持つパーツを、1要素の配列で取得。その番号の図形が無ければ空の配列。part・character・selectは本文だけを対象にします |
select(selector)の選択書式
cは文字番号、pは通しパーツ番号、!は除外を表します。カンマで複数の条件を 指定でき、c3-5やp8-10のような範囲にも対応します。
local parts = ctx.paths:select("c1, p8-10, !p9")同じパーツを複数回取得した場合、同一フレーム内では同じ可変オブジェクトが返されます。
取得したパーツ
| フィールド | 型 | 単位 | 内容 |
|---|---|---|---|
index | integer | - | フレーム全体の1始まり通しパーツ番号 |
character_index | integer | - | 所属文字の1始まり番号 |
index_in_character | integer | - | 所属文字内の1始まりパーツ番号 |
line_index | integer | - | 所属行の1始まり番号 |
text | string | - | 所属文字が表すテキスト |
path | path | - | 変更対象の描画パス |
pathの編集
pathはパーツの描画輪郭を表す可変オブジェクトです。元の輪郭を消去・置換したり、 直線やベジェ曲線を追加したりできます。メソッドと座標系の詳細は 描画パス編集APIを参照してください。
1.15 ctx.glyphs
APIレベル: 9+
ctx.glyphs:declare(declaration)
ctx.glyphs:declare(declaration)は、パスと文字メトリクスを持つカスタムグリフを宣言し、 ctx.global.textへ埋め込める1文字のプレースホルダー文字列を返します。 レイアウト生成前に宣言を確定する必要があるため、OnPreLayoutでのみ呼び出せます。
この宣言は2つの座標空間を扱います。形状を描くpathは既存の描画APIと同じY-down、 形状を配置するadvance_*とboundsは既存のgeometry APIと同じY-upです。 したがって、縦書きで下方向へ900 units送る場合はadvance_y = -900と指定します。
| field | type | 既定値 | 単位・内容 |
|---|---|---|---|
path | MtDrawingPath | 空パス | 初期形状。Part中心原点、Y-down、1000 units = 1 em |
advance_x | number | 0.0 | 水平送り。右が正、1000 units = 1 em |
advance_y | number | 0.0 | 垂直送り。上が正、1000 units = 1 em。縦書きの下方向送りは負 |
bounds | number[4] | pathから自動算出 | {minimumX, minimumY, maximumX, maximumY}。ベースライン原点、Y-up、1000 units = 1 em |
boundsを省略すると、Part中心のXをadvance_x / 2へ置き、pathの最下端をベースラインへ 揃えます。自動boundsは{ advance_x / 2 + pathMinimumX, 0, advance_x / 2 + pathMaximumX, pathMaximumY - pathMinimumY }です。このためmt.svg_pathで view_boxを指定して中心原点へ正規化したSVGアイコンは、寸法を重複指定せずそのまま利用できます。 pathが空の場合は{0,0,0,0}になります。advance_yは送りメトリクスであり、横書きの自動配置には使いません。
縦書きでは、横書き用のベースライン位置にかかわらず、字面中心をadvance_yが作るセルの中央へ 配置します。trackingと個別marginsはセルの後方余白なので字面中心には含めません。 advance_y = 0の場合は現在の縦書きpen位置へ字面中心を置きます。
幅も高さも0のbounds（例:{0,0,0,0}）は「描画はするが測らないグリフ」として扱い、 h_align / v_alignが参照する整列ボックスから除外します。送りを持たない装飾マーカーを テキスト末尾へ追加しても、行が整列端から動きません。整列は送りではなくboundsで決まるため、 負のmarginsで送りを打ち消してもこの除外の代わりにはなりません。
boundsを明示すると、その中心をPart中心として使用します。ベースラインより下が負、上が正です。 たとえばベースラインから上へ700 units、左右へ500 units広がる図形は { -500, 0, 500, 700 }と指定します。パス座標だけは既存の描画パスAPIと同じY-downです。
local icon = mt.svg_path("M 2 2 L 22 2 L 22 22 L 2 22 Z", {
view_box = { 0, 0, 24, 24 },
em_scale = 0.8,
})
function OnPreLayout(ctx)
local marker = ctx.glyphs:declare({
path = icon,
advance_x = 1000,
advance_y = -1000,
})
ctx.global.text = "A" .. marker .. "B"
endpathは宣言時点のsnapshotです。宣言後に元のパスを変更しても、宣言済みの形状は変わりません。 pathを省略しboundsを指定すると、送り幅とboundsだけを持つ不可視文字として使用できます。同じカスタムグリフを 複数箇所へ置く場合は、返されたmarkerを複数回テキストへ埋め込みます。 advance_xとadvance_yは、trackingと個別marginsを含まない純粋なグリフ送りです。 カスタムグリフにも通常文字と同じく、その文字の後方送りへtrackingと対応するmarginsを加算します。 このためadvance_x = 0でも、横書きではtracking + margins[i]分の送りが残ります。
プレースホルダーはホストがUnicode私用領域のU+E002から宣言順に割り当てます。U+E000と U+E001は内部の改行処理用に予約されています。カスタムグリフも通常文字と同じ文字数・パーツ数の 上限を消費します。hookまたはcommitが失敗したフレームでは、そのフレームの宣言をすべて破棄します。
1.16 ctx.inputs
ctx.inputsはInspectorのScript Inputsで設定した値を全コールバックへ渡す読み取り専用objectです。 各配列は1始まりで、要素数は固定です。
| フィールド | 型 | 要素数 | 内容 |
|---|---|---|---|
numbers | number[] | 14 | 単位を持たない数値入力 |
colors | MtColor[] | 8 | RGBA色入力 |
texts | string[] | 4 | 単一行のテキスト入力 |
booleans | boolean[] | 8 | checkboxの真偽値入力 |
local amount = ctx.inputs.numbers[1]
local primary = ctx.inputs.colors[1]
local caption = ctx.inputs.texts[1]
local enabled = ctx.inputs.booleans[1]ctx.inputs、各配列、色の各channelはすべて読み取り専用です。配列外のindexはnilを返します。
1.17 ctx.shapes
ctx.shapesは、本文とは別に置く図形（背景、枠、飾りなど）を扱います。図形はctx.global.textに 含まれず、送り幅・整列・折り返しといったレイアウトの流れに入りません。ctx.chars・ctx.char_count・ ctx.parts・ctx.part_countは本文だけを数え、図形はctx.shapes[number]・ctx.shape_countで扱います。
図形はOnPreLayoutで宣言し、OnLayoutとOnPathでは1始まりの図形番号で読みます。
ctx.shapes:declare(declaration)
図形を1つ宣言し、1始まりの図形番号（宣言した順）を返します。OnPreLayoutでのみ呼び出せます。 未知のフィールドや不正な値はエラーになります。
| field | type | 既定値 | 内容 |
|---|---|---|---|
path | MtDrawingPath | 空パス | 図形の輪郭。図形の位置が原点、Y-down、1000 units = 1 em（カスタムグリフのpathと同じ座標系） |
layer | string | "back" | "back"は本文より後ろ、"front"は本文より前に描く |
parent | integer | なし | 親にする図形の番号。先に宣言した図形（このdeclareより前の戻り値）に限ります。省略すると親なしです |
camera | integer | 親のカメラ。なければなし | この図形を3Dで投影するカメラの番号。先にctx.shape_cameras:declare()で宣言したものに限ります。親のある図形は親のカメラを引き継ぎ、親と違う番号を指定するとエラーです（カメラのない親の子も指定できません）。カメラのない図形は、これまでどおりキャンバスに固定されます |
pathは宣言時点のsnapshotです。同じ層の図形は、z_indexが小さい順、同じなら宣言した順に重なります。
parentを指定した図形は、親に対する相対の位置・回転・拡大・伸縮になります。子の変形は、親の変形を受けた座標系で働きます。
offset_x/offset_yが0.5のとき、子は親の位置（親のパスの原点）に重なります。ずれ量は、親の拡大・回転・伸縮を受けます。- 子の
rotation・scale・stretch_*・pivot_*は、子自身の位置を中心に、親の座標系で働きます。親が非等方に伸縮していると、回転した子は歪んで見えます。 - 親の
opacity・fill・stroke・shadow・blur・textureは、子に引き継がれません。各図形が自分で設定します。 - 子も親になれます（祖父母まで辿ります）。親を
opacity = 0にして、子だけを見せることもできます。 - 親の拡大が
0になると、子も大きさを失い、何も描かれません。連鎖の倍率は倍精度で累積し、その図形の描画用の行列が単精度の範囲を超えるときも、その図形は何も描かれません（途中の図形が範囲を超えても、後ろの図形の倍率が戻れば、後ろの図形は描かれます）。 - 親に使えるのは図形だけで、本文の文字は親にできません。
local rectangle = mt.svg_path("M -500 -300 L 500 -300 L 500 300 L -500 300 Z")
function OnPreLayout(ctx)
local background = ctx.shapes:declare({ path = rectangle })
local frame = ctx.shapes:declare({ path = rectangle, layer = "front" })
end図形の設定
ctx.shapes[number]はOnLayoutとOnPathで参照できます。OnLayoutでは次のフィールドを、ctx.chars[index]と 同じ規則で設定できます。
| フィールド | 型 | 内容 |
|---|---|---|
index | integer | 図形番号。ctx.shapes:declareの戻り値と同じ値 |
offset_x / offset_y | number | 位置のずれ。0.5でずれなし。何も設定しない図形は、キャンバスの中央に出ます |
pivot_x / pivot_y / scale / stretch_x / stretch_y / rotation / z / yaw / pitch | number | ctx.chars[index]と同じ変形。図形は自分の位置（パスの原点）を中心に回転・拡縮し、pivot_*もそこからの変位です |
opacity | number | 不透明度の倍率（0〜1） |
parent | integer | 読み取り専用。ctx.shapes:declareで指定した親の図形番号。親がないときは0 |
camera | integer | 読み取り専用。この図形を投影するカメラの番号（親から引き継いだ番号を含む）。カメラがないときは0 |
z_index | number | 描画順の値（既定値0）。同じ層の中で、小さいものから順に描かれ（大きいものが手前）、同じ値は宣言した順です。layerの背面・前面は越えません。+inf・-infは最大・最小として並び、NaNは代入するとエラーです。親子関係とは無関係です |
fill / stroke / shadow / texture / blur | table | 個別の見た目。ctx.chars[index]と同じ項目 |
path | path | 図形の輪郭。OnLayoutのみ。宣言したパスから始まり、path:assign(p)などで直接編集する。毎フレーム、宣言したパスへ戻る |
pathは代入できません。shape.path:assign(p)のように、渡したパスをコピーして置き換えます。編集したパスだけが そのフレームで使われます。ctx.paths:shape(number)（OnPath）で、OnLayoutで編集した後のパスを、さらに編集できます。
function OnLayout(ctx)
local shape = ctx.shapes[1]
shape.path:assign(drawLights(ctx))
shape.opacity = 0.8
shape.fill.use = true
shape.fill.color = { r = 1.0, g = 0.5, b = 0.7, a = 1.0 }
endctx.shape_cameras:declare()
図形用のカメラを1つ宣言し、1始まりのカメラ番号（宣言した順）を返します。OnPreLayoutでのみ呼び出せ、上限は16個です。 図形用のカメラは、本文のカメラ（ctx.camera）とは別のカメラです。本文のカメラ、Global、本文の3D姿勢は図形に影響せず、 図形用のカメラも本文に影響しません。
ctx.shape_cameras[number]はOnLayoutで参照・設定できます。値は毎フレーム、本文のカメラの既定値から始まるので、 動かしたいフレームごとに書きます。
| フィールド | 型 | 既定値 | 内容 |
|---|---|---|---|
target_x / target_y | number | 0.5 / 0.5 | カメラの注視点（キャンバスの割合）。target_yは上向きが正 |
yaw / pitch | number | 0 | カメラの軌道角（度）。ctx.cameraと同じ向き |
perspective | number | 0.5 | 遠近感の強さ。0〜1に丸められます |
zoom | number | 1 | ズーム倍率 |
lens_shift_x / lens_shift_y | number | 0 | レンズシフト（キャンバスの割合）。lens_shift_yは上向きが正 |
数値は有限である必要があり、NaN・infを書くとエラーです。位置・姿勢・カメラの値が数として扱えなくなった図形（z = 1e308など）は、何も描かれません。
カメラを指定した図形（ctx.shapes:declare({ camera = number })）は、yaw・pitch・zを含む自分の姿勢が3Dになり、 そのカメラで投影されます。
- 各図形は自分の位置（パスの原点）を中心に回ります。親の姿勢は、子の位置と向きに掛かります。親を
pitchで倒すと、親の上方向にずらした子は奥行き方向に動きます。 - 同じ親子の木は、1つのカメラで投影されます。子が
cameraを省略すれば親のカメラを使い、親と違う番号を指定するとエラーです。 - カメラのない図形では、
yaw・pitch・zは見た目に効きません。 scaleは図形の面内（x・y）にだけ効き、奥行きには効きません。縮尺を変えた親の下で、回転した子は、せん断（斜めに歪むこと）します。回転した図形に付ける子の形を保ちたいときは、scaleを1のままにして、大きさをパスの寸法と、子のoffset（親の長さ）に直接反映してください。- 描画順は、層、
z_indexの順で決まり、同じ層・同じz_indexの中で、同じカメラの図形どうしだけ奥行きの遠い順に並びます。カメラの違う図形、カメラのない図形の位置は動かしません。 - 線幅、影、ぼかしの大きさは、図形の位置の奥行きの縮尺に従います。
function OnPreLayout(ctx)
local view = ctx.shape_cameras:declare()
local card = ctx.shapes:declare({ path = rectangle, camera = view })
end
function OnLayout(ctx)
ctx.shape_cameras[1].pitch = 20
ctx.shapes[1].yaw = ctx.time * 90
end本文と違う扱い
- レイアウトの流れ（送り幅、整列、折り返し）に入りません。
- Write On、Gradient、Bounding Box、Deform、Crayon、ビューアでの選択の対象になりません。
- Globalの変形と本文の3Dのカメラの影響を受けません。図形はキャンバスに固定され、
ctx.shape_camerasのカメラを指定した図形だけが、そのカメラで3Dに投影されます。 - 手動の順序（
manual_order_text）に図形の番号は書けません。描画順は、layer、z_index、宣言の順で決まります。本文を図形の間に挟むことはできません。 - 文字数・パーツ数の上限を使いません。図形の数の上限は、全プリセット共通で
ctx.meta.limits.max_shapesです。上限を超えた宣言はエラーです。 - Output Separationの影響は受けます。
- 制限事項: 本文のCrayon（実験的機能）の線は、
layer = "front"の図形より手前に描かれます。 mt.layout.place_2d・mt.layout.get_canvas_position_2d・mt.layout.canvas_to_offset_2dは、図形を文字と同じように受け取れます。アンカーは図形の位置です。親のある図形では、親の変形を通した位置を扱い、place_2dとcanvas_to_offset_2dは親の座標系のoffsetを返します（親の大きさが0のときはエラー）。- 本文の見た目の設定（文字色、縁取り、影、ぼかし、glow、テクスチャ）は図形にも掛かります。掛けたくない設定は、
OnLayoutでctx.shapes[number]へ設定して上書きします。