MetzNet
/
dfhack
3
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Organizes and documents Units::is*(unit) functions

develop
Josh Cooper 2022-11-12 16:40:20 -08:00
parent ebd450af0e
commit d112649886
3 changed files with 1012 additions and 849 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

295
docs/Lua API.rst
Unescape Escape View File

@ -1188,150 +1188,301 @@ Job module
Units module Units module
------------ ------------
* ``dfhack.units.getPosition(unit)`` * ``dfhack.units.isUnitInBox(unit,x1,y1,z1,x2,y2,z2)``
Returns true *x,y,z* of the unit, or *nil* if invalid; may be not equal to unit.pos if caged. The unit is within the specified coordinates.
* ``dfhack.units.isUnitInBox(unit,x1,y1,z1,x2,y2,z2)`` * ``dfhack.units.isActive(unit)``
Returns true if the unit is within the specified coordinates. The unit is active (alive and on the map).
* ``dfhack.units.getUnitsInBox(x1,y1,z1,x2,y2,z2[,filter])`` * ``dfhack.units.isVisible(unit)``
Returns a table of all units within the specified coordinates. If the ``filter`` The unit is visible on the map.
argument is given, only units where ``filter(unit)`` returns true will be included.
Note that ``pos2xyz()`` cannot currently be used to convert coordinate objects to
the arguments required by this function.
* ``dfhack.units.teleport(unit, pos)`` * ``dfhack.units.isCitizen(unit[,ignore_sanity])``
Moves the specified unit and any riders to the target coordinates, setting The unit is an alive sane citizen of the fortress; wraps the
tile occupancy flags appropriately. Returns true if successful. same checks the game uses to decide game-over by extinction,
with an additional sanity check. You can identify citizens,
regardless of their sanity, by passing ``true`` as the optional
second parameter.
* ``dfhack.units.getGeneralRef(unit, type)`` * ``dfhack.units.isFortControlled(unit)``
Searches for a general_ref with the given type. Similar to ``dfhack.units.isCitizen(unit)``, but is based on checks
for units hidden in ambush, and includes tame animals. Returns *false*
if not in fort mode.
* ``dfhack.units.getSpecificRef(unit, type)`` * ``dfhack.units.isOwnCiv(unit)``
Searches for a specific_ref with the given type. The unit belongs to the player's civilization.
* ``dfhack.units.getContainer(unit)`` * ``dfhack.units.isOwnGroup(unit)``
Returns the container (cage) item or *nil*. The unit belongs to the player's group.
* ``dfhack.units.setNickname(unit,nick)`` * ``dfhack.units.isOwnRace(unit)``
Sets the unit's nickname properly. The unit belongs to the player's race.
* ``dfhack.units.getOuterContainerRef(unit)`` * ``dfhack.units.isAlive(unit)``
Returns a table (in the style of a ``specific_ref`` struct) of the outermost object that contains the unit (or one of the unit itself.) The unit isn't dead or undead.
The ``type`` field contains a ``specific_ref_type`` of ``UNIT``, ``ITEM_GENERAL``, or ``VERMIN_EVENT``.
The ``object`` field contains a pointer to a unit, item, or vermin, respectively.
* ``dfhack.units.getVisibleName(unit)`` * ``dfhack.units.isDead(unit)``
Returns the language_name object visible in game, accounting for false identities. The unit is completely dead and passive, or a ghost. Equivalent to
``dfhack.units.isKilled(unit) or dfhack.units.isGhost(unit)``.
* ``dfhack.units.getIdentity(unit)`` * ``dfhack.units.isKilled(unit)``
Returns the false identity of the unit if it has one, or *nil*. The unit has been killed.
* ``dfhack.units.getNemesis(unit)`` * ``dfhack.units.isSane(unit)``
Returns the nemesis record of the unit if it has one, or *nil*. The unit is capable of rational action, i.e. not dead, insane, zombie, or active werewolf.
* ``dfhack.units.isCrazed``
The unit is berserk and will attack all other creatures except members of its own species
that are also crazed. (can be modified by curses)
* ``dfhack.units.isGhost(unit)``
The unit is a ghost.
* ``dfhack.units.isHidden(unit)``
The unit is hidden to the player, accounting for sneaking. Works for any game mode.
* ``dfhack.units.isHidingCurse(unit)`` * ``dfhack.units.isHidingCurse(unit)``
Checks if the unit hides improved attributes from its curse. The unit is hiding a curse.
* ``dfhack.units.getPhysicalAttrValue(unit, attr_type)``
* ``dfhack.units.getMentalAttrValue(unit, attr_type)``
Computes the effective attribute value, including curse effect. * ``dfhack.units.isMale(unit)``
* ``dfhack.units.isCrazed(unit)`` The unit is male.
* ``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.isFemale(unit)``
* ``dfhack.units.getMiscTrait(unit, type[, create])`` The unit is female.
Finds (or creates if requested) a misc trait object with the given id. * ``dfhack.units.isBaby(unit)``
* ``dfhack.units.isActive(unit)`` The unit is a baby.
The unit is active (alive and on the map). * ``dfhack.units.isChild(unit)``
* ``dfhack.units.isAlive(unit)`` The unit is a child.
The unit isn't dead or undead. * ``dfhack.units.isAdult(unit)``
* ``dfhack.units.isDead(unit)`` The unit is an adult.
The unit is completely dead and passive, or a ghost. Equivalent to * ``dfhack.units.isGay(unit)``
``dfhack.units.isKilled(unit) or dfhack.units.isGhost(unit)``.
* ``dfhack.units.isKilled(unit)`` The unit is gay.
The unit has been killed. * ``dfhack.units.isNake(unit)``
* ``dfhack.units.isGhost(unit)`` The unit is naked.
The unit is a ghost. * ``dfhack.units.isVisiting(unit)``
* ``dfhack.units.isSane(unit)`` The unit is visiting. eg. Merchants, Diplomatics, travelers.
* ``dfhack.units.isTrainableHunting(unit)``
The unit is trainable for hunting.
* ``dfhack.units.isTrainableWar(unit)``
The unit is trainable for war.
* ``dfhack.units.isTrained(unit)``
The unit is trained.
* ``dfhack.units.isHunter(unit)``
The unit is a trained hunter.
* ``dfhack.units.isWar(unit)``
The unit is trained for war.
* ``dfhack.units.isTame(unit)``
The unit is tame.
* ``dfhack.units.isTamable(unit)``
The unit is tamable.
* ``dfhack.units.isDomesticated(unit)``
The unit is domesticated.
* ``dfhack.units.isMarkedForSlaughter(unit)``
The unit is marked for slaughter.
* ``dfhack.units.isGelded(unit)``
The unit is gelded.
* ``dfhack.units.isEggLayer(unit)``
The unit is an egg layer.
* ``dfhack.units.isGrazer(unit)``
The unit is a grazer.
* ``dfhack.units.isMilkable(unit)``
The unit is milkable.
* ``dfhack.units.isForest(unit)``
The unit is of the forest.
* ``dfhack.units.isMischievous(unit)``
The unit is mischievous.
* ``dfhack.units.isAvailableForAdoption(unit)``
The unit is available for adoption.
* ``dfhack.units.isOpposedToLife(unit)``
* ``dfhack.units.hasExtravision(unit)``
* ``dfhack.units.isBloodsucker(unit)``
Simple checks of caste attributes that can be modified by curses.
The unit is capable of rational action, i.e. not dead, insane, zombie, or active werewolf.
* ``dfhack.units.isDwarf(unit)`` * ``dfhack.units.isDwarf(unit)``
The unit is of the correct race of the fortress. The unit is of the correct race for the fortress.
* ``dfhack.units.isCitizen(unit[,ignore_sanity])`` * ``dfhack.units.isAnimal(unit)``
The unit is an alive sane citizen of the fortress; wraps the The unit is an animal.
same checks the game uses to decide game-over by extinction
(except for the sanity check).
* ``dfhack.units.isInvader(unit)`` * ``dfhack.units.isMerchant(unit)``
The unit is an active invader or marauder. The unit is a merchant.
* ``dfhack.units.isVisiting(unit)`` * ``dfhack.units.isDiplomat(unit)``
The unit is either a merchant, diplomat, or plain visitor. The unit is a diplomat.
* ``dfhack.units.isVisitor(unit)`` * ``dfhack.units.isVisitor(unit)``
The unit is strictly a visitor. Merchants and diplomats do not count here. The unit is a regular visitor with no special purpose (eg. merchant).
* ``dfhack.units.isInvader(unit)``
The unit is an active invader or marauder.
* ``dfhack.units.isUndead(unit[,include_vamps])`` * ``dfhack.units.isUndead(unit[,include_vamps])``
The unit is undead, but not a vampire. The unit is undead, but not a vampire.
* ``dfhack.units.isNightCreature(unit)``
The unit is undead, but not a vampire.
* ``dfhack.units.isSemiMegabeast(unit)``
The unit is undead, but not a vampire.
* ``dfhack.units.isMegabeast(unit)``
The unit is a megabeast.
* ``dfhack.units.isTitan(unit)``
The unit is a titan.
* ``dfhack.units.isDemon(unit)``
The unit is a demon.
* ``dfhack.units.isDanger(unit)``
The unit is dangerous, and probably hostile. This includes
Great Dangers (see below), semi-megabeasts, night creatures,
undead, invaders, and crazed units.
* ``dfhack.units.isGreatDanger(unit)`` * ``dfhack.units.isGreatDanger(unit)``
The unit is of Great Danger. This include demons, titans, and megabeasts. The unit is of Great Danger. This include demons, titans, and megabeasts.
* ``dfhack.units.isDanger(unit)``
The unit is dangerous, and probably hostile. This includes Great Dangers, semi-megabeasts, night creatures, undead, and invaders. * ``dfhack.units.getPosition(unit)``
* ``dfhack.units.isFortControlled(unit)`` Returns true *x,y,z* of the unit, or *nil* if invalid; may be not equal to unit.pos if caged.
Similar to ``dfhack.units.isCitizen(unit)``, but is based on checks for units hidden in ambush, and includes tame animals. Returns *false* if not in fort mode. * ``dfhack.units.getUnitsInBox(x1,y1,z1,x2,y2,z2[,filter])``
* ``dfhack.units.isVisible(unit)`` Returns a table of all units within the specified coordinates. If the ``filter``
argument is given, only units where ``filter(unit)`` returns true will be included.
Note that ``pos2xyz()`` cannot currently be used to convert coordinate objects to
the arguments required by this function.
The unit is visible on the map. * ``dfhack.units.teleport(unit, pos)``
* ``dfhack.units.isHidden(unit)`` Moves the specified unit and any riders to the target coordinates, setting
tile occupancy flags appropriately. Returns true if successful.
The unit is hidden to the player, accounting for sneaking. Works for any game mode. * ``dfhack.units.getGeneralRef(unit, type)``
Searches for a general_ref with the given type.
* ``dfhack.units.getSpecificRef(unit, type)``
Searches for a specific_ref with the given type.
* ``dfhack.units.getContainer(unit)``
Returns the container (cage) item or *nil*.
* ``dfhack.units.setNickname(unit,nick)``
Sets the unit's nickname properly.
* ``dfhack.units.getOuterContainerRef(unit)``
Returns a table (in the style of a ``specific_ref`` struct) of the outermost object that contains the unit (or one of the unit itself.)
The ``type`` field contains a ``specific_ref_type`` of ``UNIT``, ``ITEM_GENERAL``, or ``VERMIN_EVENT``.
The ``object`` field contains a pointer to a unit, item, or vermin, respectively.
* ``dfhack.units.getVisibleName(unit)``
Returns the language_name object visible in game, accounting for false identities.
* ``dfhack.units.getIdentity(unit)``
Returns the false identity of the unit if it has one, or *nil*.
* ``dfhack.units.getNemesis(unit)``
Returns the nemesis record of the unit if it has one, or *nil*.
* ``dfhack.units.getPhysicalAttrValue(unit, attr_type)``
* ``dfhack.units.getMentalAttrValue(unit, attr_type)``
Computes the effective attribute value, including curse effect.
* ``dfhack.units.getMiscTrait(unit, type[, create])``
Finds (or creates if requested) a misc trait object with the given id.
* ``dfhack.units.getAge(unit[,true_age])`` * ``dfhack.units.getAge(unit[,true_age])``

132
library/include/modules/Units.h
Unescape Escape View File

@ -68,14 +68,78 @@ static const int MAX_COLORS = 15;
* The Units module - allows reading all non-vermin units and their properties * The Units module - allows reading all non-vermin units and their properties
*/ */
DFHACK_EXPORT bool isUnitInBox(df::unit* u,
int16_t x1, int16_t y1, int16_t z1,
int16_t x2, int16_t y2, int16_t z2);
DFHACK_EXPORT bool isActive(df::unit *unit);
DFHACK_EXPORT bool isVisible(df::unit* unit);
DFHACK_EXPORT bool isCitizen(df::unit *unit, bool ignore_sanity = false);
DFHACK_EXPORT bool isFortControlled(df::unit *unit);
DFHACK_EXPORT bool isOwnCiv(df::unit* unit);
DFHACK_EXPORT bool isOwnGroup(df::unit* unit);
DFHACK_EXPORT bool isOwnRace(df::unit* unit);
DFHACK_EXPORT bool isAlive(df::unit *unit);
DFHACK_EXPORT bool isDead(df::unit *unit);
DFHACK_EXPORT bool isKilled(df::unit *unit);
DFHACK_EXPORT bool isSane(df::unit *unit);
DFHACK_EXPORT bool isCrazed(df::unit *unit);
DFHACK_EXPORT bool isGhost(df::unit *unit);
/// is unit hidden to the player? accounts for ambushing
DFHACK_EXPORT bool isHidden(df::unit *unit);
DFHACK_EXPORT bool isHidingCurse(df::unit *unit);
DFHACK_EXPORT bool isMale(df::unit* unit);
DFHACK_EXPORT bool isFemale(df::unit* unit);
DFHACK_EXPORT bool isBaby(df::unit* unit);
DFHACK_EXPORT bool isChild(df::unit* unit);
DFHACK_EXPORT bool isAdult(df::unit* unit);
DFHACK_EXPORT bool isGay(df::unit* unit);
DFHACK_EXPORT bool isNaked(df::unit* unit);
DFHACK_EXPORT bool isVisiting(df::unit* unit);
DFHACK_EXPORT bool isTrainableHunting(df::unit* unit);
DFHACK_EXPORT bool isTrainableWar(df::unit* unit);
DFHACK_EXPORT bool isTrained(df::unit* unit);
DFHACK_EXPORT bool isHunter(df::unit* unit);
DFHACK_EXPORT bool isWar(df::unit* unit);
DFHACK_EXPORT bool isTame(df::unit* unit);
DFHACK_EXPORT bool isTamable(df::unit* unit);
DFHACK_EXPORT bool isDomesticated(df::unit* unit);
DFHACK_EXPORT bool isMarkedForSlaughter(df::unit* unit);
DFHACK_EXPORT bool isGelded(df::unit* unit);
DFHACK_EXPORT bool isEggLayer(df::unit* unit);
DFHACK_EXPORT bool isGrazer(df::unit* unit);
DFHACK_EXPORT bool isMilkable(df::unit* unit);
DFHACK_EXPORT bool isForest(df::unit* unit);
DFHACK_EXPORT bool isMischievous(df::unit *unit);
DFHACK_EXPORT bool isAvailableForAdoption(df::unit* unit);
DFHACK_EXPORT bool hasExtravision(df::unit *unit);
DFHACK_EXPORT bool isOpposedToLife(df::unit *unit);
DFHACK_EXPORT bool isBloodsucker(df::unit *unit);
DFHACK_EXPORT bool isDwarf(df::unit *unit);
DFHACK_EXPORT bool isAnimal(df::unit* unit);
DFHACK_EXPORT bool isMerchant(df::unit* unit);
DFHACK_EXPORT bool isDiplomat(df::unit* unit);
DFHACK_EXPORT bool isVisitor(df::unit* unit);
DFHACK_EXPORT bool isInvader(df::unit* unit);
DFHACK_EXPORT bool isUndead(df::unit* unit, bool include_vamps = false);
DFHACK_EXPORT bool isNightCreature(df::unit* unit);
DFHACK_EXPORT bool isSemiMegabeast(df::unit* unit);
DFHACK_EXPORT bool isMegabeast(df::unit* unit);
DFHACK_EXPORT bool isTitan(df::unit* unit);
DFHACK_EXPORT bool isDemon(df::unit* unit);
DFHACK_EXPORT bool isDanger(df::unit* unit);
DFHACK_EXPORT bool isGreatDanger(df::unit* unit);
/* Read Functions */ /* Read Functions */
// Read units in a box, starting with index. Returns -1 if no more units // Read units in a box, starting with index. Returns -1 if no more units
// found. Call repeatedly do get all units in a specified box (uses tile coords) // found. Call repeatedly do get all units in a specified box (uses tile coords)
DFHACK_EXPORT int32_t getNumUnits(); DFHACK_EXPORT int32_t getNumUnits();
DFHACK_EXPORT df::unit *getUnit(const int32_t index); DFHACK_EXPORT df::unit *getUnit(const int32_t index);
DFHACK_EXPORT bool isUnitInBox(df::unit* u,
int16_t x1, int16_t y1, int16_t z1,
int16_t x2, int16_t y2, int16_t z2);
DFHACK_EXPORT bool getUnitsInBox(std::vector<df::unit*> &units, DFHACK_EXPORT bool getUnitsInBox(std::vector<df::unit*> &units,
int16_t x1, int16_t y1, int16_t z1, int16_t x1, int16_t y1, int16_t z1,
int16_t x2, int16_t y2, int16_t z2); int16_t x2, int16_t y2, int16_t z2);
@ -102,34 +166,11 @@ DFHACK_EXPORT df::language_name *getVisibleName(df::unit *unit);
DFHACK_EXPORT df::identity *getIdentity(df::unit *unit); DFHACK_EXPORT df::identity *getIdentity(df::unit *unit);
DFHACK_EXPORT df::nemesis_record *getNemesis(df::unit *unit); DFHACK_EXPORT df::nemesis_record *getNemesis(df::unit *unit);
DFHACK_EXPORT bool isHidingCurse(df::unit *unit);
DFHACK_EXPORT int getPhysicalAttrValue(df::unit *unit, df::physical_attribute_type attr); DFHACK_EXPORT int getPhysicalAttrValue(df::unit *unit, df::physical_attribute_type attr);
DFHACK_EXPORT int getMentalAttrValue(df::unit *unit, df::mental_attribute_type attr); DFHACK_EXPORT int getMentalAttrValue(df::unit *unit, df::mental_attribute_type attr);
DFHACK_EXPORT bool casteFlagSet(int race, int caste, df::caste_raw_flags flag); DFHACK_EXPORT bool casteFlagSet(int race, int caste, df::caste_raw_flags flag);
DFHACK_EXPORT bool isCrazed(df::unit *unit); DFHACK_EXPORT df::unit_misc_trait *getMiscTrait(df::unit *unit, df::misc_trait_type type, bool create = false);
DFHACK_EXPORT bool isOpposedToLife(df::unit *unit);
DFHACK_EXPORT bool hasExtravision(df::unit *unit);
DFHACK_EXPORT bool isBloodsucker(df::unit *unit);
DFHACK_EXPORT bool isMischievous(df::unit *unit);
DFHACK_EXPORT df::unit_misc_trait *getMiscTrait(df::unit *unit, df::misc_trait_type type, bool create = false);
DFHACK_EXPORT bool isDead(df::unit *unit);
DFHACK_EXPORT bool isAlive(df::unit *unit);
DFHACK_EXPORT bool isSane(df::unit *unit);
DFHACK_EXPORT bool isCitizen(df::unit *unit, bool ignore_sanity = false);
DFHACK_EXPORT bool isFortControlled(df::unit *unit);
DFHACK_EXPORT bool isDwarf(df::unit *unit);
DFHACK_EXPORT bool isWar(df::unit* unit);
DFHACK_EXPORT bool isHunter(df::unit* unit);
DFHACK_EXPORT bool isAvailableForAdoption(df::unit* unit);
DFHACK_EXPORT bool isOwnCiv(df::unit* unit);
DFHACK_EXPORT bool isOwnGroup(df::unit* unit);
DFHACK_EXPORT bool isOwnRace(df::unit* unit);
DFHACK_EXPORT bool isVisible(df::unit* unit);
/// is unit hidden to the player? accounts for ambushing
DFHACK_EXPORT bool isHidden(df::unit *unit);
DFHACK_EXPORT std::string getRaceNameById(int32_t race_id); DFHACK_EXPORT std::string getRaceNameById(int32_t race_id);
DFHACK_EXPORT std::string getRaceName(df::unit* unit); DFHACK_EXPORT std::string getRaceName(df::unit* unit);
@ -141,43 +182,6 @@ DFHACK_EXPORT std::string getRaceBabyName(df::unit* unit);
DFHACK_EXPORT std::string getRaceChildNameById(int32_t race_id); DFHACK_EXPORT std::string getRaceChildNameById(int32_t race_id);
DFHACK_EXPORT std::string getRaceChildName(df::unit* unit); DFHACK_EXPORT std::string getRaceChildName(df::unit* unit);
DFHACK_EXPORT bool isInvader(df::unit* unit);
DFHACK_EXPORT bool isBaby(df::unit* unit);
DFHACK_EXPORT bool isChild(df::unit* unit);
DFHACK_EXPORT bool isAdult(df::unit* unit);
DFHACK_EXPORT bool isAnimal(df::unit* unit);
DFHACK_EXPORT bool isEggLayer(df::unit* unit);
DFHACK_EXPORT bool isGrazer(df::unit* unit);
DFHACK_EXPORT bool isMilkable(df::unit* unit);
DFHACK_EXPORT bool isTrainableWar(df::unit* unit);
DFHACK_EXPORT bool isTrainableHunting(df::unit* unit);
DFHACK_EXPORT bool isTamable(df::unit* unit);
DFHACK_EXPORT bool isMale(df::unit* unit);
DFHACK_EXPORT bool isFemale(df::unit* unit);
DFHACK_EXPORT bool isVisiting(df::unit* unit);
DFHACK_EXPORT bool isMerchant(df::unit* unit);
DFHACK_EXPORT bool isDiplomat(df::unit* unit);
DFHACK_EXPORT bool isVisitor(df::unit* unit);
DFHACK_EXPORT bool isForest(df::unit* unit);
DFHACK_EXPORT bool isMarkedForSlaughter(df::unit* unit);
DFHACK_EXPORT bool isTame(df::unit* unit);
DFHACK_EXPORT bool isTrained(df::unit* unit);
DFHACK_EXPORT bool isGay(df::unit* unit);
DFHACK_EXPORT bool isNaked(df::unit* unit);
DFHACK_EXPORT bool isUndead(df::unit* unit, bool include_vamps = false);
DFHACK_EXPORT bool isGhost(df::unit *unit);
DFHACK_EXPORT bool isActive(df::unit *unit);
DFHACK_EXPORT bool isKilled(df::unit *unit);
DFHACK_EXPORT bool isGelded(df::unit* unit);
DFHACK_EXPORT bool isDomesticated(df::unit* unit);
DFHACK_EXPORT bool isDemon(df::unit* unit);
DFHACK_EXPORT bool isTitan(df::unit* unit);
DFHACK_EXPORT bool isMegabeast(df::unit* unit);
DFHACK_EXPORT bool isGreatDanger(df::unit* unit);
DFHACK_EXPORT bool isSemiMegabeast(df::unit* unit);
DFHACK_EXPORT bool isNightCreature(df::unit* unit);
DFHACK_EXPORT bool isDanger(df::unit* unit);
DFHACK_EXPORT double getAge(df::unit *unit, bool true_age = false); DFHACK_EXPORT double getAge(df::unit *unit, bool true_age = false);
DFHACK_EXPORT int getKillCount(df::unit *unit); DFHACK_EXPORT int getKillCount(df::unit *unit);

1450
library/modules/Units.cpp
View File

File diff suppressed because it is too large Load Diff