add block.compose_state(...), block.decompose_state(...)

doc/en/scripting/builtins/libblock.md

@@ -14,6 +14,7 @@ block.material(blockid: int) -> str
 block.caption(blockid: int) -> str
 
 -- Returns integer ID by block position
+-- If the chunk at the specified coordinates is not loaded, returns -1.
 block.get(x: int, y: int, z: int) -> int
 
 -- Returns block state (rotation + additional information) as an integer.
@@ -31,6 +32,12 @@ block.place(x: int, y: int, z: int, id: int, states: int, [optional] playerid: i
 -- Breaks a block at the given coordinates on behalf of the player, triggering the on_broken event.
 -- playerid is optional
 block.destruct(x: int, y: int, z: int, playerid: int)
+
+-- Compose the complete state as an integer
+block.compose_state(rotation: int, segment: int, userbits: int) -> int
+
+-- Decompose the complete state into: rotation, segment, user bits
+block.decompose_state(state: int) -> int, int, int
 ```
 
 > [!WARNING]

doc/ru/scripting/builtins/libblock.md

@@ -17,7 +17,7 @@ block.caption(blockid: int) -> str
 -- Если чанк на указанных координатах не загружен, возвращает -1.
 block.get(x: int, y: int, z: int) -> int
 
--- Возвращает состояние (поворот + доп. информация) в виде целого числа
+-- Возвращает полное состояние (поворот + сегмент + доп. информация) в виде целого числа
 block.get_states(x: int, y: int, z: int) -> int
 
 -- Устанавливает блок с заданным числовым id и состоянием (0 - по-умолчанию) на заданных координатах.
@@ -31,6 +31,12 @@ block.place(x: int, y: int, z: int, id: int, states: int, [optional] playerid: i
 -- Ломает блок на заданных координатах от лица игрока, вызывая событие on_broken.
 -- playerid не является обязательным
 block.destruct(x: int, y: int, z: int, playerid: int)
+
+-- Собирает полное состояние в виде целого числа
+block.compose_state(rotation: int, segment: int, userbits: int) -> int
+
+-- Разбирает полное состояние на: вращение, сегмент, пользовательские биты
+block.decompose_state(state: int) -> int, int, int
 ```
 
 > [!WARNING]

src/logic/scripting/lua/libblock.cpp

@@ -380,6 +380,23 @@ static int l_raycast(lua::State* L) {
     return 0;
 }
 
+static int l_compose_state(lua::State* L) {
+    blockstate state {};
+    state.rotation = lua::tointeger(L, 1);
+    state.segment = lua::tointeger(L, 2);
+    state.userbits = lua::tointeger(L, 3);
+    return lua::pushinteger(L, blockstate2int(state));
+}
+
+static int l_decompose_state(lua::State* L) {
+    auto stateInt = static_cast<blockstate_t>(lua::tointeger(L, 1));
+    auto state = int2blockstate(stateInt);
+    lua::pushinteger(L, state.rotation);
+    lua::pushinteger(L, state.segment);
+    lua::pushinteger(L, state.userbits);
+    return 3;
+}
+
 const luaL_Reg blocklib [] = {
     {"index", lua::wrap<l_index>},
     {"name", lua::wrap<l_get_def>},
@@ -411,5 +428,7 @@ const luaL_Reg blocklib [] = {
     {"place", lua::wrap<l_place>},
     {"destruct", lua::wrap<l_destruct>},
     {"raycast", lua::wrap<l_raycast>},
+    {"compose_state", lua::wrap<l_compose_state>},
+    {"decompose_state", lua::wrap<l_decompose_state>},
     {NULL, NULL}
 };