Skip to content

Commit 8316610

Browse files
zimuya4153zimuya4153
committed
refactor: fix and enhance BinaryStream and Packet
1 parent 2812f31 commit 8316610

6 files changed

Lines changed: 529 additions & 273 deletions

File tree

‎docs/apis/GameAPI/Packet.md‎

Lines changed: 158 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,16 @@
1-
# 🎓 Packet API
1+
# 🎓 Packet API
22

3-
The following objects and APIs provide the basic BDS packet interface for scripts.
3+
The following objects and APIs provide the basic BDS packet interface for scripts.
44

5-
(Please refer to Nukkit, PokcetMine, BDS Reverse to know the packet structure) If the client crashes, it is a packet structure error, not a bug.
5+
(Please refer to Nukkit, PokcetMine, BDS Reverse to know the packet structure) If the client crashes, it is a packet structure error, not a bug.
66

77
The documentation does not list the packet ID and its structure, please check it yourself.
88

9-
109
## 目录
10+
1111
- 🔉 [Packet Object API](#-packet-object-api)
1212
- 🔌 [Binary stream object API](#-binary-stream-object-api)
1313

14-
15-
1614
## 🔉 Packet Object API
1715

1816
In LLSE, 「Packet Object」 is used to get information about packets.
@@ -21,10 +19,8 @@ In LLSE, 「Packet Object」 is used to get information about packets.
2119

2220
#### Get from API
2321

24-
Call some **return packet object** function to get to the packet object given by BDS
25-
See [Binary Stream Objects](#-binary-stream-object-api) for details
26-
27-
22+
Call some **return packet object** function to get to the packet object given by BDS
23+
See [Binary Stream Objects](#-binary-stream-object-api) for details
2824

2925
### Packet Objects - Functions
3026

@@ -35,9 +31,7 @@ Every packet object contains some member functions (member methods) that can be
3531
`pkt.getName()`
3632

3733
- Return value：packet name
38-
- Return value type： `String`
39-
40-
34+
- Return value type： `String`
4135

4236
#### Get packet ID
4337

@@ -46,15 +40,55 @@ Every packet object contains some member functions (member methods) that can be
4640
- Return value：packet id
4741
- Return value type： `Integer`
4842

43+
#### Send packet to specified target
44+
45+
!!! warning
46+
This function is only available in 0.19.0 and later.
47+
48+
`pkt.sendTo(pos)`
49+
`pkt.sendTo(x,y,z,dimid)`
50+
`pkt.sendTo(target)`
51+
52+
- Parameters：
53+
54+
- pos : `IntPos` / `FloatPos`
55+
The coordinates of the packet send target (or use x, y, z, dimid to determine the target position)
56+
- target : `Player` / `Entity`
57+
Packet send target
58+
59+
- Return value：success or not
60+
- Return value type： `Boolean`
61+
62+
If `target` is `Player`, the packet will be sent to the specified player.
63+
If `target` is `Entity`, the packet will be sent to players around the specified entity.
4964

65+
#### Send packet to all clients
66+
67+
!!! warning
68+
This function is only available in 0.19.0 and later.
69+
70+
`pkt.sendToClients()`
71+
72+
- Return value：success or not
73+
- Return value type： `Boolean`
74+
75+
#### Send packet to server
76+
77+
!!! warning
78+
This function is only available in 0.19.0 and later.
79+
80+
`pkt.sendToServer()`
81+
82+
- Return value：success or not
83+
- Return value type： `Boolean`
5084

5185
## 🔌 Binary Stream Object API
5286

5387
### Create a binary stream object
5488

55-
[JavaScript] ```new BinaryStream()```
89+
[JavaScript] `new BinaryStream()`
5690

57-
[Lua] ```BinaryStream()```
91+
[Lua] `BinaryStream()`
5892

5993
- Return value: Binary stream object
6094
- Return value type： `BinaryStream`
@@ -70,72 +104,141 @@ Every binary stream object contains some member functions (member methods) that
70104
- Return value: success or not
71105
- Return value type： `Boolean`
72106

107+
#### Get binary stream read pointer
108+
109+
!!! warning
110+
This function is only available in 0.19.0 and later.
111+
112+
`bs.getReadPointer()`
113+
114+
- Return value: current read pointer
115+
- Return value type： `Integer`
116+
117+
#### Set binary stream read pointer
73118

119+
!!! warning
120+
This function is only available in 0.19.0 and later.
121+
122+
`bs.setReadPointer(pos)`
123+
124+
- Parameters：
125+
126+
- pos : `Integer`
127+
New read pointer
128+
129+
- Return value: success or not
130+
- Return value type： `Boolean`
131+
132+
#### Get binary stream data
133+
134+
!!! warning
135+
The optional parameter and `ByteBuffer` return value of this function are only available in 0.19.0 and later.
136+
137+
`bs.getData([clear])`
138+
139+
- Parameters：
140+
141+
- clear : `Boolean` (Optional parameter)
142+
Whether to clear stream data after reading. The default value is `true`
143+
144+
- Return value: binary stream data
145+
- Return value type： `ByteBuffer`
146+
147+
Before 0.19.0, this function can only be used as `bs.getData()`.
148+
At that time, it always cleared the stream data after reading, and the return value type was `String`.
149+
150+
Because the old return value was `String`, in JavaScript it may be forcibly encoded as UTF-8, causing binary data corruption and incorrect data content.
151+
152+
#### Set binary stream data
153+
154+
!!! warning
155+
This function is only available in 0.19.0 and later.
156+
157+
`bs.setData(data)`
158+
159+
- Parameters：
160+
161+
- data : `ByteBuffer`
162+
Binary stream data
163+
164+
- Return value: success or not
165+
- Return value type： `Boolean`
74166

75167
#### Write to binary stream
76168

77-
`bs.writexxxx(value)`
169+
`bs.writexxxx(value)`
78170

79171
- Parameters：
172+
80173
- value : `NULL`
81174
Refer to the table below
175+
For some numeric write functions, `String` is also accepted
82176

83177
- Return value：success or not
84178
- Return value type： `Boolean`
85179

86-
| Available functions | Parameter Type |
87-
| ------------------------------ | -------------- |
88-
| writeBool | `Boolean` |
89-
| writeByte | `Integer` |
90-
| writeDouble | `Number` |
91-
| writeFloat | `Float` |
92-
| writeSignedBigEndianInt | `Number` |
93-
| writeSignedInt | `Number` |
94-
| writeSignedInt64 | `Number` |
95-
| writeSignedShort | `Integer` |
96-
| writeString | `String` |
97-
| writeUnsignedChar | `Integer` |
98-
| writeUnsignedInt | `Number` |
99-
| writeUnsignedInt64 | `Number` |
100-
| writeUnsignedShort | `Integer` |
101-
| writeUnsignedVarInt | `Number` |
102-
| writeUnsignedVarInt64 | `Number` |
103-
| writeVarInt | `Number` |
104-
| writeVarInt64 | `Number` |
105-
| writeVec3 | `FloatPos` |
106-
| writeBlockPos (Added in 0.9.5) | `BlockPos` |
107-
| writeCompoundTag | `NbtCompound` |
108-
| writeItem (Added in 0.9.5) | `Item` |
109-
110-
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` |
111206

112207
#### Building packet from binary stream
113208

114-
`bs.createPacket(pktid)`
209+
!!! warning
210+
The optional parameter of this function is only available in 0.19.0 and later.
211+
212+
`bs.createPacket(pktid[,raw])`
115213

116214
- Parameters：
215+
117216
- pktid : `Integer`
118217
Packet ID
218+
- raw : `Boolean` (Optional parameter)
219+
Create raw network packet from current binary stream data. The default value is `false`
119220

120221
- Return value：Packet object
121222
- Return value type： `Packet`
122223

123-
224+
Before 0.19.0, this function can only be used as `bs.createPacket(pktid)`.
124225

125226
### Dome Code
126227

127228
Send TextPacket packets to a player
229+
128230
```js
129-
mc.listen("onChat",function(pl,msg){
130-
const bs = new BinaryStream()
131-
var text = "LLSE Packet Test"
132-
bs.reserve(text.length + 8)
133-
bs.writeUnsignedChar(0)
134-
bs.writeBool(true)
135-
bs.writeString(text)
136-
bs.writeString("")
137-
bs.writeString("")
138-
var pkt = bs.createPacket(9)
139-
pl.sendPacket(pkt)
140-
})
231+
mc.listen("onChat", (player, message) => {
232+
const text = "LLSE Packet Test";
233+
const bs = new BinaryStream();
234+
bs.reserve(text.length + 8);
235+
bs.writeBool(false);
236+
bs.writeByte(/* TextPacketPayload::mBody::MessageOnly (Variant Index) */0);
237+
bs.writeByte(/* TextPacketType::Raw (Enum) */0);
238+
bs.writeString(text);
239+
bs.writeString(""); // xuid
240+
bs.writeString(""); // platformId
241+
bs.writeString(""); // filtered message
242+
bs.createPacket(9).sendTo(player);
243+
});
141244
```

0 commit comments

Comments
 (0)