m-character sockets

example/web-avatar-client/package.json

@@ -11,8 +11,7 @@
     "iterate": "tsx ./build.ts --watch",
     "type-check": "tsc --noEmit",
     "lint": "eslint \"./{src,test}/**/*.{js,jsx,ts,tsx}\" --max-warnings 0",
-    "lint-fix": "eslint \"./{src,test}/**/*.{js,jsx,ts,tsx}\" --fix",
-    "test": "jest"
+    "lint-fix": "eslint \"./{src,test}/**/*.{js,jsx,ts,tsx}\" --fix"
   },
   "dependencies": {
     "@mml-io/3d-web-client-core": "^0.12.1",

example/web-avatar-client/src/AvatarEditor.tsx

@@ -5,7 +5,7 @@ import {
 } from "@mml-io/3d-web-avatar";
 import {
   AvatarVisualizer,
-  Character,
+  MMLCharacter,
   CharacterComposition,
   CharacterPartsSelector,
   CollectionDataType,
@@ -42,7 +42,7 @@ export function AvatarEditor<C extends CollectionDataType>(props: {
   showMirror: boolean;
 }) {
   const [characterMesh, setCharacterMesh] = useState<Object3D | null>(null);
-  const [character] = useState(new Character(new ModelLoader()));
+  const [character] = useState(new MMLCharacter(new ModelLoader()));
   const [selectedPart, setSelectedPart] = useState<BodyPartTypes>("fullBody");
   const [errors, setErrors] = useState(props.loadingErrors);
 
@@ -76,7 +76,9 @@ export function AvatarEditor<C extends CollectionDataType>(props: {
       // The character parts picker provides the full body separately from the parts that are then layered onto it
       const obj3d = await character.mergeBodyParts(
         fullBody.url,
-        Object.values(parts).map((part) => part.url),
+        Object.values(parts).map((part) => ({
+          url: part.url,
+        })),
       );
       setCharacterMesh(obj3d);
       setSelectedPart("fullBody");

example/web-avatar-client/tsconfig.json

@@ -19,8 +19,8 @@
     "noEmit": true,
     "baseUrl": ".",
     "incremental": true,
-    "skipLibCheck": true
+    "skipLibCheck": true,
   },
-  "include": ["src/**/*", "test/**/*", "./build.ts"],
-  "exclude": ["**/build/*", "types-src"]
+  "include": ["src/**/*", "./build.ts"],
+  "exclude": ["**/build/*", "types-src"],
 }

example/web-client/src/index.ts

@@ -53,7 +53,16 @@ const characterDescription: CharacterDescription = {
   // Option 2 - Use an MML Character from a URL
   // mmlCharacterUrl: "https://...",
   // Option 3 - Use an MML Character from a string
-  // mmlCharacterString: `<m-character src="https://..."></m-character>`,
+  // mmlCharacterString: `
+  // <m-character src="/assets/models/bot.glb">
+  //   <m-model src="/assets/models/ears.glb"
+  //     socket="head"
+  //     x="0.077" y="0" z="0.04"
+  //     sx="1.1" sy="1.1" sz="1.1"
+  //     rz="-90"
+  //   ></m-model>
+  // </m-character>
+  // `,
 };
 
 const protocol = window.location.protocol === "https:" ? "wss:" : "ws:";

packages/3d-web-avatar/package.json

@@ -16,7 +16,8 @@
     "start": "NODE_ENV=production node build/index.js 2>error.log",
     "type-check": "tsc --noEmit",
     "lint": "eslint \"./{src,test}/**/*.{js,jsx,ts,tsx}\" --max-warnings 0",
-    "lint-fix": "eslint \"./{src,test}/**/*.{js,jsx,ts,tsx}\" --fix"
+    "lint-fix": "eslint \"./{src,test}/**/*.{js,jsx,ts,tsx}\" --fix",
+    "test": "jest"
   },
   "dependencies": {
     "react": "^18.2.0",

packages/3d-web-avatar/src/character/Character.ts → packages/3d-web-avatar/src/character/MMLCharacter.ts

@@ -1,20 +1,24 @@
 import {
-  BoxHelper,
+  Bone,
   BufferAttribute,
+  Euler,
   Group,
+  MathUtils,
   Matrix4,
-  MeshStandardMaterial,
+  Mesh,
   Object3D,
   Skeleton,
   SkinnedMesh,
+  Vector3,
 } from "three";
 import { GLTF } from "three/examples/jsm/loaders/GLTFLoader.js";
 
+import { MMLCharacterDescriptionPart } from "../helpers/parseMMLDescription";
 import { SkeletonHelpers } from "../helpers/SkeletonHelpers";
 
 import { ModelLoader } from "./ModelLoader";
 
-export class Character {
+export class MMLCharacter {
   private skeletonHelpers: SkeletonHelpers = new SkeletonHelpers();
   private skinnedMeshesParent: Group | null = null;
   private sharedSkeleton: Skeleton | null = null;
@@ -62,26 +66,34 @@ export class Character {
     );
   }
 
-  public async mergeBodyParts(fullBodyURL: string, bodyParts: Array<string>): Promise<Object3D> {
+  public async mergeBodyParts(
+    fullBodyURL: string,
+    bodyParts: Array<MMLCharacterDescriptionPart>,
+  ): Promise<Object3D> {
     const fullBodyAsset = await this.modelLoader.load(fullBodyURL);
     const fullBodyGLTF = this.skeletonHelpers.cloneGLTF(fullBodyAsset as GLTF, "fullBody");
 
-    const assetPromises: Array<Promise<{ asset: GLTF; partUrl: string }>> = bodyParts.map(
-      (partUrl) => {
+    const assetPromises: Array<Promise<{ asset: GLTF; part: MMLCharacterDescriptionPart }>> =
+      bodyParts.map((part) => {
         return new Promise((resolve) => {
-          this.modelLoader.load(partUrl).then((asset) => {
-            resolve({ asset: asset!, partUrl });
+          this.modelLoader.load(part.url).then((asset) => {
+            resolve({ asset: asset!, part });
           });
         });
-      },
-    );
+      });
     const assets = await Promise.all(assetPromises);
 
     const fullBodyModelGroup = fullBodyGLTF.gltf.scene;
 
     this.skinnedMeshesParent = null;
 
+    const availableBones = new Map<string, Bone>();
     fullBodyModelGroup.traverse((child) => {
+      const asBone = child as Bone;
+      if (asBone.isBone) {
+        availableBones.set(child.name, asBone);
+      }
+
       const asSkinnedMesh = child as SkinnedMesh;
       if (asSkinnedMesh.isSkinnedMesh) {
         asSkinnedMesh.castShadow = true;
@@ -95,19 +107,57 @@ export class Character {
     this.sharedMatrixWorld = fullBodyGLTF.matrixWorld;
 
     for (const loadingAsset of assets) {
-      const gltf = this.skeletonHelpers.cloneGLTF(loadingAsset.asset, loadingAsset.partUrl);
+      const part = loadingAsset.part;
+      const gltf = this.skeletonHelpers.cloneGLTF(loadingAsset.asset, part.url);
       const modelGroup = gltf.gltf.scene;
-      modelGroup.traverse((child) => {
-        const asSkinnedMesh = child as SkinnedMesh;
-        if (asSkinnedMesh.type === "SkinnedMesh") {
-          const skinnedMeshClone = child.clone(true) as SkinnedMesh;
-          this.remapBoneIndices(skinnedMeshClone);
-          skinnedMeshClone.castShadow = true;
-          skinnedMeshClone.receiveShadow = true;
-          skinnedMeshClone.bind(this.sharedSkeleton!, this.sharedMatrixWorld!);
-          this.skinnedMeshesParent?.add(skinnedMeshClone);
+      if (part.socket) {
+        const socketName = part.socket.socket;
+        let bone = availableBones.get("root");
+        if (availableBones.has(socketName)) {
+          bone = availableBones.get(socketName);
+        } else {
+          console.warn(
+            `WARNING: no bone found for [${socketName}] socket. Attatching to Root bone`,
+          );
         }
-      });
+        if (bone) {
+          modelGroup.position.set(0, 0, 0);
+          modelGroup.rotation.set(0, 0, 0);
+          modelGroup.scale.set(1, 1, 1);
+
+          bone.add(modelGroup);
+
+          modelGroup.rotateZ(-Math.PI / 2);
+
+          const offsetPosition = new Vector3(
+            part.socket.position.x,
+            part.socket.position.y,
+            part.socket.position.z,
+          );
+          modelGroup.position.copy(offsetPosition);
+
+          const offsetRotation = new Euler(
+            MathUtils.degToRad(part.socket.rotation.x),
+            MathUtils.degToRad(part.socket.rotation.y),
+            MathUtils.degToRad(part.socket.rotation.z),
+          );
+          modelGroup.setRotationFromEuler(offsetRotation);
+
+          modelGroup.scale.set(part.socket.scale.x, part.socket.scale.y, part.socket.scale.z);
+        }
+      } else {
+        modelGroup.traverse((child) => {
+          const asSkinnedMesh = child as SkinnedMesh;
+          if (asSkinnedMesh.isSkinnedMesh) {
+            const skinnedMeshClone = child.clone(true) as SkinnedMesh;
+            this.remapBoneIndices(skinnedMeshClone);
+            skinnedMeshClone.castShadow = true;
+            skinnedMeshClone.receiveShadow = true;
+            skinnedMeshClone.bind(this.sharedSkeleton!, this.sharedMatrixWorld!);
+            this.skinnedMeshesParent?.add(skinnedMeshClone);
+          }
+        });
+      }
     }
     return fullBodyGLTF!.gltf.scene as Object3D;
   }

packages/3d-web-avatar/src/helpers/parseMMLDescription.ts

@@ -1,6 +1,12 @@
 export type MMLCharacterDescriptionPart = {
   url: string;
   type?: string;
+  socket?: {
+    socket: string;
+    position: { x: number; y: number; z: number };
+    scale: { x: number; y: number; z: number };
+    rotation: { x: number; y: number; z: number };
+  };
 };
 
 export type MMLCharacterDescription = {
@@ -69,7 +75,27 @@ export const parseMMLDescription = (
     );
     parts = directModelChildren.map((model) => {
       const partSrc = model.getAttribute("src") ?? "";
-      return { url: partSrc };
+
+      const socketAttr = model.getAttribute("socket");
+      const position = {
+        x: parseFloat(model.getAttribute("x") ?? "0") || 0,
+        y: parseFloat(model.getAttribute("y") ?? "0") || 0,
+        z: parseFloat(model.getAttribute("z") ?? "0") || 0,
+      };
+      const scale = {
+        x: parseFloat(model.getAttribute("sx") ?? "1") || 1,
+        y: parseFloat(model.getAttribute("sy") ?? "1") || 1,
+        z: parseFloat(model.getAttribute("sz") ?? "1") || 1,
+      };
+      const rotation = {
+        x: parseFloat(model.getAttribute("rx") ?? "0") || 0,
+        y: parseFloat(model.getAttribute("ry") ?? "0") || 0,
+        z: parseFloat(model.getAttribute("rz") ?? "0") || 0,
+      };
+
+      const socketObj = socketAttr ? { socket: socketAttr, position, scale, rotation } : undefined;
+
+      return { url: partSrc, socket: socketObj };
     });
 
     const wrappedModelTags = Array.from(doc.querySelectorAll("m-character m-model")).filter(

packages/3d-web-avatar/src/index.ts

@@ -1,4 +1,4 @@
-export { Character } from "./character/Character";
+export { MMLCharacter } from "./character/MMLCharacter";
 export { cloneModel } from "./helpers/SkeletonHelpers";
 export { TimeManagerInterface } from "./character/types";
 export { ModelLoader } from "./character/ModelLoader";

packages/3d-web-avatar/test/collection.json

@@ -0,0 +1,77 @@
+{
+  "fullBody": [
+    {
+      "name": "Full Body 1",
+      "asset": "/assets/avatar/parts/SK_Outfit_Body_Male.glb",
+      "thumb": "/assets/avatar/thumbs/SK_Outfit_Body_Male.jpg"
+    }
+  ],
+  "head": [
+    {
+      "name": "Dude Head 1",
+      "asset": "/assets/avatar/parts/SK_Outfit_Hat_02.glb",
+      "thumb": "/assets/avatar/thumbs/SK_Outfit_Hat_02.jpg"
+    },
+    {
+      "name": "Dude Head 2",
+      "asset": "/assets/avatar/parts/SK_Outfit_Hat_01.glb",
+      "thumb": "/assets/avatar/thumbs/SK_Outfit_Hat_01.jpg"
+    },
+    {
+      "name": "Dude Head 3",
+      "asset": "/assets/avatar/parts/SK_Outfit_Hat_03.glb",
+      "thumb": "/assets/avatar/thumbs/SK_Outfit_Hat_03.jpg"
+    }
+  ],
+  "upperBody": [
+    {
+      "name": "Dude Upper Body 1",
+      "asset": "/assets/avatar/parts/SK_Outfit_One_Hoody_01.glb",
+      "thumb": "/assets/avatar/thumbs/SK_Outfit_One_Hoody_01.jpg"
+    },
+    {
+      "name": "Dude Upper Body 2",
+      "asset": "/assets/avatar/parts/SK_Outfit_Two_Long_Coat_with_Collared_Shirt_01.glb",
+      "thumb": "/assets/avatar/thumbs/SK_Outfit_Two_Long_Coat_with_Collared_Shirt_01.jpg"
+    },
+    {
+      "name": "Dude Upper Body 3",
+      "asset": "/assets/avatar/parts/SK_Outfit_Three_Flanel_Shirt_01.glb",
+      "thumb": "/assets/avatar/thumbs/SK_Outfit_Three_Flanel_Shirt_01.jpg"
+    }
+  ],
+  "lowerBody": [
+    {
+      "name": "Dude Lower Body 1",
+      "asset": "/assets/avatar/parts/SK_Outfit_Two_Tight_Joggers_01.glb",
+      "thumb": "/assets/avatar/thumbs/SK_Outfit_Two_Tight_Joggers_01.jpg"
+    },
+    {
+      "name": "Dude Lower Body 2",
+      "asset": "/assets/avatar/parts/SK_Outfit_Three_Tight_Jeans_with_Chain_01.glb",
+      "thumb": "/assets/avatar/thumbs/SK_Outfit_Three_Tight_Jeans_with_Chain_01.jpg"
+    },
+    {
+      "name": "Dude Lower Body 3",
+      "asset": "/assets/avatar/parts/SK_Outfit_One_Cargo_Shorts_01.glb",
+      "thumb": "/assets/avatar/thumbs/SK_Outfit_One_Cargo_Shorts_01.jpg"
+    }
+  ],
+  "feet": [
+    {
+      "name": "Dude Feet 1",
+      "asset": "/assets/avatar/parts/SK_Outfit_One_High_Tops_01.glb",
+      "thumb": "/assets/avatar/thumbs/SK_Outfit_One_High_Tops_01.jpg"
+    },
+    {
+      "name": "Dude Feet 2",
+      "asset": "/assets/avatar/parts/SK_Outfit_Three_Mid_Tops_01.glb",
+      "thumb": "/assets/avatar/thumbs/SK_Outfit_Three_Mid_Tops_01.jpg"
+    },
+    {
+      "name": "Dude Feet 3",
+      "asset": "/assets/avatar/parts/SK_Outfit_Three_Mid_Tops_02.glb",
+      "thumb": "/assets/avatar/thumbs/SK_Outfit_Three_Mid_Tops_02.jpg"
+    }
+  ]
+}