VoxBridge（之声桥）

将 VoxEdit 模型转换为 Unity 和 Roblox – 现在具有特定于平台的材质导出功能！

VoxBridge 是一款专业工具，可将从 The Sandbox VoxEdit 导出的 3D 模型转换为针对 Unity 和 Roblox 游戏引擎的优化格式。它会自动处理网格优化、纹理处理和特定于平台的材质转换，以确保您的模型在目标平台中完美运行。

• PBR 纹理通道重新映射：自动将纹理打包到 Unity 的标准着色器格式中
• 不再有灰色材料：R=金属，G=光滑度，B=AO，A=光泽
• 自动应用：在对 Unity 目标进行Node.js处理后运行
• 完美渲染：适用于 GLTF 查看器和 Unity！

• 三角形计数：报告中准确的三角形计数前/后
• 智能缩减：保留动画关键顶点
• 顶点焊接：自动合并重复的顶点
• 详细日志记录：显示精确的多边形减少百分比

• 文件大小：人类可读的格式（“21.49 MB”而不是字节）
• 三角形统计数据：前/后与减少百分比
• 优化状态：应用的内容（简化、焊接等）
• 性能指标：文件大小减小、处理时间
• 动画数据：骨骼计数、皮肤数据、动画计数
• 智能简化：保留动画顶点（减少 0% = 保护动画✅）
• 静态模型缩减：显示实际的多边形缩减（对于非绑定模型，则为 20-40%）

• Unity 兼容打包：根级别的所有文件（无子目录）
• 完美 URI 匹配：GLTF 纹理引用匹配文件位置
• 更轻松的导入：只需解压缩并拖入 Unity – 纹理会自动加载

• Unity 目标 （-t unity）：自动将 PBR 纹理打包到 Unity 的标准着色器格式中

  • R = 金属，G = 光滑度，B = AO，A = 光泽
  • 通过正确重新映射纹理通道来修复灰色材质问题
  • 在 GLTF 查看器和 Unity 中完美运行！

• Roblox Target （-t roblox）：简化的 Roblox 材料导出

  • 仅保留 BaseColor + 法线贴图（Roblox 实际使用的内容）
  • 删除未使用的 PBR 纹理以缩小文件大小
  • 针对 Roblox 的渲染引擎进行了优化

• 标准 GLTF 目标 （-t gltf）：完全符合 GLTF

  • 无需修改，适用于所有 GLTF/GLB 查看器
  • 完整的 PBR 支持

• 静态模型：简单模型导出为优化的三网格体（移除骨架）
• 动画模型：完整绑定和动画保留（蒙皮网格体）
• 自动检测或手动控制--force-static / --force-node

• 文件夹中可用的独立可执行文件/dist
• 无需安装 – 只需运行并转换！
• Node.js可选的，但建议用于：
  • 复杂模型处理（动画、大文件）
  • 高级优化（Draco，纹理大小调整）
  • 复杂资产的处理速度提高 2-3 倍

• 🚀 快速入门 – 5 分钟内启动并运行
• 📥 下载 – 为您的平台获取 VoxBridge
• 📋 支持的格式 – 哪些有效，哪些无效
• 🛠️ 故障排除 – 常见问题和解决方案
• 📖 文档 – 详细指南和参考资料

输入：从 The Sandbox Vox 导出的文件编辑
输出：针对 Roblox 或 Unity
优化的文件 目的：弥合体素艺术创作和游戏开发之间的差距.glb.gltf

⚠️ 重要提示： VoxBridge 仅适用于从 The Sandbox VoxEdit 导出的 GLB 文件。此阶段不支持其他格式，如 OBJ、FBX 或随机 3D 模型。

VoxBridge 现在具有智能转换系统，可自动检测 3D 模型的复杂性，并将它们路由到最佳处理路径：

🔍 自动检测：

• 静态模型：没有动画、皮肤或变形目标的简单模型
• 复杂模型：具有动画、绑定、变形目标或高级材质的模型

⚡ 处理路径：

• 静态路径：基于 Trimesh 的快速处理简单模型
• 复杂路径：使用 glTF-Transform 进行全Node.js处理，实现高级功能

🎛️ 手动覆盖：

• --force-static：强制静态处理（更快，但可能会丢失复杂特征）
• --force-node：强制复杂处理（速度较慢，但保留所有特征）

对于创作者（无需终端）：

• 使用 GUI – 只需双击并拖动您的文件
• 非常适合艺术家和非技术用户
• 可视化界面使转换变得简单

对于开发人员：

• 使用命令行 – 完全控制和自动化
• 非常适合批处理和脚本编写
• 高级选项和定制

• 作系统：Windows 10+、macOS 10.14+ 或 Linux （x64）
• 内存：最低 2GB，推荐 4GB
• 存储空间：200MB 可用空间
• 图形：对 GUI 的基本图形支持
• Node.js：18+ LTS（可选但推荐）

VoxBridge 无需Node.js即可工作，但可获得最佳性能：

• ✅ 简单/静态模型：无需Node.js即可正常工作（基本转换）
• ⚡ 复杂/动画模型：需要Node.js：
  • 动画和绑定保留
  • 大文件处理 （>50MB）
  • 高级优化（Draco 压缩、纹理大小调整）
  • 处理速度提高 2-3 倍

安装Node.js：从 nodejs.org 下载最新的 LTS 版本

📖 需要详细的安装帮助？有关分步说明和故障排除，请参阅安装指南。

无需终端知识！非常适合艺术家和创作者。

1. 下载适用于您平台的独立可执行文件
2. 将文件解压到任何文件夹
3. 双击 （Windows） 或 （Linux/macOS）voxbridge-gui.exe./voxbridge-gui
4. 加载从 VoxEdit 导出的文件.glb
5. 选择目标平台（Roblox 或 Unity）
6. 点击“转换”并在 ZIP 文件中找到您的结果！

💡 GUI 使一切变得直观和简单 – 只需拖放和转换！

1. 下载适用于您平台的独立可执行文件
2. 将文件解压到任何文件夹
3. 打开该文件夹中的命令提示符/终端
4. 运行转换命令：

# Unity export (fixes gray materials with packed textures!)
./voxbridge convert --input model.glb --output-dir ./output -t unity

# Roblox export (lightweight, optimized materials)
./voxbridge convert --input model.glb --output-dir ./output -t roblox

# Standard GLTF export (works in all viewers)
./voxbridge convert --input model.glb --output-dir ./output -t gltf

# Static model (fast, Python-only - no Node.js needed)
./voxbridge convert --input static_model.glb --output-dir ./output -t unity --force-static

# Animated model (preserves rigging - requires Node.js)
./voxbridge convert --input animated_model.glb --output-dir ./output -t unity --force-node

# Batch processing
./voxbridge batch ./input_folder --output-dir ./output_folder -t unity

下载最新版本：GitHub Releases

💡 最新版本： v2.0.1 – 包括 Unity PBR 纹理打包、网格简化和综合报告！

📖 需要有关独立可执行文件的帮助？有关特定于平台的详细说明，请参阅独立可执行文件指南。

• GLB（GLTF 二进制文件）– 从 The Sandbox VoxEdit 导出
• glTF – 来自 VoxEdit 的基于文本的 GLTF 文件

• glTF – 针对 Unity 或 Roblox 进行了优化
• ZIP 包 – 输出文件的自动打包

• OBJ 文件 – 现阶段不支持
• FBX文件 – 现阶段不支持
• 随机 3D 模型 – 只有 VoxEdit 导出有效
• 其他格式 – 仅 VoxEdit 的 GLB/glTF

💡 始终以 GLB 格式从 VoxEdit 导出您的资产以获得最佳效果。

• 输入：VoxEdit .glb/.gltf 文件
• 输出：具有打包 PBR 纹理的 Unity 优化 glTF
• 材质处理：自动将纹理打包到 Unity 的标准着色器格式中
  • R 通道 = 金属
  • G 通道 = 平滑度（倒置粗糙度）
  • B 通道 = 环境光遮蔽
  • 通道 = 光泽度
• 修复：Unity 中的灰色材质问题！
• 适用于：Unity 和 GLTF 查看器

• 输入：VoxEdit .glb/.gltf 文件
• 输出：与 Roblox 兼容的 glTF，具有简化的材料
• 物料搬运：仅保留 Roblox 使用的内容
  • BaseColor（反照率）纹理
  • 法线贴图（如果存在）
  • 去除金属/粗糙度/遮挡（Roblox 未使用）
• 优点：文件大小更小，导入速度更快
• 优化为：Roblox Studio

• 输入：VoxEdit .glb/.gltf 文件
• 输出：标准 GLTF，支持完全 PBR
• 物料搬运：无需修改，完全符合 GLTF 规范
• 用于：GLTF/GLB 查看器、其他游戏引擎

VoxBridge 智能处理不同的模型类型：

出口流程：

• 转换为优化的三网格
• 移除原始骨架（不需要）
• 处理速度更快，文件大小更小
• 无需Node.js即可工作

用例：

• 建筑物、道具、装饰品
• 不移动的物体
• 简单的角色模型

例：

./voxbridge convert --input building.glb -o output/ -t unity --force-static

出口流程：

• 保留完整的索具和蒙皮
• 保持动画
• 删除静态重复项
• 需要Node.js才能获得最佳结果

用例：

• 带有动画的角色
• 纵模型
• 蒙皮网格体

例：

./voxbridge convert --input character.glb -o output/ -t unity --force-node

💡 自动检测：默认情况下，VoxBridge 会自动检测您的模型是静态的还是动画的，并使用适当的处理路径。

# Get help
./voxbridge --help

# ===== PLATFORM-SPECIFIC EXPORTS =====

# Unity export (fixes gray materials!)
./voxbridge convert -i model.glb -o output/ -t unity

# Roblox export (optimized, lightweight)
./voxbridge convert -i model.glb -o output/ -t roblox

# Standard GLTF export (universal)
./voxbridge convert -i model.glb -o output/ -t gltf

# ===== STATIC VS ANIMATED MODELS =====

# Static model (fast, no Node.js needed)
./voxbridge convert -i prop.glb -o output/ -t unity --force-static

# Animated model (requires Node.js)
./voxbridge convert -i character.glb -o output/ -t unity --force-node

# Auto-detect (default - chooses best path)
./voxbridge convert -i model.glb -o output/ -t unity

# ===== ADVANCED OPTIONS =====

# Unity with mesh optimization (requires Node.js)
./voxbridge convert -i model.glb -o output/ -t unity --optimize-mesh

# Roblox with Draco compression (requires Node.js)
./voxbridge convert -i model.glb -o output/ -t roblox --use-draco

# Full optimization (requires Node.js)
./voxbridge convert -i model.glb -o output/ -t unity 
  --optimize-mesh --texture-size 1024 --use-draco --quantize

# ===== BATCH PROCESSING =====

# Batch convert folder to Unity
./voxbridge batch ./input_folder -o ./output_folder -t unity

# Batch convert to Roblox
./voxbridge batch ./input_folder -o ./output_folder -t roblox

# ===== DIAGNOSTICS =====

# Check system and Node.js availability
./voxbridge doctor

# Verbose output for debugging
./voxbridge convert -i model.glb -o output/ -t unity --verbose

📖 需要更多命令详细信息？有关全面的文档，请参阅使用指南和纹理打包指南。

不要尝试这些 – 它们不会起作用：

• ❌ 使用 OBJ 或 FBX 文件作为输入
• ❌ 从互联网上拖动随机 3D 模型
• ❌ 使用其他体素编辑器中的模型
• ❌ 期望其他格式有效
• ❌ 使用未安装Node.js的复杂处理标志

请改为执行以下作：

• ✅ 始终从 The Sandbox VoxEdit 导出为 GLB
• ✅ 使用 GUI 进行首次转换（无需终端！
• ✅ 检查转换后模型的输出 ZIP 文件
• ✅ 安装 Node.js 18+ 以获得复杂模型的完整功能

如需完整功能：

• 复杂模型处理需要Node.js 18+
• 自动回退：如果Node.js不可用，VoxBridge 将使用仅 Python 的处理
• 性能影响：使用 Node.js 复杂处理速度提高 2-3 倍

需要什么Node.js：

• 网格简化 （--optimize-mesh)
• 天龙座压缩 （--use-draco)
• 纹理大小调整 （--texture-size)
• 量化 （--quantize)
• 复杂模型处理（动画、绑定）

没有Node.js什么有效：

• 基本转换 （--force-static)
• 简单的模型处理
• GLB 填料 （--pack-glb)
• 基本材料转换

• 📖 快速入门指南：docs/QUICK_START.md – 分步入门
• 📖 纹理打包指南： docs/TEXTURE_PACKING_GUIDE.md – 特定于平台的材质导出
• 📖 LOD生成指南：docs/LOD_GENERATION_GUIDE.md – 新！使用LOD进行移动优化
• 📖 使用指南：docs/usage.md – 完整的 CLI 文档
• 📖 安装指南：docs/installation.md – 详细的安装帮助
• 📖 独立可执行文件：docs/STANDALONE_EXECUTABLES.md – 特定于平台的说明
• 📖 性能分析：docs/performance.md – 基准和性能指标
• 📖 当前状态：docs/CURRENT_STATUS.md – 项目状态和里程碑

• 📖 为什么三角形保持不变：WHY_TRIANGLES_STAY_SAME.md – 新！了解动画模型的网格简化
• 📖 完整修复：COMPLETE_FIXES_SUMMARY.md – v2.0.1 技术更改
• 📖 沙盒授权状态：SANDBOX_GRANT_COMPLETION.md – 所有 3 个里程碑都已完成

• 🎯 纹理打包快速参考：QUICK_REFERENCE_TEXTURE_PACKING.md – 命令一览
• 📊 实现摘要：TEXTURE_PACKING_IMPLEMENTATION_SUMMARY.md – 技术细节

• GLTF 规格：https://registry.khronos.org/glTF/
• Roblox 网格导入：https://create.roblox.com/docs/art/modeling/meshes
• Unity GLTF 导入：https://docs.unity3d.com/Packages/com.unity.formats.gltf
• 沙盒 Vox编辑：https://www.sandbox.game/voxedit

• 报告问题：GitHub 问题
• 提问：GitHub 讨论

如果 Windows 询问如何打开文件而不是运行它：

解决方案 1：使用命令提示符（推荐）

# Open Command Prompt (cmd.exe), not PowerShell
cd C:pathtoextractedfolder
voxbridge.exe --help
voxbridge-gui.exe

解决方案 2：PowerShell 替代方案

# In PowerShell, use this syntax:
cd C:pathtoextractedfolder
.voxbridge.exe --help
& ".voxbridge-gui.exe"

chmod +x voxbridge voxbridge-gui

# Get detailed error info
./voxbridge convert --input model.glb --output-dir ./output --target roblox --verbose

# Check system status and Node.js availability
./voxbridge doctor

如果看到“找不到Node.js运行程序”或“复杂处理失败”：

解决方案 1：安装Node.js（推荐）

# Install Node.js 18+ from https://nodejs.org/
# Then restart your terminal and try again
./voxbridge convert --input model.glb --output-dir ./output --target unity --force-node

解决方案 2：使用仅 Python 处理

# Force static processing (no Node.js required)
./voxbridge convert --input model.glb --output-dir ./output --target unity --force-static

解决方案 3：检查Node.js安装

# Verify Node.js is installed and accessible
node --version
npm --version

某些防病毒软件可能会将可执行文件标记为可疑。这是一个误报，因为：

• 可执行文件是使用 PyInstaller 构建的
• 它包含 Python 运行时和库
• 不存在恶意代码

解决方案：在 Windows Defender 中为 VoxBridge 文件夹添加例外。

📖 需要更多故障排除帮助？有关详细解决方案，请参阅安装指南，有关特定于命令的帮助，请参阅使用指南。

对于想要从源代码构建的开发人员：

📖 性能和基准：有关详细基准，请参阅性能分析，有关项目里程碑的当前状态。

• Python：3.12（不是 3.13）- 兼容性必需
• 依赖项：从 requirements.txt 安装

# Clone repository
git clone https://github.com/Supercoolkayy/voxbridge.git
cd voxbridge

# Create virtual environment
python3.12 -m venv venv
source venv/bin/activate  # On Windows: venvScriptsactivate

# Install dependencies
pip install -r requirements.txt

# Install in development mode
pip install -e .

# Run tests
python -m pytest tests/

# Launch GUI for testing
python gui.py

# Linux/macOS
./build.sh

# Windows (requires Windows machine)
build_windows.bat

📖 基准测试：有关性能测试和优化分析，请参阅基准测试指南。

MIT 许可证 – 有关详细信息，请参阅许可证。

VoxBridge v2.0.0 – 具有特定平台材质导出的专业资产转换

由 Dapps 制作，❤️而不是应用程序 |麻省理工学院许可证