Skip to content

Setup

Jump to bottom
filloax edited this page Aug 10, 2026 · 3 revisions

Setup

Apibalego connects Minecraft to a gamemaster web server. The server polls the web server periodically for data (HTTP polling), and can optionally keep a real-time connection (WebSocket). All gameplay features controlled through this system depend on what the connected mods register as API entries.

Caution

Only connect to trusted sources. A connected gamemaster server can send commands, load datapacks, and control mod features in your world.

Requirements

Gamemaster web server

Apibalego needs an external web server to connect to. It reads data from a configurable endpoint on that server.

Egobalego at Home is a ready-made gamemaster web app you can run locally. Download it from its releases page and run the start script. The first launch installs dependencies automatically and opens the console in your browser.

Configuration done in that console is what the mod reads. Refer to its own documentation for how to set up entries.

See Gamemaster Server for more details.

Enabling HTTP polling

HTTP polling periodically fetches data from the gamemaster server. The mod sends a GET request to <dataSyncUrl>/<dataSyncEndpoint> on a configurable interval.

  1. Open the config (in-game mod menu, or config/apibalego.jsonc).
  2. Set dataSyncUrl to the address of your gamemaster server (e.g. http://my-ngrok-url.ngrok.io).
  3. Set webDataSync to true.
  4. Reload the world for changes to take effect.

Alternatively, if you have op, use in-game commands:

/gmaster url <url>
/gmaster enable

The mod caches the last successful response in world save data. If the server is unreachable on startup, the cached response is replayed so existing entries still apply.

Enabling WebSocket live updates

The WebSocket connection allows the gamemaster to push updates in real time instead of waiting for the next poll cycle. It uses Socket.IO

Warning

NeoForge: live updates may be broken depending on version

  1. Set liveUpdateUrl to the gamemaster server address.
  2. Set liveUpdateService to true.
  3. Reload the world.

The WebSocket and HTTP polling are independent. Both can be active at the same time (recommended, so the mod loads existing state on world start via polling, then receives real-time updates via WebSocket).

Client-side connection

Apibalego can also connect on the client side, independently of any server. This allows the gamemaster to show toasts or change the main menu splash text even from the main menu, and especially download Resource packs (if enabled) before joining a world.

  1. Set clientDataSyncUrl to the address of your gamemaster server.
  2. Set clientDataSync to true.

The client polls a separate endpoint (clientDataSyncEndpoint, default client_data) from the server-side endpoint. The client-side connection supports its own set of API entries.

Clone this wiki locally