Getting started

The Enchanted Board is a framework-free browser application. A clean checkout can run the game without installing frontend packages or compiling source files.

Requirements

  • Node.js 22 or newer

  • A modern browser

  • Python 3.12 or newer when developing the feedback service, running the complete test suite, or building documentation

  • Python pip and venv support for documentation builds (python3-venv on Debian or Ubuntu)

  • Google Chrome only when running the optional visual QA script

Run the game

From the repository root, start the static development server:

npm start

Open http://localhost:4173, choose a game mode, and select Begin the duel. The opening flight starts after that selection and reveals the initialized board when it finishes.

Two query-string shortcuts are useful while developing:

  • http://localhost:4173/?quickplay=1 starts an Ivory-versus-computer game.

  • http://localhost:4173/?skipIntro=1 keeps the setup screen but skips the opening flight after the duel begins.

The local server deliberately serves static files only. It does not proxy /api/feedback. Feedback-service and production-operation details remain in the private repository guides.

Play and controls

  • Click or tap a piece, then choose a highlighted destination.

  • Use the arrow keys to move focus around the board and Enter or Space to select or move.

  • Press Escape to clear a selection or finish the current movement, capture duel, arrival, or closing scene.

  • Use Reveal a hint, Undo, Flip board, and New duel from the command panel.

  • Toggle 3D view, sound, on-board battles, and Swift movement at any time.

In computer mode, Undo returns to the previous human decision point. In local two-player mode, it reverses the latest move.

Make and verify a change

Stylesheets are authored in styles/ and assembled into the checked-in styles/app.css bundle. Rebuild that bundle after changing a source stylesheet:

npm run build:css

Before opening a pull request, run the complete application verification command:

npm run verify

This checks JavaScript syntax and release hygiene, verifies the generated CSS, and runs the JavaScript and Python test suites. The testing guide describes focused commands and the manual browser checklist.

For a documentation change, also create an isolated documentation environment and run the warning-as-error Sphinx build:

python3 -m venv .venv
. .venv/bin/activate
python -m pip install -r docs/requirements.txt
npm run docs:build

Where to go next

  • Read the architecture guide before changing game state, rendering, movement, combat, or feedback boundaries.

  • Use the testing guide for focused suites and visual QA.

  • Consult the private repository guides when changing feedback data handling, production releases, or recovery procedures.