How hexafield/catan works
Project Type & Purpose
• This project is a full-stack game application that implements a demo version of the board game Catan in an XR (extended reality) context.
• It is designed for interactive gameplay using a hex grid board, dice rolls, settlement placements, and other game mechanics.
• The README mentions a “P2P Signaling server” and “client connectivity,” so there is a networked component with a dedicated backend signaling server communicating with clients.
• The main use case is to allow players to interact in a 3D/VR/AR environment—though some planned features (like VR mode, AR tabletop mode) are pending.
File Structure for Architectural Clues
• Top-Level Files:
• server.ts: Implements the server-side (likely the signaling server for peer-to-peer connection).
• client.js, index.html, manifest.json: Entry points for the web client.
• package.json, tsconfig.json, vite.config.ts, tailwind.config.js: Indicate use of TypeScript, Vite build tooling, and Tailwind for styling.
• Directories:
• src: Contains the React (or JSX-based) application code for game screens (e.g., GamePage.tsx, main.tsx) and several game systems.
▪ Game logic is modularized into subdirectories:
• game: e.g., DiceRollSystem.tsx, GameSystem.tsx
• hexes: e.g., HexagonGridSystem.tsx (with functions and constants)
• player: PlayerSystem.tsx
• resources: ResourceSystem.tsx
• structures: A set of files dealing with structure placement, purchase, and functions.
• public: Contains static assets, including loader decoders for various 3D assets (e.g., Basis, Draco) and worker scripts used for asynchronous BVH generation and 3D computations.
• tests: Contains a dummy test, indicating initial testing setup.
• .github/workflows: CI/CD pipelines for deployment and builds.
• These components suggest a design that separates the game’s rendering/UI logic, core gameplay systems, static asset delivery and asynchronous 3D computation workers, plus a minimal backend signaling server.
Core Components
• Client Application
• UI/Presentation Layer:
▪ index.html that bootstraps client.js and further loads the React components within src (e.g., GamePage.tsx, various UI components for dice roll, settlement placements, etc.)
• Game Systems Layer:
▪ Game System (GameSystem.tsx) coordinating game flow.
▪ Hexagon Grid System (HexagonGridSystem.tsx) with its helper functions/constants.
▪ Dice Roll System (DiceRollSystem.tsx), Player System (PlayerSystem.tsx), Resource System (ResourceSystem.tsx), and Structure Systems (StructurePlacementSystem.tsx, StructurePurchaseSystem.tsx, StructureSystem.tsx). Each module handles specific game mechanics.
• Supporting Subsystems:
▪ Integration of Web Workers (located under public/workers) handling tasks like BVH generation and 3D mesh processing.
▪ Loader Decoders (in public/loader_decoders) for assets in different formats (Basis, Draco) that are used to load and decode 3D models.
• Build & Configuration:
▪ Vite configuration, Tailwind CSS integration, and TypeScript strictness impacting how the game modules are built and styled.
• Server / P2P Signaling Layer
• Server.ts acts as the signaling server facilitating P2P connectivity and game session management (e.g., initiating game rounds, dice roll synchronization, resource updates).
Relationships and Data Flow
• User interactions (e.g., dice roll, structure placement) triggering game logic changes.
• Interactions between the Game Systems and asynchronous workers (the public/workers scripts). Indicate that computationally heavy tasks (like BVH generation) are offloaded.
• A flow for static asset loading from the Public directory (both assets and WASM decoders) into the Client.
• Optionally, denote the build/deployment pipeline from the GitHub workflows as a separate process that feeds into both the client and server deployments.
Architectural Patterns & Design Principles
• Separation of concerns:
• Client side handles rendering, user interactions, and game logic modularization across several systems.
• Server side deals solely with networking and P2P connectivity.
• Worker scripts handle offloading computational tasks (e.g., 3D processing) ensuring a responsive UI.
• Use modular design – each game subsystem is represented as an independent component. Their integration points (via events, callbacks, or direct function calls) should be illustrated.
• Leverage client-driven workflows: The use of Vite, Tailwind, and Typed React (tsx) suggests modern web development practices that modularize UI and business logic.
Relevant Technologies, Frameworks & Libraries
• Vite (highlighted in configuration files)
• TypeScript and React (inferred from .tsx files)
• Tailwind CSS (as per tailwind.config.js for UI styling)
• WASM modules along with Web Workers for optimal 3D asset processing (public/loader_decoders and public/workers)
• P2P signaling possibly using WebRTC or similar mechanisms as suggested by server.ts
• Client Application: subdivided into UI Layer and Game Logic Layer.
• Game Systems modules: DiceRoll, HexagonGrid, Player, Resource, Structures.
• Asynchronous Processes: Web Workers and WASM asset loaders.
• Server (P2P/Signaling): Representing server.ts.
• Data flow among UI, game systems, asset loaders, and server.
• Communication protocols (e.g., signaling for P2P connections).
• Integration points for configuration and build pipelines (optional but useful for deployment context).