Print

Please login or register.
1 Hour 1 Day 1 Week 1 Month Forever
Login with username, password and session length

[Roses]

https://github.com/Pheosics/roses_collection
Use the master branch for the most recent stable version, and the devel branch for the most recent developments

UPDATE 07/06/2021
Fixed the {ATTRIBUTE} and {SKILL} shortcuts for the enhanced items. Now the attributes/skills are correctly increased/decreased when the item is equipped/unequipped

What is it
This is a collection of scripts, systems, and utilities that can be used with DFHack to modify the DF experience. The two main folders are Scripts (which include scripts and systems) and Utilities. All Utilities are built with Python 3+ and are run outside of the game. The scripts and systems are lua files that are run through DFHack. Scripts are run just like any other DFHack script and can be called from the command line or through any other method used to call the base DFHack scripts. Each script contains a help message which can be accessed by using script-name -help. The systems are called automatically behind the scenes and gather information through the raws (or in the case where there are no corresponding raws, such as the Class System, it uses a fake raw file).

Design philosophy
As many of you know, I have been around on this forum for awhile (over 11 years) and have created many scripts. Unfortunately they often became unusably complex as I added more and more to each script while still trying to maintain each scripts individuality. It eventually got to the point where even I had trouble running my own scripts and so I decided that a fresh start was needed. Instead of trying to make each script a stand alone download I have created a set of functions which act as the powerhouse behind the whole thing. These functions are made available through custom classes where appropriate, and through simple calls otherwise. Since each function serves a specific purpose they are relatively small and their use is shared across many different scripts. Additionally they can be called by other modders scripts if desired. Each script included in the collection (except for the intialization script) is also available to be called as a module through dfhack.reqscript, providing a simpler interface to the functions.

In addition to the scripts and their functions, there are the systems. Systems are a somewhat unique method through which a modder can change the way the game works, without worrying about writing their own scripts or getting the DFHack syntax correct. These also take advantage of the functions, but operate behind the scenes by reading the raw/objects files. Some of what the systems do can already be done with the existing modding tools (e.q. you can put "modtools/outside-only -building SCREW_PRESS -type OUTSIDE_ONLY" in the onLoad init file or you can put {OUTSIDE_ONLY} under the SCREW_PRESS in the building_custom.txt raw file), but other uses are not currently found in other scripts. The advantage to this method of scripting is that it allows modders who want to interface only with the raws the ability to use DFHack still.

How to use it

• Copy the Scripts/raw/scripts folder into your DF raw folder (hopefully there are no conflicts with any other scripts you have installed there)
• Copy the Scripts/raw/systems folder into your DF raw folder (directly into the raw folder, not the raw/scripts folder)
• Put core/initialize in your onLoad init file. If you want more verbose output you can use -v repeatedly (up to -vvvvv)
• All available systems should now be working, and all scripts should now be callable through any other methods you want

Update history
UPDATE 10/13/2020
Added Reactions to the Enhanced System. More detail is on the third post

UPDATE 04/06/2020
Massive revamp of all scripts, functions, and systems. See next two posts for included scripts and systems. Utilities are not currently up to date and should not be used. More information coming soon.

[Roses]

Current Scripts

unit Scripts

Spoiler: unit/attack (click to show/hide)

unit/attack
===========
Purpose::
    Create a custom attack using either supplied or calculated values

Uses::
   functions/unit
   functions/item
   functions/math

Arguments::
    -defender <UNIT_ID>
        Unit ID of defending unit
    -attacker <UNIT_ID>
        Unit ID of attacking unit
    -target <BP_CATEGORY>
        Body part category to target for attack
        If absent it will select a random body part weighted by size
    -weapon
        If present it will use the attacker unit's equipped weapon
        If absent it will assume a body part attack
    -attack <ATTACK_TOKEN>
        Attack token (e.g. PUNCH) of attack to use
        If absent it will select a random attack
    -velocity <#>
        Velocity to use for attack
        If absent it will calculate the velocity based on various factors
    -hitchance <#>
        Chance for attack to hitchance
        DEFAULT VALUE: 100
    -delay <#>
        Delay time until attack executes
        DEFAULT VALUE: 1
    -number <#>
        Number of attacks to executes
        DEFAULT VALUE: 1
           
Examples::
   * Add a random body part attack to the attacker targeting a random body part of the defender
      unit/attack -attacker \\UNIT_ID -defender \\UNIT_ID
   * Add a random weapon attack to the attacker targeting the defenders head
      unit/attack -attacker \\UNIT_ID -defender \\UNIT_ID -target HEAD -weapon -velocity 1000
   * Add 100 punch attacks to attacker target defenders upper body
      unit/attack -attacker \\UNIT_ID -defender \\UNIT_ID -target UPPERBODY -attack PUNCH -number 100

Spoiler: unit/butcher (click to show/hide)

unit/butcher
============
Purpose::
    Butcher a unit

Uses::
   NONE

Arguments::
    -unit <UNIT_ID>
        Unit id to check for butchering
        Will check for a given corpse from that unit first
    -corpse <ITEM_ID>
        Item id to check for butcher
    -location [ <x> <y> <z> ]
        Location to check for butchering
    -kill
        If present will kill unit to be butchered if still alive
   
Examples::
   * Kill and butcher a currently living unit
      unit/butcher -unit \\UNIT_ID -kill
   * Butcher a corpse item
      unit/butcher -corpse \\ITEM_ID
   * Butcher any corpses at the target location
      unit/butcher -location [ \\LOCATION ]

Spoiler: unit/change-action (click to show/hide)

unit/change-action
==================
Purpose::
    Changes the information for a given action
   NOTE: Only tested with movement and attack actions at this point

Uses::
   functions/unit

Arguments::
    -unit <UNIT_ID>
    -action <ActionType>
        The type of action to modify
        Valid Values:
            All
            Move
            Attack
    -data [ <DATA_KEY> <DATA_VALUE> ... ]
        sets the cooresponding data key to the data value for each action
   -clear
      if present, removes the action(s)

Examples::
   * Set a timer of 200 for all current actions
      unit/change-action -unit \\UNIT_ID -action All -data [ timer 200 ]
   
   * Set the velocity of any attack actions
      unit/change-action -unit \\UNIT_ID -action Attack -data [ velocity 500 ]
      
   * Remove all movement actions
      unit/change-action -unit \\UNIT_ID -action Move -clear

Spoiler: unit/change-attribute (click to show/hide)

unit/change-attribute
=====================
Purpose::
    Change the attriubute(s) of a unit

Uses::
   functions/unit

Arguments::
    -unit <UNIT_ID>
        id of unit to change attributes of
    -attribute [ <ATTRIBUTE_TOKEN> <CHANGE> <ATTRIBUTE_TOKEN> <CHANGE> ]
        Attribute token(s) of the attribute(s) to be changed
    -dur <#ticks>
        Length of time in in-game ticks for the change to last

Examples::
   * Add 100 to the units strength base value
      unit/change-attribute -unit \\UNIT_ID -attribute [ STRENGTH +100 ]
   * Change toughness and endurance to 10% and willpower to 50% of base value for 3600 ticks
      unit/change-attribute -unit \\UNIT_ID -attribute [ ENDURANCE /10 TOUGHNESS /10 WILLPOWER /2 ] -dur 3600
   * Set units willpower to 5000 for 1000 ticks
      unit/change-attribute -unit \\UNIT_ID -attribute [ WILLPOWER 5000 ] -dur 1000

Spoiler: unit/change-body (click to show/hide)

unit/change-body
================
Purpose::
    Changes the entire body or individual body parts of a given unit

Uses::
   functions/unit

Arguments::
    -unit <UNIT_ID>
        id of unit to target for change
    -bodyPart <PART_TYPE:PART_SUBTYPE> or [ <PART_TYPE:PART_SUBTYPE> <PART_TYPE:PART_SUBTYPE> ...]
      Part subtypes are based on part type decisions
        Valid PART_TYPEs:
         All      - targets whole body (all parts)
         Category - finds target based on body part CATEGORY
         Token    - finds target based on body part TOKEN
         Flag     - finds target based on body part FLAG
    -temperature <CHANGE>
        If present will change the temperature of the body part(s)
    -status [ <STATUS> <BOOLEAN> <STATUS> <BOOLEAN> ... ]
        If present will change the status of the body part(s)
        Valid Values:
            Fire - Sets the body part on fire
    -size [ <SIZE_TYPE> <CHANGE> <SIZE_TYPE> <CHANGE> ]
        Changes the dimensions of given units size
        Changing sizes of individual body parts is not currently possible
        Valid SIZE_TYPEs:
            All
            Length
            Area
            Size
    -dur <#ticks>
        Length of time in in-game ticks for change to last
        If absent change is permanent, except for temperatures which naturally stabalize

Examples::
   * Set the units hands and feet on fire for 1000 ticks
      unit/change-body -unit \\UNIT_ID -bodyPart [ FLAG:GRASP FLAG:STANCE ] -status [ on_fire true ] -dur 1000
   * Set the units lower legs to a temperature of 9000 Urists (temperature changes are automatically time limited)
      unit/change-body -unit \\UNIT_ID -bodyPart CATEGORY:LEG_LOWER -temperature 9000
   * Double the units size
      unit/change-body -unit \\UNIT_ID -size [ All x2 ]

Spoiler: unit/change-personality (click to show/hide)

unit/change-personality
=====================
Purpose::
    Change the traits, dreams, values, and emotions of a unit

Uses::
   functions/unit

Arguments::
    -unit #ID
        id of unit to change traits of
    -trait [ <TRAIT_TOKEN> <CHANGE> <TRAIT_TOKEN> <CHANGE> ... ]
        Trait token(s) of the trait(s) to be changed
    -dur #ticks
        Length of time in in=game ticks for the change to last

Examples::
   * Increase units ELOQUENCY trait by 20
      unit/trait-change -unit \\UNIT_ID -trait [ ELOQUENCY +20 ]

Spoiler: unit/change-skill (click to show/hide)

unit/change-skill
=================
Purpose::
    Change the skill(s) of a unit

Uses::
   functions/unit

Arguments::
    -unit <UNIT_ID>
        id of unit to change attributes of
    -skill [ <SKILL_TOKEN> <CHANGE> <SKILL_TOKEN <CHANGE> ... ]
        Skill token(s) of the skill(s) to be changed
    -type <ChangeType>
        Valid Values:
            Experience - changes a skills experience
            Level      - changes a skills level (DEFAULT)
    -add
        If present and unit doesn't have the skill, will add the skill
    -dur <#ticks>
        Length of time in in-game ticks for the change to last

Examples::
   * Increase units mining skill by 1 level
      unit/change-skill -unit \\UNIT_ID -skill [ MINING +1 ]
   * Half units engraving and masonry skills level for 3600 ticks
      unit/change-skill -unit \\UNIT_ID -skill [ ENGRAVING /2 MASONRY /2 ] -dur 3600
   * Set units dodging skill level to 0 for 1000 ticks
      unit/change-skill -unit \\UNIT_ID -skill [ DODGING 0 ] -dur 1000
   * Increase units mining skill experience by 100
      unit/change-skill -unit \\UNIT_ID -type Experience -skill [ MINING +100 ]

Spoiler: unit/propel (click to show/hide)

unit/propel
===========
Purpose::
    Turns a unit into a projectile with a given velocity

Uses::
   functions/unit

Arguments::
    -unit <UNIT_ID>
        ID of the unit to turn into a projectile
    -source <UNIT_ID> or [ <x> <y> <z> ]
        Location to use when using -mode Relative
    -velocity [ <vx> <vy> <vz> ]
        Velocity in x,y,z
    -mode <PROPEL_MODE>
        Method for calculation actual projectile velocity
        Valid Types:
            Fixed
            Random
            Relative

Examples::
   * Propel a unit upwards with a vz of 100
      unit/propel -unit \\UNIT_ID -velocity [ 0 0 100 ] -mode Fixed
   * Propel a unit with a random vx and vy between -50 and 50
      unit/propel -unit \\UNIT_ID -velocity [ 50 50 0 ] -mode Random
   * Propel a unit with vx, vy, and vz magnitude of 10 and sign relative to a source unit
      unit/propel -unit \\UNIT_ID -source \\UNIT_ID -velocity [ 10 10 10 ] -mode Relative
   * Propel a unit with vx, vy, and vz magnitude of 10 and sign relative to a source location
      unit/propel -unit \\UNIT_ID -source [ \\LOCATION ] -velocity [ 10 10 10 ] -mode Relative

item Scripts

Spoiler: item/change-material (click to show/hide)

item/change-material
====================
Purpose::
    Change the material of a given item or equipped item(s)

Arguments::
    -item <ITEM_ID>
        id of item to change
    -material <MATERIAL_TYPE:MATERIAL_SUBTYPE>
        Material to change item into
    -unit <UNIT_ID>
        id of unit to change if using -equipment
    -equipment <ITEM_TYPE>
        Type of equipment to check for
        Valid Types:
            ALL
            WEAPON
            ARMOR
            HELM
            SHOES
            SHIELD
            GLOVES
            PANTS
            AMMO
    -dur <#ticks>
        Length of time for change to last

Examples::
   * Change specific item's material to diamond for 3600 ticks
      item/change-material -item \\ITEM_ID -material INORGANIC:DIAMOND -dur 3600
   * Change a units weapon(s) to slade
      item/change-material -unit \\UNIT_ID -equipment WEAPON -mat INORGANIC:SLADE

Spoiler: item/change-quality (click to show/hide)

item/change-quality
====================
Purpose::
    Change the quality of a given item or equipped item(s)

Arguments::
    -item <ITEM_ID>
        id of item to change
    -quality <#>
        Quality to set item to
    -upgrade
        If present will increase quality by 1
    -downgrade
        If present will decrease quality by 1
    -unit <UNIT_ID>
        id of unit to change if using -equipment
    -equipment <ITEM_TYPE>
        Type of equipment to check for
        Valid Types:
            ALL
            WEAPON
            ARMOR
            HELM
            SHOES
            SHIELD
            GLOVES
            PANTS
            AMMO
    -dur <#ticks>
        Length of time for change to last

Examples::
   * Upgrade units equipment by 1 quality level for 3600 ticks
      item/change-quality -unit \\UNIT_ID -equipment ALL -upgrade -dur 3600
   * Set items quality to 4
      item/change-quality -item \\ITEM_ID -quality 4

Spoiler: item/change-subtype (click to show/hide)

item/change-subtype
====================
Purpose::
    Change the subtype of a given item or equipped item(s)
 
Arguments::
    -item #ID
        id of item to change
    -subtype ITEM_SUBTYPE
        Subtype to change item into
    -unit #ID
        id of unit to change if using -equipment
    -equipment ITEM_TYPE
        Type of equipment to check for
        Valid Types:
            ALL
            WEAPON
            ARMOR
            HELM
            SHOES
            SHIELD
            GLOVES
            PANTS
            AMMO
    -dur #ticks
        Length of time for change to last

Examples::
   * Change specific item's subtype for 3600 ticks
      item/change-subtype -item \\ITEM_ID -subtype ITEM_WEAPON_SWORD_SHORT -dur 3600
   * Change a units equipped ammo
      item/change-subtype -unit \\UNIT_ID -equipment AMMO -subtype ITEM_AMMO_BOLT_BROKEN

Spoiler: item/create (click to show/hide)

item/create
===========
Purpose::
    Creates an item and its cooresponding item table for tracking

Arguments::
    -creator #ID
        id of creator unit, set to 0 if not present
    -item ITEM_TYPE:ITEM_SUBTYPE
        Item to be created
    -material MATERIAL_TYPE:MATERIAL_SUBTYPE
        Material to make item out of
    -quality #(0-7)
        Quality to create the item at
    -dur #ticks
        Length of time for item to exist
    -matchingGloves
        If present it will create two gloves with correct handedness
    -matchingShoes
        If present it will create two shoes

Examples::
    item/create -item WEAPON:ITEM_WEAPON_SWORD_SHORT -material INORGANIC:SUPER_INORGANIC -quality 7 -dur 3600

Spoiler: item/destroy (click to show/hide)

item/destroy
===========
Purpose::

Function Calls::
     
Arguments::
   -item
      Item to be destroyed

Examples::

Spoiler: item/projectile (click to show/hide)

item/projectile
===============
Purpose::
    Turn an item into a projectile
    Either creates an item from scratch or checks a units inventory
    Projectile mechanics are either Falling or Shooting

Arguments::
    -type <Type>
        Type of projectile to create (changes number meanings)
        Valid Types:
            Falling
            Shooting
    -unitSource <UNIT_ID>
        id of source unit of projectile
    -unitTarget <UNIT_ID>
        id of target unit of projectile
    -locationSource [ <x> <y> <z> ]
        Location of starting point of projectile
    -locationTarget [ <x> <y> <z> ]
        Location of targets point of projectile
    -item <ITEM_TYPE:ITEM_SUBTYPE>
        Item to be created or checked for
    -material <MATERIAL_TYPE:MATERIAL_SUBTYPE>
        Material of item to be created (if not using -equipped)
    -height <#>
        Number of tiles above target to start projectile if using -type Falling
    -equipped
        If present will check unitSource's inventory
        If not present will create necessary items
    -number <#>
        Number of items to fire
        If creating will create this many
        If using equipped with use up to this many
        DEFAULT 1
    -velocity <#> or [ <vx> <vy> <vz> ]
        If using -type Shooting velocity is a single number
        If using -type Falling velcoity is an [ x y z ] triplet
        DEFAULT 20 or [ 0 0 0 ]
    -maxrange <#>
        Maximum range the projectile can travel in tiles and still hit
        DEFAULT 10
    -minrange <#>
        Minimum range the projectile must travel to hit
        DEFAULT 1
    -hitchance <#>
        Chance for projectile to hit target
        DEFAULT 50
    -quality <#>
        If creating items will create items at given quality
        DEFAULT 0

Examples::
   * Create a falling projectile over unitTarget out of unitSources equipped bolt
      item/projectile -unitSource \\UNIT_ID -unitTarget \\UNIT_ID -item AMMO:ITEM_AMMO_BOLT -equipped -type Falling -height 10
   * Create 10 steel short swords from unitSource to locationTarget
      item/projectile -unitSource \\UNIT_ID -locationTarget [ \\LOCATION ] -item WEAPON:ITEM_WEAPON_SWORD_SHORT -material INORGANIC:STEEL -number 10 -velocity 50 -maxrange 4 -hitchance 10

entity Scripts

Spoiler: entity/change-resource (click to show/hide)

entity/change-resource
==================
Purpose::
    Adds and removes available resources for an entity

Uses::
   functions/entity

Arguments::
    -entity <HISTORICAL_ENTITY_ID>
        ID number of entity to change
    -type <RESROUCE_TYPE:RESOURCE_SUBTYPE>
        The type and subtype of resource to change
        Valid TYPEs and SUBTYPEs:
            CREATURE
                PET | PACK | MINION | WAGON | EXOTIC | MOUNT
            INORGANIC
                METAL | STONE | GEM | GLASS | SAND | CLAY
            ITEM
                WEAPON | SHIELD | AMMO | HELM | ARMOR | PANTS | SHOES | GLOVES
                TRAP | SIEGE | TOY | INSTRUMENT | TOOL
            ORGANIC
                LEATHER | FIBER | SILK | WOOL | WOOD | PLANT | SEED | BONE
                MEAT | CHEESE | SHELL | IVORY | HORN | PEARL | DRINK
            PRODUCT
                PICK | MELEE | RANGED | AMMO | ARMOR | ANVIL | CRAFTS
                BARRELS | FLASKS | QUIVERS | BACKPACKS | CAGES
    -obj <CREATURE_RACE:CREATURE_CASTE> or <MATERIAL_TYPE:MATERIAL_SUBTYPE> or <ITEM_TYPE:ITEM_SUBTYPE>
        The type and subtype of the creature or material to add
        For Example
            DWARF:MALE
            ELF:BONE
            CEDAR:WOOD
    -add
        Adds the resource to the entity
    -remove
        Removes the resource from the entity

Examples::
   * Add female dragons to the entities available pets
      entity/change-resource -entity \\ENTITY_ID -add -type CREATURE:PET -obj DRAGON:FEMALE
   * Add adamantine to the entities available metals
      entity/change-resource -entity \\ENTITY_ID -add -type INORGANIC:METAL -obj INORGANIC:ADAMANTINE
   * Remove all animals from the entities available mounts
      entity/change-resource -entity \\ENTITY_ID -remove -type CREATURE:MOUNT -obj ALL:ALL

building Scripts

Spoiler: building/change-subtype (click to show/hide)

building/change-subtype
=======================
Purpose::
    Change the subtype of a building from one custom building to a different custom building
    Or from one hard coded subtype to another hard coded subtype of the same type
   Does not support changing building type (e.g. going from Workshop -> Furnace or Chair -> Bed)

Uses::
   functions/building

Arguments::
    -building <BUILDING_ID>
        id of building to be changed
    -subtype <SUBTYPE>
        Custom building token or hardcoded building token (e.g. FARMERS)
    -dur #ticks
        Length of time in in-game ticks for the change to last
        Added items will not be removed at end of duration

Examples::
   * Change a custom building to a different custom building subtype for 7200 ticks
      building/change-subtype -building \\BUILDING_ID -subtype NEW_CUSTOM_BUILDING -dur 7200
   * Change a metalsmith forge to a magma forge
      building/change-subtype -building \\BUILDING_ID -subtype MAGMAFORGE

Spoiler: building/create (click to show/hide)

building/create
===============
Purpose::
    Create a fully functioning building

Uses::
   functions/building

Arguments::
    -location [ x y z ]
    -type Type
        Building type to create
        Valid Types:
            Furnace
            Workshop
    -subtype SUBTYPE
        Building token to create

Examples::
   * Create a custom building (e.g. a building found in the raws)
      building/create -location [ \\LOCATION ] -type Workshop -subtype SCREW_PRESS
   * Create a hardcoded building
      building/create -location [ \\LOCATION ] -type Furnace -subtype SMELTER

map Scripts

Spoiler: map/spawn-flow (click to show/hide)

map/spawn-flow
============
Purpose::
   Create a flow at a given position

Uses::
   functions/map
   functions/math

Arguments::
   -unit <UNIT_ID>
      id of unit to use as target
   -pos [ <x> <y> <z> ]
      map position to use as target
   -type FLOWTYPE
      Valid Types:
         Miasma
         Steam
         Mist
         MaterialDust
         MagmaMist
         Smoke
         Dragonfire
         Fire
         Web
         MaterialGas
         MaterialVapor
         OceanWave
         SeaFoam
         ItemCloud
   -density <#>
      density of spawned flow
   -inorganic <INORGANIC_TOKEN>
      inorganic token to use for flows that have specific inorganic materials
   -static
      if present the spawned flow will not spread to nearby map squares
      and will just slowly decay in place
   -offset [ <x> <y> <z> ]
      positional offset from -unit or -pos
   -plan <filename>
      plan file name to use for determining positions
   -shape <SHAPE>
      shape to use for determining positions
      Valid Shapes:
         SQUARE
         CIRCLE
   -origin <UNIT_ID> or [ <x> <y> <z> ]
      position to use as the origin for -plan
   -radius <x> or [ <x> <y> ] or [ <x> <y> <z> ]
      determines the size of the -shape
   -number <#>
      if present will choose positions randomly
      
Examples::
   * Create density 100 INORGANIC:STEEL webs in a circle with a radius of 6 tiles
      map/spawn-flow -unit \\UNIT_ID -type WEB -density 100 -inorganic STEEL -shape CIRCLE -radius [ 6 6 ]
   * Create a density 50 fire flow in a cone, the flow will not spread and will remain in the tiles chosen
      map/spawn-flow -pos [ \\LOCATION ] -type FIRE -density 50 -static -origin \\UNIT_ID -plan CONE_LARGE.txt

Spoiler: map/spawn-liquid (click to show/hide)

map/spawn-liquid
============
Purpose::
   Create water or magma at a given position

Uses::
   functions/map
   functions/math

Arguments::
   -unit <UNIT_ID>
      id of unit to use as target
   -pos [ <x> <y> <z> ]
      map position to use as target
   -magma
      if present will spawn magma instead of water
   -depth <#>
      depth of spawned liquid
   -offset [ <x> <y> <z> ]
      positional offset from -unit or -pos
   -plan <filename>
      plan file name to use for determining positions
   -shape <SHAPE>
      shape to use for determining positions
      Valid Shapes:
         SQUARE
         CIRCLE
   -origin <UNIT_ID> or [ <x> <y> <z> ]
      position to use as the origin for -plan
   -radius <x> or [ <x> <y> ] or [ <x> <y> <z> ]
      determines the size of the -shape
   -number <#>
      if present will choose positions randomly
      
Examples::
   * Create a radius 6 circle of depth 7 water
      map/spawn-liquid -unit \\UNIT_ID -depth 7 -shape CIRCLE -radius [ 6 6 ]
   * Create a cone of depth 2 magma based on an external file
      map/spawn-liquid -pos [ \\LOCATION ] -magma -depth 2 -origin \\UNIT_ID -plan CONE_LARGE.txt

[Roses]

Current Systems

Enhanced System

Purpose: The Enhanced System takes the raws as they are now and adds new token options to them. These additional tokens are declared in curly brackets {} and so are not read by DF itself, but instead by the system.
System Modules: Enhanced Buildings, Enhanced Items, Enhanced Reactions

enhancedBuildings

Raw File Type: Building
Eventful Functions:

• onJobInitiated
• onJobCompleted

Custom Events:

Accepted Tokens: (in no particular order yet)

• {POWER_PRODUCED:#} - Amount of power produced if {MECHANICAL}
• {GEAR_POINT:x} - Location of gear connection point if {MECHANICAL}
• {ON_FINISH} - Sets up a trigger for when the building is finished
• {DESCRIPTION:string} - Sets a description to be used for the journal utility in the future
• {ON_DECONSTRUCT} - Sets up a trigger for when the building is being deconstructed
• {OUTSIDE_ONLY} - If present, will only allow construction if all squares are outside
• {REPEATING_SCRIPT} - A dfhack script to run at a specific frequency (if # == 0 the script is only run once)
• {ON_REMOVED} - Sets up a trigger for when the building is fully removed (from deconstruction)
• {ON_START} - Sets up a trigger for when the building is started (after materials are gathered)
• {MECHANICAL} - Sets the building as a mechanical building through require('plugins.building-hacks').registerBuilding
• {REQUIRED_MAGMA:#} - Amount of magma needed around and/or under the building to be constructed
• {POWER_CONSUMED:#} - Amount of power consumed if {MECHANICAL}
• {CONSTRUCTION_TIME:skill:basedur:skilldecrease:mindur} - Changes the amount of time it takes to construct the building once all materials are brought to it
• {MAX_AMOUNT:#} - Max number of this building that can be constructed (equivalent to {FORBIDDEN_BUILDING:THIS_BUILDING:#}
• {FORBIDDEN_BUILDING:A:B} - Amount of specific building needed to exist in order for this building to not be constructed
• {REQUIRED_BUILDING:A:B} - Amount of specific building needed to exist in order for this building to be constructed
• {REQUIRED_WATER:#} - Amount of water needed around and/or under the building to be constructed
• {ON_QUEUE} - Sets up a trigger for when the building is started (before materials are gathered)
• {INSIDE_ONLY} - If present, will only allow construction if all squares are inside
• {NEEDS_POWER} - Sets needs_power to true for registerBuilding
• {AUTO_GEARS} - Sets auto_gears to true for registerBuilding
• {SCRIPT} - A dfhack script to run once with a specific probability

Simple Examples:
   [BUILDING_WORKSHOP:FOUNTAIN]
      [NAME:Fountain]
      {DESCRIPTION:A building that continually produces mist}
      ... DF Building Stuff ...
      {REQUIRED_WATER:4}
      {ON_FINISH}
         {REPEATING_SCRIPT:map/spawn-flow -pos [ BUILDING_LOCATION ] -type Mist -density 100:25}
      
   [BUILDING_WORKSHOP:COMPLEX_BUILDING]
      [NAME:Complex Building]
      {DESCRIPTION:A complex building that takes a long time to build}
      ... DF Building Stuff ...
      {CONSTRUCTION_TIME:MECHANICS:1000:10:1} Base construction time is 1000 ticks, lowers by 10 for each skill level, max build speed is 1
      
   [BUILDING_WORKSHOP:WINDMILL]
      [NAME:Windmill]
      {DESCRIPTION:A building that can only be built outside and makes power}
      ... DF Building Stuff ...
      {OUTSIDE_ONLY}
      {MECHANICAL}
         {AUTO_GEARS}
         {POWER_PRODUCED:25}

enhancedItems

Raw File Type: Item
Eventful Functions:

• onProjItemCheckImpact
• onUnitAttack
• onProjItemCheckMovement
• onInventoryChange

Custom Events:

• onItemAction
• onItemProjectile

Accepted Tokens: (in no particular order yet)

• {ON_PARRY} - Sets up a trigger for when a unit parries with the item
• {ON_PROJECTILE_FIRED} - Sets up a trigger for when an item projectile is fired
• {ATTRIBUTE_CHANGE:target:attribute:change:chance} - Equivalent to {SCRIPT:unit/change-attribute ...}
• {DESCRIPTION:string} - Sets a description to be used for the journal utility in the future
• {ON_PROJECTILE_HIT} - Sets up a trigger for when an item projectile hits
• {SYNDROME_CHANGE:target:syndrome:change:chance} - Equivalent to {SCRIPT:unit/change-syndrome ...}
• {SCRIPT} - A dfhack script to run with a specific chance when triggered
• {ATTRIBUTE:A:B} - Used as a shortcut for ON_EQUIP and ON_UNEQUIP attribute changes
• {ON_PROJECTILE_MOVE} - Sets up a trigger for when an item projectile moves
• {ON_EQUIP} - Sets up a trigger for when the item is equipped
• {CLASS:string} - Define an item class, not currently used for anything
• {ON_BLOCK} - Sets up a trigger for when a unit blocks with the item
• {ON_ATTACK} - Sets up a trigger for when a unit attacks (melee) with the item
• {FIRE_RATE:base:change:max} - Adjust the fire rate for ranged weapons
• {ON_UNEQUIP} - Sets up a trigger for when the item is unequipped
• {REPEATING_SCRIPT} - A dfhack script to run with a specific frequency
• {SKILL_CHANGE:target:skill:change:chance} - Equivalent to {SCRIPT:unit/change-skill ...}
• {ON_SHOOT} - Sets up a trigger for when a unit attacks (ranged) with the item
• {ON_WOUND} - Sets up a trigger for when a unit wounds another unit with the item
• {SKILL:A:B} - Used as a shortcut for ON_EQUIP and ON_UNEQUIP skill changes

Simple Examples:
   [ITEM_SHIELD:ITEM_SHIELD_EXAMPLE]
      [NAME:Example Shield]
      {DESCRIPTION:Knocks enemy backwards half the time when you block}
      ... DF Item Stuff ...
      {ON_BLOCK}
         {SCRIPT:unit/propel -unit OPPONENT -source BLOCKER -velocity [ 50 50 0 ] -mode Relative:50}

   [ITEM_WEAPON:RAPID_FIRE_CROSSBOW]
      [NAME:Fast Shooting Crossbow]
      {DESCRIPTION:Shoots bolts very fast}
      ... DF Item Stuff ...
      {FIRE_RATE:10:2:1} -- Base fire rate is 10, increases by 2 for each skill level, max shot speed is 1

   [ITEM_WEAPON:BLOOD_SWORD]
      [NAME:Blood Sword]
      {DESCRIPTION:Drains blood from opponent when wounded}
      ... DF Item Stuff ...
      {ON_WOUND}
         {SCRIPT:unit/change-body -unit OPPONENT -blood \-10:100}
         {SCRIPT:unit/change-body -unit HOLDER -blood 10:100}

enhancedReactions

Raw File Type: Reaction
Eventful Functions:

• onReactionComplete
• onJobCompleted
• onJobInitiated

Custom Events:

Accepted Tokens: (in no particular order yet)

• {REACTION_TIME:skill:basedur:skilldecrease:mindur} - Changes the amount of time it takes to complete the reaction once all materials are brought to it
• {REQUIRED_MAGMA:#} - Amount of nearby magma required for the reaction (does not consume the magma)
• {ON_FINISH} - Sets up a trigger for when the reaction is finished (no product necessary)
• {DESCRIPTION:string} - Sets a description to be used for the journal utility in the future
• {REQUIRED_WATER:#} - Amount of nearby water required for the reaction (does not consume the water)
• {PRODUCT:probability:amount:type:subtype:mattype:matsubtype} - Add custom products to a reaction (only for when the reaction finishes)
• {REPEATING_SCRIPT} - A dfhack script to run with a specific frequency
• {ON_QUEUE} - Sets up a trigger for when the reaction is started (before materials are gathered)
• {SCRIPT} - A dfhack script to run with a specific chance when triggered
• {ON_PRODUCT} - Sets up a trigger for when the reaction is finished and a product is created
• {ON_START} - Sets up a trigger for when the reaction is started (after materials are gathered)
• {CREATE:probability:amount:type:subtype:mattype:matsubtype} - Add custom products to a reaction (produced for any specified trigger)

Simple Examples:
   [REACTION:MAKE_WAX_CRAFTS]
      {REACTION_TIME:WAX_WORKING:1:1:1}
      {PRODUCT:100:7:LIQUID:WATER:NONE:NONE}
      {PRODUCT:100:150:FLOW:MATERIALDUST:INORGANIC:SLADE}
      {ON_QUEUE} -- Triggers when the reaction is queued
         {SCRIPT:devel/print-args ON_QUEUE REACTION_NAME WORKER_ID BUILDING_ID [ LOCATION ]:100}
      {ON_START} -- Triggers after the ingredients are gathered
         {SCRIPT:devel/print-args ON_START REACTION_NAME WORKER_ID BUILDING_ID [ LOCATION ]:100}
      {ON_FINISH} -- Triggers when the reaction is finished, no product needed
         {SCRIPT:devel/print-args ON_FINISH REACTION_NAME WORKER_ID BUILDING_ID [ LOCATION ]:100}
      {ON_PRODUCT} -- Triggers when the reaction is finished and a product is produced
         {SCRIPT:devel/print-args ON_PRODUCT REACTION_NAME WORKER_ID BUILDING_ID [ LOCATION ]:100}
      [NAME:make wax crafts]
      [BUILDING:CRAFTSMAN:CUSTOM_SHIFT_W]
      [REAGENT:wax:150:GLOB:NONE:NONE:NONE]
      [REACTION_CLASS:WAX]
      [PRODUCT:100:1:CRAFTS:NONE:GET_MATERIAL_FROM_REAGENT:wax:NONE]
      [SKILL:WAX_WORKING]

[Roses]

Current Utilities (WIP)

[Meph]

Questions about the wrapper script.

1. Does anyone other than myself use the 'wrapper' script?
2. If so, what are your opinions on how the system currently works? There are a couple options to try and improve usability. (For instance instead of having to do -profession required:CARPENTER or -profession immune:MASON I could make a separate rprofession and iprofession).
3. I would like to add more features (including checking for body parts, inventory items, etc...). But I am wondering when it becomes too much. I unfortunately can't think of a better way to allow more custom targeting options.
4. Upper or lowercase? That is to say, currently if you want to require a target to have at least 2000 strength you would say -physical min:STRENGTH:2000. Should that instead be MIN:STRENGTH:2000? Something else entirely?
5. Any other suggestions?

1. I wanted to, but you changed syntax a lot, kept working on it, and then I went away on tour.
2. None yet.
3. Wait till someone requests it? It's complex enough as is; I think.
4. Dont care if low/upper case, just keep it consistent.
5. Probably later.

[Isngrim]

Questions about the wrapper script.

1. Does anyone other than myself use the 'wrapper' script?
2. If so, what are your opinions on how the system currently works? There are a couple options to try and improve usability. (For instance instead of having to do -profession required:CARPENTER or -profession immune:MASON I could make a separate rprofession and iprofession).
3. I would like to add more features (including checking for body parts, inventory items, etc...). But I am wondering when it becomes too much. I unfortunately can't think of a better way to allow more custom targeting options.
4. Upper or lowercase? That is to say, currently if you want to require a target to have at least 2000 strength you would say -physical min:STRENGTH:2000. Should that instead be MIN:STRENGTH:2000? Something else entirely?
5. Any other suggestions?

1: I'm trying to, but the new structuring for using the scripts for modding is throwing me through a loop. Edit* as is my grammar
2: as far as I can tell its great,though i do like the iprofession/rprofession
3, 4, and  5 : I'd have to agree with Meph

[expwnent]

Posting to watch.

Have you switched the !BLAH system over to the \\BLAH system to make it more uniform with modtools stuff?

[Roses]

Posting to watch.

Have you switched the !BLAH system over to the \\BLAH system to make it more uniform with modtools stuff?

Yes, I did have a question about that though, and more specifically about the entire utils.processArgs thing. A couple questions actually;

1. Is processArgs recursive? What I mean is when using something like modtools/interaction-trigger does it read through everything in the -command argument? Or does it just lump it all into one thing?
2. Similarly, if I can't use the same \\BLAH that the other modtools things use correct? Because it would be overwritten?
3. Should it always be two \? Is there ever a time you would only use one \?

EDIT: Thanks for the feedback. My current plan is to rewrite the wrapper script to make it more intelligeble for people who want to see what is going on, and to make it easily addable to in the future. The rewrite shouldn't change the syntax from what it was before, and I am actually going to allow for both upper or lower case (since that is super easy to do). I am currently planning on breaking -profession, -noble, and -entity into a required and immune section (from #2 in the previous post)

[Meph]

EnchancedItems - similar to EnchancedCreatures, except for items. Will also display an items history.

I've seen a script like this flying around, but it was never finished.

[Roses]

EnchancedItems - similar to EnchancedCreatures, except for items. Will also display an items history.

I've seen a script like this flying around, but it was never finished.

Yes, I've seen one too, except I am planning on doing more advanced things (like sharpness increasing the more units the item kills, etc...)

[Meph]

Call me boring, but shouldnt the sharpness decrease, the more the weapon is used? (except on magical weapons)

[Roses]

Call me boring, but shouldnt the sharpness decrease, the more the weapon is used? (except on magical weapons)

Yes, and that would be possible too, but I was thinking more for magical weapons and such. Basically just to give items more flavor and options all around.

[Meph]

Can you give artefacts some random effects? For example a file with X effects that are user-defined, and any artefact created in dwarf mode gets a random one from the list?

But I probably should not make suggestions at this point, seeing how full (and unfinished) your todo list is.

[Roses]

Hahaha, yeah that todo list is just staring at me. Wish I could just take a month break from real life and get everything done. But, actually, yes, that was one of the plans. The actual DFHack part of it all is rather simple, but it's going to be figuring out how to make it module and customizable that is more difficult.

[Max™]

That artifact idea is why I left the artifact critical script just artifacts rather than all attacks.