JavaScript Layers

概要

JavaScript は JavaScript Utility、JavaScript Shape、JavaScript Deformer、JavaScript Emitter、JavaScript Modifier、JavaScript Emitter など、さまざまな Layers で使用して、Cavalry の多くの Attribute タイプを設定できます。

式から書き込める主なデータ型は次のとおりです：

名前	attrType	説明
Double	double	小数桁を持つ数値。例: 4.153。
Double2	double2	2つの double のセット。例: Position 103.453, 487.543。
Double3	double3	3つの double のセット。例: Position (2.5D) 103.453, 487.543, 50.730。
Int	int	小数点のない整数。例: 4。
Int2	int2	2つの整数のセット。例: Composition Resolution 1920, 1080。
Bool	bool	2つの状態を持つチェックボックス — 1 または 0（オン/オフ）。
String	string	英数字と記号を含むことができます。
Color	color	R、G、B、A 値を含む Attribute。
Point Data	pointData	Distributions によって生成されたポイント。Using Point data を参照。
Asset	assetId	.json、.txt、.csv Asset を受け入れます。Using Assets を参照。
Layer	layerId	任意の Layer を受け入れます。Using Layer data を参照。

つまり、JavaScript をサポートする Layers は Cavalry の上記の任意のデータ型に接続できます。

互換性のない2つのデータ型を接続すると（例：式が int を返すが JavaScript が string に接続されている場合）、自動的にデータ型を変換しようとしますが、浮動小数点精度などの要素をより適切に制御するために、出力を正しくマッチングすることを強くお勧めします。

上記のすべての型は入力としても利用でき、スクリプト内で Attribute 名で参照できます。別の Attribute を変数として追加するには、UI 下部の + ボタンをクリックし、関連するデータ型を選択します。その後、一致するデータ型を持つ別の Attribute から入力接続を作成できます。デフォルトでは、変数名は文字 n の後に数字が続きます（例: n0, n1）。ただし、Attribute を右クリックして Rename を選択することで名前を変更できます。

変数名は大文字と小文字が区別され、スペースを含めてはいけません。

JavaScript は Context Module をインポートします。これには Duplicator で使用するいくつかの便利なメンバーが含まれています。

• ctx.index - Duplicator からの Index。
• ctx.count - Duplicator からの Count。
• ctx.positionX/ ctx.positionY - Duplicator ポイントの位置。
• ctx.layerId - JavaScript Layer に計算を要求した Layer の id。
• ctx.attributeId - JavaScript Layer に計算を要求した Attribute の id。

これらの値の使用例については、Create > Demo Scenes > JavaScript > Position to Color プリセットを参照してください。

複雑なデータ型（color、int2、double2）は、次のパターンに従うシンプルな JavaScript オブジェクトです：

let color = {    r: 200,    g: 100,    b: 50,    a: 255};let someDouble2 = {    x: 200.4,    y: 55.6};

簡単のために、入力値を変更または返すことができます。

この Layer で JavaScript 式を記述する主なルールは、値を返さなければならないことです。たとえば、次の式は値を返す関数を呼び出します：

function toCelsius(fahrenheit) {    return (5/9) * (fahrenheit-32);}toCelsius(n0);

グローバルレベルで変数を設定する場合は、let/const ではなく var を使用してください。JavaScript Layers は毎フレーム実行されるため、let/const をグローバルで使用すると、式が2回目に実行されるときに変数が既に存在し、再代入できないため失敗します。

Using Assets

JavaScript は JSON/Text/CSV Assets（CSV Asset には Google Sheets や Microsoft Excel が含まれます）を利用できます。これらの Asset タイプを JavaScript Layers で使用するには、+ ボタンをクリックし、Add Text/JSON/CSV Asset を選択します。これにより、サポートされている Asset を入力として受け取ることができる新しい Attribute が作成されます。

• Text Assets は文字列として読み込まれます。
• JSON Assets は JSON オブジェクトリテラルとして読み込まれます。
• CSV Assets は JSON オブジェクトリテラルとして読み込まれます。
  • トップレベルの Object プロパティはすべて列名と一致します。
  • 各列には以下が含まれます：
    • rows - 行データの配列（数値または文字列）。
    • min - 列内の最小数値（列が数値の場合）。
    • max - 列内の最大数値（列が数値の場合）。

// Attribute 'n1' に接続された CSV のすべての列名を出力します。var columns = Object.keys(n1);for (var columnName of columns) {    console.log(columnName);}

// Attribute 'n1' に接続された CSV/Google Sheet でタイトルが 'Cavalry' の列の最大値を返します。n1.Cavalry.max;// 列タイトルにスペースが含まれる場合、例: 'Cavalry Users'。n1["Cavalry Users"].min;

// Attribute 'n1' に接続された CSV/Google Sheet でタイトルが 'Cavalry Users' の列のすべての値の合計を返します。function setSum() {    let total = 0;    for (let row of n1["Cavalry Users"].rows) {        total += Number(row)    }    return total;}setSum();

// Attribute 'n1' に接続された JSON asset が与えられた場合、"title" キーの値を出力します。// JavaScript Utility を Text Shape の String に接続します。/* example.json の内容{    "data": {        "title": "My Title",        "body": "This is some body text."    }}*/n1.data.title

Asset として使用する場合、Excel ファイルの最初のタブのみがサポートされることに注意してください。

Using Point data

1. JavaScript Deformer を作成します。
2. Attribute Editor UI の下部にある + ボタンをクリックし、‘Add Point Data’ を選択して新しい Dynamic Attribute を追加します。
3. Duplicator を作成します。
4. Distribution Attribute を右クリックし、Reveal Generator を選択します。
5. Duplicator を削除します（Grid Distribution は残ります）。
6. gridDistribution.id→javaScriptDeformer.n1 を接続します（これは手順2で追加した新しい Point Data Attribute です）。
7. JavaScript 入力のコードを次のいずれかに置き換えます：
   • console.log(n1.points[0].position.x); または;
   • console.log(n1.points.length);
8. Shape を作成します。
9. javaScriptDeformer.id→shape.deformers を接続します。これは JavaScript Deformer が計算を行うために必要です。

プレイヘッドを次のフレームに進めて、値を JavaScript Console に出力します。最初の例は最初の pointId の position.x を出力し（[0] の値を変更して他の pointId を返します）、2番目の例は Distribution 内のポイント数を返します（デフォルトの 3x3 グリッドでは 9）。

Using Layer data

接続された Layer のタイプによって、利用可能なオブジェクトが決まります：

• Drawable（例: Null、Falloff）- 次の 2D World Space Transform 変数を持つ layer オブジェクトが利用可能になります：
  • position（例: n1.layer.position、n1.layer.position.x）
  • rotation（例: n1.layer.rotation、n1.layer.rotation.z）
  • scale（例: n1.layer.scale、n1.layer.scale.x）
• Shape（例: Rectangle、Duplicator）- mesh プロパティ（例: n1.mesh）が利用可能になり、ローカル空間のメッシュ階層を表します。mesh プロパティは Cavalry Module の Mesh class のインスタンスです。

Layer 動的入力を使用する場合、hasInput を使用して Layer が接続されているかどうかを判断します。たとえば、存在しないメッシュデータを読み取ろうとするのを防ぐためにこれを使用できます。

// 'n1' が Layer 動的入力であると仮定します。console.log(n1.hasInput);// Layer が 'n1' に接続されている場合は true を返します。

JavaScript は 2D と 2.5D Layers を区別しないため、2D Layers には rotation.z を使用します。

// Closest Point on Path の例。// これを JavaScript Editor に貼り付け、'Run Script' を押します。// Null と2つの Shapes を作成しますconst nullId = api.create("null", "Move Me!!");const ellipse1Id = api.primitive("ellipse", "Ellipse");const ellipse2Id = api.primitive("ellipse", "Path");api.setFill(ellipse2Id, false);api.setStroke(ellipse2Id, true);api.set(ellipse2Id, {"generator.radius": [350,350]});// JavaScript Utility を作成します。const jsUtil = api.create("javaScript");// 動的 Attributes と式を追加します。api.addDynamic(jsUtil, "array", "layerId");api.addDynamic(jsUtil, "array", "layerId");const expression = 'function getPoint() {\n\xa0\xa0\xa0\xa0let toPt = n2.layer.position;\n\xa0\xa0\xa0\xa0let closestPoint = n1.path.findClosestPoint(toPt.x, toPt.y);\n\xa0\xa0\xa0\xa0return closestPoint.position;\n};\ngetPoint();'api.set(jsUtil, {"expression": expression});// 接続を行います。api.connect(ellipse2Id, "id", jsUtil, "array.1");api.connect(nullId, "id", jsUtil, "array.2");api.connect(jsUtil, "id", ellipse1Id, "position");

Output dependent calculations

JavaScript Layers は、どの Layer と Attribute が計算をトリガーしたかを知ることができる Cavalry で唯一の場所です。この情報を使用して、どの接続が計算されているかに応じて異なる値を出力できます。ctx.layerId と ctx.attributeId プロパティを使用してこの情報にアクセスします。

// この例では、JSON Asset が JavaScript Layer の n1 Attribute に接続されていると仮定します。function getText() {    if (ctx.layerId == "textShape#1") {        // textShape#1 が JavaScript に値を要求している場合、指定された JSON 値を返します        return n1["colors"]["Green"];    } else if (ctx.layerId == "textShape#2") {        // textShape#2 が JavaScript に値を要求している場合、異なる JSON 値を返します        return n1["colors"]["Yellow"];    }    return "None";}getText();

式のエラーは JavaScript Console に出力されます。

Cmd/Ctrl + Return で式を実行する場合、式を実行するには出力接続が必要です。

See Scripting→ Example JavaScript Expressions→