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/valence-rs/valence 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.

GO — Healthy across all four use cases

• Last commit 4mo ago
• 22+ active contributors
• Distributed ownership (top contributor 20% of recent commits)
• MIT licensed
• CI configured
• Tests present
• ⚠ Slowing — last commit 4mo ago

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

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

What it runs against: a local clone of valence-rs/valence — 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 valence-rs/valence | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 143 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of valence-rs/valence. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/valence-rs/valence.git
#   cd valence
#
# 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 valence-rs/valence and re-run."
  exit 2
fi

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

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

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

# 4. Critical files exist
test -f "Cargo.toml" \\
  && ok "Cargo.toml" \\
  || miss "missing critical file: Cargo.toml"
test -f "crates/valence_entity/build.rs" \\
  && ok "crates/valence_entity/build.rs" \\
  || miss "missing critical file: crates/valence_entity/build.rs"
test -f "crates/valence_command/src/lib.rs" \\
  && ok "crates/valence_command/src/lib.rs" \\
  || miss "missing critical file: crates/valence_command/src/lib.rs"
test -f "crates/java_string/src/lib.rs" \\
  && ok "crates/java_string/src/lib.rs" \\
  || miss "missing critical file: crates/java_string/src/lib.rs"
test -f "crates/valence_anvil/src/lib.rs" \\
  && ok "crates/valence_anvil/src/lib.rs" \\
  || miss "missing critical file: crates/valence_anvil/src/lib.rs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 143 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~113d)"
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/valence-rs/valence"
  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).

Valence is a Rust framework for building Minecraft: Java Edition servers from scratch, built on Bevy ECS. It provides protocol-level abstractions for authentication, chunks, entities, block states, and NBT serialization, letting developers create custom game logic without implementing the Minecraft protocol themselves. Monorepo structure: root Cargo.toml orchestrates workspace; crates/ subdirectory contains modular plugins (valence_network, valence_nbt, valence_anvil, valence_advancement, etc.); benches/ holds performance tests (decode_array.rs, packet.rs, idle.rs); examples/ (implied by README structure) provides runnable demos. Each feature flag in Cargo.toml corresponds to an optional plugin crate.

Rust game developers and server architects building custom Minecraft experiences (minigame servers, modded experiences) who want low-level protocol control and high performance without the complexity of modding vanilla servers or proxies.

Early-stage but actively developed: the README explicitly warns of incomplete features and breaking changes. The monorepo has 1.8M+ lines of Rust code, CI/CD via GitHub Actions (ci.yml, ci-pr-comments.yml), and multiple feature-gated crates suggesting organized development. However, the codebase is pre-1.0 and targeting 'the most recent stable version of Minecraft' only, indicating it's not production-ready for widely-compatible servers.

High risk factors include: single primary sponsor/maintainer (rj00a), early maturity stage with explicit breaking change warnings, and heavy reliance on unstable Bevy ECS ecosystem (itself pre-1.0 historically). No evidence of major corporate adoption visible. The plugin system's flexibility is powerful but puts protocol compliance burden on end users.

Cannot determine exact recent commits from provided data, but the feature matrix suggests active development across: protocol encoding/decoding (var_int, var_long benches), world persistence (anvil format via valence_anvil), player management (player_list, advancement, equipment features), and ECS integration patterns. The CI workflows and dependabot config indicate continuous maintenance.

git clone https://github.com/valence-rs/valence.git
cd valence
cargo build
cargo run --example <example_name>  # See examples/ directory for available demos

Daily commands:

cargo build --release
cargo run --example <name>  # Run a specific example server
cargo test  # Run test suite
cargo bench  # Run benchmarks in benches/

• Cargo.toml — Workspace root configuration defining all crate dependencies, versions, and feature flags that control the entire Valence framework
• crates/valence_entity/build.rs — Build-time code generation for entity types from extracted Minecraft data, critical for entity system initialization
• crates/valence_command/src/lib.rs — Core command parsing and execution system, essential for understanding how commands flow through the framework
• crates/java_string/src/lib.rs — CESU-8 Java string encoding implementation required for all Minecraft protocol string handling
• crates/valence_anvil/src/lib.rs — Anvil world format parser integrating with Bevy ECS, demonstrates how external data is loaded into the game world
• README.md — Framework overview and positioning as a Minecraft server engine built on Bevy ECS, sets architectural expectations

Add a new gameplay feature crate

1. Create new crate directory at crates/valence_feature_name/ with Cargo.toml following the pattern of crates/valence_boss_bar/Cargo.toml (crates/valence_feature_name/Cargo.toml)
2. Implement ECS components and systems in crates/valence_feature_name/src/lib.rs, exporting public plugin/system registration (crates/valence_feature_name/src/lib.rs)
3. Add feature flag in root Cargo.toml under [features] section and add dep:valence_feature_name conditional dependency (Cargo.toml)
4. If feature interacts with protocol, add message handling in system that listens to network packet events from Bevy channels (crates/valence_feature_name/src/lib.rs)

Add a new command argument parser

1. Create parser module at crates/valence_command/src/parsers/custom_type.rs implementing Parse and Serialize traits (crates/valence_command/src/parsers/custom_type.rs)
2. Add mod declaration and re-export in crates/valence_command/src/parsers.rs (crates/valence_command/src/parsers.rs)
3. Register parser in crates/valence_command/src/lib.rs parser registry by adding to the match arm in parse dispatch (crates/valence_command/src/lib.rs)
4. Add integration test demonstrating parser usage with sample input strings (crates/valence_command/tests/parser_integration.rs)

Extend entity types with custom metadata

1. Update crates/valence_entity/extracted/entities.json with new entity type or metadata field matching Minecraft registry format (crates/valence_entity/extracted/entities.json)
2. Modify build.rs code generation in crates/valence_entity/build.rs to handle new metadata fields and generate corresponding Rust code (crates/valence_entity/build.rs)
3. Run cargo build to regenerate entity component definitions (crates/valence_entity/src/lib.rs)
4. Create ECS system in your game crate that reads the new entity component metadata and applies server-side behavior (examples/custom_entity_system.rs)

Add support for a new world format or data source

1. Create parser module in new crate crates/valence_format_name/src/lib.rs mirroring structure of crates/valence_anvil/src/lib.rs (crates/valence_format_name/src/lib.rs)
2. Implement binary parsing logic in crates/valence_format_name/src/parsing.rs for format-specific serialization (crates/valence_format_name/src/parsing.rs)
3. Expose Bevy system that converts parsed world data into ECS entities with standard Valence world components (crates/valence_format_name/src/bevy.rs)
4. Add feature flag in root Cargo.toml and update default features if broadly useful (Cargo.toml)

• Bevy ECS — Provides data-driven architecture for managing thousands of entities (players, mobs, items) with composable systems; enables straightforward parallelization of game logic
• Rust — Memory safety and performance critical for production game servers handling many concurrent connections; strong static typing catches protocol violations at compile time
• CESU-8 encoding (java_string) — Minecraft protocol requires exact Java string encoding compatibility; custom implementation ensures bit-for-bit protocol compliance
• Procedural macros (valence_command_macros) — Reduces boilerplate for command definition and handler binding; enables declarative syntax matching Minecraft command conventions
• Build-time code generation (build.rs) — Converts Minecraft game data (entities.json) into strongly-typed Rust components; keeps codebase in sync with game updates

• Feature-flagged optional subsystems (advancement, boss_bar, equipment, etc.)

  • Why: Server developers often need only subset of functionality; reduces binary size and compile time for minimal servers
  • Consequence: Adds complexity to feature coordination; developers must verify feature compatibility when combining subsystems

• Extracted entity/block data (entities.json, misc.json) regenerated via build.rs

  • Why: Keeps definitions in sync with current Minecraft version; single source of truth prevents drift
  • Consequence: Build process slower for full rebuilds; requires careful data extraction pipeline maintenance

• Command system built on graph structures rather than attribute macros

  • Why: Provides fine-grained control over argument validation; maps closely to Minecraft command semantics
  • Consequence: More verbose command registration than some competing frameworks; steeper learning curve for complex command trees

• Anvil world format parser (valence_anvil) separate from core ECS

  • Why: undefined
  • Consequence: undefined

Bevy ECS learning curve: unfamiliar to developers not using entity-component-system patterns; understand system scheduling (before/after constraints) before adding game logic. CESU-8 strings: Java uses modified UTF-8; java_string crate handles this, but raw string handling will fail. Protocol version pinning: targets only latest Minecraft version; older clients need a proxy (ViaBackwards mentioned in README). Feature flag interdependencies: some plugins may depend on others (e.g., inventory might need network); check crate dependencies. No embedded data files: must generate or provide asset packs separately; the example_pack.zip is an asset, not auto-loaded.

• ECS (Entity-Component-System) — Valence is built entirely on Bevy ECS; understanding entities (players, mobs), components (position, health), and systems (game logic) is foundational to writing any game code.
• NBT (Named Binary Tag) — Minecraft's primary data format for chunks, entities, and items; Valence includes valence_nbt crate as a core library, and you must understand NBT structure to manipulate world data.
• CESU-8 Encoding — Java (and Minecraft) use modified UTF-8; Valence's java_string crate handles this, and raw string handling will fail silently if you ignore it—critical for player names, chat, and metadata.
• Minecraft Protocol Versioning — Valence targets a single Minecraft version; understanding packet IDs, state transitions (handshake → login → play), and protocol evolution is necessary to extend or debug the network layer.
• Anvil Region File Format — Minecraft world persistence uses .mca (anvil) files; valence_anvil crate abstracts this, but you need to know region/chunk/section hierarchy to work with terrain generation or world loading.
• Bevy Plugin System — Valence's modularity is entirely based on Bevy plugins (feature flags like 'inventory', 'advancement' map to crate plugins); writing custom game logic requires authoring plugins.
• Var-Length Integer Encoding — Minecraft protocol uses variable-length encoding for integers (smaller values = fewer bytes); Valence includes benches/var_int.rs and var_long.rs, and protocol codec performance depends on this.

• bevyengine/bevy — Underlying ECS and plugin system; Valence plugins are built as Bevy plugins, so understanding Bevy's architecture is prerequisite.
• PaperMC/Paper — De-facto standard Minecraft server implementation; Valence aims to replicate its protocol compliance and features (advancement system, block states, etc.).
• wiki/wiki.vg — Community-maintained Minecraft protocol documentation; Valence's protocol codec must match wiki.vg specifications exactly.
• ViaVersion/ViaBackwards — Protocol version compatibility layer; Valence README explicitly recommends it for supporting older clients, so understanding ViaBackwards helps with backwards-compatibility testing.
• fastlane/fastlane — Not directly related, but demonstrates monorepo feature-flag patterns similar to Valence's optional plugin architecture.

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 valence_network crate packet encoding/decoding

The valence_network crate is critical for Minecraft server functionality but has minimal visible test coverage in benches/packet.rs. This crate handles protocol serialization which is error-prone. Adding unit tests covering edge cases (var_int boundaries, chunk data encoding, NBT serialization) would prevent regressions and make contributions safer.

• [ ] Review crates/valence_network/src structure for modules lacking tests
• [ ] Add tests in each module for var_int encoding (boundaries: 127, 128, 16383, 16384, etc.)
• [ ] Add tests for packet round-trip encoding/decoding with various data types
• [ ] Add tests for malformed packet handling and error cases
• [ ] Ensure bench/packet.rs benchmarks remain performant after test additions

Create missing README.md files for crates with incomplete documentation

Several crates under crates/ reference README.md in their Cargo.toml but appear to lack detailed setup/usage docs (valence_command, valence_equipment, valence_inventory, valence_player_list, valence_scoreboard, valence_weather, valence_world_border). New contributors need clear examples of how to use these crates.

• [ ] Identify which crates in crates/ are missing or have stub README.md files
• [ ] For each crate, add: purpose statement, feature overview, basic usage example with code snippet
• [ ] Document required features from parent Cargo.toml (e.g., command crate requires 'command' feature)
• [ ] Add cross-references to related crates and main valence README
• [ ] Ensure READMEs follow the format established in crates/java_string/README.md and crates/valence_anvil/README.md

Add GitHub Actions workflow to validate all feature flag combinations compile correctly

With 11+ optional features in Cargo.toml (advancement, anvil, boss_bar, equipment, inventory, etc.), there's significant risk of feature flag combinations causing compilation failures or breaking the default feature set. This is currently only caught on PR review.

• [ ] Create .github/workflows/feature-matrix.yml that tests all 2^11 feature combinations
• [ ] Use cargo hack or iterative approach to test: no-default-features, each single feature, all features
• [ ] Ensure CI passes on linux-gnu, and optionally macos/windows for broader coverage
• [ ] Add check for unused dependencies with cargo-udeps when feature combinations differ
• [ ] Document the new workflow in CONTRIBUTING.md pointing contributors to run it locally before PR

• Add missing documentation examples for crates/valence_nbt/src/lib.rs: the README references 'a speedy new library' but the crate lacks inline code examples showing how to parse/serialize NBT data.
• Expand benches/decode_array.rs: add benchmarks for edge cases (empty arrays, max-size arrays, mixed types) to ensure encoding/decoding doesn't regress.
• Create missing integration test file crates/valence_anvil/tests/region_load.rs: test loading real Minecraft region files to catch protocol incompatibilities early.

The Valence Minecraft server framework shows a generally secure codebase structure with proper use of Rust's type system and Bevy ECS. Primary concerns are: (1) an incomplete/truncated dependency declaration that should be corrected immediately, (2) absence of a SECURITY.md policy file for vulnerability reporting, and (3) the need to verify secure handling of network input and command parsing. The project uses modern Rust tooling and dependency management via workspace features, which is positive. No hardcoded secrets, exposed configurations, or obvious injection vulnerabilities were detected in the provided file structure. Recommended actions: fix the Cargo.toml truncation, add security.md policy, and conduct thorough code review of network packet handling and command parsing implementations.

• Medium · Incomplete Dependency Declaration — Cargo.toml - dependencies section. The Cargo.toml file appears to have a truncated dependency entry for 'valence_player_list' with 'optiona' (likely 'optional' was cut off). This could indicate incomplete or corrupted configuration that might lead to unexpected dependency resolution behavior. Fix: Complete the dependency declaration by ensuring 'valence_player_list' has the full 'optional = true' attribute. Verify all dependencies are properly declared and test the build process.
• Low · Broad Feature Flags in Default Set — Cargo.toml - features section. The default features include 'testing' which is an empty feature flag. While not inherently dangerous, including testing/debug features in production defaults could expose unnecessary code paths or dependencies. Fix: Review whether 'testing' feature should be in the default set. Consider making it opt-in for development builds only. Document the purpose of the 'testing' feature flag.
• Low · Missing Security Policy — Repository root. No SECURITY.md file is present in the repository root. Best practices recommend having a documented security policy for responsible vulnerability disclosure. Fix: Create a SECURITY.md file that includes: instructions for reporting security vulnerabilities, expected response time, and guidelines for responsible disclosure.
• Low · No Dependency Pinning Strategy Visible — Cargo.toml and repository root. The Cargo.toml uses workspace dependencies without visible lock file in the provided structure. Ensure Cargo.lock is committed to the repository for reproducible builds. Fix: Verify that Cargo.lock is committed to the repository. Use 'cargo update' cautiously and test updates thoroughly before merging to main.
• Low · No Input Validation Documentation — valence_network crate and related network handling code. As a Minecraft server framework, the codebase likely handles network packets and player input. While no explicit vulnerabilities are evident from file structure, there's no visible documentation or validation patterns shown. Fix: Implement and document comprehensive input validation for all network packet handling. Review the command parser implementations in valence_command crate for potential injection vectors.

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

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

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