Metadata-Version: 2.4
Name: particlefx
Version: 1.0.0
Summary: 纯 Python + NumPy 粒子系统库 — 多渲染器（pygame/PIL/ModernGL）+ 效果工厂 + Taichi 流体后端 + GPU 模拟
Author: 全哥
License: MIT License
        
        Copyright (c) 2026 siwpan
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://gitee.com/siwpan/particlefx
Project-URL: Repository, https://gitee.com/siwpan/particlefx
Project-URL: Issues, https://gitee.com/siwpan/particlefx/issues
Project-URL: Changelog, https://gitee.com/siwpan/particlefx/blob/master/CHANGELOG.md
Keywords: particle,particle-system,effects,vfx,pygame,numpy,rendering,gpu
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Games/Entertainment
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Provides-Extra: pygame
Requires-Dist: pygame-ce>=2.4; extra == "pygame"
Provides-Extra: pil
Requires-Dist: Pillow>=10.0; extra == "pil"
Provides-Extra: numba
Requires-Dist: numba>=0.60; extra == "numba"
Provides-Extra: taichi
Requires-Dist: taichi>=1.7; extra == "taichi"
Provides-Extra: gpu
Requires-Dist: moderngl>=5.10; extra == "gpu"
Requires-Dist: pygame-ce>=2.4; extra == "gpu"
Provides-Extra: schema
Requires-Dist: jsonschema>=4.0; extra == "schema"
Provides-Extra: all
Requires-Dist: pygame-ce>=2.4; extra == "all"
Requires-Dist: Pillow>=10.0; extra == "all"
Requires-Dist: numba>=0.60; extra == "all"
Requires-Dist: taichi>=1.7; extra == "all"
Requires-Dist: moderngl>=5.10; extra == "all"
Requires-Dist: jsonschema>=4.0; extra == "all"
Dynamic: license-file

# particlefx — 独立粒子系统

[![PyPI version](https://img.shields.io/pypi/v/particlefx)](https://pypi.org/project/particlefx/)
[![PyPI Python versions](https://img.shields.io/pypi/pyversions/particlefx)](https://pypi.org/project/particlefx/)
[![PyPI license](https://img.shields.io/pypi/l/particlefx)](https://pypi.org/project/particlefx/)

> 仓库：<https://gitee.com/siwpan/particlefx> ｜ 许可：MIT（见 [LICENSE](LICENSE)）
> 注：文中 <PATH> 为路径占位符，请替换为你本机实际的目录 / 可执行文件路径。

## 安装

```bash
pip install particlefx              # 仅核心（NumPy）
pip install "particlefx[pygame]"    # + pygame 渲染器
pip install "particlefx[all]"       # + 全部可选依赖
```

**发行名 vs 导入名**：PyPI 上的发行名是 `particlefx`，Python 导入名同为 `particlefx`（无连字符差异）。

```python
from particlefx import ParticleSystem, Emitter, ForceField
from particlefx.renderers import PygameRenderer
```

## 设计理念

1. **独立性**：不依赖任何项目，纯 Python + NumPy 实现
2. **可复用性**：pip 安装即用，也可复制 `particlefx/` 目录到目标项目微调
3. **简洁性**：只提供核心功能，不添加冗余特性

## 项目结构

```
particlefx/
├── particlefx/           # Python 包（命名空间根）
│   ├── core/
│   │   ├── particle.py         # 核心粒子类（Particle/ParticleSystem/Emitter/ForceField/
│   │   │                       #   ParticleAttractor/ParticlePool/碰撞/光照/LOD/事件）
│   │   ├── particle_numpy.py   # NumPy 向量化粒子系统（SoA）
│   │   ├── particle_numba.py   # v5.0：Numba JIT 更新内核（可选依赖）
│   │   ├── particle_taichi.py  # v5.0：Taichi WCSPH 流体后端（可选依赖）
│   │   └── spatial_hash.py     # v5.0：均匀网格空间哈希
│   ├── renderers/
│   │   ├── pygame_renderer.py      # Pygame 渲染器（additive/screen 混合 + Bloom）
│   │   ├── pil_renderer.py         # PIL 渲染器（离屏/GIF/视频帧/分层渲染）
│   │   ├── postfx.py               # v5.0：可编程后处理链（Bloom/色调映射/晕影/色差/颗粒）
│   │   ├── fluid_renderer.py       # CPU 折中版 SSFR 流体渲染
│   │   ├── particle_renderer_moderngl.py  # GPU 实例化粒子（含软粒子深度淡出）
│   │   ├── fluid_renderer_modernGL.py     # GPU 统一渲染器（4 种路径 + 软粒子）
│   │   └── particle_sim_gpu.py     # v5.0：Compute Shader 全 GPU 模拟
│   ├── components/
│   │   ├── effects.py / effects_factory.py  # 效果工厂（代码 + JSON 声明式）
│   │   ├── effects_config.json              # 30+ 预设效果配方
│   │   ├── effects_config.schema.json       # v5.0：配方 JSON Schema
│   │   └── palettes.json                    # 主题调色板库
│   └── systems/
│       ├── fireworks_system.py   # 烟花（14 样式 × 10 调色板）
│       ├── weather_system.py     # 天气（6 种）
│       └── combat_effects.py     # 战斗特效（攻击/技能/飘字/死亡）
├── examples/                 # 交互 Demo + 视频生成器 + pygbag Web 入口
├── docs/                     # api.md / effects.md / enhancements.md
└── tests/                    # pytest 全套测试
```

## 核心类

### Particle（粒子）

单个粒子的数据结构：

```python
@dataclass
class Particle:
    x: float  # x 位置
    y: float  # y 位置
    vx: float  # x 速度
    vy: float  # y 速度
    life: float  # 剩余生命值 (0-1)
    max_life: float  # 最大生命值
    size: float  # 大小
    color: Tuple[int, int, int]  # RGB 颜色
    alpha: float = 1.0  # 透明度 (0-1)
```

### ParticleSystem（粒子系统管理器）

管理所有粒子、发射器和力场：

```python
ps = ParticleSystem(max_particles=1000)
ps.add_emitter(emitter)
ps.add_force_field(gravity)
ps.update(dt, audio_data)
ps.render(renderer)
```

### Emitter（发射器）

发射粒子：

```python
emitter = Emitter(
    x=width//2, y=height,
    rate=50.0,  # 发射速率（粒子/秒）
    spread=3.14,  # 扩散角度（弧度）
    speed=200.0,  # 发射速度
    life=2.0,  # 粒子生命值
    size=3.0,  # 粒子大小
    color=(255, 200, 50)  # 粒子颜色
)
```

### ForceField（力场）

模拟重力、风力、吸引力等：

```python
# 重力（向下）
gravity = ForceField(field_type='gravity', strength=100.0)

# 风力（向右）
wind = ForceField(field_type='wind', strength=50.0)

# 吸引力（指向某点）
attractor = ForceField(field_type='attraction', x=400, y=300, strength=200.0)
```

## 使用方法

### 1. pip 安装（推荐）

```bash
pip install particlefx
```

装完直接用，无需复制目录：

```python
from particlefx import ParticleSystem, Emitter, ForceField
from particlefx.renderers import PygameRenderer
```

### 2. 复制到目标项目

若需深度微调，也可复制包目录到目标项目：

```bash
# 复制到其他目标项目（按需微调）
cp -r particlefx/ <你的项目目录>/particlefx/
```

### 3. 微调适配

根据目标项目的架构进行微调：

- **pywallpaper**：已集成 `particle.py` 原语，可以直接使用
- **draw**：需要创建新的渲染器（`draw/renderers/particle_renderer.py`）

### 4. 使用示例

```python
from particlefx import ParticleSystem, Emitter, ForceField
from particlefx.renderers import PygameRenderer

# 创建粒子系统
ps = ParticleSystem(max_particles=1000)

# 创建发射器
emitter = Emitter(x=400, y=300, rate=50.0, ...)
ps.add_emitter(emitter)

# 创建力场
gravity = ForceField(field_type='gravity', strength=100.0)
ps.add_force_field(gravity)

# 更新和渲染
ps.update(dt)
renderer = PygameRenderer(screen)
ps.render(renderer)
```

## 示例效果

### 烟花（Fireworks）

```bash
cd examples/
python fireworks.py
```

### 其他效果（待创建）

- 雨水（Rain）
- 雪花（Snow）
- 爆炸（Explosion）
- 魔法效果（Magic）

## 音频驱动

粒子系统支持音频驱动：

```python
# 更新时传入音频数据
audio_data = {
    'rms': 0.5,  # 音频 RMS 能量
    'beat': True,  # 是否检测到节拍
    'band_energy': [0.1, 0.2, 0.3]  # 频段能量
}
ps.update(dt, audio_data)
```

在 `Emitter.emit()` 中，可以根据 `audio_data` 调整发射速率：

```python
if audio_data:
    energy = audio_data.get('rms', 1.0)
    current_rate *= (1.0 + energy * 2.0)  # 根据音频能量调整发射速率
```

## 性能优化

### NumPy 向量化

将粒子数据存储在 NumPy 数组中，使用向量化计算：

```python
# TODO: 创建 ParticleSystemNumpy 类
class ParticleSystemNumpy:
    def __init__(self):
        self.positions = np.zeros((max_particles, 2))  # x, y
        self.velocities = np.zeros((max_particles, 2))  # vx, vy
        self.lives = np.zeros(max_particles)  # life
        # ...
```

### Numba JIT 编译

使用 Numba 编译粒子更新循环：

```python
from numba import jit

@jit(nopython=True)
def update_particles(positions, velocities, lives, dt):
    # ...
```

## 依赖

- **必需**：NumPy
- **可选**（对应 pip extras）：
  - `pygame-ce` — pygame 渲染器（`particlefx/renderers/pygame_renderer.py`）
  - `Pillow` — PIL 渲染器（`particlefx/renderers/pil_renderer.py`）
  - `numba` — JIT 更新内核
  - `taichi` — WCSPH 流体后端
  - `moderngl` — GPU 渲染器 / Compute Shader 模拟
  - `jsonschema` — 效果配方 Schema 校验

## v5.0 增强功能（2026）

按"成本从低到高"落地的 9 项增强，全部保持**可选依赖零开销 + 向后兼容**：

| # | 增强 | 入口 | 可选依赖 |
|---|------|------|---------|
| ① | 对象池 + 空间哈希 | `ParticleSystem(use_pool=True, use_spatial_hash=True)` | 无 |
| ② | Numba JIT 更新内核 | `particlefx.core.particle_numba.NumbaParticleSystem` | numba |
| ③ | 软粒子深度淡出 | `GPUParticleRenderer(enable_depth_fade=True)` | moderngl |
| ④ | 浏览器 Web 导出 | `pygbag --app_name web_main examples` | pygbag |
| ⑤ | 粒子吸引子 + 粒子光源 | `ParticleAttractor` / `enable_pairwise_force` / `enable_particle_lights` | 无 |
| ⑥ | 可编程后处理链 | `particlefx.renderers.postfx.PostFXChain` | 无 |
| ⑦ | JSON Schema 校验 | `EffectsFactory(validate=True)` | jsonschema(可选) |
| ⑧ | Taichi SPH 流体 | `particlefx.core.particle_taichi.TaichiSPHSystem` | taichi |
| ⑨ | Compute 全 GPU 模拟 | `particlefx.renderers.particle_sim_gpu.GPUParticleSimulator` | moderngl |

详见 [docs/enhancements.md](docs/enhancements.md)。

## 许可证

MIT License（可自由复制、修改、使用）

## 作者

- 全哥（独立开发者）
- AI 助手（WorkBuddy）

## 更新日志

详见 [CHANGELOG.md](CHANGELOG.md)。

- **2026-10-21**：v1.0.0 发布至 PyPI（发行名 `particlefx`），源码重组为 `particlefx/` 命名空间包
- **2026-06-23**：初始版本，创建核心类和示例效果
