> For the complete documentation index, see [llms.txt](https://axiomemu.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://axiomemu.gitbook.io/docs/bridgeserver/bridgeserver.md).

# Overview

BridgeServer exports live gameplay events to your website, bots and Discord

BridgeServer is a read-only events server. Your GameServer reports what happens in the world, BridgeServer stores it, streams it, and announces it in Discord - and serves rankings and profiles from the game database over a plain HTTP API.

It is an optional component. Your server runs perfectly without it.

{% hint style="info" %}
Bridge is a paid add-on. The `axiom-bridge` module must be on your license: without it BridgeServer refuses to start and the GameServer-side [Bridge plugin](/docs/data/plugins/bridge.md) stays inert.
{% endhint %}

## Role

* Accepts event pushes from one or more GameServers, authenticated with a shared key
* Keeps a rolling history of events in its own database file
* Streams events live to any number of subscribers
* Serves rankings, character and guild profiles, castle siege state and population from the game database, read-only
* Optionally relays announcement-worthy events to a Discord webhook

## Read-Only by Contract

BridgeServer has no path back into the game. Nothing it exposes can create an item, move a character, or write to the game database. The GameServer connects **outward** to BridgeServer, so BridgeServer needs no route into your game network, and BridgeServer being down, restarting or unreachable cannot stall or crash your server.

Events produced while BridgeServer is unreachable are lost rather than queued. A Bridge outage is a gap in the feed, never a gap in the game.

## File Location

```
BridgeServer/
├── BridgeServer.exe
├── BridgeServer.ini
├── bridge.db          (created on first run)
└── Log/
    └── YYYY-MM-DD.txt
```

All configuration lives in the BridgeServer root. There is no `Data/` subfolder.

## Configuration Files

| File                                                         | Purpose                                                           |
| ------------------------------------------------------------ | ----------------------------------------------------------------- |
| [`BridgeServer.ini`](/docs/bridgeserver/bridgeserver-ini.md) | Ports, shared key, Discord webhook, game database access, license |
| [`Config.xml`](/docs/data/plugins/bridge.md)                 | GameServer side - which events are exported                       |

## Ports

| Port   | Default | Faces                                             |
| ------ | ------- | ------------------------------------------------- |
| Ingest | `55980` | Your GameServers only. Never expose this publicly |
| HTTP   | `55981` | Your website, bots and dashboards                 |

## Startup Order

{% stepper %}
{% step %}

### License activation

Reads `LicenseKey` from `BridgeServer.ini` and checks for the `axiom-bridge` module. Failure aborts startup.
{% endstep %}

{% step %}

### Open the history store

Opens (or creates) `bridge.db` next to the executable.
{% endstep %}

{% step %}

### Start the Discord relay

Skipped when `DiscordWebhookUrl` is empty.
{% endstep %}

{% step %}

### Connect to the game database

Skipped when `MuDbODBC` is empty; ranking and profile endpoints then return 503.
{% endstep %}

{% step %}

### Open the ingest and HTTP ports

Both must bind successfully or startup aborts.
{% endstep %}
{% endstepper %}

## Dependencies

* At least one GameServer with the [Bridge plugin](/docs/data/plugins/bridge.md) enabled and pointed at this host
* Optional: an ODBC data source for the game database, for rankings and profiles
* Optional: a Discord webhook URL for the built-in relay
* A firewall that keeps the ingest port private, and exposes the HTTP port only as far as you actually need

## The History Store

`bridge.db` holds exported events for the history endpoint. It is telemetry, entirely separate from your game database, and is safe to delete - you lose event history, nothing else. It grows with your event volume, so a server exporting all chat and every monster kill will grow it far faster than one exporting only announcements.

Population and event-schedule gauges are snapshots, not history: they are cached and streamed live, never written to the history store or relayed to Discord.

## Discord Relay

Set `DiscordWebhookUrl` and the announcement-worthy events - player kills, boss kills, rare drops, resets, event starts and winners, shop sales, sell posts, chaos results and global posts - are posted as embeds, batched to respect Discord's rate limits.

`DiscordRelayAll=1` mirrors **everything**, including logins, chat, trades and monster kills. That is a demonstration mode, not a production setting.

For real deployments the usual pattern is the other way round: read the [HTTP API](/docs/bridgeserver/api.md) from your own bot and route events to whichever channels you like, with your own formatting.

## Logs

`Log/YYYY-MM-DD.txt` is appended throughout the day, with a new file on the first event after the local date changes. Old log files accumulate; archive or delete as needed.

## Common Issues

* **BridgeServer exits at startup** - license key missing or invalid, or the `axiom-bridge` module is not on the license
* **No events arrive** - the GameServer plugin is disabled, points at the wrong host or port, or the shared keys differ
* **Rankings and profiles return 503** - `MuDbODBC` is empty, the data source name does not exist on this machine, or the first refresh has not completed yet
* **Nothing appears in Discord** - `DiscordWebhookUrl` is empty or the webhook was deleted; check the log for delivery failures
* **`bridge.db` is growing fast** - chat export or monster-kill export is on

## Related

* [BridgeServer.ini](/docs/bridgeserver/bridgeserver-ini.md) - ports, shared key, Discord, database, license
* [HTTP API](/docs/bridgeserver/api.md) - endpoints for your website and bots
* [Bridge Config.xml](/docs/data/plugins/bridge.md) - GameServer side: what gets exported