PLOY3D引擎系列教程

PLOY3D引擎系列教程

PLOY3D引擎【预览版】是卜云 PLOYCLOUD推出的基于WebGPU、WebGL2.0、WebAssembly和TypeScript开发的原生Web3D、AR和VR引擎。具有功能完备、轻量级、高性能的优势，可以在手机、平板、笔记本、PC电脑等全终端浏览器上稳定运行。是Web前端开发3D地图、3D可视化、数字孪生等智慧应用以及娱乐游戏的最佳选择。

提示：获取引擎SDK和样例代码请访问gitee以及查阅api文档 。更多引擎和引擎编辑器演示视频请关注抖音号。文章可转载，谢谢！

系列目录

• 简单的3D场景
• 简单的物理碰撞模拟场景
• 简单的GLTF模型导入
• 复杂的GLTF模型导入（包含骨骼蒙皮、网格变形表情、动画）
• 可扩展的包含骨骼驱动和动画驱动的角色控制器

---

---

一、PLOY3D应用的最基本框架

本文将介绍如何搭建PLOY3D应用的最基本框架，后续教程都在该框架下补充完善。这也是实际项目开发的建议起点。

二、使用步骤

1.在HTML中引入相关脚本

引入引擎SDK核心脚本和样例程序脚本：

<script src="./common/miaoverse/miaoverse.js"></script>
<script src="./js/examples.js"></script>

HTML页面装载完成后启动业务应用：

<script>
    // 资源包服务路径（发布前请修改）
    var packageUrl = "";
    // 后台接口服务路径（发布前请修改）
    var serviceUrl = "";
    // 引擎发布号（发布前请修改）
    var engineVer = "r01";

    // 页面装载完成后启动引擎，并运行业务应用
    window.onload = function () {
        // 启动APP类，该函数实现在examples.js样例脚本中
        Start("default", (app) => {
            console.log(app);
        });
    }
</script>

2.在TS脚本中实现实例化逻辑

创建PLOY3D引擎实例：

// 创建PLOY3D引擎实例
const Engine = new Miaoverse({
    // 引擎起动时间戳
    startTS: Date.now(),
    // 子线程脚本路径
    workerUrlJS: "./common/miaoverse/miaoverse.worker.js",
    // 进度条控制方法
    Progress(rate, msg, log) {
        App.Progress(rate, msg, log);
    },
    // ...其它配置项请查阅api文档
});

定义应用启动入口函数：

function Start(appid: string, callback: (app: WebApp) => void) {
    App = new WebApp();

    App.Startup()
        .then((app_) => {
            callback(app_);
        })
        .catch(msg => {
            Engine.Track(msg);

            callback(null);
        });
}

3.自定义实现WebApp类

实现页面UI绘制方法WebApp.InitUI：

protected async InitUI(progress: (rate: number, msg: string) => void) {

    // 可以使用React等在此绘制您的页面 ...

    progress(1.0, "UI渲染完成");

    return true;
}

实现引擎初始化方法WebApp.InitEngine：

protected async InitEngine(progress: (rate: number, msg: string) => void) {

    await Engine.Startup(progress);

    progress(1.0, "引擎初始化完成");

    return true;
}

实现场景初始化方法WebApp.InitScene：

protected async InitScene(progress: (rate: number, msg: string) => void) {
    // 以默认方法配置并运行场景
    // 该默认方法创建并激活了一个空白场景，并将鼠标事件关联到场景自带相机上，使用默认的相机控制逻辑
    // 用户可参考文档自定义实现该方法
    Engine.scenes.Run();

    // 可以在此处添加其它场景模型 ...

    progress(1.0, "场景初始化完成");

    return true;
}

实现应用启动方法WebApp.Startup：

public async Startup() {
    // 获取3D画布元素，引擎帧将渲染到该画布元素上
    this._canvas3d = document.getElementById("canvas3d");

    // 首先初始化UI，确保画布元素已经在DOM中
    await this.InitUI((rate: number, msg: string) => {
        this.Progress(0.1 * rate, msg, true);
    });

    // 初始化PLOY3D引擎
    await this.InitEngine((rate: number, msg: string) => {
        this.Progress(0.1 + 0.4 * rate, msg, true);
    });

    // 创建、激活并初始化3D场景
    await this.InitScene((rate: number, msg: string) => {
        this.Progress(0.5 + 0.5 * rate, msg, true);
    });

    // 响应ESC键关闭应用
    Engine.scenes.AddKeyboardListener("down", (key) => {
        if (key == 27 && this._started) {
            this.Shutdown();
        }
    });

    // 启动完成、关闭进度条
    this._started = true;
    this.Progress(-1, "");

    // 令引擎连续绘制60万帧
    // 通常我们不建议这么做，而是必要时在调用刷新画面，这有助于降低移动端能耗
    Engine.scenes.DrawFrame(600000);

    return this;
}

实现应用退出方法WebApp.Shutdown：

public async Shutdown() {
    if (!this._started) {
        return;
    }

    this._started = false;

    const state = await Engine.Shutdown();

    // 按正常流程关闭您的应用，并检视应用的终末状态，有助于发现应用开发中存在的一些问题
    console.log(state);
}

---

总结

以上即为PLOY3D应用的最基本结构，在具体项目中主要是修改场景初始化方法（WebApp.InitScene），并将UI中的数据和事件与场景内容联动起来，后续教程我们将逐步讲解。