@mml-io/3d-web-client-core 0.22.0 → 0.23.0

package/build/camera/CameraManager.d.ts

@@ -1,5 +1,6 @@
-import { PerspectiveCamera, Vector3 } from "three";
+import { PerspectiveCamera } from "three";
 import { CollisionsManager } from "../collisions/CollisionsManager";
+import { Vect3 } from "../math";
 import { TweakPane } from "../tweakpane/TweakPane";
 export declare class CameraManager {
     private targetElement;
@@ -31,7 +32,8 @@ export declare class CameraManager {
     private targetTheta;
     private target;
     private hadTarget;
-    private rayCaster;
+    private cameraRay;
+    private tempVec3;
     private eventHandlerCollection;
     private finalTarget;
     private isLerping;
@@ -51,8 +53,8 @@ export declare class CameraManager {
     private onMouseWheel;
     private zoom;
     private onContextMenu;
-    setTarget(target: Vector3): void;
-    setLerpedTarget(target: Vector3, targetDistance: number): void;
+    setTarget(target: Vect3): void;
+    setLerpedTarget(target: Vect3, targetDistance: number): void;
     reverseUpdateFromPositions(): void;
     adjustCameraPosition(): void;
     dispose(): void;

package/build/character/Character.d.ts

@@ -1,10 +1,11 @@
-import { Color, Group } from "three";
+import { AnimationClip, Group, Object3D } from "three";
 import { CameraManager } from "../camera/CameraManager";
+import { EulXYZ } from "../math/EulXYZ";
+import { Vect3 } from "../math/Vect3";
 import { Composer } from "../rendering/composer";
-import { CharacterModelLoader } from "./CharacterModelLoader";
-import { CharacterSpeakingIndicator } from "./CharacterSpeakingIndicator";
 import { AnimationState } from "./CharacterState";
 import { CharacterTooltip } from "./CharacterTooltip";
+import { CharacterModelLoader } from "./loading/CharacterModelLoader";
 export type AnimationConfig = {
     idleAnimationFileUrl: string;
     jogAnimationFileUrl: string;
@@ -12,6 +13,13 @@ export type AnimationConfig = {
     airAnimationFileUrl: string;
     doubleJumpAnimationFileUrl: string;
 };
+export type LoadedAnimations = {
+    idleAnimation: AnimationClip;
+    jogAnimation: AnimationClip;
+    sprintAnimation: AnimationClip;
+    airAnimation: AnimationClip;
+    doubleJumpAnimation: AnimationClip;
+};
 export type CharacterDescription = {
     meshFileUrl: string;
     mmlCharacterString?: null;
@@ -27,28 +35,36 @@ export type CharacterDescription = {
 };
 export type CharacterConfig = {
     username: string;
-    characterDescription: CharacterDescription;
-    animationConfig: AnimationConfig;
+    characterDescription: CharacterDescription | null;
+    animationsPromise: Promise<LoadedAnimations>;
     characterModelLoader: CharacterModelLoader;
     characterId: number;
     modelLoadedCallback: () => void;
+    modelLoadFailedCallback?: (error: Error) => void;
     cameraManager: CameraManager;
     composer: Composer;
     isLocal: boolean;
+    abortController?: AbortController;
 };
 export declare class Character extends Group {
     private config;
     private model;
-    color: Color;
-    tooltip: CharacterTooltip;
-    speakingIndicator: CharacterSpeakingIndicator | null;
+    usernameTooltip: CharacterTooltip;
     chatTooltips: CharacterTooltip[];
     constructor(config: CharacterConfig);
-    updateCharacter(username: string, characterDescription: CharacterDescription): void;
+    getColors(): Array<[number, number, number]>;
+    updateCharacter(username: string, characterDescription: CharacterDescription | null, abortController: AbortController, onModelLoaded: () => void, onModelLoadFailed: (error: Error) => void): void;
     private setTooltipHeights;
+    static loadAnimations(characterModelLoader: CharacterModelLoader, animationConfig: AnimationConfig): Promise<LoadedAnimations>;
     private load;
     updateAnimation(targetAnimation: AnimationState): void;
     update(time: number, deltaTime: number): void;
+    getPosition(): Vect3;
+    getRotation(): EulXYZ;
+    setPosition(x: number, y: number, z: number): void;
+    setRotation(x: number, y: number, z: number, w: number): void;
     getCurrentAnimation(): AnimationState;
     addChatBubble(message: string): void;
+    getMesh(): Object3D | null;
+    dispose(): void;
 }

package/build/character/CharacterManager.d.ts

@@ -1,15 +1,18 @@
 import { PositionAndRotation } from "@mml-io/mml-web";
-import { Euler, Group, Vector3 } from "three";
+import { Group } from "three";
 import { CameraManager } from "../camera/CameraManager";
 import { CollisionsManager } from "../collisions/CollisionsManager";
 import { KeyInputManager } from "../input/KeyInputManager";
 import { VirtualJoystick } from "../input/VirtualJoystick";
+import { EulXYZ } from "../math/EulXYZ";
+import { Vect3 } from "../math/Vect3";
 import { Composer } from "../rendering/composer";
 import { TimeManager } from "../time/TimeManager";
 import { TweakPane } from "../tweakpane/TweakPane";
-import { AnimationConfig, Character, CharacterDescription } from "./Character";
-import { CharacterModelLoader } from "./CharacterModelLoader";
+import { Character, CharacterDescription, LoadedAnimations } from "./Character";
 import { CharacterState } from "./CharacterState";
+import { CharacterInstances } from "./instancing/CharacterInstances";
+import { CharacterModelLoader } from "./loading/CharacterModelLoader";
 import { LocalController } from "./LocalController";
 import { RemoteController } from "./RemoteController";
 type SpawnPosition = {
@@ -54,37 +57,63 @@ export type CharacterManagerConfig = {
     virtualJoystick?: VirtualJoystick;
     remoteUserStates: Map<number, CharacterState>;
     sendUpdate: (update: CharacterState) => void;
-    animationConfig: AnimationConfig;
+    sendLocalCharacterColors: (colors: Array<[number, number, number]>) => void;
+    animationsPromise: Promise<LoadedAnimations>;
     spawnConfiguration: SpawnConfigurationState;
     characterResolve: (clientId: number) => {
-        username: string;
-        characterDescription: CharacterDescription;
+        username: string | null;
+        characterDescription: CharacterDescription | null;
+        colors: Array<[number, number, number]> | null;
     };
     updateURLLocation?: boolean;
 };
+type LoadedCharacterState = {
+    character: Character;
+    remoteController: RemoteController;
+    characterLoaded: boolean;
+};
+type RemoteCharacterState = {
+    id: number;
+    loadedCharacterState: LoadedCharacterState | null;
+    lastPosition: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    distanceSquared: number;
+    lastLODChange: number;
+    abortController?: AbortController;
+};
 export declare class CharacterManager {
     private config;
-    readonly headTargetOffset: Vector3;
+    static readonly headTargetOffset: Vect3;
     private localClientId;
-    remoteCharacters: Map<number, Character>;
-    remoteCharacterControllers: Map<number, RemoteController>;
-    private localCharacterSpawned;
+    remoteCharacters: Map<number, RemoteCharacterState>;
     localController: LocalController;
     localCharacter: Character | null;
-    private speakingCharacters;
+    characterInstances: CharacterInstances | null;
     readonly group: Group;
     private lastUpdateSentTime;
+    private readonly MAX_REAL_REMOTE_CHARACTERS;
+    private readonly LOD_CHANGE_COOLDOWN_MS;
+    private readonly MAX_SCENE_ADDITIONS_PER_FRAME;
+    private pendingSpawns;
+    private loadingCharacters;
+    private charactersReadyForScene;
     constructor(config: CharacterManagerConfig);
-    spawnLocalCharacter(id: number, username: string, characterDescription: CharacterDescription, spawnPosition?: Vector3, spawnRotation?: Euler): void;
-    createRespawnButton(): HTMLDivElement;
+    spawnLocalCharacter(id: number, username: string, characterDescription: CharacterDescription | null, spawnPosition?: Vect3, spawnRotation?: EulXYZ): void;
+    private calculateDistanceSquared;
+    private evaluateLOD;
+    private promoteToReal;
+    private demoteToInstance;
     setupTweakPane(tweakPane: TweakPane): void;
-    spawnRemoteCharacter(id: number, username: string, characterDescription: CharacterDescription, spawnPosition?: Vector3, spawnRotation?: Euler): void;
+    private initializeCharacterInstances;
     getLocalCharacterPositionAndRotation(): PositionAndRotation;
     clear(): void;
-    setSpeakingCharacter(id: number, value: boolean): void;
+    dispose(): void;
     addSelfChatBubble(message: string): void;
     addChatBubble(id: number, message: string): void;
-    respawnIfPresent(id: number): void;
+    networkCharacterInfoUpdated(id: number): void;
     update(): void;
 }
 export {};

package/build/character/CharacterModel.d.ts

@@ -1,21 +1,24 @@
 import { type MMLCharacterDescription } from "@mml-io/3d-web-avatar";
-import { ModelLoader } from "@mml-io/model-loader";
-import { AnimationAction, AnimationMixer, Bone, Object3D } from "three";
+import { AnimationAction, AnimationMixer, Bone, Color, Object3D } from "three";
 import { CameraManager } from "../camera/CameraManager";
-import { AnimationConfig, CharacterDescription } from "./Character";
-import { CharacterModelLoader } from "./CharacterModelLoader";
+import { CharacterDescription, LoadedAnimations } from "./Character";
 import { AnimationState } from "./CharacterState";
+import { CharacterModelLoader } from "./loading/CharacterModelLoader";
+export declare const colorPartNamesIndex: readonly ["hair", "shirt_short", "shirt_long", "pants_short", "pants_long", "shoes", "skin", "lips"];
+export type ColorPartName = (typeof colorPartNamesIndex)[number];
+export declare function colorsToColorArray(colors: Map<ColorPartName, Color>): Array<[number, number, number]>;
+export declare function colorArrayToColors(colorArray: Array<[number, number, number]>): Map<ColorPartName, Color>;
 export type CharacterModelConfig = {
     characterDescription: CharacterDescription;
-    animationConfig: AnimationConfig;
+    animationsPromise: Promise<LoadedAnimations>;
     characterModelLoader: CharacterModelLoader;
     cameraManager: CameraManager;
     characterId: number;
     isLocal: boolean;
+    abortController?: AbortController;
 };
 export declare class CharacterModel {
     private config;
-    static ModelLoader: ModelLoader;
     mesh: Object3D | null;
     headBone: Bone | null;
     characterHeight: number | null;
@@ -25,16 +28,17 @@ export declare class CharacterModel {
     currentAnimation: AnimationState;
     mmlCharacterDescription: MMLCharacterDescription;
     private isPostDoubleJump;
+    private colors;
     constructor(config: CharacterModelConfig);
     init(): Promise<void>;
     private applyCustomMaterials;
     updateAnimation(targetAnimation: AnimationState): void;
-    private setMainMesh;
     private composeMMLCharacter;
     private loadCharacterFromDescription;
-    private loadMainMesh;
+    getColors(): Array<[number, number, number]>;
     private cleanAnimationClips;
     private setAnimationFromFile;
     private transitionToAnimation;
     update(time: number): void;
+    dispose(): void;
 }

package/build/character/CharacterState.d.ts

@@ -8,7 +8,6 @@ export declare enum AnimationState {
     "doubleJump" = 6
 }
 export type CharacterState = {
-    id: number;
     position: {
         x: number;
         y: number;
@@ -18,14 +17,5 @@ export type CharacterState = {
         quaternionY: number;
         quaternionW: number;
     };
-    camPosition?: {
-        x: number;
-        y: number;
-        z: number;
-    };
-    camQuaternion?: {
-        y: number;
-        w: number;
-    };
     state: AnimationState;
 };

package/build/character/CharacterTooltip.d.ts

@@ -27,5 +27,6 @@ export declare class CharacterTooltip extends Sprite {
     hide(): void;
     show(): void;
     update(): void;
+    dispose(): void;
 }
 export {};

package/build/character/LocalController.d.ts

@@ -1,8 +1,10 @@
-import { Line3, Quaternion, Vector3 } from "three";
 import { CameraManager } from "../camera/CameraManager";
 import { CollisionsManager } from "../collisions/CollisionsManager";
 import { KeyInputManager } from "../input/KeyInputManager";
 import { VirtualJoystick } from "../input/VirtualJoystick";
+import { Line } from "../math/Line";
+import { Quat } from "../math/Quat";
+import { IVect3, Vect3 } from "../math/Vect3";
 import { TimeManager } from "../time/TimeManager";
 import { Character } from "./Character";
 import { SpawnConfigurationState } from "./CharacterManager";
@@ -21,7 +23,7 @@ export declare class LocalController {
     private config;
     capsuleInfo: {
         radius: number;
-        segment: Line3;
+        segment: Line;
     };
     gravity: number;
     jumpForce: number;
@@ -39,7 +41,7 @@ export declare class LocalController {
     groundRunControl: number;
     baseControl: number;
     minimumSurfaceAngle: number;
-    latestPosition: Vector3;
+    latestPosition: Vect3;
     characterOnGround: boolean;
     coyoteTime: boolean;
     private collisionDetectionSteps;
@@ -53,22 +55,21 @@ export declare class LocalController {
     private rotationOffset;
     private azimuthalAngle;
     private tempSegment;
-    private tempQuaternion;
-    private tempEuler;
+    private tempQuat;
+    private tempEulXYZ;
     private tempVector;
     private tempVector2;
-    private tempVector3;
-    private rayCaster;
-    private surfaceTempQuaternion;
-    private surfaceTempQuaternion2;
+    private tempVect3;
+    private tempRay;
+    private surfaceTempQuat;
+    private surfaceTempQuat2;
     private surfaceTempVector1;
     private surfaceTempVector2;
-    private surfaceTempVector3;
+    private surfaceTempVect3;
     private surfaceTempVector4;
     private surfaceTempVector5;
     private surfaceTempRay;
     private lastFrameSurfaceState;
-    jumpPressed: boolean;
     jumpReleased: boolean;
     networkState: CharacterState;
     private controlState;
@@ -89,9 +90,9 @@ export declare class LocalController {
     private processJump;
     private applyControls;
     private updatePosition;
-    getMovementFromSurfaces(userPosition: Vector3, deltaTime: number): {
-        rotation: Quaternion;
-        position: Vector3;
+    getMovementFromSurfaces(userPosition: IVect3, deltaTime: number): {
+        rotation: Quat;
+        position: Vect3;
     } | null;
     private updateNetworkState;
     resetPosition(): void;

package/build/character/LowPolyModel.d.ts

@@ -0,0 +1 @@
+export declare const lowPolyLoDModelURL: any;

package/build/character/RemoteController.d.ts

@@ -1,14 +1,14 @@
 import { Character } from "./Character";
-import { AnimationState, CharacterState } from "./CharacterState";
+import { CharacterState } from "./CharacterState";
 export type RemoteControllerConfig = {
-    id: number;
     character: Character;
 };
 export declare class RemoteController {
-    private config;
-    currentAnimation: AnimationState;
+    private character;
     networkState: CharacterState;
-    constructor(config: RemoteControllerConfig);
+    private hasReceivedInitialUpdate;
+    private interpolationRate;
+    constructor(character: Character);
     update(clientUpdate: CharacterState, time: number, deltaTime: number): void;
     private updateFromNetwork;
 }

package/build/character/Spawning.d.ts

@@ -0,0 +1,8 @@
+import { EulXYZ } from "../math/EulXYZ";
+import { Vect3 } from "../math/Vect3";
+import { SpawnConfigurationState } from "./CharacterManager";
+export declare function getSpawnData(config: SpawnConfigurationState, useLocationHash?: boolean): {
+    spawnPosition: Vect3;
+    spawnRotation: EulXYZ;
+    cameraPosition: Vect3;
+};

package/build/character/instancing/CharacterColourSamplingUtils.d.ts

@@ -0,0 +1,14 @@
+import { Color, SkinnedMesh, Object3D } from "three";
+import { ColorPartName } from "../CharacterModel";
+import { InstancedMesh2 } from "./vendor/";
+export type ColorSamplingOptions = {
+    circularSamplingRadius?: number;
+    topDownSamplingSize?: {
+        width: number;
+        height: number;
+    };
+    debug?: boolean;
+};
+export declare function captureCharacterColors(characterMesh: SkinnedMesh, options: ColorSamplingOptions): Map<ColorPartName, Color>;
+export declare function captureCharacterColorsFromObject3D(object3D: Object3D, options: ColorSamplingOptions): Map<ColorPartName, Color>;
+export declare function updateDebugTextureCanvas(instancedMesh: InstancedMesh2): void;

package/build/character/instancing/CharacterInstances.d.ts

@@ -0,0 +1,92 @@
+import { Color, Object3D, Quaternion, Vector3 } from "three";
+import { CameraManager } from "../../camera/CameraManager";
+import { EulXYZ, Vect3 } from "../../math";
+import { TimeManager } from "../../time/TimeManager";
+import { LoadedAnimations } from "../Character";
+import { ColorPartName } from "../CharacterModel";
+import { AnimationState } from "../CharacterState";
+import { CharacterModelLoader } from "../loading/CharacterModelLoader";
+export type CharacterInstancesConfig = {
+    animationsPromise: Promise<LoadedAnimations>;
+    characterModelLoader: CharacterModelLoader;
+    cameraManager: CameraManager;
+    timeManager: TimeManager;
+    debug?: boolean;
+};
+export type InstanceData = {
+    characterId: number;
+    instanceId: number;
+    isActive: boolean;
+    isShadowed: boolean;
+    time: number;
+    speed: number;
+    offset: number;
+    currentAnimationState: string;
+    animationTime: number;
+    targetPosition: Vector3;
+    targetQuaternion: Quaternion;
+    lerpSpeed: number;
+    hasNewTarget: boolean;
+};
+export declare class CharacterInstances {
+    private config;
+    private mixer;
+    private action;
+    private instancedMesh;
+    private skinnedMesh;
+    private propertyBindings;
+    private interpolants;
+    private propertyBindingsLOD;
+    private interpolantsLOD;
+    private invMatrixWorld;
+    private cameraLocalPosition;
+    private delta;
+    private characterScale;
+    private currentBindingMode;
+    private debug;
+    private animationClip;
+    private animationSegments;
+    private characterIdToInstanceIdMap;
+    private animationStateToSegmentName;
+    /**
+     * Apply colors to an instance at the given index
+     * @param instanceIndex The index of the instance to apply colors to
+     * @param colors Optional specific colors to apply, if not provided, random colors will be used
+     */
+    private applyInstanceColors;
+    constructor(config: CharacterInstancesConfig);
+    initialize(): Promise<Object3D | null>;
+    spawnInstance(characterId: number, colors: Map<ColorPartName, Color>, position: Vect3, rotation: EulXYZ, animationState: AnimationState): void;
+    despawnInstance(characterId: number): void;
+    /**
+     * Shadows an instance instead of fully despawning it. This keeps the instance data
+     * intact (including colors) while hiding it when a real character is promoted.
+     * This avoids texture updates when the character is later demoted back to an instance.
+     */
+    shadowInstance(characterId: number): void;
+    /**
+     * Reactivates a previously shadowed instance. This is used when a real character
+     * is demoted back to an instance, allowing us to reuse the existing instance data
+     * and avoid texture updates from creating a new instance.
+     */
+    unshadowInstance(characterId: number): void;
+    updateInstance(characterId: number, position: Vect3, rotation: EulXYZ, animationState: AnimationState): void;
+    updateInstanceColors(characterId: number, colors: Map<string, Color>): void;
+    private updateInstancedMeshBounds;
+    private setMainMesh;
+    private loadAnimation;
+    private createInstancedMesh;
+    private setupAnimationOptimization;
+    private initializeSkeletonData;
+    getPositionForInstance(characterId: number): Vect3 | null;
+    private updateAllInstanceLerping;
+    update(deltaTime: number, totalTime: number): void;
+    setupFrustumCulling(): void;
+    clear(): void;
+    dispose(): void;
+    /**
+     * Immediately sets an instance position without lerping. Used when unshadowing
+     * instances to position them at the real character's last known position.
+     */
+    setInstancePositionImmediate(characterId: number, position: Vect3, rotation: EulXYZ, animationState: AnimationState): boolean;
+}

package/build/character/instancing/CharacterInstancingAnimationUtils.d.ts

@@ -0,0 +1,7 @@
+import { AnimationClip } from "three";
+export type SegmentTime = {
+    startTime: number;
+    endTime: number;
+    duration: number;
+};
+export declare function createSingleTimeline(individualClips: Map<string, AnimationClip>): [Map<string, SegmentTime>, AnimationClip];

package/build/character/instancing/CharacterInstancingUtils.d.ts

@@ -0,0 +1,3 @@
+import { SkinnedMesh } from "three";
+export declare function mergeSkinnedMeshes(skinnedMeshes: SkinnedMesh[], debug?: boolean): SkinnedMesh;
+export declare function validateAndCleanSkeleton(skinnedMesh: SkinnedMesh): void;