# 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:

```console
npm start
```

Open [http://localhost:4173](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:

```console
npm run build:css
```

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

```console
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](testing.md)
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:

```console
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](architecture.md) before changing game state,
  rendering, movement, combat, or feedback boundaries.
- Use the [testing guide](testing.md) for focused suites and visual QA.
- Consult the private repository guides when changing feedback data handling,
  production releases, or recovery procedures.