Getting Started

Getting Started

Requirements

• Go 1.24 or newer (the module targets go 1.26)
• A Minecraft: Java Edition 1.21.4 client for testing
• Network access to Mojang's session service when online_mode: true

No Java runtime is required to build or run GoCraft.

---

Quick start

git clone https://github.com/GoCraft-MC/GoCraft.git
cd GoCraft
go mod download
go test ./...
go build -o gocraft .
./gocraft

Connect a Java 1.21.4 client to localhost:25565.

Windows: use go build -o gocraft.exe . and then .\gocraft.exe

On first run, GoCraft writes a default server.yml into the working directory and generates a world.

---

First-run checklist

1. Start the server — it binds the Java listener on 0.0.0.0:25565 by default.
2. Edit server.yml — set your MOTD, max_players, difficulty, default_gamemode, etc. See Configuration.
3. Become operator — add your username to operators in server.yml, or run /op <you> from the console. Operators bypass all permission checks.
4. Enable Bedrock (optional) — set bedrock.enabled: true and open the UDP port. See Bedrock and Cross-Play.
5. Add plugins / custom items (optional) — see Native Go Plugins and Custom Items.

---

Online mode

online_mode: true

• true — requires Mojang/Xbox authentication; usernames and UUIDs are verified.
• false — offline/cracked mode; anyone can join with any name. Use only on trusted/local networks.

---

Running the tests

GoCraft is heavily test-covered, including cross-edition parity tests. Before submitting changes:

go fmt ./...
go test ./...
go build ./...

The build fails if the edition-neutral core/ package imports java/ or bedrock/ — this is enforced by a compile-time architecture test (core/world/arch_test.go). See Contributing.

---

Where things live

Path	Purpose
server.yml	Runtime configuration
world/, world_nether/, world_end/	Anvil region files (disk storage)
packs/	Custom item packs
plugins/	Native Go plugin bundles (.gcpkg)
permissions.json	Permission groups/users
whitelist.json	Shared Java/Bedrock allowlist

See Project Structure for a full tour of the source tree.