agent-sprite-forge-2d-game-assets

# Agent Sprite Forge — 2D Game Asset Generation > Skill by [ara.so](https://ara.so) — AI Agent Skills collection. Agent Sprite Forge is a Codex-first 2D game asset workflow where the agent decides the plan, image generation creates the raw visuals, and deterministic scripts turn those visuals into reusable game assets. This skill enables AI agents to generate sprite sheets, layered maps, transparent PNGs, animated GIFs, and engine-ready exports for Godot and Unity. ## What It Does - **Sprite Sheets**: Characters, monsters, props, attacks, spells, projectiles, impacts, idles, walks, and reference-guided variants - **Layered Maps**: Ground-only bases, dressed references, prop packs, transparent props, y-sort placement, collision, zones, and previews - **Engine Handoff**: Godot scenes, editable TileMap layers, separated props, encounter grass, collision bodies, exits, and debug players - **Local Cleanup**: Chroma-key removal, frame extraction, alignment, transparent PNG/GIF export, prop-pack slicing, and QA metadata ## Installation ```bash # Clone the repository git clone https://github.com/0x0funky/agent-sprite-forge.git cd agent-sprite-forge # Install dependencies pip install -r requirements.txt # Set up environment variables export OPENAI_API_KEY="your-api-key-here" # or create .env file echo "OPENAI_API_KEY=your-api-key-here" > .env ``` ### Requirements - Python 3.8+ - PIL/Pillow for image processing - OpenAI API access (for image generation) - Optional: Godot 4.x or Unity for engine exports ## Core Skills ### 1. Generate 2D Sprite Sheets (`$generate2dsprite`) Use this skill when you need animated units, playable characters, monsters, props, spell bundles, or projectile/impact effects. **Basic sprite generation:** ```python from agent_sprite_forge import SpriteGenerator # Initialize generator sprite_gen = SpriteGenerator() # Generate character sprite sheet result = sprite_gen.generate( prompt="samurai warrior walking animation, 4 directions, pixel art style", frames=4, directions=["down", "left", "right", "up"], output_dir="./output/sprites" ) # Result includes: # - sprite_sheet.png (full sheet) # - frames/ (individual PNG frames) # - animations/ (GIF animations per direction) # - metadata.json (frame info, dimensions, cleanup settings) ``` **Attack and spell animations:** ```python # Generate spell cast animation spell_result = sprite_gen.generate( prompt="fire mage casting fireball spell, side view, 6 frames", frames=6, animation_type="cast", include_projectile=True, output_dir="./output/spells/fireball" ) # Generates: # - cast_animation.gif # - projectile_animation.gif # - impact_animation.gif (if include_impact=True) # - transparent PNG frames for each ``` **Reference-guided variants:** ```python # Generate sprite based on reference image ref_result = sprite_gen.generate_from_reference( reference_image="./refs/crocodile.jpg", prompt="crocodile playing with a stone, 8 frame loop animation", frames=8, preserve_style=True, output_dir="./output/croc_animation" ) ``` ### 2. Generate 2D Maps (`$generate2dmap`) Use this skill for layered RPG maps with ground, props, collision, and engine-ready exports. **Basic layered map generation:** ```python from agent_sprite_forge import MapGenerator map_gen = MapGenerator() # Generate layered map with prop extraction map_result = map_gen.generate_layered_map( prompt="cyberpunk canal district, neon signs, bridges, water", style="hand-painted HD game map", include_props=True, output_dir="./output/maps/cyber_canal" ) # Generates: # - ground_base.png (clean ground layer) # - dressed_reference.png (fully decorated reference) # - prop_pack_3x3.png (extracted props grid) # - props/ (individual transparent prop PNGs) # - layered_preview.png (flattened preview) # - metadata.json (layer info, prop positions) ``` **Godot TileMap export:** ```python # Generate Godot-ready map project godot_map = map_gen.generate_godot_map( prompt="forest village with paths, houses, trees, pond", tileset_size=16, # 16x16 tiles map_size=(40, 30), # tiles include_collision=True, include_zones=True, # encounter grass, exits output_dir="./output/godot_maps/forest_village" ) # Generates: # - tileset.png (autotile-ready) # - prop_sheet_3x3.png # - scenes/ForestVillage.tscn (editable scene) # - resources/tileset.tres # - resources/prop_atlas.tres # - scripts/debug_player.gd # - collision and area metadata ``` ### 3. Post-Processing and Cleanup **Chroma-key background removal:** ```python from agent_sprite_forge.processors import BackgroundRemover remover = BackgroundRemover() # Remove background and export transparent PNG clean_sprite = remover.remove_background( input_path="./raw/sprite_sheet.png", chroma_color="#00FF00", # green screen tolerance=30, output_path="./output/sprite_sheet_clean.png" ) ``` **Frame extraction and GIF export:** ```python from agent_sprite_forge.processors import FrameExtractor, GIFExporter # Extract frames from sprite sheet extractor = FrameExtractor() frames = extractor.extract_frames( sprite_sheet="./output/sprite_sheet_clean.png", frame_width=64, frame_height=64, output_dir="./output/frames" ) # Create animated GIF gif_exporter = GIFExporter() gif_exporter.create_animation( frames_dir="./output/frames", output_path="./output/animation.gif", frame_duration=100, # milliseconds loop=0 # infinite loop ) ``` **Prop pack slicing:** ```python from agent_sprite_forge.processors import PropPackSlicer slicer = PropPackSlicer() # Slice 3x3 prop pack into individual props props = slicer.slice_prop_pack( prop_pack="./output/maps/cyber_canal/prop_pack_3x3.png", grid_size=(3, 3), output_dir="./output/maps/cyber_canal/props", remove_background=True, chroma_color="#FFFFFF" ) # Returns list of prop files with bounding box metadata ``` ## Configuration Create a `config.yaml` file to set defaults: ```yaml # Image generation settings image_generation: model: "dall-e-3" size: "1024x1024" quality: "hd" style: "natural" # or "vivid" # Sprite settings sprites: default_frame_count: 4 default_frame_size: [64, 64] background_color: "#00FF00" # chroma key export_formats: ["png", "gif"] # Map settings maps: default_tile_size: 16 prop_pack_grid: [3, 3] layer_order: ["ground", "props", "collision", "zones"] # Processing processing: chroma_tolerance: 30 gif_frame_duration: 100 png_compression: 9 # Engine exports godot: version: "4.5" tilemap_layer_enabled: true include_debug_player: true unity: version: "2022.3" sprite_pixels_per_unit: 16 include_prefabs: true ``` Load config in Python: ```python from agent_sprite_forge import load_config config = load_config("config.yaml") sprite_gen = SpriteGenerator(config=config) ``` ## Common Patterns ### Full Character Asset Pipeline ```python from agent_sprite_forge import SpriteGenerator, BackgroundRemover, FrameExtractor, GIFExporter def create_character_assets(character_name, prompt_base): """Generate complete character asset set""" sprite_gen = SpriteGenerator() # 1. Generate directional walk animations walk_result = sprite_gen.generate( prompt=f"{prompt_base}, walking animation, 4 directions", frames=4, directions=["down", "left", "right", "up"], output_dir=f"./output/characters/{character_name}/walk" ) # 2. Generate attack animation attack_result = sprite_gen.generate( prompt=f"{prompt_base}, sword attack, side view", frames=6, animation_type="attack", output_dir=f"./output/characters/{character_name}/attack" ) # 3. Generate idle animation idle_result = sprite_gen.generate( prompt=f"{prompt_base}, idle breathing animation", frames=2, animation_type="idle", output_dir=f"./output/characters/{character_name}/idle" ) return { "walk": walk_result, "attack": attack_result, "idle": idle_result } # Usage samurai_assets = create_character_assets( "samurai_warrior", "pixel art samurai in blue armor" ) ``` ### RPG Map with Godot Export ```python from agent_sprite_forge import MapGenerator def create_rpg_zone(zone_name, description): """Generate RPG map zone with Godot export""" map_gen = MapGenerator() # Generate layered map map_result = map_gen.generate_godot_map( prompt=description, tileset_size=16, map_size=(40, 30), include_collision=True, include_zones=True, zone_types=["encounter_grass", "exit", "trigger"], output_dir=f"./output/maps/{zone_name}" ) # Add custom metadata map_result.add_metadata({ "zone_name": zone_name, "encounters": ["slime", "bat", "wolf"], "exits": [ {"name": "north_exit", "to": "zone_02"}, {"name": "south_exit", "to": "zone_00"} ] }) return map_result # Usage forest_zone = create_rpg_zone( "forest_01", "dense forest with winding path, old shrine, mushroom clusters" ) ``` ### Spell Bundle Generation ```python def create_spell_bundle(spell_name, element, color_scheme): """Generate complete spell asset bundle""" sprite_gen = SpriteGenerator() spell_dir = f"./output/spells/{spell_name}" # Cast animation cast = sprite_gen.generate( prompt=f"mage casting {element} spell, {color_scheme} colors, side view", frames=6, output_dir=f"{spell_dir}/cast" ) # Projectile projectile = sprite_gen.generate( prompt=f"{element} projectile, {color_scheme}, spinning animation", frames=4, animation_type="projectile", output_dir=f"{spell_dir}/projectile" ) # Impact impact = sprite_gen.generate( prompt=f"{element} explosion impact, {color_scheme}, burst effect", frames=8, animation_type="impact", output_dir=f"{spell_dir}/impact" ) return { "cast": cast, "projectile": projectile, "impact": impact } # Usage fireball = create_spell_bundle("fireball", "fire", "red and orange") ice_lance = create_spell_bundle("ice_lance", "ice", "blue and white") ``` ### Unity Survivors-like Setup ```python from agent_sprite_forge import SpriteGenerator, UnityExporter def setup_survivors_game(game_name): """Generate assets for survivors-like game""" sprite_gen = SpriteGenerator() unity_export = UnityExporter() base_dir = f"./output/unity_projects/{game_name}" # Hero sheets (4 directions) hero = sprite_gen.generate( prompt="anime hero character, walking animation, 4 directions", frames=4, directions=["down", "left", "right", "up"], output_dir=f"{base_dir}/Assets/Heroes/Hero01" ) # Summon/minion sheets summons = [] for i, summon_type in enumerate(["wolf", "eagle", "bear"]): summon = sprite_gen.generate( prompt=f"spirit {summon_type} companion, idle and attack", frames=6, output_dir=f"{base_dir}/Assets/Summons/{summon_type}" ) summons.append(summon) # Enemy sheets enemies = [] for enemy_type in ["slime", "skeleton", "demon"]: enemy = sprite_gen.generate( prompt=f"{enemy_type} enemy, walk and attack animation", frames=4, output_dir=f"{base_dir}/Assets/Enemies/{enemy_type}"