mcpylib 1.0.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- mcpylib-1.0.0/PKG-INFO +707 -0
- mcpylib-1.0.0/README.md +691 -0
- mcpylib-1.0.0/pyproject.toml +24 -0
- mcpylib-1.0.0/src/mcpylib/__init__.py +9 -0
- mcpylib-1.0.0/src/mcpylib/client.py +603 -0
- mcpylib-1.0.0/src/mcpylib/py.typed +0 -0
mcpylib-1.0.0/PKG-INFO
ADDED
|
@@ -0,0 +1,707 @@
|
|
|
1
|
+
Metadata-Version: 2.3
|
|
2
|
+
Name: mcpylib
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: Python library for controlling Minecraft servers remotely
|
|
5
|
+
Keywords: minecraft,bukkit,spigot,api
|
|
6
|
+
Author: treeleaves30760
|
|
7
|
+
Author-email: treeleaves30760 <treeleaves30760@gmail.com>
|
|
8
|
+
Classifier: Development Status :: 3 - Alpha
|
|
9
|
+
Classifier: Intended Audience :: Developers
|
|
10
|
+
Classifier: Programming Language :: Python :: 3
|
|
11
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
12
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
13
|
+
Requires-Dist: python-dotenv>=1.2.1
|
|
14
|
+
Requires-Python: >=3.11
|
|
15
|
+
Description-Content-Type: text/markdown
|
|
16
|
+
|
|
17
|
+
# MCPyLib - Python Client Library
|
|
18
|
+
|
|
19
|
+
Python client library for controlling Minecraft servers remotely.
|
|
20
|
+
|
|
21
|
+
## Installation
|
|
22
|
+
|
|
23
|
+
### Using uv (Recommended)
|
|
24
|
+
|
|
25
|
+
[uv](https://github.com/astral-sh/uv) is a fast Python package manager that's 10-100x faster than pip.
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
# Install uv if you haven't already
|
|
29
|
+
curl -LsSf https://astral.sh/uv/install.sh | sh
|
|
30
|
+
# or on macOS: brew install uv
|
|
31
|
+
|
|
32
|
+
# Clone and install
|
|
33
|
+
git clone <repository-url>
|
|
34
|
+
cd MCPyLib
|
|
35
|
+
uv sync
|
|
36
|
+
|
|
37
|
+
# Run scripts with uv
|
|
38
|
+
uv run python your_script.py
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
### Using pip (Traditional method)
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
# Clone and install
|
|
45
|
+
git clone <repository-url>
|
|
46
|
+
cd MCPyLib
|
|
47
|
+
pip install -e .
|
|
48
|
+
|
|
49
|
+
# Or when published to PyPI
|
|
50
|
+
pip install mcpylib
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
### Why use uv?
|
|
54
|
+
|
|
55
|
+
- **Fast**: 10-100x faster than pip
|
|
56
|
+
- **Reliable**: Automatic dependency locking (uv.lock)
|
|
57
|
+
- **Simple**: One command to set up everything
|
|
58
|
+
- **Isolated**: Automatic virtual environment management
|
|
59
|
+
|
|
60
|
+
## Quick Start
|
|
61
|
+
|
|
62
|
+
### Create and run your first script
|
|
63
|
+
|
|
64
|
+
```python
|
|
65
|
+
# quickstart.py
|
|
66
|
+
from mcpylib import MCPyLib
|
|
67
|
+
|
|
68
|
+
# Initialize client
|
|
69
|
+
mc = MCPyLib(
|
|
70
|
+
ip="127.0.0.1", # Server IP
|
|
71
|
+
port=65535, # Server port
|
|
72
|
+
token="your_token" # Authentication token
|
|
73
|
+
)
|
|
74
|
+
|
|
75
|
+
# Set a diamond block
|
|
76
|
+
mc.setblock(100, 64, 200, "minecraft:diamond_block")
|
|
77
|
+
|
|
78
|
+
# Get block type
|
|
79
|
+
block = mc.getblock(100, 64, 200)
|
|
80
|
+
print(f"Block: {block}") # Output: Block: minecraft:diamond_block
|
|
81
|
+
|
|
82
|
+
# Fill a 10x10x10 region with glass
|
|
83
|
+
count = mc.fill(0, 60, 0, 10, 70, 10, "minecraft:glass")
|
|
84
|
+
print(f"Filled {count} blocks")
|
|
85
|
+
|
|
86
|
+
# Get player position
|
|
87
|
+
pos = mc.getPos("Steve")
|
|
88
|
+
print(f"Player at: {pos}") # Output: Player at: [100, 64, 200]
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
### Run the script
|
|
92
|
+
|
|
93
|
+
```bash
|
|
94
|
+
# With uv (recommended)
|
|
95
|
+
uv run python quickstart.py
|
|
96
|
+
|
|
97
|
+
# Or with pip
|
|
98
|
+
python quickstart.py
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
## API Reference
|
|
102
|
+
|
|
103
|
+
### MCPyLib Class
|
|
104
|
+
|
|
105
|
+
#### Constructor
|
|
106
|
+
|
|
107
|
+
```python
|
|
108
|
+
MCPyLib(ip="127.0.0.1", port=65535, token="", timeout=10.0)
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
**Parameters:**
|
|
112
|
+
- `ip` (str): Server IP address
|
|
113
|
+
- `port` (int): Server port
|
|
114
|
+
- `token` (str): Authentication token from server
|
|
115
|
+
- `timeout` (float): Socket timeout in seconds
|
|
116
|
+
|
|
117
|
+
#### Methods
|
|
118
|
+
|
|
119
|
+
##### setblock()
|
|
120
|
+
|
|
121
|
+
```python
|
|
122
|
+
setblock(x: int, y: int, z: int, block_name: str, block_state: dict = None, nbt: dict = None) -> int
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
Set a block at the specified coordinates with optional block state and NBT data.
|
|
126
|
+
|
|
127
|
+
**Parameters:**
|
|
128
|
+
- `x`, `y`, `z` (int): Block coordinates
|
|
129
|
+
- `block_name` (str): Block type (e.g., "minecraft:stone" or "stone")
|
|
130
|
+
- `block_state` (dict, optional): Block state properties like direction, rotation, etc.
|
|
131
|
+
- `nbt` (dict, optional): NBT data for block entities (signs, chests, etc.)
|
|
132
|
+
|
|
133
|
+
**Returns:**
|
|
134
|
+
- `1` if successful
|
|
135
|
+
|
|
136
|
+
**Raises:**
|
|
137
|
+
- `ConnectionError`: Failed to connect to server
|
|
138
|
+
- `AuthenticationError`: Invalid token
|
|
139
|
+
- `CommandError`: Invalid coordinates, block type, or state properties
|
|
140
|
+
|
|
141
|
+
**Example:**
|
|
142
|
+
```python
|
|
143
|
+
# Basic block placement
|
|
144
|
+
mc.setblock(100, 64, 200, "minecraft:diamond_block")
|
|
145
|
+
mc.setblock(101, 64, 200, "gold_block") # "minecraft:" prefix is optional
|
|
146
|
+
|
|
147
|
+
# Place a stair facing north
|
|
148
|
+
mc.setblock(100, 64, 201, "oak_stairs", block_state={"facing": "north", "half": "bottom"})
|
|
149
|
+
|
|
150
|
+
# Place a fence gate facing east
|
|
151
|
+
mc.setblock(100, 64, 202, "oak_fence_gate", block_state={"facing": "east", "open": "false"})
|
|
152
|
+
|
|
153
|
+
# Place a log with horizontal axis
|
|
154
|
+
mc.setblock(100, 64, 203, "oak_log", block_state={"axis": "x"})
|
|
155
|
+
|
|
156
|
+
# Place a sign with text
|
|
157
|
+
mc.setblock(100, 64, 204, "oak_sign",
|
|
158
|
+
block_state={"rotation": "0"},
|
|
159
|
+
nbt={"Text1": "Hello", "Text2": "World", "Text3": "", "Text4": ""}
|
|
160
|
+
)
|
|
161
|
+
|
|
162
|
+
# Place a chest with custom name
|
|
163
|
+
mc.setblock(100, 64, 205, "chest",
|
|
164
|
+
block_state={"facing": "north"},
|
|
165
|
+
nbt={"CustomName": '{"text":"My Chest"}'}
|
|
166
|
+
)
|
|
167
|
+
|
|
168
|
+
# Place a waterlogged fence
|
|
169
|
+
mc.setblock(100, 64, 206, "oak_fence", block_state={"waterlogged": "true"})
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
**Common Block State Properties:**
|
|
173
|
+
- `facing`: Direction the block faces ("north", "south", "east", "west", "up", "down")
|
|
174
|
+
- `rotation`: Rotation for signs and banners ("0" to "15")
|
|
175
|
+
- `axis`: Axis for logs and pillars ("x", "y", "z")
|
|
176
|
+
- `half`: Upper or lower half ("top", "bottom")
|
|
177
|
+
- `shape`: Stair shape ("straight", "inner_left", "inner_right", "outer_left", "outer_right")
|
|
178
|
+
- `open`: Whether doors/gates are open ("true", "false")
|
|
179
|
+
- `powered`: Whether redstone components are powered ("true", "false")
|
|
180
|
+
- `waterlogged`: Whether block contains water ("true", "false")
|
|
181
|
+
|
|
182
|
+
##### getblock()
|
|
183
|
+
|
|
184
|
+
```python
|
|
185
|
+
getblock(x: int, y: int, z: int) -> str
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
Get the block type at coordinates.
|
|
189
|
+
|
|
190
|
+
**Parameters:**
|
|
191
|
+
- `x`, `y`, `z` (int): Block coordinates
|
|
192
|
+
|
|
193
|
+
**Returns:**
|
|
194
|
+
- Block type as string (e.g., "minecraft:stone")
|
|
195
|
+
|
|
196
|
+
**Raises:**
|
|
197
|
+
- `ConnectionError`: Failed to connect to server
|
|
198
|
+
- `AuthenticationError`: Invalid token
|
|
199
|
+
- `CommandError`: Invalid coordinates
|
|
200
|
+
|
|
201
|
+
**Example:**
|
|
202
|
+
```python
|
|
203
|
+
block = mc.getblock(100, 64, 200)
|
|
204
|
+
print(block) # "minecraft:diamond_block"
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
##### fill()
|
|
208
|
+
|
|
209
|
+
```python
|
|
210
|
+
fill(x1: int, y1: int, z1: int, x2: int, y2: int, z2: int, block_name: str) -> int
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
Fill a region with the specified block type.
|
|
214
|
+
|
|
215
|
+
**Parameters:**
|
|
216
|
+
- `x1`, `y1`, `z1` (int): Starting coordinates
|
|
217
|
+
- `x2`, `y2`, `z2` (int): Ending coordinates
|
|
218
|
+
- `block_name` (str): Block type
|
|
219
|
+
|
|
220
|
+
**Returns:**
|
|
221
|
+
- Number of blocks affected
|
|
222
|
+
|
|
223
|
+
**Raises:**
|
|
224
|
+
- `ConnectionError`: Failed to connect to server
|
|
225
|
+
- `AuthenticationError`: Invalid token
|
|
226
|
+
- `CommandError`: Invalid coordinates or block type
|
|
227
|
+
|
|
228
|
+
**Example:**
|
|
229
|
+
```python
|
|
230
|
+
# Fill a 10x10x10 cube with glass
|
|
231
|
+
count = mc.fill(0, 60, 0, 10, 70, 10, "minecraft:glass")
|
|
232
|
+
print(f"Filled {count} blocks") # "Filled 1331 blocks"
|
|
233
|
+
```
|
|
234
|
+
|
|
235
|
+
##### getPos()
|
|
236
|
+
|
|
237
|
+
```python
|
|
238
|
+
getPos(username: str) -> List[int]
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
Get a player's current position.
|
|
242
|
+
|
|
243
|
+
**Parameters:**
|
|
244
|
+
- `username` (str): Player's Minecraft username (case-sensitive)
|
|
245
|
+
|
|
246
|
+
**Returns:**
|
|
247
|
+
- List of `[x, y, z]` coordinates (integers)
|
|
248
|
+
|
|
249
|
+
**Raises:**
|
|
250
|
+
- `ConnectionError`: Failed to connect to server
|
|
251
|
+
- `AuthenticationError`: Invalid token
|
|
252
|
+
- `CommandError`: Player not found or not online
|
|
253
|
+
|
|
254
|
+
**Example:**
|
|
255
|
+
```python
|
|
256
|
+
pos = mc.getPos("Steve")
|
|
257
|
+
x, y, z = pos
|
|
258
|
+
print(f"Steve is at ({x}, {y}, {z})")
|
|
259
|
+
```
|
|
260
|
+
|
|
261
|
+
##### teleport()
|
|
262
|
+
|
|
263
|
+
```python
|
|
264
|
+
teleport(username: str, x: float, y: float, z: float, yaw: float = None, pitch: float = None) -> bool
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
Teleport a player to specified coordinates.
|
|
268
|
+
|
|
269
|
+
**Parameters:**
|
|
270
|
+
- `username` (str): Player's Minecraft username
|
|
271
|
+
- `x`, `y`, `z` (float): Target coordinates
|
|
272
|
+
- `yaw` (float, optional): Rotation yaw angle
|
|
273
|
+
- `pitch` (float, optional): Rotation pitch angle
|
|
274
|
+
|
|
275
|
+
**Returns:**
|
|
276
|
+
- `True` if successful
|
|
277
|
+
|
|
278
|
+
**Raises:**
|
|
279
|
+
- `ConnectionError`: Failed to connect to server
|
|
280
|
+
- `AuthenticationError`: Invalid token
|
|
281
|
+
- `CommandError`: Player not found or teleport fails
|
|
282
|
+
|
|
283
|
+
**Example:**
|
|
284
|
+
```python
|
|
285
|
+
# Teleport to coordinates
|
|
286
|
+
mc.teleport("Steve", 100, 64, 200)
|
|
287
|
+
|
|
288
|
+
# Teleport with rotation
|
|
289
|
+
mc.teleport("Steve", 100, 64, 200, yaw=90.0, pitch=0.0)
|
|
290
|
+
```
|
|
291
|
+
|
|
292
|
+
##### gamemode()
|
|
293
|
+
|
|
294
|
+
```python
|
|
295
|
+
gamemode(username: str, mode: str) -> bool
|
|
296
|
+
```
|
|
297
|
+
|
|
298
|
+
Change a player's game mode.
|
|
299
|
+
|
|
300
|
+
**Parameters:**
|
|
301
|
+
- `username` (str): Player's Minecraft username
|
|
302
|
+
- `mode` (str): Game mode ("survival", "creative", "adventure", "spectator")
|
|
303
|
+
|
|
304
|
+
**Returns:**
|
|
305
|
+
- `True` if successful
|
|
306
|
+
|
|
307
|
+
**Raises:**
|
|
308
|
+
- `ConnectionError`: Failed to connect to server
|
|
309
|
+
- `AuthenticationError`: Invalid token
|
|
310
|
+
- `CommandError`: Player not found or invalid game mode
|
|
311
|
+
|
|
312
|
+
**Example:**
|
|
313
|
+
```python
|
|
314
|
+
mc.gamemode("Steve", "creative")
|
|
315
|
+
mc.gamemode("Alex", "survival")
|
|
316
|
+
mc.gamemode("Bob", "spectator")
|
|
317
|
+
```
|
|
318
|
+
|
|
319
|
+
##### time()
|
|
320
|
+
|
|
321
|
+
```python
|
|
322
|
+
time(action: str, value: int = None) -> int
|
|
323
|
+
```
|
|
324
|
+
|
|
325
|
+
Control world time.
|
|
326
|
+
|
|
327
|
+
**Parameters:**
|
|
328
|
+
- `action` (str): Action to perform ("set", "add", "query")
|
|
329
|
+
- `value` (int, optional): Time value (0-24000) for "set" or "add" actions
|
|
330
|
+
|
|
331
|
+
**Returns:**
|
|
332
|
+
- Current world time (0-24000)
|
|
333
|
+
|
|
334
|
+
**Raises:**
|
|
335
|
+
- `ConnectionError`: Failed to connect to server
|
|
336
|
+
- `AuthenticationError`: Invalid token
|
|
337
|
+
- `CommandError`: Invalid action or value out of range
|
|
338
|
+
|
|
339
|
+
**Example:**
|
|
340
|
+
```python
|
|
341
|
+
# Set time to day (1000)
|
|
342
|
+
mc.time("set", 1000)
|
|
343
|
+
|
|
344
|
+
# Add 6000 ticks
|
|
345
|
+
mc.time("add", 6000)
|
|
346
|
+
|
|
347
|
+
# Query current time
|
|
348
|
+
current_time = mc.time("query")
|
|
349
|
+
print(f"Current time: {current_time}")
|
|
350
|
+
```
|
|
351
|
+
|
|
352
|
+
##### weather()
|
|
353
|
+
|
|
354
|
+
```python
|
|
355
|
+
weather(condition: str, duration: int = None) -> bool
|
|
356
|
+
```
|
|
357
|
+
|
|
358
|
+
Control world weather.
|
|
359
|
+
|
|
360
|
+
**Parameters:**
|
|
361
|
+
- `condition` (str): Weather condition ("clear", "rain", "thunder")
|
|
362
|
+
- `duration` (int, optional): Duration in seconds
|
|
363
|
+
|
|
364
|
+
**Returns:**
|
|
365
|
+
- `True` if successful
|
|
366
|
+
|
|
367
|
+
**Raises:**
|
|
368
|
+
- `ConnectionError`: Failed to connect to server
|
|
369
|
+
- `AuthenticationError`: Invalid token
|
|
370
|
+
- `CommandError`: Invalid weather condition
|
|
371
|
+
|
|
372
|
+
**Example:**
|
|
373
|
+
```python
|
|
374
|
+
# Clear weather
|
|
375
|
+
mc.weather("clear")
|
|
376
|
+
|
|
377
|
+
# Rain for 10 minutes (600 seconds)
|
|
378
|
+
mc.weather("rain", duration=600)
|
|
379
|
+
|
|
380
|
+
# Thunder storm for 5 minutes
|
|
381
|
+
mc.weather("thunder", duration=300)
|
|
382
|
+
```
|
|
383
|
+
|
|
384
|
+
##### give()
|
|
385
|
+
|
|
386
|
+
```python
|
|
387
|
+
give(username: str, item: str, amount: int = 1) -> bool
|
|
388
|
+
```
|
|
389
|
+
|
|
390
|
+
Give items to a player.
|
|
391
|
+
|
|
392
|
+
**Parameters:**
|
|
393
|
+
- `username` (str): Player's Minecraft username
|
|
394
|
+
- `item` (str): Item type (e.g., "minecraft:diamond" or "diamond")
|
|
395
|
+
- `amount` (int): Quantity (1-64, default: 1)
|
|
396
|
+
|
|
397
|
+
**Returns:**
|
|
398
|
+
- `True` if successful
|
|
399
|
+
|
|
400
|
+
**Raises:**
|
|
401
|
+
- `ConnectionError`: Failed to connect to server
|
|
402
|
+
- `AuthenticationError`: Invalid token
|
|
403
|
+
- `CommandError`: Player not found, invalid item, or amount out of range
|
|
404
|
+
|
|
405
|
+
**Example:**
|
|
406
|
+
```python
|
|
407
|
+
# Give 10 diamonds
|
|
408
|
+
mc.give("Steve", "minecraft:diamond", 10)
|
|
409
|
+
|
|
410
|
+
# Give 1 diamond sword (amount defaults to 1)
|
|
411
|
+
mc.give("Steve", "diamond_sword")
|
|
412
|
+
|
|
413
|
+
# Give 64 stone blocks
|
|
414
|
+
mc.give("Alex", "stone", 64)
|
|
415
|
+
```
|
|
416
|
+
|
|
417
|
+
##### summon()
|
|
418
|
+
|
|
419
|
+
```python
|
|
420
|
+
summon(entity_type: str, x: float, y: float, z: float) -> str
|
|
421
|
+
```
|
|
422
|
+
|
|
423
|
+
Summon an entity at specified coordinates.
|
|
424
|
+
|
|
425
|
+
**Parameters:**
|
|
426
|
+
- `entity_type` (str): Entity type (e.g., "minecraft:zombie", "pig", "creeper")
|
|
427
|
+
- `x`, `y`, `z` (float): Spawn coordinates
|
|
428
|
+
|
|
429
|
+
**Returns:**
|
|
430
|
+
- Entity UUID as string
|
|
431
|
+
|
|
432
|
+
**Raises:**
|
|
433
|
+
- `ConnectionError`: Failed to connect to server
|
|
434
|
+
- `AuthenticationError`: Invalid token
|
|
435
|
+
- `CommandError`: Invalid entity type or coordinates
|
|
436
|
+
|
|
437
|
+
**Example:**
|
|
438
|
+
```python
|
|
439
|
+
# Summon a zombie
|
|
440
|
+
uuid = mc.summon("minecraft:zombie", 100, 64, 200)
|
|
441
|
+
|
|
442
|
+
# Summon a pig (namespace prefix optional)
|
|
443
|
+
uuid = mc.summon("pig", 150, 70, 250)
|
|
444
|
+
|
|
445
|
+
# Summon a creeper
|
|
446
|
+
uuid = mc.summon("creeper", 200, 64, 300)
|
|
447
|
+
```
|
|
448
|
+
|
|
449
|
+
##### kill()
|
|
450
|
+
|
|
451
|
+
```python
|
|
452
|
+
kill(selector: str) -> int
|
|
453
|
+
```
|
|
454
|
+
|
|
455
|
+
Remove entities from the world.
|
|
456
|
+
|
|
457
|
+
**Parameters:**
|
|
458
|
+
- `selector` (str): Entity selector:
|
|
459
|
+
- `"all"` - Kill all entities
|
|
460
|
+
- Entity type (e.g., `"zombie"`, `"creeper"`) - Kill all of that type
|
|
461
|
+
- `"player:username"` - Kill a specific player
|
|
462
|
+
|
|
463
|
+
**Returns:**
|
|
464
|
+
- Number of entities killed
|
|
465
|
+
|
|
466
|
+
**Raises:**
|
|
467
|
+
- `ConnectionError`: Failed to connect to server
|
|
468
|
+
- `AuthenticationError`: Invalid token
|
|
469
|
+
- `CommandError`: Invalid selector or player not found
|
|
470
|
+
|
|
471
|
+
**Example:**
|
|
472
|
+
```python
|
|
473
|
+
# Kill all entities
|
|
474
|
+
count = mc.kill("all")
|
|
475
|
+
print(f"Killed {count} entities")
|
|
476
|
+
|
|
477
|
+
# Kill all zombies
|
|
478
|
+
zombie_count = mc.kill("zombie")
|
|
479
|
+
|
|
480
|
+
# Kill all creepers
|
|
481
|
+
creeper_count = mc.kill("creeper")
|
|
482
|
+
|
|
483
|
+
# Kill a specific player
|
|
484
|
+
mc.kill("player:Steve")
|
|
485
|
+
```
|
|
486
|
+
|
|
487
|
+
##### edit()
|
|
488
|
+
|
|
489
|
+
```python
|
|
490
|
+
edit(x: int, y: int, z: int, blocks: List[List[List]]) -> int
|
|
491
|
+
```
|
|
492
|
+
|
|
493
|
+
High-performance bulk block editing (like WorldEdit). Place large structures with mixed block types in a single operation.
|
|
494
|
+
|
|
495
|
+
**Parameters:**
|
|
496
|
+
- `x`, `y`, `z` (int): Starting coordinates
|
|
497
|
+
- `blocks` (List[List[List]]): 3D array of blocks [x][y][z], where each element can be:
|
|
498
|
+
- `str`: Block name (e.g., "stone", "minecraft:glass")
|
|
499
|
+
- `None`: Skip this position (leave unchanged)
|
|
500
|
+
- `dict`: Complex block with state and NBT:
|
|
501
|
+
```python
|
|
502
|
+
{
|
|
503
|
+
"block": "minecraft:chest",
|
|
504
|
+
"block_state": {"facing": "north"}, # Optional
|
|
505
|
+
"nbt": {"CustomName": '{"text":"Storage"}'} # Optional
|
|
506
|
+
}
|
|
507
|
+
```
|
|
508
|
+
|
|
509
|
+
**Returns:**
|
|
510
|
+
- Number of blocks placed
|
|
511
|
+
|
|
512
|
+
**Raises:**
|
|
513
|
+
- `ConnectionError`: Failed to connect to server
|
|
514
|
+
- `AuthenticationError`: Invalid token
|
|
515
|
+
- `CommandError`: Invalid block data or coordinates
|
|
516
|
+
|
|
517
|
+
**Example:**
|
|
518
|
+
```python
|
|
519
|
+
# Simple 2x2x2 cube
|
|
520
|
+
blocks = [
|
|
521
|
+
[["stone", "glass"], ["stone", "glass"]],
|
|
522
|
+
[["stone", "glass"], ["stone", "glass"]]
|
|
523
|
+
]
|
|
524
|
+
mc.edit(100, 64, 200, blocks)
|
|
525
|
+
|
|
526
|
+
# Mixed mode with complex blocks
|
|
527
|
+
blocks = [
|
|
528
|
+
[[None, "stone"], ["glass", None]],
|
|
529
|
+
[[{
|
|
530
|
+
"block": "minecraft:chest",
|
|
531
|
+
"block_state": {"facing": "north"},
|
|
532
|
+
"nbt": {"CustomName": '{"text":"Loot"}'}
|
|
533
|
+
}, "stone"], ["diamond_block", "gold_block"]]
|
|
534
|
+
]
|
|
535
|
+
mc.edit(100, 64, 200, blocks)
|
|
536
|
+
|
|
537
|
+
# Build a house
|
|
538
|
+
blocks = []
|
|
539
|
+
for x in range(10):
|
|
540
|
+
x_layer = []
|
|
541
|
+
for y in range(5):
|
|
542
|
+
y_layer = [None] * 10
|
|
543
|
+
x_layer.append(y_layer)
|
|
544
|
+
blocks.append(x_layer)
|
|
545
|
+
|
|
546
|
+
# Floor
|
|
547
|
+
for x in range(10):
|
|
548
|
+
for z in range(10):
|
|
549
|
+
blocks[x][0][z] = "stone"
|
|
550
|
+
|
|
551
|
+
# Walls
|
|
552
|
+
for y in range(1, 4):
|
|
553
|
+
for x in range(10):
|
|
554
|
+
blocks[x][y][0] = "cobblestone"
|
|
555
|
+
blocks[x][y][9] = "cobblestone"
|
|
556
|
+
for z in range(10):
|
|
557
|
+
blocks[0][y][z] = "cobblestone"
|
|
558
|
+
blocks[9][y][z] = "cobblestone"
|
|
559
|
+
|
|
560
|
+
# Roof
|
|
561
|
+
for x in range(10):
|
|
562
|
+
for z in range(10):
|
|
563
|
+
blocks[x][4][z] = "oak_planks"
|
|
564
|
+
|
|
565
|
+
count = mc.edit(100, 64, 200, blocks)
|
|
566
|
+
print(f"House built: {count} blocks")
|
|
567
|
+
```
|
|
568
|
+
|
|
569
|
+
**Performance Notes:**
|
|
570
|
+
- Use `edit()` for structures with multiple different block types
|
|
571
|
+
- Use `fill()` for large areas of the same block
|
|
572
|
+
- Much faster than calling `setblock()` repeatedly
|
|
573
|
+
- Supports thousands of blocks in a single operation
|
|
574
|
+
|
|
575
|
+
##### clone()
|
|
576
|
+
|
|
577
|
+
```python
|
|
578
|
+
clone(x1: int, y1: int, z1: int, x2: int, y2: int, z2: int, dest_x: int, dest_y: int, dest_z: int) -> int
|
|
579
|
+
```
|
|
580
|
+
|
|
581
|
+
Clone a region of blocks to a new location.
|
|
582
|
+
|
|
583
|
+
**Parameters:**
|
|
584
|
+
- `x1`, `y1`, `z1` (int): Source region start coordinates
|
|
585
|
+
- `x2`, `y2`, `z2` (int): Source region end coordinates
|
|
586
|
+
- `dest_x`, `dest_y`, `dest_z` (int): Destination coordinates
|
|
587
|
+
|
|
588
|
+
**Returns:**
|
|
589
|
+
- Number of blocks cloned
|
|
590
|
+
|
|
591
|
+
**Raises:**
|
|
592
|
+
- `ConnectionError`: Failed to connect to server
|
|
593
|
+
- `AuthenticationError`: Invalid token
|
|
594
|
+
- `CommandError`: Region too large (max 32,768 blocks)
|
|
595
|
+
|
|
596
|
+
**Example:**
|
|
597
|
+
```python
|
|
598
|
+
# Clone a 10x10x10 region
|
|
599
|
+
count = mc.clone(0, 64, 0, 10, 74, 10, 20, 64, 0)
|
|
600
|
+
print(f"Cloned {count} blocks")
|
|
601
|
+
|
|
602
|
+
# Copy a house from one location to another
|
|
603
|
+
mc.clone(100, 64, 100, 110, 74, 110, 200, 64, 200)
|
|
604
|
+
```
|
|
605
|
+
|
|
606
|
+
## Exception Handling
|
|
607
|
+
|
|
608
|
+
MCPyLib defines custom exceptions:
|
|
609
|
+
|
|
610
|
+
```python
|
|
611
|
+
from mcpylib import MCPyLib, MCPyLibError, ConnectionError, AuthenticationError, CommandError
|
|
612
|
+
|
|
613
|
+
try:
|
|
614
|
+
mc = MCPyLib(token="wrong_token")
|
|
615
|
+
mc.setblock(100, 64, 200, "minecraft:stone")
|
|
616
|
+
except AuthenticationError as e:
|
|
617
|
+
print(f"Authentication failed: {e}")
|
|
618
|
+
except ConnectionError as e:
|
|
619
|
+
print(f"Connection failed: {e}")
|
|
620
|
+
except CommandError as e:
|
|
621
|
+
print(f"Command failed: {e}")
|
|
622
|
+
except MCPyLibError as e:
|
|
623
|
+
print(f"General error: {e}")
|
|
624
|
+
```
|
|
625
|
+
|
|
626
|
+
## Block Names
|
|
627
|
+
|
|
628
|
+
Block names can be specified with or without the "minecraft:" namespace prefix:
|
|
629
|
+
|
|
630
|
+
```python
|
|
631
|
+
# Both are valid
|
|
632
|
+
mc.setblock(0, 64, 0, "minecraft:stone")
|
|
633
|
+
mc.setblock(0, 64, 0, "stone")
|
|
634
|
+
|
|
635
|
+
# Common blocks
|
|
636
|
+
mc.setblock(0, 64, 0, "grass_block")
|
|
637
|
+
mc.setblock(0, 65, 0, "oak_log")
|
|
638
|
+
mc.setblock(0, 66, 0, "diamond_block")
|
|
639
|
+
mc.setblock(0, 67, 0, "glowstone")
|
|
640
|
+
```
|
|
641
|
+
|
|
642
|
+
See the [Minecraft Wiki](https://minecraft.fandom.com/wiki/Java_Edition_data_values) for a complete list of block IDs.
|
|
643
|
+
|
|
644
|
+
## Advanced Usage
|
|
645
|
+
|
|
646
|
+
### Custom Timeout
|
|
647
|
+
|
|
648
|
+
```python
|
|
649
|
+
# Set a longer timeout for slow connections
|
|
650
|
+
mc = MCPyLib(
|
|
651
|
+
ip="192.168.1.100",
|
|
652
|
+
port=65535,
|
|
653
|
+
token="your_token",
|
|
654
|
+
timeout=30.0 # 30 seconds
|
|
655
|
+
)
|
|
656
|
+
```
|
|
657
|
+
|
|
658
|
+
### Building Structures
|
|
659
|
+
|
|
660
|
+
```python
|
|
661
|
+
def build_cube(mc, x, y, z, size, block):
|
|
662
|
+
"""Build a hollow cube"""
|
|
663
|
+
# Bottom and top
|
|
664
|
+
mc.fill(x, y, z, x+size, y, z+size, block)
|
|
665
|
+
mc.fill(x, y+size, z, x+size, y+size, z+size, block)
|
|
666
|
+
|
|
667
|
+
# Sides
|
|
668
|
+
mc.fill(x, y, z, x, y+size, z+size, block)
|
|
669
|
+
mc.fill(x+size, y, z, x+size, y+size, z+size, block)
|
|
670
|
+
mc.fill(x, y, z, x+size, y+size, z, block)
|
|
671
|
+
mc.fill(x, y, z+size, x+size, y+size, z+size, block)
|
|
672
|
+
|
|
673
|
+
# Build a 10x10x10 glass cube
|
|
674
|
+
build_cube(mc, 0, 64, 0, 10, "glass")
|
|
675
|
+
```
|
|
676
|
+
|
|
677
|
+
### Following Players
|
|
678
|
+
|
|
679
|
+
```python
|
|
680
|
+
import time
|
|
681
|
+
|
|
682
|
+
def follow_player(mc, username, interval=1.0):
|
|
683
|
+
"""Track player movement"""
|
|
684
|
+
try:
|
|
685
|
+
while True:
|
|
686
|
+
pos = mc.getPos(username)
|
|
687
|
+
print(f"{username} is at {pos}")
|
|
688
|
+
time.sleep(interval)
|
|
689
|
+
except KeyboardInterrupt:
|
|
690
|
+
print("Stopped tracking")
|
|
691
|
+
except CommandError as e:
|
|
692
|
+
print(f"Error: {e}")
|
|
693
|
+
|
|
694
|
+
follow_player(mc, "Steve")
|
|
695
|
+
```
|
|
696
|
+
|
|
697
|
+
## Requirements
|
|
698
|
+
|
|
699
|
+
- Python 3.11 or higher
|
|
700
|
+
- No external dependencies (uses only standard library)
|
|
701
|
+
|
|
702
|
+
## See Also
|
|
703
|
+
|
|
704
|
+
- [Main Documentation](../README.md)
|
|
705
|
+
- [Server Plugin Documentation](../ServerPlugin/README.md)
|
|
706
|
+
- [Communication Protocol](../PROTOCOL.md)
|
|
707
|
+
- [Example Scripts](../example.py)
|