Setup local

De zéro à pnpm dev en moins de cinq minutes.

Prérequis

• Node.js ≥ 22 (testé sur 22 et 24)
• pnpm ≥ 9.15 (activé via corepack)
• Git
• Un navigateur moderne (Chrome, Firefox, Safari)

Premier lancement

# Cloner le repo
git clone https://git.beben0.com/benjamin.henri/pixel-plaza.git
cd pixel-plaza

# Activer pnpm via corepack (si pas déjà fait)
corepack enable pnpm
corepack prepare pnpm@9.15.0 --activate

# Installer les dépendances du workspace
pnpm install

# Lancer le client + le serveur en parallèle
pnpm dev

Par défaut :

• Le client Vite est sur http://localhost:5173
• Le serveur Colyseus écoute sur le port 2567

Ouvre http://localhost:5173 dans deux onglets pour voir deux avatars se rencontrer dans le lobby (c'est le test manuel le plus rapide pour vérifier que tout marche).

Commandes utiles

Commande	Effet
pnpm dev	Lance client + serveur en parallèle
pnpm dev:client	Lance uniquement le client
pnpm dev:server	Lance uniquement le serveur
pnpm test	Lance les tests (vitest) sur tous les packages
pnpm typecheck	Vérifie les types TS sur tout le workspace
pnpm lint	ESLint sur tout le workspace
pnpm build	Build de production du client
pnpm e2e	Tests end-to-end (Playwright)
pnpm docs:dev	Lance le serveur Docusaurus de cette doc (apps/docs)
pnpm docs:build	Construit le site Docusaurus statique

Structure du monorepo

pixel-plaza/
├── client/        PixiJS 8 + Vite (rendu, UI, PWA)
├── server/        Colyseus (temps réel autoritatif)
├── shared/        Logique pure (grille iso, A*, protocole)
├── e2e/           Tests Playwright
├── tools/         Outils internes (MCP worlds, etc.)
├── deploy/        Stack Swarm pour la prod
├── docs/          Documentation de design (markdown, source de vérité)
└── apps/
    └── docs/      ← ce site Docusaurus

Le principe d'intention

Toute interaction client → serveur passe par une intention :

// Le client envoie
client.send('move', { x: 4, y: 7 });
client.send('chat', { text: 'salut' });

// Le serveur valide, simule, et réplique

Les intentions sont définies dans shared/src/protocol.ts. Le serveur valide chaque intention avant de l'appliquer à l'état de la room. C'est le principe anti-triche fondateur du projet.

Problèmes fréquents

• Port 2567 déjà pris : change PORT dans l'environnement du serveur
• WebSocket ne se connecte pas : vérifie que client et serveur tournent ensemble (pnpm dev, pas l'un sans l'autre)
• pnpm install échoue : supprime node_modules et relance, ou utilise pnpm install --frozen-lockfile
• Erreurs de type après git pull : lance pnpm install (de nouvelles deps ont pu être ajoutées)
• Windows + npm bloqué : le projet utilise pnpm via corepack, pas npm. Utilise corepack pnpm@9.15.0 ... si pnpm n'est pas sur le PATH

Pour aller plus loin : Architecture, Déploiement.