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/feather-rs/feather 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

• 25+ active contributors
• Distributed ownership (top contributor 16% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 2y 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 feather-rs/feather repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/feather-rs/feather.

What it runs against: a local clone of feather-rs/feather — 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 feather-rs/feather | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | 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 ≤ 786 days ago | Catches sudden abandonment since generation |

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

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 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 "feather/base/src/lib.rs" \\
  && ok "feather/base/src/lib.rs" \\
  || miss "missing critical file: feather/base/src/lib.rs"
test -f "feather/common/src/entities.rs" \\
  && ok "feather/common/src/entities.rs" \\
  || miss "missing critical file: feather/common/src/entities.rs"
test -f "feather/blocks/src/lib.rs" \\
  && ok "feather/blocks/src/lib.rs" \\
  || miss "missing critical file: feather/blocks/src/lib.rs"
test -f "feather/base/src/anvil.rs" \\
  && ok "feather/base/src/anvil.rs" \\
  || miss "missing critical file: feather/base/src/anvil.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 786 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~756d)"
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/feather-rs/feather"
  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).

Feather is a Minecraft server implementation written in Rust that aims to be fast, modular, and extensible via WebAssembly plugins. It parses and serves Minecraft 1.16.5 worlds using the Anvil format (stored in feather/base/src/anvil/), manages chunk loading via packed arrays and palettes (feather/base/src/chunk/), and runs untrusted plugin code in a sandboxed WASM VM via the Quill plugin API. The core value proposition is minimal-feature, high-performance gameplay suitable for hub and minigame servers. Workspace monorepo with three logical layers: libcraft/ (7 core crates: blocks, items, particles, text, inventory, generators, macros) providing Minecraft primitives; Quill/ (5+ crates: sys, api, plugin-format, cargo-quill, plus 8 example plugins) for WASM plugin infrastructure; feather/ (9 crates: base, blocks, ecs, protocol, datapacks, worldgen, server, plugin-host) implementing the server. The base layer (feather/base/src/anvil/, feather/base/src/chunk/) handles world serialization and chunk management. ECS pattern is used (feather/ecs/).

Rust developers and Minecraft server operators who want to run lightweight, modular minigame or hub servers with custom plugin logic, without the overhead of vanilla Minecraft Server or Spigot. Plugin developers targeting the Rust/WASM ecosystem specifically (via Quill plugins compiled to wasm32-unknown-unknown).

The project is inactive and experimental. The README explicitly states 'This project is currently inactive. Consider contributing to valence instead.' CI/CD pipelines exist (.github/workflows/main.yml and release.yml), but there are no commit dates visible in the file list to confirm recent activity. The codebase is well-structured with 5M+ lines of Rust, but the official guidance is to look elsewhere for active development.

High abandonment risk: the maintainers explicitly recommend contributors switch to Valence. The workspace is large (40+ member crates) with complex interdependencies across libcraft, Quill, and Feather proper, making maintenance burden significant. Breaking changes in Rust ecosystem (especially around WASM tooling) are likely unaddressed. No visible test suite mentioned in file structure, and 1.16.5 support is frozen (no multiversion strategy).

No active development. The repository is a snapshot of a completed but abandoned project. The last significant work appears to have been on Quill plugin infrastructure and example plugins (query-entities, block-access, observe-creativemode-flight-event). No open PRs, milestones, or issues visible in the metadata provided.

Clone and build with Cargo:

git clone https://github.com/feather-rs/feather.git
cd feather
cargo build --release -p feather-server

Run the server binary from the release build directory. Requires Rust 1.56+ (inferred from WASM tooling in Quill). Precompiled binaries available from GitHub Actions workflow artifacts (not GitHub Releases, which are outdated per README).

Daily commands:

cargo build --release -p feather-server
./target/release/feather-server

Server listens for Minecraft 1.16.5 clients on default port (19132 or 25565, not specified in files). Loads world from ./world/ or creates new world in current directory. No explicit configuration file mentioned; world NBT and player data stored in Anvil format.

• Cargo.toml — Workspace root defining all members (feather, libcraft, quill) and their interdependencies; essential for understanding project structure and build order.
• feather/base/src/lib.rs — Core abstraction layer for chunks, blocks, entities, and anvil I/O; foundational for all feather server functionality.
• feather/common/src/entities.rs — Entity system definition and trait definitions; critical for server entity management and behavior.
• feather/blocks/src/lib.rs — Block registry and generated block properties; central to block state management across the server.
• feather/base/src/anvil.rs — Anvil format parser for world persistence; handles all save/load operations for levels, chunks, and entities.
• feather/common/src/chunk/mod.rs — Chunk management and caching system; orchestrates chunk loading, entity tracking, and client visibility.
• docs/architecture.md — High-level design document explaining the modular architecture, plugin system, and layering approach.

Add a New Entity Type

1. Create a new file in feather/common/src/entities/ named after your entity (e.g., phantom.rs) with position, velocity, and type-specific metadata fields. (feather/common/src/entities/phantom.rs)
2. Implement the Entity trait from feather/common/src/entities.rs and define any custom behavior methods. (feather/common/src/entities.rs)
3. Add the module declaration in feather/common/src/entities.rs (e.g., pub mod phantom;) and export the struct. (feather/common/src/entities.rs)
4. Add NBT deserialization logic in feather/base/src/anvil/entity.rs to load the entity from saved world data. (feather/base/src/anvil/entity.rs)

Add a New Plugin Event

1. Define a new struct in quill/api/src/events/ inheriting from the appropriate event trait (e.g., PlayerEvent, BlockEvent). (quill/api/src/events/mod.rs)
2. Use the #[quill_event] macro to register the event and auto-generate FFI bindings. (quill/api/plugin-macro/src/lib.rs)
3. Emit the event from the main server loop in the appropriate handler (e.g., tick, player join) by creating the event struct and calling the dispatcher. (feather/common/src/entities.rs)

Add Support for a New Block Variant

1. Update the block data source (typically a JSON registry) in feather/blocks/generator/ or manually in vanilla data files. (feather/blocks/generator/src/load.rs)
2. Run the block generator to regenerate feather/blocks/src/generated/ files (properties, table.dat, block_fns.rs). (feather/blocks/generator/src/main.rs)
3. Add any custom collision, rendering, or behavioral logic in feather/base/src/block.rs or entity-specific handlers. (feather/base/src/block.rs)

Extend the Anvil Persistence Format

1. Add deserialization code for new NBT tags in the appropriate file (e.g., feather/base/src/anvil/entity.rs for entities, feather/base/src/anvil/player.rs for player data). (feather/base/src/anvil/entity.rs)
2. Update the serialization helper in feather/base/src/anvil/serialization_helper.rs to encode/decode new compound types. (feather/base/src/anvil/serialization_helper.rs)
3. Add tests or integration points in the chunk worker to ensure round-trip serialization/deserialization works. (feather/common/src/chunk/worker.rs)

• Rust — Memory safety without garbage collection, zero-cost abstractions, and excellent multi-threading support for concurrent chunk loading and entity updates.
• NBT (Named Binary Tag) via Anvil format — Standard Minecraft world persistence format; enables direct compatibility with vanilla saves and tools.
• ECS-style entity component system (trait-based) — Modular entity behavior without inheritance; allows plugins to extend entities via traits and attached metadata.
• Plugin system via Quill (FFI + code generation) — Sandboxed plugin isolation, stable ABI across versions, and ergonomic Rust API for server extensibility.
• Palette-based block compression — Reduces chunk memory footprint by ~10× for most terrain; critical for server scalability with large view distances.

• Single-version support (1.16.5 only)

  • Why: Reduces protocol implementation burden and complexity; allows deeper optimization for one client version.
  • Consequence: Existing players on other versions must use proxies or downgrade clients; multiversion parity is non-goal.

• Chunk worker pool with async I/O

  • Why: Prevents blocking the main tick loop during disk reads; maintains server responsiveness.
  • Consequence: Added complexity for chunk state synchronization and eventual consistency; potential race conditions if not carefully managed.

• Plugin system as separate compilation units (not hot-reload)

  • Why: Simplifies safety guarantees and ABI stability; avoids runtime linking complexity.
  • Consequence: Plugins require full server restart to deploy; no live-reload capability.

• Focus on minigame/hub servers rather than full survival

  • Why: Reduced scope allows faster iteration and better plugin ecosystem for common use cases.
  • Consequence: Missing many vanilla mechanics (redstone, farming, breeding); unsuitable for survival mode servers.

• Full vanilla Minecraft feature parity (redstone, complex mob AI,

WASM toolchain required: Building Quill plugins requires wasm32-unknown-unknown target installed (rustup target add wasm32-unknown-unknown). NBT serialization fragile: Anvil format parsing in feather/base/src/anvil/serialization_helper.rs is tightly coupled to Minecraft 1.16.5 NBT schema; upgrading versions will break. Chunk lock contention: feather/base/src/chunk_lock.rs uses a simple locking mechanism that may bottleneck under heavy concurrent chunk access. No hot reload: Plugins require full server restart to reload. Metadata encoding: feather/base/src/metadata.rs is hand-encoded; updating for new entity properties is error-prone.

• Anvil Format — Feather's world persistence depends entirely on correct Anvil parsing (NBT-based region file format). Understanding chunk boundaries, tag structures, and compression is essential for debugging world loading bugs.
• Bit-Packed Arrays (Packed Array Format) — Block data in chunks uses variable-bit-width packing (4-15 bits per block depending on palette size) to minimize memory; feather/base/src/chunk/packed_array.rs is performance-critical and non-obvious.
• Block Palette — Minecraft uses indirect indexing via palettes to store blocks efficiently; Feather's palette implementation in feather/base/src/chunk/palette.rs must correctly map palette indices to block states for protocol compliance.
• Entity Component System (ECS) — Feather's architecture is built on ECS principles (feather/ecs/) for decoupling entity behaviors; essential for understanding how plugins interact with players, mobs, and items without tight coupling.
• WebAssembly Sandboxing — The Quill plugin API compiles untrusted user code to WASM and runs it in an isolated VM; understanding WASM memory isolation and capability-based security is critical for plugin security review.
• Named Binary Tag (NBT) — Minecraft's data serialization format used for world files, player data, and item NBT tags; feather/base/src/anvil/serialization_helper.rs depends on correct NBT parsing for all persistence.
• Minecraft Protocol — Client-server communication happens via versioned protocol packets defined in feather/protocol/; any client-facing change requires understanding packet structure, encoding, and version compatibility (locked to 1.16.5).

• valence-rs/valence — Active successor project; the Feather maintainers explicitly recommend contributors move here for continued development of a performant Rust Minecraft server
• feather-rs/libcraft — Extracted Minecraft primitives library from Feather; provides reusable blocks, items, and text encoding for other Rust Minecraft projects
• PrismarineJS/node-minecraft-protocol — JavaScript equivalent protocol implementation; useful for understanding Minecraft protocol design decisions and testing interoperability
• SpigotMC/Spigot — Industry standard Java Minecraft server; Feather's plugin API is inspired by Spigot but targets WASM instead of JVM bytecode
• StacksmashNT/RustMC-Core — Alternative Rust Minecraft server implementation with similar goals; reference for architectural patterns and performance optimization techniques

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 feather/base/src/anvil/ serialization modules

The anvil module handles critical Minecraft world persistence (block_entity.rs, entity.rs, level.rs, player.rs, region.rs). These modules lack visible test coverage despite being core infrastructure. Adding unit tests for NBT serialization/deserialization and region file parsing would catch regressions early and make the codebase more maintainable for contributors working on world loading/saving features.

• [ ] Create feather/base/src/anvil/tests/ directory
• [ ] Add unit tests in feather/base/src/anvil/block_entity.rs for NBT serialization roundtrips
• [ ] Add unit tests in feather/base/src/anvil/region.rs for chunk data encoding/decoding
• [ ] Add integration test in feather/base/tests/ for loading a sample Minecraft region file
• [ ] Document test coverage in CONTRIBUTING.md for anvil module maintainers

Add missing GitHub Actions workflow for clippy and fmt checks on PRs

The repository has main.yml and release.yml workflows, but no explicit CI job enforcing rust code style (rustfmt) and linting (clippy) on pull requests. Given the presence of .rustfmt.toml, adding a dedicated workflow would catch style issues before merge and reduce friction in code review.

• [ ] Create .github/workflows/lint.yml with clippy job (cargo clippy --all-targets --all-features -- -D warnings)
• [ ] Add rustfmt check job (cargo fmt -- --check) in the same workflow
• [ ] Configure workflow to run on PR creation and pushes to main branches
• [ ] Update CONTRIBUTING.md to document that PRs must pass clippy and rustfmt checks

Document feather/ecs/ module architecture with examples

The workspace includes a feather/ecs crate (visible in Cargo.toml members list), but there is no corresponding documentation file or README explaining the ECS system design. Given that the plugin API (quill) depends on this system and docs/architecture.md exists, contributors and plugin developers need specific documentation on the ECS module's structure, usage patterns, and how to add custom components/systems.

• [ ] Create docs/ecs-architecture.md covering ECS module design and key abstractions
• [ ] Add code examples for defining custom components and systems in the ECS doc
• [ ] Add a reference section linking to feather/ecs/src/ modules
• [ ] Update CONTRIBUTING.md with a link to the ECS architecture guide for plugin developers
• [ ] Optionally add a README.md in feather/ecs/ with a quick-start example

• Add unit tests for feather/base/src/chunk/palette.rs and feather/base/src/chunk/packed_array.rs block serialization round-trips; currently no test coverage visible and these are critical for chunk integrity.
• Write integration tests for Anvil format round-trip in feather/base/src/anvil/level.rs; verify that loading and re-saving a world preserves block state, entities, and player data without loss.
• Document the chunk coordinate system and biome storage model in docs/ with diagrams; feather/base/src/chunk/biome_store.rs is undocumented and learners struggle to understand the 4x4 biome grid vs. block grid mapping.

• High · Inactive Project with Outdated Dependencies — README.md, Cargo.lock. The project is explicitly marked as inactive in the README, with a recommendation to use 'valence' instead. This means security updates and vulnerability patches are unlikely to be applied. The Cargo.lock file indicates a large dependency tree that may contain unpatched security vulnerabilities. Fix: Consider migrating to actively maintained alternatives like valence-rs/valence. If continued use is necessary, regularly audit and update dependencies using 'cargo audit' and 'cargo update'.
• High · Outdated Minecraft Protocol Support — README.md, feather/protocol. The project only supports Minecraft 1.16.5 clients, which is significantly outdated (released November 2020). This version may have known security vulnerabilities in the protocol implementation that are not being patched. Fix: Update to support recent Minecraft versions. Implement protocol security patches as they are released. Consider implementing version negotiation to support multiple versions.
• Medium · Potential Deserialization Vulnerabilities in NBT Processing — feather/base/src/anvil/, feather/base/src/chunk/. The codebase includes NBT file parsing (assets/dimension.nbt, assets/dimension_codec.nbt) and Anvil format handling (feather/base/src/anvil/). Binary deserialization of untrusted data without apparent validation could lead to arbitrary code execution or DoS attacks. Fix: Implement strict validation of NBT and Anvil format data. Use fuzzing to test deserialization paths. Consider using well-audited serialization libraries and implement size limits on deserialized objects.
• Medium · Unsafe Code in Chunk Data Structures — feather/base/src/chunk/packed_array.rs, feather/base/src/chunk/light.rs. The packed array implementation (feather/base/src/chunk/packed_array.rs) and light data structures likely contain unsafe Rust code for performance. Without careful review, this could introduce memory safety issues. Fix: Conduct a thorough security audit of all unsafe blocks. Add comprehensive tests including fuzzing. Consider using safe alternatives or well-audited libraries for bit-packing operations.
• Medium · Plugin System Security Risks — feather/plugin-host/, quill/api/. The plugin host system (feather/plugin-host/) allows arbitrary code execution through plugins. There is no apparent sandboxing or permission system visible in the file structure to restrict plugin capabilities. Fix: Implement a capability-based security model for plugins. Add plugin signature verification and approval mechanisms. Document security best practices for plugin developers. Consider implementing resource limits (CPU, memory, file I/O).
• Medium · Unrestricted File I/O in Anvil World Format Handler — feather/base/src/anvil/region.rs, feather/base/src/anvil/player.rs. World save files are processed from the feather/base/src/anvil/ module. If world data comes from untrusted sources, malicious NBT data could cause path traversal attacks or excessive file operations. Fix: Validate all file paths to prevent directory traversal. Implement rate limiting on file operations. Sanitize world data before processing. Use a whitelist approach for allowed file paths.
• Medium · Chat Processing Without Apparent Input Validation — feather/common/src/chat.rs. The chat module (feather/common/src/chat.rs) processes player chat messages. Without proper input validation and sanitization, this could be vulnerable to injection attacks or command injection. Fix: Implement strict input validation for chat messages. Use parameterized commands to prevent command injection. Implement chat message length limits. Consider using an allowlist for special characters.
• Low · Missing Security Headers Documentation — .github/workflows/. No evidence of security headers, CORS configuration, or authentication documentation in visible configuration files. Fix: Document security configuration for deployments. Add security headers to any HTTP APIs. Implement proper authentication and authorization checks.
• Low · Git Submodules Without Integrity Verification — undefined. The .gitmodules file indicates use of submodules Fix: undefined

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.