Skip to content

Fix and enhance some things #376

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
zimuya4153 wants to merge 3 commits into
base: develop
Choose a base branch
from
Open

Fix and enhance some things #376

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
8316610
refactor: fix and enhance BinaryStream and Packet
zimuya4153 Jun 29, 2026
19e1092
fix: fix command parameter result
zimuya4153 Jun 29, 2026
5e39cd8
feat: add some apis
zimuya4153 Jun 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

## [Unreleased]

### Added

- Added packet sending APIs: `Packet::sendTo`, `Packet::sendToClients` and `Packet::sendToServer` @zimuya4153
- Added `BinaryStream` APIs: `getReadPointer`, `setReadPointer`, `setData`, `writeBytes`, `writeUuid` and `writeNormalizedFloat` @zimuya4153
- Added server APIs: `mc.getMotd`, `mc.getOnlinePlayerNum`, `mc.getMaxNumPlayers`, `mc.getDimensionId` and `mc.getDimensionName` @zimuya4153

### Changed

- `BinaryStream::getData([clear])` now supports the optional `clear` parameter and returns `ByteBuffer` instead of `String` @zimuya4153
- `BinaryStream::createPacket(pktid[,raw])` now supports creating raw packets @zimuya4153
- Allowed string arguments for several `BinaryStream::write*` numeric APIs to better support BigInt values @zimuya4153

## [0.18.2] - 2026-04-17

### Fixed
Expand Down
213 changes: 158 additions & 55 deletions docs/apis/GameAPI/Packet.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,18 +1,16 @@
# 🎓 Packet API
# 🎓 Packet API

The following objects and APIs provide the basic BDS packet interface for scripts.
The following objects and APIs provide the basic BDS packet interface for scripts.

(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.
(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.

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


## 目录

- 🔉 [Packet Object API](#-packet-object-api)
- 🔌 [Binary stream object API](#-binary-stream-object-api)



## 🔉 Packet Object API

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

#### Get from API

Call some **return packet object** function to get to the packet object given by BDS
See [Binary Stream Objects](#-binary-stream-object-api) for details


Call some **return packet object** function to get to the packet object given by BDS
See [Binary Stream Objects](#-binary-stream-object-api) for details

### Packet Objects - Functions

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

- Return value：packet name
- Return value type： `String`


- Return value type： `String`

#### Get packet ID

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

#### Send packet to specified target

!!! warning
This function is only available in 0.19.0 and later.

`pkt.sendTo(pos)`
`pkt.sendTo(x,y,z,dimid)`
`pkt.sendTo(target)`

- Parameters：

- pos : `IntPos` / `FloatPos`
The coordinates of the packet send target (or use x, y, z, dimid to determine the target position)
- target : `Player` / `Entity`
Packet send target

- Return value：success or not
- Return value type： `Boolean`

If `target` is `Player`, the packet will be sent to the specified player.
If `target` is `Entity`, the packet will be sent to players around the specified entity.

#### Send packet to all clients

!!! warning
This function is only available in 0.19.0 and later.

`pkt.sendToClients()`

- Return value：success or not
- Return value type： `Boolean`

#### Send packet to server

!!! warning
This function is only available in 0.19.0 and later.

`pkt.sendToServer()`

- Return value：success or not
- Return value type： `Boolean`

## 🔌 Binary Stream Object API

### Create a binary stream object

[JavaScript] ```new BinaryStream()```
[JavaScript] `new BinaryStream()`

[Lua] ```BinaryStream()```
[Lua] `BinaryStream()`

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

#### Get binary stream read pointer

!!! warning
This function is only available in 0.19.0 and later.

`bs.getReadPointer()`

- Return value: current read pointer
- Return value type： `Integer`

#### Set binary stream read pointer

!!! warning
This function is only available in 0.19.0 and later.

`bs.setReadPointer(pos)`

- Parameters：

- pos : `Integer`
New read pointer

- Return value: success or not
- Return value type： `Boolean`

#### Get binary stream data

!!! warning
The optional parameter and `ByteBuffer` return value of this function are only available in 0.19.0 and later.

`bs.getData([clear])`

- Parameters：

- clear : `Boolean` (Optional parameter)
Whether to clear stream data after reading. The default value is `true`

- Return value: binary stream data
- Return value type： `ByteBuffer`

Before 0.19.0, this function can only be used as `bs.getData()`.
At that time, it always cleared the stream data after reading, and the return value type was `String`.

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.

#### Set binary stream data

!!! warning
This function is only available in 0.19.0 and later.

`bs.setData(data)`

- Parameters：

- data : `ByteBuffer`
Binary stream data

- Return value: success or not
- Return value type： `Boolean`

#### Write to binary stream

`bs.writexxxx(value)`
`bs.writexxxx(value)`

- Parameters：

- value : `NULL`
Refer to the table below
For some numeric write functions, `String` is also accepted

- Return value：success or not
- Return value type： `Boolean`

| Available functions | Parameter Type |
| ------------------------------ | -------------- |
| writeBool | `Boolean` |
| writeByte | `Integer` |
| writeDouble | `Number` |
| writeFloat | `Float` |
| writeSignedBigEndianInt | `Number` |
| writeSignedInt | `Number` |
| writeSignedInt64 | `Number` |
| writeSignedShort | `Integer` |
| writeString | `String` |
| writeUnsignedChar | `Integer` |
| writeUnsignedInt | `Number` |
| writeUnsignedInt64 | `Number` |
| writeUnsignedShort | `Integer` |
| writeUnsignedVarInt | `Number` |
| writeUnsignedVarInt64 | `Number` |
| writeVarInt | `Number` |
| writeVarInt64 | `Number` |
| writeVec3 | `FloatPos` |
| writeBlockPos (Added in 0.9.5) | `BlockPos` |
| writeCompoundTag | `NbtCompound` |
| writeItem (Added in 0.9.5) | `Item` |


| Available functions | Parameter Type |
| -------------------------------------- | -------------------- |
| writeBool | `Boolean` |
| writeByte | `Integer` |
| writeBytes (Added in 0.19.0) | `ByteBuffer` |
| writeDouble | `Number` / `String` |
| writeFloat | `Float` / `String` |
| writeNormalizedFloat (Added in 0.19.0) | `Float` / `String` |
| writeSignedBigEndianInt | `Number` / `String` |
| writeSignedInt | `Number` / `String` |
| writeSignedInt64 | `Number` / `String` |
| writeSignedShort | `Integer` / `String` |
| writeString | `String` |
| writeUnsignedChar | `Integer` |
| writeUnsignedInt | `Number` / `String` |
| writeUnsignedInt64 | `Number` / `String` |
| writeUnsignedShort | `Integer` / `String` |
| writeUnsignedVarInt | `Number` / `String` |
| writeUnsignedVarInt64 | `Number` / `String` |
| writeVarInt | `Number` / `String` |
| writeVarInt64 | `Number` / `String` |
| writeVec3 | `FloatPos` |
| writeBlockPos (Added in 0.9.5) | `BlockPos` |
| writeCompoundTag | `NbtCompound` |
| writeItem (Added in 0.9.5) | `Item` |
| writeUuid (Added in 0.19.0) | `String` |

#### Building packet from binary stream

`bs.createPacket(pktid)`
!!! warning
The optional parameter of this function is only available in 0.19.0 and later.

`bs.createPacket(pktid[,raw])`

- Parameters：

- pktid : `Integer`
Packet ID
- raw : `Boolean` (Optional parameter)
Create raw network packet from current binary stream data. The default value is `false`

- Return value：Packet object
- Return value type： `Packet`


Before 0.19.0, this function can only be used as `bs.createPacket(pktid)`.

### Dome Code

Send TextPacket packets to a player

```js
mc.listen("onChat",function(pl,msg){
const bs = new BinaryStream()
var text = "LLSE Packet Test"
bs.reserve(text.length + 8)
bs.writeUnsignedChar(0)
bs.writeBool(true)
bs.writeString(text)
bs.writeString("")
bs.writeString("")
var pkt = bs.createPacket(9)
pl.sendPacket(pkt)
})
mc.listen("onChat", (player, message) => {
const text = "LLSE Packet Test";
const bs = new BinaryStream();
bs.reserve(text.length + 8);
bs.writeBool(false);
bs.writeByte(/* TextPacketPayload::mBody::MessageOnly (Variant Index) */0);
bs.writeByte(/* TextPacketType::Raw (Enum) */0);
bs.writeString(text);
bs.writeString(""); // xuid
bs.writeString(""); // platformId
bs.writeString(""); // filtered message
bs.createPacket(9).sendTo(player);
});
```
Loading