vimny-levels

The community level shelf for Vimny, the Vim-teaching dungeon crawler. Every file under levels/ is one custom level.

A level is a JSON file, not code — the game reads it, builds a room from it, and runs none of it. That is why it is safe to play a level a stranger wrote.

How the game uses this repo

Vimny fetches index.json — the manifest — and lists the levels in its overworld, where a player can browse and install them. Installing pulls the level's raw JSON, runs it through the validator, and drops it on the local shelf (~/.Vimny/levels/), where it appears under community/.

Nothing here executes on the player's machine. The only thing downloaded is data.

Submitting a level

1. Author it — with the in-game forge (forge/ in the overworld, % for a new draft) or by hand. The format is documented in Vimny's docs/AUTHORING.md.
2. Validate it — it must pass before it can go on the shelf:

   python3 -m sharing validate mylevel.json
   

3. Add the file — drop mylevel.json into levels/.
4. List it — add a row to index.json (see the format below).
5. Open a pull request. CI re-runs the validator on your file.

Manifest format

index.json is a JSON object with a levels array. Each row points at one file and carries just enough metadata for the browser to show it without downloading every level first:

{
  "schema": 1,
  "levels": [
    {
      "name": "The Counting Crypts",
      "author": "",
      "slug": "counting-crypts",
      "teaches": ["count"],
      "path": "levels/counting-crypts.json"
    }
  ]
}

field	meaning
name	the level's display name (matches the name in the level file)
author	who wrote it (may be empty)
slug	a stable, unique, kebab-case id — also the filename stem
teaches	the Vim command(s) the level is built around
path	where the level file lives in this repo

Keep slug, the filename stem, and path consistent: a level at levels/counting-crypts.json has slug counting-crypts.

License

All levels in this repository are licensed CC BY 4.0 (see LICENSE).

By opening a pull request, you agree that your level is contributed under CC BY 4.0 — anyone may play, remix, and redistribute it, with attribution.

This is independent of Vimny's own license: the game is GPL software, and a GPL program reading CC-licensed data files is fine — the data is not a derivative work of the engine.