pyTrialmc 2026.10.7__tar.gz

pytrialmc-2026.10.7/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: pyTrialmc
+Version: 2026.10.7
+Summary: Write Minecraft Java Edition mods in Python
+Keywords: minecraft,mod,modloader,python
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Games/Entertainment
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# pyTrialmc
+
+Write Minecraft Java Edition mods in **Python**.
+
+`pyTrialmc` is the Python library of the pyTrial loader. Your mod imports it, and
+it ships the command line tool that creates, declares and packages mod projects.
+
+| | |
+| --- | --- |
+| Release | 26 October 07 |
+| Version | 2026.10.7 |
+| Requires | Python 3.9 or newer |
+
+## Install
+
+```bash
+pip install pyTrialmc
+```
+
+## Create a project
+
+```bash
+cd my_mod
+pytrialmc -init
+```
+
+`-init` writes the project skeleton in the current directory:
+
+```
+pytrial.mod.json     mod metadata read by the loader
+main.py              the mod entry file
+src/                 one file per element
+└── example_block.py
+```
+
+`main.py` is the entry file the loader executes:
+
+```python
+from pyTrialmc import *
+
+mod = modsrc()
+
+# Declare one element per line, every element is implemented by src/<name>.py.
+# Any kind from ELEMENT_KINDS is available as mod.add.<kind>(name, **options).
+# mod.add.block("example_block")
+# mod.add.item("example_ingot", stack_size=64)
+
+mod.main()
+modmain()
+```
+
+## Declare elements
+
+`mod.add` carries one method per element kind, named after the kind. The first
+argument is the element name, and it also names the implementation file in `src/`.
+
+```python
+mod.add.block("ruby_block", hardness=4.0)
+mod.add.item("ruby_ingot", stack_size=64)
+mod.add.creative_tab("ruby_tab", title="Ruby", icon="ruby_mod:ruby_ingot")
+mod.add.command("ruby", description="Ruby command", aliases=["rb"])
+```
+
+The catalog covers 37 kinds:
+
+| | Kinds |
+| --- | --- |
+| | advancement, armor, armor_trim, attribute, banner_pattern, biome, block, command, creative_tab, custom_element, damage_type, dimension, enchantment, feature, fluid, function, gui, game_rule |
+| | item, item_extension, key_binding, living_entity, loot_table, overlay, painting, particle, plant, potion_effect, potion_item, procedure, projectile, recipe, special_entity, structure, tool, villager_profession, villager_trade |
+
+`block`, `item`, `creative_tab` and `command` are active: the loader bridges them
+into the game today. Every other kind is declared and reported by the loader as
+not supported yet, so declaring one never fails; the Python side stays unchanged
+when its bridge lands.
+
+### Element files
+
+One element per file, file name equal to the declared name, so
+`mod.add.block("ruby_block")` is implemented by `src/ruby_block.py`:
+
+```python
+OPTIONS = {"hardness": 2.5, "light": 4}
+
+
+def configure(element):
+    element.options["resistance"] = 9.0
+```
+
+Option priority: arguments passed to `mod.add.*` > `configure()` > `OPTIONS`.
+
+## Lifecycle hooks
+
+The loader may also call these, if your entry file defines them:
+
+```python
+def on_declare(ctx): ...            # registration phase
+def on_load(ctx): ...               # everything is registered
+def on_event(event_id, payload): ...# game or loader events
+def on_hook(hook_id, args): ...     # bytecode hook callbacks
+def on_unload(): ...                # the mod is going away
+```
+
+`ctx` carries `mod_id`, `version`, `minecraft_version`, `root`, `config_dir`
+and `cache_dir`.
+
+## Package the mod
+
+```bash
+pytrialmc -b:1.21.8
+```
+
+That writes `dist/<modId>-<modVersion>.pytm`. Copy the package into
+`<gameDir>/pytrial/mods/`.
+
+## Command line
+
+```
+pytrialmc -init                 create a mod project here (main.py + src/)
+pytrialmc -b:<game version>     build a loadable jar
+pytrialmc -debug                print debug output
+```
+
+Environment: `PYTRIALMC_DEBUG=1`, `PYTRIALMC_COLOR=1`, `NO_COLOR=1`.
+
+## The loader
+
+The Python library only declares content. The loader and the launcher are the
+Java side of pyTrial: an independent loader that starts Minecraft itself through a
+Java agent, without Forge or Fabric, then runs each mod in a Python process and
+registers the declared content into the game.
+
+```bash
+java -jar pytrial-bootstrap.jar install   # install into the game directory
+java -jar pytrial-bootstrap.jar launch    # start the game with pyTrial
+java -jar pytrial-bootstrap.jar mods      # list the discovered Python mods
+```
+
+Installing creates `<gameDir>/pytrial/` with `loader/`, `mods/`, `config/`,
+`cache/` and launch scripts. Architecture and the mod format are documented in
+`docs/`.

pytrialmc-2026.10.7/README.md

@@ -0,0 +1,140 @@
+# pyTrialmc
+
+Write Minecraft Java Edition mods in **Python**.
+
+`pyTrialmc` is the Python library of the pyTrial loader. Your mod imports it, and
+it ships the command line tool that creates, declares and packages mod projects.
+
+| | |
+| --- | --- |
+| Release | 26 October 07 |
+| Version | 2026.10.7 |
+| Requires | Python 3.9 or newer |
+
+## Install
+
+```bash
+pip install pyTrialmc
+```
+
+## Create a project
+
+```bash
+cd my_mod
+pytrialmc -init
+```
+
+`-init` writes the project skeleton in the current directory:
+
+```
+pytrial.mod.json     mod metadata read by the loader
+main.py              the mod entry file
+src/                 one file per element
+└── example_block.py
+```
+
+`main.py` is the entry file the loader executes:
+
+```python
+from pyTrialmc import *
+
+mod = modsrc()
+
+# Declare one element per line, every element is implemented by src/<name>.py.
+# Any kind from ELEMENT_KINDS is available as mod.add.<kind>(name, **options).
+# mod.add.block("example_block")
+# mod.add.item("example_ingot", stack_size=64)
+
+mod.main()
+modmain()
+```
+
+## Declare elements
+
+`mod.add` carries one method per element kind, named after the kind. The first
+argument is the element name, and it also names the implementation file in `src/`.
+
+```python
+mod.add.block("ruby_block", hardness=4.0)
+mod.add.item("ruby_ingot", stack_size=64)
+mod.add.creative_tab("ruby_tab", title="Ruby", icon="ruby_mod:ruby_ingot")
+mod.add.command("ruby", description="Ruby command", aliases=["rb"])
+```
+
+The catalog covers 37 kinds:
+
+| | Kinds |
+| --- | --- |
+| | advancement, armor, armor_trim, attribute, banner_pattern, biome, block, command, creative_tab, custom_element, damage_type, dimension, enchantment, feature, fluid, function, gui, game_rule |
+| | item, item_extension, key_binding, living_entity, loot_table, overlay, painting, particle, plant, potion_effect, potion_item, procedure, projectile, recipe, special_entity, structure, tool, villager_profession, villager_trade |
+
+`block`, `item`, `creative_tab` and `command` are active: the loader bridges them
+into the game today. Every other kind is declared and reported by the loader as
+not supported yet, so declaring one never fails; the Python side stays unchanged
+when its bridge lands.
+
+### Element files
+
+One element per file, file name equal to the declared name, so
+`mod.add.block("ruby_block")` is implemented by `src/ruby_block.py`:
+
+```python
+OPTIONS = {"hardness": 2.5, "light": 4}
+
+
+def configure(element):
+    element.options["resistance"] = 9.0
+```
+
+Option priority: arguments passed to `mod.add.*` > `configure()` > `OPTIONS`.
+
+## Lifecycle hooks
+
+The loader may also call these, if your entry file defines them:
+
+```python
+def on_declare(ctx): ...            # registration phase
+def on_load(ctx): ...               # everything is registered
+def on_event(event_id, payload): ...# game or loader events
+def on_hook(hook_id, args): ...     # bytecode hook callbacks
+def on_unload(): ...                # the mod is going away
+```
+
+`ctx` carries `mod_id`, `version`, `minecraft_version`, `root`, `config_dir`
+and `cache_dir`.
+
+## Package the mod
+
+```bash
+pytrialmc -b:1.21.8
+```
+
+That writes `dist/<modId>-<modVersion>.pytm`. Copy the package into
+`<gameDir>/pytrial/mods/`.
+
+## Command line
+
+```
+pytrialmc -init                 create a mod project here (main.py + src/)
+pytrialmc -b:<game version>     build a loadable jar
+pytrialmc -debug                print debug output
+```
+
+Environment: `PYTRIALMC_DEBUG=1`, `PYTRIALMC_COLOR=1`, `NO_COLOR=1`.
+
+## The loader
+
+The Python library only declares content. The loader and the launcher are the
+Java side of pyTrial: an independent loader that starts Minecraft itself through a
+Java agent, without Forge or Fabric, then runs each mod in a Python process and
+registers the declared content into the game.
+
+```bash
+java -jar pytrial-bootstrap.jar install   # install into the game directory
+java -jar pytrial-bootstrap.jar launch    # start the game with pyTrial
+java -jar pytrial-bootstrap.jar mods      # list the discovered Python mods
+```
+
+Installing creates `<gameDir>/pytrial/` with `loader/`, `mods/`, `config/`,
+`cache/` and launch scripts. Architecture and the mod format are documented in
+`docs/`.

pytrialmc-2026.10.7/pyTrialmc/__init__.py

@@ -0,0 +1,73 @@
+from .console import console, is_debug, set_debug
+from .elements import ACTIVE_KINDS, ELEMENT_KINDS, ELEMENT_LABELS
+from .runtime import (
+    close_gui,
+    error,
+    log,
+    off,
+    on,
+    open_gui,
+    register,
+    register_advancement,
+    register_biome,
+    register_block,
+    register_block_entity,
+    register_command,
+    register_creative_tab,
+    register_dimension,
+    register_enchantment,
+    register_entity,
+    register_feature,
+    register_gui,
+    register_item,
+    register_loot_table,
+    register_menu,
+    register_particle,
+    register_potion_effect,
+    register_recipe,
+    register_sound,
+    warn,
+)
+from .source import Element, ModSource, declared_elements, modmain, modsrc
+
+__version__ = "2026.10.7"
+
+__all__ = [
+    "console",
+    "is_debug",
+    "set_debug",
+    "log",
+    "warn",
+    "error",
+    "on",
+    "off",
+    "register",
+    "register_block",
+    "register_item",
+    "register_command",
+    "register_block_entity",
+    "register_entity",
+    "register_menu",
+    "register_creative_tab",
+    "register_sound",
+    "register_particle",
+    "register_recipe",
+    "register_advancement",
+    "register_loot_table",
+    "register_biome",
+    "register_dimension",
+    "register_feature",
+    "register_enchantment",
+    "register_potion_effect",
+    "register_gui",
+    "open_gui",
+    "close_gui",
+    "modsrc",
+    "modmain",
+    "ModSource",
+    "Element",
+    "declared_elements",
+    "ELEMENT_KINDS",
+    "ELEMENT_LABELS",
+    "ACTIVE_KINDS",
+]

pytrialmc-2026.10.7/pyTrialmc/build.py

@@ -0,0 +1,106 @@
+import io
+import json
+import zipfile
+from datetime import datetime, timezone
+from pathlib import Path
+
+from . import __version__
+from . import crypto
+from .color import GREEN, RED, paint
+from .console import console
+
+METADATA_FILE = "pytrial.mod.json"
+BUILD_INFO_FILE = "pytrial.build.json"
+OUTPUT_DIR = "dist"
+PACKAGE_SUFFIX = ".pytm"
+
+EXCLUDED_DIRS = {
+    "dist",
+    "build",
+    "__pycache__",
+    ".git",
+    ".venv",
+    ".idea",
+    ".vscode",
+    "venv",
+    "env",
+}
+EXCLUDED_SUFFIXES = {".pyc", ".pyo"}
+
+
+def collect_files(root):
+    files = []
+    skipped = []
+    for path in sorted(root.rglob("*")):
+        if not path.is_file():
+            continue
+        relative = path.relative_to(root)
+        if any(part in EXCLUDED_DIRS for part in relative.parts[:-1]):
+            skipped.append(relative.as_posix())
+            continue
+        if path.suffix in EXCLUDED_SUFFIXES:
+            skipped.append(relative.as_posix())
+            continue
+        if relative.name == BUILD_INFO_FILE:
+            skipped.append(relative.as_posix())
+            continue
+        files.append(path)
+
+    console.debug("included entries: " + str([path.relative_to(root).as_posix() for path in files]))
+    if skipped:
+        console.debug("skipped entries: " + str(skipped))
+    return files
+
+
+def build_package(root, game_version, output_dir=None):
+    game_version = (game_version or "").strip()
+    if not game_version:
+        print(paint("Missing game version, usage: pytrialmc -b:<game version>", RED))
+        return 1
+
+    metadata_path = root / METADATA_FILE
+    if not metadata_path.is_file():
+        print(paint("No " + METADATA_FILE + " in the current directory, run: pytrialmc -init", RED))
+        return 1
+
+    console.debug("build root: " + str(root))
+    console.debug("game version: " + game_version)
+
+    try:
+        metadata = json.loads(metadata_path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, UnicodeDecodeError) as error:
+        print(paint(METADATA_FILE + " is not valid JSON: " + str(error), RED))
+        return 1
+
+    mod_id = metadata.get("id") or root.name
+    mod_version = metadata.get("version") or "1.0.0"
+    console.debug("mod id: " + str(mod_id) + ", mod version: " + str(mod_version))
+
+    target_dir = Path(output_dir) if output_dir else root / OUTPUT_DIR
+    target_dir.mkdir(parents=True, exist_ok=True)
+    package_path = target_dir / (mod_id + "-" + mod_version + PACKAGE_SUFFIX)
+
+    build_info = {
+        "builder": "pyTrialmc",
+        "builderVersion": __version__,
+        "gameVersion": game_version,
+        "modId": mod_id,
+        "modVersion": mod_version,
+        "builtAt": datetime.now(timezone.utc).isoformat(),
+    }
+
+    files = collect_files(root)
+    buffer = io.BytesIO()
+    with zipfile.ZipFile(buffer, "w", zipfile.ZIP_DEFLATED) as archive:
+        archive.writestr(BUILD_INFO_FILE, json.dumps(build_info, ensure_ascii=False, indent=2) + "\n")
+        for path in files:
+            archive.write(path, path.relative_to(root).as_posix())
+    package_path.write_bytes(crypto.encrypt(buffer.getvalue()))
+
+    console.debug("package written: " + str(package_path))
+
+    print(paint("Built " + str(package_path), GREEN))
+    print("  game version: " + game_version)
+    print("  entries: " + str(len(files) + 1))
+    print("  copy it into <gameDir>/pytrial/mods/")
+    return 0

pytrialmc-2026.10.7/pyTrialmc/cli.py

@@ -0,0 +1,66 @@
+import sys
+from pathlib import Path
+
+from . import __version__
+from .build import build_package
+from .color import BOLD, CYAN, DIM, RED, paint
+from .console import console, is_debug, set_debug
+from .project import init_project
+
+DEBUG_FLAG = "-debug"
+
+
+def usage_text():
+    lines = [
+        paint("pyTrialmc " + __version__, BOLD, CYAN),
+        "",
+        paint("Usage:", BOLD),
+        "  pytrialmc -init                 " + paint("create a mod project here (main.py + src/)", DIM),
+        "  pytrialmc -b:<game version>     " + paint("build a loadable jar", DIM),
+        "  pytrialmc -debug                " + paint("print debug output", DIM),
+        "",
+        paint("Examples:", BOLD),
+        "  pytrialmc -init",
+        "  pytrialmc -b:1.21.8",
+        "  pytrialmc -b:1.21.8 -debug",
+        "",
+        paint("Environment:", BOLD),
+        "  PYTRIALMC_DEBUG=1   " + paint("same as -debug", DIM),
+        "  PYTRIALMC_COLOR=1   " + paint("force colors, 0 to disable", DIM),
+        "  NO_COLOR=1          " + paint("disable colors", DIM),
+    ]
+    return "\n".join(lines)
+
+
+def main(argv=None):
+    args = list(sys.argv[1:] if argv is None else argv)
+
+    if DEBUG_FLAG in args:
+        args.remove(DEBUG_FLAG)
+        set_debug(True)
+
+    console.debug("argv: " + repr(args))
+    console.debug("python: " + sys.version.split()[0])
+    console.debug("cwd: " + str(Path.cwd()))
+    console.debug("colors: " + str(paint("", BOLD) != ""))
+
+    if not args or args[0] in ("-h", "--help", "help"):
+        print(usage_text())
+        return 0
+
+    command = args[0]
+    console.debug("command: " + command)
+
+    if command == "-init":
+        return init_project(Path.cwd())
+
+    if command.startswith("-b:"):
+        return build_package(Path.cwd(), command[len("-b:"):])
+
+    print(paint("Unknown option: " + command, RED))
+    print(usage_text())
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

pytrialmc-2026.10.7/pyTrialmc/color.py

@@ -0,0 +1,34 @@
+import os
+import sys
+
+RESET = "\033[0m"
+BOLD = "\033[1m"
+DIM = "\033[2m"
+RED = "\033[31m"
+GREEN = "\033[32m"
+YELLOW = "\033[33m"
+BLUE = "\033[34m"
+MAGENTA = "\033[35m"
+CYAN = "\033[36m"
+GREY = "\033[90m"
+
+_DISABLED = {"0", "false", "off", "never", "no"}
+_ENABLED = {"1", "true", "on", "always", "force", "yes"}
+
+
+def enabled(stream=None):
+    if os.environ.get("NO_COLOR"):
+        return False
+    override = os.environ.get("PYTRIALMC_COLOR", "").strip().lower()
+    if override in _DISABLED:
+        return False
+    if override in _ENABLED:
+        return True
+    target = sys.stdout if stream is None else stream
+    return bool(getattr(target, "isatty", lambda: False)())
+
+
+def paint(text, *styles, stream=None):
+    if not styles or not enabled(stream):
+        return str(text)
+    return "".join(styles) + str(text) + RESET

pytrialmc-2026.10.7/pyTrialmc/console.py

@@ -0,0 +1,42 @@
+import os
+
+from . import runtime
+from .color import CYAN, GREY, paint
+
+_TRUTHY = {"1", "true", "on", "yes", "always"}
+
+_debug = os.environ.get("PYTRIALMC_DEBUG", "").strip().lower() in _TRUTHY
+
+
+def set_debug(value):
+    global _debug
+    _debug = bool(value)
+    return _debug
+
+
+def is_debug():
+    return _debug
+
+
+def _join(args):
+    return " ".join(str(arg) for arg in args)
+
+
+def _write(text, color):
+    if runtime.is_bound():
+        runtime.log(text)
+    else:
+        print(paint(text, color))
+
+
+class _Console:
+
+    def log(self, *args):
+        _write(_join(args), CYAN)
+
+    def debug(self, *args):
+        if _debug:
+            _write("[debug] " + _join(args), GREY)
+
+
+console = _Console()

pytrialmc-2026.10.7/pyTrialmc/crypto.py

@@ -0,0 +1,42 @@
+import hashlib
+import os
+
+MAGIC = b"PYTM"
+VERSION = 1
+SALT_LENGTH = 16
+CHECKSUM_LENGTH = 32
+HEADER_LENGTH = len(MAGIC) + 1 + SALT_LENGTH + CHECKSUM_LENGTH
+KEY = hashlib.sha256(b"pyTrial mod package v1").digest()
+
+
+def _keystream(salt, length):
+    stream = bytearray()
+    counter = 0
+    while len(stream) < length:
+        stream += hashlib.sha256(KEY + salt + counter.to_bytes(4, "little")).digest()
+        counter += 1
+    return bytes(stream[:length])
+
+
+def _xor(data, stream):
+    return bytes(left ^ right for left, right in zip(data, stream))
+
+
+def encrypt(data):
+    salt = os.urandom(SALT_LENGTH)
+    body = _xor(data, _keystream(salt, len(data)))
+    return MAGIC + bytes([VERSION]) + salt + hashlib.sha256(data).digest() + body
+
+
+def decrypt(data):
+    if len(data) <= HEADER_LENGTH or data[: len(MAGIC)] != MAGIC:
+        raise ValueError("not a pyTrial package")
+    if data[len(MAGIC)] != VERSION:
+        raise ValueError("unsupported package version " + str(data[len(MAGIC)]))
+    start = len(MAGIC) + 1
+    salt = data[start : start + SALT_LENGTH]
+    checksum = data[start + SALT_LENGTH : HEADER_LENGTH]
+    plain = _xor(data[HEADER_LENGTH:], _keystream(salt, len(data) - HEADER_LENGTH))
+    if hashlib.sha256(plain).digest() != checksum:
+        raise ValueError("package checksum mismatch")
+    return plain