RetroBot

Official Discord bot for RetroRealm. Exposes Playmatch as Discord slash commands so users can identify ROMs, browse matched companies and platforms, and submit metadata suggestions without leaving Discord.

Every response is rendered with Discord's Components V2 (top-level Container, TextDisplay, Separator, ActionRow). No classic embeds.

Features

Supported

• /list companies and /list platforms with paginated tables
• /get game <hashes|name+size> for a full Playmatch metadata card (matched platform, company, ROM files, DAT file, provider mappings)
• /suggest game|company|platform with owner approval buttons and an outcome DM back to the submitter
• /match game|company|platform for manual metadata matching, restricted to bot owners and trusted roles
• /toggle_update role toggle for the RetroRealm guild
• /ping and a custom /help
• Components V2 flag (IS_COMPONENTS_V2) on every outgoing message

Planned

• Pin serenity and poise back to released crates.io versions once a Components V2 release ships
• Expose further Playmatch endpoints as commands as they stabilise

Getting Started

Prerequisites

1. Rust 1.95+ from here
2. A Discord bot token. Create an application at the Discord Developer Portal, enable a Bot user, and use the applications.commands scope when inviting it
3. Access to a Playmatch instance. The public one at playmatch.retrorealm.dev works, or self-host from RetroRealm/playmatch

Development

1. Clone the repository
2. Create a .env in the repository root with the variables below
3. Run cargo run (debug) or cargo run --release

Environment variables

Variable	Required	Purpose
DISCORD_TOKEN	yes	Bot token from the Discord Developer Portal
PLAYMATCH_API_AUTH	yes	Bearer token for the Playmatch API
PLAYMATCH_API_URL	no	Playmatch host URL, defaults to https://playmatch.retrorealm.dev. The bot appends the /api/v2 base path.
REDIS_URL	yes	Redis connection string (e.g. redis://localhost:6379), used to persist posted suggestion cards across restarts
DISCORD_STATUS	no	Activity kind (playing, listening, watching, competing)
DISCORD_STATUS_NAME	no	Activity text shown next to the kind
DISCORD_RETROREALM_SERVER_ID	for guild commands	Guild id used when registering guild-scoped commands
DISCORD_RETROREALM_STAFF_ROLE_ID	no	Role id that bypasses trusted-role checks
DISCORD_TRUSTED_ROLE_IDS	no	Comma-separated role ids allowed to run /match
DISCORD_RETROREALM_UPDATE_ROLE_ID	no	Role id toggled by /toggle_update
DISCORD_RETROREALM_SUGGESTION_CHANNEL_ID	no	Channel id where suggestion review cards are posted

Regenerating the playmatch client

The playmatch_client crate is generated with cargo-progenitor 0.14 from the checked-in spec. The pristine spec breaks progenitor in two places (operations with more than one error payload type, and object-typed query parameters), so it is normalized first:

1. Fetch the current spec to resources/playmatch-openapi.json.
2. python scripts/normalize_openapi.py resources/playmatch-openapi.json /tmp/playmatch-normalized.json
3. cargo progenitor -i /tmp/playmatch-normalized.json -o playmatch_client -n playmatch_client -v 0.2.0 --interface builder --license-name MIT --include-client true

progenitor 0.14 emits the builder module's imports as use super::types;. After regenerating, change that one line in playmatch_client/src/lib.rs to use super::{progenitor_client, types}; so the included client code resolves. This is the only manual edit; never change playmatch_client/ otherwise.

Deployment

Docker images are available here at ghcr.io/retrorealm/retrobot.

Built With

• Rust - the programming language used
• tokio - async runtime
• serenity - Discord API client (next branch, for Components V2)
• poise - command framework on top of serenity (serenity-next branch)
• reqwest - HTTP client
• progenitor - generator for the in-tree playmatch_client crate

Contributing

Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.

Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

Authors

• DevYukine - Initial work - DevYukine

See also the list of contributors who participated in this project.

License

This project is licensed under the MIT License - see the LICENSE.md file for details

Acknowledgments

• Playmatch - the backing API this bot is built around
• serenity / poise - the Discord framework