Développement¶

Prérequis¶

Outil	Version	Installation
Rust	stable, avec la cible `wasm32-unknown-unknown`	`rustup target add wasm32-unknown-unknown`
`wasm-bindgen-cli`	0.2.127, identique à `wasm-bindgen` dans `Cargo.lock`	`cargo install wasm-bindgen-cli --version 0.2.127 --locked`
Node.js et npm	Node 22 ou plus	—
Docker et Compose	—	seulement pour tester l'image

Version de wasm-bindgen

Si wasm-bindgen-cli et la dépendance wasm-bindgen du Cargo.lock divergent, le module WASM ne se charge pas dans le navigateur. Après une mise à jour de la dépendance, il faut aussi mettre à jour la version dans le Dockerfile (étape wasm-builder).

Lancer en local¶

Dev (rechargement à chaud)Comme en production (un seul processus)Docker

# 1. Bindings WASM consommés par le client
#    (à refaire après toute modification de crates/orapa-core ou crates/orapa-wasm)
cd web && npm install && npm run build:wasm

# 2. Serveur de jeu, écoute sur :8080
cd .. && cargo run -p orapa-server

# 3. Client Vite, dans un autre terminal : http://localhost:5173
cd web && npm run dev

Vite relaie /ws vers ws://127.0.0.1:8080 (web/vite.config.ts). Il faut donc lancer le serveur et le client.

cd web && npm run build          # build:wasm + tsc -b + vite build, vers web/dist
cd .. && ORAPA_STATIC_DIR=web/dist cargo run -p orapa-server
# http://localhost:8080

docker compose up --build        # http://localhost:8080

Même image que la production, voir Déploiement.

Variables d'environnement du serveur¶

Variable	Défaut	Rôle
`PORT`	`8080`	Port d'écoute HTTP et WebSocket (sur `0.0.0.0`)
`ORAPA_STATIC_DIR`	`web/dist` (relatif au répertoire courant)	Dossier des fichiers statiques du client
`RUST_LOG`	filtre `info` si absente	Niveau de log `tracing` (`info`, `debug`…)

Scripts npm (`web/package.json`)¶

Script	Effet
`npm run build:wasm`	Depuis la racine : `cargo build --target wasm32-unknown-unknown --release -p orapa-wasm`, puis `wasm-bindgen … --out-dir web/src/wasm --target web --typescript`
`npm run dev`	Serveur de dev Vite (port 5173)
`npm run build`	`build:wasm`, puis `tsc -b`, puis `vite build`
`npm run lint`	`oxlint`
`npm run preview`	`vite preview`

web/src/wasm/ est généré et ignoré par git. Sans npm run build:wasm, le client ne compile pas.

Tests et qualité¶

cargo test --workspace                 # moteur, serveur (unitaires + intégration WebSocket), wasm (cible hôte)
cargo test -p orapa-core               # moteur seul, à lancer après toute modification de data/pieces.json
cargo clippy --workspace --all-targets
cd web && npx tsc -b && npx oxlint src # typecheck + lint (pas de tests côté client)

Fichier	Ce qui est couvert
`orapa-core/src/colors.rs`	Les 16 combinaisons, indépendance à l'ordre et aux doublons
`orapa-core/src/beam.rs`	Rebond sur carré et sur cathète, déviation sur hypoténuse, absorption, Diamant sans couleur, boucle fermée (`Lost`), réversibilité des trajets
`orapa-core/src/pieces.rs`	Chargement du catalogue, aires, nombre d'orientations, aire identique pour toutes les orientations
`orapa-core/src/placement.rs`	Hors grille, chevauchement, contact d'arête, coin à coin et hypoténuse autorisés, pièce inatteignable, détection de symétrie
`orapa-core/src/solution.rs`	Solution identique, différente, ou qui se chevauche
`orapa-core/src/generator.rs`	200 tirages aléatoires (avec et sans extensions), tous valides
`orapa-server/src/logic.rs`	Mort subite, victoire immédiate du second joueur, égalité, élimination, partie à 2 vies, mode aide désactivé
`orapa-server/tests/integration.rs`	Duel complet via WebSocket, reconnexion, démarrage en solo
`orapa-wasm/src/lib.rs`	Catalogue JSON, validation (plateau vide, JSON invalide), onde et sondage

Pas de CI

Le dépôt ne contient pas de pipeline d'intégration continue : les tests se lancent à la main avant de pousser. Un push sur main déclenche directement le redéploiement en production.

Démo CLI¶

cargo run -p orapa-cli -- --seed 1 --all                    # résultat des 36 ondes
cargo run -p orapa-cli -- --seed 1 --beam 7                 # une seule onde
cargo run -p orapa-cli -- --seed 1 --diamond --black --all  # avec les extensions

Option	Défaut	Rôle
`--seed <n>`	`1`	Graine du tirage aléatoire du plateau
`--beam <id>`	—	Point de tir (`A`–`R`, `1`–`18`)
`--all`	non	Les 36 ondes (prioritaire sur `--beam`)
`--diamond`	non	Ajoute le Diamant
`--black`	non	Ajoute le Corps noir

La CLI affiche le plateau tiré en ASCII (· vide, ■ carré, ◤ ◥ ◢ ◣ demi-cases, sans les couleurs), puis le résultat de chaque onde (ressort en 14, couleur Violet, signal absorbé (corps noir), onde perdue dans la mine (boucle)), mais pas le trajet. Sans --beam ni --all, elle liste les points de tir disponibles.

Modifier le catalogue de pièces¶

Modifier uniquement le tableau cells de la pièce dans data/pieces.json (forme de base, orientation 0). Les orientations sont générées par le moteur.
cargo test -p orapa-core : un test vérifie que chaque orientation a la même aire que la forme de base, ce qui attrape la plupart des erreurs de saisie.
npm run build:wasm puis redémarrer le serveur. Le catalogue est embarqué à la compilation (include_str!), dans le binaire serveur comme dans le WASM.

Le fichier règle aussi grid (dimensions) et rules.white_symmetry_forbidden.

Limites du catalogue

Les identifiants sont figés dans le code : red, yellow, blue, white1, white2 (pièces de base, PieceCatalog::base_ids), diamond et black (GameOptions::piece_ids), plus les libellés piece.* de web/src/i18n/fr.ts. Ajouter une pièce demande donc du code.
Les points de tir à lettres vont de A à R (18 lettres) : largeur + hauteur ne peut pas dépasser 18 sans modifier entry_points (et web/src/lib/points.ts).
Plusieurs tests supposent une grille 10×8 et 7 pièces.

Aide-mémoire : je modifie… je fais ensuite…¶

Je modifie	À faire ensuite
`data/pieces.json`	`cargo test -p orapa-core`, `npm run build:wasm`, redémarrer le serveur
`crates/orapa-core`	`cargo test -p orapa-core`, `npm run build:wasm`
`crates/orapa-wasm`	`npm run build:wasm`
`orapa-server/src/protocol.rs`	Reporter les changements dans `web/src/types/protocol.ts`
`entry_points` (`beam.rs`)	Reporter dans `web/src/lib/points.ts`
`mix_colors` (`colors.rs`)	Reporter dans `RESULT_MIX` (`web/src/lib/colors.ts`)
Textes de l'interface	`web/src/i18n/fr.ts`
Version de `wasm-bindgen`	`cargo install wasm-bindgen-cli --version …` en local, et la version dans le `Dockerfile`