mcio-ctrl 1.4.0__tar.gz

mcio_ctrl-1.4.0/PKG-INFO

@@ -0,0 +1,57 @@
+Metadata-Version: 2.4
+Name: mcio-ctrl
+Version: 1.4.0
+Summary: Python interface to connect to the MCio Minecraft mod
+Author: TwoTurtles
+Author-email: TwoTurtles <97465192+twoturtles@users.noreply.github.com>
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Dist: pyzmq>=26.2.0
+Requires-Dist: cbor2>=5.6.5
+Requires-Dist: glfw>=2.7.0
+Requires-Dist: pyopengl>=3.1.7
+Requires-Dist: gymnasium>=1.0.0
+Requires-Dist: pillow>=11.0.0
+Requires-Dist: imageio>=2.37.0
+Requires-Dist: imageio-ffmpeg>=0.6.0
+Requires-Dist: minecraft-launcher-lib>=7.1
+Requires-Dist: tqdm>=4.67.1
+Requires-Dist: requests>=2.32.3
+Requires-Dist: ruamel-yaml>=0.18.6
+Requires-Dist: dacite>=1.8.1
+Requires-Dist: nbt>=1.5.1
+Requires-Python: >=3.12
+Project-URL: Changelog, https://github.com/twoturtles/mcio_ctrl/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/twoturtles/mcio_ctrl/issues
+Project-URL: Source, https://github.com/twoturtles/mcio_ctrl
+Description-Content-Type: text/markdown
+
+# mcio_ctrl
+
+### [MCio mod](https://github.com/twoturtles/MCio) | [mcio_ctrl](https://github.com/twoturtles/mcio_ctrl) | [Documentation](https://github.com/twoturtles/mcio_ctrl/wiki) | [Discord](https://discord.gg/PBfdc27h4q)
+
+`mcio_ctrl` is a comprehensive Python library designed to interface seamlessly with [MCio](https://github.com/twoturtles/MCio), a Minecraft Fabric mod tailored for AI agent development. It includes a versatile [Gymnasium](https://gymnasium.farama.org/) environment, making it ideal for reinforcement learning research and development.
+
+## Key Features
+
+* **Simplified Installation and Launching:** API and commands to easily install Minecraft with the MCio mod, create custom worlds, and launch the game directly from Python.
+* **Pre-built Gymnasium Environments:** Offers example environments, including compatibility with MineRL 1.0 actions and observations, all leveraging the robust low-level API.
+* **Customizable Base Environment:** A convenient base class for quickly creating tailored Gymnasium environments suited to specific research needs.
+* **Interactive GUI Support:** Enables human control of Minecraft through the standard Minecraft controls using the MCio backend. (Seamless Human-in-the-loop is planned for future updates.)
+* **Type-Hinting and Development Convenience:** Fully type-hinted for easier integration, improved code clarity, and streamlined development workflows.
+* **BONUS:** Easily [set up VPT and STEVE-1](https://github.com/jxiong21029/mcio-vpt-example) on modern Minecraft with support for [Sodium](https://modrinth.com/mod/sodium)!
+
+
+## Quick Links
+
+* **Documentation:** Find comprehensive documentation and tutorials on our [Wiki](https://github.com/twoturtles/mcio_ctrl/wiki).
+
+* **MCio Mod:**
+  * [GitHub Repository](https://github.com/twoturtles/MCio)
+  * [Modrinth Project Page](https://modrinth.com/mod/mcio)
+
+* **Python Interface (`mcio_ctrl`):**
+  * [GitHub Repository](https://github.com/twoturtles/mcio_ctrl)
+  * [PyPI Package](https://pypi.org/project/mcio_ctrl/)

mcio_ctrl-1.4.0/README.md

@@ -0,0 +1,27 @@
+# mcio_ctrl
+
+### [MCio mod](https://github.com/twoturtles/MCio) | [mcio_ctrl](https://github.com/twoturtles/mcio_ctrl) | [Documentation](https://github.com/twoturtles/mcio_ctrl/wiki) | [Discord](https://discord.gg/PBfdc27h4q)
+
+`mcio_ctrl` is a comprehensive Python library designed to interface seamlessly with [MCio](https://github.com/twoturtles/MCio), a Minecraft Fabric mod tailored for AI agent development. It includes a versatile [Gymnasium](https://gymnasium.farama.org/) environment, making it ideal for reinforcement learning research and development.
+
+## Key Features
+
+* **Simplified Installation and Launching:** API and commands to easily install Minecraft with the MCio mod, create custom worlds, and launch the game directly from Python.
+* **Pre-built Gymnasium Environments:** Offers example environments, including compatibility with MineRL 1.0 actions and observations, all leveraging the robust low-level API.
+* **Customizable Base Environment:** A convenient base class for quickly creating tailored Gymnasium environments suited to specific research needs.
+* **Interactive GUI Support:** Enables human control of Minecraft through the standard Minecraft controls using the MCio backend. (Seamless Human-in-the-loop is planned for future updates.)
+* **Type-Hinting and Development Convenience:** Fully type-hinted for easier integration, improved code clarity, and streamlined development workflows.
+* **BONUS:** Easily [set up VPT and STEVE-1](https://github.com/jxiong21029/mcio-vpt-example) on modern Minecraft with support for [Sodium](https://modrinth.com/mod/sodium)!
+
+
+## Quick Links
+
+* **Documentation:** Find comprehensive documentation and tutorials on our [Wiki](https://github.com/twoturtles/mcio_ctrl/wiki).
+
+* **MCio Mod:**
+  * [GitHub Repository](https://github.com/twoturtles/MCio)
+  * [Modrinth Project Page](https://modrinth.com/mod/mcio)
+
+* **Python Interface (`mcio_ctrl`):**
+  * [GitHub Repository](https://github.com/twoturtles/mcio_ctrl)
+  * [PyPI Package](https://pypi.org/project/mcio_ctrl/)

mcio_ctrl-1.4.0/pyproject.toml

@@ -0,0 +1,59 @@
+[project]
+name = "mcio_ctrl"
+version = "1.4.0"
+description = "Python interface to connect to the MCio Minecraft mod"
+readme = "README.md"
+authors = [
+    { name = "TwoTurtles", email = "97465192+twoturtles@users.noreply.github.com" },
+]
+license = "MIT"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+requires-python = ">=3.12"
+dependencies = [
+    "pyzmq>=26.2.0",
+    "cbor2>=5.6.5",
+    "glfw>=2.7.0",
+    "PyOpenGL>=3.1.7",
+    "gymnasium>=1.0.0",
+    "pillow>=11.0.0",
+    "imageio>=2.37.0",
+    "imageio-ffmpeg>=0.6.0",
+    "minecraft-launcher-lib>=7.1",
+    "tqdm>=4.67.1",
+    "requests>=2.32.3",
+    "ruamel.yaml>=0.18.6",
+    "dacite>=1.8.1",
+    "NBT>=1.5.1",
+]
+
+[build-system]
+requires = ["uv_build>=0.7.12,<0.8"]
+build-backend = "uv_build"
+
+[project.urls]
+Source = "https://github.com/twoturtles/mcio_ctrl"
+Issues = "https://github.com/twoturtles/mcio_ctrl/issues"
+Changelog = "https://github.com/twoturtles/mcio_ctrl/blob/main/CHANGELOG.md"
+
+[project.scripts]
+mcio = "mcio_ctrl.scripts.mcio_cmd:main"
+
+[dependency-groups]
+dev = [
+    "pre-commit>=4.0.1",
+    "mypy>=1.13.0",
+    "ruff>=0.8.1",
+    "black>=24.10.0",
+    "pip",
+    "pytest>=8.3.4",
+    "pytest-mock>=3.14.0",
+    "pytest-cov>=6.0.0",
+    "isort>=5.13.2",
+]
+
+[tool.isort]
+profile = "black"

mcio_ctrl-1.4.0/src/mcio_ctrl/__about__.py

@@ -0,0 +1 @@
+__version__ = "1.3.1.dev0"

mcio_ctrl-1.4.0/src/mcio_ctrl/__init__.py

@@ -0,0 +1,32 @@
+from . import (
+    config,
+    controller,
+    envs,
+    gui,
+    instance,
+    mc_mock,
+    mcio_gui,
+    network,
+    server,
+    types,
+    util,
+    world,
+)
+
+__version__ = "1.4.0"
+
+__all__ = [
+    "__version__",
+    "config",
+    "controller",
+    "envs",
+    "gui",
+    "instance",
+    "mc_mock",
+    "mcio_gui",
+    "network",
+    "server",
+    "types",
+    "util",
+    "world",
+]

mcio_ctrl-1.4.0/src/mcio_ctrl/cbor.py

@@ -0,0 +1,78 @@
+"""CBOR processing helpers"""
+
+import logging
+from dataclasses import fields, is_dataclass
+from typing import Any, Final, TypeVar
+
+import cbor2
+
+LOG = logging.getLogger(__name__)
+
+# Used by MCio and mcio_ctrl to annotate protocol classes
+MCIO_PROTOCOL_TYPE: Final[str] = "__mcio_type__"
+
+# Maps protcol class names to the type and vice versa
+_MCIO_NAME_TO_TYPE: dict[str, type] = {}
+_MCIO_TYPE_TO_NAME: dict[type, str] = {}
+
+
+T = TypeVar("T")
+
+
+def MCioType(cls: type[T]) -> type[T]:
+    """Decorator to register a class as used in the MCio protocol"""
+    # Use the Java Jackson style MINIMAL_CLASS name which includes a leading dot.
+    name = "." + cls.__name__
+    _MCIO_NAME_TO_TYPE[name] = cls
+    _MCIO_TYPE_TO_NAME[cls] = name
+    return cls
+
+
+def encode(obj: Any) -> bytes:
+    """Encode object to CBOR using MCioType class annotations"""
+    return cbor2.dumps(typed_asdict(obj))
+
+
+def decode(data: bytes) -> Any | None:
+    """Decode CBOR using MCioType classes where possible. Returns None on error"""
+    try:
+        return cbor2.loads(data, object_hook=_object_hook)
+    except Exception as e:
+        LOG.error(f"CBOR load error: {type(e).__name__}: {e}")
+        return None
+
+
+def _object_hook(decoder: cbor2.CBORDecoder, obj_dict: dict[Any, Any]) -> Any:
+    """Used by the CBOR parser. Decodes packet entries into MCioType classes where possible."""
+    mcio_type = obj_dict.pop(MCIO_PROTOCOL_TYPE, None)
+    if isinstance(mcio_type, str):
+        cls = _MCIO_NAME_TO_TYPE.get(mcio_type)
+        if cls:
+            return cls(**obj_dict)
+        else:
+            LOG.error(f"Unknown MCioType type: {mcio_type}")
+
+    # Non MCioType
+    return obj_dict
+
+
+def typed_asdict(obj: Any) -> Any:
+    """Like dataclass asdict, but annotates MCioType classes with type info.
+    Recursively walks the dataclass.
+    """
+    if is_dataclass(obj):
+        cls = type(obj)
+        cls_name = _MCIO_TYPE_TO_NAME.get(cls)
+        result = {
+            key: typed_asdict(getattr(obj, key))
+            for key in (f.name for f in fields(obj))
+        }
+        if cls_name:
+            result[MCIO_PROTOCOL_TYPE] = cls_name
+        return result
+    elif isinstance(obj, (list, tuple)):
+        return [typed_asdict(i) for i in obj]
+    elif isinstance(obj, dict):
+        return {k: typed_asdict(v) for k, v in obj.items()}
+    else:
+        return obj

mcio_ctrl-1.4.0/src/mcio_ctrl/config.py

@@ -0,0 +1,118 @@
+"""Persistent config - mcio.yaml"""
+
+import logging
+import types
+from dataclasses import asdict, dataclass, field
+from io import StringIO
+from pathlib import Path
+from typing import Any, Final, Optional, TypeAlias
+
+import dacite
+from ruamel.yaml import YAML
+
+LOG = logging.getLogger(__name__)
+
+##
+# Global defines
+
+DEFAULT_MCIO_DIR: Final[Path] = Path("~/.mcio/").expanduser()
+DEFAULT_MINECRAFT_VERSION: Final[str] = "1.21.3"
+
+
+##
+# Configuration
+
+# XXX Consider saving necessary config in each entity's directory
+
+CONFIG_FILENAME: Final[str] = "mcio.yaml"
+CONFIG_VERSION: Final[int] = 1
+InstanceName: TypeAlias = str
+WorldName: TypeAlias = str
+MinecraftVersion: TypeAlias = str
+
+
+@dataclass
+class WorldConfig:
+    name: WorldName = ""
+    minecraft_version: MinecraftVersion = ""  # Save the version that created this world
+    seed: str = ""
+
+
+@dataclass
+class InstanceConfig:
+    name: InstanceName = ""
+    launch_version: MinecraftVersion = ""
+    minecraft_version: MinecraftVersion = ""
+    worlds: dict[WorldName, WorldConfig] = field(default_factory=dict)
+
+
+@dataclass
+class ServerConfig:
+    minecraft_version: MinecraftVersion = ""
+    jvm_version: str = ""
+
+
+@dataclass
+class Config:
+    config_version: int = CONFIG_VERSION  # XXX Eventually check this
+    instances: dict[InstanceName, InstanceConfig] = field(default_factory=dict)
+    world_storage: dict[WorldName, WorldConfig] = field(default_factory=dict)
+    servers: dict[MinecraftVersion, ServerConfig] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, config_dict: dict[str, Any]) -> Optional["Config"]:
+        try:
+            rv = dacite.from_dict(data_class=cls, data=config_dict)
+        except Exception as e:
+            # This means the dict doesn't match Config
+            LOG.error(f"Failed to parse config file: {e}")
+            return None
+        return rv
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+class ConfigManager:
+    def __init__(self, mcio_dir: Path | str, save: bool = False) -> None:
+        """Set save to true to save automatically on exiting"""
+        self.save_on_exit = save
+        mcio_dir = Path(mcio_dir).expanduser()
+        self.config_file = mcio_dir / CONFIG_FILENAME
+        self.yaml = YAML(typ="rt")
+        self.config: Config = Config()
+
+    def load(self) -> None:
+        if self.config_file.exists():
+            with open(self.config_file) as f:
+                # load() returns None if the file has no data.
+                cfg_dict = self.yaml.load(f) or {}
+                self.config = Config.from_dict(cfg_dict) or Config()
+        else:
+            self.config = Config()
+
+    def pformat(self) -> str:
+        """Pretty print the config"""
+        string_stream = StringIO()
+        self.yaml.dump(self.config.to_dict(), string_stream)
+        return string_stream.getvalue()
+
+    def save(self) -> None:
+        with open(self.config_file, "w") as f:
+            self.yaml.dump(self.config.to_dict(), f)
+
+    def __enter__(self) -> "ConfigManager":
+        self.load()
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: types.TracebackType | None,
+    ) -> bool | None:
+        if exc_type is None:
+            # Clean exit
+            if self.save_on_exit:
+                self.save()
+        return None

mcio_ctrl-1.4.0/src/mcio_ctrl/controller.py

@@ -0,0 +1,193 @@
+import logging
+import threading
+from typing import Protocol
+
+from . import network, types, util
+
+LOG = logging.getLogger(__name__)
+
+
+class ControllerCommon(Protocol):
+    """Protocol for the fundamental controller interface shared by sync/async implementations"""
+
+    _action_sequence_last_sent: int
+    _mcio_conn: network._Connection
+
+    def send_action(self, action: network.ActionPacket) -> None:
+        """Send action to minecraft. Automatically sets action.sequence."""
+        self._action_sequence_last_sent += 1
+        action.sequence = self._action_sequence_last_sent
+        self._mcio_conn.send_action(action)
+
+    def send_stop(self) -> None:
+        """Send a stop packet to Minecraft. This should cause Minecraft to cleanly exit."""
+        self._mcio_conn.send_stop()
+
+    def recv_observation(self) -> network.ObservationPacket: ...
+    def close(self) -> None: ...
+
+
+class ControllerSync(ControllerCommon):
+    """
+    Handles SYNC mode connections to Minecraft.
+    Blocks in recv waiting for a new observation.
+    """
+
+    def __init__(
+        self,
+        *,
+        action_port: int | None = None,
+        observation_port: int | None = None,
+        wait_for_connection: bool = True,
+        connection_timeout: float | None = None,
+    ):
+        self._action_sequence_last_sent = 0
+        self._mcio_conn = network._Connection(
+            action_port=action_port,
+            observation_port=observation_port,
+            wait_for_connection=wait_for_connection,
+            connection_timeout=connection_timeout,
+        )
+        self.check_mode = True
+
+    def recv_observation(
+        self, block: bool = True, timeout: float | None = None
+    ) -> network.ObservationPacket:
+        """Receive observation. Always blocks - ignores block and timeout args"""
+        obs = self._mcio_conn.recv_observation(block=True)
+        if obs is None:
+            # Exiting or packet decode error
+            return network.ObservationPacket()
+
+        if self.check_mode:
+            self.check_mode = False
+            mode = types.MCioMode.SYNC
+            if mode != obs.mode:
+                LOG.warning(f"Mode-Mismatch controller={mode} mcio={obs.mode}")
+
+        return obs
+
+    def close(self) -> None:
+        """Shut down the network connection"""
+        self._mcio_conn.close()
+
+
+class ControllerAsync(ControllerCommon):
+    """
+    Handles ASYNC mode connections to Minecraft
+    """
+
+    def __init__(
+        self,
+        *,
+        action_port: int | None = None,
+        observation_port: int | None = None,
+        wait_for_connection: bool = True,
+        connection_timeout: float | None = None,
+    ):
+        self._action_sequence_last_sent = 0
+
+        self.process_counter = util.TrackPerSecond("ProcessObservationPPS")
+        self.queued_counter = util.TrackPerSecond("QueuedActionsPPS")
+        self.check_mode = True
+
+        # Flag to signal observation thread to stop.
+        self._running = threading.Event()
+        self._running.set()
+
+        self._observation_queue = util.LatestItemQueue[network.ObservationPacket]()
+        self._mcio_conn = network._Connection(
+            action_port=action_port,
+            observation_port=observation_port,
+            wait_for_connection=wait_for_connection,
+            connection_timeout=connection_timeout,
+        )
+
+        # Start observation thread
+        self._observation_thread = threading.Thread(
+            target=self._observation_thread_fn, name="ObservationThread"
+        )
+        self._observation_thread.daemon = True
+        self._observation_thread.start()
+
+        LOG.info("Controller init complete")
+
+    def recv_observation(
+        self, block: bool = True, timeout: float | None = None
+    ) -> network.ObservationPacket:
+        """
+        Returns the most recently received observation pulling it from the processing queue.
+        Block and timeout are like queue.Queue.get().
+        Can raise Empty exception if non-blocking or timeout is used.
+        """
+        # RECV 2
+        observation = self._observation_queue.get(block=block, timeout=timeout)
+        return observation
+
+    def send_and_recv_match(
+        self, action: network.ActionPacket, max_skip: int | None = 5
+    ) -> network.ObservationPacket:
+        """Send action to minecraft. Automatically sets action.sequence.
+        This will ensure the next observation you receive came after this action.
+        Since we're running in async mode, observations may be in flight that occurred
+        before Minecraft processed this action.
+        max_skip is the maximum number of observations to skip before giving up.
+        Because the observations are stored in a LatestItemQueue, there shouldn't be
+        many to skip - only observations that were in flight after the action was sent, but
+        before Minecraft processed it. Generally we should only hit max_skip if something went
+        wrong, like the action was dropped. This could happen, for example, when the agent
+        starts before Minecraft.
+        """
+        self.send_action(action)
+        wait_seq = self._action_sequence_last_sent
+        n_skip = 0
+        while True:
+            observation = self._observation_queue.get()
+            obs_action_seq = observation.last_action_sequence
+            if obs_action_seq >= wait_seq:
+                break
+            n_skip += 1
+            if max_skip is not None and n_skip >= max_skip:
+                LOG.warning("Max-Skip")
+                break
+            LOG.debug(
+                f"SKIPPING obs={observation.sequence} last_action={obs_action_seq} < waiting={wait_seq}"
+            )
+            # print(f"SKIPPING obs={observation.sequence} last_action={obs_action_seq} < waiting={wait_seq}")
+        return observation
+
+    def _observation_thread_fn(self) -> None:
+        """Loops. Receives observation packets from minecraft and places on observation_queue"""
+        LOG.info("ObservationThread start")
+        while self._running.is_set():
+            # RECV 1
+            # I don't think we'll ever drop here. this is a short loop to recv the packet
+            # and put it on the queue to be processed.
+            observation = self._mcio_conn.recv_observation(block=True)
+            if observation is None:
+                continue  # Exiting or packet decode error
+
+            if self.check_mode:
+                self.check_mode = False
+                mode = types.MCioMode.ASYNC
+                if mode != observation.mode:
+                    LOG.warning(
+                        f"Mode-Mismatch controller={mode} mcio={observation.mode}"
+                    )
+
+            dropped = self._observation_queue.put(observation)
+            if dropped:
+                # This means the main (processing) thread isn't reading fast enough.
+                # The first few are always dropped, presumably as we empty the initial zmq buffer
+                # that built up during pause for "slow joiner syndrome".
+                # XXX This should not longer happen since we're using push/pull? Change log level?
+                LOG.debug("Dropped observation packet from processing queue")
+                pass
+
+        LOG.info("ObservationThread shut down")
+
+    def close(self) -> None:
+        """Shut down the network connection"""
+        self._running.clear()
+        self._mcio_conn.close()
+        self._observation_thread.join()

mcio_ctrl-1.4.0/src/mcio_ctrl/envs/__init__.py

@@ -0,0 +1,19 @@
+from gymnasium.envs.registration import register
+
+from . import base_env, mcio_env, minerl_env
+
+__all__ = [
+    "base_env",
+    "mcio_env",
+    "minerl_env",
+]
+
+register(
+    id="MCio/MCioEnv-v0",
+    entry_point="mcio_ctrl.envs.mcio_env:MCioEnv",
+)
+
+register(
+    id="MCio/MinerlEnv-v0",
+    entry_point="mcio_ctrl.envs.minerl_env:MinerlEnv",
+)