人工智能AI AgentMCP 服务工具调用GUI 自动化语音数字人交互助手【免费下载链接】airi 自托管、归你拥有的 Grok 风格 AI 伴侣与 waifu / 赛博生命灵魂容器目标是接近 Neuro-sama 的高度支持实时语音聊天、Minecraft 和 Factorio 游玩支持 Web / macOS / Windows。项目地址https://gitcode.com/moeru-ai/airi点击查看免费下载本指南以当前仓库中 vendored 的 V-Sekai godot-vrm 插件位于 engines/stage-tamagotchi-godot/addons/vrm为主体系统讲解该插件在 Godot Engine 4.x 下对 VRM 格式的完整支持能力从 VRM 0.0 / 1.0 导入、VRM 1.0 导出、MToon 材质与 SpringBone 弹簧骨骼到头部隐藏Head Hiding等第一人称相关设置。读完本文你将掌握如何在 Godot 项目中安装启用该插件、理解各导入选项与运行时属性的真实含义并能对照 Airi 项目stage-tamagotchi-godotGodot 舞台的源码了解如何在运行时非编辑器侧实现 VRM 模型的热加载。VRM 是什么面向 VR 应用的人形化身体格式VRM 是用于承载 VR 应用中 3D 人形化身3D model数据的一种文件格式其基础是 glTF 2.0。任何人都可以自由使用。glTF 保证了几何、材质与动画的基础表达能力VRM 则在 glTF 之上补充了 VR 场景所需的人形化约束人类骨骼映射Humanoid、表情 BlendShapemood / viseme、视线追踪LookAt、第一人称头部隐藏、SpringBone 物理模拟以及作者版权信息等。在 Airi 项目中这一插件被 vendored 到 Godot 引擎舞台stage-tamagotchi-godot承担虚拟角色AI 伴侣/赛博生命模型的加载与渲染。项目通过git-subrepo元数据记录了上游来源addons/vrm插件版本2.0.1对应only-addon分支提交651205484c35f5cd7ba56475ff636e10db8ad674见 engines/stage-tamagotchi-godot/README.md 的 VRM Runtime Import 一节。功能支持矩阵导入、导出与各 VRMC 扩展插件同时实现了 VRM 模型的导入器importer与导出器exporter覆盖到 VRM 1.0。按原文档整理的功能矩阵如下能力状态说明VRM 0.0 导入✅ 已实现导入时会转换为 VRM 1.0 兼容的命名VRM 1.0 导入✅ 已实现—VRM 导出.vrm✅ 已实现所有模型统一按 VRM 1.0 导出glTF 导出.gltf带 VRM 1.0 扩展✅ 支持支持VRMC_node_constraint、VRMC_materials_mtoon⚠️ 独立的非.vrm.gltf导出不支持VRMC_springBoneVRMC_materials_mtoon✅ 已实现MToon 材质系统VRMC_node_constraint⚠️ 存在缺陷与 retargeting 组合时已知有问题VRMC_springBone✅ 已实现已可用但需要进一步优化VRMC_materials_hdr_emissive✅ 已实现HDR 自发光材质VRMC_vrm✅ 已实现顶层 VRM 扩展详见下文分解VRMC_vrm内部的子能力分解firstPerson头部隐藏已实现并作为导入选项提供支持运行阶段需要相机分层或运行时脚本配合eyeOffset已实现表现为挂在Head骨上的BoneAttachment3D节点LookOffsetlookAt⚠️ 仅生成动画轨道应用层需要自行创建BlendSpace2D才能使用expressionsmood、viseme 表情BlendShape/binds 与材质颜色/UV 偏移均已实现生成面向BlendTreeAdd2模式的动画轨道humanoid已实现使用%GeneralSkeleton与SkeletonProfileHumanoid兼容的 retargeting 机制Metadata元数据已实现包括 License 信息与缩略图。从源码看插件的结构功能矩阵并非空谈可以在插件源码中逐一印证。编辑器插件入口 plugin.gd 在_enter_tree()中完成了一系列关键注册GLTFDocument.register_gltf_document_extension(VRMC_vrm_inst) GLTFDocument.register_gltf_document_extension(VRMC_node_constraint_inst) GLTFDocument.register_gltf_document_extension(VRMC_springBone_inst) GLTFDocument.register_gltf_document_extension(VRMC_materials_hdr_emissiveMultiplier_inst) GLTFDocument.register_gltf_document_extension(VRMC_materials_mtoon_inst) import_plugin preload(./import_vrm.gd).new() add_scene_format_importer_plugin(import_plugin)其中import_vrm.gd声明_get_recognized_extensions()返回[vrm]因此.vrm文件会被识别为可导入场景。值得注意的是plugin.gd中VRMC_vrm_animation的注册被注释掉了这正对应文档 Future work 一节VRMC_vrm_animation尚未实现其预期用途是支持 humanoid 动画库AnimationLibrary的导入/导出。plugin.cfg中登记的插件元信息为nameVRM、descriptionVRM Importer、version2.0.1、scriptplugin.gd见 engines/stage-tamagotchi-godot/addons/vrm/plugin.cfg。VRM 0.0 与 1.0 两条解析路径插件在 vrm_extension.gd 中处理 VRM 0.0glTF 扩展键VRM在 addons/vrm/1.0 目录下分别实现 VRM 1.0 的VRMC_vrm、VRMC_springBone、VRMC_materials_mtoon、VRMC_node_constraint、VRMC_materials_hdr_emissiveMultiplier与尚未启用的VRMC_vrm_animation。两条路径都会在导入完成后把根节点挂上vrm_toplevel.gd脚本VRMTopLevel并把元数据资源写入vrm_meta属性见 vrm_toplevel.gd 与 vrm_meta.gd。VRM 0.0 与 1.0 的元数据字段存在差异0.0 使用licenseName如CC0、CC_BY_NC、Redistribution_Prohibited等1.0 则改用licenseUrl与thirdPartyLicenses。VRMC_vrm.gd的_create_meta会完成映射例如把 1.0 的avatarPermission: onlyAuthor转换为 0.0 风格的OnlyAuthor、把commercialUsage: corporation转换为AllowCorporation见 addons/vrm/1.0/VRMC_vrm.gd。VRM 0.0 导入时的特有处理从vrm_extension.gd的_import_post可以看到 VRM 0.0 独有的两处修正朝向修正VRM 0.0 因规范失误导致模型默认背向z 翻转而非 x 翻转导入时通过vrm_utils.rotate_scene_180(...)将整个场景旋转 180°骨骼命名转换VRM 0.0 的拇指链命名与 1.0 不同。vrm_constants.gd中get_vrm_to_human_bone(is_vrm_0)会把leftThumbIntermediate映射到LeftThumbProximal、leftThumbProximal映射到LeftThumbMetacarpal从而统一到 VRM 1.0 兼容命名见 vrm_constants.gd。此外vrm_extension.gd中的vrm0_to_vrm1_presets字典将 VRM 0.0 的表情预设名转换为 1.0 风格joy→happy、angry→angry、sorrow→sad、fun→relaxed、a→aa、i→ih、u→ou、e→ee、o→oh、blink→blink、blink_l→blinkLeft、blink_r→blinkRight以及lookup/lookdown/lookleft/lookright→lookUp/lookDown/lookLeft/lookRight。这正是文档所说转换为 VRM 1.0 兼容命名的落点。头部隐藏Head Hiding设置详解头部隐藏是 VRM 为第一人称视角设计的核心特性当玩家以第一人称视角观看时角色的头部网格可能遮挡视线应当被隐藏。插件在导入时提供了专门的场景导入设置scene import options。导入设置Import Optionsvrm_options_post_import_plugin.gd通过_get_import_options注册了三个导入选项见 vrm_options_post_import_plugin.gd选项键类型默认值说明vrm/head_hiding_methodint枚举0ThirdPersonOnly头部隐藏模式vrm/only_if_head_hiding_uses_layers/first_person_layersint3D 渲染层2第一人称使用的 MeshInstance3D layer 位vrm/only_if_head_hiding_uses_layers/third_person_layersint3D 渲染层4第三人称使用的 MeshInstance3D layer 位head_hiding_method的枚举值定义在 vrm_constants.gd 的enum HeadHidingSetting值枚举名行为0ThirdPersonOnly仅保留第三人称视角所需网格1FirstPersonOnly仅保留第一人称视角所需网格2FirstPersonOnlyWithShadow第一人称 阴影补充网格3BothLayers同时保留第一/第三人称两层4BothLayersWithShadow两层 阴影补充网格5IgnoreHeadHiding忽略 firstPerson 标记按普通 glTF 导入处理运行时属性Runtime Usage在运行时导入时头部隐藏模式由GLTFState对象上的附加数据属性决定与编辑器导入选项一一对应vrm/head_hiding_methodvrm_constants.HeadHidingSetting枚举决定模式vrm/first_person_layers与vrm/third_person_layers整数仅在BothLayers与BothLayersWithShadow模式下生效分别决定第一/第三人称MeshInstance3D的渲染 layer。其余模式FirstPersonOnlyWithShadow、FirstPersonOnly、ThirdPersonOnly会删除或修改特定网格使角色适合第一或第三人称使用。Shadow 模式会额外创建一个被隐藏头部的网格副本并设为ShadowsOnly让被隐藏的头部仍然投射阴影——如果你的游戏包含第一人称模式且灯光开启了阴影强烈建议使用 Shadow 模式。源码层面的执行逻辑在 vrm_extension.gd 的_first_person_head_hiding中插件会读取firstPerson扩展数据以firstPersonBone默认为 head 骨为基准递归收集头部相关的骨骼链再遍历meshAnnotations中的firstPersonFlagAuto/Both/FirstPersonOnly/ThirdPersonOnly最后调用vrm_utils.perform_head_hiding(...)完成实际的网格隐藏或复制。而导入器 import_vrm.gd 则把导入选项写入 GLTFStatestate.set_additional_data(vrm/head_hiding_method, options.get(vrm/head_hiding_method, 0) as vrm_constants.HeadHidingSetting) state.set_additional_data(vrm/first_person_layers, options.get(vrm/only_if_head_hiding_uses_layers/first_person_layers, 2) as int) state.set_additional_data(vrm/third_person_layers, options.get(vrm/only_if_head_hiding_uses_layers/third_person_layers, 4) as int)同一文件还体现了导入器的一个关键细节state.handle_binary_image GLTFState.HANDLE_BINARY_EMBED_AS_UNCOMPRESSED原因是HANDLE_BINARY_EMBED_AS_BASISU在 Godot 4.0 / 4.1 下处理部分文件时会崩溃。关于 Godot 4.3 的 SkeletonModifier3D 行为差异godot-vrm 会在Skeleton3D下创建一个内部子节点用于处理 VRM 弹簧骨骼spring bones与节点约束node constraints的骨架修饰器skeleton modifier计算。在 Godot 4.3 上由于骨架修饰器行为的变化会带来一些差异update_secondary_fixed不再受支持取而代之的是Skeleton节点自行决定使用物理physics还是空闲idle处理。这一差异可以在 vrm_secondary.gd 中看到完整的兼容处理func _ready() - void: ... if ClassDB.class_exists(SkeletonModifier3D): internal_modifier_node ClassDB.instantiate(SkeletonModifier3D) internal_modifier_node.name VRM_internal_skeleton_modifier skel.add_child(internal_modifier_node, false, Node.INTERNAL_MODE_BACK) internal_modifier_node.connect(modification_processed, self._on_secondary_process_modification_processed) func _process(delta: float): if not ClassDB.class_exists(SkeletonModifier3D): if not update_secondary_fixed: do_process(delta) func _physics_process(delta: float) - void: if not ClassDB.class_exists(SkeletonModifier3D): if update_secondary_fixed: do_process(delta)从源码结构可以推断在存在SkeletonModifier3D的 Godot 版本上弹簧骨骼计算完全交由SkeletonModifier3D的modification_processed信号驱动_on_secondary_process_modification_processed会根据skel.modifier_callback_mode_process决定取物理帧还是渲染帧的 delta在不存在该类的旧版本上则回退到传统的_process/_physics_process分支此时update_secondary_fixed才决定使用哪个回调。SpringBone 相关导出参数在 vrm_toplevel.gd 中VRMTopLevel暴露了一组 Springbone 设置供导入后的模型在 Inspector 中直接调参Springbone Settings分类update_secondary_fixed、disable_colliders、override_springbone_center、default_springbone_center、springbone_gravity_multiplier默认1.0、springbone_gravity_rotation、springbone_add_forceRun in Editor分类update_in_editor、gizmo_spring_bone、gizmo_spring_bone_color默认浅黄色允许在编辑器中预览弹簧骨骼与碰撞体 gizmo。单个弹簧骨骼的参数在 vrm_spring_bone.gd 中定义stiffness_scale刚度范围 0–10、drag_force_scale阻尼0–3、hit_radius_scale命中半径0–1、gravity_scale重力-10–10、gravity_dir_default默认(0, -1, 0)模拟重力(1, 0, 0)模拟风、以及可选的逐关节覆盖数组stiffness_force、gravity_power、gravity_dir、drag_force、hit_radius外加center_bone/center_node参考系。碰撞体则由 vrm_collider.gd 与 vrm_collider_group.gd 承载。安装与启用目录名不可改名原文档对安装路径有两个硬性约束务必遵守vrm插件目录将插件文件夹安装到addons/vrm绝对不可改名——该路径会被生成的 VRM 元脚本meta scripts引用Godot-MToon-Shader目录将 MToon 着色器安装到addons/Godot-MToon-Shader同样不可改名——该路径会被生成的材质引用。安装完成后在Project Settings - Plugins中启用VRM与Godot-MToon-Shader两个插件。在 Airi 仓库中stage-tamagotchi-godot工程的启用配置已经写好在 engines/stage-tamagotchi-godot/project.godot[editor_plugins] enabledPackedStringArray(res://addons/Godot-MToon-Shader/plugin.cfg, res://addons/vrm/plugin.cfg)启用插件后即可在编辑器中直接拖入.vrm文件进行导入导入生成的场景根节点会挂上VRMTopLevel脚本其vrm_meta属性展开后名为 CLICK TO SEE METADATA其中包含标题、版本、作者、联系信息、权限允许使用人群、暴力/色情内容、商业用途、再分发、修改等与许可信息见 vrm_meta.gd。导出与元数据校验插件在编辑器菜单 Export As 中注册了VRM 1.0 Avatar...项快捷键V见plugin.gd中的export_as_id 0x56524d31 # VRM1。导出前会调用VRMC_vrm._validate_meta(meta)校验元数据若许可下拉框或基础信息未填写会弹出提示要求补全。导出过程会把场景临时写成.tmp.glb再重命名为.vrm。⚠️重要警告当导出.gltf非.vrm时Godot 不会自动克隆场景根节点。由于部分导出操作具有破坏性导出过程可能损坏部分材质请务必先保存场景导出后立即还原revertMToon 着色器与材质管线该插件同时附带了一套完整的、独立于 Unity 的MToon Shader for Godot独立实现。MToon 是 VRM 生态中最常用的卡通/toon 着色器负责皮肤、头发、衣物的基础着色与描边效果。vrm_extension.gd的_process_vrm_material展示了 MToon 材质导入时的核心映射逻辑插件根据_BlendModeOpaque / Cutout / Transparent / TransparentWithZWrite与_CullModeOff / Front / Back选择对应的.gdshader变体并加载到 engines/stage-tamagotchi-godot/addons/Godot-MToon-Shader 目录如mtoon.gdshader、mtoon_cutout.gdshader、mtoon_trans.gdshader、mtoon_outline.gdshader等同时把_MainTex、_ShadeTexture、_BumpMap、_RimTexture、_SphereAdd、_EmissionMap、_OutlineWidthTexture、_UvAnimMaskTexture等纹理与_Color、_ShadeColor、_RimColor、_EmissionColor、_OutlineColor等颜色逐项写入 ShaderMaterial。_EmissionColor会按 HDR 处理将超过 1.0 的最大通道拆分为_EmissionMultiplier。此外还会根据 VRM 的renderQueue计算render_priority保证透明材质的绘制顺序。Airi 项目还对该 shader 打了本地补丁见 docs/vendor-patches.md为mtoon_common.gdshaderinc启用render_mode ambient_light_disabled并把 cutout 材质接入 Godot 的 alpha scissor 抗锯齿路径alpha_to_coverage。原因是 Airi 的舞台预设拥有天空、地面与环境呈现的控制权Godot 默认的环境光/辐照度会随舞台环境变化冲淡 MToon 化身的角色固有色同时 VRM 的头发、睫毛、配饰与描边 cutout 通道在远距离会出现锯齿alpha-to-coverage 配合 3D MSAA 可显著改善project.godot中anti_aliasing/quality/msaa_3d2。整体渲染分层思路见 docs/rendering-effects.mdMToon/基础材质负责化身本体着色MaterialOverlay负责无侵入的辅助通道如 stencil/mask/IDCompositorEffect负责同帧屏幕空间后处理。在 Airi 中的实际运用运行时 VRM 导入桥原文档面向 Godot 编辑器使用场景而 Airi 的stage-tamagotchi-godot舞台还需要在导出后的运行时Electron sidecar 进程接收并加载用户选择的 VRM 模型。由于addons/vrm/import_vrm.gd是编辑器专用的EditorSceneFormatImporter编辑器插件在导出的运行时并不会激活Airi 因此实现了一条运行时桥接路径完整调用链记录在 docs/vrm-runtime-import.mdscripts/vrm/VrmAvatarLoader.cs - scripts/vrm/VrmRuntimeImporter.gd - scripts/vrm/AiriVrmRuntimeExtension.gd - addons/vrm/vrm_extension.gd关键实现细节VrmRuntimeImporter.gd镜像了编辑器导入器 import_vrm.gd 的流程通过 Godot 静态 APIGLTFDocument.register_gltf_document_extension(...)注册扩展、设置HANDLE_BINARY_EMBED_AS_UNCOMPRESSED、使用IMPORT_USE_NAMED_SKIN_BINDS : 16与EditorSceneFormatImporter.IMPORT_USE_NAMED_SKIN_BINDS同一位Godot 4.6.2 的modules/gltf/gltf_document.cpp中GLTF_IMPORT_USE_NAMED_SKIN_BINDS 16。该 flag 对当前 VRM 示例模型是必需的——缺少它模型虽可导入但网格与骨骼绑定会出现可见畸变VrmAvatarLoader.cs由 C# 侧加载并调用 GDScript 导入器接收 Electron 物化到userData/godot-stage/models/modelId/fileName的本地文件路径返回一个**脱离场景树detached**的NodeAiriVrmRuntimeExtension.gd继承 vendored 的vrm_extension.gd修复了 Godot 4.6 的一个内部 bug当GLTFState.get_additional_data(vrm/already_processed)读取未设置的键时会产生 missing-key 错误。运行时导入器在导入前先 seed 该键为false扩展则只把true视为已处理从而既保留上游 preflight 行为又避免报错。节点生命周期由StageSceneController管理先导入新 VRM 到 detached 节点 → 挂到AvatarRoot下 → 替换当前化身引用 → 移除并排队释放旧化身导入失败时保留旧化身可见。⚠️版本边界该运行时桥目前只覆盖VRM 0.x路径glTF 扩展键VRM。VRM 1.0扩展键VRMC_vrm及配套VRMC_*虽然在编辑器插件中已注册但运行时尚未注册 vendored 的addons/vrm/1.0/VRMC_*.gd扩展集合。此外由于 VRM 0.x 的 workaround 会在append_from_file前 seedvrm/already_processed而VRMC_vrm.gd遇到该键已设置时会跳过导入因此不能仅靠注册1.0/VRMC_vrm.gd来开启 VRM 1.0 运行时导入——在拥有真实 fixture 并完成独立注册之前不应声称运行时已覆盖 VRM 1.0。测试验证仓库中的材质渲染检查测试 tests/material-rendering-check/materialRenderingCheck.gd 以AvatarSample-A/AvatarSample-B两个示例 VRM 为素材通过VrmRuntimeImporter.gd导入后统计材质断言必须导入 MToon 材质、alpha/cutout MToon 材质、透明 MToon 材质以及 MToon 描边通道mtoon_outline。这从测试层面印证了文档中VRMC_materials_mtoon✅ 已实现的说法。对 Godot 3.x 用户的说明本插件要求Godot Engine 4.0 stable 或更新版本。如果你需要兼容 Godot Engine 3.2.2 及以上版本需要使用上游仓库的godot3分支本仓库Airi中 vendored 的版本仅面向 Godot 4.xproject.godot的config/features声明为4.7, C#, Forward Plus。未来工作VRMC_vrm_animation插件尚未实现VRMC_vrm_animation其预期用途是 humanoid 动画库AnimationLibrary的导入与导出。目前1.0/VRMC_vrm_animation.gd已随 vendored 目录存在但plugin.gd中对应的GLTFDocument.register_gltf_document_extension(VRMC_vrm_animation_inst)处于注释状态需要在上游实现完成后解除注册并补充运行时注册路径。小结godot-vrm 是当前 Godot 生态中功能最完整的 VRM 解决方案之一它同时覆盖 VRM 0.0/1.0 导入与 VRM 1.0 导出、MToon 材质、SpringBone 弹簧骨骼、NodeConstraint 约束、HDR 自发光以及第一人称头部隐藏并自带可编辑的 VRM 元数据资源。Airi 项目以 vendored 方式将其纳入stage-tamagotchi-godot舞台并在其上叠加了运行时导入桥与 MToon 材质渲染补丁实现了Electron 侧下发模型路径、Godot sidecar 侧运行时热加载 VRM 化身的完整链路。对希望在 Godot 4 中接入 VRM 化身的开发者而言先按本文安装两个不可改名目录并启用插件再从 vrm_extension.gd 与 docs/vrm-runtime-import.md 入手是最快的上手路径。赞分享人工智能AI AgentMCP 服务工具调用GUI 自动化语音数字人交互助手【免费下载链接】airi 自托管、归你拥有的 Grok 风格 AI 伴侣与 waifu / 赛博生命灵魂容器目标是接近 Neuro-sama 的高度支持实时语音聊天、Minecraft 和 Factorio 游玩支持 Web / macOS / Windows。项目地址https://gitcode.com/moeru-ai/airi点击查看免费下载相关推荐完整指南UniVRM在Unity中的VRM模型导入与导出完整指南UniVRM在Unity中的VRM模型导入与导出 UniVRM是一个基于glTF的VRM格式实现专为Unity引擎设计。VRM格式作为3D虚拟形象文图形学3D渲染VRM-Addon-for-Blender 实战在 Blender 中从零创建人型 VRM 模型并导出 .vrmVRM Addon for Blender 实战在 Blender 中从零创建人型 VRM 模型并导出 .vrm 本篇技术指南基于 VRM Addon for图形学数字人UE5 VRM模型快速导入实战VRM4U插件完全指南 UE5 VRM模型快速导入实战VRM4U插件完全指南 想要在虚幻引擎5中轻松导入和使用VRM模型吗 VRM4U插件 就是你的终极解决方案这款强大的运图形学3D渲染游戏开发上一篇Deepseek Coder 1.3b Instruct代码安全分析生成代码漏洞检测报告下一篇自动光盘翻录机Automatic Ripping Machine简称ARM创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考