cuju-render 0.1.0__py3-none-any.whl

cuju/render/web/js/players/clips.js

@@ -0,0 +1,224 @@
+// Copyright 2026 The cuju Authors
+// SPDX-License-Identifier: Apache-2.0
+
+// The celebration clips that a team uploads, binary glTF files with a skinned skeleton and one or
+// more animations. Each animation is read at 30 frames a second on a rig of the clip's own
+// skeleton, with the joint mapping that a custom model uses, and turned into GRF's nodes by
+// retarget.js, so it plays on GRF's player and on any model as the procedural moves do.
+//
+// A team's style names an animation by the prefix upload, the clip's name and the animation's
+// index, as PREFIX below shows. Two teams may hold clips of the same name, so while a match plays
+// the names of each team's style carry the tag of that team as well, after a space.
+
+import * as THREE from 'three';
+import { api } from '../core/api.js';
+import { Rig, fileBoneNames, guessJoints, parseModel } from './players.js';
+import {
+    FPS, MAX_SECONDS, REST_BODY_HEIGHT, forgetUploads, hasUpload, nodeClip, registerUpload,
+} from './retarget.js';
+import { t } from '../core/i18n.js';
+
+export const MAX_CLIP_BYTES = 10 * 1024 * 1024;
+export const MAX_TEAM_CLIP_BYTES = 40 * 1024 * 1024;
+export const MAX_CLIPS = 16;
+const PREFIX = 'upload:';
+// Windows opens a device for these names, the server refuses them as clip names.
+const DEVICES = /^(con|prn|aux|nul|com[0-9]|lpt[0-9])$/;
+
+export function isUploadName(name) {
+    return typeof name === 'string' && name.startsWith(PREFIX);
+}
+
+// The name of a clip made from the name of its file, lower case letters, digits and underscores.
+export function clipNameOf(filename) {
+    let name = String(filename || '').replace(/\.glb$/i, '').toLowerCase()
+        .replace(/[^a-z0-9_]+/g, '_').replace(/^_+|_+$/g, '').slice(0, 40);
+    if (!name || DEVICES.test(name)) {
+        name = `clip_${name}`.replace(/_+$/, '').slice(0, 40) || 'clip';
+    }
+    return name;
+}
+
+// The celebrations a team's clips offer, each its name in a style and the animation's name.
+export function uploadMoves(team) {
+    const clips = team && Array.isArray(team.clips) ? team.clips : [];
+    return clips.flatMap((c) => (c.animations || []).map((label, i) => [`${PREFIX}${c.name}.${i}`, label, c.name]));
+}
+
+// The animation's name of a celebration that names a team's clip, or null.
+export function uploadMoveLabel(team, value) {
+    const found = uploadMoves(team).find(([v]) => v === value);
+    return found ? found[1] : null;
+}
+
+// Checks the bytes of a clip as the server will, and reads it. Returns the parsed file, the names
+// of its skinned bones and the mapping guessed from them, or throws an error to show.
+export async function readClip(buffer) {
+    if (buffer.byteLength > MAX_CLIP_BYTES) {
+        throw new Error(t('clips.tooLarge', { size: Math.ceil(buffer.byteLength / 1048576) }));
+    }
+    const gltf = await parseModel(buffer);
+    const bones = fileBoneNames(gltf);
+    if (!gltf.animations || !gltf.animations.length) {
+        throw new Error(t('clips.noAnimation'));
+    }
+    return { gltf, bones, guess: guessJoints(bones) };
+}
+
+// Reads one animation of a parsed clip on the clip's own skeleton and returns a clip of nodes. The
+// rig of the skeleton may be given, so the animations of one file share it.
+export function retargetAnimation(gltf, animation, joints, rig = new Rig(gltf.scene, joints, {})) {
+    const corrections = new Array(14).fill(null);
+    const index = new Array(14).fill(-1);
+    rig.bones.forEach((b, j) => {
+        if (b.node > 0 && b.correction) {
+            corrections[b.node] = b.correction.toArray();
+            index[b.node] = j;
+        }
+    });
+    // The rig places the pelvis this high above the clip's floor at rest, in its own frame.
+    const floor = rig.bones[index[1]].position.y - rig.heightRatio * REST_BODY_HEIGHT;
+    const instance = rig.instantiate();
+    for (const b of instance.bones) {
+        if (b) {
+            b.matrixAutoUpdate = true;
+            b.matrixWorldAutoUpdate = true;
+        }
+    }
+    const mixer = new THREE.AnimationMixer(instance.root);
+    const action = mixer.clipAction(animation);
+    action.play();
+    const duration = Math.min(MAX_SECONDS, Math.max(0, animation.duration || 0));
+    const count = duration > 0 ? Math.max(2, Math.round(duration * FPS) + 1) : 1;
+    const matrix = new THREE.Matrix4();
+    const p = new THREE.Vector3();
+    const q = new THREE.Quaternion();
+    const s = new THREE.Vector3();
+    const samples = [];
+    try {
+        for (let i = 0; i < count; i++) {
+            const time = count > 1 ? (i / (count - 1)) * duration : 0;
+            action.time = Math.max(0, Math.min(time, (animation.duration || 0) - 1e-4));
+            mixer.update(0);
+            instance.root.updateMatrixWorld(true);
+            const bones = new Array(14).fill(null);
+            let body = [0, 0, 0];
+            for (let n = 1; n < 14; n++) {
+                const j = index[n];
+                const bone = j >= 0 ? instance.bones[j] : null;
+                if (!bone) {
+                    continue;
+                }
+                matrix.multiplyMatrices(rig.placement, bone.matrixWorld).decompose(p, q, s);
+                bones[n] = q.toArray();
+                if (n === 1) {
+                    body = p.toArray();
+                }
+            }
+            samples.push({ bones, body });
+        }
+    } finally {
+        mixer.stopAllAction();
+        mixer.uncacheRoot(instance.root);
+        rig.release(instance);
+    }
+    return nodeClip(samples, { corrections, heightRatio: rig.heightRatio, floor }, duration);
+}
+
+// The tag of each team whose clips the page loaded, so the names of two teams never meet.
+const tags = new Map();
+const loads = new Map();
+
+function tagOf(id) {
+    if (!tags.has(id)) {
+        tags.set(id, `c${tags.size + 1}`);
+    }
+    return tags.get(id);
+}
+
+// The name a celebration of a team plays under while its clips are loaded, the name itself for
+// every other move.
+export function qualify(value, tag) {
+    if (!tag || !isUploadName(value)) {
+        return value;
+    }
+    const name = `${value} ${tag}`;
+    return hasUpload(name) ? name : value;
+}
+
+// The name in a style of a celebration that plays under a tagged name.
+export function unqualify(name) {
+    return isUploadName(name) ? name.replace(/ c\d+$/, '') : name;
+}
+
+// Gives the celebrations of a style the names their loaded clips play under, in place.
+export function qualifyStyle(style, tag) {
+    if (!style || !tag) {
+        return style;
+    }
+    if (Array.isArray(style.celebrations)) {
+        style.celebrations = style.celebrations.map((v) => qualify(v, tag));
+    }
+    for (const p of Array.isArray(style.players) ? style.players : []) {
+        if (p && typeof p.celebration === 'string') {
+            p.celebration = qualify(p.celebration, tag);
+        }
+    }
+    return style;
+}
+
+// Loads the clips of a registry team and returns the team's tag, or null when it holds none.
+// The clips load once while they stay the same, and a clip that fails is left out quietly, so its
+// celebrations give way to the procedural moves.
+export async function loadTeamClips(team) {
+    if (!team || !team.id || !Array.isArray(team.clips) || !team.clips.length) {
+        if (team && team.id && tags.has(team.id)) {
+            forgetUploads(` ${tags.get(team.id)}`);
+            loads.delete(team.id);
+        }
+        return null;
+    }
+    const tag = tagOf(team.id);
+    const signature = JSON.stringify(team.clips);
+    const cached = loads.get(team.id);
+    if (cached && cached.signature === signature) {
+        await cached.promise;
+        return tag;
+    }
+    const entry = { signature, promise: null };
+    loads.set(team.id, entry);
+    entry.promise = (async () => {
+        const made = [];
+        for (const clip of team.clips) {
+            try {
+                const buffer = await api.clipBytes(team.id, clip.name);
+                const { gltf, guess } = await readClip(buffer);
+                const joints = clip.joints && clip.joints.body ? clip.joints : guess;
+                if (!joints.body) {
+                    console.warn('clip without a pelvis left out', clip.name);
+                    continue;
+                }
+                const rig = new Rig(gltf.scene, joints, {});
+                gltf.animations.forEach((animation, i) => {
+                    try {
+                        const label = (clip.animations && clip.animations[i]) || animation.name || t('clips.animation', { n: i + 1 });
+                        made.push([`${PREFIX}${clip.name}.${i} ${tag}`, retargetAnimation(gltf, animation, joints, rig), label]);
+                    } catch (err) {
+                        console.warn('clip animation left out', clip.name, i, err);
+                    }
+                });
+            } catch (err) {
+                console.warn('clip left out', clip.name, err);
+            }
+        }
+        // Only the newest load of a team registers its clips.
+        if (loads.get(team.id) === entry) {
+            forgetUploads(` ${tag}`);
+            for (const [name, nodes, label] of made) {
+                registerUpload(name, nodes, label);
+            }
+        }
+    })();
+    await entry.promise;
+    return tag;
+}

cuju/render/web/js/players/kaykit.js

@@ -0,0 +1,162 @@
+// Copyright 2026 The cuju Authors
+// SPDX-License-Identifier: Apache-2.0
+
+// The animation clips of Kay Lousberg's KayKit Character Animations, made for Rig_Medium, the
+// rig that every shipped KayKit character shares. The files load once, the first time a model on
+// that rig is used, and their clips join every such rig, so a player plays them by name.
+
+import * as THREE from 'three';
+import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
+import { t } from '../core/i18n.js';
+
+const PACKS = ['general', 'movementbasic', 'movementadvanced', 'simulation', 'special', 'combatmelee'];
+const URL_OF = (pack) => `assets/animations/kaykit-rig-medium-${pack}.glb`;
+
+// Clips with nothing to show on a football pitch, or that only reset the rig.
+const SKIPPED = /^(T-Pose|EXPERIMENTAL_.*)$/;
+
+// Bones every model on Rig_Medium carries, how a rig of the family is told apart.
+const FAMILY_BONES = ['root', 'hips', 'spine', 'chest', 'head', 'upperarml', 'upperarmr', 'upperlegl', 'upperlegr'];
+
+let library = null;
+
+// Every clip of the packs that loaded, a pack that fails is left out quietly.
+export function kaykitClips() {
+    if (!library) {
+        library = Promise.all(PACKS.map(async (pack) => {
+            try {
+                const gltf = await new GLTFLoader().loadAsync(URL_OF(pack));
+                return (gltf.animations || []).filter((c) => c && c.name && !SKIPPED.test(c.name));
+            } catch {
+                return [];
+            }
+        })).then((lists) => {
+            const seen = new Set();
+            const out = [];
+            for (const clip of lists.flat()) {
+                if (!seen.has(clip.name)) {
+                    seen.add(clip.name);
+                    out.push(clip);
+                }
+            }
+            return out;
+        });
+    }
+    return library;
+}
+
+// The names of the objects of a scene, as GLTFLoader leaves them.
+function namesOf(scene) {
+    const names = new Set();
+    scene.traverse((obj) => {
+        if (obj.name) {
+            names.add(obj.name);
+        }
+    });
+    return names;
+}
+
+// Whether a scene is a model on Rig_Medium.
+export function isKayKitScene(scene) {
+    if (!scene) {
+        return false;
+    }
+    const names = namesOf(scene);
+    return names.has('Rig_Medium') || FAMILY_BONES.every((n) => names.has(n));
+}
+
+// Adds the KayKit clips to a rig on Rig_Medium, each cut down to the tracks of bones the model
+// has, so a model without hand slots binds every track it keeps. A clip the model's own file
+// carries under the same name stays. Resolves to the rig, with or without the clips.
+export async function attachKayKitClips(rig) {
+    if (!rig || !rig.scene || !Array.isArray(rig.clips) || rig.kaykit || !isKayKitScene(rig.scene)) {
+        return rig;
+    }
+    rig.kaykit = true;
+    try {
+        const clips = await kaykitClips();
+        const names = namesOf(rig.scene);
+        const own = new Set(rig.clips.map((c) => c.name));
+        for (const clip of clips) {
+            if (own.has(clip.name)) {
+                continue;
+            }
+            const tracks = clip.tracks.filter((track) => {
+                const node = THREE.PropertyBinding.parseTrackName(track.name).nodeName;
+                return names.has(node);
+            });
+            if (tracks.length) {
+                rig.clips.push(new THREE.AnimationClip(clip.name, clip.duration, tracks));
+            }
+        }
+    } catch {
+        // The procedural moves stand in for any clip that did not load.
+    }
+    return rig;
+}
+
+// Clips for each role on a KayKit model, the first one the model has wins. A name with a greater
+// than sign plays its first clip once and then loops the second.
+export const KAYKIT_ROLES = {
+    celebrate: ['clip:Cheering', 'clip:Jump_Full_Long', 'clip:Skeletons_Taunt_Longer', 'clip:Jump_Full_Short', 'clip:Waving', 'clip:Push_Ups'],
+    jump: ['clip:Jump_Full_Short', 'clip:Jump_Full_Long', 'clip:Cheering'],
+    cheer: ['clip:Cheering', 'clip:Jump_Full_Short'],
+    taunt: ['clip:Skeletons_Taunt_Longer', 'clip:Skeletons_Taunt', 'clip:Cheering'],
+    showoff: ['clip:Push_Ups', 'clip:Skeletons_Taunt'],
+    wave: ['clip:Waving', 'clip:Cheering'],
+    huddle: ['clip:Cheering', 'clip:Idle_B'],
+    idle: ['clip:Idle_A', 'clip:Idle_B'],
+    calm: ['clip:Idle_B', 'clip:Idle_A'],
+    dejected: ['clip:Sit_Floor_Down>Sit_Floor_Idle', 'clip:Crouching', 'clip:Idle_B'],
+    crouch: ['clip:Crouching', 'clip:Idle_B'],
+    floored: ['clip:Lie_Down>Lie_Idle', 'clip:Sit_Floor_Down>Sit_Floor_Idle'],
+    handshake: ['clip:Interact', 'clip:Idle_A'],
+    punch: ['clip:Melee_Unarmed_Attack_Punch_A', 'clip:Cheering'],
+    kick: ['clip:Melee_Unarmed_Attack_Kick', 'clip:Cheering'],
+};
+
+// The celebrations a KayKit scorer picks from when his team leaves the choice open, with the
+// air punch and the kick of the combat pack for a little more swagger.
+export const KAYKIT_CELEBRATIONS = [
+    'clip:Cheering', 'clip:Jump_Full_Long', 'clip:Skeletons_Taunt_Longer', 'clip:Push_Ups', 'clip:Waving',
+    'clip:Jump_Full_Short', 'clip:Melee_Unarmed_Attack_Punch_A', 'clip:Skeletons_Taunt',
+];
+
+// The KayKit clips the team editor offers as celebrations, with their names in the editor.
+export const KAYKIT_MENU = [
+    ['Cheering', t('kaykit.cheering')],
+    ['Waving', t('kaykit.waving')],
+    ['Jump_Full_Short', t('kaykit.jump')],
+    ['Jump_Full_Long', t('kaykit.big_jump')],
+    ['Skeletons_Taunt', t('kaykit.taunt')],
+    ['Skeletons_Taunt_Longer', t('kaykit.long_taunt')],
+    ['Push_Ups', t('kaykit.push_ups')],
+    ['Sit_Ups', t('kaykit.sit_ups')],
+    ['Melee_Unarmed_Attack_Punch_A', t('kaykit.air_punch')],
+    ['Melee_Unarmed_Attack_Kick', t('kaykit.air_kick')],
+    ['Dodge_Forward', t('kaykit.forward_roll')],
+    ['Sit_Floor_Down>Sit_Floor_Idle', t('kaykit.sit')],
+    ['Lie_Down>Lie_Idle', t('kaykit.lie')],
+    ['Idle_B', t('kaykit.stand_cool')],
+];
+
+const LABELS = new Map(KAYKIT_MENU);
+
+// The editor's name of a KayKit clip, or null for another name.
+export function kaykitLabel(name) {
+    return LABELS.get(String(name || '').replace(/^clip:/, '')) || null;
+}
+
+// The clips the editor lists for a rig, by name without the clip prefix. A KayKit rig lists the
+// menu above, then the clips of its own file, any other rig every clip it has.
+export function menuClips(rig) {
+    if (!rig || !Array.isArray(rig.clips)) {
+        return [];
+    }
+    if (!rig.kaykit) {
+        return rig.clips.map((c) => c.name);
+    }
+    const has = (name) => name.split('>').every((part) => rig.clips.some((c) => c.name === part));
+    const own = ((rig.options && rig.options.animations) || []).map((c) => c && c.name).filter(Boolean);
+    return [...KAYKIT_MENU.map(([name]) => name).filter(has), ...own.filter((n) => !LABELS.has(n))];
+}