Submit a mod
Mods are listed through a pull request to the Blockheads-Club/mods repository. CI checks the files and a maintainer reviews the rest.
How to submit
-
Build and publish your mod
Run bhmod pack and attach the .bhmod file to a release in your own repository. The download link must be a public https:// address ending in .bhmod.
-
Fork Blockheads-Club/mods
Add one file: mods/<first letter>/<id>.toml, for example mods/h/hello-lua.toml. It holds the mod’s name, owners, repository and every published version.
-
Describe the version
For each version give the download URL, the SHA-256 and size of the .bhmod file, the sides, the API range, the permissions and the date.
-
Open a pull request
CI runs the checks below and comments with the result. A maintainer reviews and merges. Then the index is rebuilt and this page picks it up on its next build.
Rules
- One mod per pull request.
- Every new mod gets a security review: a maintainer reads its code before it is listed. Updates are reviewed again when they add permissions or native code.
- Only the owners listed in the file can add versions. The first submitter becomes the first owner.
- Versions are append-only. Never edit or remove a published version; the only allowed change is yanked = true, to pull a broken or unsafe version.
- Only submit mods you made or may share, and keep their licence in your repository.
- Ask only for the permissions the mod really needs.
- No game files and no copied game assets.
What CI checks
- The file follows the index schema and its path matches the mod id.
- The pull request touches exactly one mod.
- Versions are only appended; existing ones change only by yanked.
- The pull request author is one of the owners.
- The download works, and its SHA-256 and size match.
- The package follows the package rules, and its mod.toml matches the entry.
- Dependencies exist in the index and their version ranges can be met.
- WASM modules validate and Lua/Luau scripts compile.
- A permission diff is posted. Every new mod, versions with native code and updates that add a permission get the needs-security-review label and wait for a maintainer’s review.
Mods with native = true run code outside the sandbox. They are allowed, but they are reviewed by hand and shown with a red warning.
Tools
The mod SDK has the bhmod command line tool, the schemas and examples.