[unity] Added automatic load balancing for threading system for improved performance. Closes #3012.

Author: HaraldCsaszar

CHANGELOG.md

@@ -364,6 +364,8 @@
   - Added `SkeletonUpdateSystem.Instance.GroupRenderersBySkeletonType` and `GroupAnimationBySkeletonType` properties. Defaults to disabled. Later when smart partitioning is implemented, enabling this parameter might slightly improve cache locality. Until then having it enabled combined with different skeleton complexity would lead to worse load balancing.
   - Added previously missing editor drag & drop skeleton instantiation option *SkeletonGraphic (UI) Mecanim* combining components `SkeletonGraphic` and `SkeletonMecanim`.
   - Added define `SPINE_DISABLE_THREADING` to disable threaded animation and mesh generation entirely, removing the respective code. This define can be set as `Scripting Define Symbols` globally or for selective build profiles where desired.
+  - Added automatic load balancing (work stealing) for improved performance when using threaded animation and mesh generation, enabled by default. Load balancing can be disabled via a new Spine preferences parameter `Threading Defaults - Load Balancing` setting a build define accordingly. 
+    Additional configuration parameters `SkeletonUpdateSystem.UpdateChunksPerThread` and `LateUpdateChunksPerThread` are available to fine-tune the chunk count for load balancing. A minimum of 8 chunks is recommended with load balancing enabled. Higher values add higher overhead with potentially detrimental effect on performance.
 
 - **Deprecated**
 

spine-unity/Assets/Spine/Editor/spine-unity/Editor/Utility/BuildSettings.cs

@@ -86,6 +86,7 @@ public static class SpineBuildEnvUtility {
 		public const string SPINE_ALLOW_UNSAFE_CODE = "SPINE_ALLOW_UNSAFE";
 		public const string SPINE_AUTO_UPGRADE_COMPONENTS_OFF = "SPINE_AUTO_UPGRADE_COMPONENTS_OFF";
 		public const string SPINE_ENABLE_THREAD_PROFILING = "SPINE_ENABLE_THREAD_PROFILING";
+		public const string SPINE_DISABLE_LOAD_BALANCING = "SPINE_DISABLE_LOAD_BALANCING";
 
 		static bool IsInvalidGroup (BuildTargetGroup group) {
 			int gi = (int)group;

spine-unity/Assets/Spine/Editor/spine-unity/Editor/Utility/Preferences.cs

@@ -512,6 +512,18 @@ public static void HandlePreferencesGUI () {
 						() => RuntimeSettings.UseThreadedAnimation, value => RuntimeSettings.UseThreadedAnimation = value,
 						new GUIContent("Threaded Animation", "Global setting for the equally named SkeletonAnimation and SkeletonGraphic Inspector parameter."));
 
+#if SPINE_DISABLE_LOAD_BALANCING
+					bool loadBalancingEnabled = false;
+#else
+					bool loadBalancingEnabled = true;
+#endif
+					using (new GUILayout.HorizontalScope()) {
+						EditorGUILayout.PrefixLabel(new GUIContent("Load Balancing",
+							"Enable load balancing to better utilize threads." +
+							"Only has an effect when using threaded animation or threaded mesh generation."));
+						EnableDisableDefineButtons(SpineBuildEnvUtility.SPINE_DISABLE_LOAD_BALANCING, loadBalancingEnabled, invert: true);
+					}
+
 #if ALLOWS_CUSTOM_PROFILING
 #if SPINE_ENABLE_THREAD_PROFILING
 					bool threadProfilingEnabled = true;

spine-unity/Assets/Spine/Editor/spine-unity/Editor/Windows/SpinePreferences.cs

@@ -522,6 +522,19 @@ public static void HandlePreferencesGUI (SerializedObject settings) {
 						() => RuntimeSettings.UseThreadedAnimation, value => RuntimeSettings.UseThreadedAnimation = value,
 						new GUIContent("Threaded Animation", "Global setting for the equally named SkeletonAnimation and SkeletonGraphic Inspector parameter."));
 
+#if SPINE_DISABLE_LOAD_BALANCING
+					bool loadBalancingEnabled = false;
+#else
+					bool loadBalancingEnabled = true;
+#endif
+					using (new GUILayout.HorizontalScope()) {
+						EditorGUILayout.PrefixLabel(new GUIContent("Load Balancing",
+							"Enable load balancing to better utilize threads." +
+							"Only has an effect when using threaded animation or threaded mesh generation."));
+						SpineEditorUtilities.EnableDisableDefineButtons(SpineBuildEnvUtility.SPINE_DISABLE_LOAD_BALANCING,
+							loadBalancingEnabled, invert: true);
+					}
+
 #if ALLOWS_CUSTOM_PROFILING
 #if SPINE_ENABLE_THREAD_PROFILING
 					bool threadProfilingEnabled = true;

spine-unity/Assets/Spine/Runtime/spine-unity/Threading/CircularArray.cs

@@ -0,0 +1,67 @@
+/******************************************************************************
+ * Spine Runtimes License Agreement
+ * Last updated July 28, 2023. Replaces all prior versions.
+ *
+ * Copyright (c) 2013-2025, Esoteric Software LLC
+ *
+ * Integration of the Spine Runtimes into software or otherwise creating
+ * derivative works of the Spine Runtimes is permitted under the terms and
+ * conditions of Section 2 of the Spine Editor License Agreement:
+ * http://esotericsoftware.com/spine-editor-license
+ *
+ * Otherwise, it is permitted to integrate the Spine Runtimes into software or
+ * otherwise create derivative works of the Spine Runtimes (collectively,
+ * "Products"), provided that each user of the Products must obtain their own
+ * Spine Editor license and redistribution of the Products in any form must
+ * include this license and copyright notice.
+ *
+ * THE SPINE RUNTIMES ARE PROVIDED BY ESOTERIC SOFTWARE LLC "AS IS" AND ANY
+ * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+ * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ * DISCLAIMED. IN NO EVENT SHALL ESOTERIC SOFTWARE LLC BE LIABLE FOR ANY
+ * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+ * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES,
+ * BUSINESS INTERRUPTION, OR LOSS OF USE, DATA, OR PROFITS) HOWEVER CAUSED AND
+ * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THE
+ * SPINE RUNTIMES, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ *****************************************************************************/
+
+using System;
+using System.Threading;
+
+/// <summary>
+/// An array with wrap-around access for LockFreeWorkStealingDeque based on the paper
+/// "Dynamic Circular Work-Stealing Deque", authors David Chase and Yossi Lev.
+/// https://www.dre.vanderbilt.edu/~schmidt/PDF/work-stealing-dequeue.pdf
+/// Modified to support negative indices.
+/// </summary>
+public class CircularArray<T> {
+	private int size;
+	private T[] segment;
+	private uint mask;
+
+	public int Size { get { return size; } }
+
+	public CircularArray (int sizePoT) {
+		this.size = sizePoT;
+		segment = new T[sizePoT];
+		mask = (uint)(sizePoT - 1);
+	}
+
+	public T Get (int i) {
+		return this.segment[((uint)i) & mask];
+	}
+
+	public void Put (int i, T item) {
+		this.segment[((uint)i) & mask] = item;
+	}
+
+	public CircularArray<T> Grow (int b, int t, int newSizePoT) {
+		CircularArray<T> a = new CircularArray<T>(newSizePoT);
+		for (int i = t; i < b; i++) {
+			a.Put(i, this.Get(i));
+		}
+		return a;
+	}
+}

spine-unity/Assets/Spine/Runtime/spine-unity/Threading/CircularArray.cs.meta

@@ -2,7 +2,7 @@
  * Spine Runtimes License Agreement
  * Last updated July 28, 2023. Replaces all prior versions.
  *
- * Copyright (c) 2013-2024, Esoteric Software LLC
+ * Copyright (c) 2013-2025, Esoteric Software LLC
  *
  * Integration of the Spine Runtimes into software or otherwise creating
  * derivative works of the Spine Runtimes is permitted under the terms and

spine-unity/Assets/Spine/Runtime/spine-unity/Threading/LockFreeSPSCQueue.cs

@@ -0,0 +1,141 @@
+/******************************************************************************
+ * Spine Runtimes License Agreement
+ * Last updated July 28, 2023. Replaces all prior versions.
+ *
+ * Copyright (c) 2013-2025, Esoteric Software LLC
+ *
+ * Integration of the Spine Runtimes into software or otherwise creating
+ * derivative works of the Spine Runtimes is permitted under the terms and
+ * conditions of Section 2 of the Spine Editor License Agreement:
+ * http://esotericsoftware.com/spine-editor-license
+ *
+ * Otherwise, it is permitted to integrate the Spine Runtimes into software or
+ * otherwise create derivative works of the Spine Runtimes (collectively,
+ * "Products"), provided that each user of the Products must obtain their own
+ * Spine Editor license and redistribution of the Products in any form must
+ * include this license and copyright notice.
+ *
+ * THE SPINE RUNTIMES ARE PROVIDED BY ESOTERIC SOFTWARE LLC "AS IS" AND ANY
+ * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+ * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ * DISCLAIMED. IN NO EVENT SHALL ESOTERIC SOFTWARE LLC BE LIABLE FOR ANY
+ * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+ * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES,
+ * BUSINESS INTERRUPTION, OR LOSS OF USE, DATA, OR PROFITS) HOWEVER CAUSED AND
+ * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THE
+ * SPINE RUNTIMES, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ *****************************************************************************/
+
+using System.Threading;
+
+/// <summary>
+/// A generic lock-free deque supporting work-stealing based on the paper
+/// "Dynamic Circular Work-Stealing Deque", authors David Chase and Yossi Lev
+/// https://www.dre.vanderbilt.edu/~schmidt/PDF/work-stealing-dequeue.pdf.
+/// Requires that Push and Pop are called from the same thread.
+/// Simplified by not supporting growing the array size during a Push,
+/// in our usage scenario we populate tasks ahead of time before the first Pop.
+/// </summary>
+public class LockFreeWorkStealingDeque<T> {
+	public static readonly T Empty = default(T);
+	public static readonly T Abort = default(T);
+
+	private /*volatile*/ CircularArray<T> activeArray;
+	private volatile int bottom = 0;
+	private volatile int top = 0;
+
+	public int Capacity { get { return activeArray.Size; } }
+
+	public LockFreeWorkStealingDeque (int capacity) {
+		capacity = UnityEngine.Mathf.NextPowerOfTwo(capacity);
+		activeArray = new CircularArray<T>(capacity);
+		bottom = 0;
+		top = 0;
+	}
+
+	/// <summary>Push an element (at the bottom), has to be called by owner of the deque, not a thief.</summary>
+	public void Push (T item) {
+		int b = bottom;
+		int t = top;
+		CircularArray<T> a = this.activeArray;
+		int size = b - t;
+		if (size >= a.Size - 1) {
+			a = a.Grow(b, t, a.Size * 2);
+			this.activeArray = a;
+		}
+		a.Put(b, item);
+		bottom = b + 1;
+	}
+
+	/// <summary>Non-standard addition for ahead-of-time pushing to maintain queue FIFO order.
+	/// Push an element at the top, must only be called before any other thread calls Push, Pop or Steal.</summary>
+	public void PushTop (T item) {
+		int b = bottom;
+		int t = top;
+		CircularArray<T> a = this.activeArray;
+		int size = b - t;
+		if (size >= a.Size - 1) {
+			a = a.Grow(b, t, a.Size * 2);
+			this.activeArray = a;
+		}
+		int newT = t - 1;
+		a.Put(newT, item);
+		top = newT;
+	}
+
+	/// <summary>
+	/// Makes a different worker than the owner steal an element (from the top).
+	/// Returns false if empty.
+	/// </summary>
+	public bool Steal (out T item) {
+		int t = top;
+		int b = bottom;
+		CircularArray<T> a = this.activeArray;
+		int size = b - t;
+		if (size <= 0) {
+			item = Empty;
+			return false;
+		}
+		T o = a.Get(t);
+		// increment top
+		if (Interlocked.CompareExchange(ref top, t + 1, t) != t) {
+			item = Abort;
+			return false;
+		}
+		item = o;
+		return true;
+	}
+
+	/// <summary>Pop an element (from the bottom), has to be called by owner of the deque, not a thief.</summary>
+	/// <returns>false if empty.</returns>
+	public bool Pop (out T item) {
+		int b = bottom;
+		CircularArray<T> a = this.activeArray;
+		--b;
+		this.bottom = b;
+		int t = top;
+		int size = b - t;
+		if (size < 0) {
+			bottom = t;
+			item = Empty;
+			return false;
+		}
+		T o = a.Get(b);
+		if (size > 0) {
+			item = o;
+			return true;
+		}
+
+		bool wasSuccessful = true;
+		if (Interlocked.CompareExchange(ref top, t + 1, t) != t) {
+			item = Empty;
+			wasSuccessful = false;
+		}
+		else {
+			item = o;
+		}
+		bottom = t + 1;
+		return wasSuccessful;
+	}
+}