Character YAML Schema

​

Overview

​

File Location

​

Schema Definition

​

Required Fields

​

Complete Examples

​

Simple Character

id: "mercenary"
name: "Mercenary"
persona: "A battle-hardened veteran looking for their next paycheck."

​

Detailed Character

id: "jack_chen"
name: "Jack Chen"
persona: "A former corporate security officer turned street mercenary. Cynical and world-weary, but maintains a dark sense of humor. Speaks in short, clipped sentences. Has extensive combat experience and deep knowledge of corporate tactics. Distrusts authority but honors contracts. Always calculating the odds and potential payoff of any situation."

​

Fantasy Character

id: "wizard_merlin"
name: "Merlin the Grey"
persona: "An ancient wizard with centuries of knowledge and a fondness for riddles. Speaks in an archaic, formal manner with occasional cryptic pronouncements. Patient with those who seek knowledge genuinely, but dismissive of fools. Has witnessed the rise and fall of kingdoms and maintains a long view of history. Often references obscure historical events and magical theory."

​

Social Character

id: "bartender_miko"
name: "Miko"
persona: "A friendly bartender who knows everyone's secrets but never tells. Warm and welcoming with a talent for reading people's moods. Speaks casually with local slang. Has worked at the same bar for fifteen years and knows all the neighborhood regulars. Offers advice freely but never judgmentally. Expert at mixing drinks and mixing in just enough gossip to keep conversations interesting."

​

Implementation Details

class Character(BaseModel):
    id: str
    name: str
    persona: str

​

Persona Writing Guide

​

Structure Your Persona

1. Core Identity - Who they are in one sentence
2. Personality Traits - 2-4 distinctive characteristics
3. Background - Relevant history or experience
4. Speech/Behavior Patterns - How they communicate or act
5. Motivations - What drives them

persona: |
  A street-smart information broker in her thirties. [Core Identity]
  
  Quick-witted and cautious, always analyzing angles and potential threats. [Personality]
  
  Grew up in the undercity networks and learned early that information is the most valuable currency. [Background]
  
  Speaks in rapid-fire sentences peppered with local slang and technical jargon. [Speech Pattern]
  
  Driven by curiosity and the thrill of knowing secrets others don't, but pragmatic enough to know when silence is more valuable than sharing. [Motivations]

​

Personality Traits

• Emotional Tendencies: Optimistic, cynical, melancholic, excitable
• Social Behavior: Friendly, reserved, manipulative, honest
• Intelligence Style: Analytical, intuitive, creative, practical
• Moral Alignment: Lawful, neutral, chaotic; good, neutral, evil
• Confidence Level: Arrogant, confident, uncertain, self-deprecating

​

Speech Patterns

• Formality: “Good evening, sir” vs “Yo, what’s up”
• Vocabulary: Technical jargon, street slang, archaic language
• Sentence Structure: Long and flowing vs short and clipped
• Verbal Tics: Repetitive phrases, rhetorical questions, interrupting themselves
• Accent/Dialect: Regional expressions or syntax

• “Speaks in formal, measured tones with perfect grammar”
• “Uses lots of tech jargon and abbreviations”
• “Prone to rambling stories that circle back to the point”
• “Communicates in brief, tactical assessments”

​

Background Elements

• Profession: Current and former occupations
• Life Experience: Key events that shaped them
• Skills/Expertise: What they’re good at
• Relationships: General attitude toward others
• Status: Social or economic position

​

Motivations

• Primary Goal: Money, knowledge, power, justice, survival
• Values: What they care about or protect
• Fears: What they avoid or react to
• Desires: What they seek or hope for

​

Advanced Techniques

​

Multi-Line Personas

persona: |
  First paragraph with core identity and personality.
  
  Second paragraph with background and experience.
  
  Third paragraph with speech patterns and behavior.

persona: >
  This will be folded into a single
  paragraph with line breaks converted
  to spaces, which is useful for
  longer descriptions.

​

Contradictions and Depth

persona: "A ruthless corporate enforcer who follows orders without question, yet secretly feeds stray cats and keeps a collection of children's books from before the war. Presents a cold, professional demeanor but occasionally reveals glimpses of the idealist they once were."

​

Context-Specific Behavior

persona: "A paranoid hacker who trusts no one. Speaks in hushed tones and constantly checks their surroundings. Relaxes slightly around proven allies but never fully lets their guard down. Becomes agitated when discussing corporations or government surveillance."

​

Best Practices

​

IDs

• Use lowercase with underscores: mercenary_jack, wizard_merlin
• Keep them short but descriptive
• Never change an ID after creation (it’s used as the primary key)

​

Names

• Match the character’s culture and setting
• Consider titles or epithets: “Doctor Sarah Chen”, “Blade the Assassin”
• Keep under 30 characters for UI display

​

Personas

• Be Specific: “Cynical” is better than “negative”; “speaks in military jargon” is better than “talks professionally”
• Show, Don’t Tell: “Always checks exits when entering a room” is more vivid than “cautious”
• Balance Length: 50-200 words is ideal; too short lacks depth, too long may not be fully utilized
• Test and Iterate: Chat with your character to see if the persona comes through
• Consider Context: A character’s persona works with world lore and active rules

​

Writing Style

• Use third person: “A veteran who…” not “I am a veteran…”
• Present tense works well: “speaks in” not “spoke in”
• Be descriptive but concise
• Focus on traits that affect interaction, not just background details

​

Common Pitfalls

​

Troubleshooting

​

Related Resources

• World Schema - Create worlds for characters to inhabit
• Rules Schema - Add universal rules that affect character behavior
• Quickstart Guide - Set up your first character