游戏开发图形学【免费下载链接】spine-runtimes2D skeletal animation runtimes for Spine.项目地址https://gitcode.com/gh_mirrors/sp/spine-runtimes点击查看免费下载com.esotericsoftware.spine.ui-toolkit显示名为Spine UI Toolkit [Experimental]是 spine-unity 运行时的 UI Toolkit 集成插件它为 UI Toolkit 提供一个名为SpineVisualElement的控件元素让 Spine 骨骼动画可以直接嵌入到 UI Toolkit 的 Visual Tree AssetUXML中并通过 UI Builder 像普通 UI 元素一样编排。本文以该模块的官方文档Documentation/README.md为骨架结合仓库中的运行时源码、示例 UXML、材质与着色器完整讲解安装步骤、UI Builder 配置方法、UXML 属性语义、运行时网格生成机制以及 Premultiply-alphaPMA与混合模式相关的限制与最新实现现状。读完本文你将能够独立把 Spine 骨骼角色集成进基于 UI Toolkit 的 Unity 界面系统中。一、插件定位为 spine-unity 补齐 UI Toolkit 支持在 spine-unity 生态中SkeletonGraphic是面向 uGUICanvas / Graphic的骨骼渲染组件。而随着 Unity UI Toolkit 逐步成为新的界面方案官方为此提供了本插件This plugin provides integration of UI Toolkit for the spine-unity runtime. The plugin adds aSpineVisualElementcontrol element to be used with UI Toolkit, providing functionality similar toSkeletonGraphicto add your Spine skeletons to a Visual Tree Asset via UI Toolkits UI Builder.翻译过来即SpineVisualElement承担了「UI Toolkit 版 SkeletonGraphic」的角色可以把骨架直接放进 Visual Tree Asset利用 UI Builder 的可视化编辑能力完成布局与动画配置。文档同时给出使用前提的提醒Please be sure to test this package first and create backups of your project before using.由于该插件标注为 Experimental预览阶段官方文档明确要求先在小范围内测试并备份工程再投入正式项目本文后续所有实操建议也应遵循这一前提。二、环境要求与安装2.1 版本要求根据包的 package.json本插件对运行环境有明确的硬性要求项目要求说明Unity 版本6000.3及以上需要包含一个官方 bugfix涉及部分默认 UXMLConverter 依赖当前文化区域 Culture 的问题因此低版本 Unity 无法正常工作spine-unity 运行时4.3.42或更新package.json 中声明的依赖为com.esotericsoftware.spine.spine-unity: 4.3.86UI Elements 模块com.unity.modules.uielements: 1.0.0UPM 依赖声明用于访问 UI Toolkit API包自身版本为4.3.0-preview.8关键字为spine、ui toolkit、ui、preview这解释了为什么它在 Package Manager 中显示为 Experimental。2.2 安装方式该插件位于仓库的 spine-unity/Modules/com.esotericsoftware.spine.ui-toolkit 目录是一个标准 UPM 包结构含package.json、Runtime/、Editor/、Shaders/、Materials/、Samples~。安装步骤在 Unity 中打开Window ▸ Package Manager点击 ▸ Add package from disk…选择本目录下的package.json完成本地包安装等待依赖解析会自动拉取com.esotericsoftware.spine.spine-unity与com.unity.modules.uielements。提示仓库还提供了 package-no-spine-unity-dependency.json这是一份不声明 spine-unity 依赖的替代清单适用于 spine-unity 已作为其它包被项目引用的场景避免版本冲突。编译层面运行时代码通过 spine-ui-toolkit.asmdef 组织显式引用spine-unity与spine-csharp两个程序集因此安装后会自动参与项目编译无需额外操作。2.3 安装官方示例Samples包内自带示例资源Samples~/Examples在 Package Manager 选中本包后切换Samples标签页即可安装名为Examples的示例。官方文档明确建议For usage of theSpineVisualElementcontrol element, you can check out the includedUI Toolkit Example.unityexample scene andSpineUIToolkit.uxmlfile which can be installed via theSamplestab in the Unity Package Manager window.安装后你会在项目中得到UI Toolkit Example.unity示例场景展示多个SpineVisualElement在界面中的实际渲染效果SpineUIToolkit.uxml示例 Visual Tree Asset即 Samples~/Examples/SpineUIToolkit.uxml示例骨骼资源Spine Skeletons/RaptorRaptor 龙与Spine Skeletons/whirlyblendmodes混合模式演示骨架各自包含_SkeletonData.asset、_Atlas.asset与配套 Material。三、快速上手运行官方示例安装 Samples 后打开UI Toolkit Example.unity即可看到效果。这个场景背后的 UXML 结构非常有参考价值其核心内容节选如下ui:UXML xmlns:uiUnityEngine.UIElements xmlns:uieUnityEditor.UIElements editor-extension-modeFalse ui:VisualElement styleflex-direction: row; flex-wrap: wrap; height: 100%; width: 100%; ui:Label textSpine Visual Element for UI Toolkit .../ ui:VisualElement nameSpineSkeletons styleflex-grow: 1; width: 100%; height: 70%; ... Spine.Unity.SpineVisualElement starting-animationroar skeleton-data-assetproject://database/.../raptor-pro_SkeletonData.asset?... nameSpineVisualElement initial-skin-namedefault multiple-materialsfalse styleheight: 400px; width: 400px; blend-mode-materials Spine.Unity.UITKBlendModeMaterials normal-materialproject://database/Packages/com.esotericsoftware.spine.ui-toolkit/Materials/Spine-UITK-Normal-Straight.mat?.../ /blend-mode-materials /Spine.Unity.SpineVisualElement !-- 第二个 Raptorstarting-animationwalk -- !-- 第三个 Raptorstarting-animationgun-grab -- Spine.Unity.SpineVisualElement starting-animationanimation skeleton-data-asset.../whirlyblendmodes_SkeletonData.asset?... initial-skin-name reference-bounds-0.2435999,0.5221,0,4.56708,3.606879,0 styleheight: 400px; width: 400px; blend-mode-materials Spine.Unity.UITKBlendModeMaterials normal-material.../Spine-UITK-Normal-Straight.mat additive-material.../Spine-UITK-Additive-Straight.mat multiply-material.../Spine-UITK-Multiply-Straight.mat screen-material.../Spine-UITK-Screen-Straight.mat/ /blend-mode-materials /Spine.Unity.SpineVisualElement /ui:VisualElement /ui:VisualElement /ui:UXML从这个示例可以提炼出SpineVisualElement的典型用法直接在 UXML 中声明Spine.Unity.SpineVisualElement元素命名空间Spine.Unity通过skeleton-data-asset绑定 SkeletonDataAsset可指向_SkeletonData.asset资源通过starting-animation指定默认播放的动画名initial-skin-name指定初始皮肤通过style像普通 VisualElement 一样控制尺寸与布局示例中均为height: 400px; width: 400px;通过嵌套的blend-mode-materials子对象配置 Normal/Additive/Multiply/Screen 四个材质的引用。四、在 UI Builder 中配置 SpineVisualElement官方文档给出了 UI Builder 中的具体入口The newSpineVisualElementcan be found in the UnityUI Builderwindow underLibrary - Project - Custom ControlsSpine - Unity - SpineVisualElement. It can be added to your hierarchy and configured as normal UI Toolkit elements while providing Spine skeleton attributes as well.操作路径打开Window ▸ UI Toolkit ▸ UI Builder在左侧Library面板切到Project标签展开Custom Controls找到Spine - Unity - SpineVisualElement直接拖入层级Hierarchy即可。之后布局相关宽度/高度、margin、flex、position 等全部按普通 VisualElement 配置骨骼相关Inspector 中会出现SkeletonDataAsset、Initial Skin Name、Starting Animation、startingLoop、timeScale、unscaledTime、freeze、Multiple Materials、flipBackFaces、Bounds Animation、Reference Bounds等专用属性材质相关Blend Mode Materials区域提供四个材质槽Normal/Additive/Multiply/Screen并带有Detect Materials按钮详见第六节。由于SpineVisualElement用[UxmlElement]/[UxmlAttribute]标注见 SpineVisualElement.cs它在 UI Builder 与 UXML 中都能被正确序列化与识别这也是它能作为自定义控件出现在 UI Builder 里的根本原因。五、UXML 属性速查表与运行时语义SpineVisualElement的核心公开属性均可在 SpineVisualElement.cs 中找到UXML 中的属性名采用 kebab-case 形式。下表为完整速查C# 属性UXML 属性kebab-case类型默认值语义SkeletonDataAssetskeleton-data-assetSkeletonDataAssetnull骨骼数据资源驱动整个元素初始化InitialSkinNameinitial-skin-namestring初始皮肤名编辑器下若名字不存在会回退为defaultStartingAnimationstarting-animationstring运行模式下播放的起始动画startingLoopstarting-loopbooltrue起始动画是否循环timeScaletime-scalefloat1.0动画时间缩放作用于状态更新unscaledTimeunscaled-timeboolfalse使用Time.unscaledDeltaTime推进动画freezefreezeboolfalse冻结更新跳过状态推进与网格刷新MultipleMaterialsmultiple-materialsbooltrue是否按子网格分别使用材质混合模式支持的关键开关flipBackFacesflip-back-facesbooltrue翻转背面图元绕序否则 UI Toolkit 不绘制背面BoundsAnimationbounds-animationstring用于计算参考包围盒的动画编辑器预览用ReferenceBoundsreference-boundsBounds(0,0,0)/(0,0,0)手动指定的参考包围盒用于缩放适配blendModeMaterialsblend-mode-materialsUITKBlendModeMaterialsnew()嵌套 UxmlObject含 4 个材质槽AnimationState—只读属性AnimationState—懒初始化后返回骨骼动画状态供脚本驱动UpdateMode—属性UpdateModeFullUpdate更新粒度控制见 5.35.1 初始化流程Initialize当SkeletonDataAsset、InitialSkinName或StartingAnimation在编辑器中被赋值时且非运行态属性 setter 会触发Initialize(true)。核心初始化逻辑SpineVisualElement.cs依次执行取数据SkeletonDataAsset.GetSkeletonData(false)获取SkeletonData任一环节为空即提前返回校验资源检查atlasAssets.Length 0且首个 Atlas 的MaterialCount 0确保有可用图集材质创建运行时对象new Spine.AnimationState(...)与new Skeleton(skeletonData) { ScaleX 1, ScaleY -1 }——注意ScaleY -1这是因为 UI Toolkit 的坐标系 Y 轴向下骨骼世界坐标需要翻转才能正确显示设置皮肤与动画skeleton.SetSkin(initialSkinName)编辑器非运行态播放boundsAnimation运行态播放startingAnimation通过state.SetAnimation(0, animationObject, startingLoop)计算参考包围盒若ReferenceBounds尚未设置调用AdjustReferenceMeshBounds()注册调度schedule.Execute(Update).Every(1)把每帧Update注册进 UI Toolkit 的调度器约每帧一次这是元素持续驱动动画的驱动源编辑器即时刷新非运行态立即执行一次Update(0.0f)并MarkDirtyRepaint()。5.2 每帧更新链路SpineVisualElement的更新链路SpineVisualElement.cs为Update() / Update(deltaTime) └─ UpdateAnimationStatus(deltaTime) // state.Update(delta * timeScale); skeleton.Update(...) └─ ApplyAnimation() // state.Apply / state.ApplyEventTimelinesOnly UpdateWorldTransform └─ PrepareInstructionsAndRenderers() // 生成 SkeletonRendererInstruction 与子网格分配材质其中Update()无参在运行态根据unscaledTime选择Time.unscaledDeltaTime或Time.deltaTime作为增量编辑器下则退化为Update(0f)不推进时间仅刷新一帧。freeze为true时整个无参Update()直接返回。5.3 UpdateMode 更新粒度UpdateMode枚举定义在 spine-unity 核心的 ISkeletonAnimation.cs注释标明「可选地限制更新例如只应用动画但不更新网格」值说明Nothing不更新Update(float)在小于OnlyAnimationStatus时直接返回OnlyAnimationStatus只推进状态state.Update/skeleton.Update不应用动画、不生成网格OnlyEventTimelines只应用事件时间线state.ApplyEventTimelinesOnly用于只关心事件回调的场景EverythingExceptMesh预留的粒度档位FullUpdate完整链路状态 → 应用动画 → 世界变换 → 网格生成与刷新默认这个枚举与SkeletonGraphic等 spine-unity 组件共用同一套语义便于在不同渲染通道之间保持行为一致。六、网格生成与材质分配的实现细节SpineVisualElement不使用 uGUI 的 Canvas 渲染而是走 UI Toolkit 的generateVisualContent/MeshGenerationContext管线。6.1 子网格与渲染元素每个SpineVisualElement内部维护一组rendererElements绝对定位的透明VisualElement子元素每个子网格submesh对应一个渲染元素SpineVisualElement.cs。MultipleMaterials为true默认时SetActiveRendererCount(submeshCount)会按子网格数量动态增删渲染元素并在AssignBlendModeMaterial中根据图集的混合模式要求为每个渲染元素分配对应材质style.unityMaterial。6.2 顶点/索引填充与 NativeArray 缓冲网格数据生成由 MeshGeneratorUIElements.cs 完成它继承 spine-unity 的MeshGenerator但把输出目标从UnityEngine.Mesh换成 UI Toolkit 的UnityEngine.UIElements.Vertex通过NativeArrayUIVertex/NativeSliceushort。GenerateVisualContentsSpineVisualElement.cs中的关键逻辑meshGenerator.settings.pmaVertexColors false;——顶点色按 straight alpha 语义写入纹理的 PMA 与否交由材质关键字区分见 6.3每个子网格执行Begin()→AddSubmesh()→PrepareUISubmesh()分配/复用NativeArray持久缓冲容量不足时按 2 倍扩容并释放旧缓冲flipBackFaces为true时调用FlipBackfaceWindingOrder()修正背面绕序UI Toolkit 默认不绘制背面图元最后FillContext()通过context.Allocate(...)SetAllVertices/SetAllIndices把数据提交给 UI Toolkit 渲染。6.3 PMA 与混合模式的现状文档限制 vs 源码实现官方 README 明确列出两项限制原文Premultiply-alpha (PMA) atlas textures are not supported due to limitations of the UI ToolkitVisualElementAPI, not allowing custom shaders. Please export your atlas textures as straight alpha to avoid artifacts.Custom slot blend modes (additive, multiply, screen) are not supported due to the same custom shader limitation.即文档声明的结论是① PMA 图集不支持需导出 straight alpha② 自定义混合模式additive / multiply / screen不支持二者都归因于「VisualElement API 不允许自定义 shader」。但从当前仓库源码结构看这一限制很可能对应的是早期预览版本现版本4.3.0-preview.8已出现明显进展自定义 UITK 着色器Shaders/目录下存在 Spine-UITK-Additive.shaderBlend One One、Spine-UITK-Multiply.shaderBlend DstColor OneMinusSrcAlpha、Spine-UITK-Screen.shader以及Spine-UITK-Normal.shadergraph均以uie_custom_vert/uie_custom_frag自定义 UI Toolkit 顶点/片元入口并带有isCustomUITKShader标签说明 UI Toolkit 的自定义 shader 能力已被使用PMA / Straight 双套材质Materials/下共 8 个材质每种混合模式各配-Straight与-PMA两个变体二者仅差一个_StraightAlphaTexture关键字Straight 材质为1PMA 材质为0见 Spine-UITK-Normal-Straight.mat 与 Spine-UITK-Normal-PMA.mat——着色器用该关键字切换对纹理 alpha 的解读方式从而支持 PMA 图集自动检测与分配Editor/SpineVisualElementAttributeDrawers.cs 中的 Inspector 抽屉提供Detect Materials按钮会调用SkeletonGraphicUtility检测图集纹理是否为 PMA再结合skeletonDataAsset.blendModeMaterials.RequiresBlendModeMaterials自动填入对应的 Straight/PMA 材质示例即证示例 UXML 中whirlyblendmodes骨架专用于混合模式演示已同时配置了 Additive/Multiply/Screen 三个混合材质。因此可以推断README 中「不支持 PMA」「不支持混合模式」的表述可能只适用于早期版本当前源码已具备 PMA 纹理与混合模式的支持路径。不过由于该插件仍是 Experimental文档的官方立场并未更新稳妥做法仍是使用前先做小范围验证并备份工程若使用 PMA 图集或混合模式遇到异常回退为 straight alpha Normal 材质是文档推荐的安全方案。七、边界Bounds与自动缩放适配UI Toolkit 元素通过 CSS 布局确定矩形区域而骨骼有自己的包围盒二者需要换算。SpineVisualElement的处理分为两步参考包围盒计算AdjustReferenceMeshBounds()SpineVisualElement.cs先执行一次Update(0f)用MeshGenerator累加所有子网格后取GetMeshBounds()若结果为退化边界extents 为 0会回退为Vector3.one * 2f的默认包围盒避免除零缩放与位移换算AdjustOffsetScaleToMeshBounds()SpineVisualElement.cs按targetRect与参考包围盒的宽高比取min缩放并计算出居中偏移最终写入渲染元素的translate/scale/transformOrigin样式使骨骼在元素矩形内等比居中显示。GeometryChangedEvent回调会在布局变化时自动重算因此元素尺寸被 UI Builder、代码或动画调整后骨骼会跟随适配。编辑器配套的Update Bounds按钮由BoundsFromAnimationAttributeDrawer提供SpineVisualElementAttributeDrawers.cs则基于BoundsAnimationInitialSkinName的组合用SkeletonClipping计算骨架实际包围盒并写回ReferenceBounds若组合导致零包围盒无可见附件会给出明确警告并回退为默认包围盒。这一机制保证了在编辑器里 WYSIWYG 的边界预览。八、注意事项与排障建议结合官方文档的警告与源码实现使用时建议注意以下几点先测试、后备份Experimental 包可能随版本调整 API 与资源结构官方文档反复强调先验证再用于正式项目版本匹配必须使用 Unity6000.3与 spine-unity4.3.42否则 UXML 序列化或 UI Toolkit 管线会出现不可预期行为图集 alpha 选择按文档建议优先导出 straight alpha 图集若必须使用 PMA 图集确认 Blend Mode Materials 四个槽位已填对应的-PMA材质可用 Detect Materials 自动完成混合模式失效排查先确认MultipleMaterials为true再确认blendModeMaterials四槽均已赋值且与图集材质匹配示例中whirlyblendmodes是验证混合模式是否生效的标准素材骨骼不显示按Initialize的校验链逐步检查——SkeletonDataAsset是否有效、atlas 资源与MaterialCount是否 0、皮肤名是否存在编辑器下会自动回退default、reference-bounds是否异常编辑器/运行态动画差异编辑器非运行态播放的是BoundsAnimation用于边界预览运行态才播放StartingAnimation这是设计行为而非 bug。官方示例场景UI Toolkit Example.unity与SpineUIToolkit.uxml是最直接的验证环境遇到任何问题都建议先回到示例上确认是环境问题还是资源配置问题再套用到自己的界面中。赞分享游戏开发图形学【免费下载链接】spine-runtimes2D skeletal animation runtimes for Spine.项目地址https://gitcode.com/gh_mirrors/sp/spine-runtimes点击查看免费下载相关推荐Pixi-Spine终极指南在PixiJS中完美集成Spine骨骼动画Pixi Spine终极指南在PixiJS中完美集成Spine骨骼动画 想要为你的Web应用或游戏添加专业级的2D骨骼动画吗Pixi Spine项目正是你需Spine骨骼动画在Godot引擎中的集成应用指南Spine骨骼动画在Godot引擎中的集成应用指南 还在为Godot项目中复杂的角色动画制作而烦恼吗今天我们要介绍的Spine骨骼动画模块将彻底改变你的动画melonJS Spine 插件实战指南在 HTML5 游戏中集成 Spine 4.3 骨骼动画melonJS Spine 插件实战指南在 HTML5 游戏中集成 Spine 4.3 骨骼动画 导读 melonjs/spine plugin 是 mel游戏开发图形学上一篇doggo 部署方案大全从本地安装到 Docker 容器化部署下一篇git-scribe高级教程自定义样式表与模板实现个性化电子书设计终极指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
游戏开发图形学【免费下载链接】spine-runtimes2D skeletal animation runtimes for Spine.项目地址https://gitcode.com/gh_mirrors/sp/spine-runtimes点击查看免费下载com.esotericsoftware.spine.ui-toolkit显示名为Spine UI Toolkit [Experimental]是 spine-unity 运行时的 UI Toolkit 集成插件它为 UI Toolkit 提供一个名为SpineVisualElement的控件元素让 Spine 骨骼动画可以直接嵌入到 UI Toolkit 的 Visual Tree AssetUXML中并通过 UI Builder 像普通 UI 元素一样编排。本文以该模块的官方文档Documentation/README.md为骨架结合仓库中的运行时源码、示例 UXML、材质与着色器完整讲解安装步骤、UI Builder 配置方法、UXML 属性语义、运行时网格生成机制以及 Premultiply-alphaPMA与混合模式相关的限制与最新实现现状。读完本文你将能够独立把 Spine 骨骼角色集成进基于 UI Toolkit 的 Unity 界面系统中。一、插件定位为 spine-unity 补齐 UI Toolkit 支持在 spine-unity 生态中SkeletonGraphic是面向 uGUICanvas / Graphic的骨骼渲染组件。而随着 Unity UI Toolkit 逐步成为新的界面方案官方为此提供了本插件This plugin provides integration of UI Toolkit for the spine-unity runtime. The plugin adds aSpineVisualElementcontrol element to be used with UI Toolkit, providing functionality similar toSkeletonGraphicto add your Spine skeletons to a Visual Tree Asset via UI Toolkits UI Builder.翻译过来即SpineVisualElement承担了「UI Toolkit 版 SkeletonGraphic」的角色可以把骨架直接放进 Visual Tree Asset利用 UI Builder 的可视化编辑能力完成布局与动画配置。文档同时给出使用前提的提醒Please be sure to test this package first and create backups of your project before using.由于该插件标注为 Experimental预览阶段官方文档明确要求先在小范围内测试并备份工程再投入正式项目本文后续所有实操建议也应遵循这一前提。二、环境要求与安装2.1 版本要求根据包的 package.json本插件对运行环境有明确的硬性要求项目要求说明Unity 版本6000.3及以上需要包含一个官方 bugfix涉及部分默认 UXMLConverter 依赖当前文化区域 Culture 的问题因此低版本 Unity 无法正常工作spine-unity 运行时4.3.42或更新package.json 中声明的依赖为com.esotericsoftware.spine.spine-unity: 4.3.86UI Elements 模块com.unity.modules.uielements: 1.0.0UPM 依赖声明用于访问 UI Toolkit API包自身版本为4.3.0-preview.8关键字为spine、ui toolkit、ui、preview这解释了为什么它在 Package Manager 中显示为 Experimental。2.2 安装方式该插件位于仓库的 spine-unity/Modules/com.esotericsoftware.spine.ui-toolkit 目录是一个标准 UPM 包结构含package.json、Runtime/、Editor/、Shaders/、Materials/、Samples~。安装步骤在 Unity 中打开Window ▸ Package Manager点击 ▸ Add package from disk…选择本目录下的package.json完成本地包安装等待依赖解析会自动拉取com.esotericsoftware.spine.spine-unity与com.unity.modules.uielements。提示仓库还提供了 package-no-spine-unity-dependency.json这是一份不声明 spine-unity 依赖的替代清单适用于 spine-unity 已作为其它包被项目引用的场景避免版本冲突。编译层面运行时代码通过 spine-ui-toolkit.asmdef 组织显式引用spine-unity与spine-csharp两个程序集因此安装后会自动参与项目编译无需额外操作。2.3 安装官方示例Samples包内自带示例资源Samples~/Examples在 Package Manager 选中本包后切换Samples标签页即可安装名为Examples的示例。官方文档明确建议For usage of theSpineVisualElementcontrol element, you can check out the includedUI Toolkit Example.unityexample scene andSpineUIToolkit.uxmlfile which can be installed via theSamplestab in the Unity Package Manager window.安装后你会在项目中得到UI Toolkit Example.unity示例场景展示多个SpineVisualElement在界面中的实际渲染效果SpineUIToolkit.uxml示例 Visual Tree Asset即 Samples~/Examples/SpineUIToolkit.uxml示例骨骼资源Spine Skeletons/RaptorRaptor 龙与Spine Skeletons/whirlyblendmodes混合模式演示骨架各自包含_SkeletonData.asset、_Atlas.asset与配套 Material。三、快速上手运行官方示例安装 Samples 后打开UI Toolkit Example.unity即可看到效果。这个场景背后的 UXML 结构非常有参考价值其核心内容节选如下ui:UXML xmlns:uiUnityEngine.UIElements xmlns:uieUnityEditor.UIElements editor-extension-modeFalse ui:VisualElement styleflex-direction: row; flex-wrap: wrap; height: 100%; width: 100%; ui:Label textSpine Visual Element for UI Toolkit .../ ui:VisualElement nameSpineSkeletons styleflex-grow: 1; width: 100%; height: 70%; ... Spine.Unity.SpineVisualElement starting-animationroar skeleton-data-assetproject://database/.../raptor-pro_SkeletonData.asset?... nameSpineVisualElement initial-skin-namedefault multiple-materialsfalse styleheight: 400px; width: 400px; blend-mode-materials Spine.Unity.UITKBlendModeMaterials normal-materialproject://database/Packages/com.esotericsoftware.spine.ui-toolkit/Materials/Spine-UITK-Normal-Straight.mat?.../ /blend-mode-materials /Spine.Unity.SpineVisualElement !-- 第二个 Raptorstarting-animationwalk -- !-- 第三个 Raptorstarting-animationgun-grab -- Spine.Unity.SpineVisualElement starting-animationanimation skeleton-data-asset.../whirlyblendmodes_SkeletonData.asset?... initial-skin-name reference-bounds-0.2435999,0.5221,0,4.56708,3.606879,0 styleheight: 400px; width: 400px; blend-mode-materials Spine.Unity.UITKBlendModeMaterials normal-material.../Spine-UITK-Normal-Straight.mat additive-material.../Spine-UITK-Additive-Straight.mat multiply-material.../Spine-UITK-Multiply-Straight.mat screen-material.../Spine-UITK-Screen-Straight.mat/ /blend-mode-materials /Spine.Unity.SpineVisualElement /ui:VisualElement /ui:VisualElement /ui:UXML从这个示例可以提炼出SpineVisualElement的典型用法直接在 UXML 中声明Spine.Unity.SpineVisualElement元素命名空间Spine.Unity通过skeleton-data-asset绑定 SkeletonDataAsset可指向_SkeletonData.asset资源通过starting-animation指定默认播放的动画名initial-skin-name指定初始皮肤通过style像普通 VisualElement 一样控制尺寸与布局示例中均为height: 400px; width: 400px;通过嵌套的blend-mode-materials子对象配置 Normal/Additive/Multiply/Screen 四个材质的引用。四、在 UI Builder 中配置 SpineVisualElement官方文档给出了 UI Builder 中的具体入口The newSpineVisualElementcan be found in the UnityUI Builderwindow underLibrary - Project - Custom ControlsSpine - Unity - SpineVisualElement. It can be added to your hierarchy and configured as normal UI Toolkit elements while providing Spine skeleton attributes as well.操作路径打开Window ▸ UI Toolkit ▸ UI Builder在左侧Library面板切到Project标签展开Custom Controls找到Spine - Unity - SpineVisualElement直接拖入层级Hierarchy即可。之后布局相关宽度/高度、margin、flex、position 等全部按普通 VisualElement 配置骨骼相关Inspector 中会出现SkeletonDataAsset、Initial Skin Name、Starting Animation、startingLoop、timeScale、unscaledTime、freeze、Multiple Materials、flipBackFaces、Bounds Animation、Reference Bounds等专用属性材质相关Blend Mode Materials区域提供四个材质槽Normal/Additive/Multiply/Screen并带有Detect Materials按钮详见第六节。由于SpineVisualElement用[UxmlElement]/[UxmlAttribute]标注见 SpineVisualElement.cs它在 UI Builder 与 UXML 中都能被正确序列化与识别这也是它能作为自定义控件出现在 UI Builder 里的根本原因。五、UXML 属性速查表与运行时语义SpineVisualElement的核心公开属性均可在 SpineVisualElement.cs 中找到UXML 中的属性名采用 kebab-case 形式。下表为完整速查C# 属性UXML 属性kebab-case类型默认值语义SkeletonDataAssetskeleton-data-assetSkeletonDataAssetnull骨骼数据资源驱动整个元素初始化InitialSkinNameinitial-skin-namestring初始皮肤名编辑器下若名字不存在会回退为defaultStartingAnimationstarting-animationstring运行模式下播放的起始动画startingLoopstarting-loopbooltrue起始动画是否循环timeScaletime-scalefloat1.0动画时间缩放作用于状态更新unscaledTimeunscaled-timeboolfalse使用Time.unscaledDeltaTime推进动画freezefreezeboolfalse冻结更新跳过状态推进与网格刷新MultipleMaterialsmultiple-materialsbooltrue是否按子网格分别使用材质混合模式支持的关键开关flipBackFacesflip-back-facesbooltrue翻转背面图元绕序否则 UI Toolkit 不绘制背面BoundsAnimationbounds-animationstring用于计算参考包围盒的动画编辑器预览用ReferenceBoundsreference-boundsBounds(0,0,0)/(0,0,0)手动指定的参考包围盒用于缩放适配blendModeMaterialsblend-mode-materialsUITKBlendModeMaterialsnew()嵌套 UxmlObject含 4 个材质槽AnimationState—只读属性AnimationState—懒初始化后返回骨骼动画状态供脚本驱动UpdateMode—属性UpdateModeFullUpdate更新粒度控制见 5.35.1 初始化流程Initialize当SkeletonDataAsset、InitialSkinName或StartingAnimation在编辑器中被赋值时且非运行态属性 setter 会触发Initialize(true)。核心初始化逻辑SpineVisualElement.cs依次执行取数据SkeletonDataAsset.GetSkeletonData(false)获取SkeletonData任一环节为空即提前返回校验资源检查atlasAssets.Length 0且首个 Atlas 的MaterialCount 0确保有可用图集材质创建运行时对象new Spine.AnimationState(...)与new Skeleton(skeletonData) { ScaleX 1, ScaleY -1 }——注意ScaleY -1这是因为 UI Toolkit 的坐标系 Y 轴向下骨骼世界坐标需要翻转才能正确显示设置皮肤与动画skeleton.SetSkin(initialSkinName)编辑器非运行态播放boundsAnimation运行态播放startingAnimation通过state.SetAnimation(0, animationObject, startingLoop)计算参考包围盒若ReferenceBounds尚未设置调用AdjustReferenceMeshBounds()注册调度schedule.Execute(Update).Every(1)把每帧Update注册进 UI Toolkit 的调度器约每帧一次这是元素持续驱动动画的驱动源编辑器即时刷新非运行态立即执行一次Update(0.0f)并MarkDirtyRepaint()。5.2 每帧更新链路SpineVisualElement的更新链路SpineVisualElement.cs为Update() / Update(deltaTime) └─ UpdateAnimationStatus(deltaTime) // state.Update(delta * timeScale); skeleton.Update(...) └─ ApplyAnimation() // state.Apply / state.ApplyEventTimelinesOnly UpdateWorldTransform └─ PrepareInstructionsAndRenderers() // 生成 SkeletonRendererInstruction 与子网格分配材质其中Update()无参在运行态根据unscaledTime选择Time.unscaledDeltaTime或Time.deltaTime作为增量编辑器下则退化为Update(0f)不推进时间仅刷新一帧。freeze为true时整个无参Update()直接返回。5.3 UpdateMode 更新粒度UpdateMode枚举定义在 spine-unity 核心的 ISkeletonAnimation.cs注释标明「可选地限制更新例如只应用动画但不更新网格」值说明Nothing不更新Update(float)在小于OnlyAnimationStatus时直接返回OnlyAnimationStatus只推进状态state.Update/skeleton.Update不应用动画、不生成网格OnlyEventTimelines只应用事件时间线state.ApplyEventTimelinesOnly用于只关心事件回调的场景EverythingExceptMesh预留的粒度档位FullUpdate完整链路状态 → 应用动画 → 世界变换 → 网格生成与刷新默认这个枚举与SkeletonGraphic等 spine-unity 组件共用同一套语义便于在不同渲染通道之间保持行为一致。六、网格生成与材质分配的实现细节SpineVisualElement不使用 uGUI 的 Canvas 渲染而是走 UI Toolkit 的generateVisualContent/MeshGenerationContext管线。6.1 子网格与渲染元素每个SpineVisualElement内部维护一组rendererElements绝对定位的透明VisualElement子元素每个子网格submesh对应一个渲染元素SpineVisualElement.cs。MultipleMaterials为true默认时SetActiveRendererCount(submeshCount)会按子网格数量动态增删渲染元素并在AssignBlendModeMaterial中根据图集的混合模式要求为每个渲染元素分配对应材质style.unityMaterial。6.2 顶点/索引填充与 NativeArray 缓冲网格数据生成由 MeshGeneratorUIElements.cs 完成它继承 spine-unity 的MeshGenerator但把输出目标从UnityEngine.Mesh换成 UI Toolkit 的UnityEngine.UIElements.Vertex通过NativeArrayUIVertex/NativeSliceushort。GenerateVisualContentsSpineVisualElement.cs中的关键逻辑meshGenerator.settings.pmaVertexColors false;——顶点色按 straight alpha 语义写入纹理的 PMA 与否交由材质关键字区分见 6.3每个子网格执行Begin()→AddSubmesh()→PrepareUISubmesh()分配/复用NativeArray持久缓冲容量不足时按 2 倍扩容并释放旧缓冲flipBackFaces为true时调用FlipBackfaceWindingOrder()修正背面绕序UI Toolkit 默认不绘制背面图元最后FillContext()通过context.Allocate(...)SetAllVertices/SetAllIndices把数据提交给 UI Toolkit 渲染。6.3 PMA 与混合模式的现状文档限制 vs 源码实现官方 README 明确列出两项限制原文Premultiply-alpha (PMA) atlas textures are not supported due to limitations of the UI ToolkitVisualElementAPI, not allowing custom shaders. Please export your atlas textures as straight alpha to avoid artifacts.Custom slot blend modes (additive, multiply, screen) are not supported due to the same custom shader limitation.即文档声明的结论是① PMA 图集不支持需导出 straight alpha② 自定义混合模式additive / multiply / screen不支持二者都归因于「VisualElement API 不允许自定义 shader」。但从当前仓库源码结构看这一限制很可能对应的是早期预览版本现版本4.3.0-preview.8已出现明显进展自定义 UITK 着色器Shaders/目录下存在 Spine-UITK-Additive.shaderBlend One One、Spine-UITK-Multiply.shaderBlend DstColor OneMinusSrcAlpha、Spine-UITK-Screen.shader以及Spine-UITK-Normal.shadergraph均以uie_custom_vert/uie_custom_frag自定义 UI Toolkit 顶点/片元入口并带有isCustomUITKShader标签说明 UI Toolkit 的自定义 shader 能力已被使用PMA / Straight 双套材质Materials/下共 8 个材质每种混合模式各配-Straight与-PMA两个变体二者仅差一个_StraightAlphaTexture关键字Straight 材质为1PMA 材质为0见 Spine-UITK-Normal-Straight.mat 与 Spine-UITK-Normal-PMA.mat——着色器用该关键字切换对纹理 alpha 的解读方式从而支持 PMA 图集自动检测与分配Editor/SpineVisualElementAttributeDrawers.cs 中的 Inspector 抽屉提供Detect Materials按钮会调用SkeletonGraphicUtility检测图集纹理是否为 PMA再结合skeletonDataAsset.blendModeMaterials.RequiresBlendModeMaterials自动填入对应的 Straight/PMA 材质示例即证示例 UXML 中whirlyblendmodes骨架专用于混合模式演示已同时配置了 Additive/Multiply/Screen 三个混合材质。因此可以推断README 中「不支持 PMA」「不支持混合模式」的表述可能只适用于早期版本当前源码已具备 PMA 纹理与混合模式的支持路径。不过由于该插件仍是 Experimental文档的官方立场并未更新稳妥做法仍是使用前先做小范围验证并备份工程若使用 PMA 图集或混合模式遇到异常回退为 straight alpha Normal 材质是文档推荐的安全方案。七、边界Bounds与自动缩放适配UI Toolkit 元素通过 CSS 布局确定矩形区域而骨骼有自己的包围盒二者需要换算。SpineVisualElement的处理分为两步参考包围盒计算AdjustReferenceMeshBounds()SpineVisualElement.cs先执行一次Update(0f)用MeshGenerator累加所有子网格后取GetMeshBounds()若结果为退化边界extents 为 0会回退为Vector3.one * 2f的默认包围盒避免除零缩放与位移换算AdjustOffsetScaleToMeshBounds()SpineVisualElement.cs按targetRect与参考包围盒的宽高比取min缩放并计算出居中偏移最终写入渲染元素的translate/scale/transformOrigin样式使骨骼在元素矩形内等比居中显示。GeometryChangedEvent回调会在布局变化时自动重算因此元素尺寸被 UI Builder、代码或动画调整后骨骼会跟随适配。编辑器配套的Update Bounds按钮由BoundsFromAnimationAttributeDrawer提供SpineVisualElementAttributeDrawers.cs则基于BoundsAnimationInitialSkinName的组合用SkeletonClipping计算骨架实际包围盒并写回ReferenceBounds若组合导致零包围盒无可见附件会给出明确警告并回退为默认包围盒。这一机制保证了在编辑器里 WYSIWYG 的边界预览。八、注意事项与排障建议结合官方文档的警告与源码实现使用时建议注意以下几点先测试、后备份Experimental 包可能随版本调整 API 与资源结构官方文档反复强调先验证再用于正式项目版本匹配必须使用 Unity6000.3与 spine-unity4.3.42否则 UXML 序列化或 UI Toolkit 管线会出现不可预期行为图集 alpha 选择按文档建议优先导出 straight alpha 图集若必须使用 PMA 图集确认 Blend Mode Materials 四个槽位已填对应的-PMA材质可用 Detect Materials 自动完成混合模式失效排查先确认MultipleMaterials为true再确认blendModeMaterials四槽均已赋值且与图集材质匹配示例中whirlyblendmodes是验证混合模式是否生效的标准素材骨骼不显示按Initialize的校验链逐步检查——SkeletonDataAsset是否有效、atlas 资源与MaterialCount是否 0、皮肤名是否存在编辑器下会自动回退default、reference-bounds是否异常编辑器/运行态动画差异编辑器非运行态播放的是BoundsAnimation用于边界预览运行态才播放StartingAnimation这是设计行为而非 bug。官方示例场景UI Toolkit Example.unity与SpineUIToolkit.uxml是最直接的验证环境遇到任何问题都建议先回到示例上确认是环境问题还是资源配置问题再套用到自己的界面中。赞分享游戏开发图形学【免费下载链接】spine-runtimes2D skeletal animation runtimes for Spine.项目地址https://gitcode.com/gh_mirrors/sp/spine-runtimes点击查看免费下载相关推荐Pixi-Spine终极指南在PixiJS中完美集成Spine骨骼动画Pixi Spine终极指南在PixiJS中完美集成Spine骨骼动画 想要为你的Web应用或游戏添加专业级的2D骨骼动画吗Pixi Spine项目正是你需Spine骨骼动画在Godot引擎中的集成应用指南Spine骨骼动画在Godot引擎中的集成应用指南 还在为Godot项目中复杂的角色动画制作而烦恼吗今天我们要介绍的Spine骨骼动画模块将彻底改变你的动画melonJS Spine 插件实战指南在 HTML5 游戏中集成 Spine 4.3 骨骼动画melonJS Spine 插件实战指南在 HTML5 游戏中集成 Spine 4.3 骨骼动画 导读 melonjs/spine plugin 是 mel游戏开发图形学上一篇doggo 部署方案大全从本地安装到 Docker 容器化部署下一篇git-scribe高级教程自定义样式表与模板实现个性化电子书设计终极指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
