guide

Instruction file imported from thinktidevibes/2D-Survival-Multiplayer-Game (.cursor/rules/guide.mdc). Copyright stays with the author.

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

Key Client Patterns

1. SpacetimeDB Connection:

   • Initialize connection in top-level component with useEffect
   • Store connection object for later use
   • Handle connection events with callbacks

2. Data Subscription:

   • Use conn.subscriptionBuilder() with SQL queries
   • Implement spatial filtering with WHERE clauses
   • Register table callbacks with conn.db.tableName.onUpdate() (camelCase)

3. Rendering Optimization:

   • Use chunk-based loading for world data
   • Implement view-distance culling
   • Use interpolation for smooth movement

Integration Patterns

When working with this codebase, observe these integration patterns:

1. Server-Client Data Flow:

   • Server is authoritative for game state
   • Client predicts actions for responsiveness
   • Server validates and reconciles conflicting actions

2. Schema Synchronization:

   • TypeScript bindings are generated from Rust schema
   • Regenerate bindings when schema changes
   • Use imported types from generated files

3. Development Workflow:

   • Build server module with spacetime build (usually done implicitly by publish)
   • Publish to local instance from server/ directory: spacetime publish vibe-survival-game
   • Generate TypeScript bindings from server/ directory: spacetime generate --lang typescript --out-dir ../client/src/generated
   • Run both publish and generate commands whenever the server schema (lib.rs) changes.
   • Run client with npm run dev (from project root)

Implementation Guidelines

When implementing new features, follow these guidelines:

1. For New Entity Types:

   • Add table definition in server schema
   • Create reducers for entity interactions
   • Implement client-side rendering component
   • Add appropriate subscriptions

2. For Game Systems:

   • Define data structures on server side
   • Implement core logic as reducers
   • Create client UI components
   • Connect through appropriate subscriptions

3. For World Features:

   • Extend terrain generation in appropriate modules
   • Ensure efficient loading/unloading based on player proximity
   • Consider performance implications

Performance Considerations

AI should prioritize these performance considerations:

1. Network Efficiency:

   • Use relevance filtering in subscriptions
   • Limit update frequency for non-critical entities
   • Batch related updates when possible

2. Rendering Optimization:

   • Implement entity culling based on view distance
   • Use appropriate data structures for spatial queries
   • Consider object pooling for frequently created entities

3. State Management:

   • Implement reconciliation for client-server state
   • Use appropriate local caching
   • Consider partial updates for large entities

Technical Constraints

AI should be aware of these technical constraints:

1. SpacetimeDB Version Compatibility:

   • Client SDK version must match server version exactly
   • Table names in SQL queries are case-sensitive
   • Generated bindings require specific import patterns

2. React Implementation:

   • Components should follow functional pattern with hooks
   • State updates must be immutable
   • SpacetimeDB connection should be initialized once

3. Server Implementation:

   • All database modifications must occur within reducers
   • Public tables are accessible to all clients
   • Identity handling is required for player authentication

This documentation should be consulted when analyzing code structure, suggesting improvements, or implementing new features in the 2D Survival Multiplayer project.