A real-time multiplayer 2.5D JRPG built with modern web technologies, Rust backend, and blockchain integration for NFT assets. Features server-authoritative game design with client-side rendering and Web3 integration.

• Genre: 2.5D JRPG with real-time multiplayer and roguelite elements
• Art Style: Pixel art with 2.5D rendering and isometric maps
• Platform: Web browsers (desktop and mobile), Tauri desktop app (planned)
• Architecture: Server-authoritative client-server with WebSocket communication
• Backend: Rust with Game Entity System (GES) and ECS architecture
• Frontend: React with Canvas API, WebGL rendering (planned)
• Blockchain: Substrate (Ink!) and EVM-compatible chains for NFT assets

game/
├── docs/                          # Project documentation
│   ├── 001-initial-project-specification.md
│   ├── 002-blockchain-entity-system-architecture.md
│   ├── 003-game-design-document.md
│   ├── 004-task-registry.md
│   ├── 005-data-structures-and-architecture.md
│   └── 006-quick-reference-card.md
├── packages/                      # Monorepo packages
│   ├── client/                   # React frontend application
│   ├── server/                   # Rust backend with GES
│   ├── shared-types/             # TypeScript type definitions
│   ├── shared-logic/             # Rust game logic modules
│   └── assets/                   # Game assets and resources
├── tools/                        # Development tools and scripts
├── Makefile                      # Build and development commands
├── package.json                  # Root package.json for pnpm monorepo
├── Cargo.toml                    # Root Cargo.toml for Rust workspace
└── README.md

• Node.js: 18.0.0 or higher
• pnpm: 8.0.0 or higher (we use pnpm instead of npm)
• Rust: Latest stable version
• Git: For version control

1. Clone the repository

   git clone https://github.com/yourusername/game-2.5d-jrpg.git
   cd game-2.5d-jrpg

2. Install pnpm dependencies

   pnpm install

3. Build shared packages

   make build-shared

4. Build and run development stack

   make dev

• Build all packages: make build
• Build client only: make build-client
• Build server only: make build-server
• Start development: make dev (runs both client and server)
• Check status: make status
• Clean builds: make clean

Blockchain Layer (Web3)
├── NFT Assets (Ink!/Solidity)
├── IPFS Content Storage
└── Account Abstraction
    ↓
Server Layer (Rust)
├── Game Entity System (GES)
├── AI Movement & Behavior
├── Item Spawning & Management
├── Combat & Interaction Systems
└── Blockchain Interface
    ↓
Client Layer (React)
├── Derived Game State
├── Canvas Rendering (2.5D)
├── Fog of War System
├── Input Handling
└── WebSocket Sync

• Server: Maintains authoritative game state and validates all actions
• Client: Derives local state from server via WebSocket synchronization
• Consistency: All clients see identical game world
• Anti-Cheat: Server validates critical actions before applying
• Web3 Integration: Server manages NFT asset state and blockchain interactions

1. ECS Layer: Generic entity management with components
2. Game Logic Layer: Game-specific behavior and state
3. UI Layer: React components and Canvas rendering
4. Sync Layer: WebSocket communication with server

• Initial Project Specification: Project overview and technical architecture
• Blockchain Architecture: Web3 integration and NFT asset system
• Game Design Document: Game mechanics, features, and design vision
• Task Registry: Development tasks and progress tracking
• Data Structures & Architecture: Single source of truth for system design
• Quick Reference Card: Common patterns and pitfalls to avoid

• Monorepo Structure: pnpm workspaces + Cargo workspace
• Type System: Shared TypeScript types and Rust modules
• Client Foundation: React app with Canvas rendering
• Game Loop: 60 FPS game loop with input handling
• Camera System: Zoom, pan, and player following
• Fog of War: Dual-radius visibility and exploration system
• AI Movement: Autonomous NPC movement with patrol patterns
• Item Spawning: Dynamic consumables and collectibles
• Stamina System: Movement costs and regeneration

• Server Integration: WebSocket communication setup
• State Synchronization: Client-server state sync
• Blockchain Interface: NFT asset integration

• Multiplayer Foundation: Player synchronization
• Combat System: Turn-based and real-time combat
• Quest System: Roguelite quest generation
• Tauri Desktop App: Native desktop wrapper
• Docker Containerization: Full stack deployment

• Framework: React 18 with TypeScript
• Graphics: Canvas API (2.5D rendering), WebGL (planned)
• State Management: Client-side derived state with server sync
• Real-time: WebSocket communication
• Build Tool: Vite with pnpm

• Language: Rust with latest stable
• Architecture: Game Entity System (GES) with ECS patterns
• Networking: WebSocket server with real-time updates
• Game Systems: AI, combat, item management, blockchain interface

• Substrate: Ink! smart contracts for NFT assets
• EVM: Solidity contracts for cross-chain compatibility
• IPFS: Decentralized content storage
• Account Abstraction: Simplified Web3 user experience

• Monorepo: pnpm workspaces + Cargo workspace
• Git Workflow: Conventional commits with commitlint
• Build System: Makefile with parallel execution
• Code Quality: TypeScript strict mode, Rust clippy

1. Follow the conventional commit format (enforced by commitlint)
2. Update documentation for any changes
3. Ensure all tests pass
4. Follow the DRY principle and layered architecture
5. Maintain proper separation of concerns
6. Use the quick reference card for common patterns

type(scope): description

feat: add new feature
fix: bug fix
docs: documentation changes
style: formatting changes
refactor: code refactoring
test: adding tests
chore: maintenance tasks

• Single Source of Truth: Server maintains authoritative state
• Layered Separation: ECS → Game Logic → UI layers
• Reference-Based Relationships: Game objects reference ECS entities
• Component Composition: Entities composed of multiple components

• Entity Creation: Always create both Entity + Game Object
• State Updates: Use update functions, never direct modification
• Collection Management: Keep all related collections in sync
• Server Sync: Client state derived from server, not self-initialized

• Monorepo setup and package structure
• Type system and shared modules
• Client foundation and game loop
• Basic rendering and camera system

• Fog of War and exploration
• AI movement and behavior
• Item spawning and management
• Stamina and movement systems
• Server integration and WebSocket sync

• Player synchronization
• Combat and interaction systems
• Blockchain interface implementation
• NFT asset integration

• Tauri desktop app
• Docker containerization
• Performance optimization
• Production deployment

This project is licensed under the MIT License - see the LICENSE file for details.

• Zero Reality Team: Core development and architecture
• JRPG Community: Game design inspiration
• Pixel Art Community: Aesthetic guidance
• Rust & Web3 Communities: Technical expertise

For detailed development information, see the docs folder. For current task status, see Task Registry.