### Run Test Web App

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/_autodocs/integration-guide.md

Instructions to navigate to the test web app directory, install dependencies, and start the development server.

```bash
cd apps/test-web-app
npm install
npm run dev
```

--------------------------------

### Install TypeGPU Confetti and React Native WGPU

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/_autodocs/integration-guide.md

Install the necessary packages for React Web integration.

```bash
npm install react-native-wgpu typegpu-confetti
```

--------------------------------

### Install typegpu-confetti

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/README.md

Install the main typegpu-confetti package after setting up react-native-wgpu.

```sh
npm install typegpu-confetti
```

--------------------------------

### Custom Initialization Function Example

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/_autodocs/api-reference/exported-accessors-and-slots.md

An example of a custom particle initialization function using random values and accessing global particle data. Ensure 'gpu' is used for GPU execution context.

```typescript
import { d } from 'typegpu';
import { particlesAccess, timeAccess, maxDurationTimeSlot } from 'typegpu-confetti';
import { randf } from '@typegpu/noise';

const customInit: InitParticleFn = (i) => {
  'use gpu';
  randf.seed2(d.vec2f(d.f32(i), d.f32(timeAccess.$ % 1111)));
  
  const particle = particlesAccess.$[i];
  particle.position = d.vec2f(randf.sample() * 2 - 1, 1);
  particle.velocity = d.vec2f(randf.sample() * 2 - 1, -randf.sample());
  particle.timeLeft = maxDurationTimeSlot.$ * 1000;
  particle.seed = randf.sample();
};
```

--------------------------------

### Install react-native-wgpu

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/README.md

Install the react-native-wgpu package to use typegpu-confetti in React Native. Ensure you run `expo prebuild` as Expo Go is not supported.

```sh
npm install react-native-wgpu
```

--------------------------------

### Install unplugin-typegpu Babel Plugin

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/README.md

Install the unplugin-typegpu Babel plugin to pass JavaScript functions marked with the "use gpu" directive to the Confetti component.

```sh
npm install unplugin-typegpu
```

--------------------------------

### Global Confetti Setup (React Web)

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/_autodocs/api-reference/confetti-provider.md

Recommended pattern: Wrap your entire React application with ConfettiProvider for global access to confetti effects.

```typescript
import { ConfettiProvider } from 'typegpu-confetti/react';

function App() {
  return (
    <ConfettiProvider>
      <YourEntireApp />
    </ConfettiProvider>
  );
}

```

--------------------------------

### Custom Gravity Function Example

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/_autodocs/api-reference/exported-accessors-and-slots.md

An example of a custom gravity function that pulls particles towards the screen center. Ensure 'gpu' is used for GPU execution context.

```typescript
import { d } from 'typegpu';
import { aspectRatioAccess, particlesAccess } from 'typegpu-confetti';

const customGravity: GravityFn = (pos) => {
  'use gpu';
  // Gravity that pulls toward screen center
  const center = d.vec2f(0, 0);
  const direction = center.minus(pos).normalize();
  const strength = 0.2;
  return direction.mul(strength);
};
```

--------------------------------

### Particle Data Initialization Example

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/_autodocs/types.md

Initializes particle state including position, velocity, seed, and timeLeft. Requires 'use gpu', 'typegpu', and '@typegpu/noise' imports, and access to global GPU data.

```typescript
const particle = particlesAccess.$[index];
particle.position = d.vec2f(x, y);        // vec2f - normalized coordinates
particle.velocity = d.vec2f(vx, vy);      // vec2f - per-second movement
particle.seed = randf.sample();            // f32 - random value for oscillation
particle.timeLeft = maxDurationTime.$ * 1000; // f32 - milliseconds remaining
```

--------------------------------

### Custom Radial Gravity Example

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/_autodocs/configuration.md

This example demonstrates how to implement custom gravity behavior using a GPU function. The `gravity` prop accepts a function that calculates acceleration based on particle position, here simulating a pull towards the center.

```typescript
import { Confetti, gravityFn } from 'typegpu-confetti/react';
import { d } from 'typegpu';

function RadialGravity() {
  const radialGravity = (pos: d.v2f) => {
    'use gpu';
    // Pull particles toward center
    const center = d.vec2f(0, 0);
    const direction = center.minus(pos).normalize();
    return direction.mul(0.1);
  };

  return <Confetti gravity={radialGravity} />; 
}
```

--------------------------------

### Large, Long-Duration Confetti Example

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/_autodocs/configuration.md

This example shows how to configure larger confetti particles with a longer animation duration and increased particle counts. It utilizes the `size`, `maxDurationTime`, `initParticleAmount`, and `maxParticleAmount` props.

```typescript
import { Confetti } from 'typegpu-confetti/react';

function LongConfetti() {
  return (
    <Confetti
      size={2}
      maxDurationTime={5}
      initParticleAmount={500}
      maxParticleAmount={2000}
    />
  );
}
```

--------------------------------

### Custom InitParticle Function with 'use gpu' Directive

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/_autodocs/api-reference/confetti-component.md

An example of a custom initParticle function requiring the 'use gpu' directive for proper transpilation.

```typescript
const customInit: InitParticleFn = (i) => {
  'use gpu';
  const particle = particlesAccess.$[i];
  particle.position = d.vec2f(randf.sample() * 2 - 1, randf.sample());
  particle.velocity = d.vec2f(randf.sample() - 0.5, -randf.sample());
};
```

--------------------------------

### Custom Color Palette Example

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/_autodocs/configuration.md

This example demonstrates how to set a custom array of RGBA colors for the confetti particles. The `colorPalette` prop accepts an array of `[r, g, b, a]` arrays.

```typescript
import { Confetti } from 'typegpu-confetti/react';

function CustomColors() {
  const colors: [number, number, number, number][] = [
    [255, 0, 0, 1],      // Red
    [0, 255, 0, 1],      // Green
    [0, 0, 255, 1],      // Blue
    [255, 255, 0, 1],    // Yellow
  ];

  return <Confetti colorPalette={colors} />; 
}
```

--------------------------------

### ConfettiProvider Setup (React Web)

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/_autodocs/api-reference/confetti-provider.md

Wrap your application with ConfettiProvider to enable confetti animations. Use the useConfetti hook within child components to access confetti functionality.

```typescript
import React from 'react';
import { ConfettiProvider, useConfetti } from 'typegpu-confetti/react';

function App() {
  return (
    <ConfettiProvider>
      <YourApp />
    </ConfettiProvider>
  );
}

function YourApp() {
  const confettiRef = useConfetti();

  return (
    <button onClick={() => confettiRef?.current?.addParticles(100)}>
      Celebrate!
    </button>
  );
}
```

--------------------------------

### Initialize Particle Data in GPU Function

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/_autodocs/api-reference/exported-accessors-and-slots.md

Example of initializing a particle's properties within a GPU function using the `particlesAccess` accessor. This sets initial position, velocity, seed, and timeLeft for a given particle index.

```typescript
const initParticle: InitParticleFn = (i) => {
  'use gpu';
  const particle = particlesAccess.$[i];
  particle.position = d.vec2f(0, 0);
  particle.velocity = d.vec2f(0, -1);
  particle.seed = 0.5;
  particle.timeLeft = 2000;
};
```

--------------------------------

### Confetti Provider Setup

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/README.md

Wrap a top-level component with `ConfettiProvider` to make the `useConfetti` hook accessible throughout the application and ensure confetti covers the entire screen.

```tsx
import { ConfettiProvider } from 'typegpu-confetti/react-native';

function SomeHighLevelContainerComponent() {
  return (
    <ConfettiProvider>
      <App />
    </ConfettiProvider>
  );
}
```

--------------------------------

### ConfettiProvider Setup (React Native)

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/_autodocs/api-reference/confetti-provider.md

Wrap your application with ConfettiProvider to enable confetti effects. Use the useConfetti hook in descendant components to control confetti.

```typescript
import React from 'react';
import { View } from 'react-native';
import { ConfettiProvider, useConfetti } from 'typegpu-confetti/react-native';

function App() {
  return (
    <ConfettiProvider>
      <YourApp />
    </ConfettiProvider>
  );
}

function YourApp() {
  const confettiRef = useConfetti();

  return (
    <Button
      title="Celebrate!"
      onPress={() => confettiRef?.current?.addParticles(100)}
    />
  );
}

```

--------------------------------

### Custom Gravity Function with 'use gpu' Directive

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/_autodocs/api-reference/confetti-component.md

An example of a custom gravity function that must include the 'use gpu' directive for transpilation by unplugin-typegpu.

```typescript
const customGravity: GravityFn = (pos) => {
  'use gpu';
  return d.vec2f(0, -0.3);
};
```

--------------------------------

### TypeGPU Confetti Package Exports Field

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/_autodocs/integration-guide.md

Example of the 'exports' field in package.json for conditional module resolution in TypeGPU Confetti.

```json
{
  "exports": {
    ".": "./src/index.ts",
    "./react": "./src/react/index.ts",
    "./react-native": "./src/react-native/index.ts"
  }
}
```

--------------------------------

### Access and Modify Particle Data in WGSL

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/_autodocs/api-reference/gpu-functions-and-slots.md

Example of accessing and modifying individual particle data within a WGSL shader using the particles accessor.

```wgsl
let particle = particles[i];
particle.position = vec2f(0.5, 0.5);
```

--------------------------------

### Confetti Component Usage (React Web)

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/_autodocs/api-reference/confetti-component.md

Example of using the Confetti component in a React Web application. It demonstrates how to control particle emission using a ref and a button click.

```typescript
import React, { useRef } from 'react';
import { Confetti, type ConfettiRef } from 'typegpu-confetti/react';

function MyComponent() {
  const confettiRef = useRef<ConfettiRef>(null);

  const handleCelebrate = () => {
    confettiRef.current?.addParticles(100);
  };

  return (
    <div>
      <Confetti ref={confettiRef} initParticleAmount={0} />
      <button onClick={handleCelebrate}>Celebrate!</button>
    </div>
  );
}
```

--------------------------------

### Find Empty Particle Slot in GPU Function

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/_autodocs/api-reference/exported-accessors-and-slots.md

Example of iterating through particles to find an available slot for a new particle. It checks `timeLeft` to identify inactive particles that can be reused.

```typescript
const addParticle = () => {
  'use gpu';
  for (let i = 0; i < maxParticleAmountAccess.$; i++) {
    if (particlesAccess.$[i].timeLeft < 0.1) {
      // Found empty slot, initialize it
      return;
    }
  }
};
```

--------------------------------

### Implement Gravity Using Delta Time in GPU Function

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/_autodocs/api-reference/exported-accessors-and-slots.md

Example of using delta time within a GPU function to influence gravity. The comment indicates that gravity is scaled by delta time in the main compute shader.

```typescript
const gravity: GravityFn = (pos) => {
  'use gpu';
  // Gravity is scaled by delta time in mainCompute
  return d.vec2f(0, -0.3);
};
```

--------------------------------

### Custom GPU Gravity Function (Radial Pull)

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/_autodocs/README.md

Example of a custom GPU function for gravity that pulls particles towards the center of the screen. It requires the 'use gpu' directive and uses 'typegpu' vector types.

```typescript
import { Confetti } from 'typegpu-confetti/react';
import { d } from 'typegpu';

function MyConfetti() {
  const radialGravity = (pos: d.v2f) => {
    'use gpu';
    const center = d.vec2f(0, 0);
    const direction = center.minus(pos).normalize();
    return direction.mul(0.2);
  };

  return <Confetti gravity={radialGravity} />; 
}
```

--------------------------------

### TypeGPU Confetti Build Script

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/_autodocs/integration-guide.md

The command to run the build process for TypeGPU Confetti, which executes a prepack script.

```bash
npm run build  # Runs `node prepack.mjs`
```

--------------------------------

### Documentation Structure Overview

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/_autodocs/MANIFEST.md

This snippet illustrates the directory structure of the typegpu-confetti documentation, showing the location of key files and subdirectories.

```text
/workspace/home/output/
├── README.md                          # Start here: Overview & architecture
├── API-INDEX.md                       # Quick lookup: All exports & types
├── MANIFEST.md                        # This file
├── configuration.md                   # Props, defaults, examples
├── integration-guide.md                # Setup for React & React Native
├── types.md                           # Type definitions & usage
├── api-reference/
│   ├── confetti-component.md          # Confetti component API
│   ├── confetti-provider.md           # Provider & useConfetti API
│   ├── gpu-functions-and-slots.md     # GPU shaders & primitives
│   └── exported-accessors-and-slots.md # Exported GPU state
└── MANIFEST.md                        # This index

```

--------------------------------

### Configure Unplugin TypeGPU with Babel

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/_autodocs/integration-guide.md

Add the unplugin-typegpu Babel plugin to your Babel configuration file.

```javascript
module.exports = {
  plugins: [
    ['unplugin-typegpu/babel'],
  ],
};
```

--------------------------------

### Import All Types

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/_autodocs/API-INDEX.md

Import all available types from the 'typegpu-confetti' package.

```typescript
import type { ConfettiProps, ConfettiRef, GravityFn, InitParticleFn } from 'typegpu-confetti';
```

--------------------------------

### Project File Structure

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/_autodocs/integration-guide.md

Overview of the TypeGPU Confetti project's directory layout, highlighting key files and their purposes.

```tree
src/
├── index.ts                           # Main entry point (types & slots)
├── core/
│   ├── create-confetti-component.tsx  # Core component factory
│   ├── types.ts                       # ConfettiProps, ConfettiRef
│   ├── schemas.ts                     # GPU shaders, slots, accessors
│   ├── defaults.ts                    # Default configuration
│   └── utils.ts                       # Helper functions
├── react/
│   ├── index.ts                       # React entry point
│   ├── Confetti.tsx                   # React Web component wrapper
│   └── ConfettiProvider.tsx           # React context provider
└── react-native/
    ├── index.ts                       # React Native entry point
    ├── Confetti.tsx                   # React Native component wrapper
    └── ConfettiProvider.tsx           # React Native context provider
```

--------------------------------

### Use useConfetti Hook

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/README.md

Use the `useConfetti` hook to get a reference to the Confetti component and control animations. The component must be a descendant of `ConfettiProvider`.

```tsx
import { useConfetti } from 'typegpu-confetti/react-native';

function SomeInnerComponent() {
  const confettiRef = useConfetti();

  return (
    <View>
      <Button title="run confetti" onPress={() => confettiRef?.current?.addParticles(50)} />
    </View>
  );
}
```

--------------------------------

### Spiral Particle Initialization

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/_autodocs/types.md

Initializes particles in a spiral pattern with velocities based on their angle. Requires 'use gpu', 'typegpu', and access to global particle count.

```typescript
const spiralInit: InitParticleFn = (i) => {
  'use gpu';
  const particle = particlesAccess.$[i];
  const angle = d.f32(i) / maxParticleAmount.$ * 6.28;
  const radius = 0.5;
  particle.position = d.vec2f(cos(angle) * radius, sin(angle) * radius);
  particle.velocity = d.vec2f(sin(angle) * 0.5, cos(angle) * 0.5);
};
```

--------------------------------

### React Web Entry Point Exports

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/_autodocs/integration-guide.md

Exports for the React Web integration of typegpu-confetti.

```typescript
export { default as Confetti } from './Confetti.tsx';
export { ConfettiProvider, useConfetti } from './ConfettiProvider.tsx';
```

--------------------------------

### Default Particle Initialization

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/_autodocs/types.md

Initializes particles with random positions and velocities for a default spread effect. Requires 'use gpu', 'typegpu', and '@typegpu/noise' imports.

```typescript
const defaultInit: InitParticleFn = (i) => {
  'use gpu';
  const particle = particlesAccess.$[i];
  particle.position = d.vec2f(randf.sample() * 2 - 1, randf.sample() / 1.5 + 1);
  particle.velocity = d.vec2f(randf.sample() * 2 - 1, -(randf.sample() / 25 + 0.01) * 50);
};
```

--------------------------------

### Configure Unplugin TypeGPU with Vite

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/_autodocs/integration-guide.md

Add the unplugin-typegpu Vite plugin to your vite.config.js file.

```javascript
import typeGPU from 'unplugin-typegpu/vite';

export default {
  plugins: [typeGPU()],
};
```

--------------------------------

### Set Particle Lifetime Using Max Duration in GPU Function

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/_autodocs/api-reference/exported-accessors-and-slots.md

Example of setting a particle's `timeLeft` property to the maximum animation duration. This ensures particles persist for the intended duration of the effect.

```typescript
const initParticle: InitParticleFn = (i) => {
  'use gpu';
  const particle = particlesAccess.$[i];
  particle.timeLeft = maxDurationTimeSlot.$ * 1000;  // Set lifetime equal to max duration
};
```

--------------------------------

### Configure Unplugin TypeGPU with Webpack

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/_autodocs/integration-guide.md

Configure Webpack to use unplugin-typegpu loader for processing files.

```javascript
module.exports = {
  module: {
    rules: [
      {
        test: /\.[jt]sx?$/,
        loader: 'unplugin-typegpu/webpack',
      },
    ],
  },
};
```

--------------------------------

### Import React Web Components

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/_autodocs/API-INDEX.md

Import React components and hooks for web applications.

```typescript
import { Confetti, ConfettiProvider, useConfetti } from 'typegpu-confetti/react';
```

--------------------------------

### Custom GPU Initialization Function (Circular Burst)

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/_autodocs/README.md

Demonstrates a custom GPU function for particle initialization that creates a circular burst effect. It calculates particle positions and velocities based on an angle derived from the particle index.

```typescript
import { Confetti } from 'typegpu-confetti/react';
import { d } from 'typegpu';
import { particlesAccess } from 'typegpu-confetti';

function BurstConfetti() {
  const burstInit = (i: number) => {
    'use gpu';
    const angle = (d.f32(i) / 100) * 6.28;
    const particle = particlesAccess.$[i];
    particle.position = d.vec2f(cos(angle) * 0.3, sin(angle) * 0.3);
    particle.velocity = d.vec2f(cos(angle) * 2, sin(angle) * 2);
  };

  return <Confetti initParticle={burstInit} />; 
}
```

--------------------------------

### Prebuild Native Code for React Native

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/_autodocs/integration-guide.md

Run expo prebuild to generate native code for non-Expo React Native projects.

```bash
expo prebuild --clean
```

--------------------------------

### Basic React Web ConfettiProvider and Hook Usage

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/_autodocs/integration-guide.md

Shows how to use ConfettiProvider and the useConfetti hook for managing confetti state in a React Web application. Enables celebrating via a button click.

```typescript
import { ConfettiProvider, useConfetti } from 'typegpu-confetti/react';

function App() {
  return (
    <ConfettiProvider>
      <MyPage />
    </ConfettiProvider>
  );
}

function MyPage() {
  const confettiRef = useConfetti();

  return (
    <div>
      <button onClick={() => confettiRef?.current?.addParticles(100)}>
        Celebrate!
      </button>
    </div>
  );
}
```

--------------------------------

### Import Advanced GPU Primitives

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/_autodocs/API-INDEX.md

Import specific GPU accessors and slots for advanced usage.

```typescript
import { particlesAccess, gravitySlot, timeAccess } from 'typegpu-confetti';
```

--------------------------------

### initParticleFn

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/_autodocs/api-reference/exported-accessors-and-slots.md

A TypeGPU function template that wraps user-provided particle initialization functions. It is instantiated with `initParticleFn(userInitFunction)` when configuring compute pipelines and modifies global particle data.

```APIDOC
## initParticleFn

### Description
A TypeGPU function template that wraps user-provided particle initialization functions.

### Signature
`(index: i32) -> void`

### Binding
Instantiated with `initParticleFn(userInitFunction)` when configuring compute pipelines.

### Side effects
Modifies global particle data via `particlesAccess.$[index]`.
```

--------------------------------

### TypeGPU Confetti TypeScript Props and Refs

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/_autodocs/integration-guide.md

Demonstrates how to use TypeScript types for Confetti component props and refs. Ensure correct import paths for types.

```typescript
import { Confetti, type ConfettiProps, type ConfettiRef } from 'typegpu-confetti/react';

const props: ConfettiProps = {
  colorPalette: [[255, 0, 0, 1]],
  size: 1.5,
  maxDurationTime: 3,
};

const ref = React.useRef<ConfettiRef>(null);
```

--------------------------------

### initParticleSlot

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/_autodocs/api-reference/exported-accessors-and-slots.md

A TypeGPU slot that binds the user-provided particle initialization function to compute pipelines. It is done automatically in `createConfettiComponent` and used in `initCompute` and `addParticleComputePipeline` shaders.

```APIDOC
## initParticleSlot

### Description
A TypeGPU slot that binds the user-provided particle initialization function to compute pipelines.

### Binding
Done automatically in `createConfettiComponent` when the component configures `initCompute` and `addParticleComputePipeline`.

### Used in
`initCompute` and `addParticleComputePipeline` shaders to initialize particle state.
```

--------------------------------

### Configuration Options

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/_autodocs/MANIFEST.md

Available configuration options for customizing the confetti effect, including color, size, duration, and particle behavior.

```APIDOC
## Configuration Options

### Description
These options allow for detailed customization of the confetti animation's appearance and behavior.

| Option | Type | Default | Notes |
|---|---|---|---|
| `colorPalette` | `[r, g, b, a][]` | 5-color palette | RGBA values with r,g,b from 0-255, and a from 0-1. |
| `size` | `number` | `1` | A multiplier affecting the visual size of particles. |
| `maxDurationTime` | `number | null` | `2` | The duration of the animation in seconds. `null` means indefinite. |
| `initParticleAmount` | `number` | `200` (or `0` in provider) | The initial number of particles to spawn. |
| `maxParticleAmount` | `number` | `1000` (or `500` in provider) | The maximum number of particles allowed in the simulation. |
| `gravity` | `GravityFn` | Downward (0, -0.3) | A custom GPU acceleration function for particle gravity. |
| `initParticle` | `InitParticleFn` | Random spawn | A custom GPU initialization function for particle properties.
```

--------------------------------

### Seed Randomness Using Time in GPU Function

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/_autodocs/api-reference/exported-accessors-and-slots.md

Demonstrates seeding a random number generator within a GPU function using the elapsed time. This ensures that particle initialization is dependent on time, leading to varied results.

```typescript
const initParticle: InitParticleFn = (i) => {
  'use gpu';
  randf.seed2(d.vec2f(d.f32(i), d.f32(time.$ % 1111)));
  // Use seeded randomness for particle initialization
};
```

--------------------------------

### Default Confetti Configuration Object

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/_autodocs/README.md

Provides the default configuration settings for TypeGPU Confetti, including animation duration, particle counts, color palettes, and default gravity and initialization functions.

```typescript
{
  maxDurationTime: 2,
  initParticleAmount: 200,
  maxParticleAmount: 1000,
  
  size: 1,
  colorPalette: [
    [154, 177, 155, 1],
    [67, 129, 193, 1],
    [99, 71, 77, 1],
    [239, 121, 138, 1],
    [255, 166, 48, 1],
  ],
  
  gravity: (pos) => {
    'use gpu';
    return d.vec2f(0, -0.3);
  },
  
  initParticle: (i) => {
    'use gpu';
    const particle = particlesAccess.$[i];
    particle.position = d.vec2f(randf.sample() * 2 - 1, randf.sample() / 1.5 + 1);
    particle.velocity = d.vec2f(randf.sample() * 2 - 1, -(randf.sample() / 25 + 0.01) * 50);
  },
}
```

--------------------------------

### TypeGPU Confetti Publish Configuration

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/_autodocs/integration-guide.md

Configures the publish settings for TypeGPU Confetti, supporting both ESM and CJS module formats in the build output.

```json
{
  "publishConfig": {
    "exports": {
      ".": {
        "types": "./dist/index.d.ts",
        "module": "./dist/index.js",
        "import": "./dist/index.js",
        "default": "./dist/index.cjs"
      }
    }
  }
}
```

--------------------------------

### Define Initialize Particle Function Template

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/_autodocs/api-reference/gpu-functions-and-slots.md

Defines a TypeGPU function template for particle initialization with a signature of (index: i32) -> void. It modifies global particlesAccess to initialize particle properties.

```typescript
export const initParticleFn = tgpu.fn([d.i32]);
```

--------------------------------

### File Structure of TypeGPU Confetti

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/_autodocs/README.md

This snippet outlines the directory structure of the TypeGPU Confetti library, showing the organization of core components, React wrappers, and React Native implementations.

```tree
src/
├── index.ts                           # Main entry: types & slots
├── core/
│   ├── create-confetti-component.tsx  # Core factory
│   ├── types.ts                       # ConfettiProps, ConfettiRef
│   ├── schemas.ts                     # GPU shaders, slots, accessors
│   ├── defaults.ts                    # Default config
│   └── utils.ts                       # Error handling wrapper
├── react/
│   ├── index.ts                       # React entry
│   ├── Confetti.tsx                   # React wrapper
│   └── ConfettiProvider.tsx           # Context provider
└── react-native/
    ├── index.ts                       # React Native entry
    ├── Confetti.tsx                   # React Native wrapper
    └── ConfettiProvider.tsx           # Context provider
```

--------------------------------

### initCompute

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/_autodocs/api-reference/gpu-functions-and-slots.md

A compute shader function used for initializing particle states. It calls user-provided functions to set initial positions, velocities, and other properties for each particle.

```APIDOC
## initCompute

### Description
Initializes particle states by calling user-provided functions to set initial properties like position and velocity.

### Type
Compute shader function

### Workgroup size
1 thread per workgroup

### Input
- **in.gid.x** (u32) - Global thread index (particle index to initialize)

### Logic (per particle, once at start or on restart)
1. Call `preInitParticle(index)` to set `timeLeft` and seed.
2. Call the user's `initParticle(index)` to set position/velocity.

### Bindings required
- **particles** (accessor) - Mutable particle buffer
- **maxDurationTime** (slot) - Animation duration in milliseconds
- **initParticle** (slot) - User-provided initialization function
- **time** (accessor) - Elapsed time for seeding
```

--------------------------------

### Particle Data Structure for GPU Initialization

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/README.md

Defines the structure of particle data used for initialization on the GPU. This includes position, velocity, seed, and time left, accessible via tgpu accessors.

```typescript
const ParticleData = d.struct({
    position: d.vec2f,
    velocity: d.vec2f,
    seed: d.f32,
    timeLeft: d.f32,
  });
```

--------------------------------

### TypeGPU Confetti Peer Dependencies

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/_autodocs/integration-guide.md

Defines the peer dependencies required for TypeGPU Confetti, including React, React Native, and react-native-wgpu.

```json
{
  "peerDependencies": {
    "@typegpu/react": "*",
    "react": "*",
    "react-native": "*",
    "react-native-wgpu": ">=0.4.2"
  },
  "peerDependenciesMeta": {
    "react": { "optional": true },
    "react-native": { "optional": true },
    "react-native-wgpu": { "optional": true }
  }
```

--------------------------------

### Confetti Component Usage with ConfettiProps

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/_autodocs/types.md

Shows how to configure the Confetti component with custom properties like color palette, size, duration, and particle amounts.

```typescript
import {
  Confetti
} from 'typegpu-confetti/react';

function Example() {
  const customColors: ConfettiProps['colorPalette'] = [
    [255, 0, 0, 1],
    [0, 255, 0, 1],
    [0, 0, 255, 1],
  ];

  return (
    <Confetti
      colorPalette={customColors}
      size={1.5}
      maxDurationTime={3}
      initParticleAmount={100}
      maxParticleAmount={500}
    />
  );
}
```

--------------------------------

### Type Definition for InitParticleFn

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/_autodocs/README.md

Defines the signature for a custom GPU function used for particle initialization. It must be marked with the 'use gpu' directive and receives the particle index.

```typescript
type InitParticleFn = (index: number) => void;
```

--------------------------------

### Basic React Native ConfettiProvider and Hook Usage

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/_autodocs/integration-guide.md

Shows how to use ConfettiProvider and the useConfetti hook for confetti management in React Native. Enables celebrating with confetti through a button.

```typescript
import { View } from 'react-native';
import { ConfettiProvider, useConfetti } from 'typegpu-confetti/react-native';

function App() {
  return (
    <ConfettiProvider>
      <MyPage />
    </ConfettiProvider>
  );
}

function MyPage() {
  const confettiRef = useConfetti();

  return (
    <View style={{ flex: 1 }}>
      <Button
        title="Celebrate!"
        onPress={() => confettiRef?.current?.addParticles(100)}
      />
    </View>
  );
}
```

--------------------------------

### Import React Native Components

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/_autodocs/API-INDEX.md

Import React components and hooks for React Native applications.

```typescript
import { Confetti, ConfettiProvider, useConfetti } from 'typegpu-confetti/react-native';
```

--------------------------------

### Import Confetti Component (React Web)

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/_autodocs/api-reference/confetti-component.md

Import the Confetti component for React Web applications from the 'typegpu-confetti/react' package.

```typescript
import { Confetti } from 'typegpu-confetti/react';
```

--------------------------------

### Confetti Component Usage with ConfettiRef

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/_autodocs/types.md

Demonstrates how to use the ConfettiRef to control the Confetti component's animation programmatically via buttons.

```typescript
import {
  useRef
} from 'react';
import {
  Confetti,
  type ConfettiRef
} from 'typegpu-confetti/react';

function Example() {
  const ref = useRef<ConfettiRef>(null);

  return (
    <div>
      <Confetti ref={ref} />
      <button onClick={() => ref.current?.pause()}>Pause</button>
      <button onClick={() => ref.current?.resume()}>Resume</button>
      <button onClick={() => ref.current?.restart()}>Restart</button>
      <button onClick={() => ref.current?.addParticles(50)}>Add 50</button>
    </div>
  );
}
```

--------------------------------

### ConfettiProvider and useConfetti Hook

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/_autodocs/README.md

Provides a context for managing confetti state and allows access to confetti control functions via a hook.

```APIDOC
## ConfettiProvider & useConfetti Hook

### Description

The `ConfettiProvider` component sets up a context that manages the confetti animation's state. The `useConfetti` hook provides convenient access to the imperative control methods (`pause`, `resume`, `restart`, `addParticles`) exposed by the `ConfettiRef` interface within any descendant component.

### Usage

Wrap your application or a relevant part of it with `ConfettiProvider`.

```jsx
import { ConfettiProvider, useConfetti } from 'typegpu-confetti/react';

function App() {
  return (
    <ConfettiProvider>
      <ConfettiControls />
      {/* Other components */}
    </ConfettiProvider>
  );
}

function ConfettiControls() {
  const { pause, resume, restart, addParticles } = useConfetti();

  return (
    <button onClick={() => addParticles(100)}>Add Particles</button>
    // ... other control buttons
  );
}
```

### `useConfetti` Hook Return Value

- **`pause`**: () => void - Function to pause the confetti animation.
- **`resume`**: () => void - Function to resume the confetti animation.
- **`restart`**: () => void - Function to restart the confetti animation.
- **`addParticles`**: (amount: number) => void - Function to add a specified number of particles.
```

--------------------------------

### Core TypeGPU Confetti Exports

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/_autodocs/integration-guide.md

Exports from the main entry point of the typegpu-confetti package, including core types and GPU accessors.

```typescript
export {
  // Core types
  type ConfettiProps,
  type ConfettiRef,
  
  // GPU accessors and slots (for advanced use)
  gravitySlot,
  gravityFn,
  initParticleSlot,
  initParticleFn,
  maxDurationTimeSlot,
  particlesAccess,
  deltaTimeAccess,
  aspectRatioAccess,
  timeAccess,
  
  // Deprecated aliases
  gravity,
  initParticle,
  maxDurationTime,
  particles,
  deltaTime,
  canvasAspectRatio,
  time,
  maxParticleAmount,
} from './core/schemas.ts';
```

--------------------------------

### ParticleGeometry

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/_autodocs/api-reference/gpu-functions-and-slots.md

Defines the structure for per-particle rendering properties, including tilt, angle, and color, used in the per-instance buffer.

```APIDOC
## ParticleGeometry

### Description
Defines the structure for per-particle rendering properties, including tilt, angle, and color, used in the per-instance buffer.

### Fields
- **tilt** (f32) - Width/height scale of the particle quad
- **angle** (f32) - Rotation angle in degrees
- **color** (vec4f) - RGBA color (0–1 range)
```

--------------------------------

### TypeGPU Confetti GPU Error Handling

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/_autodocs/integration-guide.md

Wraps shader compilation with deferred error handling using pushErrorScope and popErrorScope to log validation failures.

```typescript
root.device.pushErrorScope('validation');
// Shader compilation happens here
root.device.popErrorScope().then(warn);
```

--------------------------------

### TypeGPU Confetti Node.js Engine Requirement

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/_autodocs/integration-guide.md

Specifies the minimum required Node.js version for developing with TypeGPU Confetti.

```json
{
  "engines": {
    "node": ">=22.0.0"
  }
}
```

--------------------------------

### Correct TypeGPU Confetti Imports

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/_autodocs/integration-guide.md

Use platform-specific imports for React and React Native. Avoid importing core functions from platform-specific modules.

```typescript
// ✅ Correct
import { Confetti } from 'typegpu-confetti/react';
import { ConfettiProvider, useConfetti } from 'typegpu-confetti/react-native';
import type { ConfettiProps, ConfettiRef } from 'typegpu-confetti';

// ❌ Incorrect
import Confetti from 'typegpu-confetti';  // Use platform-specific import
import { gravityFn } from 'typegpu-confetti/react';  // gravityFn is in core, not react
```

--------------------------------

### Direct Confetti Ref Usage in React

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/_autodocs/README.md

Shows an alternative React usage pattern using a direct ref to the Confetti component. This provides methods for controlling the confetti, such as pause, resume, restart, and adding particles.

```typescript
import { Confetti, type ConfettiRef } from 'typegpu-confetti/react';
import { useRef } from 'react';

function MyComponent() {
  const ref = useRef<ConfettiRef>(null);

  return (
    <>
      <Confetti ref={ref} initParticleAmount={100} />
      <button onClick={() => ref.current?.pause()}>Pause</button>
      <button onClick={() => ref.current?.resume()}>Resume</button>
      <button onClick={() => ref.current?.restart()}>Restart</button>
      <button onClick={() => ref.current?.addParticles(50)}>Add 50</button>
    </>
  );
}
```

--------------------------------

### Confetti Component with Imperative Handle

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/README.md

Use the `Confetti` component with a ref to imperatively control its state and add particles. Ensure the ref is typed as `ConfettiRef`.

```tsx
import type { ConfettiRef } from 'typegpu-confetti';
import { Confetti } from 'typegpu-confetti/react-native';

function SomeComponent() {
  const ref = useRef<ConfettiRef>(null);

  return (
    <View>
      <Confetti initParticleAmount={200} maxParticleAmount={1000} ref={ref} />
      <Button title="add particles" onPress={() => ref.current?.addParticles(200)} />
    </View>
  );
}
```

--------------------------------

### Define Initialization Compute Shader

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/_autodocs/api-reference/gpu-functions-and-slots.md

Defines the compute shader for initializing particles. It runs with a single thread per workgroup to set initial particle states using user-provided functions.

```typescript
export const initCompute = tgpu.computeFn({
  in: { gid: d.builtin.globalInvocationId },
  workgroupSize: [1],
})(/* WGSL implementation */);
```

--------------------------------

### Define Vertex Shader Output Structure

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/_autodocs/api-reference/gpu-functions-and-slots.md

Defines the output structure for the vertex shader, which is then passed as input to the fragment shader. Includes clip-space position, interpolated color, and a flat expiration flag.

```typescript
export const VertexOutput = {
  position: d.builtin.position,
  color: d.vec4f,
  isExpired: d.interpolate('flat', d.u32),
};
```

--------------------------------

### gravitySlot

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/_autodocs/api-reference/exported-accessors-and-slots.md

A TypeGPU slot that binds the user-provided gravity function to the main compute pipeline. It is done automatically in `createConfettiComponent` and used in the `mainCompute` shader.

```APIDOC
## gravitySlot

### Description
A TypeGPU slot that binds the user-provided gravity function to the main compute pipeline.

### Binding
Done automatically in `createConfettiComponent` when the component configures the compute pipeline.

### Used in
`mainCompute` shader to compute particle acceleration.
```

--------------------------------

### gravityFn

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/_autodocs/api-reference/exported-accessors-and-slots.md

A TypeGPU function template that wraps user-provided gravity functions. It is instantiated with `gravityFn(userGravityFunction)` when configuring the compute pipeline and returns an acceleration vector applied to particle velocity.

```APIDOC
## gravityFn

### Description
A TypeGPU function template (not a runtime function) that wraps user-provided gravity functions.

### Signature
`(pos: vec2f) -> vec2f`

### Binding
Instantiated with `gravityFn(userGravityFunction)` when configuring the compute pipeline.

### Returns
An acceleration vector applied to particle velocity.
```

--------------------------------

### Define Particle Initialization Slot

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/_autodocs/api-reference/gpu-functions-and-slots.md

Defines a TypeGPU slot for binding a user-provided particle initialization function. This slot is used in initCompute and addParticleComputePipeline shaders.

```typescript
export const initParticleSlot = tgpu.slot<TgpuFn<(index: d.I32) => d.Void>>();
```

--------------------------------

### React Web Exports

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/_autodocs/README.md

This snippet lists the exports available for use in React Web applications.

```typescript
export { Confetti, ConfettiProvider, useConfetti }
```

--------------------------------

### React Web Imports

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/_autodocs/types.md

Imports ConfettiProps and ConfettiRef for React Web applications.

```typescript
// React Web
import type { ConfettiProps, ConfettiRef } from 'typegpu-confetti';
```

--------------------------------

### GPU Accessors

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/_autodocs/API-INDEX.md

Provides read-only access to uniform and storage buffer data used in the GPU simulation, such as particle data, delta time, and simulation parameters.

```APIDOC
## particlesAccess Accessor

### Description
Provides mutable access to the particle data buffer.

### Type
`TgpuArray<ParticleData>`

### Location
`typegpu-confetti/api-reference/exported-accessors-and-slots.md#particlesaccess`

### Deprecated Alias
`particles`

## deltaTimeAccess Accessor

### Description
Provides access to the time elapsed since the last frame in milliseconds.

### Type
`f32`

### Location
`typegpu-confetti/api-reference/exported-accessors-and-slots.md#deltaaccess`

### Deprecated Alias
`deltaTime`

## timeAccess Accessor

### Description
Provides access to the total elapsed time since the component mounted, in milliseconds.

### Type
`f32`

### Location
`typegpu-confetti/api-reference/exported-accessors-and-slots.md#timeaccess`

### Deprecated Alias
`time`

## aspectRatioAccess Accessor

### Description
Provides the aspect ratio of the canvas (width divided by height).

### Type
`f32`

### Location
`typegpu-confetti/api-reference/exported-accessors-and-slots.md#aspectratioaccess`

### Deprecated Alias
`canvasAspectRatio`

## maxParticleAmountAccess Accessor

### Description
Provides the maximum number of particles allowed in the simulation.

### Type
`i32`

### Location
`typegpu-confetti/api-reference/exported-accessors-and-slots.md#maxparticleamountaccess`

### Deprecated Alias
`maxParticleAmount`
```

--------------------------------

### Define Gravity Function Template

Source: https://github.com/software-mansion-labs/typegpu-confetti/blob/main/_autodocs/api-reference/gpu-functions-and-slots.md

Defines a TypeGPU function template for gravity computations with a signature of (pos: vec2f) -> vec2f. It is instantiated at runtime with the user's gravity function.

```typescript
export const gravityFn = tgpu.fn([d.vec2f], d.vec2f);
```