Skip to content

Development

Jump to bottom
Pavel Erokhin edited this page Oct 19, 2026 · 1 revision

How WorldAPI is made and checked.

Stack

  • Kotlin and Gradle Kotlin DSL
  • Paper API 26.3
  • Ktor with the CIO engine for REST and the WebSocket
  • kotlinx-serialization, with kaml for the config
  • Exposed and HikariCP for the database
  • The Eclipse compiler for Java scripts
  • The admin panel: React, Vite, TypeScript, shadcn/ui and Tailwind, TanStack Router and Query, built with Bun

Tests

./gradlew build runs them. There is no MockBukkit for Paper 26.3, so tests use small fakes in src/test.

WORLDAPI_TEST_DATABASES=postgresql://u:p@host:port/db,mysql://... runs the store tests against real database servers.

Changing an endpoint

  1. Change the route and its data classes.
  2. Run WORLDAPI_UPDATE_OPENAPI=1 ./gradlew test. It rewrites docs/openapi.json; a stale document fails the tests.
  3. In minecraft-mcp, run npm run generate and fix what the typecheck flags.
  4. Describe it on the matching page of this wiki.

Add fields; don't rename or remove them. Sites, the MCP server, and the exporter read them.

On a real server

.claude/scripts/paper_smoke.py starts a local Paper with the jar and fails on any error about the plugin:

python3 -I .claude/scripts/paper_smoke.py --game 26.3 --plugin build/libs/worldapi-dev.jar \
  --modrinth plan --expect "Listening on .* endpoints" --expect "Registered extension: WorldAPI"

To call endpoints by hand, run the Docker Compose snippet from Installation with the jar in plugins/, and curl it with the admin token from its config.yml.

The admin panel

  • cd admin && bun run dev serves the panel with hot reload and passes /api and the WebSocket through to a local server on 8110.
  • Its API types come from docs/openapi.json: bun run generate, which every build runs first, so a changed endpoint fails the panel's typecheck.
  • cd admin && bun run typecheck checks it alone.

AI involvement

AI wrote most of the code and the documentation from my task descriptions, and I review what it makes. AI also writes the commit messages from the changes. WorldAPI was built for AI agents to use, so they helped test it too.

Every Monday an autopilot run in GitHub Actions updates the dependencies and the game version with Claude, fixes what breaks, and releases when what the plugin ships changed.

Next: Releasing.

WorldAPI on GitHub · Related projects · Issues

Home

Server owners

API

Developers

Clone this wiki locally