npm package: @galacean/particle-runtime
Description: Configuration-driven particle runtime with Vite/Vitest, UMD build exposing ParticleSystem.
Latest version: 0.0.9

# Particle Runtime

🎆 基于 Galacean Engine 的配置驱动粒子系统运行时库

## ✨ 特性

- **配置驱动**：通过 JSON 配置创建复杂的粒子效果
- **多种构建格式**：支持 ES Module、CommonJS 和 UMD 格式
- **CDN 友好**：可直接通过 CDN 在浏览器中使用
- **类型安全**：完整的 TypeScript 类型定义
- **易于使用**：简单的 API，一行代码创建粒子效果

## 📦 安装

### NPM 安装

```bash
npm install particle-runtime @galacean/engine
```

### CDN 使用

```html
<!-- 引入 Galacean Engine -->
<script src="https://unpkg.com/@galacean/engine@latest/dist/browser.min.js"></script>

<!-- 引入 Particle Runtime -->
<script src="https://unpkg.com/particle-runtime@latest/dist/index.umd.js"></script>
```

## 🚀 快速开始

### ES Module 方式

```typescript
import { ParticleSystem } from 'particle-runtime';

const config = {
    name: "fire-effect",
    particles: [{
        entityName: "fire",
        material: {
            baseColor: { r: 1, g: 0.5, b: 0, a: 1 },
            blendMode: "additive"
        },
        main: {
            duration: 5.0,
            isLoop: true,
            startLifetime: { mode: "constant", constant: 2.0 },
            startSpeed: { mode: "constant", constant: 2.0 },
            startSize: { mode: "constant", constant: 0.5 },
            maxParticles: 100,
            simulationSpace: "world"
        },
        emission: {
            enabled: true,
            rateOverTime: { mode: "constant", constant: 30 }
        }
    }],
    global: {
        camera: { position: { x: 0, y: 0, z: 5 } }
    },
    hierarchy: {
        "fire": { parent: "root", position: { x: 0, y: 0, z: 0 } }
    }
};

// 创建粒子效果
const effect = await ParticleSystem.create(config, 'canvas-id');
```

### CDN 方式

```html
<!DOCTYPE html>
<html>
<head>
    <title>Particle Effect</title>
</head>
<body>
    <canvas id="canvas" width="800" height="600"></canvas>
    
    <script src="https://unpkg.com/@galacean/engine@latest/dist/browser.min.js"></script>
    <script src="https://unpkg.com/particle-runtime@latest/dist/index.umd.js"></script>
    
    <script>
        // 使用全局变量 ParticleRuntime
        const effect = await ParticleRuntime.ParticleSystem.create(config, 'canvas');
    </script>
</body>
</html>
```

## 🎮 API 参考

### ParticleSystem.create()

创建粒子效果的主要方法。

```typescript
static async create(config: ParticleConfig, canvasId: string | HTMLCanvasElement): Promise<ParticleEffect>
```

**参数：**
- `config`: 粒子配置对象
- `canvasId`: Canvas 元素的 ID 或 Canvas 元素本身

**返回：** `ParticleEffect` 实例

### ParticleEffect 方法

```typescript
// 控制播放
effect.play();     // 播放
effect.pause();    // 暂停
effect.stop();     // 停止
effect.reset();    // 重置

// 获取状态
effect.isPlaying;  // 播放状态
effect.getConfig(); // 获取配置

// 销毁资源
effect.destroy();  // 销毁效果
```

## 📋 配置说明

粒子配置对象包含以下主要部分：

```typescript
interface ParticleConfig {
    name: string;                    // 效果名称
    particles: ParticleSystemConfig[]; // 粒子系统数组
    global?: GlobalConfig;           // 全局配置
    hierarchy?: HierarchyConfig;     // 层级结构
}
```

详细的配置规范请参考：[配置 Schema 文档](./docs/particle-system-config-schema.md)

## 🎯 示例

### 基础示例

查看 `examples/` 目录中的示例文件：

- [`simple-usage.html`](./examples/simple-usage.html) - 简单使用示例
- [`cdn-usage.html`](./examples/cdn-usage.html) - 完整的 CDN 使用演示

### 复杂效果

查看 `case/test.ts` 文件，包含完整的火焰效果配置示例。

## 🛠️ 开发

### 环境要求

- Node.js 16+
- TypeScript 5.0+

### 安装依赖

```bash
npm install
```

### 开发命令

```bash
# 开发模式
npm run dev

# 构建
npm run build

# 运行测试
npm test

# 监听测试
npm run test:watch
```

### 构建输出

构建后会在 `dist/` 目录生成以下文件：

- `index.es.js` - ES Module 格式
- `index.cjs.js` - CommonJS 格式  
- `index.umd.js` - UMD 格式（用于 CDN）
- `*.d.ts` - TypeScript 类型定义文件

## 📚 文档

- [配置 Schema 文档](./docs/particle-system-config-schema.md)
- [CDN 使用指南](./examples/README.md)
- [API 文档](./docs/api.md)

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📄 许可证

MIT License

## 🔗 相关链接

- [Galacean Engine](https://galacean.antgroup.com/)
- [示例演示](./examples/)
- [配置文档](./docs/)

---

**快速体验：** 打开 `examples/simple-usage.html` 文件即可看到粒子效果演示！