Skip to content

Commit e21f5ad

Browse files
NewKrokNewKrok
authored
Merge pull request #10 from NewKrok/dev
2.3.0
2 parents eeecfcb + 24918c0 commit e21f5ad

11 files changed

Lines changed: 1814 additions & 842 deletions

‎.claude/CLAUDE.md‎

Lines changed: 250 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,250 @@
1+
# Claude Guidelines - Three Particles Project
2+
3+
## Project Overview
4+
5+
**Package:** `@newkrok/three-particles` (v2.2.0)
6+
**Description:** Three.js-based high-performance particle system library designed for creating visually stunning particle effects with ease. Perfect for game developers and 3D applications.
7+
**Author:** Istvan Krisztian Somoracz
8+
**License:** MIT
9+
**Repository:** https://github.com/NewKrok/three-particles
10+
11+
### Key Features
12+
- Easy integration with Three.js
13+
- Visual editor for creating and fine-tuning effects: [THREE Particles Editor](https://github.com/NewKrok/three-particles-editor)
14+
- Highly customizable particle properties (position, velocity, size, color, alpha, rotation, etc.)
15+
- Support for various emitter shapes and parameters
16+
- TypeDoc API documentation: https://newkrok.github.io/three-particles/
17+
18+
### Live Demos
19+
- Editor & Live Demo: https://newkrok.com/three-particles-editor/index.html
20+
- CodePen Examples: Basic, Fire Animation, Projectile Simulation
21+
22+
---
23+
24+
## Project Structure
25+
26+
```
27+
src/
28+
├── js/effects/three-particles/
29+
│ ├── index.ts # Main entry point
30+
│ ├── three-particles.ts # Core particle system
31+
│ ├── three-particles-bezier.ts # Bezier curve utilities
32+
│ ├── three-particles-curves.ts # Curve handling
33+
│ ├── three-particles-enums.ts # Enums (Shape, EmitFrom, etc.)
34+
│ ├── three-particles-modifiers.ts # Modifiers for particle behavior
35+
│ ├── three-particles-utils.ts # Utility functions
36+
│ ├── types.ts # TypeScript type definitions
37+
│ └── shaders/ # GLSL shaders
38+
│ ├── particle-system-vertex-shader.glsl.ts
39+
│ └── particle-system-fragment-shader.glsl.ts
40+
├── types/ # Custom type declarations
41+
└── __tests__/ # Jest test files
42+
```
43+
44+
---
45+
46+
## Core Concepts & Architecture
47+
48+
### Main API Functions
49+
- `createParticleSystem(config: ParticleSystemConfig): ParticleSystem` - Creates a new particle system
50+
- `updateParticleSystems(cycleData: CycleData)` - Updates all active particle systems
51+
52+
### Key Types (from types.ts)
53+
- **ParticleSystemConfig**: Main configuration object for particle systems
54+
- Transform (position, rotation, scale)
55+
- Duration, looping, startDelay
56+
- Start properties (lifetime, speed, size, opacity, rotation, color)
57+
- Emission settings (rateOverTime, rateOverDistance)
58+
- Shape configuration (sphere, cone, circle, rectangle, box)
59+
- Modifiers (velocityOverLifetime, sizeOverLifetime, opacityOverLifetime, rotationOverLifetime, noise)
60+
- Renderer settings (blending, transparency, depth testing)
61+
- Texture & texture sheet animation
62+
- Callbacks (onUpdate, onComplete)
63+
64+
- **LifetimeCurve**: Supports Bezier curves and easing functions for animating values over time
65+
- **Shape Types**: Sphere, Cone, Circle, Rectangle, Box
66+
- **Simulation Spaces**: Local vs World
67+
68+
### Important Enums (three-particles-enums.ts)
69+
- `Shape`: SPHERE, CONE, CIRCLE, RECTANGLE, BOX
70+
- `EmitFrom`: VOLUME, SHELL, EDGE
71+
- `SimulationSpace`: LOCAL, WORLD
72+
- `TimeMode`: LIFETIME, SPEED
73+
- `LifeTimeCurve`: BEZIER, EASING
74+
75+
---
76+
77+
## Development Guidelines
78+
79+
### Code Style
80+
- **Strict TypeScript typing** - Always use explicit types, avoid `any`
81+
- Follow **ESLint** and **Prettier** configurations
82+
- Maintain consistency with existing code structure and patterns
83+
- Use descriptive variable and function names
84+
- Add JSDoc comments for public APIs (see types.ts for examples)
85+
86+
### TypeScript Configuration
87+
- Target: ES2020
88+
- Module: ESNext
89+
- Strict mode enabled
90+
- Declaration files generated
91+
- Path alias: `@newkrok/three-particles` maps to `./src/index.ts`
92+
93+
### Testing
94+
- **Framework**: Jest with TypeScript support (ts-jest, babel-jest)
95+
- **Test files**: Located in `src/__tests__/`
96+
- **Coverage**: Coverage reports generated in `coverage/` directory
97+
- Always write tests for new features
98+
- Test files follow pattern: `*.test.ts`
99+
100+
**Commands:**
101+
```bash
102+
npm test # Run all tests
103+
npm run test:watch # Run tests in watch mode
104+
```
105+
106+
### Build Process
107+
- TypeScript compilation to `dist/`
108+
- Webpack bundling for browser distribution
109+
- Generates both ES modules and minified bundles
110+
- Declaration files (.d.ts) included
111+
112+
**Build command:**
113+
```bash
114+
npm run build # Clean dist/ + TypeScript compile + Webpack bundle
115+
```
116+
117+
**Output:**
118+
- `dist/index.js` - Main ES module
119+
- `dist/index.d.ts` - TypeScript declarations
120+
- `dist/three-particles.min.js` - Minified browser bundle
121+
122+
### Git Workflow
123+
- Main branch: `master`
124+
- Conventional commits enforced via commitlint
125+
- Husky pre-commit hooks configured
126+
- Commit messages should follow conventional format
127+
- Add Co-authored-by for Claude commits:
128+
```
129+
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
130+
```
131+
132+
---
133+
134+
## Dependencies
135+
136+
### Core Dependencies
137+
- **three** (^0.180.0) - Peer dependency, must be installed by consumer
138+
- **@newkrok/three-utils** (^2.0.1) - Utility functions for Three.js
139+
- **easing-functions** (1.3.0) - Easing functions for animations
140+
- **three-noise** (1.1.2) - Noise generation for particle effects
141+
142+
### Dev Tools
143+
- TypeScript 5.7.3
144+
- Jest 30.2.0 (testing)
145+
- ESLint 9.18.0 (linting)
146+
- Prettier 3.4.2 (formatting)
147+
- Webpack 5.97.1 (bundling)
148+
- Husky 9.1.7 (git hooks)
149+
- Commitlint (commit message validation)
150+
- Madge (circular dependency detection)
151+
- TypeDoc (documentation generation)
152+
153+
---
154+
155+
## Common Tasks
156+
157+
### Adding a New Feature
158+
1. Understand the existing code structure
159+
2. Add types to `types.ts` if needed
160+
3. Implement the feature in appropriate file(s)
161+
4. Add/update enums in `three-particles-enums.ts` if needed
162+
5. Write unit tests in `src/__tests__/`
163+
6. Update TypeDoc comments
164+
7. Run tests: `npm test`
165+
8. Build: `npm run build`
166+
9. Lint: `npm run lint`
167+
168+
### Modifying Particle Behavior
169+
- Core logic in: `three-particles.ts`
170+
- Modifiers in: `three-particles-modifiers.ts`
171+
- Curves in: `three-particles-curves.ts`, `three-particles-bezier.ts`
172+
- Shaders in: `shaders/` directory
173+
174+
### Adding New Shape Type
175+
1. Add enum to `Shape` in `three-particles-enums.ts`
176+
2. Add type definition to `types.ts`
177+
3. Implement shape logic in `three-particles.ts`
178+
4. Add tests
179+
180+
---
181+
182+
## Useful Commands
183+
184+
```bash
185+
# Installation
186+
npm install # Install dependencies
187+
188+
# Development
189+
npm run build # Build project (clean + compile + bundle)
190+
npm run prepublishOnly # Runs automatically before publishing
191+
npm test # Run Jest tests
192+
npm run test:watch # Run tests in watch mode
193+
npm run lint # Run ESLint
194+
npm run prepare # Setup Husky git hooks
195+
196+
# Tools
197+
npx madge --circular src # Check for circular dependencies
198+
npx typedoc # Generate documentation
199+
```
200+
201+
---
202+
203+
## Important Notes
204+
205+
### When Making Changes
206+
- **Always check types.ts first** - This file contains comprehensive type definitions and examples
207+
- **Shader changes** - If modifying GLSL shaders, test thoroughly across different browsers/devices
208+
- **Performance** - This is a high-performance library, avoid unnecessary allocations in update loops
209+
- **Three.js compatibility** - Currently targets Three.js ^0.180.0
210+
- **ES Modules** - Project uses ES modules (type: "module" in package.json)
211+
212+
### Known Patterns
213+
- **Curve system**: Uses Bezier curves and easing functions for value interpolation over time
214+
- **Constant or Random**: Many properties support either constant values or `{ min, max }` ranges
215+
- **Lifecycle callbacks**: `onUpdate` and `onComplete` for hooking into particle system lifecycle
216+
- **Gyroscope usage**: For world-space simulation (see `SimulationSpace.WORLD`)
217+
218+
### Testing Considerations
219+
- Tests may need mocking for Three.js objects
220+
- Node.js version compatibility (>=18.0.0)
221+
- Jest configured with Babel for TypeScript support
222+
223+
---
224+
225+
## Additional Resources
226+
227+
- **Documentation**: `.claude/doc/` folder for additional project documentation
228+
- **TypeDoc**: Auto-generated at https://newkrok.github.io/three-particles/
229+
- **Editor**: Visual particle editor for testing configurations
230+
- **Examples**: CodePen examples show real-world usage patterns
231+
232+
---
233+
234+
## Quick Reference: Key Files to Check
235+
236+
When working on specific features, refer to these files:
237+
238+
| Task | File(s) to Check |
239+
|------|------------------|
240+
| Type definitions | `src/js/effects/three-particles/types.ts` |
241+
| Core particle logic | `src/js/effects/three-particles/three-particles.ts` |
242+
| Enums & constants | `src/js/effects/three-particles/three-particles-enums.ts` |
243+
| Curve handling | `src/js/effects/three-particles/three-particles-curves.ts` |
244+
| Bezier utilities | `src/js/effects/three-particles/three-particles-bezier.ts` |
245+
| Modifiers | `src/js/effects/three-particles/three-particles-modifiers.ts` |
246+
| Utilities | `src/js/effects/three-particles/three-particles-utils.ts` |
247+
| Shaders | `src/js/effects/three-particles/shaders/*.glsl.ts` |
248+
| Tests | `src/__tests__/*.test.ts` |
249+
| Build config | `webpack.config.js`, `tsconfig.json` |
250+
| Package info | `package.json` |

‎README.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -66,3 +66,53 @@ updateParticleSystems({now, delta, elapsed});
6666
# Documentation
6767

6868
Automatically generated TypeDoc: [https://newkrok.github.io/three-particles/](https://newkrok.github.io/three-particles/)
69+
70+
## Important Notes
71+
72+
### Color Over Lifetime
73+
74+
The `colorOverLifetime` feature uses a **multiplier-based approach** (similar to Unity's particle system), where each RGB channel curve acts as a multiplier applied to the particle's `startColor`.
75+
76+
**Formula:** `finalColor = startColor * colorOverLifetime`
77+
78+
**⚠️ Important:** To achieve full color transitions, set `startColor` to white `{ r: 1, g: 1, b: 1 }`. If any channel in `startColor` is set to 0, that channel cannot be modified by `colorOverLifetime`.
79+
80+
**Example - Rainbow effect:**
81+
```javascript
82+
{
83+
startColor: {
84+
min: { r: 1, g: 1, b: 1 }, // White - allows full color range
85+
max: { r: 1, g: 1, b: 1 }
86+
},
87+
colorOverLifetime: {
88+
isActive: true,
89+
r: { // Red: full → half → off
90+
type: 'BEZIER',
91+
scale: 1,
92+
bezierPoints: [
93+
{ x: 0, y: 1, percentage: 0 },
94+
{ x: 0.5, y: 0.5, percentage: 0.5 },
95+
{ x: 1, y: 0, percentage: 1 }
96+
]
97+
},
98+
g: { // Green: off → full → off
99+
type: 'BEZIER',
100+
scale: 1,
101+
bezierPoints: [
102+
{ x: 0, y: 0, percentage: 0 },
103+
{ x: 0.5, y: 1, percentage: 0.5 },
104+
{ x: 1, y: 0, percentage: 1 }
105+
]
106+
},
107+
b: { // Blue: off → half → full
108+
type: 'BEZIER',
109+
scale: 1,
110+
bezierPoints: [
111+
{ x: 0, y: 0, percentage: 0 },
112+
{ x: 0.5, y: 0.5, percentage: 0.5 },
113+
{ x: 1, y: 1, percentage: 1 }
114+
]
115+
}
116+
}
117+
}
118+
```

0 commit comments

Comments
 (0)