PixiCharacter SDK

一个基于 PixiJS 的轻量级角色动画 SDK，支持自定义外观、动画和语音功能。

特性

• 轻量级: 只包含核心功能，无冗余代码
• 模块化: 清晰的架构设计，易于扩展
• 类型安全: 完整的 TypeScript 支持
• 动画丰富: 内置多种动画效果
• 资源管理: 智能的资源加载和缓存
• 语音支持: 集成语音合成功能

安装

npm install pixijs-character-sdk

快速开始

import { PixiCharacter } from 'pixijs-character-sdk';

// 创建角色实例
const character = new PixiCharacter(container, {
    width: 600,
    height: 400,
    body: './assets/body.svg',
    clothes: './assets/clothes.svg',
    hat: './assets/hat.svg',
    onError: (error) => console.error(error)
});

// 执行动画
await character.wave();
await character.jump();
await character.spin();

项目结构

pixijs-sdk/
├── src/                    # 核心SDK源码
│   ├── core/              # 核心模块
│   │   ├── AnimationManager.ts
│   │   ├── AnimationPresets.ts
│   │   ├── CharacterRenderer.ts
│   │   ├── ResourceManager.ts
│   │   └── SpeechManager.ts
│   ├── types/             # 类型定义
│   ├── utils/             # 工具函数
│   ├── PixiCharacter.ts   # 主类
│   ├── lib.ts            # 库入口文件
│   └── index.ts          # 开发入口文件
├── demo/                  # 演示文件（不包含在构建中）
│   ├── SimpleDemo.tsx
│   ├── main.tsx
│   └── index.html
├── public/               # 静态资源（不包含在构建中）
│   └── assets/
├── dist/                 # 构建输出
│   ├── pixijs-character-sdk.es.js
│   ├── pixijs-character-sdk.umd.js
│   └── index.d.ts
└── dance-test.html       # 跳舞功能测试页面

构建优化

排除内容

• ✅ public/ 文件夹 - 静态资源文件
• ✅ demo/ 文件夹 - 演示代码
• ✅ React 依赖 - 外部化处理

构建输出

• ES模块: pixijs-character-sdk.es.js
• UMD格式: pixijs-character-sdk.umd.js
• 类型声明: index.d.ts

动画功能

基础动画

• wave() - 挥手动画
• jump() - 跳跃动画
• spin() - 旋转动画
• bounce() - 弹跳动画
• shake() - 摇晃动画
• move(x, y) - 移动动画

自定义参数

// 自定义动画参数
await character.wave({
    direction: 'left',
    angle: 0.5,
    duration: 1000
});

await character.jump({
    height: 60,
    bounces: 2,
    duration: 800
});

外观控制

动态换装

// 更换身体
await character.setBody('./assets/body2.svg');

// 更换衣服
await character.setClothes('./assets/shirt2.svg');

// 更换帽子
await character.setHat('./assets/hat2.svg');

手部控制

// 设置手部位置
character.setHandPosition('left', -30, -25);
character.setHandPosition('right', 30, -25);

// 获取手部位置
const leftPos = character.getHandPosition('left');

📝 API 文档

PixiCharacter 类

构造函数

new PixiCharacter(container: HTMLElement, config: CharacterConfig)

配置选项

interface CharacterConfig {
    width: number;
    height: number;
    body?: string;
    clothes?: string;
    hat?: string;
    leftHand?: string;
    rightHand?: string;
    leftHandPosition?: { x: number; y: number };
    rightHandPosition?: { x: number; y: number };
    onAnimationStart?: (name: string) => void;
    onAnimationEnd?: (name: string) => void;
    onSpeechStart?: (text: string) => void;
    onSpeechEnd?: (text: string) => void;
    onError?: (error: string) => void;
}

主要方法

• wave(params?) - 挥手动画
• jump(params?) - 跳跃动画
• spin(params?) - 旋转动画
• bounce(params?) - 弹跳动画
• shake(params?) - 摇晃动画
• move(x, y, params?) - 移动动画
• setBody(path) - 设置身体
• setClothes(path) - 设置衣服
• setHat(path) - 设置帽子
• setHandPosition(handType, x, y) - 设置手部位置
• getHandPosition(handType) - 获取手部位置
• speak(text) - 语音合成
• stop() - 停止所有动画
• destroy() - 销毁实例

🛠️ 开发

安装依赖

npm install

开发模式

npm run dev

构建库

npm run build

类型检查

npm run type-check