腳本入門

簡介

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，然後將指令碼檔案拖入此資料夾。允許巢狀資料夾，並將顯示為子選單。儲存到此資料夾的指令碼將立即可從 Window > Scripts 選單中使用，無需重新啟動 Cavalry。

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}。