Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
136 lines (96 loc) · 4.12 KB

CONTRIBUTING.md

File metadata and controls

136 lines (96 loc) · 4.12 KB
Raw

Contributing to Runner Gallery

Thank you for your interest in sharing your custom runner! This repository distributes custom runner resources for RunCat Neo, browsable at https://runcat-dev.github.io/RunnerGallery/.

How to Add a Runner

1. Choose a runner name

Use a lowercase, hyphen-separated name (e.g., welsh-corgi). This name is used for the directory and file names.

2. Prepare the files

Place the following three files in runners/<runner-name>/:

runners/
└── <runner-name>/
    ├── <runner-name>-frames.zip
    ├── metadata.json
    └── preview.png

<runner-name>-frames.zip

A zip archive of a <runner-name>-frames/ directory containing the animation frames:

<runner-name>-frames/
├── <runner-name>-frame-0.png
├── <runner-name>-frame-1.png
└── ...

Frame requirements:

  • Format: PNG, not interlaced
  • File name: <runner-name>-frame-<N>.png, numbered consecutively from 0
  • Height: exactly 36px
  • Width: between 10px and 100px
  • All frames must have the same size
  • A transparent background is recommended
  • The zip must contain nothing but the frames — no Finder-generated files such as .DS_Store, __MACOSX/, or ._*

Tip for macOS users — creating the zip from the command line avoids Finder-generated junk:

zip -r <runner-name>-frames.zip <runner-name>-frames -x "*.DS_Store" "__MACOSX/*"

metadata.json

{
  "author": "Your Name (YourGitHubID)",
  "displayName": "Display Name",
  "type": "monochrome",
  "tags": ["animal"]
}

type must be one of:

  • monochrome — grayscale or single-color runners
  • color — runners that use more than one hue

tags is a list of tags, chosen from this closed set:

tag meaning
animal Any living creature, including fictional ones (excludes human-shaped characters)
dog Dogs. Requires animal as well
object Inanimate objects, tools, geometric shapes
mechanism Moving mechanical devices. Requires object as well
fitness Exercise or workout-themed runners

Guidelines:

  • Human-shaped characters do not receive animal. If nothing fits, use an empty array [].
  • Prefer fewer tags when unsure. Extra tags can always be added later.
  • Adding a new tag needs to be proposed in a separate PR that updates both this document and KNOWN_TAGS in .github/scripts/validate_runners.py.

preview.png

An animated PNG (APNG) used for the gallery preview:

  • Format: APNG, not interlaced (a static PNG will not animate in the gallery)
  • Height: 36px
  • Width: at most 100px

3. Update the manifest

Add your runner name to runners/manifest.json. Keep the list sorted alphabetically. CI enforces this.

{
  "runners": [
    "beagle",
    "your-runner-name"
  ]
}

4. Check your runner locally

Every Pull Request is automatically checked: the frame archive must contain nothing but your frames, and every image must be a genuine, fully decodable PNG. You can run exactly the same checks yourself before pushing, so that you do not have to wait for CI:

pip install -r .github/scripts/requirements.txt
python3 .github/scripts/validate_runners.py --all

Anything it reports tells you which file is at fault and what to change.

5. Open a Pull Request

  1. Fork this repository and create a branch.
  2. Commit your runner files and the manifest change.
  3. Open a Pull Request and fill in the template, including the checklist.

Licensing and Originality

  • By submitting a runner, you agree that it will be distributed under this repository's Apache-2.0 license.
  • The runner must be your original work, or you must hold the rights to it.
  • Runners containing third-party intellectual property (e.g., Pokémon, Mario, or other copyrighted/trademarked characters) cannot be accepted, even as fan art.

Previewing the Site Locally

The gallery page loads runners/manifest.json with fetch(), which does not work over file://. Run a local server from the repository root instead:

python3 -m http.server 8000

Then open http://localhost:8000/ in your browser.