From d4d4135096cb9d17f9057dbd2eeb44050d25ad75 Mon Sep 17 00:00:00 2001 From: expwnent Date: Thu, 24 Oct 2013 19:40:59 -0400 Subject: [PATCH] Update texts. Also added some documentation on event stuff. --- Lua API.html | 53 ++++++++++++++++++++++++++++++++++++++++++++-------- Lua API.rst | 8 ++++---- Readme.html | 10 +++++++++- 3 files changed, 58 insertions(+), 13 deletions(-) diff --git a/Lua API.html b/Lua API.html index fd524c416..4aecf48a0 100644 --- a/Lua API.html +++ b/Lua API.html @@ -421,14 +421,15 @@ ul.auto-toc {
  • sort
  • Eventful
    • -
  • Scripts @@ -3138,8 +3139,41 @@ tweaking (e.g. adding custom reactions)

    • +
    +

    Events from EventManager

    +

    These events are straight from EventManager module. Each of them first needs to be enabled. See functions for more info. If you register a listener before the game is loaded, be aware that no events will be triggered immediately after loading, so you might need to add another event listener for when the game first loads in some cases.

    +
      +

    1. onBuildingCreatedDestroyed(building_id)

      +

      Gets called when building is created or destroyed.

      +
      2. +

    2. onConstructionCreatedDestroyed(building_id)

      +

      Gets called when construction is created or destroyed.

      +
      3. +

    3. onJobInitiated(job)

      +

      Gets called when job is issued.

      +
      4. +

    4. onJobCompleted(job)

      +

      Gets called when job is finished. The job that is passed to this function is a copy. Requires a frequency of 0 in order to distinguish between workshop jobs that were cancelled by the user and workshop jobs that completed successfully.

      +
      5. +

    5. onUnitDeath(unit_id)

      +

      Gets called on unit death.

      +
      6. +

    6. onItemCreated(item_id)

      +

      Gets called when item is created (except due to traders, migrants, invaders and spider webs).

      +
      7. +

    7. onSyndrome(unit_id,syndrome_index)

      +

      Gets called when new syndrome appears on a unit.

      +
      8. +

    8. onInvasion(invasion_id)

      +

      Gets called when new invasion happens.

      +
      9. +

    9. onInventoryChange(unit_id,item_id,old_equip,new_equip)

      +

      Gets called when someone picks up an item, puts one down, or changes the way they are holding it. If an item is picked up, old_equip will be null. If an item is dropped, new_equip will be null. If an item is re-equipped in a new way, then neither will be null. You absolutely must NOT alter either old_equip or new_equip or you might break other plugins.

      +
      10. +
    +
    -

    Functions

    +

    Functions

    1. registerReaction(reaction_name,callback)

      Simplified way of using onReactionComplete; the callback is function (same params as event).

      @@ -3150,10 +3184,13 @@ tweaking (e.g. adding custom reactions)

    2. addReactionToShop(reaction_name,shop_name)

      Add a custom reaction to the building.

      3. +

    3. enableEvent(evType,frequency)

      +

      Enable event checking for EventManager events. For event types use eventType table. Note that different types of events require different frequencies to be effective. The frequency is how many ticks EventManager will wait before checking if that type of event has happened. If multiple scripts or plugins use the same event type, the smallest frequency is the one that is used, so you might get events triggered more often than the frequency you use here.

      +
    -

    Examples

    +

    Examples

    Spawn dragon breath on each item attempt to contaminate wound:

     b=require "plugins.eventful"
@@ -3190,7 +3227,7 @@ b.addReactionToShop("TAN_A_HIDE","LEATHERWORKS")
    -

    Scripts

    +

    Scripts

    Any files with the .lua extension placed into hack/scripts/* are automatically used by the DFHack core as commands. The matching command name consists of the name of the file sans @@ -3221,7 +3258,7 @@ The name argument should be the name stem, as

    Note that this function lets errors propagate to the caller.

    -

    Save init script

    +

    Save init script

    If a save directory contains a file called raw/init.lua, it is automatically loaded and executed every time the save is loaded. It can also define the following functions to be called by dfhack:

    diff --git a/Lua API.rst b/Lua API.rst index 480ff141a..1fd5147b5 100644 --- a/Lua API.rst +++ b/Lua API.rst @@ -3053,7 +3053,7 @@ List of events Events from EventManager ------------------------ -These events are straight from EventManager module. Each of them first needs to be enabled. See functions for more info. +These events are straight from EventManager module. Each of them first needs to be enabled. See functions for more info. If you register a listener before the game is loaded, be aware that no events will be triggered immediately after loading, so you might need to add another event listener for when the game first loads in some cases. 1. ``onBuildingCreatedDestroyed(building_id)`` @@ -3069,7 +3069,7 @@ These events are straight from EventManager module. Each of them first needs to 4. ``onJobCompleted(job)`` - Gets called when job is finished. The job that is passed to this function is a copy. + Gets called when job is finished. The job that is passed to this function is a copy. Requires a frequency of 0 in order to distinguish between workshop jobs that were cancelled by the user and workshop jobs that completed successfully. 5. ``onUnitDeath(unit_id)`` @@ -3089,7 +3089,7 @@ These events are straight from EventManager module. Each of them first needs to 9. ``onInventoryChange(unit_id,item_id,old_equip,new_equip)`` - Gets called when someone picks up an item, puts one down, or changes the way they are holding it. + Gets called when someone picks up an item, puts one down, or changes the way they are holding it. If an item is picked up, old_equip will be null. If an item is dropped, new_equip will be null. If an item is re-equipped in a new way, then neither will be null. You absolutely must NOT alter either old_equip or new_equip or you might break other plugins. Functions --------- @@ -3108,7 +3108,7 @@ Functions 4. ``enableEvent(evType,frequency)`` - Enable event checking for EventManager events. For event types use ``eventType`` table. + Enable event checking for EventManager events. For event types use ``eventType`` table. Note that different types of events require different frequencies to be effective. The frequency is how many ticks EventManager will wait before checking if that type of event has happened. If multiple scripts or plugins use the same event type, the smallest frequency is the one that is used, so you might get events triggered more often than the frequency you use here. Examples -------- diff --git a/Readme.html b/Readme.html index c795a6d4b..3786fe8e0 100644 --- a/Readme.html +++ b/Readme.html @@ -2993,7 +2993,15 @@ To skip a row in your design, use a single ;.<

    invasion-now civName trigger an invasion from the civilization with the id civName, starting in about ten ticks

    invasion-now civName start trigger an invasion from civName in a number of ticks between 10*start and 11*start-1 (inclusive)

    invasion-now civName start end trigger an invasion from civName in about 10*start ticks, and continue triggering invasions every ten ticks afterward until about 10*end ticks have passed

    -

    Probably fails if the start time of a triggered invasion is later than the start of the next year.

    +

    Probably fails if the start time of a triggered invasion is later than the start of the next year. +digmat +====== +Designates a tile for digging. Monitors the tile, and when it is dug out, add +surrounding discovered tiles of the same material for digging. Similar to 'digv', +but less cheaty. Works for stone layers, soil layers, veins, etc.

    +

    If the tile you call the script on already has a digging designation, reuse the +same designation for future digging (eg dig up/downstairs). When digging stairs, +also designate tiles on z-1 and z+1 when they are discovered.