Skip to content

Home

Jump to bottom
Andrew R. edited this page Jul 24, 2026 · 1 revision

Shamoo

Shamoo is a TypeScript framework and Java runtime for Minecraft plugins on Paper servers and Velocity proxies. shamooc discovers declarations from TypeScript, the CLI emits separate source-mapped ESM bundles, and ShamooRuntime runs each installed plugin generation in its own Javet/Node isolate.

The current release candidate is v0.1.0-rc.1. It targets Java 21, Paper 1.21.8 build 55, Velocity 3.4.0, Node.js 22 or newer for development, and Linux x86-64 for the bundled Javet native runtime. Release-candidate packages are distributed as GitHub release tarballs; the npm registry is not yet the canonical source and packages must not be assumed to be published there.

Start here

  1. Install ShamooRuntime and the TypeScript tools.
  2. Build and deploy a complete first Paper plugin.
  3. Keep the CLI and configuration reference nearby.
  4. Choose Paper events, Velocity events, or the exact-version packet API.
  5. Read Runtime and security before enabling untrusted code or capabilities.

What is implemented

  • Separate Paper and Velocity bundles with compiler metadata format 2 and Runtime manifest version 1.
  • 37 compiler-recognized core decorators, 422 generated Paper event decorators, and 46 generated Velocity event decorators.
  • Pinned Paper, Velocity, Paper NMS, and packet declarations generated from checksum-verified JVM models.
  • Watched, transactional plugin installations with generation replacement, lifecycle draining, resource cleanup, dependency ordering, and source maps.
  • Data-only host operations for events, commands, scheduling, packets, services, contract events, and optional Paper-to-Velocity messaging.
  • Deny-by-default Node module resolution and mediated text-file access.

Important current limits

  • The bundled TypeScript adapter can instantiate only exported, zero-constructor-argument components. It does not yet construct the full DI graph.
  • The bundled adapter directly registers handlers; it does not run the full guard, pipe, interceptor, filter, validator, condition, or parameter-binding pipeline.
  • Generated JVM interfaces are compile-time declarations. Current deployed event callbacks receive small data-only payloads, not live Bukkit or Velocity objects.
  • Packet declarations are exact to Paper 1.21.8 build 55 and require compiler permission, Runtime operator enablement, and a plugin allowlist.
  • The runtime is defense in depth inside the Minecraft server process, not an operating-system sandbox.

Repositories

Shamoo is licensed under Apache-2.0.

Getting Started

Decorators

Runtime

Project

Clone this wiki locally