docs: yet another day, yet another doc update. Also improved optional args for gear char/tile

Author: warmist

docs/dev/Lua API.rst

@@ -6574,7 +6574,7 @@ Functions
                     Each frame tile is table of with following optional members: ``ch``, ``fg``,
                     ``bg``, ``bold``, ``tile``, ``tile_overlay``, ``tile_signpost``, ``tile_item``.
                     First 4 are function same as ascii workshop definition. The latter 4 are graphics
-                    layers. ``tile_signpost `` is only valid in first row and it shows up above the workshop.
+                    layers. ``tile_signpost`` is only valid in first row and it shows up above the workshop.
 
   :frame_skip:     How many ticks to display one frame. If set to negative number, zero or skipped, frames
                    are synchronized with machine animation.
@@ -6588,8 +6588,9 @@ Functions
   :make_graphics_too:  replace same tiles in graphics mode with tiles from vanilla df mechanism
   :frame_length:      How many ticks to display one frame. If set to negative number, zero or skipped, frames
                       are synchronized with machine animation.
-  :gear_tiles:        Optional table with of 2 or 4 indexes. First two define ascii tiles and next two graphics tiles.
-                      This overrides default gear tiles.
+  :gear_tiles:        Optional table with ``ch``, ``ch_alt``, ``tile``, ``tile_alt``. First two are ascii
+                      gear tiles and are used to find tiles in workshop raw and animate them. Second two are
+                      used to animate graphical tiles.
 
 * ``setOnUpdate(workshop_type, interval, callback)``
 
@@ -6638,20 +6639,35 @@ Examples
 Simple mechanical workshop::
 
   local bhacks = require('plugins.building-hacks')
-  --work only powered, consume 15 power and one connection point at 0,0
-  bhacks.setMachineInfo("BONE_GRINDER",true,15,0,{{x=0,y=0}})
-  --set animation to switch between gear tiles at 0,0
-  bhacks.setAnimationInfo("BONE_GRINDER",{
-      {[0]={42,7,0,0}}, --first frame, 1 changed tile
-      {[0]={15,7,0,0}} -- second frame, same
-      }
-    )
+
+  --work only powered, consume 15 power and one connection point at 0, 0
+  bhacks.setMachineInfo("BONE_GRINDER", true, 15, 0, {{x=0, y=0}})
+
+  --load custom graphical tiles for use if graphics is enabled
+  local tile1=dfhack.screen.findGraphicsTile('DRAGON_ENGINE_TILES', 0, 0)
+  local tile2=dfhack.screen.findGraphicsTile('DRAGON_ENGINE_TILES', 1, 0)
+
+  local frames={}
+  --first frame - tile (1, 1) changed to character 42
+  ensure_key(frames, 1, 1)[1]={ch=42, fg=7, bg=0, bold=0, tile=tile1}
+  --second frame - tile (1,1) changed to character 15
+  ensure_key(frames, 2, 1)[1]={ch=15, fg=7, bg=0, bold=0, tile=tile2}
+
+  --set animation to switch between gear tiles at 1,1
+  bhacks.setAnimationInfo("BONE_GRINDER", frames)
 
 Or with auto_gears::
 
   local bhacks = require('plugins.building-hacks')
-  bhacks.setMachineInfoAuto("BONE_GRINDER",true,15)
-  bhacks.setAnimationInfoAuto("BONE_GRINDER",true)
+
+  --load custom graphical tiles for use if graphics is enabled
+  local tile1=dfhack.screen.findGraphicsTile('DRAGON_ENGINE_TILES', 0, 0)
+  local tile2=dfhack.screen.findGraphicsTile('DRAGON_ENGINE_TILES', 1, 0)
+
+  --work only powered, consume 15 power and find connection point from building raws
+  bhacks.setMachineInfoAuto("BONE_GRINDER", true, 15)
+  --set animation to switch between default ascii gears and specific graphic tiles loaded above
+  bhacks.setAnimationInfoAuto("BONE_GRINDER", true, -1, {tile=tile1, tile_alt=tile2})
 
 buildingplan
 ============

plugins/lua/building-hacks.lua

@@ -15,6 +15,10 @@ local _ENV = mkmodule('plugins.building-hacks')
 ]]
 
 _registeredStuff={}
+
+local CHAR_GEAR=42
+local CHAR_GEAR_ALT=15
+
 --cache graphics tiles for mechanical gears
 local graphics_cache
 function reload_graphics_cache(  )
@@ -71,7 +75,7 @@ end
 
 --locate gears on the workshop from the raws definition
 local function findGears( shop_def ,gear_tiles) --finds positions of all gears and inverted gears
-    gear_tiles=gear_tiles or {ch=42,ch_alt=15}
+    gear_tiles=gear_tiles or {ch=CHAR_GEAR,ch_alt=CHAR_GEAR_ALT}
     local w,h=shop_def.dim_x,shop_def.dim_y
     local stage=shop_def.build_stages
     local ret={}
@@ -96,28 +100,28 @@ local function lookup_color( shop_def,x,y,stage )
 end
 --adds frames for all gear icons and inverted gear icons
 local function processFramesAuto( shop_def ,gears,auto_graphics,gear_tiles)
-    gear_tiles=gear_tiles or {ch=42,ch_alt=15,tile=graphics_cache[1],tile_alt=graphics_cache[2]}
+    gear_tiles=gear_tiles or {ch=CHAR_GEAR,ch_alt=CHAR_GEAR_ALT,tile=graphics_cache[1],tile_alt=graphics_cache[2]}
     local frames={{},{}} --two frames only
     local stage=shop_def.build_stages
 
     for i,v in ipairs(gears) do
 
         local tile,tile_inv
         if v.inverted then
-            tile=gear_tiles.ch
-            tile_inv=gear_tiles.ch_alt
+            tile=gear_tiles.ch or CHAR_GEAR
+            tile_inv=gear_tiles.ch_alt or CHAR_GEAR_ALT
         else
-            tile=gear_tiles.ch_alt
-            tile_inv=gear_tiles.ch
+            tile=gear_tiles.ch_alt or CHAR_GEAR_ALT
+            tile_inv=gear_tiles.ch or CHAR_GEAR
         end
 
         table.insert(frames[1],{x=v.x,y=v.y,ch=tile,fg=lookup_color(shop_def,v.x,v.y,stage)})
         table.insert(frames[2],{x=v.x,y=v.y,ch=tile_inv,fg=lookup_color(shop_def,v.x,v.y,stage)})
 
         --insert default gear graphics if auto graphics is on
         if auto_graphics then
-            frames[1][#frames[1]].tile=gear_tiles.tile
-            frames[2][#frames[2]].tile=gear_tiles.tile_alt
+            frames[1][#frames[1]].tile=gear_tiles.tile or graphics_cache[1]
+            frames[2][#frames[2]].tile=gear_tiles.tile_alt or graphics_cache[2]
         end
     end