modtools/create-unit
====================

Tags: dev

Command: "modtools/create-unit"

  Create arbitrary units.

Creates a unit.  Usage:

   -race raceName
       (obligatory)
       Specify the race of the unit to be created.
       examples:
           DWARF
           HUMAN

   -caste casteName
       Specify the caste of the unit to be created.
       If omitted, the caste is randomly selected.
       examples:
           MALE
           FEMALE
           DEFAULT

   -domesticate
       Tames the unit if it lacks the CAN_LEARN and CAN_SPEAK tokens.

   -civId id
       Make the created unit a member of the specified civilisation
       (or none if id = -1).  If id is \\LOCAL, make it a member of the
       civ associated with the fort; otherwise id must be an integer

   -groupId id
       Make the created unit a member of the specified group
       (or none if id = -1).  If id is \\LOCAL, make it a member of the
       group associated with the fort; otherwise id must be an integer

   -setUnitToFort
       Sets the groupId and civId to those of the player in Fortress mode.
       Equivalent to -civId \\LOCAL and -groupId \\LOCAL.

   -name entityRawName
       Set the unit's name to be a random name appropriate for the
       given entity. \\LOCAL can be specified instead to automatically
       use the fort group entity in fortress mode only.
       examples:
           MOUNTAIN
           EVIL

   -nick nickname
       This can be included to nickname the unit.
       Replace "nickname" with the desired name.

   -age howOld
       This can be included to specify the unit's age.
       Replace "howOld" with a (non-negative) number.
       The unit's age is set randomly if this is omitted.

   -equip [ ITEM:MATERIAL:QUANTITY ... ]
       This can be included to create items and equip them onto
           the created unit.
       This is carried out via the same logic used in arena mode,
           so equipment will always be sized correctly and placed
           on what the game deems to be appropriate bodyparts.
           Clothing is also layered in the appropriate order.
       Note that this currently comes with some limitations,
           such as an inability to specify item quality
           and objects not being placed in containers
           (for example, arrows are not placed in quivers).
       Item quantity defaults to 1 if omitted.
       When spaces are included in the item or material name,
           the entire item description should be enclosed in
           quotation marks. This can also be done to increase
           legibility when specifying multiple items.
       examples:
           -equip [ RING:CREATURE:DWARF:BONE:3 ]
               3 dwarf bone rings
           -equip [ ITEM_WEAPON_PICK:INORGANIC:IRON ]
               1 iron pick
           -equip [ "ITEM_SHIELD_BUCKLER:PLANT:OAK:WOOD" "AMULET:AMBER" ]
               1 oaken buckler and 1 amber amulet

   -skills [ SKILL:LEVEL ... ]
       This can be included to add skills to the created unit.
       Specify a skill token followed by a skill level value.
       Look up "Skill Token" and "Skill" on the DF Wiki for a list
           of valid tokens and levels respectively.
       Note that the skill level provided must be a number greater than 0.
       If the unit possesses a matching natural skill, this is added to it.
       Quotation marks can be added for legibility as explained above.
       example:
           -skill [ SNEAK:1 EXTRACT_STRAND:15 ]
               novice ambusher, legendary strand extractor

   -profession token
       This can be included to set the unit's profession.
       Replace "token" with a Unit Type Token (check the DF Wiki for a list).
       For skill-based professions, it is recommended to give the unit
           the appropriate skill set via -skills.
       This can also be used to make animals trained for war/hunting.
       Note that this will be overridden if the unit has been given the age
           of a baby or child, as these have a special "profession" set.
       Using this for setting baby/child status is not recommended;
           this should be done via -age instead.
       examples:
           STRAND_EXTRACTOR
           MASTER_SWORDSMAN
           TRAINED_WAR

   -customProfession name
       This can be included to give the unit a custom profession name.
       Enclose the name in quotation marks if it includes spaces.
       example:
           -customProfession "Destroyer of Worlds"

   -duration ticks
       If this is included, the unit will vanish in a puff of smoke
           once the specified number of ticks has elapsed.
       Replace "ticks" with an integer greater than 0.
       Note that the unit's equipment will not vanish.

   -quantity howMany
       This can be included to create multiple creatures simultaneously.
       Replace "howMany" with the desired number of creatures.
       Quantity defaults to 1 if this is omitted.

   -location [ x y z ]
       (obligatory)
       Specify the coordinates where you want the unit to appear.

   -locationRange [ x_offset y_offset z_offset ]
       If included, the unit will be spawned at a random location
           within the specified range relative to the target -location.
       z_offset defaults to 0 if omitted.
       When creating multiple units, the location is randomised each time.
       example:
           -locationRange [ 4 3 1 ]
               attempts to place the unit anywhere within
               -4 to +4 tiles on the x-axis
               -3 to +3 tiles on the y-axis
               -1 to +1 tiles on the z-axis
               from the specified -location coordinates

   -locationType type
       May be used with -locationRange
           to specify what counts as a valid tile for unit spawning.
       Unit creation will not occur if no valid tiles are available.
       Replace "type" with one of the following:
           Walkable
               units will only be placed on walkable ground tiles
               this is the default used if -locationType is omitted
           Open
               open spaces are also valid spawn points
               this is intended for flying units
           Any
               all tiles, including solid walls, are valid
               this is only recommended for ghosts not carrying items

   -flagSet [ flag1 flag2 ... ]
       This can be used to set the specified unit flags to true.
       Flags may be selected from:
           df.unit_flags1
           df.unit_flags2
           df.unit_flags3
           df.unit_flags4
       example:
           flagSet [ announce_titan ]
               causes an announcement describing the unit to appear
               when it is discovered ("[Unit] has come! ...")

   -flagClear [ flag1 flag2 ... ]
       As above, but sets the specified unit flags to false.
