summaryrefslogtreecommitdiff
path: root/LUA_API.rst
diff options
context:
space:
mode:
Diffstat (limited to 'LUA_API.rst')
-rw-r--r--LUA_API.rst380
1 files changed, 373 insertions, 7 deletions
diff --git a/LUA_API.rst b/LUA_API.rst
index 2bb2c949..f532d221 100644
--- a/LUA_API.rst
+++ b/LUA_API.rst
@@ -488,7 +488,7 @@ Input & Output
lock. Using an explicit ``dfhack.with_suspend`` will prevent
this, forcing the function to block on input with lock held.
-* ``dfhack.interpreter([prompt[,env[,history_filename]]])``
+* ``dfhack.interpreter([prompt[,history_filename[,env]]])``
Starts an interactive lua interpreter, using the specified prompt
string, global environment and command-line history file.
@@ -550,6 +550,20 @@ Exception handling
The default value of the ``verbose`` argument of ``err:tostring()``.
+Miscellaneous
+-------------
+
+* ``dfhack.VERSION``
+
+ DFHack version string constant.
+
+* ``dfhack.curry(func,args...)``, or ``curry(func,args...)``
+
+ Returns a closure that invokes the function with args combined
+ both from the curry call and the closure call itself. I.e.
+ ``curry(func,a,b)(c,d)`` equals ``func(a,b,c,d)``.
+
+
Locking and finalization
------------------------
@@ -709,6 +723,10 @@ can be omitted.
Returns the dfhack directory path, i.e. ``".../df/hack/"``.
+* ``dfhack.getTickCount()``
+
+ Returns the tick count in ms, exactly as DF ui uses.
+
* ``dfhack.isWorldLoaded()``
Checks if the world is loaded.
@@ -724,15 +742,20 @@ can be omitted.
Gui module
----------
-* ``dfhack.gui.getCurViewscreen()``
+* ``dfhack.gui.getCurViewscreen([skip_dismissed])``
- Returns the viewscreen that is current in the core.
+ Returns the topmost viewscreen. If ``skip_dismissed`` is *true*,
+ ignores screens already marked to be removed.
* ``dfhack.gui.getFocusString(viewscreen)``
Returns a string representation of the current focus position
in the ui. The string has a "screen/foo/bar/baz..." format.
+* ``dfhack.gui.getCurFocus([skip_dismissed])``
+
+ Returns the focus string of the current viewscreen.
+
* ``dfhack.gui.getSelectedWorkshopJob([silent])``
When a job is selected in *'q'* mode, returns the job, else
@@ -754,15 +777,29 @@ Gui module
last case, the highlighted *contained item* is returned, not
the container itself.
+* ``dfhack.gui.getSelectedBuilding([silent])``
+
+ Returns the building selected via *'q'*, *'t'*, *'k'* or *'i'*.
+
* ``dfhack.gui.showAnnouncement(text,color[,is_bright])``
Adds a regular announcement with given text, color, and brightness.
The is_bright boolean actually seems to invert the brightness.
+* ``dfhack.gui.showZoomAnnouncement(type,pos,text,color[,is_bright])``
+
+ Like above, but also specifies a position you can zoom to from the announcement menu.
+
* ``dfhack.gui.showPopupAnnouncement(text,color[,is_bright])``
Pops up a titan-style modal announcement window.
+* ``dfhack.gui.showAutoAnnouncement(type,pos,text,color[,is_bright])``
+
+ Uses the type to look up options from announcements.txt, and calls the
+ above operations accordingly. If enabled, pauses and zooms to position.
+
+
Job module
----------
@@ -835,6 +872,26 @@ Units module
Returns the nemesis record of the unit if it has one, or *nil*.
+* ``dfhack.units.isHidingCurse(unit)``
+
+ Checks if the unit hides improved attributes from its curse.
+
+* ``dfhack.units.getPhysicalAttrValue(unit, attr_type)``
+* ``dfhack.units.getMentalAttrValue(unit, attr_type)``
+
+ Computes the effective attribute value, including curse effect.
+
+* ``dfhack.units.isCrazed(unit)``
+* ``dfhack.units.isOpposedToLife(unit)``
+* ``dfhack.units.hasExtravision(unit)``
+* ``dfhack.units.isBloodsucker(unit)``
+
+ Simple checks of caste attributes that can be modified by curses.
+
+* ``dfhack.units.getMiscTrait(unit, type[, create])``
+
+ Finds (or creates if requested) a misc trait object with the given id.
+
* ``dfhack.units.isDead(unit)``
The unit is completely dead and passive, or a ghost.
@@ -861,6 +918,14 @@ Units module
Returns the age of the unit in years as a floating-point value.
If ``true_age`` is true, ignores false identities.
+* ``dfhack.units.getEffectiveSkill(unit, skill)``
+
+ Computes the effective rating for the given skill, taking into account exhaustion, pain etc.
+
+* ``dfhack.units.computeMovementSpeed(unit)``
+
+ Computes number of frames * 100 it takes the unit to move in its current state of mind and body.
+
* ``dfhack.units.getNoblePositions(unit)``
Returns a list of tables describing noble position assignments, or *nil*.
@@ -875,6 +940,15 @@ Units module
Retrieves the profession name for the given race/caste using raws.
+* ``dfhack.units.getProfessionColor(unit[,ignore_noble])``
+
+ Retrieves the color associated with the profession, using noble assignments
+ or raws. The ``ignore_noble`` boolean disables the use of noble positions.
+
+* ``dfhack.units.getCasteProfessionColor(race,caste,prof_id)``
+
+ Retrieves the profession color for the given race/caste using raws.
+
Items module
------------
@@ -929,6 +1003,14 @@ Items module
Move the item to the unit inventory. Returns *false* if impossible.
+* ``dfhack.items.remove(item[, no_uncat])``
+
+ Removes the item, and marks it for garbage collection unless ``no_uncat`` is true.
+
+* ``dfhack.items.makeProjectile(item)``
+
+ Turns the item into a projectile, and returns the new object, or *nil* if impossible.
+
Maps module
-----------
@@ -945,10 +1027,18 @@ Maps module
Returns a map block object for given x,y,z in local block coordinates.
+* ``dfhack.maps.isValidTilePos(coords)``, or isValidTilePos(x,y,z)``
+
+ Checks if the given df::coord or x,y,z in local tile coordinates are valid.
+
* ``dfhack.maps.getTileBlock(coords)``, or ``getTileBlock(x,y,z)``
Returns a map block object for given df::coord or x,y,z in local tile coordinates.
+* ``dfhack.maps.ensureTileBlock(coords)``, or ``ensureTileBlock(x,y,z)``
+
+ Like ``getTileBlock``, but if the block is not allocated, try creating it.
+
* ``dfhack.maps.getRegionBiome(region_coord2d)``, or ``getRegionBiome(x,y)``
Returns the biome info struct for the given global map region.
@@ -957,6 +1047,11 @@ Maps module
Enables updates for liquid flow or temperature, unless already active.
+* ``dfhack.maps.spawnFlow(pos,type,mat_type,mat_index,dimension)``
+
+ Spawns a new flow (i.e. steam/mist/dust/etc) at the given pos, and with
+ the given parameters. Returns it, or *nil* if unsuccessful.
+
* ``dfhack.maps.getGlobalInitFeature(index)``
Returns the global feature object with the given index.
@@ -1027,6 +1122,11 @@ Burrows module
Buildings module
----------------
+* ``dfhack.buildings.setOwner(item,unit)``
+
+ Replaces the owner of the building. If unit is *nil*, removes ownership.
+ Returns *false* in case of error.
+
* ``dfhack.buildings.getSize(building)``
Returns *width, height, centerx, centery*.
@@ -1204,6 +1304,178 @@ Constructions module
Returns *true, was_only_planned* if removed; or *false* if none found.
+Screen API
+----------
+
+The screen module implements support for drawing to the tiled screen of the game.
+Note that drawing only has any effect when done from callbacks, so it can only
+be feasibly used in the core context.
+
+Basic painting functions:
+
+* ``dfhack.screen.getWindowSize()``
+
+ Returns *width, height* of the screen.
+
+* ``dfhack.screen.getMousePos()``
+
+ Returns *x,y* of the tile the mouse is over.
+
+* ``dfhack.screen.inGraphicsMode()``
+
+ Checks if [GRAPHICS:YES] was specified in init.
+
+* ``dfhack.screen.paintTile(pen,x,y[,char,tile])``
+
+ Paints a tile using given parameters. Pen is a table with following possible fields:
+
+ ``ch``
+ Provides the ordinary tile character, as either a 1-character string or a number.
+ Can be overridden with the ``char`` function parameter.
+ ``fg``
+ Foreground color for the ordinary tile. Defaults to COLOR_GREY (7).
+ ``bg``
+ Background color for the ordinary tile. Defaults to COLOR_BLACK (0).
+ ``bold``
+ Bright/bold text flag. If *nil*, computed based on (fg & 8); fg is masked to 3 bits.
+ Otherwise should be *true/false*.
+ ``tile``
+ Graphical tile id. Ignored unless [GRAPHICS:YES] was in init.txt.
+ ``tile_color = true``
+ Specifies that the tile should be shaded with *fg/bg*.
+ ``tile_fg, tile_bg``
+ If specified, overrides *tile_color* and supplies shading colors directly.
+
+ Returns *false* if coordinates out of bounds, or other error.
+
+* ``dfhack.screen.readTile(x,y)``
+
+ Retrieves the contents of the specified tile from the screen buffers.
+ Returns a pen, or *nil* if invalid or TrueType.
+
+* ``dfhack.screen.paintString(pen,x,y,text)``
+
+ Paints the string starting at *x,y*. Uses the string characters
+ in sequence to override the ``ch`` field of pen.
+
+ Returns *true* if painting at least one character succeeded.
+
+* ``dfhack.screen.fillRect(pen,x1,y1,x2,y2)``
+
+ Fills the rectangle specified by the coordinates with the given pen.
+ Returns *true* if painting at least one character succeeded.
+
+* ``dfhack.screen.findGraphicsTile(pagename,x,y)``
+
+ Finds a tile from a graphics set (i.e. the raws used for creatures),
+ if in graphics mode and loaded.
+
+ Returns: *tile, tile_grayscale*, or *nil* if not found.
+ The values can then be used for the *tile* field of *pen* structures.
+
+* ``dfhack.screen.clear()``
+
+ Fills the screen with blank background.
+
+* ``dfhack.screen.invalidate()``
+
+ Requests repaint of the screen by setting a flag. Unlike other
+ functions in this section, this may be used at any time.
+
+In order to actually be able to paint to the screen, it is necessary
+to create and register a viewscreen (basically a modal dialog) with
+the game.
+
+**NOTE**: As a matter of policy, in order to avoid user confusion, all
+interface screens added by dfhack should bear the "DFHack" signature.
+
+Screens are managed with the following functions:
+
+* ``dfhack.screen.show(screen[,below])``
+
+ Displays the given screen, possibly placing it below a different one.
+ The screen must not be already shown. Returns *true* if success.
+
+* ``dfhack.screen.dismiss(screen[,to_first])``
+
+ Marks the screen to be removed when the game enters its event loop.
+ If ``to_first`` is *true*, all screens up to the first one will be deleted.
+
+* ``dfhack.screen.isDismissed(screen)``
+
+ Checks if the screen is already marked for removal.
+
+Apart from a native viewscreen object, these functions accept a table
+as a screen. In this case, ``show`` creates a new native viewscreen
+that delegates all processing to methods stored in that table.
+
+**NOTE**: Lua-implemented screens are only supported in the core context.
+
+Supported callbacks and fields are:
+
+* ``screen._native``
+
+ Initialized by ``show`` with a reference to the backing viewscreen
+ object, and removed again when the object is deleted.
+
+* ``function screen:onShow()``
+
+ Called by ``dfhack.screen.show`` if successful.
+
+* ``function screen:onDismiss()``
+
+ Called by ``dfhack.screen.dismiss`` if successful.
+
+* ``function screen:onDestroy()``
+
+ Called from the destructor when the viewscreen is deleted.
+
+* ``function screen:onResize(w, h)``
+
+ Called before ``onRender`` or ``onIdle`` when the window size has changed.
+
+* ``function screen:onRender()``
+
+ Called when the viewscreen should paint itself. This is the only context
+ where the above painting functions work correctly.
+
+ If omitted, the screen is cleared; otherwise it should do that itself.
+ In order to make a see-through dialog, call ``self._native.parent:render()``.
+
+* ``function screen:onIdle()``
+
+ Called every frame when the screen is on top of the stack.
+
+* ``function screen:onHelp()``
+
+ Called when the help keybinding is activated (usually '?').
+
+* ``function screen:onInput(keys)``
+
+ Called when keyboard or mouse events are available.
+ If any keys are pressed, the keys argument is a table mapping them to *true*.
+ Note that this refers to logical keybingings computed from real keys via
+ options; if multiple interpretations exist, the table will contain multiple keys.
+
+ The table also may contain special keys:
+
+ ``_STRING``
+ Maps to an integer in range 0-255. Duplicates a separate "STRING_A???" code for convenience.
+
+ ``_MOUSE_L, _MOUSE_R``
+ If the left or right mouse button is pressed.
+
+ If this method is omitted, the screen is dismissed on receival of the ``LEAVESCREEN`` key.
+
+* ``function screen:onGetSelectedUnit()``
+* ``function screen:onGetSelectedItem()``
+* ``function screen:onGetSelectedJob()``
+* ``function screen:onGetSelectedBuilding()``
+
+ Implement these to provide a return value for the matching
+ ``dfhack.gui.getSelected...`` function.
+
+
Internal API
------------
@@ -1235,6 +1507,12 @@ and are only documented here for completeness:
Returns a sequence of tables describing virtual memory ranges of the process.
+* ``dfhack.internal.patchMemory(dest,src,count)``
+
+ Like memmove below, but works even if dest is read-only memory, e.g. code.
+ If destination overlaps a completely invalid memory region, or another error
+ occurs, returns false.
+
* ``dfhack.internal.memmove(dest,src,count)``
Wraps the standard memmove function. Accepts both numbers and refs as pointers.
@@ -1296,8 +1574,8 @@ Core context specific functions:
Event type
----------
-An event is just a lua table with a predefined metatable that
-contains a __call metamethod. When it is invoked, it loops
+An event is a native object transparently wrapping a lua table,
+and implementing a __call metamethod. When it is invoked, it loops
through the table with next and calls all contained values.
This is intended as an extensible way to add listeners.
@@ -1312,10 +1590,18 @@ Features:
* ``event[key] = function``
- Sets the function as one of the listeners.
+ Sets the function as one of the listeners. Assign *nil* to remove it.
**NOTE**: The ``df.NULL`` key is reserved for the use by
- the C++ owner of the event, and has some special semantics.
+ the C++ owner of the event; it is an error to try setting it.
+
+* ``#event``
+
+ Returns the number of non-nil listeners.
+
+* ``pairs(event)``
+
+ Iterates over all listeners in the table.
* ``event(args...)``
@@ -1545,6 +1831,86 @@ function:
argument specifies the indentation step size in spaces. For
the other arguments see the original documentation link above.
+class
+=====
+
+Implements a trivial single-inheritance class system.
+
+* ``Foo = defclass(Foo[, ParentClass])``
+
+ Defines or updates class Foo. The ``Foo = defclass(Foo)`` syntax
+ is needed so that when the module or script is reloaded, the
+ class identity will be preserved through the preservation of
+ global variable values.
+
+ The ``defclass`` function is defined as a stub in the global
+ namespace, and using it will auto-load the class module.
+
+* ``Class.super``
+
+ This class field is set by defclass to the parent class, and
+ allows a readable ``Class.super.method(self, ...)`` syntax for
+ calling superclass methods.
+
+* ``Class.ATTRS { foo = xxx, bar = yyy }``
+
+ Declares certain instance fields to be attributes, i.e. auto-initialized
+ from fields in the table used as the constructor argument. If omitted,
+ they are initialized with the default values specified in this declaration.
+
+ If the default value should be *nil*, use ``ATTRS { foo = DEFAULT_NIL }``.
+
+* ``new_obj = Class{ foo = arg, bar = arg, ... }``
+
+ Calling the class as a function creates and initializes a new instance.
+ Initialization happens in this order:
+
+ 1. An empty instance table is created, and its metatable set.
+ 2. The ``preinit`` method is called via ``invoke_before`` (see below)
+ with the table used as argument to the class. This method is intended
+ for validating and tweaking that argument table.
+ 3. Declared ATTRS are initialized from the argument table or their default values.
+ 4. The ``init`` method is called via ``invoke_after`` with the argument table.
+ This is the main constructor method.
+ 5. The ``postinit`` method is called via ``invoke_after`` with the argument table.
+ Place code that should be called after the object is fully constructed here.
+
+Predefined instance methods:
+
+* ``instance:assign{ foo = xxx }``
+
+ Assigns all values in the input table to the matching instance fields.
+
+* ``instance:callback(method_name, [args...])``
+
+ Returns a closure that invokes the specified method of the class,
+ properly passing in self, and optionally a number of initial arguments too.
+ The arguments given to the closure are appended to these.
+
+* ``instance:invoke_before(method_name, args...)``
+
+ Navigates the inheritance chain of the instance starting from the most specific
+ class, and invokes the specified method with the arguments if it is defined in
+ that specific class. Equivalent to the following definition in every class::
+
+ function Class:invoke_before(method, ...)
+ if rawget(Class, method) then
+ rawget(Class, method)(self, ...)
+ end
+ Class.super.invoke_before(method, ...)
+ end
+
+* ``instance:invoke_after(method_name, args...)``
+
+ Like invoke_before, only the method is called after the recursive call to super,
+ i.e. invocations happen in the parent to child order.
+
+ These two methods are inspired by the Common Lisp before and after methods, and
+ are intended for implementing similar protocols for certain things. The class
+ library itself uses them for constructors.
+
+To avoid confusion, these methods cannot be redefined.
+
=======
Plugins