Sovereign_Lands

# 🏰 Sovereign Lands — 3D Third-Person Open-World Kingdom (GTA-Style Web3 Sandbox)

> *"The kingdom decided this, not a server."*

### 💡 Elevator Pitch
Sovereign Lands is a 100% in-browser 3D third-person open-world sandbox combining GTA-style over-the-shoulder locomotion and physics with on-chain spatial land deeds (ERC-721) on Polygon Amoy, real-time holographic construction, and Bring-Your-Own-AI (BYOAI) autonomous NPCs. No 60GB downloads, no centralized game servers, and zero cloud GPU bottlenecks—running at 60 FPS in under 2 seconds.

---

### ❓ The Problem It Solves
1. **Web2 Gaming Lock-In**: Traditional games lock your items and land on private corporate servers. If the studio bans your account or turns off the server, your investments vanish.
2. **Web3 Metaverse Friction**: Legacy metaverses often suffer from high browser latency, clunky point-and-click movement, and lifeless "ghost towns" with stationary, pre-scripted NPCs.
3. **Studio AI Costs**: Hosting real-time LLM game characters on centralized cloud GPUs creates unsustainable server bills for developers.

---

### ⚔️ What It Does & Key Features

- **🎮 GTA-Style 3D Locomotion & Physics**: Smooth over-the-shoulder third-person camera with spring-arm raycast collision, fixed 60Hz Rapier 3D physics, sprinting, and jumping across a continuous 500m × 500m dual-biome realm (Northern Taiga vs. Southern Plains).
- **📜 True On-Chain Spatial Land Deeds (ERC-721)**: Every plot of land is an on-chain NFT on Polygon Amoy storing continuous 3D Cartesian coordinates (`minX`, `minZ`, `maxX`, `maxZ`). The smart contract dynamically indexes territory and assigns realm allegiance based on world coordinates.
- **🏗️ Real-Time Holographic Construction**: Tap `[C]` to project a floating 3D holographic wireframe that snaps to terrain elevation and glows green within your parcel bounds (or red if obstructed) to deploy Farmsteads, Guard Towers, Stone Walls, and Castle Keeps.
- **🌾 Autonomous Yield & Realm Tithes**: Farmsteads passively accrue gold over time based on block timestamps. Players harvest net gold while an automated tax tithe streams directly into the kingdom treasury.
- **🏛️ Citadel DAO & Deterministic Warfare**: Landowners gather at the Citadel War Table to vote on realm tax rates, treasury distribution, and war declarations with parcel-weighted votes. Battles resolve 100% on-chain by pitting attacker military strength against defender fortifications to plunder enemy treasuries.
- **🤖 Bring-Your-Own-AI (BYOAI) Autonomous NPCs**: Roaming medieval inhabitants possess spatial awareness and dialogue memory powered entirely client-side using the player's personal LLM keys (Gemini, OpenAI, Claude, or local Ollama)—ensuring 100% data privacy and zero server GPU bills.

---

### 🛠️ How We Built It (Tech Stack)
- **Frontend / 3D Engine**: Next.js 14 (App Router), Three.js, React Three Fiber (R3F), `@react-three/rapier` (Fixed 60Hz Physics), Tailwind CSS, Framer Motion.
- **Smart Contracts & Blockchain**: Gas-optimized Solidity (`0.8.20`) built with Foundry (`forge`), deployed on **Polygon Amoy Testnet (Chain ID 80002)** and Base Sepolia.
- **Web3 Client Integration**: Wagmi v2, Viem 2.13.
- **Autonomous AI Engine**: Client-side BYOAI architecture with encrypted `localStorage` KeyVault supporting Google Gemini 1.5, OpenAI GPT-4o, Anthropic Claude 3.5, and local Ollama (`localhost:11434`).

---

### 🏆 What We’re Proud Of (Built in 12 Hours!)
- Engineered a **zero-backend, serverless architecture** where the browser handles rendering and physics, while smart contracts act as the decentralized, tamper-proof world backend.
- Designed an on-chain 3D Axis-Aligned Bounding Box (AABB) spatial query engine that lets WebGL clients stream nearby parcels and structures in real-time.
- Delivered a buttery-smooth 60 FPS open-world experience with an interactive radar mini-map, floating holographic build preview, and full Web3 HUD.