Write once.
Run in the shared world.

Availability

Two runtimes, one contract

Each Go plugin is a separate executable, not a Go -buildmode=plugin library. Java plugins use a separate Java 25 runtime that hosts multiple plugins. The Minecraft server and shared game state remain in Go.

• Structure is data. Event layouts and command trees cross the ABI; Go function values do not.
• The host owns state. Allowed event mutations return in the verdict; additional host effects are queued for a safe tick.
• One API serves both editions. Protocol-specific encoding stays in the Java and Bedrock adapters.

Getting started today

Use Go 1.26.0, JDK 25 and the checked-in Gradle wrapper. CLI v0.2.1 supports custom-event generation and packaging. For this native-event preview, use matching feat/go-events-api branches in GoCraft, the JVM repository and the examples; the Go example already pins the matching published SDK and ABI commits.

git clone --branch feat/go-events-api https://github.com/GoCraft-MC/gocraft-jvm.git
git clone --branch feat/go-events-api https://github.com/GoCraft-MC/gocraft-plugin-examples.git
go install github.com/GoCraft-MC/gocraft-cli@v0.2.1
# Ensure your Go binary directory is on PATH.
(cd gocraft-jvm && ./gradlew publishToMavenLocal)
cd gocraft-plugin-examples
gocraft-cli gen -lang java -package gocraft.example.greeting \
  -o java/src/main/java/gocraft/example/greeting go
(cd java && sh ./gradlew gocraftBundle)
(cd go && SHOP_BUNDLE=../java/build/gocraft/gocraft-example-java.gcpkg ./build.sh)

Bundle layout

Every language ships the same .gcpkg ZIP format. The host reads and validates metadata before it starts a runtime.

plugin.toml          # validated manifest
commands.pb          # optional neutral command tree
bin/example-go      # Go executable at the manifest entry
payload/*.jar       # Java bundles instead carry plugin jars
assets/
  ...                # plugin-owned resources

The packer reads a staged directory; it does not compile source. Java's Gradle task stages jars automatically. The Go example script generates types, builds its binary with GOWORK=off, and checks events.lock.json before packing. Native executables must match the server's OS and architecture.

plugin.toml

The manifest lets GoCraft discover subscriptions and commands without executing plugin code. Unknown keys fail strict decoding.

id = "dev.example.protect"
version = "0.1.0"
api = 1
runtime = "go"
entry = "bin/protect"

[[subscribe]]
event = "block.break"
priority = "high"
perms = ["protect.bypass"]

[[subscribe]]
event = "player.chat"

[commands]
tree = "commands.pb"

Events

Native events are generated from the shared ABI schema into typed Go structs and Java classes. Only cancellable handlers receive EventControl. Register listeners and declare each subscription in the manifest.

// import gocraft "github.com/GoCraft-MC/gocraft-api-go"
return ctx.Events().OnPlayerChat(func(event *gocraft.PlayerChatEvent, control gocraft.EventControl) {
    if event.Message == "hide-go" {
        control.Cancel()
        return
    }
    if event.Message == "hello-go" {
        event.Message = "Hello from the typed Go event API."
    }
})

import fr.gocraft.api.EventControl;
import fr.gocraft.api.Subscribe;
import fr.gocraft.api.event.PlayerChatEvent;

public final class ChatListener {
    @Subscribe
    public void onChat(PlayerChatEvent event, EventControl control) {
        if ("hide-java".equals(event.message())) {
            control.cancel();
            return;
        }
        if ("hello-java".equals(event.message())) {
            event.setMessage("Hello from the typed Java event API.");
        }
    }
}

Go callbacks in one plugin share the event pointer and control. Accepted mutations reach the next plugin; cancellation stops later plugins. Subscriptions use priority order, then plugin ID. Observational notifications are asynchronous and cannot be cancelled.

Only declared mutable fields return through IPC. Changing a Go snapshot such as a player's name does not change server state; Java exposes setters only for mutable values. Chat rewritten to start with / remains chat, while command rewrites are reparsed and permission-checked.

Source: Native event semantics and hook timing. Complete registration and lifecycle code: Go and Java examples.

Native gameplay events

The preview has 14 native event types. The final column indicates whether cancellation is supported; mutable values are listed in the middle. All other values are snapshots.

Cancelled placement and inventory actions restore the client's prediction to canonical state. Bedrock multi-slot transactions use slot=-1, not Java's individual click gesture. Zero damage prevents application; non-finite numeric mutations are rejected.

// Inside OnLoad, with block.break declared in plugin.toml.
return ctx.Events().OnBlockBreak(func(event *gocraft.BlockBreakEvent, control gocraft.EventControl) {
    if !event.Can("protect.bypass") {
        control.Cancel()
        _ = event.Player.SendMessage("Protected area.")
    }
})

Commands

Commands are a neutral tree. Java renders it as Brigadier data, Bedrock renders it as Available Commands, and the plugin runtime only receives the selected local executor ID and typed values.

func (p *Plugin) Commands() *gocraft.CommandSet {
    set := gocraft.NewCommandSet()
    set.Command("greet").Permission("example.greet").Runs(func(call *gocraft.CommandContext) error {
        call.Reply("Hello, " + call.SenderName + "!")
        return nil
    })
    return set
}

Argument types

Core command names cannot be replaced. Plugin-versus-plugin collisions are namespaced deterministically, such as /economy:shop.

Permissions

Declare permission reads in the manifest. The host resolves them once against its group and operator model, then injects the answers into an event. Command branches carry their permission node and are pruned before a client can tab-complete them.

• Event permissions come from subscribe.perms.
• Command permissions use Go's .Permission(...) or Java's @Permission and command builders.
• Invocation rechecks access on the server; client pruning is not treated as security.
• Installing a plugin is trusting it. The manifest is not a process sandbox.

Effects and world writes

There are two return paths. Cancellation and allowed event-field mutations are validated before the guarded action continues. Additional effects, such as sending a message, go through the host's FIFO queue instead of writing game state from a plugin thread.

Calls enqueued while a drain is already running stay queued for the following tick. Closing the queue returns ErrMutationQueueClosed instead of silently accepting data.

Lifecycle

1. 1
   Scan

   Read and validate all manifests and command trees without executing code.

2. 2
   Preflight

   Provision only the runtime languages required by installed bundles.

3. 3
   Register structure

   Resolve command conflicts before a runtime process starts.

4. 4
   Load, warm and ready

   Start runtimes, attach subscriptions, perform handler-free JVM warm-up, then signal readiness before listeners open.

5. 5
   Stop in reverse

   Revoke subscriptions and commands, unload instances, then stop runtimes.

Any partial startup failure rolls back loaded instances, event subscriptions, command trees and runtime processes.

Go registers callbacks in OnLoad, followed by OnEnable and OnDisable. Java receives Host through its constructor and registers listeners in enable(). Unloading detaches subscriptions; runtime recovery creates fresh plugin state. Persist durable data in the plugin's data directory, not only in memory.

Limits and guarantees