O Waylords is a Discord bot for roleplay server founders and members, focused on reducing admin overhead while improving scene flow, character tracking, and server presentation.
This README is the current single source of truth for:
- Functional requirements gathered so far
- What is already implemented
- What is still missing
- Progress toward core milestones
- High-fit RP features to add next
- Build a dashboard-first RP bot experience with strong admin visibility and controls
- Standardize server setup with community-aware templates and safe migration options
- Move character management to server-owned records with approval-based moderation workflows
- Deliver flexible scene registration and turn systems with configurable strictness
- Provide immersive roleplay presentation tools for embeds, lore, and location context
- Keep rich sheet authoring native to Discord workflows without external sheet/docs APIs
- Python 3.13+
- discord.py 2.6+
- MongoDB (via
pymongo) for character storage - python-dotenv for environment configuration
See PROJECT_PLAN.md for the complete sequential feature implementation plan (32 features over 25–32 weeks).
/use_template <code>- Pulls a Discord server template by code
- Asks for confirmation by reaction
- Rebuilds channels/roles/settings via template parser
- Preserves command channel and bot suite channels
/register_character <name> <link> <photo>- Creates and stores a character in MongoDB
/my_characters- Shows the caller's characters with pagination
/view_character <name>- Public character lookup by name
/edit_character <name> [new_name] [new_link] [new_photo]- Allows owner to update character data
/delete_character <name> [user]- Members can delete their own characters
- Admins can delete another user's character
/user-characters <user>(admin-only)- Shows a specific user's server characters
- Restricted to bot suite channels for controlled visibility
- On startup and on guild join, ensures a private Bot Suite category exists:
O Waylords Bot Suitebot-logsbot-commands
- Initializes MongoDB connection on ready
Each requirement is listed in one place only.
- The bot will include an online dashboard.
- The dashboard will include an admin-only character index for each server.
- Character index entries will be shown as sortable cards.
- Dashboard actions will generate audit events (viewer, action type, target entity, timestamp).
- Server owner can delete all stored data for a specific user with one command.
- Trusted-admin model:
- Users with Discord Administrator permission are auto-trusted.
- Owner can manually trust additional users for bot admin actions.
- Onboarding automations are configurable and designed to work with community server setup.
- On guild join, bot recommends community server setup flow.
- A persisted server variable tracks whether the guild is using a custom template.
- Sensitive administrative actions (trust changes, user data purge, onboarding policy edits) must be audit logged.
- Central built-in templates will be maintained from your example servers.
- Template choice flow is community-aware and explicitly communicates community mode.
- If community mode is enabled, bot can add community-focused channels (for example forums and announcements).
- Command user can protect selected channels/categories during template apply.
- Command user can choose archive-old-channels instead of delete-old-channels.
- Channels can be designated with type labels: roleplay, lore, or social.
- Scene registration is blocked in social-designated channels.
- Designations can auto-apply permissions when using built-in templates.
- If server is using a custom template, designation logic will not overwrite permissions.
- Template apply, archive, protect, and designation changes must write structured audit logs.
- Registry mode can be selected per server:
- Built-in character template
- Docs-based template storing name, link, photo, and tags
- Servers can define custom tags used for character filtering and search.
- Characters are server-owned records, not user-owned records.
- Users submit character entries in designated submission channels.
- New character submissions create approval tickets in the bot suite for admin review.
- Admins can request edits before approval.
- Optional admin toggle:
- Users can edit character records only through admin approval flow.
- Admin authority model:
- Admins can delete any character.
- Users request deletions; admins execute deletion.
- Character records persist creator user ID even if creator leaves the server.
- When a user leaves, admins receive a notification with an optional command to remove all user-associated stored data.
- Registry should support future custom built-in templates defined by list items plus datatype declarations in Discord markup or markdown blocks.
- Each character token stores an edit history log.
- Character relationship links are supported:
- A user can create relationships automatically between their own characters.
- Cross-user relationships require a request flow and acceptance by the other user.
- A unified request queue will be used for moderation workflows, including character approvals, edit requests, deletion requests, and cross-user relationship requests.
- Character create/approve/edit/delete and relationship actions must be written to audit logs.
- Long-term optional systems include leveling, inventory, and custom stat blocks.
- Scenes can be registered without approval.
- Optional GM designation can be enabled per server to control scene-start permissions.
- Server policy can choose one of two modes:
- Any regular roleplayer can start scenes.
- Only designated GMs and admins can start scenes.
- Scene registration includes:
- Involved characters
- Turn order mode (if enabled)
- Scene tags and metadata
- Turn order supports initiative modes with no GM dependency:
- Randomized order
- Command-user chosen order
- Stat-based order when relevant character stats are available
- Admins can create scene tag definitions for metadata categorization.
- Scene registration posts a metadata embed in-channel and stores that message ID for jump links.
- Scenes support addenda events (for example location jumps and character additions) persisted in scene metadata.
- Admins can configure turn strictness levels, including no-turn-order mode.
- Strict modes can enforce timeouts, reminders, and auto-skip behavior.
- Turn prompts are sent as user-specific visible messages in the channel.
- Users can skip their own turn via reaction on the turn prompt.
- Bot provides RNG dice commands for roleplay rolls only.
- Scene lifecycle events, turn actions, and GM policy changes must be audit logged.
- A checks framework is explicitly out of current scope.
- Dashboard includes an embed composer for admins.
- Dashboard includes a lore codex manager for searchable world entries.
- Embed composer supports:
- Message content
- Custom author identity (name plus profile image)
- Selected-user persona mode
- Content-related image
- These embeds are intended for announcements, lore channels, and similar presentation use.
- Roleplay channel designation can optionally include a location image used by scene registrations in that location.
- RP channels support IC and OOC overlays to separate in-character and out-of-character messaging context.
- Non-AI RP quality assist is in scope as an encoded, rule-based validation system that admins can configure.
- Embed publishing, lore codex updates, and RP quality-rule edits must be audit logged.
- No API integration with Google Sheets, Google Docs, or similar external docs tools for rich sheet authoring.
Progress values are based on current code in this repository.
- Core MVP progress: 27%
- Data persistence foundation: 78%
- Admin and RP systems beyond character CRUD: 12%
- Done
- Product scope and dashboard requirements are documented.
- Missing
- Online dashboard implementation
- Admin-only sortable character card view
- Dashboard embed composer UI
- Dashboard lore codex manager
- Dashboard action audit event stream and viewer filters
- Done
- Template application command exists
- Role/channel/category recreation implemented
- Guild settings update implemented
- Bot suite auto-provisioning implemented
- Missing
- Built-in template catalog sourced from example servers
- Community-aware setup recommendations on guild join
- Community-mode channel automation (forums/announcements)
- Built-in preset templates selector flow
- Keep/replace/archive branching and protected channel/category controls
- RP channel designation and management tooling
- Lore/social/roleplay designation enforcement rules
- Custom-template safety rule (no permission overwrite)
- Template apply and channel-policy audit logs
- Robust error recovery + rollback strategy
- Done
- Register, view, edit, delete flows
- Admin view into user character data
- Pagination UI for longer lists
- MongoDB persistence and retrieval helpers
- Missing
- Server-owned character model migration (from user-owned flows)
- Admin-configurable character schema per guild
- Submission-channel and approval-ticket workflow
- Admin approval gating for edits/deletions
- Unified request queue (approvals, edits, deletions, relationship requests)
- Relationship request/accept flow across users
- Leave-event admin notification with one-command user data purge option
- Versioning/status model for character sheets
- Tag definitions and server-level filtered search
- Character moderation and relationship action audit logs
- Done
- Requirement set is defined, including GM-optional start policies.
- Missing
- Scene create/join/close lifecycle
- GM designation and scene-start permission mode controls
- Turn engine with initiative modes (random/chosen/stat-based)
- Turn engine with queue, timeout, reminders, and auto-skip
- Optional permission gating by active turn
- Scene metadata embed generation and stored jump-link message IDs
- Scene addenda tracking (location jumps, added characters)
- RNG dice command set (without checks framework)
- Scene lifecycle and turn-action audit logs
- Done
- Bot suite channels created for command/log organization
- Missing
- Owner-trusted-admin allowlist commands
- Automatic trust for Discord Administrator permission holders
- Welcome/leave automation commands and templates
- Welcome/leave toggles and message templates
- Community-setup onboarding guidance and configuration
- Owner command to delete all data for one user
- Trust, onboarding, and data-purge audit logs
- Done
- Requirements defined for IC/OOC overlays and non-AI quality assist.
- Missing
- IC/OOC overlay implementation and channel behavior rules
- Rule-based RP quality assist engine editable by admins
- Roleplay channel location-image registration and scene integration
- Lore codex entry management and search behavior
- Embed/lore publishing and quality-assist rule-change audit logs
- Current state
admin.pyexists but has no implementation
- Needed
- Central admin control commands and settings surfaces
These are ideas intentionally left out of the active scope for now.
- Character condition tracker
- Status effects, injuries, buffs/debuffs, cooldowns, and timers
- Narrative prompt engine
- Optional random event cards, environment prompts, and conflict hooks
- Scene recap generator
- End-of-scene summary from key turns and tagged events
- Full checks framework
- Structured skill/stat checks beyond basic RNG dice rolling
- AI-assisted writing or quality tooling
- Deferred until explicitly desired
Required for runtime:
BOT_TOKENMONGO_URIMONGO_DB_NAME(optional, defaults toowaylords_db)