threlte-vfx 0.1.0 → 0.2.1

package/README.md

@@ -1,6 +1,8 @@
-# r3f-vfx
+# ✨ Three VFX ✨
 
-High-performance GPU-accelerated particle system for Three.js WebGPU with React Three Fiber.
+High-performance GPU-accelerated particle system for Three.js WebGPU.
+
+Available for React Three Fiber (R3F), and experimentally for vanilla Three.js, TresJS (Vue), and Threlte (Svelte).
 
 ## Features
 
@@ -12,24 +14,22 @@ High-performance GPU-accelerated particle system for Three.js WebGPU with React
 - 🔗 **Emitter System** - Decoupled emitters that can share particle systems
 - ⚡ **WebGPU Native** - Built specifically for Three.js WebGPU renderer
 
-## Installation
+⚠️ Three VFX only supports WebGPU at the moment ([79% global support](https://caniuse.com/webgpu)). A `fallback` option is available to replace the particle systems by your own fallback objects.
 
-```bash
-npm install r3f-vfx
-```
 
-### Peer Dependencies
+## Quick Start
+
+### React Three Fiber
+
+Add it to your React Three Fiber project with:
 
 ```bash
-npm install three @react-three/fiber react
+npm install r3f-vfx
 ```
 
-## Quick Start
-
 ```tsx
 import { Canvas } from '@react-three/fiber'
-import { VFXParticles, Appearance, EmitterShape } from 'r3f-vfx'
-import * as THREE from 'three/webgpu'
+import { VFXParticles } from 'r3f-vfx'
 
 function App() {
   return (
@@ -40,7 +40,64 @@ function App() {
 }
 ```
 
-That's it, start designing in the debug panel, then copy JSX
+### Vanilla Three.js (Experimental)
+
+Add it to your vanilla Three.js project with:
+
+```bash
+npm install vanilla-vfx
+```
+
+```ts
+import { VFXParticles } from 'vanilla-vfx'
+
+const particles = new VFXParticles(renderer, { debug: true })
+scene.add(particles.renderObject)
+```
+
+### TresJS / Vue (Experimental)
+
+Add it to your TresJS project with:
+
+```bash
+npm install tres-vfx
+```
+
+```vue
+<script setup>
+  import { TresCanvas } from '@tresjs/core'
+  import { VFXParticles } from 'tres-vfx'
+</script>
+
+<template>
+  <TresCanvas>
+    <VFXParticles debug />
+  </TresCanvas>
+</template>
+```
+
+### Threlte / Svelte (Experimental)
+
+Add it to your Threlte project with:
+
+```bash
+npm install threlte-vfx
+```
+
+```svelte
+<script>
+  import { Canvas } from '@threlte/core'
+  import VFXParticles from 'threlte-vfx/VFXParticles.svelte'
+</script>
+
+<Canvas>
+  <VFXParticles debug />
+</Canvas>
+```
+
+## How to use
+
+Use the debug panel to design your effect, then copy the generated code and replace it in your code.
 
 ## API Reference
 

package/dist/VFXEmitter.svelte

@@ -0,0 +1,171 @@
+<script lang="ts">
+import { T, useThrelte, useTask } from '@threlte/core'
+import { onMount } from 'svelte'
+import { Vector3, Quaternion, Group } from 'three/webgpu'
+import {
+  EmitterController,
+  isWebGPUBackend,
+  coreStore,
+  type EmitterControllerOptions,
+} from 'core-vfx'
+
+// Reusable temp objects for transforms (avoid allocations in render loop)
+const worldPos = new Vector3()
+const worldQuat = new Quaternion()
+
+let {
+  name = undefined,
+  particlesRef = undefined,
+  position = [0, 0, 0],
+  emitCount = 10,
+  delay = 0,
+  autoStart = true,
+  loop = true,
+  localDirection = false,
+  direction = undefined,
+  overrides = null,
+  onEmit = undefined,
+  children,
+}: {
+  name?: string
+  particlesRef?: any
+  position?: [number, number, number]
+  emitCount?: number
+  delay?: number
+  autoStart?: boolean
+  loop?: boolean
+  localDirection?: boolean
+  direction?: EmitterControllerOptions['direction']
+  overrides?: Record<string, unknown> | null
+  onEmit?: EmitterControllerOptions['onEmit']
+  children?: import('svelte').Snippet
+} = $props()
+
+const { renderer } = useThrelte()
+
+let groupRef: Group | null = $state(null)
+let isWebGPU = $state(false)
+
+const controller = new EmitterController({
+  emitCount,
+  delay,
+  autoStart,
+  loop,
+  localDirection,
+  direction,
+  overrides,
+  onEmit,
+})
+
+function getParticleSystem() {
+  if (particlesRef) {
+    return particlesRef.value || particlesRef
+  }
+  return name ? coreStore.getState().getParticles(name) : undefined
+}
+
+// Watch option changes
+$effect(() => {
+  const _deps = [
+    emitCount,
+    delay,
+    autoStart,
+    loop,
+    localDirection,
+    direction,
+    overrides,
+    onEmit,
+  ]
+
+  controller.updateOptions({
+    emitCount,
+    delay,
+    autoStart,
+    loop,
+    localDirection,
+    direction,
+    overrides,
+    onEmit,
+  })
+})
+
+function checkWebGPU() {
+  if (renderer && isWebGPUBackend(renderer)) {
+    isWebGPU = true
+    const system = getParticleSystem()
+    if (system) controller.setSystem(system)
+  }
+}
+
+onMount(() => {
+  checkWebGPU()
+})
+
+// Frame loop
+useTask((delta) => {
+  if (!isWebGPU) return
+
+  if (!controller.getSystem()) {
+    const system = getParticleSystem()
+    if (system) controller.setSystem(system)
+  }
+
+  if (!groupRef) return
+
+  groupRef.getWorldPosition(worldPos)
+  groupRef.getWorldQuaternion(worldQuat)
+  controller.update(delta, worldPos, worldQuat)
+})
+
+// Exposed API
+export function emit(emitOverrides: Record<string, unknown> | null = null) {
+  if (!groupRef) return false
+
+  if (!controller.getSystem()) {
+    const system = getParticleSystem()
+    if (system) controller.setSystem(system)
+  }
+
+  if (!controller.getSystem()) {
+    if (name) {
+      console.warn(
+        `VFXEmitter: No particle system found for name "${name}"`
+      )
+    }
+    return false
+  }
+
+  groupRef.getWorldPosition(worldPos)
+  groupRef.getWorldQuaternion(worldQuat)
+  return controller.emitAtPosition(worldPos, worldQuat, emitOverrides)
+}
+
+export function burst(count: number) {
+  if (!groupRef) return false
+
+  if (!controller.getSystem()) {
+    const system = getParticleSystem()
+    if (system) controller.setSystem(system)
+  }
+
+  if (!controller.getSystem()) return false
+
+  groupRef.getWorldPosition(worldPos)
+  groupRef.getWorldQuaternion(worldQuat)
+  return controller.burst(count, worldPos, worldQuat)
+}
+
+export function start() {
+  controller.start()
+}
+
+export function stop() {
+  controller.stop()
+}
+</script>
+
+<T.Group bind:ref={groupRef} position={position}>
+  {#if children}
+    {@render children()}
+  {/if}
+</T.Group>