<div align="center">

VXLverse

Create, Play, Share: The Ultimate 3D Game & Art Gallery Platform

</div>

🌟 Welcome to VXLverse

VXLverse is a revolutionary browser-based platform that empowers creators to build, customize, and share immersive 3D voxel games and stunning virtual art galleries—no coding required. Combining intuitive design tools with powerful AI capabilities, VXLverse makes both game development and virtual art exhibition accessible to everyone while offering advanced features for experienced creators.

<div align="center">

The powerful VXLverse editor with real-time 3D rendering, scene hierarchy, and properties panel

</div>

🎮 Complete Game Creation Suite

Create immersive 3D games with our intuitive tools and powerful features:

⚔️ Dynamic Combat System

<div align="center">

Engaging combat with projectiles, health systems, and dynamic interactions

</div>

Create thrilling action gameplay with minimal setup:

• Projectile-Based Combat - Implement throwing mechanics, fireballs, and ranged attacks
• Health & Damage Systems - Configure hit points, damage values, and combat balancing
• Enemy AI Behaviors - Define patrol paths, aggression ranges, and combat strategies
• Visual Effects - Add impact animations, particle effects, and combat feedback

📜 Quest & Progression System

<div align="center">

Comprehensive quest system with objectives, rewards, and progression tracking

</div>

Build engaging gameplay loops with our flexible quest system:

• Experience-Based Rewards - Grant XP, items, or abilities upon quest completion
• Multi-Stage Quests - Create complex quest chains with branching paths
• Condition Triggers - Set up quest availability based on player level, inventory, or previous actions
• Visual Quest Markers - Guide players with intuitive quest indicators and waypoints

🤖 AI-Powered NPC Conversations

<div align="center">

Create dynamic NPCs with unique personalities using our Mistral AI integration

</div>

Bring your game world to life with intelligent NPCs powered by Mistral's Large Language Model:

• Rich Character Backstories - Simply provide character backgrounds and let the AI handle the rest
• Dynamic Memory - NPCs remember previous conversations and player choices
• Natural Language Processing - Players can interact using natural language instead of predefined options
• Persistent Conversations - All dialogues are saved to PocketBase for continuity across game sessions
• Emotion & Personality - NPCs respond with appropriate emotions based on their defined traits

🛠️ Professional-Grade Tools

🏗️ Intuitive Editor

• Scene Hierarchy Management - Organize complex game worlds with nested objects and groups
• Properties Panel - Configure every aspect of your game objects with visual controls
• Grid & Snapping System - Achieve pixel-perfect placement with customizable grid settings
• 3D Model Library - Access hundreds of pre-made assets with one-click importing
• Real-time Lighting - Set the mood with dynamic lighting, shadows, and time-of-day effects

🎨 Advanced Game Design

• Visual Scripting - Create complex game logic without writing code
• Behavior Trees - Define sophisticated AI behaviors and enemy patterns
• Physics System - Implement realistic object interactions and collision responses
• Animation Editor - Create and modify character animations with intuitive controls
• Particle Effects - Add visual flair with customizable particle systems

🧠 Cutting-Edge Technology

• Mistral AI Integration - Enterprise-grade LLM for dynamic NPC conversations
• Real-time 3D Rendering - Optimized Three.js and React Three Fiber implementation
• Efficient State Management - Zustand-powered state handling for complex game systems
• PocketBase Backend - Secure storage for models, conversations, and player data
• Progressive Web App - Install and play offline on desktop and mobile devices
• Responsive Design - Beautiful UI built with Tailwind CSS and Framer Motion

🚀 Getting Started

Prerequisites

• Node.js (v16.0.0 or higher)
• npm or yarn

Quick Start

# Clone the repository
git clone https://github.com/mpoapostolis/vxlverse-v3.git
cd vxlverse-v3

# Install dependencies
npm install

# Start the development server
npm run dev

Open your browser and navigate to http://localhost:3000

📖 Create Your First Game

1. Setting Up Your Game World

• Create a New Scene - Click the "+" button and choose a template or start from scratch
• Design Your Environment - Add terrain, buildings, and decorative elements
• Configure Lighting - Set the mood with ambient, directional, and point lights
• Add Interactive Objects - Place NPCs, items, and interactive elements

2. Implementing Game Mechanics

• Combat System - Configure projectiles, health systems, and enemy behaviors
• Quest Framework - Create objectives with experience rewards and progression
• Inventory System - Set up collectible items and equipment
• Movement Controls - Fine-tune character movement, jumping, and interactions

3. Creating Intelligent NPCs

• Write Character Backstories - Provide rich backgrounds for the AI to build upon
• Configure Dialogue Triggers - Set up interaction zones and conversation starters
• Link Quests to Dialogues - Connect conversations to quest objectives and rewards
• Test Conversations - Interact with NPCs to ensure natural dialogue flow

4. Polishing Your Game

• Playtest in Preview Mode - Experience your game as players would
• Refine Game Balance - Adjust difficulty, rewards, and progression
• Add Sound Effects & Music - Enhance immersion with audio elements
• Optimize Performance - Ensure smooth gameplay across different devices

🏗️ Technical Architecture

VXLverse employs a sophisticated component-based architecture built with React and TypeScript:

VXLverse/
├── Editor/                # Main workspace components
│   ├── ScenePanel         # Hierarchy and object management
│   ├── PropertiesPanel    # Object configuration interface
│   ├── EditorScene        # 3D rendering environment
│   └── ToolsPanel         # Creation and manipulation tools
├── Game/                  # In-game components
│   ├── GameHUD            # Pixel-art style interface
│   ├── DialogueModal      # AI-powered conversation system
│   ├── CombatSystem       # Fighting mechanics and projectiles
│   ├── QuestManager       # Quest tracking and rewards
│   └── Inventory          # Item management system
├── AI/                    # AI integration components
│   ├── MistralService     # LLM API communication layer
│   ├── ConversationManager# Dialogue history and context handling
│   └── CharacterMemory    # Persistent NPC memory system
└── Stores/                # State management
    ├── editorStore.ts     # Editor state container
    ├── gameStore.ts       # Game runtime state
    └── userStore.ts       # User preferences and authentication

The architecture follows a clean separation of concerns, with dedicated modules for editor functionality, game systems, and AI integration. State management is handled through Zustand stores, providing efficient state updates and persistence with minimal re-renders.

🤝 Contributing

We welcome contributions from developers of all skill levels! Whether you're fixing bugs, adding features, or improving documentation, your help makes VXLverse better for everyone.

1. Fork the repository
2. Create your feature branch: git checkout -b amazing-feature
3. Commit your changes: git commit -m 'Add some amazing feature'
4. Push to the branch: git push origin amazing-feature
5. Open a Pull Request

Check our Contributing Guidelines for more detailed information.

📜 License

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

🙏 Acknowledgements

• Three.js and React Three Fiber - 3D rendering engine
• Tailwind CSS - Utility-first CSS framework
• Framer Motion - Animation library
• PocketBase - Open source backend
• Mistral AI - Advanced language model for NPC conversations
• NSFWJS - Client-side content moderation
• TensorFlow.js - Machine learning framework
• Zustand - State management
• Vite - Next generation frontend tooling

🖼️ Virtual Art Gallery Platform

VXLverse now offers a powerful virtual art gallery creation system, allowing artists and curators to showcase their work in immersive 3D environments:

🎨 Gallery Creation Features

<div align="center">

Create stunning virtual art galleries with customizable layouts and lighting

</div>

• Intuitive Gallery Builder - Design beautiful 3D spaces to showcase artwork
• **Image Upload &