@react-three/viverse 0.2.1 → 0.2.2

package/README.md

@@ -61,9 +61,10 @@ Get started with **[building a simple game](https://pmndrs.github.io/viverse/tut
 - [Accessing avatar and profile](https://pmndrs.github.io/viverse/tutorials/access-avatar-and-profile)
 - [Equipping the character with items](https://pmndrs.github.io/viverse/tutorials/equipping-items)
 - [Using custom animations and models](https://pmndrs.github.io/viverse/tutorials/custom-models-and-animations)
+- [Actions](https://pmndrs.github.io/viverse/tutorials/actions)
+- [Custom Character Controller](https://pmndrs.github.io/viverse/tutorials/custom-character-controller)
 - [How to remove the viverse integrations](https://pmndrs.github.io/viverse/tutorials/remove-viverse-integrations)
 - [Publish to VIVERSE](https://pmndrs.github.io/viverse/tutorials/publish-to-viverse)
-- Building your own character controller - _Coming Soon_
 
 ## Not into react?
 

package/dist/gamepad.d.ts

@@ -1 +1 @@
-export declare function useXRControllerInput(): void;
+export declare function useXRControllerLocomotionActionBindings(): void;

package/dist/gamepad.js

@@ -2,10 +2,10 @@ import { JumpAction, MoveBackwardAction, MoveForwardAction, MoveLeftAction, Move
 import { useFrame } from '@react-three/fiber';
 import { useXRControllerButtonEvent, useXRInputSourceState } from '@react-three/xr';
 import { useEffect, useRef } from 'react';
-export function useXRControllerInput() {
+export function useXRControllerLocomotionActionBindings() {
     const leftController = useXRInputSourceState('controller', 'left');
     const rightController = useXRInputSourceState('controller', 'right');
-    useXRControllerButtonEvent(rightController, 'a-button', (state) => state === 'pressed' && JumpAction.emit());
+    useXRControllerButtonEvent(rightController, 'a-button', (state) => state === 'pressed' && JumpAction.emit(undefined));
     const forwardWriterRef = useRef(undefined);
     const backwardWriterRef = useRef(undefined);
     const leftWriterRef = useRef(undefined);

package/dist/index.d.ts

@@ -69,6 +69,8 @@ export declare function useViversePublicAvatarList(): Awaited<ReturnType<AvatarC
 export declare function useViversePublicAvatarByID(id: string): Awaited<ReturnType<AvatarClient['getPublicAvatarByID']>> | undefined;
 export * from './material.js';
 export * as Vanilla from '@pmndrs/viverse';
+export { EventAction, StateAction, BooleanOr, PointerLockRotateZoomActionBindings, KeyboardLocomotionActionBindings, updateSimpleCharacterVelocity, MoveRightAction, MoveLeftAction, MoveForwardAction, MoveBackwardAction, RunAction, JumpAction, ZoomAction, RotateYawAction, RotatePitchAction, shouldJump, lowerBody, upperBody, WalkAnimationUrl, RunAnimationUrl, IdleAnimationUrl, JumpUpAnimationUrl, JumpLoopAnimationUrl, JumpDownAnimationUrl, FirstPersonCharacterCameraBehavior, BvhCharacterPhysics, type BvhCharacterPhysicsOptions, BvhPhysicsWorld, bvhBoneMap, CharacterCameraBehavior, } from '@pmndrs/viverse';
+export type { VRMHumanBoneName } from '@pmndrs/viverse';
 export * from '@viverse/sdk';
 export * from '@viverse/sdk/avatar-client';
 export * from './gamepad.js';

package/dist/index.js

@@ -154,6 +154,8 @@ export function useViversePublicAvatarByID(id) {
 }
 export * from './material.js';
 export * as Vanilla from '@pmndrs/viverse';
+// Direct re-exports from @pmndrs/viverse used in examples and docs
+export { EventAction, StateAction, BooleanOr, PointerLockRotateZoomActionBindings, KeyboardLocomotionActionBindings, updateSimpleCharacterVelocity, MoveRightAction, MoveLeftAction, MoveForwardAction, MoveBackwardAction, RunAction, JumpAction, ZoomAction, RotateYawAction, RotatePitchAction, shouldJump, lowerBody, upperBody, WalkAnimationUrl, RunAnimationUrl, IdleAnimationUrl, JumpUpAnimationUrl, JumpLoopAnimationUrl, JumpDownAnimationUrl, FirstPersonCharacterCameraBehavior, BvhCharacterPhysics, BvhPhysicsWorld, bvhBoneMap, CharacterCameraBehavior, } from '@pmndrs/viverse';
 export * from '@viverse/sdk';
 export * from '@viverse/sdk/avatar-client';
 export * from './gamepad.js';

package/dist/simple.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-import { RunAction, shouldJump, updateSimpleCharacterInputVelocity, updateSimpleCharacterRotation, } from '@pmndrs/viverse';
+import { RunAction, shouldJump, updateSimpleCharacterVelocity, updateSimpleCharacterRotation, } from '@pmndrs/viverse';
 import { IdleAnimationUrl, JumpDownAnimationUrl, JumpForwardAnimationUrl, JumpLoopAnimationUrl, JumpUpAnimationUrl, RunAnimationUrl, WalkAnimationUrl, } from '@pmndrs/viverse/src/animation/default.js';
 import { useFrame } from '@react-three/fiber';
 import { Graph, GrapthState, Parallel, RunTimeline, Switch, SwitchCase, timePassed } from '@react-three/timeline';
@@ -9,14 +9,14 @@ import { CharacterAnimationAction } from './animation.js';
 import { useViverseActiveAvatar } from './index.js';
 import { CharacterModelProvider } from './model.js';
 import { useBvhCharacterPhysics } from './physics.js';
-import { useCharacterCameraBehavior, useCharacterModelLoader, useSimpleCharacterInputs } from './utils.js';
-export const SimpleCharacter = forwardRef(({ input, inputOptions, cameraBehavior, children, movement, physics: physicsOptions, model, useViverseAvatar, animation, ...props }, ref) => {
-    useSimpleCharacterInputs(input, inputOptions);
+import { useCharacterCameraBehavior, useCharacterModelLoader, useSimpleCharacterActionBindings } from './utils.js';
+export const SimpleCharacter = forwardRef(({ input, actionBindings, inputOptions, actionBindingOptions, cameraBehavior, children, movement, physics: physicsOptions, model, useViverseAvatar, animation, ...props }, ref) => {
+    useSimpleCharacterActionBindings(actionBindings ?? input, actionBindingOptions ?? inputOptions);
     const internalRef = useRef(null);
     useCharacterCameraBehavior(internalRef, cameraBehavior);
     const physics = useBvhCharacterPhysics(internalRef, physicsOptions);
     const lastJumpTimeRef = useRef(-Infinity);
-    useFrame((state) => updateSimpleCharacterInputVelocity(state.camera, physics, movement));
+    useFrame((state) => updateSimpleCharacterVelocity(state.camera, physics, movement));
     useFrame(() => {
         if (model != false || movement?.jump === false) {
             return;

package/dist/utils.d.ts

@@ -1,14 +1,46 @@
-import { CharacterCameraBehavior, CharacterAnimationOptions, CharacterModelOptions, SimpleCharacterCameraBehaviorOptions, CharacterModel, SimpleCharacterInputOptions } from '@pmndrs/viverse';
+import { CharacterCameraBehavior, CharacterAnimationOptions, CharacterModelOptions, CharacterCameraBehaviorOptions, CharacterModel, SimpleCharacterActionBindingOptions, WriteonlyEventAction, StateAction } from '@pmndrs/viverse';
 import { RefObject } from 'react';
 import { Object3D } from 'three';
-export declare function useCharacterCameraBehavior(model: Object3D | RefObject<Object3D | null>, options?: SimpleCharacterCameraBehaviorOptions): RefObject<CharacterCameraBehavior | undefined>;
-export declare function useCharacterModelLoader(options?: CharacterModelOptions): CharacterModel;
+export declare function useCharacterCameraBehavior(model: Object3D | RefObject<Object3D | null>, options?: CharacterCameraBehaviorOptions): RefObject<CharacterCameraBehavior | undefined>;
+export declare function useCharacterModelLoader({ useViverseAvatar, ...modelOptions }?: CharacterModelOptions & {
+    useViverseAvatar?: boolean;
+}): CharacterModel;
 export declare function useCharacterAnimationLoader(model: CharacterModel, options: CharacterAnimationOptions): import("three").AnimationClip;
 /**
- * @deprecated use inputs directly
+ * @deprecated use the specific action binding hooks directly
  */
-export declare function useSimpleCharacterInputs(inputsClasses?: ReadonlyArray<{
-    new (domElement: HTMLElement): {
-        dispose(): void;
-    };
-}>, options?: SimpleCharacterInputOptions): void;
+export declare function useSimpleCharacterActionBindings(actionBindingsClasses?: ReadonlyArray<{
+    new (domElement: HTMLElement, abortSignal: AbortSignal): unknown;
+}>, options?: SimpleCharacterActionBindingOptions): void;
+export declare function useKeyboardActionBinding(action: WriteonlyEventAction<KeyboardEvent> | StateAction<boolean>, options: {
+    keys: Array<string>;
+    requiresPointerLock?: boolean;
+}): void;
+export declare function usePointerButtonActionBinding(action: WriteonlyEventAction<PointerEvent> | StateAction<boolean>, options: {
+    domElement?: HTMLElement | RefObject<HTMLElement | null>;
+    buttons?: Array<number>;
+    requiresPointerLock?: boolean;
+}): void;
+export declare function usePointerCaptureRotateZoomActionBindings(options?: {
+    rotationSpeed?: number;
+    zoomSpeed?: number;
+}): void;
+export declare function usePointerLockRotateZoomActionBindings(options?: {
+    rotationSpeed?: number;
+    zoomSpeed?: number;
+    lockOnClick?: boolean;
+}): void;
+export declare function useKeyboardLocomotionActionBindings(options?: {
+    moveForwardKeys?: Array<string>;
+    moveBackwardKeys?: Array<string>;
+    moveLeftKeys?: Array<string>;
+    moveRightKeys?: Array<string>;
+    runKeys?: Array<string>;
+    jumpKeys?: Array<string>;
+    requiresPointerLock?: boolean;
+}): void;
+export declare function useScreenButton(image: string): HTMLElement;
+export declare function useScreenJoystickLocomotionActionBindings(options?: {
+    runDistancePx?: number;
+    deadZonePx?: number;
+}): void;

package/dist/utils.js

@@ -1,9 +1,10 @@
 import { VRM } from '@pixiv/three-vrm';
-import { CharacterCameraBehavior, flattenCharacterAnimationOptions, flattenCharacterModelOptions, loadCharacterModel, loadCharacterAnimation, ScreenJoystickInput, ScreenJumpButtonInput, PointerCaptureInput, LocomotionKeyboardInput, applySimpleCharacterInputOptions, } from '@pmndrs/viverse';
+import { CharacterCameraBehavior, flattenCharacterAnimationOptions, flattenCharacterModelOptions, loadCharacterModel, loadCharacterAnimation, ScreenJoystickLocomotionActionBindings, ScreenButtonJumpActionBindings, PointerCaptureRotateZoomActionBindings, KeyboardLocomotionActionBindings, applySimpleCharacterActionBindingOptions, KeyboardActionBinding, PointerButtonActionBinding, defaultScreenButtonStyles, PointerLockRotateZoomActionBindings, DefaultMoveBackwardKeys, DefaultMoveForwardKeys, DefaultJumpKeys, DefaultMoveLeftKeys, DefaultMoveRightKeys, DefaultRunKeys, } from '@pmndrs/viverse';
 import { useFrame, useThree } from '@react-three/fiber';
 import { useEffect, useMemo, useRef } from 'react';
 import { suspend } from 'suspend-react';
 import { Object3D } from 'three';
+import { useViverseActiveAvatar } from './index.js';
 import { useBvhPhysicsWorld } from './physics.js';
 export function useCharacterCameraBehavior(model, options) {
     const behaviorRef = useRef(undefined);
@@ -23,12 +24,22 @@ export function useCharacterCameraBehavior(model, options) {
             return;
         }
         behaviorRef.current?.update(state.camera, resolvedModel, delta, raycast, options);
-    });
+    }, -1);
     return behaviorRef;
 }
 const loadCharacterModelSymbol = Symbol('loadCharacterModel');
-export function useCharacterModelLoader(options) {
-    const model = suspend((_, ...params) => loadCharacterModel(...params), [loadCharacterModelSymbol, ...flattenCharacterModelOptions(options)]);
+export function useCharacterModelLoader({ useViverseAvatar = true, ...modelOptions } = {}) {
+    const avatar = useViverseActiveAvatar();
+    const model = suspend((_, ...params) => loadCharacterModel(...params), [
+        loadCharacterModelSymbol,
+        ...flattenCharacterModelOptions(avatar != null && useViverseAvatar
+            ? {
+                ...modelOptions,
+                type: 'vrm',
+                url: avatar?.vrmUrl,
+            }
+            : modelOptions),
+    ]);
     useFrame((_, delta) => {
         if (model instanceof VRM) {
             model.update(delta);
@@ -42,38 +53,166 @@ export function useCharacterAnimationLoader(model, options) {
     return suspend((_, ...params) => loadCharacterAnimation(...params), [loadCharacterAnimationSymbol, model, ...flattenCharacterAnimationOptions(options)]);
 }
 /**
- * @deprecated use inputs directly
+ * @deprecated use the specific action binding hooks directly
  */
-export function useSimpleCharacterInputs(inputsClasses = [
-    ScreenJoystickInput,
-    ScreenJumpButtonInput,
-    PointerCaptureInput,
-    LocomotionKeyboardInput,
+export function useSimpleCharacterActionBindings(actionBindingsClasses = [
+    ScreenJoystickLocomotionActionBindings,
+    ScreenButtonJumpActionBindings,
+    PointerCaptureRotateZoomActionBindings,
+    KeyboardLocomotionActionBindings,
 ], options) {
     const dom = useThree((s) => s.gl.domElement);
+    const actionBindingsList = useMemo(() => [], 
     // eslint-disable-next-line react-hooks/exhaustive-deps
-    const inputs = useMemo(() => [], [dom]);
+    [dom]);
     useEffect(() => {
-        const removedInputs = new Set(inputs);
-        for (const inputClass of inputsClasses) {
-            const existingInput = inputs.find((existingInput) => existingInput instanceof inputClass);
-            if (existingInput != null) {
-                removedInputs.delete(existingInput);
+        const removeActionBindingsSet = new Set(actionBindingsList);
+        for (const actionBindingsClass of actionBindingsClasses) {
+            const existingActionBindings = actionBindingsList.find((existingActionBindings) => existingActionBindings instanceof actionBindingsClass);
+            if (existingActionBindings != null) {
+                removeActionBindingsSet.delete(existingActionBindings);
                 continue;
             }
-            inputs.push(new inputClass(dom));
+            const abortController = new AbortController();
+            actionBindingsList.push({ actionBindings: new actionBindingsClass(dom, abortController.signal), abortController });
         }
-        for (const removedInput of removedInputs) {
-            removedInput.dispose();
-            const index = inputs.indexOf(removedInput);
+        for (const entry of removeActionBindingsSet) {
+            entry.abortController.abort();
+            const index = actionBindingsList.indexOf(entry);
             if (index != -1) {
-                inputs.splice(index, 1);
+                actionBindingsList.splice(index, 1);
             }
         }
-        applySimpleCharacterInputOptions(inputs, options);
+        applySimpleCharacterActionBindingOptions(actionBindingsList, options);
     });
     useEffect(() => () => {
-        inputs.forEach((input) => input.dispose());
-        inputs.length = 0;
-    }, [inputs]);
+        actionBindingsList.forEach(({ abortController }) => abortController.abort());
+        actionBindingsList.length = 0;
+    }, [actionBindingsList]);
+}
+export function useKeyboardActionBinding(action, options) {
+    const ref = useRef(undefined);
+    const domElement = useThree((s) => s.gl.domElement);
+    useEffect(() => {
+        const abortController = new AbortController();
+        ref.current = new KeyboardActionBinding(action, domElement, abortController.signal);
+        return () => abortController.abort();
+    }, [action, domElement]);
+    useEffect(() => {
+        if (ref.current == null) {
+            return;
+        }
+        ref.current.keys = options.keys;
+        ref.current.requiresPointerLock = options.requiresPointerLock;
+    });
+}
+export function usePointerButtonActionBinding(action, options) {
+    const ref = useRef(undefined);
+    const canvasDomElement = useThree((s) => s.gl.domElement);
+    const domElement = options.domElement ?? canvasDomElement;
+    useEffect(() => {
+        const abortController = new AbortController();
+        ref.current = new PointerButtonActionBinding(action, domElement instanceof HTMLElement ? domElement : domElement.current, abortController.signal);
+        return () => abortController.abort();
+    }, [action, domElement]);
+    useEffect(() => {
+        if (ref.current == null) {
+            return;
+        }
+        ref.current.buttons = options.buttons;
+        ref.current.requiresPointerLock = options.requiresPointerLock;
+    });
+}
+export function usePointerCaptureRotateZoomActionBindings(options) {
+    const ref = useRef(undefined);
+    const domElement = useThree((s) => s.gl.domElement);
+    useEffect(() => {
+        const abortController = new AbortController();
+        ref.current = new PointerCaptureRotateZoomActionBindings(domElement, abortController.signal);
+        return () => abortController.abort();
+    }, [domElement]);
+    useEffect(() => {
+        if (ref.current == null) {
+            return;
+        }
+        ref.current.rotationSpeed = options?.rotationSpeed;
+        ref.current.zoomSpeed = options?.zoomSpeed;
+    });
+}
+export function usePointerLockRotateZoomActionBindings(options) {
+    const ref = useRef(undefined);
+    const domElement = useThree((s) => s.gl.domElement);
+    useEffect(() => {
+        const abortController = new AbortController();
+        ref.current = new PointerLockRotateZoomActionBindings(domElement, abortController.signal);
+        return () => abortController.abort();
+    }, [domElement]);
+    useEffect(() => {
+        if (ref.current == null) {
+            return;
+        }
+        ref.current.lockOnClick = options?.lockOnClick;
+        ref.current.rotationSpeed = options?.rotationSpeed;
+        ref.current.zoomSpeed = options?.zoomSpeed;
+    });
+}
+export function useKeyboardLocomotionActionBindings(options) {
+    const ref = useRef(undefined);
+    const domElement = useThree((s) => s.gl.domElement);
+    useEffect(() => {
+        const abortController = new AbortController();
+        ref.current = new KeyboardLocomotionActionBindings(domElement, abortController.signal);
+        return () => abortController.abort();
+    }, [domElement]);
+    useEffect(() => {
+        if (ref.current == null) {
+            return;
+        }
+        ref.current.moveBackwardBinding.keys = options?.moveBackwardKeys ?? DefaultMoveBackwardKeys;
+        ref.current.moveBackwardBinding.requiresPointerLock = options?.requiresPointerLock;
+        ref.current.moveForwardBinding.keys = options?.moveForwardKeys ?? DefaultMoveForwardKeys;
+        ref.current.moveForwardBinding.requiresPointerLock = options?.requiresPointerLock;
+        ref.current.jumpBinding.keys = options?.jumpKeys ?? DefaultJumpKeys;
+        ref.current.jumpBinding.requiresPointerLock = options?.requiresPointerLock;
+        ref.current.moveLeftBinding.keys = options?.moveLeftKeys ?? DefaultMoveLeftKeys;
+        ref.current.moveLeftBinding.requiresPointerLock = options?.requiresPointerLock;
+        ref.current.moveRightBinding.keys = options?.moveRightKeys ?? DefaultMoveRightKeys;
+        ref.current.moveRightBinding.requiresPointerLock = options?.requiresPointerLock;
+        ref.current.runBinding.keys = options?.runKeys ?? DefaultRunKeys;
+        ref.current.runBinding.requiresPointerLock = options?.requiresPointerLock;
+    });
+}
+export function useScreenButton(image) {
+    const element = useMemo(() => document.createElement('div'), []);
+    element.style.backgroundImage = image;
+    const domElement = useThree((s) => s.gl.domElement);
+    useEffect(() => {
+        domElement.className = 'viverse-button viverse-jump mobile-only';
+        const parent = domElement.parentNode ?? domElement;
+        parent.appendChild(element);
+        Object.assign(element.style, defaultScreenButtonStyles);
+        const stopPropagation = (e) => e.stopPropagation();
+        element.addEventListener('pointerdown', stopPropagation);
+        return () => {
+            element.remove();
+            element.removeEventListener('pointerdown', stopPropagation);
+        };
+    }, [element, domElement]);
+    return element;
+}
+export function useScreenJoystickLocomotionActionBindings(options) {
+    const ref = useRef(undefined);
+    const domElement = useThree((s) => s.gl.domElement);
+    useEffect(() => {
+        const abortController = new AbortController();
+        ref.current = new ScreenJoystickLocomotionActionBindings(domElement, abortController.signal);
+        return () => abortController.abort();
+    }, [domElement]);
+    useEffect(() => {
+        if (ref.current == null) {
+            return;
+        }
+        ref.current.deadZonePx = options?.deadZonePx;
+        ref.current.runDistancePx = options?.runDistancePx;
+    });
 }

package/package.json

@@ -29,7 +29,7 @@
     "@pixiv/three-vrm": "^3.4.2",
     "zustand": "^5.0.6",
     "@react-three/xr": "^6.6.20",
-    "@pmndrs/viverse": "^0.2.1"
+    "@pmndrs/viverse": "^0.2.2"
   },
   "peerDependencies": {
     "@react-three/fiber": "*"
@@ -40,7 +40,7 @@
     "@types/react": "^19.1.8",
     "react": "^19.1.0"
   },
-  "version": "0.2.1",
+  "version": "0.2.2",
   "scripts": {
     "build": "tsc",
     "check:prettier": "prettier --check src",