Change get_liquids_at signature, update docs and example

docs/src/includes/_globals.md

@@ -1542,11 +1542,12 @@ Get the current layer that the liquid is spawn in. Related function [set_liquid_
 
 > Search script examples for [get_liquids_at](https://github.com/spelunky-fyi/overlunky/search?l=Lua&q=get_liquids_at)
 
-#### int get_liquids_at([MASK](#MASK) liquid_mask, float x, float y, [LAYER](#LAYER) layer)
+#### tuple<int, int> get_liquids_at(float x, float y, [LAYER](#LAYER) layer)
 
 Optimized function to check for the amount of liquids at a certain position, by accessing a 2d array of liquids by third of a tile. Try the `liquids.lua` example to know better how it works.
-Water blobs increase the number by 2 on the grid, while lava blobs increase it by 3. The maximum is usually 6
-Coarse water increase the number by 3, coarse and stagnant lava by 6. Combinations of both normal and coarse can make the number higher than 6
+Returns a pair of water and lava, in that order.
+Water blobs increase the number by 2 on the grid, while lava blobs increase it by 3. The maximum is usually 6.
+Coarse water increase the number by 3, coarse and stagnant lava by 6. Combinations of both normal and coarse can make the number higher than 6.
 
 ### get_local_prng
 

examples/liquids.lua

@@ -1,3 +1,7 @@
+meta.name = "Liquids by grid"
+meta.version = "1.0"
+meta.description = "Shows the amounts of liquids by grid, using the `get_liquids_at` function"
+
 register_option_bool("only_draw_at_mouse", "Testing: Draw only liquid num at mouse position", "", false)
 register_option_bool("draw_grid_lines", "Draw grid lines", "", true)
 register_option_bool("draw_text_shadow", "Draw text shadow", "", true)
@@ -39,8 +43,7 @@ end
 ---@param x number
 ---@param y number
 local function draw_liquids_at(ctx, x, y)
-	local water = get_liquids_at(MASK.WATER, x, y, LAYER.PLAYER)
-	local lava = get_liquids_at(MASK.LAVA, x, y, LAYER.PLAYER)
+	local water, lava = get_liquids_at(x, y, LAYER.PLAYER)
 	if water == 0 and lava == 0 then return end
 
 	local spacing <const> = 0.0135 / last_zoom

src/game_api/rpc.cpp

@@ -1355,36 +1355,22 @@ void add_entity_to_liquid_collision(uint32_t uid, bool add)
     }
 }
 
-uint8_t get_liquids_at(ENTITY_MASK liquid_mask, float x, float y, LAYER layer)
+std::pair<uint8_t, uint8_t> get_liquids_at(float x, float y, LAYER layer)
 {
     uint8_t actual_layer = enum_to_layer(layer);
     LiquidPhysics* liquid_physics = State::get().ptr()->liquid_physics;
-    if (actual_layer != get_liquid_layer())
-        return 0;
     // if (y > 125.5 || y < 0 || x > 85.5 || x < 0) // Original check by the game, can result is accesing the array out of bounds
     //     return 0;
-    if (y < 0 || x < 0)
-        return 0;
+    if (actual_layer != get_liquid_layer() || y < 0 || x < 0)
+        return {0, 0};
 
     uint32_t ix = static_cast<int>((x + 0.5) / 0.3333333);
     uint32_t iy = static_cast<int>((y + 0.5) / 0.3333333);
     if (iy >= (g_level_max_y * 3) || ix >= (g_level_max_x * 3))
-        return 0;
+        return {0, 0};
 
     auto& liquids_at = (*liquid_physics->liquids_by_third_of_tile)[iy][ix];
-    if (liquid_mask == ENTITY_MASK::ANY)
-    {
-        return liquids_at.water + liquids_at.lava;
-    }
-    else
-    {
-        uint8_t liquids_num = 0;
-        if (test_mask(liquid_mask, ENTITY_MASK::WATER))
-            liquids_num += liquids_at.water;
-        if (test_mask(liquid_mask, ENTITY_MASK::LAVA))
-            liquids_num += liquids_at.lava;
-        return liquids_num;
-    }
+    return {liquids_at.water, liquids_at.lava};
 }
 
 bool disable_floor_embeds(bool disable)

src/game_api/rpc.hpp

@@ -103,7 +103,7 @@ void set_adventure_seed(int64_t first, int64_t second);
 std::pair<int64_t, int64_t> get_adventure_seed(std::optional<bool> run_start);
 void update_liquid_collision_at(float x, float y, bool add, std::optional<LAYER> layer = std::nullopt);
 void add_entity_to_liquid_collision(uint32_t uid, bool add);
-uint8_t get_liquids_at(ENTITY_MASK liquid_mask, float x, float y, LAYER layer);
+std::pair<uint8_t, uint8_t> get_liquids_at(float x, float y, LAYER layer);
 bool disable_floor_embeds(bool disable);
 void set_cursepot_ghost_enabled(bool enable);
 void game_log(std::string message);

src/game_api/script/lua_vm.cpp

@@ -1928,8 +1928,9 @@ end
     lua["update_liquid_collision_at"] = update_liquid_collision_at;
 
     /// Optimized function to check for the amount of liquids at a certain position, by accessing a 2d array of liquids by third of a tile. Try the `liquids.lua` example to know better how it works.
-    /// Water blobs increase the number by 2 on the grid, while lava blobs increase it by 3. The maximum is usually 6
-    /// Coarse water increase the number by 3, coarse and stagnant lava by 6. Combinations of both normal and coarse can make the number higher than 6
+    /// Returns a pair of water and lava, in that order.
+    /// Water blobs increase the number by 2 on the grid, while lava blobs increase it by 3. The maximum is usually 6.
+    /// Coarse water increase the number by 3, coarse and stagnant lava by 6. Combinations of both normal and coarse can make the number higher than 6.
     lua["get_liquids_at"] = get_liquids_at;
 
     /// Disable all crust item spawns, returns whether they were already disabled before the call