CLAUDE.md

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

Project Overview

Endstone is a plugin API for Minecraft Bedrock Dedicated Servers (BDS), supporting both Python and C++ plugins. It hooks into the BDS binary to expose a high-level Bukkit-like API for plugin development.

Build Commands

Prerequisites

• Windows: clang-cl + lld-link (LLVM 18+, e.g. the "C++ Clang tools for Windows" component of Visual Studio 2022), plus the MSVC toolchain for the Windows SDK and STL headers, and CMake 3.29+
• Linux: Clang 18+ with libc++
• CMake, Ninja, Conan 2.0+

LLVM 18+ is the hard minimum: the public API headers use std::format, which is only complete in libc++ from LLVM 18.

Install dependencies with Conan

The project ships .conan2/profiles/default (a Jinja-templated profile) that auto-detects the host compiler and pins the right settings: clang-cl on Windows, clang/libc++ on Linux, Ninja generator. Do not run conan profile detect — it would overwrite this file. Just:

pip install conan
conan install . --build=missing

Windows: run from a Visual Studio Developer prompt with clang-cl/lld-link on PATH.

Activate Conan build environment (only for the manual CMake path)

# Windows (cmd)
.\build\RelWithDebInfo\generators\conanbuild.bat

# Linux
source ./build/RelWithDebInfo/generators/conanbuild.sh

Build with CMake

cmake --preset conan-relwithdebinfo
cmake --build --preset conan-relwithdebinfo

The profile builds dependencies as Release but the project itself as RelWithDebInfo (&:build_type=RelWithDebInfo), so conan-relwithdebinfo is the only preset Conan generates. NDEBUG is still defined, so the BEDROCK_STATIC_ASSERT_SIZE layout checks are active.

Install from source (builds Python wheel)

The PEP 517 backend (conan-py-build) runs Conan internally, so no separate conan install step is required:

pip install -U .
# or with uv:
uv pip install -U .

To keep the C++ build tree persistent across reinstalls (much faster after the first build), pass a build dir via config_settings:

pip install -U . -C build-dir=./build

Testing

C++ tests (GTest)

ctest --test-dir build/RelWithDebInfo

Python tests

pytest tests/endstone/python

Code Style

C++ (clang-format + clang-tidy)

• Based on Microsoft style with Stroustrup braces
• Naming conventions (from .clang-tidy):
  • Classes/Structs/Enums: CamelCase
  • Methods: camelBack
  • Private/protected members: lower_case_ (trailing underscore)
  • Local variables/parameters: lower_case
  • Macros: UPPER_CASE

Python (ruff)

• Line length: 120 characters
• Enabled rules: I (isort), F (pyflakes)

Comments (all languages)

• Keep comments terse and human. Default to no comment; when one is warranted, one short line.
• Config comments (endstone.default.toml and friends) say what the setting does, not why it exists or how it works.
• No multi-line explanations, rationale, design-decision narration, or parenthetical asides.
• Do not leave "LLM notes" — comments that explain why a change was made, reference the development process, or restate what the code plainly does.
• Match the comment density and verbosity of the surrounding or original code (e.g. a port stays as terse as its upstream).

Architecture

Source Structure

• include/endstone/ - Public C++ API headers (header-only library for plugin development)
• src/bedrock/ - Bedrock server type definitions and reverse-engineered structures
• src/endstone/core/ - Core implementation of the Endstone API
• src/endstone/runtime/ - Runtime hooks into BDS via funchook (bedrock_hooks/ subdirectory)
• src/endstone/python/ - Python bindings via pybind11
• endstone/ - Python package (CLI, plugin loader, metrics)

Key Components

1. Runtime Hooks (src/endstone/runtime/bedrock_hooks/): Intercepts BDS functions to inject Endstone behavior. Each hook file corresponds to a BDS subsystem (player, level, network, etc.).
2. Bedrock Layer (src/bedrock/): Type-compatible structures matching BDS internal types. Required for ABI compatibility when hooking.
3. Core Layer (src/endstone/core/): Implements the public API by wrapping bedrock types. Contains subsystems: command, event, inventory, level, plugin, scheduler, scoreboard.
4. Plugin System: Supports both C++ plugins (loaded as shared libraries with endstone_ prefix) and Python plugins (loaded via endstone.plugin.plugin_loader).

Plugin Development

C++ plugins link against endstone::endstone (header-only) and use the endstone_add_plugin() CMake function. Python plugins inherit from endstone.plugin.Plugin.

Dependencies

Core dependencies managed via Conan: fmt, boost, pybind11, spdlog, nlohmann_json, entt, magic_enum, sentry-native. See conanfile.py for full list.

Conan Recipes

Custom third-party recipes live under recipes/ and are published to the endstone Cloudsmith remote.

• Upload recipes only, never prebuilt binaries. Let consumers and CI build the binaries from source: conan upload "<name>/<version>" -r endstone --only-recipe -c.

Git Conventions

• Never add a Co-Authored-By line for Claude when creating commits.
• CHANGELOG.md must strictly follow Keep a Changelog 1.1.0:
  • Write for humans (server admins and plugin developers), not machines.
  • Every version gets an entry; latest version comes first.
  • Group changes by type: Added, Changed, Deprecated, Removed, Fixed, Security.
  • Versions and sections must be linkable (reference-style links at bottom).
  • Display the release date of each version.
  • Include user-visible changes and API changes; omit internal implementation details (no refactoring notes, no internal class/struct changes).
  • One short sentence per entry: state what changed, not why or how.
  • Append the issue number when a fix closes an issue, e.g. (#528).
  • Do not list fixes for bugs introduced by unreleased work, such as a BDS bump in the same release.
  • Do not list fixes with no visible effect on the release branch, such as a back-port for an API that only exists on develop.
  • Do not add caveats that read as restrictions, such as "Only 1.26.51 clients can join" or a transport warning Bedrock logs but does not enforce.
  • Prefix breaking changes with **BREAKING**: in the Changed or Removed section.