WAIT — Mixed signals — read the receipts

• Last commit today
• 14 active contributors
• GPL-3.0 licensed
• CI configured
• ⚠ Concentrated ownership — top contributor handles 70% of recent commits
• ⚠ GPL-3.0 is copyleft — check downstream compatibility
• ⚠ No test directory detected

_{Computed from maintenance signals — commit recency, contributor breadth, bus factor, license, CI, tests}

Pumpkin is a Minecraft server implementation written entirely in Rust, designed to replace the official Java server with a high-performance, memory-efficient alternative. It supports both Java Edition and Bedrock Edition clients, implements vanilla game mechanics (block physics, lighting, chunk generation, entity spawning), and provides extensibility through a plugin API—all optimized for multi-threaded performance on modern hardware. Monorepo structured as a Cargo workspace with 11 interdependent crates: pumpkin/ is the main server binary, pumpkin-protocol/ handles Java/Bedrock packet encoding, pumpkin-world/ manages world state and chunk I/O, pumpkin-plugin-api/ defines the plugin interface, and pumpkin-data/ holds JSON asset registries (blocks.json, entities.json, etc.). Assets are versioned data files checked into assets/; the Dockerfile and devcontainer.json indicate containerized development.

Server administrators and Minecraft hosting providers who want to run large-scale multiplayer servers with lower resource overhead than Paper/Spigot, and developers interested in contributing to or extending a from-scratch Minecraft server implementation in Rust.

Actively developed but pre-1.0: the repo explicitly marks itself as 'under heavy development' with a tracked milestone (issue #449) listing remaining work before 1.0. It has CI/CD (GitHub Actions for Rust, Docker builds), strict Clippy linting in Cargo.toml, and shows active commits, but core features like full chunk generation, redstone, combat, entity AI, and plugins are marked as W.I.P. Not production-ready yet; experimental/early-stage.

Single-engine implementation risk: unlike Paper which extends Bukkit, Pumpkin reimplements the entire server from scratch, meaning subtle vanilla behavior mismatches are likely. The workspace depends on 11 internal crates (pumpkin-protocol, pumpkin-world, pumpkin-plugin-api, etc.) creating tight coupling; breaking changes in core crates ripple widely. No visibility into external dependency versions beyond Cargo.lock, and the 'edition = "2024"' setting is future-unstable (Rust 1.95+), which limits contributor accessibility.

Active work on protocol support (tracked issue #1401), world simulation (issue #1403: player tab-list, scoreboard, lighting implemented; chunk generation pending), player mechanics (issue #1405: combat and advancements incomplete), entity AI (issue #1406: W.I.P), plugin system (issue #1407), and commands (issue #15). Dependabot is configured for automated dependency updates. The repo tracks 5 major feature areas via GitHub Projects.

git clone https://github.com/Pumpkin-MC/Pumpkin.git
cd Pumpkin
cargo build --release
cargo run --bin pumpkin

Optionally use Nix: nix develop (.envrc present), or Docker: docker build -t pumpkin . then docker run pumpkin.

Daily commands:

cargo run --bin pumpkin

Devcontainer is configured in .devcontainer/devcontainer.json for containerized development. Production: use release build (cargo build --release) and Docker (docker build -f Dockerfile). Configuration via TOML (mentioned in Features; no example config visible in file list).

• Cargo.toml — Workspace configuration defining all 11 member crates; essential for understanding project structure and dependencies across the entire server implementation.
• pumpkin/Cargo.toml — Main server crate entry point; defines core dependencies for the Minecraft server runtime and protocol handling.
• pumpkin-protocol — Protocol layer handling Minecraft packet serialization/deserialization; critical for Java & Bedrock client communication.
• pumpkin-world — World management and chunk loading system; implements the core world state and persistence logic.
• pumpkin-plugin-api — Public plugin API surface; defines extensibility contracts that contributors must understand for plugin development.
• assets/packet — Protocol packet definitions for Minecraft versions 1.20.5–1.21.11; required reference for packet handling implementation.
• pumpkin-config — Configuration management crate; handles server settings and runtime configuration loading.

Add a new Minecraft protocol packet handler

1. Define the packet structure in the protocol crate using packet schema from assets/packet/<version>_packets.json (pumpkin-protocol)
2. Implement serialization/deserialization using the Codec trait in pumpkin-codecs (pumpkin-codecs)
3. Register the packet handler in the main server's connection handler (pumpkin)
4. Add integration tests validating packet round-trip encoding (pumpkin-protocol)

Create a new game mechanic plugin

1. Create a new plugin crate using the pumpkin-plugin-api and #[pumpkin_plugin] macro (pumpkin-plugin-api)
2. Define event handlers using #[event_listener] from pumpkin-api-macros (pumpkin-api-macros)
3. Implement your game logic responding to player actions, block changes, etc. (pumpkin-plugin-api)
4. Load the plugin via configuration in the plugin loader system (pumpkin-config)

Add support for a new Minecraft version

1. Add packet definitions for the new version to assets/packet/<version>_packets.json (assets/packet)
2. Update registry definitions in assets/registry/<version>_synced_registries.json (assets/registry)
3. Add metadata type definitions to assets/meta_data_type/<version>_meta_data_type.json (assets/meta_data_type)
4. Update pumpkin-data version parsing and registry loading logic to handle new version (pumpkin-data)
5. Add version-specific tests in protocol handler (pumpkin-protocol)

Extend world generation with new biomes/features

1. Add biome definitions to assets/biome.json and assets/multi_noise_biome_tree.json (assets)
2. Define configured features and placed features in assets/configured_features.json and assets/placed_feature.json (assets)
3. Implement feature generator logic in pumpkin-world chunk generation system (pumpkin-world)
4. Test chunk generation using precomputed chunk test files (e.g., assets/no_blend_no_beard_0_0.chunk) (pumpkin-world)

• Rust — Memory safety without garbage collection, fearless concurrency with async/await, and zero-cost abstractions enable high-performance server with minimal latency variance.
• Multi-threaded async runtime (Tokio implied by workspace) — Handles thousands of concurrent player connections efficiently; allows blocking I/O (world saves, chunk generation) on dedicated thread pools without blocking network loop.
• Protocol codec architecture (pumpkin-codecs) — Separates concerns between wire format and business logic; enables easy version-compatibility without code duplication across protocol versions.
• Plugin system with macros (pumpkin-plugin-api, pumpkin-api-macros) — Compile-time plugin discovery and event routing eliminates runtime reflection overhead; allows extensibility without forking server code.
• JSON asset definitions (blocks.json, items.json, etc.) — Decouples game data from code; enables rapid version updates and client version support without recompilation.

• Rust instead of Java for Minecraft server

  • Why: Java dominates Minecraft ecosystem (Spigot, Paper); Rust offers superior performance and memory efficiency.
  • Consequence: Smaller community, fewer third-party libraries, but better single-threaded performance and predictable GC pauses.

• Asset-driven registries (JSON) instead of code-generated enums

  • Why: Reduces recompilation when updating to new Minecraft versions.
  • Consequence: Runtime deserialization overhead; schema validation must be manual.

• Single server process (no clustering mentioned in README)

  • Why: Simplifies state consistency and world synchronization.
  • Consequence: Vertical scaling only; horizontal scaling via plugin-layer proxy would require custom coordination.

• Strict clippy lints (deny all, nursery, pedantic, cargo)

  • Why: Maintains high code quality and consistency across all contributors.
  • Consequence: Slower development velocity; contributors must address all warnings before PR merge.

• Modding API compatibility with Minecraft Forge or Fabric (server-side plugins only, not client-side mod support)
• Clustering or distributed world state (single-server architecture)
• Full parity with every obscure vanilla mechanic edge-case (prioritizes common gameplay)
• Support for legacy Minecraft versions (older than 1.20.5)

Rust 1.95+ is a future version (repo uses edition = '2024'); contributors on older Rust will hit compilation errors. No visible server.toml or example config, so first-time users must infer configuration. Workspace crates have tight interdependencies; building a single crate like pumpkin-protocol without others may fail. Assets (blocks.json, entities.json) appear to be hand-maintained—drift from vanilla can cause silent gameplay bugs. Plugin API is post-1.0 scope; plugins may not work before then.

• Minecraft Protocol (Java & Bedrock) — Pumpkin must perfectly implement packet encoding/decoding for both editions; protocol version mismatches are silent failures
• NBT (Named Binary Tag) — Minecraft's binary data format for chunks, entities, and items—assets/bedrock_block_states.nbt and chunk loading depend on correct NBT parsing
• Chunk Loading & LOD (Level of Detail) — Features list mentions 'Chunk Loading (Vanilla, Linear, Pump)' suggesting multiple chunk-loading algorithms; choosing the wrong one causes lag spikes or memory bloat
• Tokio async runtime — Pumpkin's multi-threading goal implies async/await; understanding Tokio's task spawning and channels is essential for networking and world ticking
• Redstone simulation — Issue #1402 tracks redstone; it's a state machine requiring tick-based propagation—critical for automation and contraptions
• Procedural Macros (pumpkin-macros, pumpkin-api-macros) — Code generation for plugin/packet definitions; mistakes in macro design cause hard-to-debug derive errors across all crates
• Sparse chunk storage & serialization — Pumpkin must efficiently store and serialize millions of block state changes; the chunk format (Vanilla vs Linear vs Pump) directly impacts disk I/O and memory

• PaperMC/Paper — Most popular high-performance Java server; Pumpkin's direct competitor but built on Bukkit/Spigot rather than reimplemented
• veloren/veloren — Another Rust-based voxel game server showing Rust networking and world simulation patterns applicable to Minecraft
• GeyserMC/Geyser — Bridges Bedrock and Java protocols; Pumpkin aims to support both natively, so this is a reference implementation for protocol translation
• sandertv/gophertunnel — Go-based Bedrock protocol implementation; reference for Bedrock packet structure that Pumpkin's protocol layer must match
• Pumpkin-MC/pumpkin-plugins — Official example plugins and plugin ecosystem for Pumpkin (if it exists); shows plugin API usage patterns

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for pumpkin-protocol packet serialization/deserialization

The repo has packet definitions in assets/packet/ (1_20_5_packets.json, 1_21_11_packets.json) and a pumpkin-protocol workspace member, but there's no visible test suite validating packet encoding/decoding. Given the critical nature of protocol correctness for server stability, adding tests against these packet specs would catch regressions early and improve reliability across Minecraft versions.

• [ ] Create tests/integration_tests.rs or tests/ directory in pumpkin-protocol/
• [ ] Load packet definitions from assets/packet/*.json in test setup
• [ ] Write parametrized tests for each packet type (encode → decode → verify equality)
• [ ] Test version-specific packet variations (1_20_5, 1_21_11, etc.)
• [ ] Add test coverage for edge cases (malformed packets, boundary values)
• [ ] Ensure tests run in CI by adding/updating .github/workflows/rust.yml

Add CI workflow for validating asset JSON schema compliance

The assets/ directory contains 40+ JSON files (blocks.json, items.json, entities.json, chunk_gen_settings.json, etc.) that are critical data sources. Currently there's no automated validation that these files maintain consistent schema or structure. A GitHub Action workflow would catch malformed assets before they break the server.

• [ ] Create .github/workflows/validate-assets.yml workflow
• [ ] Use a JSON schema validator (e.g., ajv-cli or rust-based tool) to validate each asset file
• [ ] Define or document expected schemas for critical files (blocks.json, items.json, entities.json)
• [ ] Add validation for metadata_type/*.json files across all versions
• [ ] Configure workflow to run on pushes to assets/ and on PRs
• [ ] Add step to validate NBT binary files (.chunk files) if tooling exists

Add clippy lint documentation and suppression justifications for allowed lints

The Cargo.toml defines extensive clippy lint rules (allowing 18 lints like cast_precision_loss, float_cmp, etc.), but there's no documentation explaining why each allowance exists. This creates maintenance burden for future contributors who don't know if an allowed lint can be re-enabled. Adding inline documentation or a LINTS.md file would improve code review quality.

• [ ] Create docs/LINTS.md documenting each allowed clippy lint in workspace.lints.clippy
• [ ] For each 'allow' entry, add 1-2 sentences explaining the rationale (e.g., 'cast_precision_loss: Minecraft uses floats extensively for coordinates where precision loss is acceptable')
• [ ] Reference specific files or modules where each lint is frequently triggered (if applicable)
• [ ] Add comments above allow rules in Cargo.toml linking to docs/LINTS.md
• [ ] Include guidance on when future developers should consider re-denying a lint
• [ ] Link to this documentation from CONTRIBUTING.md

• Add unit tests for pumpkin-codecs/src/ (no test directory visible for the codecs crate, but it's critical for packet encoding)
• Document the TOML configuration schema in README.md with example server.toml—no concrete config file or docs are visible
• Complete the entity AI stub in pumpkin-world/ (currently marked W.I.P in features list; pick one simple mob like passive animals and implement basic pathfinding)

The Pumpkin Minecraft server codebase demonstrates generally good security practices with strong configurations in Docker (non-root user, capability dropping, read-only filesystem, no-new-privileges). However, there are critical file integrity issues (incomplete Dockerfile ENTRYPOINT and Cargo.toml sections) that must be resolved before deployment. The strict Clippy linting configuration is a positive security signal. No obvious injection vulnerabilities, hardcoded secrets, or dependency issues were detected from the provided snippets. The main concerns are configuration completeness, invalid Rust edition specification, and ensuring infrastructure-level security controls for the exposed game port.

• Medium · Incomplete Dockerfile ENTRY point — Dockerfile (final line). The Dockerfile's ENTRYPOINT instruction is incomplete (ends with 'ENTRY'). This may cause the container to fail at runtime or use an unexpected default entrypoint. The binary path '/bin/pumpkin' should be explicitly specified. Fix: Complete the ENTRYPOINT instruction: 'ENTRYPOINT ["/bin/pumpkin"]' or 'CMD ["/bin/pumpkin"]'
• Medium · Incomplete Cargo.toml Profile Configuration — Cargo.toml ([profile.release] section). The Cargo.toml file has an incomplete [profile.release] section (ends with just 'l'). This indicates a truncated or malformed configuration file that may not apply intended compiler optimizations or security hardening flags. Fix: Complete the profile.release configuration with appropriate settings. Consider adding: 'lto = true', 'codegen-units = 1', 'strip = true', and 'panic = "abort"' for hardened release builds.
• Low · Non-standard Rust Edition — Cargo.toml ([workspace.package] section). The Cargo.toml specifies edition = "2024", which is not a valid Rust edition. Valid editions are '2015', '2018', and '2021'. This will cause compilation to fail. Fix: Update to a valid Rust edition, likely '2021' which is the latest stable edition.
• Low · Future Rust Version Requirement — Cargo.toml ([workspace.package] section). The codebase specifies rust-version = "1.95", which does not exist yet. Current stable Rust versions are in the 1.7x-1.8x range. This may indicate a copy-paste error or placeholder. Fix: Verify and correct the MSRV (Minimum Supported Rust Version) to an actual released version, typically something like '1.70' or '1.75'.
• Low · Exposed Minecraft Port in Docker — Dockerfile (EXPOSE 25565) and docker-compose.yml (ports: 25565:25565). Port 25565 (Minecraft server port) is exposed in both the Dockerfile and docker-compose.yml without authentication requirements. While expected for a game server, ensure proper network security controls are in place at the infrastructure level. Fix: Ensure firewall rules restrict access to this port. Consider implementing rate-limiting and DDoS protection at the infrastructure level.
• Low · Hardcoded Security Contact Email — SECURITY.md. The security contact email (lilalexmed@proton.me) is publicly visible in SECURITY.md, potentially exposing it to spam or targeted attacks on the security team. Fix: Consider using a dedicated security email alias (e.g., security@pumpkinmc.org) instead of a personal email, or use GitHub's Security Advisory private reporting feature.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/Pumpkin-MC/Pumpkin shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live Pumpkin-MC/Pumpkin repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/Pumpkin-MC/Pumpkin.

What it runs against: a local clone of Pumpkin-MC/Pumpkin — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in Pumpkin-MC/Pumpkin | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of Pumpkin-MC/Pumpkin. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/Pumpkin-MC/Pumpkin.git
#   cd Pumpkin
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of Pumpkin-MC/Pumpkin and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "Pumpkin-MC/Pumpkin(\\.git)?\\b" \\
  && ok "origin remote is Pumpkin-MC/Pumpkin" \\
  || miss "origin remote is not Pumpkin-MC/Pumpkin (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(GPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"GPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is GPL-3.0" \\
  || miss "license drift — was GPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "Cargo.toml" \\
  && ok "Cargo.toml" \\
  || miss "missing critical file: Cargo.toml"
test -f "pumpkin/Cargo.toml" \\
  && ok "pumpkin/Cargo.toml" \\
  || miss "missing critical file: pumpkin/Cargo.toml"
test -f "pumpkin-protocol" \\
  && ok "pumpkin-protocol" \\
  || miss "missing critical file: pumpkin-protocol"
test -f "pumpkin-world" \\
  && ok "pumpkin-world" \\
  || miss "missing critical file: pumpkin-world"
test -f "pumpkin-plugin-api" \\
  && ok "pumpkin-plugin-api" \\
  || miss "missing critical file: pumpkin-plugin-api"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/Pumpkin-MC/Pumpkin"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.