Contributing to wgsl-fns

Contributing Overview

The wgsl-fns library welcomes contributions of new WGSL functions! Whether you've created a useful mathematical function, noise algorithm, or shader utility, we'd love to include it in the library for others to use.

Getting Started

1. Fork the Repository

Start by forking the wgsl-fns repository on GitHub and cloning it to your local machine.

git clone https://github.com/koole/wgsl-fns.git
cd wgsl-fns
npm install

2. Set Up Development Environment

Install dependencies and start the development watcher:

npm install
npm run dev    # Watch for changes during development
npm test       # Run tests

Adding New Functions

1. Choose the Right Category

Add your function to the appropriate category file:

2. Function Structure

Each function should follow this structure with complete JSDoc documentation:

/**
 * @wgsl
 * @name myFunction
 * @description Brief description of what the function does
 * @param {f32} x First parameter description
 * @param {f32} y Second parameter description
 * @returns {f32} Description of return value
 * @requires dependency1 dependency2
 */
export const myFunction = `//! requires dependency1 dependency2
fn myFunction(x: f32, y: f32) -> f32 {
    return dependency1(x) + dependency2(y);
}`;

3. Documentation Requirements

4. Dependency Declaration

If your function calls other WGSL functions, declare dependencies using magic comments:

export const fbm = `//! requires noise2D hash22
fn fbm(p: vec2<f32>) -> f32 {
    var value = 0.0;
    var amplitude = 0.5;
    var frequency = 0.0;
    
    for (var i = 0; i < 4; i++) {
        value += amplitude * noise2D(p * frequency);
        frequency *= 2.0;
        amplitude *= 0.5;
    }
    
    return value;
}`;

The build system uses these comments to automatically resolve dependencies when users call getFns().

Register Your Function

1. Export from Category File

Make sure your function is exported from the category file (e.g., src/math.ts).

2. Add to Functions Registry

Add your function to src/functions.ts:

// Import your function
import { myFunction } from './math';

// Add to the functions object
export const functions = {
  // ...existing functions...
  myFunction,
} as const;

Testing

Run Tests

Before submitting your contribution, make sure all tests pass:

npm test           # Run all tests
npm run test:ci    # Run tests with build (CI command)

What Tests Check

Submitting Your Contribution

1. Create a Pull Request

Once your function is ready and tests pass:

git add .
git commit -m "Add myFunction to math utilities"
git push origin your-branch-name

Then create a pull request on GitHub with a clear description of your function and its use case.

2. Pull Request Guidelines

Example Contribution

Here's a complete example of adding a new easing function:

// In src/math.ts

/**
 * @wgsl
 * @name easeInOutCubic
 * @description Cubic ease-in-out function for smooth animations
 * @param {f32} t Progress value between 0.0 and 1.0
 * @returns {f32} Eased value between 0.0 and 1.0
 */
export const easeInOutCubic = `fn easeInOutCubic(t: f32) -> f32 {
    if (t < 0.5) {
        return 4.0 * t * t * t;
    }
    let p = 2.0 * t - 2.0;
    return 1.0 + p * p * p / 2.0;
}`;

// In src/functions.ts
import { easeInOutCubic } from './math';

export const functions = {
  // ...existing functions...
  easeInOutCubic,
} as const;

Release Process

Once your pull request is merged, the maintainers will handle the release process:

Need Help?