# 导入导出Virtools文档

!!! warning "这是实验性内容"
    原生导入导出Virtools文档是BBP插件的试验性内容，它可能存在许多问题，请参阅[报告问题](./report-bugs.md)章节来了解更多。当遇到问题时，请及时汇报。BBP插件的作者不对因BBP插件问题导致的任何后果负责。

## 导入Virtools文档

点击`File - Import - Virtools File`可以导入Virtools文档。导入支持CMO，VMO，NMO文件。点击后会弹出文件打开界面，并在侧边栏展示导入设置，如下图所示。首先你需要选择导入的Virtools文档，然后在侧边栏配置导入设置，配置完导入设置后即可点击导入开始导入，并等待Blender下方提示导入完成即可。

![](../imgs/import-virtools.png)

### 冲突解决选项

Conflict Options（冲突解决选项）章节指示了当导入器遇到物体名称重复的情况时，该如何处理。分为6个等级，分别针对Object（物体），Light（灯光），Camera（摄像机），Mesh（网格），Material（材质），Texture（贴图）。处理方式则有2种：Rename（重命名）和Use Current（使用当前）。选择重命名后，当遇到重复名称时，将会自动为其添加名称后缀使其名称唯一化。而选择使用当前，则会忽略从文件中导入此项，转而使用Blender文档中已经存在的同名的项目。

!!! info "与Virtools冲突解决的不同"
    相比较于在Virtools的冲突解决对话框，BBP插件提供的冲突解决选项不支持替换功能，同时其粒度也不支持精细到单个实例，只能针对一整个类型进行设定。因此你无法单独为每一个冲突的实例设置不同的冲突解决方案。但目前这种设置已经能满足绝大对数的使用场景了。

冲突解决选项章节里的选项的默认值是通常导入时会选择的解决方案。当然针对特殊导入情况需要特殊设置，例如正在从外部导入一个从原版中导出的机关模型，则可能连材质选项都可以选择使用当前，而无需复制一份。正确使用冲突解决选项是制图经验所给予的，本手册不会对此进行教学。

### Virtools参数

众所周知，Virtools使用基于系统的多字节字符编码来处理文档，因而很容易出现所谓乱码问题。Blender本身不会出现乱码问题，然而如果我们不能以正确的编码读取Virtools文档，则当Virtools文档被导入Blender时，其中存储的字符仍然可能会呈现乱码状态。Virtools Params（Virtools参数）章节的Encodings（编码）属性用于指定读取Virtools文档的编码。可以指定多个编码，越靠上的编码越优先使用，当无法解码时才会使用下一级编码。下面列出一些常用的编码：

* cp1252：Ballance所用的西欧编码
* gbk：中文Windows系统默认编码

编码属性非常重要，如果设置了错误的编码，导入Blender的各类物体的名称会出现不可认知的情况，又或者会导致程序出错。

!!! info "有哪些编码可以使用？"
    自BBP 4.1版本后，我们使用编码的名字基本上就是照抄Python的编码名。大多数Python中常用的编码名都有映射，只有一些特别罕见的编码没有支持，对于具体支持的编码则需要查看源码。有关Python支持的编码，请查看[Python相关文档](https://docs.python.org/3/library/codecs.html#standard-encodings)。编码名不区分大小写。

!!! warning "从旧版本迁移的警告"
    自BBP 4.1版本开始，BBP的Virtools文档导入模块使用的底层库LibCmo版本号提升为0.2。在此版本前，编码属性是一个平台相关的设定。在Windows下，这里需要填写的是[Windows代码页](https://learn.microsoft.com/en-us/windows/win32/intl/code-page-identifiers)数字。而在其它操作系统下，LibCmo使用iconv进行字符编码解码，因此需要使用合法的[iconv编码标识符](https://www.gnu.org/software/libiconv/)。

    这一切在LibCmo 0.2后发生了改变，从这个版本开始，LibCmo采用了类似Python的统一编码名。它是平台无关的，你不再需要检查你正在使用的操作系统是Windows还是Linux，所有平台的编码字符均为相同的字符串。这也就意味着如果您之前自定义过编码设置，你需要注意将他们转换到新的统一编码名，因为旧的编码名可能在统一编码名下没有对应映射，例如之前在Windows上指定的`1252`，在新的统一编码名下应当被书写为`cp1252`，原编码在新系统下无法被正确识别。

## 导出Virtools文档

点击`File - Export - Virtools File`可以导出Virtools文档。点击后会弹出文件打开界面，并在侧边栏展示导出设置，如下图所示。首先你需要选择导出的Virtools文档的位置，然后在侧边栏配置导出设置，配置完导出设置后即可点击导出开始导出，并等待Blender下方提示导出完成即可。

![](../imgs/export-virtools.png)

### 导出目标

Export Target（导出目标）章节用于决定你需要将哪写物体导出到Virtools文档中。你可以在四种模式中选择其一，来决定需要导出的内容：

* Object：导出单个物体。选择后需要在下面选择需要导出的物体。
* Collection：导出单个集合，**这是最常用的选项**。选择后需要在下面选择需要导出的集合。值得注意的是，该选项支持嵌套集合导出，即选择集合的时候，会将集合中的集合的物体也一起导出。
* Selected Objects：导出选择的物体。你需要在导出前选择好需要导出的物体。
* All Objects：导出该文档中的所有物体。该选项慎用，因为它是粗暴地遍历文档中的物体列表来进行导出，很可能会导出许多你不需要的物体。

!!! warning "可导出目标与修改器"
    自BBP 4.4版本开始，BBP不仅支持导出Mesh类型物体，还开始支持导出所有可转换为Mesh类型的物体，包括：Curve（曲线），Surface（表面），Font（字体）和Meta Ball（融球）。此前BBP仅支持Mesh类型物体的导出。通过该功能，用户不再需要将各类物体转换为网格之后再进行地图导出和测试，例如使用曲线放样得到花式钢轨的工作，现在可以直接在曲线状态进行导出，然后在游戏中进行可通关性的测试，测试完毕后再将其固化为网格，并添加相应材质。凭借该功能可大幅加速地图制作和调整速度。

    额外的，自BBP 4.4版本开始，导出时也不再需要给物体应用修改器了。BBP在导出时会在一个类似“临时物体”的东西上应用所有修改器后再导出（你可以这么近似理解，实际实现并非如此）。该功能可为之后使用几何节点等修改器赋能Ballance地图快速创作打下坚实基础。

### Virtools参数

Virtools Params（Virtools参数）章节与导入Virtools文档中的类似。Encodings（编码）属性决定了导出Virtools文档时所用的编码。

Global Texture Save Option（全局贴图保存选项）决定了那些设置了Use Global（使用全局设定）的贴图的真实保存方式。通常而言，设置为Raw Data（原始数据）则可以100%保证保存的Virtools文档可以包含正确贴图，但是其体积也可能会变大，设置为External（外部数据）则可以尽可能减少文件大小，但可能会出现导出的文档找不到贴图文件的问题。我们建议你在进行材质设置时就对每个材质单独指定应该如何保存，而不是依赖全局选项来设置。这个选项是给那些依赖全局贴图保存选项的旧地图的再编辑来使用的。还需要注意的是，尽管这个选项里有Use Global选项，但请 **不要** 选择，否则会导致错误，因为显然你不能让一个全局选项再去使用全局选项的设置。

Use Compress（使用压缩）属性指定保存的文档是否压缩存储。压缩可以显著减少文档体积，且在现代计算机平台上，压缩所造成的性能损失几乎可以忽略不计。当选择使用压缩后，一个额外的Compress Level（压缩等级）属性将会显示，用于指定压缩的级别，数值越高，压缩率越大，文件越小。

### Ballance参数

Ballance Params（Ballance参数）章节包含针对Ballance特有内容，对导出过程进行优化的参数。

Successive Sector（小节连续）是一个解决导出小节组时出现的Bug的选项。由于某些原因，如果一个小节中没有任何机关（实际上是某小节组中没有归入任何物体），导出插件会认为该小节组不存在，因而遗漏导出。且由于Ballance对最终小节，即飞船出现小节的判定是从1开始递增寻找最后一个存在的小节组，所以二者叠加，会导致Ballance错误地认定地图的小节数，从而在错误的小节显示飞船，这也就是导出Bug。当勾选此选项后，导出文档时会预先按照当前Blender文件中Ballance地图信息中指定的小节数预先创建所有小节组，然后再进行导出，这样就不会遗漏创建某些小节组，飞船也会在正确的小节显示。

这个选项通常在导出可游玩的地图时选中，如果你只是想导出一些模型，那么需要关闭此选项，否则会在最终文件中产生许多无用的小节组。

## 无法导入导出

通常而言，在你正确按照之前介绍的步骤安装和配置插件后，你理论上就可以使用Virtools文档的导入导出功能了。但难免有意外发生。这里说的无法导入导出指的是导入和导出Virtools文档的按钮是灰色的，不可点击的。你需要按照下述步骤检查。如果你所指的是在导入导出过程中出错了，请参考本页页首的警告信息。

首先检查你是否已经在[配置插件](configure-plugin.md)章节正确配置了插件的`External Texture Folder`设置项。如果你没有配置，则自然无法导入导出Virtools文件。因为导入导出Virtools文件需要依赖Ballance原版贴图数据。请按教程认真配置这一设置项。

如果你确定你已经设置了正确的贴图路径，你可以尝试点击菜单`Window - Toggle System Console`来打开控制台。在控制台中，可能会有一些相关的错误信息输出在其中，例如加载底层BMap库时失败等。加载底层BMap库失败通常只发生在一些罕见架构的机器上，例如使用Snapdragon处理器的Windows系统等，因为我们打包的插件中，并未包含支持这些平台的Virtools文件底层读取库BMap。在面对这种情况时，你有两个选择，一是汇报给开发者，等待开发者主动支持，二是自行编译该库（仅建议有丰富计算机知识的人这样做）。
