> ## Documentation Index > Fetch the complete documentation index at: https://docs.summerengine.com/llms.txt > Use this file to discover all available pages before exploring further. # Character portrait skill for AI agents > Generate one polished character bust for dialogue UI, character select, lore cards or codex entries. A Summer Engine skill for AI agents. `character-portrait` is a skill from the [Summer skill library](/mcp/skills): a guide your AI agent reads when the task matches, so it builds the good version on the first try. Generate one polished character bust for dialogue UI, character select, lore cards or codex entries. | | | | - | - | | Status | Stable | | Domains | 2D art, Asset pipeline | | Version | `1.0.4` | | Engine version | `>=4.6` | | Recommended set | Yes, installed by `--recommended` | ## When your agent uses it * Generating a single polished bust/portrait of a character for dialogue UI, character-select screens, lore cards, or codex entries * A dialogue box, party roster, or codex entry needs one consistent face for a named character ## Install `summer setup` installs every skill for your agent. To add only this one: ```bash theme={null} npx -y summer-engine@latest skills install character-portrait --agent claude-code ``` Swap `claude-code` for your agent, such as `codex` or `cursor`. See [Skills](/mcp/skills#quick-start) for every option. ## The skill This skill produces ONE polished character portrait — bust or shoulders-up framing, neutral or stylized background, designed to drop into a dialogue UI, character-select screen, or lore card. It is the **opposite** of `concept-art`: concept art explores; this skill commits. The single biggest failure mode is **inconsistency across a cast**. Generating five party members one at a time without a locked anchor produces five images that look like they're from five different games — different lighting, different angle, different palette, different rendering style. This skill makes you write a **locked anchor suffix** the first time and re-use it verbatim for every subsequent portrait. If the user is still exploring the look, this is the wrong skill — route to `concept-art` first, lock a direction, then come back here. The `asset-strategy` meta-router asks **"Quick check — exploring the look (3-4 variants for art direction) or generating a final character portrait for dialogue UI?"** to disambiguate. ## When to use * "Generate a portrait for the merchant NPC." * "I need a character-select image for the four playable heroes." * "Make a lore-card image of the king." * "Add a VN-style dialogue portrait for Aria." * The cast is locked and the visual direction is locked; you're producing finals. ## When NOT to use * The user is still exploring → `concept-art`. * The user wants pixel art → `pixel-art`. * The user wants a full-body 3D model → `asset-strategy`. * The user wants 4+ animated expressions of the same character — generate one base portrait here, then use img2img with the base as `referenceImageUrl` for each expression. ## Steps ### 1. Read or establish the locked anchor Check `.summer/portrait-anchor.md` first. ``` Read .summer/portrait-anchor.md ``` If it doesn't exist, this is the first portrait in the cast — you must define the anchor now. Ask the user (or infer from `.summer/GameSoul.md`): * **Framing:** bust (chest up) or shoulders-up? * **Angle:** straight-on, three-quarter left, three-quarter right? * **Lighting:** soft front, dramatic side, rim-lit, golden-hour? * **Background:** flat color, soft gradient, painterly blur, in-world environment? * **Rendering style:** painterly, anime, semi-realistic, line-art-with-flat-color? Write the anchor to `.summer/portrait-anchor.md`: ``` ## Portrait anchor (re-use verbatim for every cast member) framing: bust, shoulders to crown of head visible angle: three-quarter view, slight turn to character's left lighting: soft warm key from upper right, cool fill from left, gentle rim background: muted painterly gradient, dark teal to deep brown, no scene detail style: semi-realistic painterly, soft edges, oil-painting feel ``` Note there is no aspect line in the anchor: framing is the `aspectRatio` argument of `assets.generate_image`, not prompt text. Bust framing reads fine square (`1:1`, the default); true portrait framing is `aspectRatio: "3:4"`. Whichever you pick, use it for the *whole* cast — mixed aspect is as visible as mixed lighting. Every subsequent portrait in this cast appends the anchor to the prompt verbatim. **Do not edit the anchor mid-cast** unless the user explicitly says "I want the new ones to look different." ### 2. Search for an existing portrait ``` assets.search({ query: " portrait", assetType: "2d_image", scope: "all" }) ``` Reuse beats regenerate. If the user wants to iterate on an existing one, pull its URL and pass it as `referenceImageUrl` for img2img. ### 3. Build the prompt — character + anchor Pattern: ``` . ``` The character description should include: identity (age, build, hair, distinctive features), expression, costume/equipment, any signature prop. Keep it under 60 words including the anchor. ### 4. Confirm and call > Generating Aria the witch portrait — 1 image (uses credits), model nano-banana-2, anchor locked from `.summer/portrait-anchor.md`. OK? ``` assets.generate_image({ prompt: "Aria, young witch, mid-twenties, pale skin, long black hair with silver streak, sharp green eyes, half-smile, wearing dark indigo robes with silver embroidery, raven on shoulder. ", model: "nano-banana-2", style: "none", aspectRatio: "" }) ``` `style: "none"` because the anchor's "semi-realistic painterly" already specifies style. Only `cartoon` and `anime` append anything to the prompt, and `realistic` / `none` append nothing — any other value is coerced to `none`. So the preset cannot "fight" a painterly anchor; it just does nothing either way, and every bit of the look has to be in the prompt. There is no `options` object: shape and size are `aspectRatio`, `width` and `height`. ### 5. Import and wire into UI ``` summer_import_from_url( url="", path="res://ui/portraits/aria.png" ) ``` For dialogue UI nodes, wire the texture into a `TextureRect`: ``` summer_set_prop( scenePath="res://ui/dialogue.tscn", path="./DialogueBox/PortraitRect", key="texture", value="res://ui/portraits/aria.png" ) ``` `texture` is a property on the node, so this is `summer_set_prop` — which needs an explicit `scenePath`, a node path relative to that scene's root (`./`), and a `key` argument, not `property`. `summer_set_resource_property` is for reaching one level *inside* a resource the node already holds and requires all five of `scenePath`, `nodePath`, `resourceProperty`, `subProperty`, `value`. For character-select with multiple portraits, name files consistently: `aria.png`, `borin.png`, `cael.png`, `dara.png`. Index-able from code via `"res://ui/portraits/%s.png" % character_id`. ### 6. Iterate (img2img) instead of regenerating from scratch If the user wants the portrait tweaked ("smaller smile", "darker robes"), use img2img with the existing image as `referenceImageUrl`. Preserves identity and lighting. ``` assets.generate_image({ prompt: " with a smaller, more subtle smile", referenceImageUrl: "", model: "nano-banana-2", style: "none" }) ``` ## Prompt patterns | Goal | Prompt skeleton (subject part only — append anchor verbatim) | Why | | - | - | - | | Generic NPC | `, , , , , wearing ` | Identity-first; no scene context | | Hero / protagonist | `, , , , confident , wearing , holding ` | Adds prop for memorability | | Antagonist | `, , , wearing , ` | Antagonists need visual asymmetry | | Lore card / king | `, , regal , wearing , , formal portrait pose` | Formal pose overrides anchor's three-quarter | | Expression variant | ` with ` + `referenceImageUrl: ` | img2img preserves identity | | Younger / older variant | ` as a ` + `referenceImageUrl: ` | For flashback / time-skip portraits | ### Bad prompts (and why) | Bad | Failure mode | | - | - | | `cool warrior portrait` | No identity, no anchor. Returns generic stock art. | | `the witch but make her sad` (no img2img ref) | Without `referenceImageUrl`, you get a *different* witch who is sad. Identity drift. | | Anchor inconsistent across cast | Each portrait looks like a different game. The cast doesn't read as a cast. | | `full body portrait` | "Portrait" implies bust. If you want full body, say so explicitly in the prompt and use a tall `aspectRatio` (`2:3`) — full body is a different asset class anyway; consider `concept-art` or the 3D pipeline. | | `transparent background` for a painterly portrait | Painterly + transparent fails on most models. Use a flat or gradient background, then alpha-cut in an editor if you must. | ## Anti-patterns * **No anchor file.** Every cast member generated ad-hoc looks unrelated. Define the anchor on portrait #1, re-use for the rest of the cast. * **Editing the anchor mid-cast.** If you change lighting from "warm key" to "dramatic side" halfway through, the cast splits visually. Either commit to the change and regenerate everyone, or stick with the anchor. * **Regenerating from scratch when img2img would do.** Identity drifts every regen. Iterate via `referenceImageUrl`. * **Using the portrait as a 3D reference.** Portraits have dramatic lighting, painterly backgrounds, and cropped framing — all of which corrupt 3D generation. For 3D, generate a separate clean white-bg full-body T-pose via `asset-strategy`. * **Expecting `style` to carry the look.** Only `cartoon` and `anime` append anything; `realistic` and `none` append nothing and any other value is coerced to `none`. If the anchor names the style, `"none"` is correct — but the anchor text is doing all the work, not the preset. ## Edge cases * **Character has a non-human silhouette (lizardfolk, demon, robot).** The anchor still applies — framing, lighting, background, rendering style. Only the subject description changes. Verify the model can hold the silhouette under "bust framing" — some models default to humanoid. * **Player wants to swap costumes mid-game.** Generate one base portrait per costume (`aria_traveler.png`, `aria_robes.png`, `aria_armored.png`) and switch by index. Use img2img from the base for consistency. * **Cast of 12+ characters.** Anchor discipline gets harder as fatigue sets in. Print the anchor as a header in your generation script and don't write any prompt without it. * **User wants the portrait to "read at small size" (32×32 in a portrait list).** That's pixel-art territory; route to `pixel-art`. ## Without Summer Engine In a session without Summer Engine tools (the assets profile; the `summer-assets` skill has the whole loop), do steps 1-4 and 6, and skip step 5 (import and UI wiring). Pass `out` with the person's folder so the PNG lands there (the `summer-assets` skill says how), and tell them the path. ## Fallback (no MCP) Print the prompt and the call: ``` assets.generate_image({ prompt: "", model: "nano-banana-2", style: "none" }) ``` Tell the user to run via the Summer dashboard, then `summer_import_from_url` the result to `res://ui/portraits/.png`. ## Handoff After the portrait is wired: * **More cast members** → re-invoke this skill with the same anchor. Don't redefine. * **Expression variants** → re-invoke with `referenceImageUrl` set to the base portrait. * **Pixel-art version of the same character** → `pixel-art`. * **3D model of the same character** → `asset-strategy` (the portrait is NOT a usable 3D reference; generate a separate T-pose). * **Dialogue system wiring** → `scene-composition` for the UI hierarchy. ## See also * `concept-art` — explore the look first if not yet locked. * `asset-strategy` — meta-router and the 3D pipeline. * `scene-composition` — wiring the portrait into a dialogue UI scene. * `summer_docs_read` id `reference/mcp-tools-reference` — how to call `assets.generate_image`. ## From a shell No Summer MCP tools in this session? Run each one as a command; when `summer --version` is missing or below 4.0, use `npx -y summer-engine@latest` in place of `summer`. Fields are flags in kebab-case (`--scene-path res://main.tscn`) or one `--input ''`, and `summer ops describe ` prints the exact input. The `summer-cli` skill has the rest. | In this skill | Command | | - | - | | `assets.generate_image`, `summer_assets_generate_image` | `summer assets generate-image` | | `summer_assets_search` | `summer assets search` | | `summer_docs_read` | `summer docs read` | | `summer_import_from_url` | `summer engine import-from-url` | | `summer_set_prop` | `summer engine set-prop` | | `summer_set_resource_property` | `summer engine set-resource-property` | ## Related skills * [`concept-art`](/skills/concept-art): Explore art direction with 3-4 rough concept variants of a character, environment or prop. * [`pixel-art`](/skills/pixel-art): Generate pixel-art sprites, items, tiles and portraits at a set resolution with a limited palette. * [`asset-strategy`](/skills/asset-strategy): Route any 'I need a \[thing]' asset request to the right skill: 2D, 3D, audio, video, VFX or animation. * [`create-asset-sheet`](/skills/create-asset-sheet): Generate a pack of 2D assets from one prompt (tile sheet, UI kit, character pack, biome), sliced. *** Source: [`library/skills/character-portrait/SKILL.md`](https://github.com/SummerEngine/summer/blob/main/library/skills/character-portrait/SKILL.md), rendered from `summer-engine@4.3.0` on npm. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.