guide

2D Survival Multiplayer Architecture Guidelines

This rules file specifies the architecture, patterns, and conventions for the Vibe Coding 2D Survival Multiplayer project. AI assistants should use this information to understand the codebase structure and make appropriate recommendations.

Core Architecture

The project implements a client-server architecture with these primary components:

1. Backend: SpacetimeDB module written in Rust (server/) for game logic, state management, and data persistence
2. Frontend: React/TypeScript client (client/) for rendering, input handling, and user interface
3. Communication Layer: SpacetimeDB for real-time synchronization between clients and server

Server Architecture

The backend is organized into these logical components:

• Schema Definitions: Tables defined in server/lib.rs with #[spacetimedb::table] attributes
• Game Logic: Reducer functions (#[spacetimedb::reducer]) implementing core gameplay mechanics
• Module Organization: Functionality separated into domain-specific files (e.g., environment.rs, inventory_management.rs)

Key Server Patterns

1. Table Schema Convention:

   • Use snake_case for table names (name = "player")
   • Mark tables as public when client access is required
   • Use Identity type for player identification
   • Implement Clone for all table structures

2. Reducer Implementation:

   • Use #[spacetimedb::reducer] and appropriate return types
   • Implement core game logic in separate modules
   • Handle identity connection/disconnection explicitly
   • Use ctx.db to access database tables

3. Database Access Pattern:

   • Access tables via ctx.db.table_name()
   • Use .identity().find(id), .identity().update(data), etc. for operations
   • Handle errors with Result<(), String> return types

Client Architecture

The client follows these organizational principles:

• Core Components: Main game loop in App.tsx, rendering in GameScene.tsx
• Component Structure: Character system in Player.tsx, UI in PlayerUI.tsx
• State Management: React hooks for local state, SpacetimeDB subscriptions for shared state