Skip to content

claude.md

Latest commit

 

History

History
71 lines (57 loc) · 6.2 KB

claude.md

File metadata and controls

71 lines (57 loc) · 6.2 KB
Raw

XChess Deep Architecture & Structure Map

Welcome. This is the comprehensive, deep-dive architectural map of XChess. Use this document as your source of truth for debugging, extending features, or understanding state flow.

1. Core Paradigm & Data Flow

XChess uses a strict State vs. Presentation separation.

  • State is exclusively owned by ChessEngine.js (a pure JS class). It holds the logical 8x8 grid.
  • Presentation is owned by Phaser 3 (GameScene.js and its managers). It maintains a parallel 8x8 grid of graphical sprites (pieceSprites).
  • Communication: The UI/Input triggers methods on ChessEngine. GameScene then reads the result and orchestrates the visual updates (animations, FX, piece destruction).

2. Directory & File Breakdown

Root Directory

  • main.js: The absolute entry point. Initializes the ChessEngine singleton and the Phaser Game instance (new Phaser.Game(config)). Passes the engine to GameScene via the scene.start data payload. Also manages the global light/dark theme toggle (theme-toggle DOM element).
  • style.css: The sole stylesheet controlling all HTML UI overlays, the promotion modal, HUD, and the dark/light mode CSS variables.

/src/core/ (Game Logic)

  • ChessEngine.js:
    • State: Maintains this.board (8x8 array of {type, color, hasMoved, isGhost, originalPiece}), this.turn ('white'|'black'), this.moveHistory (for undos), and this.clocks.
    • Responsibilities: Validates moves (isValidMove), calculates check/checkmate (isInCheck, isCheckmate), executes moves (movePiece, undoMove), and manages time (updateClock).
    • Dependencies: Imports and utilizes XtraRuleRegistry to evaluate non-standard moves (Xtra rules).

/src/rules/ (Xtra Abilities)

Implements a Strategy Pattern. Each rule evaluates if a special move is valid and computes collateral damage.

  • XtraRuleRegistry.js: Master registry. Toggled via the UI. When ChessEngine validates a move, it queries the registry to see if any active rule allows it.
  • KnightTrampleRule.js: Allows Knights to jump over an enemy and kill it en route to the destination.
  • RookExplosiveLandingRule.js: Rook destroys all pieces (except kings/itself) in a 3x3 radius upon landing.
  • QueenSirensCallRule.js: Queen pulls an enemy piece into an adjacent square and destroys it without moving.
  • BishopRicochetRule.js: Bishop bounces off the board edges to change trajectory.
  • KingSwapperRule.js: King swaps places with an allied piece instead of moving normally.
  • PawnStraightShooterRule.js: Pawn captures by shooting straight ahead (2 tiles) instead of diagonally.

/src/scene/ (Phaser Rendering & Orchestration)

  • GameScene.js: The Controller. At ~250 lines, it avoids being a "God Object".
    • Flow: Listens to input -> queries engine.isValidMove -> moves the physical sprite -> checks for captures -> plays animations -> updates turns.
    • Delegation: Instantiates and delegates strictly to renderer, indicator, fx, checkVfx, ui, and promo.
  • BoardRenderer.js:
    • State: Maintains this.pieceSprites (8x8 array of Phaser Graphics).
    • Responsibilities: Draws the dark/light checkerboard tiles. Handles pointer events (click to select, click to move) and dispatches them back to GameScene.
  • MoveIndicator.js: Given a selected piece, queries the engine for valid moves and draws graphical overlays (dots for empty squares, red corners for captures, AoE boxes, ricochet path lines).
  • FXManager.js: The VFX system. Contains reusable particle emitters (purpleBurst, redBurst, cyanSpark, goldFlare). Also houses complex asynchronous cinematic functions (playExplosiveFX, playTrampleFX, playSirensCallFX, playSwapFX) utilizing timelines and tweens. Note: Camera shakes are limited ONLY to playExplosiveFX.
  • CheckVisuals.js: Draws the pulsing red tile under a King in check, and the dashed red threat-line from the attacking piece to the King.

/src/pieces/ (Graphics & Animation)

  • PieceFactory.js: Procedurally generates the vector shapes for pieces (Pawn, Rook, Knight, Bishop, Queen, King) using Phaser primitive paths (no PNGs/SVGs used). Returns a nested Container with an infinite floating/hovering tween.
  • CaptureAnimations.js: Defines the specific death animations when pieces are killed normally (e.g., swords slashing for Knight, lightning for Queen, crumbling for Rook).
  • Pieces.js: Stores static constants like premium adult dark/light mode hex colors and stroke widths.

/src/ui/ (DOM / HTML HUD)

  • UIManager.js: Bridges Phaser and the HTML DOM.
    • Generates the Xtra Rules toggle cards (#rules-container).
    • Updates the turn text and timer clocks.
    • Manages the Undo button (only visible if Bot ELO < 500).
    • Handles the Music toggle button (mutes both HTML Audio and Phaser Web Audio).
    • Displays the Game Over toast.
  • PromotionModal.js: Controls the hidden HTML modal #promotion-modal. When a pawn reaches the back rank, this pauses the game, awaits a user click (Q, R, B, N), and resolves the promotion in both the ChessEngine and the Phaser BoardRenderer.

/src/audio/ (Sound System)

  • SoundFX.js: A procedural Web Audio API synthesizer. Generates dynamic sound waves for moves (thud), captures (clash), checks (alarm), and errors (buzz), ensuring zero external asset loading time.

/src/ai/ (Single Player Bot)

  • Bot.js: Evaluates board state. Implements Minimax with Alpha-Beta pruning. Reads the #elo-select DOM element to determine search depth (intelligence) and randomness (blunders).

3. Important Implementation Details & Rules

  • Coordinates: The board uses (row, col) formatting universally. Row 0 is the top (Black's back rank), Row 7 is the bottom (White's back rank).
  • DOM IDs: Never change HTML IDs without updating the corresponding class (e.g., UIManager relies on #music-toggle, #undo-btn, #elo-select).
  • Dependencies: Never introduce circular dependencies. Managers (FXManager, BoardRenderer, etc.) should only communicate up to GameScene, never to each other directly. GameScene passes required references (like pieceSprites) as arguments.