# Player Guide This guide defines the Godot-Lab player-character workflow. Use it when asking an AI artist or asset agent to create the playable character for the top-down RPG. The player workflow has two steps: 1. **Step 1: Player Design Page** - create the approved visual and technical handoff. 2. **Step 2: Player Sprite Actions** - produce importable sprites action by action, with a hard maximum of 10 animation sprites/actions for the first pack. For downloadable step-specific prompts, use: - `player_design_page_guide.md` for Step 1. - `player_sprite_action_guide.md` for Step 2. Do not ask for a giant all-in-one character sheet first. The design page must be approved before sprite production starts. ## Goals - Top-down readable player silhouette. - Works on phone, tablet, and desktop. - Fits a 64 px tile-based world. - Starts plain and classless, matching the gameplay guide. - Can later support Power, Agility, Intelligence, Fighter, Mage, Sorcerer, and material-colored powers. - Imports cleanly into Godot as `CharacterBody2D` plus `AnimatedSprite2D` / `SpriteFrames`. ## Recommended Runtime Scale - Source frame canvas: `128x128` px per frame. - Runtime visual height target: about `56-72` px tall. - Feet/base point: locked to the same pixel position in every frame. - Collision footprint: roughly centered under the feet, not the full visual body. - Transparent PNG only; no checkerboard, matte, fake alpha, or cropped edges. ## Step 1: Player Design Page Use Step 1 to design the character, not to create final animation frames. ### Step 1 Output Create a single design page image plus a short metadata file: - `player_design_page.png` - `player_design_spec.json` - optional `player_design_notes.md` The page should be useful to both humans and a later sprite-generation AI. ### Step 1 Page Must Include - final player concept in the center - front/down view - back/up view - side view - small gameplay-scale preview beside a 64 px tile - foot/base point marker - approximate collision footprint - readable silhouette on light and dark backgrounds - color palette swatches - plain/classless starting outfit - one small upgrade cue each for Power, Agility, and Intelligence - optional later class direction notes for Fighter, Mage, and Sorcerer ### Step 1 Design Requirements - The player should be readable at phone size. - The character should feel like a beginner adventurer, not already a fully powered class. - Avoid huge weapons, huge capes, oversized hats, and details that will disappear at runtime scale. - Do not bake in class identity too early. - Keep a clear body center, readable head, readable feet, and clean movement silhouette. - The side view must be usable for both left and right through horizontal flip. ### Step 1 Prompt Template ```text Create a production handoff design page for a top-down Godot RPG player character. Game context: - top-down exploration survival RPG - 64 px tile-based world - player starts plain/classless - later progression uses Power, Agility, Intelligence - later classes may include Fighter, Mage, and Sorcerer - art must work on phone, tablet, and desktop Canvas: - one clean design page, 2048x2048 px or larger - no logo, no watermark, no fake UI text - use readable labels only if they are part of the design page; labels must not be part of final sprites Character: - beginner adventurer, readable at small size - friendly but capable - clear head/body/feet silhouette - outfit should be simple enough to animate - no huge cape, huge weapon, or extreme hair that will crop during animation Required views: - front/down view - back/up view - side view - small gameplay-scale preview next to a 64 px tile - light-background readability preview - dark-background readability preview Technical annotations: - mark the feet/base point - show approximate collision footprint - show fixed 128x128 frame canvas around one pose - include color palette swatches - show tiny upgrade accents for Power, Agility, Intelligence without turning the character into a final class Final feel: The page should be a clean production design handoff that a second AI can use to create transparent animation sprites action by action. ``` ## Step 2: Player Sprite Actions Step 2 produces real game sprites after the design page is approved. Generate **one action at a time** or a very small batch. Do not generate more than 10 animation sprites/actions in the first complete player pack. Every Step 2 request must include an explicit **action input**. The action input tells the AI what single animation to generate so it can focus on quality instead of trying to solve the whole player pack at once. ### Step 2 Action Input Use this input block for every sprite-generation request: ```json { "action_type": "idle", "direction": "down", "animation_name": "idle_down", "frame_count": 4, "fps": 6, "loop": true, "source_design": "player_design_page.png" } ``` Allowed `action_type` values for the first pack: - `idle` - `walk` - `action` - `hurt_or_death` Allowed `direction` values: - `down` - `up` - `side` - `universal` only for `hurt_or_death` Animation naming rule: - `idle` + `down` = `idle_down` - `idle` + `up` = `idle_up` - `idle` + `side` = `idle_side` - `walk` + `down` = `walk_down` - `walk` + `up` = `walk_up` - `walk` + `side` = `walk_side` - `action` + `down` = `action_down` - `action` + `up` = `action_up` - `action` + `side` = `action_side` - `hurt_or_death` + `universal` = `hurt_or_death` If the input does not match one of those names, stop and ask for a corrected action input. ### Max 10 Actions For First Pack The first player pack must include no more than these 10 actions: 1. `idle_down` 2. `idle_up` 3. `idle_side` 4. `walk_down` 5. `walk_up` 6. `walk_side` 7. `action_down` 8. `action_up` 9. `action_side` 10. `hurt_or_death` Use horizontal flip for left/right side movement in Godot. Do not add separate left and right sprites yet. Do not add class-specific sprites yet. Do not add separate sword, spell, dodge, swim, climb, emote, or mount animations in the first pack. ### Action Frame Targets - `idle`: 2-4 frames, `fps` 4-6, looping. - `walk`: 6-8 frames, `fps` 8-12, looping. - `action`: 4-6 frames, `fps` 8-12, non-looping. - `hurt_or_death`: 3-6 frames, `fps` 6-10, non-looping. If generation quality drops, reduce frame count before adding more actions. ### Step 2 Output For each action, produce: - `sprites/actions/.png` - `sprites/actions/.json` - `preview/_contact_sheet.png` - `preview/_gameplay_scale.png` - `preview/_alpha_edge_light.png` - `preview/_alpha_edge_dark.png` The file under `sprites/actions/` must be a production sprite strip, not a preview. It must be a horizontal RGBA PNG containing only the requested action frames. Hard size rule: - width = `frame_count * 128` - height = `128` - examples: - 4 frames = `512x128` - 6 frames = `768x128` - 8 frames = `1024x128` Reject and regenerate if the sprite image is any other size. Preview files can have labels, tile grids, or backgrounds; production sprite files cannot. #### Production Sprite Gate Before packaging the zip, inspect `sprites/actions/.png` directly. Do not rely on the contact sheet. The action is `import_ready: true` only if all of these are true: - PNG color mode is RGBA or equivalent with a real alpha channel. - Alpha is not fully opaque; at least the padding around the character is transparent. - No white, gray, checkerboard, tile, canvas texture, or matte background is baked into transparent areas. - Image dimensions exactly equal `frame_count * 128` by `128`. - Each frame occupies one exact 128x128 cell with no gutters between frames. - Character silhouette stays inside each cell with transparent padding on every side. - Feet/base point is the same pixel location in every frame. - The sprite strip contains only the requested animation, no title text, frame numbers, labels, borders, previews, or extra poses. If any item fails, set `import_ready: false` in the JSON and regenerate or clean the sprite before using it in Godot. Never mark preview-style renders as production sprites. A file with a baked checkerboard is reference-only, even if it looks visually transparent. #### Quick Machine Validation Use this check before accepting a generated action pack. Replace the paths if needed. ```bash python3 - <<'PY' from PIL import Image import json from pathlib import Path action = "idle_down" root = Path("player-action-work") png_path = root / "sprites" / "actions" / f"{action}.png" json_path = root / "sprites" / "actions" / f"{action}.json" meta = json.loads(json_path.read_text()) im = Image.open(png_path) expected = (meta["frame_count"] * 128, 128) errors = [] if im.size != expected: errors.append(f"wrong size: {im.size}, expected {expected}") if im.mode != "RGBA": errors.append(f"wrong mode: {im.mode}, expected RGBA") else: alpha = im.getchannel("A") if alpha.getextrema() == (255, 255): errors.append("alpha is fully opaque; no real transparency") if alpha.getbbox() == (0, 0, im.size[0], im.size[1]): errors.append("opaque pixels touch the image bounds; no transparent padding") if errors: print("IMPORT_READY=false") for err in errors: print("-", err) raise SystemExit(1) print("IMPORT_READY=true") PY ``` If this script prints `IMPORT_READY=false`, do not import the sprite into Godot and do not call the pack finished. After all approved actions are generated, assemble: - `sprites/player_spritesheet.png` - `sprites/player_animations.json` - `preview/player_all_actions_contact_sheet.png` - `preview/player_gameplay_scale_all.png` - `validation/player_sprite_validation.md` ### Per-Action JSON Each action JSON should include: ```json { "action": "walk_down", "action_type": "walk", "direction": "down", "frame_size_px": [128, 128], "frame_count": 8, "fps": 10, "loop": true, "base_point_px": [64, 104], "collision_footprint_px": { "shape": "capsule_or_rect", "center": [64, 108], "size": [28, 18] }, "source_design": "player_design_page.png", "side_view_flips_for_left_right": true, "transparent_background": true, "sheet_size_px": [1024, 128], "import_ready": true, "validation": { "rgba_with_alpha": true, "has_transparent_padding": true, "no_baked_checkerboard_or_matte": true, "exact_sheet_dimensions": true, "exact_128_px_cells": true, "base_point_stable": true, "production_sprite_not_preview": true }, "notes": "Transparent RGBA PNG. Feet/base point remains stable across frames." } ``` ### Quality Bar By Action Type #### `idle` - Pose should feel alive but calm. - Movement should be subtle: tiny breathing, blink, small cloth/hair sway. - Feet must stay planted. - No weapon swing, magic effect, jump, or dramatic body motion. - Down/up/side versions should feel like the same character from different angles. #### `walk` - Walk cycle must read clearly at gameplay scale. - Feet should alternate cleanly. - Body bob should be subtle and not look like jumping. - The base point should remain stable enough to avoid visual sliding in Godot. - Side walk must flip cleanly for left/right. - Avoid long trailing cloth/hair that creates frame-edge or flip problems. #### `action` - This is the generic first-pack action: use/cast/basic attack. - It should work before the player has a class. - The motion should be readable but not too specialized. - It can include a small neutral arc, hand motion, or brief focus flash. - Do not add sword-specific, spell-specific, or class-specific gear unless explicitly requested later. - Non-looping: clear anticipation, action, and settle frames. #### `hurt_or_death` - One universal direction is acceptable for the first pack. - It should communicate damage/failure quickly at phone size. - The character can recoil, slump, or fall, but must stay inside the 128x128 canvas. - Avoid gore, scary detail, or overly dramatic deformation. - Non-looping. ### Step 2 Sprite Requirements - Every frame must use the same `128x128` canvas. - The final strip size must be exactly `frame_count * 128` by `128`. - The final strip must use RGBA PNG with real transparency. - Transparent padding must be alpha `0`, not checkerboard, white, gray, or textured background. - The feet/base point must not drift. - The character cannot touch the frame edge. - No cropped weapon, hair, shadow, hand, foot, or effect. - No background. - No labels. - No contact-sheet borders inside final frames. - Real alpha transparency. - Side animation must work when flipped horizontally. - The silhouette must remain readable at gameplay scale. - Walk cycles must not slide visually when played in place. - The sprite strip must contain only frames for the requested action input. - Final action output must not include unrelated poses or bonus animations. - Output should preserve a clean pivot/base point suitable for Godot Y-sort and collision. - Do not upscale the production strip into a presentation sheet. - Do not crop frames from a contact sheet unless they are cleaned back into exact transparent 128x128 cells. ### Step 2 Prompt Template ```text Using the approved player design page, generate ONE transparent sprite animation action for a top-down Godot RPG player. Action input: { "action_type": "ACTION_TYPE_HERE", "direction": "DIRECTION_HERE", "animation_name": "ANIMATION_NAME_HERE", "frame_count": FRAME_COUNT_HERE, "fps": FPS_HERE, "loop": LOOP_TRUE_OR_FALSE, "source_design": "player_design_page.png" } Generate only this animation: - ANIMATION_NAME_HERE Do not generate the full character pack. Do not generate other actions. Do not generate extra directions. Technical target: - 128x128 px canvas per frame - final production strip size must be frame_count * 128 px wide by 128 px tall - for 4 frames, final production strip must be exactly 512x128 px - transparent RGBA PNG with a real alpha channel - alpha padding must be truly transparent pixels, not a baked checkerboard/matte - fixed feet/base point at the same pixel location in every frame - recommended base point: [64, 104] - recommended collision footprint center: [64, 108] - recommended collision footprint size: [28, 18] - character should occupy about 56-72 px visual height at runtime - leave safe transparent padding on all sides - no background, no labels, no watermark - no checkerboard, matte, or fake alpha - no frame border or contact-sheet border baked into the final sprite strip Animation requirements: - use FRAME_COUNT_HERE frames - fps: FPS_HERE - loop: LOOP_TRUE_OR_FALSE - direction/view: DOWN_UP_OR_SIDE - side view must be flippable for left/right in Godot - if action_type is idle: subtle breathing/blink/cloth motion only - if action_type is walk: clean alternating foot cycle, no visual sliding - if action_type is action: generic classless use/cast/basic action, non-looping - if action_type is hurt_or_death: clear damage/failure read, non-looping, no gore Consistency: - match the approved design page exactly - keep the same proportions, outfit, palette, head shape, and readable silhouette - do not add class-specific armor, weapons, or powers unless the action requires a small generic effect - keep the same shadow/feet relationship across frames - keep the character centered on the same base point - preserve phone-size readability over tiny detail Deliver: - one horizontal sprite strip for this action - sprite strip must be saved at sprites/actions/ANIMATION_NAME_HERE.png - sprite strip must be exact size: frame_count * 128 by 128 - a contact-sheet preview - a gameplay-scale preview on a neutral 64 px tile background - action metadata with frame size, frame count, fps, loop flag, base point, and collision footprint - alpha-edge preview on light and dark backgrounds - one short note describing any known limitations Packaging rule: - if the production sprite strip has no real alpha, wrong dimensions, labels, frame borders, or baked checkerboard, do not package it as import-ready - set import_ready:false and mark it reference_only until regenerated ``` ## Validation Checklist Before importing into Godot: - [ ] design page is approved - [ ] no more than 10 first-pack actions exist - [ ] every action has a transparent PNG - [ ] every action has metadata - [ ] frame size is exactly 128x128 - [ ] sprite strip size is exactly `frame_count * 128` by `128` - [ ] sprite PNG is RGBA or equivalent with a real alpha channel - [ ] sprite has transparent padding pixels; alpha is not fully opaque - [ ] base point is consistent - [ ] side action flips cleanly - [ ] gameplay-scale preview is readable - [ ] no frame touches the image edge - [ ] no checkerboard/background is baked in - [ ] final sprite is not a contact sheet or preview - [ ] final sprite contains no labels, borders, frame numbers, tile grids, or matte - [ ] walk actions loop cleanly - [ ] action names match Godot animation names ## Godot Import Notes The current project uses `CharacterBody2D` with `AnimatedSprite2D`. Import the approved pack as a `SpriteFrames` resource and keep these initial animation names stable: - `idle_down` - `idle_up` - `idle_side` - `walk_down` - `walk_up` - `walk_side` - `action_down` - `action_up` - `action_side` - `hurt_or_death` For the first implementation, the player script can choose direction from movement input, play idle/walk based on velocity, and use `flip_h` for left/right side animations.