The VS Code of video editing, built for agents.
TypeScript
/* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
import { Cache, ChildOf, Computed, Name, Playback } from '../traits';
import { store } from '../world/store';
import { isStage, isScene } from './predicates';
// Direct module, not the utils barrel: utils/time reaches back into this file.
import { sortByItemIndex } from '../utils/sort';
import type { Entity, World, QueryParameter } from 'koota';
export function getParentEntity(entity: Entity | null | undefined): Entity | null {
if (!entity) return null;
return entity.targetFor(ChildOf) ?? null;
}
export function getEntityChildren(world: World, parent: Entity): Entity[] {
return [...world.query(ChildOf(parent))].sort(sortByItemIndex);
}
/**
* Parent node, or null when the parent is the stage (or missing).
* Use this wherever "top-level" matters; getParentEntity returns the raw
* parent including the stage.
*/
export function getParentNode(entity: Entity | null | undefined): Entity | null {
const parent = getParentEntity(entity);
if (parent === null || isStage(parent)) return null;
return parent;
}
const NO_CONTAINERS: Entity[] = [];
/**
* The `<clipPath>`s and `<mask>`s cutting `node`: its own, then the masks
* limiting its effects. The nodes under them are placed in `node`'s space and
* time, and each container carries `node`'s matrix and clock for them (see
* the transform and playback systems), so a walk that places a node's
* children places these too.
*/
export function getMaskContainers(world: World, node: Entity): Entity[] {
const cache = store(world, Cache);
const nid = node.id();
const clipPaths = cache.clipPaths[nid];
const masks = cache.masks[nid];
const effects = cache.effects[nid];
if (!clipPaths?.length && !masks?.length && !effects?.length) return NO_CONTAINERS;
const containers = [...clipPaths ?? [], ...masks ?? []];
for (const effect of effects ?? []) {
const limits = cache.masks[effect.id()];
if (limits?.length) containers.push(...limits);
}
return containers;
}
/**
* Nearest ancestor of `entity` (excluding `entity` itself) that is a scene, or null.
*/
export function getSceneAncestor(entity: Entity): Entity | null {
let current = getParentEntity(entity);
while (current !== null) {
if (isScene(current)) return current;
current = getParentEntity(current);
}
return null;
}
export function getSiblingEntities(world: World, entity: Entity, ...traits: QueryParameter[]): Entity[] {
const parent = getParentEntity(entity);
if (parent === null) return [];
return [...world.query(ChildOf(parent), ...traits)];
}
export function getEntityTree(world: World, root: Entity): Entity[] {
const tree: Entity[] = [];
const walk = (entity: Entity): Entity[] => {
tree.push(entity);
for (const child of world.query(ChildOf(entity))) {
walk(child);
}
return tree;
};
return walk(root);
}
/**
* Returns the local frame for a node in its own source/content time: the
* timeline frame relative to the node's origin, scaled by its playback rate.
* This matches `Computed.localTime` (the space keyframes are sampled
* in), so keyframes authored at any playback rate land on the right content
* frame.
*/
export function getNodeLocalFrame(node: Entity): number {
const computed = node.get(Computed);
const origin = computed?.origin ?? 0;
const playbackRate = computed?.playbackRate || 1;
let current: Entity | null = node;
while (current) {
const parent = getParentNode(current);
// must be a top-level playback entity
if (current.has(Playback) && parent === null) {
const currentTime = current.get(Computed)?.localTime ?? 0;
return Math.round((currentTime - origin) * playbackRate);
}
current = parent;
}
return 0;
}
export function getNextName(world: World, prefix: string): string {
let max = 0;
const pattern = new RegExp(`^${prefix.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')} (\\d+)$`);
for (const entity of world.query(Name)) {
const match = entity.get(Name)!.value.match(pattern);
if (match) {
const n = parseInt(match[1] ?? '0');
if (n > max) max = n;
}
}
return `${prefix} ${max + 1}`;
}