スクリプティング入門

概要

Cavalry の JavaScript は、シーン内のレイヤーとデータへのアクセスを提供し、カスタムワークフローを実行するスクリプトを作成できるようにします。これには、レイヤーの作成、属性の設定、接続の作成などが含まれます。

最も簡単な始め方は、Create > Demo Scenes > JavaScript メニューの例を確認することです。

以下は、Text Shape を作成してアニメーションさせるサンプルスクリプトです。このスクリプトは JavaScript Editor で実行できます。タブにコピー＆ペーストして Run Script ボタンを押すだけです。

// Get the height of the composition (we're going to drop the text from the top)var height = api.get(api.getActiveComp(), "resolution.y");// The time difference between the first and last letters droppingvar timeOffset = 20;// Make a text shapevar textShapeId = api.create("textShape", "Bouncy Text");// Set some attributes on the text layer// The attributes are set via a dictionary of (key, value) pairs// This means many attributes can be set at once.api.set(textShapeId, {"horizontalAlignment": 1,                       "fontSize": 120,                      "font.style": "Black",                      "verticalAlignment": 1,                       "material.materialColor": "#ff24e0",                       "autoWidth": true,                        "autoHeight": true});// Get the bounding box of the text layervar bbox = api.getBoundingBox(textShapeId, true);// How far to we need to move the text shape to get it 'offscreen'var distToEdge = bbox.y * -1 + height * .5;// Get the start frame of the text shape (this could just be 0, but we're getting the in frame just to show off)var startFrame = api.getInFrame(textShapeId);// Set the end framevar endFrame = startFrame+40;// Create a Sub-Mesh layer which will power the 'per character' animation.var subMeshId = api.create("subMesh", "Bounce In Animator");// Set some keyframes, and set magic easingapi.keyframe(subMeshId, startFrame, {"shapePosition.y": distToEdge});api.keyframe(subMeshId, endFrame, {"shapePosition.y": 0});api.magicEasing(subMeshId, "shapePosition.y", startFrame, "BounceOut");// Connect the Sub-Mesh to the Text layer's Deformers Attributeapi.connect(subMeshId, "id", textShapeId, "deformers");// Parent the Sub-Mesh to the Text.api.parent(subMeshId, textShapeId);// Create a Stagger - this will be used to create the time offsetvar staggerId = api.create("stagger", "Bounce In Stagger");// Set the minimum/ maximum attributes on the Staggerapi.set(staggerId, {"minimum": -timeOffset, "maximum": 0});// Flip the Graph on the Stagger so it goes from 0 to timeOffsetapi.flipGraph(staggerId, "graph", "vertical");// Add the text shape to the Staggerapi.parent(textShapeId, staggerId);

サンプルスクリプト→

UI スクリプトのインストール

UI スクリプトをインストールするには、Help > Show Scripts Folder に移動し、スクリプトファイルをこのフォルダにドラッグします。ネストされたフォルダも許可され、サブメニューとして表示されます。このフォルダに保存されたスクリプトは、Cavalry を再起動することなく、すぐに Window > Scripts メニューから利用可能になります。

Cavalry シーン

すべての Cavalry シーンは、複数のレイヤーツリーで構成されています。シーン内のすべてのアセットレイヤーを含むアセットツリーがあり、それに加えて、Cavalry の各コンポジションには独自のレイヤーツリーがあります。JavaScript を使用してこれらのツリーを走査し、Cavalry の（ほぼ）すべてのレイヤーにアクセスできます。各ツリーは、任意の数のレイヤーで、任意の数のレベルで構成できます。

レイヤーと属性へのアクセス

コンポジション内のレイヤーと属性にアクセスするには、LayerId および/または AttributeId が必要です。

レイヤー ID

スクリプトでレイヤーにアクセスするために使用できる layerId を取得するには、Attribute Editor、Scene Window、または Viewport でレイヤーを右クリックし、コンテキストメニューから Copy Layer Id を選択します。

レイヤータイプ

layerType は layerId の一部であるため、上記と同じ方法でアクセスできます。layerType は layerId の # より前の部分です。例えば、layerId が basicShape#1 の場合、layerType は basicShape です。

属性 ID

スクリプトで属性にアクセスするために使用できる attrId を取得するには、Attribute Editor で属性を右クリックし、コンテキストメニューから Copy Scripting Path を選択します。例：

Basic Shape を作成します。
Attribute Editor で、Position 属性を右クリックします。
コンテキストメニューから Copy Scripting Path を選択します。

これにより position がクリップボードにコピーされ、スクリプト内で引数として使用できます：

api.get("basicShape#1", "position");

モジュール

JavaScript は複数の場所で使用でき、Cavalry にはシーンからデータへのアクセスを提供する 4 つのモジュールが含まれています。データの操作を容易にするための便利なメソッドも多数提供されています。Cavalry が提供するすべての JavaScript モジュールがどこでも利用できるわけではないことに注意してください。

API モジュール

JavaScript Editor でのみ利用可能。
シーンとファイルシステムへの編集アクセスを提供。
このモジュールのプレフィックスは api。

Context モジュール

JavaScript Layers で利用可能。
JavaScript Utility の出力計算に関連するメソッドへのアクセスを提供。
このモジュールのプレフィックスは ctx。

Cavalry モジュール

JavaScript Layers と JavaScript Editor で利用可能。
データの作成と操作のためのユーティリティメソッドとクラスを提供。
このモジュールのプレフィックスは cavalry。

Deformer モジュール

JavaScript Deformer でのみ利用可能。
このモジュールのプレフィックスは def。

ログ

console.<method>() を使用して、Cavalry の JavaScript Console にメッセージを書き込みます。以下のメソッドを使用して、素早い認識のために異なる色のアクセントを含むコンテキスト固有のメッセージを出力できます。

console.log("This is a test."); // Typically used in testing (green).console.info("Confirming this happened as expected."); // Confirm when something expected has happened (green).console.warn("Just to let you know..."); // Warn a user when they've done something unexpected (yellow).console.error("Something went wrong."); // Flag when something has gone wrong (red).console.debug("I am a developer."); // Print a message to Terminal/Cmd Prompt.

用語集

多くのメンバー関数は、引数として入力を受け取ったり、異なる型の値を返したりします：

int - 整数は小数点のない数値です。例：4。
number - 小数桁を持つ数値です。例：4.153。
string - 文字列は英数字と記号を含むことができ、二重引用符で囲む必要があります。例："string"。
bool - ブール値は true または false です。
array - 配列は項目のリストです。例：["one", "two", "three"] または [1, 2, 3]。
object - オブジェクトはプロパティ（名前（またはキー）と値）のコレクションです。例：{width:10, height:10}。