{"id":31144178,"url":"https://github.com/cazala/party","last_synced_at":"2026-01-20T17:54:33.793Z","repository":{"id":313811811,"uuid":"1028575099","full_name":"cazala/party","owner":"cazala","description":"webgpu particle system and physics engine with realtime playground","archived":false,"fork":false,"pushed_at":"2026-01-12T06:27:59.000Z","size":2395,"stargazers_count":22,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-12T08:12:00.107Z","etag":null,"topics":["engine","particle","physics","playground","simulation","system","webgpu"],"latest_commit_sha":null,"homepage":"https://caza.la/party","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cazala.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-29T18:24:51.000Z","updated_at":"2026-01-12T06:25:54.000Z","dependencies_parsed_at":"2025-09-08T17:25:08.967Z","dependency_job_id":"685f0ca6-702a-4cb6-8352-92f06d46f334","html_url":"https://github.com/cazala/party","commit_stats":null,"previous_names":["cazala/party"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/cazala/party","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cazala%2Fparty","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cazala%2Fparty/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cazala%2Fparty/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cazala%2Fparty/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cazala","download_url":"https://codeload.github.com/cazala/party/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cazala%2Fparty/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28478725,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T11:59:17.896Z","status":"ssl_error","status_checked_at":"2026-01-16T11:55:55.838Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["engine","particle","physics","playground","simulation","system","webgpu"],"created_at":"2025-09-18T14:28:36.773Z","updated_at":"2026-01-16T12:42:29.577Z","avatar_url":"https://github.com/cazala.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Party 🎉 - [caza.la/party](https://caza.la/party)\n\nA high-performance particle physics simulation system with interactive playground, built with TypeScript and WebGPU/CPU dual runtime support.\n\n## Key Features\n\n- **Dual Runtime Architecture**: Auto-selection between WebGPU (GPU compute) and CPU fallback for maximum compatibility\n- **High Performance**: Spatial grid optimization, configurable workgroup sizes, and efficient neighbor queries\n- **Modular Force System**: Environment, boundary, collisions, behavior (flocking), fluid dynamics (SPH), sensors, joints, interaction, and grab modules\n- **Advanced Rendering**: Trails with decay/diffusion, particle instancing, line rendering, and multiple color modes\n- **Playground Sessions**: Save/load/share sessions (module settings, oscillators, and optional particles/joints)\n- **Real-time Oscillators**: Animate any module parameter with configurable frequency and bounds\n- **Interactive Playground**: React-based interface with undo/redo, hotkeys, and live parameter adjustment\n- **Text Spawner**: Spawn particles from text in the core spawner and INIT UI\n\n## Documentation\n\nComprehensive documentation is available in the [`docs/`](./docs) directory:\n\n- **[User Guide](./docs/user-guide.md)**: Complete guide for using the core library as an end user. Covers engine API, runtime selection, module configuration, particle management, oscillators, and all built-in force and render modules with examples.\n\n- **[Module Author Guide](./docs/module-author-guide.md)**: Step-by-step guide for creating custom force and render modules. Covers the module lifecycle, input/output system, CPU and WebGPU implementations, and best practices.\n\n- **[Maintainer Guide](./docs/maintainer-guide.md)**: Internal architecture documentation for contributors. Explains code organization, dual runtime system (CPU/WebGPU), module system, spatial grid, pipelines, oscillators, and how to extend the system.\n\n- **[Playground User Guide](./docs/playground-user-guide.md)**: Guide for using the interactive playground application. Covers the UI, tools, session management, oscillators, hotkeys, and workflow tips.\n\n- **[Playground Maintainer Guide](./docs/playground-maintainer-guide.md)**: Technical documentation for maintaining and extending the playground. Covers architecture, state management (Redux), component structure, hooks, tools system, and development workflows.\n\n## Packages\n\nThis is a monorepo containing:\n\n### [@cazala/party](./packages/core) - Core Engine\n\nThe heart of the system - a TypeScript particle physics engine featuring:\n\n- **Engine**: Unified API with automatic WebGPU/CPU runtime selection\n- **Modular Architecture**: Pluggable force and render modules with lifecycle management\n- **Spatial Optimization**: Efficient neighbor queries via spatial grid partitioning\n- **Advanced Physics**: Gravity, collisions, flocking, fluid dynamics, joints, and more\n- **Oscillators**: Animate any module parameter over time with smooth interpolation\n- **Configuration Export/Import**: Serialize complete simulation states\n\n### [Playground](./packages/playground) - Interactive Application\n\nA React-based web application providing:\n\n- **Visual Interface**: Real-time controls for all simulation parameters\n- **Multiple Tools**: Spawn, grab, joint, pin, remove, and draw modes\n- **Session System**: Save, load, rename, duplicate, and reorder sessions with drag-and-drop\n- **Oscillator UI**: Visual sliders with speed cycling and parameter automation\n- **Hotkeys**: Comprehensive keyboard shortcuts for efficient workflow\n- **Undo/Redo**: Full history system for non-destructive editing\n\n### [`worker`](./packages/worker) - Cloudflare Worker\n\nA route-scoped reverse proxy that serves the playground at `caza.la/party` while proxying to `party.caza.la`.\n\n## Quick Start\n\n### Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/cazala/party.git\ncd party\n\n# Install dependencies\nnpm run setup\n\n# Start the playground in development mode\nnpm run dev\n```\n\nVisit `http://localhost:3000` to access the interactive playground.\n\n\u003e **Note**: This project uses pnpm workspaces internally for optimal monorepo management, but all commands are available through npm scripts. You only need npm installed.\n\n### Using the Core Library\n\n```typescript\nimport {\n  Engine,\n  // Force modules\n  Environment,\n  Boundary,\n  Collisions,\n  Behavior,\n  Fluids,\n  // Render modules\n  Particles,\n  Trails,\n} from \"@cazala/party\";\n\nconst canvas = document.querySelector(\"canvas\")!;\n\nconst forces = [\n  // Environmental physics\n  new Environment({\n    gravityStrength: 600,\n    gravityDirection: \"down\",\n    inertia: 0.05,\n    friction: 0.01,\n  }),\n\n  // Boundary interactions\n  new Boundary({\n    mode: \"bounce\",\n    restitution: 0.9,\n    friction: 0.1,\n  }),\n\n  // Particle collisions\n  new Collisions({ restitution: 0.85 }),\n\n  // Flocking behavior\n  new Behavior({\n    cohesion: 1.5,\n    alignment: 1.2,\n    separation: 12,\n    viewRadius: 100,\n  }),\n\n  // Fluid dynamics\n  new Fluids({\n    influenceRadius: 80,\n    pressureMultiplier: 25,\n    viscosity: 0.8,\n  }),\n];\n\nconst render = [\n  new Trails({ trailDecay: 10, trailDiffuse: 4 }),\n  new Particles({ colorType: 2, hue: 0.55 }), // Hue-based coloring\n];\n\nconst engine = new Engine({\n  canvas,\n  forces,\n  render,\n  runtime: \"auto\", // Auto-selects WebGPU when available, fallback to CPU\n});\n\nawait engine.initialize();\n\n// Add some particles\nfor (let i = 0; i \u003c 100; i++) {\n  engine.addParticle({\n    position: { x: Math.random() * canvas.width, y: Math.random() * canvas.height },\n    velocity: { x: (Math.random() - 0.5) * 4, y: (Math.random() - 0.5) * 4 },\n    mass: 1 + Math.random() * 2,\n    size: 3 + Math.random() * 7,\n    color: { r: 1, g: 1, b: 1, a: 1 },\n  });\n}\n\nengine.play();\n```\n\n## Architecture\n\n### Engine Runtime Selection\n\n```\n┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐\n│     Engine      │    │   WebGPU        │    │      CPU        │\n│                 │    │   Runtime       │    │    Runtime      │\n│ • Auto-select   │◄──►│ • GPU Compute   │    │ • Canvas2D      │\n│ • Unified API   │    │ • Spatial Grid  │    │ • JS Simulation │\n│ • Module System │    │ • WGSL Shaders  │    │ • Fallback      │\n└─────────────────┘    └─────────────────┘    └─────────────────┘\n```\n\n### Module System\n\n```\n┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐\n│  Force Modules  │    │ Render Modules  │    │   Oscillators   │\n│                 │    │                 │    │                 │\n│ • Environment   │    │ • Particles     │    │ • Parameter     │\n│ • Boundary      │    │ • Trails        │    │   Animation     │\n│ • Collisions    │    │ • Lines         │    │ • Time-based    │\n│ • Behavior      │    │                 │    │ • Configurable  │\n│ • Fluids        │    │                 │    │   Frequency     │\n│ • Sensors       │    │                 │    │                 │\n│ • Interaction   │    │                 │    │                 │\n│ • Joints        │    │                 │    │                 │\n│ • Grab          │    │                 │    │                 │\n└─────────────────┘    └─────────────────┘    └─────────────────┘\n```\n\n### Force System Lifecycle\n\nThe force system uses a multi-phase lifecycle for optimal performance:\n\n1. **state**: Global pre-computation (e.g., fluid density calculation)\n2. **apply**: Per-particle force application (acceleration/velocity changes)\n3. **constrain**: Position corrections and constraints (iterative)\n4. **correct**: Post-integration velocity corrections\n\n### Available Modules\n\n#### Force Modules\n\n- **Environment**: Gravity, inertia, friction, and damping with directional/radial options\n- **Boundary**: Boundary interactions (bounce, kill, warp) with repel forces and friction\n- **Collisions**: Particle-particle collision detection and elastic response\n- **Behavior**: Flocking behaviors (cohesion, alignment, separation, wander, chase/avoid)\n- **Fluids**: Smoothed Particle Hydrodynamics (SPH) with near-pressure optimization\n- **Sensors**: Trail-following and color-based steering with configurable behaviors\n- **Interaction**: User-controlled attraction/repulsion with falloff\n- **Joints**: Distance constraints between particles with momentum preservation\n- **Grab**: Efficient single-particle mouse/touch dragging\n\n#### Render Modules\n\n- **Particles**: Instanced particle rendering with multiple color modes and pinned particle visualization\n- **Trails**: Decay and diffusion effects with performance-optimized compute passes\n- **Lines**: Line rendering between particle pairs with configurable styling\n\n## Development\n\n### Setup\n\n```bash\n# Install dependencies for all packages\nnpm run setup\n\n# Build the core library\nnpm run build:core\n\n# Start development server for playground\nnpm run dev\n\n# Build everything for production\nnpm run build\n\n# Type check all packages\nnpm run type-check\n\n# Run tests\nnpm test\n```\n\n### Project Structure\n\n```\nparty/\n├── packages/\n│   ├── core/                      # Core engine library\n│   │   ├── src/\n│   │   │   ├── engine.ts          # Main engine facade\n│   │   │   ├── index.ts           # Public API exports\n│   │   │   ├── interfaces.ts      # Common interfaces\n│   │   │   ├── modules/           # Force and render modules\n│   │   │   │   ├── forces/\n│   │   │   │   └── render/\n│   │   │   ├── oscillators.ts\n│   │   │   ├── particle.ts\n│   │   │   ├── runtimes/          # WebGPU and CPU implementations\n│   │   │   │   ├── cpu/\n│   │   │   │   └── webgpu/\n│   │   │   ├── spawner.ts\n│   │   │   ├── vector.ts\n│   │   │   └── view.ts\n│   │   ├── package.json\n│   │   ├── README.md\n│   │   ├── rollup.config.js\n│   │   └── tsconfig.json\n│   └── playground/                # React playground application\n│       ├── src/\n│       │   ├── components/\n│       │   ├── constants/\n│       │   ├── contexts/\n│       │   ├── history/\n│       │   ├── hooks/\n│       │   ├── slices/\n│       │   ├── styles/\n│       │   ├── types/\n│       │   └── utils/\n│       ├── index.html\n│       ├── package.json\n│       ├── README.md\n│       ├── tsconfig.json\n│       └── vite.config.js\n├── docs/                          # Documentation\n│   ├── maintainer-guide.md\n│   ├── module-author-guide.md\n│   ├── playground-maintainer-guide.md\n│   ├── playground-user-guide.md\n│   └── user-guide.md\n├── LICENSE\n├── package.json                   # Root workspace configuration\n├── package-lock.json\n├── pnpm-lock.yaml\n├── pnpm-workspace.yaml\n├── tsconfig.json\n└── README.md\n```\n\n## Performance\n\n### WebGPU Runtime\n\n- **GPU Compute**: Parallel particle processing with configurable workgroup sizes\n- **Spatial Grid**: GPU-accelerated neighbor queries\n- **Memory Efficiency**: Optimized buffer layouts and minimal CPU-GPU transfers\n- **Scalability**: Handles thousands of particles at 60+ FPS\n\n### CPU Runtime\n\n- **Fallback Compatibility**: Works on all devices without WebGPU support\n- **Spatial Optimization**: Efficient neighbor queries via spatial partitioning\n- **Canvas2D Rendering**: Hardware-accelerated 2D graphics\n- **Memory Management**: Minimal allocations in tight loops\n\n### Configuration\n\n- **cellSize**: Spatial grid resolution (8-64 typical)\n- **maxNeighbors**: Neighbor query limit (64-256 typical)\n- **constrainIterations**: Constraint solver iterations (CPU: ~5, WebGPU: ~50)\n- **workgroupSize**: WebGPU compute workgroup size (32-256)\n- **maxParticles**: Limit the number of particles processed in simulation and rendering. When set to a number, only particles with index \u003c `maxParticles` are processed. Set to `null` (default) to process all particles. Useful for performance tuning. \n\n## Browser Support\n\n- **WebGPU**: Chrome 113+, Edge 113+, Safari 18+, Firefox (experimental)\n- **Mobile**: iOS 18+ (Safari), Android (Chrome 113+)\n- **CPU Fallback**: All modern browsers with Canvas2D support\n- **Auto-Detection**: Seamless fallback when WebGPU is unavailable\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Contributing\n\nWe welcome contributions! Please see our [maintainer guide](docs/maintainer-guide.md) for architecture details and [module author guide](docs/module-author-guide.md) for creating custom modules.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcazala%2Fparty","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcazala%2Fparty","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcazala%2Fparty/lists"}