mcp server

LICENSE

@@ -0,0 +1,196 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction,
+and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by
+the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all
+other entities that control, are controlled by, or are under common
+control with that entity. For the purposes of this definition,
+"control" means (i) the power, direct or indirect, to cause the
+direction or management of such entity, whether by contract or
+otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity
+exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications,
+including but not limited to software source code, documentation
+source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical
+transformation or translation of a Source form, including but
+not limited to compiled object code, generated documentation,
+and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or
+Object form, made available under the License, as indicated by a
+copyright notice that is included in or attached to the work
+(an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object
+form, that is based on (or derived from) the Work and for which the
+editorial revisions, annotations, elaborations, or other modifications
+represent, as a whole, an original work of authorship. For the purposes
+of this License, Derivative Works shall not include works that remain
+separable from, or merely link (or bind by name) to the interfaces of,
+the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including
+the original version of the Work and any modifications or additions
+to that Work or Derivative Works thereof, that is intentionally
+submitted to Licensor for inclusion in the Work by the copyright owner
+or by an individual or Legal Entity authorized to submit on behalf of
+the copyright owner. For the purposes of this definition, "submitted"
+means any form of electronic, verbal, or written communication sent
+to the Licensor or its representatives, including but not limited to
+communication on electronic mailing lists, source code control systems,
+and issue tracking systems that are managed by, or on behalf of, the
+Licensor for the purpose of discussing and improving the Work, but
+excluding communication that is conspicuously marked or otherwise
+designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity
+on behalf of whom a Contribution has been received by Licensor and
+subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+copyright license to reproduce, prepare Derivative Works of,
+publicly display, publicly perform, sublicense, and distribute the
+Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+(except as stated in this section) patent license to make, have
+made, use, offer to sell, sell, import, and otherwise transfer the
+Work, where such license applies only to those patent claims
+licensable by such Contributor that are necessarily infringed by
+their Contribution(s) alone or by combination of their
+Contribution(s) with the Work to which such Contribution(s) was
+submitted. If You institute patent litigation against any entity
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+the Work or a Contribution incorporated within the Work constitutes
+direct or contributory patent infringement, then any patent licenses
+granted to You under this License for that Work shall terminate as of
+the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+Work or Derivative Works thereof in any medium, with or without
+modifications, and in Source or Object form, provided that You
+meet the following conditions:
+
+You must give any other recipients of the Work or Derivative Works
+a copy of this License; and
+You must cause any modified files to carry prominent notices stating
+that You changed the files; and
+You must retain, in the Source form of any Derivative Works that You
+distribute, all copyright, patent, trademark, and attribution notices
+from the Source form of the Work, excluding those notices that do not
+pertain to any part of the Derivative Works; and
+If the Work includes a "NOTICE" text file as part of its
+distribution, then any Derivative Works that You distribute must
+include a readable copy of the attribution notices contained
+within such NOTICE file, excluding those notices that do not pertain
+to any part of the Derivative Works, in at least one of the following
+places: within a NOTICE text file distributed as part of the
+Derivative Works; within the Source form or documentation, if
+provided along with the Derivative Works; or, within a display
+generated by the Derivative Works, if and wherever such third-party
+notices normally appear. The contents of the NOTICE file are
+for informational purposes only and do not modify the License. You may
+add Your own attribution notices within Derivative Works that You
+distribute, alongside or as an addendum to the NOTICE text from the
+Work, provided that such additional attribution notices cannot be
+construed as modifying the License.
+
+You may add Your own copyright statement to Your modifications and
+may provide additional or different license terms and conditions
+for use, reproduction, or distribution of Your modifications, or
+for any such Derivative Works as a whole, provided Your use,
+reproduction, and distribution of the Work otherwise complies with
+the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+any Contribution intentionally submitted for inclusion in the Work
+by You to the Licensor shall be under the terms and conditions of
+this License, without any additional terms or conditions.
+Notwithstanding the above, nothing herein shall supersede or modify
+the terms of any separate license agreement you may have executed
+with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+names, trademarks, service marks, or product names of the Licensor,
+except as required for reasonable and customary use in describing the
+origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+agreed to in writing, Licensor provides the Work (and each
+Contributor provides its Contributions) on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+implied, including, without limitation, any warranties or conditions
+of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+PARTICULAR PURPOSE. You are solely responsible for determining the
+appropriateness of using or redistributing the Work and assume any
+risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+whether in tort (including negligence), contract, or otherwise,
+unless required by applicable law (such as deliberate and grossly
+negligent acts) or agreed to in writing, shall any Contributor be
+liable to You for damages, including any direct, indirect, special,
+incidental, or consequential damages of any character arising as a
+result of this License or out of the use or inability to use the
+Work (including but not limited to damages for loss of goodwill,
+work stoppage, computer failure or malfunction, or any and all
+other commercial damages or losses), even if such Contributor
+has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+the Work or Derivative Works thereof, You may choose to offer,
+and charge a fee for, acceptance of support, warranty, indemnity,
+or other liability obligations and/or rights consistent with this
+License. However, in accepting such obligations, You may act only
+on Your own behalf and on Your sole responsibility, not on behalf
+of any other Contributor, and only if You agree to indemnify,
+defend, and hold each Contributor harmless for any liability
+incurred by, or claims asserted against, such Contributor by reason
+of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+To apply the Apache License to your work, attach the following
+boilerplate notice, with the fields enclosed by brackets "[]"
+replaced with your own identifying information. (Don't include
+the brackets!) The text should be enclosed in the appropriate
+comment syntax for the file format. We also recommend that a
+file or class name and description of purpose be included on
+the same "printed page" as the copyright notice for easier
+identification within third-party archives.
+
+   Copyright 2025 Rohith Raghunathan Nair
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at:
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

README.md

@@ -1,14 +1,107 @@
 ---
-title: GameSmith
-emoji: 🔥
+title: PixelForge AI
+emoji: 🎮
 colorFrom: purple
-colorTo: green
+colorTo: blue
 sdk: gradio
-sdk_version: 6.0.1
+sdk_version: 5.9.0
 app_file: app.py
 pinned: false
-license: apache-2.0
-short_description: 'Bring your characters to life: Create. Animate. Ship.'
+tags:
+  - building-mcp-track-creative
+  - mcp-in-action-track-creative
+  - tool
+  - game-dev
+  - pixel-art
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 🎮 PixelForge AI: The Intelligent Game Asset Studio
+
+**Author:** Rohith Raghunathan Nair
+
+## 🚀 Overview
+
+**PixelForge AI** is a dual-interface Game Asset Generator that functions as both a human-friendly **Web App** and an AI-accessible **MCP Server**. 
+
+It solves the biggest bottleneck in indie game development: **Creating consistent, animated assets.**
+
+By leveraging **Google Gemini 2.5 Flash** for style-consistent sprite generation and **Google Veo** for physics-aware animation, PixelForge allows developers (and AI agents!) to go from a text prompt to a ready-to-use sprite sheet in seconds.
+
+## 🏆 Hackathon Tracks
+
+This project is submitted to:
+- **Track 1: Building MCP** (Creative) - `building-mcp-track-creative`
+- **Track 2: MCP in Action** (Creative) - `mcp-in-action-track-creative`
+
+## ✨ Features
+
+1.  **Text-to-Sprite Generation:** Creates high-quality, flat 2D pixel art characters using advanced prompting strategies to ensure game-ready assets (no 3D artifacts, solid backgrounds).
+2.  **AI Animation (Veo):** Uses Google's Veo model to generate fluid animations (Idle, Walk, Run, Jump) that strictly adhere to the pixel art style of the input sprite.
+3.  **Asset Extraction:** Automatically converts the generated video animations into standard sprite sheet frames (PNGs) and ZIP archives, ready for engines like Unity, Godot, or Phaser.
+4.  **MCP Native:** All functionality is exposed via the Model Context Protocol. You can ask Claude: *"Make a knight sprite, animate it walking, and give me the frames"* and it will execute the entire pipeline autonomously.
+
+## 🛠️ Installation & Usage
+
+### Prerequisites
+- Python 3.10+
+- Google Gemini API Key (with access to Veo and Gemini models)
+- FFmpeg (installed on system)
+
+### Setup
+
+1.  Clone the repository:
+    ```bash
+    git clone https://huggingface.co/spaces/YOUR_USERNAME/PixelForge-AI
+    cd PixelForge-AI
+    ```
+
+2.  Install dependencies:
+    ```bash
+    pip install -r requirements.txt
+    ```
+
+3.  Set your API Key:
+    ```bash
+    export GEMINI_API_KEY="your_google_api_key_here"
+    ```
+
+4.  Run the server:
+    ```bash
+    python app.py
+    ```
+
+5.  **For Humans:** Open `http://localhost:7860` in your browser.
+6.  **For Agents (MCP):** Connect your MCP client (Claude Desktop, Cursor) to `http://localhost:7860/sse`.
+
+## 🤖 MCP Configuration (Claude Desktop)
+
+Add this to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "pixel-forge": {
+      "command": "python",
+      "args": [
+        "/path/to/PixelForge-AI/app.py"
+      ],
+      "env": {
+        "GEMINI_API_KEY": "your_key_here"
+      }
+    }
+  }
+}
+```
+
+## 💡 Winning Ideas for MCP Hackathon
+*(As requested, here are 5 winning concepts for the MCP Hackathon)*
+
+1.  **PixelForge AI (This Project):** A creative pipeline that bridges the gap between generative video and usable game assets, solving a real "last mile" problem for developers.
+2.  **NPC-GPT (The Living Character Engine):** An MCP server that generates not just the visual sprite (using PixelForge tools) but also the character's stats, dialogue trees, and behavior scripts, packaging them into a JSON file for Godot/Unity.
+3.  **RetroRemix (Legacy Game Reskinner):** A tool where users upload screenshots of old games, and the AI identifies assets (tiles, enemies) and "remasters" them into a new style (e.g., "Cyberpunk Mario") using the sprite pipeline.
+4.  **StoryBoarder (Cinematic Cutscene Gen):** An agentic workflow that takes a script, breaks it into scenes, generates keyframes using Gemini, animates short loops using Veo, and assembles a rough animatic video.
+5.  **LevelGod (Procedural World Builder):** A tool focused on "Tile Connectivity". You generate a center tile, and the MCP server iteratively generates the connecting tiles (top, bottom, corners) to ensure seamless looping textures for infinite runners or RPG maps.
+
+## 📜 License
+
+MIT License

app.py

@@ -0,0 +1,205 @@
+import gradio as gr
+import os
+import base64
+from io import BytesIO
+from PIL import Image
+import tempfile
+from tools import generate_pixel_character, animate_pixel_character, extract_sprite_frames
+
+# --- Helper Functions for Gradio Logic ---
+
+def process_generate_sprite(prompt, ref_img):
+    try:
+        ref_b64 = None
+        if ref_img is not None:
+            # Convert numpy array or PIL image to base64
+            if isinstance(ref_img, str): # path
+                with open(ref_img, "rb") as f:
+                    ref_b64 = base64.b64encode(f.read()).decode('utf-8')
+            elif hasattr(ref_img, "save"): # PIL Image
+                buffered = BytesIO()
+                ref_img.save(buffered, format="PNG")
+                ref_b64 = base64.b64encode(buffered.getvalue()).decode('utf-8')
+        
+        b64_result = generate_pixel_character(prompt, ref_b64)
+        
+        # Convert back to PIL for display
+        img_data = base64.b64decode(b64_result)
+        return Image.open(BytesIO(img_data)), b64_result
+    except Exception as e:
+        raise gr.Error(str(e))
+
+def process_animate_sprite(sprite_img, animation_type, extra_prompt):
+    try:
+        if sprite_img is None:
+            raise ValueError("Please provide a sprite image first.")
+            
+        # Convert input image to base64
+        sprite_b64 = None
+        if isinstance(sprite_img, str): # path provided by Gradio example or upload
+             with open(sprite_img, "rb") as f:
+                sprite_b64 = base64.b64encode(f.read()).decode('utf-8')
+        elif hasattr(sprite_img, "save"): # PIL Image
+            buffered = BytesIO()
+            sprite_img.save(buffered, format="PNG")
+            sprite_b64 = base64.b64encode(buffered.getvalue()).decode('utf-8')
+        elif isinstance(sprite_img, tuple): # Sometimes Gradio returns (path, meta)
+             # Handle other formats if necessary
+             pass
+        
+        # If sprite_b64 is still None (e.g. numpy array), try to convert
+        if sprite_b64 is None:
+             # Assuming numpy array -> PIL -> Base64
+             im = Image.fromarray(sprite_img)
+             buffered = BytesIO()
+             im.save(buffered, format="PNG")
+             sprite_b64 = base64.b64encode(buffered.getvalue()).decode('utf-8')
+
+        video_b64 = animate_pixel_character(sprite_b64, animation_type, extra_prompt)
+        
+        # Save to temp file for Gradio to display
+        video_bytes = base64.b64decode(video_b64)
+        with tempfile.NamedTemporaryFile(delete=False, suffix=".mp4") as f:
+            f.write(video_bytes)
+            video_path = f.name
+            
+        return video_path, video_b64
+    except Exception as e:
+        raise gr.Error(str(e))
+
+def process_extract_frames(video_file, fps):
+    try:
+        if video_file is None:
+            raise ValueError("Please upload a video file.")
+            
+        # Read video file to base64
+        with open(video_file, "rb") as f:
+            video_b64 = base64.b64encode(f.read()).decode('utf-8')
+            
+        zip_b64, frames_b64 = extract_sprite_frames(video_b64, fps)
+        
+        # Save zip to temp file
+        with tempfile.NamedTemporaryFile(delete=False, suffix=".zip") as f:
+            f.write(base64.b64decode(zip_b64))
+            zip_path = f.name
+            
+        # Convert frames to gallery format (list of paths or PIL images)
+        gallery_images = []
+        for fb64 in frames_b64:
+            img_data = base64.b64decode(fb64)
+            gallery_images.append(Image.open(BytesIO(img_data)))
+            
+        return gallery_images, zip_path
+    except Exception as e:
+        raise gr.Error(str(e))
+
+
+# --- Gradio UI Layout ---
+
+with gr.Blocks(title="PixelForge AI - Game Asset Studio", theme=gr.themes.Soft()) as demo:
+    gr.Markdown(
+        """
+        # 🎮 PixelForge AI
+        ### The Intelligent Game Asset Studio
+        
+        Generate, animate, and export pixel art sprites for your games using Google Gemini & Veo.
+        *Built for the Hugging Face MCP Hackathon.*
+        """
+    )
+    
+    with gr.Tab("1. Generate Sprite"):
+        with gr.Row():
+            with gr.Column():
+                prompt_input = gr.Textbox(
+                    label="Character Description",
+                    placeholder="A brave knight in rusty armor, side view...",
+                    lines=3
+                )
+                ref_input = gr.Image(label="Style Reference (Optional)", type="pil")
+                gen_btn = gr.Button("Generate Sprite", variant="primary")
+            
+            with gr.Column():
+                result_image = gr.Image(label="Generated Sprite", type="pil")
+                # Hidden state to pass base64 to next tab if needed
+                sprite_b64_state = gr.State()
+        
+        gen_btn.click(
+            process_generate_sprite,
+            inputs=[prompt_input, ref_input],
+            outputs=[result_image, sprite_b64_state]
+        )
+
+    with gr.Tab("2. Animate"):
+        with gr.Row():
+            with gr.Column():
+                # Allow user to use generated image or upload new
+                anim_input_image = gr.Image(label="Input Sprite", type="pil")
+                anim_type = gr.Dropdown(
+                    choices=["idle", "walk", "run", "jump"],
+                    value="idle",
+                    label="Animation Type"
+                )
+                extra_anim_prompt = gr.Textbox(
+                    label="Motion Tweaks (Optional)",
+                    placeholder="Make it bounce more..."
+                )
+                anim_btn = gr.Button("Animate", variant="primary")
+            
+            with gr.Column():
+                result_video = gr.Video(label="Generated Animation")
+                video_b64_state = gr.State()
+        
+        # Link previous tab result to this input
+        result_image.change(
+            lambda x: x,
+            inputs=[result_image],
+            outputs=[anim_input_image]
+        )
+        
+        anim_btn.click(
+            process_animate_sprite,
+            inputs=[anim_input_image, anim_type, extra_anim_prompt],
+            outputs=[result_video, video_b64_state]
+        )
+
+    with gr.Tab("3. Extract Frames"):
+        with gr.Row():
+            with gr.Column():
+                # Allow user to use generated video or upload new
+                extract_input_video = gr.Video(label="Input Animation")
+                fps_slider = gr.Slider(minimum=4, maximum=24, value=8, step=1, label="FPS")
+                extract_btn = gr.Button("Extract Frames", variant="primary")
+            
+            with gr.Column():
+                frames_gallery = gr.Gallery(label="Sprite Sheet Frames")
+                download_zip = gr.File(label="Download Sprite Sheet (ZIP)")
+        
+        # Link previous tab result
+        result_video.change(
+            lambda x: x,
+            inputs=[result_video],
+            outputs=[extract_input_video]
+        )
+        
+        extract_btn.click(
+            process_extract_frames,
+            inputs=[extract_input_video, fps_slider],
+            outputs=[frames_gallery, download_zip]
+        )
+
+    gr.Markdown("---")
+    gr.Markdown("### 🤖 Model Context Protocol (MCP)")
+    gr.Markdown(
+        """
+        This app doubles as an MCP Server! Connect it to Claude or Cursor to generate assets directly in your chat.
+        
+        **Tools Exposed:**
+        - `generate_pixel_character(prompt)`
+        - `animate_pixel_character(sprite_b64, animation_type)`
+        - `extract_sprite_frames(video_b64)`
+        """
+    )
+
+if __name__ == "__main__":
+    # Launch with MCP support enabled
+    demo.launch(mcp_server=True)

requirements.txt

@@ -0,0 +1,7 @@
+gradio>=5.9.0
+mcp
+google-genai
+pillow
+numpy
+ffmpeg-python
+python-dotenv

tools.py

@@ -0,0 +1,310 @@
+import os
+import base64
+import io
+import json
+import math
+import time
+from typing import List, Optional, Tuple, Dict, Any
+from PIL import Image
+import ffmpeg
+from google import genai
+from google.genai import types
+
+# Initialize API Key from environment
+# Users should set GEMINI_API_KEY in their environment variables
+API_KEY = os.environ.get("GEMINI_API_KEY")
+
+def _get_client():
+    if not API_KEY:
+        raise ValueError("GEMINI_API_KEY environment variable is not set.")
+    return genai.Client(api_key=API_KEY)
+
+def generate_pixel_character(
+    prompt_text: str, 
+    reference_image_b64: Optional[str] = None
+) -> str:
+    """
+    Generates a static 2D pixel art sprite character based on a text description.
+    
+    Args:
+        prompt_text: Description of the character (e.g., "A brave knight with a red cape").
+        reference_image_b64: Optional base64 string of a reference image to influence style.
+        
+    Returns:
+        A base64 string of the generated PNG image.
+    """
+    client = _get_client()
+    
+    base_instructions = (
+        "Generate a 2D pixel art sprite character. Style: flat 2D pixel art, NOT 3D, "
+        "NOT photorealistic, NOT rendered. Use pixelated art style with visible pixels. "
+        "Character should be a 2D sprite sheet style character, side view, full body, centered. "
+        "White solid background (not transparent, not checkerboard). No shadows, no 3D effects, "
+        "no depth, no gradients. Pure 2D pixel art sprite style like classic video game sprites. "
+        "Do NOT add text or UI."
+    )
+    
+    full_prompt = f"{prompt_text}\n\n{base_instructions}" if prompt_text else base_instructions
+    
+    # Config for Gemini 2.5 Flash Image (supports generate_content)
+    model_id = "gemini-2.5-flash-image"
+    
+    contents = [types.Content(parts=[types.Part.from_text(text=full_prompt)])]
+    
+    if reference_image_b64:
+        # Remove data URL prefix if present
+        if "," in reference_image_b64:
+            reference_image_b64 = reference_image_b64.split(",", 1)[1]
+            
+        image_bytes = base64.b64decode(reference_image_b64)
+        contents[0].parts.append(types.Part.from_bytes(data=image_bytes, mime_type="image/png"))
+
+    try:
+        response = client.models.generate_content(
+            model=model_id,
+            contents=contents,
+            config=types.GenerateContentConfig(
+                temperature=0.4
+            )
+        )
+        
+        if not response.candidates or not response.candidates[0].content.parts:
+            raise RuntimeError("No content generated by the model.")
+            
+        for part in response.candidates[0].content.parts:
+            if part.inline_data:
+                # Return raw base64
+                return base64.b64encode(part.inline_data.data).decode('utf-8')
+                
+        raise RuntimeError("Model returned content but no image data found.")
+        
+    except Exception as e:
+        raise RuntimeError(f"Failed to generate character: {str(e)}")
+
+def animate_pixel_character(
+    sprite_b64: str,
+    animation_type: str = "idle",
+    extra_prompt: str = ""
+) -> str:
+    """
+    Animates a static pixel art sprite using Google's Veo model.
+    
+    Args:
+        sprite_b64: Base64 string of the input static sprite (PNG).
+        animation_type: One of "idle", "walk", "run", "jump".
+        extra_prompt: Optional additional instructions for the motion.
+        
+    Returns:
+        A base64 string of the generated video (MP4).
+    """
+    client = _get_client()
+    
+    # Clean base64
+    if "," in sprite_b64:
+        sprite_b64 = sprite_b64.split(",", 1)[1]
+    
+    sprite_bytes = base64.b64decode(sprite_b64)
+    
+    # Prompt construction (ported from original project)
+    base_style = """
+CRITICAL STYLE REQUIREMENTS - YOU MUST FOLLOW THESE EXACTLY:
+- This is a 2D PIXEL ART animation. The input image is a 2D pixel art sprite.
+- The clip should be about 4 seconds long so it can be used as a game sprite animation.
+- You MUST maintain the EXACT same 2D pixel art style as the input image.
+- DO NOT make it 3D, DO NOT make it realistic, DO NOT add depth, DO NOT add shadows.
+- DO NOT add lighting, DO NOT add gradients, DO NOT add shine or gloss.
+- DO NOT render it in 3D style, DO NOT make it photorealistic.
+- The character must remain flat 2D pixel art throughout the entire animation.
+- Match the pixelated, low-resolution, retro game sprite aesthetic of the input image exactly.
+- Use a solid pure white background (#FFFFFF), completely flat, no gradient, no textures, no shadows, no ground line, no objects.
+- The character must stay centered, side view, and fill a reasonable portion of the frame.
+- No text, UI, logos, borders, or props.
+- Keep the same pixel density and resolution as the input image.
+""".strip()
+
+    motion_prompts = {
+        "idle": """
+ANIMATION TYPE: IDLE
+- The character must stand completely still in place.
+- Only animate a very subtle breathing motion: tiny up/down movement of the chest.
+- Optional: very slight idle sway (left/right) of the body, but minimal.
+- NO walking, NO movement across the screen, NO leg movement.
+- The animation should be a single seamless idle loop that starts and ends in almost the same pose so it can be looped cleanly.
+- Do not add any extra actions or transitions after the idle cycle finishes.
+- Keep the animation loop smooth and subtle.
+""",
+        "walk": """
+ANIMATION TYPE: WALK CYCLE
+- Animate a classic 2D side-scrolling walk cycle in place, side view.
+- The character walks on the spot (does NOT move across the screen).
+- Show clear leg alternation: left leg forward, right leg back, then switch.
+- Arms should swing opposite to legs (left arm forward when right leg forward).
+- The character's body should have a slight up/down bounce as they walk.
+- The video should contain one clean walk cycle that returns to the starting pose so it can loop seamlessly.
+- Avoid extra camera movement or additional actions at the end of the clip.
+- The character must stay centered in the frame throughout.
+""",
+        "run": """
+ANIMATION TYPE: RUN CYCLE
+- Animate a faster run cycle in place, side view.
+- The character runs faster than walking with more exaggerated motion.
+- Legs move faster with longer strides.
+- Arms pump more vigorously than walking.
+- Body has more pronounced up/down bounce.
+- The character stays centered and runs on the spot, like a classic game sprite.
+- The clip should be a single, smooth run cycle that ends in nearly the same pose as the first frame for looping.
+- Do not add extra motions or transitions after the run cycle is complete.
+""",
+        "jump": """
+ANIMATION TYPE: JUMP CYCLE
+- Animate a complete jump cycle in place: anticipation (squat down), jump up, hang time at peak, fall down, land, then settle back into the starting pose.
+- The character should compress slightly before jumping (anticipation).
+- At the peak of the jump, there should be a brief hang time.
+- The landing should have a slight compression/squat.
+- The clip should contain one complete jump cycle that ends very close to the initial idle pose, so it can be looped with other animations.
+- Avoid extra steps, actions, or camera moves after the landing.
+- NO camera movement, keep the character centered throughout.
+"""
+    }
+
+    selected_motion = motion_prompts.get(animation_type, motion_prompts["idle"]).strip()
+    extra = f"\nAdditional user instruction: {extra_prompt.strip()}" if extra_prompt else ""
+    full_prompt = f"{base_style}\n\n{selected_motion}\n\n{extra}"
+
+    # Fallback chain for Veo models
+    veo_models = [
+        "veo-3.1-fast-generate-preview",  # Currently the best for this
+        "veo-3.1-generate-preview"
+    ]
+
+    last_error = None
+    
+    for model_name in veo_models:
+        try:
+            print(f"Attempting animation with model: {model_name}")
+            
+            response = client.models.generate_videos(
+                model=model_name,
+                prompt=full_prompt,
+                image=types.Image(
+                    image_bytes=sprite_bytes,
+                    mime_type="image/png"
+                ),
+                config=types.GenerateVideosConfig(
+                    aspect_ratio="16:9",
+                    # duration_seconds=4 # Not always supported in all SDK versions/models, but implied
+                )
+            )
+            
+            # Poll for completion
+            # The Python SDK might handle polling in generate_videos if not async, 
+            # or we get an operation object.
+            # In the new google-genai SDK, generate_videos returns a Job or response.
+            # Let's assume it waits or we need to wait. 
+            # Actually, looking at docs, generate_videos returns a GenerateVideosResponse 
+            # which contains the video immediately OR it's a long-running op.
+            # For "generate-preview" models, it's often synchronous or fast.
+            # However, if it returns an operation, we must wait.
+            
+            # NOTE: The Python SDK structure might differ slightly from Node.
+            # If response has 'generated_videos', we are good.
+            
+            if hasattr(response, 'generated_videos'):
+                video = response.generated_videos[0]
+                if video.video.bytes:
+                    return base64.b64encode(video.video.bytes).decode('utf-8')
+                elif video.video.uri:
+                    # We might need to fetch it if it's a URI
+                     # For now, assuming bytes are returned or handled by SDK
+                     pass
+            
+            # If it's an operation (Job), we'd need to poll. 
+            # But usually the synchronous wrapper does this.
+            # Let's try to return the bytes.
+            
+            # If we need to handle the Job object manually:
+            if hasattr(response, 'done'): # It's an operation
+                 while not response.done:
+                     time.sleep(5)
+                     response = client.operations.get(response.name)
+                 
+                 # Now get result
+                 if response.result and response.result.generated_videos:
+                     video_bytes = response.result.generated_videos[0].video.bytes
+                     return base64.b64encode(video_bytes).decode('utf-8')
+
+            # If we got here and haven't returned, try to inspect standard fields
+            # The new SDK is quite dynamic.
+            
+            # Let's assume standard happy path for now.
+            return base64.b64encode(response.generated_videos[0].video.bytes).decode('utf-8')
+
+        except Exception as e:
+            print(f"Model {model_name} failed: {e}")
+            last_error = e
+            continue
+
+    raise RuntimeError(f"All animation models failed. Last error: {last_error}")
+
+def extract_sprite_frames(
+    video_b64: str,
+    fps: int = 8
+) -> Tuple[str, List[str]]:
+    """
+    Extracts frames from an MP4 video and returns a path to a ZIP file and list of frame images.
+    
+    Args:
+        video_b64: Base64 string of the MP4 video.
+        fps: Frames per second to extract (default 8).
+        
+    Returns:
+        Tuple containing:
+        1. Base64 string of the ZIP file containing all frames.
+        2. List of Base64 strings for the individual frames (for preview).
+    """
+    # Create temporary directory
+    import tempfile
+    import shutil
+    import glob
+    
+    if "," in video_b64:
+        video_b64 = video_b64.split(",", 1)[1]
+    
+    video_bytes = base64.b64decode(video_b64)
+    
+    with tempfile.TemporaryDirectory() as tmp_dir:
+        input_path = os.path.join(tmp_dir, "input.mp4")
+        with open(input_path, "wb") as f:
+            f.write(video_bytes)
+            
+        output_pattern = os.path.join(tmp_dir, "frame_%03d.png")
+        
+        try:
+            (
+                ffmpeg
+                .input(input_path)
+                .filter('fps', fps=fps)
+                .output(output_pattern)
+                .overwrite_output()
+                .run(capture_stdout=True, capture_stderr=True)
+            )
+        except ffmpeg.Error as e:
+            raise RuntimeError(f"FFmpeg error: {e.stderr.decode('utf8')}")
+            
+        # Collect frames
+        frame_files = sorted(glob.glob(os.path.join(tmp_dir, "frame_*.png")))
+        
+        frames_b64 = []
+        for frame_file in frame_files:
+            with open(frame_file, "rb") as f:
+                frames_b64.append(base64.b64encode(f.read()).decode('utf-8'))
+                
+        # Create ZIP
+        zip_path = os.path.join(tmp_dir, "sprites.zip")
+        shutil.make_archive(zip_path.replace('.zip', ''), 'zip', tmp_dir, '.')
+        
+        # Read ZIP
+        with open(zip_path, "rb") as f:
+            zip_b64 = base64.b64encode(f.read()).decode('utf-8')
+            
+        return zip_b64, frames_b64