DOCS

Overview

CHESSWORLD.GAMES is a browser-based game platform built by the Zenith chess engine team. It exists as both a creative outlet and an entry point for new contributors — if you want to join the team, building a game here is your first step.

The platform is intentionally modular. You build your game in an isolated directory, use whatever technology stack you prefer, and submit it for review. You never need to touch the core website code.

The Challenge

Before joining the Zenith team, every developer completes one challenge:

Create your own mini game. Not a clone. Not a tutorial project. Your game. Your rules. Your idea.

Your game must:

• Have a clear set of rules
• Be playable (even if simple)
• Demonstrate your approach to logic and structure
• Be related to chess in some way

There are no restrictions on genre, complexity, or language/framework — as long as it runs in a browser and integrates with the platform structure described below.

We're not judging polish. We're looking for clarity of thought, code structure, documentation practices, problem-solving approach, and creativity.

Adding a Game

Adding your game requires zero modifications to the core site. Here is the full process:

git clone https://github.com/alaishach/game.chessworld.git
cd game.chessworld

git checkout -b game/your-game-name

mkdir games/your-game-name

npm install
npm run dev

File Structure

Your game folder is entirely self-contained. Files marked required must be present for your PR to be accepted.

games/
└── your-game-name/
    ├── game.json          ← platform manifest (required)
    ├── description.md     ← shown above the game iframe (required)
    ├── rules.md           ← shown below the game iframe (required)
    ├── thumbnail.png      ← 16:9 preview screenshot (required)
    ├── README.md          ← dev notes for reviewers (required)
    ├── index.html         ← your game entry point
    ├── src/
    │   ├── main.js
    │   └── style.css
    └── assets/

If you use a build step, include build instructions in your README.md and commit the built output. Your final output must be servable as static files.

game.json Manifest

Every game requires a game.json file. This is how the platform discovers, displays, and validates your game.

{
  "title": "Your Game Title",
  "description": "A short 1-2 sentence description for the games listing page.",
  "author": "your-github-username",
  "version": "1.0.0",
  "thumbnail": "thumbnail.png",
  "entry": "index.html",
  "tags": ["strategy", "singleplayer"],
  "rating": "E",
  "chessRelation": "One sentence on how your game connects to chess.",
  "changelog": [
    {
      "version": "1.0.0",
      "date": "2026-04-01",
      "notes": "Initial release."
    }
  ]
}

Markdown Files

Two markdown files are required in every game folder. They are parsed by the platform and rendered automatically on your game's page.

description.md — rendered above the iframe

# Your Game Title

A paragraph describing what your game is and why it's worth playing.

You can use multiple paragraphs, **bold**, *italics*, and inline `code`.

rules.md — rendered below the iframe

## Rules

- Rule one
- Rule two
- Rule three

## Controls

| Action | How |
|--------|-----|
| Select | Click a piece |
| Move   | Click a valid square |
| Restart| Click the Restart button |

API Routes

Because the platform runs on Astro SSR, your game can include server-side API routes. Place them inside your game folder under an api/ subdirectory and they will be mounted automatically.

games/your-game-name/
└── api/
    └── score.ts

API routes must export a handler function using Astro's standard endpoint format:

import type { APIRoute } from 'astro';

export const POST: APIRoute = async ({ request }) => {
  const body = await request.json();
  // your logic here
  return new Response(JSON.stringify({ ok: true }), {
    headers: { 'Content-Type': 'application/json' },
  });
};

Database Options

Games that need to persist data (leaderboards, saved states, etc.) are responsible for their own storage. The platform does not provide a shared database.

Recommended options that work well on Netlify edge/functions:

• Upstash Redis — serverless Redis, free tier available, ideal for leaderboards and counters
• PlanetScale / Turso — serverless MySQL/SQLite, good for relational data
• Supabase — Postgres with a generous free tier and a simple REST API
• localStorage — for single-player games where data only needs to persist per browser

Commit Standards

All commits must follow the Conventional Commits format. PRs with non-conforming commit histories will be asked to rebase before merge.

type(scope): short description

# Examples
feat(pawn-push): add difficulty selector
fix(pawn-push): correct pawn promotion logic
docs(pawn-push): update rules.md controls table
style(pawn-push): adjust board colour contrast
refactor(pawn-push): extract move validation to helper
chore(pawn-push): update game.json version to 1.1.0

The scope should always be your game folder name. Keep the subject line under 72 characters and written in the imperative mood ("add", "fix", "update" — not "added" or "fixes").

Quality Standards

There is no minimum complexity requirement, but every submission is reviewed against these criteria before merge:

• Playable end-to-end — the game must have a clear start, a win/lose/end condition, and a way to restart
• No console errors — open the browser console during a full playthrough; it must be clean
• Mobile-usable — the game does not need to be mobile-first, but it must not be broken on a phone screen
• Accessible thumbnail — the thumbnail.png must be a real screenshot at 16:9 ratio, minimum 800×450px
• Accurate manifest — the game.json description, rating, and tags must accurately reflect the actual game
• Readable code — reviewers will read your source. Variable names, structure, and comments should make intent clear

Content Ratings

Every game must declare a content rating in game.json. Be honest — mislabelled ratings are grounds for immediate removal.

Size Limits

Keep your game folder lean. Large assets slow the platform for everyone.

What Not To Do

These are the most common reasons PRs get rejected or games get removed.

Submission

When your game is ready, push your branch and open a pull request against main on GitHub.

git push origin game/your-game-name

In your PR description, include:

• A brief description of what your game is and how it works
• A note on how it connects to chess
• Any environment variables the platform maintainer needs to set
• Any known issues or limitations

A maintainer will review your PR. Feedback will be left as review comments. Address each comment and push new commits — do not force-push during review as it makes it hard to track changes.

Updating Your Game

After your game is live, updates follow the same process: branch, change, PR. A few additional rules apply:

• Increment the version field in game.json following semver — patch for bug fixes, minor for new features
• Add a new entry to the changelog array describing what changed
• Do not change your game's folder name — it is part of the public URL and changing it would break existing links

Breaking changes — anything that resets player progress or significantly alters the rules — should be noted prominently in the changelog entry and in your PR description.

Game Removal

Games can be removed in two ways:

• Voluntary: Open a PR that removes your game folder and sets a note in the PR description. The maintainer will handle the registry update.
• Involuntary: Games that violate content standards, contain malicious code, or have been abandoned and broken for more than 90 days may be removed by the maintainer without notice.

If your game is removed involuntarily, you will be notified via a GitHub issue on your PR with the reason.

SSR APIs

The platform exposes a small set of server-side utilities available to all games via import. These are provided by the platform and should not be reimplemented in your game folder.

Reading the game registry

import { getRegistry } from '@/lib/registry';

const games = await getRegistry();
// returns: string[] of registered game folder names

Reading a game manifest

import { getManifest } from '@/lib/registry';

const manifest = await getManifest('pawn-push');
// returns: parsed game.json object, or null if not found

Reading markdown content

import { getGameContent } from '@/lib/content';

const description = await getGameContent('pawn-push', 'description');
const rules = await getGameContent('pawn-push', 'rules');
// returns: rendered HTML string from the markdown file