mcapibridge 0.1.0__tar.gz

mcapibridge-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TaotianZhufang
+
+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.

mcapibridge-0.1.0/PKG-INFO

@@ -0,0 +1,280 @@
+Metadata-Version: 2.4
+Name: mcapibridge
+Version: 0.1.0
+Summary: Python libary for MCAPIBridge
+Author: TaotianZhufang
+License: MIT License
+        
+        Copyright (c) 2026 TaotianZhufang
+        
+        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.
+        
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# MCAPIBridge Python Libary
+
+MCAPIBridge is a mod for Minecraft loaded with Fabric.This libary offers some ways to connect Minecraft with this mod in Python.
+
+## QuickStart
+
+### Install
+Ensure your mod loaded.
+
+Put`mc.py`into your project folder or use pip to install this.
+```
+pip install mcapibridge
+```
+This is a simple example to connect.
+```
+from mc import Minecraft
+import time
+
+# Default ip is localhost and port is 4711
+# You can use mc = Minecraft(host=YOURIP,port=YOURPORT) to change
+mc = Minecraft()
+
+# Show a message
+mc.postToChat("§aHello, Minecraft! Python is here.")
+```
+
+---
+
+## Usage
+
+### Basic
+
+#### `postToChat(msg)`
+Send a message to chat screen.
+*   **msg**: String message.Support `§` .You can check it on Minecraft wiki.
+
+#### `runCommand(cmd)`
+Run commands as Server.
+*   **cmd**: Srting command without '/'
+
+Ex: `mc.runCommand("time set day")`
+
+---
+
+### World
+
+#### `setBlock(x, y, z, block_id, dimension=None)`
+Set a block at the point given.
+*   **x, y, z**: Int positions.
+*   **block_id**: String ID.If it is Minecraft vanilla,the ID can be written without `Minecraft:`. Ex:`"stone"`, `"diamond_block"`.Support other namespaces.
+*	**dimension**: Optional String target dimension/player name.
+
+#### `getBlock(x, y, z, dimension=None)`
+Gets the block ID at the specified coordinates.
+*   **x, y, z**: Int positions.
+*   **dimension**: Optional String target dimension/player name.
+*   **return**: String block ID.Ex.`"minecraft:grass_block"`.
+
+#### `spawnEntity(x, y, z, entity_id, yaw=0.0, pitch=0.0, dimension=None)`
+Spawn an entity at the point given.
+*   **entity_id**: String ID.If it is Minecraft vanilla,the ID can be written without `Minecraft:`. Ex:`"zombie"`, `"pig"`, `"lightning_bolt"`.Support other namespaces.
+*   **yaw**: Optional Int degree.Horizontal degree.
+*   **pitch**: Optional Int degree.Vertical degree.
+*   **dimension**: Optional String target dimension/player name.
+
+#### `setEntityVelocity(entity_id, vx, vy, vz)`
+Sets the velocity of an entity.
+*   **entity_id**: Int ID.
+*   **vx, vy, vz**: Double velocity components.
+
+#### `setEntityNoGravity(entity_id, enable=True)`
+Enables or disables gravity for an entity.
+*   **entity_id**: Int ID.
+
+#### `getEntities(x, y, z, radius=10, dimension=None)`
+Gets the block ID at the specified coordinates.
+*   **x, y, z**: Double positions.
+*   **radius**: Double search radius.
+*   **dimension**: Optional String target dimension/player name.
+*   **return**: List of Dicts: [{'id': 123, 'type': 'minecraft:zombie', 'pos': Vec3}, ...]
+
+#### `spawnParticle(x, y, z, particle_id, count=10, dx=0.0, dy=0.0, dz=0.0, speed=0.0, dimension=None)`
+Spawn particle at the point given.
+*   **particle_id**: String ID.If it is Minecraft vanilla,the ID can be written without `Minecraft:`. Ex:`"flame"`, `"heart"`.Support other namespaces.
+*   **count**: Int count.
+*   **dx, dy, dz**: Optional double diffusion ranges.(when count=0, it represents the direction vector)
+*   **speed**: Optional double speed.
+*   **dimension**: Optional String target dimension/player name.
+
+#### `setSign(x, y, z, line1="", line2="", line3="", line4="", dimension=None)`
+Sets the text on a sign block.
+*   **x, y, z**: Int positions.
+*   **line1-4**: String text for each line.
+*   **dimension**: Optional String target dimension/player name.
+
+**The block at the position must already be a sign.**
+
+---
+
+### Info
+
+#### `getOnlinePlayers()`
+Get players' name online.
+*   **return**: Dict:  `[{'name': 'Steve', 'id': 123}, ...]`。
+
+#### `getPlayerPos(target="")`
+Get player's position and yaw and pitch.
+*   **target**: String player name.
+*   **return**: Int x,y,z and Double yaw,pitch.
+
+#### `getPlayerEntityId(name)`
+Get player's ID.
+*   **name**: String player name.
+*   **return**: Int ID.
+
+#### `getPlayerName(entity_id)`
+Get player's ID.
+*   **entity_id**: Int ID.
+*   **return**: String player name.
+
+#### `getPlayerDetails(target="")`
+Get player's details.
+*   **target**: String player name.
+*   **return**: Dict including
+    *   `name`: String player name
+    *   `id`: Int ID
+    *   `mode`: String gamemode
+    *   `health`: Double health
+    *   `max_health`: Double max health
+    *   `food`: Int food
+    *   `held_item`: String item held
+    *   `held_count`: Int item held count
+
+---
+
+### State
+
+#### `setHealth(target, amount)`
+Set player's health.
+*   **target**: String player name.
+*   **amount**: Double health.
+
+#### `setFood(target, amount)`
+Set player's food.
+*   **target**: String player name.
+*   **amount**: Int food(0-20).
+
+#### `giveEffect(target, effect_name, duration_sec=30, amplifier=1)`
+Effect player.
+*   **effect_name**: String effect ID.Ex:`"speed"`,`"night_vision"`.
+*   **duration_sec**: Int seconds.
+*   **amplifier**: Int amplifier.
+
+#### `setFlying(target, allow_flight=True, is_flying=True)`
+Enable player to fly in survival mode.
+*   **target**: String player name.
+
+#### `setFlySpeed(target, speed=0.05)`
+Set flight speed.
+*   **target**: String player name.
+*   **speed**: Double speed.Default 0.05.
+
+#### `setWalkSpeed(target, speed=0.1)`
+Set walk speed.
+*   **target**: String player name.
+*   **speed**: Double speed.Default 0.1.
+
+#### `setGodMode(target, enable=True)`
+Enable invulnerability.
+*   **target**: String player name.
+
+---
+
+### Inventory
+
+#### `getInventory(target="")`
+Get player's inventory.
+*   **return**: List of Dicts.Every dict has `{'slot': block_ID, 'id': item_ID, 'count': item_count}`.
+
+#### `give(target, item_id, count=1)`
+Give player item.
+*   **item_id**: String item ID.
+*   **count**: Int count.
+
+#### `clearInventory(target, item_id="")`
+Clear inventory.
+*   **target**: String player name.
+*   **item_id**: String item ID.
+
+---
+
+### TP
+
+#### `teleport(x, y, z, target="")`
+TP player.
+*   **x, y, z**: Int target x,y,z.
+*   **target**: String player ID.
+
+#### `teleportEntity(entity_id, x, y, z)`
+TP entitie.
+*   **entity_id**: Int entity id.
+
+---
+
+### Events
+
+#### `pollBlockHits()`
+Get click events.
+*   **return**: List Class `[BlockHit1,BlockHit2,.....]`
+    * **pos**: Class Vec3
+		* Double x
+		* Double y
+		* Double z
+	* **face**: Int click face.
+	* **entityId**: Int ID of clicking on entity.
+	* **action**: Int action type:1--left click,2--right click.(Left click event is only affected by player clicking where which can reach)
+	* **type**: String action:"LEFT_CLICK" or "RIGHT_CLICK"
+
+#### `pollChatPosts()`
+Get player message events.
+*   **return**: List Class `[ChatPost1,ChatPost2,.....]`
+	* **name**: String player name.
+	* **message**: String message.
+
+---
+
+### Helper Methods
+
+#### `getDirectionVector(target="")`
+Calculates the direction vector based on a player's rotation. Useful for shooting projectiles.
+*   **target**: String player ID.
+*   **return**: Class `Vec3` normalized direction vector.
+
+---
+
+### Helper Classes
+
+#### `Vec3`
+Represents a 3D vector/coordinate.
+*   **properties**: `x`,`y`,`z`.
+*   **Methods**:
+    *   **length()**: Returns vector length.
+
+#### `PlayerPos`
+**Inherits Vec3.**Represents player position with rotation.
+*   **properties**: `x`,`y`,`z`,`yaw`,`pitch`.
+*   **Methods**:
+    *   **forward(distance=1.0)**: Returns a new `Vec3` position at `distance` blocks ahead of the player's view.

mcapibridge-0.1.0/README.MD

@@ -0,0 +1,248 @@
+# MCAPIBridge Python Libary
+
+MCAPIBridge is a mod for Minecraft loaded with Fabric.This libary offers some ways to connect Minecraft with this mod in Python.
+
+## QuickStart
+
+### Install
+Ensure your mod loaded.
+
+Put`mc.py`into your project folder or use pip to install this.
+```
+pip install mcapibridge
+```
+This is a simple example to connect.
+```
+from mc import Minecraft
+import time
+
+# Default ip is localhost and port is 4711
+# You can use mc = Minecraft(host=YOURIP,port=YOURPORT) to change
+mc = Minecraft()
+
+# Show a message
+mc.postToChat("§aHello, Minecraft! Python is here.")
+```
+
+---
+
+## Usage
+
+### Basic
+
+#### `postToChat(msg)`
+Send a message to chat screen.
+*   **msg**: String message.Support `§` .You can check it on Minecraft wiki.
+
+#### `runCommand(cmd)`
+Run commands as Server.
+*   **cmd**: Srting command without '/'
+
+Ex: `mc.runCommand("time set day")`
+
+---
+
+### World
+
+#### `setBlock(x, y, z, block_id, dimension=None)`
+Set a block at the point given.
+*   **x, y, z**: Int positions.
+*   **block_id**: String ID.If it is Minecraft vanilla,the ID can be written without `Minecraft:`. Ex:`"stone"`, `"diamond_block"`.Support other namespaces.
+*	**dimension**: Optional String target dimension/player name.
+
+#### `getBlock(x, y, z, dimension=None)`
+Gets the block ID at the specified coordinates.
+*   **x, y, z**: Int positions.
+*   **dimension**: Optional String target dimension/player name.
+*   **return**: String block ID.Ex.`"minecraft:grass_block"`.
+
+#### `spawnEntity(x, y, z, entity_id, yaw=0.0, pitch=0.0, dimension=None)`
+Spawn an entity at the point given.
+*   **entity_id**: String ID.If it is Minecraft vanilla,the ID can be written without `Minecraft:`. Ex:`"zombie"`, `"pig"`, `"lightning_bolt"`.Support other namespaces.
+*   **yaw**: Optional Int degree.Horizontal degree.
+*   **pitch**: Optional Int degree.Vertical degree.
+*   **dimension**: Optional String target dimension/player name.
+
+#### `setEntityVelocity(entity_id, vx, vy, vz)`
+Sets the velocity of an entity.
+*   **entity_id**: Int ID.
+*   **vx, vy, vz**: Double velocity components.
+
+#### `setEntityNoGravity(entity_id, enable=True)`
+Enables or disables gravity for an entity.
+*   **entity_id**: Int ID.
+
+#### `getEntities(x, y, z, radius=10, dimension=None)`
+Gets the block ID at the specified coordinates.
+*   **x, y, z**: Double positions.
+*   **radius**: Double search radius.
+*   **dimension**: Optional String target dimension/player name.
+*   **return**: List of Dicts: [{'id': 123, 'type': 'minecraft:zombie', 'pos': Vec3}, ...]
+
+#### `spawnParticle(x, y, z, particle_id, count=10, dx=0.0, dy=0.0, dz=0.0, speed=0.0, dimension=None)`
+Spawn particle at the point given.
+*   **particle_id**: String ID.If it is Minecraft vanilla,the ID can be written without `Minecraft:`. Ex:`"flame"`, `"heart"`.Support other namespaces.
+*   **count**: Int count.
+*   **dx, dy, dz**: Optional double diffusion ranges.(when count=0, it represents the direction vector)
+*   **speed**: Optional double speed.
+*   **dimension**: Optional String target dimension/player name.
+
+#### `setSign(x, y, z, line1="", line2="", line3="", line4="", dimension=None)`
+Sets the text on a sign block.
+*   **x, y, z**: Int positions.
+*   **line1-4**: String text for each line.
+*   **dimension**: Optional String target dimension/player name.
+
+**The block at the position must already be a sign.**
+
+---
+
+### Info
+
+#### `getOnlinePlayers()`
+Get players' name online.
+*   **return**: Dict:  `[{'name': 'Steve', 'id': 123}, ...]`。
+
+#### `getPlayerPos(target="")`
+Get player's position and yaw and pitch.
+*   **target**: String player name.
+*   **return**: Int x,y,z and Double yaw,pitch.
+
+#### `getPlayerEntityId(name)`
+Get player's ID.
+*   **name**: String player name.
+*   **return**: Int ID.
+
+#### `getPlayerName(entity_id)`
+Get player's ID.
+*   **entity_id**: Int ID.
+*   **return**: String player name.
+
+#### `getPlayerDetails(target="")`
+Get player's details.
+*   **target**: String player name.
+*   **return**: Dict including
+    *   `name`: String player name
+    *   `id`: Int ID
+    *   `mode`: String gamemode
+    *   `health`: Double health
+    *   `max_health`: Double max health
+    *   `food`: Int food
+    *   `held_item`: String item held
+    *   `held_count`: Int item held count
+
+---
+
+### State
+
+#### `setHealth(target, amount)`
+Set player's health.
+*   **target**: String player name.
+*   **amount**: Double health.
+
+#### `setFood(target, amount)`
+Set player's food.
+*   **target**: String player name.
+*   **amount**: Int food(0-20).
+
+#### `giveEffect(target, effect_name, duration_sec=30, amplifier=1)`
+Effect player.
+*   **effect_name**: String effect ID.Ex:`"speed"`,`"night_vision"`.
+*   **duration_sec**: Int seconds.
+*   **amplifier**: Int amplifier.
+
+#### `setFlying(target, allow_flight=True, is_flying=True)`
+Enable player to fly in survival mode.
+*   **target**: String player name.
+
+#### `setFlySpeed(target, speed=0.05)`
+Set flight speed.
+*   **target**: String player name.
+*   **speed**: Double speed.Default 0.05.
+
+#### `setWalkSpeed(target, speed=0.1)`
+Set walk speed.
+*   **target**: String player name.
+*   **speed**: Double speed.Default 0.1.
+
+#### `setGodMode(target, enable=True)`
+Enable invulnerability.
+*   **target**: String player name.
+
+---
+
+### Inventory
+
+#### `getInventory(target="")`
+Get player's inventory.
+*   **return**: List of Dicts.Every dict has `{'slot': block_ID, 'id': item_ID, 'count': item_count}`.
+
+#### `give(target, item_id, count=1)`
+Give player item.
+*   **item_id**: String item ID.
+*   **count**: Int count.
+
+#### `clearInventory(target, item_id="")`
+Clear inventory.
+*   **target**: String player name.
+*   **item_id**: String item ID.
+
+---
+
+### TP
+
+#### `teleport(x, y, z, target="")`
+TP player.
+*   **x, y, z**: Int target x,y,z.
+*   **target**: String player ID.
+
+#### `teleportEntity(entity_id, x, y, z)`
+TP entitie.
+*   **entity_id**: Int entity id.
+
+---
+
+### Events
+
+#### `pollBlockHits()`
+Get click events.
+*   **return**: List Class `[BlockHit1,BlockHit2,.....]`
+    * **pos**: Class Vec3
+		* Double x
+		* Double y
+		* Double z
+	* **face**: Int click face.
+	* **entityId**: Int ID of clicking on entity.
+	* **action**: Int action type:1--left click,2--right click.(Left click event is only affected by player clicking where which can reach)
+	* **type**: String action:"LEFT_CLICK" or "RIGHT_CLICK"
+
+#### `pollChatPosts()`
+Get player message events.
+*   **return**: List Class `[ChatPost1,ChatPost2,.....]`
+	* **name**: String player name.
+	* **message**: String message.
+
+---
+
+### Helper Methods
+
+#### `getDirectionVector(target="")`
+Calculates the direction vector based on a player's rotation. Useful for shooting projectiles.
+*   **target**: String player ID.
+*   **return**: Class `Vec3` normalized direction vector.
+
+---
+
+### Helper Classes
+
+#### `Vec3`
+Represents a 3D vector/coordinate.
+*   **properties**: `x`,`y`,`z`.
+*   **Methods**:
+    *   **length()**: Returns vector length.
+
+#### `PlayerPos`
+**Inherits Vec3.**Represents player position with rotation.
+*   **properties**: `x`,`y`,`z`,`yaw`,`pitch`.
+*   **Methods**:
+    *   **forward(distance=1.0)**: Returns a new `Vec3` position at `distance` blocks ahead of the player's view.

mcapibridge-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mcapibridge"
+version = "0.1.0"
+description = "Python libary for MCAPIBridge"
+requires-python = ">=3.7"
+license = { file = "LICENSE" }
+readme = "README.MD"
+authors = [
+    { name = "TaotianZhufang" }
+]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+

mcapibridge-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mcapibridge-0.1.0/src/mc/__init__.py

@@ -0,0 +1,9 @@
+from .minecraft import Minecraft, Vec3, PlayerPos, BlockHit, ChatPost
+
+__all__ = [
+    "Minecraft",
+    "Vec3",
+    "PlayerPos",
+    "BlockHit",
+    "ChatPost",
+]

mcapibridge-0.1.0/src/mc/minecraft.py

@@ -0,0 +1,342 @@
+import socket
+import math
+import time
+
+class Vec3:
+    def __init__(self, x, y, z):
+        self.x, self.y, self.z = x, y, z
+    def __repr__(self): return f"Vec3({self.x:.2f}, {self.y:.2f}, {self.z:.2f})"
+    def __sub__(self, o): return Vec3(self.x-o.x, self.y-o.y, self.z-o.z)
+    def length(self): return math.sqrt(self.x**2 + self.y**2 + self.z**2)
+
+class PlayerPos(Vec3):
+    def __init__(self, x, y, z, yaw, pitch):
+        super().__init__(x, y, z)
+        self.yaw = yaw
+        self.pitch = pitch
+
+    def __repr__(self):
+        return f"PlayerPos(x={self.x:.1f}, y={self.y:.1f}, z={self.z:.1f}, yaw={self.yaw:.1f}, pitch={self.pitch:.1f})"
+    
+    def forward(self, distance=1.0):
+        yaw_rad = math.radians(self.yaw)
+        pitch_rad = math.radians(self.pitch)
+        
+        vx = -math.sin(yaw_rad) * math.cos(pitch_rad)
+        vy = -math.sin(pitch_rad)
+        vz = math.cos(yaw_rad) * math.cos(pitch_rad)
+        
+        return Vec3(self.x + vx * distance, self.y + vy * distance, self.z + vz * distance)
+
+class ChatPost:
+    def __init__(self, name, message):
+        self.name = name
+        self.message = message
+    
+    def __repr__(self):
+        return f"[{self.name}]: {self.message}"
+
+class BlockHit:
+    def __init__(self, x, y, z, face, entityId, action):
+        self.pos = Vec3(x, y, z)
+        self.face = face
+        self.entityId = entityId
+        self.action = action # 1=Left, 2=Right
+        self.type = "RIGHT_CLICK" if action == 2 else "LEFT_CLICK"
+
+class Minecraft:
+    def __init__(self, host="localhost", port=4711):
+        self.host = host
+        self.port = port
+        self.socket = None
+        self.file_reader = None
+        self.connected = False
+        self._connect()
+
+    def _connect(self):
+        try:
+            if self.socket:
+                try: self.socket.close()
+                except: pass
+            
+            self.socket = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+            self.socket.settimeout(5) 
+            self.socket.connect((self.host, self.port))
+            
+            self.file_reader = self.socket.makefile('r', encoding='utf-8')
+            self.connected = True
+            print(f"[MCAPI] Connected ({self.host}:{self.port}).")
+            return True
+        except (ConnectionRefusedError, socket.timeout):
+            print("[MCAPI] Lost connection.Retry...")
+            self.connected = False
+            return False
+
+    def _send(self, cmd):
+        try:
+            if not self.connected:
+                if not self._connect(): return
+
+            self.socket.sendall((cmd + "\n").encode("utf-8"))
+        except (BrokenPipeError, ConnectionResetError, socket.timeout, OSError):
+            print("[MCAPI] Lost connection.Retry...")
+            if self._connect():
+                try:
+                    self.socket.sendall((cmd + "\n").encode("utf-8"))
+                except:
+                    print("[MCAPI] Retry failed.")
+
+    def _recv(self):
+        if not self.connected: return ""
+        try:
+            line = self.file_reader.readline()
+            if not line:
+                print("[MCAPI] Retry.")
+                self.connected = False
+                for i in range(3):
+                    time.sleep(1)
+                    if self._connect():
+                        return self._recv()
+                return ""
+            return line.strip()
+        except (socket.timeout, OSError):
+            return ""
+
+    def postToChat(self, msg):
+        self._send(f"chat.post({msg})")
+
+    def runCommand(self, cmd):
+        if cmd.startswith("/"): cmd = cmd[1:]
+        self._send(f"server.runCommand({cmd})")
+
+    def setBlock(self, x, y, z, block_id, dimension=None):
+        if dimension:
+            self._send(f"world.setBlock({int(x)},{int(y)},{int(z)},{block_id},{dimension})")
+        else:
+            self._send(f"world.setBlock({int(x)},{int(y)},{int(z)},{block_id})")
+
+    def spawnEntity(self, x, y, z, entity_id, yaw=0.0, pitch=0.0, dimension=None):
+        if dimension:
+            self._send(f"world.spawnEntity({x},{y},{z},{entity_id},{yaw},{pitch},{dimension})")
+        else:
+            self._send(f"world.spawnEntity({x},{y},{z},{entity_id},{yaw},{pitch})")
+            
+        return int(self._recv())
+
+    def spawnParticle(self, x, y, z, particle_id, count=10, dx=0.0, dy=0.0, dz=0.0, speed=0.0, dimension=None):
+        cmd = f"{x},{y},{z},{particle_id},{count},{dx},{dy},{dz},{speed}"
+        if dimension:
+            cmd += f",{dimension}"
+        self._send(f"world.spawnParticle({cmd})")
+
+    def setEntityVelocity(self, entity_id, vx, vy, vz):
+        self._send(f"entity.setVelocity({entity_id},{vx},{vy},{vz})")
+
+    def getDirectionVector(self,target=""):
+        pos = self.getPlayerPos(target=target)
+        
+        self._send("player.getPos()")
+        data = self._recv().split(",")
+        if len(data) < 5: return Vec3(0,0,1)
+        
+        yaw = float(data[3])
+        pitch = float(data[4])
+        
+        yaw_rad = math.radians(yaw)
+        pitch_rad = math.radians(pitch)
+        
+        vx = -math.sin(yaw_rad) * math.cos(pitch_rad)
+        vy = -math.sin(pitch_rad)
+        vz = math.cos(yaw_rad) * math.cos(pitch_rad)
+        
+        return Vec3(vx, vy, vz)
+
+    def setEntityNoGravity(self, entity_id, enable=True):
+        val = "true" if enable else "false"
+        self._send(f"entity.setNoGravity({entity_id},{val})")
+
+    def getPlayerPos(self, target=""):
+        self._send(f"player.getPos({target})")
+        data = self._recv()
+        if not data: return PlayerPos(0,0,0,0,0)
+        # x, y, z, yaw, pitch
+        parts = data.split(",")
+        if len(parts) >= 5:
+            return PlayerPos(
+                float(parts[0]), float(parts[1]), float(parts[2]),
+                float(parts[3]), float(parts[4])
+            )
+        return PlayerPos(0,0,0,0,0)
+
+    def getOnlinePlayers(self):
+        self._send("world.getPlayers()")
+        d = self._recv()
+        if not d: return []
+        players = []
+        for item in d.split("|"):
+            parts = item.split(",")
+            if len(parts) == 2:
+                players.append({"name": parts[0], "id": int(parts[1])})
+        return players
+
+    def getPlayerDetails(self, target=""):
+        self._send(f"player.getDetails({target})")
+        d = self._recv()
+        if not d or "Error" in d: return None
+        p = d.split(",")
+        # Name,ID,Mode,HP,MaxHP,Food,HeldItem,Count
+        return {
+            "name": p[0],
+            "id": int(p[1]),
+            "mode": p[2],
+            "health": float(p[3]),
+            "max_health": float(p[4]),
+            "food": int(p[5]),
+            "held_item": p[6],
+            "held_count": int(p[7])
+        }
+
+    def getPlayerEntityId(self, name):
+        players = self.getOnlinePlayers()
+        for p in players:
+            if p['name'] == name:
+                return p['id']
+        return None
+
+    def getPlayerName(self, entity_id):
+        players = self.getOnlinePlayers()
+        for p in players:
+            if p['id'] == entity_id:
+                return p['name']
+        return None
+    
+    def getInventory(self, target=""):
+        self._send(f"player.getInventory({target})")
+        d = self._recv()
+        
+        if not d or "EMPTY" in d or "ERROR" in d: return []
+        
+        items = []
+        for item_str in d.split("|"):
+            parts = item_str.split(":")
+            if len(parts) == 3:
+                items.append({
+                    "slot": int(parts[0]),
+                    "id": parts[1],
+                    "count": int(parts[2])
+                })
+            elif len(parts) == 4:
+                items.append({
+                    "slot": int(parts[0]),
+                    "id": f"{parts[1]}:{parts[2]}",
+                    "count": int(parts[3])
+                })
+        return items
+
+    def setHealth(self, target, amount):
+        self._send(f"player.setHealth({target},{amount})")
+
+    def setFood(self, target, amount):
+        self._send(f"player.setFood({target},{amount})")
+
+    def give(self, target, item_id, count=1):
+        self._send(f"player.give({target},{item_id},{count})")
+
+    def clearInventory(self, target, item_id=""):
+        self._send(f"player.clear({target},{item_id})")
+
+    def giveEffect(self, target, effect_name, duration_sec=30, amplifier=1):
+        self._send(f"player.effect({target},{effect_name},{duration_sec},{amplifier})")
+
+    def teleport(self, x, y, z, target=""):
+        if target:
+            self._send(f"player.teleport({target},{x},{y},{z})")
+        else:
+            self._send(f"player.teleport({x},{y},{z})")
+
+    def teleportEntity(self, entity_id, x, y, z):
+        self._send(f"entity.teleport({entity_id},{x},{y},{z})")
+
+    def pollBlockHits(self):
+        self._send("events.block.hits()")
+        d = self._recv()
+        hits = []
+        if not d: return hits
+        for item in d.split("|"):
+            p = item.split(",")
+            if len(p) >= 6:
+                hits.append(BlockHit(
+                    int(p[0]), int(p[1]), int(p[2]), 
+                    int(p[3]), int(p[4]), int(p[5])
+                ))
+        return hits
+    
+    def pollChatPosts(self):
+        """
+        [ChatPost(name='Steve', message='Hello'), ...]
+        """
+        self._send("events.chat.posts()")
+        data = self._recv()
+        posts = []
+        if not data: return posts
+        
+        for item in data.split("|"):
+            parts = item.split(",", 1)
+            if len(parts) == 2:
+                posts.append(ChatPost(parts[0], parts[1]))
+        return posts
+
+    def setFlying(self, target, allow_flight=True, is_flying=True):
+        a = "true" if allow_flight else "false"
+        f = "true" if is_flying else "false"
+        self._send(f"player.setFlying({target},{a},{f})")
+
+    def setFlySpeed(self, target, speed=0.05):
+        # Default speed:0.05
+        self._send(f"player.setSpeed({target},true,{speed})")
+
+    def setWalkSpeed(self, target, speed=0.1):
+        # Default speed:0.1
+        self._send(f"player.setSpeed({target},false,{speed})")
+
+    def setGodMode(self, target, enable=True):
+        val = "true" if enable else "false"
+        self._send(f"player.setGod({target},{val})")
+
+    def getBlock(self, x, y, z, dimension=None):
+        cmd = f"world.getBlock({int(x)},{int(y)},{int(z)})"
+        if dimension: cmd = f"world.getBlock({int(x)},{int(y)},{int(z)},{dimension})"
+        self._send(cmd)
+        return self._recv()
+
+    def getEntities(self, x, y, z, radius=10, dimension=None):
+        """
+        [{'id': 123, 'type': 'zombie', 'pos': Vec3}, ...]
+        """
+        cmd = f"world.getEntities({x},{y},{z},{radius})"
+        if dimension: cmd = f"world.getEntities({x},{y},{z},{radius},{dimension})"
+        self._send(cmd)
+        data = self._recv()
+        if not data: return []
+        
+        entities = []
+        for item in data.split("|"):
+            # ID,Type,X,Y,Z
+            p = item.split(",")
+            if len(p) >= 5:
+                entities.append({
+                    "id": int(p[0]),
+                    "type": p[1],
+                    "pos": Vec3(float(p[2]), float(p[3]), float(p[4]))
+                })
+        return entities
+
+    def setSign(self, x, y, z, line1="", line2="", line3="", line4="", dimension=None):
+        l1 = line1.replace(",", "，")
+        l2 = line2.replace(",", "，")
+        l3 = line3.replace(",", "，")
+        l4 = line4.replace(",", "，")
+        
+        cmd = f"world.setSign({int(x)},{int(y)},{int(z)},{l1},{l2},{l3},{l4})"
+        if dimension: cmd += f",{dimension}"
+        self._send(cmd)

mcapibridge-0.1.0/src/mcapibridge.egg-info/PKG-INFO

@@ -0,0 +1,280 @@
+Metadata-Version: 2.4
+Name: mcapibridge
+Version: 0.1.0
+Summary: Python libary for MCAPIBridge
+Author: TaotianZhufang
+License: MIT License
+        
+        Copyright (c) 2026 TaotianZhufang
+        
+        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.
+        
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# MCAPIBridge Python Libary
+
+MCAPIBridge is a mod for Minecraft loaded with Fabric.This libary offers some ways to connect Minecraft with this mod in Python.
+
+## QuickStart
+
+### Install
+Ensure your mod loaded.
+
+Put`mc.py`into your project folder or use pip to install this.
+```
+pip install mcapibridge
+```
+This is a simple example to connect.
+```
+from mc import Minecraft
+import time
+
+# Default ip is localhost and port is 4711
+# You can use mc = Minecraft(host=YOURIP,port=YOURPORT) to change
+mc = Minecraft()
+
+# Show a message
+mc.postToChat("§aHello, Minecraft! Python is here.")
+```
+
+---
+
+## Usage
+
+### Basic
+
+#### `postToChat(msg)`
+Send a message to chat screen.
+*   **msg**: String message.Support `§` .You can check it on Minecraft wiki.
+
+#### `runCommand(cmd)`
+Run commands as Server.
+*   **cmd**: Srting command without '/'
+
+Ex: `mc.runCommand("time set day")`
+
+---
+
+### World
+
+#### `setBlock(x, y, z, block_id, dimension=None)`
+Set a block at the point given.
+*   **x, y, z**: Int positions.
+*   **block_id**: String ID.If it is Minecraft vanilla,the ID can be written without `Minecraft:`. Ex:`"stone"`, `"diamond_block"`.Support other namespaces.
+*	**dimension**: Optional String target dimension/player name.
+
+#### `getBlock(x, y, z, dimension=None)`
+Gets the block ID at the specified coordinates.
+*   **x, y, z**: Int positions.
+*   **dimension**: Optional String target dimension/player name.
+*   **return**: String block ID.Ex.`"minecraft:grass_block"`.
+
+#### `spawnEntity(x, y, z, entity_id, yaw=0.0, pitch=0.0, dimension=None)`
+Spawn an entity at the point given.
+*   **entity_id**: String ID.If it is Minecraft vanilla,the ID can be written without `Minecraft:`. Ex:`"zombie"`, `"pig"`, `"lightning_bolt"`.Support other namespaces.
+*   **yaw**: Optional Int degree.Horizontal degree.
+*   **pitch**: Optional Int degree.Vertical degree.
+*   **dimension**: Optional String target dimension/player name.
+
+#### `setEntityVelocity(entity_id, vx, vy, vz)`
+Sets the velocity of an entity.
+*   **entity_id**: Int ID.
+*   **vx, vy, vz**: Double velocity components.
+
+#### `setEntityNoGravity(entity_id, enable=True)`
+Enables or disables gravity for an entity.
+*   **entity_id**: Int ID.
+
+#### `getEntities(x, y, z, radius=10, dimension=None)`
+Gets the block ID at the specified coordinates.
+*   **x, y, z**: Double positions.
+*   **radius**: Double search radius.
+*   **dimension**: Optional String target dimension/player name.
+*   **return**: List of Dicts: [{'id': 123, 'type': 'minecraft:zombie', 'pos': Vec3}, ...]
+
+#### `spawnParticle(x, y, z, particle_id, count=10, dx=0.0, dy=0.0, dz=0.0, speed=0.0, dimension=None)`
+Spawn particle at the point given.
+*   **particle_id**: String ID.If it is Minecraft vanilla,the ID can be written without `Minecraft:`. Ex:`"flame"`, `"heart"`.Support other namespaces.
+*   **count**: Int count.
+*   **dx, dy, dz**: Optional double diffusion ranges.(when count=0, it represents the direction vector)
+*   **speed**: Optional double speed.
+*   **dimension**: Optional String target dimension/player name.
+
+#### `setSign(x, y, z, line1="", line2="", line3="", line4="", dimension=None)`
+Sets the text on a sign block.
+*   **x, y, z**: Int positions.
+*   **line1-4**: String text for each line.
+*   **dimension**: Optional String target dimension/player name.
+
+**The block at the position must already be a sign.**
+
+---
+
+### Info
+
+#### `getOnlinePlayers()`
+Get players' name online.
+*   **return**: Dict:  `[{'name': 'Steve', 'id': 123}, ...]`。
+
+#### `getPlayerPos(target="")`
+Get player's position and yaw and pitch.
+*   **target**: String player name.
+*   **return**: Int x,y,z and Double yaw,pitch.
+
+#### `getPlayerEntityId(name)`
+Get player's ID.
+*   **name**: String player name.
+*   **return**: Int ID.
+
+#### `getPlayerName(entity_id)`
+Get player's ID.
+*   **entity_id**: Int ID.
+*   **return**: String player name.
+
+#### `getPlayerDetails(target="")`
+Get player's details.
+*   **target**: String player name.
+*   **return**: Dict including
+    *   `name`: String player name
+    *   `id`: Int ID
+    *   `mode`: String gamemode
+    *   `health`: Double health
+    *   `max_health`: Double max health
+    *   `food`: Int food
+    *   `held_item`: String item held
+    *   `held_count`: Int item held count
+
+---
+
+### State
+
+#### `setHealth(target, amount)`
+Set player's health.
+*   **target**: String player name.
+*   **amount**: Double health.
+
+#### `setFood(target, amount)`
+Set player's food.
+*   **target**: String player name.
+*   **amount**: Int food(0-20).
+
+#### `giveEffect(target, effect_name, duration_sec=30, amplifier=1)`
+Effect player.
+*   **effect_name**: String effect ID.Ex:`"speed"`,`"night_vision"`.
+*   **duration_sec**: Int seconds.
+*   **amplifier**: Int amplifier.
+
+#### `setFlying(target, allow_flight=True, is_flying=True)`
+Enable player to fly in survival mode.
+*   **target**: String player name.
+
+#### `setFlySpeed(target, speed=0.05)`
+Set flight speed.
+*   **target**: String player name.
+*   **speed**: Double speed.Default 0.05.
+
+#### `setWalkSpeed(target, speed=0.1)`
+Set walk speed.
+*   **target**: String player name.
+*   **speed**: Double speed.Default 0.1.
+
+#### `setGodMode(target, enable=True)`
+Enable invulnerability.
+*   **target**: String player name.
+
+---
+
+### Inventory
+
+#### `getInventory(target="")`
+Get player's inventory.
+*   **return**: List of Dicts.Every dict has `{'slot': block_ID, 'id': item_ID, 'count': item_count}`.
+
+#### `give(target, item_id, count=1)`
+Give player item.
+*   **item_id**: String item ID.
+*   **count**: Int count.
+
+#### `clearInventory(target, item_id="")`
+Clear inventory.
+*   **target**: String player name.
+*   **item_id**: String item ID.
+
+---
+
+### TP
+
+#### `teleport(x, y, z, target="")`
+TP player.
+*   **x, y, z**: Int target x,y,z.
+*   **target**: String player ID.
+
+#### `teleportEntity(entity_id, x, y, z)`
+TP entitie.
+*   **entity_id**: Int entity id.
+
+---
+
+### Events
+
+#### `pollBlockHits()`
+Get click events.
+*   **return**: List Class `[BlockHit1,BlockHit2,.....]`
+    * **pos**: Class Vec3
+		* Double x
+		* Double y
+		* Double z
+	* **face**: Int click face.
+	* **entityId**: Int ID of clicking on entity.
+	* **action**: Int action type:1--left click,2--right click.(Left click event is only affected by player clicking where which can reach)
+	* **type**: String action:"LEFT_CLICK" or "RIGHT_CLICK"
+
+#### `pollChatPosts()`
+Get player message events.
+*   **return**: List Class `[ChatPost1,ChatPost2,.....]`
+	* **name**: String player name.
+	* **message**: String message.
+
+---
+
+### Helper Methods
+
+#### `getDirectionVector(target="")`
+Calculates the direction vector based on a player's rotation. Useful for shooting projectiles.
+*   **target**: String player ID.
+*   **return**: Class `Vec3` normalized direction vector.
+
+---
+
+### Helper Classes
+
+#### `Vec3`
+Represents a 3D vector/coordinate.
+*   **properties**: `x`,`y`,`z`.
+*   **Methods**:
+    *   **length()**: Returns vector length.
+
+#### `PlayerPos`
+**Inherits Vec3.**Represents player position with rotation.
+*   **properties**: `x`,`y`,`z`,`yaw`,`pitch`.
+*   **Methods**:
+    *   **forward(distance=1.0)**: Returns a new `Vec3` position at `distance` blocks ahead of the player's view.

mcapibridge-0.1.0/src/mcapibridge.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+LICENSE
+README.MD
+pyproject.toml
+src/mc/__init__.py
+src/mc/minecraft.py
+src/mcapibridge.egg-info/PKG-INFO
+src/mcapibridge.egg-info/SOURCES.txt
+src/mcapibridge.egg-info/dependency_links.txt
+src/mcapibridge.egg-info/top_level.txt

mcapibridge-0.1.0/src/mcapibridge.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

mcapibridge-0.1.0/src/mcapibridge.egg-info/top_level.txt

@@ -0,0 +1 @@
+mc