reface/CONTRIBUTING.md

How to contribute to Reface

Thanks for showing interest in contributing to rbx-reface. This is mostly a solo developer project so any support is welcome!

Setup

Tools are managed via Rokit. Install Rokit first, then run:

rokit install

This installs Rojo and Wally at the versions pinned in rokit.toml.

To build the package:

rojo build --output build/build.rbxm

Working on the module

The code should be well typed, documented when needed (but as self-documenting as possible), and easy to modify. Don't be scared to break up small things into their own functions, tables, or even submodules (especially data).

A few conventions to follow:

• Naming: camelCase for functions and variables, PascalCase for type names.
• Types: all function parameters and return values should be typed. Shared types live in typing.luau.
• String interpolation: use backtick interpolation (`like {this}`) rather than .. concatenation.
• Errors: use warn() with a rbx-reface: prefix for non-fatal issues, rather than error() or print().

Working on the face databases

The face databases (faceByBundle.luau and faceByMesh.luau) are generated - don't edit them by hand.

scripts/faces.csv is a plain list of face asset IDs. When a new face is added or the list changes, regenerate the databases by running:

uv run scripts/codegen.py

The script hits the Roblox catalog API to resolve each face ID to its bundle, then resolves the bundle to its head mesh asset. It writes the results directly into src/faceByBundle.luau and src/faceByMesh.luau. It includes retry logic for rate limits, but may still be slow if you're adding many faces at once.

Python 3.13+ is required. uv handles the dependency (requests) automatically.

Opening issues and pull requests

• For bugs, please include the relevant head or face asset ID.
• For larger changes (new features, restructuring), open an issue first so we can verify where we're at before you put in the work.
• For small fixes or database additions, a PR directly is fine.