feat: fix and enhance some things (#376)

* refactor: fix and enhance BinaryStream and Packet

* fix: fix command parameter result

* feat: add some apis

* feat(legacy api): add VaillanI18n internationalization api

* chore: update CHANGELOG.md

* feat: add error output for SQLiteSession::backup

* fix: fix the NbtCompound::setTag

---------

Co-authored-by: xianyubb <2149656630@qq.com>

Author: zimuya4153

CHANGELOG.md

@@ -7,6 +7,61 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.19.1] - 2026-07-05
+
+### Added
+
+- Added packet APIs:
+  `Packet::sendTo`, `Packet::sendToClients`, `Packet::sendToServer`,
+  `Packet` / `LXL_Packet` global aliases @zimuya4153
+- Added `BinaryStream` APIs:
+  `getReadPointer`, `setReadPointer`, `setData`, `writeBytes`, `readBytes`,
+  `writeUuid` @zimuya4153
+- Added server APIs:
+  `mc.getMotd`, `mc.getOnlinePlayerNum`, `mc.getMaxNumPlayers`,
+  `mc.getDimensionId`, `mc.getDimensionName` @zimuya4153
+- Added gameplay helpers:
+  `en.setCustomName`, `mc.summonMob`, `mc.loadMob`, `it.addCount`,
+  `it.removeCount`, `it.setCount`, `system.randomUuid` @zimuya4153
+- Added player state APIs:
+  `pl.isSwimming`, `pl.isCrawling` @zimuya4153
+- Added name access APIs:
+  `be.setCustomName`, `be.getCustomName`, `en.getCustomName`,
+  `it.getDisplayName` @zimuya4153
+- Added player data API:
+  `mc.getAllPlayerUuids([isOnlineMode])` for enumerating saved player UUIDs
+- Added database API:
+  `DBSession::backup(path)` for backing up SQL sessions
+- Added `VaillanI18n` API for modifying Minecraft vanilla language data
+  @zimuya4153 @xianyubb
+- Added `toSNBT([space[,format]])` to all NBT object types @zimuya4153
+
+### Changed
+
+- Improved `BinaryStream`:
+  `getData([release])` now returns `ByteBuffer`, does not clear by default, and
+  optionally releases data after reading; `createPacket(pktid[,raw])` now
+  supports raw packets; scalar `read*` APIs were added; several numeric
+  `write*` APIs now accept `String` for BigInt-friendly input
+  @zimuya4153
+- Improved file and item behavior:
+  `File.readFrom(path[,isBinary])` now supports binary reads;
+  `File.writeTo(path, text)` now accepts `ByteBuffer`;
+  `it.setLore([])` now clears custom lore instead of failing @zimuya4153
+- Improved player NBT APIs:
+  `mc.getPlayerNbt(uuid)` now returns `Null` when no saved data exists and can
+  read online players directly; `mc.setPlayerNbt(uuid, nbt[, forceCreate,
+  isOnlineMode])` now supports optional offline record creation; player NBT
+  APIs now validate UUID input more strictly @zimuya4153
+- Improved NBT serialization:
+  `NbtCompound::toSNBT([space[,format]])` now supports explicitly selecting
+  `SnbtFormat`; one-argument usage still defaults to `SnbtFormat::ForceQuote`
+  @zimuya4153
+
+### Fixed
+
+- Fixed `NbtCompound::setTag` @zimuya4153
+
 ## [0.19.0] - 2026-07-04
 
 ### Changed
@@ -1263,7 +1318,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 [#353]: https://github.com/LiteLDev/LegacyScriptEngine/issues/353
 [#358]: https://github.com/LiteLDev/LegacyScriptEngine/issues/358
 
-[Unreleased]: https://github.com/LiteLDev/LegacyScriptEngine/compare/v0.19.0...HEAD
+[Unreleased]: https://github.com/LiteLDev/LegacyScriptEngine/compare/v0.19.1...HEAD
+[0.19.1]: https://github.com/LiteLDev/LegacyScriptEngine/compare/v0.19.0...v0.19.1
 [0.19.0]: https://github.com/LiteLDev/LegacyScriptEngine/compare/v0.18.2...v0.19.0
 [0.18.2]: https://github.com/LiteLDev/LegacyScriptEngine/compare/v0.18.1...v0.18.2
 [0.18.1]: https://github.com/LiteLDev/LegacyScriptEngine/compare/v0.18.0...v0.18.1

docs/apis/DataAPI/DataBase.md

@@ -209,6 +209,22 @@ The `query` method returns:
 
 ---
 
+### Backup Database
+
+`session.backup(path)`
+
+* **Parameters:**
+* `path`: `String`
+  Destination path of the backup database file.
+
+
+* **Returns:** Whether the backup operation succeeded.
+* **Return Type:** `Boolean`
+
+> Currently this is implemented for SQLite sessions.
+
+---
+
 ### Close Database Session
 
 `session.close()`
@@ -432,4 +448,4 @@ mc.regPlayerCmd("getcoin", "Get a coin!", (pl, args)=>{
   dat[pl.realName]++;
   modified[pl.realName]++;
 });
-```
+```

docs/apis/DataAPI/DataBase.zh.md

@@ -203,6 +203,20 @@ SQL数据库适用于使用SQL语句处理大量的关系型数据。接口底
 
 
 
+### 备份数据库
+
+`session.backup(path)`
+
+- 参数：
+  - path : `String`
+    备份数据库文件的目标路径
+- 返回值：备份操作是否成功
+- 返回值类型：`Boolean`
+
+> 目前该接口只为 SQLite 会话实现。
+
+
+
 ### 关闭数据库会话
 
 `session.close()`

docs/apis/GameAPI/BlockEntity.md

@@ -70,4 +70,27 @@ For more usage of NBT objects, please refer to [NBT Interface Documentation](../
 - Return type: The block entity's block object.
 - Return value type: `Block`
 
+#### Set Block Entity Custom Name
+
+!!! warning
+This function is only available in 0.19.1 and later.
+
+`be.setCustomName(name)`
+
+- Parameters:
+  - name : `String`
+    New block entity custom name.
+- Return type: Whether setting was successful.
+- Return value type: `Boolean`
+
+#### Get Block Entity Custom Name
+
+!!! warning
+This function is only available in 0.19.1 and later.
+
+`be.getCustomName()`
+
+- Return type: The block entity's custom name.
+- Return value type: `String`
+
 

docs/apis/GameAPI/BlockEntity.zh.md

@@ -70,4 +70,27 @@
 - 返回值：方块实体对应的方块对象
 - 返回值类型：`Block`
 
+#### 设置方块实体自定义名称
+
+!!! warning
+    此函数仅在0.19.1及以后版本可用
+
+`be.setCustomName(name)`
+
+- 参数：
+  - name : `String`
+    新的方块实体自定义名称
+- 返回值：是否设置成功
+- 返回值类型：`Boolean`
+
+#### 获取方块实体自定义名称
+
+!!! warning
+    此函数仅在0.19.1及以后版本可用
+
+`be.getCustomName()`
+
+- 返回值：方块实体自定义名称
+- 返回值类型：`String`
+
 

docs/apis/GameAPI/Entity.md

@@ -73,6 +73,52 @@ Through this function, generate a new creature at the specified location and get
 > Therefore, if there is a need to operate an entity for a long time, please obtain the real-time entity object through
 > the above methods.
 
+#### Summon New Creature and Get Its Entity Object
+
+!!! warning
+This function is only available in 0.19.1 and later.
+
+Through this function, summon a new creature at the specified location and get its corresponding entity object.
+
+`mc.summonMob(name,pos[,event])`  
+`mc.summonMob(name,x,y,z,dimid[,event])`
+
+- Parameters:
+    - name : `String`  
+      The namespace name of the creature, such as `minecraft:creeper`
+    - pos : `IntPos `/ `FloatPos`  
+      A coordinate object of where the mob is spawned (or use x, y, z, dimid to determine where to spawn).
+    - event : `String`  
+      Optional initialization event name
+- Return value: The generated entity object.
+- Return value type:  `Entity`
+    - If the return value is `Null` it means that the generation failed
+
+> Note: Do not save an entity object **long-term**.
+> When the entity corresponding to the entity object is destroyed, the corresponding entity object will become invalid.
+> Therefore, if there is a need to operate an entity for a long time, please obtain the real-time entity object through
+> the above methods.
+
+#### Load Creature From NBT and Get Its Entity Object
+
+!!! warning
+This function is only available in 0.19.1 and later.
+
+Through this function, spawn a creature with the specified NBT data at the specified location and get its corresponding
+entity object.
+
+`mc.loadMob(nbt,pos)`  
+`mc.loadMob(nbt,x,y,z,dimid)`
+
+- Parameters:
+    - nbt : `NbtCompound`  
+      Creature NBT object
+    - pos : `IntPos `/ `FloatPos`  
+      A coordinate object of where the mob is spawned (or use x, y, z, dimid to determine where to spawn).
+- Return value: The generated entity object.
+- Return value type:  `Entity`
+    - If the return value is `Null` it means that the generation failed
+
 #### Clone A Creature and Get Its Entity Object
 
 Through this function, generate a new creature at the specified location and get its corresponding entity object.
@@ -393,6 +439,29 @@ Note that the damage dealt here is real damage and cannot be reduced by protecti
 - Return value: Whether the entity was scaled.
 - Return value type: `Boolean`
 
+#### Set Entity Custom Name
+
+!!! warning
+This function is only available in 0.19.1 and later.
+
+`en.setCustomName(name)`
+
+- Parameters:
+    - name : `String`
+      The entity's new custom name
+- Return value: Whether setting was successful
+- Return value type: `Boolean`
+
+#### Get Entity Custom Name
+
+!!! warning
+This function is only available in 0.19.1 and later.
+
+`en.getCustomName()`
+
+- Return value: The entity's custom name
+- Return value type: `String`
+
 #### Get Entity Distance To Pos
 
 `en.distanceTo(pos)`

docs/apis/GameAPI/Entity.zh.md

@@ -69,6 +69,49 @@
 > 注意：不要**长期保存**一个实体对象  
 > 当实体对象对应的实体被销毁时，对应的实体对象将同时释放。因此，如果有长期操作某个实体的需要，请通过上述途径获取实时的实体对象
 
+#### 召唤新生物并获取
+
+!!! warning
+    此函数仅在0.19.1及以后版本可用
+
+通过此函数，在指定的位置召唤一个新生物，并获取它对应的实体对象
+
+`mc.summonMob(name,pos[,event])`  
+`mc.summonMob(name,x,y,z,dimid[,event])`
+
+- 参数：
+    - name : `String`  
+      生物的命名空间名称，如 `minecraft:creeper`
+    - pos : `IntPos `/ `FloatPos`  
+      生成生物的位置的坐标对象（或者使用x, y, z, dimid来确定生成位置）
+    - event : `String`  
+      可选的初始化事件名称
+- 返回值：生成的实体对象
+- 返回值类型：`Entity`
+    - 如返回值为 `Null` 则表示生成失败
+
+> 注意：不要**长期保存**一个实体对象  
+> 当实体对象对应的实体被销毁时，对应的实体对象将同时释放。因此，如果有长期操作某个实体的需要，请通过上述途径获取实时的实体对象
+
+#### 通过NBT加载生物并获取
+
+!!! warning
+    此函数仅在0.19.1及以后版本可用
+
+通过此函数，使用指定的NBT数据在指定位置生成一个生物，并获取它对应的实体对象
+
+`mc.loadMob(nbt,pos)`  
+`mc.loadMob(nbt,x,y,z,dimid)`
+
+- 参数：
+    - nbt : `NbtCompound`  
+      生物的NBT对象
+    - pos : `IntPos `/ `FloatPos`  
+      生成生物的位置的坐标对象（或者使用x, y, z, dimid来确定生成位置）
+- 返回值：生成的实体对象
+- 返回值类型：`Entity`
+    - 如返回值为 `Null` 则表示生成失败
+
 #### 复制生物并获取
 
 通过此函数，在指定的位置复制另一个实体，并获取它对应的实体对象
@@ -383,6 +426,29 @@
 - 返回值: 实体是否成功地被缩放
 - 返回值类型: `Boolean`
 
+#### 设置实体自定义名称
+
+!!! warning
+    此函数仅在0.19.1及以后版本可用
+
+`en.setCustomName(name)`
+
+- 参数:
+    - name : `String`
+      实体新的自定义名称
+- 返回值: 是否设置成功
+- 返回值类型: `Boolean`
+
+#### 获取实体自定义名称
+
+!!! warning
+    此函数仅在0.19.1及以后版本可用
+
+`en.getCustomName()`
+
+- 返回值: 实体自定义名称
+- 返回值类型: `String`
+
 #### 获取实体到坐标的距离
 
 `en.distanceTo(pos)`