From 642a625586b9d40440bd3ce05d827f707ccce5ac Mon Sep 17 00:00:00 2001 From: Alexander Gavrilov Date: Sun, 13 May 2012 18:39:00 +0400 Subject: Support custom buildings in dfhack.buildings.getFiltersByType. Also document it and constructBuilding in Lua API docs. --- Lua API.html | 63 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) (limited to 'Lua API.html') diff --git a/Lua API.html b/Lua API.html index 3e023ebd..ed2e9f6a 100644 --- a/Lua API.html +++ b/Lua API.html @@ -1163,6 +1163,69 @@ Returns true if the building was destroyed and deallocated immediately.
More high-level functions are implemented in lua and can be loaded by require('dfhack.buildings'). See hack/lua/dfhack/buildings.lua.
+Among them are:
+dfhack.buildings.getFiltersByType(argtable,type,subtype,custom)
+Returns a sequence of lua structures, describing input item filters +suitable for the specified building type, or nil if unknown or invalid. +The returned sequence is suitable for use as the job_items argument +of constructWithFilters. +Uses tables defined in buildings.lua.
+Argtable members material (the default name), bucket, barrel, +chain, mechanism, screw, pipe, anvil, weapon are used to +augment the basic attributes with more detailed information if the +building has input items with the matching name (see the tables for naming details). +Note that it is impossible to override any properties this way, only supply those that +are not mentioned otherwise; one exception is that flags2.non_economic +is automatically cleared if an explicit material is specified.
+dfhack.buildings.constructBuilding{...}
+Creates a building in one call, using options contained +in the argument table. Returns the building, or nil, error.
+NOTE: Despite the name, unless the building is abstract, +the function creates it in an 'unconstructed' stage, with +a queued in-game job that will actually construct it. I.e. +the function replicates programmatically what can be done +through the construct building menu in the game ui, except +that it does less environment constraint checking.
+The following options can be used:
+pos = coordinates, or x = ..., y = ..., z = ...
+Mandatory. Specifies the left upper corner of the building.
+type = df.building_type.FOO, subtype = ..., custom = ...
+Mandatory. Specifies the type of the building. Obviously, subtype +and custom are only expected if the type requires them.
+fields = { ... }
+Initializes fields of the building object after creation with df.assign.
+width = ..., height = ..., direction = ...
+Sets size and orientation of the building. If it is +fixed-size, specified dimensions are ignored.
+full_rectangle = true
+For buildings like stockpiles or farm plots that can normally +accomodate individual tile exclusion, forces an error if any +tiles within the specified width*height are obstructed.
+items = { item, item ... }, or filters = { {...}, {...}... }
+Specifies explicit items or item filters to use in construction. +It is the job of the user to ensure they are correct for the building type.
+abstract = true
+Specifies that the building is abstract and does not require construction. +Required for stockpiles and civzones; an error otherwise.
+material = {...}, mechanism = {...}, ...
+If none of items, filter, or abstract is used, +the function uses getFiltersByType to compute the input +item filters, and passes the argument table through. If no filters +can be determined this way, constructBuilding throws an error.
+