dfplugin

README

df-plugin

Lightweight plugin and event bus for the df-mc/dragonfly Minecraft Bedrock server.

Register callbacks for every player.Handler event Dragonfly emits — no need to implement the full interface.

Install

go get github.com/ahnsunggwan45/df-plugin

Requires Go 1.23+ and github.com/df-mc/dragonfly.

Quick start

Wire the plugin manager into your server's Accept loop:

package main

import (
    "log/slog"

    "github.com/df-mc/dragonfly/server"
    "github.com/df-mc/dragonfly/server/player/chat"

    "github.com/ahnsunggwan45/df-plugin"

    // Blank-import your plugins so their init() runs.
    _ "yourmodule/plugins/joinannounce"
)

func main() {
    chat.Global.Subscribe(chat.StdoutSubscriber{})
    dfplugin.LogLoaded(slog.Default())

    srv := server.DefaultConfig().MustNew()
    srv.CloseOnProgramEnd()
    srv.Listen()

    for p := range srv.Accept() {
        dfplugin.Install(p) // attaches handler + fires OnJoin
    }
}

Writing a plugin

Each plugin is just a package whose init() calls dfplugin.Register. Set only the event fields you care about — the rest are skipped.

package joinannounce

import (
    "fmt"

    "github.com/df-mc/dragonfly/server/player"
    "github.com/df-mc/dragonfly/server/player/chat"

    "github.com/ahnsunggwan45/df-plugin"
)

func init() {
    dfplugin.Register(dfplugin.Plugin{
        Name: "joinannounce",
        OnJoin: func(p *player.Player) {
            _, _ = chat.Global.WriteString(fmt.Sprintf("%s joined the server.", p.Name()))
        },
        OnQuit: func(p *player.Player) {
            _, _ = chat.Global.WriteString(fmt.Sprintf("%s left the server.", p.Name()))
        },
    })
}

Then blank-import the plugin package from your main package so its init() runs.

Supported events

All 36 methods of Dragonfly's player.Handler are exposed as optional callbacks:

OnJoin, OnQuit, OnMove, OnJump, OnTeleport, OnChangeWorld, OnToggleSprint, OnToggleSneak, OnChat, OnFoodLoss, OnHeal, OnHurt, OnDeath, OnRespawn, OnSkinChange, OnFireExtinguish, OnStartBreak, OnBlockBreak, OnBlockPlace, OnBlockPick, OnItemUse, OnItemUseOnBlock, OnItemUseOnEntity, OnItemRelease, OnItemConsume, OnAttackEntity, OnExperienceGain, OnPunchAir, OnSignEdit, OnSleep, OnLecternPageTurn, OnItemDamage, OnItemPickup, OnHeldSlotChange, OnItemDrop, OnTransfer, OnCommand, OnDiagnostics.

Cancelling and mutating events

Most callbacks receive ctx *player.Context. Call ctx.Cancel() to cancel the event. Pointer arguments (e.g. msg *string, damage *float64, drops *[]item.Stack) may be reassigned to mutate the event payload.

OnChat: func(ctx *player.Context, p *player.Player, msg *string) {
    if strings.Contains(*msg, "badword") {
        ctx.Cancel()
        return
    }
    *msg = "[chat] " + *msg
},
OnBlockBreak: func(ctx *player.Context, p *player.Player, pos cube.Pos, drops *[]item.Stack, xp *int) {
    if p.GameMode() != world.GameModeCreative {
        ctx.Cancel() // survival players cannot break blocks
    }
},

Example

A runnable example server lives under example/. It bundles the joinannounce plugin and produces a working Bedrock server on :19132:

git clone https://github.com/ahnsunggwan45/df-plugin
cd df-plugin/example
go run .

Connect with a Bedrock client to localhost:19132 and you should see <name> joined the server. in chat.

License

MIT

Documentation

Overview

Package dfplugin provides a lightweight plugin/event-bus layer for the df-mc/dragonfly Minecraft Bedrock server. Plugins are registered via Register() (typically from init()) and receive callbacks for every player.Handler event Dragonfly emits.

Index

• func Install(p *player.Player)
• func LogLoaded(log *slog.Logger)
• func Register(p Plugin)
• type Plugin
  • func Plugins() []Plugin

Functions

func Install

func Install(p *player.Player)

Install attaches the composite handler to a player and fires OnJoin hooks. Call this once per player from the srv.Accept() loop.

func LogLoaded

func LogLoaded(log *slog.Logger)

LogLoaded prints the list of registered plugins to the given logger.

func Register

func Register(p Plugin)

Register adds a plugin to the global registry. Call this from an init() function in the plugin's package and ensure the package is imported (typically via a blank import in plugins_gen.go).

Types

type Plugin

type Plugin struct {
	Name string

	OnJoin func(p *player.Player)

	OnMove            func(ctx *player.Context, p *player.Player, newPos mgl64.Vec3, newRot cube.Rotation)
	OnJump            func(p *player.Player)
	OnTeleport        func(ctx *player.Context, p *player.Player, pos mgl64.Vec3)
	OnChangeWorld     func(p *player.Player, before, after *world.World)
	OnToggleSprint    func(ctx *player.Context, p *player.Player, after bool)
	OnToggleSneak     func(ctx *player.Context, p *player.Player, after bool)
	OnChat            func(ctx *player.Context, p *player.Player, msg *string)
	OnFoodLoss        func(ctx *player.Context, p *player.Player, from int, to *int)
	OnHeal            func(ctx *player.Context, p *player.Player, health *float64, src world.HealingSource)
	OnHurt            func(ctx *player.Context, p *player.Player, damage *float64, immune bool, attackImmunity *time.Duration, src world.DamageSource)
	OnDeath           func(p *player.Player, src world.DamageSource, keepInv *bool)
	OnRespawn         func(p *player.Player, pos *mgl64.Vec3, w **world.World)
	OnSkinChange      func(ctx *player.Context, p *player.Player, skin *skin.Skin)
	OnFireExtinguish  func(ctx *player.Context, p *player.Player, pos cube.Pos)
	OnStartBreak      func(ctx *player.Context, p *player.Player, pos cube.Pos)
	OnBlockBreak      func(ctx *player.Context, p *player.Player, pos cube.Pos, drops *[]item.Stack, xp *int)
	OnBlockPlace      func(ctx *player.Context, p *player.Player, pos cube.Pos, b world.Block)
	OnBlockPick       func(ctx *player.Context, p *player.Player, pos cube.Pos, b world.Block)
	OnItemUse         func(ctx *player.Context, p *player.Player)
	OnItemUseOnBlock  func(ctx *player.Context, p *player.Player, pos cube.Pos, face cube.Face, clickPos mgl64.Vec3)
	OnItemUseOnEntity func(ctx *player.Context, p *player.Player, e world.Entity)
	OnItemRelease     func(ctx *player.Context, p *player.Player, i item.Stack, dur time.Duration)
	OnItemConsume     func(ctx *player.Context, p *player.Player, i item.Stack)
	OnAttackEntity    func(ctx *player.Context, p *player.Player, e world.Entity, force, height *float64, critical *bool)
	OnExperienceGain  func(ctx *player.Context, p *player.Player, amount *int)
	OnPunchAir        func(ctx *player.Context, p *player.Player)
	OnSignEdit        func(ctx *player.Context, p *player.Player, pos cube.Pos, frontSide bool, oldText, newText string)
	OnSleep           func(ctx *player.Context, p *player.Player, sendReminder *bool)
	OnLecternPageTurn func(ctx *player.Context, p *player.Player, pos cube.Pos, oldPage int, newPage *int)
	OnItemDamage      func(ctx *player.Context, p *player.Player, i item.Stack, damage *int)
	OnItemPickup      func(ctx *player.Context, p *player.Player, i *item.Stack)
	OnHeldSlotChange  func(ctx *player.Context, p *player.Player, from, to int)
	OnItemDrop        func(ctx *player.Context, p *player.Player, s item.Stack)
	OnTransfer        func(ctx *player.Context, p *player.Player, addr *net.UDPAddr)
	OnCommand         func(ctx *player.Context, p *player.Player, command cmd.Command, args []string)
	OnQuit            func(p *player.Player)
	OnDiagnostics     func(p *player.Player, d session.Diagnostics)
}

Plugin describes a unit of behavior. Set only the fields whose events you care about — the rest stay nil and are skipped at dispatch time.

func Plugins

func Plugins() []Plugin

Plugins returns a snapshot of currently registered plugins.