Discord Dicebot

Discord slash-command dice bot for TRPG play. The current codebase is split into:

• contracts/ for gateway/app-server request, response, and catalog DTOs
• core/ for domain, use cases, presenters, text registry, sheet access, and SQLite infrastructure
• app-server/ for internal HTTP APIs and command execution
• gateway/ for Discord Gateway connectivity, slash command sync, and command proxying

Commands

The bot uses Discord slash commands, not a legacy ! prefix.

• /rhelp shows the full command list
• /rhelp <command> shows detailed help for one command
• /r, /ra, /rd, /rl, /rt, /rw handle general dice and aliases
• /ruse, /rr, /rstat, /rdel, /rccc handle CoC sheet registration and rolls
• /rdnd generates DnD ability scores

Localized command/help text is loaded from resource files such as src/main/resources/command-text/ko_kr.yml.

Configuration

Required:

• Discord bot token:
  • -Ddicebot.token=...
  • DICEBOT_TOKEN

Google Sheets credentials:

• -Ddicebot.google.credentials=/path/to/google-service-account.json
• DICEBOT_GOOGLE_CREDENTIALS=/path/to/google-service-account.json

The Google service-account credential path must be configured explicitly. The runtime does not auto-discover credential files by name.

Optional runtime settings:

• app-server base URL for the gateway:
  • -Ddicebot.app-server.base-url=http://127.0.0.1:8080
  • DICEBOT_APP_SERVER_BASE_URL=http://127.0.0.1:8080
• app-server port:
  • -Ddicebot.app-server.port=8080
  • DICEBOT_APP_SERVER_PORT=8080
• shard count:
  • -Ddicebot.shards=...
  • DICEBOT_SHARDS
• SQLite path:
  • -Ddicebot.sqlite.path=...
  • DICEBOT_SQLITE_PATH
• command text locale:
  • -Ddicebot.command-text.locale=ko_kr
  • DICEBOT_COMMAND_TEXT_LOCALE=ko_kr
• command executor settings:
  • -Ddicebot.command.parallelism=...
  • DICEBOT_COMMAND_PARALLELISM
  • -Ddicebot.command.queue-capacity=...
  • DICEBOT_COMMAND_QUEUE_CAPACITY
• sheet hot cache size:
  • -Ddicebot.sheet.hot-cache-size=...
  • DICEBOT_SHEET_HOT_CACHE_SIZE
• environment label for logs and telemetry:
  • -Ddicebot.environment=production
  • DICEBOT_ENVIRONMENT=production
• gateway New Relic health publishing:
  • -Ddicebot.health.publish.enabled=true
  • DICEBOT_HEALTH_PUBLISH_ENABLED=true
  • DICEBOT_APP_READY_URL=http://127.0.0.1:8080/internal/v1/health/ready
  • DICEBOT_HEALTH_PUBLISH_INTERVAL_SECONDS=60
  • DICEBOT_HEALTH_PUBLISH_TIMEOUT_SECONDS=2
  • DICEBOT_HEALTH_EVENT_TYPE=DicebotHealthCheck

New Relic is optional. If the Java agent is attached with JAVA_TOOL_OPTIONS=-javaagent:/path/to/newrelic.jar, the gateway can publish DicebotHealthCheck custom events for app-server readiness and shard health. The deployment workflow can install and verify the Java agent when DICEBOT_NEW_RELIC_ENABLED=true; without the agent, the New Relic API calls are no-ops.

Use separate DICEBOT_ENVIRONMENT, NEW_RELIC_APP_NAME, NEW_RELIC_LABELS, and component-specific NEW_RELIC_LOG_FILE_NAME values for production and staging. For example, keep dicebot-gateway-production and dicebot-gateway-staging as separate New Relic applications, and filter health alerts by environment.

Build And Test

bash ./gradlew test
bash ./gradlew build

Run

After building, start the app-server first and then the gateway:

java -Ddicebot.sqlite.path=.local/state/dicebot.db -Ddicebot.google.credentials=.local/credentials/google-service-account.json -jar app-server/build/libs/app-server-<version>.jar
java -Ddicebot.token=... -Ddicebot.app-server.base-url=http://127.0.0.1:8080 -jar gateway/build/libs/gateway-<version>.jar

Deployment files and public troubleshooting notes live under deploy/.

Google Sheets Notes

CoC sheet registration currently accepts these URL styles:

• .../edit#gid=2107011865
• .../edit?gid=2107011865#gid=2107011865
• .../edit?gid=2107011865

If a URL does not include gid, the slash command can fall back to an explicit sheet tab name.