脚本入门

简介

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