@linx/3d-core

Pure JavaScript 3D 角色引擎核心包，无框架依赖。

安装

npm install @linx/3d-core three

特性

• 🎭 Character3DViewer - 主控制器类
• 📦 模型加载（GLB/FBX）
• 🎨 姿势管理
• 🎬 动画管理
• 🎯 无框架依赖
• 📘 完整 TypeScript 支持

快速开始

import { Character3DViewer } from '@linx/3d-core';

// 创建容器元素
const container = document.getElementById('character-container');

// 创建 viewer 实例
const viewer = new Character3DViewer(container, {
  cameraView: 'full',
  cameraRotateEnable: true,
  lightAmbientIntensity: 2
});

// 加载角色
await viewer.showAvatar({
  url: 'https://models.readyplayer.me/your-avatar-id.glb',
  body: 'F',
  emotion: 'neutral'
});

// 开始渲染循环
viewer.start();

// 控制角色
viewer.startSpeaking();
viewer.setEmotion('happy');
await viewer.playPose('sitting', 5);

API

Character3DViewer

主控制器类。

构造函数

constructor(container: HTMLElement, options?: Character3DViewerOptions)

方法

• showAvatar(config: AvatarConfig): Promise<void> - 加载并显示角色
• start(): void - 开始渲染循环
• stop(): void - 停止渲染循环
• startSpeaking(): void - 开始说话动画
• stopSpeaking(): void - 停止说话动画
• setEmotion(emotion: string): void - 设置情绪
• setView(view: CameraView): void - 设置相机视角
• playPose(name: string, duration?: number): Promise<void> - 播放姿势
• playAnimation(url: string, duration?: number): Promise<void> - 播放动画
• playGesture(name: string, duration?: number, mirror?: boolean): void - 播放手势
• dispose(): void - 销毁实例

管理器

PoseManager

姿势管理器。

import { PoseManager } from '@linx/3d-core';

const poseManager = new PoseManager();
poseManager.registerPose('custom', poseTemplate);
const pose = poseManager.getPose('custom');

AnimationManager

动画管理器。

import { AnimationManager } from '@linx/3d-core';

const animManager = new AnimationManager();
animManager.setEmotion('happy');
animManager.setState('talking');

ModelLoader

模型加载器。

import { ModelLoader } from '@linx/3d-core';

const loader = new ModelLoader();
const gltf = await loader.loadGLB('model.glb');
const fbx = await loader.loadFBX('animation.fbx');

配置选项

interface Character3DViewerOptions {
  // 相机设置
  cameraView?: 'full' | 'mid' | 'upper' | 'head';
  cameraDistance?: number;
  cameraX?: number;
  cameraY?: number;
  cameraRotateEnable?: boolean;
  cameraPanEnable?: boolean;
  cameraZoomEnable?: boolean;
  
  // 光照设置
  lightAmbientColor?: number | string;
  lightAmbientIntensity?: number;
  lightDirectColor?: number | string;
  lightDirectIntensity?: number;
  
  // 渲染设置
  pixelRatio?: number;
  fps?: number;
  
  // 角色设置
  avatarEmotion?: string;
  movementFactor?: number;
}

License

MIT