Repository files navigation

typegpu-confetti is a package for highly-customizable confetti animations in React Native, computed and rendered exclusively on the GPU. Written usingreact-native-wgpu andTypeGPU.

importConfettifrom'typegpu-confetti';functionSomeComponent(){return(<View><ConfettiinitParticleAmount={200}/></View>);}

importConfetti,{typeConfettiRef}from'typegpu-confetti';functionSomeComponent(){constref=useRef<ConfettiRef>(null);return(<View><ConfettiinitParticleAmount={200}maxParticleAmount={1000}ref={ref}/><Buttontitle="add particles"onPress={()=>ref.current?.addParticles(200)}/></View>);}

Ref exposes the following functions, that can update the already created confetti simulation, without restarting it:

typeConfettiRef={pause:()=>void;resume:()=>void;restart:()=>void;addParticles:(amount:number)=>void;};

import{useConfetti}from'typegpu-confetti';functionSomeInnerComponent(){constconfettiRef=useConfetti();return(<View><Buttontitle="run confetti"onPress={()=>confettiRef.current?.addParticles(50)}/></View>);}

To use the hook, the component needs to be descendent from theConfettiProvider component, which accepts the same props asConfetti. It's recommended to wrap a top-level component with the provider, to make sure the confetti covers the whole screen, if that's the desired effect, and make the hook accessible anywhere inside the app.

import{ConfettiProvider}from'typegpu-confetti';functionSomeHighLevelContainerComponent(){return(<ConfettiProvider><App/></ConfettiProvider>);}

typeConfettiPropTypes={colorPalette?:[number,number,number,number][];size?:number;maxDurationTime?:number;initParticleAmount?:number;maxParticleAmount?:number;gravity?:TgpuFn<[d.Vec2f],d.Vec2f>;initParticle?:TgpuFn<[d.I32],undefined>;};

• colorPalette: JavaScript array of[r, g, b, a] colors, from which particles will have their colors randomly assigned.

• size: multiplier allowing customizing the sizes of particles, while keeping their the random variation.size < 1: particles smaller than default,size > 1: bigger

• maxDurationTime: time in seconds around which the animation should end.

  One second before this time the particles gradually lose their opacity until completely transparent.

  It ismaxDurationTime, instead of justdurationTime, because if all of the particles leave the screen, then the animation technically ends earlier, though frames are still being rendered to the canvas until the end ofmaxDurationTime.

  RunningaddParticles function on the ref will reset the time counter to zero each call.

• initParticleAmount: the number of particles that will be drawn whenever the component mounts.

  To not run the animation automatically on mount, but after manually invoking theaddParticles function on some event, set this prop to 0.

• maxParticleAmount: the maximum number of particles that can be part of the simulation at any time.

  If this number is smaller thaninitParticleAmount, then it's ignored andinitParticleAmount is used instead.

  When invokingaddParticles would result in passing this limit, then the oldest simulated particles are replaced with the new ones. They are replaced instantly, without the fading-out animation.

• gravity:tgpu function accepting onevec2f vector (particle position) and returning onevec2f vector (acceleration for the particle).

  To define this function, you can use thegravityFn shell to which you pass the implementation via thedoes method as a WGSL code string or just a JavaScript function (experimental).

• initParticle: tgpu function accepting onei32 argument (particle index), which is to be used for initializing particle age, position, velocity, random number generator seed.

  To access the necessary data inside the function, you should use theparticles andmaxDurationTime tgpu accessors.

  particles value is aTgpuArray withmaxParticleAmount elements of typeParticleData,maxDurationTime value is of typenumber.

  constParticleData=d.struct({position:d.vec2f,velocity:d.vec2f,seed:d.f32,age:d.f32,});