minego/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

MinEGO is a Go-based Minecraft protocol implementation that generates packet codecs and data components for Minecraft Java Edition protocol version 1.21.6 (protocol 771). The project uses code generation to create serialization/deserialization code for Minecraft network packets and item components.

Architecture

The project follows a modular architecture centered around code generation:

• codec/data/component/ - Contains Go structs for all Minecraft item components (e.g., damage, enchantments, custom_name). Each component implements the slot.Component interface with Type() and ID() methods.
• codec/data/packet/game/ - Contains client and server packet definitions following the Minecraft protocol specification
• codec/data/slot/ - Core slot/item stack implementation and component registration system
• net/ - Network layer implementation (currently empty)
• Protocol Reference - codec/data/packet/protocol.wiki contains the complete Minecraft protocol specification from wiki.vg

Code Generation System

The project uses a custom code generator called packetizer that processes Go structs marked with //codec:gen comments. This generates the necessary ReadFrom/WriteTo methods for network serialization.

Key patterns:

• Structs marked with //codec:gen will have codecs auto-generated
• Structs marked with //codec:ignore are excluded from generation
• Components must implement Type() slot.ComponentID and ID() string methods
• Components are registered in codec/data/component/components.go using slot.RegisterComponent()

Development Commands

Code Generation

# Generate packet codecs (run from project root)
./gen-packet.sh
# This runs: packetizer ./codec

Standard Go Commands

# Build the project
go build

# Run tests (if any exist)
go test ./...

# Format code
go fmt ./...

# Get dependencies
go mod tidy

Dependencies

• github.com/Tnze/go-mc - Core Minecraft protocol library (uses forked version)
• packetizer - Custom code generation tool (available at /root/go/bin/packetizer)

Working with Components

When adding new Minecraft item components:

1. Create the struct in codec/data/component/ following existing patterns
2. Add //codec:gen comment above the struct
3. Implement Type() and ID() methods with correct component ID and namespace
4. Register the component in components.go init() function
5. Run ./gen-packet.sh to generate codecs

Working with Packets

When adding new packet types:

1. Define the packet struct in appropriate client/ or server/ directory
2. Add //codec:gen comment for auto-generation
3. Register the packet in the appropriate packets map
4. Run ./gen-packet.sh to generate codecs

Module Path

The project uses git.konjactw.dev/patyhank/minego as its module path and includes a replace directive for the go-mc dependency pointing to a custom fork.

Code Generation Tasks

• Java to Go Packet Conversion:
  • Task to implement Game State packets by converting Java code from ~/GoProjects/mc-network-source/network/protocol/game to Go structs
  • Focus on maintaining the same read/write logic during translation
  • Ensure packet structures match the original Java implementation
  • Use packetizer for automatic codec generation

Reference Notes

• PacketID Reference:
  • In /root/go/pkg/mod/git.konjactw.dev/patyhank/go-mc@v1.20.3-0.20250618004758-a3d57fde34e8/data/packetid/packetid.go, you can find all packet IDs (excluding handshake stage)

Packet Serialization Techniques

• 對於Optional封包資料 簡易的格式可以使用pk.Option[XXX,*XXX] 的方法 比較複雜的需要自己實作一個ReadFrom&WriteTo 並且移除codec:gen的標記

Example

// ExampleTypeFull full example for codec generator
//
//codec:gen
type ExampleTypeFull struct {
	PlayerID         int32 `mc:"VarInt"`
	PlayerName       string
	UUID             uuid.UUID      `mc:"UUID"`
	ResourceLocation string         `mc:"Identifier"`
	Data             nbt.RawMessage `mc:"NBT"`
	ByteData         []byte         `mc:"ByteArray"`
	Health           float32
	Balance          float64
	Message          chat.Message
	SentMessages     []chat.Message
}