playrig 0.0.0-stage → 0.1.0

package/editions/ae/library-starter/_common.jsx

@@ -0,0 +1,187 @@
+// Shared helpers appended to every recipe by `playrig ae lib run`. ES3 only.
+// Function declarations are hoisted, so recipes can call these from their first line,
+// and appending (not prepending) keeps recipe line numbers intact in error reports.
+
+// "#RRGGBB" or "#RGB" -> [r, g, b] in 0..1
+function libHex(h) {
+    var s = String(h).replace("#", ""), n;
+    if (s.length === 3) { s = s.charAt(0) + s.charAt(0) + s.charAt(1) + s.charAt(1) + s.charAt(2) + s.charAt(2); }
+    n = parseInt(s, 16);
+    if (isNaN(n) || s.length !== 6) { throw new Error("Bad colour \"" + h + "\" (use #RRGGBB)"); }
+    return [((n >> 16) & 255) / 255, ((n >> 8) & 255) / 255, (n & 255) / 255];
+}
+
+// Find the comp named `name` (error if several); create it if missing.
+function libComp(name, w, h, dur, fps) {
+    var found = [], i, it;
+    for (i = 1; i <= app.project.numItems; i++) {
+        it = app.project.item(i);
+        if (it instanceof CompItem && it.name === name) { found.push(it); }
+    }
+    if (found.length > 1) { throw new Error("Several comps are named \"" + name + "\""); }
+    if (found.length === 1) { return found[0]; }
+    return app.project.items.addComp(name, w, h, 1, dur, fps);
+}
+
+// First layer in `comp` called `name`, or null.
+function libLayer(comp, name) {
+    var i;
+    for (i = 1; i <= comp.numLayers; i++) { if (comp.layer(i).name === name) { return comp.layer(i); } }
+    return null;
+}
+
+function libRequireLayer(comp, name) {
+    var l = libLayer(comp, name);
+    if (!l) { throw new Error("No layer named \"" + name + "\" in comp \"" + comp.name + "\""); }
+    return l;
+}
+
+function libSolid(comp, name, hex, w, h) {
+    return comp.layers.addSolid(libHex(hex), name, w || comp.width, h || comp.height, 1, comp.duration);
+}
+
+// Number of temporal-ease objects a property needs (one per dimension; spatial props take one).
+function libEaseDims(prop) {
+    var t = prop.propertyValueType;
+    if (t === PropertyValueType.ThreeD) { return 3; }
+    if (t === PropertyValueType.TwoD) { return 2; }
+    return 1;
+}
+
+// Set temporal ease (influence %) on key `k`; speed 0 = classic ease. Pass inInfl/outInfl 0 to skip a side.
+function libEaseKey(prop, k, inInfl, outInfl) {
+    var d = libEaseDims(prop), a = [], b = [], i;
+    for (i = 0; i < d; i++) { a.push(new KeyframeEase(0, Math.max(0.1, inInfl || 16.667))); b.push(new KeyframeEase(0, Math.max(0.1, outInfl || 16.667))); }
+    prop.setTemporalEaseAtKey(k, a, b);
+}
+
+// Add a keyframe and ease it. Influence 16.7 ~ linear feel, 33 = easy ease, 60-85 = strong ease.
+function libKey(prop, time, value, inInfl, outInfl) {
+    prop.setValueAtTime(time, value);
+    var k = prop.nearestKeyIndex(time);
+    libEaseKey(prop, k, inInfl, outInfl);
+    return k;
+}
+
+// Frames -> seconds for a comp.
+function libFrames(comp, n) { return n / comp.frameRate; }
+
+// Split a "a|b|c" list param (or accept an array).
+function libList(v) {
+    var parts, out = [], i, s;
+    if (v instanceof Array) { return v; }
+    parts = String(v).split("|");
+    for (i = 0; i < parts.length; i++) { s = parts[i].replace(/^\s+|\s+$/g, ""); if (s.length) { out.push(s); } }
+    return out;
+}
+
+// Make sure the target comp exists with the recipe's size/duration/fps, then return it.
+// P.comp is the target; if it already exists it is used as is (so recipes can be layered into one comp).
+function libTargetComp() {
+    return libComp(P.comp, P.width || 1920, P.height || 1080, P.duration || 5, P.fps || 24);
+}
+
+// Add a text layer (point text) and style it; returns { layer, doc, prop }.
+function libText(comp, text, font, size, hex, tracking, justification) {
+    var layer = comp.layers.addText(text), prop = layer.property("ADBE Text Properties").property("ADBE Text Document"), doc = prop.value;
+    doc.resetCharStyle();
+    doc.fontSize = size;
+    doc.font = font;
+    doc.applyFill = true;
+    doc.fillColor = libHex(hex);
+    doc.applyStroke = false;
+    doc.tracking = tracking || 0;
+    doc.justification = justification || ParagraphJustification.CENTER_JUSTIFY;
+    prop.setValue(doc);
+    return { layer: layer, prop: prop, doc: doc };
+}
+
+// Add a text animator driven by an Expression Selector.
+//   basedOn: 1 = characters, 2 = characters excluding spaces, 3 = words, 4 = lines
+//   expr:    expression for the selector Amount (must return [v, v, v], 0..100)
+//   props:   { "ADBE Text Position 3D": [x, y, z], "ADBE Text Opacity": 0, ... } animator properties to add
+function libTextAnimator(layer, name, basedOn, expr, props) {
+    var a = layer.property("ADBE Text Properties").property("ADBE Text Animators").addProperty("ADBE Text Animator"), sels, sel, k;
+    a.name = name;
+    sels = a.property("ADBE Text Selectors");
+    while (sels.numProperties > 0) { sels.property(1).remove(); } // scripted animators may start with a default Range Selector
+    sel = sels.addProperty("ADBE Text Expressible Selector");
+    sel.property("ADBE Text Range Type2").setValue(basedOn);
+    sel.property("ADBE Text Expressible Amount").expression = expr;
+    for (k in props) { if (props.hasOwnProperty(k)) { a.property("ADBE Text Animator Properties").addProperty(k).setValue(props[k]); } }
+    return a;
+}
+
+// Bold (or otherwise re-font) the first occurrence of `word` inside a text layer. Returns true if applied.
+function libStyleWord(textProp, word, font) {
+    var doc = textProp.value, i = word ? doc.text.indexOf(word) : -1, r;
+    if (i < 0) { return false; }
+    r = doc.characterRange(i, i + word.length);
+    r.font = font; // r is a live view into doc
+    textProp.setValue(doc);
+    return true;
+}
+
+// ---------------------------------------------------------------------------------------------------------------
+// Recipe instances: every layer a recipe creates in its target comp is tagged (layer.comment = "aeb:<recipe>:<instance>")
+// so the same recipe can later replace ONLY its own layers in place (playrig ae lib run <id> --replace), keeping stacking order.
+// __AEB is injected by the CLI: { recipe, instance, replace }. __aebPre runs before the recipe, __aebPost after it.
+function __aebFindComp() {
+    var i, it;
+    for (i = 1; i <= app.project.numItems; i++) {
+        it = app.project.item(i);
+        if (it instanceof CompItem && it.name === P.comp) { return it; }
+    }
+    return null;
+}
+
+function __aebCount(comp, tag) {
+    var i, n = 0;
+    for (i = 1; i <= comp.numLayers; i++) { if (comp.layer(i).comment === tag) { n++; } }
+    return n;
+}
+
+function __aebPre() {
+    var A = __AEB, comp = __aebFindComp(), base = A.instance, i, l, victims = [], dependents = 0, top = 0, j, isVictim, n;
+    A.before = {};
+    A.above = null;
+    A.removed = 0;
+    if (!comp) { A.tag = "aeb:" + A.recipe + ":" + base; return; }
+    if (A.replace) {
+        A.tag = "aeb:" + A.recipe + ":" + base;
+        for (i = 1; i <= comp.numLayers; i++) {
+            if (comp.layer(i).comment === A.tag) { victims.push(comp.layer(i)); if (!top) { top = i; } }
+        }
+        if (!victims.length) { PLAYRIG.log("--replace: no layers from " + A.recipe + " (instance \"" + base + "\") in " + comp.name + "; building fresh"); }
+        else {
+            if (top > 1) { A.above = comp.layer(top - 1); }
+            for (i = 1; i <= comp.numLayers; i++) {   // layers from OTHER recipes parented to a victim will lose their parent
+                l = comp.layer(i); isVictim = false;
+                for (j = 0; j < victims.length; j++) { if (l.index === victims[j].index) { isVictim = true; } }
+                if (isVictim || !l.parent) { continue; }
+                for (j = 0; j < victims.length; j++) { if (l.parent.index === victims[j].index) { dependents++; break; } }
+            }
+            for (i = victims.length - 1; i >= 0; i--) { victims[i].remove(); }
+            A.removed = victims.length;
+            if (dependents) { PLAYRIG.log("note: " + dependents + " layer(s) from other recipes were parented to the replaced layers and are now unparented. If the replaced recipe is a rig/camera it re-parents them now; otherwise re-run that rig with --replace."); }
+        }
+    } else {
+        n = 1;
+        A.tag = "aeb:" + A.recipe + ":" + base;
+        while (__aebCount(comp, A.tag) > 0) { n++; A.tag = "aeb:" + A.recipe + ":" + base + "-" + n; }
+        if (n > 1) { PLAYRIG.log("note: " + comp.name + " already holds layers from " + A.recipe + "; this run is instance \"" + base + "-" + n + "\". Use --replace (with --instance " + base + ") to update the first set in place instead of adding another."); }
+    }
+    for (i = 1; i <= comp.numLayers; i++) { A.before[comp.layer(i).id] = true; }
+}
+
+function __aebPost() {
+    var A = __AEB, comp = __aebFindComp(), i, l, fresh = [], prev;
+    if (!comp) { return; }
+    for (i = 1; i <= comp.numLayers; i++) { l = comp.layer(i); if (!A.before[l.id]) { fresh.push(l); } }
+    for (i = 0; i < fresh.length; i++) { if (!fresh[i].comment) { fresh[i].comment = A.tag; } }
+    if (A.removed && A.above) {                     // put the replacement exactly where the old layers were
+        prev = A.above;
+        for (i = 0; i < fresh.length; i++) { fresh[i].moveAfter(prev); prev = fresh[i]; }
+    }
+    PLAYRIG.log("tagged " + fresh.length + " layer(s) as " + A.tag + (A.removed ? " (replaced " + A.removed + " in place)" : ""));
+}

package/editions/ae/library-starter/categories.json

@@ -0,0 +1,9 @@
+{
+  "background": "Full-frame backdrops: gradients, grids, textures.",
+  "type": "Text animation: headline reveals, typewriters, exits.",
+  "elements": "Shapes and UI elements: chips, stickers, panels, logos.",
+  "camera": "Camera moves and 3D rigs.",
+  "grade": "Colour treatments applied over a scene.",
+  "transition": "Ways of getting from one scene to the next.",
+  "structure": "Assembling scenes into a finished sequence (master comps, edits)."
+}

package/editions/ae/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "playrig-ae",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Playrig for After Effects: the ScriptUI panel, motion library and skills. Versioned on its own (tags ae-v*).",
+  "license": "SEE LICENSE IN LICENSE"
+}

package/editions/ae/panel/Playrig.jsx

@@ -0,0 +1,39 @@
+#targetengine "playrig"
+// Playrig for After Effects: stub. This is the only file in After Effects' ScriptUI Panels folder, so it is also the
+// panel's name in the Window menu. It stays tiny and stable, and loads the real panel (core.jsx) from the newest of:
+//   1. the user's data folder (<userData>/Playrig/ae/current), where verified updates are installed without admin rights
+//   2. "Playrig lib" next to this file, the copy that `playrig install ae` put there
+// If a newer copy fails to load, the bundled one is used. ES3 only.
+
+(function (thisObj) {
+    var G = $.global;
+    var STUB_API = 1; // a payload that needs a newer stub is ignored (see version.json "stubApi")
+    var here = new File($.fileName).parent.fsName;
+
+    function readVersion(dir) {
+        var f = new File(dir + "/version.json"), s, m, api;
+        if (!f.exists) { return null; }
+        try { f.encoding = "UTF-8"; f.open("r"); s = f.read(); f.close(); } catch (e) { return null; }
+        m = /"version"\s*:\s*"(\d+)\.(\d+)\.(\d+)/.exec(s);
+        api = /"stubApi"\s*:\s*(\d+)/.exec(s);
+        if (!m || (api && Number(api[1]) > STUB_API)) { return null; }
+        return [Number(m[1]), Number(m[2]), Number(m[3])];
+    }
+    function newer(a, b) { var i; for (i = 0; i < 3; i++) { if (a[i] !== b[i]) { return a[i] > b[i]; } } return false; }
+
+    var bundled = here + "/Playrig lib";
+    var user = Folder.userData.fsName + "/Playrig/ae/current";
+    var bv = readVersion(bundled), uv = readVersion(user), order = [], i, core;
+    if (uv && new File(user + "/core.jsx").exists && (!bv || newer(uv, bv))) { order.push(user); }
+    if (new File(bundled + "/core.jsx").exists) { order.push(bundled); }
+    if (!order.length) {
+        try { alert("Playrig is not installed correctly: \"Playrig lib\" is missing next to Playrig.jsx. Run: playrig install ae"); } catch (e0) { }
+        return;
+    }
+    for (i = 0; i < order.length; i++) {
+        core = new File(order[i] + "/core.jsx");
+        G.__PLAYRIG_PANEL = thisObj;
+        G.__PLAYRIG_HERE = order[i];
+        try { $.evalFile(core); return; } catch (e) { G.__PLAYRIG_LOAD_ERROR = String(e); }
+    }
+})(this);