https://github.com/ali-haggag7/logic-arena
⚔️ Logic Arena — Competitive real-time robot battle simulator. Program your robot using AliScript, a custom scripting language, and fight in 3D arenas. Built with Next.js, NestJS, and React Three Fiber.
https://github.com/ali-haggag7/logic-arena
game monorepo nestjs nextjs pnpm programming-game react-three-fiber robotics typescript websocket
Last synced: about 1 month ago
JSON representation
⚔️ Logic Arena — Competitive real-time robot battle simulator. Program your robot using AliScript, a custom scripting language, and fight in 3D arenas. Built with Next.js, NestJS, and React Three Fiber.
- Host: GitHub
- URL: https://github.com/ali-haggag7/logic-arena
- Owner: Ali-Haggag7
- Created: 2026-04-05T14:58:28.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-06-04T21:01:24.000Z (about 1 month ago)
- Last Synced: 2026-06-04T23:03:10.854Z (about 1 month ago)
- Topics: game, monorepo, nestjs, nextjs, pnpm, programming-game, react-three-fiber, robotics, typescript, websocket
- Language: TypeScript
- Homepage: https://logicarena.dev
- Size: 10.4 MB
- Stars: 5
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
```
██╗ ██████╗ ██████╗ ██╗ ██████╗ █████╗ ██████╗ ███████╗███╗ ██╗ █████╗
██║ ██╔═══██╗██╔════╝ ██║██╔════╝ ██╔══██╗██╔══██╗██╔════╝████╗ ██║██╔══██╗
██║ ██║ ██║██║ ███╗██║██║ ███████║██████╔╝█████╗ ██╔██╗ ██║███████║
██║ ██║ ██║██║ ██║██║██║ ██╔══██║██╔══██╗██╔══╝ ██║╚██╗██║██╔══██║
███████╗╚██████╔╝╚██████╔╝██║╚██████╗ ██║ ██║██║ ██║███████╗██║ ╚████║██║ ██║
╚══════╝ ╚═════╝ ╚═════╝ ╚═╝ ╚═════╝ ╚═╝ ╚═╝╚═╝ ╚═╝╚══════╝╚═╝ ╚═══╝╚═╝ ╚═╝
```
**v3.4.0 | Program your robot. Outsmart your opponent. Dominate the arena.**
[](https://www.typescriptlang.org/)
[](https://nextjs.org/)
[](https://nestjs.com/)
[](https://threejs.org/)
[](https://www.prisma.io/)
[](https://socket.io/)
[](https://logicarena.dev)
[](https://www.docker.com/)
[](https://logicarena.dev)
[**Live Demo (v3.4.0)**](https://logicarena.dev) · [**Documentation**](#project-documentation) · [**Report Bug**](https://github.com/Ali-Haggag7/logic-arena/issues)
---
## What is Logic Arena?
Logic Arena is a **competitive coding platform** where developers write scripts in **AliScript** — a custom domain-specific language — to control autonomous robots that battle in a physics-driven 3D arena. Think LeetCode meets StarCraft.
> *"The best robot isn't the fastest — it's the most intelligent."*
Unlike traditional games, **you don't play Logic Arena with a keyboard or a gamepad**. You program your robot's behavior before the match, and watch your logic execute in real-time against opponents. Every win is a proof of your algorithmic thinking.
---
## ✨ Core Features
### 🤖 AliScript v3 — Custom Combat Language
Write robot behavior scripts using Logic Arena's custom language. Supports **Dictionaries, State Machines, Dot Notation**, advanced sensory arrays, and **Swarm Intelligence** via a secure broadcast protocol. Strict server-side execution sandboxing limits script size, logic timeouts (TLE quotas), whitelisted commands, and applies execution rate limiting. Mobile players can use the intuitive **Block Editor** to drag and drop logic instead of typing code.
### ⚡ Real-Time Physics, FOV, and Super Powers
Features vector-based physics, collision detection, and projectile simulations running at 20 ticks/second. Robots possess an FOV (Field of View) and SCAN system tracking 15-degree rotation behavior. Equip **Tactical Super Powers** like SHIELD, CLOAK, DASH, TELEPORT, MINE, or TAUNT to turn the tide. All tactical choices consume points through a robust Energy & STASIS system.
### 🎮 3D Arena Renderer & Garage
The battle arena is rendered in **Three.js / React Three Fiber** — a full 3D environment with dynamic lighting, obstacle geometry, AAA robot meshes, and particle effects synchronized via **Socket.io**. Unlock and equip unique custom robot chassis models in the **Garage**.
### 💼 Economy & Black Market
Earn progression through battles and campaigns, and spend your currency in the **Black Market (Vault)** to unlock custom paints, premium tracer rounds, and elite chassis models. Equip items using a high-fidelity 3D interactive viewer.
### 🏆 Global Leaderboard & Spectator Mode
Watch top-tier players clash in real time. The **Spectator Mode** features a zero-payload overhead architecture allowing users to securely "watch" live matches directly from the Global Leaderboard, complete with live viewer counts.
### 🌍 Diverse Game Modes
- **COMBAT**: The classic deathmatch (1v1, FFA).
- **CAPTURE**: Area control mechanics for tactical positioning.
- **SURVIVAL**: Endless waves of obstacles and NPC enemies.
- **RACING**: Waypoint checkpoint navigation.
- **CAMPAIGN**: Algorithmic Warfare challenges against pre-programmed boss bots.
### 🛡️ Enterprise-Grade Security
Built with a 4-Layer security architecture:
1. **Perimeter:** HttpOnly Cookies, Redis global & route-specific rate limiting (300 req/min for Admin, 60 req/min for Public).
2. **Database:** Prisma ORM payload protection and sanitization.
3. **Execution:** AliScript AST Sandbox hardening & memory TLE quotas.
4. **Frontend:** React XSS DOM protection.
### 📱 PWA Support & Multi-Theme System
Toggle between Cyberpunk, Light, and Obsidian Ember themes. Fully Progressive Web App support ensures it's installable locally with offline pages, safe-area mapping, and a frictionless mobile-first dashboard experience featuring an exclusive Drag-and-Drop Block IDE.
### 📊 Admin Command Center
A comprehensive dashboard featuring live KPI cards, data tables, memory gauges, and charts for User and Match analytics, alongside a full Community Feedback workflow hub.
---
## 🏗️ Architecture
Logic Arena is a **pnpm monorepo** with distinct decoupled packages:
```text
logic-arena/
├── apps/
│ ├── client/ # Next.js 16 — Frontend (App Router, PWA)
│ └── server/ # NestJS 11 — Backend API + WebSocket
└── packages/
├── engine/ # Shared Game Engine (TypeScript, 20 TPS Physics)
└── logic-parser/ # AST Parser & AliScript Evaluator + Block Compiler
```
### Data Flow
```text
[Player writes AliScript v3 (Text or Blocks)]
↓
[Client sends script via API payload]
↓
[Server parses & evaluates AST securely in Sandbox]
↓
[Game Engine: physics tick every 50ms (20 ticks/sec)]
↓
[State delta broadcast to Match Room + Spectators]
↓
[React Three Fiber renders the frame using Interpolation]
↓
[Snapshot saved to database / Redis every tick]
```
### Tech Stack
| Layer | Technology |
|-------|-----------|
| Frontend | Next.js 16, React Three Fiber, Framer Motion, TailwindCSS, @dnd-kit |
| Backend | NestJS 11, Socket.io, JWT Auth, Cloudinary (Avatars), Nodemailer |
| Production / Scaling | Docker + Nginx, Redis (Upstash) for presence + rate limiting |
| Packages / Engine | Custom typescript physics engine, AST logic-parser |
| Database | PostgreSQL + Prisma ORM |
| PWA Integration | Service Worker, webmanifest |
| Monorepo | pnpm workspaces |
---
## 🚀 Getting Started
### Prerequisites
- Node.js 18+
- pnpm 8+
- PostgreSQL database
- Redis instance
### Installation
```bash
# Clone the repo
git clone https://github.com/Ali-Haggag7/logic-arena.git
cd logic-arena
# Install all dependencies
pnpm install
# Set up environment variables
cp apps/server/.env.example apps/server/.env
# Fill in DATABASE_URL, DIRECT_URL, JWT_SECRET, REDIS_URL, CLOUDINARY keys
```
### Database & Redis Setup
```bash
cd apps/server
npx prisma db push
npx prisma generate
# Ensure your Redis instance is ready and accessible based on your REDIS_URL
```
### Running the Project
```bash
# Start the full stack development environment synchronously
pnpm run dev:all
```
Open [http://localhost:3000](http://localhost:3000) — register an account and enter the arena.
---
## 🎮 How to Play
1. **Register** an account and log in.
2. Go to **Lobby** and challenge an opponent or join the **Campaign**.
3. Open the **Script Console** inside the arena (use the Block Editor on mobile!).
4. Write your AliScript strategy:
```text
IF GET_DISTANCE(ENEMY) < 400
FIRE
END
MOVE_FAST
```
5. Hit **EXECUTE** — your robot follows your logic in real-time.
6. Check the **Leaderboard** to track your global ranking and combat analytics.
---
## 📜 AliScript v3 Reference
| Category | Commands / Operators |
|----------|-------------|
| **Movement** | `MOVE`, `MOVE_FAST`, `BACKUP`, `STOP`, `PATHFIND` |
| **Actions** | `FIRE`, `BURST_FIRE`, `SCAN`, `WAIT` |
| **Abilities**| `USE_SHIELD`, `USE_CLOAK`, `USE_DASH`, `USE_TELEPORT`, `USE_MINE`, `USE_TAUNT` |
| **Variables/Data** | `SET`, Dictionaries (`state.mode = "attack"`), Arrays |
| **Control Flow** | `IF` / `ELSE` / `END`, `WHILE` / `DO` / `END`, `FOR` |
| **Logic/Operators** | `AND`, `OR`, `NOT`, `!=`, `<=`, `>=`, parentheses grouping |
| **Sensing** | `GET_DISTANCE()`, `GET_HEALTH()`, `GET_ENERGY()`, `RAYCAST()` |
| **Functions** | `FUNCTION`, `CALL` |
| **Swarm/Comms** | `BROADCAST`, `RECEIVE` |
---
## 📁 Project Documentation
| Document | Description |
|----------|-------------|
| [System Architecture](./docs/system-architecture.md) | Data flow, backend services, security model |
| [Script Sandboxing](./docs/script-sandboxing.md) | Server-side AST script isolation & TLE quotas |
| [ERD Diagram](./docs/erd-diagram.md) | Full PostgreSQL database schema |
| [Game Rules](./docs/game-rules.md) | Physics, combat, abilities, modes, Energy system |
| [Folder Structure](./docs/folder-structure.md) | Monorepo layout and architectural conventions |
| [AliScript Language](./docs/aliscript-language.md) | Complete language syntax and reference guide |
| [Rotation System Guide](./docs/rotation-system-guide.md) | Deep dive into robot FOV and scanner mechanics |
---
## 🗺️ Roadmap Progress
- [x] Custom AliScript language engine (v3)
- [x] Real-time multiplayer with Socket.io
- [x] 3D arena renderer (Three.js / R3F)
- [x] OAuth + JWT authentication system
- [x] Match history, Radar charts & Combat Analytics
- [x] Match replay system (2D Canvas)
- [x] Tournament bracket system
- [x] Dictionaries, Arrays, State Machines & Functions
- [x] Swarm Intelligence (Broadcast protocol)
- [x] Black Market & Economy System
- [x] Robot Garage (Custom AAA 3D Models)
- [x] Docker + Redis for production scale
- [x] Live Spectator Mode & Viewer counts
- [x] PWA support & Mobile-first Block Editor dashboard
- [x] LeetCode-style Campaign Mode
- [x] Dynamic Game Modes (RACING, CAPTURE, SURVIVAL)
- [x] Tactical Super Powers
- [x] Admin Command Center & Throttling
- [x] 4-Layer Architecture Security Hardening
- [ ] Fog of War
- [ ] University competition launch
- [ ] Multi-team bracket stress testing
---
## 👨💻 Author
**Ali Haggag** — Computer Science Student, building the future of competitive programming education.
[](https://github.com/Ali-Haggag7)
[](mailto:ali.haggag2005@gmail.com)
[](https://www.linkedin.com/in/ali-haggag7/)
[](https://alihaggag.me/)
---
**Logic Arena** — *Where code becomes combat.*
⭐ Star this repo if it impressed you