DOCSEARCHbyAlgolia
Submit Docs

Endstone Documentation

repository·main·Indexed 19 days ago

https://github.com/endstonemc/endstone

Endstone is a high-performance Minecraft Bedrock server software that provides a plugin API for Bedrock Dedicated Servers, supporting both Python and C++. It allows for deep gameplay access and extensibility through a layered architecture consisting of a header-only C++ API, Python bindings, a core implementation layer, and a runtime for binary hooks.

Tokens
22.2K
Snippets
69
Records
115
Agent score
69%

What's inside Endstone

  1. Understand the Endstone Feature Roadmap

    main

    The Endstone roadmap outlines the progression of features aimed at achieving parity with Paper (Java) and ScriptAPI (Bedrock). The roadmap is organized into six phases, moving from essential plugin developer tools to advanced world manipulation and ecosystem features.

    Key Phases:

    • Phase 1: Plugin Developer Essentials (High Impact): Focuses on configuration, persistent data, potion effects, entity attributes, and player visibility.
    • Phase 2: Content Creation APIs: Focuses on recipes, block actors (block entities), rich text, and chunk management.
    • Phase 3: Commands & Entity Control: Focuses on typed command arguments, entity AI/pathfinding, and vehicle events.
    • Phase 4: World & Structure APIs: Focuses on structure management, camera control, world borders, and loot tables.
    • Phase 5: External Communication: Focuses on plugin messaging channels and debug visualization.
    • Phase 6: Ecosystem & Advanced: Focuses on world generation and ECS access.

  2. Planned Command Argument System

    main

    To replace the current raw vector<string> argument system, Endstone plans to implement a type-safe command argument system similar to Brigadier. This will support tab completion and specific types like int, float, player, entity, position, block, and item.

    Planned API:

    • CommandBuilder::argument(name, ArgumentType)

  3. Understand the Endstone project structure

    main

    Endstone is composed of several distinct layers that separate the plugin developer experience from the Minecraft Bedrock Dedicated Server (BDS) internals:

    • Endstone API (include/endstone): A header-only C++ API layer. This is the primary interface used to create plugins. It provides version-agnostic abstractions so plugins can work across different Minecraft versions without interfacing directly with Mojang's code.
    • Endstone Python Bindings (src/endstone_python): The bridge that allows developers to write plugins in Python by translating Python API calls into the underlying C++ API calls.
    • Endstone Core (src/endstone_core): The implementation layer that sits between the API and the game. It translates abstracted API calls into specific BDS internal calls.
    • Endstone Runtime (src/endstone_runtime): Contains hooks applied to the BDS executable binary to modify functionality or provide bug fixes that the standard API cannot reach.
    • Endstone DevTools (src/endstone_devtools): A GUI (Windows only, requires OpenGL) used to dump data from the vanilla software.

  4. Planned Block Actor (Block Entity) API

    main

    Developers will be able to access and modify data for block entities like chests, signs, furnaces, and hoppers. This will extend the existing BlockState system.

    Planned Implementation:

    • Use the BlockActor base class for save/load via CompoundTag.
    • Type-specific subclasses for Sign, Chest, Furnace, etc.

  5. Planned Configuration API

    main

    Endstone plans to implement a standard Configuration API to allow plugins to manage persistent settings without manual file I/O. This will include support for YAML or TOML formats.

    Planned Methods:

    • Plugin::saveDefaultConfig()
    • Plugin::getConfig()
    • Plugin::reloadConfig()
    • Plugin::saveConfig()
    • Plugin::getDataFolder() (already exists in include/endstone/plugin/plugin.h)

  6. Planned Potion Effect Management

    main

    Endstone plans to expose the existing Bedrock layer to allow developers to manage potion effects on entities. Currently, the EffectType registry exists, but there are no public methods to manipulate effects.

    Planned API for Mob:

    • addEffect(type, duration, amplifier)
    • removeEffect(type)
    • getEffect(type)
    • getActiveEffects()

    This will use a PotionEffect wrapper class containing duration, amplifier, ambient, particles, and icon data.

  7. Planned Entity Attribute Access

    main

    To enable RPG-style plugins and custom combat mechanics, Endstone plans to expose the Attribute registry (including 17 types and AttributeModifier) through the Mob class.

    Planned API:

    • Mob::getAttribute(type) -> AttributeInstance

  8. Planned Persistent Data Container (PDC)

    main

    To bridge the gap between Paper and ScriptAPI, Endstone plans to implement a PersistentDataHolder interface. This allows storing arbitrary typed key-value data on entities, items, and the world that persists across restarts.

    Implementation Details:

    • Data will be stored via namespaced NBT subtags (e.g., endstone:custom_data).
    • ItemStack already supports NBT via getNbt() and setNbt().
    • The API will provide typed get, set, has, and remove methods using NamespacedKey.

  9. Choose between the Python and C++ APIs

    main

    Endstone provides two distinct APIs for plugin development depending on your requirements:

    • Python API: Recommended for a quick start and high flexibility. Use this if you want to prototype quickly or prefer Python's ease of use.
    • C++ API: Recommended for performance-critical tasks. Use this if you need to implement highly optimized, performance-driven code.

  10. Use user-defined enum types in commands

    main

    You can define custom enumeration types for command parameters to restrict input to a specific set of string constants. This is useful for creating commands with specific modes or actions.

    Syntax:

    • Mandatory: (value1|value2|value3)<name: EnumType>
    • Optional: (value1|value2|value3)[name: EnumType]

    Values are separated by the pipeline operator | and enclosed in parentheses ().

    Example usage syntax:
/home (add|list|del)<action: HomeAction>

  11. Planned Chunk API

    main

    Endstone aims to expand the minimal Chunk implementation to allow for full world manipulation. This includes enabling ChunkLoadEvent and ChunkUnloadEvent.

    Planned API for Chunk:

    • getBlock(x, y, z)
    • getEntities()
    • isLoaded()
    • isGenerated()
    • isSlimeChunk()
    • setForceLoaded(bool)

    Planned API for Dimension:

    • getForceLoadedChunks()
    • getChunkAtAsync(x, z) (returning a future/callback)

  12. Planned Recipe API

    main

    Endstone plans to allow plugins to register custom recipes at runtime, including shaped, shapeless, and furnace recipes. This will involve sending CraftingDataPacket to clients to sync the changes.

    Planned API:

    • Server::addRecipe(recipe)
    • Server::removeRecipe(recipe)
    • Supported types: ShapedRecipe, ShapelessRecipe, FurnaceRecipe.