get_tile_fid correct for backwards compatibility and flexibility

- Allow to pass elevation using the free bits of the tileNum value to access elevations 1 and 2 (instead of defaulting to dude_elevation, which is not how it worked before)
- Access roof FID and raw data using mode flags in the top 4 bits

artifacts/scripting/functions.yml

@@ -823,7 +823,11 @@
 - name: Tiles and paths
   items:
   - name: get_tile_fid
-    detail: int get_tile_fid(int tile)
+    detail: int get_tile_fid(int tileData)
+    doc: |
+      - returns FID information about the square under the given tile at elevation 0
+      - pass elevation as 4-bit number in bits 25-28 to access other elevations
+      - pass result mode in bits 29-32: 0 - Ground FID, 1 - Roof FID, 2 - Raw data.
     opcode: 0x823a
   - name: tile_under_cursor
     detail: int tile_under_cursor
@@ -850,6 +854,14 @@
       - returns the tile number at the x, y position relative to the top-left corner of the screen
       - if the position is outside of the range of tiles, it will return -1
     macro: sfall.h
+  - name: get_tile_ground_fid
+    detail: int get_tile_ground_fid(int tileNum, int elevation)
+    doc: Returns FID of a ground tile at given tileNum and elevation.
+    macro: sfall.h
+  - name: get_tile_roof_fid
+    detail: int get_tile_roof_fid(int tileNum, int elevation)
+    doc: Returns FID of a roof tile at given tileNum and elevation. Note that FID of 1 is used when there is no actual roof.
+    macro: sfall.h
 
   - name: obj_blocking_line
     detail: ObjectPtr obj_blocking_line(ObjectPtr objFrom, int tileTo, int blockingType)

artifacts/scripting/headers/sfall.h

@@ -321,6 +321,9 @@
 #define get_npc_stat_max(stat)                                  sfall_func2("get_stat_max", stat, 1)
 #define get_npc_stat_min(stat)                                  sfall_func2("get_stat_min", stat, 1)
 #define get_sfall_arg_at(argNum)                                sfall_func1("get_sfall_arg_at", argNum)
+#define get_tile_fid_ext(tile, elev, mode)                      get_tile_fid(((mode bwand 0xF) * 0x10000000) bwor ((elev bwand 0xF) * 0x1000000) bwor (tile bwand 0xFFFFFF))
+#define get_tile_ground_fid(tile, elev)                         get_tile_fid_ext(tile, elev, 0)
+#define get_tile_roof_fid(tile, elev)                           get_tile_fid_ext(tile, elev, 1)
 #define get_terrain_name(x, y)                                  sfall_func2("get_terrain_name", x, y)
 #define get_text_width(text)                                    sfall_func1("get_text_width", text)
 #define has_fake_perk_npc(npc, perk)                            sfall_func2("has_fake_perk_npc", npc, perk)