Add graphics support for building-hacks

docs/dev/Lua API.rst

@@ -6520,87 +6520,154 @@ The names of the functions are also available as the keys of the
 building-hacks
 ==============
 
-This plugin overwrites some methods in workshop df class so that mechanical workshops are
-possible. Although plugin export a function it's recommended to use lua decorated function.
+This plugin extends DF workshops to support custom powered buildings.
+
+.. note::
+    When using numeric ids for workshops be aware that those id can change between worlds,
+    depending on what other custom types exist in the raws for that world.
 
 .. contents::
   :local:
 
 Functions
 ---------
 
-``registerBuilding(table)`` where table must contain name, as a workshop raw name,
-the rest are optional:
-
-    :name:
-        custom workshop id e.g., ``SOAPMAKER``
-
-        .. note:: this is the only mandatory field.
-
-    :fix_impassible:
-        if true make impassable tiles impassable to liquids too
-    :consume:
-        how much machine power is needed to work.
-        Disables reactions if not supplied enough and ``needs_power==1``
-    :produce:
-        how much machine power is produced.
-    :needs_power:
-        if produced in network < consumed stop working, default true
-    :gears:
-        a table or ``{x=?,y=?}`` of connection points for machines.
-    :action:
-        a table of number (how much ticks to skip) and a function which
-        gets called on shop update
-    :animate:
-        a table of frames which can be a table of:
-
-        a. tables of 4 numbers ``{tile,fore,back,bright}`` OR
-        b. empty table (tile not modified) OR
-        c. ``{x=<number> y=<number> + 4 numbers like in first case}``,
-           this generates full frame useful for animations that change little (1-2 tiles)
-
-    :canBeRoomSubset:
-        a flag if this building can be counted in room. 1 means it can,
-        0 means it can't and -1 default building behaviour
-    :auto_gears:
-        a flag that automatically fills up gears and animations.
-        It looks over the building definition for gear icons and maps them.
-
-    Animate table also might contain:
-
-    :frameLength:
-        how many ticks does one frame take OR
-    :isMechanical:
-        a bool that says to try to match to mechanical system (i.e., how gears are turning)
-
-``getPower(building)`` returns two number - produced and consumed power if building can be
-modified and returns nothing otherwise
-
-``setPower(building,produced,consumed)`` sets current power production and
-consumption for a building.
+* ``setOwnableBuilding(workshop_type)``
+
+  Set workshop to be included in zones (such as a bedroom or tavern).
+
+  :workshop_type:   custom workshop string id, e.g. ``SOAPMAKER`` or numeric id
+
+* ``fixImpassible(workshop_type)``
+
+  Set workshop non walkable tiles to also block liquids (i.e. water and magma).
+
+  :workshop_type:   custom workshop string id, e.g. ``SOAPMAKER`` or numeric id
+
+* ``setMachineInfo(workshop_type, needs_power, power_consumed, power_produced, connection_points)``
+
+  Setup and enable machine-like functionality for the workshop. All workshops of this type will have
+  this as their default power consumption/production. Note: due to implementation limitations,
+  workshops only connect to other machines if the other machines are planned after than this one.
+
+  :workshop_type:       custom workshop string id e.g. ``SOAPMAKER`` or numeric id
+  :needs_power:         true if the workshop should only be usable if it has sufficient power
+  :power_consumed:      buildings of this type consume this amount of power by default
+  :power_produced:      buildings of this type output this amount of power by default
+  :connection_points:   a table of ``{x=?,y=?}`` zero-based coordinates that can connect to other machines
+
+* ``setMachineInfoAuto(workshop_type, needs_power, power_consumed, power_produced, [gear_tiles])``
+
+  Same as ``setMachineInfo`` but fills out the ``connection_points`` table based on the
+  building definition in the raws. It places connection points on tiles which have the gear
+  tile. ``gear_tiles`` is an optional array of two tiles that are counted as gears in the
+  workshop ascii tile raws. The default gear tiles are ``42`` and ``15``.
+
+* ``setAnimationInfo(workshop_type, frames, frame_skip)``
+
+  Animate workshop by replacing displayed tiles (or graphical tiles). There are two ways this works:
+  if ``frame_skip>0`` then it shows each frame for ``frame_skip`` of frames or if ``frame_skip<=0``
+  Frames are synchronized with the machines this building is connected to.
+
+  :workshop_type:   custom workshop string id, e.g. ``SOAPMAKER`` or numeric id
+  :frames:          table of frames. Each frame is array of rows of tiles with ids from ``1`` to ``31``.
+                    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.
+
+  :frame_skip:     How many ticks to display one frame. If set to negative number, zero or skipped, frames
+                   are synchronized with machine animation.
+
+* ``setAnimationInfoAuto(workshop_type, make_graphics_too[, frame_length][, gear_tiles])``
+
+  Animate workshop as with function above but generate frames automatically. This works by finding
+  tiles which have gears and animating them with alternating gear tiles.
+
+  :workshop_type:     custom workshop string id, e.g. ``SOAPMAKER`` or numeric id
+  :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 ``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)``
+
+  Register callback to be called every ``interval`` ticks for each building of this
+  type. This can be very expensive if the interval is low and/or there are many
+  workshops of this type. Keep these callbacks light!
+
+  :workshop_type:   custom workshop string id, e.g. ``SOAPMAKER`` or numeric id
+  :interval:        how many ticks to skip between event triggers
+  :callback:        function to call. Function signature is ``func(workshop)`` where ``workshop`` is of type
+                    ``df.building_workshopst``
+
+* ``getPower(building)``
+
+  If this building is of a type registered with building-hacks, returns values for
+  consumed and produced power. Otherwise, returns ``nil``.
+
+  :building:   specific workshop that produces or consumes power
+
+* ``setPower(building, power_consumed, power_produced)``
+
+  Dynamically sets current power production and consumption for a specific workshop
+  (which must be of a type registered with building-hacks).
+
+  :building:   specific workshop that produces or consumes power
+  :power_consumed:   set building to consume this amount of power
+  :power_produced:   output this amount of power
+
+
+Events
+------
+
+This module exports two events. However only one is documented here and is intended to be used directly. To use
+``onUpdateAction`` instead call ``setOnUpdate`` function.
+
+* ``onSetTriggerState(workshop, state)``
+
+  Notify when building is triggered from linked lever or trap.
+
+  :workshop:   object of type ``df.building_workshopst`` that is triggered.
+  :state:   integer value of new state.
 
 Examples
 --------
 
 Simple mechanical workshop::
 
-  require('plugins.building-hacks').registerBuilding{name="BONE_GRINDER",
-    consume=15,
-    gears={x=0,y=0}, --connection point
-    animate={
-      isMechanical=true, --animate the same conn. point as vanilla gear
-      frames={
-      {{x=0,y=0,42,7,0,0}}, --first frame, 1 changed tile
-      {{x=0,y=0,15,7,0,0}} -- second frame, same
-      }
-    }
+  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}})
+
+  --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::
 
-  require('plugins.building-hacks').registerBuilding{name="BONE_GRINDER",
-    consume=15,
-    auto_gears=true
-    }
+  local bhacks = require('plugins.building-hacks')
+
+  --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
 ============

docs/plugins/building-hacks.rst

@@ -3,7 +3,7 @@ building-hacks
 
 .. dfhack-tool::
     :summary: Provides a Lua API for creating powered workshops.
-    :tags: unavailable
+    :tags: fort gameplay buildings
     :no-command:
 
 See `building-hacks-api` for more details.

plugins/CMakeLists.txt

@@ -78,7 +78,7 @@ if(BUILD_SUPPORTED)
     dfhack_plugin(autoslab autoslab.cpp)
     dfhack_plugin(blueprint blueprint.cpp LINK_LIBRARIES lua)
     dfhack_plugin(burrow burrow.cpp LINK_LIBRARIES lua)
-    #dfhack_plugin(building-hacks building-hacks.cpp LINK_LIBRARIES lua)
+    dfhack_plugin(building-hacks building-hacks.cpp LINK_LIBRARIES lua)
     add_subdirectory(buildingplan)
     dfhack_plugin(changeitem changeitem.cpp)
     dfhack_plugin(changelayer changelayer.cpp)