feat: spring bones (#60)

* feat: unity upgrade + jetbrains folders into gitignore

* fix: spring bones integration

* fix: apply color to all the submeshes

* feat: js bridge to modify bones params

* fix: SetSpringBonesParam was returning bool for no reason

* chore: logs

* fix: now SetSpringChainsForWearable replaces the whole spring bones hierarchy.

* feat: read wearablesDTO instead of the SpringBoneJointComponent

* fix: issue when parsing bones in root chains

* fix: align spring bones payload with definitive wearable JSON

springBones now read from metadata.data.springBones (was top-level on
ActiveEntity) and models keyed by main-file hash (was filename). Vector3
converter accepts both array and object forms. Driver respects isRoot
flag and walks chains in skinned.bones order.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix: align spring bones simulation with unity-explorer

Switch from reparenting extras under the live avatar skeleton to keeping
spring bones in the wearable hierarchy and snapping the wearable's
intermediate parent to the live avatar bone every frame. Run the sim at
fixed 60 Hz sub-steps so authored stiffness/drag are framerate-invariant.
Restore captured rest rotations in UnregisterAll so re-registration after
emote/reload doesn't lock onto stale sim state. Match unity-explorer's
chain expansion: only isRoot entries seed chains and tagged children are
skipped during descendant collection.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix: sync wearable parent scale per frame for spring bones

Emotes that animate avatar bone scale (e.g. head-explode) now propagate
to spring-bone wearables. Previously scale was aligned only at chain
registration so the wearable parent kept its initial scale while the
avatar bone grew.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix: spring bones for builder base64 wearables

* fix: chain per tagged bone, linear first-child walk

* fix: spring bones without params now depend on their parents worldmatrix transform

* fix: code review applied

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: alejandro-jimenez-dcl

.gitignore

@@ -27,6 +27,9 @@
 # Visual Studio cache directory
 .vs/
 
+# JetBrains IDE directory
+.idea/
+
 # Gradle cache directory
 .gradle/
 

Assets/Scenes/Main.unity

@@ -130,6 +130,7 @@ GameObject:
   - component: {fileID: 9355361}
   - component: {fileID: 9355362}
   - component: {fileID: 9355363}
+  - component: {fileID: 9355364}
   m_Layer: 0
   m_Name: AvatarRoot
   m_TagString: Untagged
@@ -233,6 +234,7 @@ MonoBehaviour:
   - {fileID: 979165189}
   - {fileID: 979165180}
   - {fileID: 979165181}
+  springBonesDriver: {fileID: 9355364}
   setsHighlight: 0
   highlightCenter: {x: 0, y: 0.18, z: 0}
   highlightSize: {x: 0.57, y: 2.3}
@@ -254,6 +256,18 @@ MonoBehaviour:
   autoRotateSpeed: 10
   autoRotateDelay: 1
   returnSpeed: 2
+--- !u!114 &9355364
+MonoBehaviour:
+  m_ObjectHideFlags: 0
+  m_CorrespondingSourceObject: {fileID: 0}
+  m_PrefabInstance: {fileID: 0}
+  m_PrefabAsset: {fileID: 0}
+  m_GameObject: {fileID: 9355360}
+  m_Enabled: 1
+  m_EditorHideFlags: 0
+  m_Script: {fileID: 11500000, guid: 95ea887eb11d7f94eaef9ace0bb62be9, type: 3}
+  m_Name: 
+  m_EditorClassIdentifier: Assembly-CSharp::SpringBones.SpringBonesDriver
 --- !u!1001 &64509934
 PrefabInstance:
   m_ObjectHideFlags: 0
@@ -2747,6 +2761,7 @@ GameObject:
   m_Component:
   - component: {fileID: 8085770638703914882}
   - component: {fileID: 8085770638703914883}
+  - component: {fileID: 8085770638703914884}
   m_Layer: 0
   m_Name: AvatarRoot
   m_TagString: Untagged
@@ -4566,9 +4581,22 @@ MonoBehaviour:
   - {fileID: 64509949}
   - {fileID: 64509940}
   - {fileID: 64509941}
+  springBonesDriver: {fileID: 8085770638703914884}
   setsHighlight: 1
   highlightCenter: {x: 0, y: 0.18, z: 0}
   highlightSize: {x: 0.57, y: 2.3}
+--- !u!114 &8085770638703914884
+MonoBehaviour:
+  m_ObjectHideFlags: 0
+  m_CorrespondingSourceObject: {fileID: 0}
+  m_PrefabInstance: {fileID: 0}
+  m_PrefabAsset: {fileID: 0}
+  m_GameObject: {fileID: 2042814726327143098}
+  m_Enabled: 1
+  m_EditorHideFlags: 0
+  m_Script: {fileID: 11500000, guid: 95ea887eb11d7f94eaef9ace0bb62be9, type: 3}
+  m_Name: 
+  m_EditorClassIdentifier: Assembly-CSharp::SpringBones.SpringBonesDriver
 --- !u!114 &8186094461447319126
 MonoBehaviour:
   m_ObjectHideFlags: 0

Assets/Scripts/AangConfiguration.cs

@@ -246,8 +246,8 @@ public static void RecreateFrom(string url)
         foreach (var parameter in split)
         {
             var keyValueSplit = parameter.Split('=');
-            var key = HttpUtility.UrlDecode(keyValueSplit[0]);
-            var value = keyValueSplit.Length > 1 ? HttpUtility.UrlDecode(keyValueSplit[1]) : string.Empty;
+            var key = HttpUtility.UrlDecode(keyValueSplit[0]).Trim();
+            var value = (keyValueSplit.Length > 1 ? HttpUtility.UrlDecode(keyValueSplit[1]) : string.Empty).Trim();
 
             switch (key)
             {
@@ -298,7 +298,7 @@ public static void RecreateFrom(string url)
                     break;
                 case "env":
                     APIService.Environment = value == "dev" ? "zone" : "org";
-                    Debug.Log($"Using environment {APIService.Environment}");
+                    Debug.Log($"Using environment {APIService.Environment} (env value=[{value}])");
                     break;
                 case "disableLoader":
                     Instance.DisableLoader = bool.Parse(value);

Assets/Scripts/Data/ActiveEntityResponse.cs

@@ -43,6 +43,7 @@ public class Data
                 public string[] replaces = Array.Empty<string>();
                 public string[] removesDefaultHiding = Array.Empty<string>();
                 public bool loop; // For emotes only
+                public SpringBonesDto springBones;
             }
 
             [Serializable]

Assets/Scripts/Data/EntityDefinition.cs

@@ -19,8 +19,25 @@ public class EntityDefinition
         public readonly EntityType Type;
         public readonly EntityFlags Flags;
 
+        [CanBeNull] private readonly SpringBonesDto _springBones;
+
         [ItemCanBeNull] private readonly Dictionary<BodyShape, Representation> _representations;
 
+        /// <summary>
+        /// Returns the spring-bone params (boneName → params) declared in the wearable
+        /// metadata for the given body shape's mainFile, or null if none.
+        /// </summary>
+        [CanBeNull]
+        public IReadOnlyDictionary<string, SpringBoneParamsDto> GetSpringBoneParams(BodyShape shape)
+        {
+            if (_springBones?.models == null) return null;
+            if (!HasRepresentation(shape)) return null;
+
+            var mainFileHash = _representations[shape].MainFileHash;
+            if (string.IsNullOrEmpty(mainFileHash)) return null;
+            return _springBones.models.TryGetValue(mainFileHash, out var map) ? map : null;
+        }
+
         public Representation[] GetAllRepresentations()
         {
             // TODO: Cleanup
@@ -48,28 +65,32 @@ public bool HasRepresentation(BodyShape bodyShape)
         public Representation this[BodyShape shape] => _representations[shape] ?? throw new InvalidOperationException(
             $"Missing {shape} representation for {URN}");
 
-        private EntityDefinition(string urn, string category, string thumbnail, EntityType type, EntityFlags flags, Dictionary<BodyShape, Representation> representations)
+        private EntityDefinition(string urn, string category, string thumbnail, EntityType type, EntityFlags flags,
+            Dictionary<BodyShape, Representation> representations, [CanBeNull] SpringBonesDto springBones)
         {
             URN = urn;
             Category = category;
             Thumbnail = thumbnail;
             Type = type;
             _representations = representations;
             Flags = flags;
+            _springBones = springBones;
         }
 
         public class Representation
         {
             public readonly Dictionary<string, string> Files;
             public readonly string MainFile;
+            public readonly string MainFileHash;
             public readonly string[] Hides;
             public readonly string[] RemovesDefaultHiding;
 
-            private Representation(Dictionary<string, string> files, string mainFile, string[] hides,
-                string[] removesDefaultHiding)
+            private Representation(Dictionary<string, string> files, string mainFile, string mainFileHash,
+                string[] hides, string[] removesDefaultHiding)
             {
                 Files = files;
                 MainFile = mainFile;
+                MainFileHash = mainFileHash;
                 Hides = hides;
                 RemovesDefaultHiding = removesDefaultHiding;
             }
@@ -112,9 +133,13 @@ public static Representation ForBodyShape(string bodyShape, ActiveEntity entity)
                         StringComparer.OrdinalIgnoreCase
                     );
 
+                var mainFileHash = entity.content
+                    .FirstOrDefault(c => string.Equals(c.file, main, StringComparison.OrdinalIgnoreCase))?.hash;
+
                 var representation = new Representation(
                     filesDict,
                     entityRepresentation.mainFile,
+                    mainFileHash,
                     entityRepresentation.overrideHides is { Length: > 0 }
                         ? entityRepresentation.overrideHides
                         : data.hides.Union(entityRepresentation.overrideReplaces is { Length: > 0 }
@@ -135,7 +160,7 @@ public static Representation ForEmbeddedEmote(string emote)
                     {
                         ["main"] = Path.Combine(Application.streamingAssetsPath, $"{emote}.glb")
                     },
-                    "main", Array.Empty<string>(),
+                    "main", null, Array.Empty<string>(),
                     Array.Empty<string>()
                 );
             }
@@ -161,7 +186,8 @@ public static EntityDefinition FromActiveEntity(ActiveEntity entity)
                 [BodyShape.Female] = Representation.ForBodyShape(WearablesConstants.BODY_SHAPE_FEMALE, entity)
             };
 
-            return new EntityDefinition(urn, category, thumbnail, type, flags, representations);
+            return new EntityDefinition(urn, category, thumbnail, type, flags, representations,
+                entity.IsEmote ? null : entity.metadata?.data?.springBones);
         }
 
         public static EntityDefinition FromBase64(byte[] b64)
@@ -173,6 +199,23 @@ public static EntityDefinition FromBase64(byte[] b64)
             var raw = JsonUtility.FromJson<RawActiveEntity>(base64String);
             var entity = raw.ToActiveEntity();
 
+            // JsonUtility can't deserialize the nested Dictionary in springBones.models,
+            // so re-parse just that field with Newtonsoft and inject it into the entity.
+            if (!entity.IsEmote && entity.metadata?.data != null)
+            {
+                try
+                {
+                    var jo = Newtonsoft.Json.Linq.JObject.Parse(base64String);
+                    var springBonesToken = jo["data"]?["springBones"];
+                    if (springBonesToken != null)
+                        entity.metadata.data.springBones = springBonesToken.ToObject<SpringBonesDto>();
+                }
+                catch (Exception e)
+                {
+                    Debug.LogError($"[Base64] failed to parse springBones: {e.Message}");
+                }
+            }
+
             return FromActiveEntity(entity);
         }
 
@@ -188,7 +231,8 @@ public static EntityDefinition FromEmbeddedEmote(string emote, bool loop)
                 {
                     [BodyShape.Male] = Representation.ForEmbeddedEmote(emote),
                     [BodyShape.Female] = Representation.ForEmbeddedEmote(emote)
-                }
+                },
+                null
             );
         }
     }

Assets/Scripts/Data/RawActiveEntity.cs

@@ -54,6 +54,14 @@ public class Translation
             public string text;
         }
 
+        static string ExtractHashFromUrl(string url)
+        {
+            if (string.IsNullOrEmpty(url)) return null;
+            var trimmed = url.TrimEnd('/');
+            var slash = trimmed.LastIndexOf('/');
+            return slash >= 0 && slash + 1 < trimmed.Length ? trimmed[(slash + 1)..] : null;
+        }
+
         public ActiveEntity ToActiveEntity()
         {
             var reps = IsEmote ? emoteDataADR74.representations : data.representations;
@@ -64,7 +72,14 @@ public ActiveEntity ToActiveEntity()
                 type = IsEmote ? "emote" : "wearable",
                 content = reps
                     .SelectMany(r => r.contents
-                        .Select(c => new ActiveEntity.Content { file = c.key, url = c.url }))
+                        .Select(c => new ActiveEntity.Content
+                        {
+                            file = c.key,
+                            url = c.url,
+                            // Spring-bone metadata keys models by content hash (CID). The CID is the
+                            // last path segment of the builder-api URL — extract it so the lookup works.
+                            hash = ExtractHashFromUrl(c.url),
+                        }))
                     .GroupBy(c => c.file)
                     .Select(g => g.First())
                     .ToArray(),

Assets/Scripts/Data/SpringBonesDto.cs

@@ -0,0 +1,62 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using Newtonsoft.Json;
+using Newtonsoft.Json.Linq;
+using UnityEngine;
+
+namespace Data
+{
+    [Serializable]
+    public class SpringBonesDto
+    {
+        public int version;
+        public Dictionary<string, Dictionary<string, SpringBoneParamsDto>> models;
+    }
+
+    [Serializable]
+    public class SpringBoneParamsDto
+    {
+        public float stiffness;
+        public float drag;
+
+        [JsonConverter(typeof(Vector3JsonConverter))]
+        public Vector3 gravityDir;
+
+        public float gravityPower;
+        public float hitRadius;
+        public bool isRoot;
+    }
+
+    public class Vector3JsonConverter : JsonConverter<Vector3>
+    {
+        public override void WriteJson(JsonWriter writer, Vector3 value, JsonSerializer serializer)
+        {
+            writer.WriteStartObject();
+            writer.WritePropertyName("x");
+            writer.WriteValue(value.x);
+            writer.WritePropertyName("y");
+            writer.WriteValue(value.y);
+            writer.WritePropertyName("z");
+            writer.WriteValue(value.z);
+            writer.WriteEndObject();
+        }
+
+        public override Vector3 ReadJson(JsonReader reader, Type objectType, Vector3 existingValue, bool hasExistingValue, JsonSerializer serializer)
+        {
+            if (reader.TokenType == JsonToken.Null) return existingValue;
+            var t = JToken.Load(reader);
+            if (t.Type == JTokenType.Array)
+            {
+                return new Vector3(
+                    t.Count() > 0 ? t[0].Value<float>() : 0f,
+                    t.Count() > 1 ? t[1].Value<float>() : 0f,
+                    t.Count() > 2 ? t[2].Value<float>() : 0f);
+            }
+            return new Vector3(
+                t["x"]?.Value<float>() ?? 0f,
+                t["y"]?.Value<float>() ?? 0f,
+                t["z"]?.Value<float>() ?? 0f);
+        }
+    }
+}

Assets/Scripts/Data/SpringBonesDto.cs.meta

@@ -81,6 +81,20 @@ public void SetUrns(string value) =>
     [UsedImplicitly]
     public void SetUsername(string value) => AangConfiguration.Instance.Username = value;
 
+    [UsedImplicitly]
+    public void SetSpringBonesParams(string value)
+    {
+        SpringBones.SpringBonesParamsPayload payload;
+        try { payload = SpringBones.SpringBonesParamsPayload.Parse(value); }
+        catch (Exception e)
+        {
+            Debug.LogError($"[SpringBones] failed to parse SetSpringBonesParams payload: {e.Message}");
+            return;
+        }
+        if (payload == null) return;
+        previewController.SetSpringBonesParams(payload);
+    }
+
     [UsedImplicitly]
     public void GetElementBounds(string elementName) => configuratorUIPresenter.GetElementBounds(elementName);