bedrockplus 0.1.0.dev1__py3-none-win_amd64.whl

bedrockplus/objects.py

@@ -0,0 +1,413 @@
+"""Small typed object layer built on the stable BedrockPlus host API.
+
+These wrappers deliberately expose only operations that the current host can
+perform reliably. Command-backed methods return queue acceptance; they do not
+claim that BDS successfully completed the command.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+
+from .api import PluginHost
+
+
+_FORMAT_CODE = re.compile(r"&([0-9a-fk-or])", re.IGNORECASE)
+_RESOURCE_ID = re.compile(r"^[a-z0-9_.-]+:[a-z0-9_./-]+$")
+
+
+def _format_message(message: str) -> str:
+    """Translate plugin-friendly ``&a`` formatting to Minecraft ``§a``."""
+    if not isinstance(message, str):
+        raise TypeError("message must be a string")
+    if "\x00" in message or "\r" in message or "\n" in message:
+        raise ValueError("message may not contain NUL or line breaks")
+    if len(message) > 4096:
+        raise ValueError("message exceeds 4096 characters")
+    return _FORMAT_CODE.sub(lambda match: f"§{match.group(1)}", message)
+
+
+def _command_line(command: str) -> str:
+    if not isinstance(command, str):
+        raise TypeError("command must be a string")
+    command = command.strip()
+    if command.startswith("/"):
+        command = command[1:].lstrip()
+    if not command:
+        raise ValueError("command may not be empty")
+    if "\x00" in command or "\r" in command or "\n" in command:
+        raise ValueError("command may not contain NUL or line breaks")
+    if len(command) > 4096:
+        raise ValueError("command exceeds 4096 characters")
+    return command
+
+
+def _selector_name(name: str) -> str:
+    if not isinstance(name, str):
+        raise TypeError("player name must be a string")
+    name = name.strip()
+    if not name:
+        raise ValueError("player name may not be empty")
+    if "\x00" in name or "\r" in name or "\n" in name:
+        raise ValueError("player name may not contain NUL or line breaks")
+    if len(name) > 128:
+        raise ValueError("player name exceeds 128 characters")
+    escaped = name.replace("\\", "\\\\").replace('"', '\\"')
+    return f'@a[name="{escaped}",c=1]'
+
+
+def _optional_int(value: str | None) -> int | None:
+    if value is None or value == "":
+        return None
+    try:
+        return int(value)
+    except ValueError:
+        return None
+
+
+def _optional_float(value: str | None) -> float | None:
+    if value is None or value == "":
+        return None
+    try:
+        parsed = float(value)
+    except ValueError:
+        return None
+    return parsed if math.isfinite(parsed) else None
+
+
+@dataclass(frozen=True, slots=True)
+class Vector3:
+    """Immutable three-dimensional position or direction snapshot."""
+
+    x: float
+    y: float
+    z: float
+
+    def __post_init__(self) -> None:
+        for value in (self.x, self.y, self.z):
+            if not isinstance(value, (int, float)) or not math.isfinite(value):
+                raise ValueError("Vector3 values must be finite numbers")
+
+
+@dataclass(frozen=True, slots=True)
+class SocketAddress:
+    """A copied network endpoint; no native connection object is retained."""
+
+    host: str
+    port: int
+
+    def __post_init__(self) -> None:
+        if not self.host or "\x00" in self.host or len(self.host) > 255:
+            raise ValueError("host must be a bounded non-empty string")
+        if not 0 <= self.port <= 65535:
+            raise ValueError("port must be between 0 and 65535")
+
+
+@dataclass(frozen=True, slots=True)
+class ConnectionInfo:
+    """Optional client-connection facts copied from an authenticated event.
+
+    Availability is capability-based. Unsupported or unavailable properties are
+    ``None``/empty rather than guessed. Device IDs and IP addresses are sensitive
+    personal data and should not be logged or persisted without a clear need.
+    """
+
+    address: SocketAddress | None = None
+    ping_ms: int | None = None
+    device_id: str = ""
+    device_model: str = ""
+    device_os: str = ""
+    input_mode: str = ""
+    game_version: str = ""
+    locale: str = ""
+    client_fps: float | None = None
+
+    def __post_init__(self) -> None:
+        if self.ping_ms is not None and self.ping_ms < 0:
+            raise ValueError("ping_ms may not be negative")
+        if self.client_fps is not None and (
+            not math.isfinite(self.client_fps) or self.client_fps < 0
+        ):
+            raise ValueError("client_fps must be a finite non-negative value")
+
+
+@dataclass(frozen=True, slots=True)
+class Location:
+    """Copied world location suitable for event snapshots."""
+
+    level_name: str
+    dimension_id: str
+    position: Vector3
+    yaw: float = 0.0
+    pitch: float = 0.0
+
+    def __post_init__(self) -> None:
+        if not self.level_name or len(self.level_name) > 128:
+            raise ValueError("level_name must be a bounded non-empty string")
+        if not self.dimension_id or len(self.dimension_id) > 128:
+            raise ValueError("dimension_id must be a bounded non-empty string")
+        if not math.isfinite(self.yaw) or not math.isfinite(self.pitch):
+            raise ValueError("yaw and pitch must be finite")
+
+
+@dataclass(frozen=True, slots=True)
+class Level:
+    """Lightweight identity for a BDS level and dimension."""
+
+    server: Server
+    name: str
+    dimension_id: str = "minecraft:overworld"
+
+
+@dataclass(frozen=True, slots=True)
+class Entity:
+    """Copied entity identity; it never exposes or retains a BDS pointer."""
+
+    server: Server
+    runtime_id: int
+    type_id: str
+    location: Location | None = None
+
+    def __post_init__(self) -> None:
+        if self.runtime_id < 0:
+            raise ValueError("runtime_id may not be negative")
+        if not _RESOURCE_ID.fullmatch(self.type_id):
+            raise ValueError("type_id must be a namespaced resource identifier")
+
+
+@dataclass(frozen=True, slots=True)
+class ItemStack:
+    """Immutable item snapshot used by inventory and item events."""
+
+    type_id: str
+    amount: int = 1
+    aux_value: int = 0
+    custom_name: str = ""
+
+    def __post_init__(self) -> None:
+        if not _RESOURCE_ID.fullmatch(self.type_id):
+            raise ValueError("type_id must be a namespaced resource identifier")
+        if not 0 <= self.amount <= 255:
+            raise ValueError("amount must be between 0 and 255")
+        if len(self.custom_name) > 1024 or any(c in self.custom_name for c in "\x00\r\n"):
+            raise ValueError("custom_name is invalid")
+
+
+class Server:
+    """Plugin-scoped view of the running BedrockPlus server."""
+
+    def __init__(self, host: PluginHost) -> None:
+        self._host = host
+
+    @property
+    def name(self) -> str:
+        """Product name for this server runtime."""
+        return "BedrockPlus"
+
+    @property
+    def api_version(self) -> int:
+        """BedrockPlus plugin API version implemented by this object."""
+        return 1
+
+    @property
+    def data_directory(self) -> Path:
+        """Private writable data directory for the calling plugin."""
+        return Path(self._host.data_directory())
+
+    def dispatch_command(self, command: str) -> bool:
+        """Queue a vanilla or BedrockPlus command as the server console."""
+        return self._host.dispatch_server_command(_command_line(command))
+
+    def broadcast(self, message: str) -> bool:
+        """Queue a tellraw message for every online player.
+
+        Minecraft formatting such as ``&aGreen`` is translated to ``§aGreen``.
+        The JSON payload is ASCII-safe for the Windows BDS console boundary.
+        """
+        payload = json.dumps(
+            {"rawtext": [{"text": _format_message(message)}]},
+            ensure_ascii=True,
+            separators=(",", ":"),
+        )
+        return self.dispatch_command(f"tellraw @a {payload}")
+
+    def player(self, name: str, session_id: str = "") -> Player:
+        """Create a lightweight player reference from known identity fields."""
+        return Player(server=self, name=name, session_id=session_id)
+
+    def level(
+        self,
+        name: str = "BedrockPlus",
+        dimension_id: str = "minecraft:overworld",
+    ) -> Level:
+        """Create a lightweight level/dimension identity."""
+        return Level(server=self, name=name, dimension_id=dimension_id)
+
+    def entity(
+        self,
+        runtime_id: int,
+        type_id: str,
+        location: Location | None = None,
+    ) -> Entity:
+        """Create a copied entity snapshot without retaining native state."""
+        return Entity(self, runtime_id, type_id, location)
+
+    def item_stack(
+        self,
+        type_id: str,
+        amount: int = 1,
+        aux_value: int = 0,
+        custom_name: str = "",
+    ) -> ItemStack:
+        """Create an immutable item value for plugin-owned state and commands."""
+        return ItemStack(type_id, amount, aux_value, custom_name)
+
+    def player_from_event(self, event: Mapping[str, object]) -> Player:
+        """Create a player reference from any event containing player fields.
+
+        ``Mapping`` is intentional here: specialized event ``TypedDict`` types
+        such as :class:`PlayerJoinEvent` narrow ``fields`` to their own schema
+        and therefore are not type-compatible with the mutable generic
+        :class:`Event` dictionary.
+        """
+        raw_fields = event.get("fields")
+        if not isinstance(raw_fields, Mapping):
+            raise ValueError("event does not contain player fields")
+
+        def text_field(key: str) -> str:
+            value = raw_fields.get(key)
+            return value if isinstance(value, str) else ""
+
+        name = text_field("player.name")
+        if not name:
+            raise ValueError("event does not contain player.name")
+        address = None
+        address_host = text_field("player.address")
+        address_port = _optional_int(text_field("player.port"))
+        if address_host and address_port is not None:
+            try:
+                address = SocketAddress(address_host, address_port)
+            except ValueError:
+                address = None
+        connection_values = (
+            address,
+            _optional_int(text_field("player.ping_ms")),
+            text_field("player.device_id"),
+            text_field("player.device_model"),
+            text_field("player.device_os"),
+            text_field("player.input_mode"),
+            text_field("player.game_version"),
+            text_field("player.locale"),
+            _optional_float(text_field("player.client_fps")),
+        )
+        connection = (
+            ConnectionInfo(*connection_values)
+            if any(value not in (None, "") for value in connection_values)
+            else None
+        )
+        return Player(
+            server=self,
+            name=name,
+            session_id=text_field("player.session"),
+            unique_id=text_field("player.uuid"),
+            xuid=text_field("player.xuid"),
+            connection=connection,
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class Player:
+    """Lightweight player identity with command-backed operations.
+
+    A ``Player`` does not keep a native BDS pointer and does not imply that the
+    player is still connected. It is safe to retain as identity data, while
+    methods may later be accepted by the queue but fail in BDS if the player left.
+    """
+
+    server: Server
+    name: str
+    session_id: str = ""
+    unique_id: str = ""
+    xuid: str = ""
+    connection: ConnectionInfo | None = None
+
+    def __post_init__(self) -> None:
+        # Normalize and validate immutable identity fields once.
+        normalized_name = self.name.strip()
+        _selector_name(normalized_name)
+        object.__setattr__(self, "name", normalized_name)
+        for field_name in ("session_id", "unique_id", "xuid"):
+            value = getattr(self, field_name)
+            if not isinstance(value, str):
+                raise TypeError(f"{field_name} must be a string")
+            if any(character in value for character in "\x00\r\n"):
+                raise ValueError(f"{field_name} may not contain NUL or line breaks")
+            if len(value) > 512:
+                raise ValueError(f"{field_name} exceeds 512 characters")
+
+    @property
+    def display_name(self) -> str:
+        return self.name
+
+    @property
+    def selector(self) -> str:
+        """Escaped one-player selector used by command-backed methods."""
+        return _selector_name(self.name)
+
+    @property
+    def address(self) -> SocketAddress | None:
+        return self.connection.address if self.connection else None
+
+    @property
+    def ping_ms(self) -> int | None:
+        return self.connection.ping_ms if self.connection else None
+
+    @property
+    def device_id(self) -> str:
+        return self.connection.device_id if self.connection else ""
+
+    @property
+    def device_model(self) -> str:
+        return self.connection.device_model if self.connection else ""
+
+    @property
+    def input_mode(self) -> str:
+        return self.connection.input_mode if self.connection else ""
+
+    @property
+    def device_os(self) -> str:
+        return self.connection.device_os if self.connection else ""
+
+    @property
+    def game_version(self) -> str:
+        return self.connection.game_version if self.connection else ""
+
+    @property
+    def locale(self) -> str:
+        return self.connection.locale if self.connection else ""
+
+    def send_message(self, message: str) -> bool:
+        """Queue a private tellraw message for this player."""
+        payload = json.dumps(
+            {"rawtext": [{"text": _format_message(message)}]},
+            ensure_ascii=True,
+            separators=(",", ":"),
+        )
+        return self.server.dispatch_command(f"tellraw {self.selector} {payload}")
+
+    def run_command(self, command: str) -> bool:
+        """Queue a command with this player as the execution origin entity."""
+        return self.server.dispatch_command(
+            f"execute as {self.selector} at @s run {_command_line(command)}"
+        )
+
+    def kick(self, reason: str = "Kicked by a BedrockPlus plugin") -> bool:
+        """Queue a vanilla kick command for this player."""
+        return self.server.dispatch_command(
+            f"kick {self.selector} {_format_message(reason)}"
+        )

bedrockplus/py.typed

@@ -0,0 +1 @@
+

bedrockplus-0.1.0.dev1.dist-info/METADATA

@@ -0,0 +1,41 @@
+Metadata-Version: 2.3
+Name: bedrockplus
+Version: 0.1.0.dev1
+Summary: BedrockPlus server command and typed Python plugin API
+Author: Turkmen
+Requires-Python: >=3.13,<3.14
+Description-Content-Type: text/markdown
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Environment :: Console
+Classifier: Operating System :: Microsoft :: Windows :: Windows 10
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+License-File: THIRD_PARTY_NOTICES.md
+License-File: microsoft-detours-MIT.txt
+
+# BedrockPlus
+
+BedrockPlus is a Windows x64 Bedrock Dedicated Server and plugin platform
+created by Turkmen. This pre-release package installs the global `bedrockplus`
+command and the typed Python plugin API used by Visual Studio Code and other
+Python language servers.
+
+```text
+pip install bedrockplus
+bedrockplus
+```
+
+The first server initialization downloads the selected supported BDS archive
+from the official source, verifies its SHA-256, and keeps it in the server's
+`Downloads` directory. BedrockPlus itself does not redistribute BDS.
+
+Plugin development commands are grouped below `bedrockplus plugin`:
+
+```text
+bedrockplus plugin python init "My Plugin"
+bedrockplus plugin pack
+```
+
+This package requires 64-bit Python 3.13 and currently supports Windows x64.
+It includes public launcher code, API types, clean release binaries, required
+notices, and no private BedrockPlus source code or debug files.

bedrockplus-0.1.0.dev1.dist-info/RECORD

@@ -0,0 +1,36 @@
+bedrockplus-0.1.0.dev1.dist-info/METADATA,sha256=T7cPsYYFAd9EJWKAY9YrAvruvzJTftKqU-O67c6IqMc,1429
+bedrockplus-0.1.0.dev1.dist-info/WHEEL,sha256=wiwg5m8WpyUtzKVa7RZ10snpJ3BzERMjpss-HwWwkpY,109
+bedrockplus-0.1.0.dev1.dist-info/entry_points.txt,sha256=Eir8NvyMKKBDLKYcHXmk7A_9E3EzdcU1-RWq8N5Pnlw,53
+bedrockplus-0.1.0.dev1.dist-info/licenses/THIRD_PARTY_NOTICES.md,sha256=MMxnOYvV7fYCVtVMrZarrHnDXY-x27768RSMbNIpf38,966
+bedrockplus-0.1.0.dev1.dist-info/licenses/microsoft-detours-MIT.txt,sha256=FuPJzbT6FKhie8S17wI3dzp5w60dASwojzfilXPhFsw,1095
+bedrockplus-0.1.0.dev1.dist-info/top_level.txt,sha256=HumA7phI-GEslUzJO2TiNLPq1w8P1SopWrCXeWo2AhQ,12
+bedrockplus/__init__.py,sha256=Ju1K7GiqKYS6Xwok9TjaR55VTtqU_1jgskF_wOxuzGs,1895
+bedrockplus/__main__.py,sha256=D31U8_ux95qF64EQ8ReT25nabzxh7ped5avpobXz_bM,49
+bedrockplus/_assets/Initialize-BedrockPlusServer.ps1,sha256=IbJuQOgBWKKZFUNVl8HlzVB_-lBSA6SPJ_VIIS4s9Hc,16938
+bedrockplus/_assets/README.md,sha256=M3pQZTExXfGWDNQiv1umJC5tVjSdUsbQPXdk9_WEh64,3353
+bedrockplus/_assets/SHA256SUMS,sha256=2lsdwaXQEgDDr0C8t8cWXlPqVxLn0yHsXIdc50TEJCQ,1839
+bedrockplus/_assets/Start-BedrockPlus.ps1,sha256=MNcQ96egCL-V0FHVlRT3sV5zfyfKFamgU_CLf81vIJE,4918
+bedrockplus/_assets/THIRD_PARTY_NOTICES.md,sha256=MMxnOYvV7fYCVtVMrZarrHnDXY-x27768RSMbNIpf38,966
+bedrockplus/_assets/bedrockplus.exe,sha256=93ziv6Nx51qPNCnERo6ina5jTopXqCDGld9XnsvLFtg,619520
+bedrockplus/_assets/bedrockplus_bootstrap.dll,sha256=ZslxFuMtGqkD7_jqhHlNUvh-nynrnlTC2VJsUzF0oxQ,139264
+bedrockplus/_assets/bedrockplus_plugin_host.dll,sha256=VKfNWPTsSt4IjB1EHjBNFtbqn60K54RLEtIO-yGRZMc,198656
+bedrockplus/_assets/bedrockplus_plugin_worker.dll,sha256=hb-UQPe4MTSNaUFew0p0QwMQTnpsIB9YLja4PK-huPg,1275392
+bedrockplus/_assets/bedrockplus_runtime.dll,sha256=VN7BIJHoGJy-HEsqIpcy3-czqfeQPzZZ9zya-LDcnWM,141824
+bedrockplus/_assets/bin/bedrockplus.ps1,sha256=Um9dWDpSvQQBRTZS4Y6XJnTjblmvUElYZIpi01YBErg,7585
+bedrockplus/_assets/compatibility/bds/1.26.51.1/windows-x64.json,sha256=zSEW0UaeZpIZJ4xoKqBK4TMWIpx_gcQEuHs5cob5auE,671
+bedrockplus/_assets/compatibility/bds/supported-versions.json,sha256=pN4y1rikFDbfP46ApRD3ghnGTcRf2-DgvXEi4Okn0nQ,446
+bedrockplus/_assets/licenses/microsoft-detours-MIT.txt,sha256=FuPJzbT6FKhie8S17wI3dzp5w60dASwojzfilXPhFsw,1095
+bedrockplus/_assets/plugins/README.txt,sha256=m01CoSeU5sDfc3hczS5fl8eEw8QZ-a0tUDzl81BgZLY,564
+bedrockplus/_assets/release-manifest.json,sha256=tMCPXP5YwR8AebIbMTKeOuz7VC08UysxglzeXXRsh-E,3599
+bedrockplus/_assets/server/README.txt,sha256=N_BopYLhmNo2Mtv3igfP0icUcr7dxPnc5sO4GEEKdus,538
+bedrockplus/_assets/tools/bppack.py,sha256=6LiT1WhgKuCYFKCBVuWbrQYLfXl7WfeWbu5qIp6l848,82264
+bedrockplus/_assets/tools/init_python_plugin.py,sha256=nw7uRe-Nc8LS7eACsiRYkicPydcLg1m_K-3uE2q_P2M,4293
+bedrockplus/_assets/tools/pack_plugin.py,sha256=20_fgpIeOXY_agJL350n-g7qku3zz2lGN3yDJjW4cSs,5193
+bedrockplus/_assets/tools/world_packs.py,sha256=wFCAAMtUXtFzUDJglynuuZ6mSomsTcL8c4CovDScnPs,27312
+bedrockplus/api.py,sha256=og8Ge3JgwEWbR40KjPdls37h26G6hOrr-Z3c16H2Og0,2146
+bedrockplus/cli.py,sha256=cbdvlxooc3qgdmvRF7u2NW--kw7c4HnRAgwoIiDtCOU,4376
+bedrockplus/commands.py,sha256=EXW6AXtRZBmqZ6rTV4sklJZJAJsKi7Cuo2Bb5eBsiUI,1240
+bedrockplus/events.py,sha256=pRRedMNAAJSwlKohYQ71W85SuQlmrJTYGL8ObLgsZUw,2807
+bedrockplus/objects.py,sha256=EpK41OhgBW0Bd4rn34M3ePcvFg1nMQ0FQgQpDUKJvo8,14246
+bedrockplus/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+bedrockplus-0.1.0.dev1.dist-info/RECORD,,

bedrockplus-0.1.0.dev1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: BedrockPlus publication builder
+Root-Is-Purelib: false
+Tag: py3-none-win_amd64

bedrockplus-0.1.0.dev1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+bedrockplus = bedrockplus.cli:main

bedrockplus-0.1.0.dev1.dist-info/licenses/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,26 @@
+# Third-party notices
+
+## Microsoft Detours
+
+- Version: 4.0.1, commit `e4bfd6b03e50de46b47abfbd1e46b384f0c5f833`
+- Upstream: https://github.com/microsoft/Detours
+- License: MIT
+- Use: statically linked into `bedrockplus_plugin_worker.dll`
+
+The complete required MIT license text is distributed in
+`licenses/microsoft-detours-MIT.txt`.
+
+## CPython
+
+- Supported runtime: CPython 3.13 x64
+- Upstream: https://www.python.org/ and https://github.com/python/cpython
+- License: Python Software Foundation License Version 2 with CPython's
+  additional historical notices
+- Use: supplied by the operator's Python installation and loaded by the
+  BedrockPlus Python plugin host
+
+BedrockPlus does not bundle CPython in this release. If that policy changes,
+the exact CPython license and component notices must be added to the release.
+
+This file does not replace a complete license text when redistribution terms
+require that text to accompany a source or binary distribution.

bedrockplus-0.1.0.dev1.dist-info/licenses/microsoft-detours-MIT.txt

@@ -0,0 +1,23 @@
+Copyright (c) Microsoft Corporation
+
+All rights reserved.
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED *AS IS*, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bedrockplus-0.1.0.dev1.dist-info/top_level.txt

@@ -0,0 +1 @@
+bedrockplus