@pmndrs/viverse 0.1.2

package/dist/simple-character.js

@@ -0,0 +1,329 @@
+import { VRM, VRMUtils } from '@pixiv/three-vrm';
+import { action, animationFinished, build, timePassed, forever, parallel, graph, } from '@pmndrs/timeline';
+import { AnimationMixer, Euler, Group, LoopOnce, Quaternion, Vector3, } from 'three';
+import { simpleCharacterAnimationNames, getSimpleCharacterModelAnimationOptions as getSimpleCharacterModelAnimationOptions, loadCharacterModelAnimation as loadCharacterModelAnimation, } from './animation/index.js';
+import { SimpleCharacterCameraBehavior } from './camera.js';
+import { InputSystem, LocomotionKeyboardInput, MoveBackwardField, MoveForwardField, MoveLeftField, MoveRightField, PointerCaptureInput, RunField, LastTimeJumpPressedField, } from './input/index.js';
+import { clearCharacterModelCache, loadCharacterModel } from './model/index.js';
+import { BvhCharacterPhysics } from './physics/index.js';
+const DefaultCrossFadeDuration = 0.1;
+const DefaultJumDelay = 0.2;
+//constants
+const NegZAxis = new Vector3(0, 0, -1);
+const _2MathPI = 2 * Math.PI;
+//helper objects
+const cameraEuler = new Euler();
+const cameraRotation = new Quaternion();
+const vector = new Vector3();
+const characterTargetEuler = new Euler();
+const goalTargetEuler = new Euler();
+const inputDirection = new Vector3();
+const quaternion = new Quaternion();
+export async function preloadSimpleCharacterAssets(options) {
+    // load model
+    const model = await loadCharacterModel(options.model);
+    if (model == null) {
+        return {};
+    }
+    model.scene.addEventListener('dispose', () => clearCharacterModelCache(options.model));
+    // load animations
+    return {
+        model,
+        animations: (await Promise.all(simpleCharacterAnimationNames.map(async (name) => loadCharacterModelAnimation(model, options.animation?.[name] ?? (await getSimpleCharacterModelAnimationOptions(name)))))).reduce((prev, animation, i) => {
+            prev[simpleCharacterAnimationNames[i]] = animation;
+            return prev;
+        }, {}),
+    };
+}
+async function* SimpleCharacterTimeline(camera, character) {
+    let lastJump = 0;
+    function shouldJump() {
+        let jumpOptions = character.options.movement?.jump;
+        if (jumpOptions === false) {
+            return false;
+        }
+        if (jumpOptions === true) {
+            jumpOptions = {};
+        }
+        if (!character.physics.isGrounded) {
+            return false;
+        }
+        const lastTimePressed = character.inputSystem.get(LastTimeJumpPressedField);
+        if (lastTimePressed == null) {
+            return false;
+        }
+        if (lastJump > lastTimePressed) {
+            return false;
+        }
+        return performance.now() / 1000 - lastTimePressed < (jumpOptions?.bufferTime ?? 0.1);
+    }
+    function applyJumpForce() {
+        character.physics.applyVelocity(vector.set(0, (typeof character.options.movement?.jump === 'object' ? character.options.movement?.jump.speed : undefined) ??
+            8, 0));
+    }
+    const model = character.model;
+    const actions = character.actions;
+    //run character
+    yield* parallel('all', 
+    // character movement
+    action({
+        update() {
+            cameraEuler.setFromQuaternion(camera.getWorldQuaternion(cameraRotation), 'YXZ');
+            cameraEuler.x = 0;
+            cameraEuler.z = 0;
+            let inputSpeed = 0;
+            let runOptions = character.options.movement?.run ?? true;
+            if (character.inputSystem.get(RunField) && runOptions !== false) {
+                runOptions = runOptions === true ? {} : runOptions;
+                inputSpeed = runOptions.speed ?? 6;
+            }
+            let walkOptions = character.options.movement?.walk ?? true;
+            if (inputSpeed === 0 && walkOptions !== false) {
+                walkOptions = walkOptions === true ? {} : walkOptions;
+                inputSpeed = walkOptions.speed ?? 3;
+            }
+            character.physics.inputVelocity
+                .set(-character.inputSystem.get(MoveLeftField) + character.inputSystem.get(MoveRightField), 0, -character.inputSystem.get(MoveForwardField) + character.inputSystem.get(MoveBackwardField))
+                .normalize()
+                .applyEuler(cameraEuler)
+                .multiplyScalar(inputSpeed);
+            //run forever
+            return true;
+        },
+    }), 
+    // rotation animations
+    model != null &&
+        action({
+            update(_, clock) {
+                // Character yaw rotation logic
+                const basedOn = character.options.animation?.yawRotationBasdOn ?? 'movement';
+                // compute goalTargetEuler
+                if (basedOn === 'camera') {
+                    goalTargetEuler.setFromQuaternion(camera.getWorldQuaternion(quaternion), 'YXZ');
+                }
+                else {
+                    //don't rotate if not moving
+                    if (character.physics.inputVelocity.lengthSq() === 0) {
+                        // run forever
+                        return true;
+                    }
+                    inputDirection.copy(character.physics.inputVelocity).normalize();
+                    quaternion.setFromUnitVectors(NegZAxis, inputDirection);
+                    goalTargetEuler.setFromQuaternion(quaternion, 'YXZ');
+                }
+                // compute currentTargetEuler
+                model.scene.getWorldQuaternion(quaternion);
+                characterTargetEuler.setFromQuaternion(quaternion, 'YXZ');
+                // apply delta yaw rotation
+                let deltaYaw = (goalTargetEuler.y - characterTargetEuler.y + _2MathPI) % _2MathPI;
+                if (deltaYaw > Math.PI) {
+                    deltaYaw = deltaYaw - _2MathPI;
+                }
+                const absDeltaYaw = Math.abs(deltaYaw);
+                if (absDeltaYaw < 0.001) {
+                    // run forever
+                    return true;
+                }
+                const yawRotationDirection = deltaYaw / absDeltaYaw;
+                const maxYawRotationSpeed = (typeof character.options.animation === 'object'
+                    ? character.options.animation.maxYawRotationSpeed
+                    : undefined) ?? 10;
+                model.scene.rotation.y += Math.min(maxYawRotationSpeed * clock.delta, absDeltaYaw) * yawRotationDirection;
+                // run forever
+                return true;
+            },
+        }), 
+    // jump and walk animations
+    actions == null
+        ? action({
+            update: () => void (shouldJump() && applyJumpForce()),
+        })
+        : graph('moving', {
+            jumpStart: {
+                timeline: async function* () {
+                    yield* action({
+                        init() {
+                            actions.jumpUp.reset();
+                            actions.jumpUp.play();
+                            actions.jumpUp.paused = true;
+                            actions.jumpUp.fadeIn(character.options.animation?.crossFadeDuration ?? DefaultCrossFadeDuration);
+                            actions.jumpForward.reset();
+                            actions.jumpForward.play();
+                            actions.jumpForward.paused = true;
+                            actions.jumpForward.fadeIn(character.options.animation?.crossFadeDuration ?? DefaultCrossFadeDuration);
+                        },
+                        update: () => void character.physics.inputVelocity.multiplyScalar(DefaultCrossFadeDuration),
+                        until: timePassed((typeof character.options.movement?.jump === 'object'
+                            ? character.options.movement?.jump.delay
+                            : undefined) ?? DefaultJumDelay, 'seconds'),
+                    });
+                    if (character.inputSystem.get(RunField)) {
+                        actions.jumpUp.fadeOut(0.1);
+                        return 'jumpForward';
+                    }
+                    else {
+                        actions.jumpForward.fadeOut(0.1);
+                        return 'jumpUp';
+                    }
+                },
+                transitionTo: {
+                    jumpDown: { when: () => !character.physics.isGrounded },
+                },
+            },
+            jumpForward: {
+                timeline: async function* () {
+                    yield* action({
+                        init: () => {
+                            actions.jumpForward.paused = false;
+                            applyJumpForce();
+                        },
+                        cleanup: () => void actions.jumpForward.fadeOut(character.options.animation?.crossFadeDuration ?? DefaultCrossFadeDuration),
+                        until: animationFinished(actions.jumpForward),
+                    });
+                    if (character.physics.isGrounded) {
+                        return 'moving';
+                    }
+                    return 'jumpLoop';
+                },
+            },
+            jumpUp: {
+                timeline: () => action({
+                    init: () => {
+                        actions.jumpUp.paused = false;
+                        applyJumpForce();
+                    },
+                    cleanup: () => void actions.jumpUp.fadeOut(character.options.animation?.crossFadeDuration ?? DefaultCrossFadeDuration),
+                    until: animationFinished(actions.jumpUp),
+                }),
+                transitionTo: {
+                    jumpDown: {
+                        when: (_, clock) => clock.actionTime > 0.1 && character.physics.isGrounded,
+                    },
+                    finally: 'jumpLoop',
+                },
+            },
+            jumpLoop: {
+                timeline: () => action({
+                    init: () => {
+                        actions.jumpLoop.reset();
+                        actions.jumpLoop.play();
+                        actions.jumpLoop.fadeIn(character.options.animation?.crossFadeDuration ?? DefaultCrossFadeDuration);
+                    },
+                    cleanup: () => actions.jumpLoop.fadeOut(character.options.animation?.crossFadeDuration ?? DefaultCrossFadeDuration),
+                    until: forever(),
+                }),
+                transitionTo: {
+                    jumpDown: { when: () => character.physics.isGrounded },
+                },
+            },
+            jumpDown: {
+                timeline: () => action({
+                    init: () => {
+                        actions.jumpUp.fadeOut(character.options.animation?.crossFadeDuration ?? DefaultCrossFadeDuration);
+                        actions.jumpForward.fadeOut(character.options.animation?.crossFadeDuration ?? DefaultCrossFadeDuration);
+                        actions.jumpDown.reset();
+                        actions.jumpDown.play();
+                        actions.jumpDown.fadeIn(character.options.animation?.crossFadeDuration ?? DefaultCrossFadeDuration);
+                    },
+                    cleanup: () => actions.jumpDown.fadeOut(character.options.animation?.crossFadeDuration ?? DefaultCrossFadeDuration),
+                    until: timePassed(50, 'milliseconds'),
+                }),
+                transitionTo: { finally: 'moving' },
+            },
+            moving: {
+                timeline: () => {
+                    let currentAnimation;
+                    return action({
+                        update() {
+                            let nextAnimation;
+                            if (character.physics.inputVelocity.lengthSq() === 0) {
+                                nextAnimation = actions.idle;
+                            }
+                            else if (character.inputSystem.get(RunField) && character.options.movement?.run != false) {
+                                nextAnimation = actions.run;
+                            }
+                            else if (character.options.movement?.walk != false) {
+                                nextAnimation = actions.walk;
+                            }
+                            else {
+                                nextAnimation = actions.idle;
+                            }
+                            if (nextAnimation === currentAnimation) {
+                                return;
+                            }
+                            currentAnimation?.fadeOut(character.options.animation?.crossFadeDuration ?? DefaultCrossFadeDuration);
+                            nextAnimation.reset();
+                            nextAnimation.play();
+                            nextAnimation.fadeIn(character.options.animation?.crossFadeDuration ?? DefaultCrossFadeDuration);
+                            currentAnimation = nextAnimation;
+                        },
+                        cleanup: () => currentAnimation?.fadeOut(character.options.animation?.crossFadeDuration ?? DefaultCrossFadeDuration),
+                    });
+                },
+                transitionTo: {
+                    jumpStart: { when: () => shouldJump() },
+                    jumpLoop: { when: () => !character.physics.isGrounded },
+                },
+            },
+        }));
+}
+export class SimpleCharacter extends Group {
+    options;
+    cameraBehavior;
+    physics;
+    mixer = new AnimationMixer(this);
+    //can be changed from the outside
+    inputSystem;
+    //loaded asychronously
+    actions;
+    model;
+    updateTimeline;
+    constructor(camera, world, domElement, options = {}) {
+        super();
+        this.options = options;
+        // input system
+        this.inputSystem =
+            options.input instanceof InputSystem
+                ? options.input
+                : new InputSystem(domElement, options.input ?? [LocomotionKeyboardInput, PointerCaptureInput]);
+        options.physics ??= {};
+        // camera behavior
+        this.cameraBehavior = new SimpleCharacterCameraBehavior(camera, this, this.inputSystem, world.raycast.bind(world));
+        // physics
+        this.physics = new BvhCharacterPhysics(this, world);
+        this.init(camera, options).catch(console.error);
+    }
+    async init(camera, options) {
+        const { model, animations } = await preloadSimpleCharacterAssets(options);
+        this.model = model;
+        if (model != null && animations != null) {
+            this.add(model.scene);
+            this.actions = {};
+            for (const name of simpleCharacterAnimationNames) {
+                this.actions[name] = this.mixer.clipAction(animations[name]);
+            }
+            this.actions.jumpDown.loop = LoopOnce;
+            this.actions.jumpDown.clampWhenFinished = true;
+            this.actions.jumpUp.loop = LoopOnce;
+            this.actions.jumpUp.clampWhenFinished = true;
+            this.actions.jumpForward.loop = LoopOnce;
+            this.actions.jumpForward.clampWhenFinished = true;
+        }
+        this.updateTimeline = build(SimpleCharacterTimeline(camera, this));
+        this.dispatchEvent({ type: 'loaded' });
+    }
+    update(delta) {
+        this.updateTimeline?.(undefined, delta);
+        this.mixer?.update(delta);
+        if (this.model instanceof VRM) {
+            this.model.update(delta);
+        }
+        this.physics.update(delta, this.options.physics);
+        this.cameraBehavior.update(delta, this.options.cameraBehavior);
+    }
+    dispose() {
+        this.parent?.remove(this);
+        this.model?.scene.dispatchEvent({ type: 'dispose' });
+        VRMUtils.deepDispose(this);
+    }
+}

package/dist/utils.d.ts

@@ -0,0 +1,2 @@
+export declare function cached<D extends ReadonlyArray<unknown>, T>(fn: (...deps: D) => Promise<T>, dependencies: D): Promise<T>;
+export declare function clearCache(fn: Function, dependencies: Array<unknown>): void;

package/dist/utils.js

@@ -0,0 +1,34 @@
+function shallowEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++) {
+        if (a[i] !== b[i])
+            return false;
+    }
+    return true;
+}
+const cacheMap = new Map();
+export function cached(fn, dependencies) {
+    let cache = cacheMap.get(fn);
+    if (cache == null) {
+        cacheMap.set(fn, (cache = []));
+    }
+    const entry = cache.find(({ deps }) => shallowEqual(deps, dependencies));
+    if (entry != null) {
+        return entry.result;
+    }
+    const result = fn(...dependencies);
+    cache.push({ deps: dependencies, result });
+    return result;
+}
+export function clearCache(fn, dependencies) {
+    const cache = cacheMap.get(fn);
+    if (cache == null) {
+        return;
+    }
+    const index = cache.findIndex(({ deps }) => shallowEqual(deps, dependencies));
+    if (index === -1) {
+        return;
+    }
+    cache.splice(index, 1);
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@pmndrs/viverse",
+  "description": "Toolkit for building and publishing Threejs Apps to Viverse.",
+  "author": "Bela Bohlender",
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://github.com/pmndrs/viverse",
+  "keywords": [
+    "viverse",
+    "character controller",
+    "three.js",
+    "typescript",
+    "web game"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:pmndrs/viverse.git"
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "three": "*"
+  },
+  "version": "0.1.2",
+  "type": "module",
+  "dependencies": {
+    "@pixiv/three-vrm": "^3.4.2",
+    "@pixiv/three-vrm-animation": "^3.4.2",
+    "@pmndrs/timeline": "^0.1.10",
+    "@viverse/sdk": "1.2.10-alpha.0",
+    "three": "*",
+    "three-mesh-bvh": "^0.9.1"
+  },
+  "devDependencies": {
+    "ts-node": "^10.9.2",
+    "@types/node": "^24.0.14"
+  },
+  "main": "dist/index.js",
+  "scripts": {
+    "generate": "node --loader ts-node/esm scripts/build-assets.ts",
+    "build": "tsc -p tsconfig.build.json",
+    "check:prettier": "prettier --check src",
+    "check:eslint": "eslint \"src/**/*.{ts,tsx}\"",
+    "fix:prettier": "prettier --write src",
+    "fix:eslint": "eslint \"src/**/*.{ts,tsx}\" --fix"
+  }
+}