Online Editor

Overview

mineHud ships with an online editor (tree/form editor, visual canvas, YAML IO). The plugin does not host the website. The UI and session relay are hosted by mineCodes (or your own Docker stack). The plugin only:

1. Creates a session and uploads a config snapshot
2. Keeps an outbound WebSocket open for apply events
3. Writes the applied config and reloads the HUD

Flow

/minehud editor
    │
    ├─ POST session snapshot ──► relay (HTTP)
    ├─ outbound WebSocket   ──► relay (WS)
    └─ chat link            ──► https://hud.mncd.pl/?session=...&secret=...

Browser editor
    ├─ GET session YAML
    ├─ WS role=editor
    └─ Save ── apply event ──► plugin applies config + reload

Plugin Configuration

editor-bridge:
  enabled: true
  editor-base-url: "https://hud.mncd.pl"
  api-base-url: "https://hud.mncd.pl/api"
  ws-base-url: "wss://hud.mncd.pl/api"
  timeout-seconds: 15

Option	Description
enabled	When false, /minehud editor reports the editor as disabled
editor-base-url	Browser UI origin (no trailing slash)
api-base-url	Relay HTTP API base
ws-base-url	Relay WebSocket base (wss:// in production behind TLS)
timeout-seconds	HTTP timeout for session create/upload

Usage

1. Ensure editor-bridge.enabled is true and URLs are correct
2. Run /minehud editor (permission minehud.command.editor)
3. Open the link from chat
4. Edit panels in the tree/form UI or on the canvas
5. Click Zapisz na serwerze — the plugin receives the apply event and reloads

The editor shows a pack-impact badge when changes require a full resource pack regeneration.

Production (mineCodes)

Default URLs point at the hosted stack:

Service	URL
Editor UI	https://hud.mncd.pl
API (HTTP)	https://hud.mncd.pl/api
API (WebSocket)	wss://hud.mncd.pl/api

No extra plugin setup is required beyond a working network path from the game server to the relay.

Self-hosted Docker

From the mineHud repository root:

docker compose up -d --build    # local: http://localhost:8080

Production images (Artifact Registry):

docker compose -f docker-compose.prod.yml pull
docker compose -f docker-compose.prod.yml up -d

nginx in the editor image:

• Serves the SPA from /
• Proxies /api/* to the relay (including WebSocket)

Put the stack behind a TLS reverse proxy (e.g. hud.mncd.pl → host WEB_PORT).

Plugin config for Docker on the same host:

editor-bridge:
  enabled: true
  editor-base-url: "http://127.0.0.1:8080"
  api-base-url: "http://127.0.0.1:8080/api"
  ws-base-url: "ws://127.0.0.1:8080/api"

Local Development

Terminal 1 — relay:

cd editor/relay
npm install
npm start
# http://127.0.0.1:18927

Verify:

curl -i http://127.0.0.1:18927/health
# response should include header: X-MineHud-Relay: minehud-relay

Terminal 2 — SPA:

cd editor
npm install
npm run dev

Plugin config:

editor-bridge:
  enabled: true
  editor-base-url: "http://127.0.0.1:5173"
  api-base-url: "http://127.0.0.1:18927"
  ws-base-url: "ws://127.0.0.1:18927"

Preview Coordinate Model

The canvas matches the in-game 480×270 GUI model:

• Text top edge ≈ anchorY + pixelY
• Line left edge ≈ anchorX + pixelX - 1 (boss-bar advance correction)
• Background is drawn slightly above the text (padding-aware)

Use the editor Debug checkbox and /minehud debug in-game to compare pixel metrics.

Troubleshooting

Issue	What to check
“Editor disabled”	editor-bridge.enabled: true
Open failed / timeout	api-base-url reachable from the game server; relay running
Link opens but save does nothing	WebSocket URL (ws-base-url / wss:// behind TLS); plugin still online
Wrong preview vs game	Compare /minehud debug with editor Debug overlay
Port already in use locally	Free 18927 / 5173 / 8080 or change ports

Server logs include details when session creation fails.