酷大师插件开发教程

• Step 0：了解酷大师插件
• Step 1：创建插件
• Step 2：下载插件模板
• Step 3： 进行插件开发
  • 沙盒 JS 代码开发
  • 插件前端 UI html 开发
  • 插件后端服务开发
    • WebHook 注册填写示例
  • 插件开发示例
• Step 4： 提交插件到酷大师官方进行审核
  • 上传插件代码并提交审核
  • 新增发布

酷大师是一个在线3d自由造型软件，提供了连线成面、拉伸、扫掠、偏移、阵列、布尔操作等几何造型功能，可以创建出各种各样灵活多变的3d模型。

• 一分钟了解用酷大师如何建马克杯
• 酷大师基础操作视频教程
• 酷大师视频教程合集
• 酷大师帮助文档
• 酷大师模型广场
• 酷大师建模基本概念

酷大师同时提供了强大的插件开发能力，利用酷大师的API接口，我们已经创建了“一键绘制楼梯”，“外景设计”，“智能灯箱”等多款插件，供大家在酷大师里使用。

本文一步步描述如何为酷大师开发插件。

Step 0：了解酷大师插件

开发者为酷大师开发的插件，会出现在酷大师顶部的“插件”（后续会更名为“插件”）菜单列表中。插件不能自动启动，需要手动点击菜单项，才能被启动。

建议可先试用一下这些酷大师官方内置插件，了解酷大师插件可以做成什么样子。

通常，一个酷大师插件可由如下三部分构成，这三部分都是可选的：

1. 一些在酷大师沙盒中运行的 JS 代码
2. 一个被酷大师持有的 iframe 弹窗加载的插件前端 UI html 文件 （或一个 html 的 url 地址）
3. 一个后端服务

这意味着某一个酷大师插件，它可能只包含1，2，3中的任意一个，任意两个，或全都有。

下面分别介绍这三部分：

1. 沙盒 JS 代码：一个插件如果想使用酷大师提供的基础建模能力，如连线成面、拉伸、扫掠、偏移、阵列、布尔操作、成组、解组等等，可以写一些 JS 代码来调用酷大师 Plugin API；这些 JS 代码由酷大师在一个沙盒环境中运行，它只能使用基本的 JS 语法并调用酷大师 Plugin API ，无法调用任何浏览器的 API 或进行网络访问。

2. UI html：一个插件如果需要 UI 界面，则可以提供一个 html 文件或 html 的 url（需以 http/https 开头），酷大师负责将它们在一个 iframe 窗口中加载进来。这个 UI html 可以用任何 web 技术进行开发。它可以和酷大师主应用程序窗口通过 Post Message 的方式互相发消息，从而实现某些交互功能。消息既可以从酷大师发给 iframe 窗口里的 html，也可以从 iframe 窗口里的 html 发给酷大师。

   1. 这些消息可以是酷大师官方定义的消息，如 'insert_model'，'update_model'，'edit_model' 等，酷大师会针对收到的这些消息，做特定的动作，或在特定的时机向插件 UI html 发送特定的消息。
   2. 这些消息也可以是插件自定义的消息。可以在沙盒 JS 代码和 html 代码中自定义消息格式和消息处理函数。插件用这种方式可以实现更加丰富的交互行为。

3. 后端服务：一个插件如果想自己拥有一些数据存储、计算的功能，可以自己开发一个后端服务。插件后端服务可以通过下列两种方式与酷大师交互：

   1. 调用酷大师后端 REST API，获取酷大师方案里的 3d 模型信息 （目前仅支持酷家乐内部团队调用，公网暂不可用）
   2. 提供一些 Web API 注册到酷大师后端 ，我们称之为 WebHook API，由酷大师后端在特定场景下调用

这三部分和酷大师的数据交互如下图所示：

用户从插件菜单列表中启动某一个插件后，酷大师会：

1. 检查该插件是否有沙盒 JS 代码，如果有，就加载到沙盒环境中执行。（沙盒代码如果自定义了消息处理函数，此时可以将它们注册到酷大师内）
2. 检查该插件是否有 UI html，如果有，就打开一个 iframe 窗口，并在 iframe 窗口中加载该 html。（此时，用户通过和 UI html 交互，即能和酷大师以及沙盒代码互相发送消息，完成各种业务逻辑）

一个插件，如果它只想做一些简单的“批处理”类似的工作，例如将画布中所有选中的平面全部拉伸 100 cm，那么它只需要写一段沙盒 JS 代码就可以了。

如果它还想让用户输入拉伸的高度，那么它需要一个前端 UI html。

如果它还想从自己的数据库中查询拉伸的高度列表，那么它可以加一个后端服务。

下面再举一些例子：

• 酷大师目前上线的“场景模型”，“智能模型”，“智能3D文字”，“智能灯箱”等插件，都只有“插件前端 UI html ”和“插件后端服务”这两部分，它们的前端通过 POST 官方 message，例如 "insert_model"，告诉酷大师它需要向画布中插入一个外部模型，酷大师获取这个消息后，从消息中获取模型的id，然后调用插件后端事先在酷大师后端注册好的 Web Hook API，根据这个外部模型id，获取外部模型的三角网格，显示在酷大师画布中。
• 酷大师目前上线的“智能楼梯”插件，只有“插件前端 UI html ”和“沙盒 JS 代码”这两部分。“插件前端 UI html ”负责获取用户输入的楼梯参数，将这些参数通过 POST 自定义 message 的方式告诉”沙盒 JS 代码“，”沙盒 JS 代码“调用酷大师 Plugin API 如创建面、拉伸等，以批处理的方式创建出楼梯模型。
• 酷大师之前开发过的的”仿真分析“插件，也只有“插件前端 UI html ”和“插件后端服务”这两部分，它会调用酷大师 REST API，从酷大师后端获取一个酷大师方案中的造型数据，进行仿真分析计算。

Step 1：创建插件

在酷家乐应用中心里创建一个新的应用，应用类型选择"酷大师插件“。您会得到一个插件 id 。此 id 是插件的唯一标识符，我们在很多后续步骤中都会用到它。

Step 2：下载插件模板

我们提供了 4 个插件模板，对于所有插件模板，其配置文件 manifest.json 中的 ”id“ 是不可以修改的，该 id 是酷大师插件平台分配给该插件的唯一识别码。

如果您不需要使用到沙盒 JS 代码，那么下载第一个模板即可。这个模板里只有一个 manifest.json 文件，您需要在 "view" 这一项中填入你的插件前端 UI html 的 url，并将 "main" 这个属性置为空，（注：当 "main" 为空时，“view“ 字段的值必须为 url），参考格式如下：

{
    "name": "示例插件",
    "id": "XGiuzmg3yOQwbSPUCWg5p",
    "position": "default",
    "version": "1.0.0",
    "view": "https://www.kudashi.com/",
    "main": ""
}

如果您需要使用沙盒 JS 代码，则可以下载后面三个模板，根据对开发者能力的要求，我们将插件模板分为三个等级：primary，middle，high。

1、等级 primary：该插件模板配置仅支持 JavaScript 开发语言，不支持 js 文件模块导入，因此仅适用于简单插件开发，同时该插件模板仅需安装少量依赖包。

2、等级 middle：该插件模板配置支持 JavaScript 、TypeScript 开发语言，不支持 js、ts 文件模块导入，因此仅适用于简单插件开发，同时该插件模板仅需安装少量依赖包。

3、等级 high：该插件模板配置支持 JavaScript 、TypeScript 开发语言，同时该插件配置了 webpack，支持文件模块、图片等资源文件导入，因此适用于复杂插件开发，同时该插件模板需安装较多依赖包。

等级 middle 和 high 的插件模板均引入了名为 “@kudashi/kds-api” 的npm包，内含酷大师 Plugin API 的 TypeScript 声明文件，方便开发者使用 TypeScript 语言进行开发。上述插件模板的具体使用方式请阅读插件模板包中的 readme 文件。

注意：上述模板仅是给开发者的参考，方便开发者快速进行酷大师插件开发，开发者不必完全按照插件模板提供的方法去开发插件。比如开发者可以对等级 primary 和 middle 的插件模板进行修改，使用 webpack 或其他工具进行打包，以使其支持文件模块、图片等资源的导入。开发者甚至可以完全不使用我们提供的插件模板，可以采用任何 web 技术生成符合酷大师要求的插件文件即可，但是有一点需要强调，配置文件 manifest.json 中的 ”id“ 是不可以修改的。

Step 3： 进行插件开发

沙盒 JS 代码开发

如果您认为您的插件需要调用 Plugin API ，那么可阅读本地安装及调试指南，它将引导您完成开发环境设置，以及介绍运行和调试酷大师插件所需的步骤。在该指南的最后，您将可以运行和调试 Step3 中下载的示例插件，该插件向用户询问数字并在画布上创建相应数量的矩形。绝大部分Plugin  API 均可从两个全局对象 app, GeomLib 访问，具体使用可参考Plugin API使用指南。

插件前端 UI html 开发

如果您认为您的插件需要一个 UI 界面，用来收集用户输入，或做特定的信息展示，则可以使用任何前端技术栈开发这个插件前端 UI 的 html。注意在这里您可以使用酷大师官方定义的消息，和酷大师前端通过 post message 的方式进行通讯。如果您同时使用了 Plugin API，也可以自定义一些消息，在沙盒代码里编写 message handler，和沙盒代码通过 post message 方式通讯。

插件后端服务开发

如果您认为您的插件需要一个后端服务来实现一些业务逻辑，则可以使用任何后端技术栈来开发这个服务。

注意在这里你可以调用酷大师后端 Restful API，也可以提供一些 WebHook API，供酷大师后端服务调用

WebHook API 可以通过开发者平台的 WebHook 配置页面配置到酷大师后端

WebHook 注册填写示例

假设插件服务的域名是 https://www.example.com，其 'get-ext-model'  消息类型的 WebHook API url 为 /myplugin/get-model，则建议：

• 填入的 url：https://www.example.com/myplugin/get-model?modelIndex={modelIndex}
• 消息类型：GET_MODEL

其中 modelIndex 是作为插件 3d 模型在酷大师方案中的唯一索引 id 使用。酷大师会根据此 modelIndex 来进行插件 3d 模型的获取、更新、删除。

插件开发示例

1. Hello world

   1. 模板插件源码解析

2. 智能楼梯插件

   1. 智能楼梯插件源码解析

3. 智能灯箱插件

   1. 智能灯箱插件示例教程

Step 4： 提交插件到酷大师官方进行审核

上传插件代码并提交审核

当您把 JS 和 HTML 代码开发完成并进行过一些调试而且通过之后，如果希望将插件进行上线的话，可以选择新建一个版本，并将插件代码压缩成zip包上传，随后可以进行联调和提交审核。

插件代码 zip 包至少需要包含 manifest.json。然后根据插件实现的具体情况，可选择性包含沙盒 JS 代码文件，UI html 文件及它引用的 JS 文件等。不需要包含插件开发过程中使用到的 ts 源代码文件，以及 node_modules 中的第三方依赖文件等。如果 UI hmtl 已经发布在一个 web 服务器上，可用 url 访问到，则在 manifest.json 中用 url 引用它即可，不需要在 zip 文件中包含它。

注意：需要保证 manifest.json 里指定的沙盒 JS 代码文件等的相对路径和 zip 包中的相对路径保持一致。例如，如果我们有如下 manifest.json 文件，则沙盒 JS 代码文件以及 UI html 代码文件的路径需如下所示：

manifest.json:

{
    "name": "酷大师插件测试",
    "id": "sKMXdgqSoeiTGhD",
    "version": "1.0.0",
    "view": "./dist/ui.html",
    "main": "./dist/main.js"
}

zip 文件中的路径:

-- zip
   -- manifest.json
   -- dist
      -- main.js
      -- ui.html
      -- ui.js

新增发布

酷大师官方审核通过后，开发者可以在开放平台左侧栏点击“发布应用” -> "新增发布"，选择已审核通过的酷大师应用（插件），进入提交发布信息的步骤。

然后提交在开放平台以下素材，填写完整发布应用的表单，通过之后您就能在插件广场和酷大师“插件”菜单里看到您的插件了！

素材	规范	描述	参考
banner	1.尺寸：792×198 2.PNG、JPG格式	设计一张能代表你插件功能的banner	智能楼梯插件banner
插件LOGO	1.尺寸：80×80 2.PNG、JPG格式	设计一个能代表你插件功能的LOGO
插件简介	上限50字	请简单描述一下你的插件功能
插件详情	上限1000字	请描述一下插件的详细使用方法	示例：楼梯插件详情

点击访问→酷家乐应用市场：酷大师插件