Skip to content

Commit 5238bb6

Browse files
zimuya4153zimuya4153
committed
feat: add some apis
1 parent 5e39cd8 commit 5238bb6

24 files changed

Lines changed: 751 additions & 146 deletions

‎CHANGELOG.md‎

Lines changed: 20 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -9,15 +9,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
99

1010
### Added
1111

12-
- Added packet sending APIs: `Packet::sendTo`, `Packet::sendToClients` and `Packet::sendToServer` @zimuya4153
13-
- Added `BinaryStream` APIs: `getReadPointer`, `setReadPointer`, `setData`, `writeBytes`, `writeUuid` and `writeNormalizedFloat` @zimuya4153
14-
- Added server APIs: `mc.getMotd`, `mc.getOnlinePlayerNum`, `mc.getMaxNumPlayers`, `mc.getDimensionId` and `mc.getDimensionName` @zimuya4153
12+
- Added packet APIs:
13+
`Packet::sendTo`, `Packet::sendToClients`, `Packet::sendToServer` @zimuya4153
14+
- Added `BinaryStream` APIs:
15+
`getReadPointer`, `setReadPointer`, `setData`, `writeBytes`, `readBytes`,
16+
`writeUuid` @zimuya4153
17+
- Added server APIs:
18+
`mc.getMotd`, `mc.getOnlinePlayerNum`, `mc.getMaxNumPlayers`,
19+
`mc.getDimensionId`, `mc.getDimensionName` @zimuya4153
20+
- Added gameplay helpers:
21+
`en.setCustomName`, `mc.summonMob`, `mc.loadMob`, `it.addCount`,
22+
`it.removeCount`, `it.setCount`, `system.randomUuid` @zimuya4153
1523

1624
### Changed
1725

18-
- `BinaryStream::getData([clear])` now supports the optional `clear` parameter and returns `ByteBuffer` instead of `String` @zimuya4153
19-
- `BinaryStream::createPacket(pktid[,raw])` now supports creating raw packets @zimuya4153
20-
- Allowed string arguments for several `BinaryStream::write*` numeric APIs to better support BigInt values @zimuya4153
26+
- Improved `BinaryStream`:
27+
`getData([clear])` now supports the optional `clear` parameter and returns
28+
`ByteBuffer`; `createPacket(pktid[,raw])` now supports raw packets; several
29+
numeric `write*` APIs now accept `String` for BigInt-friendly input
30+
@zimuya4153
31+
- Improved file and item behavior:
32+
`File.readFrom(path[,isBinary])` now supports binary reads;
33+
`File.writeTo(path, text)` now accepts `ByteBuffer`;
34+
`it.setLore([])` now clears custom lore instead of failing @zimuya4153
2135

2236
## [0.18.2] - 2026-04-17
2337

‎docs/apis/GameAPI/Entity.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -73,6 +73,52 @@ Through this function, generate a new creature at the specified location and get
7373
> Therefore, if there is a need to operate an entity for a long time, please obtain the real-time entity object through
7474
> the above methods.
7575
76+
#### Summon New Creature and Get Its Entity Object
77+
78+
!!! warning
79+
This function is only available in 0.19.0 and later.
80+
81+
Through this function, summon a new creature at the specified location and get its corresponding entity object.
82+
83+
`mc.summonMob(name,pos[,event])`
84+
`mc.summonMob(name,x,y,z,dimid[,event])`
85+
86+
- Parameters:
87+
- name : `String`
88+
The namespace name of the creature, such as `minecraft:creeper`
89+
- pos : `IntPos `/ `FloatPos`
90+
A coordinate object of where the mob is spawned (or use x, y, z, dimid to determine where to spawn).
91+
- event : `String`
92+
Optional initialization event name
93+
- Return value: The generated entity object.
94+
- Return value type: `Entity`
95+
- If the return value is `Null` it means that the generation failed
96+
97+
> Note: Do not save an entity object **long-term**.
98+
> When the entity corresponding to the entity object is destroyed, the corresponding entity object will become invalid.
99+
> Therefore, if there is a need to operate an entity for a long time, please obtain the real-time entity object through
100+
> the above methods.
101+
102+
#### Load Creature From NBT and Get Its Entity Object
103+
104+
!!! warning
105+
This function is only available in 0.19.0 and later.
106+
107+
Through this function, spawn a creature with the specified NBT data at the specified location and get its corresponding
108+
entity object.
109+
110+
`mc.loadMob(nbt,pos)`
111+
`mc.loadMob(nbt,x,y,z,dimid)`
112+
113+
- Parameters:
114+
- nbt : `NbtCompound`
115+
Creature NBT object
116+
- pos : `IntPos `/ `FloatPos`
117+
A coordinate object of where the mob is spawned (or use x, y, z, dimid to determine where to spawn).
118+
- Return value: The generated entity object.
119+
- Return value type: `Entity`
120+
- If the return value is `Null` it means that the generation failed
121+
76122
#### Clone A Creature and Get Its Entity Object
77123

78124
Through this function, generate a new creature at the specified location and get its corresponding entity object.
@@ -393,6 +439,19 @@ Note that the damage dealt here is real damage and cannot be reduced by protecti
393439
- Return value: Whether the entity was scaled.
394440
- Return value type: `Boolean`
395441

442+
#### Set Entity Custom Name
443+
444+
!!! warning
445+
This function is only available in 0.19.0 and later.
446+
447+
`en.setCustomName(name)`
448+
449+
- Parameters:
450+
- name : `String`
451+
The entity's new custom name
452+
- Return value: Whether setting was successful
453+
- Return value type: `Boolean`
454+
396455
#### Get Entity Distance To Pos
397456

398457
`en.distanceTo(pos)`

‎docs/apis/GameAPI/Entity.zh.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,49 @@
6969
> 注意：不要**长期保存**一个实体对象
7070
> 当实体对象对应的实体被销毁时，对应的实体对象将同时释放。因此，如果有长期操作某个实体的需要，请通过上述途径获取实时的实体对象
7171
72+
#### 召唤新生物并获取
73+
74+
!!! warning
75+
此函数仅在0.19.0及以后版本可用
76+
77+
通过此函数，在指定的位置召唤一个新生物，并获取它对应的实体对象
78+
79+
`mc.summonMob(name,pos[,event])`
80+
`mc.summonMob(name,x,y,z,dimid[,event])`
81+
82+
- 参数：
83+
- name : `String`
84+
生物的命名空间名称，如 `minecraft:creeper`
85+
- pos : `IntPos `/ `FloatPos`
86+
生成生物的位置的坐标对象（或者使用x, y, z, dimid来确定生成位置）
87+
- event : `String`
88+
可选的初始化事件名称
89+
- 返回值：生成的实体对象
90+
- 返回值类型：`Entity`
91+
- 如返回值为 `Null` 则表示生成失败
92+
93+
> 注意：不要**长期保存**一个实体对象
94+
> 当实体对象对应的实体被销毁时，对应的实体对象将同时释放。因此，如果有长期操作某个实体的需要，请通过上述途径获取实时的实体对象
95+
96+
#### 通过NBT加载生物并获取
97+
98+
!!! warning
99+
此函数仅在0.19.0及以后版本可用
100+
101+
通过此函数，使用指定的NBT数据在指定位置生成一个生物，并获取它对应的实体对象
102+
103+
`mc.loadMob(nbt,pos)`
104+
`mc.loadMob(nbt,x,y,z,dimid)`
105+
106+
- 参数：
107+
- nbt : `NbtCompound`
108+
生物的NBT对象
109+
- pos : `IntPos `/ `FloatPos`
110+
生成生物的位置的坐标对象（或者使用x, y, z, dimid来确定生成位置）
111+
- 返回值：生成的实体对象
112+
- 返回值类型：`Entity`
113+
- 如返回值为 `Null` 则表示生成失败
114+
72115
#### 复制生物并获取
73116

74117
通过此函数，在指定的位置复制另一个实体，并获取它对应的实体对象
@@ -383,6 +426,19 @@
383426
- 返回值: 实体是否成功地被缩放
384427
- 返回值类型: `Boolean`
385428

429+
#### 设置实体自定义名称
430+
431+
!!! warning
432+
此函数仅在0.19.0及以后版本可用
433+
434+
`en.setCustomName(name)`
435+
436+
- 参数:
437+
- name : `String`
438+
实体新的自定义名称
439+
- 返回值: 是否设置成功
440+
- 返回值类型: `Boolean`
441+
386442
#### 获取实体到坐标的距离
387443

388444
`en.distanceTo(pos)`

‎docs/apis/GameAPI/Item.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -205,6 +205,9 @@ For more usage of NBT objects, please refer to [NBT Interface Documentation](../
205205
- Return value: Whether setting the lore was successful.
206206
- Return value type: `Boolean`
207207

208+
!!! warning
209+
In 0.19.0 and later, passing an empty array will clear the item's lore.
210+
208211

209212

210213
#### Set Custom Item Name
@@ -229,4 +232,43 @@ For more usage of NBT objects, please refer to [NBT Interface Documentation](../
229232
- Return value: is the same kind of item
230233
- Return value type: `Boolean`
231234

235+
#### Increase Item Count
236+
237+
!!! warning
238+
This function is only available in 0.19.0 and later.
239+
240+
`it.addCount(count)`
241+
242+
- Parameters:
243+
- count : `Integer`
244+
Amount to add
245+
- Return value: Whether setting was successful
246+
- Return value type: `Boolean`
247+
248+
#### Decrease Item Count
249+
250+
!!! warning
251+
This function is only available in 0.19.0 and later.
252+
253+
`it.removeCount(count)`
254+
255+
- Parameters:
256+
- count : `Integer`
257+
Amount to remove
258+
- Return value: Whether setting was successful
259+
- Return value type: `Boolean`
260+
261+
#### Set Item Count
262+
263+
!!! warning
264+
This function is only available in 0.19.0 and later.
265+
266+
`it.setCount(count)`
267+
268+
- Parameters:
269+
- count : `Integer`
270+
Amount to set
271+
- Return value: Whether setting was successful
272+
- Return value type: `Boolean`
273+
232274

‎docs/apis/GameAPI/Item.zh.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -206,6 +206,9 @@
206206
- 返回值：是否设置成功
207207
- 返回值类型： `Boolean`
208208

209+
!!! warning
210+
在0.19.0及以后版本中，传入空数组会清空物品Lore。
211+
209212

210213

211214
#### 设置自定义物品名称
@@ -230,4 +233,43 @@
230233
- 返回值: 是否为同类物品
231234
- 返回值类型: `Boolean`
232235

236+
#### 增加物品数量
237+
238+
!!! warning
239+
此函数仅在0.19.0及以后版本可用
240+
241+
`it.addCount(count)`
242+
243+
- 参数:
244+
- count : `Integer`
245+
要增加的数量
246+
- 返回值: 是否设置成功
247+
- 返回值类型: `Boolean`
248+
249+
#### 减少物品数量
250+
251+
!!! warning
252+
此函数仅在0.19.0及以后版本可用
253+
254+
`it.removeCount(count)`
255+
256+
- 参数:
257+
- count : `Integer`
258+
要减少的数量
259+
- 返回值: 是否设置成功
260+
- 返回值类型: `Boolean`
261+
262+
#### 设置物品数量
263+
264+
!!! warning
265+
此函数仅在0.19.0及以后版本可用
266+
267+
`it.setCount(count)`
268+
269+
- 参数:
270+
- count : `Integer`
271+
要设置的数量
272+
- 返回值: 是否设置成功
273+
- 返回值类型: `Boolean`
274+
233275

‎docs/apis/GameAPI/Packet.md‎

Lines changed: 66 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -177,32 +177,72 @@ This function is only available in 0.19.0 and later.
177177
- Return value：success or not
178178
- Return value type： `Boolean`
179179

180-
| Available functions | Parameter Type |
181-
| -------------------------------------- | -------------------- |
182-
| writeBool | `Boolean` |
183-
| writeByte | `Integer` |
184-
| writeBytes (Added in 0.19.0) | `ByteBuffer` |
185-
| writeDouble | `Number` / `String` |
186-
| writeFloat | `Float` / `String` |
187-
| writeNormalizedFloat (Added in 0.19.0) | `Float` / `String` |
188-
| writeSignedBigEndianInt | `Number` / `String` |
189-
| writeSignedInt | `Number` / `String` |
190-
| writeSignedInt64 | `Number` / `String` |
191-
| writeSignedShort | `Integer` / `String` |
192-
| writeString | `String` |
193-
| writeUnsignedChar | `Integer` |
194-
| writeUnsignedInt | `Number` / `String` |
195-
| writeUnsignedInt64 | `Number` / `String` |
196-
| writeUnsignedShort | `Integer` / `String` |
197-
| writeUnsignedVarInt | `Number` / `String` |
198-
| writeUnsignedVarInt64 | `Number` / `String` |
199-
| writeVarInt | `Number` / `String` |
200-
| writeVarInt64 | `Number` / `String` |
201-
| writeVec3 | `FloatPos` |
202-
| writeBlockPos (Added in 0.9.5) | `BlockPos` |
203-
| writeCompoundTag | `NbtCompound` |
204-
| writeItem (Added in 0.9.5) | `Item` |
205-
| writeUuid (Added in 0.19.0) | `String` |
180+
| Available functions | Parameter Type |
181+
| ------------------------------ | -------------------- |
182+
| writeBool | `Boolean`/ `String` |
183+
| writeByte | `Integer` / `String` |
184+
| writeBytes (Added in 0.19.0) | `ByteBuffer` |
185+
| writeDouble | `Number` / `String` |
186+
| writeFloat | `Float` / `String` |
187+
| writeSignedBigEndianInt | `Number` / `String` |
188+
| writeSignedInt | `Number` / `String` |
189+
| writeSignedInt64 | `Number` / `String` |
190+
| writeSignedShort | `Integer` / `String` |
191+
| writeString | `String` |
192+
| writeUnsignedChar | `Integer` / `String` |
193+
| writeUnsignedInt | `Number` / `String` |
194+
| writeUnsignedInt64 | `Number` / `String` |
195+
| writeUnsignedShort | `Integer` / `String` |
196+
| writeUnsignedVarInt | `Number` / `String` |
197+
| writeUnsignedVarInt64 | `Number` / `String` |
198+
| writeVarInt | `Number` / `String` |
199+
| writeVarInt64 | `Number` / `String` |
200+
| writeVec3 | `FloatPos` |
201+
| writeBlockPos (Added in 0.9.5) | `BlockPos` |
202+
| writeCompoundTag | `NbtCompound` |
203+
| writeItem (Added in 0.9.5) | `Item` |
204+
| writeUuid (Added in 0.19.0) | `String` |
205+
206+
#### Read from binary stream
207+
208+
!!! warning
209+
This function group is only available in 0.19.0 and later.
210+
211+
`bs.readxxxx([asString])`
212+
`bs.readBytes(length)`
213+
214+
- Parameters:
215+
216+
- asString : `Boolean` (Optional parameter)
217+
Only available for numeric read functions. When set to `true`, the return value is converted to `String`
218+
- length : `Integer`
219+
Only available for `readBytes`. Number of bytes to read. Must be greater than `0`
220+
221+
- Return value:
222+
- Read result
223+
224+
| Available functions | Parameter Type | Return Type |
225+
| ---------------------- | -------------- | ------------------- |
226+
| readBool | None | `Boolean` |
227+
| readByte | `Boolean` | `Number` / `String` |
228+
| readBytes | `Integer` | `ByteBuffer` |
229+
| readUnsignedChar | `Boolean` | `Number` / `String` |
230+
| readDouble | `Boolean` | `Number` / `String` |
231+
| readFloat | `Boolean` | `Number` / `String` |
232+
| readSignedBigEndianInt | `Boolean` | `Number` / `String` |
233+
| readSignedInt | `Boolean` | `Number` / `String` |
234+
| readSignedInt64 | `Boolean` | `Number` / `String` |
235+
| readSignedShort | `Boolean` | `Number` / `String` |
236+
| readString | None | `String` |
237+
| readUnsignedInt | `Boolean` | `Number` / `String` |
238+
| readUnsignedInt64 | `Boolean` | `Number` / `String` |
239+
| readUnsignedShort | `Boolean` | `Number` / `String` |
240+
| readUnsignedVarInt | `Boolean` | `Number` / `String` |
241+
| readUnsignedVarInt64 | `Boolean` | `Number` / `String` |
242+
| readVarInt | `Boolean` | `Number` / `String` |
243+
| readVarInt64 | `Boolean` | `Number` / `String` |
244+
245+
When `asString` is `true`, numeric `read*` functions return `String`; otherwise they return `Number`.
206246

207247
#### Building packet from binary stream
208248

0 commit comments

Comments
 (0)