vis-three/vis-three

A web 3D development framework for assembled based on three.js

A web 3D development framework for assembled based on three.js

VIS-THREE

基于 three.js 的组装式前端 3D 开发框架。

夫物速成则疾亡，晚就则善终。朝华之草，夕而零落；松柏之茂，隆寒不衰。是以大雅君子恶速成。——《群书治要》

说明

• main 分支正在进行0.7.x版本大更新，npm最新版本会升级到0.7.x版本，进行 npm 测试调试，docs 会进行0.7.x版本升级。
• 当前的文档版本和稳定 npm 版本，请查看0.6.x分支。
• 使用文档版本请规定版本号：npm i @vis-three/xxxx@^0.6.0。

主页、文档、案例在线地址

github 入口：https://vis-three.github.io

gitee 入口：https://vis-three.gitee.io

gitee 的 pages 服务目前已暂停服务，gitee 的视频类静态资源访问会失效，如有需要请移步 github。

文档内容不一定是最新版本内容，持续更新。当前的文档版为：0.6.x

贡献者

赞助者

赞助者

赞助商

关于 issue

issue 的使用

issue 不只是用来提问讨论，也是一个文档，如果您有相关的问题，不妨先去历史 issue 中开启全部查找，分为 2 个平台:

• github
• gitee

这样可以避免重复提问与重复的回答，节省大家的时间与精力。

新建 issue

当前的新建 issue 有不同的 issue 分类模板，选择相应的 issue 模板根据模板指引进行 issue 新增。

关于赞助模式

开发赞助

赞助不一定就是要付费，只要您为本项目做出贡献比如成为贡献者，就是对本项目的赞助，如何成为贡献者请阅读下方的贡献者与开发组部分。

付费赞助

长期赞助：长期赞助或订阅式的赞助对于当下的环境来说还是比较难的，随喜功德了。

需求赞助：对一个需求的解决进而进行的付费赞助，开发组罗列以下几个 issue 标签作为可需求赞助支持点：

• 新增标签
• 文档标签
• 案例标签
• 提问标签

赞助额度：由于不同需求工作量会不同，具体赞助额度可进入社区 Q 群中商讨，群内会有赞助标准与讨论空间。

多人赞助：如果多人所提 issue 在功能需求上差不多，可进行 issue 与赞助分摊合并，方便大家。

赞助鸣谢：赞助后的相关信息会计入上方的赞助名单中公开。

诚信与公益：如果您非常需要一个功能，而暂时又无法达成赞助条件，我们可以为您提供帮助，因为我们相信人都是善良与真诚的。如果您提的需求或功能非常的有价值与富有建设性，我们会把它纳入开发核心流程，并不需要赞助费用。

贡献者与开发组

可以阅读贡献指南，对本项目进行熟悉。

如何快速上手入门？

issue 部分会进行相关的开发任务分类：

• 任务：入门
• 任务：初级
• 任务：中级
• 任务：高级

如果您不知道如何开始，或者想通过实践熟悉项目，可以采取解决相应的任务issue 进行。

成为贡献者

提交您的代码 pr，并通过管理员的代码审核。

贡献开发收益

如果您完成了相关的 issue，并且这个 issue 是属于需求赞助部分的，您将收到此 issue 的全额赞助费用。

如果有赞助商进行长期赞助，也会获得贡献占比的相应分红。

贡献开发鸣谢

只要提交并通过代码审核，您就会自动成为贡献者并记录于上方的贡献者名单中。

备注

• gitee 仓库为 github 的同步备份仓库，pr 提交请以 github 为基准
• github 地址：https://github.com/vis-three/vis-three

vis-three's Issues

canvas,url引入问题

1.使用canvas二维绘图,toBlob toDataURL转换格式,loadResourcesAsync导入该资源文件失败！！！！
2.想使用CANVASTEXTURE等，无导入canvas.
注:辛苦您了，呜呜呜呜，掉头发掉头发

engine 没有 setSceneBySymbol 方法，ts报错。

问题描述

engine 没有 setSceneBySymbol 方法，ts报错。运行没问题，

问题或报错截图

无

运行环境

系统: windows@10
浏览器： chrome@131
脚手架： [email protected]
node: 14.20.0

可调试环境

No response

附加代码上下文

const engine = new ModelingEngineSupport()

const scene = generateConfig(CONFIGTYPE.SCENE);
engine.applyConfig(scene).setSceneBySymbol(scene.vid);

启动 packages/examples 和packages/website时候报错

问题描述

是不是vis-three/packages/library/package.json少安装了"@vis-three/middleware" 库

问题或报错截图

运行环境

系统: windows@10
浏览器： chrome@131
脚手架： [email protected]
node: 14.20.0

可调试环境

No response

附加代码上下文

No response

模块新增：@vis-three/library-plugin统一插件模块

任务描述

对于依赖npm插件较多的项目，需要一个包能提供所有的插件供项目使用，解决多次安装的问题。

需求连接：#17

目前可以参考：@vis-three/library-module的模式进行。
参考位置：/packages/library/module

任务步骤

github的pr工作流参考：https://zhuanlan.zhihu.com/p/584834288

1. 移动/packages/library目录
2. 新增plugin文件夹，参照module文件夹进行npm模块构建，比如package.json等等。
3. git与pr提交格式，commit信息附带本issue连接，示例：feat：本issue标题—— https://github.com/vis-three/vis-three/issues/xxx

任务周期

完成时

Cannot install dependencies in stackblitz

问题描述

I fork this Repositories and try to pnpm i dependencies in stackblitz,but it can't install dependencies. I am not familiar with PNPM.I hope these dependencies can be installed in stackblitz.what should i do?

问题或报错截图

Progress: total 1112, downloaded 1103
 ERROR  Failed to fetch dependencies:

• [email protected]
• [email protected]
• [email protected]
• [email protected]
• @babel/[email protected]
• [email protected]
• @algolia/[email protected]
• @eslint/[email protected]
• [email protected]

HttpError: Failed to fetch dependencies:

• [email protected]
• [email protected]
• [email protected]
• [email protected]
• @babel/[email protected]
• [email protected]
• @algolia/[email protected]
• @eslint/[email protected]
• [email protected]
  at _0x13327e.fetchDependencies (https://w-corp.staticblitz.com/fetch.worker.22b9f6d5.js:1:262853)

运行环境

❯ node -v
v18.18.0

可调试环境

https://stackblitz.com/~/github.com/pwlviolet/vis-three

附加代码上下文

None

解决问题的回报选择

提供修复 pr 或者完善项目（解决任务issue，文档完善，代码优化，示例优化等等）。

文档新增：提供文档的英文版本

任务描述

提供可切换语言的文档，新增英文文档版本。

需求连接：#19

任务步骤

github的pr工作流参考：https://zhuanlan.zhihu.com/p/584834288

1. 移动/package/docs目录。
2. 参照vitepress文档进行项目文档的国际化处理。
3. git与pr提交格式，commit信息附带本issue连接，示例：feat：本issue标题—— https://github.com/vis-three/vis-three/issues/xxx

任务周期

完成时

能否提供一份英文文档以供threejs社区来讨论一下这个框架

功能描述

希望能提供一份英文文档

使用场景

供全世界的threejs社区成员来讨论一下这个框架的价值和意义所在

代码示例

No response

插件优化：loaderManagerPlugin的事件优化

任务描述

loaderManagerPlugin插件的loading事件希望提供一个实时进度。

需求连接：#9

添加的字段：

export interface LoadingEvent extends BaseEvent {
 //...
  loadProgress: number;
}

任务步骤

github的pr工作流参考：https://zhuanlan.zhihu.com/p/584834288

1. fork仓库：https://github.com/vis-three/vis-three
2. git clone到本地。
3. IDE打开进行依赖安装：pnpm i （如果没有pnpm预先安装pnpm）
4. cd到位置： 本地项目路径\packages\plugins\loaderManager\LoaderManager.ts进行相关代码修改。
5. 进行pr提交，commit信息附带本issue连接，示例：feat：loaderManagerPlugin插件优化。—— https://github.com/vis-three/vis-three/issues/xxx

此框架是否能支持微信小程序？

功能描述

此框架是否能支持微信小程序？这样可以针对微信小程序上做一些threejs的开发

使用场景

代码示例

No response

path配置化的三维路径绘制支持

功能描述

希望能提供一个能在任意平面进行路径绘制的api

使用场景

场景漫游功能，需要绘制漫游路径再进行相机动画制作

代码示例

No response

使用DisplayEngineSupport时 对transformControls设置mode会导致

问题描述

1. 我做了什么...
vue3中
engine = new DisplayEngineSupport()
engine!.transformControls.setMode("rotate");
2. 希望实现什么 ...
设置TransformControls的mode 能够对mesh进行变换
3. 但是实际上是什么 ...
报错了捏
4. 我认为问题可能出现在哪里...
似乎和CSS3Rander有关但不确定

问题或报错截图

运行环境

系统: windows@10
浏览器： [email protected]
脚手架： "vite": "^5.2.8",
node:  20.7.0

可调试环境

No response

附加代码上下文

<script setup lang="ts">
import {onMounted, ref} from "vue";
import {DisplayEngineSupport} from "@vis-three/engine-display-support";
import {GridHelperPlugin} from "@vis-three/plugin-grid-helper";
import {CONFIGTYPE, generateConfig} from "@vis-three/middleware";
import {TransformControlsPlugin} from "@vis-three/plugin-transform-controls";
import {SelectionPlugin} from "@vis-three/plugin-selection";
import {SelectionSupportPlugin} from "@vis-three/plugin-selection-support";
import {TransSelectEventStrategy} from "@vis-three/strategy-trans-select-event";
import {ModelingEngineSupport} from "@vis-three/engine-modeling-support";
import {WebGLRendererStrategy} from "@vis-three/strategy-webgl-render";

let engine: ModelingEngineSupport | null = null
onMounted(() => {
  engine = new DisplayEngineSupport()
      // 坐标轴
      .install(GridHelperPlugin({
        axesColor: 'rgba(250,220,111,0.99)'
      }))
      //物体变换控制器
      .install(TransformControlsPlugin())
      //选中
      .install(SelectionPlugin())
      .install(SelectionSupportPlugin())

      //选择事件策略
      .exec(TransSelectEventStrategy())
      .exec(WebGLRendererStrategy())
      .setDom(document.getElementById("ar2"))
      .setSize()
      .play()

  // engine!.transformControls.setMode("scale");
  // engine!.transformControls.setMode("translate");
  engine!.transformControls.setMode("rotate");


  const defaultScene = generateConfig(CONFIGTYPE.SCENE);

  engine.applyConfig(defaultScene).setSceneBySymbol(defaultScene.vid);

// 设置注入引擎
  generateConfig.injectEngine = engine;
// 开启注入场景
  generateConfig.injectScene = true;
// 开启自动注入
  generateConfig.autoInject = true;

  generateConfig(CONFIGTYPE.POINTLIGHT, {
    color: "rgb(255, 255, 255)",
    position: {
      y: 30,
    },
  });

  const commonGeometry = generateConfig(CONFIGTYPE.BOXGEOMETRY, {
    width: 10,
    height: 10,
    depth: 10,
  });

  const boxMaterial = generateConfig(CONFIGTYPE.MESHSTANDARDMATERIAL, {
    color: "rgb(255, 105, 100)",
  });

  generateConfig(CONFIGTYPE.MESH, {
    geometry: commonGeometry.vid,
    material: boxMaterial.vid,
    position: {
      x: 10,
    },
  });

  generateConfig(CONFIGTYPE.LINE, {
    geometry: commonGeometry.vid,
  });

  const pointsMaterial = generateConfig(CONFIGTYPE.POINTSMATERIAL, {
    color: "rgb(255, 255, 255)",
  });

  generateConfig(CONFIGTYPE.POINTS, {
    geometry: commonGeometry.vid,
    material: pointsMaterial.vid,
    position: {
      x: -10,
    },
  });

  resizeObserver.observe(arDiv2.value!);
})
const arDiv2 = ref<HTMLDivElement>()
const resizeObserver = new ResizeObserver((entries: any) => {
  if (engine) engine.setSize().render()
});
</script>

<template>
  <div id="ar2" ref="arDiv2">
    <div></div>
  </div>
</template>

<style scoped>
#ar2 {
  width: 100vw;
  height: 100vh;
  background-color: #fff;
  position: relative;
}

</style>

解决问题的回报承诺选择

一定的赞助资金

怎么通过脚本动画设置一个不在原点的模型进行自转？

问题描述

1. 我做了什么...
2. 希望实现什么 ...
3. 但是实际上是什么 ...
4. 我认为问题可能出现在哪里...

问题或报错截图

运行环境

系统: windows@10
浏览器： chrome@131
脚手架： [email protected]
node: 14.20.0

可调试环境

No response

附加代码上下文

No response

解决问题的回报选择

提供修复 pr 或者完善项目（文档完善，代码优化，示例优化等等）

TransformControls 移动对象没有更新值

问题描述

最新版本 b1ed66fc2e2e41a5fa9e66e432bbced1c270a001

TransformControlsSupportStrategy.html

问题或报错截图

运行环境

系统: windows@10
浏览器： chrome@131
脚手架： [email protected]
node: 14.20.0

可调试环境

No response

附加代码上下文

No response

解决问题的回报承诺选择

提供修复 pr 或者完善项目（解决任务issue，文档完善，代码优化，示例优化等等）。

0.6.7版本中Engine的类型中少了play方法的类型

问题描述

1. 我在使用了typescript的项目中尝试使用vis-three
2. 在实例化引擎的时候发现 Engine 实例少了play方法的类型提示
3. 但是实际上应该是有这个方法的

问题或报错截图

无

运行环境

node: 14.20.0

可调试环境

No response

附加代码上下文

No response

在使用了plugin-orbit-controls插件后，尝试直接修改Engine实例的camera的position，会导致plugin-orbit-controls失效

问题描述

1. 我尝试着在实现一个摄像机视角飞向某一点的功能，在使用了plugin-orbit-controls插件后，我直接修改�Engine实例的camera的position，会导致plugin-orbit-controls失效，有什么办法去解决这个问题吗

问题或报错截图

无

运行环境

系统: windows@10
浏览器： chrome@131
脚手架： [email protected]
node: 14.20.0

可调试环境

No response

附加代码上下文

No response

使用DisplayEngineSupport 构建场景后 移动端视角的旋转异常

问题描述

反馈一个bug..使用DisplayEngineSupport 构建场景后在web端右键旋转视角是正常的，但是在移动端触屏尝试旋转视角只能移动一点点然后就卡住了像是pointmove事件丢失了一样。谷歌浏览器的移动端模拟调试也能复现这个问题。
在您的demo中这个问题也是存在的应该是个bug
https://vis-three.github.io/exhibition-hall//easyFactory/index.html

问题或报错截图

无

运行环境

系统: windows@11
浏览器： [email protected]
脚手架： [email protected]
node: v16.19.1

可调试环境

No response

附加代码上下文

No response

模块新增：path3配置化支持

任务描述

目前的配置化path只有支持二维路径，需要新增三维路径的配置化能力。

需求连接：#15

目前在：vis-three\packages\library\module\path\PathConfig.ts中已经预置了path3相关的配置声明与获取函数，暂时没有补全处理器等内容。

可以参照：vis-three\packages\library\module\path\processors\PathProcessor.ts进行Path3Processor的处理器编写。

export default defineProcessor<PathConfig, Path, EngineSupport, PathCompiler>({
  type: "Path3",
  config: getPath3Config,
  commands: {},
  create(config, engine) { },
  dispose(target) {},
});

部分内容根据实际情况进行修改。

任务步骤

github的pr工作流参考：https://zhuanlan.zhihu.com/p/584834288

1. 移动vis-three\packages\library\module\path。
2. 在PathConfig.ts中增加path3相关的配置声明，配置项。
3. 在processors/Path3Processor.ts中补全相关的处理逻辑。
4. 回到path/index.ts中注册Path3Processor处理器
5. pnpm run build更新包模块
6. 修改package.json的版本号
7. git与pr提交格式，commit信息附带本issue连接，示例：feat：本issue标题—— https://github.com/vis-three/vis-three/issues/xxx

任务周期

完成时

包结构优化

功能描述

最近看了一下tresjs的文档，发现这个库把插件的管理都放在Cientos这个包下边，在读vis-three的文档时发现插件都是独个分散的，看起来很难受，这个可以优化一下吗。以下是这个库的链接https://docs.tresjs.org/guide/，https://cientos.tresjs.org/。(ps：最近在学习图形学基础和threejs，感觉暂时没有能力对库做改进，望您见谅)

使用场景

No response

代码示例

No response

generateConfig ts检查总报红，又不想写断言

loadermanager需要实时的加载进度与大模型加载卡顿的优化

功能描述

loadermanager的loading事件希望可以返回实时进度，而不是只返回成功或者失败

使用场景

在加载较大模型时，进度条会卡住，用户体验不好

关于transformControls的addEventListener问题

问题描述

你好， 因为设置轨道控制器的鼠标左键拖动作为旋转，在使用自由变换控件的时候，左键拖动物体时，就需要禁用轨道控制器。
出现的问题是，当我监听`dragging-changed`事件的时候,没有监听到，但是`change`事件是没问题的。
官网类似的例子是 https://threejs.org/examples/?q=spline#webgl_geometry_spline_editor

问题或报错截图

运行环境

系统: windows@10
浏览器： chrome@131
脚手架： [email protected]
node: 14.20.0

可调试环境

No response

附加代码上下文

engine.applyConfig(commonGeometry, boxMaterial, box)
    defaultScene.children.push(box.vid)
    engine.transformControls.addEventListener('dragging-changed', function (event) {
      engine.orbitControls.enabled = !event.value;
    })

关于插件的配置问题

问题描述

engine.applyConfig(generateConfig(CONFIGTYPE.ORBITCONTROLS,{
    mousebuuttins:{}
}));
配置插件的时候mousebuuttins不在CONFIGTYPE里，应该怎么改呢

问题或报错截图

无

运行环境

系统: windows@10
浏览器： chrome@131
脚手架： [email protected]
node: 14.20.0

可调试环境

No response

附加代码上下文

No response

文档的配色看起来有点晃眼，能调整下么？

希望VideoLoader中的参数能控制

功能描述

packages/plugins/loaderManager/loader/VideoLoader.ts中
static autoplay = true;
static preload: "" | "none" | "metadata" | "auto" = "auto";
static muted = true;
static loop = true;
另外创建video dom希望隐藏掉

使用场景

1.加载视频纹理

代码示例

import {ImageLoader, Loader, LoadingManager, Cache} from "three";

export class VideoLoader extends Loader {
    autoplay = false;
    static preload: "" | "none" | "metadata" | "auto" = "auto";
    muted = true;
    loop = true;

    constructor(manager?: LoadingManager) {
        super(manager);
    }

    load(
        url: string,
        onLoad?: (video: HTMLVideoElement) => void,
        onProgress?: (event: ProgressEvent) => void,
        onError?: (event: string | Event) => void
    ): HTMLVideoElement {
        if (this.path !== undefined) {
            url = this.path + url;
        }
        this.manager.itemStart(url);
        url = this.manager.resolveURL(url);

        const cached = Cache.get(url);

        if (cached !== undefined) {
            setTimeout(() => {
                if (onLoad) onLoad(cached);

                this.manager.itemEnd(url);
            }, 0);

            return cached;
        }

        const video = document.createElement("video");
        video.preload = VideoLoader.preload;
        video.autoplay = this.autoplay;
        video.loop = this.loop;
        video.muted = this.muted;
        video.src = url;
        video.style.position = "fixed";
        video.style.top = "0";
        video.style.left = "0";
        video.style.zIndex = "-1";
        document.body.appendChild(video);

        video.oncanplay = () => {
            Cache.add(url, video);
            this.manager.itemEnd(url);
            if (onLoad) onLoad(video);
        };

        video.onerror = (e) => {
            this.manager.itemEnd(url);
            if (onError) onError(e);
        };

        return video;
    }
}

pathDrawingPlugin如何才能设置z坐标让线段在别的平面上也可以绘制出来，现在只能在xoy平面上进行绘制

问题描述

希望可以路径绘制插件可以提供绘制z坐标的能力

问题或报错截图

无

运行环境

系统: windows@10
浏览器： chrome@131
脚手架： [email protected]
node: 14.20.0

可调试环境

No response

附加代码上下文

No response

解决问题的回报选择

提供修复 pr 或者完善项目（文档完善，代码优化，示例优化等等）

文档优化：错别字与语序优化

任务描述

对于当前文档内容中存在的错别字，遗漏字，容易理解错的语句和不通顺的语句进行优化。

任务步骤

github的pr工作流参考：https://zhuanlan.zhihu.com/p/584834288

1. fork仓库：https://github.com/vis-three/vis-three
2. git clone到本地。
3. IDE打开进行依赖安装：pnpm i （如果没有pnpm预先安装pnpm）
4. cd到位置： 本地项目路径\vis-three\packages\docs
5. 对：本地项目路径\vis-three\packages\docs\docs\start目录下的文件进行相关优化。
6. 进行pr提交，commit信息附带本issue连接，示例：docs：优化start/intro.md的相关文字内容。—— https://github.com/vis-three/vis-three/issues/xxx

备注

长期任务，不关闭。

策略：TransSelectEventStrategy 在mac上左键+ctrl 无法多选（mac上此操作等同于右键的菜单调用）

使用window.oncontextmenu=e=>e.preventDefault（）
阻止右键菜单事件后 原来的 click 无法在ctrl+左键时触发。

建议使用alt+左键的组合
vis-three：0.5.3
@vis-three/trans-select-event-strategy:0.5.1

git版本貌似与视频版本不同，约束器无法使用

问题描述

1. 根据BV1sb4y1j7WZ该视频进行操作，发现一些功能与视频不同无法实现，约束器无法使用
2. 贴图透明度无法正确调整

问题或报错截图

运行环境

源码本地启动运行

可调试环境

No response

附加代码上下文

No response

项目装包报错

问题描述

node版本:16.12.0
pnpm版本:6.11.5

问题或报错截图

request to https://registry.npmjs.org/@cypress/code-coverage/-/code-coverage-3.10.0.tgz failed, reason: connect ECONNREFUSED 127.0.0.1:21882

运行环境

系统: windows@10
浏览器： chrome@131
脚手架： [email protected]
node: 16.12.0

可调试环境

No response

附加代码上下文

No response

解决问题的回报选择

提供修复 pr 或者完善项目（文档完善，代码优化，示例优化等等）

启动报effectComposer 和 EffectComposerPlugin 错误

简单使用：

警告提示如下：

engine need install effectComposer plugin that can use pass compiler

EffectComposerPlugin: hope install close behind the WebglRendererPlugin, because WebglRendererPlugin`s renderFun can be dispose. if you not do this, render are prone to bugs

这该如何解决

lookAt()方法只生效一帧就失效了

问题描述

engine.camera.lookAt()函数不能设置target

问题或报错截图

无报错，很奇怪

运行环境:

• 系统: windows@10
• 浏览器： chrome@131
• 脚手架： [email protected]
• node：14.20.0
• 其他附加

附加代码上下文或者可调试环境

毕竟处理问题的人并不是提问人员，除了报错之外，很多时候是使用与需求冲突，请提供出错时代码的上文，还有与此功能关联的代码模块。

如果功能偏多，请将功能简化后形成可下载调试的开源仓库或者在线调试环境。

然后提供相关的开源仓库连接或者在线调试连接。

操作或者编码逻辑

1. 先使用了什么
2. 然后发现影响了什么
3. 看见了错误

预期行为

应该看向我设置的值

解决问题的回报选择

• 提供修复 pr 或者完善项目（文档完善，代码优化，示例优化等等）。
• 一定的赞助资金。

为了避免形成白嫖习惯和依赖性习惯，对于非 bug，或者非新增，非特色等提问需要选择回报模式，比如一些信息可以从文档获取，或者是自己的技术水平和理解水平导致的问题，能够提供一定的警醒作用。具体详情请进入：QQ 群：586362945 详谈。

ts构建引擎时声明报错，安装插件后部分api无法给予相关提示

engine.play()编译报错
engine.render()方法未提供默认参数