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

🎨 2DPIXELMCP v0.1.2

The Official Antigravity-to-LibreSprite Bridge

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

Legacy Magic Brush Demonstration

🚀 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.

Related MCP server: Aseprite MCP

🧠 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).

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

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).