📚 模型开发扩展

在《沙盘引擎》世界场景中，模型占据了视觉上绝大部分，任何3D模型都被统称为“模型”（Model）。

沙盘引擎默认内置了不同分类下的多种预制模型，进阶玩家\开发者可直接在此基础上使用《地图编辑器》进行地图的创作，以供不同模组的调用使用。

除了内置的预制模型外，沙盘引擎也支持导入外部文件到当前模组（支持gltf\obj格式）。

通过外部导入机制，开发者可将自己想要的模型导入到世界，同时引擎会自动（或开发者手动注册json）将模型添加到世界列表，无论是地图编辑器或脚本API，均可直接创建模型对象及修改属性。

本文将主要介绍模型开发教程及扩展规范，如果有意将自定义模型导入到沙盘引擎使用，建议参考本文介绍。

在此之前，建议优先查看《世界资源实例》介绍，以了解沙盘引擎内“模型”的基础概念。

📒 模型导入及注册

如果拥有一些外部模型想要导入到模组中，那么可以参考以下步骤和介绍。

导入前提：必须是受支持的模型格式（如：gltf及obj文件）

模型的导入与注册全部基于模组框架，首先找到模组目录下的Store\Model文件夹，将任何你想要导入的模型文件放置到这里，并正确修改标准文件名（例如：ID_Name | 10000_Model）（如果没有修改ID文件名则不会被识别）。

模型的注册和导入都会在引擎加载模组时进行。

所以在添加新的模型后，必须进行重载模组指令（reload）或重启引擎程序来触发更新。

在完成上述步骤后，如果模型文件本身没有特别的问题，那么最简单的方式，可以打开《地图编辑器》在模型列表中找到导入成功的模型（文件名绑定的ID就是引擎内模型ID），反之可以查看[~]控制台是否出现异常报错。

📘 GLTF格式注意事项

GLTF模型仅支持导入标准\规范格式的文件，如果出现导入报错或不确定是否能导入，可通过【glTF Viewer】验证模型完整\兼容性。

建议优先使用：gltf+模型与贴图一体格式。

📘 OBJ格式注意事项

OBJ格式通常由多个文件组成一个模型（例如：.obj|.mtl|.png等），这些文件分别表示【模型网格、材质配置、材质贴图等】，如果缺少部分文件可能会导致显示异常（GLTF模型通常为一体化的文件格式，则可以忽略这个问题）。

基于多文件组成的原因，导入OBJ模型时需要注意：只将.obj文件修改前缀ID文件名，其他附带文件通常不需要更改。

示例：开发者希望导入一套obj模型（Book.obj | Book.mtl | Book.png），首先按照正常步骤将所有文件放置到LocalMod\Store\Model目录内，紧接着只需要修改Book.obj文件名为10000_Book.obj即可，其他的mtl\png等附带文件不需要修改前缀。

📘 高级设定

通常情况下，大多数模型只是作为一种展示存在，至于碰撞之类的问题可以直接使用API、地图编辑器对象选项等方式来设定是否包含碰撞，以及一些Model模型通用属性设置。

除此之外，如果被导入的模型需要比较高级的设定，那么就需要开发者手动进行一次json格式的注册导入，以告知引擎某个模型有哪些高级设定。

通常情况下，多数模型并不需要进行高级设定注册。

有一种特殊情况，如果规范开发希望给每个模型都设定好分类（如：树木放到自然资源包，农舍放到乡村资源包），那么就必须给每一个模型都添加一个最基础的设定注册（引擎内置模型几乎都是这样做的，因为这主要可以让《地图编辑器》寻找模型更加方便）。

如果你看过了《世界资源实例》文章，那么你应该大致了解《沙盘引擎》以提前为不同种类的模型设定好了分类，并且是以Package包的形式来呈现的，实际上每个包就相当于一个json注册文件。

根据上述提及的文章所示，任何非官方内置的模型资源，模型ID都是从10000开始递增的，也就是说无论外部模型是否进行了高级设定注册，模型的ID都永远不会是10000以下的数字，且默认被放置到【模组资源包（特殊）】包内。

📘 高级设定步骤

那么如果想要为模型注册高级设定，请参考以下步骤来进行操作：

首先找到模组目录下的Store\Data\Model文件夹，然后找到或新建一个json文件，打开进行编辑（默认原始情况下，此目录可能需要手动新建一个json文件）。

注意：这里的json文件命名会有一些讲究。

如果你只希望为导入模型添加一些高级设定，那么你可以直接建立一个Custom.json文件，这里可以放置任何属于【未分类、外部导入模型】分类下的高级设定数据。

反之来说，如果主要希望使用《地图编辑器》的玩家方便分类寻找（或特别规范的开发），那么你可以参考上文《世界资源实例》文章内表格的格式，按照《沙盘引擎》内置的分类来进行覆盖分类。

比如：如果只是在Custom.json文件内编写属性，那么最终地图编辑器（模型分类）会被分类到【未分类+外部导入模型】，如果只是内部使用或者小范围使用，这没有什么问题。

但是，如果希望规范开发，或者导入的模型比较多，希望未来自己或其他玩家使用《地图编辑器》制作地图时方便分类寻找，那么就应该按照分类格式json来进行覆盖或叠加。

假设我们想导入一些有关“自然资源”的模型，如果我们直接注册到Custom.json，那么在《地图编辑器》我们只能在【未分类】或【外部导入模型】这两个分类中寻找，如果同类更多那么可能要寻找一小会儿。

反之，如果我们将这类模型注册到0001_Natural.json（根据文档所决定的命名方式），那么引擎将会自动检查覆盖或者新增这些配置，自然而然的，因为我们是在“自然分类包（json）”填写的配置属性，所以这个模型自然被添加到【自然资源包】分类下，这样可以让使用地图编辑器的用户更加方便快捷。

扩展：根据《世界实例资源》文档介绍，0004_TEST.json应该表示乡村资源包，如你所见，命名最关键的主要是"_"前半部分的索引ID，至于后面的名字可以合理的自定义修改。

当然，如果你已经理解了这些内容，你完全可以决定是否这样做，这会增加一些操作成本，但是也许会换取一些分类便利。

📘 配置文件

根据上方介绍的高级设定内容，应该已经大致了解设定注册的意义，现在开始介绍具体的json配置方式。

首先，请根据上方所介绍的内容选择自己的方式和对应的json文件打开，开始进行json格式的导入编写（或照葫芦画瓢）。

注意：下方代码框只是示例，json文件可能无法识别注释"//"等内容，直接使用可能产生错误

//这是一个最基础的json文件，同时应该也注意到json是以[array]数组的格式展开的
[
    //这里的{ }块表示注册了一个ID为10001的模型，没有其他的意义
    //这样做可以让10001模型放到当前Json的分类下（如果是Custom.json，那么这里就没有任何意义，因为即使不注册json也会导入模型）
    //反之亦然，如果你只想为一个导入的模型实现一个【当前Json分类】的功能，那么你只需要克隆下方json块并修改ModelID即可
    {
        "Model": 10001
    }
]

//这是一个引用自引擎内部的json文件（有时效性，举例这是一个树木模型，放置在自然资源包json）
[
    {
        "Model": 5050, //模型ID，这是必须的
        "Type": 1, //模型类型，默认是0（通用），此处1表示植被类（注意：这里的类型并不是分类，而是一种针对特殊类型的标识识别）
        "Scale": {"x": 2.8, "y": 2.8, "z": 2.8}, //模型缩放，理解为导入到引擎后的内置尺寸
        "Color": {"r": 23, "g": 118, "b": 41}, //颜色叠加（通常是全部子模型颜色共同叠加，除非特殊设定，默认是rgb=255）（如果想所谓支持多颜色修改，考虑默认以白色、灰色来进行贴图绘制）
        "DetailType": 0, //模型细节类型，默认是0（通用，表示正方体碰撞），1表示细节碰撞（Mesh碰撞，如果希望模型碰撞细节可以填写1）等
        "CollisionType": 2, //碰撞类型，默认是1（通用）（0=无碰撞；1=正常；2=触发器）
        "RandomRangeScale": [0.9, 1.2] //整体随机缩放（每次创建时），这里表示每次建立时进行0.9~1.2的随机缩放（这里缩放是针对原始尺寸缩放，而不是对象尺寸缩放）
    }
]

如果你熟悉Json的格式和规范，有些内容并不是必须的。比如你去掉一些内容，它会按照指定属性的默认值来读取（例如CollisionType，假设不填写这项，它会按照默认1=正常的属性来继承）。

📒 自定义建模

如果你手头上并没有合适的模型，或者你希望使用工具自行建立一些模型（原创是值得鼓励的事情），那么你可以参考下文进行操作。

想要开始建立模型，一个合适的工具是必不可少的，沙盘引擎和其他多数引擎一样，本身并不具备原生的建模功能，这仍然需要使用\学习一些外部的工具。

注意：这里并不会进行3D建模的详细教学，以及太多建模工具的介绍。

只是更多为有兴趣建模的开发者指引一条可能的道路和指引。

📘 推荐建模工具

注意：此处只会介绍《沙盘引擎》官方推荐的建模工具，这通常是易于上手且风格较为匹配的。

根据此文档编写到此处时的检查，下方所介绍的工具是开源免费的，并且支持商业项目。

建模工具最终实现的效果几乎是一致的，只是不同工具有不同的限制和操作方式，开发者可根据自身需要探索学习。

经过实际测试操作，以上工具均可以导出至少gltf\obj格式其中的一种，所以可直接按照上文方式导入到引擎内使用。

有关建模工具的教程请参考http://www.bilibili.com/搜索查看。

📒 特殊模型规范

📘 LOD模型及命名

注意：如果模型存在父子节点关系，应该避免将子物体命名包含_LOD相关字样，这可能会触发引擎其他机制，导致碰撞等系统出现问题。

📘 可进入建筑模型

在阅读此部分内容之前，请先查看一次《多层建筑透视分层》解释说明。

（此处内容等待同步更新完善）