Writing Your Own Personality

Understanding Personality Packs

A personality pack is a directory structure containing JSON files organized by functional module. Each module corresponds to a specific aspect of the bot's behavior and responses. The bot reads these JSON files at runtime, so you can create new personalities by providing different content without modifying any code.

The default "Ratz" personality pack (located in the codebase) serves as a complete reference example. Study its structure to understand how content is organized and formatted.

Directory Structure

Personality packs follow a modular directory structure. Each module gets its own directory, and within those directories, you organize JSON files and other content files. Here's the general structure:

your-personality-name/
├── mood/
│   ├── mood.json
│   ├── greetings.json
│   └── insultsandcompliments.json
├── menu/
│   ├── menufood.json
│   ├── menudrink.json
│   ├── food/
│   ├── drinks/
│   └── specials/
├── conversation/
│   ├── talking_to_bartender.json
│   └── eastereggs.json
├── employment/
│   ├── missions/
│   ├── jobresolution.json
│   └── fixercommentary.json
├── performances/
│   └── performances.json
├── timeofday/
│   └── time_of_day.json
├── help/
│   └── help.json
└── ... (and more modules)

The exact structure depends on which modules you want to customize. You don't need to include every module—only the ones relevant to your personality.

Bar Activity & User Activity Tracking

This is one of the most important modules for creating a sense of attentiveness and presence. The bot tracks conversation patterns, user activity, and bar atmosphere, then responds with commentary that makes it feel like your bartender is actually aware of what's happening in the space.

Activity tracking creates that crucial "sense of place" where the bot feels present and attentive, not just reactive. Your bartender comments on conversation patterns, notices when things are busy or quiet, and responds to activity changes—just like a real bartender would.

Key files:

• baractivity/bar_activity.json - Responses to bar activity patterns
• baractivity/useractivity.json - Responses to individual user activity patterns

Activity patterns that trigger responses:

• Sudden rush of many people talking - When activity spikes with multiple people chatting
• Activity picking up again after being quiet - When conversation resumes after a lull
• Uninterrupted talking for hours - When there's been continuous conversation for an extended period
• Unusually busy for the time - When activity is higher than expected for the current time of day
• Sudden extended silence after much activity - When things go quiet after being busy
• Bar is lifeless - When there's been no activity for an extended period
• Silent for the time frame - When it's unusually quiet for the current time period
• One person dominating the conversation - When a single user is doing most of the talking
• Two people talking alone - When only two people are having a conversation
• One person talking to themselves - When someone is the only active participant
• New people join the conversation - When new users start participating in active channels
• First order in some time - When someone interacts with the bartender after a period of no orders
• First comment in some time - When someone makes a comment after several days of silence

Example structure:

{
  "sudden rush of many people talking": [
    {
      "threshold": 5,
      "message": [
        "Whoa, where did all these people come from?",
        "Bar getting busy all of sudden!",
        "Looks like everyone decided to show up at once."
      ]
    },
    {
      "threshold": 10,
      "message": [
        "This is getting crowded!",
        "Ratz can barely keep up with all this activity!",
        "Place is packed now!"
      ]
    }
  ],
  "Bar is lifeless": [
    {
      "threshold": 0,
      "message": [
        "Place is dead quiet today.",
        "Not much happening here right now.",
        "Bar feels empty."
      ]
    }
  ],
  ...
}

Each activity pattern can have multiple threshold levels with different responses. The bot selects the highest threshold response that matches the current activity level, allowing for nuanced commentary that scales with the situation.

Mood Module

Defines how your bartender responds based on their current emotional state. Typically includes responses for different mood levels (very good, good, neutral, bad, very bad).

Key files:

• mood.json - Mood-specific responses
• greetings.json - Greeting messages for various situations
• insultsandcompliments.json - Responses when complimenting or insulting users
• moodchange.json - Messages when mood changes

Example structure:

{
  "very good": [
    "Response option 1",
    "Response option 2",
    "Response option 3"
  ],
  "good": [
    "Response option 1",
    "Response option 2"
  ],
  ...
}

Menu Module

Defines all food and drink items available in your bar, organized by category. This includes standard menu items, specials, regional foods, and drink suggestions.

Key files/directories:

• menufood.json - Food menu structure
• menudrink.json - Drink menu structure
• food/ - Individual food item files
• drinks/ - Individual drink item files
• specials/ - Special menu items
• suggestions.json - Menu suggestions for customers
• barrounds.json - Responses for ordering rounds

Menu items typically include name, description, price, and category information. The format depends on your setting—medieval taverns have different items than spaceport bars!

Conversation Module

Defines how your bartender engages in conversation, responds to being talked to, and handles various dialogue situations.

Key files:

• talking_to_bartender.json - Responses when users talk to the bartender
• eastereggs.json - Hidden responses to specific phrases or topics
• responses/ - Various conversation response files

Employment Module

If your personality includes missions or jobs, this module defines mission descriptions, job resolution responses, fixer/employer commentary, and team-related content.

Key files/directories:

• missions/ - Individual mission JSON files (singleplayer missions, chains, and epics)
• jobresolution.json - Responses when jobs complete (success/failure)
• fixercommentary.json - Commentary from employers/fixers
• teams.json - Team names and related content
• multiplayer.json - Multiplayer mission interactions
• lootitems.json - Items that can be obtained from missions

Detailed mission writing guide: Writing Missions →

Time-Based Content

Content that changes based on time of day, day of week, or calendar events. This helps create a sense of time passing in your bar.

Key modules:

• timeofday/ - Time-of-day commentary (morning, afternoon, evening, night)
• dayofweek/ - Day-of-week specific content
• todayin[theme]/ - Calendar events and themed days (e.g., "todayincyberpunk", "todayingaming")
• calendar/ - Calendar events and special dates
• birthday/ - Birthday messages
• milestones/ - Milestone celebration messages

Bar Events

Random events that can occur in the bar, creating dynamic and unexpected moments. These events happen spontaneously and add variety to the bar's atmosphere.

Key files:

• barevents/randomevents.json - Random events that can occur in the bar

Random events are triggered by the bot's event system and can include things like unusual occurrences, interesting situations, or atmospheric moments that add life to the bar.

Additional Atmosphere Content

Additional content modules that contribute to the bar's atmosphere and world-building.

Key modules:

• deepthoughts/ - Philosophical or thoughtful moments
• simulatednews/ - News items relevant to your setting

Other Modules

Additional modules that enhance the bot's functionality and atmosphere. These are optional but add depth to your personality:

Performances Module

Defines variety acts and performances that users can attempt in the bar. Users can try different acts, and the bot responds with success or failure outcomes. This creates entertainment opportunities and adds variety to user interactions.

Key files:

• performances/performances.json - Performance types, descriptions, and responses

Structure: Each performance includes a title, description, success responses, and failure responses. The bot tracks user performance records including successes, failures, and tips earned.

Example use cases: Singing, juggling, storytelling, magic tricks, comedy routines—any variety act that fits your bar's setting and atmosphere.

Championships Module

Defines competitive events and competitions that can occur in the bar. These are typically competitive activities like bar fights, arm wrestling, or other contests that users can participate in.

Key files:

• championships/barfight.json - Bar fight competition content
• armwrestling/armwrestling.json - Arm wrestling competition content

Use cases: Competitive events create engagement and give users goals to work toward. These can range from physical competitions to skill-based challenges, depending on your setting.

Help & Knowledge Base Module

Provides help content and a knowledge base that the bot can reference. This includes explanations of how different systems work (orders, bar tab, missions, etc.) and in-universe information.

Key files/directories:

• help/help.json - Help messages for different topics (orders, barTab, blackjack, reputation, missions, championship, location)
• help/ - HTML knowledge base files that can be referenced

Content types: Help responses explain how to use various bot features, while the knowledge base contains world-building information your bartender can reference when asked about people, places, or events.

Lore Module

Contains in-universe knowledge and world-building information. When users ask about people, places, or events, the bot can reference this content to provide consistent, character-appropriate information.

Key files/directories:

• lore/ - Text files containing information about various topics
• lore/mapping.json - Maps topic names to lore files

Usage: When enabled with LLM integration, the bot uses these lore files to answer questions about in-universe topics. This ensures consistent world-building and prevents the bot from making up information. Each topic gets its own text file with information written from your bartender's perspective.

User Welcomes Module

Defines welcome messages for new users when they first arrive or join the server. These are typically lightweight greetings that introduce the bartender and the bar to newcomers.

Key files:

• userwelcomes/curbside.json - Welcome messages for new arrivals

Purpose: Creates a welcoming atmosphere and helps new users understand they're entering a space with a personality-driven bot. Keep these concise and in-character—first impressions matter!

User Tags Module

Defines tags or labels that can be associated with users. These might represent roles, reputations, relationships, or other metadata about users in your bar.

Key files:

• usertags/standardusertags.json - Standard user tag definitions

Usage: Tags can be used to customize interactions with specific users or user groups. For example, you might have tags for "regular customer", "troublemaker", "big tipper", etc., that affect how your bartender responds to them.

Bar Tab Module

Defines responses related to bar tabs, tipping, and financial interactions. This includes responses for various tipping scenarios, tab-related situations, and payment interactions.

Key files:

• bartab/tips.json - Responses to tipping situations

Response categories: Responses for different tipping scenarios such as:

• User already has a tab (havetab)
• Trying to tip more than they have (morethanyouhave)
• Zero or very small tips (zero, tiny)
• Various tip sizes (small, medium, large, epic)

These responses help create realistic financial interactions and show your bartender's personality around money, generosity, and customer relationships.

System Messages Module

Defines system-level messages that the bot uses for operational communications. These include startup messages, system notifications, and other administrative communications.

Key files:

• system/systemmsgs.json - General system messages
• system/startupmsgs.json - Messages shown when the bot starts up

Usage: These messages are typically less character-focused and more functional, but they should still be written in your bartender's voice. Startup messages might announce the bar opening, while system messages handle technical notifications in-character.

Drinking Songs Module

Defines drinking songs, chants, and bar-themed musical content. These can be triggered for community singing activities and help create a lively, festive bar atmosphere.

Key files:

• drinkingsongs/songs.json - Song lyrics and metadata
• drinkingsongs/songs.ssml - SSML-formatted audio for text-to-speech

Structure: Each song includes lyrics, optional audio file references, and starter phrases that can trigger the song. Songs can be interactive, allowing users to participate in singing along.

Use cases: Creating festive moments, celebrating events, building community through shared activities. Songs should fit your bar's setting and atmosphere—a medieval tavern might have different songs than a spaceport bar.

Additional Optional Modules

There are other modules you might encounter or want to customize:

• counttoinfinity/ - Content for community counting challenges
• threeohthree/ - Special content for specific community activities
• birthday/ - Birthday celebration messages
• milestones/ - Milestone celebration content (server anniversaries, user achievements, etc.)
• calendar/ - Calendar event content

These modules are more specialized and may or may not be relevant to your personality. Reference the default Ratz personality pack to see examples of how they're used, and decide which ones fit your character and setting.

Basic Structure

Most JSON files in personality packs follow a simple key-value structure where keys represent different situations or categories, and values are arrays of possible response strings. The bot randomly selects from these arrays when the situation occurs.

Example format:

{
  "situation_key_1": [
    "First possible response",
    "Second possible response",
    "Third possible response"
  ],
  "situation_key_2": [
    "Response for situation 2",
    "Another response for situation 2"
  ]
}

Having multiple response options for each situation ensures variety and makes conversations feel more natural. The bot will randomly select from the available options each time.

Response Formatting

Response strings can include formatting and special placeholders:

• User placeholders: %s - Replaced with the user's name or mention
• Number placeholders: %d - Replaced with numeric values (reputation, amounts, etc.)
• Markdown formatting: Use markdown for emphasis, lists, etc. (e.g., *italic*, **bold**)
• Line breaks: Use \n for line breaks in responses

Example with placeholders:

{
  "greeting": [
    "Welcome back, %s! What can I get you?",
    "Good to see you again, %s. The usual?",
    "Hey %s! Haven't seen you in a while. \n\n*[%d reputation gained]*"
  ]
}

Module-Specific Formats

Some modules have more complex structures. For example:

• Menu items may include nested objects with name, description, price, category, etc.
• Mission files may have detailed structures with objectives, rewards, difficulty, etc.
• Performance files may define acts with success/failure conditions and responses

When creating these, reference the default Ratz personality pack files as examples. The structure is flexible, but certain fields may be expected by the bot's functionality.

Define Your Character

Before writing content, clearly define your bartender's character:

• Background: Where are they from? What's their history?
• Personality: What are their key traits? How do they interact with people?
• Speech patterns: How do they talk? What's their vocabulary and tone?
• Setting: What time period? What location? What's the world like?
• Boundaries: What will they do? What won't they do? What are their limits?

Create a style guide for yourself (like the Ratz STYLEGUIDE.md) to maintain consistency across all your content files.

Consistency is Key

Maintain consistency across all your content files. Your bartender should sound like the same person whether they're greeting someone, serving a drink, or commenting on the weather. Consistent speech patterns, vocabulary, and tone make the character believable.

Provide Variety

Include multiple response options for each situation. Even if your bartender has a catchphrase, provide 3-5 variations to avoid repetition. This makes interactions feel more natural and engaging over time.

Start Small, Expand Later

You don't need to write content for every module right away. Start with the core modules that create the most impact:

• Bar activity & user activity tracking - This creates the sense of attentiveness and presence that makes the bot feel alive
• Mood responses
• Basic greetings
• Menu items (at least a few)
• Basic conversation responses

Activity tracking should be a high priority because it's what makes your bartender feel present and aware of what's happening, rather than just reactive. Even a few well-written activity responses can dramatically improve the sense that the bot is "in the room" with everyone.

Once you have a working personality, you can gradually add more content to other modules. The bot will use default or fallback responses for modules you haven't customized yet.

Test and Iterate

Test your personality in a development environment. See how responses feel in context. Adjust tone, add more variety, and refine based on actual interactions. Creating a good personality is an iterative process.

Use the Ratz Pack as Reference

The default Ratz personality pack is a complete, working example. Study its structure, file organization, and content patterns. Use it as a reference for:

• Directory structure and organization
• JSON file formats and naming conventions
• Content organization within files
• How different modules interact