解密 kokomi.js，Three.js 的效率神器！前端卷王们偷偷在用

admin

2025年4月22日 0:50 本文热度 182

作者 alphardex

alphardex，对 WebGL、Three.js 和 Shader 编程有浓厚的兴趣。她的个人简介中提到喜欢编码、动漫、游戏和“可爱的东西”（kawaii mono），这也体现在她项目的命名上，比如 kokomi.js 的灵感来源于《原神》中的角色“珊瑚宫心海”（Sangonomiya Kokomi）。

一位穿梭在顶点着色器与动漫结界之间的技术魔女。

开源 kokomi.js

介绍

kokomi.js 是一个基于 TypeScript 开发的 Three.js 辅助库，旨在简化 Web 3D 开发的流程。它通过封装 Three.js 的常用功能，提供更高层次的抽象，让开发者能够更快速地搭建 3D 场景，同时保持代码结构清晰、可复用性强。项目的 GitHub 描述是：“A growing three.js helper library”（一个不断成长的 Three.js 辅助库），目前已有 400+ 星标，表明它在社区中获得了一定认可。

部分案例

模型展示

Shadertoy 集成

持续效应

渲染纹理

反射镜

无限画廊

更多案例

https://kokomi-js.netlify.app/examples/

特点

模块化设计

项目提供了诸如 Box、OrbitControls、AssetManager 等预封装组件，开发者可以直接调用这些类来创建和管理 3D 元素。
通过继承 kokomi.Base 类，开发者可以自定义场景逻辑，保持代码的组织性。

资源管理

AssetManager 类统一管理纹理、模型（如 GLTF）、字体等资源，支持异步加载，提升了复杂场景的开发效率。

易用性

提供简洁的 API，例如 box.spin(time) 用于旋转物体，OrbitControls 用于相机控制，降低了 Three.js 的学习曲线。

TypeScript 支持

项目使用 TypeScript 编写，提供了类型定义，方便开发者在现代前端开发环境中获得代码补全和类型检查的支持。

快速使用

首先安装 kokomi.js

npm i kokomi.js

由于它是基于 Three.js 的封装库，确保项目中已安装 three：

npm i three

创建一个简单的 3D 场景，包含一个旋转的立方体：

kokomi.Base：基类，提供了场景、相机、渲染器等基础设置。

kokomi.Box：封装的立方体类，默认带白色材质。

OrbitControls：鼠标控制相机旋转和缩放。

update：每帧调用的更新函数，time 参数由内部时钟提供。

import * as kokomi from"kokomi.js";

class Sketch extends kokomi.Base {
  create() {
    // 创建一个立方体
    const box = new kokomi.Box(this);
    box.addExisting(); // 将立方体添加到场景中

    // 添加相机控制
    new kokomi.OrbitControls(this);

    // 更新函数：让立方体旋转
    this.update((time) => {
      box.spin(time);
    });
  }
}

// 初始化
const sketch = new Sketch();
sketch.create();

运行后，你会在浏览器中看到一个可交互的旋转立方体：

加载外部资源

使用 AssetManager 加载 3D 模型（例如 GLTF 格式的狐狸模型）：

AssetManager：异步加载资源，ready 事件触发时表示加载完成。

资源类型：支持 texture（2D 贴图）、cubeTexture（3D 贴图）、gltfModel（模型）、font（字体）等。

import * as THREE from"three";
import * as kokomi from"kokomi.js";

// 定义资源列表
const resourceList = [
  { name: "foxModel", type: "gltfModel", path: "/models/Fox/glTF/Fox.gltf" },
];

class Sketch extends kokomi.Base {
  create() {
    // 设置相机位置
    this.camera.position.set(6, 4, 3);

    // 添加光源
    const ambientLight = new THREE.AmbientLight(0xffffff, 0.5);
    this.scene.add(ambientLight);
    const dirLight = new THREE.DirectionalLight(0xffffff, 0.6);
    dirLight.position.set(1, 2, 3);
    this.scene.add(dirLight);

    // 加载资源
    const assetManager = new kokomi.AssetManager(this, resourceList);
    assetManager.emitter.on("ready", () => {
      const foxModel = assetManager.items.foxModel;
      foxModel.scene.scale.set(0.02, 0.02, 0.02); // 缩放模型
      this.scene.add(foxModel.scene); // 添加到场景
    });

    // 添加相机控制
    new kokomi.OrbitControls(this);
  }
}

const sketch = new Sketch();
sketch.create();

项目配置

// vite.config.js
import { defineConfig } from "vite";

export default defineConfig({
  // 确保正确解析 .gltf 文件
  assetsInclude: ["**/*.gltf"],
});

在线编程

https://kokomi-sandbox.netlify.app/

源码

https://github.com/alphardex/kokomi.js

文档

https://kokomi-docs.netlify.app/

最后

尽管文档生态仍需完善，还有待加入更多高级特性，但kokomi.js 已展现出成为 Three.js 轻量化标杆工具的潜力，尤其适合对 Web 3D 感兴趣的前端开发者尝试。如果你正在探索 Three.js 或想快速实现一个 3D 项目，不妨试试这个库！

阅读原文：原文链接

该文章在 2025/4/22 16:43:42 编辑过

关键字查询

正在查询...