kokomi.js 使用教程

kokomi.js 使用教程

项目介绍

kokomi.js 是一个用于 Web 3D 创作的 JavaScript 库，旨在封装 three.js 中最常用的一些功能，并使项目结构更加清晰。该库由 alphardex 开发，灵感来源于游戏《原神》中的角色珊瑚宫心海（Sangonomiya Kokomi）。kokomi.js 提供了丰富的功能，包括基础场景搭建、素材管理、组件化开发等，适用于各种 3D 网页应用的开发。

项目快速启动

准备工作

首先，确保你已经安装了 Node.js 和 npm。然后，通过以下命令克隆项目并安装依赖：

git clone https://github.com/alphardex/kokomi.js.git
cd kokomi.js
npm install

创建基础场景

以下是一个简单的示例，展示如何使用 kokomi.js 创建一个基础的 3D 场景：

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: number) => {
      box.spin(time);
    });
  }
}

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

运行项目

在项目根目录下运行以下命令启动开发服务器：

npm start

打开浏览器，访问 http://localhost:3000，你将看到一个旋转的白色方块，这标志着你已经成功启动了 kokomi.js 项目。

应用案例和最佳实践

案例一：Shader 创作

kokomi.js 支持 Shader 创作，以下是一个简单的 Shader 示例：

import * as kokomi from 'kokomi.js';

class Sketch extends kokomi.Base {
  create() {
    const screenQuad = new kokomi.ScreenQuad(this, {
      shadertoyMode: true,
      fragmentShader: `
        void main() {
          gl_FragColor = vec4(1.0, 0.0, 0.0, 1.0);
        }
      `
    });
    screenQuad.addExisting();
  }
}

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

案例二：素材管理

kokomi.js 提供了 AssetManager 类来管理素材的加载。以下是一个素材管理的示例：

import * as kokomi from 'kokomi.js';
import resourceList from './resources';

class Sketch extends kokomi.Base {
  create() {
    new kokomi.OrbitControls(this);
    this.camera.position.copy(new THREE.Vector3(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.copy(new THREE.Vector3(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);
    });
  }
}

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

典型生态项目

项目一：液晶球回归

该项目展示了如何使用 kokomi.js 结合 HTML 和 Raymarching 技术创建一个液晶球效果。项目地址：液晶球回归

项目二：粉碎弹珠小游戏

该项目使用 kokomi.js 开发了一个粉碎弹珠的小游戏，展示了 kokomi.js 在游戏