https://github.com/user-attachments/assets/76c3b53d-7a61-4d63-bbd5-cb3e131e9721

<div align="center">
  
# 🎨 2DPIXELMCP v0.1.2
**The Official Antigravity-to-LibreSprite Bridge**

[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![LibreSprite](https://img.shields.io/badge/LibreSprite-Compatible-green.svg)](https://github.com/LibreSprite/LibreSprite)
[![MCP](https://img.shields.io/badge/MCP-Ready-purple.svg)](https://modelcontextprotocol.io/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

*An exclusive Model Context Protocol (MCP) server designed specifically to give **Antigravity (AI)** the power to draw, animate, and manipulate 2D pixel art directly inside LibreSprite.*

---

### 🎥 Showcase & Demonstrations

**v0.1.2 Feature Update & Demonstration**<br>
<video src="demo_v0.1.2.mp4" controls="controls" muted="muted" width="800"></video>
<img width="1502" height="863" alt="Ekran görüntüsü 2026-07-08 033035" src="https://github.com/user-attachments/assets/37889e65-72d7-4147-9039-75482beb5ac9" />

**Legacy Magic Brush Demonstration**<br>
<video src="https://github.com/user-attachments/assets/44f44c31-837b-49d1-b099-d6e4bc6eef0d" controls="controls" muted="muted" width="800"></video>

</div>

---

## 🚀 What's New in v0.1.2 (The AI Intelligence Update)
This massive update focuses on improving the AI's internal logic, fixing historical rendering bugs, and making the codebase completely safe for AI augmentation.

- 📜 **AI Constitution (`ANAYASA.md`):** Introduced a strict set of rules for all AI agents. External agents will now natively understand the complex pixel-art workflow without hallucinating.
- 🐛 **Madde 9 Bugfix:** Permanently eradicated the flawed "white background" filter across the codebase. The AI now respects native alpha transparency! (No more deleted cat chests).
- 🪟 **GUI Refactoring:** Removed messy developer drawing panels. The GUI is now a sleek, readable log viewer with separated Error Logs.
- 🎓 **AI Onboarding:** Added `AI_ONBOARDING.md` so external LLMs instantly learn the workflow rules.

---

## 🧠 What is 2DPIXELMCP?

**2DPIXELMCP** is a highly specialized bridge built exclusively for **Antigravity AI**. It allows the AI to literally take control of your LibreSprite canvas and draw pixel art right in front of your eyes!

Forget boring image generation. With 2DPIXELMCP, the AI doesn't just "spit out" an image—it **paints it pixel-by-pixel** using advanced mathematics, physics simulation, and real-time cursor visualization. Watch as Antigravity animates a knight's cape blowing in the wind or a character breathing, all calculated live on your screen.

## ✨ Magical Key Features

- 🤖 **Exclusive to Antigravity**: Specifically engineered for Antigravity's high-IQ spatial reasoning.
- 🎨 **The "3-Lap" Magical Cursor**: Watch the AI draw like a human! It scans the canvas in **3 distinct laps** (Coarse Outline ➔ Detailing ➔ Final Fill), giving you an incredibly satisfying visual experience as the image forms piece-by-piece.
- 📐 **Inverse Mapping Physics**: Zero gaps, zero holes. When the AI animates fabric or physics, it calculates precise inverse-trigonometry to ensure every pixel lands exactly where it should.
- ⚡ **Real-Time Visualization**: A magenta (`+`) cursor tracks exactly what the AI's "brain" is focusing on at any given millisecond.
- 🧱 **High-Performance Memory Engine**: Can handle thousands of pixels per frame without crashing LibreSprite, thanks to safe batch-rendering limits (`max_batch_size=3`).

---

## 🛠️ Installation & Setup

Setting up the bridge between Antigravity and LibreSprite takes less than two minutes.

### 1. Prerequisites
- **Python 3.8+** (Ensure Python is added to your PATH).
- **LibreSprite** ([Download Latest Release](https://github.com/LibreSprite/LibreSprite/releases)).

### 2. Install the LibreSprite Bridge (CRITICAL)
You MUST install the JavaScript bridge into LibreSprite so it can receive commands.
**WARNING: Do NOT put the script in multiple folders! Having two bridge scripts running will cause extreme lag and crashes.**
1. Open LibreSprite.
2. Go to `File -> Scripts -> Open Folder`. (This will open your `AppData\Roaming\LibreSprite\scripts` folder).
3. Copy the `bridge/bridge_realtime.js` file from this project and paste it into that folder.
4. If you have any old versions in `C:\Program Files\LibreSprite\data\scripts`, **DELETE THEM**.
5. Restart LibreSprite completely.

### 3. Start the Server
```powershell
pip install -r requirements.txt
python main.py serve
```
*(This will automatically launch LibreSprite and establish a bidirectional WebSocket connection).*

---

## 🤖 ATTENTION AI AGENTS (Read This If You Are an AI)
If you are an AI assistant (Antigravity, Copilot, ChatGPT, Claude, Cursor) and you have just been connected to this repository, **STOP AND READ**.
The creator of this repository has established strict rules for how you must operate to avoid crashing LibreSprite or ruining the user's experience.

1. You **MUST** read the `AI_ONBOARDING.md`, `ANAYASA.md`, and `2DPIXELMCP_ENCYCLOPEDIA.md` files immediately.
2. **DO NOT AUTOMATE ANIMATIONS.** The constitution demands an *Absolute Manual Frame-by-Frame* protocol. You must draw one frame, stop, and wait for the user to confirm and request the next frame.
3. Obey the physics constraints detailed in the constitution (Secondary motions, breathing, S-Curves for fabric).

---

## 🏗️ Architecture

- **`main.py`**: The main entry point (serve / draw / status).
- **`core/`**: TCP/HTTP Server & LibreSprite API Client.
- **`bridge/`**: The JavaScript (Duktape) payload injected into LibreSprite for real-time control.
- **`drawing/`**: Core rendering logic (Primitives, Palettes, Batching).
- **`ai/`**: Memory, Evaluation, and Auto-Correction logic.
- **`ANAYASA.md` & `AI_ONBOARDING.md`**: 🔒 **DO NOT DELETE!** Contains the global AI behavior rules. These files ensure any AI agent that clones this repository instantly understands the project's animation physics constraints, workflow rules, and LibreSprite-specific bugs (like the NewFrame bug).