Character Selection System¶

This document outlines the architecture for the character selection system in StingbatBot, which allows Discord users to select and manage their active characters in different contexts.

Overview¶

The character selection system allows users to: - Select different characters at different context levels (channel, guild, global) - Have context-specific character selections for different scenarios - Retrieve their most relevant character based on the context hierarchy

Hierarchical Selection¶

The system uses a hierarchical approach that allows users to have different character selections at different levels:

Channel Level (most specific): Character selected for a specific channel within a server
Guild Level (intermediate): Character selected for an entire Discord server
Global Level (least specific): Default character selection when no context is specified

When retrieving a selected character, the system checks from most specific to least specific context: 1. Check for a channel-specific selection 2. If none exists, check for a guild-specific selection 3. If none exists, check for a global selection 4. If none exists, return an appropriate error or prompt

This hierarchical approach allows users to have different characters for different activities while minimizing the need to constantly change selections.

Data Model¶

Schema Layer¶

The Schemas.UserSettings module defines the database structure for user settings:

A user_settings table with columns:
user_id (primary key): The Discord user ID
selected_character_id: Foreign key to the characters table
guild_id: Optional guild context identifier
channel_id: Optional channel context identifier
Timestamp fields for tracking creation and updates

This schema maintains a many-to-one relationship between settings entries and characters, with context identifiers as part of the compound key.

Context Layer¶

The Contexts.Users module handles database operations for user settings:

Getting user settings by user ID and context
Creating new user settings records
Updating existing user settings
Handling the relationship between users and their selected characters

The context module ensures that user settings are properly persisted and retrieved from the database.

Service Layer¶

The Settings module provides business logic for character selection:

select_character/4: Selects a character for a user at a specific context level
get_selected_character/3: Retrieves the most specific character selection
clear_selected_character/3: Removes a character selection
get_hierarchical_settings/3: Implements the context hierarchy lookup

Implementation Details¶

Character Selection Validation¶

Before a character can be selected, the system performs validation: 1. Checks that the character exists 2. Verifies that the character belongs to the user making the selection 3. Checks that the character name is unique for that user (as characters are identified by user_id and name) 4. If validation passes, creates or updates the user settings entry

Context Hierarchy Resolution¶

The system implements a hierarchical resolution strategy where: - The most specific context (channel level) is checked first - If no selection exists at that level, it falls back to the guild level - If no selection exists at the guild level, it falls back to the global level - The first valid selection found in this hierarchy is returned

Default Parameters for Optional Contexts¶

The system uses empty string defaults for optional context parameters, allowing for simplified API calls when certain context levels aren't relevant.

Character Reference Integrity¶

The system maintains referential integrity with characters: 1. Uses foreign key constraints to ensure selections reference valid characters 2. Handles character deletion gracefully by treating the selection as empty 3. Returns appropriate errors when selected characters cannot be found

Integration with Commands¶

The character selection system integrates with Discord commands:

The character <name> command selects a character in the current context
Commands like sheet and detail use the selected character by default
Context-specific commands provide ways to override the selection

Usage Scenarios¶

Selecting a Character¶

Users can select characters at different context levels: - For the current channel specifically - For the entire guild (applies to all channels without channel-specific selections) - Globally (applies anywhere the user doesn't have more specific selections)

Retrieving a Selected Character¶

When a user invokes a command that needs a character: 1. The system determines the current context (channel and guild) 2. It retrieves the most specific character selection for that context 3. If a character is found, it's used for the command 4. If no character is found, the user is prompted to select one

Clearing a Selection¶

Users can clear their character selections at any context level: - Clear only the channel-specific selection - Clear the guild-level selection - Clear the global selection

Implementation Status¶

The character selection system is fully implemented with:

✅ Database schema and migrations
✅ Context functions for CRUD operations
✅ Service layer for business logic
✅ Command interfaces for Discord interaction
✅ Hierarchical context resolution
✅ Integration with character commands