# Discord Integration

Defixus supports event webhooks and an optional shared, two-way Minecraft console in Discord. The console bot runs inside Minecraft: create your own Discord application, configure it on the server, and start Minecraft normally. No separate bot program, Docker, VPS or public HTTP endpoint is needed.

## Shared two-way console

The selected Discord text channel mirrors the server's runtime console. Everyone who can read the channel sees the commands, their authors, command responses and forwarded logs. Only explicitly authorized Discord users or roles can execute commands.

Authorized commands have full Minecraft server-console permissions, including commands such as `op`, mod administration commands and `stop`. Choose a private staff channel. The bot runs while Minecraft is running; after `stop`, start Minecraft using your usual server launcher.

Console permissions do not create a player entity. Defixus scans, downloads, statistics, panel and report navigation require a player in game. Console-compatible Defixus commands include `defixus list mods`, `defixus list packs`, `defixus hash defixus`, `defixus reload` and `defixus cleanup`; other mods apply their own command requirements.

### Two-way console: creating the Discord application

1. Open the [Discord Developer Portal](https://discord.com/developers/applications) and choose **New Application**. Use a dedicated application for this Minecraft server; do not run several Minecraft instances with the same bot token.
2. Open **Bot**, generate or reset the token, and save it privately. This is your own bot's credential. Do not send it in Discord, publish it, or include it in a client modpack.
3. Leave privileged intents disabled. Defixus uses slash commands and does not need Message Content, Server Members or Presence Intent. Leave **Interactions Endpoint URL** empty: Defixus receives interactions over the Gateway.
4. Under **Installation**, enable **Guild Install**. Create an installation link, or use **OAuth2 → URL Generator**, with the `bot` and `applications.commands` scopes.
5. Give the bot **View Channel** and **Send Messages** in the intended standard text channel, including its channel/category overrides. Administrator, Manage Webhooks, Manage Channels and Read Message History are not required by this implementation. Users must also be allowed to use application commands there.
6. Open the installation link and add the bot to your Discord server. The account performing this step needs permission to manage that server.

Discord provides the identity and token; Defixus provides the running bot. See Discord's [application setup](https://docs.discord.com/developers/quick-start/getting-started) and [Gateway interaction documentation](https://docs.discord.com/developers/interactions/overview).

### Configure Minecraft

1. Start Minecraft once with Defixus installed, then stop it. The optional console configuration is generated disabled.
2. Enable Discord's Developer Mode. Copy the IDs of your Discord server, console text channel, and the users or roles allowed to run console commands.
3. Edit `config/Defixus-anticheat/console/discord-bot.json`, replacing the placeholders in this example:

~~~json
{
  "enabled": true,
  "token": "PASTE_YOUR_OWN_BOT_TOKEN_LOCALLY",
  "guild-id": "YOUR_DISCORD_SERVER_ID",
  "channel-id": "YOUR_CONSOLE_TEXT_CHANNEL_ID",
  "allowed-user-ids": ["YOUR_DISCORD_USER_ID"],
  "allowed-role-ids": []
}
~~~

Replace the placeholders with real values. User and role IDs must be numeric Discord IDs, not names. At least one user or role must be authorized. Matching either an allowed user or an allowed role grants access. Discord Administrator permission alone does not grant Defixus console access.

Alternatively, set `DEFIXUS_DISCORD_BOT_TOKEN` in the Minecraft process environment and leave `token` empty. A nonblank environment value takes precedence over the file. For a simple setup, the local configuration file is sufficient.

4. Start Minecraft. Defixus connects in the background and registers `/defixus` in the configured Discord server. Wait until Minecraft has finished starting before sending commands.

The token stays on the Minecraft server and is never bundled in the distributed mod or sent to Minecraft players. Anyone with access to the server's files or process environment can access its credentials; protect that access.

### Use the console

In the configured channel, use:

~~~text
/defixus console command:list
/defixus console command:say Server restart in five minutes
/defixus console command:defixus list mods
/defixus status
~~~

Select the command from Discord's slash-command menu and enter the Minecraft command in its `command` option. A leading Minecraft slash is optional. Ordinary chat messages are not executed. The former `!` prefix is no longer used; an existing `command-prefix` field is ignored.

Accepted commands receive a public acknowledgement containing the author and command. The response is public in the same channel, including syntax errors. Long responses are split into plain-text code blocks; asynchronous responses appear as labelled continuations. Commands with no immediate response say so explicitly. Attempts from unauthorized users or the wrong channel are rejected privately.

The token known to Defixus is masked in console output and automatic mentions are disabled. Other installed mods can still log sensitive information, so channel membership must match who may read your server logs.

### Delivery and lifecycle

- Log4j messages at `INFO` and above are forwarded, including warning/error stack traces from Minecraft and loaded mods. `DEBUG` and `TRACE` are excluded.
- Forwarding begins during server startup; earlier loader/bootstrap messages are not captured.
- Log lines are grouped, with at most one log batch every two seconds. Queues are bounded and dropped output is reported when possible.
- Direct command output is limited to 32,768 UTF-16 code units per immediate response. Full immediate output is recorded in Minecraft's local log; later asynchronous output is delivered separately.
- Network failures do not stop Minecraft. Defixus reconnects automatically and rejects stale or duplicate command deliveries. Commands are not replayed after reconnection.
- If a connection fails after execution, inspect the local Minecraft log before repeating an administrative command.
- Restart Minecraft after changing bot settings. `/defixus reload` does not reload the bot.

Set `enabled` to `false` and restart Minecraft to disable the bot. Reset a leaked token in the Developer Portal and update the local configuration before restarting.

## Event notifications

Event webhooks remain independent of the console bot. Configure `config/Defixus-anticheat/discord/webhook.json`:

~~~json
{
  "enabled": false,
  "fancy-webhooks": false,
  "command_tracking": {
    "enabled": true,
    "commands": {
      "gamemode": "",
      "give": "https://discord.com/api/webhooks/REPLACE_LOCALLY"
    }
  },
  "events": {
    "command_dispatch": {"enabled": true, "url": ""},
    "player_join": {"enabled": true, "url": ""},
    "server_start": {"enabled": true, "url": ""},
    "server_stop": {"enabled": true, "url": ""}
  }
}
~~~

Use actual generated webhook URLs locally. Available events are `player_join`, `operator_join`, `operator_change`, `command_dispatch`, `player_kick`, `mod_warnings`, `pack_warnings`, `pack_changes`, `server_start` and `server_stop`.

For ordinary event alerts, enable the global switch and event switch and set that event's URL. Command alerts additionally require `command_tracking.enabled` and a listed command name; a nonempty per-command URL is sufficient even when the general command event URL is blank. An empty command URL uses `events.command_dispatch.url`. Event command alerts cover player-issued commands; Discord console activity is shown in the shared console.

`player_join` is sent after successful ordinary verification; automatic Owner/Moderator join bypasses use `operator_join`. Permission-only join bypasses do not emit either join event. `player_kick` also covers online Mustlist failures routed through the verification kick handler. Configuration-phase preparation failures are not all recorded as kick alerts. Pack-change alerts follow the applicable verification path; staff bypasses return before the ordinary pack-change alert. There is no player-quit event key in the current event schema.

`fancy-webhooks` adds statistics/hash details where supported. Event messages use the server language from `verification/settings.json`, with English fallback. Restart after changing webhook configuration.

## Optional one-way console webhook

For forwarding without commands, configure `config/Defixus-anticheat/console/discord-webhook.json`:

~~~json
{
  "enabled": false,
  "webhook-url": ""
}
~~~

Provide an HTTPS Discord webhook URL and enable this option to forward runtime console logs only. The personal bot takes precedence when enabled. An invalid or disconnected bot does not automatically switch to the console webhook. Event webhooks remain independent.

## Troubleshooting and older configurations

- **Bot offline:** confirm Minecraft is running, the bot is enabled, the token is valid and outbound Discord connections are permitted.
- **No slash commands:** check the guild ID, the invitation's `applications.commands` scope and the user's permission to use application commands. Reopen Discord after registration.
- **Channel unavailable:** use a standard text channel in the configured guild and grant the bot View Channel and Send Messages, including category/channel overrides.
- **Access denied:** check numeric user/role IDs. Being able to read the channel or having Discord Administrator permission does not replace the configured access list.
- **Logs or output missing:** check Minecraft's local log and any dropped-output notice. A noisy server can produce logs faster than Discord can display them.