t1k:nakama:plugin

Field	Value
Module	`base`
Version	`1.6.2`
Effort	`low`
Tools	—

Keywords: build, go, InitModule, nakama, plugin, runtime, shared object

How to invoke

/t1k:nakama:plugin

Nakama Plugin Development

Overview

Nakama server loads custom Go code as shared-object plugins (.so). The plugin must export an InitModule function and match the host binary’s exact dependency versions.

Key Patterns

InitModule Entry Point

func InitModule(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, initializer runtime.Initializer) error {
    // Register RPCs, hooks, matches here
    return nil
}

Build Command

go build -trimpath -buildmode=plugin -o modules/backend.so ./modules

Runtime APIs

runtime.Initializer — register RPCs (RegisterRpc), hooks (RegisterBefore*, RegisterAfter*), matches
runtime.NakamaModule — authenticate users, read/write storage, send notifications
runtime.Logger — structured logging (Info, Warn, Error, Debug)
runtime.RUNTIME_CTX_* — context keys for user ID, session ID, env vars

Dependency Pinning

Go plugins require exact binary compatibility with the host Nakama binary. All shared dependencies (protobuf, grpc, golang.org/x/*) must match pinned versions. See DEPENDENCY_PINS.md.

Gotchas

CRITICAL: Never run go get -u on shared deps — will break plugin loading
Plugin .so and Nakama binary must be compiled with the same Go version
InitModule runs once at startup — all registration must happen here, not lazily
-trimpath flag is required to avoid path-dependent build artifacts
The module directory must contain main.go with package main
Plugin ABI mismatch: Go version used to compile plugin MUST exactly match Nakama binary’s Go version. Even patch versions matter.
-buildmode=plugin required: Without this flag, the binary won’t load as a Nakama plugin.
Dependency pinning: All shared deps (protobuf, gRPC) must match Nakama’s go.sum. Use go mod tidy and verify checksums.

Checklist

go.mod module path matches expected import path
All pinned deps match DEPENDENCY_PINS.md versions
Build succeeds: go build -trimpath -buildmode=plugin -o modules/backend.so ./modules
InitModule returns nil on success, wrapped error on failure
No fmt.Print* or log.* — use runtime.Logger exclusively