---
title: Grid Royale
emoji: ⚔️
colorFrom: red
colorTo: purple
sdk: docker
app_port: 8000
pinned: false
tags:
  - "track:wood"
  - "sponsor:modal"
  - "achievement:offbrand"
---

## Team
- [LokeshReddy001](https://huggingface.co/LokeshReddy001)
- [suchith-koduru](https://huggingface.co/suchith-koduru)

# ⚔️ Grid Royale — AI Spectator Battle Royale Arena

**Grid Royale** is a premium, esports-themed spectator dashboard and 3D simulation where 8 autonomous AI agents (powered by small LLMs) fight for survival on a grid board.

This project is built and submitted as part of the Hugging Face × Gradio **Build Small Hackathon** (June 2026).

---

## 🔗 Submission Details
*   **Live Space URL**: [https://build-small-hackathon-grid-royale.hf.space](https://build-small-hackathon-grid-royale.hf.space)
*   **Gradio Panel**: [https://build-small-hackathon-grid-royale.hf.space/gradio/](https://build-small-hackathon-grid-royale.hf.space/gradio/)
*   **Demo Video:** [https://youtu.be/rcZP8uo5N8Q](https://youtu.be/rcZP8uo5N8Q)
*   **Social Post:** [https://x.com/suchith86342898/status/2066597779842138274](https://x.com/suchith86342898/status/2066597779842138274)

---

## 🧠 Core Concept
Grid Royale is a spectator-first battle royale arena. You configure the grid size, chest counts, game turn limits, and **customize individual agent system prompts** (e.g., teaching them specific behaviors, aggression levels, or defensive strategies) right from the lobby UI. Once deployed, the agents make autonomous decisions (observe, move, attack, dash, shield, heal) on every turn using their LLM brain.

---

## 🛠️ Tech Stack & Model Size
*   **Front-End UI**: Dynamic, dark cyberpunk spectator dashboard styled with vanilla CSS glassmorphism and animated with Three.js (WebGL) for smooth, premium 3D graphics.
*   **Back-End API**: FastAPI and Uvicorn server, providing JSON endpoints for game startup, state polling, and turning actions.
*   **LLM Inference**: Powered by the **google/gemma-4-26B-A4B-it** open-weight model (26B parameters, fitting strictly under the hackathon's ≤32B cap).
*   **Compute Platform**: Served serverless on **Modal** (`modal_vllm.py`) for ultra-low latency, scalable GPU inference.

---

## 🏆 Hackathon Tracks & Badges Target
By deploying this Space, we are entering the following categories:
*   **`track:wood` (Thousand Token Wood)**: A whimsical, gamified, and highly visual spectator battle royale.
*   **`sponsor:modal` (Best Use of Modal)**: Uses the serverless Modal platform to run the gemma-4-26B-A4B-it model for agent decision-making.
*   **`achievement:offbrand` (Off-Brand UI)**: Features a fully custom HTML/Three.js WebGL dashboard, bypassing the stock Gradio component UI to look like a real esports broadcast.

---

## 🚀 How to Run Locally

### 1. Set Up Environment Variables
Ensure you have the Hugging Face/OpenAI credentials set in your terminal:
```bash
export OPENAI_API_KEY="your-key-here"
export OPENAI_API_BASE="your-modal-endpoint-here"
```

### 2. Install Dependencies
```bash
pip install -r requirements.txt
```

### 3. Launch App
```bash
python main.py
```
Open [http://localhost:8000](http://localhost:8000) in your browser.