Zero Reality - 2.5D JRPG with Blockchain Integration

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.

🎮 Game Overview

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

🏗️ Project Structure

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

🚀 Getting Started

Prerequisites

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

Installation

Clone the repository

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

Install pnpm dependencies
```
pnpm install
```
Build shared packages
```
make build-shared
```
Build and run development stack
```
make dev
```

Development Commands

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

🏛️ Architecture Overview

End-to-End Integration Approach

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-Authoritative Design

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

Layered Architecture

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

📚 Documentation

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

🎯 Current Implementation Status

✅ Completed Systems

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

🔄 In Progress

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

📋 Planned Features

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

🛠️ Technology Stack

Frontend

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

Backend

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

Blockchain Integration

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

Development

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

🤝 Contributing

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

Commit Convention

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

📋 Development Guidelines

Architecture Principles

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

Common Patterns

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

🔮 Roadmap

Phase 1: Core Systems ✅

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

Phase 2: Game Systems 🔄

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

Phase 3: Multiplayer & Web3 📋

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

Phase 4: Polish & Deployment 📋

Tauri desktop app
Docker containerization
Performance optimization
Production deployment

📄 License

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

🙏 Acknowledgments

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.

Name		Name	Last commit message	Last commit date
Latest commit History 17 Commits
docs		docs
packages		packages
.gitignore		.gitignore
.nvmrc		.nvmrc
CHANGELOG.md		CHANGELOG.md
Cargo.toml		Cargo.toml
Makefile		Makefile
README.md		README.md
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml

2075/jrpg

Folders and files

Latest commit

History

Repository files navigation