Dwarf Fortress Wiki - User contributions [en]

Talk:Advanced entity position mechanics

2026-05-26T18:01:43Z

Joostheger: /* Automatic creation of hist figure for expedition leader in vanilla (if site founded by army without hist figure) */

These lines contradict eachother:
* Premature succession works in fortress mode with landholders. If a unit gets a landholdersposition and that landholder is the appointer of an yet-empty position, which is defined as succeeding from a third one, then the succession is immediately applied. The landholder himself can even be the successor of a newly created position.
* A landholder's position is, in fortress mode, not successable by a site-position or visa versa.

Needs further investigation [[User:Joostheger|Joostheger]] ([[User talk:Joostheger|talk]])
----An interesting tidbit I did find, while validating some info for the variable positions (writing and running some Lua scripts for it): The FORCED_ADMINISTRATOR position of the dwarven civilization is actually used, eventhough I so far found only one instance (where the position was used). Interestingly the precedence was 100 (not 65) and was the only position of a site government belonging to a goblin civ. The site ruled was a Mountain Halls and most inhabitants were also dwarves. The other data in the position definition matched the raw-definition of the FORCED_ADMINISTRATOR (of the dwarven civ). So the token [CONQUERED_SITE] might mean that another civ conquering a site of a dwarven civ will (or might) use the forced administrator for governing that site (and not the other way round).[[Special:Contributions/91.49.240.46|91.49.240.46]] 21:10, 10 February 2026 (UTC)
----That is an interesting fact, but I doubt it still :-) My experience is that it just works. I think that FORCED_ADMINISTRATOR is also a generated position, used by other groups that have variable positions
[[User:Joostheger|Joostheger]] ([[User talk:Joostheger|talk]]) 08:50, 12 February 2026 (UTC)

---- Well I had to create a larger world (with 250 year history) to get a few variable positions. As it turns out a FORCED_ADMINISTRATOR is used by all mayor civs, that have positions, even the tree-huggers. The dwarfs have precedence 65 for the position and all other 100 (not checked everything for the FORCED_ADMINISTRATOR). And the goblins and humans can have other site positions created afterwards, the human can even upgrade create a CUSTOM_LAW_MAKER_2 afterwards. All other vanilla races (elves and dwarves) will not get other site positions with a FORCED_ADMINISTRATOR.
ps. And yes this means that the assumption concerning the meaning of [CONQUERED_SITE] token is wrong.[[Special:Contributions/91.49.240.46|91.49.240.46]] 09:04, 12 February 2026 (UTC)

In addition: The FORCED_ADMINISTRATOR position can appoint other positions, at least if these positions are variable and created afterwards (and the civ has variable positions). But the FORCED_ADMINISTRATOR will not appoint a CUSTOM_MILITARY_STRATEGY position, if the CUSTOM_MILITARY_GOALS position was created (before the creation of the CUSTOM_MILITARY_STRATEGY position), in that case the CUSTOM_MILITARY_STRATEGY position did appoint by the CUSTOM_MILITARY_GOALS position holder. This is probably due to the higher precedence of the CUSTOM_MILITARY_GOALS position in comparison to the FORCED_ADMINISTRATOR. I do need to check the high precedence CUSTOM_OFFICIALs though, whether the reason might be something else other than precedence.[[Special:Contributions/91.49.240.46|91.49.240.46]] 10:23, 12 February 2026 (UTC)

== Possible vanilla Dwarven Civ landholder residence sites ==

It seems that in world-gen a dwarven civilization can make a town a land holder residence (a hamlet has not been found so far). This is rare. The only other sites a vanilla dwarven civ will consider a land holder residence is a (dwarven) Fortress - Hillocks or Mountain Halls will never be considered a land holder residence. These rare cases are related to a site being considered a "land for holding" and "central holding land" by a human civilization (which can only be hamlets or towns) - see note about the name baron (in the article Variable Positions). I have not yet figured out, if such a site after being taken over by a dwarven civ, if it is a town (and not a hamlet), will always be considered a land holder residence or only in some cases. Of course the town would need to be considered a land for holding by a human civ before the take over by a dwarven civ.

BTW: I am not sure, where this tidbit of information does belong (this page, the variable positions page or the noble page, after adding a section about world-gen). As the above ie. implies also something about modded civilizations with landholders (or using some certain variable positions).[[Special:Contributions/87.143.66.20|87.143.66.20]] 03:41, 3 April 2026 (UTC)

Correction: Slightly misread the script output (if two flags are true for dwarven civs in site entity links between a site and the entity of the civ, then the central holding land is missing and not the land holder residence flag). So also other sites can become a land holder residence, but the only non Fortress sites, which can receive all three flags ("land holder residence", "central holding land" and "land for holding") are towns. And this is indeed tied to the above (a human civ considering a town a central holding land and land for holding).[[Special:Contributions/87.143.66.20|87.143.66.20]] 04:09, 3 April 2026 (UTC)

----
Thank you for the insights. I believe that a site can get a landholder, if it has enough other sites economicly linked to them. There are mentions in the old devlogs about this. I think that any type of site (town, fortress, deep fortress, tree city) can become a landholders seat, because the economic system is generic for all kinds of sites.
When a market is build in a hamlet, it becomes a town. and when enough wealth is exported and generated, sites become economicly linked to them. And that triggers the elevation of that site to which it can have a landholder.
So, when I site has all the prerequisits for getting a landholder, it doesn't matter of which type of civ that landholder is. It may be a raw-defined dwarven baron, or a generated human baron-lord.
[[User:Joostheger|Joostheger]] ([[User talk:Joostheger|talk]]) 08:57, 3 April 2026 (UTC)

== Automatic creation of hist figure for expedition leader in vanilla (if site founded by army without hist figure) ==

In vanilla, if a site of a dwarven civilization is founded by the game during fortress mode and the army founding the site (and subsequentially settling at the site) lacks any hist figure, then the game will create a history figure on the spot to fill the expedition leader position (at least if any sentinent abstract population, eg. dwarves, were part of the army - I did not test any shenanigans without any abstract populations or with only pack animals etc. as hist figures in the site founding army). I am not sure if this implies, that for any modded civilization which has site positions, also in such cases a history figure to fill a certain position will be created (or if in such cases all positions will for the time being stay emtpy, until some hist figures settle there).[[Special:Contributions/91.49.252.253|91.49.252.253]] 16:13, 26 May 2026 (UTC)

Thank you for your contribution! As far as i understand it, its works like this: new location > new government entity > new positions. no histfig for a position > create one.
This means that this works not only for the exleader, but for any position that at some point needs to be filled. [[User:Joostheger|Joostheger]] ([[User talk:Joostheger|talk]]) 18:01, 26 May 2026 (UTC)

Noble

2026-05-22T07:28:36Z

Joostheger: /* Nobles in other civilizations */

{{Quality|Exceptional}}
{{av}}
[[File:noble_icon_preview.png|right]]
{{Translation
| dwarven = rîthol
| elvish = ramu
| goblin = dösta
| human = hal}}
'''Nobles''' and '''administrators''' are [[Dwarf|dwarves]] elevated to a position of rule over your fortress. Administrators perform a useful, specific task or duty unique to their position, such as [[Manager|managing work orders]], [[Broker|trading with merchants]], [[Militia commander|commanding military positions]], or even [[bookkeeper|stocks recording]]. An [[expedition leader]] or a [[mayor]] provides a critical happiness bonus to unhappy and [[stress|stressed]] dwarves, who will yell at or cry on "someone in charge", and is also responsible for interacting with [[outpost liaison|outpost liaisons]].

Certain offices are automatically [[elected]] by your fortress's citizenry, rising to ranks mostly outside of the player's control, while most administrators can be directly appointed by the player, and can be promoted, demoted and replaced at any time. Administrators are colloquially known as "utility nobles", and internally both are a type of [[position token|position]].

Developed fortresses are offered the privilege of elevating a dwarf to a noble title, allowing the dwarven [[caravan]] the luxury of trading with high-capacity [[wagon|wagons]]. This is an optional victory goal of [[Fortress mode]], and a fortress that chooses this path and produces enough wealth will see their chosen noble climb the echelons of society, all the way to attracting the reigning [[monarch]].

Higher-rank office-holders, such as nobles and the [[mayor]], can make [[demand|demands]] and set legally-binding [[mandate|mandates]], which, if not met, will upset them, such that they will punish your dwarves for "oath-breaking" if the fortress has an active [[justice]] system. They are also well-aware of their social statuses and often want expensive, well-furnished [[Zone#Quality_and_value|room]]s and other personal possessions, such as [[cabinet]]s and [[armor stand]]s, and some of them are pretentious and do not want a lower-rank dwarf to have a better room than them.

If a noble is too much of a problem and cannot be fired, it may be possible to arrange an [[unfortunate accident]] for them. Be careful, though, the death of a leader, especially a popular one like an elected [[mayor]], may cause grief among the general populace, and may have additional consequences due to how leaders are chosen. Hereditary noble titles are not succeeded by dwarves in your fortress. A fortress lacking a mayor or an expedition leader will be temporarily unable to appoint new administrators manually until a new dwarf takes office.

It is possible for some of your dwarves to hold noble titles over other [[Site|sites]] in the [[Civilization#Mountain|dwarven kingdom]]. These dwarves are still capable of issuing mandates in your fort, however, and demand the same sort of privileged treatment as any other noble. There is no further benefit to having multiple land-holders, so in the event you happen to have multiple [[baron]]s or similar, it may be more productive to [[unfortunate accident|remove]] the noble whose title is not linked to your fortress in order to avoid the unnecessary hassle with mandates and demands. Note that office-holders, whether elected or appointed, cannot be peacefully [[Emigration|exiled]], as they are presumably in charge of the emigration orders in the first place.

Outside your fortress, positions such as the [[general]] and [[outpost liaison]] are also types of administrators that attend to national affairs, answering to the [[monarch]] of each dwarven civilization. [[Human|Humans]], [[Elf|elves]] and [[goblin|goblins]] have nobles of their own, with some of the positions of their [[civilization|civilizations]] being exclusive to them, such as human law-giver and elven [[druid|druids]]. Humans and goblins are able to procedurally generate their government during world generation, with law-making officials able to create new positions for any number of reasons. While civilized, [[kobold|kobolds]] and subterranean [[animal people]] have no need for nobles or organized governments.

== Menu ==
[[File:Nobles v50.png|thumb|right|500px| The nobles and administrators menu {{menu icon|n}}, displaying a variety of positions. Those with room requirements are fulfilled, while the Mayor has a pending mandate.]] The '''Nobles and administrators''' menu, opened with {{menu icon|n}} menu button, contains a list of the noble and [[administrator]] positions of your settlement. At the top is a description section, which may change to provide detail when hovering over different elements.

Each list entry contains the following columns (from left to right):
* The name of the position or the land name (like barony), with the name of the related squad below, if applicable.
* Button to change the current holder of the position, if applicable.
* An image of the current holder of the position, if there is one.
* The [[name]] and [[Labor|profession]] of the current holder of the position (usually their profession is the position title), or {{DFtext|VACANT|6:1}} or {{DFtext|NEW|6:1}} if there is none.
* Button to give symbols to the noble. This gives the position holder an item, which is given a name at this time if it did not already have one.
* The current and required [[Office|Study/Throne Room]], [[Bedroom]], [[Dining Room]], [[Tomb]], and [[Building|Furniture]] for the position.
* Any [[Mandate|mandates]] set by the noble.
* For the [[bookkeeper]], the desired [[stocks]] display precision.

== Triggers ==
An [[expedition leader]] will be automatically selected at embark. With an expedition leader, the following positions can be assigned: [[bookkeeper]], [[broker]], [[chief medical dwarf]], [[hammerer]], [[manager]], [[militia commander]], and [[sheriff]]. With a militia commander, [[militia captain]]s can be assigned to lead other [[squad]]s.

Once the fortress population reaches 50, a [[mayor]] will be automatically elected (replacing the expedition leader). Once a mayor has been elected, the [[captain of the guard]] (replacing the sheriff) and [[dungeon master]] positions can also be assigned, in addition to those available with an expedition leader.

Landholding nobles have triggers defined in the [[Difficulty#Land_holder|difficulty settings]]. The default requirements are listed below.

*'''Population''' - Minimum population required for this position to become available.
*'''Created Wealth''' - Minimum created wealth for this position to become available.
*'''Exported Wealth''' - Minimum exported wealth for this position to become available.

{| class="sortable wikitable" style="text-align:center;"
|- style="background:#F2F2F2;"
! '''Land Holder'''
! '''Population'''
! '''Created Wealth'''
! '''Exported Wealth'''

|-
! [[Baron]]
| 20
| 100k
| 10k
|-
! [[Count]]
| 20
| 200k
| 20k
|-
! [[Duke]]
| 20
| 300k
| 30k
|}

The [[general]] arrives alongside the [[monarch]] (except when a fortress citizen or resident inherits the monarchy{{bug|11717}}).

== Needs ==
Below are the room demands made by each position. For details on room values see: [[Zone#Quality_and_value|Zone quality and value]]. It also lists the number of chests, cabinets, weapon racks, and armor stands they demand. Finally, it shows the maximum number of [[demand]]s and [[mandate]]s they can issue at any given point.



{| class="sortable wikitable" style="text-align:center;"
|- style="background:#F2F2F2;"
!Position!!Quarters!!Dining Room!!Office!!Tomb!!Chests!!Cabinets!!Racks!!Stands!!Demands!!Mandates

|-
![[Baron]]
|bgcolor="#FFBA50"|4Decent Quarters
|bgcolor="#FFBA50"|4Decent Dining Room
|bgcolor="#FFBA50"|4Decent Office
|bgcolor="#FFBA50"|4Tomb
|2
|1
|1
|1
|2
|1

|-
![[Bookkeeper]]
|0—
|0—
|bgcolor="#FFFF50"|1Meager Office
|0—
|0—
|0—
|0—
|0—
|0—
|0—

|-
![[Broker]]
|0—
|0—
|0—
|0—
|0—
|0—
|0—
|0—
|0—
|0—

|-
![[Captain of the guard|Captain of the Guard]]
|bgcolor="#FFCC50"|3Quarters
|bgcolor="#FFCC50"|3Dining Room
|bgcolor="#FFCC50"|3Office
|0—
|1
|1
|1
|1
|0—
|0—

|-
![[Champion]]
|0—
|0—
|0—
|0—
|0—
|0—
|0—
|0—
|1
|0—

|-
![[Chief medical dwarf]]
|0—
|0—
|0—
|0—
|0—
|0—
|0—
|0—
|0—
|0—

|-
![[Count]]
|bgcolor="#FF9050"|6Great Bedroom
|bgcolor="#FF9050"|6Great Dining Room
|bgcolor="#FF9050"|6Throne Room
|bgcolor="#FF9050"|6Mausoleum
|3
|2
|2
|2
|3
|2
|-
![[Diplomat]]
|bgcolor="#FF9050"|6Great Bedroom
|bgcolor="#FF9050"|6Great Dining Room
|bgcolor="#FF9050"|6Throne Room
|0—
|3
|2
|2
|2
|3
|0—
|-
![[Duke]]
|bgcolor="#FF7850"|7Grand Bedroom
|bgcolor="#FF7850"|7Grand Dining Room
|bgcolor="#FF7850"|7Opulent Throne Room
|bgcolor="#FF7850"|7Grand Mausoleum
|5
|3
|3
|3
|5
|3
|-

![[Dungeon master]]
|bgcolor="#FFCC50"|3Quarters
|bgcolor="#FFCC50"|3Dining Room
|bgcolor="#FFCC50"|3Office
|0—
|1
|1
|1
|1
|0—
|0—

|-
![[Expedition leader]]
|0—
|0—
|0—
|0—
|0—
|0—
|0—
|0—
|0—
|0—

|-
![[General]]
|bgcolor="#FFCC50"|3Quarters
|bgcolor="#FFCC50"|3Dining Room
|bgcolor="#FFBA50"|4Decent Office
|bgcolor="#FFFF50"|1Grave
|2
|1
|3
|3
|2
|0—

|-
![[Hammerer]]
|0—
|0—
|0—
|0—
|0—
|0—
|0—
|0—
|0—
|0—

|-
![[Manager]]
|0—
|0—
|bgcolor="#FFFF50"|1Meager Office
|0—
|0—
|0—
|0—
|0—
|0—
|0—

|-
![[Mayor]]
|bgcolor="#FFBA50"|4Decent Quarters
|bgcolor="#FFBA50"|4Decent Dining Room
|bgcolor="#FFBA50"|4Decent Office
|0—
|2
|1
|1
|1
|2
|1

|-
![[Militia captain]]
|0—
|0—
|0—
|0—
|0—
|0—
|0—
|0—
|0—
|0—

|-
![[Militia commander]]
|0—
|0—
|0—
|0—
|0—
|0—
|0—
|0—
|0—
|0—

|-
![[Monarch]]
|bgcolor="#FF5E40"|8Royal Bedroom
|bgcolor="#FF5E40"|8Royal Dining Room
|bgcolor="#FF5E40"|8Royal Throne Room
|bgcolor="#FF5E40"|8Royal Mausoleum
|910
|5
|5
|5
|910
|5

|-
![[Outpost liaison]]
|bgcolor="#FF9050"|6Great Bedroom
|bgcolor="#FF9050"|6Great Dining Room
|bgcolor="#FF9050"|6Throne Room
|0—
|3
|2
|2
|2
|3
|0—

|-
![[Sheriff]]
|bgcolor="#FFEA50"|2Modest Quarters
|bgcolor="#FFEA50"|2Modest Dining Room
|bgcolor="#FFEA50"|2Modest Office
|0—
|1
|1
|1
|1
|0—
|0—

|}

== Notes ==
This shows various notes for each position taken from the [[raws]].

*'''#''' - lists whether one or more dwarves can have this position. Duke/Count/Baron don't have a number listed, but each fortress can only have one.
*'''Squad''' - Lists the number and type of dwarf that this position leads.
*'''Spouse''' - The noble's spouse is also considered a noble, being called "[noble] [[consort]]". No (functional) privileges are attached to them, except of course the fact that they share the rooms with their spouse.
*'''Heir''' - Is this individual replaced by an heir when they die?
*'''Appointed By''' - Which position appoints this person initially? Note that the player actually controls all appointments via the nobles screen; this is, in effect, only which dwarf is ''necessary'' before the player can make the appointment. Barons aren't directly appointed but elevated (presumably by the Mountainhome) upon recommendation of the player. They cannot be replaced via the {{k|n}}obles screen. Once a baron/countess/duke dies, the outpost liason will not offer elevation again. There is no guarantee your fortress will receive a successor, either.
*'''Replaced By''' - What position replaces this one?
*'''Pop Req''' - Minimum population required for this position to become available. For the Baron, Count, and Duke these values come from the [[Position_token#LAND_HOLDER|land holder]] [[difficulty]] settings instead of the raws.
*'''Wealth Req''' - Minimum created & exported wealth (respectively) for this position to become available.
*'''Elected''' - Is this dwarf elected?
*'''Lazy''' - Such nobles won't do any regular [[labor]]s aside from pulling [[lever]]s, deconstructing [[wall]]s, and some other things. Currently non-functional, so "lazy" nobles can still be assigned to perform any labor.
*'''Immunity''' - Immune dwarves aren't punished for any crimes.
*'''Econ Exempt''' - These dwarves don't need money to pay for goods or rooms after the [[economy]] arrives. Due to the economy currently being disabled, this privilege goes unused for now.
*'''Military Screen Only''' - This position is only listed on the military screen.
*'''Jealous''' - These dwarves will become [[thought|upset]] if their rooms are not better than those of "lesser" dwarves. They don't have to see the rooms to become upset, since they somehow just know such rooms exist. Positions are sorted by their precedence in the nobles screen, with more important dwarves sorted above lower ranks.

{| class="sortable wikitable" style="text-align:center;"
|-
! '''Position'''
! width=5% | '''#'''
! '''Squad'''
! width=5% | '''Spouse'''
! width=5% | '''Heir'''
! '''Appointed By'''
! '''Replaced By'''
! width=5% | '''Pop Req'''
! width=7% | '''Wealth Req'''
! width=5% | '''Elected'''
! '''Lazy'''
! width=5% | '''Immunity'''
! width=5% | '''Econ Exempt'''
! width=5% | '''Military Screen Only'''
! '''Jealous'''

|-
! Baron
| -
| -
| Yes
| Yes
| Monarch
| Count
| 20
| 100k / 10k
| -
| Yes
| Yes
| Yes
| -
| Yes

|-
! Bookkeeper
| 1
| -
| -
| -
| Exp.Leader/Mayor
| -
| -
| -
| -
| -
| -
| -
| -
| -

|-
! Broker
| 1
| -
| -
| -
| Exp.Leader/Mayor
| -
| -
| -
| -
| -
| -
| -
| -
| -

|-
! Captain of the Guard
| 1
| 10:Fortress Guard
| -
| -
| Exp.Leader/Mayor
| -
| 50
| -
| -
| -
| -
| Yes
| -
| -

|-
! Champion
| 1
| -
| -
| -
| Duke/Count/Baron
| -
| -
| -
| -
| Yes
| Yes
| Yes
| -
| -

|-
! Chief Medical Dwarf
| 1
| -
| -
| -
| Exp.Leader/Mayor
| -
| -
| -
| -
| -
| -
| -
| -
| -

|-
! Count
| -
| -
| Yes
| Yes
| Monarch
| Duke
| 20
| 200k / 20k
| -
| Yes
| Yes
| Yes
| -
| Yes
|-
! Diplomat
| 1
| -
| -
| -
| Monarch
| -
| -
| -
| -
| Yes
| Yes
| Yes
| -
| Yes
|-
! Duke
| -
| -
| Yes
| Yes
| Monarch
| -
| 20
| 300k / 30k
| -
| Yes
| Yes
| Yes
| -
| Yes

|-
! Expedition Leader
| 1
| -
| -
| -
| -
| Mayor
| -
| -
| -
| -
| -
| Yes
| -
| -

|-
! General
| 1
| 10:Soldier
| -
| -
| Monarch
| -
| -
| -
| -
| Yes
| Yes
| Yes
| -
| Yes

|-
! Hammerer
| 1
| -
| -
| -
| Exp.Leader/Mayor
| -
| -
| -
| -
| Yes
| Yes
| Yes
| -
| -

|-
! Manager
| 1
| -
| -
| -
| Exp.Leader/Mayor
| -
| -
| -
| -
| -
| -
| -
| -
| -

|-
! Mayor
| 1
| -
| -
| -
| -
| -
| 50
| -
| Yes
| -
| -
| Yes
| -
| -

|-
! Militia Captain
| 1+
| 10:Militia-dwarf
| -
| -
| Militia Commander
| -
| -
| -
| -
| -
| -
| -
| Yes
| -

|-
! Militia Commander
| 1
| 10:Militia-dwarf
| -
| -
| Exp.Leader/Mayor
| -
| -
| -
| -
| -
| -
| -
| -
| -

|-
! Monarch
| 1
| -
| Yes
| Yes
| [[Armok]] himself
| -
| -
| [[Monarch|It's complicated]]
| -
| Yes
| Yes
| Yes
| -
| Yes

|-
! Outpost Liaison
| 1
| -
| -
| -
| Monarch
| -
| -
| -
| -
| Yes
| Yes
| Yes
| -
| Yes

|-
! Sheriff
| 1
| -
| -
| -
| Exp.Leader/Mayor
| Captain of the Guard
| -
| -
| -
| -
| -
| Yes
| -
| -

|}


==Appointing Administrators==
Appointed positions are chosen by the player via the nobles and administrators menu {{menu icon|n}} (representing them being appointed by higher-ranking leaders; see below). There are certain [[skill|skills]] that are relevant for each administrator's responsibilities, and not all dwarves will gain experience in the given skill. Some dwarves will never gain experience in certain [[social skill|social skills]], this is determined by each dwarf's personal traits, and it is therefore important to select the dwarf with the appropriate set of [[Personality facet|traits]] for each position.

When choosing a dwarf to assign to a position, the list of choices is sorted by the skill relevant to the job. This is ''especially'' important when appointing administrators.

*Military leaders ([[Captain of the guard|captains of the guard]], [[militia commander]]s, and [[militia captain]]s) use the [[leader]] and [[military tactics]] skills, among others.

*[[Manager|managers]] use the [[organizer]] skill.

*[[Chief medical dwarf|Chief medical dwarves]] are usually appointed based on their qualifications as a [[diagnostician]], though of course you need more than just diagnosis for a functional [[hospital]].

*[[Broker|brokers]] most critically use the [[judge of intent]] and [[appraiser]] skill, with other [[social skill|social skills]] moderately useful in negotiating deals.

*[[Bookkeeper|bookkeepers]] have their very own [[record keeper]] skill.

In-universe, when you appoint a leader, the new orders don't just descend from on high - instead, a higher-ranking official will actually appoint someone to the position. All appointed positions aside from the militia captain are appointed by the [[expedition leader]], or the [[mayor]] that replaces them when your fort's population reaches a certain point. [[Militia captain]] positions are instead appointed by the [[militia commander]], and the commander must return from any [[mission|missions]] before any appointments can be made. If your fort doesn't have the relevant higher-ranking official [[fun|for some reason]], you can't appoint certain positions until they are replaced.

= General nobility mechanics =
The nobles in your own fortress, your civilization, as well as other types of civilizations use a standardized set of mechanics. These may be seen in the [[elves]], [[humans]] or [[goblins]] or in [[Entity token|modded civilizations]].

== Nobles in other civilizations ==
''Main article:'' [[Advanced Entity Position Mechanics]]

There are two basic kinds of nobles: civ-level and site-level. Positions with the {{token|SITE|po}} tag are site-level, those without it are civ-level. These types of nobles can be regarded as separate systems. There is however some limited interaction possible: civ-level nobles can appoint site-level positions. They cannot succeed, or be replaced by site-level positions, and vice versa.

Outside of Fortress mode, the game will always attempt to assign nobles whenever possible (except for those with {{token|NUMBER|po|AS_NEEDED}}). So the rules for when nobles appear are controlled by the tags which limit them.

* Nobles with {{token|APPOINTED_BY|po|position}}require a noble of the designated position.
* Nobles with {{token|REQUIRES_POPULATION|po}} require the population to have a specific size.
* Nobles with {{token|REQUIRES_MARKET|po}} will only appear in "large" sites (which may have different rules for different site types). A player fortress is always considered as having a market, thus this requirement is fulfilled.

Positions that have no requirements will automatically be assigned to a random civ member when a new site/civ is created. In worldgen, there is no functional difference between {{token|ELECTED|po}} and having no appointment rule except that [[elected]] nobles tend to have high social skills and/or skills related to the position, while non-elected ones are assigned randomly.
If a noble dies or advances to a new position via succession, the position will be granted to another unit based on the {{token|SUCCESSION|po}} tag. If they have an heir or the position exists, the unit will be assigned. If not, a new one will be appointed according to the usual rules.
It is possible to assign multiple levels of {{token|SUCCESSION|po|BY_POSITION}}, creating a line of positions where the death of one causes all those "below" them to advance.

{{token|REPLACED_BY|po|position}} means that once the replacing position is available, the current position will disappear. As mentioned, site-level and civ-level positions are completely separate; a site position cannot be replaced by a civ-level one or vice versa. Only for replacement in the landholders-chain is the current holder promoted to the next position.

These rules are mostly followed in worldgen. It is possible to cause civs and individual sites to change their behavior substantially when they reach a certain size by controlling nobles. For example, if a site can only appoint a position with {{token|MILITARY_GOALS|po}} after reaching a particular size, that site will not send armies on missions until the required size is reached.

Another interesting point is that a civ-level {{token|LAW_MAKING|po}} position is required for the civilization to have any kind of cohesion. Without it, sites will be constantly embroiled in territorial disputes and civil wars will be commonplace.

== Landholders and Positions ==
''Main article:'' [[Position_token#Why won't my positions appear?|Why won't my positions appear?]]

The way DF determines what positions will actually appear in your fortress is somewhat counter-intuitive and fairly limiting. This guide should help you understand what you can do to actually get your positions working properly.

There are five tokens governing which positions appear in your fortress - {{token|LAND_HOLDER|po}}, {{token|REQUIRES_POPULATION|po}}, {{token|APPOINTED_BY|po}}, {{token|ELECTED|po}}, and {{token|REPLACED_BY|po}}. The first two determine when your fortress is eligible for a new position, the next two determine how a new position for which your fortress is eligible can be added, and the fifth allows you to clear up obsolete positions. Unfortunately, they also interact in some strange ways that makes creating interesting position structures difficult.

When you start a new fortress, DF compiles a list of your initial positions. To do this, it looks at the requirements for each position - any position whose only requirement is less than seven dwarves (either because they have no requirement tokens, or because their only requirement tokens are [REQUIRES_POPULATION: =< 7] or [LAND_HOLDER:some trigger whose only requirement is some number of dwarves equal to or less than 7]). Most importantly, any position whose only requirement is a [LAND_HOLDER] requirement, regardless of what the trigger for that requirement is, will be added if another eligible starting position is [REPLACED_BY] it. A non-[LAND_HOLDER] position that is [REPLACED_BY] a [LAND_HOLDER] position will never appear. With this list compiled, the game culls all positions that are [REPLACED_BY] another eligible position, and then culls all positions that have the [APPOINTED_BY] token. You may not embark with any appointed positions. Any remaining positions are then filled by a dwarf chosen at random.

Positions do not automatically appear when you reach their requirements. For example, if you remove the [ELECTED] token from the Mayor, then the Mayor will never appear, even once you reach their required number of dwarves. For a position that does not appear at embark to appear in your fortress, it must be [APPOINTED_BY] another position or [ELECTED].

Naturally, this is more complicated than it looks. [APPOINTED_BY] positions must be appointed by another position already in your fortress, or a civ-level position. Only [LAND_HOLDER] positions may be appointed by civ-level positions. [LAND_HOLDER] positions that are [APPOINTED_BY] civ-level positions are inherently tied to civ-level tokens with the ESTABLISH_COLONY_TRADE_AGREEMENTS responsibility.
{{old|v=50.01}}
If a fortress meets the [LAND_HOLDER_TRIGGER] for a new [LAND_HOLDER] tier when a caravan leaves, then the next time the outpost liaison or equivalent arrives, they will offer to make you an official colony, which will allow you to select all positions for that [LAND_HOLDER] level. Each time they appear, the outpost liaison will only promote your fortress one tier up the [LAND_HOLDER] track. The biggest problem with this system is that you may set your [LAND_HOLDER_TRIGGERS] such that you are eligible for the first tier of [LAND_HOLDER] positions at embark. If you are eligible for the first tier of [LAND_HOLDER] positions at embark, then all first-tier positions will appear twice - once at embark, and again when the outpost liaison comes to appoint you to the first tier.

==Bugs==
* Nobles may have impossible [[demand]]s, like cardinal leather items or metal beds. {{Bug|944}} (Feel free to arrange an [[unfortunate accident]] for the idiot in question) While no dwarves will get punished for not producing these items, it may enrage the noble.
* If your fort is unable to find a replacement for a noble, that noble will never be reappointed. {{bug|5299}}
* New mayors and expedition leaders will be elected / "appointed by the monarch" after some time, but it might take a while, and in the meantime, you won't be able to appoint certain nobles. {{bug|8129}}

===Selecting Squads which contain Nobles===
The [[Monarch]], [[Baron]], [[Count]] and [[Duke]] cannot be assigned as military commander, because of their succession-rules.

Here's a link to the DF forum, where some SCIENCE on Nobles in Squads has been conducted.
http://www.bay12forums.com/smf/index.php?topic=113639.msg3467517#msg3467517

{{D for Dwarf}}
Although <s>all</s> many players <s>often</s> constantly get <s>angry</s> murderously mad at nobles, wiser players simply thank their lucky stars that [[main:Armok|Armok]] never created congressdwarves.
[[File:Jacques Callot, Noble Woman with Large Collar, c. 1620-1623, NGA 36864.jpg|thumb|250px|center|A human noble from times past. Jacques Callot (1620-1623)]]
{{Nobles}}
{{Template:V50 entities}}
{{V50 menus}}
{{Category|Fortress mode}}
{{Category|Interface}}
{{Category|Nobles}}

Advanced entity position mechanics

2026-04-28T21:01:51Z

Joostheger: /* Non-working triggers */

{{Quality|Fine}}
{{Modding}}

= Introduction =

[http://www.bay12forums.com/smf/index.php?topic=182239.0 Discussion thread on the forum]

This page documents observed and tested behavior of entity positions in Dwarf Fortress that is not fully described elsewhere on the wiki. It focuses on advanced interactions between position tokens, including appointment, succession, election, and responsibility handling, across both civilization-level and site-level entities.

The mechanics described here are based on empirical testing in world generation and fortress mode, supplemented where necessary by raw analysis. In several cases, the game’s behavior is determined by evaluation order and interaction between multiple tags, rather than by individual tokens in isolation.

This page is intended for modders and advanced players who are designing or debugging custom entity position structures. It does not restate basic position mechanics, but instead highlights edge cases, non-obvious interactions, and behaviors that may appear inconsistent or undocumented.

Unless stated otherwise, the described behavior applies to current versions of the game and may differ from older releases.

==What is an entity? What is a position?==
An [[entity]] is an organizational structure that can have relationships with other entities, usually known as a [[civilization]] or a "[[site]] government" in the game, but ie. merchant [[company|companies]], [[Mercenary#Mercenary_Orders|mercenary orders]], [[guild|guilds]], [[religion|religious organizations]], bandits and necromancer towers are also entities (and necromancer towers use the same entity type as "site governments"). An entity can have positions - in most cases, these are hardcoded and generated by the game, but as for civilizations and sites, the [[raw file]]s can be customised.

A position is a special relationship between a unit and an entity. The unit holding a position has a larger influence over that entity than other citizens. Positions are mostly known as [[nobles]], but in this article. the technical term is used.

=Position levels (Site/Civ) and their interaction=
There are two basic types of positions that are customizable: '''civ(ilization)''' level and '''site level'''. Positions with the tag [SITE] are at site level, positions without the tag [SITE] are at 'civ level'. These two types of nobles can be considered '''loosely related systems'''. There are a few places where they can interact with each other.

Civ-level positions are in charge of the civilization as a whole, managing national [[trade]], laws, and [[war]]s. These are, for example, the vanilla [[monarch]], [[diplomat]] and [[general]]. (Note that the general doesn't really do anything, except creation of additional pets in world-gen for the general and possibly raising the animal training knowledge of the civilization to "general familiarity".)

'''[LAND_HOLDER]''' nobles are also positions at civ-level. These units are members of the national government, but have gained authority over some land or site. Once they do, they move to that place, but their position is still regarded as a civ-level position.

Site-level position holders are members of a site government (subsidiary to the civilization), and manage local affairs in that location. These are, for example, the [[mayor]], the [[sheriff]] and the [[broker]].

==Table of interaction between different position levels==
In this table, the possible interactions between different position levels are summarized.
The header row shows the positions defining the tokens.

The left column shows the position type that is referred to.
Example:
{| {{prettytable}}
|- bgcolor="#ddd"
! referred position-type
! LAND_HOLDER
|-
| civilization
| (baron is) APPOINTED_BY:MONARCH
|}
color coding: 
* Exists in vanilla
* Possible with mods
* Not possible
* possible to some extent.
* not yet fully investigated.
{| {{prettytable}}
|- bgcolor="#ddd"
! referred position-type
! Civilization
! SITE
! LAND_HOLDER
! CONQUERED_SITE

|-
| Civilization
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION '''(1)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION

|-
| SITE
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION '''(2)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY '''(3)''' COMMANDER REPLACED_BY SUCCESSION '''(4)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION

|-
| LAND_HOLDER
| APPOINTED_BY COMMANDER REPLACED_BY '''(6)''' SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION '''(5)'''
| APPOINTED_BY COMMANDER REPLACED_BY '''(7)''' SUCCESSION '''(8)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION

|-
| CONQUERED_SITE
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
|}

Remarks:
# Works only in world-gen, if a unit with that civ-position is present at the site.
# Works only in world-gen, the site-position holding unit will then move to the capital.
# Is completely ignored
# Works only in world-gen.
# Works only in world-gen.
# Won't appear at all
# This is necessary for the landholder chain to work properly, it doesn’t work otherwise.
# This works only outside of the landholder chain, so when landholders are simply regarded as civ-level nobles. might also work in world-gen
#

== Other interactions ==

Unfortunately, interactions with positions of other entities don't seem possible, such as APPOINTED_BY: HIGH_PRIEST. With [VARIABLE_POSITIONS], positions are automatically created with codes like CUSTOM_LAW_MAKER_2, but interaction with these positions don't seem to work, either. For more info on those, see [[Variable positions]]

=General=

==Civ-level nobles living at your site==
Nobles from your civilization can come to live at your fortress. This happens in vanilla with landholders such as [[Baron]], [[Count]] and [[Duke]], with the Monarch, but sometimes also with non-landed LAND_HOLDERS.

When a civ-level noble becomes a [[citizen]] at your location, their position is shown among the site-level positions in your [[nobles screen]]. They appear to function as a site-level noble. They may have [[demand]]s, [[mandate]]s, [[squad]]s and the like. They can appoint nobles at the site-level.

Even if they have certain site related [RESPONSIBILITY]ies, they will not do the tasks that go with them.

==Fortress mode, world-gen and their differences==
Their are a few differences in how positions function between fortress mode (normal play mode) and the world generation (world-gen).

In '''fortress mode''', the player has some control over the appointment of nobles, limited by elections, automatic filled-in positions and succession rules. Pre-fortress mode, which is referred to as '''world-gen''', the game will always attempt to assign nobles whenever possible. It is subjected to the same rules as in fortress-mode, but there are some exceptions. In '''[[World activities]]''', which is the thing that happens in the world while you play fortress mode, it seems as if the same rules are applied as fortress mode.

A difference between player-fortress-mode and world-gen, is causes by visibility (see below). Positions that are not visible by the player and thus not available for assignment, will be available in world-gen and will thus be automatically assigned.

In fortress mode, a position that is both [ELECTED] and [APPOINTED_BY], cannot be appointed by the player and is also not elected, and can thus not be filled. But in world-gen sites however, these positions are automatically filled.

Positions with [AS_NEEDED] are almost never created and filled in world-gen (depending on their [RESPONSIBILITY]ies), but can always be used in player mode.

A position can, in fortress mode, be filled by the same unit. A unit can gain multiple positions in fortress mode, for example because of [[elections]]. This will not happen in world-gen mode: a unit can only have one position. See also remarks on 'embark' and 'Losing a position'.

In world-gen, [SUCCESSION] between civ-levels and [SITE-]levels may happen. This will not happen in fortress mode, or even off-site in [[World activities]].

In fortress mode, premature SUCCESSION may happen. This will not happen in world-gen mode.

==Units holding multiple positions in multiple entities==
A unit can hold multiple positions in its civilisation or in its site-entity, however in world-gen a unit will not hold multiple positions in one site-entity or in one civilisation (note that in world-gen a unit can hold multiple variable positions of the same entity, if the entity is ie. an outcast group). It is however possible - in world-gen - for a unit to hold multiple positions as long as the positions belong to different civilizations / site-entities (ie. it is possible for a militia commander of a site-entity to later on also become a monarch of the parent civilization, while staying a militia commander), if a unit holds a position of two different site-entities (the unit will usually have left one of the groups, without relinquishing the position). Only at player-managed sites can units be holding multiple positions (of the site-entity) at once. It is currently unknown, whether it is possible in world-gen for a unit to have a civ-level position in two different civilisations (but it probably is possible, as a a unit can belong to multiple civilizations and a unit usually does not relinquish a position, when the unit gets another position, as long as the entities of both positions are not the same).

In world-gen, if there are too many positions to be filled, they simply stay empty until more units are available. E.G, a unit at a site might inherit a civ-level position and still remain a member of the local government. When this happens however, they move to the capital. If a unit gains a new position, either inherited or otherwise, it drops the previous one (of that civilisation or site-entity) - the unit will not drop any positions unrelated to the entity of the new position (ie. a CUSTOM_OUTCAST_FACTOR will not relinquish that position, if the unit becomes the ruler of a civilization and a militia commander will also not necessarily relinquish the position, if the unit becomes also the monarch of the corresponding civilization). If a unit assumes a civ-position in fortress mode, it leaves the current position.

If a unit holds the same (site-)position multiple times, it has no additional effect.

If a unit holds multiple different positions of the same entity, it has all those positions' responsibilities and properties, stacked up. Presumably, the demands for those combined positions are determined by the highest.

A unit holding a position with a succession token can be assigned another position with a (different) succession token.

A unit holding a position with a squad-position cannot hold another squad-position. It is dropped from the first, when it gets its second assigned.
A unit holding a position with a succession token cannot be assigned to a squad-position - the unit is simply not available. It works the other way around, though.

=Specific Tags and functions=
==[PRECEDENCE]==
The first defined position with precedence of 1 counts as the ruler of the civ. See also: [[Position_token#PRECEDENCE|PRECEDENCE]].

If the precedence is omitted or has a negative value, the game sets 0 as precedence, which seems to have no effect whatsoever.

When a unit has multiple positions, the name of the position with the highest rank in precedence is shown behind the unit's name.

If you omit precedence entirely, or set it to [PRECEDENCE:NONE], the position name will not be shown after the unit’s name. Your *Urist Mason* will remain simply *Mason*. This can be useful for positions that are unimportant or purely functional. The position will also not appear in the civilisation overview of your site on the world map. The position name is shown in messages, but remains hidden on the nobles screen as well. To make it visible there, use [LAND_NAME].

==[RESPONSIBILITY]ies==
Both civ and [SITE] positions can carry responsibilities. However, not all responsibilities are active for both types: some function only for civ positions, others only for site positions. When a civ noble arrives at a site and takes up residence, they do not perform responsibilities that are intended for SITE nobles. As a result, these responsibilities neither trigger their associated tasks nor unlock related game mechanics. For example, a civ-level manager living in a fortress will not perform management duties there and doesn't unlock the management-screen, even with an assigned office.
This behavior applies to the following [SITE]-level responsibilities:
* [RESPONSIBILITY:ACCOUNTING]
* [RESPONSIBILITY:BUILD_MORALE]
* [RESPONSIBILITY:HEALTH_MANAGEMENT]
* [RESPONSIBILITY:LAW_ENFORCEMENT]
* [RESPONSIBILITY:MANAGE_PRODUCTION]
* [RESPONSIBILITY:MEET_WORKERS]
* [RESPONSIBILITY:TRADE] (functions differently)
Other responsibilities may be affected as well, but have not yet been fully tested.

===World-gen effects of the [RESPONSIBILITY] of available positions ===
It is possible to cause civs and individual sites to change their behavior substantially when they reach a certain size, by controlling nobles.
* If a site can only appoint a position with [MILITARY_GOALS] after reaching a particular size, that site will not send armies on missions until the required size is reached.
* A civ-level [LAW_MAKING] position is required for the civilization to have any kind of cohesion. Without it, sites will be constantly embroiled in territorial disputes and civil wars will be commonplace.
* [MILITARY_STRATEGY] positions go out and tame wild animals. This makes your civ gain those animals as domesticated and also brings them in sieges.
* The [[Personality_facet|Personality]] of the position's holder determines how they lead the civ.

===[DELIVERS_MESSAGES]===
The only [AS_NEEDED]-position that is created in worldgen based on responsibility is that of the site-level responsibility [DELIVERS_MESSAGES].

===Outpost Liaisons and Diplomats===
Civ-positions with the responsibility [ESTABLISH_COLONY_TRADE_AGREEMENTS] ([[Outpost_Liaison|Outpost Liaison]]s) will meet with the site-noble who has responsibility for [RECEIVE_DIPLOMATS] and the highest rank of precedence (i.e. the lowest precedence value). Usually this is the [[Expedition_leader|Expedition leader]].

Once a [LAND_HOLDER] is assigned to the site, civ-positions with the responsibility [MAKE_TOPIC_AGREEMENTS] ([[Diplomat]]s) will meet with '''civ'''-level nobles present at the site who have the [RECEIVE_DIPLOMATS] responsibility. If multiple eligible nobles are available, one is selected at random. If no eligible noble is present, the diplomat leaves angrily. If the landholder is no longer present at the site, diplomats will not arrive at all.

It appears that Outpost Liaisons and Diplomats are chosen for a diplomatic mission based on availability. When multiple candidates exist, the position defined last in the raws is most often selected.

===[TRADE]===
Civ-level nobles with [TRADE] will arrive with the caravan, just as the Outpost Liaison. Their behavior is no longer active in the vanilla game, but the mechanics are still present. See [[40d:Guild_representative|Guild representative]] for more details. This civ-noble will only meet with the SITE noble with [TRADE], usually the [[Broker]].

If two civ-nobles exist with both [TRADE] and [ESTABLISH_COLONY_TRADE_AGREEMENTS], they both arrive at the same time. Even if both tokens are assigned to a single position, if more than one instance of that position exists, two of them will arrive. However in that case, somehow the elevation of the site and appointment of landholder isn't offered.

If the SITE-noble they intend to meet has both [TRADE] and [RECEIVE_DIPLOMATS], only one meeting will proceed and the other is cancelled. However, when two SITE-nobles are available, each with either [TRADE] or [RECEIVE_DIPLOMATS], both meetings will proceed and both civ-nobles will attempt to negotiate a trade agreement. It is not known what happens if these agreements are accepted or refused.

In the trade depot, the last defined position with the [TRADE] responsibility is shown as broker. However when requesting a trader, the first defined position with [TRADE] will actually go there to do the trade.

==[NUMBER]==
A position might be defined with a number. In that case, as many as defined can be available. If the positions become available, in world-gen and when embarking, they are all filled-in completely.

If the ruling position (with PRECEDENCE of 1) has a NUMBER higher than 1, a random unit of the ones holding these positions is shown as ruler in the embark screen.

A [NUMBER] of 0 (zero) has the same effect as 1.

===Automatic spreading of assumed, non-singular positions===
If there are civ positions that have a NUMBER higher then '1' and which are assumed (not APPOINTED_BY or ELECTED) but are '''not DUTY_BOUND''', these are automatically spread among the civilisation, based on population. If there are a number of '''20''' available slots of that position, they spread among a civilization with a combined population of, for example, 1000 of which your fortress has 100 (10%), '''2''' of your fortress' citizens will assume that position.
This may probably also work with elected and appointed positions, but that may be depending on the death of the current holders and this needs more testing. Assumption works within a day, anyway.

===[AS_NEEDED]===
These positions can be created automatically by the game in world-gen. This, however, only works with:
* [LAND_HOLDER]'s
* squad commanders (needs more testing)
* Messengers at sites

For all other types of positions, they're not created in world-gen, even if they are defined with RESPONSIBILITY's. For example, even in war, the game wouldn't create a MILITARY_GOALS position, if they have AS_NEEDED as number.

However, in fortress mode / player mode, these positions can be created by the player at will.

Positions with AS_NEEDED need to be created first, before any symbols are assignable as 'symbols' (objects) for the position holder to carry or wear.

Positions with AS_NEEDED cannot be created and then ELECTED in fortress mode. It only works with APPOINTED_BY.

==[REPLACED_BY], [REQUIRES_POPULATION], [REQUIRES_MARKET]==

The token [REPLACED_BY:position] means that once the replacing position meets its requirements for activation, the 'to-be-replaced' position will disappear. This is defined in [REQUIRES_POPULATION] or [REQUIRES_MARKET]. The tags are closely related to each other and seem to only have a meaningful function if combined. Nobles with [REQUIRES_POPULATION] require the population to have a specific size. Nobles with [REQUIRES_MARKET] are only activated in market sites, such as fortresses or towns. [REQUIRES_POPULATION] and [REQUIRES_MARKET] can be combined, activating that position once both requirements are met.

The [REQUIRES_MARKET] can be used to differentiate positions between hamlets and hillocks, and larger sites. IThe market always is build the year after the site is founded. So a position that is to be replaced, will be gone immediately.

The [REQUIRES_POPULATION]-tag works on the civ-level as well as on site-level, but those systems are in this mechanic strictly separated. Site-level positions cannot be replaced by civ-level positions and visa versa. This makes sense, because they both depend on their own population-count. When using REQUIRES_POPULATION on civ-level, it counts the total population of the civilisation.

See also: [[Advanced_entity_position_mechanics#Evaluation_of_Positions|Evaluation of positions]]

===Effect of replacement (and on [LAND_HOLDER]s)===

Replacement is immediate and complete - the current holding unit loses the position, even before SUCCESSION_BY_POSITION rules are applied. A position with a number of 1 will replace all the slots of a position with a higher number of slots.

Even if the next position is available but not visible, replacement still takes place. If a position is replaced, it is completely gone - it cannot be appointed, succeeded, elected or assumed any longer.
The unit immediately loses its position.

In legends, replacement is mentioned as: "(unit name) ceased to be (position name)" The replacement of an AS_NEEDED position empties the position's slot forever. In fortress mode, it may seem as if you can create new slots and appoint new units in the nobles screen, but this is reversed as soon as you close the window.

The landholder chain uses [REPLACED_BY] differently. It does not clear the position completely, but uses it for succession to the next level's position. [REPLACE_BY] is required to let that system work properly. This also means that the way in which landholders succeed (replace + as_needed) does not work in any other way.

Replacement between LAND_HOLDERS and other site- or civ positions does not work in any way. Only the vanilla replacement sequence between levels of LAND_HOLDERs does work. If the token is omitted for landholders, the landholder chain is broken, so replacement is required for the landholder system to work.

[REQUIRES_POPULATION] also does not work for [LAND_HOLDER], when you set [NUMBER] to 1. The position is not created when the required population is reached.

===What doesn't work===

'''Attention: If a position cannot be appointed, for example because of 'mutual appointment', it still exists according to replacement mechanics and will replace other positions if so defined. If a certain position(a) will be replaced by the baron's assistant, which can only be appointed by the [LAND_HOLDER] baron, than that position(s) still will be replaced from the start of the game, even if no baron or their assistant is ever present.'''

A position that is replaced by a somehow non-fillable position is still replaced. This counts for mutual-appointing positions, replacement by not-yet-assigned landholders, replacement by AS_NEEDED positions, or replacement by not-yet-appointed positions.

Replacement does not work if the replaced position is a [LAND_HOLDER], even with civ-positions. In that case, the LAND_HOLDER's position is not replaced. It does not matter if AS_NEEDED is used, or a fixed number, and it also does not matter what type of position the replacer is. So this only works (correctly) with positions that become available by REQUIRES_POPULATION.

==[CONQUERED_SITE]==

This tag determines which position is used to assign a [[Forced administrator]].

In legends mode, this is visible as an event describing the reconquest of the site: a new group is formed and the forced administrator is installed as its ruler.

All positions defined with this tag are assigned during this process, meaning multiple positions can be appointed at once.

The holder of a position marked with [CONQUERED_SITE] cannot appoint any other [SITE] positions, unless the civilization has site variable positions, in which case the forced administrator can appoint such site variable positions (allthough the variable positions for that site need to be created first and such creation only happens during world-gen, but not normal world activities).

Combining [CONQUERED_SITE] with [SITE] causes the position to function both as a forced administrator and as a normal site position available in fortress mode. However, this provides no meaningful additional mechanics and is effectively inferior to using [SITE] alone:
* [APPOINTED_BY] lines are completely ignored, meaning that the roles are automatically assumed.
* [SUCCESSION] is likewise ignored.
* the [CONQUERED_SITE]-position cannot appoint other [CONQUERED_SITE], [SITE] or combined positions.

There have been remarks that reclaiming a fortress is unplayable because of the lack of regular nobles. Unfortunately, it seems that it can't be fixed by modding.

=Availability and visibility=
==Availability of (new) positions==
Warning: Do not mistake "availability" for "visibility"!

Of all the possible positions existing in your site's entity, there may only be some available.
* Positions with [REQUIRES_POPULATION] require the population to have a specific size.
* Positions with [REQUIRES_MARKET] will only appear in "large" sites (which may have different rules for different site types). This tag has no effect in fort mode.
* Positions that are appointed by positions that have an AS_NEEDED number. The appointable positions only become available after an appointer position-slot is created. This works also on civ-level. If a position is appointed by a Land-holder, it only becomes available, when that level of landholder is created.

Only the replaced positions are culled and are no longer available.
A position that requires a certain population will become available, even if it doesn't have [APPOINTED_BY] or [ELECTED]. In that case, see 'automatic assignment' and 'assumption'

In fortress mode, in some cases 'succession' is evaluated immediately after a position becomes available. See: Succession.
==Visibility of positions==
A position might be available, but can still be invisible for the player in the [[nobles screen]]. The positions with their respective holders are visible for players:
* All site-positions that are already filled-in (even if they could not be re-filled-in considering current conditions)
* Site positions that are appointable by a filled-in site position
* Site positions that are appointable by a filled-in civ position, when that civ positions holder becomes a citizen of your fortress.
* Civ positions of units that are also a citizen of your fortress.
If a position becomes available, for example because a certain pop number has been reached, or if it is available from the start(like expedition leader), as long as it cannot be appointed, it still is INVISIBLE for the player.

It might strike someone as odd if a position becomes filled automatically in fortress mode when that position is not even visible. This might be the case if the current holder of a non-appointable position dies or succeeds another position. Regardless of player visibility, these positions will be automatically filled in if the necessary requisitions are met. It might happen with the expedition leader.

A situation with a non-visible but available position, is for example when a position is solely appointed by the expedition leader, when the expedition leader's position is left vacant. It can no longer be appointed by the player and is invisible. Then, it gets automatically assumed, proving that the position still was available.

A position that is both [APPOINTED_BY] and [ELECTED] is visible, but players cannot interact with it.

={{text anchor|Evaluation of Positions}}=
The game does not continuously check whether positions should become available, elected or be [REPLACE_BY]. This is well-known behavior—for example with the [[mayor]], who does not appear automatically when the required population ([REQUIRES_POPULATION]) is reached. Instead, positions must somehow be evaluated. This applies in several other situations as well

'''Cases that require a trigger:'''
* Election of a newly created position
* Election after the current holder dies
* Automatic assumption of a newly created position (this may take up to a day)
* New citizens (such as migrants) considering available positions
* Premature succession of a newly created position

'''Cases that do not wait for a trigger:'''
* Succession following the death of the previous holder
* Automatic assumption of existing positions that have become vacant

'''Triggers that cause the game to reevaluate noble positions:'''
* Succession of a [SITE]-position due to the death of the current holder
* [[Advanced_entity_position_mechanics#Election_Day|Election Day]]
* Automatic assumption of a [SITE]-position that becomes vacant
* (Re)assigning any site position manually
* Settlement elevation on the LAND_HOLDER track (e.g. gaining a [[Baron]] or [[Count]])

=Gaining a position=
There are several ways a unit can gain a position:
* Appointment: A unit is appointed by another unit or by the player.
* Election: A unit is elected by and among the members of the entity
* Assumption: A position is neither elected or appointed: a random unit just simply 'takes' the position
* Succession: a unit is the valid successor of this position(A), either by its current position(B) or because they are that position(A)-holder's heir.

Available positions will automatically be assigned to a random civ member when a new site/civ is created.

==Who can take a position==

* If so defined, a unit needs to be the right caste and/or class - it does not seem to work with creature types.
* The unit needs to be an adult member of the site or its parent civ's government; that is also CAN_LEARN or INTELLIGENT (SLOW_LEARNER cannot take positions) or otherwise is able to think.

==Appointment==

Positions that have an [APPOINTED_BY:position] token require that position to exist, to be available and appointed. Any position that is APPOINTED_BY can be appointed if the appointer's position is filled in.
For site-positions to be appointed, it is required that the appointer is present at that location.

If the appointing unit is temporarily not present, or if that position is not filled, positions depending on it cannot be appointed. This is the case with [[militia captains]], when the [[militia commander]] is on a [[mission]].

A site position cannot appoint a civ position ''or'' LAND_HOLDER in any way whatsoever.

Civ-level positions can appoint other civ-level positions and site-level positions can appoint other site-level positions.

Contrary to what has been said elsewhere, civ-level nobles also can appoint site-level nobles. They need to be at the site to do so. Landholders can appoint both site-level and civ-level nobles. These systems are therefore not as separate as was assumed.

'''Mutual appointment''' cannot take place. If these are the only requisites of the position, then the positions will never appear or get filled. These unfillable positions can be put to good use, for example, to replace a position that is no longer needed without creating a new one.

'''Self appointment''' doesn't normally work. If you have a position that is only appointed by itself, it is never appointed and also cannot be assumed. However, if the position has a number higher than 1, and is filled by multiple units (for example by another position that is now empty), than those units can re-assign or appoint each other from that their shared position.

If an APPOINTED_BY token refers to a non-existing position's code, the effects are as if the appointment token doesn't exist at all.

===Automatic appointment in world-gen and on the civ level===

Outside of fortress mode, the game will always attempt to appoint nobles whenever possible, as long as these positions are '''available''', even if they are invisible to the player.
It shows this message in legends: "(unit name) has been appointed to the position of (position name)"

In world-gen, all positions become available and are automatically appointed, taking population- and appointment-requirements into consideration.

Positions that are REPLACED_BY are culled and won't be filled.

If a citizen of your fortress holds a civ-level position that can appoint another civ-level position, the appointment will happen automatically and without player intervention. It may happen that another citizen of your fortress is appointed by that unit, creating civ-level position holders in your fortress, but it is unknown what is required to force this effect.

===Manual appointments by players in fortress mode===
In fortress mode, the positions that need to be appointed stay empty on embark. and it is the player's job to appoint those. A player can appoint a unit to any available position, according to the hereabove mentioned conditions. The player takes the role of the automatic appointment-system, but has no direct control over elections, successions and replacement. There are some differences in what is possible at world-gen sites and at player-controlled sites.

* A position that is appointed by a unit present as a fortress citizen, can be appointed, re-appointed or left vacant. This means also by civ-level nobles living as a citizen in your fortress; not when they are only visiting, like the diplomat.
* A position whose appointing positions are all either vacant or [REPLACED_BY] can no longer be appointed. If the position is already filled, it cannot be reappointed or vacated; the current holder simply remains in office.
* A position that is APPOINTED_BY a unit present as the land_holder of your site, can be appointed, reassigned or left vacant.
* A position that has SUCCESSION BY_HEIR or BY_POSITION can 'initially' be appointed and also re-appointed or left vacant, but as soon as the [[nobles]] screen closes, ''it can no longer be replaced or left vacant''. From then on, the succession-rules determine who gains that position when the current holder loses the position. This works even if the SUCCESSION:BY_POSITION-position is vacant or replaced.
* A position that is ELECTED nor APPOINTED_BY, can always be (re-)appointed by the player. This is the case with the [[Expedition leader]]. If it is left vacant however, it cannot be appointed, but will be assumed shortly after.
* A position that is both ELECTED and APPOINTED_BY, cannot be appointed by the player. Contrary to world-gen sites, its slot is visible, but it doesn't show the +-sign. This is either by AS_NEEDED or by a fixed number. Even if the position somehow gets filled (re)assignment is never possible
* A player can appoint a number of units to a position, as much as the NUMBER token dictates. If it is AS_NEEDED, the player may create as many slots as they like, also contrary to world-gen sites.
* A civ-position can never be appointed, even if the appointing civ noble is a citizen of your fortress. A civ position also never can be re-assigned or left vacant, would that position be defined as appointed by a site-position.

==Election==
Read more in [[Elections]]. The message that is shown is: "(creature name) has been elected to the position of (position name)"

In worldgen, there is no functional difference between ELECTED and non-appointment, except that elected nobles tend to have high social skills and/or skills related to the position, while non-elected ones are assigned randomly. See: [[Elections]]

A succession goes before an election.

A position that is both ELECTED and APPOINTED_BY never gets elected. Even if the appointees' position somehow gets filled, (re)-elections won't happen. So, it doesn't seem possible to have an elected position become available when a certain other position becomes filled.

An ELECTED civ-(or LAND_HOLDER) position at your site will never be (re)-elected in fortress mode. So real (re-)election only works with SITE-positions.

=== {{text anchor|Election Day}} ===
Election Day takes place on the 17th of Summer. On this day, a full reevaluation is performed, including all currently elected positions, which are subject to re-election. Contrary to the information on [[Elections]], nothing occurs at the start of a season.

Positions that are both [APPOINTED_BY] and [ELECTED] will not be re-elected on Election Day when assigned through [SUCCESSION].

=== Election Eligiblity ===
Any citizen may stand for election. Eligibility cannot be restricted using [ACCEPTED_CREATURE], [REJECTED_CREATURE], [ACCEPTED_CLASS], [REJECTED_CLASS], or [GENDER]. Units currently having a [SUCCESSION]-position even may be elected for a position with a [SQUAD]-token, which is otherwise impossible to assign or even succeed.

=== Skills ===
In elections, skills are taken into account for the tokens of the position which is elected.
{| class="wikitable"
|+ Relevant skills per position token
|-
! Position Token !! Relevant skills
|-
| Responsibility [[Position_token#DELIVER_MESSAGES|[DELIVER_MESSAGES]]] || [[Ambusher]], [[Observer]] and [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#ACCOUNTING|[ACCOUNTING]]] || [[Record_keeper|Record keeper]]
|-
| Responsibility [[Position_token#ESPIONAGE|[ESPIONAGE]]] || [[Schemer]]
|-
| Responsibility [[Position_token#HEALTH_MANAGEMENT|[HEALTH_MANAGEMENT]]] || [[Diagnostician|Diagnostician]]
|-
| Responsibility [[Position_token#MAKE_INTRODUCTIONS|[MAKE_INTRODUCTIONS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#MAKE_PEACE_AGREEMENTS|[MAKE_PEACE_AGREEMENTS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#MAKE_TOPIC_AGREEMENTS|[MAKE_TOPIC_AGREEMENTS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#MANAGE_PRODUCTION|[MANAGE_PRODUCTION]]] || [[Organizer]]
|-
| Responsibility [[Position_token#MEET_WORKERS|[MEET_WORKERS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#RECEIVE_DIPLOMATS|[RECEIVE_DIPLOMATS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#RELIGION|[RELIGION]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#TAME_EXOTICS|[TAME_EXOTICS]]] || [[Animal_trainer|Animal trainer]]
|-
| Responsibility [[Position_token#TRADE|[TRADE]]] || [[Social_skill|Social skills]] and [[Appraiser|Appraiser]]
|-
| [[Position_token#SQUAD|[SQUAD]]]-token || [[Tactician]] and [[Leader]]
|}

==Assumption==

A position that is not APPOINTED_BY nor ELECTED, or is appointed by positions that are not available in your site or civ, will be assumable by a random dwarf. If it has responsibilities that require certain skills, then these are taken into consideration on embark, but not when the position is assumed during the actual game.

Normally, one to three units will take the into consideration to assume a position. Most of the time when there are multiple open positions, only a single unit will assume all of them. However, a position that has REJECTED_CREATURE, REJECTED_CLASS, ALLOWED_CREATURE or ALLOWED_CLASS will be filled with all different units, even if the creature or class mentioned is irrelevant. It seems that this forces the game to loop over all the available units.

The message that is shown in Legends mode is: "(unit name) has assumed the position of (position name)". This may also take place in fortress mode, which then shows this message to the player.

If an assumable position becomes empty, it will be assumed within a day. This is the case when you leave the position of expedition-leader vacant. It also happens with entities.

Assumable positions that become empty will not be assumed if that position has a valid [SUCCESSION] -successor. In that case, the successor inherits the position.

Even positions that are somehow invisible because they cannot be directly APPOINTED_BY players, can be assumed.

When you embark, the assumable positions are automatically assigned to a random unit. If there are multiple of these positions at embark, they all are assigned to the same unit. If there are enough positions available, multiple units may gain a position, but often no more than three different ones.

If a dwarf in fortress mode assumes a position, that already has another position, it will leave the current position empty. When that position also is assumed, then this will continue until all positions have a dwarf appointed to them, with no other position.

A unit that already has a position with a [SUCCESSION] token won't take assumable positions into consideration that have a [SQUAD] token. This can be used by the modder to prevent unwanted loss of current positions.

A position that has an appointer which got replaced because of REPLACED_BY, will not become assumable. Also, positions that have an AS_NEEDED appointer that is not yet filled (or ever), will also not be assumed.

==Succession==

If a position-holder dies or advances to a new position via succession, the position will be granted to another unit based on the [SUCCESSION] tag. If they have an heir or the succeeding position exists, that unit will be assigned. If not, a new one will be appointed according to the usual rules. The message that is shown is: "(creature name) being the rightful heir, has inherited the position of (position name)"

The succeeding creature will also lose its previous position. When succession is defined using BY_POSITION, the unit naturally loses the referenced position. However, it also loses any other positions it may hold. If a unit could simultaneously inherit multiple positions, the last-defined succession overrides the earlier one, clearing the previously acquired position

Succession works both at site-level and at civ-level, both in world-gen and in fortress-mode. Succession by position on the civ-level is also visible and functional in fortress-mode. If both civ-level nobles are a citizen of your fortress, succession is applied visually. Vanilla example: The [[druid]] is succeeded by the [[acolyte]]. This means that as soon as the druid dies, the acolyte takes over.

When a position that is succeeded by position becomes available, immediately it is checked if a position-successor is available and the position is filled with that unit. Even if this is an [ELECTED] position, succession goes first. When elections eventually do happen, succession plays no role.

It is possible to assign multiple levels of [SUCCESSION:BY_POSITION] in different positions, creating a line of positions where the death of one causes all those "below" them to advance.

A position can have multiple tokens with position-succession. It looks to be random which one is used. It is not always:
* The first or last defined token
* The first or last appointed unit
* the oldest or youngest
* one with a higher or lower precedence
* a unit with relevant skills

When a position is defined with a Succession-type, that unit cannot have another position that has a Squad-type. If the succession-position itself has a squad, than it can be assigned another position with a squad, but then it will loose the previous succesion position. See further details by "Squad"

Assumed positions can also be succeeded by position, if the current holder dies.

If the successor is an AS_NEEDED position, the used unit will leave a vacant position-slot on its removal by succession. This empty slot remains a real slot, which will only be cleaned up if you (un)appoint a unit to this position-series. It isn't cleaned up after regular position validation.

A civ-level position of a unit living at your site might be inherited by a unit holding that does not currently live at your site. This, unfortunately, moves that position to a unit off site. This may also happen with the landholder of your site, for example when it is succeeded by another civ-level position. This currently poses an unsolved challenge.

===Eligibility for succession===
Succession is restricted by the tokens [ACCEPTED_CREATURE], [REJECTED_CREATURE], [ACCEPTED_CLASS], [REJECTED_CLASS] and [GENDER].

===Site and civ combined succession===

Succession can work when combining site positions with civ-level positions or land_holders, but only in world-gen mode. In fortress mode, it only works with combining the same level of nobles, with Landholders regarded as civ-level. So, in fortress mode, a site's position cannot succeed a landholder's position and it cannot succeed another type of civ-level position, and vice versa.

This won't work even if the positions:
* are AS_NEEDED or having a fixed number.
* Are LAND_HOLDERs.

===Succession [BY_HEIR]===

When a heir is needed for succession, all children and then other relatives are validated. They cannot take the position if their status does not allow it, for example if they have become a member of another civilisation. See: "Who can take a position". If the unit has no valid heir on that location, the position may go to a unit living on another site. This may cause the title of Landholder of some land to be inherited by a unit living somewhere else. That might be a problem, because then you lose your landholders.

===Premature Succession===

There are cases where [SUCCESSION:BY_POSITION] is applied prematurely: at the moment a position is first created and becomes appointable or assumable, rather than after a current holder leaves. In this situation, the succession mechanism assigns a holder immediately, without any player interaction.

When a position becomes available for the first time, the game checks whether a valid successor-by-position exists. If so, that unit is assigned instantly. It can affect positions that would normally be appointed or elected by the player, causing succession to trigger before the player has any opportunity to intervene.

This behavior occurs only in Fortress mode, but can be applied both on [SITE]-positions as well in civ-positions. That last one however is a bit harder to control. Example: [[Advanced entity position mechanics#The Archduke|The Archduke]]

This premature succession only occurs the first time a position becomes available (i.e. when it is created and becomes appointable or assumable). Even if the position remains vacant and the conditions for succession improve later, premature succession will not trigger again. From that point onward, only normal succession rules apply.

Using premature succession, a position that has [ELECTED], [APPOINTED_BY], or both, can be filled directly.
Notably, positions that combine [ELECTED] and [APPOINTED_BY] are normally impossible to fill through regular mechanics. Premature succession bypasses both election and appointment entirely, making this combination uniquely reachable through this mechanism.

No initial election takes place, and no subsequent elections will ever occur for that position. Succession always takes precedence over election, both in premature succession and in normal succession cases.

This behavior applies only in Fortress mode, not during world generation. World-gen uses simplified and more efficient mechanics, and this interaction does not occur there. Premature succession can affect both site-level and civilization-level positions.

====Multiple succession chains====

Multiple succession chains may be defined and are resolved in the order they appear in the raws.

If a position has both:
* a direct succession chain (A → C), and
* a multi-step chain (A → B → C),

and intermediate positions are vacant, resolution proceeds according to raw order. A common outcome is:
# The direct succession (A → C) is applied first, assigning A to C.
# The remaining chain then advances (A → B).
# If C still has empty slots, the final step (B → C) may occur.

If position B is already filled, behavior depends entirely on raw definition order:
* nothing may happen, or
* B may move to C first, followed by A moving to B.
====Working triggers====
Premature succession is triggered when a succeedable position is created under the following conditions:
* The succeedable position is created because its [REQUIRES_POPULATION] threshold is reached. This applies even if the position is not [APPOINTED_BY]. Premature succession takes priority over automatic assumption (e.g. the mayor declaring themselves within a day).
** The position must either be assumable or appointed by an existing position. When said appointer-position also just has been created, the premature succession of the succeedable position happenes, even when the appointer-position is empty.
* The succeedable position can be [APPOINTED_BY] another position of the same level (site or civ) that has just been created because its [REQUIRES_POPULATION] was reached.
* The succeedable position can be appointed by another [SITE] [AS_NEEDED] position that has just been created and filled.
* The succeedable (site or civ) position is [APPOINTED_BY] the [LAND_HOLDER] position, which has just been created due to site elevation. This typically resolves when the diplomat leaves the map, at which point the landholder position becomes active.
* If all other requirements are met, premature succession can occur immediately after unpausing following embark, for positions with [REQUIRES_POPULATION:7].

====Non-working (triggers)====
Premature succession does '''not''' occur in the following cases:
* An [AS_NEEDED] succeedable position slot is manually created by the player while its succeeding position is already filled. [AS_NEEDED] positions must always be appointed after creation.
* The succeeding position is filled after the succeedable position becomes available. The moment of creation is the decisive trigger; filling the source position later is too late.
* The succeedable position can be appointed by another site or civ position with a fixed number of slots that has just been appointed. In this case, the succeedable position is just available for appointment itself, nothing more
* Any situation occurring during world generation.
* The succeeding position is [REPLACED_BY] the succeedable position. In this case, replacement removes the unit from the source position first, leaving no holder available for the succession mechanism to use.rst, leaving no holder available for the succession mechanism to use.
* The position is [APPOINTED_BY] a civ-level position, that just became a citizen of your fortress. It must be noted that those civ-level positions were active all that time and the succeedable position could be appointed even before. The monarchs arrival does not trigger premature succession
* A [SQUAD]-position can not inherrit another [SQUAD]-position. This means also that premature succesion will not work in this case.

=Losing a position=

A unit can lose a position when:
* It dies
* It succeeds another position, even if it has nothing to do with the previous position.
* It is assigned to another SQUAD-holding position
* It is convicted of a crime.
* Another unit is ELECTED for the position
* It is convinced by an adventurer to give up its position, or is overthrown in a coup.
* Its position becomes replaced
* Another unit is appointed by the player, or the position is left vacant.
* It has assumed another position (of the same entity), as this always leaves the previous position vacant.

Note: A unit does not lose a position when the unit leaves the group (entity). Neither will a unit lose a position, if the corresponding entity is considered to be dead.

=Embarkment=
Two types of positions are automatically filled by embark.
* Positions without [APPOINTED_BY] or [ELECTED] (assumable). All these positions, even with a NUMBER higher than 1, are all filled with one to three dwarves. Contrary to assumption, this doesn't take into account any limitations. REJECTED_CLASS, ALLOWED_CLASS, REJECTED_CREATURE, ALLOWED_CREATURE and GENDER are applied, but without the normal spread you may expect with assumptions. Also it doesn't look at [SUCCESSION] and [SQUAD] limitations.
* Positions that are elected are filled-in by the normal election rules.

Positions that have a defined appointer are never initially filled at embark.

All positions that don't have [REQUIRES_POPULATION] or with a [REQUIRES_POPULATION] of 7 or lower, will be available at embark.

=Land Holders=

A Landholder is a '''special civ-level noble''' who gets a certain piece of land to hold, when that land is elevated to a certain level, determined by the [LAND_HOLDER] tag, and by the landholder triggers in the game's settings. In vanilla, these are the baron, the count and the duke.

A unit gaining the landholder position does not migrate to that specific named land. In world-gen, they stay just where they are, probably at the capital. In fortress mode, you can suggest a citizen for the role. So for the time being that works.

Succession is then a real issue. If you use BY_HEIR, its solved when that landholder has children living at your site. But when its not the case, the title just goes to anyone randomly. Succession BY_POSITION works, but only in the civ-chain, and there's no way to guarantee a civ-holder is at your site at that time. Even with 'automatic spread' positions, it goes to one of them randomly.

==Functioning of the regular landholder chain==

The distinct difference between a landholder and a regular civ-level noble, is that a landholder may gain the position of landholder "of (sitename)" They are then seen as ruler of a particular site.

For a land_holder position to function as such, it has a few requirements:
* NUMBER:AS_NEEDED
* The first landholder-number of 1 is defined.
* No SITE (so civ) tag in that position.
*REPLACED_BY the next level landholder
If a landholder is defined with differentiating properties, it will function like a regular noble. A higher-up landholder that lacks the required tokens or connections will then not be used in elevation.

If a fortress meets the trigger for a new LAND_HOLDER tier when a caravan leaves, then the next time the outpost liaison or equivalent arrives, they will offer to make you an official colony, which will allow you to select all positions for that LAND_HOLDER level. Each time they appear, the outpost liaison will only promote your fortress one tier up the LAND_HOLDER track.

The landholder's LAND_NAME is not required for the functioning of this system. If omitted, messages will be shown with a more generic text.

==Appointment==

This mechanism differs from the regular methods of position management. It ignores all regular appointment- and election rules, so it more or less functions like automatic assignment. A landholder is, in vanilla, appointed by the monarch. Changing this doesn't seem to do anything. If they are appointed by a site-position, a not-yet-existing civ-position, or not appointed at all: the system keeps working as usual.

A landholder can appoint civ-positions and site positions. This works as expected: the positions only are appointed then when that landholder becomes available on civ-level or when he arrives at that site for site-level positions.

If your rank of landholder is the first of its rank in the realm, and is the sole appointer of some civ-position, then immediately as it gains the title, it will appoint the empty civ-slots. This may happen on your site, but the frequency and certainty is hard to determine.

==Succession==

Succession rules are applied to some extent:
* In world-gen it works according to succession rules, and site-positions can be used here. This means that a site position or a civ-position can inherit a landholder position, and vice versa.
* In fortress mode, once a landholder has been appointed, it then can inherit civ-level positions, and vice versa. This means that your baron can become king.
* Succession rules do not apply within the [LAND_HOLDER] chain; a count will not inherit a baron's land. This is because succession does not work well with the AS_NEEDED token.
* Premature succession works in fortress mode with landholders. If a unit gets a landholder's position and that landholder is the appointer of an as yet empty position, which is defined as succeeding from a third one, then the succession is immediately applied. The landholder themselves can even be the successor of a newly created position.
* A landholder's position is, in fortress mode, not successionable by a site-position or vice versa

===Impossibilities for succession by a site-position===
It would be very beneficial if the landholder can be succeeded by a [SITE]-position. So far, the following tests have not lead to positive results:
* making landholder and site-position both non-[DUTY_BOUND]
* make the site-position be [APPOINTED_BY] the landholder and/or the monarch
* give landholder and site-position [REJECTED_CREATURE]
* Let the monarch live at your site when succession could happen.
* Let the site-position be [REPLACED_BY] the landholder.

If the vanilla [SUCCESSION:BY_HEIR]-tag is omitted, a seemingly random unit somewhere in the realm is assigned this position.

==Nomination==

The player is able to nominate a unit to become the LAND_HOLDER, but this only works with units of [LAND_HOLDER] level 1. The player can select all units, only limited by the PRECEDENCE of the current units' positions.

A unit that has a position with a PRECEDENCE lower or equal to that of the landholder's position, cannot be selected. This means that a baron (or count) from another site or the monarch cannot be selected, because their precedence is lower or equal.

The GENDER token does not work here: also units with the wrong gender (sorry) can be selected.

==Levels==
In mods, up to 10 levels of LAND_HOLDER may be defined.

If a landholder is replaced by a wrong landholder number (1 replaced by 3), then the number 3 is still correctly attached to the settlement.

If the current landholder has the highest available landholder number, then the next elevation will not happen - the diplomat will not elevate your fortress to a higher position, even if that position might be REPLACED_BY a lower landholder.

These chains do work:
* 1 -> 2a - > 2b -> 3
* 1 -> 3 -> 2 -> 4

These chains do not work:
* 2 -> 3 (need to start at 1)
* 1 -> 4 -> 2 -> 3 (stops after 4 as the highest)
* 1a -> 2, 1b -> 2 (only 1a and 2 work, 1b is not used)

==Moving landholders==

It may happen that a land-holder no longer lives at the site which they are the landholder of, specifically when the current landholder dies, leaving the title to an heir living somewhere else.

To prevent this from happening, you can make their succession from heir and make sure that their kids live at your site. Or, you can make their position succeeded by another civ position, and make it so that this civ position is somehow available on your site. But if multiple of these positions exist, it cannot be guaranteed that a citizen of your fortress will inherit the title.

In world gen, a landholder lacking the DUTY_BOUND-token will also move to the site they like, according to legends mode.

==Replacement by a generic civ-position==

If a landholder is replaced by an AS_NEEDED non-landholder civ-position, then this will work: the current landholder loses that title upon settlement-elevation and gains that civ-title. However, the civ-title lacks the landholder-property of being attached to the land. It will not show the name of the settlement alongside the position's name. So no "minister of Shovelmounts"

If a landholder is replaced by a general AS_NEEDED civ-position, that itself is also replaced by a generic AS_NEEDED civ-position, then firstly the elevation is executed and also the unit gains that new position. However, he immediately loses it, because an AS_NEEDED position that is replaced by another position can be filled initially, but units wont be able to hold that title.

==Landholder with fixed number==

A landholder's position that has a fixed number will be created and filled directly when the civilisation is born, so this position slot is then not available for the regular landholder-mechanic and will also not be used. That landholder will thus not be attached to a settlement.

It doesn't matter if the landholder's position is connected to the regular landholder's-chain with the REPLACE_BY token.

==Responsibilities==

When given a certain [RESPONSIBILITY], a landholder may function as a regular civ-level noble. If the position has [TRADE] or [OUTPOST_NEGOTIATING] responsibilities, then the landholder functions both as a diplomat and as an actual land holder. A landholder with the [MILITARY_STRATEGY] responsibility will travel around taming creatures in world-gen, according to legends mode.

Besides that, the responsibilities work the same as with any other on-site living position-holder, civ or otherwise.

=Military=
==Squad management==
In the vanilla game, the Squad interface only becomes available after a militia commander has been appointed. Until then, the window displays:{{DFtext|You must appoint somebody first to create a squad.}}

What’s surprising is how this is determined internally. In the entity raw definition, '''only the last two positions that include a [SQUAD] token are checked''' to decide whether the interface is accessible at all. As a result, if your hierarchy defines commanders A through E, appointing '''Commander D or E''' unlocks squad formation, while appointing A–C does nothing.

In other words, squad availability is not tied to ''having a militia commander'', but to ''which specific positions happen to be last in the raw list''—a notably hacky implementation.

These 'last two' are always the last two '''available positions.''' So if they get [REPLACED_BY] or become available because of [REQUIRES_POPULATION], the game adapts to those.

==Squad assignment==

Squads can be assigned, even if the leader position has no holder.

A specific unit can only have one position associated with a squad. If it gains another 'squad holding position', it is unassigned from the first one. This does not work with a 0-squad, so only 1+squads are taken into consideration. This technique can possibly be used to distribute all positions equally among all citizens. It does however not work with election and assumption.

If a civ-level position is associated with a squad and it gets a site-level squad-holding position assigned, it loses the current civ-position.

Squads can get really messed up, if you make the position (or multiple) either elected or not-elected and not-appointed, then this can cause the game to assign multiple squads to the same unit. Automatic assignment and election does not take squads into account, but the nobles screen does. This can cause the positions to be cleared as the game figures out that they have more than one position, and immediately get elected or assumed again.

Positions that cannot have a squad-position:
* A site- or civ-position with a [SUCCESSION] token cannot be appointed a squad-holding-position. The other way around, however, does work. For example, if a site-position with a [SUCCESSION]-token is appointed to a unit that has already a position with [SQUAD]. But when that squad position is assigned to another unit, it cannot be assigned back.
* A position with [SUCCESSION] can also not be assigned as a '''member''' of a squad.
* A squad-holding position with a formed squad cannot be appointed to another squad holding position.

If a position has at least one squad member, it cannot be left vacant. First, the squad has to be disbanded, then the position may be cleared.

==0-squads==
A 0-Squad is defined in a position as [SQUAD:0:member:members]. It does not seem to do anything useful as of now.
* It cannot be used to activate the [[Squad|military interface]]
* It does not restrict the assignment of [SUCCESSION] positions.
* Assigning this position does not clear any previously held squad position.
* The [[Leader]] and [[Tactician]] skill are not marked as relevant skills and are not taken into account in elections.
* It cannot be formed as a squad.

=Further testing=
The following questions may need additional testing. Feel free to add or answer
* Everything regarding COMMANDING and army-structure
** [http://www.bay12forums.com/smf/index.php?topic=175437.msg8331668#msg8331668]
** [http://www.bay12forums.com/smf/index.php?topic=165213.msg8335682#msg8335682]
** [http://www.bay12forums.com/smf/index.php?topic=174584.msg8026854#msg8026854]
* Stuff about the monarch, its arrival and its entourage.

=Oddities (Bugs)=
Almost everything on this page could be called an oddity. Because of their unexpected usability, some may also be referred to as “undocumented features.” Others, however, are simply odd and not particularly useful, yet I hesitate to call them “bugs.”
* If a certain threshold is reached that makes an elected position electable, and the triggering event that initiates this evaluation is an assumption, then the resulting assumption works partially as an election. It referred to in the messages as an election and the [REJECTED_CREATURE]-token is not applied, like it is with assumptions.

=Examples=

===The Founder===
The founder is a single dwarf, appointed at embark. They will be the only one ever to have this position and are not replaceable. When they lose their position some way, the position will not be assumed by another dwarf.
{{gamedata|title=The Founder|
[POSITION:THE_FOUNDER]
[NAME:the founder:founders]
[NUMBER:1]
[SITE]
[ALLOWED_CREATURE:DWARF:ALL] - will only be filled at embark, but not assumable later.
[REJECTED_CREATURE:DWARF:ALL] - will only be filled at embark, but not assumable later.
[SUCCESSION:BY_POSITION:THE_FOUNDER] - not unassignable, also cannot be assigned to a [SQUAD] position.
[PRECEDENCE:200]
Non APPOINTED_BY
Non ELECTED
Optional: Add responsibilities to make the game select a unit with certain skills.
}}
===Marriage bar===
Dwarven matrons are held in great honour. Upon marriage, a female dwarf is no longer expected to perform menial labour. All dwarven males hold this position by default, granting their spouses exemption from menial work.

The position becomes available with the arrival of the first migrants; otherwise, on embark, it would be assumed by females. Its succession rule is non-functional, but this prevents the player from unassigning the position. A squad size of 1 and the succession rules together prevent a unit from assuming the position more than once.

With precedence set to NONE, the position name is hidden, while LAND_NAME remains visible on the nobles screen. All married females receive the suffix “, Mrs.” and are marked as Nobles.

The practical usefulness of this position is debatable, but it serves as a clear demonstration of several mechanics.
{{gamedata|title=Mrs. Urist|

[POSITION:MRS_URIST]
[NUMBER:300]
[SITE]
[ALLOWED_CREATURE:DWARF:MALE]
Not APPOINTED_BY
Not ELECTED
[LAND_NAME:Dwarven male]
[NAME:dwarven male:dwarven male]
[PRECEDENCE:NONE]
[SPOUSE_FEMALE:, Mrs.:spouses]
[MENIAL_WORK_EXEMPTION_SPOUSE]
[REQUIRES_POPULATION:8]
[SUCCESSION:BY_POSITION:MONARCH]
[SQUAD:1:member:members]
}}
===The Archduke===
The archduke is the leader of the civilization, but exists only from landholder 4-level. Until then, its position remains vacant. When a settlement is elevated to tier 4 (grand duke), the grand duke can appoint the ruler of the civilisation, the archduke. Because of 'Premature Succession', they themself inherit that position immediately, but only when in fortress mode. Its heir then becomes grand duke.
{{gamedata|title=The Archduke| no POSITION:MONARCH or other PRECEDENCE:1

[POSITION:THE_ARCHDUKE]
[NAME:archduke:archdukes]
[NAME_MALE:archduke:archdukes]
[NAME_FEMALE:archduchess:archduchesses]
[LAND_NAME:a archduchy]
[NUMBER:1]
[PRECEDENCE:1]
[SUCCESSION:BY_POSITION:GRAND_DUKE]
[APPOINTED_BY:GRAND_DUKE]
(add additional monarch-stuff, like spouse name, demands etc.)

[POSITION:GRAND_DUKE]
[NAME:grand duke:grand dukes]
[NAME_MALE:grand duke:grand dukes]
[NAME_FEMALE:grand duchess:grand duchesses]
[NUMBER:AS_NEEDED]
[LAND_HOLDER:4]
// Optional ...
[PRECEDENCE:19]
[LAND_NAME:a archduchy]
[RESPONSIBILITY:LAW_MAKING]
[RESPONSIBILITY:RECEIVE_DIPLOMATS]
[SUCCESSION:BY_HEIR]
[APPOINTED_BY:THE_ARCHDUKE]
(add additional landholder-stuff)

!!add to [POSITION:DUKE]
[REPLACED_BY:GRAND_DUKE]

}}
{{Category|Modding}}
{{Category|Entities}}
{{Category|Guides}}

Advanced entity position mechanics

2026-04-28T08:46:22Z

Joostheger: /* Losing a position */

{{Quality|Fine}}
{{Modding}}

= Introduction =

[http://www.bay12forums.com/smf/index.php?topic=182239.0 Discussion thread on the forum]

This page documents observed and tested behavior of entity positions in Dwarf Fortress that is not fully described elsewhere on the wiki. It focuses on advanced interactions between position tokens, including appointment, succession, election, and responsibility handling, across both civilization-level and site-level entities.

The mechanics described here are based on empirical testing in world generation and fortress mode, supplemented where necessary by raw analysis. In several cases, the game’s behavior is determined by evaluation order and interaction between multiple tags, rather than by individual tokens in isolation.

This page is intended for modders and advanced players who are designing or debugging custom entity position structures. It does not restate basic position mechanics, but instead highlights edge cases, non-obvious interactions, and behaviors that may appear inconsistent or undocumented.

Unless stated otherwise, the described behavior applies to current versions of the game and may differ from older releases.

==What is an entity? What is a position?==
An [[entity]] is an organizational structure that can have relationships with other entities, usually known as a [[civilization]] or a "[[site]] government" in the game, but ie. merchant [[company|companies]], [[Mercenary#Mercenary_Orders|mercenary orders]], [[guild|guilds]], [[religion|religious organizations]], bandits and necromancer towers are also entities (and necromancer towers use the same entity type as "site governments"). An entity can have positions - in most cases, these are hardcoded and generated by the game, but as for civilizations and sites, the [[raw file]]s can be customised.

A position is a special relationship between a unit and an entity. The unit holding a position has a larger influence over that entity than other citizens. Positions are mostly known as [[nobles]], but in this article. the technical term is used.

=Position levels (Site/Civ) and their interaction=
There are two basic types of positions that are customizable: '''civ(ilization)''' level and '''site level'''. Positions with the tag [SITE] are at site level, positions without the tag [SITE] are at 'civ level'. These two types of nobles can be considered '''loosely related systems'''. There are a few places where they can interact with each other.

Civ-level positions are in charge of the civilization as a whole, managing national [[trade]], laws, and [[war]]s. These are, for example, the vanilla [[monarch]], [[diplomat]] and [[general]]. (Note that the general doesn't really do anything, except creation of additional pets in world-gen for the general and possibly raising the animal training knowledge of the civilization to "general familiarity".)

'''[LAND_HOLDER]''' nobles are also positions at civ-level. These units are members of the national government, but have gained authority over some land or site. Once they do, they move to that place, but their position is still regarded as a civ-level position.

Site-level position holders are members of a site government (subsidiary to the civilization), and manage local affairs in that location. These are, for example, the [[mayor]], the [[sheriff]] and the [[broker]].

==Table of interaction between different position levels==
In this table, the possible interactions between different position levels are summarized.
The header row shows the positions defining the tokens.

The left column shows the position type that is referred to.
Example:
{| {{prettytable}}
|- bgcolor="#ddd"
! referred position-type
! LAND_HOLDER
|-
| civilization
| (baron is) APPOINTED_BY:MONARCH
|}
color coding: 
* Exists in vanilla
* Possible with mods
* Not possible
* possible to some extent.
* not yet fully investigated.
{| {{prettytable}}
|- bgcolor="#ddd"
! referred position-type
! Civilization
! SITE
! LAND_HOLDER
! CONQUERED_SITE

|-
| Civilization
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION '''(1)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION

|-
| SITE
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION '''(2)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY '''(3)''' COMMANDER REPLACED_BY SUCCESSION '''(4)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION

|-
| LAND_HOLDER
| APPOINTED_BY COMMANDER REPLACED_BY '''(6)''' SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION '''(5)'''
| APPOINTED_BY COMMANDER REPLACED_BY '''(7)''' SUCCESSION '''(8)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION

|-
| CONQUERED_SITE
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
|}

Remarks:
# Works only in world-gen, if a unit with that civ-position is present at the site.
# Works only in world-gen, the site-position holding unit will then move to the capital.
# Is completely ignored
# Works only in world-gen.
# Works only in world-gen.
# Won't appear at all
# This is necessary for the landholder chain to work properly, it doesn’t work otherwise.
# This works only outside of the landholder chain, so when landholders are simply regarded as civ-level nobles. might also work in world-gen
#

== Other interactions ==

Unfortunately, interactions with positions of other entities don't seem possible, such as APPOINTED_BY: HIGH_PRIEST. With [VARIABLE_POSITIONS], positions are automatically created with codes like CUSTOM_LAW_MAKER_2, but interaction with these positions don't seem to work, either. For more info on those, see [[Variable positions]]

=General=

==Civ-level nobles living at your site==
Nobles from your civilization can come to live at your fortress. This happens in vanilla with landholders such as [[Baron]], [[Count]] and [[Duke]], with the Monarch, but sometimes also with non-landed LAND_HOLDERS.

When a civ-level noble becomes a [[citizen]] at your location, their position is shown among the site-level positions in your [[nobles screen]]. They appear to function as a site-level noble. They may have [[demand]]s, [[mandate]]s, [[squad]]s and the like. They can appoint nobles at the site-level.

Even if they have certain site related [RESPONSIBILITY]ies, they will not do the tasks that go with them.

==Fortress mode, world-gen and their differences==
Their are a few differences in how positions function between fortress mode (normal play mode) and the world generation (world-gen).

In '''fortress mode''', the player has some control over the appointment of nobles, limited by elections, automatic filled-in positions and succession rules. Pre-fortress mode, which is referred to as '''world-gen''', the game will always attempt to assign nobles whenever possible. It is subjected to the same rules as in fortress-mode, but there are some exceptions. In '''[[World activities]]''', which is the thing that happens in the world while you play fortress mode, it seems as if the same rules are applied as fortress mode.

A difference between player-fortress-mode and world-gen, is causes by visibility (see below). Positions that are not visible by the player and thus not available for assignment, will be available in world-gen and will thus be automatically assigned.

In fortress mode, a position that is both [ELECTED] and [APPOINTED_BY], cannot be appointed by the player and is also not elected, and can thus not be filled. But in world-gen sites however, these positions are automatically filled.

Positions with [AS_NEEDED] are almost never created and filled in world-gen (depending on their [RESPONSIBILITY]ies), but can always be used in player mode.

A position can, in fortress mode, be filled by the same unit. A unit can gain multiple positions in fortress mode, for example because of [[elections]]. This will not happen in world-gen mode: a unit can only have one position. See also remarks on 'embark' and 'Losing a position'.

In world-gen, [SUCCESSION] between civ-levels and [SITE-]levels may happen. This will not happen in fortress mode, or even off-site in [[World activities]].

In fortress mode, premature SUCCESSION may happen. This will not happen in world-gen mode.

==Units holding multiple positions in multiple entities==
A unit can hold multiple positions in its civilisation or in its site-entity, however in world-gen a unit will not hold multiple positions in one site-entity or in one civilisation (note that in world-gen a unit can hold multiple variable positions of the same entity, if the entity is ie. an outcast group). It is however possible - in world-gen - for a unit to hold multiple positions as long as the positions belong to different civilizations / site-entities (ie. it is possible for a militia commander of a site-entity to later on also become a monarch of the parent civilization, while staying a militia commander), if a unit holds a position of two different site-entities (the unit will usually have left one of the groups, without relinquishing the position). Only at player-managed sites can units be holding multiple positions (of the site-entity) at once. It is currently unknown, whether it is possible in world-gen for a unit to have a civ-level position in two different civilisations (but it probably is possible, as a a unit can belong to multiple civilizations and a unit usually does not relinquish a position, when the unit gets another position, as long as the entities of both positions are not the same).

In world-gen, if there are too many positions to be filled, they simply stay empty until more units are available. E.G, a unit at a site might inherit a civ-level position and still remain a member of the local government. When this happens however, they move to the capital. If a unit gains a new position, either inherited or otherwise, it drops the previous one (of that civilisation or site-entity) - the unit will not drop any positions unrelated to the entity of the new position (ie. a CUSTOM_OUTCAST_FACTOR will not relinquish that position, if the unit becomes the ruler of a civilization and a militia commander will also not necessarily relinquish the position, if the unit becomes also the monarch of the corresponding civilization). If a unit assumes a civ-position in fortress mode, it leaves the current position.

If a unit holds the same (site-)position multiple times, it has no additional effect.

If a unit holds multiple different positions of the same entity, it has all those positions' responsibilities and properties, stacked up. Presumably, the demands for those combined positions are determined by the highest.

A unit holding a position with a succession token can be assigned another position with a (different) succession token.

A unit holding a position with a squad-position cannot hold another squad-position. It is dropped from the first, when it gets its second assigned.
A unit holding a position with a succession token cannot be assigned to a squad-position - the unit is simply not available. It works the other way around, though.

=Specific Tags and functions=
==[PRECEDENCE]==
The first defined position with precedence of 1 counts as the ruler of the civ. See also: [[Position_token#PRECEDENCE|PRECEDENCE]].

If the precedence is omitted or has a negative value, the game sets 0 as precedence, which seems to have no effect whatsoever.

When a unit has multiple positions, the name of the position with the highest rank in precedence is shown behind the unit's name.

If you omit precedence entirely, or set it to [PRECEDENCE:NONE], the position name will not be shown after the unit’s name. Your *Urist Mason* will remain simply *Mason*. This can be useful for positions that are unimportant or purely functional. The position will also not appear in the civilisation overview of your site on the world map. The position name is shown in messages, but remains hidden on the nobles screen as well. To make it visible there, use [LAND_NAME].

==[RESPONSIBILITY]ies==
Both civ and [SITE] positions can carry responsibilities. However, not all responsibilities are active for both types: some function only for civ positions, others only for site positions. When a civ noble arrives at a site and takes up residence, they do not perform responsibilities that are intended for SITE nobles. As a result, these responsibilities neither trigger their associated tasks nor unlock related game mechanics. For example, a civ-level manager living in a fortress will not perform management duties there and doesn't unlock the management-screen, even with an assigned office.
This behavior applies to the following [SITE]-level responsibilities:
* [RESPONSIBILITY:ACCOUNTING]
* [RESPONSIBILITY:BUILD_MORALE]
* [RESPONSIBILITY:HEALTH_MANAGEMENT]
* [RESPONSIBILITY:LAW_ENFORCEMENT]
* [RESPONSIBILITY:MANAGE_PRODUCTION]
* [RESPONSIBILITY:MEET_WORKERS]
* [RESPONSIBILITY:TRADE] (functions differently)
Other responsibilities may be affected as well, but have not yet been fully tested.

===World-gen effects of the [RESPONSIBILITY] of available positions ===
It is possible to cause civs and individual sites to change their behavior substantially when they reach a certain size, by controlling nobles.
* If a site can only appoint a position with [MILITARY_GOALS] after reaching a particular size, that site will not send armies on missions until the required size is reached.
* A civ-level [LAW_MAKING] position is required for the civilization to have any kind of cohesion. Without it, sites will be constantly embroiled in territorial disputes and civil wars will be commonplace.
* [MILITARY_STRATEGY] positions go out and tame wild animals. This makes your civ gain those animals as domesticated and also brings them in sieges.
* The [[Personality_facet|Personality]] of the position's holder determines how they lead the civ.

===[DELIVERS_MESSAGES]===
The only [AS_NEEDED]-position that is created in worldgen based on responsibility is that of the site-level responsibility [DELIVERS_MESSAGES].

===Outpost Liaisons and Diplomats===
Civ-positions with the responsibility [ESTABLISH_COLONY_TRADE_AGREEMENTS] ([[Outpost_Liaison|Outpost Liaison]]s) will meet with the site-noble who has responsibility for [RECEIVE_DIPLOMATS] and the highest rank of precedence (i.e. the lowest precedence value). Usually this is the [[Expedition_leader|Expedition leader]].

Once a [LAND_HOLDER] is assigned to the site, civ-positions with the responsibility [MAKE_TOPIC_AGREEMENTS] ([[Diplomat]]s) will meet with '''civ'''-level nobles present at the site who have the [RECEIVE_DIPLOMATS] responsibility. If multiple eligible nobles are available, one is selected at random. If no eligible noble is present, the diplomat leaves angrily. If the landholder is no longer present at the site, diplomats will not arrive at all.

It appears that Outpost Liaisons and Diplomats are chosen for a diplomatic mission based on availability. When multiple candidates exist, the position defined last in the raws is most often selected.

===[TRADE]===
Civ-level nobles with [TRADE] will arrive with the caravan, just as the Outpost Liaison. Their behavior is no longer active in the vanilla game, but the mechanics are still present. See [[40d:Guild_representative|Guild representative]] for more details. This civ-noble will only meet with the SITE noble with [TRADE], usually the [[Broker]].

If two civ-nobles exist with both [TRADE] and [ESTABLISH_COLONY_TRADE_AGREEMENTS], they both arrive at the same time. Even if both tokens are assigned to a single position, if more than one instance of that position exists, two of them will arrive. However in that case, somehow the elevation of the site and appointment of landholder isn't offered.

If the SITE-noble they intend to meet has both [TRADE] and [RECEIVE_DIPLOMATS], only one meeting will proceed and the other is cancelled. However, when two SITE-nobles are available, each with either [TRADE] or [RECEIVE_DIPLOMATS], both meetings will proceed and both civ-nobles will attempt to negotiate a trade agreement. It is not known what happens if these agreements are accepted or refused.

In the trade depot, the last defined position with the [TRADE] responsibility is shown as broker. However when requesting a trader, the first defined position with [TRADE] will actually go there to do the trade.

==[NUMBER]==
A position might be defined with a number. In that case, as many as defined can be available. If the positions become available, in world-gen and when embarking, they are all filled-in completely.

If the ruling position (with PRECEDENCE of 1) has a NUMBER higher than 1, a random unit of the ones holding these positions is shown as ruler in the embark screen.

A [NUMBER] of 0 (zero) has the same effect as 1.

===Automatic spreading of assumed, non-singular positions===
If there are civ positions that have a NUMBER higher then '1' and which are assumed (not APPOINTED_BY or ELECTED) but are '''not DUTY_BOUND''', these are automatically spread among the civilisation, based on population. If there are a number of '''20''' available slots of that position, they spread among a civilization with a combined population of, for example, 1000 of which your fortress has 100 (10%), '''2''' of your fortress' citizens will assume that position.
This may probably also work with elected and appointed positions, but that may be depending on the death of the current holders and this needs more testing. Assumption works within a day, anyway.

===[AS_NEEDED]===
These positions can be created automatically by the game in world-gen. This, however, only works with:
* [LAND_HOLDER]'s
* squad commanders (needs more testing)
* Messengers at sites

For all other types of positions, they're not created in world-gen, even if they are defined with RESPONSIBILITY's. For example, even in war, the game wouldn't create a MILITARY_GOALS position, if they have AS_NEEDED as number.

However, in fortress mode / player mode, these positions can be created by the player at will.

Positions with AS_NEEDED need to be created first, before any symbols are assignable as 'symbols' (objects) for the position holder to carry or wear.

Positions with AS_NEEDED cannot be created and then ELECTED in fortress mode. It only works with APPOINTED_BY.

==[REPLACED_BY], [REQUIRES_POPULATION], [REQUIRES_MARKET]==

The token [REPLACED_BY:position] means that once the replacing position meets its requirements for activation, the 'to-be-replaced' position will disappear. This is defined in [REQUIRES_POPULATION] or [REQUIRES_MARKET]. The tags are closely related to each other and seem to only have a meaningful function if combined. Nobles with [REQUIRES_POPULATION] require the population to have a specific size. Nobles with [REQUIRES_MARKET] are only activated in market sites, such as fortresses or towns. [REQUIRES_POPULATION] and [REQUIRES_MARKET] can be combined, activating that position once both requirements are met.

The [REQUIRES_MARKET] can be used to differentiate positions between hamlets and hillocks, and larger sites. IThe market always is build the year after the site is founded. So a position that is to be replaced, will be gone immediately.

The [REQUIRES_POPULATION]-tag works on the civ-level as well as on site-level, but those systems are in this mechanic strictly separated. Site-level positions cannot be replaced by civ-level positions and visa versa. This makes sense, because they both depend on their own population-count. When using REQUIRES_POPULATION on civ-level, it counts the total population of the civilisation.

See also: [[Advanced_entity_position_mechanics#Evaluation_of_Positions|Evaluation of positions]]

===Effect of replacement (and on [LAND_HOLDER]s)===

Replacement is immediate and complete - the current holding unit loses the position, even before SUCCESSION_BY_POSITION rules are applied. A position with a number of 1 will replace all the slots of a position with a higher number of slots.

Even if the next position is available but not visible, replacement still takes place. If a position is replaced, it is completely gone - it cannot be appointed, succeeded, elected or assumed any longer.
The unit immediately loses its position.

In legends, replacement is mentioned as: "(unit name) ceased to be (position name)" The replacement of an AS_NEEDED position empties the position's slot forever. In fortress mode, it may seem as if you can create new slots and appoint new units in the nobles screen, but this is reversed as soon as you close the window.

The landholder chain uses [REPLACED_BY] differently. It does not clear the position completely, but uses it for succession to the next level's position. [REPLACE_BY] is required to let that system work properly. This also means that the way in which landholders succeed (replace + as_needed) does not work in any other way.

Replacement between LAND_HOLDERS and other site- or civ positions does not work in any way. Only the vanilla replacement sequence between levels of LAND_HOLDERs does work. If the token is omitted for landholders, the landholder chain is broken, so replacement is required for the landholder system to work.

[REQUIRES_POPULATION] also does not work for [LAND_HOLDER], when you set [NUMBER] to 1. The position is not created when the required population is reached.

===What doesn't work===

'''Attention: If a position cannot be appointed, for example because of 'mutual appointment', it still exists according to replacement mechanics and will replace other positions if so defined. If a certain position(a) will be replaced by the baron's assistant, which can only be appointed by the [LAND_HOLDER] baron, than that position(s) still will be replaced from the start of the game, even if no baron or their assistant is ever present.'''

A position that is replaced by a somehow non-fillable position is still replaced. This counts for mutual-appointing positions, replacement by not-yet-assigned landholders, replacement by AS_NEEDED positions, or replacement by not-yet-appointed positions.

Replacement does not work if the replaced position is a [LAND_HOLDER], even with civ-positions. In that case, the LAND_HOLDER's position is not replaced. It does not matter if AS_NEEDED is used, or a fixed number, and it also does not matter what type of position the replacer is. So this only works (correctly) with positions that become available by REQUIRES_POPULATION.

==[CONQUERED_SITE]==

This tag determines which position is used to assign a [[Forced administrator]].

In legends mode, this is visible as an event describing the reconquest of the site: a new group is formed and the forced administrator is installed as its ruler.

All positions defined with this tag are assigned during this process, meaning multiple positions can be appointed at once.

The holder of a position marked with [CONQUERED_SITE] cannot appoint any other [SITE] positions.

Combining [CONQUERED_SITE] with [SITE] causes the position to function both as a forced administrator and as a normal site position available in fortress mode. However, this provides no meaningful additional mechanics and is effectively inferior to using [SITE] alone:
* [APPOINTED_BY] lines are completely ignored, meaning that the roles are automatically assumed.
* [SUCCESSION] is likewise ignored.
* the [CONQUERED_SITE]-position cannot appoint other [CONQUERED_SITE], [SITE] or combined positions.

There have been remarks that reclaiming a fortress is unplayable because of the lack of regular nobles. Unfortunately, it seems that it can't be fixed by modding.

=Availability and visibility=
==Availability of (new) positions==
Warning: Do not mistake "availability" for "visibility"!

Of all the possible positions existing in your site's entity, there may only be some available.
* Positions with [REQUIRES_POPULATION] require the population to have a specific size.
* Positions with [REQUIRES_MARKET] will only appear in "large" sites (which may have different rules for different site types). This tag has no effect in fort mode.
* Positions that are appointed by positions that have an AS_NEEDED number. The appointable positions only become available after an appointer position-slot is created. This works also on civ-level. If a position is appointed by a Land-holder, it only becomes available, when that level of landholder is created.

Only the replaced positions are culled and are no longer available.
A position that requires a certain population will become available, even if it doesn't have [APPOINTED_BY] or [ELECTED]. In that case, see 'automatic assignment' and 'assumption'

In fortress mode, in some cases 'succession' is evaluated immediately after a position becomes available. See: Succession.
==Visibility of positions==
A position might be available, but can still be invisible for the player in the [[nobles screen]]. The positions with their respective holders are visible for players:
* All site-positions that are already filled-in (even if they could not be re-filled-in considering current conditions)
* Site positions that are appointable by a filled-in site position
* Site positions that are appointable by a filled-in civ position, when that civ positions holder becomes a citizen of your fortress.
* Civ positions of units that are also a citizen of your fortress.
If a position becomes available, for example because a certain pop number has been reached, or if it is available from the start(like expedition leader), as long as it cannot be appointed, it still is INVISIBLE for the player.

It might strike someone as odd if a position becomes filled automatically in fortress mode when that position is not even visible. This might be the case if the current holder of a non-appointable position dies or succeeds another position. Regardless of player visibility, these positions will be automatically filled in if the necessary requisitions are met. It might happen with the expedition leader.

A situation with a non-visible but available position, is for example when a position is solely appointed by the expedition leader, when the expedition leader's position is left vacant. It can no longer be appointed by the player and is invisible. Then, it gets automatically assumed, proving that the position still was available.

A position that is both [APPOINTED_BY] and [ELECTED] is visible, but players cannot interact with it.

={{text anchor|Evaluation of Positions}}=
The game does not continuously check whether positions should become available, elected or be [REPLACE_BY]. This is well-known behavior—for example with the [[mayor]], who does not appear automatically when the required population ([REQUIRES_POPULATION]) is reached. Instead, positions must somehow be evaluated. This applies in several other situations as well

'''Cases that require a trigger:'''
* Election of a newly created position
* Election after the current holder dies
* Automatic assumption of a newly created position (this may take up to a day)
* New citizens (such as migrants) considering available positions
* Premature succession of a newly created position

'''Cases that do not wait for a trigger:'''
* Succession following the death of the previous holder
* Automatic assumption of existing positions that have become vacant

'''Triggers that cause the game to reevaluate noble positions:'''
* Succession of a [SITE]-position due to the death of the current holder
* [[Advanced_entity_position_mechanics#Election_Day|Election Day]]
* Automatic assumption of a [SITE]-position that becomes vacant
* (Re)assigning any site position manually
* Settlement elevation on the LAND_HOLDER track (e.g. gaining a [[Baron]] or [[Count]])

=Gaining a position=
There are several ways a unit can gain a position:
* Appointment: A unit is appointed by another unit or by the player.
* Election: A unit is elected by and among the members of the entity
* Assumption: A position is neither elected or appointed: a random unit just simply 'takes' the position
* Succession: a unit is the valid successor of this position(A), either by its current position(B) or because they are that position(A)-holder's heir.

Available positions will automatically be assigned to a random civ member when a new site/civ is created.

==Who can take a position==

* If so defined, a unit needs to be the right caste and/or class - it does not seem to work with creature types.
* The unit needs to be an adult member of the site or its parent civ's government; that is also CAN_LEARN or INTELLIGENT (SLOW_LEARNER cannot take positions) or otherwise is able to think.

==Appointment==

Positions that have an [APPOINTED_BY:position] token require that position to exist, to be available and appointed. Any position that is APPOINTED_BY can be appointed if the appointer's position is filled in.
For site-positions to be appointed, it is required that the appointer is present at that location.

If the appointing unit is temporarily not present, or if that position is not filled, positions depending on it cannot be appointed. This is the case with [[militia captains]], when the [[militia commander]] is on a [[mission]].

A site position cannot appoint a civ position ''or'' LAND_HOLDER in any way whatsoever.

Civ-level positions can appoint other civ-level positions and site-level positions can appoint other site-level positions.

Contrary to what has been said elsewhere, civ-level nobles also can appoint site-level nobles. They need to be at the site to do so. Landholders can appoint both site-level and civ-level nobles. These systems are therefore not as separate as was assumed.

'''Mutual appointment''' cannot take place. If these are the only requisites of the position, then the positions will never appear or get filled. These unfillable positions can be put to good use, for example, to replace a position that is no longer needed without creating a new one.

'''Self appointment''' doesn't normally work. If you have a position that is only appointed by itself, it is never appointed and also cannot be assumed. However, if the position has a number higher than 1, and is filled by multiple units (for example by another position that is now empty), than those units can re-assign or appoint each other from that their shared position.

If an APPOINTED_BY token refers to a non-existing position's code, the effects are as if the appointment token doesn't exist at all.

===Automatic appointment in world-gen and on the civ level===

Outside of fortress mode, the game will always attempt to appoint nobles whenever possible, as long as these positions are '''available''', even if they are invisible to the player.
It shows this message in legends: "(unit name) has been appointed to the position of (position name)"

In world-gen, all positions become available and are automatically appointed, taking population- and appointment-requirements into consideration.

Positions that are REPLACED_BY are culled and won't be filled.

If a citizen of your fortress holds a civ-level position that can appoint another civ-level position, the appointment will happen automatically and without player intervention. It may happen that another citizen of your fortress is appointed by that unit, creating civ-level position holders in your fortress, but it is unknown what is required to force this effect.

===Manual appointments by players in fortress mode===
In fortress mode, the positions that need to be appointed stay empty on embark. and it is the player's job to appoint those. A player can appoint a unit to any available position, according to the hereabove mentioned conditions. The player takes the role of the automatic appointment-system, but has no direct control over elections, successions and replacement. There are some differences in what is possible at world-gen sites and at player-controlled sites.

* A position that is appointed by a unit present as a fortress citizen, can be appointed, re-appointed or left vacant. This means also by civ-level nobles living as a citizen in your fortress; not when they are only visiting, like the diplomat.
* A position whose appointing positions are all either vacant or [REPLACED_BY] can no longer be appointed. If the position is already filled, it cannot be reappointed or vacated; the current holder simply remains in office.
* A position that is APPOINTED_BY a unit present as the land_holder of your site, can be appointed, reassigned or left vacant.
* A position that has SUCCESSION BY_HEIR or BY_POSITION can 'initially' be appointed and also re-appointed or left vacant, but as soon as the [[nobles]] screen closes, ''it can no longer be replaced or left vacant''. From then on, the succession-rules determine who gains that position when the current holder loses the position. This works even if the SUCCESSION:BY_POSITION-position is vacant or replaced.
* A position that is ELECTED nor APPOINTED_BY, can always be (re-)appointed by the player. This is the case with the [[Expedition leader]]. If it is left vacant however, it cannot be appointed, but will be assumed shortly after.
* A position that is both ELECTED and APPOINTED_BY, cannot be appointed by the player. Contrary to world-gen sites, its slot is visible, but it doesn't show the +-sign. This is either by AS_NEEDED or by a fixed number. Even if the position somehow gets filled (re)assignment is never possible
* A player can appoint a number of units to a position, as much as the NUMBER token dictates. If it is AS_NEEDED, the player may create as many slots as they like, also contrary to world-gen sites.
* A civ-position can never be appointed, even if the appointing civ noble is a citizen of your fortress. A civ position also never can be re-assigned or left vacant, would that position be defined as appointed by a site-position.

==Election==
Read more in [[Elections]]. The message that is shown is: "(creature name) has been elected to the position of (position name)"

In worldgen, there is no functional difference between ELECTED and non-appointment, except that elected nobles tend to have high social skills and/or skills related to the position, while non-elected ones are assigned randomly. See: [[Elections]]

A succession goes before an election.

A position that is both ELECTED and APPOINTED_BY never gets elected. Even if the appointees' position somehow gets filled, (re)-elections won't happen. So, it doesn't seem possible to have an elected position become available when a certain other position becomes filled.

An ELECTED civ-(or LAND_HOLDER) position at your site will never be (re)-elected in fortress mode. So real (re-)election only works with SITE-positions.

=== {{text anchor|Election Day}} ===
Election Day takes place on the 17th of Summer. On this day, a full reevaluation is performed, including all currently elected positions, which are subject to re-election. Contrary to the information on [[Elections]], nothing occurs at the start of a season.

Positions that are both [APPOINTED_BY] and [ELECTED] will not be re-elected on Election Day when assigned through [SUCCESSION].

=== Election Eligiblity ===
Any citizen may stand for election. Eligibility cannot be restricted using [ACCEPTED_CREATURE], [REJECTED_CREATURE], [ACCEPTED_CLASS], [REJECTED_CLASS], or [GENDER]. Units currently having a [SUCCESSION]-position even may be elected for a position with a [SQUAD]-token, which is otherwise impossible to assign or even succeed.

=== Skills ===
In elections, skills are taken into account for the tokens of the position which is elected.
{| class="wikitable"
|+ Relevant skills per position token
|-
! Position Token !! Relevant skills
|-
| Responsibility [[Position_token#DELIVER_MESSAGES|[DELIVER_MESSAGES]]] || [[Ambusher]], [[Observer]] and [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#ACCOUNTING|[ACCOUNTING]]] || [[Record_keeper|Record keeper]]
|-
| Responsibility [[Position_token#ESPIONAGE|[ESPIONAGE]]] || [[Schemer]]
|-
| Responsibility [[Position_token#HEALTH_MANAGEMENT|[HEALTH_MANAGEMENT]]] || [[Diagnostician|Diagnostician]]
|-
| Responsibility [[Position_token#MAKE_INTRODUCTIONS|[MAKE_INTRODUCTIONS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#MAKE_PEACE_AGREEMENTS|[MAKE_PEACE_AGREEMENTS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#MAKE_TOPIC_AGREEMENTS|[MAKE_TOPIC_AGREEMENTS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#MANAGE_PRODUCTION|[MANAGE_PRODUCTION]]] || [[Organizer]]
|-
| Responsibility [[Position_token#MEET_WORKERS|[MEET_WORKERS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#RECEIVE_DIPLOMATS|[RECEIVE_DIPLOMATS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#RELIGION|[RELIGION]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#TAME_EXOTICS|[TAME_EXOTICS]]] || [[Animal_trainer|Animal trainer]]
|-
| Responsibility [[Position_token#TRADE|[TRADE]]] || [[Social_skill|Social skills]] and [[Appraiser|Appraiser]]
|-
| [[Position_token#SQUAD|[SQUAD]]]-token || [[Tactician]] and [[Leader]]
|}

==Assumption==

A position that is not APPOINTED_BY nor ELECTED, or is appointed by positions that are not available in your site or civ, will be assumable by a random dwarf. If it has responsibilities that require certain skills, then these are taken into consideration on embark, but not when the position is assumed during the actual game.

Normally, one to three units will take the into consideration to assume a position. Most of the time when there are multiple open positions, only a single unit will assume all of them. However, a position that has REJECTED_CREATURE, REJECTED_CLASS, ALLOWED_CREATURE or ALLOWED_CLASS will be filled with all different units, even if the creature or class mentioned is irrelevant. It seems that this forces the game to loop over all the available units.

The message that is shown in Legends mode is: "(unit name) has assumed the position of (position name)". This may also take place in fortress mode, which then shows this message to the player.

If an assumable position becomes empty, it will be assumed within a day. This is the case when you leave the position of expedition-leader vacant. It also happens with entities.

Assumable positions that become empty will not be assumed if that position has a valid [SUCCESSION] -successor. In that case, the successor inherits the position.

Even positions that are somehow invisible because they cannot be directly APPOINTED_BY players, can be assumed.

When you embark, the assumable positions are automatically assigned to a random unit. If there are multiple of these positions at embark, they all are assigned to the same unit. If there are enough positions available, multiple units may gain a position, but often no more than three different ones.

If a dwarf in fortress mode assumes a position, that already has another position, it will leave the current position empty. When that position also is assumed, then this will continue until all positions have a dwarf appointed to them, with no other position.

A unit that already has a position with a [SUCCESSION] token won't take assumable positions into consideration that have a [SQUAD] token. This can be used by the modder to prevent unwanted loss of current positions.

A position that has an appointer which got replaced because of REPLACED_BY, will not become assumable. Also, positions that have an AS_NEEDED appointer that is not yet filled (or ever), will also not be assumed.

==Succession==

If a position-holder dies or advances to a new position via succession, the position will be granted to another unit based on the [SUCCESSION] tag. If they have an heir or the succeeding position exists, that unit will be assigned. If not, a new one will be appointed according to the usual rules. The message that is shown is: "(creature name) being the rightful heir, has inherited the position of (position name)"

The succeeding creature will also lose its previous position. When succession is defined using BY_POSITION, the unit naturally loses the referenced position. However, it also loses any other positions it may hold. If a unit could simultaneously inherit multiple positions, the last-defined succession overrides the earlier one, clearing the previously acquired position

Succession works both at site-level and at civ-level, both in world-gen and in fortress-mode. Succession by position on the civ-level is also visible and functional in fortress-mode. If both civ-level nobles are a citizen of your fortress, succession is applied visually. Vanilla example: The [[druid]] is succeeded by the [[acolyte]]. This means that as soon as the druid dies, the acolyte takes over.

When a position that is succeeded by position becomes available, immediately it is checked if a position-successor is available and the position is filled with that unit. Even if this is an [ELECTED] position, succession goes first. When elections eventually do happen, succession plays no role.

It is possible to assign multiple levels of [SUCCESSION:BY_POSITION] in different positions, creating a line of positions where the death of one causes all those "below" them to advance.

A position can have multiple tokens with position-succession. It looks to be random which one is used. It is not always:
* The first or last defined token
* The first or last appointed unit
* the oldest or youngest
* one with a higher or lower precedence
* a unit with relevant skills

When a position is defined with a Succession-type, that unit cannot have another position that has a Squad-type. If the succession-position itself has a squad, than it can be assigned another position with a squad, but then it will loose the previous succesion position. See further details by "Squad"

Assumed positions can also be succeeded by position, if the current holder dies.

If the successor is an AS_NEEDED position, the used unit will leave a vacant position-slot on its removal by succession. This empty slot remains a real slot, which will only be cleaned up if you (un)appoint a unit to this position-series. It isn't cleaned up after regular position validation.

A civ-level position of a unit living at your site might be inherited by a unit holding that does not currently live at your site. This, unfortunately, moves that position to a unit off site. This may also happen with the landholder of your site, for example when it is succeeded by another civ-level position. This currently poses an unsolved challenge.

===Eligibility for succession===
Succession is restricted by the tokens [ACCEPTED_CREATURE], [REJECTED_CREATURE], [ACCEPTED_CLASS], [REJECTED_CLASS] and [GENDER].

===Site and civ combined succession===

Succession can work when combining site positions with civ-level positions or land_holders, but only in world-gen mode. In fortress mode, it only works with combining the same level of nobles, with Landholders regarded as civ-level. So, in fortress mode, a site's position cannot succeed a landholder's position and it cannot succeed another type of civ-level position, and vice versa.

This won't work even if the positions:
* are AS_NEEDED or having a fixed number.
* Are LAND_HOLDERs.

===Succession [BY_HEIR]===

When a heir is needed for succession, all children and then other relatives are validated. They cannot take the position if their status does not allow it, for example if they have become a member of another civilisation. See: "Who can take a position". If the unit has no valid heir on that location, the position may go to a unit living on another site. This may cause the title of Landholder of some land to be inherited by a unit living somewhere else. That might be a problem, because then you lose your landholders.

===Premature Succession===

There are cases where [SUCCESSION:BY_POSITION] is applied prematurely: at the moment a position is first created and becomes appointable or assumable, rather than after a current holder leaves. In this situation, the succession mechanism assigns a holder immediately, without any player interaction.

When a position becomes available for the first time, the game checks whether a valid successor-by-position exists. If so, that unit is assigned instantly. It can affect positions that would normally be appointed or elected by the player, causing succession to trigger before the player has any opportunity to intervene.

This behavior occurs only in Fortress mode, but can be applied both on [SITE]-positions as well in civ-positions. That last one however is a bit harder to control. Example: [[Advanced entity position mechanics#The Archduke|The Archduke]]

This premature succession only occurs the first time a position becomes available (i.e. when it is created and becomes appointable or assumable). Even if the position remains vacant and the conditions for succession improve later, premature succession will not trigger again. From that point onward, only normal succession rules apply.

Using premature succession, a position that has [ELECTED], [APPOINTED_BY], or both, can be filled directly.
Notably, positions that combine [ELECTED] and [APPOINTED_BY] are normally impossible to fill through regular mechanics. Premature succession bypasses both election and appointment entirely, making this combination uniquely reachable through this mechanism.

No initial election takes place, and no subsequent elections will ever occur for that position. Succession always takes precedence over election, both in premature succession and in normal succession cases.

This behavior applies only in Fortress mode, not during world generation. World-gen uses simplified and more efficient mechanics, and this interaction does not occur there. Premature succession can affect both site-level and civilization-level positions.

====Multiple succession chains====

Multiple succession chains may be defined and are resolved in the order they appear in the raws.

If a position has both:
* a direct succession chain (A → C), and
* a multi-step chain (A → B → C),

and intermediate positions are vacant, resolution proceeds according to raw order. A common outcome is:
# The direct succession (A → C) is applied first, assigning A to C.
# The remaining chain then advances (A → B).
# If C still has empty slots, the final step (B → C) may occur.

If position B is already filled, behavior depends entirely on raw definition order:
* nothing may happen, or
* B may move to C first, followed by A moving to B.
====Working triggers====
Premature succession is triggered when a succeedable position is created under the following conditions:
* The succeedable position is created because its [REQUIRES_POPULATION] threshold is reached. This applies even if the position is not [APPOINTED_BY]. Premature succession takes priority over automatic assumption (e.g. the mayor declaring themselves within a day).
** The position must either be assumable or appointed by an existing position. When said appointer-position also just has been created, the premature succession of the succeedable position happenes, even when the appointer-position is empty.
* The succeedable position can be [APPOINTED_BY] another position of the same level (site or civ) that has just been created because its [REQUIRES_POPULATION] was reached.
* The succeedable position can be appointed by another [SITE] [AS_NEEDED] position that has just been created and filled.
* The succeedable (site or civ) position is [APPOINTED_BY] the [LAND_HOLDER] position, which has just been created due to site elevation. This typically resolves when the diplomat leaves the map, at which point the landholder position becomes active.
* If all other requirements are met, premature succession can occur immediately after unpausing following embark, for positions with [REQUIRES_POPULATION:7].

====Non-working triggers====
Premature succession does '''not''' occur in the following cases:
* An [AS_NEEDED] succeedable position slot is manually created by the player while its succeeding position is already filled. [AS_NEEDED] positions must always be appointed after creation.
* The succeeding position is filled after the succeedable position becomes available. The moment of creation is the decisive trigger; filling the source position later is too late.
* The succeedable position can be appointed by another site or civ position with a fixed number of slots that has just been appointed. In this case, the succeedable position is just available for appointment itself, nothing more
* Any situation occurring during world generation.
* The succeeding position is [REPLACED_BY] the succeedable position. In this case, replacement removes the unit from the source position first, leaving no holder available for the succession mechanism to use.rst, leaving no holder available for the succession mechanism to use.
* The position is [APPOINTED_BY] a civ-level position, that just became a citizen of your fortress. It must be noted that those civ-level positions were active all that time and the succeedable position could be appointed even before. The monarchs arrival does not trigger premature succession

=Losing a position=

A unit can lose a position when:
* It dies
* It succeeds another position, even if it has nothing to do with the previous position.
* It is assigned to another SQUAD-holding position
* It is convicted of a crime.
* Another unit is ELECTED for the position
* It is convinced by an adventurer to give up its position
* It is overthrown in a coup.
* Its position becomes replaced
* Another unit is appointed by the player, or the position is left vacant.
* It has assumed another position (of the same entity), as this always leaves the previous position vacant.

Note: A unit does not lose a position, when the unit leaves the group (entity). Neither will a unit lose a position, if the corresponding entity is considered to be dead.

=Embarkment=
Two types of positions are automatically filled by embark.
* Positions without [APPOINTED_BY] or [ELECTED] (assumable). All these positions, even with a NUMBER higher than 1, are all filled with one to three dwarves. Contrary to assumption, this doesn't take into account any limitations. REJECTED_CLASS, ALLOWED_CLASS, REJECTED_CREATURE, ALLOWED_CREATURE and GENDER are applied, but without the normal spread you may expect with assumptions. Also it doesn't look at [SUCCESSION] and [SQUAD] limitations.
* Positions that are elected are filled-in by the normal election rules.

Positions that have a defined appointer are never initially filled at embark.

All positions that don't have [REQUIRES_POPULATION] or with a [REQUIRES_POPULATION] of 7 or lower, will be available at embark.

=Land Holders=

A Landholder is a '''special civ-level noble''' who gets a certain piece of land to hold, when that land is elevated to a certain level, determined by the tag [LAND_HOLDER] and by the landholder triggers in the game's settings. In vanilla, these are the baron, the count and the duke.

A unit gaining the landholder position does not migrate to that specific named land. In world-gen, they stay just where they are, probably at the capital. In fortress mode, you can suggest a citizen for the role. So for the time being that works.

Succession is then a real issue. If you use BY_HEIR, its solved when that landholder has children living at your site. But when its not the case, the title just goes to anyone randomly. Succession BY_POSITION works, but only in the civ-chain, and there's no way to guarantee a civ-holder is at your site at that time. Even with 'automatic spread' positions, it goes to one of them randomly.

==Functioning of the regular landholder chain==

The distinct difference between a landholder and a regular civ-level noble, is that a landholder may gain the position of landholder "of (sitename)" They are then seen as ruler of a particular site.

For a land_holder position to function as such, it has a few requirements:
* NUMBER:AS_NEEDED
* The first landholder-number of 1 is defined.
* No SITE (so civ) tag in that position.
*REPLACED_BY the next level landholder
If a landholder is defined with differentiating properties, it will function like a regular noble. A higher-up landholder that lacks the required tokens or connections will then not be used in elevation.

If a fortress meets the trigger for a new LAND_HOLDER tier when a caravan leaves, then the next time the outpost liaison or equivalent arrives, they will offer to make you an official colony, which will allow you to select all positions for that LAND_HOLDER level. Each time they appear, the outpost liaison will only promote your fortress one tier up the LAND_HOLDER track.

The landholder's LAND_NAME is not required for the functioning of this system. If omitted, messages will be shown with a more generic text.

==Appointment==

This mechanism differs from the regular methods of position management. It ignores all regular appointment- and election rules, so it more or less functions like automatic assignment. A landholder is, in vanilla, appointed by the monarch. Changing this doesn't seem to do anything. If they are appointed by a site-position, a not-yet-existing civ-position, or not appointed at all: the system keeps working as usual.

A landholder can appoint civ-positions and site positions. This works as expected: the positions only are appointed then when that landholder becomes available on civ-level or when he arrives at that site for site-level positions.

If your rank of landholder is the first of its rank in the realm, and is the sole appointer of some civ-position, then immediately as it gains the title, it will appoint the empty civ-slots. This may happen on your site, but the frequency and certainty is hard to determine.

==Succession==

Succession rules are applied to some extent:
* In world-gen it works according to succession rules, and site-positions can be used here. This means that a site position or a civ-position can inherit a landholder position, and vice versa.
* In fortress mode, once a landholder has been appointed, it then can inherit civ-level positions, and vice versa. This means that your baron can become king.
* Succession rules do not apply within the [LAND_HOLDER] chain; a count will not inherit a baron's land. This is because succession does not work well with the AS_NEEDED token.
* Premature succession works in fortress mode with landholders. If a unit gets a landholder's position and that landholder is the appointer of an as yet empty position, which is defined as succeeding from a third one, then the succession is immediately applied. The landholder themselves can even be the successor of a newly created position.
* A landholder's position is, in fortress mode, not successionable by a site-position or vice versa

===Impossibilities for succession by a site-position===
It would be very beneficial if the landholder can be succeeded by a [SITE]-position. So far, the following tests have not lead to positive results:
* making landholder and site-position both non-[DUTY_BOUND]
* make the site-position be [APPOINTED_BY] the landholder and/or the monarch
* give landholder and site-position [REJECTED_CREATURE]
* Let the monarch live at your site when succession could happen.
* Let the site-position be [REPLACED_BY] the landholder.

If the vanilla [SUCCESSION:BY_HEIR]-tag is omitted, a seemingly random unit somewhere in the realm is assigned this position.

==Nomination==

The player is able to nominate a unit to become the LAND_HOLDER, but this only works with units of [LAND_HOLDER] level 1. The player can select all units, only limited by the PRECEDENCE of the current units' positions.

A unit that has a position with a PRECEDENCE lower or equal to that of the landholder's position, cannot be selected. This means that a baron (or count) from another site or the monarch cannot be selected, because their precedence is lower or equal.

The GENDER token does not work here: also units with the wrong gender (sorry) can be selected.

==Levels==
In mods, up to 10 levels of LAND_HOLDER may be defined.

If a landholder is replaced by a wrong landholder number (1 replaced by 3), then the number 3 is still correctly attached to the settlement.

If the current landholder has the highest available landholder number, then the next elevation will not happen - the diplomat will not elevate your fortress to a higher position, even if that position might be REPLACED_BY a lower landholder.

These chains do work:
* 1 -> 2a - > 2b -> 3
* 1 -> 3 -> 2 -> 4

These chains do not work:
* 2 -> 3 (need to start at 1)
* 1 -> 4 -> 2 -> 3 (stops after 4 as the highest)
* 1a -> 2, 1b -> 2 (only 1a and 2 work, 1b is not used)

==Moving landholders==

It may happen that a land-holder no longer lives at the site which they are the landholder of, specifically when the current landholder dies, leaving the title to an heir living somewhere else.

To prevent this from happening, you can make their succession from heir and make sure that their kids live at your site. Or, you can make their position succeeded by another civ position, and make it so that this civ position is somehow available on your site. But if multiple of these positions exist, it cannot be guaranteed that a citizen of your fortress will inherit the title.

In world gen, a landholder lacking the DUTY_BOUND-token will also move to the site they like, according to legends mode.

==Replacement by a generic civ-position==

If a landholder is replaced by an AS_NEEDED non-landholder civ-position, then this will work: the current landholder loses that title upon settlement-elevation and gains that civ-title. However, the civ-title lacks the landholder-property of being attached to the land. It will not show the name of the settlement alongside the position's name. So no "minister of Shovelmounts"

If a landholder is replaced by a general AS_NEEDED civ-position, that itself is also replaced by a generic AS_NEEDED civ-position, then firstly the elevation is executed and also the unit gains that new position. However, he immediately loses it, because an AS_NEEDED position that is replaced by another position can be filled initially, but units wont be able to hold that title.

==Landholder with fixed number==

A landholder's position that has a fixed number will be created and filled directly when the civilisation is born, so this position slot is then not available for the regular landholder-mechanic and will also not be used. That landholder will thus not be attached to a settlement.

It doesn't matter if the landholder's position is connected to the regular landholder's-chain with the REPLACE_BY token.

==Responsibilities==

When given a certain [RESPONSIBILITY], a landholder may function as a regular civ-level noble. If the position has [TRADE] or [OUTPOST_NEGOTIATING] responsibilities, then the landholder functions both as a diplomat and as an actual land holder. A landholder with the [MILITARY_STRATEGY] responsibility will travel around taming creatures in world-gen, according to legends mode.

Besides that, the responsibilities work the same as with any other on-site living position-holder, civ or otherwise.

=Military=
==Squad management==
In the vanilla game, the Squad interface only becomes available after a militia commander has been appointed. Until then, the window displays:{{DFtext|You must appoint somebody first to create a squad.}}

What’s surprising is how this is determined internally. In the entity raw definition, '''only the last two positions that include a [SQUAD] token are checked''' to decide whether the interface is accessible at all. As a result, if your hierarchy defines commanders A through E, appointing '''Commander D or E''' unlocks squad formation, while appointing A–C does nothing.

In other words, squad availability is not tied to ''having a militia commander'', but to ''which specific positions happen to be last in the raw list''—a notably hacky implementation.

These 'last two' are always the last two '''available positions.''' So if they get [REPLACED_BY] or become available because of [REQUIRES_POPULATION], the game adapts to those.

==Squad assignment==

Squads can be assigned, even if the leader position has no holder.

A specific unit can only have one position associated with a squad. If it gains another 'squad holding position', it is unassigned from the first one. This does not work with a 0-squad, so only 1+squads are taken into consideration. This technique can possibly be used to distribute all positions equally among all citizens. It does however not work with election and assumption.

If a civ-level position is associated with a squad and it gets a site-level squad-holding position assigned, it loses the current civ-position.

Squads can get really messed up, if you make the position (or multiple) either elected or not-elected and not-appointed, then this can cause the game to assign multiple squads to the same unit. Automatic assignment and election does not take squads into account, but the nobles screen does. This can cause the positions to be cleared as the game figures out that they have more than one position, and immediately get elected or assumed again.

Positions that cannot have a squad-position:
* A site- or civ-position with a [SUCCESSION] token cannot be appointed a squad-holding-position. The other way around, however, does work. For example, if a site-position with a [SUCCESSION]-token is appointed to a unit that has already a position with [SQUAD]. But when that squad position is assigned to another unit, it cannot be assigned back.
* A position with [SUCCESSION] can also not be assigned as a '''member''' of a squad.
* A squad-holding position with a formed squad cannot be appointed to another squad holding position.

If a position has at least one squad member, it cannot be left vacant. First, the squad has to be disbanded, then the position may be cleared.

==0-squads==
A 0-Squad is defined in a position as [SQUAD:0:member:members]. It does not seem to do anything useful as of now.
* It cannot be used to activate the [[Squad|military interface]]
* It does not restrict the assignment of [SUCCESSION] positions.
* Assigning this position does not clear any previously held squad position.
* The [[Leader]] and [[Tactician]] skill are not marked as relevant skills and are not taken into account in elections.
* It cannot be formed as a squad.

=Further testing=
The following questions may need additional testing. Feel free to add or answer
* Everything regarding COMMANDING and army-structure
** [http://www.bay12forums.com/smf/index.php?topic=175437.msg8331668#msg8331668]
** [http://www.bay12forums.com/smf/index.php?topic=165213.msg8335682#msg8335682]
** [http://www.bay12forums.com/smf/index.php?topic=174584.msg8026854#msg8026854]
* Stuff about the monarch, its arrival and its entourage.

=Oddities (Bugs)=
Almost everything on this page could be called an oddity. Because of their unexpected usability, some may also be referred to as “undocumented features.” Others, however, are simply odd and not particularly useful, yet I hesitate to call them “bugs.”
* If a certain threshold is reached that makes an elected position electable, and the triggering event that initiates this evaluation is an assumption, then the resulting assumption works partially as an election. It referred to in the messages as an election and the [REJECTED_CREATURE]-token is not applied, like it is with assumptions.

=Examples=

===The Founder===
The founder is a single dwarf, appointed at embark. They will be the only one ever to have this position and are not replaceable. When they lose their position some way, the position will not be assumed by another dwarf.
{{gamedata|title=The Founder|
[POSITION:THE_FOUNDER]
[NAME:the founder:founders]
[NUMBER:1]
[SITE]
[ALLOWED_CREATURE:DWARF:ALL] - will only be filled at embark, but not assumable later.
[REJECTED_CREATURE:DWARF:ALL] - will only be filled at embark, but not assumable later.
[SUCCESSION:BY_POSITION:THE_FOUNDER] - not unassignable, also cannot be assigned to a [SQUAD] position.
[PRECEDENCE:200]
Non APPOINTED_BY
Non ELECTED
Optional: Add responsibilities to make the game select a unit with certain skills.
}}
===Marriage bar===
Dwarven matrons are held in great honour. Upon marriage, a female dwarf is no longer expected to perform menial labour. All dwarven males hold this position by default, granting their spouses exemption from menial work.

The position becomes available with the arrival of the first migrants; otherwise, on embark, it would be assumed by females. Its succession rule is non-functional, but this prevents the player from unassigning the position. A squad size of 1 and the succession rules together prevent a unit from assuming the position more than once.

With precedence set to NONE, the position name is hidden, while LAND_NAME remains visible on the nobles screen. All married females receive the suffix “, Mrs.” and are marked as Nobles.

The practical usefulness of this position is debatable, but it serves as a clear demonstration of several mechanics.
{{gamedata|title=Mrs. Urist|

[POSITION:MRS_URIST]
[NUMBER:300]
[SITE]
[ALLOWED_CREATURE:DWARF:MALE]
Not APPOINTED_BY
Not ELECTED
[LAND_NAME:Dwarven male]
[NAME:dwarven male:dwarven male]
[PRECEDENCE:NONE]
[SPOUSE_FEMALE:, Mrs.:spouses]
[MENIAL_WORK_EXEMPTION_SPOUSE]
[REQUIRES_POPULATION:8]
[SUCCESSION:BY_POSITION:MONARCH]
[SQUAD:1:member:members]
}}
===The Archduke===
The archduke is the leader of the civilization, but exists only from landholder 4-level. Until then, its position remains vacant. When a settlement is elevated to tier 4 (grand duke), the grand duke can appoint the ruler of the civilisation, the archduke. Because of 'Premature Succession', they themself inherit that position immediately, but only when in fortress mode. Its heir then becomes grand duke.
{{gamedata|title=The Archduke| no POSITION:MONARCH or other PRECEDENCE:1

[POSITION:THE_ARCHDUKE]
[NAME:archduke:archdukes]
[NAME_MALE:archduke:archdukes]
[NAME_FEMALE:archduchess:archduchesses]
[LAND_NAME:a archduchy]
[NUMBER:1]
[PRECEDENCE:1]
[SUCCESSION:BY_POSITION:GRAND_DUKE]
[APPOINTED_BY:GRAND_DUKE]
(add additional monarch-stuff, like spouse name, demands etc.)

[POSITION:GRAND_DUKE]
[NAME:grand duke:grand dukes]
[NAME_MALE:grand duke:grand dukes]
[NAME_FEMALE:grand duchess:grand duchesses]
[NUMBER:AS_NEEDED]
[LAND_HOLDER:4]
// Optional ...
[PRECEDENCE:19]
[LAND_NAME:a archduchy]
[RESPONSIBILITY:LAW_MAKING]
[RESPONSIBILITY:RECEIVE_DIPLOMATS]
[SUCCESSION:BY_HEIR]
[APPOINTED_BY:THE_ARCHDUKE]
(add additional landholder-stuff)

!!add to [POSITION:DUKE]
[REPLACED_BY:GRAND_DUKE]

}}
{{Category|Modding}}
{{Category|Entities}}
{{Category|Guides}}

Advanced entity position mechanics

2026-04-21T20:44:14Z

Joostheger: /* Oddities (Bugs) */

{{Quality|Fine}}
{{Modding}}

= Introduction =

[http://www.bay12forums.com/smf/index.php?topic=182239.0 Discussion thread on the forum]

This page documents observed and tested behavior of entity positions in Dwarf Fortress that is not fully described elsewhere on the wiki. It focuses on advanced interactions between position tokens, including appointment, succession, election, and responsibility handling, across both civilization-level and site-level entities.

The mechanics described here are based on empirical testing in world generation and fortress mode, supplemented where necessary by raw analysis. In several cases, the game’s behavior is determined by evaluation order and interaction between multiple tags, rather than by individual tokens in isolation.

This page is intended for modders and advanced players who are designing or debugging custom entity position structures. It does not restate basic position mechanics, but instead highlights edge cases, non-obvious interactions, and behaviors that may appear inconsistent or undocumented.

Unless stated otherwise, the described behavior applies to current versions of the game and may differ from older releases.

==What is an entity? What is a position?==
An [[entity]] is an organizational structure that can have relationships with other entities, usually known as a [[civilization]] or a "[[site]] government" in the game, but merchant [[guild]]s, religious organizations, necromancer towers, and [[bandit]] groups are also entities. An entity can have positions - in most cases, these are hardcoded and generated by the game, but as for civilizations and sites, the [[raw file]]s can be customised.

A position is a special relationship between a unit and an entity. The unit holding a position has a larger influence over that entity than other citizens. Positions are mostly known as [[nobles]], but in this article. the technical term is used.

=Position levels (Site/Civ) and their interaction=
There are two basic types of positions that are customizable: '''civ(ilization)''' level and '''site level'''. Positions with the tag [SITE] are at site level, positions without the tag [SITE] are at 'civ level'. These two types of nobles can be considered '''loosely related systems'''. There are a few places where they can interact with each other.

Civ-level positions are in charge of the civilization as a whole, managing national [[trade]], laws, and [[war]]s. These are, for example, the vanilla [[monarch]], [[diplomat]] and [[general]]. (Note that the general doesn't do anything in either mode in the current version.)

'''[LAND_HOLDER]''' nobles are also positions at civ-level. These units are members of the national government, but have gained authority over some land or site. Once they do, they move to that place, but their position is still regarded as a civ-level position.

Site-level position holders are members of a site government (subsidiary to the civilization), and manage local affairs in that location. These are, for example, the [[mayor]], the [[sheriff]] and the [[broker]].

==Table of interaction between different position levels==
In this table, the possible interactions between different position levels are summarized.
The header row shows the positions defining the tokens.

The left column shows the position type that is referred to.
Example:
{| {{prettytable}}
|- bgcolor="#ddd"
! referred position-type
! LAND_HOLDER
|-
| civilization
| (baron is) APPOINTED_BY:MONARCH
|}
color coding: 
* Exists in vanilla
* Possible with mods
* Not possible
* possible to some extent.
* not yet fully investigated.
{| {{prettytable}}
|- bgcolor="#ddd"
! referred position-type
! Civilization
! SITE
! LAND_HOLDER
! CONQUERED_SITE

|-
| Civilization
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION '''(1)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION

|-
| SITE
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION '''(2)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY '''(3)''' COMMANDER REPLACED_BY SUCCESSION '''(4)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION

|-
| LAND_HOLDER
| APPOINTED_BY COMMANDER REPLACED_BY '''(6)''' SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION '''(5)'''
| APPOINTED_BY COMMANDER REPLACED_BY '''(7)''' SUCCESSION '''(8)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION

|-
| CONQUERED_SITE
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
|}

Remarks:
# Works only in world-gen, if a unit with that civ-position is present at the site.
# Works only in world-gen, the site-position holding unit will then move to the capital.
# Is completely ignored
# Works only in world-gen.
# Works only in world-gen.
# Won't appear at all
# This is necessary for the landholder chain to work properly, it doesn’t work otherwise.
# This works only outside of the landholder chain, so when landholders are simply regarded as civ-level nobles. might also work in world-gen
#

== Other interactions ==

Unfortunately, interactions with positions of other entities don't seem possible, such as APPOINTED_BY: HIGH_PRIEST. With [VARIABLE_POSITIONS], positions are automatically created with codes like CUSTOM_LAW_MAKER_2, but interaction with these positions don't seem to work, either. For more info on those, see [[Variable positions]]

=General=

==Civ-level nobles living at your site==
Nobles from your civilization can come to live at your fortress. This happens in vanilla with landholders such as [[Baron]], [[Count]] and [[Duke]], with the Monarch, but sometimes also with non-landed LAND_HOLDERS.

When a civ-level noble becomes a [[citizen]] at your location, their position is shown among the site-level positions in your [[nobles screen]]. They appear to function as a site-level noble. They may have [[demand]]s, [[mandate]]s, [[squad]]s and the like. They can appoint nobles at the site-level.

Even if they have certain site related [RESPONSIBILITY]ies, they will not do the tasks that go with them.

==Fortress mode, world-gen and their differences==
Their are a few differences in how positions function between fortress mode (normal play mode) and the world generation (world-gen).

In '''fortress mode''', the player has some control over the appointment of nobles, limited by elections, automatic filled-in positions and succession rules. Pre-fortress mode, which is referred to as '''world-gen''', the game will always attempt to assign nobles whenever possible. It is subjected to the same rules as in fortress-mode, but there are some exceptions. In '''[[World activities]]''', which is the thing that happens in the world while you play fortress mode, it seems as if the same rules are applied as fortress mode.

A difference between player-fortress-mode and world-gen, is causes by visibility (see below). Positions that are not visible by the player and thus not available for assignment, will be available in world-gen and will thus be automatically assigned.

In fortress mode, a position that is both [ELECTED] and [APPOINTED_BY], cannot be appointed by the player and is also not elected, and can thus not be filled. But in world-gen sites however, these positions are automatically filled.

Positions with [AS_NEEDED] are almost never created and filled in world-gen (depending on their [RESPONSIBILITY]ies), but can always be used in player mode.

A position can, in fortress mode, be filled by the same unit. A unit can gain multiple positions in fortress mode, for example because of [[elections]]. This will not happen in world-gen mode: a unit can only have one position. See also remarks on 'embark' and 'Losing a position'.

In world-gen, [SUCCESSION] between civ-levels and [SITE-]levels may happen. This will not happen in fortress mode, or even off-site in [[World activities]].

In fortress mode, premature SUCCESSION may happen. This will not happen in world-gen mode.

==Units holding multiple positions in multiple entities==
A unit can hold multiple positions in its civilisation or in its site-entity, however this does not happen in world-gen. Only at player-managed sites can units be holding multiple positions at once. (It is probably not possible for a unit to hold a position in two different civilisations or two different sites.)

In world-gen, if there are too many positions to be filled, they simply stay empty until more units are available. E.G, a unit at a site might inherit a civ-level position and still remain a member of the local government. When this happens however, they move to the capital. If a unit gains a new position, either inherited or otherwise, it drops the previous one. If a unit assumes a civ-position in fortress mode, it leaves the current position.

If a unit holds the same (site-)position multiple times, it has no additional effect.

If a unit holds multiple different positions of the same entity, it has all those positions' responsibilities and properties, stacked up. Presumably, the demands for those combined positions are determined by the highest.

A unit holding a position with a succession token can be assigned another position with a (different) succession token.

A unit holding a position with a squad-position cannot hold another squad-position. It is dropped from the first, when it gets its second assigned.
A unit holding a position with a succession token cannot be assigned to a squad-position - the unit is simply not available. It works the other way around, though.

=Specific Tags and functions=
==[PRECEDENCE]==
The first defined position with precedence of 1 counts as the ruler of the civ. See also: [[Position_token#PRECEDENCE|PRECEDENCE]].

If the precedence is omitted or has a negative value, the game sets 0 as precedence, which seems to have no effect whatsoever.

When a unit has multiple positions, the name of the position with the highest rank in precedence is shown behind the unit's name.

If you omit precedence entirely, or set it to [PRECEDENCE:NONE], the position name will not be shown after the unit’s name. Your *Urist Mason* will remain simply *Mason*. This can be useful for positions that are unimportant or purely functional. The position will also not appear in the civilisation overview of your site on the world map. The position name is shown in messages, but remains hidden on the nobles screen as well. To make it visible there, use [LAND_NAME].

==[RESPONSIBILITY]ies==
Both civ and [SITE] positions can carry responsibilities. However, not all responsibilities are active for both types: some function only for civ positions, others only for site positions. When a civ noble arrives at a site and takes up residence, they do not perform responsibilities that are intended for SITE nobles. As a result, these responsibilities neither trigger their associated tasks nor unlock related game mechanics. For example, a civ-level manager living in a fortress will not perform management duties there and doesn't unlock the management-screen, even with an assigned office.
This behavior applies to the following [SITE]-level responsibilities:
* [RESPONSIBILITY:ACCOUNTING]
* [RESPONSIBILITY:BUILD_MORALE]
* [RESPONSIBILITY:HEALTH_MANAGEMENT]
* [RESPONSIBILITY:LAW_ENFORCEMENT]
* [RESPONSIBILITY:MANAGE_PRODUCTION]
* [RESPONSIBILITY:MEET_WORKERS]
* [RESPONSIBILITY:TRADE] (functions differently)
Other responsibilities may be affected as well, but have not yet been fully tested.

===World-gen effects of the [RESPONSIBILITY] of available positions ===
It is possible to cause civs and individual sites to change their behavior substantially when they reach a certain size, by controlling nobles.
* If a site can only appoint a position with [MILITARY_GOALS] after reaching a particular size, that site will not send armies on missions until the required size is reached.
* A civ-level [LAW_MAKING] position is required for the civilization to have any kind of cohesion. Without it, sites will be constantly embroiled in territorial disputes and civil wars will be commonplace.
* [MILITARY_STRATEGY] positions go out and tame wild animals. This makes your civ gain those animals as domesticated and also brings them in sieges.
* The [[Personality_facet|Personality]] of the position's holder determines how they lead the civ.

===[DELIVERS_MESSAGES]===
The only [AS_NEEDED]-position that is created in worldgen based on responsibility is that of the site-level responsibility [DELIVERS_MESSAGES].

===Outpost Liaisons and Diplomats===
Civ-positions with the responsibility [ESTABLISH_COLONY_TRADE_AGREEMENTS] ([[Outpost_Liaison|Outpost Liaison]]s) will meet with the site-noble who has responsibility for [RECEIVE_DIPLOMATS] and the highest rank of precedence (i.e. the lowest precedence value). Usually this is the [[Expedition_leader|Expedition leader]].

Once a [LAND_HOLDER] is assigned to the site, civ-positions with the responsibility [MAKE_TOPIC_AGREEMENTS] ([[Diplomat]]s) will meet with '''civ'''-level nobles present at the site who have the [RECEIVE_DIPLOMATS] responsibility. If multiple eligible nobles are available, one is selected at random. If no eligible noble is present, the diplomat leaves angrily. If the landholder is no longer present at the site, diplomats will not arrive at all.

It appears that Outpost Liaisons and Diplomats are chosen for a diplomatic mission based on availability. When multiple candidates exist, the position defined last in the raws is most often selected.

===[TRADE]===
Civ-level nobles with [TRADE] will arrive with the caravan, just as the Outpost Liaison. Their behavior is no longer active in the vanilla game, but the mechanics are still present. See [[40d:Guild_representative|Guild representative]] for more details. This civ-noble will only meet with the SITE noble with [TRADE], usually the [[Broker]].

If two civ-nobles exist with both [TRADE] and [ESTABLISH_COLONY_TRADE_AGREEMENTS], they both arrive at the same time. Even if both tokens are assigned to a single position, if more than one instance of that position exists, two of them will arrive. However in that case, somehow the elevation of the site and appointment of landholder isn't offered.

If the SITE-noble they intend to meet has both [TRADE] and [RECEIVE_DIPLOMATS], only one meeting will proceed and the other is cancelled. However, when two SITE-nobles are available, each with either [TRADE] or [RECEIVE_DIPLOMATS], both meetings will proceed and both civ-nobles will attempt to negotiate a trade agreement. It is not known what happens if these agreements are accepted or refused.

In the trade depot, the last defined position with the [TRADE] responsibility is shown as broker. However when requesting a trader, the first defined position with [TRADE] will actually go there to do the trade.

==[NUMBER]==
A position might be defined with a number. In that case, as many as defined can be available. If the positions become available, in world-gen and when embarking, they are all filled-in completely.

If the ruling position (with PRECEDENCE of 1) has a NUMBER higher than 1, a random unit of the ones holding these positions is shown as ruler in the embark screen.

A [NUMBER] of 0 (zero) has the same effect as 1.

===Automatic spreading of assumed, non-singular positions===
If there are civ positions that have a NUMBER higher then '1' and which are assumed (not APPOINTED_BY or ELECTED) but are '''not DUTY_BOUND''', these are automatically spread among the civilisation, based on population. If there are a number of '''20''' available slots of that position, they spread among a civilization with a combined population of, for example, 1000 of which your fortress has 100 (10%), '''2''' of your fortress' citizens will assume that position.
This may probably also work with elected and appointed positions, but that may be depending on the death of the current holders and this needs more testing. Assumption works within a day, anyway.

===[AS_NEEDED]===
These positions can be created automatically by the game in world-gen. This, however, only works with:
* [LAND_HOLDER]'s
* squad commanders (needs more testing)
* Messengers at sites

For all other types of positions, they're not created in world-gen, even if they are defined with RESPONSIBILITY's. For example, even in war, the game wouldn't create a MILITARY_GOALS position, if they have AS_NEEDED as number.

However, in fortress mode / player mode, these positions can be created by the player at will.

Positions with AS_NEEDED need to be created first, before any symbols are assignable as 'symbols' (objects) for the position holder to carry or wear.

Positions with AS_NEEDED cannot be created and then ELECTED in fortress mode. It only works with APPOINTED_BY.

==[REPLACED_BY], [REQUIRES_POPULATION], [REQUIRES_MARKET]==

The token [REPLACED_BY:position] means that once the replacing position meets its requirements for activation, the 'to-be-replaced' position will disappear. This is defined in [REQUIRES_POPULATION] or [REQUIRES_MARKET]. The tags are closely related to each other and seem to only have a meaningful function if combined. Nobles with [REQUIRES_POPULATION] require the population to have a specific size. Nobles with [REQUIRES_MARKET] are only activated in market sites, such as fortresses or towns. [REQUIRES_POPULATION] and [REQUIRES_MARKET] can be combined, activating that position once both requirements are met.

The [REQUIRES_MARKET] can be used to differentiate positions between hamlets and hillocks, and larger sites. IThe market always is build the year after the site is founded. So a position that is to be replaced, will be gone immediately.

The [REQUIRES_POPULATION]-tag works on the civ-level as well as on site-level, but those systems are in this mechanic strictly separated. Site-level positions cannot be replaced by civ-level positions and visa versa. This makes sense, because they both depend on their own population-count. When using REQUIRES_POPULATION on civ-level, it counts the total population of the civilisation.

See also: [[Advanced_entity_position_mechanics#Evaluation_of_Positions|Evaluation of positions]]

===Effect of replacement (and on [LAND_HOLDER]s)===

Replacement is immediate and complete - the current holding unit loses the position, even before SUCCESSION_BY_POSITION rules are applied. A position with a number of 1 will replace all the slots of a position with a higher number of slots.

Even if the next position is available but not visible, replacement still takes place. If a position is replaced, it is completely gone - it cannot be appointed, succeeded, elected or assumed any longer.
The unit immediately loses its position.

In legends, replacement is mentioned as: "(unit name) ceased to be (position name)" The replacement of an AS_NEEDED position empties the position's slot forever. In fortress mode, it may seem as if you can create new slots and appoint new units in the nobles screen, but this is reversed as soon as you close the window.

The landholder chain uses [REPLACED_BY] differently. It does not clear the position completely, but uses it for succession to the next level's position. [REPLACE_BY] is required to let that system work properly. This also means that the way in which landholders succeed (replace + as_needed) does not work in any other way.

Replacement between LAND_HOLDERS and other site- or civ positions does not work in any way. Only the vanilla replacement sequence between levels of LAND_HOLDERs does work. If the token is omitted for landholders, the landholder chain is broken, so replacement is required for the landholder system to work.

[REQUIRES_POPULATION] also does not work for [LAND_HOLDER], when you set [NUMBER] to 1. The position is not created when the required population is reached.

===What doesn't work===

'''Attention: If a position cannot be appointed, for example because of 'mutual appointment', it still exists according to replacement mechanics and will replace other positions if so defined. If a certain position(a) will be replaced by the baron's assistant, which can only be appointed by the [LAND_HOLDER] baron, than that position(s) still will be replaced from the start of the game, even if no baron or their assistant is ever present.'''

A position that is replaced by a somehow non-fillable position is still replaced. This counts for mutual-appointing positions, replacement by not-yet-assigned landholders, replacement by AS_NEEDED positions, or replacement by not-yet-appointed positions.

Replacement does not work if the replaced position is a [LAND_HOLDER], even with civ-positions. In that case, the LAND_HOLDER's position is not replaced. It does not matter if AS_NEEDED is used, or a fixed number, and it also does not matter what type of position the replacer is. So this only works (correctly) with positions that become available by REQUIRES_POPULATION.

==[CONQUERED_SITE]==

This tag determines which position is used to assign a [[Forced administrator]].

In legends mode, this is visible as an event describing the reconquest of the site: a new group is formed and the forced administrator is installed as its ruler.

All positions defined with this tag are assigned during this process, meaning multiple positions can be appointed at once.

The holder of a position marked with [CONQUERED_SITE] cannot appoint any other [SITE] positions.

Combining [CONQUERED_SITE] with [SITE] causes the position to function both as a forced administrator and as a normal site position available in fortress mode. However, this provides no meaningful additional mechanics and is effectively inferior to using [SITE] alone:
* [APPOINTED_BY] lines are completely ignored, meaning that the roles are automatically assumed.
* [SUCCESSION] is likewise ignored.
* the [CONQUERED_SITE]-position cannot appoint other [CONQUERED_SITE], [SITE] or combined positions.

There have been remarks that reclaiming a fortress is unplayable because of the lack of regular nobles. Unfortunately, it seems that it can't be fixed by modding.

=Availability and visibility=
==Availability of (new) positions==
Warning: Do not mistake "availability" for "visibility"!

Of all the possible positions existing in your site's entity, there may only be some available.
* Positions with [REQUIRES_POPULATION] require the population to have a specific size.
* Positions with [REQUIRES_MARKET] will only appear in "large" sites (which may have different rules for different site types). This tag has no effect in fort mode.
* Positions that are appointed by positions that have an AS_NEEDED number. The appointable positions only become available after an appointer position-slot is created. This works also on civ-level. If a position is appointed by a Land-holder, it only becomes available, when that level of landholder is created.

Only the replaced positions are culled and are no longer available.
A position that requires a certain population will become available, even if it doesn't have [APPOINTED_BY] or [ELECTED]. In that case, see 'automatic assignment' and 'assumption'

In fortress mode, in some cases 'succession' is evaluated immediately after a position becomes available. See: Succession.
==Visibility of positions==
A position might be available, but can still be invisible for the player in the [[nobles screen]]. The positions with their respective holders are visible for players:
* All site-positions that are already filled-in (even if they could not be re-filled-in considering current conditions)
* Site positions that are appointable by a filled-in site position
* Site positions that are appointable by a filled-in civ position, when that civ positions holder becomes a citizen of your fortress.
* Civ positions of units that are also a citizen of your fortress.
If a position becomes available, for example because a certain pop number has been reached, or if it is available from the start(like expedition leader), as long as it cannot be appointed, it still is INVISIBLE for the player.

It might strike someone as odd if a position becomes filled automatically in fortress mode when that position is not even visible. This might be the case if the current holder of a non-appointable position dies or succeeds another position. Regardless of player visibility, these positions will be automatically filled in if the necessary requisitions are met. It might happen with the expedition leader.

A situation with a non-visible but available position, is for example when a position is solely appointed by the expedition leader, when the expedition leader's position is left vacant. It can no longer be appointed by the player and is invisible. Then, it gets automatically assumed, proving that the position still was available.

A position that is both [APPOINTED_BY] and [ELECTED] is visible, but players cannot interact with it.

={{text anchor|Evaluation of Positions}}=
The game does not continuously check whether positions should become available, elected or be [REPLACE_BY]. This is well-known behavior—for example with the [[mayor]], who does not appear automatically when the required population ([REQUIRES_POPULATION]) is reached. Instead, positions must somehow be evaluated. This applies in several other situations as well

'''Cases that require a trigger:'''
* Election of a newly created position
* Election after the current holder dies
* Automatic assumption of a newly created position (this may take up to a day)
* New citizens (such as migrants) considering available positions
* Premature succession of a newly created position

'''Cases that do not wait for a trigger:'''
* Succession following the death of the previous holder
* Automatic assumption of existing positions that have become vacant

'''Triggers that cause the game to reevaluate noble positions:'''
* Succession of a [SITE]-position due to the death of the current holder
* [[Advanced_entity_position_mechanics#Election_Day|Election Day]]
* Automatic assumption of a [SITE]-position that becomes vacant
* (Re)assigning any site position manually
* Settlement elevation on the LAND_HOLDER track (e.g. gaining a [[Baron]] or [[Count]])

=Gaining a position=
There are several ways a unit can gain a position:
* Appointment: A unit is appointed by another unit or by the player.
* Election: A unit is elected by and among the members of the entity
* Assumption: A position is neither elected or appointed: a random unit just simply 'takes' the position
* Succession: a unit is the valid successor of this position(A), either by its current position(B) or because they are that position(A)-holder's heir.

Available positions will automatically be assigned to a random civ member when a new site/civ is created.

==Who can take a position==

* If so defined, a unit needs to be the right caste and/or class - it does not seem to work with creature types.
* The unit needs to be an adult member of the site or its parent civ's government; that is also CAN_LEARN or INTELLIGENT (SLOW_LEARNER cannot take positions) or otherwise is able to think.

==Appointment==

Positions that have an [APPOINTED_BY:position] token require that position to exist, to be available and appointed. Any position that is APPOINTED_BY can be appointed if the appointer's position is filled in.
For site-positions to be appointed, it is required that the appointer is present at that location.

If the appointing unit is temporarily not present, or if that position is not filled, positions depending on it cannot be appointed. This is the case with [[militia captains]], when the [[militia commander]] is on a [[mission]].

A site position cannot appoint a civ position ''or'' LAND_HOLDER in any way whatsoever.

Civ-level positions can appoint other civ-level positions and site-level positions can appoint other site-level positions.

Contrary to what has been said elsewhere, civ-level nobles also can appoint site-level nobles. They need to be at the site to do so. Landholders can appoint both site-level and civ-level nobles. These systems are therefore not as separate as was assumed.

'''Mutual appointment''' cannot take place. If these are the only requisites of the position, then the positions will never appear or get filled. These unfillable positions can be put to good use, for example, to replace a position that is no longer needed without creating a new one.

'''Self appointment''' doesn't normally work. If you have a position that is only appointed by itself, it is never appointed and also cannot be assumed. However, if the position has a number higher than 1, and is filled by multiple units (for example by another position that is now empty), than those units can re-assign or appoint each other from that their shared position.

If an APPOINTED_BY token refers to a non-existing position's code, the effects are as if the appointment token doesn't exist at all.

===Automatic appointment in world-gen and on the civ level===

Outside of fortress mode, the game will always attempt to appoint nobles whenever possible, as long as these positions are '''available''', even if they are invisible to the player.
It shows this message in legends: "(unit name) has been appointed to the position of (position name)"

In world-gen, all positions become available and are automatically appointed, taking population- and appointment-requirements into consideration.

Positions that are REPLACED_BY are culled and won't be filled.

If a citizen of your fortress holds a civ-level position that can appoint another civ-level position, the appointment will happen automatically and without player intervention. It may happen that another citizen of your fortress is appointed by that unit, creating civ-level position holders in your fortress, but it is unknown what is required to force this effect.

===Manual appointments by players in fortress mode===
In fortress mode, the positions that need to be appointed stay empty on embark. and it is the player's job to appoint those. A player can appoint a unit to any available position, according to the hereabove mentioned conditions. The player takes the role of the automatic appointment-system, but has no direct control over elections, successions and replacement. There are some differences in what is possible at world-gen sites and at player-controlled sites.

* A position that is appointed by a unit present as a fortress citizen, can be appointed, re-appointed or left vacant. This means also by civ-level nobles living as a citizen in your fortress; not when they are only visiting, like the diplomat.
* A position whose appointing positions are all either vacant or [REPLACED_BY] can no longer be appointed. If the position is already filled, it cannot be reappointed or vacated; the current holder simply remains in office.
* A position that is APPOINTED_BY a unit present as the land_holder of your site, can be appointed, reassigned or left vacant.
* A position that has SUCCESSION BY_HEIR or BY_POSITION can 'initially' be appointed and also re-appointed or left vacant, but as soon as the [[nobles]] screen closes, ''it can no longer be replaced or left vacant''. From then on, the succession-rules determine who gains that position when the current holder loses the position. This works even if the SUCCESSION:BY_POSITION-position is vacant or replaced.
* A position that is ELECTED nor APPOINTED_BY, can always be (re-)appointed by the player. This is the case with the [[Expedition leader]]. If it is left vacant however, it cannot be appointed, but will be assumed shortly after.
* A position that is both ELECTED and APPOINTED_BY, cannot be appointed by the player. Contrary to world-gen sites, its slot is visible, but it doesn't show the +-sign. This is either by AS_NEEDED or by a fixed number. Even if the position somehow gets filled (re)assignment is never possible
* A player can appoint a number of units to a position, as much as the NUMBER token dictates. If it is AS_NEEDED, the player may create as many slots as they like, also contrary to world-gen sites.
* A civ-position can never be appointed, even if the appointing civ noble is a citizen of your fortress. A civ position also never can be re-assigned or left vacant, would that position be defined as appointed by a site-position.

==Election==
Read more in [[Elections]]. The message that is shown is: "(creature name) has been elected to the position of (position name)"

In worldgen, there is no functional difference between ELECTED and non-appointment, except that elected nobles tend to have high social skills and/or skills related to the position, while non-elected ones are assigned randomly. See: [[Elections]]

A succession goes before an election.

A position that is both ELECTED and APPOINTED_BY never gets elected. Even if the appointees' position somehow gets filled, (re)-elections won't happen. So, it doesn't seem possible to have an elected position become available when a certain other position becomes filled.

An ELECTED civ-(or LAND_HOLDER) position at your site will never be (re)-elected in fortress mode. So real (re-)election only works with SITE-positions.

=== {{text anchor|Election Day}} ===
Election Day takes place on the 17th of Summer. On this day, a full reevaluation is performed, including all currently elected positions, which are subject to re-election. Contrary to the information on [[Elections]], nothing occurs at the start of a season.

Positions that are both [APPOINTED_BY] and [ELECTED] will not be re-elected on Election Day when assigned through [SUCCESSION].

=== Election Eligiblity ===
Any citizen may stand for election. Eligibility cannot be restricted using [ACCEPTED_CREATURE], [REJECTED_CREATURE], [ACCEPTED_CLASS], [REJECTED_CLASS], or [GENDER]. Units currently having a [SUCCESSION]-position even may be elected for a position with a [SQUAD]-token, which is otherwise impossible to assign or even succeed.

=== Skills ===
In elections, skills are taken into account for the tokens of the position which is elected.
{| class="wikitable"
|+ Relevant skills per position token
|-
! Position Token !! Relevant skills
|-
| Responsibility [[Position_token#DELIVER_MESSAGES|[DELIVER_MESSAGES]]] || [[Ambusher]], [[Observer]] and [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#ACCOUNTING|[ACCOUNTING]]] || [[Record_keeper|Record keeper]]
|-
| Responsibility [[Position_token#ESPIONAGE|[ESPIONAGE]]] || [[Schemer]]
|-
| Responsibility [[Position_token#HEALTH_MANAGEMENT|[HEALTH_MANAGEMENT]]] || [[Diagnostician|Diagnostician]]
|-
| Responsibility [[Position_token#MAKE_INTRODUCTIONS|[MAKE_INTRODUCTIONS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#MAKE_PEACE_AGREEMENTS|[MAKE_PEACE_AGREEMENTS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#MAKE_TOPIC_AGREEMENTS|[MAKE_TOPIC_AGREEMENTS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#MANAGE_PRODUCTION|[MANAGE_PRODUCTION]]] || [[Organizer]]
|-
| Responsibility [[Position_token#MEET_WORKERS|[MEET_WORKERS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#RECEIVE_DIPLOMATS|[RECEIVE_DIPLOMATS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#RELIGION|[RELIGION]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#TAME_EXOTICS|[TAME_EXOTICS]]] || [[Animal_trainer|Animal trainer]]
|-
| Responsibility [[Position_token#TRADE|[TRADE]]] || [[Social_skill|Social skills]] and [[Appraiser|Appraiser]]
|-
| [[Position_token#SQUAD|[SQUAD]]]-token || [[Tactician]] and [[Leader]]
|}

==Assumption==

A position that is not APPOINTED_BY nor ELECTED, or is appointed by positions that are not available in your site or civ, will be assumable by a random dwarf. If it has responsibilities that require certain skills, then these are taken into consideration on embark, but not when the position is assumed during the actual game.

Normally, one to three units will take the into consideration to assume a position. Most of the time when there are multiple open positions, only a single unit will assume all of them. However, a position that has REJECTED_CREATURE, REJECTED_CLASS, ALLOWED_CREATURE or ALLOWED_CLASS will be filled with all different units, even if the creature or class mentioned is irrelevant. It seems that this forces the game to loop over all the available units.

The message that is shown in Legends mode is: "(unit name) has assumed the position of (position name)". This may also take place in fortress mode, which then shows this message to the player.

If an assumable position becomes empty, it will be assumed within a day. This is the case when you leave the position of expedition-leader vacant. It also happens with entities.

Assumable positions that become empty will not be assumed if that position has a valid [SUCCESSION] -successor. In that case, the successor inherits the position.

Even positions that are somehow invisible because they cannot be directly APPOINTED_BY players, can be assumed.

When you embark, the assumable positions are automatically assigned to a random unit. If there are multiple of these positions at embark, they all are assigned to the same unit. If there are enough positions available, multiple units may gain a position, but often no more than three different ones.

If a dwarf in fortress mode assumes a position, that already has another position, it will leave the current position empty. When that position also is assumed, then this will continue until all positions have a dwarf appointed to them, with no other position.

A unit that already has a position with a [SUCCESSION] token won't take assumable positions into consideration that have a [SQUAD] token. This can be used by the modder to prevent unwanted loss of current positions.

A position that has an appointer which got replaced because of REPLACED_BY, will not become assumable. Also, positions that have an AS_NEEDED appointer that is not yet filled (or ever), will also not be assumed.

==Succession==

If a position-holder dies or advances to a new position via succession, the position will be granted to another unit based on the [SUCCESSION] tag. If they have an heir or the succeeding position exists, that unit will be assigned. If not, a new one will be appointed according to the usual rules. The message that is shown is: "(creature name) being the rightful heir, has inherited the position of (position name)"

The succeeding creature will also lose its previous position. When succession is defined using BY_POSITION, the unit naturally loses the referenced position. However, it also loses any other positions it may hold. If a unit could simultaneously inherit multiple positions, the last-defined succession overrides the earlier one, clearing the previously acquired position

Succession works both at site-level and at civ-level, both in world-gen and in fortress-mode. Succession by position on the civ-level is also visible and functional in fortress-mode. If both civ-level nobles are a citizen of your fortress, succession is applied visually. Vanilla example: The [[druid]] is succeeded by the [[acolyte]]. This means that as soon as the druid dies, the acolyte takes over.

When a position that is succeeded by position becomes available, immediately it is checked if a position-successor is available and the position is filled with that unit. Even if this is an [ELECTED] position, succession goes first. When elections eventually do happen, succession plays no role.

It is possible to assign multiple levels of [SUCCESSION:BY_POSITION] in different positions, creating a line of positions where the death of one causes all those "below" them to advance.

A position can have multiple tokens with position-succession. It looks to be random which one is used. It is not always:
* The first or last defined token
* The first or last appointed unit
* the oldest or youngest
* one with a higher or lower precedence
* a unit with relevant skills

When a position is defined with a Succession-type, that unit cannot have another position that has a Squad-type. If the succession-position itself has a squad, than it can be assigned another position with a squad, but then it will loose the previous succesion position. See further details by "Squad"

Assumed positions can also be succeeded by position, if the current holder dies.

If the successor is an AS_NEEDED position, the used unit will leave a vacant position-slot on its removal by succession. This empty slot remains a real slot, which will only be cleaned up if you (un)appoint a unit to this position-series. It isn't cleaned up after regular position validation.

A civ-level position of a unit living at your site might be inherited by a unit holding that does not currently live at your site. This, unfortunately, moves that position to a unit off site. This may also happen with the landholder of your site, for example when it is succeeded by another civ-level position. This currently poses an unsolved challenge.

===Eligibility for succession===
Succession is restricted by the tokens [ACCEPTED_CREATURE], [REJECTED_CREATURE], [ACCEPTED_CLASS], [REJECTED_CLASS] and [GENDER].

===Site and civ combined succession===

Succession can work when combining site positions with civ-level positions or land_holders, but only in world-gen mode. In fortress mode, it only works with combining the same level of nobles, with Landholders regarded as civ-level. So, in fortress mode, a site's position cannot succeed a landholder's position and it cannot succeed another type of civ-level position, and vice versa.

This won't work even if the positions:
* are AS_NEEDED or having a fixed number.
* Are LAND_HOLDERs.

===Succession [BY_HEIR]===

When a heir is needed for succession, all children and then other relatives are validated. They cannot take the position if their status does not allow it, for example if they have become a member of another civilisation. See: "Who can take a position". If the unit has no valid heir on that location, the position may go to a unit living on another site. This may cause the title of Landholder of some land to be inherited by a unit living somewhere else. That might be a problem, because then you lose your landholders.

===Premature Succession===

There are cases where [SUCCESSION:BY_POSITION] is applied prematurely: at the moment a position is first created and becomes appointable or assumable, rather than after a current holder leaves. In this situation, the succession mechanism assigns a holder immediately, without any player interaction.

When a position becomes available for the first time, the game checks whether a valid successor-by-position exists. If so, that unit is assigned instantly. It can affect positions that would normally be appointed or elected by the player, causing succession to trigger before the player has any opportunity to intervene.

This behavior occurs only in Fortress mode, but can be applied both on [SITE]-positions as well in civ-positions. That last one however is a bit harder to control. Example: [[Advanced entity position mechanics#The Archduke|The Archduke]]

This premature succession only occurs the first time a position becomes available (i.e. when it is created and becomes appointable or assumable). Even if the position remains vacant and the conditions for succession improve later, premature succession will not trigger again. From that point onward, only normal succession rules apply.

Using premature succession, a position that has [ELECTED], [APPOINTED_BY], or both, can be filled directly.
Notably, positions that combine [ELECTED] and [APPOINTED_BY] are normally impossible to fill through regular mechanics. Premature succession bypasses both election and appointment entirely, making this combination uniquely reachable through this mechanism.

No initial election takes place, and no subsequent elections will ever occur for that position. Succession always takes precedence over election, both in premature succession and in normal succession cases.

This behavior applies only in Fortress mode, not during world generation. World-gen uses simplified and more efficient mechanics, and this interaction does not occur there. Premature succession can affect both site-level and civilization-level positions.

====Multiple succession chains====

Multiple succession chains may be defined and are resolved in the order they appear in the raws.

If a position has both:
* a direct succession chain (A → C), and
* a multi-step chain (A → B → C),

and intermediate positions are vacant, resolution proceeds according to raw order. A common outcome is:
# The direct succession (A → C) is applied first, assigning A to C.
# The remaining chain then advances (A → B).
# If C still has empty slots, the final step (B → C) may occur.

If position B is already filled, behavior depends entirely on raw definition order:
* nothing may happen, or
* B may move to C first, followed by A moving to B.
====Working triggers====
Premature succession is triggered when a succeedable position is created under the following conditions:
* The succeedable position is created because its [REQUIRES_POPULATION] threshold is reached. This applies even if the position is not [APPOINTED_BY]. Premature succession takes priority over automatic assumption (e.g. the mayor declaring themselves within a day).
** The position must either be assumable or appointed by an existing position. When said appointer-position also just has been created, the premature succession of the succeedable position happenes, even when the appointer-position is empty.
* The succeedable position can be [APPOINTED_BY] another position of the same level (site or civ) that has just been created because its [REQUIRES_POPULATION] was reached.
* The succeedable position can be appointed by another [SITE] [AS_NEEDED] position that has just been created and filled.
* The succeedable (site or civ) position is [APPOINTED_BY] the [LAND_HOLDER] position, which has just been created due to site elevation. This typically resolves when the diplomat leaves the map, at which point the landholder position becomes active.
* If all other requirements are met, premature succession can occur immediately after unpausing following embark, for positions with [REQUIRES_POPULATION:7].

====Non-working triggers====
Premature succession does '''not''' occur in the following cases:
* An [AS_NEEDED] succeedable position slot is manually created by the player while its succeeding position is already filled. [AS_NEEDED] positions must always be appointed after creation.
* The succeeding position is filled after the succeedable position becomes available. The moment of creation is the decisive trigger; filling the source position later is too late.
* The succeedable position can be appointed by another site or civ position with a fixed number of slots that has just been appointed. In this case, the succeedable position is just available for appointment itself, nothing more
* Any situation occurring during world generation.
* The succeeding position is [REPLACED_BY] the succeedable position. In this case, replacement removes the unit from the source position first, leaving no holder available for the succession mechanism to use.rst, leaving no holder available for the succession mechanism to use.
* The position is [APPOINTED_BY] a civ-level position, that just became a citizen of your fortress. It must be noted that those civ-level positions were active all that time and the succeedable position could be appointed even before. The monarchs arrival does not trigger premature succession

=Losing a position=

A unit can lose a position when:
* It dies
* It succeeds another position, even if it has nothing to do with the previous position.
* It is assigned to another SQUAD-holding position
* It is convicted of a crime.
* Another unit is ELECTED for the position
* Its position becomes replaced
* Another unit is appointed by the player, or the position is left vacant.
* It has assumed another position, as this always leaves the previous position vacant.

=Embarkment=
Two types of positions are automatically filled by embark.
* Positions without [APPOINTED_BY] or [ELECTED] (assumable). All these positions, even with a NUMBER higher than 1, are all filled with one to three dwarves. Contrary to assumption, this doesn't take into account any limitations. REJECTED_CLASS, ALLOWED_CLASS, REJECTED_CREATURE, ALLOWED_CREATURE and GENDER are applied, but without the normal spread you may expect with assumptions. Also it doesn't look at [SUCCESSION] and [SQUAD] limitations.
* Positions that are elected are filled-in by the normal election rules.

Positions that have a defined appointer are never initially filled at embark.

All positions that don't have [REQUIRES_POPULATION] or with a [REQUIRES_POPULATION] of 7 or lower, will be available at embark.

=Land Holders=

A Landholder is a '''special civ-level noble''' who gets a certain piece of land to hold, when that land is elevated to a certain level, determined by the tag [LAND_HOLDER] and by the landholder triggers in the game's settings. In vanilla, these are the baron, the count and the duke.

A unit gaining the landholder position does not migrate to that specific named land. In world-gen, they stay just where they are, probably at the capital. In fortress mode, you can suggest a citizen for the role. So for the time being that works.

Succession is then a real issue. If you use BY_HEIR, its solved when that landholder has children living at your site. But when its not the case, the title just goes to anyone randomly. Succession BY_POSITION works, but only in the civ-chain, and there's no way to guarantee a civ-holder is at your site at that time. Even with 'automatic spread' positions, it goes to one of them randomly.

==Functioning of the regular landholder chain==

The distinct difference between a landholder and a regular civ-level noble, is that a landholder may gain the position of landholder "of (sitename)" They are then seen as ruler of a particular site.

For a land_holder position to function as such, it has a few requirements:
* NUMBER:AS_NEEDED
* The first landholder-number of 1 is defined.
* No SITE (so civ) tag in that position.
*REPLACED_BY the next level landholder
If a landholder is defined with differentiating properties, it will function like a regular noble. A higher-up landholder that lacks the required tokens or connections will then not be used in elevation.

If a fortress meets the trigger for a new LAND_HOLDER tier when a caravan leaves, then the next time the outpost liaison or equivalent arrives, they will offer to make you an official colony, which will allow you to select all positions for that LAND_HOLDER level. Each time they appear, the outpost liaison will only promote your fortress one tier up the LAND_HOLDER track.

The landholder's LAND_NAME is not required for the functioning of this system. If omitted, messages will be shown with a more generic text.

==Appointment==

This mechanism differs from the regular methods of position management. It ignores all regular appointment- and election rules, so it more or less functions like automatic assignment. A landholder is, in vanilla, appointed by the monarch. Changing this doesn't seem to do anything. If they are appointed by a site-position, a not-yet-existing civ-position, or not appointed at all: the system keeps working as usual.

A landholder can appoint civ-positions and site positions. This works as expected: the positions only are appointed then when that landholder becomes available on civ-level or when he arrives at that site for site-level positions.

If your rank of landholder is the first of its rank in the realm, and is the sole appointer of some civ-position, then immediately as it gains the title, it will appoint the empty civ-slots. This may happen on your site, but the frequency and certainty is hard to determine.

==Succession==

Succession rules are applied to some extent:
* In world-gen it works according to succession rules, and site-positions can be used here. This means that a site position or a civ-position can inherit a landholder position, and vice versa.
* In fortress mode, once a landholder has been appointed, it then can inherit civ-level positions, and vice versa. This means that your baron can become king.
* Succession rules do not apply within the [LAND_HOLDER] chain; a count will not inherit a baron's land. This is because succession does not work well with the AS_NEEDED token.
* Premature succession works in fortress mode with landholders. If a unit gets a landholder's position and that landholder is the appointer of an as yet empty position, which is defined as succeeding from a third one, then the succession is immediately applied. The landholder themselves can even be the successor of a newly created position.
* A landholder's position is, in fortress mode, not successionable by a site-position or vice versa

===Impossibilities for succession by a site-position===
It would be very beneficial if the landholder can be succeeded by a [SITE]-position. So far, the following tests have not lead to positive results:
* making landholder and site-position both non-[DUTY_BOUND]
* make the site-position be [APPOINTED_BY] the landholder and/or the monarch
* give landholder and site-position [REJECTED_CREATURE]
* Let the monarch live at your site when succession could happen.
* Let the site-position be [REPLACED_BY] the landholder.

If the vanilla [SUCCESSION:BY_HEIR]-tag is omitted, a seemingly random unit somewhere in the realm is assigned this position.

==Nomination==

The player is able to nominate a unit to become the LAND_HOLDER, but this only works with units of [LAND_HOLDER] level 1. The player can select all units, only limited by the PRECEDENCE of the current units' positions.

A unit that has a position with a PRECEDENCE lower or equal to that of the landholder's position, cannot be selected. This means that a baron (or count) from another site or the monarch cannot be selected, because their precedence is lower or equal.

The GENDER token does not work here: also units with the wrong gender (sorry) can be selected.

==Levels==
In mods, up to 10 levels of LAND_HOLDER may be defined.

If a landholder is replaced by a wrong landholder number (1 replaced by 3), then the number 3 is still correctly attached to the settlement.

If the current landholder has the highest available landholder number, then the next elevation will not happen - the diplomat will not elevate your fortress to a higher position, even if that position might be REPLACED_BY a lower landholder.

These chains do work:
* 1 -> 2a - > 2b -> 3
* 1 -> 3 -> 2 -> 4

These chains do not work:
* 2 -> 3 (need to start at 1)
* 1 -> 4 -> 2 -> 3 (stops after 4 as the highest)
* 1a -> 2, 1b -> 2 (only 1a and 2 work, 1b is not used)

==Moving landholders==

It may happen that a land-holder no longer lives at the site which they are the landholder of, specifically when the current landholder dies, leaving the title to an heir living somewhere else.

To prevent this from happening, you can make their succession from heir and make sure that their kids live at your site. Or, you can make their position succeeded by another civ position, and make it so that this civ position is somehow available on your site. But if multiple of these positions exist, it cannot be guaranteed that a citizen of your fortress will inherit the title.

In world gen, a landholder lacking the DUTY_BOUND-token will also move to the site they like, according to legends mode.

==Replacement by a generic civ-position==

If a landholder is replaced by an AS_NEEDED non-landholder civ-position, then this will work: the current landholder loses that title upon settlement-elevation and gains that civ-title. However, the civ-title lacks the landholder-property of being attached to the land. It will not show the name of the settlement alongside the position's name. So no "minister of Shovelmounts"

If a landholder is replaced by a general AS_NEEDED civ-position, that itself is also replaced by a generic AS_NEEDED civ-position, then firstly the elevation is executed and also the unit gains that new position. However, he immediately loses it, because an AS_NEEDED position that is replaced by another position can be filled initially, but units wont be able to hold that title.

==Landholder with fixed number==

A landholder's position that has a fixed number will be created and filled directly when the civilisation is born, so this position slot is then not available for the regular landholder-mechanic and will also not be used. That landholder will thus not be attached to a settlement.

It doesn't matter if the landholder's position is connected to the regular landholder's-chain with the REPLACE_BY token.

==Responsibilities==

When given a certain [RESPONSIBILITY], a landholder may function as a regular civ-level noble. If the position has [TRADE] or [OUTPOST_NEGOTIATING] responsibilities, then the landholder functions both as a diplomat and as an actual land holder. A landholder with the [MILITARY_STRATEGY] responsibility will travel around taming creatures in world-gen, according to legends mode.

Besides that, the responsibilities work the same as with any other on-site living position-holder, civ or otherwise.

=Military=
==Squad management==
In the vanilla game, the Squad interface only becomes available after a militia commander has been appointed. Until then, the window displays:{{DFtext|You must appoint somebody first to create a squad.}}

What’s surprising is how this is determined internally. In the entity raw definition, '''only the last two positions that include a [SQUAD] token are checked''' to decide whether the interface is accessible at all. As a result, if your hierarchy defines commanders A through E, appointing '''Commander D or E''' unlocks squad formation, while appointing A–C does nothing.

In other words, squad availability is not tied to ''having a militia commander'', but to ''which specific positions happen to be last in the raw list''—a notably hacky implementation.

These 'last two' are always the last two '''available positions.''' So if they get [REPLACED_BY] or become available because of [REQUIRES_POPULATION], the game adapts to those.

==Squad assignment==

Squads can be assigned, even if the leader position has no holder.

A specific unit can only have one position associated with a squad. If it gains another 'squad holding position', it is unassigned from the first one. This does not work with a 0-squad, so only 1+squads are taken into consideration. This technique can possibly be used to distribute all positions equally among all citizens. It does however not work with election and assumption.

If a civ-level position is associated with a squad and it gets a site-level squad-holding position assigned, it loses the current civ-position.

Squads can get really messed up, if you make the position (or multiple) either elected or not-elected and not-appointed, then this can cause the game to assign multiple squads to the same unit. Automatic assignment and election does not take squads into account, but the nobles screen does. This can cause the positions to be cleared as the game figures out that they have more than one position, and immediately get elected or assumed again.

Positions that cannot have a squad-position:
* A site- or civ-position with a [SUCCESSION] token cannot be appointed a squad-holding-position. The other way around, however, does work. For example, if a site-position with a [SUCCESSION]-token is appointed to a unit that has already a position with [SQUAD]. But when that squad position is assigned to another unit, it cannot be assigned back.
* A position with [SUCCESSION] can also not be assigned as a '''member''' of a squad.
* A squad-holding position with a formed squad cannot be appointed to another squad holding position.

If a position has at least one squad member, it cannot be left vacant. First, the squad has to be disbanded, then the position may be cleared.

==0-squads==
A 0-Squad is defined in a position as [SQUAD:0:member:members]. It does not seem to do anything useful as of now.
* It cannot be used to activate the [[Squad|military interface]]
* It does not restrict the assignment of [SUCCESSION] positions.
* Assigning this position does not clear any previously held squad position.
* The [[Leader]] and [[Tactician]] skill are not marked as relevant skills and are not taken into account in elections.
* It cannot be formed as a squad.

=Further testing=
The following questions may need additional testing. Feel free to add or answer
* Everything regarding COMMANDING and army-structure
** [http://www.bay12forums.com/smf/index.php?topic=175437.msg8331668#msg8331668]
** [http://www.bay12forums.com/smf/index.php?topic=165213.msg8335682#msg8335682]
** [http://www.bay12forums.com/smf/index.php?topic=174584.msg8026854#msg8026854]
* Stuff about the monarch, its arrival and its entourage.

=Oddities (Bugs)=
Almost everything on this page could be called an oddity. Because of their unexpected usability, some may also be referred to as “undocumented features.” Others, however, are simply odd and not particularly useful, yet I hesitate to call them “bugs.”
* If a certain threshold is reached that makes an elected position electable, and the triggering event that initiates this evaluation is an assumption, then the resulting assumption works partially as an election. It referred to in the messages as an election and the [REJECTED_CREATURE]-token is not applied, like it is with assumptions.

=Examples=

===The Founder===
The founder is a single dwarf, appointed at embark. They will be the only one ever to have this position and are not replaceable. When they lose their position some way, the position will not be assumed by another dwarf.
{{gamedata|title=The Founder|
[POSITION:THE_FOUNDER]
[NAME:the founder:founders]
[NUMBER:1]
[SITE]
[ALLOWED_CREATURE:DWARF:ALL] - will only be filled at embark, but not assumable later.
[REJECTED_CREATURE:DWARF:ALL] - will only be filled at embark, but not assumable later.
[SUCCESSION:BY_POSITION:THE_FOUNDER] - not unassignable, also cannot be assigned to a [SQUAD] position.
[PRECEDENCE:200]
Non APPOINTED_BY
Non ELECTED
Optional: Add responsibilities to make the game select a unit with certain skills.
}}
===Marriage bar===
Dwarven matrons are held in great honour. Upon marriage, a female dwarf is no longer expected to perform menial labour. All dwarven males hold this position by default, granting their spouses exemption from menial work.

The position becomes available with the arrival of the first migrants; otherwise, on embark, it would be assumed by females. Its succession rule is non-functional, but this prevents the player from unassigning the position. A squad size of 1 and the succession rules together prevent a unit from assuming the position more than once.

With precedence set to NONE, the position name is hidden, while LAND_NAME remains visible on the nobles screen. All married females receive the suffix “, Mrs.” and are marked as Nobles.

The practical usefulness of this position is debatable, but it serves as a clear demonstration of several mechanics.
{{gamedata|title=Mrs. Urist|

[POSITION:MRS_URIST]
[NUMBER:300]
[SITE]
[ALLOWED_CREATURE:DWARF:MALE]
Not APPOINTED_BY
Not ELECTED
[LAND_NAME:Dwarven male]
[NAME:dwarven male:dwarven male]
[PRECEDENCE:NONE]
[SPOUSE_FEMALE:, Mrs.:spouses]
[MENIAL_WORK_EXEMPTION_SPOUSE]
[REQUIRES_POPULATION:8]
[SUCCESSION:BY_POSITION:MONARCH]
[SQUAD:1:member:members]
}}
===The Archduke===
The archduke is the leader of the civilization, but exists only from landholder 4-level. Until then, its position remains vacant. When a settlement is elevated to tier 4 (grand duke), the grand duke can appoint the ruler of the civilisation, the archduke. Because of 'Premature Succession', they themself inherit that position immediately, but only when in fortress mode. Its heir then becomes grand duke.
{{gamedata|title=The Archduke| no POSITION:MONARCH or other PRECEDENCE:1

[POSITION:THE_ARCHDUKE]
[NAME:archduke:archdukes]
[NAME_MALE:archduke:archdukes]
[NAME_FEMALE:archduchess:archduchesses]
[LAND_NAME:a archduchy]
[NUMBER:1]
[PRECEDENCE:1]
[SUCCESSION:BY_POSITION:GRAND_DUKE]
[APPOINTED_BY:GRAND_DUKE]
(add additional monarch-stuff, like spouse name, demands etc.)

[POSITION:GRAND_DUKE]
[NAME:grand duke:grand dukes]
[NAME_MALE:grand duke:grand dukes]
[NAME_FEMALE:grand duchess:grand duchesses]
[NUMBER:AS_NEEDED]
[LAND_HOLDER:4]
// Optional ...
[PRECEDENCE:19]
[LAND_NAME:a archduchy]
[RESPONSIBILITY:LAW_MAKING]
[RESPONSIBILITY:RECEIVE_DIPLOMATS]
[SUCCESSION:BY_HEIR]
[APPOINTED_BY:THE_ARCHDUKE]
(add additional landholder-stuff)

!!add to [POSITION:DUKE]
[REPLACED_BY:GRAND_DUKE]

}}
{{Category|Modding}}
{{Category|Entities}}
{{Category|Guides}}

Entity token

2026-04-21T20:10:45Z

Joostheger: /* Placement */

{{Quality|Superior}}
{{av}}
{{Modding}}
'''Entity tokens''' define entities, or [[civilization]]s, in entity_*.txt files.

The <code>[OBJECT:ENTITY]</code> [[token]] begins the definition of an entity [[raw file]]. Each new entity definition that follows begins with the <code>[ENTITY:''entity_ID'']</code> token, where ''entity_ID'' is a unique identifier for that entity, and the entity's properties are then specified by the use of further entity tokens; or, tokens can be added to existing entities using <code>[SELECT_ENTITY:''entity_ID'']</code> instead.

All known entity tokens are listed below.

__TOC__
{{clear}}

== Gameplay ==
{| {{prettytable}}
|- bgcolor="#ddd"
! Token
! Arguments
! Description

|-
| {{text anchor|ALL_MAIN_POPS_CONTROLLABLE}}
|
| Allows adventure mode for entities with sites.

|-
| {{text anchor|SITE_CONTROLLABLE}}
|
| Allows fortress mode. If multiple entities have the SITE_CONTROLLABLE token, then at embark the specific civs can be chosen on the civ list screen. At least one civilization must have this token.

|-
| {{text anchor|CREATURE}}
| creature
|The type of creature that will inhabit the civilization. If multiple creature types are specified, each civilization will randomly choose one of the creatures. In entities with multiple possible creatures, you can manipulate the chance of one creature being chosen by adding multiple identical creature tags. For instance adding [CREATURE:DWARF][CREATURE:DWARF][CREATURE:DWARF][CREATURE:ELF] to the same entity will make the civs created about 75% dwarven, 25% elven. It should be noted that civilizations are in general weighted by this token: for example, if you have one entity with three [CREATURE:DWARF] tokens and another separate entity with a single [CREATURE:ELF] token, then you can expect to see three times as many of the former placed as the latter (assuming enough unclaimed [START_BIOME:X] space remains). Note that spawn rates are also limited by unclaimed biome space - if an entity can only spawn in a rarer set of biomes (only LAKE_TROPICAL_SALTWATER for example) then their spawn rate will end up being limited by the remaining unclaimed space in that biome type rather than the number of [CREATURE:X] tokens present in the entity raw.
|-
| {{text anchor|SOURCE_HFID}}
| integer
| Found on generated [[angel]] entities. Appears to draw from creatures with this HFID, which associates the entity with a historical figure of the same ID corresponding to a [[deity]].

|}

== Placement ==

Entity spawning during world gen is influenced by several factors:
* The "[[Advanced world generation#Number of Civilizations|Number of Civilizations]]" world gen setting places a hard limit on the total number of entities spawned.
* The "[[Advanced world generation#Playable Civilization Required|Playable Civilization Required]]" world gen setting forces at least one of each [[Entity token#SITE_CONTROLLABLE|SITE_CONTROLLABLE]] entity to spawn (presumably still limited by "Number of Civilizations").
* The number of <nowiki>[</nowiki>[[Entity token#CREATURE|CREATURE]]:X] tokens present in an entity modifies its chance of spawning. An entity containing more <nowiki>[</nowiki>[[Entity token#CREATURE|CREATURE]]:X] tokens will spawn more often (assuming other requirements are met) and may even block entities with fewer <nowiki>[</nowiki>[[Entity token#CREATURE|CREATURE]]:X] tokens from spawning altogether. You can use [SELECT_ENTITY:VANILLA_ENTITY_X] followed by any number of duplicate <nowiki>[</nowiki>[[Entity token#CREATURE|CREATURE]]:VANILLA_CREATURE_X] tokens to attempt to balance the spawn rates of the existing vanilla entities with any custom multi-creature entities you may add.
* The number of unclaimed [[Entity token#START_BIOME|START_BIOME]] or [[Entity token#EXCLUSIVE_START_BIOME|EXCLUSIVE_START_BIOME]] tiles remaining in the world limits the spawn rate for an entity and allows entities to block each other's spawns. If there is no "starting" [[Biome token|biome]] space left for an entity then it will not spawn and the game will try to spawn a different entity instead. This means that, on average, an entity that can start in ALL_MAIN [[Biome token|biomes]] will spawn more frequently than one that can start only in LAKE_TROPICAL_SALTWATER [[Biome token|biomes]]. This also means that entities whose starting [[Biome token|biomes]] do not overlap will not block each other's spawns.

{| {{prettytable}}
|- bgcolor="#ddd"
! Token
! Arguments
! Description

|-
| {{text anchor|BIOME_SUPPORT}}
|
* [[Biome token|biome]]
* frequency
| Controls the expansion of the civilization's territory. The higher the number is relative to other BIOME_SUPPORT tokens in the entity, the faster it can spread through the biome. These numbers are evaluated relative to each other, i.e. if one biome is 1 and the other is 2, the spread will be the same as if one was 100 and the other was 200. Civs can spread out over biomes they cannot actually build in; for example, humans spread quickly over oceans but cannot actually build in them.
[BIOME_SUPPORT:ANY_GRASSLAND:4]

The first entry of biome support should be the Start biome, as mentioned in [START_BIOME] or [EXCLUSIVE_START_BIOME], otherwise no other settlements after the first one are founded.

|-
| {{text anchor|SETTLEMENT_BIOME}}
| [[Biome token|biome]]
| If the civ's territory crosses over this biome, it can build settlements here.
[SETTLEMENT_BIOME:ANY_GRASSLAND]

|-
| {{text anchor|START_BIOME}}
| [[Biome token|biome]]
| Combination of EXCLUSIVE_START_BIOME and SETTLEMENT_BIOME; allows the civ to start in and create settlements in the biome. Note that the civ's spawn rate may be limited if all of its START or EXCLUSIVE_START biome(s) are rare in the world or have already been fully occupied by other civ spawns.
[START_BIOME:ANY_FOREST]

|-
| {{text anchor|EXCLUSIVE_START_BIOME}}
| [[Biome token|biome]]
| The birth of the civilization can occur in this biome, but cannot (necessarily) build in it. If the civ does not have SETTLEMENT_BIOME or START_BIOME for the biome in question, it will only construct a single settlement there. Note that the civ's spawn rate may be limited if all of its START or EXCLUSIVE_START biome(s) are rare in the world or have already been fully occupied by other civ spawns.
[EXCLUSIVE_START_BIOME:MOUNTAIN]

|-
| {{text anchor|DEFAULT_SITE_TYPE}}
| site type
| Valid site types are DARK_FORTRESS (π), CAVE (•), CAVE_DETAILED (Ω), TREE_CITY (î), and CITY (#). Also recognizes PLAYER_FORTRESS (creates a civ of hillocks only, that however do not contain any structures, when visited in adventure mode), and MONUMENT (creates a civ without visible sites (except tombs and castles), but may cause worldgen crashes). FORTRESS is no longer a valid entry, castles are currently controlled by BUILDS_OUTDOOR_FORTIFICATIONS. Defaults to CITY. Selecting CAVE causes the classic kobold behavior of not showing up on the "neighbors" section of the site selection screen.
Selecting DARK_FORTRESS also allows generation of [[underworld spire|certain other structures]]. It also gives the civ a [[demon|special overlord]]. DARK_FORTRESS may cause crashes during world gen at "Placing civilizations... (0)" if it combined with entity tokens that the vanilla ENTITY:EVIL does not use (likely the POSITION related tokens see [https://www.bay12forums.com/smf/index.php?topic=175747.0 this forum post]).
CAVE_DETAILED civilizations will create fortresses in mountainous regions and hillocks in non-mountainous regions. [DEFAULT_SITE_TYPE:CAVE_DETAILED]

|-
| {{text anchor|LIKES_SITE}}
| site type
| Most residents will try to move to this site type, unless already at one.
[LIKES_SITE:CAVE_DETAILED]

|-
| {{text anchor|TOLERATES_SITE}}
| site type
| Some residents will try to move to this site type, unless already at one.
[TOLERATES_SITE:CITY]

|-
| {{text anchor|WORLD_CONSTRUCTION}}
| construction
| Controls which constructions the civ will build on the world map. Valid constructions are ROAD, TUNNEL, BRIDGE, and WALL.
[WORLD_CONSTRUCTION:BRIDGE]
[WORLD_CONSTRUCTION:ROAD]
[WORLD_CONSTRUCTION:TUNNEL]
[WORLD_CONSTRUCTION:WALL]

|}

== Population ==

{| {{prettytable}}
|- bgcolor="#ddd"
! Token
! Arguments
! Description

|-
| {{text anchor|MAX_POP_NUMBER}}
| number
| Max '''historical''' population '''per entity'''. Multiply this by max starting civ to get the total maximum historical population of the species. Defaults to 500, but all vanilla entities use 10,000, except skulking uses 2,000. Does not limit the '''total''' population, but it will prevent new settlements upon reaching the number.
[MAX_POP_NUMBER:10000]

|-
| {{text anchor|MAX_SITE_POP_NUMBER}}
| number
| Max historical population per individual site. Defaults to 50, but all the vanilla entities use 120.
[MAX_SITE_POP_NUMBER:120]

|-
| {{text anchor|MAX_STARTING_CIV_NUMBER}}
| number
| Max number of civilizations of this entity type to spawn at world generation, which picks entities in some sequential order from the raws, looping through the list as needed. This is a hard limit, if set to 1, only 1 civilization of this type will be placed. If all entities have reached their limit, world generation will not try to place any more, even if its own [[Advanced_world_generation#Number_of_Civilizations|total limit]] has not been reached, and will continue on. Defaults to 3, but all vanilla entities use 100 (essentially unlimited).
[MAX_STARTING_CIV_NUMBER:100]

|}

== Flavor ==
{| {{prettytable}}
|- bgcolor="#ddd"
! Token
! Arguments
! Description

|-
| {{text anchor|PERMITTED_BUILDING}}
| building name
| The named, custom building can be built by a civilization in Fortress Mode.
[PERMITTED_BUILDING:SOAP_MAKER]

|-
| {{text anchor|PERMITTED_JOB}}
| [[Unit type token|profession]]
| Allows this job type to be selected. This applies to worldgen creatures, in the embark screen, and in play. Certain professions also influence the availability of materials for trade.
[PERMITTED_JOB:MINER]

|-
| {{text anchor|PERMITTED_REACTION}}
| reaction name
| Allows this reaction to be used by a civilization. It is used primarily in Fortress Mode, but also allows certain resources, such as [[steel]], to be available to a race. When creating custom reactions, this token '''must''' be present or the player will not be able to use the reaction in Fortress Mode.
[PERMITTED_REACTION:TAN_A_HIDE]

|-
| {{text anchor|CURRENCY_BY_YEAR}}
|
| Causes the civ's currency to be numbered with the year it was minted.

|-
| {{text anchor|CURRENCY}}
|
* inorganic material
* value
| What kind of metals the civ uses for coin minting, as well as the value of the [[coin]]. Only effective in Adventurer mode due to lack of [[dwarven economy]].

[CURRENCY:SILVER:5]

|-
| {{text anchor|ART_FACET_MODIFIER}}
|
* type
* number
| OWN_RACE, FANCIFUL, EVIL, GOOD
Number goes from 0 to 25600 where 256 is the default.
[ART_FACET_MODIFIER:OWN_RACE:512]

|-
| {{text anchor|ART_IMAGE_ELEMENT_MODIFIER}}
|
* item
* number
| CREATURE, PLANT, TREE, SHAPE, ITEM 0-25600

Determines the chance of each image occurring in that entity's artwork, such as engravings and on artifacts, for default (non-historical) artwork.

[ART_IMAGE_ELEMENT_MODIFIER:TREE:512]

|-
| {{text anchor|ITEM_IMPROVEMENT_MODIFIER}}
|
* item
* number
| ART_IMAGE, COVERED or GLAZED, RINGS_HANGING, BANDS, SPIKES, ITEMSPECIFIC, THREAD, CLOTH, SEWN_IMAGE. Also available, but effect unknown: PAGES, ILLUSTRATION, INSTRUMENT_PIECE, WRITING, IMAGE_SET, COLORATION. 0-25600

Determines the chance of the entity using that particular artwork method, such as "encircled with bands" or "menaces with spikes".

[ITEM_IMPROVEMENT_MODIFIER:SPIKES:0]

This also seems to change the amount that the entity will pay for items that are improved in these ways in their tokens.

|-
| {{text anchor|TRANSLATION}}
| language
| What language raw the entity uses.
* If an entity lacks this tag, translations are drawn randomly from all translation files. Multiple translation tags will only result in the last one being used. Migrants will sometimes arrive with no name.
* If GEN_DIVINE is entered, the entity will use a generated divine language, that is, the same language that is used for the names of [[angel]]s.
* If the entity's main creature has {{token|UTTERANCES|c}}, then this token will be ignored (except when using the naming menu) in favor of procedural [[kobold]]-style [[Kobold language|pseudolanguage]].
[TRANSLATION:DWARF]

|-
| {{text anchor|SELECT_SYMBOL}}
|
* category
* [[language#language_SYM.txt|symbol]]
| ALL, REMAINING, BATTLE, BRIDGE, CIV, CRAFT_GUILD, FESTIVAL (doesn't work, see below), HOSPITAL, LIBRARY, MERCHANT_COMPANY, MILITARY_UNIT, OTHER, RELIGION, ROAD, SIEGE, SITE, TEMPLE, TUNNEL, VESSEL, WALL, WAR
The entity will always use a word from the selected symbol(s) to generate names from that category.
* OTHER applies the symbol selection to personal names and site names. REMAINING will apply the symbol selection to all categories that have not already been declared above it.
* Specific to SELECT_SYMBOL, symbols selected this way will be used as "The X" in "The X of Y" names, and nouns from selected symbols can be used as first [[name]]s.
* FESTIVAL does not work. The game uses symbol NAME_FESTIVAL hardcoded. You may consider changing that symbol (with SELECT_SYMBOL), but then it's applied for all entities.

[SELECT_SYMBOL:ALL:PEACE]

|-
| {{text anchor|SUBSELECT_SYMBOL}}
|
* category
* [[language#language_SYM.txt|symbol]]
| As SELECT_SYMBOL, a word from the subselected symbol(s) will be used in names of that category, in addition to the word from SELECT_SYMBOL (if specified). Used in vanilla to put violent names in sieges and battles.
* Words chosen with SUBSELECT_SYMBOL will appear as either adjectives or "of Y" in "The X of Y" names.
* CULL_SYMBOL does not affect subselected symbols.

[SELECT_SYMBOL:SIEGE:NAME_SIEGE]

[SUBSELECT_SYMBOL:SIEGE:VIOLENT]

|-
| {{text anchor|CULL_SYMBOL}}
|
* category
* [[Language#language_SYM.txt|symbol]]
| Causes the entity to not use the words in these SYM sets.
[CULL_SYMBOL:ALL:UGLY]

|-
| {{text anchor|FRIENDLY_COLOR}}
| see [[color]]
|
The color of this entity's civilization settlements in the world gen and embark screens, also used when announcing arrival of their caravan. Defaults to 7:0:1.

[FRIENDLY_COLOR:1:0:1]

|}

== Religion ==
{| {{prettytable}}
|- bgcolor="#ddd"
! Token
! Arguments
! Description

|-
| {{text anchor|RELIGION}}
| type
|
* REGIONAL_FORCE: The creatures will worship a single force associated with the terrain of their initial biome.
* PANTHEON: The creatures will worship a group of gods, each aligned with their spheres and other appropriate ones as well.

Can be specified multiple times, and will pick randomly from the assigned types. Additional instances of each type will weight the random choice, but unlike {{token|CREATURE|e}}, will not make the entity more likely to spawn.

[RELIGION:PANTHEON]

|-
| {{text anchor|RELIGION_SPHERE}}
| [[Sphere#Available_spheres|sphere]]
| Can be any available [[sphere]] - multiple entries are possible. Choosing a religious sphere will automatically make its opposing sphere not possible for the species to have: adding [[Sphere#WATER|WATER]], for example, means civs of this entity will never get [[Sphere#FIRE|FIRE]] as a religious sphere. Note that the [[Sphere#DEATH|DEATH]] sphere favours the appearance of necromancers (and therefore, towers) "in" the entity.

[RELIGION_SPHERE:FORTRESSES]

|-
| {{text anchor|SPHERE_ALIGNMENT}}
|
* [[Sphere#Available_spheres|sphere]]
* number
|
This token forces an entity to favor or disfavor particular religious spheres. Default is 256, minimum is 0, maximum is 25600.
* Presently, this doesn't cause them to acquire those spheres more often when generating a pantheon.
* [[Sphere#PLANTS|PLANTS]] and [[Sphere#ANIMALS|ANIMALS]] affect the prevalence of depicting {{token|VEGETATION}} and {{token|NATURAL}} creatures, respectively, in a similar fashion to {{token|ART_FACET_MODIFIER|e}}.
* [[Sphere#WAR|WAR]] modifies the effective [[item value]] of [[weapon]]s and [[armor]] to [[trader]]s of this entity. The multiplier is SPHERE_ALIGNMENT/256, though this only applies to equipment the entity's main creature can properly wield.

[SPHERE_ALIGNMENT:TREES:512]

|}

== Leadership ==
{| {{prettytable}}
|- bgcolor="#ddd"
! Token
! Arguments
! Description

|-
| {{text anchor|POSITION}}
| string
| Defines a leader/noble position for a civilization. These replace previous tags such as [MAYOR] and [CAN_HAVE_SITE_LEADER] and so on. To define a position further, see [[Position token]].

|-
| {{text anchor|SITE_VARIABLE_POSITIONS}}
| Position responsibility or ALL
| Allows a site responsibility to be taken up by a dynamically generated position (lords, hearthpersons, etc.). Any defined positions holding a given responsibility will take precedence over generated positions for that responsibility. Also appears to cause site disputes.{{Verify}} See also: [[variable positions]]

|-
| {{text anchor|VARIABLE_POSITIONS}}
| Position responsibility or ALL
| Allows a responsibility to be taken up by a dynamically generated position (such as Law-maker). Any defined positions holding a given responsibility will take precedence over generated positions for that responsibility. See also: [[variable positions]]

|}

== Behavior ==
{| {{prettytable}}
|- bgcolor="#ddd"
! Token
! Arguments
! Description

|-
| {{text anchor|ETHIC}}
|
*behavior
*reaction
| Sets the civ's view of [[ethic]]s (certain behaviors), from capital punishment to completely acceptable. This also causes the civ to look upon opposing ethics with disfavor if their reaction to it is opposing, and when at extremes (one ACCEPTABLE, another civ UNTHINKABLE; for example) they will often go to war over it.
[ETHIC:EAT_SAPIENT_KILL:ACCEPTABLE]

|-
| {{text anchor|VALUE}}
|
*value
*number
| Sets the civ's [[Personality value|cultural values]]. Numbers range from -50 (complete anathema) to 0 (neutral) to 50 (highly valued).
[VALUE:CRAFTSMANSHIP:50]

Certain values must be set to 15 or more for civs to create structures and form entities during history gen:
* 15+ KNOWLEDGE for libraries
* 15+ COOPERATION ''and'' 15+ CRAFTSMANSHIP for craft guilds
** Guilds also need guild-valid professions (see [[#PERMITTED_JOB|PERMITTED_JOB]])

If the positions of an entity are variable (and include the CUSTOM_OFFICIAL_1), then CUNNING > 10 is needed for the CUSTOM_OFFICIAL_1 to have the espionage responsibility.

Also note that the values of a civ can deviate from the fixed values set in the raws, if the civ is able to make libraries. See [[Library#Adventure mode|here]] for more details.

|-
| {{text anchor|VARIABLE_VALUE}}
|
*value or ALL
*min
*max
| Makes values randomized rather than specified.
This tag overrides the VALUE tag. Using [VARIABLE_VALUE:ALL:x:y] and then overwriting single values with further [VARIABLE_VALUE:value:x:y] tags works.

|-
| {{text anchor|WILL_ACCEPT_TRIBUTE}}
|
| Makes the civ's traders accept offered goods.

|-
| {{text anchor|WANDERER}}, {{text anchor|BEAST_HUNTER}}, {{text anchor|SCOUT}}, {{text anchor|MERCENARY}}
|
| The civ will send out these sorts of adventurers in worldgen, which seems to increase Tracker skill. These types of adventurers will sometimes be seen leading a battle (instead of war leaders or generals) in remote locations during world-gen, in charge of the defenders.

Mercenaries and monster hunters from the civ may visit player's fortress and petition for residency there to enlist in the military or hunt monsters in caverns, respectively.

|-
| {{text anchor|ABUSE_BODIES}}
|
| The civilization will mutilate bodies when they are the victors in history-gen warfare, such as hanging bodies from trees, putting them on spikes, and so forth. Adventurers killed in Adventurer mode will sometimes be impaled on spikes wherever they died, with or without this token, and regardless of whether they actually antagonized the townspeople.

|-
| {{text anchor|ACTIVE_SEASON}}
| season
| The season when the civ is most active: when they will trade, interact with you via diplomats, and/or invade you. Civs can have multiple season entries. Note: If multiple caravans arrive at the same time, you are able to select which civ to trade with at the depot menu. ACTIVE_SEASON tags may be changed for a currently active fort.
[ACTIVE_SEASON:AUTUMN]

|-
| {{text anchor|AMBUSHER}}
|
| When invading, sneaks around and shoots at straggling members of your society. They will spawn on the edge of the map and will only be visible when one of their party are spotted; this can be quite dangerous to undefended trade depots. If the civilization also has the SIEGER token, they will eventually ramp it up to less subtle means of warfare.

|-
| {{text anchor|AT_PEACE_WITH_WILDLIFE}}
|
| Will not attack wildlife, and will not be attacked by them, even if you have them in your party. This can be somewhat disconcerting when attacked by bears in the forest, and your elven ally sits back and does nothing. Additionally, this token determines if the entity can settle in savage biomes.

|-
| {{text anchor|BABYSNATCHER}}
|
| Sends thieves to steal babies. Without this tag (or AMBUSHER, or ITEM_THIEF), enemy civs will only siege (if capable), and will siege as early as they would otherwise babysnatch. This can happen as early as the first year of the fort! In addition, babysnatcher civs will snatch children during worldgen, allowing them to become part of the civ if they do not escape. Also causes this civ to be hostile to any entity without this token.

Note: If the playable civ in fortress mode has this tag (e.g. you add BABYSNATCHER to the dwarf entity) then the roles will be reversed and elves and humans will siege and ambush and goblins will be friendly to you. However, animals traded away to one's own caravan will count as snatched, reported upon the animal leaving the map, and the animal will not count as having been exported.

|-
| {{text anchor|BUILDS_OUTDOOR_FORTIFICATIONS}}
|
| Makes the civilization build castles from [[mead hall]]s. Only functions when the type of site built is a hamlet/town. This, combined with the correct type of [[position token|position]] associated with a site, is why adventurers can only lay claim to human sites. {{bug|8001}}

|-
| {{text anchor|BUILDS_OUTDOOR_TOMBS}}
|
| Makes the civilization build tombs.

|-
| {{text anchor|BANDITRY}}
| percentage
| Sets a percentage of the entity population to be used as bandits.

|-
| {{text anchor|DIPLOMAT_BODYGUARDS}}
|
| Visiting diplomats are accompanied by a pair of soldiers.
|-
| {{text anchor|GENERATED}}
|
| Found on generated divine "HF Guardian Entities". Cannot be used in user-defined raws.

|-
| {{text anchor|INVADERS_IGNORE_NEUTRALS}}
|
| Causes invaders to ignore visiting caravans and other neutral creatures.{{verify}}

|-
| {{text anchor|ITEM_THIEF}}
|
| Sends thieves to steal items. This will also occur in history generation, and thieves will have the "thief" profession. Items stolen in history gen will be scattered around that creature's home. Also causes that civ to be hostile to any entity without this token. Without this tag (or AMBUSHER, or BABYSNATCHER), enemy civs will only siege (if capable), and will siege as early as they would otherwise steal.

Note: If the playable civ in Fortress Mode has this tag (e.g. you add ITEM_THIEF to the Dwarf entity) then the roles will be reversed and elves and humans will siege and ambush and kobolds will be friendly to you. However, ALL items traded away to one's own caravan will count as stolen, reported when the items leave the map, and the stolen items will not count as exported.

|-
| {{text anchor|LOCAL_BANDITRY}}
|
| Causes the entity to send out patrols that can ambush adventurers. Said patrols will be hostile to any adventurers they encounter, regardless of race or nationality.

|-
| {{text anchor|MERCHANT_BODYGUARDS}}
|
| Caravan merchants are accompanied by soldiers.

|-
| {{text anchor|MERCHANT_NOBILITY}}
|
| Merchants will engage in cross-civ trading and form companies.

In previous versions, this resulted in the civ having a Guild Representative / Merchant Baron / Merchant Prince, but now this is controlled solely by positions.

|-
| {{text anchor|PROGRESS_TRIGGER_POPULATION}}
| level
| 0 to 5, civ will come to site once population at site has reached that level. If multiple progress triggers exist for a civ, it will come when any one of them is fulfilled instead of waiting for all of them to be reached. A value of 0 disables the trigger. 1 corresponds to 20 dwarves, 2 to 50 dwarves, 3 to 80, 4 to 110, and 5 to 140. Progress triggers may be changed, added, or deleted for a currently active fort. Note: hostile civs require that this be fulfilled as well as at least one other non-siege trigger before visiting for non-siege activities.

|-
| {{text anchor|PROGRESS_TRIGGER_PRODUCTION}}
| level
| 0 to 5, civ will come to site once created wealth has reached that level. If multiple progress triggers exist for a civ, it will come when any one of them is fulfilled instead of waiting for all of them to be reached. A value of 0 disables the trigger. 1 corresponds to 5000☼ created wealth, 2 to 25000☼, 3 to 100000☼, 4 to 200000☼, and 5 to 300000☼. Progress triggers may be changed, added, or deleted for a currently active fort.

|-
| {{text anchor|PROGRESS_TRIGGER_TRADE}}
| level
| 0 to 5, civ will come to site once exported goods has reached that level. If multiple progress triggers exist for a civ, it will come when any one of them is fulfilled instead of waiting for all of them to be reached. A value of 0 disables the trigger. 1 corresponds to 500☼ exported wealth, 2 to 2500☼, 3 to 10000☼, 4 to 20000☼, and 5 to 30000☼. Progress triggers may be changed, added, or deleted for a currently active fort.

|-
| {{text anchor|PROGRESS_TRIGGER_POP_SIEGE}}
| level
| 0 to 5, civ will begin to send sieges against the player civ when this level is reached if it is hostile.

If multiple progress triggers exist for a civ, it will come when any one of them is fulfilled instead of waiting for all of them to be reached. A value of 0 disables the trigger.

|-
| {{text anchor|PROGRESS_TRIGGER_PROD_SIEGE}}
| level
| 0 to 5, civ will begin to send sieges against the player civ when this level is reached if it is hostile.

|-
| {{text anchor|PROGRESS_TRIGGER_TRADE_SIEGE}}
| level
| 0 to 5, civ will begin to send sieges against the player civ when this level is reached if it is hostile.

|-
| {{text anchor|SIEGER}}
|
| Will start campfires and wait around at the edge of your map for a month or two before rushing in to attack. This will occur when the progress triggers for sieging are reached. If the civ lacks smaller methods of conflict (AMBUSHER, BABYSNATCHER, ITEM_THIEF), they will instead send smaller-scale sieges when their triggers for "first contact" are reached.

|-
| {{text anchor|SIEGE_SKILLED_MINERS}}{{v|53.01}}
|
| Improves the skill of [[miner]] invaders by a factor of 5. Used for [[dwarves]] in vanilla.

|-
| {{text anchor|SITE_GUARDIAN}}
|
| Guards certain special sites, such as a [[vault]] belonging to a [[demon]] allied with a [[deity]]. Used in generated divine entities.

|-
| {{text anchor|SKULKING}}
|
| This makes the severity of attacks depend on the extent of item/baby thievery rather than the passage of time. Designed to go with ITEM_THIEF, may or may not work with BABYSNATCHER. Prevents the civ from engaging in diplomacy or ending up at war.

|-
| {{text anchor|TREE_CAP_DIPLOMACY}}
|
| Visiting diplomats impose tree cutting quotas; without this, they will simply compliment your fortress and leave. Also causes the diplomat to make unannounced first contact at the very beginning of the first spring after your fortress becomes a land holder.

|-
| {{text anchor|LAYER_LINKED}}
|
| Defines if a civilization is a hidden subterranean entity, such as [[bat man]] civilizations. May spawn in any of the three caverns; cavern dweller raids due to [[agitation]] will pull from these. If you embark as this civ, you have access to pets and trees from all three layers, not only the first.

|-
| {{text anchor|GENERATE_KEYBOARD_INSTRUMENTS}}, {{text anchor|GENERATE_PERCUSSION_INSTRUMENTS}}, {{text anchor|GENERATE_STRINGED_INSTRUMENTS}}, {{text anchor|GENERATE_WIND_INSTRUMENTS}}, {{text anchor|GENERATE_DANCE_FORMS}}, {{text anchor|GENERATE_MUSICAL_FORMS}}, {{text anchor|GENERATE_POETIC_FORMS}}
|
| Makes civilizations generate the given instruments/forms.

|-
| {{text anchor|SCHOLAR}}
| scholar type
| ALL, ASTRONOMER, CHEMIST, DOCTOR, ENGINEER, GEOGRAPHER, HISTORIAN, MATHEMATICIAN, NATURALIST, PHILOSOPHER

|-
| {{text anchor|SET_SCHOLARS_ON_VALUES_AND_JOBS}}
|
| Generates scholars based on the values generated with the VARIABLE_VALUE tag.

|-
| {{text anchor|NO_ARTIFACT_CLAIMS}}
|
| Used for kobolds.

|-
| {{text anchor|MINING_UNDERWORLD_DISASTERS}}
|
| The civilization can breach the [[Underworld]] during world generation, spawning a civilization of {{token|EVIL}} creatures lead by a unique [[demon]].

|-
| {{text anchor|MYTHICAL}}{{version|51.01-beta26}}
|
| Builds [[mysterious dungeon]]s.

|}

== Available resources ==
{| {{prettytable}}
|- bgcolor="#ddd"
! Token
! Arguments
! Description

|-
| {{text anchor|AMMO}}
| item token
| Used after a ranged weapon type.
[AMMO:ITEM_AMMO_BOLTS]

|-
| {{text anchor|ARMOR}}
|
* item token
* rarity
| Rarity is optional, and valid values are FORCED, COMMON, UNCOMMON, and RARE (anything else is treated as COMMON). FORCED items will be available 100% of the time, COMMON items 50%, UNCOMMON items 10%, and RARE items 1%. If certain armor types are lacking after performing one pass of randomised checks, the game will repeat random checks until an option is successfully chosen.
[ARMOR:ITEM_ARMOR_PLATEMAIL:COMMON]

|-
| {{text anchor|DIGGER}}
| item token
| Causes the selected weapon to fall under the "digging tools" section of the embark screen. Also forces the weapon to be made out of metal, which can cause issues if a modded entity has access to picks without access to metal - for those cases, listing the pick under the [WEAPON] token works just as well. Note that this tag is neither necessary nor sufficient to allow use of that item as a mining tool – for that, the item itself needs to be a weapon with {{token|SKILL|wp|MINING}}.
[DIGGER:ITEM_WEAPON_PICK]

|-
| {{text anchor|GLOVES}}
|
* item token
* rarity
| Rarity is optional, and valid values are FORCED, COMMON, UNCOMMON, and RARE (anything else is treated as COMMON). Uses the same rarity values and methods as outlined in ARMOR.
[GLOVES:ITEM_GLOVES_GLOVES:COMMON]

|-
| {{text anchor|HELM}}
|
* item token
* rarity
| Rarity is optional, and valid values are FORCED, COMMON, UNCOMMON, and RARE (anything else is treated as COMMON). Uses the same rarity values and methods as outlined in ARMOR.
[HELM:ITEM_HELM_HELM:COMMON]

|-
| {{text anchor|INSTRUMENT}}
| item token
| No longer used due to the ability to generate instruments in world generation. It is still usable if pre-defined instruments are modded in, and generated musical forms are capable of selecting pre-defined instruments to use. However, reactions for making instruments, instrument parts, and/or assembling such instruments need to be added as well, as this token no longer adds such instruments to the craftdwarf's workshop menu.
[INSTRUMENT:ITEM_INSTRUMENT_FLUTE]

|-
| {{text anchor|PANTS}}
|
* item token
* rarity
| Rarity is optional, and valid values are FORCED, COMMON, UNCOMMON, and RARE (anything else is treated as COMMON). Uses the same rarity values and methods as outlined in ARMOR.
[PANTS:ITEM_PANTS_PANTS:COMMON]

|-
| {{text anchor|SHIELD}}
| item token
|
[SHIELD:ITEM_SHIELD_SHIELD]

|-
| {{text anchor|SHOES}}
|
* item token
* rarity
| Rarity is optional, and valid values are FORCED, COMMON, UNCOMMON, and RARE (anything else is treated as COMMON). Uses the same rarity values and methods as outlined in ARMOR.
[SHOES:ITEM_SHOES_SHOES:COMMON]

|-
| {{text anchor|SIEGEAMMO}}
| item token
|
[SIEGEAMMO:ITEM_SIEGEAMMO_BALLISTA]

|-
| {{text anchor|TOOL}}
| item token
|
[TOOL:ITEM_TOOL_NEST_BOX]

|-
| {{text anchor|TOY}}
| item token
|
[TOY:ITEM_TOY_PUZZLEBOX]

|-
| {{text anchor|TRAPCOMP}}
| item token
|
[TRAPCOMP:ITEM_TRAPCOMP_GIANTAXEBLADE]

|-
| {{text anchor|WEAPON}}
| item token
| While this does not accept a rarity value, something similar can be achieved by having multiple variations of a weapon type with small differences and specifying each of them.{{cite forum|179547}}
[WEAPON:ITEM_WEAPON_AXE_BATTLE]

|-
| {{text anchor|USE_ANIMAL_PRODUCTS}}
|
| Allows use of products made from animals. All relevant creatures will be able to provide wool, silk, and extracts (including milk and venom) for trade, and non-sentient creatures (unless ethics state otherwise) will be able to provide eggs, caught fish, meat, leather, bone, shell, pearl, horn, and ivory.

|-
| {{text anchor|USE_ANY_PET_RACE}}
|
| Any creature in the civilization's list of usables (from the surrounding 7x7 or so of squares and map features in those squares) will be included in the initial usable creature list, which then gets pared down or otherwise considered. Without this, only common domestic and equipment creatures are added to the initial list.

|-
| {{text anchor|USE_CAVE_ANIMALS}}
|
| If they don't have it, creatures with exclusively subterranean biomes are skipped. If they have it, cave creatures will be included in the initial usable creature list.

|-
| {{text anchor|USE_EVIL_ANIMALS}}
|
| Without this, {{token|EVIL|c}} creatures are skipped, otherwise, evil creatures with {{token|SLOW_LEARNER|c}} or ''without'' {{token|CAN_LEARN|c}} will be included in the initial usable creature list, even the normally untameable species.

|-
| {{text anchor|USE_EVIL_PLANTS}}
|
| Same as USE_EVIL_ANIMALS for all uses of plants.

|-
| {{text anchor|USE_EVIL_WOOD}}
|
| Same as USE_EVIL_ANIMALS for all uses of wood.

|-
| {{text anchor|USE_GOOD_ANIMALS}}
|
| Without this, {{token|GOOD|c}} creatures are skipped, otherwise, good creatures ''without'' {{token|CAN_LEARN|c}} will be included in the initial usable creature list, even the normally untameable species.

|-
| {{text anchor|USE_GOOD_PLANTS}}
|
| Same as USE_GOOD_ANIMALS for all uses of plants.

|-
| {{text anchor|USE_GOOD_WOOD}}
|
| Same as USE_GOOD_ANIMALS for all uses of wood.

|-
| {{text anchor|USE_MISC_PROCESSED_WOOD_PRODUCTS}}
|
| If the relevant professions are permitted, controls availability of lye ({{token|LYE_MAKER|ut}}), charcoal ({{token|WOOD_BURNER|ut}}), and potash ({{token|POTASH_MAKER|ut}}).

|-
| {{text anchor|USE_NON_EXOTIC_PET_RACE}}
|
| Makes the civilization use all locally available non-exotic pets.

|-
| {{text anchor|COMMON_DOMESTIC_MOUNT}}
|
| Gives the civilization access to creatures with {{token|COMMON_DOMESTIC|c}} and {{token|MOUNT|c}}. Additionally, all available (based on USE_ANY_PET_RACE, USE_CAVE_ANIMALS, USE_GOOD_ANIMALS, and USE_EVIL_ANIMALS) creature with {{token|MOUNT|c}} and {{token|PET|c}} will be allowed for use as mounts during combat.

|-
| {{text anchor|COMMON_DOMESTIC_PACK}}
|
| Gives the civilization access to creatures with {{token|COMMON_DOMESTIC|c}} and {{token|PACK_ANIMAL.|c}} Additionally, all available (see above) creatures with {{token|PACK_ANIMAL|c}} and {{token|PET|c}} will be allowed for use during trade as pack animals.

|-
| {{text anchor|COMMON_DOMESTIC_PET}}
|
| Gives the civilization access to creatures with {{token|COMMON_DOMESTIC|c}} and {{token|PET|c}}. Additionally, all available (see above) creatures with {{token|PET|c}} will be allowed for use as pets.

|-
| {{text anchor|COMMON_DOMESTIC_PULL}}
|
| Gives the civilization access to creatures with {{token|COMMON_DOMESTIC|c}} and {{token|WAGON_PULLER|c}}. Additionally, all available (see above) creatures with {{token|WAGON_PULLER|c}} and {{token|PET|c}} will be allowed for use during trade to pull [[wagon]]s.

|-
| {{text anchor|RIVER_PRODUCTS}}
|
| Allow use of river products in the goods available for trade.

|-
| {{text anchor|OCEAN_PRODUCTS}}
|
| Allow use of ocean products (including [[amber]] and [[coral]]) in the goods available for trade. Without OCEAN_PRODUCTS, civilizations will not be able to trade ocean fish even if they are ''also'' available from other sources (e.g. [[sturgeon]]s and [[stingray]]s).

|-
| {{text anchor|INDOOR_FARMING}}
|
| Allow use of underground plant products in the goods available for trade. Lack of suitable vegetation in the caverns will cause [[World generation#Rejections|worldgen rejection]]s. According to Droseran: "Gives access to plants (structural material) and seeds. It only checks for {{token|EDIBLE_RAW|md}} or {{token|EDIBLE_COOKED|md}} on the plant's structural material. It doesn't check if the plant can be used in a reaction to produce something edible, only if it can be eaten raw or cooked. If an entity with this token is placed in a biome that doesn't have at least one of these tokens on the structural material, the map is rejected. Due to the randomness of plant selection in biomes, this can happen a lot as only about half of the vanilla plants have edible structural materials. Removing either of these tokens from plants dramatically increases map rejections."

|-
| {{text anchor|OUTDOOR_FARMING}}
|
| Allow use of outdoor plant products in the goods available for trade. Lack of suitable vegetation in this civilization's starting area will cause [[World generation#Rejections|worldgen rejection]]s. According to Droseran: "Gives access to plants (structural material) and seeds. It only checks for {{token|EDIBLE_RAW|md}} or {{token|EDIBLE_COOKED|md}} on the plant's structural material. It doesn't check if the plant can be used in a reaction to produce something edible, only if it can be eaten raw or cooked. If an entity with this token is placed in a biome that doesn't have at least one of these tokens on the structural material, the map is rejected. Due to the randomness of plant selection in biomes, this can happen a lot as only about half of the vanilla plants have edible structural materials. Removing either of these tokens from plants dramatically increases map rejections."

|-
| {{text anchor|INDOOR_GARDENS}}
|
| Allow use of underground plant growths (quarry bush leaves, in unmodded games) in the goods available for trade. According to Droseran: "Will never cause map rejections. It allows growths to be used, but doesn't care if none exist. If an entity doesn't have a farming token, they won't have seeds or plants available on embark/trade. But you can still farm in fortress mode with only this token, you just have to get the seeds manually or trading with another civ."

|-
| {{text anchor|OUTDOOR_GARDENS}}
|
| Allow use of outdoor plant growths in the goods available for trade. According to Droseran: "Will never cause map rejections. It allows growths to be used, but doesn't care if none exist. If an entity doesn't have a farming token, they won't have seeds or plants available on embark/trade. But you can still farm in fortress mode with only this token, you just have to get the seeds manually or trading with another civ."

|-
| {{text anchor|INDOOR_ORCHARDS}}
|
| Allows use of indoor tree growths in the goods available for trade. Not used in vanilla entities, as vanilla underground trees do not grow fruit. Needs INDOOR_WOOD to function. Will cause rejections, if growths are unavailable. According to Droseran: "Gives access to tree growths. It only checks for growths on trees that are {{token|EDIBLE_RAW|md}} or {{token|EDIBLE_COOKED|md}}. If an entity with this token is placed in a biome that does not have a tree with a growth with at least one of these tokens, the map is rejected."

|-
| {{text anchor|OUTDOOR_ORCHARDS}}
|
| Allows use of outdoor tree growths in the goods available for trade. Needs OUTDOOR_WOOD to function{{verify}}. According to Droseran: "Gives access to tree growths. It only checks for growths on trees that are [EDIBLE_RAW] or [EDIBLE_COOKED]. If an entity with this token is placed in a biome that does not have a tree with a growth with at least one of these tokens, the map is rejected."

|-
| {{text anchor|CLOTHING}}
|
| Civilization members will attempt to wear clothing.

|-
| {{text anchor|SUBTERRANEAN_CLOTHING}}
|
| Will wear things made of spider silk and other subterranean materials.

|-
| {{text anchor|EQUIPMENT_IMPROVEMENTS}}
|
| Adds decorations to equipment based on the level of the generated unit. Also improves item quality.

|-
| {{text anchor|IMPROVED_BOWS}}
|
| Adds decorations to weapons generated for bowman and master bowman.

|-
| {{text anchor|METAL_PREF}}
|
| Allows metal materials to be used to make cages (inexpensive metals only) and crafts.

|-
| {{text anchor|STONE_PREF}}
|
| Allows the civilization to make use of nearby stone types. If the {{token|FURNACE_OPERATOR|ut}} job is permitted, also allows ore-bearing stones to be smelted into metals.

|-
| {{text anchor|WOOD_WEAPONS}}
|
| The civilization can make traditionally metallic weapons such as swords and spears from wood.

|-
| {{text anchor|WOOD_ARMOR}}
|
| The civilization can make traditionally metallic armor such as mail shirts and helmets from wood.

|-
| {{text anchor|GEM_PREF}}
|
| Enables creatures of this entity to bring gems in trade.

|-
| {{text anchor|INDOOR_WOOD}}
|
| Allow use of subterranean wood types, such as tower-cap and fungiwood logs.

|-
| {{text anchor|OUTDOOR_WOOD}}
|
| Allow use of outdoor wood types, such as mangrove and oak.

|-
| {{text anchor|GEM_SHAPE}}
| [[Descriptor shape token|shape]]
| Precious gems cut by this civilization's jewelers can be of this shape.

|-
| {{text anchor|STONE_SHAPE}}
| [[Descriptor shape token|shape]]
| Ordinary non-gem stones cut by this civilization's jewelers can be of this shape.

|-
| {{text anchor|DIVINE_MAT_CLOTHING}}
|
| Allows use of materials with {{token|DIVINE|im}} for clothing. Used for generated divine entities.

|-
| {{text anchor|DIVINE_MAT_CRAFTS}}
|
| Allows use of materials with {{token|DIVINE|im}} for crafts.{{verify}} Used for generated divine entities.

|-
| {{text anchor|DIVINE_MAT_WEAPONS}}
|
| Allows use of metals with {{token|DIVINE|im}} for weapons. Used for generated divine entities.

|-
| {{text anchor|DIVINE_MAT_ARMOR}}
|
| Allows use of metals with {{token|DIVINE|im}} for armor. Used for generated divine entities.
|}

== Animal definitions ==

{| {{prettytable}}
|- bgcolor="#ddd"
! Token
! Arguments
! Description

|-
| {{text anchor|ANIMAL}}
|
| Start an animal definition.

|-
| {{text anchor|ANIMAL_TOKEN}}
| [[creature token]]
| Select specific creature.

|-
| {{text anchor|ANIMAL_CASTE_TOKEN}}
| [[Caste|creature caste token]]
| Select specific creature caste (requires ANIMAL_TOKEN). Sites with animal populations will still include all castes, but only the selected ones will be used for specific roles.

|-
| {{text anchor|ANIMAL_CLASS}}
| [[Creature token#CREATURE_CLASS|creature class]]
| Select creature castes with this creature class (multiple uses allowed).

|-
| {{text anchor|ANIMAL_FORBIDDEN_CLASS}}
| [[Creature token#CREATURE_CLASS|creature class]]
| Forbid creature castes with this creature class (multiple uses allowed).

|-
| {{text anchor|ANIMAL_ALWAYS_PRESENT}}
|
| Animal will be present even if it does not naturally occur in the entity's terrain. All creatures, including [[demon]]s, night trolls and other generated ones will be used if no specific creature or class is selected.

|-
|
* {{text anchor|ANIMAL_NEVER_MOUNT}}, {{text anchor|ANIMAL_ALWAYS_MOUNT}}
* {{text anchor|ANIMAL_NEVER_WAGON_PULLER}}, {{text anchor|ANIMAL_ALWAYS_WAGON_PULLER}}
* {{text anchor|ANIMAL_NEVER_SIEGE}}, {{text anchor|ANIMAL_ALWAYS_SIEGE}}
* {{text anchor|ANIMAL_NEVER_PET}}, {{text anchor|ANIMAL_ALWAYS_PET}}
* {{text anchor|ANIMAL_NEVER_PACK_ANIMAL}}, {{text anchor|ANIMAL_ALWAYS_PACK_ANIMAL}}
|
| Override creature usage tokens. Respectively:
* [[Creature token#MOUNT|MOUNT]] and [[Creature token#MOUNT_EXOTIC|MOUNT_EXOTIC]]
* [[Creature token#WAGON_PULLER|WAGON_PULLER]]
* [[Creature token#TRAINABLE_WAR|TRAINABLE_WAR]] and not [[Creature token#CAN_LEARN|CAN_LEARN]]
* [[Creature token#PET|PET]] and [[Creature token#PET_EXOTIC|PET_EXOTIC]]
* [[Creature token#PACK_ANIMAL|PACK_ANIMAL]]
ALWAYS overrides NEVER if a caste is matched by more than one animal definition.

|}

== Tissue styling-related tokens ==
{| {{prettytable}}
|- bgcolor="#ddd"
! Token
! Arguments
! Description

|-
| {{text anchor|TISSUE_STYLE}}
| tissue style unit ID
| Select a tissue layer which has the ID attached using TISSUE_STYLE_UNIT token in unit raws. This allows setting further cultural style parameters for the selected tissue layer.

|-
| {{text anchor|TS_MAINTAIN_LENGTH}}
|
* minimum length?
* maximum length?
| Presumably sets culturally preferred tissue length for selected tissue. Needs testing.
Dwarves have their beards set to 100:NONE by default.

|-
| {{text anchor|TS_PREFERRED_SHAPING}}
| styling token
| Valid tokens are NEATLY_COMBED, BRAIDED, DOUBLE_BRAIDS, PONY_TAILS, CLEAN_SHAVEN and STANDARD_HAIR/BEARD/MOUSTACHE/SIDEBURNS_SHAPINGS.
Presumably sets culturally preferred tissue shapings for selected tissue. Needs testing.

|}

== Examples ==
:''Main articles: [[Entity examples]]''

{{Category|Modding}}
{{Category|Tokens}}
{{Category|Entities}}
[[ru:Entity token]]

Entity token

2026-04-09T14:34:24Z

Joostheger: /* Flavor */

{{Quality|Superior}}
{{av}}
{{Modding}}
'''Entity tokens''' define entities, or [[civilization]]s, in entity_*.txt files.

The <code>[OBJECT:ENTITY]</code> [[token]] begins the definition of an entity [[raw file]]. Each new entity definition that follows begins with the <code>[ENTITY:''entity_ID'']</code> token, where ''entity_ID'' is a unique identifier for that entity, and the entity's properties are then specified by the use of further entity tokens; or, tokens can be added to existing entities using <code>[SELECT_ENTITY:''entity_ID'']</code> instead.

All known entity tokens are listed below.

__TOC__
{{clear}}

== Gameplay ==
{| {{prettytable}}
|- bgcolor="#ddd"
! Token
! Arguments
! Description

|-
| {{text anchor|ALL_MAIN_POPS_CONTROLLABLE}}
|
| Allows adventure mode for entities with sites.

|-
| {{text anchor|SITE_CONTROLLABLE}}
|
| Allows fortress mode. If multiple entities have the SITE_CONTROLLABLE token, then at embark the specific civs can be chosen on the civ list screen. At least one civilization must have this token.

|-
| {{text anchor|CREATURE}}
| creature
|The type of creature that will inhabit the civilization. If multiple creature types are specified, each civilization will randomly choose one of the creatures. In entities with multiple possible creatures, you can manipulate the chance of one creature being chosen by adding multiple identical creature tags. For instance adding [CREATURE:DWARF][CREATURE:DWARF][CREATURE:DWARF][CREATURE:ELF] to the same entity will make the civs created about 75% dwarven, 25% elven. It should be noted that civilizations are in general weighted by this token: for example, if you have one entity with three [CREATURE:DWARF] tokens and another separate entity with a single [CREATURE:ELF] token, then you can expect to see three times as many of the former placed as the latter (assuming enough unclaimed [START_BIOME:X] space remains). Note that spawn rates are also limited by unclaimed biome space - if an entity can only spawn in a rarer set of biomes (only LAKE_TROPICAL_SALTWATER for example) then their spawn rate will end up being limited by the remaining unclaimed space in that biome type rather than the number of [CREATURE:X] tokens present in the entity raw.
|-
| {{text anchor|SOURCE_HFID}}
| integer
| Found on generated [[angel]] entities. Appears to draw from creatures with this HFID, which associates the entity with a historical figure of the same ID corresponding to a [[deity]].

|}

== Placement ==

Entity spawning during world gen is influenced by several factors:
* The "[[Advanced world generation#Number of Civilizations|Number of Civilizations]]" world gen setting places a hard limit on the total number of entities spawned.
* The "[[Advanced world generation#Playable Civilization Required|Playable Civilization Required]]" world gen setting forces at least one of each [[Entity token#SITE_CONTROLLABLE|SITE_CONTROLLABLE]] entity to spawn (presumably still limited by "Number of Civilizations").
* The number of <nowiki>[</nowiki>[[Entity token#CREATURE|CREATURE]]:X] tokens present in an entity modifies its chance of spawning. An entity containing more <nowiki>[</nowiki>[[Entity token#CREATURE|CREATURE]]:X] tokens will spawn more often (assuming other requirements are met) and may even block entities with fewer <nowiki>[</nowiki>[[Entity token#CREATURE|CREATURE]]:X] tokens from spawning altogether. You can use [SELECT_ENTITY:VANILLA_ENTITY_X] followed by any number of duplicate <nowiki>[</nowiki>[[Entity token#CREATURE|CREATURE]]:VANILLA_CREATURE_X] tokens to attempt to balance the spawn rates of the existing vanilla entities with any custom multi-creature entities you may add.
* The number of unclaimed [[Entity token#START_BIOME|START_BIOME]] or [[Entity token#EXCLUSIVE_START_BIOME|EXCLUSIVE_START_BIOME]] tiles remaining in the world limits the spawn rate for an entity and allows entities to block each other's spawns. If there is no "starting" [[Biome token|biome]] space left for an entity then it will not spawn and the game will try to spawn a different entity instead. This means that, on average, an entity that can start in ALL_MAIN [[Biome token|biomes]] will spawn more frequently than one that can start only in LAKE_TROPICAL_SALTWATER [[Biome token|biomes]]. This also means that entities whose starting [[Biome token|biomes]] do not overlap will not block each other's spawns.

{| {{prettytable}}
|- bgcolor="#ddd"
! Token
! Arguments
! Description

|-
| {{text anchor|BIOME_SUPPORT}}
|
* [[Biome token|biome]]
* frequency
| Controls the expansion of the civilization's territory. The higher the number is relative to other BIOME_SUPPORT tokens in the entity, the faster it can spread through the biome. These numbers are evaluated relative to each other, i.e. if one biome is 1 and the other is 2, the spread will be the same as if one was 100 and the other was 200. Civs can spread out over biomes they cannot actually build in; for example, humans spread quickly over oceans but cannot actually build in them.
[BIOME_SUPPORT:ANY_GRASSLAND:4]

The first entry of biome support should be the Start biome, as mentioned in [START_BIOME] or [EXCLUSIVE_START_BIOME], otherwise no other settlements after the first one are founded.

|-
| {{text anchor|SETTLEMENT_BIOME}}
| [[Biome token|biome]]
| If the civ's territory crosses over this biome, it can build settlements here.
[SETTLEMENT_BIOME:ANY_GRASSLAND]

|-
| {{text anchor|START_BIOME}}
| [[Biome token|biome]]
| Combination of EXCLUSIVE_START_BIOME and SETTLEMENT_BIOME; allows the civ to start in and create settlements in the biome. Note that the civ's spawn rate may be limited if all of its START or EXCLUSIVE_START biome(s) are rare in the world or have already been fully occupied by other civ spawns.
[START_BIOME:ANY_FOREST]

|-
| {{text anchor|EXCLUSIVE_START_BIOME}}
| [[Biome token|biome]]
| The birth of the civilization can occur in this biome, but cannot (necessarily) build in it. If the civ does not have SETTLEMENT_BIOME or START_BIOME for the biome in question, it will only construct a single settlement there. Note that the civ's spawn rate may be limited if all of its START or EXCLUSIVE_START biome(s) are rare in the world or have already been fully occupied by other civ spawns.
[EXCLUSIVE_START_BIOME:MOUNTAIN]

|-
| {{text anchor|DEFAULT_SITE_TYPE}}
| site type
| Valid site types are DARK_FORTRESS (π), CAVE (•), CAVE_DETAILED (Ω), TREE_CITY (î), and CITY (#). Also recognizes PLAYER_FORTRESS (creates a civ of hillocks only), and MONUMENT (creates a civ without visible sites (except tombs and castles), but may cause worldgen crashes). FORTRESS is no longer a valid entry, castles are currently controlled by BUILDS_OUTDOOR_FORTIFICATIONS. Defaults to CITY. Selecting CAVE causes the classic kobold behavior of not showing up on the "neighbors" section of the site selection screen.
Selecting DARK_FORTRESS also allows generation of [[underworld spire|certain other structures]]. It also gives the civ a [[demon|special overlord]]. DARK_FORTRESS may cause crashes during world gen at "Placing civilizations... (0)" if it combined with entity tokens that the vanilla ENTITY:EVIL does not use (likely the POSITION related tokens see [https://www.bay12forums.com/smf/index.php?topic=175747.0 this forum post]).
CAVE_DETAILED civilizations will create fortresses in mountainous regions and hillocks in non-mountainous regions. [DEFAULT_SITE_TYPE:CAVE_DETAILED]

|-
| {{text anchor|LIKES_SITE}}
| site type
| Most residents will try to move to this site type, unless already at one.
[LIKES_SITE:CAVE_DETAILED]

|-
| {{text anchor|TOLERATES_SITE}}
| site type
| Some residents will try to move to this site type, unless already at one.
[TOLERATES_SITE:CITY]

|-
| {{text anchor|WORLD_CONSTRUCTION}}
| construction
| Controls which constructions the civ will build on the world map. Valid constructions are ROAD, TUNNEL, BRIDGE, and WALL.
[WORLD_CONSTRUCTION:BRIDGE]
[WORLD_CONSTRUCTION:ROAD]
[WORLD_CONSTRUCTION:TUNNEL]
[WORLD_CONSTRUCTION:WALL]

|}

== Population ==

{| {{prettytable}}
|- bgcolor="#ddd"
! Token
! Arguments
! Description

|-
| {{text anchor|MAX_POP_NUMBER}}
| number
| Max '''historical''' population '''per entity'''. Multiply this by max starting civ to get the total maximum historical population of the species. Defaults to 500, but all vanilla entities use 10,000, except skulking uses 2,000. Does not limit the '''total''' population, but it will prevent new settlements upon reaching the number.
[MAX_POP_NUMBER:10000]

|-
| {{text anchor|MAX_SITE_POP_NUMBER}}
| number
| Max historical population per individual site. Defaults to 50, but all the vanilla entities use 120.
[MAX_SITE_POP_NUMBER:120]

|-
| {{text anchor|MAX_STARTING_CIV_NUMBER}}
| number
| Max number of civilizations of this entity type to spawn at world generation, which picks entities in some sequential order from the raws, looping through the list as needed. This is a hard limit, if set to 1, only 1 civilization of this type will be placed. If all entities have reached their limit, world generation will not try to place any more, even if its own [[Advanced_world_generation#Number_of_Civilizations|total limit]] has not been reached, and will continue on. Defaults to 3, but all vanilla entities use 100 (essentially unlimited).
[MAX_STARTING_CIV_NUMBER:100]

|}

== Flavor ==
{| {{prettytable}}
|- bgcolor="#ddd"
! Token
! Arguments
! Description

|-
| {{text anchor|PERMITTED_BUILDING}}
| building name
| The named, custom building can be built by a civilization in Fortress Mode.
[PERMITTED_BUILDING:SOAP_MAKER]

|-
| {{text anchor|PERMITTED_JOB}}
| [[Unit type token|profession]]
| Allows this job type to be selected. This applies to worldgen creatures, in the embark screen, and in play. Certain professions also influence the availability of materials for trade.
[PERMITTED_JOB:MINER]

|-
| {{text anchor|PERMITTED_REACTION}}
| reaction name
| Allows this reaction to be used by a civilization. It is used primarily in Fortress Mode, but also allows certain resources, such as [[steel]], to be available to a race. When creating custom reactions, this token '''must''' be present or the player will not be able to use the reaction in Fortress Mode.
[PERMITTED_REACTION:TAN_A_HIDE]

|-
| {{text anchor|CURRENCY_BY_YEAR}}
|
| Causes the civ's currency to be numbered with the year it was minted.

|-
| {{text anchor|CURRENCY}}
|
* inorganic material
* value
| What kind of metals the civ uses for coin minting, as well as the value of the [[coin]]. Only effective in Adventurer mode due to lack of [[dwarven economy]].

[CURRENCY:SILVER:5]

|-
| {{text anchor|ART_FACET_MODIFIER}}
|
* type
* number
| OWN_RACE, FANCIFUL, EVIL, GOOD
Number goes from 0 to 25600 where 256 is the default.
[ART_FACET_MODIFIER:OWN_RACE:512]

|-
| {{text anchor|ART_IMAGE_ELEMENT_MODIFIER}}
|
* item
* number
| CREATURE, PLANT, TREE, SHAPE, ITEM 0-25600

Determines the chance of each image occurring in that entity's artwork, such as engravings and on artifacts, for default (non-historical) artwork.

[ART_IMAGE_ELEMENT_MODIFIER:TREE:512]

|-
| {{text anchor|ITEM_IMPROVEMENT_MODIFIER}}
|
* item
* number
| ART_IMAGE, COVERED or GLAZED, RINGS_HANGING, BANDS, SPIKES, ITEMSPECIFIC, THREAD, CLOTH, SEWN_IMAGE. Also available, but effect unknown: PAGES, ILLUSTRATION, INSTRUMENT_PIECE, WRITING, IMAGE_SET, COLORATION. 0-25600

Determines the chance of the entity using that particular artwork method, such as "encircled with bands" or "menaces with spikes".

[ITEM_IMPROVEMENT_MODIFIER:SPIKES:0]

This also seems to change the amount that the entity will pay for items that are improved in these ways in their tokens.

|-
| {{text anchor|TRANSLATION}}
| language
| What language raw the entity uses.
* If an entity lacks this tag, translations are drawn randomly from all translation files. Multiple translation tags will only result in the last one being used. Migrants will sometimes arrive with no name.
* If GEN_DIVINE is entered, the entity will use a generated divine language, that is, the same language that is used for the names of [[angel]]s.
* If the entity's main creature has {{token|UTTERANCES|c}}, then this token will be ignored (except when using the naming menu) in favor of procedural [[kobold]]-style [[Kobold language|pseudolanguage]].
[TRANSLATION:DWARF]

|-
| {{text anchor|SELECT_SYMBOL}}
|
* category
* [[language#language_SYM.txt|symbol]]
| ALL, REMAINING, BATTLE, BRIDGE, CIV, CRAFT_GUILD, FESTIVAL (doesn't work, see below), HOSPITAL, LIBRARY, MERCHANT_COMPANY, MILITARY_UNIT, OTHER, RELIGION, ROAD, SIEGE, SITE, TEMPLE, TUNNEL, VESSEL, WALL, WAR
The entity will always use a word from the selected symbol(s) to generate names from that category.
* OTHER applies the symbol selection to personal names and site names. REMAINING will apply the symbol selection to all categories that have not already been declared above it.
* Specific to SELECT_SYMBOL, symbols selected this way will be used as "The X" in "The X of Y" names, and nouns from selected symbols can be used as first [[name]]s.
* FESTIVAL does not work. The game uses symbol NAME_FESTIVAL hardcoded. You may consider changing that symbol (with SELECT_SYMBOL), but then it's applied for all entities.

[SELECT_SYMBOL:ALL:PEACE]

|-
| {{text anchor|SUBSELECT_SYMBOL}}
|
* category
* [[language#language_SYM.txt|symbol]]
| As SELECT_SYMBOL, a word from the subselected symbol(s) will be used in names of that category, in addition to the word from SELECT_SYMBOL (if specified). Used in vanilla to put violent names in sieges and battles.
* Words chosen with SUBSELECT_SYMBOL will appear as either adjectives or "of Y" in "The X of Y" names.
* CULL_SYMBOL does not affect subselected symbols.

[SELECT_SYMBOL:SIEGE:NAME_SIEGE]

[SUBSELECT_SYMBOL:SIEGE:VIOLENT]

|-
| {{text anchor|CULL_SYMBOL}}
|
* category
* [[Language#language_SYM.txt|symbol]]
| Causes the entity to not use the words in these SYM sets.
[CULL_SYMBOL:ALL:UGLY]

|-
| {{text anchor|FRIENDLY_COLOR}}
| see [[color]]
|
The color of this entity's civilization settlements in the world gen and embark screens, also used when announcing arrival of their caravan. Defaults to 7:0:1.

[FRIENDLY_COLOR:1:0:1]

|}

== Religion ==
{| {{prettytable}}
|- bgcolor="#ddd"
! Token
! Arguments
! Description

|-
| {{text anchor|RELIGION}}
| type
|
* REGIONAL_FORCE: The creatures will worship a single force associated with the terrain of their initial biome.
* PANTHEON: The creatures will worship a group of gods, each aligned with their spheres and other appropriate ones as well.

Can be specified multiple times, and will pick randomly from the assigned types. Additional instances of each type will weight the random choice, but unlike {{token|CREATURE|e}}, will not make the entity more likely to spawn.

[RELIGION:PANTHEON]

|-
| {{text anchor|RELIGION_SPHERE}}
| [[Sphere#Available_spheres|sphere]]
| Can be any available [[sphere]] - multiple entries are possible. Choosing a religious sphere will automatically make its opposing sphere not possible for the species to have: adding [[Sphere#WATER|WATER]], for example, means civs of this entity will never get [[Sphere#FIRE|FIRE]] as a religious sphere. Note that the [[Sphere#DEATH|DEATH]] sphere favours the appearance of necromancers (and therefore, towers) "in" the entity.

[RELIGION_SPHERE:FORTRESSES]

|-
| {{text anchor|SPHERE_ALIGNMENT}}
|
* [[Sphere#Available_spheres|sphere]]
* number
|
This token forces an entity to favor or disfavor particular religious spheres. Default is 256, minimum is 0, maximum is 25600.
* Presently, this doesn't cause them to acquire those spheres more often when generating a pantheon.
* [[Sphere#PLANTS|PLANTS]] and [[Sphere#ANIMALS|ANIMALS]] affect the prevalence of depicting {{token|VEGETATION}} and {{token|NATURAL}} creatures, respectively, in a similar fashion to {{token|ART_FACET_MODIFIER|e}}.
* [[Sphere#WAR|WAR]] modifies the effective [[item value]] of [[weapon]]s and [[armor]] to [[trader]]s of this entity. The multiplier is SPHERE_ALIGNMENT/256, though this only applies to equipment the entity's main creature can properly wield.

[SPHERE_ALIGNMENT:TREES:512]

|}

== Leadership ==
{| {{prettytable}}
|- bgcolor="#ddd"
! Token
! Arguments
! Description

|-
| {{text anchor|POSITION}}
| string
| Defines a leader/noble position for a civilization. These replace previous tags such as [MAYOR] and [CAN_HAVE_SITE_LEADER] and so on. To define a position further, see [[Position token]].

|-
| {{text anchor|SITE_VARIABLE_POSITIONS}}
| Position responsibility or ALL
| Allows a site responsibility to be taken up by a dynamically generated position (lords, hearthpersons, etc.). Any defined positions holding a given responsibility will take precedence over generated positions for that responsibility. Also appears to cause site disputes.{{Verify}} See also: [[variable positions]]

|-
| {{text anchor|VARIABLE_POSITIONS}}
| Position responsibility or ALL
| Allows a responsibility to be taken up by a dynamically generated position (such as Law-maker). Any defined positions holding a given responsibility will take precedence over generated positions for that responsibility. See also: [[variable positions]]

|}

== Behavior ==
{| {{prettytable}}
|- bgcolor="#ddd"
! Token
! Arguments
! Description

|-
| {{text anchor|ETHIC}}
|
*behavior
*reaction
| Sets the civ's view of [[ethic]]s (certain behaviors), from capital punishment to completely acceptable. This also causes the civ to look upon opposing ethics with disfavor if their reaction to it is opposing, and when at extremes (one ACCEPTABLE, another civ UNTHINKABLE; for example) they will often go to war over it.
[ETHIC:EAT_SAPIENT_KILL:ACCEPTABLE]

|-
| {{text anchor|VALUE}}
|
*value
*number
| Sets the civ's [[Personality value|cultural values]]. Numbers range from -50 (complete anathema) to 0 (neutral) to 50 (highly valued).
[VALUE:CRAFTSMANSHIP:50]

Certain values must be set to 15 or more for civs to create structures and form entities during history gen:
* 15+ KNOWLEDGE for libraries
* 15+ COOPERATION ''and'' 15+ CRAFTSMANSHIP for craft guilds
** Guilds also need guild-valid professions (see [[#PERMITTED_JOB|PERMITTED_JOB]])

If the positions of an entity are variable (and include the CUSTOM_OFFICIAL_1), then CUNNING > 10 is needed for the CUSTOM_OFFICIAL_1 to have the espionage responsibility.

|-
| {{text anchor|VARIABLE_VALUE}}
|
*value or ALL
*min
*max
| Makes values randomized rather than specified.
This tag overrides the VALUE tag. Using [VARIABLE_VALUE:ALL:x:y] and then overwriting single values with further [VARIABLE_VALUE:value:x:y] tags works.

|-
| {{text anchor|WILL_ACCEPT_TRIBUTE}}
|
| Makes the civ's traders accept offered goods.

|-
| {{text anchor|WANDERER}}, {{text anchor|BEAST_HUNTER}}, {{text anchor|SCOUT}}, {{text anchor|MERCENARY}}
|
| The civ will send out these sorts of adventurers in worldgen, which seems to increase Tracker skill. These types of adventurers will sometimes be seen leading a battle (instead of war leaders or generals) in remote locations during world-gen, in charge of the defenders.

Mercenaries and monster hunters from the civ may visit player's fortress and petition for residency there to enlist in the military or hunt monsters in caverns, respectively.

|-
| {{text anchor|ABUSE_BODIES}}
|
| The civilization will mutilate bodies when they are the victors in history-gen warfare, such as hanging bodies from trees, putting them on spikes, and so forth. Adventurers killed in Adventurer mode will sometimes be impaled on spikes wherever they died, with or without this token, and regardless of whether they actually antagonized the townspeople.

|-
| {{text anchor|ACTIVE_SEASON}}
| season
| The season when the civ is most active: when they will trade, interact with you via diplomats, and/or invade you. Civs can have multiple season entries. Note: If multiple caravans arrive at the same time, you are able to select which civ to trade with at the depot menu. ACTIVE_SEASON tags may be changed for a currently active fort.
[ACTIVE_SEASON:AUTUMN]

|-
| {{text anchor|AMBUSHER}}
|
| When invading, sneaks around and shoots at straggling members of your society. They will spawn on the edge of the map and will only be visible when one of their party are spotted; this can be quite dangerous to undefended trade depots. If the civilization also has the SIEGER token, they will eventually ramp it up to less subtle means of warfare.

|-
| {{text anchor|AT_PEACE_WITH_WILDLIFE}}
|
| Will not attack wildlife, and will not be attacked by them, even if you have them in your party. This can be somewhat disconcerting when attacked by bears in the forest, and your elven ally sits back and does nothing. Additionally, this token determines if the entity can settle in savage biomes.

|-
| {{text anchor|BABYSNATCHER}}
|
| Sends thieves to steal babies. Without this tag (or AMBUSHER, or ITEM_THIEF), enemy civs will only siege (if capable), and will siege as early as they would otherwise babysnatch. This can happen as early as the first year of the fort! In addition, babysnatcher civs will snatch children during worldgen, allowing them to become part of the civ if they do not escape. Also causes this civ to be hostile to any entity without this token.

Note: If the playable civ in fortress mode has this tag (e.g. you add BABYSNATCHER to the dwarf entity) then the roles will be reversed and elves and humans will siege and ambush and goblins will be friendly to you. However, animals traded away to one's own caravan will count as snatched, reported upon the animal leaving the map, and the animal will not count as having been exported.

|-
| {{text anchor|BUILDS_OUTDOOR_FORTIFICATIONS}}
|
| Makes the civilization build castles from [[mead hall]]s. Only functions when the type of site built is a hamlet/town. This, combined with the correct type of [[position token|position]] associated with a site, is why adventurers can only lay claim to human sites. {{bug|8001}}

|-
| {{text anchor|BUILDS_OUTDOOR_TOMBS}}
|
| Makes the civilization build tombs.

|-
| {{text anchor|BANDITRY}}
| percentage
| Sets a percentage of the entity population to be used as bandits.

|-
| {{text anchor|DIPLOMAT_BODYGUARDS}}
|
| Visiting diplomats are accompanied by a pair of soldiers.
|-
| {{text anchor|GENERATED}}
|
| Found on generated divine "HF Guardian Entities". Cannot be used in user-defined raws.

|-
| {{text anchor|INVADERS_IGNORE_NEUTRALS}}
|
| Causes invaders to ignore visiting caravans and other neutral creatures.{{verify}}

|-
| {{text anchor|ITEM_THIEF}}
|
| Sends thieves to steal items. This will also occur in history generation, and thieves will have the "thief" profession. Items stolen in history gen will be scattered around that creature's home. Also causes that civ to be hostile to any entity without this token. Without this tag (or AMBUSHER, or BABYSNATCHER), enemy civs will only siege (if capable), and will siege as early as they would otherwise steal.

Note: If the playable civ in Fortress Mode has this tag (e.g. you add ITEM_THIEF to the Dwarf entity) then the roles will be reversed and elves and humans will siege and ambush and kobolds will be friendly to you. However, ALL items traded away to one's own caravan will count as stolen, reported when the items leave the map, and the stolen items will not count as exported.

|-
| {{text anchor|LOCAL_BANDITRY}}
|
| Causes the entity to send out patrols that can ambush adventurers. Said patrols will be hostile to any adventurers they encounter, regardless of race or nationality.

|-
| {{text anchor|MERCHANT_BODYGUARDS}}
|
| Caravan merchants are accompanied by soldiers.

|-
| {{text anchor|MERCHANT_NOBILITY}}
|
| Merchants will engage in cross-civ trading and form companies.

In previous versions, this resulted in the civ having a Guild Representative / Merchant Baron / Merchant Prince, but now this is controlled solely by positions.

|-
| {{text anchor|PROGRESS_TRIGGER_POPULATION}}
| level
| 0 to 5, civ will come to site once population at site has reached that level. If multiple progress triggers exist for a civ, it will come when any one of them is fulfilled instead of waiting for all of them to be reached. A value of 0 disables the trigger. 1 corresponds to 20 dwarves, 2 to 50 dwarves, 3 to 80, 4 to 110, and 5 to 140. Progress triggers may be changed, added, or deleted for a currently active fort. Note: hostile civs require that this be fulfilled as well as at least one other non-siege trigger before visiting for non-siege activities.

|-
| {{text anchor|PROGRESS_TRIGGER_PRODUCTION}}
| level
| 0 to 5, civ will come to site once created wealth has reached that level. If multiple progress triggers exist for a civ, it will come when any one of them is fulfilled instead of waiting for all of them to be reached. A value of 0 disables the trigger. 1 corresponds to 5000☼ created wealth, 2 to 25000☼, 3 to 100000☼, 4 to 200000☼, and 5 to 300000☼. Progress triggers may be changed, added, or deleted for a currently active fort.

|-
| {{text anchor|PROGRESS_TRIGGER_TRADE}}
| level
| 0 to 5, civ will come to site once exported goods has reached that level. If multiple progress triggers exist for a civ, it will come when any one of them is fulfilled instead of waiting for all of them to be reached. A value of 0 disables the trigger. 1 corresponds to 500☼ exported wealth, 2 to 2500☼, 3 to 10000☼, 4 to 20000☼, and 5 to 30000☼. Progress triggers may be changed, added, or deleted for a currently active fort.

|-
| {{text anchor|PROGRESS_TRIGGER_POP_SIEGE}}
| level
| 0 to 5, civ will begin to send sieges against the player civ when this level is reached if it is hostile.

If multiple progress triggers exist for a civ, it will come when any one of them is fulfilled instead of waiting for all of them to be reached. A value of 0 disables the trigger.

|-
| {{text anchor|PROGRESS_TRIGGER_PROD_SIEGE}}
| level
| 0 to 5, civ will begin to send sieges against the player civ when this level is reached if it is hostile.

|-
| {{text anchor|PROGRESS_TRIGGER_TRADE_SIEGE}}
| level
| 0 to 5, civ will begin to send sieges against the player civ when this level is reached if it is hostile.

|-
| {{text anchor|SIEGER}}
|
| Will start campfires and wait around at the edge of your map for a month or two before rushing in to attack. This will occur when the progress triggers for sieging are reached. If the civ lacks smaller methods of conflict (AMBUSHER, BABYSNATCHER, ITEM_THIEF), they will instead send smaller-scale sieges when their triggers for "first contact" are reached.

|-
| {{text anchor|SIEGE_SKILLED_MINERS}}{{v|53.01}}
|
| Improves the skill of [[miner]] invaders by a factor of 5. Used for [[dwarves]] in vanilla.

|-
| {{text anchor|SITE_GUARDIAN}}
|
| Guards certain special sites, such as a [[vault]] belonging to a [[demon]] allied with a [[deity]]. Used in generated divine entities.

|-
| {{text anchor|SKULKING}}
|
| This makes the severity of attacks depend on the extent of item/baby thievery rather than the passage of time. Designed to go with ITEM_THIEF, may or may not work with BABYSNATCHER. Prevents the civ from engaging in diplomacy or ending up at war.

|-
| {{text anchor|TREE_CAP_DIPLOMACY}}
|
| Visiting diplomats impose tree cutting quotas; without this, they will simply compliment your fortress and leave. Also causes the diplomat to make unannounced first contact at the very beginning of the first spring after your fortress becomes a land holder.

|-
| {{text anchor|LAYER_LINKED}}
|
| Defines if a civilization is a hidden subterranean entity, such as [[bat man]] civilizations. May spawn in any of the three caverns; cavern dweller raids due to [[agitation]] will pull from these. If you embark as this civ, you have access to pets and trees from all three layers, not only the first.

|-
| {{text anchor|GENERATE_KEYBOARD_INSTRUMENTS}}, {{text anchor|GENERATE_PERCUSSION_INSTRUMENTS}}, {{text anchor|GENERATE_STRINGED_INSTRUMENTS}}, {{text anchor|GENERATE_WIND_INSTRUMENTS}}, {{text anchor|GENERATE_DANCE_FORMS}}, {{text anchor|GENERATE_MUSICAL_FORMS}}, {{text anchor|GENERATE_POETIC_FORMS}}
|
| Makes civilizations generate the given instruments/forms.

|-
| {{text anchor|SCHOLAR}}
| scholar type
| ALL, ASTRONOMER, CHEMIST, DOCTOR, ENGINEER, GEOGRAPHER, HISTORIAN, MATHEMATICIAN, NATURALIST, PHILOSOPHER

|-
| {{text anchor|SET_SCHOLARS_ON_VALUES_AND_JOBS}}
|
| Generates scholars based on the values generated with the VARIABLE_VALUE tag.

|-
| {{text anchor|NO_ARTIFACT_CLAIMS}}
|
| Used for kobolds.

|-
| {{text anchor|MINING_UNDERWORLD_DISASTERS}}
|
| The civilization can breach the [[Underworld]] during world generation, spawning a civilization of {{token|EVIL}} creatures lead by a unique [[demon]].

|-
| {{text anchor|MYTHICAL}}{{version|51.01-beta26}}
|
| Builds [[mysterious dungeon]]s.

|}

== Available resources ==
{| {{prettytable}}
|- bgcolor="#ddd"
! Token
! Arguments
! Description

|-
| {{text anchor|AMMO}}
| item token
| Used after a ranged weapon type.
[AMMO:ITEM_AMMO_BOLTS]

|-
| {{text anchor|ARMOR}}
|
* item token
* rarity
| Rarity is optional, and valid values are FORCED, COMMON, UNCOMMON, and RARE (anything else is treated as COMMON). FORCED items will be available 100% of the time, COMMON items 50%, UNCOMMON items 10%, and RARE items 1%. If certain armor types are lacking after performing one pass of randomised checks, the game will repeat random checks until an option is successfully chosen.
[ARMOR:ITEM_ARMOR_PLATEMAIL:COMMON]

|-
| {{text anchor|DIGGER}}
| item token
| Causes the selected weapon to fall under the "digging tools" section of the embark screen. Also forces the weapon to be made out of metal, which can cause issues if a modded entity has access to picks without access to metal - for those cases, listing the pick under the [WEAPON] token works just as well. Note that this tag is neither necessary nor sufficient to allow use of that item as a mining tool – for that, the item itself needs to be a weapon with {{token|SKILL|wp|MINING}}.
[DIGGER:ITEM_WEAPON_PICK]

|-
| {{text anchor|GLOVES}}
|
* item token
* rarity
| Rarity is optional, and valid values are FORCED, COMMON, UNCOMMON, and RARE (anything else is treated as COMMON). Uses the same rarity values and methods as outlined in ARMOR.
[GLOVES:ITEM_GLOVES_GLOVES:COMMON]

|-
| {{text anchor|HELM}}
|
* item token
* rarity
| Rarity is optional, and valid values are FORCED, COMMON, UNCOMMON, and RARE (anything else is treated as COMMON). Uses the same rarity values and methods as outlined in ARMOR.
[HELM:ITEM_HELM_HELM:COMMON]

|-
| {{text anchor|INSTRUMENT}}
| item token
| No longer used due to the ability to generate instruments in world generation. It is still usable if pre-defined instruments are modded in, and generated musical forms are capable of selecting pre-defined instruments to use. However, reactions for making instruments, instrument parts, and/or assembling such instruments need to be added as well, as this token no longer adds such instruments to the craftdwarf's workshop menu.
[INSTRUMENT:ITEM_INSTRUMENT_FLUTE]

|-
| {{text anchor|PANTS}}
|
* item token
* rarity
| Rarity is optional, and valid values are FORCED, COMMON, UNCOMMON, and RARE (anything else is treated as COMMON). Uses the same rarity values and methods as outlined in ARMOR.
[PANTS:ITEM_PANTS_PANTS:COMMON]

|-
| {{text anchor|SHIELD}}
| item token
|
[SHIELD:ITEM_SHIELD_SHIELD]

|-
| {{text anchor|SHOES}}
|
* item token
* rarity
| Rarity is optional, and valid values are FORCED, COMMON, UNCOMMON, and RARE (anything else is treated as COMMON). Uses the same rarity values and methods as outlined in ARMOR.
[SHOES:ITEM_SHOES_SHOES:COMMON]

|-
| {{text anchor|SIEGEAMMO}}
| item token
|
[SIEGEAMMO:ITEM_SIEGEAMMO_BALLISTA]

|-
| {{text anchor|TOOL}}
| item token
|
[TOOL:ITEM_TOOL_NEST_BOX]

|-
| {{text anchor|TOY}}
| item token
|
[TOY:ITEM_TOY_PUZZLEBOX]

|-
| {{text anchor|TRAPCOMP}}
| item token
|
[TRAPCOMP:ITEM_TRAPCOMP_GIANTAXEBLADE]

|-
| {{text anchor|WEAPON}}
| item token
| While this does not accept a rarity value, something similar can be achieved by having multiple variations of a weapon type with small differences and specifying each of them.{{cite forum|179547}}
[WEAPON:ITEM_WEAPON_AXE_BATTLE]

|-
| {{text anchor|USE_ANIMAL_PRODUCTS}}
|
| Allows use of products made from animals. All relevant creatures will be able to provide wool, silk, and extracts (including milk and venom) for trade, and non-sentient creatures (unless ethics state otherwise) will be able to provide eggs, caught fish, meat, leather, bone, shell, pearl, horn, and ivory.

|-
| {{text anchor|USE_ANY_PET_RACE}}
|
| Any creature in the civilization's list of usables (from the surrounding 7x7 or so of squares and map features in those squares) will be included in the initial usable creature list, which then gets pared down or otherwise considered. Without this, only common domestic and equipment creatures are added to the initial list.

|-
| {{text anchor|USE_CAVE_ANIMALS}}
|
| If they don't have it, creatures with exclusively subterranean biomes are skipped. If they have it, cave creatures will be included in the initial usable creature list.

|-
| {{text anchor|USE_EVIL_ANIMALS}}
|
| Without this, {{token|EVIL|c}} creatures are skipped, otherwise, evil creatures with {{token|SLOW_LEARNER|c}} or ''without'' {{token|CAN_LEARN|c}} will be included in the initial usable creature list, even the normally untameable species.

|-
| {{text anchor|USE_EVIL_PLANTS}}
|
| Same as USE_EVIL_ANIMALS for all uses of plants.

|-
| {{text anchor|USE_EVIL_WOOD}}
|
| Same as USE_EVIL_ANIMALS for all uses of wood.

|-
| {{text anchor|USE_GOOD_ANIMALS}}
|
| Without this, {{token|GOOD|c}} creatures are skipped, otherwise, good creatures ''without'' {{token|CAN_LEARN|c}} will be included in the initial usable creature list, even the normally untameable species.

|-
| {{text anchor|USE_GOOD_PLANTS}}
|
| Same as USE_GOOD_ANIMALS for all uses of plants.

|-
| {{text anchor|USE_GOOD_WOOD}}
|
| Same as USE_GOOD_ANIMALS for all uses of wood.

|-
| {{text anchor|USE_MISC_PROCESSED_WOOD_PRODUCTS}}
|
| If the relevant professions are permitted, controls availability of lye ({{token|LYE_MAKER|ut}}), charcoal ({{token|WOOD_BURNER|ut}}), and potash ({{token|POTASH_MAKER|ut}}).

|-
| {{text anchor|USE_NON_EXOTIC_PET_RACE}}
|
| Makes the civilization use all locally available non-exotic pets.

|-
| {{text anchor|COMMON_DOMESTIC_MOUNT}}
|
| Gives the civilization access to creatures with {{token|COMMON_DOMESTIC|c}} and {{token|MOUNT|c}}. Additionally, all available (based on USE_ANY_PET_RACE, USE_CAVE_ANIMALS, USE_GOOD_ANIMALS, and USE_EVIL_ANIMALS) creature with {{token|MOUNT|c}} and {{token|PET|c}} will be allowed for use as mounts during combat.

|-
| {{text anchor|COMMON_DOMESTIC_PACK}}
|
| Gives the civilization access to creatures with {{token|COMMON_DOMESTIC|c}} and {{token|PACK_ANIMAL.|c}} Additionally, all available (see above) creatures with {{token|PACK_ANIMAL|c}} and {{token|PET|c}} will be allowed for use during trade as pack animals.

|-
| {{text anchor|COMMON_DOMESTIC_PET}}
|
| Gives the civilization access to creatures with {{token|COMMON_DOMESTIC|c}} and {{token|PET|c}}. Additionally, all available (see above) creatures with {{token|PET|c}} will be allowed for use as pets.

|-
| {{text anchor|COMMON_DOMESTIC_PULL}}
|
| Gives the civilization access to creatures with {{token|COMMON_DOMESTIC|c}} and {{token|WAGON_PULLER|c}}. Additionally, all available (see above) creatures with {{token|WAGON_PULLER|c}} and {{token|PET|c}} will be allowed for use during trade to pull [[wagon]]s.

|-
| {{text anchor|RIVER_PRODUCTS}}
|
| Allow use of river products in the goods available for trade.

|-
| {{text anchor|OCEAN_PRODUCTS}}
|
| Allow use of ocean products (including [[amber]] and [[coral]]) in the goods available for trade. Without OCEAN_PRODUCTS, civilizations will not be able to trade ocean fish even if they are ''also'' available from other sources (e.g. [[sturgeon]]s and [[stingray]]s).

|-
| {{text anchor|INDOOR_FARMING}}
|
| Allow use of underground plant products in the goods available for trade. Lack of suitable vegetation in the caverns will cause [[World generation#Rejections|worldgen rejection]]s. According to Droseran: "Gives access to plants (structural material) and seeds. It only checks for {{token|EDIBLE_RAW|md}} or {{token|EDIBLE_COOKED|md}} on the plant's structural material. It doesn't check if the plant can be used in a reaction to produce something edible, only if it can be eaten raw or cooked. If an entity with this token is placed in a biome that doesn't have at least one of these tokens on the structural material, the map is rejected. Due to the randomness of plant selection in biomes, this can happen a lot as only about half of the vanilla plants have edible structural materials. Removing either of these tokens from plants dramatically increases map rejections."

|-
| {{text anchor|OUTDOOR_FARMING}}
|
| Allow use of outdoor plant products in the goods available for trade. Lack of suitable vegetation in this civilization's starting area will cause [[World generation#Rejections|worldgen rejection]]s. According to Droseran: "Gives access to plants (structural material) and seeds. It only checks for {{token|EDIBLE_RAW|md}} or {{token|EDIBLE_COOKED|md}} on the plant's structural material. It doesn't check if the plant can be used in a reaction to produce something edible, only if it can be eaten raw or cooked. If an entity with this token is placed in a biome that doesn't have at least one of these tokens on the structural material, the map is rejected. Due to the randomness of plant selection in biomes, this can happen a lot as only about half of the vanilla plants have edible structural materials. Removing either of these tokens from plants dramatically increases map rejections."

|-
| {{text anchor|INDOOR_GARDENS}}
|
| Allow use of underground plant growths (quarry bush leaves, in unmodded games) in the goods available for trade. According to Droseran: "Will never cause map rejections. It allows growths to be used, but doesn't care if none exist. If an entity doesn't have a farming token, they won't have seeds or plants available on embark/trade. But you can still farm in fortress mode with only this token, you just have to get the seeds manually or trading with another civ."

|-
| {{text anchor|OUTDOOR_GARDENS}}
|
| Allow use of outdoor plant growths in the goods available for trade. According to Droseran: "Will never cause map rejections. It allows growths to be used, but doesn't care if none exist. If an entity doesn't have a farming token, they won't have seeds or plants available on embark/trade. But you can still farm in fortress mode with only this token, you just have to get the seeds manually or trading with another civ."

|-
| {{text anchor|INDOOR_ORCHARDS}}
|
| Allows use of indoor tree growths in the goods available for trade. Not used in vanilla entities, as vanilla underground trees do not grow fruit. Needs INDOOR_WOOD to function. Will cause rejections, if growths are unavailable. According to Droseran: "Gives access to tree growths. It only checks for growths on trees that are {{token|EDIBLE_RAW|md}} or {{token|EDIBLE_COOKED|md}}. If an entity with this token is placed in a biome that does not have a tree with a growth with at least one of these tokens, the map is rejected."

|-
| {{text anchor|OUTDOOR_ORCHARDS}}
|
| Allows use of outdoor tree growths in the goods available for trade. Needs OUTDOOR_WOOD to function{{verify}}. According to Droseran: "Gives access to tree growths. It only checks for growths on trees that are [EDIBLE_RAW] or [EDIBLE_COOKED]. If an entity with this token is placed in a biome that does not have a tree with a growth with at least one of these tokens, the map is rejected."

|-
| {{text anchor|CLOTHING}}
|
| Civilization members will attempt to wear clothing.

|-
| {{text anchor|SUBTERRANEAN_CLOTHING}}
|
| Will wear things made of spider silk and other subterranean materials.

|-
| {{text anchor|EQUIPMENT_IMPROVEMENTS}}
|
| Adds decorations to equipment based on the level of the generated unit. Also improves item quality.

|-
| {{text anchor|IMPROVED_BOWS}}
|
| Adds decorations to weapons generated for bowman and master bowman.

|-
| {{text anchor|METAL_PREF}}
|
| Allows metal materials to be used to make cages (inexpensive metals only) and crafts.

|-
| {{text anchor|STONE_PREF}}
|
| Allows the civilization to make use of nearby stone types. If the {{token|FURNACE_OPERATOR|ut}} job is permitted, also allows ore-bearing stones to be smelted into metals.

|-
| {{text anchor|WOOD_WEAPONS}}
|
| The civilization can make traditionally metallic weapons such as swords and spears from wood.

|-
| {{text anchor|WOOD_ARMOR}}
|
| The civilization can make traditionally metallic armor such as mail shirts and helmets from wood.

|-
| {{text anchor|GEM_PREF}}
|
| Enables creatures of this entity to bring gems in trade.

|-
| {{text anchor|INDOOR_WOOD}}
|
| Allow use of subterranean wood types, such as tower-cap and fungiwood logs.

|-
| {{text anchor|OUTDOOR_WOOD}}
|
| Allow use of outdoor wood types, such as mangrove and oak.

|-
| {{text anchor|GEM_SHAPE}}
| [[Descriptor shape token|shape]]
| Precious gems cut by this civilization's jewelers can be of this shape.

|-
| {{text anchor|STONE_SHAPE}}
| [[Descriptor shape token|shape]]
| Ordinary non-gem stones cut by this civilization's jewelers can be of this shape.

|-
| {{text anchor|DIVINE_MAT_CLOTHING}}
|
| Allows use of materials with {{token|DIVINE|im}} for clothing. Used for generated divine entities.

|-
| {{text anchor|DIVINE_MAT_CRAFTS}}
|
| Allows use of materials with {{token|DIVINE|im}} for crafts.{{verify}} Used for generated divine entities.

|-
| {{text anchor|DIVINE_MAT_WEAPONS}}
|
| Allows use of metals with {{token|DIVINE|im}} for weapons. Used for generated divine entities.

|-
| {{text anchor|DIVINE_MAT_ARMOR}}
|
| Allows use of metals with {{token|DIVINE|im}} for armor. Used for generated divine entities.
|}

== Animal definitions ==

{| {{prettytable}}
|- bgcolor="#ddd"
! Token
! Arguments
! Description

|-
| {{text anchor|ANIMAL}}
|
| Start an animal definition.

|-
| {{text anchor|ANIMAL_TOKEN}}
| [[creature token]]
| Select specific creature.

|-
| {{text anchor|ANIMAL_CASTE_TOKEN}}
| [[Caste|creature caste token]]
| Select specific creature caste (requires ANIMAL_TOKEN). Sites with animal populations will still include all castes, but only the selected ones will be used for specific roles.

|-
| {{text anchor|ANIMAL_CLASS}}
| [[Creature token#CREATURE_CLASS|creature class]]
| Select creature castes with this creature class (multiple uses allowed).

|-
| {{text anchor|ANIMAL_FORBIDDEN_CLASS}}
| [[Creature token#CREATURE_CLASS|creature class]]
| Forbid creature castes with this creature class (multiple uses allowed).

|-
| {{text anchor|ANIMAL_ALWAYS_PRESENT}}
|
| Animal will be present even if it does not naturally occur in the entity's terrain. All creatures, including [[demon]]s, night trolls and other generated ones will be used if no specific creature or class is selected.

|-
|
* {{text anchor|ANIMAL_NEVER_MOUNT}}, {{text anchor|ANIMAL_ALWAYS_MOUNT}}
* {{text anchor|ANIMAL_NEVER_WAGON_PULLER}}, {{text anchor|ANIMAL_ALWAYS_WAGON_PULLER}}
* {{text anchor|ANIMAL_NEVER_SIEGE}}, {{text anchor|ANIMAL_ALWAYS_SIEGE}}
* {{text anchor|ANIMAL_NEVER_PET}}, {{text anchor|ANIMAL_ALWAYS_PET}}
* {{text anchor|ANIMAL_NEVER_PACK_ANIMAL}}, {{text anchor|ANIMAL_ALWAYS_PACK_ANIMAL}}
|
| Override creature usage tokens. Respectively:
* [[Creature token#MOUNT|MOUNT]] and [[Creature token#MOUNT_EXOTIC|MOUNT_EXOTIC]]
* [[Creature token#WAGON_PULLER|WAGON_PULLER]]
* [[Creature token#TRAINABLE_WAR|TRAINABLE_WAR]] and not [[Creature token#CAN_LEARN|CAN_LEARN]]
* [[Creature token#PET|PET]] and [[Creature token#PET_EXOTIC|PET_EXOTIC]]
* [[Creature token#PACK_ANIMAL|PACK_ANIMAL]]
ALWAYS overrides NEVER if a caste is matched by more than one animal definition.

|}

== Tissue styling-related tokens ==
{| {{prettytable}}
|- bgcolor="#ddd"
! Token
! Arguments
! Description

|-
| {{text anchor|TISSUE_STYLE}}
| tissue style unit ID
| Select a tissue layer which has the ID attached using TISSUE_STYLE_UNIT token in unit raws. This allows setting further cultural style parameters for the selected tissue layer.

|-
| {{text anchor|TS_MAINTAIN_LENGTH}}
|
* minimum length?
* maximum length?
| Presumably sets culturally preferred tissue length for selected tissue. Needs testing.
Dwarves have their beards set to 100:NONE by default.

|-
| {{text anchor|TS_PREFERRED_SHAPING}}
| styling token
| Valid tokens are NEATLY_COMBED, BRAIDED, DOUBLE_BRAIDS, PONY_TAILS, CLEAN_SHAVEN and STANDARD_HAIR/BEARD/MOUSTACHE/SIDEBURNS_SHAPINGS.
Presumably sets culturally preferred tissue shapings for selected tissue. Needs testing.

|}

== Examples ==
:''Main articles: [[Entity examples]]''

{{Category|Modding}}
{{Category|Tokens}}
{{Category|Entities}}
[[ru:Entity token]]

Talk:Variable positions

2026-04-09T11:01:51Z

Joostheger:

----Hi! nice work so far!
A few points:
* I really wonder where the differences between human and goblins are coming from. Do you have any idea? I almost know for sure that the difference in MARKET-positions is because of humans have the CITY- type in DEFAULT_SITE_TYPE. But the others, I dont know. perhaps because of their values or ethics?
* There is a lot of vague language in this article ('Some religious entities(...)', which ones?), but also to much certainty, at places :-) . I would suggest to make it more tight. ChatGPT or another text AI can be of good use there, to remove any ambiguity
* The number of -1 is very strange to me, because this is an invalid value when writing raws for entities. Do you have any idea what the circumstances are for these positions? I see for example with the priests. Can it be that PRIEST is REPLACED_BY HIGH_PRIEST and also by highest priest? In that case, number -1 means: "currently replaced". It should not have a current holder. For example, can you check a site with a mayor, does the expedition leader has -1? in that case, its caused by replacement.
* Landholders are a strange bunch, I'm curious if you find out anything about those!
[[User:Joostheger|Joostheger]] ([[User talk:Joostheger|talk]]) 12:22, 12 February 2026 (UTC)

Thank you.
* Not sure. The thing is even if the goblins do overtake another site, no market officials will be created. So it is more likely an ethics or values thing. The same for the reduced number of different officials.
* Well no. And the thing about "Some religious entities" in that case is, that some religious entities do not have any positions (eg. due to no variable position being created during world gen for these religious entities), but all of these entities (with no positions) will probably not create an abbot (CUSTOM_LAW_MAKER), but priest and so on (if the world-gen could/would be restarted). But without checking all religious entities without positions in detail, it might be that in some cases an religious entity (which could create an abbot) does not have a position at the end of world gen. So while there is from one perspective some ambiguity, from another perspective it is very precise.
* The number -1 means that it is unlimited, meaning for that position an unlimited amount of assignments can be created.
* No there is no replacement between the priest. Look at the responsibilities for priest and the others. Also the highest priest is capped at one (ie. like the pope), while their is an unlimited number of high priests possible (like cardinals or bishops).
* So far all entries in the variable position were empty. So it seems that neither humans nor goblins are landholders. And I still need a little bit more familiarity with Lua, for a few more complicated scripts (which also correctly query the different abstract building types).

In general some info is still missing. And also I am in a few cases not sure yet, what exactly is the case, so some ambiguity might also stem from that. Only at the last step I will try to remove (unneccessary) ambiguity.

ps. At some point the commented out text passages should be removed (deleted), but if I would try to do it, it will be detected as possibly harmful and not be allowed.[[Special:Contributions/91.49.240.46|91.49.240.46]] 13:15, 12 February 2026 (UTC)
----
* Ok ill help you remove the commented lines, but you really should create an account :-)
* The number unlimited is written in the raws as AS_NEEDED. is that correct? If you, i'll suggest to replace the -1 with AS_NEEDED, to make that consistent with other positions and understandability
* I dont think you'll find any other landholders by the way. I think it isnt in variable positions to have that. Landholders arent also neccesary to let the game run and simulate an interesint world, while these variable positions are.
[[User:Joostheger|Joostheger]] ([[User talk:Joostheger|talk]]) 14:52, 12 February 2026 (UTC)

----
* Well I might eventually create an account, iff no email address (etc.) needs to be provided.
* The translation of data into understandable form is not a priority, but -1 will be changed eventually (or a note added).

ps. I will probably not edit anything in the next few hours on the article, so now or maybe tommorrow might be a good idea to remove the lines currently commented out.[[Special:Contributions/91.49.240.46|91.49.240.46]] 15:21, 12 February 2026 (UTC)

----
Most of the "easy" work has been done. Next steps would be (not necessarily in the stated order):
1. replacing/removing the technical flags.
2. further research on what the concret requirements for the creation of different official and market official positions on site level is.
3. Figureing out the reason why goblins so far only create variable positions on site level, when the leader was a custom bandit leader (ie. at least in case of the forced admin it should be possible).
4. Figureing out why the goblins only create a subset of all possible variable official positions (both on site and civ level).
5. Researching why the goblins do not create custom market officials.
6. Figureing out why in some cases the dwarves use the generic forced admin and not the forced admin from the dwarven raws.
7. Removing any ambiguity (if possible) from the page and improve understandability. For that I suggest that with pointing to the unclear part a discussion entry is made, so that I am made aware of it and can then clear it up.
8. Improve formatting and table presentation: ie. possibly move some info to other tables to reduce table width (of the existing table). Or use smaller fonts (scaling) for some table entries. etc.
9. Figureing out (and testing) which other values in the tags [variable_positions] (and variable_site_positions) are valid. I do not think that it is only [variable_positions:all]. (This won't be done by me).
10. Add section(s) for modifing the game data, so that in an existing world a few more variable positions are created (and filled with historical figures). So that the variable positions then function as if the variable positions had already been created (and filled) during world gen.

I am probably missing a few things. But that is all for now, from my part. Further edits (by me) to the variable positions page will not be done before next week.[[Special:Contributions/91.49.240.46|91.49.240.46]] 17:32, 13 February 2026 (UTC)
----
a few thoughs on your questions:
3: I quess that the most important factors are their DEFAULT_SITE_TYPE and their values. 4: same. See: [[https://www.bay12forums.com/smf/index.php?topic=110027.msg8610297#msg8610297]]. 5: Because there are no markets in the dark fortress. 6: I think that the entity MOUNTAINS (dwarves) always uses the raw-forced administrator. I think that what you have seen, are probably not entity type 1, but maybe like outcasts or villains or whatever. 9: I can see what i can do [[User:Joostheger|Joostheger]] ([[User talk:Joostheger|talk]]) 21:10, 17 February 2026 (UTC)

----
Well the dwarves are (probably) supposed to only use the forced
administrator as defined in the raws, but they are not.

In one case the site ruled by the forced administrator was originally
a human site, which was then taken over by a (dwarven) necromancer.
Afterwards a dwarven civ defeated the necromancer forces and formed a new government with a forced administrator (with precedence 100).
And the government still rules at the end of world gen.

The other was originally a dwarven site (hillock).
It was then taken over by a necromancer (again dwarven).
The dwarves (original owners) then took the site back and put
a forced administrator in place (again with precedence 100). But the
site did change its owner again afterwards.

To 3.: The goblins can take over other sites, so that is unlikely the cause. And would also not explain why the goblins with a custom bandit leader do create some officials, but the forced admin does not. (It is a totally different question, why the normal goblin site leaders do not create any officials.)

To 4.: Well for one thing the ethics (and not the values) might play a role (ie. most things being a "personal matter"). For some other things (chef, grain official) it is probably either that the goblins do neither drink nor eat or it is (indirectly) because of that as they might not have some labors/jobs (see [[https://dwarffortressbugtracker.com/view.php?id=11727]]). The later is probably also the reason, why they do not have doctors. The values on the other hand will probably play a role, whether the custom law maker is a diplomat (or has the military strategy responsibility).

To 5.: Again the goblins can take over other sites, so unless they always destroy the markets, when they occupy such a site, this cannot be the reason. But needs to be something else.

To. 9: The question is, whether the definitions allows multiple variable_position tags (resp. site variable position tags) or if only one is evaluated (and used). Furthermore the question is, whether only ALL and the name of a responsibility (like MANAGE_WORK_ORDERS) is allowed or if the name of the custom officials (as used as code) is also valid. And then a follow-up question would be, if ie. MILITARY_STRATEGY is written as entry, whether this will always create the CUSTOM_MILITARY_STRATEGY. And what about the cases, when an official has usually two responsibilities (like the "chef"), will that official be created with only one resp., if only one is given. Do both responsibilities need to be written (ie. with a comma as separator) in one tag. But that are all modding related questions (and not questions for modifying an existing world).

BTW: In many cases, when I looked into the history, a forced administrator was created usually after a site had been taken over by a necromancer (some time before). But I have not figured out yet, how I can easily check (from the entity definition), which group belongs to a necromancer and which not.[[Special:Contributions/91.49.240.46|91.49.240.46]] 16:44, 18 February 2026 (UTC)

== Variable Positions and Quests ==

Quiet a few variable positions do have the same flags set as ie. the CUSTOM_BANDIT_LEADER (who is according to the Quest page) able to give out quests to adventurers, allthough some of the variable positions do not have any squads (which again according to the Quest page is necessary to be able to give out quests), but then again the question is, whether that information on the Quest page (which seems to have been more or less only been migrated from an older version to the current v5x version) is current (or has even been correct for the older version). It is probably a good idea if someone tests out in the adventure mode, if ie. the guild leader (dean/doyen), merchant corporation leader (and representative) and other variable positions (who are mentioned on this page to have the quest_giver and/or kill_quest flag set) are able to give out quests to adventurers and then ie. update the Quest page with the results.[[Special:Contributions/91.49.240.46|91.49.240.46]] 14:05, 7 March 2026 (UTC)

== Holding multiple variable positions in world-gen. ==

Well while checking something else, I did come across a human necromancer, who currently holds 4 (variable) position assignments (and which are not former position assignments). The first three positions belong to an OUTCAST group, where the human holds the CUSTOM_OUTCAST_LT position (first assignment still active) and then two different CUSTOM_OUTCAST_FACTOR (assignments). The last position is the CUSTOM_LAW_MAKER (law-giver) of a human civilization (gained afterwards). The information is via dfhack and legends of a world directly after finishing world-gen (for the dfhack info a new game was started in the world and either before selecting the type of the game dfhack was used for analyzing the current game data or after selecting legends mode and analyzing the current game data with dfhack in addition to using the legends). In how far the necromancer is fullfilling all assignments is - of course - a totally different matter. An indepth analysis, how seldom/rare it is and which entities and position assignments are possible, will be done at a later date (possibly end of this month).[[Special:Contributions/91.49.243.26|91.49.243.26]] 11:52, 14 March 2026 (UT
----
Hello nameless one, love your work so far! Very impressive.
About CUSTOM_OUTCAST_LT being only a single one, there is another possible reason discussed in the forums. Search for 'army' and 'lieutentant'. It is, that there is (almost) never a reason to create more than one army commander, despite the civ being able to do so.
[[User:Joostheger|Joostheger]] ([[User talk:Joostheger|talk]]) 13:23, 15 March 2026 (UTC)
----
The squad size of the CUSTOM_OUTCAST_LT is zero (unless you do doubt the table entry), ie. in contrast to the usual army commanders. So the reason for no more than one CUSTOM_OUTCAST_LT has nothing to do, with being an army commander. To see for yourself, just ie. set the number for the OUTPOST_LIASION to AS_NEEDED and look whether you will get an OUTPOST_LIASION created (ie. the problem has not really anything to do with being an army commander or not, but with the AS_NEEDED or unlimited number, without the game knowing what condition to check, whether to create an (or another) assignment for the position, at least if the position is not tied to a number of locations/sites or the position being a landholder, which is again tied to the number of sites of a certain kind). And the reason for one CUSTOM_OUTCAST_LT getting created, instead of zero is already in the note.[[Special:Contributions/91.49.243.26|91.49.243.26]] 12:28, 16 March 2026 (UTC)

Addition: The only discussion I could find in the bay12 forums are from 2021 and thus concern v47 and not the current version. Besides considering that in my current game one human civ attacks itself nearly each year, shortly after their caravan returns home, in some cases with the attacker only a yak bull or yak cow (otherwise usually a single human), I do not think that any previous info about creation of army commanders is relevant, as yak bulls (and yak cows) are doing just fine as army commanders (of their one-yak-army). Or to put it in other words army commanders are currently created on the fly (otherwise in a world I did analyze there would be no way that a necromancer, with a tower, even if the necromancer would draft all position holders and itself as an army commander, could attack 20-30 different sites all at the start of a season of the same year; this btw. happened at least twice in the span of the 250 years of history in world-gen allthough with different necromancers).
ps. If you are wondering the yak bulls/cows and the humans are previous traders, who visited my fortress.[[Special:Contributions/91.49.243.26|91.49.243.26]] 17:02, 16 March 2026 (UTC)
----
Here are the posts I was referring to. Do with it what you want.
* https://www.bay12forums.com/smf/index.php?topic=175437.msg8331668#msg8331668
* https://www.bay12forums.com/smf/index.php?topic=165213.msg8335682#msg8335682

It surprises me that CUSTOM_OUTCAST_LT has a squad of 0, despite its obvious responsibilities. Since this game is far from finished, my guess is that this is just an oversight. I would be cautious in drawing conclusions, because a lot of what you're working with is outdated, and hasn't been seen by the developers for years.
another tip: in de old dev-diaries are hidden gems of information. See for example https://www.bay12games.com/dwarves/dev_2011.html and look for 'outcast'.
[[User:Joostheger|Joostheger]] ([[User talk:Joostheger|talk]]) 09:56, 17 March 2026 (UTC)

---- Here's a piece of valuable information:
"I also allowed the '''variable-position''' cultures (humans and goblins) to '''form''' many more administrative '''positions''' to give them layers for the intrigue to operate over (the dwarves already have many layers, from the bookkeepers over to the landed nobles and monarch.) Now they can end up with a keeper of the seal, a royal justiciar, a chief housekeeper, a master of beasts, and many other randomized possibilities, '''depending on the values of the culture, its permitted professions and other traits'''. The positions overlap with the current dwarven responsibilities, though there are a few new ones. This doesn't mean much yet, specifically, but there will be some practical considerations implemented before we're through." source: https://www.bay12games.com/dwarves/dev_2018.html?utm_source=chatgpt.com
[[User:Joostheger|Joostheger]] ([[User talk:Joostheger|talk]]) 10:19, 7 April 2026 (UTC)

Yeah, I will have to look into the intrique part at some point - currently I can only create the positions, create the assignments, have the position be filled, the corresponding historical events to be shown in legends, have the positions take care of their responsibilities and have them take residence in the appropiate building (with corresponding historical event to start ruling from a mead hall or keep), not knowing if that is enough to also get the "intrique" part going. But I did found a more or less intriqueing part, where a human site government had a baron and a baroness (at the same time, both baron/baroness created during world-gen) - the assignment did point to the histfig which assumed the position later (but in legends for both histfigs it was claimed that they are the current baron/baroness). And both had taken residence in the local keep (as a seat of power). I did come across this bit, when checking under which circumstances the law-giver will take up residence somewhere to rule. (Which as it turns out must be a keep in the capital, which means that the infrastructure.TOWN value must be greater than zero, but will not do so, if the captial is currently ruled by a FORCED_ADMINISTRATOR, who interestingly will not get upgraded to a CUSTOM_LAW_MAKER_2, if the ruled site is the capital. If the capital has a keep and the site government, which is part of the civ, is not ruled by a FORCED_ADMINISTRATOR than the law-giver and the site ruler will usually take residence in the keep to rule from it. In case of the FORCED_ADMINISTRATOR only the admin will take residence in the keep.)[[Special:Contributions/87.143.74.72|87.143.74.72]] 10:13, 9 April 2026 (UTC)
----
Yeah, but the intrigue is not the most interesting part here. It is that positions are created, based on cultural values. [[User:Joostheger|Joostheger]] ([[User talk:Joostheger|talk]]) 11:01, 9 April 2026 (UTC)

Talk:Variable positions

2026-04-07T10:19:28Z

Joostheger: /* Holding multiple variable positions in world-gen. */

Entity token

2026-04-07T08:50:44Z

Joostheger: /* Placement */ apparently, the sequence in which biome support tokens are defined, matters.

{{Quality|Superior}}
{{av}}
{{Modding}}
'''Entity tokens''' define entities, or [[civilization]]s, in entity_*.txt files.

The <code>[OBJECT:ENTITY]</code> [[token]] begins the definition of an entity [[raw file]]. Each new entity definition that follows begins with the <code>[ENTITY:''entity_ID'']</code> token, where ''entity_ID'' is a unique identifier for that entity, and the entity's properties are then specified by the use of further entity tokens; or, tokens can be added to existing entities using <code>[SELECT_ENTITY:''entity_ID'']</code> instead.

All known entity tokens are listed below.

__TOC__
{{clear}}

== Gameplay ==
{| {{prettytable}}
|- bgcolor="#ddd"
! Token
! Arguments
! Description

|-
| {{text anchor|ALL_MAIN_POPS_CONTROLLABLE}}
|
| Allows adventure mode for entities with sites.

|-
| {{text anchor|SITE_CONTROLLABLE}}
|
| Allows fortress mode. If multiple entities have the SITE_CONTROLLABLE token, then at embark the specific civs can be chosen on the civ list screen. At least one civilization must have this token.

|-
| {{text anchor|CREATURE}}
| creature
|The type of creature that will inhabit the civilization. If multiple creature types are specified, each civilization will randomly choose one of the creatures. In entities with multiple possible creatures, you can manipulate the chance of one creature being chosen by adding multiple identical creature tags. For instance adding [CREATURE:DWARF][CREATURE:DWARF][CREATURE:DWARF][CREATURE:ELF] to the same entity will make the civs created about 75% dwarven, 25% elven. It should be noted that civilizations are in general weighted by this token: for example, if you have one entity with three [CREATURE:DWARF] tokens and another separate entity with a single [CREATURE:ELF] token, then you can expect to see three times as many of the former placed as the latter (assuming enough unclaimed [START_BIOME:X] space remains). Note that spawn rates are also limited by unclaimed biome space - if an entity can only spawn in a rarer set of biomes (only LAKE_TROPICAL_SALTWATER for example) then their spawn rate will end up being limited by the remaining unclaimed space in that biome type rather than the number of [CREATURE:X] tokens present in the entity raw.
|-
| {{text anchor|SOURCE_HFID}}
| integer
| Found on generated [[angel]] entities. Appears to draw from creatures with this HFID, which associates the entity with a historical figure of the same ID corresponding to a [[deity]].

|}

== Placement ==

Entity spawning during world gen is influenced by several factors:
* The "[[Advanced world generation#Number of Civilizations|Number of Civilizations]]" world gen setting places a hard limit on the total number of entities spawned.
* The "[[Advanced world generation#Playable Civilization Required|Playable Civilization Required]]" world gen setting forces at least one of each [[Entity token#SITE_CONTROLLABLE|SITE_CONTROLLABLE]] entity to spawn (presumably still limited by "Number of Civilizations").
* The number of <nowiki>[</nowiki>[[Entity token#CREATURE|CREATURE]]:X] tokens present in an entity modifies its chance of spawning. An entity containing more <nowiki>[</nowiki>[[Entity token#CREATURE|CREATURE]]:X] tokens will spawn more often (assuming other requirements are met) and may even block entities with fewer <nowiki>[</nowiki>[[Entity token#CREATURE|CREATURE]]:X] tokens from spawning altogether. You can use [SELECT_ENTITY:VANILLA_ENTITY_X] followed by any number of duplicate <nowiki>[</nowiki>[[Entity token#CREATURE|CREATURE]]:VANILLA_CREATURE_X] tokens to attempt to balance the spawn rates of the existing vanilla entities with any custom multi-creature entities you may add.
* The number of unclaimed [[Entity token#START_BIOME|START_BIOME]] or [[Entity token#EXCLUSIVE_START_BIOME|EXCLUSIVE_START_BIOME]] tiles remaining in the world limits the spawn rate for an entity and allows entities to block each other's spawns. If there is no "starting" [[Biome token|biome]] space left for an entity then it will not spawn and the game will try to spawn a different entity instead. This means that, on average, an entity that can start in ALL_MAIN [[Biome token|biomes]] will spawn more frequently than one that can start only in LAKE_TROPICAL_SALTWATER [[Biome token|biomes]]. This also means that entities whose starting [[Biome token|biomes]] do not overlap will not block each other's spawns.

{| {{prettytable}}
|- bgcolor="#ddd"
! Token
! Arguments
! Description

|-
| {{text anchor|BIOME_SUPPORT}}
|
* [[Biome token|biome]]
* frequency
| Controls the expansion of the civilization's territory. The higher the number is relative to other BIOME_SUPPORT tokens in the entity, the faster it can spread through the biome. These numbers are evaluated relative to each other, i.e. if one biome is 1 and the other is 2, the spread will be the same as if one was 100 and the other was 200. Civs can spread out over biomes they cannot actually build in; for example, humans spread quickly over oceans but cannot actually build in them.
[BIOME_SUPPORT:ANY_GRASSLAND:4]

The first entry of biome support should be the Start biome, as mentioned in [START_BIOME] or [EXCLUSIVE_START_BIOME], otherwise no other settlements after the first one are founded.

|-
| {{text anchor|SETTLEMENT_BIOME}}
| [[Biome token|biome]]
| If the civ's territory crosses over this biome, it can build settlements here.
[SETTLEMENT_BIOME:ANY_GRASSLAND]

|-
| {{text anchor|START_BIOME}}
| [[Biome token|biome]]
| Combination of EXCLUSIVE_START_BIOME and SETTLEMENT_BIOME; allows the civ to start in and create settlements in the biome. Note that the civ's spawn rate may be limited if all of its START or EXCLUSIVE_START biome(s) are rare in the world or have already been fully occupied by other civ spawns.
[START_BIOME:ANY_FOREST]

|-
| {{text anchor|EXCLUSIVE_START_BIOME}}
| [[Biome token|biome]]
| The birth of the civilization can occur in this biome, but cannot (necessarily) build in it. If the civ does not have SETTLEMENT_BIOME or START_BIOME for the biome in question, it will only construct a single settlement there. Note that the civ's spawn rate may be limited if all of its START or EXCLUSIVE_START biome(s) are rare in the world or have already been fully occupied by other civ spawns.
[EXCLUSIVE_START_BIOME:MOUNTAIN]

|-
| {{text anchor|DEFAULT_SITE_TYPE}}
| site type
| Valid site types are DARK_FORTRESS (π), CAVE (•), CAVE_DETAILED (Ω), TREE_CITY (î), and CITY (#). Also recognizes PLAYER_FORTRESS (creates a civ of hillocks only), and MONUMENT (creates a civ without visible sites (except tombs and castles), but may cause worldgen crashes). FORTRESS is no longer a valid entry, castles are currently controlled by BUILDS_OUTDOOR_FORTIFICATIONS. Defaults to CITY. Selecting CAVE causes the classic kobold behavior of not showing up on the "neighbors" section of the site selection screen.
Selecting DARK_FORTRESS also allows generation of [[underworld spire|certain other structures]]. It also gives the civ a [[demon|special overlord]]. DARK_FORTRESS may cause crashes during world gen at "Placing civilizations... (0)" if it combined with entity tokens that the vanilla ENTITY:EVIL does not use (likely the POSITION related tokens see [https://www.bay12forums.com/smf/index.php?topic=175747.0 this forum post]).
CAVE_DETAILED civilizations will create fortresses in mountainous regions and hillocks in non-mountainous regions. [DEFAULT_SITE_TYPE:CAVE_DETAILED]

|-
| {{text anchor|LIKES_SITE}}
| site type
| Most residents will try to move to this site type, unless already at one.
[LIKES_SITE:CAVE_DETAILED]

|-
| {{text anchor|TOLERATES_SITE}}
| site type
| Some residents will try to move to this site type, unless already at one.
[TOLERATES_SITE:CITY]

|-
| {{text anchor|WORLD_CONSTRUCTION}}
| construction
| Controls which constructions the civ will build on the world map. Valid constructions are ROAD, TUNNEL, BRIDGE, and WALL.
[WORLD_CONSTRUCTION:BRIDGE]
[WORLD_CONSTRUCTION:ROAD]
[WORLD_CONSTRUCTION:TUNNEL]
[WORLD_CONSTRUCTION:WALL]

|}

== Population ==

{| {{prettytable}}
|- bgcolor="#ddd"
! Token
! Arguments
! Description

|-
| {{text anchor|MAX_POP_NUMBER}}
| number
| Max '''historical''' population '''per entity'''. Multiply this by max starting civ to get the total maximum historical population of the species. Defaults to 500, but all vanilla entities use 10,000, except skulking uses 2,000. Does not limit the '''total''' population, but it will prevent new settlements upon reaching the number.
[MAX_POP_NUMBER:10000]

|-
| {{text anchor|MAX_SITE_POP_NUMBER}}
| number
| Max historical population per individual site. Defaults to 50, but all the vanilla entities use 120.
[MAX_SITE_POP_NUMBER:120]

|-
| {{text anchor|MAX_STARTING_CIV_NUMBER}}
| number
| Max number of civilizations of this entity type to spawn at world generation, which picks entities in some sequential order from the raws, looping through the list as needed. This is a hard limit, if set to 1, only 1 civilization of this type will be placed. If all entities have reached their limit, world generation will not try to place any more, even if its own [[Advanced_world_generation#Number_of_Civilizations|total limit]] has not been reached, and will continue on. Defaults to 3, but all vanilla entities use 100 (essentially unlimited).
[MAX_STARTING_CIV_NUMBER:100]

|}

== Flavor ==
{| {{prettytable}}
|- bgcolor="#ddd"
! Token
! Arguments
! Description

|-
| {{text anchor|PERMITTED_BUILDING}}
| building name
| The named, custom building can be built by a civilization in Fortress Mode.
[PERMITTED_BUILDING:SOAP_MAKER]

|-
| {{text anchor|PERMITTED_JOB}}
| [[Unit type token|profession]]
| Allows this job type to be selected. This applies to worldgen creatures, in the embark screen, and in play. Certain professions also influence the availability of materials for trade.
[PERMITTED_JOB:MINER]

|-
| {{text anchor|PERMITTED_REACTION}}
| reaction name
| Allows this reaction to be used by a civilization. It is used primarily in Fortress Mode, but also allows certain resources, such as [[steel]], to be available to a race. When creating custom reactions, this token '''must''' be present or the player will not be able to use the reaction in Fortress Mode.
[PERMITTED_REACTION:TAN_A_HIDE]

|-
| {{text anchor|CURRENCY_BY_YEAR}}
|
| Causes the civ's currency to be numbered with the year it was minted.

|-
| {{text anchor|CURRENCY}}
|
* inorganic material
* value
| What kind of metals the civ uses for coin minting, as well as the value of the [[coin]]. Only effective in Adventurer mode due to lack of [[dwarven economy]].

[CURRENCY:SILVER:5]

|-
| {{text anchor|ART_FACET_MODIFIER}}
|
* type
* number
| OWN_RACE, FANCIFUL, EVIL, GOOD
Number goes from 0 to 25600 where 256 is the default.
[ART_FACET_MODIFIER:OWN_RACE:512]

|-
| {{text anchor|ART_IMAGE_ELEMENT_MODIFIER}}
|
* item
* number
| CREATURE, PLANT, TREE, SHAPE, ITEM 0-25600

Determines the chance of each image occurring in that entity's artwork, such as engravings and on artifacts, for default (non-historical) artwork.

[ART_IMAGE_ELEMENT_MODIFIER:TREE:512]

|-
| {{text anchor|ITEM_IMPROVEMENT_MODIFIER}}
|
* item
* number
| ART_IMAGE, COVERED or GLAZED, RINGS_HANGING, BANDS, SPIKES, ITEMSPECIFIC, THREAD, CLOTH, SEWN_IMAGE 0-25600

Determines the chance of the entity using that particular artwork method, such as "encircled with bands" or "menaces with spikes".

[ITEM_IMPROVEMENT_MODIFIER:SPIKES:0]

This also seems to change the amount that the entity will pay for items that are improved in these ways in their tokens.

|-
| {{text anchor|TRANSLATION}}
| language
| What language raw the entity uses.
* If an entity lacks this tag, translations are drawn randomly from all translation files. Multiple translation tags will only result in the last one being used. Migrants will sometimes arrive with no name.
* If GEN_DIVINE is entered, the entity will use a generated divine language, that is, the same language that is used for the names of [[angel]]s.
* If the entity's main creature has {{token|UTTERANCES|c}}, then this token will be ignored (except when using the naming menu) in favor of procedural [[kobold]]-style [[Kobold language|pseudolanguage]].
[TRANSLATION:DWARF]

|-
| {{text anchor|SELECT_SYMBOL}}
|
* category
* [[language#language_SYM.txt|symbol]]
| ALL, REMAINING, BATTLE, BRIDGE, CIV, CRAFT_GUILD, FESTIVAL (doesn't work, see below), HOSPITAL, LIBRARY, MERCHANT_COMPANY, MILITARY_UNIT, OTHER, RELIGION, ROAD, SIEGE, SITE, TEMPLE, TUNNEL, VESSEL, WALL, WAR
The entity will always use a word from the selected symbol(s) to generate names from that category.
* OTHER applies the symbol selection to personal names and site names. REMAINING will apply the symbol selection to all categories that have not already been declared above it.
* Specific to SELECT_SYMBOL, symbols selected this way will be used as "The X" in "The X of Y" names, and nouns from selected symbols can be used as first [[name]]s.
* FESTIVAL does not work. The game uses symbol NAME_FESTIVAL hardcoded. You may consider changing that symbol (with SELECT_SYMBOL), but then it's applied for all entities.

[SELECT_SYMBOL:ALL:PEACE]

|-
| {{text anchor|SUBSELECT_SYMBOL}}
|
* category
* [[language#language_SYM.txt|symbol]]
| As SELECT_SYMBOL, a word from the subselected symbol(s) will be used in names of that category, in addition to the word from SELECT_SYMBOL (if specified). Used in vanilla to put violent names in sieges and battles.
* Words chosen with SUBSELECT_SYMBOL will appear as either adjectives or "of Y" in "The X of Y" names.
* CULL_SYMBOL does not affect subselected symbols.

[SELECT_SYMBOL:SIEGE:NAME_SIEGE]

[SUBSELECT_SYMBOL:SIEGE:VIOLENT]

|-
| {{text anchor|CULL_SYMBOL}}
|
* category
* [[Language#language_SYM.txt|symbol]]
| Causes the entity to not use the words in these SYM sets.
[CULL_SYMBOL:ALL:UGLY]

|-
| {{text anchor|FRIENDLY_COLOR}}
| see [[color]]
|
The color of this entity's civilization settlements in the world gen and embark screens, also used when announcing arrival of their caravan. Defaults to 7:0:1.

[FRIENDLY_COLOR:1:0:1]

|}

== Religion ==
{| {{prettytable}}
|- bgcolor="#ddd"
! Token
! Arguments
! Description

|-
| {{text anchor|RELIGION}}
| type
|
* REGIONAL_FORCE: The creatures will worship a single force associated with the terrain of their initial biome.
* PANTHEON: The creatures will worship a group of gods, each aligned with their spheres and other appropriate ones as well.

Can be specified multiple times, and will pick randomly from the assigned types. Additional instances of each type will weight the random choice, but unlike {{token|CREATURE|e}}, will not make the entity more likely to spawn.

[RELIGION:PANTHEON]

|-
| {{text anchor|RELIGION_SPHERE}}
| [[Sphere#Available_spheres|sphere]]
| Can be any available [[sphere]] - multiple entries are possible. Choosing a religious sphere will automatically make its opposing sphere not possible for the species to have: adding [[Sphere#WATER|WATER]], for example, means civs of this entity will never get [[Sphere#FIRE|FIRE]] as a religious sphere. Note that the [[Sphere#DEATH|DEATH]] sphere favours the appearance of necromancers (and therefore, towers) "in" the entity.

[RELIGION_SPHERE:FORTRESSES]

|-
| {{text anchor|SPHERE_ALIGNMENT}}
|
* [[Sphere#Available_spheres|sphere]]
* number
|
This token forces an entity to favor or disfavor particular religious spheres. Default is 256, minimum is 0, maximum is 25600.
* Presently, this doesn't cause them to acquire those spheres more often when generating a pantheon.
* [[Sphere#PLANTS|PLANTS]] and [[Sphere#ANIMALS|ANIMALS]] affect the prevalence of depicting {{token|VEGETATION}} and {{token|NATURAL}} creatures, respectively, in a similar fashion to {{token|ART_FACET_MODIFIER|e}}.
* [[Sphere#WAR|WAR]] modifies the effective [[item value]] of [[weapon]]s and [[armor]] to [[trader]]s of this entity. The multiplier is SPHERE_ALIGNMENT/256, though this only applies to equipment the entity's main creature can properly wield.

[SPHERE_ALIGNMENT:TREES:512]

|}

== Leadership ==
{| {{prettytable}}
|- bgcolor="#ddd"
! Token
! Arguments
! Description

|-
| {{text anchor|POSITION}}
| string
| Defines a leader/noble position for a civilization. These replace previous tags such as [MAYOR] and [CAN_HAVE_SITE_LEADER] and so on. To define a position further, see [[Position token]].

|-
| {{text anchor|SITE_VARIABLE_POSITIONS}}
| Position responsibility or ALL
| Allows a site responsibility to be taken up by a dynamically generated position (lords, hearthpersons, etc.). Any defined positions holding a given responsibility will take precedence over generated positions for that responsibility. Also appears to cause site disputes.{{Verify}} See also: [[variable positions]]

|-
| {{text anchor|VARIABLE_POSITIONS}}
| Position responsibility or ALL
| Allows a responsibility to be taken up by a dynamically generated position (such as Law-maker). Any defined positions holding a given responsibility will take precedence over generated positions for that responsibility. See also: [[variable positions]]

|}

== Behavior ==
{| {{prettytable}}
|- bgcolor="#ddd"
! Token
! Arguments
! Description

|-
| {{text anchor|ETHIC}}
|
*behavior
*reaction
| Sets the civ's view of [[ethic]]s (certain behaviors), from capital punishment to completely acceptable. This also causes the civ to look upon opposing ethics with disfavor if their reaction to it is opposing, and when at extremes (one ACCEPTABLE, another civ UNTHINKABLE; for example) they will often go to war over it.
[ETHIC:EAT_SAPIENT_KILL:ACCEPTABLE]

|-
| {{text anchor|VALUE}}
|
*value
*number
| Sets the civ's [[Personality value|cultural values]]. Numbers range from -50 (complete anathema) to 0 (neutral) to 50 (highly valued).
[VALUE:CRAFTSMANSHIP:50]

Certain values must be set to 15 or more for civs to create structures and form entities during history gen:
* 15+ KNOWLEDGE for libraries
* 15+ COOPERATION ''and'' 15+ CRAFTSMANSHIP for craft guilds
** Guilds also need guild-valid professions (see [[#PERMITTED_JOB|PERMITTED_JOB]])

If the positions of an entity are variable (and include the CUSTOM_OFFICIAL_1), then CUNNING > 10 is needed for the CUSTOM_OFFICIAL_1 to have the espionage responsibility.

|-
| {{text anchor|VARIABLE_VALUE}}
|
*value or ALL
*min
*max
| Makes values randomized rather than specified.
This tag overrides the VALUE tag. Using [VARIABLE_VALUE:ALL:x:y] and then overwriting single values with further [VARIABLE_VALUE:value:x:y] tags works.

|-
| {{text anchor|WILL_ACCEPT_TRIBUTE}}
|
| Makes the civ's traders accept offered goods.

|-
| {{text anchor|WANDERER}}, {{text anchor|BEAST_HUNTER}}, {{text anchor|SCOUT}}, {{text anchor|MERCENARY}}
|
| The civ will send out these sorts of adventurers in worldgen, which seems to increase Tracker skill. These types of adventurers will sometimes be seen leading a battle (instead of war leaders or generals) in remote locations during world-gen, in charge of the defenders.

Mercenaries and monster hunters from the civ may visit player's fortress and petition for residency there to enlist in the military or hunt monsters in caverns, respectively.

|-
| {{text anchor|ABUSE_BODIES}}
|
| The civilization will mutilate bodies when they are the victors in history-gen warfare, such as hanging bodies from trees, putting them on spikes, and so forth. Adventurers killed in Adventurer mode will sometimes be impaled on spikes wherever they died, with or without this token, and regardless of whether they actually antagonized the townspeople.

|-
| {{text anchor|ACTIVE_SEASON}}
| season
| The season when the civ is most active: when they will trade, interact with you via diplomats, and/or invade you. Civs can have multiple season entries. Note: If multiple caravans arrive at the same time, you are able to select which civ to trade with at the depot menu. ACTIVE_SEASON tags may be changed for a currently active fort.
[ACTIVE_SEASON:AUTUMN]

|-
| {{text anchor|AMBUSHER}}
|
| When invading, sneaks around and shoots at straggling members of your society. They will spawn on the edge of the map and will only be visible when one of their party are spotted; this can be quite dangerous to undefended trade depots. If the civilization also has the SIEGER token, they will eventually ramp it up to less subtle means of warfare.

|-
| {{text anchor|AT_PEACE_WITH_WILDLIFE}}
|
| Will not attack wildlife, and will not be attacked by them, even if you have them in your party. This can be somewhat disconcerting when attacked by bears in the forest, and your elven ally sits back and does nothing. Additionally, this token determines if the entity can settle in savage biomes.

|-
| {{text anchor|BABYSNATCHER}}
|
| Sends thieves to steal babies. Without this tag (or AMBUSHER, or ITEM_THIEF), enemy civs will only siege (if capable), and will siege as early as they would otherwise babysnatch. This can happen as early as the first year of the fort! In addition, babysnatcher civs will snatch children during worldgen, allowing them to become part of the civ if they do not escape. Also causes this civ to be hostile to any entity without this token.

Note: If the playable civ in fortress mode has this tag (e.g. you add BABYSNATCHER to the dwarf entity) then the roles will be reversed and elves and humans will siege and ambush and goblins will be friendly to you. However, animals traded away to one's own caravan will count as snatched, reported upon the animal leaving the map, and the animal will not count as having been exported.

|-
| {{text anchor|BUILDS_OUTDOOR_FORTIFICATIONS}}
|
| Makes the civilization build castles from [[mead hall]]s. Only functions when the type of site built is a hamlet/town. This, combined with the correct type of [[position token|position]] associated with a site, is why adventurers can only lay claim to human sites. {{bug|8001}}

|-
| {{text anchor|BUILDS_OUTDOOR_TOMBS}}
|
| Makes the civilization build tombs.

|-
| {{text anchor|BANDITRY}}
| percentage
| Sets a percentage of the entity population to be used as bandits.

|-
| {{text anchor|DIPLOMAT_BODYGUARDS}}
|
| Visiting diplomats are accompanied by a pair of soldiers.
|-
| {{text anchor|GENERATED}}
|
| Found on generated divine "HF Guardian Entities". Cannot be used in user-defined raws.

|-
| {{text anchor|INVADERS_IGNORE_NEUTRALS}}
|
| Causes invaders to ignore visiting caravans and other neutral creatures.{{verify}}

|-
| {{text anchor|ITEM_THIEF}}
|
| Sends thieves to steal items. This will also occur in history generation, and thieves will have the "thief" profession. Items stolen in history gen will be scattered around that creature's home. Also causes that civ to be hostile to any entity without this token. Without this tag (or AMBUSHER, or BABYSNATCHER), enemy civs will only siege (if capable), and will siege as early as they would otherwise steal.

Note: If the playable civ in Fortress Mode has this tag (e.g. you add ITEM_THIEF to the Dwarf entity) then the roles will be reversed and elves and humans will siege and ambush and kobolds will be friendly to you. However, ALL items traded away to one's own caravan will count as stolen, reported when the items leave the map, and the stolen items will not count as exported.

|-
| {{text anchor|LOCAL_BANDITRY}}
|
| Causes the entity to send out patrols that can ambush adventurers. Said patrols will be hostile to any adventurers they encounter, regardless of race or nationality.

|-
| {{text anchor|MERCHANT_BODYGUARDS}}
|
| Caravan merchants are accompanied by soldiers.

|-
| {{text anchor|MERCHANT_NOBILITY}}
|
| Merchants will engage in cross-civ trading and form companies.

In previous versions, this resulted in the civ having a Guild Representative / Merchant Baron / Merchant Prince, but now this is controlled solely by positions.

|-
| {{text anchor|PROGRESS_TRIGGER_POPULATION}}
| level
| 0 to 5, civ will come to site once population at site has reached that level. If multiple progress triggers exist for a civ, it will come when any one of them is fulfilled instead of waiting for all of them to be reached. A value of 0 disables the trigger. 1 corresponds to 20 dwarves, 2 to 50 dwarves, 3 to 80, 4 to 110, and 5 to 140. Progress triggers may be changed, added, or deleted for a currently active fort. Note: hostile civs require that this be fulfilled as well as at least one other non-siege trigger before visiting for non-siege activities.

|-
| {{text anchor|PROGRESS_TRIGGER_PRODUCTION}}
| level
| 0 to 5, civ will come to site once created wealth has reached that level. If multiple progress triggers exist for a civ, it will come when any one of them is fulfilled instead of waiting for all of them to be reached. A value of 0 disables the trigger. 1 corresponds to 5000☼ created wealth, 2 to 25000☼, 3 to 100000☼, 4 to 200000☼, and 5 to 300000☼. Progress triggers may be changed, added, or deleted for a currently active fort.

|-
| {{text anchor|PROGRESS_TRIGGER_TRADE}}
| level
| 0 to 5, civ will come to site once exported goods has reached that level. If multiple progress triggers exist for a civ, it will come when any one of them is fulfilled instead of waiting for all of them to be reached. A value of 0 disables the trigger. 1 corresponds to 500☼ exported wealth, 2 to 2500☼, 3 to 10000☼, 4 to 20000☼, and 5 to 30000☼. Progress triggers may be changed, added, or deleted for a currently active fort.

|-
| {{text anchor|PROGRESS_TRIGGER_POP_SIEGE}}
| level
| 0 to 5, civ will begin to send sieges against the player civ when this level is reached if it is hostile.

If multiple progress triggers exist for a civ, it will come when any one of them is fulfilled instead of waiting for all of them to be reached. A value of 0 disables the trigger.

|-
| {{text anchor|PROGRESS_TRIGGER_PROD_SIEGE}}
| level
| 0 to 5, civ will begin to send sieges against the player civ when this level is reached if it is hostile.

|-
| {{text anchor|PROGRESS_TRIGGER_TRADE_SIEGE}}
| level
| 0 to 5, civ will begin to send sieges against the player civ when this level is reached if it is hostile.

|-
| {{text anchor|SIEGER}}
|
| Will start campfires and wait around at the edge of your map for a month or two before rushing in to attack. This will occur when the progress triggers for sieging are reached. If the civ lacks smaller methods of conflict (AMBUSHER, BABYSNATCHER, ITEM_THIEF), they will instead send smaller-scale sieges when their triggers for "first contact" are reached.

|-
| {{text anchor|SIEGE_SKILLED_MINERS}}{{v|53.01}}
|
| Improves the skill of [[miner]] invaders by a factor of 5. Used for [[dwarves]] in vanilla.

|-
| {{text anchor|SITE_GUARDIAN}}
|
| Guards certain special sites, such as a [[vault]] belonging to a [[demon]] allied with a [[deity]]. Used in generated divine entities.

|-
| {{text anchor|SKULKING}}
|
| This makes the severity of attacks depend on the extent of item/baby thievery rather than the passage of time. Designed to go with ITEM_THIEF, may or may not work with BABYSNATCHER. Prevents the civ from engaging in diplomacy or ending up at war.

|-
| {{text anchor|TREE_CAP_DIPLOMACY}}
|
| Visiting diplomats impose tree cutting quotas; without this, they will simply compliment your fortress and leave. Also causes the diplomat to make unannounced first contact at the very beginning of the first spring after your fortress becomes a land holder.

|-
| {{text anchor|LAYER_LINKED}}
|
| Defines if a civilization is a hidden subterranean entity, such as [[bat man]] civilizations. May spawn in any of the three caverns; cavern dweller raids due to [[agitation]] will pull from these. If you embark as this civ, you have access to pets and trees from all three layers, not only the first.

|-
| {{text anchor|GENERATE_KEYBOARD_INSTRUMENTS}}, {{text anchor|GENERATE_PERCUSSION_INSTRUMENTS}}, {{text anchor|GENERATE_STRINGED_INSTRUMENTS}}, {{text anchor|GENERATE_WIND_INSTRUMENTS}}, {{text anchor|GENERATE_DANCE_FORMS}}, {{text anchor|GENERATE_MUSICAL_FORMS}}, {{text anchor|GENERATE_POETIC_FORMS}}
|
| Makes civilizations generate the given instruments/forms.

|-
| {{text anchor|SCHOLAR}}
| scholar type
| ALL, ASTRONOMER, CHEMIST, DOCTOR, ENGINEER, GEOGRAPHER, HISTORIAN, MATHEMATICIAN, NATURALIST, PHILOSOPHER

|-
| {{text anchor|SET_SCHOLARS_ON_VALUES_AND_JOBS}}
|
| Generates scholars based on the values generated with the VARIABLE_VALUE tag.

|-
| {{text anchor|NO_ARTIFACT_CLAIMS}}
|
| Used for kobolds.

|-
| {{text anchor|MINING_UNDERWORLD_DISASTERS}}
|
| The civilization can breach the [[Underworld]] during world generation, spawning a civilization of {{token|EVIL}} creatures lead by a unique [[demon]].

|-
| {{text anchor|MYTHICAL}}{{version|51.01-beta26}}
|
| Builds [[mysterious dungeon]]s.

|}

== Available resources ==
{| {{prettytable}}
|- bgcolor="#ddd"
! Token
! Arguments
! Description

|-
| {{text anchor|AMMO}}
| item token
| Used after a ranged weapon type.
[AMMO:ITEM_AMMO_BOLTS]

|-
| {{text anchor|ARMOR}}
|
* item token
* rarity
| Rarity is optional, and valid values are FORCED, COMMON, UNCOMMON, and RARE (anything else is treated as COMMON). FORCED items will be available 100% of the time, COMMON items 50%, UNCOMMON items 10%, and RARE items 1%. If certain armor types are lacking after performing one pass of randomised checks, the game will repeat random checks until an option is successfully chosen.
[ARMOR:ITEM_ARMOR_PLATEMAIL:COMMON]

|-
| {{text anchor|DIGGER}}
| item token
| Causes the selected weapon to fall under the "digging tools" section of the embark screen. Also forces the weapon to be made out of metal, which can cause issues if a modded entity has access to picks without access to metal - for those cases, listing the pick under the [WEAPON] token works just as well. Note that this tag is neither necessary nor sufficient to allow use of that item as a mining tool – for that, the item itself needs to be a weapon with {{token|SKILL|wp|MINING}}.
[DIGGER:ITEM_WEAPON_PICK]

|-
| {{text anchor|GLOVES}}
|
* item token
* rarity
| Rarity is optional, and valid values are FORCED, COMMON, UNCOMMON, and RARE (anything else is treated as COMMON). Uses the same rarity values and methods as outlined in ARMOR.
[GLOVES:ITEM_GLOVES_GLOVES:COMMON]

|-
| {{text anchor|HELM}}
|
* item token
* rarity
| Rarity is optional, and valid values are FORCED, COMMON, UNCOMMON, and RARE (anything else is treated as COMMON). Uses the same rarity values and methods as outlined in ARMOR.
[HELM:ITEM_HELM_HELM:COMMON]

|-
| {{text anchor|INSTRUMENT}}
| item token
| No longer used due to the ability to generate instruments in world generation. It is still usable if pre-defined instruments are modded in, and generated musical forms are capable of selecting pre-defined instruments to use. However, reactions for making instruments, instrument parts, and/or assembling such instruments need to be added as well, as this token no longer adds such instruments to the craftdwarf's workshop menu.
[INSTRUMENT:ITEM_INSTRUMENT_FLUTE]

|-
| {{text anchor|PANTS}}
|
* item token
* rarity
| Rarity is optional, and valid values are FORCED, COMMON, UNCOMMON, and RARE (anything else is treated as COMMON). Uses the same rarity values and methods as outlined in ARMOR.
[PANTS:ITEM_PANTS_PANTS:COMMON]

|-
| {{text anchor|SHIELD}}
| item token
|
[SHIELD:ITEM_SHIELD_SHIELD]

|-
| {{text anchor|SHOES}}
|
* item token
* rarity
| Rarity is optional, and valid values are FORCED, COMMON, UNCOMMON, and RARE (anything else is treated as COMMON). Uses the same rarity values and methods as outlined in ARMOR.
[SHOES:ITEM_SHOES_SHOES:COMMON]

|-
| {{text anchor|SIEGEAMMO}}
| item token
|
[SIEGEAMMO:ITEM_SIEGEAMMO_BALLISTA]

|-
| {{text anchor|TOOL}}
| item token
|
[TOOL:ITEM_TOOL_NEST_BOX]

|-
| {{text anchor|TOY}}
| item token
|
[TOY:ITEM_TOY_PUZZLEBOX]

|-
| {{text anchor|TRAPCOMP}}
| item token
|
[TRAPCOMP:ITEM_TRAPCOMP_GIANTAXEBLADE]

|-
| {{text anchor|WEAPON}}
| item token
| While this does not accept a rarity value, something similar can be achieved by having multiple variations of a weapon type with small differences and specifying each of them.{{cite forum|179547}}
[WEAPON:ITEM_WEAPON_AXE_BATTLE]

|-
| {{text anchor|USE_ANIMAL_PRODUCTS}}
|
| Allows use of products made from animals. All relevant creatures will be able to provide wool, silk, and extracts (including milk and venom) for trade, and non-sentient creatures (unless ethics state otherwise) will be able to provide eggs, caught fish, meat, leather, bone, shell, pearl, horn, and ivory.

|-
| {{text anchor|USE_ANY_PET_RACE}}
|
| Any creature in the civilization's list of usables (from the surrounding 7x7 or so of squares and map features in those squares) will be included in the initial usable creature list, which then gets pared down or otherwise considered. Without this, only common domestic and equipment creatures are added to the initial list.

|-
| {{text anchor|USE_CAVE_ANIMALS}}
|
| If they don't have it, creatures with exclusively subterranean biomes are skipped. If they have it, cave creatures will be included in the initial usable creature list.

|-
| {{text anchor|USE_EVIL_ANIMALS}}
|
| Without this, {{token|EVIL|c}} creatures are skipped, otherwise, evil creatures with {{token|SLOW_LEARNER|c}} or ''without'' {{token|CAN_LEARN|c}} will be included in the initial usable creature list, even the normally untameable species.

|-
| {{text anchor|USE_EVIL_PLANTS}}
|
| Same as USE_EVIL_ANIMALS for all uses of plants.

|-
| {{text anchor|USE_EVIL_WOOD}}
|
| Same as USE_EVIL_ANIMALS for all uses of wood.

|-
| {{text anchor|USE_GOOD_ANIMALS}}
|
| Without this, {{token|GOOD|c}} creatures are skipped, otherwise, good creatures ''without'' {{token|CAN_LEARN|c}} will be included in the initial usable creature list, even the normally untameable species.

|-
| {{text anchor|USE_GOOD_PLANTS}}
|
| Same as USE_GOOD_ANIMALS for all uses of plants.

|-
| {{text anchor|USE_GOOD_WOOD}}
|
| Same as USE_GOOD_ANIMALS for all uses of wood.

|-
| {{text anchor|USE_MISC_PROCESSED_WOOD_PRODUCTS}}
|
| If the relevant professions are permitted, controls availability of lye ({{token|LYE_MAKER|ut}}), charcoal ({{token|WOOD_BURNER|ut}}), and potash ({{token|POTASH_MAKER|ut}}).

|-
| {{text anchor|USE_NON_EXOTIC_PET_RACE}}
|
| Makes the civilization use all locally available non-exotic pets.

|-
| {{text anchor|COMMON_DOMESTIC_MOUNT}}
|
| Gives the civilization access to creatures with {{token|COMMON_DOMESTIC|c}} and {{token|MOUNT|c}}. Additionally, all available (based on USE_ANY_PET_RACE, USE_CAVE_ANIMALS, USE_GOOD_ANIMALS, and USE_EVIL_ANIMALS) creature with {{token|MOUNT|c}} and {{token|PET|c}} will be allowed for use as mounts during combat.

|-
| {{text anchor|COMMON_DOMESTIC_PACK}}
|
| Gives the civilization access to creatures with {{token|COMMON_DOMESTIC|c}} and {{token|PACK_ANIMAL.|c}} Additionally, all available (see above) creatures with {{token|PACK_ANIMAL|c}} and {{token|PET|c}} will be allowed for use during trade as pack animals.

|-
| {{text anchor|COMMON_DOMESTIC_PET}}
|
| Gives the civilization access to creatures with {{token|COMMON_DOMESTIC|c}} and {{token|PET|c}}. Additionally, all available (see above) creatures with {{token|PET|c}} will be allowed for use as pets.

|-
| {{text anchor|COMMON_DOMESTIC_PULL}}
|
| Gives the civilization access to creatures with {{token|COMMON_DOMESTIC|c}} and {{token|WAGON_PULLER|c}}. Additionally, all available (see above) creatures with {{token|WAGON_PULLER|c}} and {{token|PET|c}} will be allowed for use during trade to pull [[wagon]]s.

|-
| {{text anchor|RIVER_PRODUCTS}}
|
| Allow use of river products in the goods available for trade.

|-
| {{text anchor|OCEAN_PRODUCTS}}
|
| Allow use of ocean products (including [[amber]] and [[coral]]) in the goods available for trade. Without OCEAN_PRODUCTS, civilizations will not be able to trade ocean fish even if they are ''also'' available from other sources (e.g. [[sturgeon]]s and [[stingray]]s).

|-
| {{text anchor|INDOOR_FARMING}}
|
| Allow use of underground plant products in the goods available for trade. Lack of suitable vegetation in the caverns will cause [[World generation#Rejections|worldgen rejection]]s. According to Droseran: "Gives access to plants (structural material) and seeds. It only checks for {{token|EDIBLE_RAW|md}} or {{token|EDIBLE_COOKED|md}} on the plant's structural material. It doesn't check if the plant can be used in a reaction to produce something edible, only if it can be eaten raw or cooked. If an entity with this token is placed in a biome that doesn't have at least one of these tokens on the structural material, the map is rejected. Due to the randomness of plant selection in biomes, this can happen a lot as only about half of the vanilla plants have edible structural materials. Removing either of these tokens from plants dramatically increases map rejections."

|-
| {{text anchor|OUTDOOR_FARMING}}
|
| Allow use of outdoor plant products in the goods available for trade. Lack of suitable vegetation in this civilization's starting area will cause [[World generation#Rejections|worldgen rejection]]s. According to Droseran: "Gives access to plants (structural material) and seeds. It only checks for {{token|EDIBLE_RAW|md}} or {{token|EDIBLE_COOKED|md}} on the plant's structural material. It doesn't check if the plant can be used in a reaction to produce something edible, only if it can be eaten raw or cooked. If an entity with this token is placed in a biome that doesn't have at least one of these tokens on the structural material, the map is rejected. Due to the randomness of plant selection in biomes, this can happen a lot as only about half of the vanilla plants have edible structural materials. Removing either of these tokens from plants dramatically increases map rejections."

|-
| {{text anchor|INDOOR_GARDENS}}
|
| Allow use of underground plant growths (quarry bush leaves, in unmodded games) in the goods available for trade. According to Droseran: "Will never cause map rejections. It allows growths to be used, but doesn't care if none exist. If an entity doesn't have a farming token, they won't have seeds or plants available on embark/trade. But you can still farm in fortress mode with only this token, you just have to get the seeds manually or trading with another civ."

|-
| {{text anchor|OUTDOOR_GARDENS}}
|
| Allow use of outdoor plant growths in the goods available for trade. According to Droseran: "Will never cause map rejections. It allows growths to be used, but doesn't care if none exist. If an entity doesn't have a farming token, they won't have seeds or plants available on embark/trade. But you can still farm in fortress mode with only this token, you just have to get the seeds manually or trading with another civ."

|-
| {{text anchor|INDOOR_ORCHARDS}}
|
| Allows use of indoor tree growths in the goods available for trade. Not used in vanilla entities, as vanilla underground trees do not grow fruit. Needs INDOOR_WOOD to function. Will cause rejections, if growths are unavailable. According to Droseran: "Gives access to tree growths. It only checks for growths on trees that are {{token|EDIBLE_RAW|md}} or {{token|EDIBLE_COOKED|md}}. If an entity with this token is placed in a biome that does not have a tree with a growth with at least one of these tokens, the map is rejected."

|-
| {{text anchor|OUTDOOR_ORCHARDS}}
|
| Allows use of outdoor tree growths in the goods available for trade. Needs OUTDOOR_WOOD to function{{verify}}. According to Droseran: "Gives access to tree growths. It only checks for growths on trees that are [EDIBLE_RAW] or [EDIBLE_COOKED]. If an entity with this token is placed in a biome that does not have a tree with a growth with at least one of these tokens, the map is rejected."

|-
| {{text anchor|CLOTHING}}
|
| Civilization members will attempt to wear clothing.

|-
| {{text anchor|SUBTERRANEAN_CLOTHING}}
|
| Will wear things made of spider silk and other subterranean materials.

|-
| {{text anchor|EQUIPMENT_IMPROVEMENTS}}
|
| Adds decorations to equipment based on the level of the generated unit. Also improves item quality.

|-
| {{text anchor|IMPROVED_BOWS}}
|
| Adds decorations to weapons generated for bowman and master bowman.

|-
| {{text anchor|METAL_PREF}}
|
| Allows metal materials to be used to make cages (inexpensive metals only) and crafts.

|-
| {{text anchor|STONE_PREF}}
|
| Allows the civilization to make use of nearby stone types. If the {{token|FURNACE_OPERATOR|ut}} job is permitted, also allows ore-bearing stones to be smelted into metals.

|-
| {{text anchor|WOOD_WEAPONS}}
|
| The civilization can make traditionally metallic weapons such as swords and spears from wood.

|-
| {{text anchor|WOOD_ARMOR}}
|
| The civilization can make traditionally metallic armor such as mail shirts and helmets from wood.

|-
| {{text anchor|GEM_PREF}}
|
| Enables creatures of this entity to bring gems in trade.

|-
| {{text anchor|INDOOR_WOOD}}
|
| Allow use of subterranean wood types, such as tower-cap and fungiwood logs.

|-
| {{text anchor|OUTDOOR_WOOD}}
|
| Allow use of outdoor wood types, such as mangrove and oak.

|-
| {{text anchor|GEM_SHAPE}}
| [[Descriptor shape token|shape]]
| Precious gems cut by this civilization's jewelers can be of this shape.

|-
| {{text anchor|STONE_SHAPE}}
| [[Descriptor shape token|shape]]
| Ordinary non-gem stones cut by this civilization's jewelers can be of this shape.

|-
| {{text anchor|DIVINE_MAT_CLOTHING}}
|
| Allows use of materials with {{token|DIVINE|im}} for clothing. Used for generated divine entities.

|-
| {{text anchor|DIVINE_MAT_CRAFTS}}
|
| Allows use of materials with {{token|DIVINE|im}} for crafts.{{verify}} Used for generated divine entities.

|-
| {{text anchor|DIVINE_MAT_WEAPONS}}
|
| Allows use of metals with {{token|DIVINE|im}} for weapons. Used for generated divine entities.

|-
| {{text anchor|DIVINE_MAT_ARMOR}}
|
| Allows use of metals with {{token|DIVINE|im}} for armor. Used for generated divine entities.
|}

== Animal definitions ==

{| {{prettytable}}
|- bgcolor="#ddd"
! Token
! Arguments
! Description

|-
| {{text anchor|ANIMAL}}
|
| Start an animal definition.

|-
| {{text anchor|ANIMAL_TOKEN}}
| [[creature token]]
| Select specific creature.

|-
| {{text anchor|ANIMAL_CASTE_TOKEN}}
| [[Caste|creature caste token]]
| Select specific creature caste (requires ANIMAL_TOKEN). Sites with animal populations will still include all castes, but only the selected ones will be used for specific roles.

|-
| {{text anchor|ANIMAL_CLASS}}
| [[Creature token#CREATURE_CLASS|creature class]]
| Select creature castes with this creature class (multiple uses allowed).

|-
| {{text anchor|ANIMAL_FORBIDDEN_CLASS}}
| [[Creature token#CREATURE_CLASS|creature class]]
| Forbid creature castes with this creature class (multiple uses allowed).

|-
| {{text anchor|ANIMAL_ALWAYS_PRESENT}}
|
| Animal will be present even if it does not naturally occur in the entity's terrain. All creatures, including [[demon]]s, night trolls and other generated ones will be used if no specific creature or class is selected.

|-
|
* {{text anchor|ANIMAL_NEVER_MOUNT}}, {{text anchor|ANIMAL_ALWAYS_MOUNT}}
* {{text anchor|ANIMAL_NEVER_WAGON_PULLER}}, {{text anchor|ANIMAL_ALWAYS_WAGON_PULLER}}
* {{text anchor|ANIMAL_NEVER_SIEGE}}, {{text anchor|ANIMAL_ALWAYS_SIEGE}}
* {{text anchor|ANIMAL_NEVER_PET}}, {{text anchor|ANIMAL_ALWAYS_PET}}
* {{text anchor|ANIMAL_NEVER_PACK_ANIMAL}}, {{text anchor|ANIMAL_ALWAYS_PACK_ANIMAL}}
|
| Override creature usage tokens. Respectively:
* [[Creature token#MOUNT|MOUNT]] and [[Creature token#MOUNT_EXOTIC|MOUNT_EXOTIC]]
* [[Creature token#WAGON_PULLER|WAGON_PULLER]]
* [[Creature token#TRAINABLE_WAR|TRAINABLE_WAR]] and not [[Creature token#CAN_LEARN|CAN_LEARN]]
* [[Creature token#PET|PET]] and [[Creature token#PET_EXOTIC|PET_EXOTIC]]
* [[Creature token#PACK_ANIMAL|PACK_ANIMAL]]
ALWAYS overrides NEVER if a caste is matched by more than one animal definition.

|}

== Tissue styling-related tokens ==
{| {{prettytable}}
|- bgcolor="#ddd"
! Token
! Arguments
! Description

|-
| {{text anchor|TISSUE_STYLE}}
| tissue style unit ID
| Select a tissue layer which has the ID attached using TISSUE_STYLE_UNIT token in unit raws. This allows setting further cultural style parameters for the selected tissue layer.

|-
| {{text anchor|TS_MAINTAIN_LENGTH}}
|
* minimum length?
* maximum length?
| Presumably sets culturally preferred tissue length for selected tissue. Needs testing.
Dwarves have their beards set to 100:NONE by default.

|-
| {{text anchor|TS_PREFERRED_SHAPING}}
| styling token
| Valid tokens are NEATLY_COMBED, BRAIDED, DOUBLE_BRAIDS, PONY_TAILS, CLEAN_SHAVEN and STANDARD_HAIR/BEARD/MOUSTACHE/SIDEBURNS_SHAPINGS.
Presumably sets culturally preferred tissue shapings for selected tissue. Needs testing.

|}

== Examples ==
:''Main articles: [[Entity examples]]''

{{Category|Modding}}
{{Category|Tokens}}
{{Category|Entities}}
[[ru:Entity token]]

Talk:Advanced entity position mechanics

2026-04-03T08:57:26Z

Joostheger: /* Possible vanilla Dwarven Civ landholder residence sites */

Entity token

2026-03-25T14:00:01Z

Joostheger: /* Population */

{{Quality|Superior}}
{{av}}
{{Modding}}
'''Entity tokens''' define entities, or [[civilization]]s, in entity_*.txt files.

The <code>[OBJECT:ENTITY]</code> [[token]] begins the definition of an entity [[raw file]]. Each new entity definition that follows begins with the <code>[ENTITY:''entity_ID'']</code> token, where ''entity_ID'' is a unique identifier for that entity, and the entity's properties are then specified by the use of further entity tokens; or, tokens can be added to existing entities using <code>[SELECT_ENTITY:''entity_ID'']</code> instead.

All known entity tokens are listed below.

__TOC__
{{clear}}

== Gameplay ==
{| {{prettytable}}
|- bgcolor="#ddd"
! Token
! Arguments
! Description

|-
| {{text anchor|ALL_MAIN_POPS_CONTROLLABLE}}
|
| Allows adventure mode for entities with sites.

|-
| {{text anchor|SITE_CONTROLLABLE}}
|
| Allows fortress mode. If multiple entities have the SITE_CONTROLLABLE token, then at embark the specific civs can be chosen on the civ list screen. At least one civilization must have this token.

|-
| {{text anchor|CREATURE}}
| creature
|The type of creature that will inhabit the civilization. If multiple creature types are specified, each civilization will randomly choose one of the creatures. In entities with multiple possible creatures, you can manipulate the chance of one creature being chosen by adding multiple identical creature tags. For instance adding [CREATURE:DWARF][CREATURE:DWARF][CREATURE:DWARF][CREATURE:ELF] to the same entity will make the civs created about 75% dwarven, 25% elven. It should be noted that civilizations are in general weighted by this token: for example, if you have one entity with three [CREATURE:DWARF] tokens and another separate entity with a single [CREATURE:ELF] token, then you can expect to see three times as many of the former placed as the latter (assuming enough unclaimed [START_BIOME:X] space remains). Note that spawn rates are also limited by unclaimed biome space - if an entity can only spawn in a rarer set of biomes (only LAKE_TROPICAL_SALTWATER for example) then their spawn rate will end up being limited by the remaining unclaimed space in that biome type rather than the number of [CREATURE:X] tokens present in the entity raw.
|-
| {{text anchor|SOURCE_HFID}}
| integer
| Found on generated [[angel]] entities. Appears to draw from creatures with this HFID, which associates the entity with a historical figure of the same ID corresponding to a [[deity]].

|}

== Placement ==

Entity spawning during world gen is influenced by several factors:
* The "[[Advanced world generation#Number of Civilizations|Number of Civilizations]]" world gen setting places a hard limit on the total number of entities spawned.
* The "[[Advanced world generation#Playable Civilization Required|Playable Civilization Required]]" world gen setting forces at least one of each [[Entity token#SITE_CONTROLLABLE|SITE_CONTROLLABLE]] entity to spawn (presumably still limited by "Number of Civilizations").
* The number of <nowiki>[</nowiki>[[Entity token#CREATURE|CREATURE]]:X] tokens present in an entity modifies its chance of spawning. An entity containing more <nowiki>[</nowiki>[[Entity token#CREATURE|CREATURE]]:X] tokens will spawn more often (assuming other requirements are met) and may even block entities with fewer <nowiki>[</nowiki>[[Entity token#CREATURE|CREATURE]]:X] tokens from spawning altogether. You can use [SELECT_ENTITY:VANILLA_ENTITY_X] followed by any number of duplicate <nowiki>[</nowiki>[[Entity token#CREATURE|CREATURE]]:VANILLA_CREATURE_X] tokens to attempt to balance the spawn rates of the existing vanilla entities with any custom multi-creature entities you may add.
* The number of unclaimed [[Entity token#START_BIOME|START_BIOME]] or [[Entity token#EXCLUSIVE_START_BIOME|EXCLUSIVE_START_BIOME]] tiles remaining in the world limits the spawn rate for an entity and allows entities to block each other's spawns. If there is no "starting" [[Biome token|biome]] space left for an entity then it will not spawn and the game will try to spawn a different entity instead. This means that, on average, an entity that can start in ALL_MAIN [[Biome token|biomes]] will spawn more frequently than one that can start only in LAKE_TROPICAL_SALTWATER [[Biome token|biomes]]. This also means that entities whose starting [[Biome token|biomes]] do not overlap will not block each other's spawns.

{| {{prettytable}}
|- bgcolor="#ddd"
! Token
! Arguments
! Description

|-
| {{text anchor|BIOME_SUPPORT}}
|
* [[Biome token|biome]]
* frequency
| Controls the expansion of the civilization's territory. The higher the number is relative to other BIOME_SUPPORT tokens in the entity, the faster it can spread through the biome. These numbers are evaluated relative to each other, i.e. if one biome is 1 and the other is 2, the spread will be the same as if one was 100 and the other was 200. Civs can spread out over biomes they cannot actually build in; for example, humans spread quickly over oceans but cannot actually build in them.
[BIOME_SUPPORT:ANY_GRASSLAND:4]

|-
| {{text anchor|SETTLEMENT_BIOME}}
| [[Biome token|biome]]
| If the civ's territory crosses over this biome, it can build settlements here.
[SETTLEMENT_BIOME:ANY_GRASSLAND]

|-
| {{text anchor|START_BIOME}}
| [[Biome token|biome]]
| Combination of EXCLUSIVE_START_BIOME and SETTLEMENT_BIOME; allows the civ to start in and create settlements in the biome. Note that the civ's spawn rate may be limited if all of its START or EXCLUSIVE_START biome(s) are rare in the world or have already been fully occupied by other civ spawns.
[START_BIOME:ANY_FOREST]

|-
| {{text anchor|EXCLUSIVE_START_BIOME}}
| [[Biome token|biome]]
| The birth of the civilization can occur in this biome, but cannot (necessarily) build in it. If the civ does not have SETTLEMENT_BIOME or START_BIOME for the biome in question, it will only construct a single settlement there. Note that the civ's spawn rate may be limited if all of its START or EXCLUSIVE_START biome(s) are rare in the world or have already been fully occupied by other civ spawns.
[EXCLUSIVE_START_BIOME:MOUNTAIN]

|-
| {{text anchor|DEFAULT_SITE_TYPE}}
| site type
| Valid site types are DARK_FORTRESS (π), CAVE (•), CAVE_DETAILED (Ω), TREE_CITY (î), and CITY (#). Also recognizes PLAYER_FORTRESS (creates a civ of hillocks only), and MONUMENT (creates a civ without visible sites (except tombs and castles), but may cause worldgen crashes). FORTRESS is no longer a valid entry, castles are currently controlled by BUILDS_OUTDOOR_FORTIFICATIONS. Defaults to CITY. Selecting CAVE causes the classic kobold behavior of not showing up on the "neighbors" section of the site selection screen.
Selecting DARK_FORTRESS also allows generation of [[underworld spire|certain other structures]]. It also gives the civ a [[demon|special overlord]]. DARK_FORTRESS may cause crashes during world gen at "Placing civilizations... (0)" if it combined with entity tokens that the vanilla ENTITY:EVIL does not use (likely the POSITION related tokens see [https://www.bay12forums.com/smf/index.php?topic=175747.0 this forum post]).
CAVE_DETAILED civilizations will create fortresses in mountainous regions and hillocks in non-mountainous regions. [DEFAULT_SITE_TYPE:CAVE_DETAILED]

|-
| {{text anchor|LIKES_SITE}}
| site type
| Most residents will try to move to this site type, unless already at one.
[LIKES_SITE:CAVE_DETAILED]

|-
| {{text anchor|TOLERATES_SITE}}
| site type
| Some residents will try to move to this site type, unless already at one.
[TOLERATES_SITE:CITY]

|-
| {{text anchor|WORLD_CONSTRUCTION}}
| construction
| Controls which constructions the civ will build on the world map. Valid constructions are ROAD, TUNNEL, BRIDGE, and WALL.
[WORLD_CONSTRUCTION:BRIDGE]
[WORLD_CONSTRUCTION:ROAD]
[WORLD_CONSTRUCTION:TUNNEL]
[WORLD_CONSTRUCTION:WALL]

|}

== Population ==

{| {{prettytable}}
|- bgcolor="#ddd"
! Token
! Arguments
! Description

|-
| {{text anchor|MAX_POP_NUMBER}}
| number
| Max '''historical''' population '''per entity'''. Multiply this by max starting civ to get the total maximum historical population of the species. Defaults to 500, but all vanilla entities use 10,000, except skulking uses 2,000. Does not limit the '''total''' population, but it will prevent new settlements upon reaching the number.
[MAX_POP_NUMBER:10000]

|-
| {{text anchor|MAX_SITE_POP_NUMBER}}
| number
| Max historical population per individual site. Defaults to 50, but all the vanilla entities use 120.
[MAX_SITE_POP_NUMBER:120]

|-
| {{text anchor|MAX_STARTING_CIV_NUMBER}}
| number
| Max number of civilizations of this entity type to spawn at world generation, which picks entities in some sequential order from the raws, looping through the list as needed. This is a hard limit, if set to 1, only 1 civilization of this type will be placed. If all entities have reached their limit, world generation will not try to place any more, even if its own [[Advanced_world_generation#Number_of_Civilizations|total limit]] has not been reached, and will continue on. Defaults to 3, but all vanilla entities use 100 (essentially unlimited).
[MAX_STARTING_CIV_NUMBER:100]

|}

== Flavor ==
{| {{prettytable}}
|- bgcolor="#ddd"
! Token
! Arguments
! Description

|-
| {{text anchor|PERMITTED_BUILDING}}
| building name
| The named, custom building can be built by a civilization in Fortress Mode.
[PERMITTED_BUILDING:SOAP_MAKER]

|-
| {{text anchor|PERMITTED_JOB}}
| [[Unit type token|profession]]
| Allows this job type to be selected. This applies to worldgen creatures, in the embark screen, and in play. Certain professions also influence the availability of materials for trade.
[PERMITTED_JOB:MINER]

|-
| {{text anchor|PERMITTED_REACTION}}
| reaction name
| Allows this reaction to be used by a civilization. It is used primarily in Fortress Mode, but also allows certain resources, such as [[steel]], to be available to a race. When creating custom reactions, this token '''must''' be present or the player will not be able to use the reaction in Fortress Mode.
[PERMITTED_REACTION:TAN_A_HIDE]

|-
| {{text anchor|CURRENCY_BY_YEAR}}
|
| Causes the civ's currency to be numbered with the year it was minted.

|-
| {{text anchor|CURRENCY}}
|
* inorganic material
* value
| What kind of metals the civ uses for coin minting, as well as the value of the [[coin]]. Only effective in Adventurer mode due to lack of [[dwarven economy]].

[CURRENCY:SILVER:5]

|-
| {{text anchor|ART_FACET_MODIFIER}}
|
* type
* number
| OWN_RACE, FANCIFUL, EVIL, GOOD
Number goes from 0 to 25600 where 256 is the default.
[ART_FACET_MODIFIER:OWN_RACE:512]

|-
| {{text anchor|ART_IMAGE_ELEMENT_MODIFIER}}
|
* item
* number
| CREATURE, PLANT, TREE, SHAPE, ITEM 0-25600

Determines the chance of each image occurring in that entity's artwork, such as engravings and on artifacts, for default (non-historical) artwork.

[ART_IMAGE_ELEMENT_MODIFIER:TREE:512]

|-
| {{text anchor|ITEM_IMPROVEMENT_MODIFIER}}
|
* item
* number
| ART_IMAGE, COVERED or GLAZED, RINGS_HANGING, BANDS, SPIKES, ITEMSPECIFIC, THREAD, CLOTH, SEWN_IMAGE 0-25600

Determines the chance of the entity using that particular artwork method, such as "encircled with bands" or "menaces with spikes".

[ITEM_IMPROVEMENT_MODIFIER:SPIKES:0]

This also seems to change the amount that the entity will pay for items that are improved in these ways in their tokens.

|-
| {{text anchor|TRANSLATION}}
| language
| What language raw the entity uses.
* If an entity lacks this tag, translations are drawn randomly from all translation files. Multiple translation tags will only result in the last one being used. Migrants will sometimes arrive with no name.
* If GEN_DIVINE is entered, the entity will use a generated divine language, that is, the same language that is used for the names of [[angel]]s.
* If the entity's main creature has {{token|UTTERANCES|c}}, then this token will be ignored (except when using the naming menu) in favor of procedural [[kobold]]-style [[Kobold language|pseudolanguage]].
[TRANSLATION:DWARF]

|-
| {{text anchor|SELECT_SYMBOL}}
|
* category
* [[language#language_SYM.txt|symbol]]
| ALL, REMAINING, BATTLE, BRIDGE, CIV, CRAFT_GUILD, FESTIVAL (doesn't work, see below), HOSPITAL, LIBRARY, MERCHANT_COMPANY, MILITARY_UNIT, OTHER, RELIGION, ROAD, SIEGE, SITE, TEMPLE, TUNNEL, VESSEL, WALL, WAR
The entity will always use a word from the selected symbol(s) to generate names from that category.
* OTHER applies the symbol selection to personal names and site names. REMAINING will apply the symbol selection to all categories that have not already been declared above it.
* Specific to SELECT_SYMBOL, symbols selected this way will be used as "The X" in "The X of Y" names, and nouns from selected symbols can be used as first [[name]]s.
* FESTIVAL does not work. The game uses symbol NAME_FESTIVAL hardcoded. You may consider changing that symbol (with SELECT_SYMBOL), but then it's applied for all entities.

[SELECT_SYMBOL:ALL:PEACE]

|-
| {{text anchor|SUBSELECT_SYMBOL}}
|
* category
* [[language#language_SYM.txt|symbol]]
| As SELECT_SYMBOL, a word from the subselected symbol(s) will be used in names of that category, in addition to the word from SELECT_SYMBOL (if specified). Used in vanilla to put violent names in sieges and battles.
* Words chosen with SUBSELECT_SYMBOL will appear as either adjectives or "of Y" in "The X of Y" names.
* CULL_SYMBOL does not affect subselected symbols.

[SELECT_SYMBOL:SIEGE:NAME_SIEGE]

[SUBSELECT_SYMBOL:SIEGE:VIOLENT]

|-
| {{text anchor|CULL_SYMBOL}}
|
* category
* [[Language#language_SYM.txt|symbol]]
| Causes the entity to not use the words in these SYM sets.
[CULL_SYMBOL:ALL:UGLY]

|-
| {{text anchor|FRIENDLY_COLOR}}
| see [[color]]
|
The color of this entity's civilization settlements in the world gen and embark screens, also used when announcing arrival of their caravan. Defaults to 7:0:1.

[FRIENDLY_COLOR:1:0:1]

|}

== Religion ==
{| {{prettytable}}
|- bgcolor="#ddd"
! Token
! Arguments
! Description

|-
| {{text anchor|RELIGION}}
| type
|
* REGIONAL_FORCE: The creatures will worship a single force associated with the terrain of their initial biome.
* PANTHEON: The creatures will worship a group of gods, each aligned with their spheres and other appropriate ones as well.

Can be specified multiple times, and will pick randomly from the assigned types. Additional instances of each type will weight the random choice, but unlike {{token|CREATURE|e}}, will not make the entity more likely to spawn.

[RELIGION:PANTHEON]

|-
| {{text anchor|RELIGION_SPHERE}}
| [[Sphere#Available_spheres|sphere]]
| Can be any available [[sphere]] - multiple entries are possible. Choosing a religious sphere will automatically make its opposing sphere not possible for the species to have: adding [[Sphere#WATER|WATER]], for example, means civs of this entity will never get [[Sphere#FIRE|FIRE]] as a religious sphere. Note that the [[Sphere#DEATH|DEATH]] sphere favours the appearance of necromancers (and therefore, towers) "in" the entity.

[RELIGION_SPHERE:FORTRESSES]

|-
| {{text anchor|SPHERE_ALIGNMENT}}
|
* [[Sphere#Available_spheres|sphere]]
* number
|
This token forces an entity to favor or disfavor particular religious spheres. Default is 256, minimum is 0, maximum is 25600.
* Presently, this doesn't cause them to acquire those spheres more often when generating a pantheon.
* [[Sphere#PLANTS|PLANTS]] and [[Sphere#ANIMALS|ANIMALS]] affect the prevalence of depicting {{token|VEGETATION}} and {{token|NATURAL}} creatures, respectively, in a similar fashion to {{token|ART_FACET_MODIFIER|e}}.
* [[Sphere#WAR|WAR]] modifies the effective [[item value]] of [[weapon]]s and [[armor]] to [[trader]]s of this entity. The multiplier is SPHERE_ALIGNMENT/256, though this only applies to equipment the entity's main creature can properly wield.

[SPHERE_ALIGNMENT:TREES:512]

|}

== Leadership ==
{| {{prettytable}}
|- bgcolor="#ddd"
! Token
! Arguments
! Description

|-
| {{text anchor|POSITION}}
| string
| Defines a leader/noble position for a civilization. These replace previous tags such as [MAYOR] and [CAN_HAVE_SITE_LEADER] and so on. To define a position further, see [[Position token]].

|-
| {{text anchor|SITE_VARIABLE_POSITIONS}}
| Position responsibility or ALL
| Allows a site responsibility to be taken up by a dynamically generated position (lords, hearthpersons, etc.). Any defined positions holding a given responsibility will take precedence over generated positions for that responsibility. Also appears to cause site disputes.{{Verify}} See also: [[variable positions]]

|-
| {{text anchor|VARIABLE_POSITIONS}}
| Position responsibility or ALL
| Allows a responsibility to be taken up by a dynamically generated position (such as Law-maker). Any defined positions holding a given responsibility will take precedence over generated positions for that responsibility. See also: [[variable positions]]

|}

== Behavior ==
{| {{prettytable}}
|- bgcolor="#ddd"
! Token
! Arguments
! Description

|-
| {{text anchor|ETHIC}}
|
*behavior
*reaction
| Sets the civ's view of [[ethic]]s (certain behaviors), from capital punishment to completely acceptable. This also causes the civ to look upon opposing ethics with disfavor if their reaction to it is opposing, and when at extremes (one ACCEPTABLE, another civ UNTHINKABLE; for example) they will often go to war over it.
[ETHIC:EAT_SAPIENT_KILL:ACCEPTABLE]

|-
| {{text anchor|VALUE}}
|
*value
*number
| Sets the civ's [[Personality value|cultural values]]. Numbers range from -50 (complete anathema) to 0 (neutral) to 50 (highly valued).
[VALUE:CRAFTSMANSHIP:50]

Certain values must be set to 15 or more for civs to create structures and form entities during history gen:
* 15+ KNOWLEDGE for libraries
* 15+ COOPERATION ''and'' 15+ CRAFTSMANSHIP for craft guilds
** Guilds also need guild-valid professions (see [[#PERMITTED_JOB|PERMITTED_JOB]])

If the positions of an entity are variable (and include the CUSTOM_OFFICIAL_1), then CUNNING > 10 is needed for the CUSTOM_OFFICIAL_1 to have the espionage responsibility.

|-
| {{text anchor|VARIABLE_VALUE}}
|
*value or ALL
*min
*max
| Makes values randomized rather than specified.
This tag overrides the VALUE tag. Using [VARIABLE_VALUE:ALL:x:y] and then overwriting single values with further [VARIABLE_VALUE:value:x:y] tags works.

|-
| {{text anchor|WILL_ACCEPT_TRIBUTE}}
|
| Makes the civ's traders accept offered goods.

|-
| {{text anchor|WANDERER}}, {{text anchor|BEAST_HUNTER}}, {{text anchor|SCOUT}}, {{text anchor|MERCENARY}}
|
| The civ will send out these sorts of adventurers in worldgen, which seems to increase Tracker skill. These types of adventurers will sometimes be seen leading a battle (instead of war leaders or generals) in remote locations during world-gen, in charge of the defenders.

Mercenaries and monster hunters from the civ may visit player's fortress and petition for residency there to enlist in the military or hunt monsters in caverns, respectively.

|-
| {{text anchor|ABUSE_BODIES}}
|
| The civilization will mutilate bodies when they are the victors in history-gen warfare, such as hanging bodies from trees, putting them on spikes, and so forth. Adventurers killed in Adventurer mode will sometimes be impaled on spikes wherever they died, with or without this token, and regardless of whether they actually antagonized the townspeople.

|-
| {{text anchor|ACTIVE_SEASON}}
| season
| The season when the civ is most active: when they will trade, interact with you via diplomats, and/or invade you. Civs can have multiple season entries. Note: If multiple caravans arrive at the same time, you are able to select which civ to trade with at the depot menu. ACTIVE_SEASON tags may be changed for a currently active fort.
[ACTIVE_SEASON:AUTUMN]

|-
| {{text anchor|AMBUSHER}}
|
| When invading, sneaks around and shoots at straggling members of your society. They will spawn on the edge of the map and will only be visible when one of their party are spotted; this can be quite dangerous to undefended trade depots. If the civilization also has the SIEGER token, they will eventually ramp it up to less subtle means of warfare.

|-
| {{text anchor|AT_PEACE_WITH_WILDLIFE}}
|
| Will not attack wildlife, and will not be attacked by them, even if you have them in your party. This can be somewhat disconcerting when attacked by bears in the forest, and your elven ally sits back and does nothing. Additionally, this token determines if the entity can settle in savage biomes.

|-
| {{text anchor|BABYSNATCHER}}
|
| Sends thieves to steal babies. Without this tag (or AMBUSHER, or ITEM_THIEF), enemy civs will only siege (if capable), and will siege as early as they would otherwise babysnatch. This can happen as early as the first year of the fort! In addition, babysnatcher civs will snatch children during worldgen, allowing them to become part of the civ if they do not escape. Also causes this civ to be hostile to any entity without this token.

Note: If the playable civ in fortress mode has this tag (e.g. you add BABYSNATCHER to the dwarf entity) then the roles will be reversed and elves and humans will siege and ambush and goblins will be friendly to you. However, animals traded away to one's own caravan will count as snatched, reported upon the animal leaving the map, and the animal will not count as having been exported.

|-
| {{text anchor|BUILDS_OUTDOOR_FORTIFICATIONS}}
|
| Makes the civilization build castles from [[mead hall]]s. Only functions when the type of site built is a hamlet/town. This, combined with the correct type of [[position token|position]] associated with a site, is why adventurers can only lay claim to human sites. {{bug|8001}}

|-
| {{text anchor|BUILDS_OUTDOOR_TOMBS}}
|
| Makes the civilization build tombs.

|-
| {{text anchor|BANDITRY}}
| percentage
| Sets a percentage of the entity population to be used as bandits.

|-
| {{text anchor|DIPLOMAT_BODYGUARDS}}
|
| Visiting diplomats are accompanied by a pair of soldiers.
|-
| {{text anchor|GENERATED}}
|
| Found on generated divine "HF Guardian Entities". Cannot be used in user-defined raws.

|-
| {{text anchor|INVADERS_IGNORE_NEUTRALS}}
|
| Causes invaders to ignore visiting caravans and other neutral creatures.{{verify}}

|-
| {{text anchor|ITEM_THIEF}}
|
| Sends thieves to steal items. This will also occur in history generation, and thieves will have the "thief" profession. Items stolen in history gen will be scattered around that creature's home. Also causes that civ to be hostile to any entity without this token. Without this tag (or AMBUSHER, or BABYSNATCHER), enemy civs will only siege (if capable), and will siege as early as they would otherwise steal.

Note: If the playable civ in Fortress Mode has this tag (e.g. you add ITEM_THIEF to the Dwarf entity) then the roles will be reversed and elves and humans will siege and ambush and kobolds will be friendly to you. However, ALL items traded away to one's own caravan will count as stolen, reported when the items leave the map, and the stolen items will not count as exported.

|-
| {{text anchor|LOCAL_BANDITRY}}
|
| Causes the entity to send out patrols that can ambush adventurers. Said patrols will be hostile to any adventurers they encounter, regardless of race or nationality.

|-
| {{text anchor|MERCHANT_BODYGUARDS}}
|
| Caravan merchants are accompanied by soldiers.

|-
| {{text anchor|MERCHANT_NOBILITY}}
|
| Merchants will engage in cross-civ trading and form companies.

In previous versions, this resulted in the civ having a Guild Representative / Merchant Baron / Merchant Prince, but now this is controlled solely by positions.

|-
| {{text anchor|PROGRESS_TRIGGER_POPULATION}}
| level
| 0 to 5, civ will come to site once population at site has reached that level. If multiple progress triggers exist for a civ, it will come when any one of them is fulfilled instead of waiting for all of them to be reached. A value of 0 disables the trigger. 1 corresponds to 20 dwarves, 2 to 50 dwarves, 3 to 80, 4 to 110, and 5 to 140. Progress triggers may be changed, added, or deleted for a currently active fort. Note: hostile civs require that this be fulfilled as well as at least one other non-siege trigger before visiting for non-siege activities.

|-
| {{text anchor|PROGRESS_TRIGGER_PRODUCTION}}
| level
| 0 to 5, civ will come to site once created wealth has reached that level. If multiple progress triggers exist for a civ, it will come when any one of them is fulfilled instead of waiting for all of them to be reached. A value of 0 disables the trigger. 1 corresponds to 5000☼ created wealth, 2 to 25000☼, 3 to 100000☼, 4 to 200000☼, and 5 to 300000☼. Progress triggers may be changed, added, or deleted for a currently active fort.

|-
| {{text anchor|PROGRESS_TRIGGER_TRADE}}
| level
| 0 to 5, civ will come to site once exported goods has reached that level. If multiple progress triggers exist for a civ, it will come when any one of them is fulfilled instead of waiting for all of them to be reached. A value of 0 disables the trigger. 1 corresponds to 500☼ exported wealth, 2 to 2500☼, 3 to 10000☼, 4 to 20000☼, and 5 to 30000☼. Progress triggers may be changed, added, or deleted for a currently active fort.

|-
| {{text anchor|PROGRESS_TRIGGER_POP_SIEGE}}
| level
| 0 to 5, civ will begin to send sieges against the player civ when this level is reached if it is hostile.

If multiple progress triggers exist for a civ, it will come when any one of them is fulfilled instead of waiting for all of them to be reached. A value of 0 disables the trigger.

|-
| {{text anchor|PROGRESS_TRIGGER_PROD_SIEGE}}
| level
| 0 to 5, civ will begin to send sieges against the player civ when this level is reached if it is hostile.

|-
| {{text anchor|PROGRESS_TRIGGER_TRADE_SIEGE}}
| level
| 0 to 5, civ will begin to send sieges against the player civ when this level is reached if it is hostile.

|-
| {{text anchor|SIEGER}}
|
| Will start campfires and wait around at the edge of your map for a month or two before rushing in to attack. This will occur when the progress triggers for sieging are reached. If the civ lacks smaller methods of conflict (AMBUSHER, BABYSNATCHER, ITEM_THIEF), they will instead send smaller-scale sieges when their triggers for "first contact" are reached.

|-
| {{text anchor|SIEGE_SKILLED_MINERS}}{{v|53.01}}
|
| Improves the skill of [[miner]] invaders by a factor of 5. Used for [[dwarves]] in vanilla.

|-
| {{text anchor|SITE_GUARDIAN}}
|
| Guards certain special sites, such as a [[vault]] belonging to a [[demon]] allied with a [[deity]]. Used in generated divine entities.

|-
| {{text anchor|SKULKING}}
|
| This makes the severity of attacks depend on the extent of item/baby thievery rather than the passage of time. Designed to go with ITEM_THIEF, may or may not work with BABYSNATCHER. Prevents the civ from engaging in diplomacy or ending up at war.

|-
| {{text anchor|TREE_CAP_DIPLOMACY}}
|
| Visiting diplomats impose tree cutting quotas; without this, they will simply compliment your fortress and leave. Also causes the diplomat to make unannounced first contact at the very beginning of the first spring after your fortress becomes a land holder.

|-
| {{text anchor|LAYER_LINKED}}
|
| Defines if a civilization is a hidden subterranean entity, such as [[bat man]] civilizations. May spawn in any of the three caverns; cavern dweller raids due to [[agitation]] will pull from these. If you embark as this civ, you have access to pets and trees from all three layers, not only the first.

|-
| {{text anchor|GENERATE_KEYBOARD_INSTRUMENTS}}, {{text anchor|GENERATE_PERCUSSION_INSTRUMENTS}}, {{text anchor|GENERATE_STRINGED_INSTRUMENTS}}, {{text anchor|GENERATE_WIND_INSTRUMENTS}}, {{text anchor|GENERATE_DANCE_FORMS}}, {{text anchor|GENERATE_MUSICAL_FORMS}}, {{text anchor|GENERATE_POETIC_FORMS}}
|
| Makes civilizations generate the given instruments/forms.

|-
| {{text anchor|SCHOLAR}}
| scholar type
| ALL, ASTRONOMER, CHEMIST, DOCTOR, ENGINEER, GEOGRAPHER, HISTORIAN, MATHEMATICIAN, NATURALIST, PHILOSOPHER

|-
| {{text anchor|SET_SCHOLARS_ON_VALUES_AND_JOBS}}
|
| Generates scholars based on the values generated with the VARIABLE_VALUE tag.

|-
| {{text anchor|NO_ARTIFACT_CLAIMS}}
|
| Used for kobolds.

|-
| {{text anchor|MINING_UNDERWORLD_DISASTERS}}
|
| The civilization can breach the [[Underworld]] during world generation, spawning a civilization of {{token|EVIL}} creatures lead by a unique [[demon]].

|-
| {{text anchor|MYTHICAL}}{{version|51.01-beta26}}
|
| Builds [[mysterious dungeon]]s.

|}

== Available resources ==
{| {{prettytable}}
|- bgcolor="#ddd"
! Token
! Arguments
! Description

|-
| {{text anchor|AMMO}}
| item token
| Used after a ranged weapon type.
[AMMO:ITEM_AMMO_BOLTS]

|-
| {{text anchor|ARMOR}}
|
* item token
* rarity
| Rarity is optional, and valid values are FORCED, COMMON, UNCOMMON, and RARE (anything else is treated as COMMON). FORCED items will be available 100% of the time, COMMON items 50%, UNCOMMON items 10%, and RARE items 1%. If certain armor types are lacking after performing one pass of randomised checks, the game will repeat random checks until an option is successfully chosen.
[ARMOR:ITEM_ARMOR_PLATEMAIL:COMMON]

|-
| {{text anchor|DIGGER}}
| item token
| Causes the selected weapon to fall under the "digging tools" section of the embark screen. Also forces the weapon to be made out of metal, which can cause issues if a modded entity has access to picks without access to metal - for those cases, listing the pick under the [WEAPON] token works just as well. Note that this tag is neither necessary nor sufficient to allow use of that item as a mining tool – for that, the item itself needs to be a weapon with {{token|SKILL|wp|MINING}}.
[DIGGER:ITEM_WEAPON_PICK]

|-
| {{text anchor|GLOVES}}
|
* item token
* rarity
| Rarity is optional, and valid values are FORCED, COMMON, UNCOMMON, and RARE (anything else is treated as COMMON). Uses the same rarity values and methods as outlined in ARMOR.
[GLOVES:ITEM_GLOVES_GLOVES:COMMON]

|-
| {{text anchor|HELM}}
|
* item token
* rarity
| Rarity is optional, and valid values are FORCED, COMMON, UNCOMMON, and RARE (anything else is treated as COMMON). Uses the same rarity values and methods as outlined in ARMOR.
[HELM:ITEM_HELM_HELM:COMMON]

|-
| {{text anchor|INSTRUMENT}}
| item token
| No longer used due to the ability to generate instruments in world generation. It is still usable if pre-defined instruments are modded in, and generated musical forms are capable of selecting pre-defined instruments to use. However, reactions for making instruments, instrument parts, and/or assembling such instruments need to be added as well, as this token no longer adds such instruments to the craftdwarf's workshop menu.
[INSTRUMENT:ITEM_INSTRUMENT_FLUTE]

|-
| {{text anchor|PANTS}}
|
* item token
* rarity
| Rarity is optional, and valid values are FORCED, COMMON, UNCOMMON, and RARE (anything else is treated as COMMON). Uses the same rarity values and methods as outlined in ARMOR.
[PANTS:ITEM_PANTS_PANTS:COMMON]

|-
| {{text anchor|SHIELD}}
| item token
|
[SHIELD:ITEM_SHIELD_SHIELD]

|-
| {{text anchor|SHOES}}
|
* item token
* rarity
| Rarity is optional, and valid values are FORCED, COMMON, UNCOMMON, and RARE (anything else is treated as COMMON). Uses the same rarity values and methods as outlined in ARMOR.
[SHOES:ITEM_SHOES_SHOES:COMMON]

|-
| {{text anchor|SIEGEAMMO}}
| item token
|
[SIEGEAMMO:ITEM_SIEGEAMMO_BALLISTA]

|-
| {{text anchor|TOOL}}
| item token
|
[TOOL:ITEM_TOOL_NEST_BOX]

|-
| {{text anchor|TOY}}
| item token
|
[TOY:ITEM_TOY_PUZZLEBOX]

|-
| {{text anchor|TRAPCOMP}}
| item token
|
[TRAPCOMP:ITEM_TRAPCOMP_GIANTAXEBLADE]

|-
| {{text anchor|WEAPON}}
| item token
| While this does not accept a rarity value, something similar can be achieved by having multiple variations of a weapon type with small differences and specifying each of them.{{cite forum|179547}}
[WEAPON:ITEM_WEAPON_AXE_BATTLE]

|-
| {{text anchor|USE_ANIMAL_PRODUCTS}}
|
| Allows use of products made from animals. All relevant creatures will be able to provide wool, silk, and extracts (including milk and venom) for trade, and non-sentient creatures (unless ethics state otherwise) will be able to provide eggs, caught fish, meat, leather, bone, shell, pearl, horn, and ivory.

|-
| {{text anchor|USE_ANY_PET_RACE}}
|
| Any creature in the civilization's list of usables (from the surrounding 7x7 or so of squares and map features in those squares) will be included in the initial usable creature list, which then gets pared down or otherwise considered. Without this, only common domestic and equipment creatures are added to the initial list.

|-
| {{text anchor|USE_CAVE_ANIMALS}}
|
| If they don't have it, creatures with exclusively subterranean biomes are skipped. If they have it, cave creatures will be included in the initial usable creature list.

|-
| {{text anchor|USE_EVIL_ANIMALS}}
|
| Without this, {{token|EVIL|c}} creatures are skipped, otherwise, evil creatures with {{token|SLOW_LEARNER|c}} or ''without'' {{token|CAN_LEARN|c}} will be included in the initial usable creature list, even the normally untameable species.

|-
| {{text anchor|USE_EVIL_PLANTS}}
|
| Same as USE_EVIL_ANIMALS for all uses of plants.

|-
| {{text anchor|USE_EVIL_WOOD}}
|
| Same as USE_EVIL_ANIMALS for all uses of wood.

|-
| {{text anchor|USE_GOOD_ANIMALS}}
|
| Without this, {{token|GOOD|c}} creatures are skipped, otherwise, good creatures ''without'' {{token|CAN_LEARN|c}} will be included in the initial usable creature list, even the normally untameable species.

|-
| {{text anchor|USE_GOOD_PLANTS}}
|
| Same as USE_GOOD_ANIMALS for all uses of plants.

|-
| {{text anchor|USE_GOOD_WOOD}}
|
| Same as USE_GOOD_ANIMALS for all uses of wood.

|-
| {{text anchor|USE_MISC_PROCESSED_WOOD_PRODUCTS}}
|
| If the relevant professions are permitted, controls availability of lye ({{token|LYE_MAKER|ut}}), charcoal ({{token|WOOD_BURNER|ut}}), and potash ({{token|POTASH_MAKER|ut}}).

|-
| {{text anchor|USE_NON_EXOTIC_PET_RACE}}
|
| Makes the civilization use all locally available non-exotic pets.

|-
| {{text anchor|COMMON_DOMESTIC_MOUNT}}
|
| Gives the civilization access to creatures with {{token|COMMON_DOMESTIC|c}} and {{token|MOUNT|c}}. Additionally, all available (based on USE_ANY_PET_RACE, USE_CAVE_ANIMALS, USE_GOOD_ANIMALS, and USE_EVIL_ANIMALS) creature with {{token|MOUNT|c}} and {{token|PET|c}} will be allowed for use as mounts during combat.

|-
| {{text anchor|COMMON_DOMESTIC_PACK}}
|
| Gives the civilization access to creatures with {{token|COMMON_DOMESTIC|c}} and {{token|PACK_ANIMAL.|c}} Additionally, all available (see above) creatures with {{token|PACK_ANIMAL|c}} and {{token|PET|c}} will be allowed for use during trade as pack animals.

|-
| {{text anchor|COMMON_DOMESTIC_PET}}
|
| Gives the civilization access to creatures with {{token|COMMON_DOMESTIC|c}} and {{token|PET|c}}. Additionally, all available (see above) creatures with {{token|PET|c}} will be allowed for use as pets.

|-
| {{text anchor|COMMON_DOMESTIC_PULL}}
|
| Gives the civilization access to creatures with {{token|COMMON_DOMESTIC|c}} and {{token|WAGON_PULLER|c}}. Additionally, all available (see above) creatures with {{token|WAGON_PULLER|c}} and {{token|PET|c}} will be allowed for use during trade to pull [[wagon]]s.

|-
| {{text anchor|RIVER_PRODUCTS}}
|
| Allow use of river products in the goods available for trade.

|-
| {{text anchor|OCEAN_PRODUCTS}}
|
| Allow use of ocean products (including [[amber]] and [[coral]]) in the goods available for trade. Without OCEAN_PRODUCTS, civilizations will not be able to trade ocean fish even if they are ''also'' available from other sources (e.g. [[sturgeon]]s and [[stingray]]s).

|-
| {{text anchor|INDOOR_FARMING}}
|
| Allow use of underground plant products in the goods available for trade. Lack of suitable vegetation in the caverns will cause [[World generation#Rejections|worldgen rejection]]s. According to Droseran: "Gives access to plants (structural material) and seeds. It only checks for {{token|EDIBLE_RAW|md}} or {{token|EDIBLE_COOKED|md}} on the plant's structural material. It doesn't check if the plant can be used in a reaction to produce something edible, only if it can be eaten raw or cooked. If an entity with this token is placed in a biome that doesn't have at least one of these tokens on the structural material, the map is rejected. Due to the randomness of plant selection in biomes, this can happen a lot as only about half of the vanilla plants have edible structural materials. Removing either of these tokens from plants dramatically increases map rejections."

|-
| {{text anchor|OUTDOOR_FARMING}}
|
| Allow use of outdoor plant products in the goods available for trade. Lack of suitable vegetation in this civilization's starting area will cause [[World generation#Rejections|worldgen rejection]]s. According to Droseran: "Gives access to plants (structural material) and seeds. It only checks for {{token|EDIBLE_RAW|md}} or {{token|EDIBLE_COOKED|md}} on the plant's structural material. It doesn't check if the plant can be used in a reaction to produce something edible, only if it can be eaten raw or cooked. If an entity with this token is placed in a biome that doesn't have at least one of these tokens on the structural material, the map is rejected. Due to the randomness of plant selection in biomes, this can happen a lot as only about half of the vanilla plants have edible structural materials. Removing either of these tokens from plants dramatically increases map rejections."

|-
| {{text anchor|INDOOR_GARDENS}}
|
| Allow use of underground plant growths (quarry bush leaves, in unmodded games) in the goods available for trade. According to Droseran: "Will never cause map rejections. It allows growths to be used, but doesn't care if none exist. If an entity doesn't have a farming token, they won't have seeds or plants available on embark/trade. But you can still farm in fortress mode with only this token, you just have to get the seeds manually or trading with another civ."

|-
| {{text anchor|OUTDOOR_GARDENS}}
|
| Allow use of outdoor plant growths in the goods available for trade. According to Droseran: "Will never cause map rejections. It allows growths to be used, but doesn't care if none exist. If an entity doesn't have a farming token, they won't have seeds or plants available on embark/trade. But you can still farm in fortress mode with only this token, you just have to get the seeds manually or trading with another civ."

|-
| {{text anchor|INDOOR_ORCHARDS}}
|
| Allows use of indoor tree growths in the goods available for trade. Not used in vanilla entities, as vanilla underground trees do not grow fruit. Needs INDOOR_WOOD to function. Will cause rejections, if growths are unavailable. According to Droseran: "Gives access to tree growths. It only checks for growths on trees that are {{token|EDIBLE_RAW|md}} or {{token|EDIBLE_COOKED|md}}. If an entity with this token is placed in a biome that does not have a tree with a growth with at least one of these tokens, the map is rejected."

|-
| {{text anchor|OUTDOOR_ORCHARDS}}
|
| Allows use of outdoor tree growths in the goods available for trade. Needs OUTDOOR_WOOD to function{{verify}}. According to Droseran: "Gives access to tree growths. It only checks for growths on trees that are [EDIBLE_RAW] or [EDIBLE_COOKED]. If an entity with this token is placed in a biome that does not have a tree with a growth with at least one of these tokens, the map is rejected."

|-
| {{text anchor|CLOTHING}}
|
| Civilization members will attempt to wear clothing.

|-
| {{text anchor|SUBTERRANEAN_CLOTHING}}
|
| Will wear things made of spider silk and other subterranean materials.

|-
| {{text anchor|EQUIPMENT_IMPROVEMENTS}}
|
| Adds decorations to equipment based on the level of the generated unit. Also improves item quality.

|-
| {{text anchor|IMPROVED_BOWS}}
|
| Adds decorations to weapons generated for bowman and master bowman.

|-
| {{text anchor|METAL_PREF}}
|
| Allows metal materials to be used to make cages (inexpensive metals only) and crafts.

|-
| {{text anchor|STONE_PREF}}
|
| Allows the civilization to make use of nearby stone types. If the {{token|FURNACE_OPERATOR|ut}} job is permitted, also allows ore-bearing stones to be smelted into metals.

|-
| {{text anchor|WOOD_WEAPONS}}
|
| The civilization can make traditionally metallic weapons such as swords and spears from wood.

|-
| {{text anchor|WOOD_ARMOR}}
|
| The civilization can make traditionally metallic armor such as mail shirts and helmets from wood.

|-
| {{text anchor|GEM_PREF}}
|
| Enables creatures of this entity to bring gems in trade.

|-
| {{text anchor|INDOOR_WOOD}}
|
| Allow use of subterranean wood types, such as tower-cap and fungiwood logs.

|-
| {{text anchor|OUTDOOR_WOOD}}
|
| Allow use of outdoor wood types, such as mangrove and oak.

|-
| {{text anchor|GEM_SHAPE}}
| [[Descriptor shape token|shape]]
| Precious gems cut by this civilization's jewelers can be of this shape.

|-
| {{text anchor|STONE_SHAPE}}
| [[Descriptor shape token|shape]]
| Ordinary non-gem stones cut by this civilization's jewelers can be of this shape.

|-
| {{text anchor|DIVINE_MAT_CLOTHING}}
|
| Allows use of materials with {{token|DIVINE|im}} for clothing. Used for generated divine entities.

|-
| {{text anchor|DIVINE_MAT_CRAFTS}}
|
| Allows use of materials with {{token|DIVINE|im}} for crafts.{{verify}} Used for generated divine entities.

|-
| {{text anchor|DIVINE_MAT_WEAPONS}}
|
| Allows use of metals with {{token|DIVINE|im}} for weapons. Used for generated divine entities.

|-
| {{text anchor|DIVINE_MAT_ARMOR}}
|
| Allows use of metals with {{token|DIVINE|im}} for armor. Used for generated divine entities.
|}

== Animal definitions ==

{| {{prettytable}}
|- bgcolor="#ddd"
! Token
! Arguments
! Description

|-
| {{text anchor|ANIMAL}}
|
| Start an animal definition.

|-
| {{text anchor|ANIMAL_TOKEN}}
| [[creature token]]
| Select specific creature.

|-
| {{text anchor|ANIMAL_CASTE_TOKEN}}
| [[Caste|creature caste token]]
| Select specific creature caste (requires ANIMAL_TOKEN). Sites with animal populations will still include all castes, but only the selected ones will be used for specific roles.

|-
| {{text anchor|ANIMAL_CLASS}}
| [[Creature token#CREATURE_CLASS|creature class]]
| Select creature castes with this creature class (multiple uses allowed).

|-
| {{text anchor|ANIMAL_FORBIDDEN_CLASS}}
| [[Creature token#CREATURE_CLASS|creature class]]
| Forbid creature castes with this creature class (multiple uses allowed).

|-
| {{text anchor|ANIMAL_ALWAYS_PRESENT}}
|
| Animal will be present even if it does not naturally occur in the entity's terrain. All creatures, including [[demon]]s, night trolls and other generated ones will be used if no specific creature or class is selected.

|-
|
* {{text anchor|ANIMAL_NEVER_MOUNT}}, {{text anchor|ANIMAL_ALWAYS_MOUNT}}
* {{text anchor|ANIMAL_NEVER_WAGON_PULLER}}, {{text anchor|ANIMAL_ALWAYS_WAGON_PULLER}}
* {{text anchor|ANIMAL_NEVER_SIEGE}}, {{text anchor|ANIMAL_ALWAYS_SIEGE}}
* {{text anchor|ANIMAL_NEVER_PET}}, {{text anchor|ANIMAL_ALWAYS_PET}}
* {{text anchor|ANIMAL_NEVER_PACK_ANIMAL}}, {{text anchor|ANIMAL_ALWAYS_PACK_ANIMAL}}
|
| Override creature usage tokens. Respectively:
* [[Creature token#MOUNT|MOUNT]] and [[Creature token#MOUNT_EXOTIC|MOUNT_EXOTIC]]
* [[Creature token#WAGON_PULLER|WAGON_PULLER]]
* [[Creature token#TRAINABLE_WAR|TRAINABLE_WAR]] and not [[Creature token#CAN_LEARN|CAN_LEARN]]
* [[Creature token#PET|PET]] and [[Creature token#PET_EXOTIC|PET_EXOTIC]]
* [[Creature token#PACK_ANIMAL|PACK_ANIMAL]]
ALWAYS overrides NEVER if a caste is matched by more than one animal definition.

|}

== Tissue styling-related tokens ==
{| {{prettytable}}
|- bgcolor="#ddd"
! Token
! Arguments
! Description

|-
| {{text anchor|TISSUE_STYLE}}
| tissue style unit ID
| Select a tissue layer which has the ID attached using TISSUE_STYLE_UNIT token in unit raws. This allows setting further cultural style parameters for the selected tissue layer.

|-
| {{text anchor|TS_MAINTAIN_LENGTH}}
|
* minimum length?
* maximum length?
| Presumably sets culturally preferred tissue length for selected tissue. Needs testing.
Dwarves have their beards set to 100:NONE by default.

|-
| {{text anchor|TS_PREFERRED_SHAPING}}
| styling token
| Valid tokens are NEATLY_COMBED, BRAIDED, DOUBLE_BRAIDS, PONY_TAILS, CLEAN_SHAVEN and STANDARD_HAIR/BEARD/MOUSTACHE/SIDEBURNS_SHAPINGS.
Presumably sets culturally preferred tissue shapings for selected tissue. Needs testing.

|}

== Examples ==
:''Main articles: [[Entity examples]]''

{{Category|Modding}}
{{Category|Tokens}}
{{Category|Entities}}
[[ru:Entity token]]

Talk:Variable positions

2026-03-17T09:56:54Z

Joostheger:

Talk:Variable positions

2026-03-15T13:23:20Z

Joostheger:

Advanced entity position mechanics

2026-03-12T11:57:27Z

Joostheger: /* Civ-level nobles living at your site */

{{Quality|Fine}}
{{Modding}}

= Introduction =

[http://www.bay12forums.com/smf/index.php?topic=182239.0 Discussion thread on the forum]

This page documents observed and tested behavior of entity positions in Dwarf Fortress that is not fully described elsewhere on the wiki. It focuses on advanced interactions between position tokens, including appointment, succession, election, and responsibility handling, across both civilization-level and site-level entities.

The mechanics described here are based on empirical testing in world generation and fortress mode, supplemented where necessary by raw analysis. In several cases, the game’s behavior is determined by evaluation order and interaction between multiple tags, rather than by individual tokens in isolation.

This page is intended for modders and advanced players who are designing or debugging custom entity position structures. It does not restate basic position mechanics, but instead highlights edge cases, non-obvious interactions, and behaviors that may appear inconsistent or undocumented.

Unless stated otherwise, the described behavior applies to current versions of the game and may differ from older releases.

==What is an entity? What is a position?==
An [[entity]] is an organizational structure that can have relationships with other entities, usually known as a [[civilization]] or a "[[site]] government" in the game, but merchant [[guild]]s, religious organizations, necromancer towers, and [[bandit]] groups are also entities. An entity can have positions - in most cases, these are hardcoded and generated by the game, but as for civilizations and sites, the [[raw file]]s can be customised.

A position is a special relationship between a unit and an entity. The unit holding a position has a larger influence over that entity than other citizens. Positions are mostly known as [[nobles]], but in this article. the technical term is used.

=Position levels (Site/Civ) and their interaction=
There are two basic types of positions that are customizable: '''civ(ilization)''' level and '''site level'''. Positions with the tag [SITE] are at site level, positions without the tag [SITE] are at 'civ level'. These two types of nobles can be considered '''loosely related systems'''. There are a few places where they can interact with each other.

Civ-level positions are in charge of the civilization as a whole, managing national [[trade]], laws, and [[war]]s. These are, for example, the vanilla [[monarch]], [[diplomat]] and [[general]]. (Note that the general doesn't do anything in either mode in the current version.)

'''[LAND_HOLDER]''' nobles are also positions at civ-level. These units are members of the national government, but have gained authority over some land or site. Once they do, they move to that place, but their position is still regarded as a civ-level position.

Site-level position holders are members of a site government (subsidiary to the civilization), and manage local affairs in that location. These are, for example, the [[mayor]], the [[sheriff]] and the [[broker]].

==Table of interaction between different position levels==
In this table, the possible interactions between different position levels are summarized.
The header row shows the positions defining the tokens.

The left column shows the position type that is referred to.
Example:
{| {{prettytable}}
|- bgcolor="#ddd"
! referred position-type
! LAND_HOLDER
|-
| civilization
| (baron is) APPOINTED_BY:MONARCH
|}
color coding: 
* Exists in vanilla
* Possible with mods
* Not possible
* possible to some extent.
* not yet fully investigated.
{| {{prettytable}}
|- bgcolor="#ddd"
! referred position-type
! Civilization
! SITE
! LAND_HOLDER
! CONQUERED_SITE

|-
| Civilization
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION '''(1)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION

|-
| SITE
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION '''(2)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY '''(3)''' COMMANDER REPLACED_BY SUCCESSION '''(4)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION

|-
| LAND_HOLDER
| APPOINTED_BY COMMANDER REPLACED_BY '''(6)''' SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION '''(5)'''
| APPOINTED_BY COMMANDER REPLACED_BY '''(7)''' SUCCESSION '''(8)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION

|-
| CONQUERED_SITE
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
|}

Remarks:
# Works only in world-gen, if a unit with that civ-position is present at the site.
# Works only in world-gen, the site-position holding unit will then move to the capital.
# Is completely ignored
# Works only in world-gen.
# Works only in world-gen.
# Won't appear at all
# This is necessary for the landholder chain to work properly, it doesn’t work otherwise.
# This works only outside of the landholder chain, so when landholders are simply regarded as civ-level nobles. might also work in world-gen
#

== Other interactions ==

Unfortunately, interactions with positions of other entities don't seem possible, such as APPOINTED_BY: HIGH_PRIEST. With [VARIABLE_POSITIONS], positions are automatically created with codes like CUSTOM_LAW_MAKER_2, but interaction with these positions don't seem to work, either. For more info on those, see [[Variable positions]]

=General=

==Civ-level nobles living at your site==
Nobles from your civilization can come to live at your fortress. This happens in vanilla with landholders such as [[Baron]], [[Count]] and [[Duke]], with the Monarch, but sometimes also with non-landed LAND_HOLDERS.

When a civ-level noble becomes a [[citizen]] at your location, their position is shown among the site-level positions in your [[nobles screen]]. They appear to function as a site-level noble. They may have [[demand]]s, [[mandate]]s, [[squad]]s and the like. They can appoint nobles at the site-level.

Even if they have certain site related [RESPONSIBILITY]ies, they will not do the tasks that go with them.

==Fortress mode, world-gen and their differences==
Their are a few differences in how positions function between fortress mode (normal play mode) and the world generation (world-gen).

In '''fortress mode''', the player has some control over the appointment of nobles, limited by elections, automatic filled-in positions and succession rules. Pre-fortress mode, which is referred to as '''world-gen''', the game will always attempt to assign nobles whenever possible. It is subjected to the same rules as in fortress-mode, but there are some exceptions. In '''[[World activities]]''', which is the thing that happens in the world while you play fortress mode, it seems as if the same rules are applied as fortress mode.

A difference between player-fortress-mode and world-gen, is causes by visibility (see below). Positions that are not visible by the player and thus not available for assignment, will be available in world-gen and will thus be automatically assigned.

In fortress mode, a position that is both [ELECTED] and [APPOINTED_BY], cannot be appointed by the player and is also not elected, and can thus not be filled. But in world-gen sites however, these positions are automatically filled.

Positions with [AS_NEEDED] are almost never created and filled in world-gen (depending on their [RESPONSIBILITY]ies), but can always be used in player mode.

A position can, in fortress mode, be filled by the same unit. A unit can gain multiple positions in fortress mode, for example because of [[elections]]. This will not happen in world-gen mode: a unit can only have one position. See also remarks on 'embark' and 'Losing a position'.

In world-gen, [SUCCESSION] between civ-levels and [SITE-]levels may happen. This will not happen in fortress mode, or even off-site in [[World activities]].

In fortress mode, premature SUCCESSION may happen. This will not happen in world-gen mode.

==Units holding multiple positions in multiple entities==
A unit can hold multiple positions in its civilisation or in its site-entity, however this does not happen in world-gen. Only at player-managed sites can units be holding multiple positions at once. (It is probably not possible for a unit to hold a position in two different civilisations or two different sites.)

In world-gen, if there are too many positions to be filled, they simply stay empty until more units are available. E.G, a unit at a site might inherit a civ-level position and still remain a member of the local government. When this happens however, they move to the capital. If a unit gains a new position, either inherited or otherwise, it drops the previous one. If a unit assumes a civ-position in fortress mode, it leaves the current position.

If a unit holds the same (site-)position multiple times, it has no additional effect.

If a unit holds multiple different positions of the same entity, it has all those positions' responsibilities and properties, stacked up. Presumably, the demands for those combined positions are determined by the highest.

A unit holding a position with a succession token can be assigned another position with a (different) succession token.

A unit holding a position with a squad-position cannot hold another squad-position. It is dropped from the first, when it gets its second assigned.
A unit holding a position with a succession token cannot be assigned to a squad-position - the unit is simply not available. It works the other way around, though.

=Specific Tags and functions=
==[PRECEDENCE]==
The first defined position with precedence of 1 counts as the ruler of the civ. See also: [[Position_token#PRECEDENCE|PRECEDENCE]].

If the precedence is omitted or has a negative value, the game sets 0 as precedence, which seems to have no effect whatsoever.

When a unit has multiple positions, the name of the position with the highest rank in precedence is shown behind the unit's name.

If you omit precedence entirely, or set it to [PRECEDENCE:NONE], the position name will not be shown after the unit’s name. Your *Urist Mason* will remain simply *Mason*. This can be useful for positions that are unimportant or purely functional. The position will also not appear in the civilisation overview of your site on the world map. The position name is shown in messages, but remains hidden on the nobles screen as well. To make it visible there, use [LAND_NAME].

==[RESPONSIBILITY]ies==
Both civ and [SITE] positions can carry responsibilities. However, not all responsibilities are active for both types: some function only for civ positions, others only for site positions. When a civ noble arrives at a site and takes up residence, they do not perform responsibilities that are intended for SITE nobles. As a result, these responsibilities neither trigger their associated tasks nor unlock related game mechanics. For example, a civ-level manager living in a fortress will not perform management duties there and doesn't unlock the management-screen, even with an assigned office.
This behavior applies to the following [SITE]-level responsibilities:
* [RESPONSIBILITY:ACCOUNTING]
* [RESPONSIBILITY:BUILD_MORALE]
* [RESPONSIBILITY:HEALTH_MANAGEMENT]
* [RESPONSIBILITY:LAW_ENFORCEMENT]
* [RESPONSIBILITY:MANAGE_PRODUCTION]
* [RESPONSIBILITY:MEET_WORKERS]
* [RESPONSIBILITY:TRADE] (functions differently)
Other responsibilities may be affected as well, but have not yet been fully tested.

===World-gen effects of the [RESPONSIBILITY] of available positions ===
It is possible to cause civs and individual sites to change their behavior substantially when they reach a certain size, by controlling nobles.
* If a site can only appoint a position with [MILITARY_GOALS] after reaching a particular size, that site will not send armies on missions until the required size is reached.
* A civ-level [LAW_MAKING] position is required for the civilization to have any kind of cohesion. Without it, sites will be constantly embroiled in territorial disputes and civil wars will be commonplace.
* [MILITARY_STRATEGY] positions go out and tame wild animals. This makes your civ gain those animals as domesticated and also brings them in sieges.
* The [[Personality_facet|Personality]] of the position's holder determines how they lead the civ.

===[DELIVERS_MESSAGES]===
The only [AS_NEEDED]-position that is created in worldgen based on responsibility is that of the site-level responsibility [DELIVERS_MESSAGES].

===Outpost Liaisons and Diplomats===
Civ-positions with the responsibility [ESTABLISH_COLONY_TRADE_AGREEMENTS] ([[Outpost_Liaison|Outpost Liaison]]s) will meet with the site-noble who has responsibility for [RECEIVE_DIPLOMATS] and the highest rank of precedence (i.e. the lowest precedence value). Usually this is the [[Expedition_leader|Expedition leader]].

Once a [LAND_HOLDER] is assigned to the site, civ-positions with the responsibility [MAKE_TOPIC_AGREEMENTS] ([[Diplomat]]s) will meet with '''civ'''-level nobles present at the site who have the [RECEIVE_DIPLOMATS] responsibility. If multiple eligible nobles are available, one is selected at random. If no eligible noble is present, the diplomat leaves angrily. If the landholder is no longer present at the site, diplomats will not arrive at all.

It appears that Outpost Liaisons and Diplomats are chosen for a diplomatic mission based on availability. When multiple candidates exist, the position defined last in the raws is most often selected.

===[TRADE]===
Civ-level nobles with [TRADE] will arrive with the caravan, just as the Outpost Liaison. Their behavior is no longer active in the vanilla game, but the mechanics are still present. See [[40d:Guild_representative|Guild representative]] for more details. This civ-noble will only meet with the SITE noble with [TRADE], usually the [[Broker]].

If two civ-nobles exist with both [TRADE] and [ESTABLISH_COLONY_TRADE_AGREEMENTS], they both arrive at the same time. Even if both tokens are assigned to a single position, if more than one instance of that position exists, two of them will arrive. However in that case, somehow the elevation of the site and appointment of landholder isn't offered.

If the SITE-noble they intend to meet has both [TRADE] and [RECEIVE_DIPLOMATS], only one meeting will proceed and the other is cancelled. However, when two SITE-nobles are available, each with either [TRADE] or [RECEIVE_DIPLOMATS], both meetings will proceed and both civ-nobles will attempt to negotiate a trade agreement. It is not known what happens if these agreements are accepted or refused.

In the trade depot, the last defined position with the [TRADE] responsibility is shown as broker. However when requesting a trader, the first defined position with [TRADE] will actually go there to do the trade.

==[NUMBER]==
A position might be defined with a number. In that case, as many as defined can be available. If the positions become available, in world-gen and when embarking, they are all filled-in completely.

If the ruling position (with PRECEDENCE of 1) has a NUMBER higher than 1, a random unit of the ones holding these positions is shown as ruler in the embark screen.

A [NUMBER] of 0 (zero) has the same effect as 1.

===Automatic spreading of assumed, non-singular positions===
If there are civ positions that have a NUMBER higher then '1' and which are assumed (not APPOINTED_BY or ELECTED) but are '''not DUTY_BOUND''', these are automatically spread among the civilisation, based on population. If there are a number of '''20''' available slots of that position, they spread among a civilization with a combined population of, for example, 1000 of which your fortress has 100 (10%), '''2''' of your fortress' citizens will assume that position.
This may probably also work with elected and appointed positions, but that may be depending on the death of the current holders and this needs more testing. Assumption works within a day, anyway.

===[AS_NEEDED]===
These positions can be created automatically by the game in world-gen. This, however, only works with:
* [LAND_HOLDER]'s
* squad commanders (needs more testing)
* Messengers at sites

For all other types of positions, they're not created in world-gen, even if they are defined with RESPONSIBILITY's. For example, even in war, the game wouldn't create a MILITARY_GOALS position, if they have AS_NEEDED as number.

However, in fortress mode / player mode, these positions can be created by the player at will.

Positions with AS_NEEDED need to be created first, before any symbols are assignable as 'symbols' (objects) for the position holder to carry or wear.

Positions with AS_NEEDED cannot be created and then ELECTED in fortress mode. It only works with APPOINTED_BY.

==[REPLACED_BY], [REQUIRES_POPULATION], [REQUIRES_MARKET]==

The token [REPLACED_BY:position] means that once the replacing position meets its requirements for activation, the 'to-be-replaced' position will disappear. This is defined in [REQUIRES_POPULATION] or [REQUIRES_MARKET]. The tags are closely related to each other and seem to only have a meaningful function if combined. Nobles with [REQUIRES_POPULATION] require the population to have a specific size. Nobles with [REQUIRES_MARKET] are only activated in market sites, such as fortresses or towns. [REQUIRES_POPULATION] and [REQUIRES_MARKET] can be combined, activating that position once both requirements are met.

The [REQUIRES_MARKET] can be used to differentiate positions between hamlets and hillocks, and larger sites. IThe market always is build the year after the site is founded. So a position that is to be replaced, will be gone immediately.

The [REQUIRES_POPULATION]-tag works on the civ-level as well as on site-level, but those systems are in this mechanic strictly separated. Site-level positions cannot be replaced by civ-level positions and visa versa. This makes sense, because they both depend on their own population-count. When using REQUIRES_POPULATION on civ-level, it counts the total population of the civilisation.

See also: [[Advanced_entity_position_mechanics#Evaluation_of_Positions|Evaluation of positions]]

===Effect of replacement (and on [LAND_HOLDER]s)===

Replacement is immediate and complete - the current holding unit loses the position, even before SUCCESSION_BY_POSITION rules are applied. A position with a number of 1 will replace all the slots of a position with a higher number of slots.

Even if the next position is available but not visible, replacement still takes place. If a position is replaced, it is completely gone - it cannot be appointed, succeeded, elected or assumed any longer.
The unit immediately loses its position.

In legends, replacement is mentioned as: "(unit name) ceased to be (position name)" The replacement of an AS_NEEDED position empties the position's slot forever. In fortress mode, it may seem as if you can create new slots and appoint new units in the nobles screen, but this is reversed as soon as you close the window.

The landholder chain uses [REPLACED_BY] differently. It does not clear the position completely, but uses it for succession to the next level's position. [REPLACE_BY] is required to let that system work properly. This also means that the way in which landholders succeed (replace + as_needed) does not work in any other way.

Replacement between LAND_HOLDERS and other site- or civ positions does not work in any way. Only the vanilla replacement sequence between levels of LAND_HOLDERs does work. If the token is omitted for landholders, the landholder chain is broken, so replacement is required for the landholder system to work.

[REQUIRES_POPULATION] also does not work for [LAND_HOLDER], when you set [NUMBER] to 1. The position is not created when the required population is reached.

===What doesn't work===

'''Attention: If a position cannot be appointed, for example because of 'mutual appointment', it still exists according to replacement mechanics and will replace other positions if so defined. If a certain position(a) will be replaced by the baron's assistant, which can only be appointed by the [LAND_HOLDER] baron, than that position(s) still will be replaced from the start of the game, even if no baron or their assistant is ever present.'''

A position that is replaced by a somehow non-fillable position is still replaced. This counts for mutual-appointing positions, replacement by not-yet-assigned landholders, replacement by AS_NEEDED positions, or replacement by not-yet-appointed positions.

Replacement does not work if the replaced position is a [LAND_HOLDER], even with civ-positions. In that case, the LAND_HOLDER's position is not replaced. It does not matter if AS_NEEDED is used, or a fixed number, and it also does not matter what type of position the replacer is. So this only works (correctly) with positions that become available by REQUIRES_POPULATION.

==[CONQUERED_SITE]==

This tag determines which position is used to assign a [[Forced administrator]].

In legends mode, this is visible as an event describing the reconquest of the site: a new group is formed and the forced administrator is installed as its ruler.

All positions defined with this tag are assigned during this process, meaning multiple positions can be appointed at once.

The holder of a position marked with [CONQUERED_SITE] cannot appoint any other [SITE] positions.

Combining [CONQUERED_SITE] with [SITE] causes the position to function both as a forced administrator and as a normal site position available in fortress mode. However, this provides no meaningful additional mechanics and is effectively inferior to using [SITE] alone:
* [APPOINTED_BY] lines are completely ignored, meaning that the roles are automatically assumed.
* [SUCCESSION] is likewise ignored.
* the [CONQUERED_SITE]-position cannot appoint other [CONQUERED_SITE], [SITE] or combined positions.

There have been remarks that reclaiming a fortress is unplayable because of the lack of regular nobles. Unfortunately, it seems that it can't be fixed by modding.

=Availability and visibility=
==Availability of (new) positions==
Warning: Do not mistake "availability" for "visibility"!

Of all the possible positions existing in your site's entity, there may only be some available.
* Positions with [REQUIRES_POPULATION] require the population to have a specific size.
* Positions with [REQUIRES_MARKET] will only appear in "large" sites (which may have different rules for different site types). This tag has no effect in fort mode.
* Positions that are appointed by positions that have an AS_NEEDED number. The appointable positions only become available after an appointer position-slot is created. This works also on civ-level. If a position is appointed by a Land-holder, it only becomes available, when that level of landholder is created.

Only the replaced positions are culled and are no longer available.
A position that requires a certain population will become available, even if it doesn't have [APPOINTED_BY] or [ELECTED]. In that case, see 'automatic assignment' and 'assumption'

In fortress mode, in some cases 'succession' is evaluated immediately after a position becomes available. See: Succession.
==Visibility of positions==
A position might be available, but can still be invisible for the player in the [[nobles screen]]. The positions with their respective holders are visible for players:
* All site-positions that are already filled-in (even if they could not be re-filled-in considering current conditions)
* Site positions that are appointable by a filled-in site position
* Site positions that are appointable by a filled-in civ position, when that civ positions holder becomes a citizen of your fortress.
* Civ positions of units that are also a citizen of your fortress.
If a position becomes available, for example because a certain pop number has been reached, or if it is available from the start(like expedition leader), as long as it cannot be appointed, it still is INVISIBLE for the player.

It might strike someone as odd if a position becomes filled automatically in fortress mode when that position is not even visible. This might be the case if the current holder of a non-appointable position dies or succeeds another position. Regardless of player visibility, these positions will be automatically filled in if the necessary requisitions are met. It might happen with the expedition leader.

A situation with a non-visible but available position, is for example when a position is solely appointed by the expedition leader, when the expedition leader's position is left vacant. It can no longer be appointed by the player and is invisible. Then, it gets automatically assumed, proving that the position still was available.

A position that is both [APPOINTED_BY] and [ELECTED] is visible, but players cannot interact with it.

={{text anchor|Evaluation of Positions}}=
The game does not continuously check whether positions should become available, elected or be [REPLACE_BY]. This is well-known behavior—for example with the [[mayor]], who does not appear automatically when the required population ([REQUIRES_POPULATION]) is reached. Instead, positions must somehow be evaluated. This applies in several other situations as well

'''Cases that require a trigger:'''
* Election of a newly created position
* Election after the current holder dies
* Automatic assumption of a newly created position (this may take up to a day)
* New citizens (such as migrants) considering available positions
* Premature succession of a newly created position

'''Cases that do not wait for a trigger:'''
* Succession following the death of the previous holder
* Automatic assumption of existing positions that have become vacant

'''Triggers that cause the game to reevaluate noble positions:'''
* Succession of a [SITE]-position due to the death of the current holder
* [[Advanced_entity_position_mechanics#Election_Day|Election Day]]
* Automatic assumption of a [SITE]-position that becomes vacant
* (Re)assigning any site position manually
* Settlement elevation on the LAND_HOLDER track (e.g. gaining a [[Baron]] or [[Count]])

=Gaining a position=
There are several ways a unit can gain a position:
* Appointment: A unit is appointed by another unit or by the player.
* Election: A unit is elected by and among the members of the entity
* Assumption: A position is neither elected or appointed: a random unit just simply 'takes' the position
* Succession: a unit is the valid successor of this position(A), either by its current position(B) or because they are that position(A)-holder's heir.

Available positions will automatically be assigned to a random civ member when a new site/civ is created.

==Who can take a position==

* If so defined, a unit needs to be the right caste and/or class - it does not seem to work with creature types.
* The unit needs to be an adult member of the site or its parent civ's government; that is also CAN_LEARN or INTELLIGENT (SLOW_LEARNER cannot take positions) or otherwise is able to think.

==Appointment==

Positions that have an [APPOINTED_BY:position] token require that position to exist, to be available and appointed. Any position that is APPOINTED_BY can be appointed if the appointer's position is filled in.
For site-positions to be appointed, it is required that the appointer is present at that location.

If the appointing unit is temporarily not present, or if that position is not filled, positions depending on it cannot be appointed. This is the case with [[militia captains]], when the [[militia commander]] is on a [[mission]].

A site position cannot appoint a civ position ''or'' LAND_HOLDER in any way whatsoever.

Civ-level positions can appoint other civ-level positions and site-level positions can appoint other site-level positions.

Contrary to what has been said elsewhere, civ-level nobles also can appoint site-level nobles. They need to be at the site to do so. Landholders can appoint both site-level and civ-level nobles. These systems are therefore not as separate as was assumed.

'''Mutual appointment''' cannot take place. If these are the only requisites of the position, then the positions will never appear or get filled. These unfillable positions can be put to good use, for example, to replace a position that is no longer needed without creating a new one.

'''Self appointment''' doesn't normally work. If you have a position that is only appointed by itself, it is never appointed and also cannot be assumed. However, if the position has a number higher than 1, and is filled by multiple units (for example by another position that is now empty), than those units can re-assign or appoint each other from that their shared position.

If an APPOINTED_BY token refers to a non-existing position's code, the effects are as if the appointment token doesn't exist at all.

===Automatic appointment in world-gen and on the civ level===

Outside of fortress mode, the game will always attempt to appoint nobles whenever possible, as long as these positions are '''available''', even if they are invisible to the player.
It shows this message in legends: "(unit name) has been appointed to the position of (position name)"

In world-gen, all positions become available and are automatically appointed, taking population- and appointment-requirements into consideration.

Positions that are REPLACED_BY are culled and won't be filled.

If a citizen of your fortress holds a civ-level position that can appoint another civ-level position, the appointment will happen automatically and without player intervention. It may happen that another citizen of your fortress is appointed by that unit, creating civ-level position holders in your fortress, but it is unknown what is required to force this effect.

===Manual appointments by players in fortress mode===
In fortress mode, the positions that need to be appointed stay empty on embark. and it is the player's job to appoint those. A player can appoint a unit to any available position, according to the hereabove mentioned conditions. The player takes the role of the automatic appointment-system, but has no direct control over elections, successions and replacement. There are some differences in what is possible at world-gen sites and at player-controlled sites.

* A position that is appointed by a unit present as a fortress citizen, can be appointed, re-appointed or left vacant. This means also by civ-level nobles living as a citizen in your fortress; not when they are only visiting, like the diplomat.
* A position whose appointing positions are all either vacant or [REPLACED_BY] can no longer be appointed. If the position is already filled, it cannot be reappointed or vacated; the current holder simply remains in office.
* A position that is APPOINTED_BY a unit present as the land_holder of your site, can be appointed, reassigned or left vacant.
* A position that has SUCCESSION BY_HEIR or BY_POSITION can 'initially' be appointed and also re-appointed or left vacant, but as soon as the [[nobles]] screen closes, ''it can no longer be replaced or left vacant''. From then on, the succession-rules determine who gains that position when the current holder loses the position. This works even if the SUCCESSION:BY_POSITION-position is vacant or replaced.
* A position that is ELECTED nor APPOINTED_BY, can always be (re-)appointed by the player. This is the case with the [[Expedition leader]]. If it is left vacant however, it cannot be appointed, but will be assumed shortly after.
* A position that is both ELECTED and APPOINTED_BY, cannot be appointed by the player. Contrary to world-gen sites, its slot is visible, but it doesn't show the +-sign. This is either by AS_NEEDED or by a fixed number. Even if the position somehow gets filled (re)assignment is never possible
* A player can appoint a number of units to a position, as much as the NUMBER token dictates. If it is AS_NEEDED, the player may create as many slots as they like, also contrary to world-gen sites.
* A civ-position can never be appointed, even if the appointing civ noble is a citizen of your fortress. A civ position also never can be re-assigned or left vacant, would that position be defined as appointed by a site-position.

==Election==
Read more in [[Elections]]. The message that is shown is: "(creature name) has been elected to the position of (position name)"

In worldgen, there is no functional difference between ELECTED and non-appointment, except that elected nobles tend to have high social skills and/or skills related to the position, while non-elected ones are assigned randomly. See: [[Elections]]

A succession goes before an election.

A position that is both ELECTED and APPOINTED_BY never gets elected. Even if the appointees' position somehow gets filled, (re)-elections won't happen. So, it doesn't seem possible to have an elected position become available when a certain other position becomes filled.

An ELECTED civ-(or LAND_HOLDER) position at your site will never be (re)-elected in fortress mode. So real (re-)election only works with SITE-positions.

=== {{text anchor|Election Day}} ===
Election Day takes place on the 17th of Summer. On this day, a full reevaluation is performed, including all currently elected positions, which are subject to re-election. Contrary to the information on [[Elections]], nothing occurs at the start of a season.

Positions that are both [APPOINTED_BY] and [ELECTED] will not be re-elected on Election Day when assigned through [SUCCESSION].

=== Election Eligiblity ===
Any citizen may stand for election. Eligibility cannot be restricted using [ACCEPTED_CREATURE], [REJECTED_CREATURE], [ACCEPTED_CLASS], [REJECTED_CLASS], or [GENDER]. Units currently having a [SUCCESSION]-position even may be elected for a position with a [SQUAD]-token, which is otherwise impossible to assign or even succeed.

=== Skills ===
In elections, skills are taken into account for the tokens of the position which is elected.
{| class="wikitable"
|+ Relevant skills per position token
|-
! Position Token !! Relevant skills
|-
| Responsibility [[Position_token#DELIVER_MESSAGES|[DELIVER_MESSAGES]]] || [[Ambusher]], [[Observer]] and [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#ACCOUNTING|[ACCOUNTING]]] || [[Record_keeper|Record keeper]]
|-
| Responsibility [[Position_token#ESPIONAGE|[ESPIONAGE]]] || [[Schemer]]
|-
| Responsibility [[Position_token#HEALTH_MANAGEMENT|[HEALTH_MANAGEMENT]]] || [[Diagnostician|Diagnostician]]
|-
| Responsibility [[Position_token#MAKE_INTRODUCTIONS|[MAKE_INTRODUCTIONS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#MAKE_PEACE_AGREEMENTS|[MAKE_PEACE_AGREEMENTS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#MAKE_TOPIC_AGREEMENTS|[MAKE_TOPIC_AGREEMENTS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#MANAGE_PRODUCTION|[MANAGE_PRODUCTION]]] || [[Organizer]]
|-
| Responsibility [[Position_token#MEET_WORKERS|[MEET_WORKERS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#RECEIVE_DIPLOMATS|[RECEIVE_DIPLOMATS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#RELIGION|[RELIGION]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#TAME_EXOTICS|[TAME_EXOTICS]]] || [[Animal_trainer|Animal trainer]]
|-
| Responsibility [[Position_token#TRADE|[TRADE]]] || [[Social_skill|Social skills]] and [[Appraiser|Appraiser]]
|-
| [[Position_token#SQUAD|[SQUAD]]]-token || [[Tactician]] and [[Leader]]
|}

==Assumption==

A position that is not APPOINTED_BY nor ELECTED, or is appointed by positions that are not available in your site or civ, will be assumable by a random dwarf. If it has responsibilities that require certain skills, then these are taken into consideration on embark, but not when the position is assumed during the actual game.

Normally, one to three units will take the into consideration to assume a position. Most of the time when there are multiple open positions, only a single unit will assume all of them. However, a position that has REJECTED_CREATURE, REJECTED_CLASS, ALLOWED_CREATURE or ALLOWED_CLASS will be filled with all different units, even if the creature or class mentioned is irrelevant. It seems that this forces the game to loop over all the available units.

The message that is shown in Legends mode is: "(unit name) has assumed the position of (position name)". This may also take place in fortress mode, which then shows this message to the player.

If an assumable position becomes empty, it will be assumed within a day. This is the case when you leave the position of expedition-leader vacant. It also happens with entities.

Assumable positions that become empty will not be assumed if that position has a valid [SUCCESSION] -successor. In that case, the successor inherits the position.

Even positions that are somehow invisible because they cannot be directly APPOINTED_BY players, can be assumed.

When you embark, the assumable positions are automatically assigned to a random unit. If there are multiple of these positions at embark, they all are assigned to the same unit. If there are enough positions available, multiple units may gain a position, but often no more than three different ones.

If a dwarf in fortress mode assumes a position, that already has another position, it will leave the current position empty. When that position also is assumed, then this will continue until all positions have a dwarf appointed to them, with no other position.

A unit that already has a position with a [SUCCESSION] token won't take assumable positions into consideration that have a [SQUAD] token. This can be used by the modder to prevent unwanted loss of current positions.

A position that has an appointer which got replaced because of REPLACED_BY, will not become assumable. Also, positions that have an AS_NEEDED appointer that is not yet filled (or ever), will also not be assumed.

==Succession==

If a position-holder dies or advances to a new position via succession, the position will be granted to another unit based on the [SUCCESSION] tag. If they have an heir or the succeeding position exists, that unit will be assigned. If not, a new one will be appointed according to the usual rules. The message that is shown is: "(creature name) being the rightful heir, has inherited the position of (position name)"

The succeeding creature will also lose its previous position. When succession is defined using BY_POSITION, the unit naturally loses the referenced position. However, it also loses any other positions it may hold. If a unit could simultaneously inherit multiple positions, the last-defined succession overrides the earlier one, clearing the previously acquired position

Succession works both at site-level and at civ-level, both in world-gen and in fortress-mode. Succession by position on the civ-level is also visible and functional in fortress-mode. If both civ-level nobles are a citizen of your fortress, succession is applied visually. Vanilla example: The [[druid]] is succeeded by the [[acolyte]]. This means that as soon as the druid dies, the acolyte takes over.

When a position that is succeeded by position becomes available, immediately it is checked if a position-successor is available and the position is filled with that unit. Even if this is an [ELECTED] position, succession goes first. When elections eventually do happen, succession plays no role.

It is possible to assign multiple levels of [SUCCESSION:BY_POSITION] in different positions, creating a line of positions where the death of one causes all those "below" them to advance.

A position can have multiple tokens with position-succession. It looks to be random which one is used. It is not always:
* The first or last defined token
* The first or last appointed unit
* the oldest or youngest
* one with a higher or lower precedence
* a unit with relevant skills

When a position is defined with a Succession-type, that unit cannot have another position that has a Squad-type. If the succession-position itself has a squad, than it can be assigned another position with a squad, but then it will loose the previous succesion position. See further details by "Squad"

Assumed positions can also be succeeded by position, if the current holder dies.

If the successor is an AS_NEEDED position, the used unit will leave a vacant position-slot on its removal by succession. This empty slot remains a real slot, which will only be cleaned up if you (un)appoint a unit to this position-series. It isn't cleaned up after regular position validation.

A civ-level position of a unit living at your site might be inherited by a unit holding that does not currently live at your site. This, unfortunately, moves that position to a unit off site. This may also happen with the landholder of your site, for example when it is succeeded by another civ-level position. This currently poses an unsolved challenge.

===Eligibility for succession===
Succession is restricted by the tokens [ACCEPTED_CREATURE], [REJECTED_CREATURE], [ACCEPTED_CLASS], [REJECTED_CLASS] and [GENDER].

===Site and civ combined succession===

Succession can work when combining site positions with civ-level positions or land_holders, but only in world-gen mode. In fortress mode, it only works with combining the same level of nobles, with Landholders regarded as civ-level. So, in fortress mode, a site's position cannot succeed a landholder's position and it cannot succeed another type of civ-level position, and vice versa.

This won't work even if the positions:
* are AS_NEEDED or having a fixed number.
* Are LAND_HOLDERs.

===Succession [BY_HEIR]===

When a heir is needed for succession, all children and then other relatives are validated. They cannot take the position if their status does not allow it, for example if they have become a member of another civilisation. See: "Who can take a position". If the unit has no valid heir on that location, the position may go to a unit living on another site. This may cause the title of Landholder of some land to be inherited by a unit living somewhere else. That might be a problem, because then you lose your landholders.

===Premature Succession===

There are cases where [SUCCESSION:BY_POSITION] is applied prematurely: at the moment a position is first created and becomes appointable or assumable, rather than after a current holder leaves. In this situation, the succession mechanism assigns a holder immediately, without any player interaction.

When a position becomes available for the first time, the game checks whether a valid successor-by-position exists. If so, that unit is assigned instantly. It can affect positions that would normally be appointed or elected by the player, causing succession to trigger before the player has any opportunity to intervene.

This behavior occurs only in Fortress mode, but can be applied both on [SITE]-positions as well in civ-positions. That last one however is a bit harder to control. Example: [[Advanced entity position mechanics#The Archduke|The Archduke]]

This premature succession only occurs the first time a position becomes available (i.e. when it is created and becomes appointable or assumable). Even if the position remains vacant and the conditions for succession improve later, premature succession will not trigger again. From that point onward, only normal succession rules apply.

Using premature succession, a position that has [ELECTED], [APPOINTED_BY], or both, can be filled directly.
Notably, positions that combine [ELECTED] and [APPOINTED_BY] are normally impossible to fill through regular mechanics. Premature succession bypasses both election and appointment entirely, making this combination uniquely reachable through this mechanism.

No initial election takes place, and no subsequent elections will ever occur for that position. Succession always takes precedence over election, both in premature succession and in normal succession cases.

This behavior applies only in Fortress mode, not during world generation. World-gen uses simplified and more efficient mechanics, and this interaction does not occur there. Premature succession can affect both site-level and civilization-level positions.

====Multiple succession chains====

Multiple succession chains may be defined and are resolved in the order they appear in the raws.

If a position has both:
* a direct succession chain (A → C), and
* a multi-step chain (A → B → C),

and intermediate positions are vacant, resolution proceeds according to raw order. A common outcome is:
# The direct succession (A → C) is applied first, assigning A to C.
# The remaining chain then advances (A → B).
# If C still has empty slots, the final step (B → C) may occur.

If position B is already filled, behavior depends entirely on raw definition order:
* nothing may happen, or
* B may move to C first, followed by A moving to B.
====Working triggers====
Premature succession is triggered when a succeedable position is created under the following conditions:
* The succeedable position is created because its [REQUIRES_POPULATION] threshold is reached. This applies even if the position is not [APPOINTED_BY]. Premature succession takes priority over automatic assumption (e.g. the mayor declaring themselves within a day).
** The position must either be assumable or appointed by an existing position. When said appointer-position also just has been created, the premature succession of the succeedable position happenes, even when the appointer-position is empty.
* The succeedable position can be [APPOINTED_BY] another position of the same level (site or civ) that has just been created because its [REQUIRES_POPULATION] was reached.
* The succeedable position can be appointed by another [SITE] [AS_NEEDED] position that has just been created and filled.
* The succeedable (site or civ) position is [APPOINTED_BY] the [LAND_HOLDER] position, which has just been created due to site elevation. This typically resolves when the diplomat leaves the map, at which point the landholder position becomes active.
* If all other requirements are met, premature succession can occur immediately after unpausing following embark, for positions with [REQUIRES_POPULATION:7].

====Non-working triggers====
Premature succession does '''not''' occur in the following cases:
* An [AS_NEEDED] succeedable position slot is manually created by the player while its succeeding position is already filled. [AS_NEEDED] positions must always be appointed after creation.
* The succeeding position is filled after the succeedable position becomes available. The moment of creation is the decisive trigger; filling the source position later is too late.
* The succeedable position can be appointed by another site or civ position with a fixed number of slots that has just been appointed. In this case, the succeedable position is just available for appointment itself, nothing more
* Any situation occurring during world generation.
* The succeeding position is [REPLACED_BY] the succeedable position. In this case, replacement removes the unit from the source position first, leaving no holder available for the succession mechanism to use.rst, leaving no holder available for the succession mechanism to use.
* The position is [APPOINTED_BY] a civ-level position, that just became a citizen of your fortress. It must be noted that those civ-level positions were active all that time and the succeedable position could be appointed even before. The monarchs arrival does not trigger premature succession

=Losing a position=

A unit can lose a position when:
* It dies
* It succeeds another position, even if it has nothing to do with the previous position.
* It is assigned to another SQUAD-holding position
* It is convicted of a crime.
* Another unit is ELECTED for the position
* Its position becomes replaced
* Another unit is appointed by the player, or the position is left vacant.
* It has assumed another position, as this always leaves the previous position vacant.

=Embarkment=
Two types of positions are automatically filled by embark.
* Positions without [APPOINTED_BY] or [ELECTED] (assumable). All these positions, even with a NUMBER higher than 1, are all filled with one to three dwarves. Contrary to assumption, this doesn't take into account any limitations. REJECTED_CLASS, ALLOWED_CLASS, REJECTED_CREATURE, ALLOWED_CREATURE and GENDER are applied, but without the normal spread you may expect with assumptions. Also it doesn't look at [SUCCESSION] and [SQUAD] limitations.
* Positions that are elected are filled-in by the normal election rules.

Positions that have a defined appointer are never initially filled at embark.

All positions that don't have [REQUIRES_POPULATION] or with a [REQUIRES_POPULATION] of 7 or lower, will be available at embark.

=Land Holders=

A Landholder is a '''special civ-level noble''' who gets a certain piece of land to hold, when that land is elevated to a certain level, determined by the tag [LAND_HOLDER] and by the landholder triggers in the game's settings. In vanilla, these are the baron, the count and the duke.

A unit gaining the landholder position does not migrate to that specific named land. In world-gen, they stay just where they are, probably at the capital. In fortress mode, you can suggest a citizen for the role. So for the time being that works.

Succession is then a real issue. If you use BY_HEIR, its solved when that landholder has children living at your site. But when its not the case, the title just goes to anyone randomly. Succession BY_POSITION works, but only in the civ-chain, and there's no way to guarantee a civ-holder is at your site at that time. Even with 'automatic spread' positions, it goes to one of them randomly.

==Functioning of the regular landholder chain==

The distinct difference between a landholder and a regular civ-level noble, is that a landholder may gain the position of landholder "of (sitename)" They are then seen as ruler of a particular site.

For a land_holder position to function as such, it has a few requirements:
* NUMBER:AS_NEEDED
* The first landholder-number of 1 is defined.
* No SITE (so civ) tag in that position.
*REPLACED_BY the next level landholder
If a landholder is defined with differentiating properties, it will function like a regular noble. A higher-up landholder that lacks the required tokens or connections will then not be used in elevation.

If a fortress meets the trigger for a new LAND_HOLDER tier when a caravan leaves, then the next time the outpost liaison or equivalent arrives, they will offer to make you an official colony, which will allow you to select all positions for that LAND_HOLDER level. Each time they appear, the outpost liaison will only promote your fortress one tier up the LAND_HOLDER track.

The landholder's LAND_NAME is not required for the functioning of this system. If omitted, messages will be shown with a more generic text.

==Appointment==

This mechanism differs from the regular methods of position management. It ignores all regular appointment- and election rules, so it more or less functions like automatic assignment. A landholder is, in vanilla, appointed by the monarch. Changing this doesn't seem to do anything. If they are appointed by a site-position, a not-yet-existing civ-position, or not appointed at all: the system keeps working as usual.

A landholder can appoint civ-positions and site positions. This works as expected: the positions only are appointed then when that landholder becomes available on civ-level or when he arrives at that site for site-level positions.

If your rank of landholder is the first of its rank in the realm, and is the sole appointer of some civ-position, then immediately as it gains the title, it will appoint the empty civ-slots. This may happen on your site, but the frequency and certainty is hard to determine.

==Succession==

Succession rules are applied to some extent:
* In world-gen it works according to succession rules, and site-positions can be used here. This means that a site position or a civ-position can inherit a landholder position, and vice versa.
* In fortress mode, once a landholder has been appointed, it then can inherit civ-level positions, and vice versa. This means that your baron can become king.
* Succession rules do not apply within the [LAND_HOLDER] chain; a count will not inherit a baron's land. This is because succession does not work well with the AS_NEEDED token.
* Premature succession works in fortress mode with landholders. If a unit gets a landholder's position and that landholder is the appointer of an as yet empty position, which is defined as succeeding from a third one, then the succession is immediately applied. The landholder themselves can even be the successor of a newly created position.
* A landholder's position is, in fortress mode, not successionable by a site-position or vice versa

===Impossibilities for succession by a site-position===
It would be very beneficial if the landholder can be succeeded by a [SITE]-position. So far, the following tests have not lead to positive results:
* making landholder and site-position both non-[DUTY_BOUND]
* make the site-position be [APPOINTED_BY] the landholder and/or the monarch
* give landholder and site-position [REJECTED_CREATURE]
* Let the monarch live at your site when succession could happen.
* Let the site-position be [REPLACED_BY] the landholder.

If the vanilla [SUCCESSION:BY_HEIR]-tag is omitted, a seemingly random unit somewhere in the realm is assigned this position.

==Nomination==

The player is able to nominate a unit to become the LAND_HOLDER, but this only works with units of [LAND_HOLDER] level 1. The player can select all units, only limited by the PRECEDENCE of the current units' positions.

A unit that has a position with a PRECEDENCE lower or equal to that of the landholder's position, cannot be selected. This means that a baron (or count) from another site or the monarch cannot be selected, because their precedence is lower or equal.

The GENDER token does not work here: also units with the wrong gender (sorry) can be selected.

==Levels==
In mods, up to 10 levels of LAND_HOLDER may be defined.

If a landholder is replaced by a wrong landholder number (1 replaced by 3), then the number 3 is still correctly attached to the settlement.

If the current landholder has the highest available landholder number, then the next elevation will not happen - the diplomat will not elevate your fortress to a higher position, even if that position might be REPLACED_BY a lower landholder.

These chains do work:
* 1 -> 2a - > 2b -> 3
* 1 -> 3 -> 2 -> 4

These chains do not work:
* 2 -> 3 (need to start at 1)
* 1 -> 4 -> 2 -> 3 (stops after 4 as the highest)
* 1a -> 2, 1b -> 2 (only 1a and 2 work, 1b is not used)

==Moving landholders==

It may happen that a land-holder no longer lives at the site which they are the landholder of, specifically when the current landholder dies, leaving the title to an heir living somewhere else.

To prevent this from happening, you can make their succession from heir and make sure that their kids live at your site. Or, you can make their position succeeded by another civ position, and make it so that this civ position is somehow available on your site. But if multiple of these positions exist, it cannot be guaranteed that a citizen of your fortress will inherit the title.

In world gen, a landholder lacking the DUTY_BOUND-token will also move to the site they like, according to legends mode.

==Replacement by a generic civ-position==

If a landholder is replaced by an AS_NEEDED non-landholder civ-position, then this will work: the current landholder loses that title upon settlement-elevation and gains that civ-title. However, the civ-title lacks the landholder-property of being attached to the land. It will not show the name of the settlement alongside the position's name. So no "minister of Shovelmounts"

If a landholder is replaced by a general AS_NEEDED civ-position, that itself is also replaced by a generic AS_NEEDED civ-position, then firstly the elevation is executed and also the unit gains that new position. However, he immediately loses it, because an AS_NEEDED position that is replaced by another position can be filled initially, but units wont be able to hold that title.

==Landholder with fixed number==

A landholder's position that has a fixed number will be created and filled directly when the civilisation is born, so this position slot is then not available for the regular landholder-mechanic and will also not be used. That landholder will thus not be attached to a settlement.

It doesn't matter if the landholder's position is connected to the regular landholder's-chain with the REPLACE_BY token.

==Responsibilities==

When given a certain [RESPONSIBILITY], a landholder may function as a regular civ-level noble. If the position has [TRADE] or [OUTPOST_NEGOTIATING] responsibilities, then the landholder functions both as a diplomat and as an actual land holder. A landholder with the [MILITARY_STRATEGY] responsibility will travel around taming creatures in world-gen, according to legends mode.

Besides that, the responsibilities work the same as with any other on-site living position-holder, civ or otherwise.

=Military=
==Squad management==
In the vanilla game, the Squad interface only becomes available after a militia commander has been appointed. Until then, the window displays:{{DFtext|You must appoint somebody first to create a squad.}}

What’s surprising is how this is determined internally. In the entity raw definition, '''only the last two positions that include a [SQUAD] token are checked''' to decide whether the interface is accessible at all. As a result, if your hierarchy defines commanders A through E, appointing '''Commander D or E''' unlocks squad formation, while appointing A–C does nothing.

In other words, squad availability is not tied to ''having a militia commander'', but to ''which specific positions happen to be last in the raw list''—a notably hacky implementation.

These 'last two' are always the last two '''available positions.''' So if they get [REPLACED_BY] or become available because of [REQUIRES_POPULATION], the game adapts to those.

==Squad assignment==

Squads can be assigned, even if the leader position has no holder.

A specific unit can only have one position associated with a squad. If it gains another 'squad holding position', it is unassigned from the first one. This does not work with a 0-squad, so only 1+squads are taken into consideration. This technique can possibly be used to distribute all positions equally among all citizens. It does however not work with election and assumption.

If a civ-level position is associated with a squad and it gets a site-level squad-holding position assigned, it loses the current civ-position.

Squads can get really messed up, if you make the position (or multiple) either elected or not-elected and not-appointed, then this can cause the game to assign multiple squads to the same unit. Automatic assignment and election does not take squads into account, but the nobles screen does. This can cause the positions to be cleared as the game figures out that they have more than one position, and immediately get elected or assumed again.

Positions that cannot have a squad-position:
* A site- or civ-position with a [SUCCESSION] token cannot be appointed a squad-holding-position. The other way around, however, does work. For example, if a site-position with a [SUCCESSION]-token is appointed to a unit that has already a position with [SQUAD]. But when that squad position is assigned to another unit, it cannot be assigned back.
* A position with [SUCCESSION] can also not be assigned as a '''member''' of a squad.
* A squad-holding position with a formed squad cannot be appointed to another squad holding position.

If a position has at least one squad member, it cannot be left vacant. First, the squad has to be disbanded, then the position may be cleared.

==0-squads==
A 0-Squad is defined in a position as [SQUAD:0:member:members]. It does not seem to do anything useful as of now.
* It cannot be used to activate the [[Squad|military interface]]
* It does not restrict the assignment of [SUCCESSION] positions.
* Assigning this position does not clear any previously held squad position.
* The [[Leader]] and [[Tactician]] skill are not marked as relevant skills and are not taken into account in elections.
* It cannot be formed as a squad.

=Further testing=
The following questions may need additional testing. Feel free to add or answer
* Everything regarding COMMANDING and army-structure
** [http://www.bay12forums.com/smf/index.php?topic=175437.msg8331668#msg8331668]
** [http://www.bay12forums.com/smf/index.php?topic=165213.msg8335682#msg8335682]
** [http://www.bay12forums.com/smf/index.php?topic=174584.msg8026854#msg8026854]
* Stuff about the monarch, its arrival and its entourage.

=Oddities (Bugs)=
Almost everything on this page could be called an oddity. Because of their unexpected usability, some may also be referred to as “undocumented features.” Others, however, are simply odd and not particularly useful, yet I hesitate to call them “bugs.”
* If a certain threshold is reached that makes an elected position electable, and the triggering event that initiates this evaluation is an assumption, then the resulting assumption is also referred to in the messages as an election

=Examples=

===The Founder===
The founder is a single dwarf, appointed at embark. They will be the only one ever to have this position and are not replaceable. When they lose their position some way, the position will not be assumed by another dwarf.
{{gamedata|title=The Founder|
[POSITION:THE_FOUNDER]
[NAME:the founder:founders]
[NUMBER:1]
[SITE]
[ALLOWED_CREATURE:DWARF:ALL] - will only be filled at embark, but not assumable later.
[REJECTED_CREATURE:DWARF:ALL] - will only be filled at embark, but not assumable later.
[SUCCESSION:BY_POSITION:THE_FOUNDER] - not unassignable, also cannot be assigned to a [SQUAD] position.
[PRECEDENCE:200]
Non APPOINTED_BY
Non ELECTED
Optional: Add responsibilities to make the game select a unit with certain skills.
}}
===Marriage bar===
Dwarven matrons are held in great honour. Upon marriage, a female dwarf is no longer expected to perform menial labour. All dwarven males hold this position by default, granting their spouses exemption from menial work.

The position becomes available with the arrival of the first migrants; otherwise, on embark, it would be assumed by females. Its succession rule is non-functional, but this prevents the player from unassigning the position. A squad size of 1 and the succession rules together prevent a unit from assuming the position more than once.

With precedence set to NONE, the position name is hidden, while LAND_NAME remains visible on the nobles screen. All married females receive the suffix “, Mrs.” and are marked as Nobles.

The practical usefulness of this position is debatable, but it serves as a clear demonstration of several mechanics.
{{gamedata|title=Mrs. Urist|

[POSITION:MRS_URIST]
[NUMBER:300]
[SITE]
[ALLOWED_CREATURE:DWARF:MALE]
Not APPOINTED_BY
Not ELECTED
[LAND_NAME:Dwarven male]
[NAME:dwarven male:dwarven male]
[PRECEDENCE:NONE]
[SPOUSE_FEMALE:, Mrs.:spouses]
[MENIAL_WORK_EXEMPTION_SPOUSE]
[REQUIRES_POPULATION:8]
[SUCCESSION:BY_POSITION:MONARCH]
[SQUAD:1:member:members]
}}
===The Archduke===
The archduke is the leader of the civilization, but exists only from landholder 4-level. Until then, its position remains vacant. When a settlement is elevated to tier 4 (grand duke), the grand duke can appoint the ruler of the civilisation, the archduke. Because of 'Premature Succession', they themself inherit that position immediately, but only when in fortress mode. Its heir then becomes grand duke.
{{gamedata|title=The Archduke| no POSITION:MONARCH or other PRECEDENCE:1

[POSITION:THE_ARCHDUKE]
[NAME:archduke:archdukes]
[NAME_MALE:archduke:archdukes]
[NAME_FEMALE:archduchess:archduchesses]
[LAND_NAME:a archduchy]
[NUMBER:1]
[PRECEDENCE:1]
[SUCCESSION:BY_POSITION:GRAND_DUKE]
[APPOINTED_BY:GRAND_DUKE]
(add additional monarch-stuff, like spouse name, demands etc.)

[POSITION:GRAND_DUKE]
[NAME:grand duke:grand dukes]
[NAME_MALE:grand duke:grand dukes]
[NAME_FEMALE:grand duchess:grand duchesses]
[NUMBER:AS_NEEDED]
[LAND_HOLDER:4]
// Optional ...
[PRECEDENCE:19]
[LAND_NAME:a archduchy]
[RESPONSIBILITY:LAW_MAKING]
[RESPONSIBILITY:RECEIVE_DIPLOMATS]
[SUCCESSION:BY_HEIR]
[APPOINTED_BY:THE_ARCHDUKE]
(add additional landholder-stuff)

!!add to [POSITION:DUKE]
[REPLACED_BY:GRAND_DUKE]

}}
{{Category|Modding}}
{{Category|Entities}}
{{Category|Guides}}

Advanced entity position mechanics

2026-03-12T11:56:19Z

Joostheger: /* Further testing */

{{Quality|Fine}}
{{Modding}}

= Introduction =

[http://www.bay12forums.com/smf/index.php?topic=182239.0 Discussion thread on the forum]

This page documents observed and tested behavior of entity positions in Dwarf Fortress that is not fully described elsewhere on the wiki. It focuses on advanced interactions between position tokens, including appointment, succession, election, and responsibility handling, across both civilization-level and site-level entities.

The mechanics described here are based on empirical testing in world generation and fortress mode, supplemented where necessary by raw analysis. In several cases, the game’s behavior is determined by evaluation order and interaction between multiple tags, rather than by individual tokens in isolation.

This page is intended for modders and advanced players who are designing or debugging custom entity position structures. It does not restate basic position mechanics, but instead highlights edge cases, non-obvious interactions, and behaviors that may appear inconsistent or undocumented.

Unless stated otherwise, the described behavior applies to current versions of the game and may differ from older releases.

==What is an entity? What is a position?==
An [[entity]] is an organizational structure that can have relationships with other entities, usually known as a [[civilization]] or a "[[site]] government" in the game, but merchant [[guild]]s, religious organizations, necromancer towers, and [[bandit]] groups are also entities. An entity can have positions - in most cases, these are hardcoded and generated by the game, but as for civilizations and sites, the [[raw file]]s can be customised.

A position is a special relationship between a unit and an entity. The unit holding a position has a larger influence over that entity than other citizens. Positions are mostly known as [[nobles]], but in this article. the technical term is used.

=Position levels (Site/Civ) and their interaction=
There are two basic types of positions that are customizable: '''civ(ilization)''' level and '''site level'''. Positions with the tag [SITE] are at site level, positions without the tag [SITE] are at 'civ level'. These two types of nobles can be considered '''loosely related systems'''. There are a few places where they can interact with each other.

Civ-level positions are in charge of the civilization as a whole, managing national [[trade]], laws, and [[war]]s. These are, for example, the vanilla [[monarch]], [[diplomat]] and [[general]]. (Note that the general doesn't do anything in either mode in the current version.)

'''[LAND_HOLDER]''' nobles are also positions at civ-level. These units are members of the national government, but have gained authority over some land or site. Once they do, they move to that place, but their position is still regarded as a civ-level position.

Site-level position holders are members of a site government (subsidiary to the civilization), and manage local affairs in that location. These are, for example, the [[mayor]], the [[sheriff]] and the [[broker]].

==Table of interaction between different position levels==
In this table, the possible interactions between different position levels are summarized.
The header row shows the positions defining the tokens.

The left column shows the position type that is referred to.
Example:
{| {{prettytable}}
|- bgcolor="#ddd"
! referred position-type
! LAND_HOLDER
|-
| civilization
| (baron is) APPOINTED_BY:MONARCH
|}
color coding: 
* Exists in vanilla
* Possible with mods
* Not possible
* possible to some extent.
* not yet fully investigated.
{| {{prettytable}}
|- bgcolor="#ddd"
! referred position-type
! Civilization
! SITE
! LAND_HOLDER
! CONQUERED_SITE

|-
| Civilization
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION '''(1)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION

|-
| SITE
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION '''(2)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY '''(3)''' COMMANDER REPLACED_BY SUCCESSION '''(4)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION

|-
| LAND_HOLDER
| APPOINTED_BY COMMANDER REPLACED_BY '''(6)''' SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION '''(5)'''
| APPOINTED_BY COMMANDER REPLACED_BY '''(7)''' SUCCESSION '''(8)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION

|-
| CONQUERED_SITE
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
|}

Remarks:
# Works only in world-gen, if a unit with that civ-position is present at the site.
# Works only in world-gen, the site-position holding unit will then move to the capital.
# Is completely ignored
# Works only in world-gen.
# Works only in world-gen.
# Won't appear at all
# This is necessary for the landholder chain to work properly, it doesn’t work otherwise.
# This works only outside of the landholder chain, so when landholders are simply regarded as civ-level nobles. might also work in world-gen
#

== Other interactions ==

Unfortunately, interactions with positions of other entities don't seem possible, such as APPOINTED_BY: HIGH_PRIEST. With [VARIABLE_POSITIONS], positions are automatically created with codes like CUSTOM_LAW_MAKER_2, but interaction with these positions don't seem to work, either. For more info on those, see [[Variable positions]]

=General=

==Civ-level nobles living at your site==
Nobles from your civilization can come to live at your fortress. This happens in vanilla with landholders such as [[Baron]], [[Count]] and [[Duke]], with the Monarch, but sometimes also with non-landed LAND_HOLDERS.

When a civ-level noble becomes a [[citizen]] at your location, their position is shown among the site-level positions in your [[nobles screen]]. They appear to function as a site-level noble. They may have [[demand]]s, [[mandate]]s, [[squad]]s and the like. They can appoint nobles at the site-level.

If they have certain [RESPONSIBILITY]ies, they do the tasks that go with them.

==Fortress mode, world-gen and their differences==
Their are a few differences in how positions function between fortress mode (normal play mode) and the world generation (world-gen).

In '''fortress mode''', the player has some control over the appointment of nobles, limited by elections, automatic filled-in positions and succession rules. Pre-fortress mode, which is referred to as '''world-gen''', the game will always attempt to assign nobles whenever possible. It is subjected to the same rules as in fortress-mode, but there are some exceptions. In '''[[World activities]]''', which is the thing that happens in the world while you play fortress mode, it seems as if the same rules are applied as fortress mode.

A difference between player-fortress-mode and world-gen, is causes by visibility (see below). Positions that are not visible by the player and thus not available for assignment, will be available in world-gen and will thus be automatically assigned.

In fortress mode, a position that is both [ELECTED] and [APPOINTED_BY], cannot be appointed by the player and is also not elected, and can thus not be filled. But in world-gen sites however, these positions are automatically filled.

Positions with [AS_NEEDED] are almost never created and filled in world-gen (depending on their [RESPONSIBILITY]ies), but can always be used in player mode.

A position can, in fortress mode, be filled by the same unit. A unit can gain multiple positions in fortress mode, for example because of [[elections]]. This will not happen in world-gen mode: a unit can only have one position. See also remarks on 'embark' and 'Losing a position'.

In world-gen, [SUCCESSION] between civ-levels and [SITE-]levels may happen. This will not happen in fortress mode, or even off-site in [[World activities]].

In fortress mode, premature SUCCESSION may happen. This will not happen in world-gen mode.

==Units holding multiple positions in multiple entities==
A unit can hold multiple positions in its civilisation or in its site-entity, however this does not happen in world-gen. Only at player-managed sites can units be holding multiple positions at once. (It is probably not possible for a unit to hold a position in two different civilisations or two different sites.)

In world-gen, if there are too many positions to be filled, they simply stay empty until more units are available. E.G, a unit at a site might inherit a civ-level position and still remain a member of the local government. When this happens however, they move to the capital. If a unit gains a new position, either inherited or otherwise, it drops the previous one. If a unit assumes a civ-position in fortress mode, it leaves the current position.

If a unit holds the same (site-)position multiple times, it has no additional effect.

If a unit holds multiple different positions of the same entity, it has all those positions' responsibilities and properties, stacked up. Presumably, the demands for those combined positions are determined by the highest.

A unit holding a position with a succession token can be assigned another position with a (different) succession token.

A unit holding a position with a squad-position cannot hold another squad-position. It is dropped from the first, when it gets its second assigned.
A unit holding a position with a succession token cannot be assigned to a squad-position - the unit is simply not available. It works the other way around, though.

=Specific Tags and functions=
==[PRECEDENCE]==
The first defined position with precedence of 1 counts as the ruler of the civ. See also: [[Position_token#PRECEDENCE|PRECEDENCE]].

If the precedence is omitted or has a negative value, the game sets 0 as precedence, which seems to have no effect whatsoever.

When a unit has multiple positions, the name of the position with the highest rank in precedence is shown behind the unit's name.

If you omit precedence entirely, or set it to [PRECEDENCE:NONE], the position name will not be shown after the unit’s name. Your *Urist Mason* will remain simply *Mason*. This can be useful for positions that are unimportant or purely functional. The position will also not appear in the civilisation overview of your site on the world map. The position name is shown in messages, but remains hidden on the nobles screen as well. To make it visible there, use [LAND_NAME].

==[RESPONSIBILITY]ies==
Both civ and [SITE] positions can carry responsibilities. However, not all responsibilities are active for both types: some function only for civ positions, others only for site positions. When a civ noble arrives at a site and takes up residence, they do not perform responsibilities that are intended for SITE nobles. As a result, these responsibilities neither trigger their associated tasks nor unlock related game mechanics. For example, a civ-level manager living in a fortress will not perform management duties there and doesn't unlock the management-screen, even with an assigned office.
This behavior applies to the following [SITE]-level responsibilities:
* [RESPONSIBILITY:ACCOUNTING]
* [RESPONSIBILITY:BUILD_MORALE]
* [RESPONSIBILITY:HEALTH_MANAGEMENT]
* [RESPONSIBILITY:LAW_ENFORCEMENT]
* [RESPONSIBILITY:MANAGE_PRODUCTION]
* [RESPONSIBILITY:MEET_WORKERS]
* [RESPONSIBILITY:TRADE] (functions differently)
Other responsibilities may be affected as well, but have not yet been fully tested.

===World-gen effects of the [RESPONSIBILITY] of available positions ===
It is possible to cause civs and individual sites to change their behavior substantially when they reach a certain size, by controlling nobles.
* If a site can only appoint a position with [MILITARY_GOALS] after reaching a particular size, that site will not send armies on missions until the required size is reached.
* A civ-level [LAW_MAKING] position is required for the civilization to have any kind of cohesion. Without it, sites will be constantly embroiled in territorial disputes and civil wars will be commonplace.
* [MILITARY_STRATEGY] positions go out and tame wild animals. This makes your civ gain those animals as domesticated and also brings them in sieges.
* The [[Personality_facet|Personality]] of the position's holder determines how they lead the civ.

===[DELIVERS_MESSAGES]===
The only [AS_NEEDED]-position that is created in worldgen based on responsibility is that of the site-level responsibility [DELIVERS_MESSAGES].

===Outpost Liaisons and Diplomats===
Civ-positions with the responsibility [ESTABLISH_COLONY_TRADE_AGREEMENTS] ([[Outpost_Liaison|Outpost Liaison]]s) will meet with the site-noble who has responsibility for [RECEIVE_DIPLOMATS] and the highest rank of precedence (i.e. the lowest precedence value). Usually this is the [[Expedition_leader|Expedition leader]].

Once a [LAND_HOLDER] is assigned to the site, civ-positions with the responsibility [MAKE_TOPIC_AGREEMENTS] ([[Diplomat]]s) will meet with '''civ'''-level nobles present at the site who have the [RECEIVE_DIPLOMATS] responsibility. If multiple eligible nobles are available, one is selected at random. If no eligible noble is present, the diplomat leaves angrily. If the landholder is no longer present at the site, diplomats will not arrive at all.

It appears that Outpost Liaisons and Diplomats are chosen for a diplomatic mission based on availability. When multiple candidates exist, the position defined last in the raws is most often selected.

===[TRADE]===
Civ-level nobles with [TRADE] will arrive with the caravan, just as the Outpost Liaison. Their behavior is no longer active in the vanilla game, but the mechanics are still present. See [[40d:Guild_representative|Guild representative]] for more details. This civ-noble will only meet with the SITE noble with [TRADE], usually the [[Broker]].

If two civ-nobles exist with both [TRADE] and [ESTABLISH_COLONY_TRADE_AGREEMENTS], they both arrive at the same time. Even if both tokens are assigned to a single position, if more than one instance of that position exists, two of them will arrive. However in that case, somehow the elevation of the site and appointment of landholder isn't offered.

If the SITE-noble they intend to meet has both [TRADE] and [RECEIVE_DIPLOMATS], only one meeting will proceed and the other is cancelled. However, when two SITE-nobles are available, each with either [TRADE] or [RECEIVE_DIPLOMATS], both meetings will proceed and both civ-nobles will attempt to negotiate a trade agreement. It is not known what happens if these agreements are accepted or refused.

In the trade depot, the last defined position with the [TRADE] responsibility is shown as broker. However when requesting a trader, the first defined position with [TRADE] will actually go there to do the trade.

==[NUMBER]==
A position might be defined with a number. In that case, as many as defined can be available. If the positions become available, in world-gen and when embarking, they are all filled-in completely.

If the ruling position (with PRECEDENCE of 1) has a NUMBER higher than 1, a random unit of the ones holding these positions is shown as ruler in the embark screen.

A [NUMBER] of 0 (zero) has the same effect as 1.

===Automatic spreading of assumed, non-singular positions===
If there are civ positions that have a NUMBER higher then '1' and which are assumed (not APPOINTED_BY or ELECTED) but are '''not DUTY_BOUND''', these are automatically spread among the civilisation, based on population. If there are a number of '''20''' available slots of that position, they spread among a civilization with a combined population of, for example, 1000 of which your fortress has 100 (10%), '''2''' of your fortress' citizens will assume that position.
This may probably also work with elected and appointed positions, but that may be depending on the death of the current holders and this needs more testing. Assumption works within a day, anyway.

===[AS_NEEDED]===
These positions can be created automatically by the game in world-gen. This, however, only works with:
* [LAND_HOLDER]'s
* squad commanders (needs more testing)
* Messengers at sites

For all other types of positions, they're not created in world-gen, even if they are defined with RESPONSIBILITY's. For example, even in war, the game wouldn't create a MILITARY_GOALS position, if they have AS_NEEDED as number.

However, in fortress mode / player mode, these positions can be created by the player at will.

Positions with AS_NEEDED need to be created first, before any symbols are assignable as 'symbols' (objects) for the position holder to carry or wear.

Positions with AS_NEEDED cannot be created and then ELECTED in fortress mode. It only works with APPOINTED_BY.

==[REPLACED_BY], [REQUIRES_POPULATION], [REQUIRES_MARKET]==

The token [REPLACED_BY:position] means that once the replacing position meets its requirements for activation, the 'to-be-replaced' position will disappear. This is defined in [REQUIRES_POPULATION] or [REQUIRES_MARKET]. The tags are closely related to each other and seem to only have a meaningful function if combined. Nobles with [REQUIRES_POPULATION] require the population to have a specific size. Nobles with [REQUIRES_MARKET] are only activated in market sites, such as fortresses or towns. [REQUIRES_POPULATION] and [REQUIRES_MARKET] can be combined, activating that position once both requirements are met.

The [REQUIRES_MARKET] can be used to differentiate positions between hamlets and hillocks, and larger sites. IThe market always is build the year after the site is founded. So a position that is to be replaced, will be gone immediately.

The [REQUIRES_POPULATION]-tag works on the civ-level as well as on site-level, but those systems are in this mechanic strictly separated. Site-level positions cannot be replaced by civ-level positions and visa versa. This makes sense, because they both depend on their own population-count. When using REQUIRES_POPULATION on civ-level, it counts the total population of the civilisation.

See also: [[Advanced_entity_position_mechanics#Evaluation_of_Positions|Evaluation of positions]]

===Effect of replacement (and on [LAND_HOLDER]s)===

Replacement is immediate and complete - the current holding unit loses the position, even before SUCCESSION_BY_POSITION rules are applied. A position with a number of 1 will replace all the slots of a position with a higher number of slots.

Even if the next position is available but not visible, replacement still takes place. If a position is replaced, it is completely gone - it cannot be appointed, succeeded, elected or assumed any longer.
The unit immediately loses its position.

In legends, replacement is mentioned as: "(unit name) ceased to be (position name)" The replacement of an AS_NEEDED position empties the position's slot forever. In fortress mode, it may seem as if you can create new slots and appoint new units in the nobles screen, but this is reversed as soon as you close the window.

The landholder chain uses [REPLACED_BY] differently. It does not clear the position completely, but uses it for succession to the next level's position. [REPLACE_BY] is required to let that system work properly. This also means that the way in which landholders succeed (replace + as_needed) does not work in any other way.

Replacement between LAND_HOLDERS and other site- or civ positions does not work in any way. Only the vanilla replacement sequence between levels of LAND_HOLDERs does work. If the token is omitted for landholders, the landholder chain is broken, so replacement is required for the landholder system to work.

[REQUIRES_POPULATION] also does not work for [LAND_HOLDER], when you set [NUMBER] to 1. The position is not created when the required population is reached.

===What doesn't work===

'''Attention: If a position cannot be appointed, for example because of 'mutual appointment', it still exists according to replacement mechanics and will replace other positions if so defined. If a certain position(a) will be replaced by the baron's assistant, which can only be appointed by the [LAND_HOLDER] baron, than that position(s) still will be replaced from the start of the game, even if no baron or their assistant is ever present.'''

A position that is replaced by a somehow non-fillable position is still replaced. This counts for mutual-appointing positions, replacement by not-yet-assigned landholders, replacement by AS_NEEDED positions, or replacement by not-yet-appointed positions.

Replacement does not work if the replaced position is a [LAND_HOLDER], even with civ-positions. In that case, the LAND_HOLDER's position is not replaced. It does not matter if AS_NEEDED is used, or a fixed number, and it also does not matter what type of position the replacer is. So this only works (correctly) with positions that become available by REQUIRES_POPULATION.

==[CONQUERED_SITE]==

This tag determines which position is used to assign a [[Forced administrator]].

In legends mode, this is visible as an event describing the reconquest of the site: a new group is formed and the forced administrator is installed as its ruler.

All positions defined with this tag are assigned during this process, meaning multiple positions can be appointed at once.

The holder of a position marked with [CONQUERED_SITE] cannot appoint any other [SITE] positions.

Combining [CONQUERED_SITE] with [SITE] causes the position to function both as a forced administrator and as a normal site position available in fortress mode. However, this provides no meaningful additional mechanics and is effectively inferior to using [SITE] alone:
* [APPOINTED_BY] lines are completely ignored, meaning that the roles are automatically assumed.
* [SUCCESSION] is likewise ignored.
* the [CONQUERED_SITE]-position cannot appoint other [CONQUERED_SITE], [SITE] or combined positions.

There have been remarks that reclaiming a fortress is unplayable because of the lack of regular nobles. Unfortunately, it seems that it can't be fixed by modding.

=Availability and visibility=
==Availability of (new) positions==
Warning: Do not mistake "availability" for "visibility"!

Of all the possible positions existing in your site's entity, there may only be some available.
* Positions with [REQUIRES_POPULATION] require the population to have a specific size.
* Positions with [REQUIRES_MARKET] will only appear in "large" sites (which may have different rules for different site types). This tag has no effect in fort mode.
* Positions that are appointed by positions that have an AS_NEEDED number. The appointable positions only become available after an appointer position-slot is created. This works also on civ-level. If a position is appointed by a Land-holder, it only becomes available, when that level of landholder is created.

Only the replaced positions are culled and are no longer available.
A position that requires a certain population will become available, even if it doesn't have [APPOINTED_BY] or [ELECTED]. In that case, see 'automatic assignment' and 'assumption'

In fortress mode, in some cases 'succession' is evaluated immediately after a position becomes available. See: Succession.
==Visibility of positions==
A position might be available, but can still be invisible for the player in the [[nobles screen]]. The positions with their respective holders are visible for players:
* All site-positions that are already filled-in (even if they could not be re-filled-in considering current conditions)
* Site positions that are appointable by a filled-in site position
* Site positions that are appointable by a filled-in civ position, when that civ positions holder becomes a citizen of your fortress.
* Civ positions of units that are also a citizen of your fortress.
If a position becomes available, for example because a certain pop number has been reached, or if it is available from the start(like expedition leader), as long as it cannot be appointed, it still is INVISIBLE for the player.

It might strike someone as odd if a position becomes filled automatically in fortress mode when that position is not even visible. This might be the case if the current holder of a non-appointable position dies or succeeds another position. Regardless of player visibility, these positions will be automatically filled in if the necessary requisitions are met. It might happen with the expedition leader.

A situation with a non-visible but available position, is for example when a position is solely appointed by the expedition leader, when the expedition leader's position is left vacant. It can no longer be appointed by the player and is invisible. Then, it gets automatically assumed, proving that the position still was available.

A position that is both [APPOINTED_BY] and [ELECTED] is visible, but players cannot interact with it.

={{text anchor|Evaluation of Positions}}=
The game does not continuously check whether positions should become available, elected or be [REPLACE_BY]. This is well-known behavior—for example with the [[mayor]], who does not appear automatically when the required population ([REQUIRES_POPULATION]) is reached. Instead, positions must somehow be evaluated. This applies in several other situations as well

'''Cases that require a trigger:'''
* Election of a newly created position
* Election after the current holder dies
* Automatic assumption of a newly created position (this may take up to a day)
* New citizens (such as migrants) considering available positions
* Premature succession of a newly created position

'''Cases that do not wait for a trigger:'''
* Succession following the death of the previous holder
* Automatic assumption of existing positions that have become vacant

'''Triggers that cause the game to reevaluate noble positions:'''
* Succession of a [SITE]-position due to the death of the current holder
* [[Advanced_entity_position_mechanics#Election_Day|Election Day]]
* Automatic assumption of a [SITE]-position that becomes vacant
* (Re)assigning any site position manually
* Settlement elevation on the LAND_HOLDER track (e.g. gaining a [[Baron]] or [[Count]])

=Gaining a position=
There are several ways a unit can gain a position:
* Appointment: A unit is appointed by another unit or by the player.
* Election: A unit is elected by and among the members of the entity
* Assumption: A position is neither elected or appointed: a random unit just simply 'takes' the position
* Succession: a unit is the valid successor of this position(A), either by its current position(B) or because they are that position(A)-holder's heir.

Available positions will automatically be assigned to a random civ member when a new site/civ is created.

==Who can take a position==

* If so defined, a unit needs to be the right caste and/or class - it does not seem to work with creature types.
* The unit needs to be an adult member of the site or its parent civ's government; that is also CAN_LEARN or INTELLIGENT (SLOW_LEARNER cannot take positions) or otherwise is able to think.

==Appointment==

Positions that have an [APPOINTED_BY:position] token require that position to exist, to be available and appointed. Any position that is APPOINTED_BY can be appointed if the appointer's position is filled in.
For site-positions to be appointed, it is required that the appointer is present at that location.

If the appointing unit is temporarily not present, or if that position is not filled, positions depending on it cannot be appointed. This is the case with [[militia captains]], when the [[militia commander]] is on a [[mission]].

A site position cannot appoint a civ position ''or'' LAND_HOLDER in any way whatsoever.

Civ-level positions can appoint other civ-level positions and site-level positions can appoint other site-level positions.

Contrary to what has been said elsewhere, civ-level nobles also can appoint site-level nobles. They need to be at the site to do so. Landholders can appoint both site-level and civ-level nobles. These systems are therefore not as separate as was assumed.

'''Mutual appointment''' cannot take place. If these are the only requisites of the position, then the positions will never appear or get filled. These unfillable positions can be put to good use, for example, to replace a position that is no longer needed without creating a new one.

'''Self appointment''' doesn't normally work. If you have a position that is only appointed by itself, it is never appointed and also cannot be assumed. However, if the position has a number higher than 1, and is filled by multiple units (for example by another position that is now empty), than those units can re-assign or appoint each other from that their shared position.

If an APPOINTED_BY token refers to a non-existing position's code, the effects are as if the appointment token doesn't exist at all.

===Automatic appointment in world-gen and on the civ level===

Outside of fortress mode, the game will always attempt to appoint nobles whenever possible, as long as these positions are '''available''', even if they are invisible to the player.
It shows this message in legends: "(unit name) has been appointed to the position of (position name)"

In world-gen, all positions become available and are automatically appointed, taking population- and appointment-requirements into consideration.

Positions that are REPLACED_BY are culled and won't be filled.

If a citizen of your fortress holds a civ-level position that can appoint another civ-level position, the appointment will happen automatically and without player intervention. It may happen that another citizen of your fortress is appointed by that unit, creating civ-level position holders in your fortress, but it is unknown what is required to force this effect.

===Manual appointments by players in fortress mode===
In fortress mode, the positions that need to be appointed stay empty on embark. and it is the player's job to appoint those. A player can appoint a unit to any available position, according to the hereabove mentioned conditions. The player takes the role of the automatic appointment-system, but has no direct control over elections, successions and replacement. There are some differences in what is possible at world-gen sites and at player-controlled sites.

* A position that is appointed by a unit present as a fortress citizen, can be appointed, re-appointed or left vacant. This means also by civ-level nobles living as a citizen in your fortress; not when they are only visiting, like the diplomat.
* A position whose appointing positions are all either vacant or [REPLACED_BY] can no longer be appointed. If the position is already filled, it cannot be reappointed or vacated; the current holder simply remains in office.
* A position that is APPOINTED_BY a unit present as the land_holder of your site, can be appointed, reassigned or left vacant.
* A position that has SUCCESSION BY_HEIR or BY_POSITION can 'initially' be appointed and also re-appointed or left vacant, but as soon as the [[nobles]] screen closes, ''it can no longer be replaced or left vacant''. From then on, the succession-rules determine who gains that position when the current holder loses the position. This works even if the SUCCESSION:BY_POSITION-position is vacant or replaced.
* A position that is ELECTED nor APPOINTED_BY, can always be (re-)appointed by the player. This is the case with the [[Expedition leader]]. If it is left vacant however, it cannot be appointed, but will be assumed shortly after.
* A position that is both ELECTED and APPOINTED_BY, cannot be appointed by the player. Contrary to world-gen sites, its slot is visible, but it doesn't show the +-sign. This is either by AS_NEEDED or by a fixed number. Even if the position somehow gets filled (re)assignment is never possible
* A player can appoint a number of units to a position, as much as the NUMBER token dictates. If it is AS_NEEDED, the player may create as many slots as they like, also contrary to world-gen sites.
* A civ-position can never be appointed, even if the appointing civ noble is a citizen of your fortress. A civ position also never can be re-assigned or left vacant, would that position be defined as appointed by a site-position.

==Election==
Read more in [[Elections]]. The message that is shown is: "(creature name) has been elected to the position of (position name)"

In worldgen, there is no functional difference between ELECTED and non-appointment, except that elected nobles tend to have high social skills and/or skills related to the position, while non-elected ones are assigned randomly. See: [[Elections]]

A succession goes before an election.

A position that is both ELECTED and APPOINTED_BY never gets elected. Even if the appointees' position somehow gets filled, (re)-elections won't happen. So, it doesn't seem possible to have an elected position become available when a certain other position becomes filled.

An ELECTED civ-(or LAND_HOLDER) position at your site will never be (re)-elected in fortress mode. So real (re-)election only works with SITE-positions.

=== {{text anchor|Election Day}} ===
Election Day takes place on the 17th of Summer. On this day, a full reevaluation is performed, including all currently elected positions, which are subject to re-election. Contrary to the information on [[Elections]], nothing occurs at the start of a season.

Positions that are both [APPOINTED_BY] and [ELECTED] will not be re-elected on Election Day when assigned through [SUCCESSION].

=== Election Eligiblity ===
Any citizen may stand for election. Eligibility cannot be restricted using [ACCEPTED_CREATURE], [REJECTED_CREATURE], [ACCEPTED_CLASS], [REJECTED_CLASS], or [GENDER]. Units currently having a [SUCCESSION]-position even may be elected for a position with a [SQUAD]-token, which is otherwise impossible to assign or even succeed.

=== Skills ===
In elections, skills are taken into account for the tokens of the position which is elected.
{| class="wikitable"
|+ Relevant skills per position token
|-
! Position Token !! Relevant skills
|-
| Responsibility [[Position_token#DELIVER_MESSAGES|[DELIVER_MESSAGES]]] || [[Ambusher]], [[Observer]] and [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#ACCOUNTING|[ACCOUNTING]]] || [[Record_keeper|Record keeper]]
|-
| Responsibility [[Position_token#ESPIONAGE|[ESPIONAGE]]] || [[Schemer]]
|-
| Responsibility [[Position_token#HEALTH_MANAGEMENT|[HEALTH_MANAGEMENT]]] || [[Diagnostician|Diagnostician]]
|-
| Responsibility [[Position_token#MAKE_INTRODUCTIONS|[MAKE_INTRODUCTIONS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#MAKE_PEACE_AGREEMENTS|[MAKE_PEACE_AGREEMENTS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#MAKE_TOPIC_AGREEMENTS|[MAKE_TOPIC_AGREEMENTS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#MANAGE_PRODUCTION|[MANAGE_PRODUCTION]]] || [[Organizer]]
|-
| Responsibility [[Position_token#MEET_WORKERS|[MEET_WORKERS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#RECEIVE_DIPLOMATS|[RECEIVE_DIPLOMATS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#RELIGION|[RELIGION]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#TAME_EXOTICS|[TAME_EXOTICS]]] || [[Animal_trainer|Animal trainer]]
|-
| Responsibility [[Position_token#TRADE|[TRADE]]] || [[Social_skill|Social skills]] and [[Appraiser|Appraiser]]
|-
| [[Position_token#SQUAD|[SQUAD]]]-token || [[Tactician]] and [[Leader]]
|}

==Assumption==

A position that is not APPOINTED_BY nor ELECTED, or is appointed by positions that are not available in your site or civ, will be assumable by a random dwarf. If it has responsibilities that require certain skills, then these are taken into consideration on embark, but not when the position is assumed during the actual game.

Normally, one to three units will take the into consideration to assume a position. Most of the time when there are multiple open positions, only a single unit will assume all of them. However, a position that has REJECTED_CREATURE, REJECTED_CLASS, ALLOWED_CREATURE or ALLOWED_CLASS will be filled with all different units, even if the creature or class mentioned is irrelevant. It seems that this forces the game to loop over all the available units.

The message that is shown in Legends mode is: "(unit name) has assumed the position of (position name)". This may also take place in fortress mode, which then shows this message to the player.

If an assumable position becomes empty, it will be assumed within a day. This is the case when you leave the position of expedition-leader vacant. It also happens with entities.

Assumable positions that become empty will not be assumed if that position has a valid [SUCCESSION] -successor. In that case, the successor inherits the position.

Even positions that are somehow invisible because they cannot be directly APPOINTED_BY players, can be assumed.

When you embark, the assumable positions are automatically assigned to a random unit. If there are multiple of these positions at embark, they all are assigned to the same unit. If there are enough positions available, multiple units may gain a position, but often no more than three different ones.

If a dwarf in fortress mode assumes a position, that already has another position, it will leave the current position empty. When that position also is assumed, then this will continue until all positions have a dwarf appointed to them, with no other position.

A unit that already has a position with a [SUCCESSION] token won't take assumable positions into consideration that have a [SQUAD] token. This can be used by the modder to prevent unwanted loss of current positions.

A position that has an appointer which got replaced because of REPLACED_BY, will not become assumable. Also, positions that have an AS_NEEDED appointer that is not yet filled (or ever), will also not be assumed.

==Succession==

If a position-holder dies or advances to a new position via succession, the position will be granted to another unit based on the [SUCCESSION] tag. If they have an heir or the succeeding position exists, that unit will be assigned. If not, a new one will be appointed according to the usual rules. The message that is shown is: "(creature name) being the rightful heir, has inherited the position of (position name)"

The succeeding creature will also lose its previous position. When succession is defined using BY_POSITION, the unit naturally loses the referenced position. However, it also loses any other positions it may hold. If a unit could simultaneously inherit multiple positions, the last-defined succession overrides the earlier one, clearing the previously acquired position

Succession works both at site-level and at civ-level, both in world-gen and in fortress-mode. Succession by position on the civ-level is also visible and functional in fortress-mode. If both civ-level nobles are a citizen of your fortress, succession is applied visually. Vanilla example: The [[druid]] is succeeded by the [[acolyte]]. This means that as soon as the druid dies, the acolyte takes over.

When a position that is succeeded by position becomes available, immediately it is checked if a position-successor is available and the position is filled with that unit. Even if this is an [ELECTED] position, succession goes first. When elections eventually do happen, succession plays no role.

It is possible to assign multiple levels of [SUCCESSION:BY_POSITION] in different positions, creating a line of positions where the death of one causes all those "below" them to advance.

A position can have multiple tokens with position-succession. It looks to be random which one is used. It is not always:
* The first or last defined token
* The first or last appointed unit
* the oldest or youngest
* one with a higher or lower precedence
* a unit with relevant skills

When a position is defined with a Succession-type, that unit cannot have another position that has a Squad-type. If the succession-position itself has a squad, than it can be assigned another position with a squad, but then it will loose the previous succesion position. See further details by "Squad"

Assumed positions can also be succeeded by position, if the current holder dies.

If the successor is an AS_NEEDED position, the used unit will leave a vacant position-slot on its removal by succession. This empty slot remains a real slot, which will only be cleaned up if you (un)appoint a unit to this position-series. It isn't cleaned up after regular position validation.

A civ-level position of a unit living at your site might be inherited by a unit holding that does not currently live at your site. This, unfortunately, moves that position to a unit off site. This may also happen with the landholder of your site, for example when it is succeeded by another civ-level position. This currently poses an unsolved challenge.

===Eligibility for succession===
Succession is restricted by the tokens [ACCEPTED_CREATURE], [REJECTED_CREATURE], [ACCEPTED_CLASS], [REJECTED_CLASS] and [GENDER].

===Site and civ combined succession===

Succession can work when combining site positions with civ-level positions or land_holders, but only in world-gen mode. In fortress mode, it only works with combining the same level of nobles, with Landholders regarded as civ-level. So, in fortress mode, a site's position cannot succeed a landholder's position and it cannot succeed another type of civ-level position, and vice versa.

This won't work even if the positions:
* are AS_NEEDED or having a fixed number.
* Are LAND_HOLDERs.

===Succession [BY_HEIR]===

When a heir is needed for succession, all children and then other relatives are validated. They cannot take the position if their status does not allow it, for example if they have become a member of another civilisation. See: "Who can take a position". If the unit has no valid heir on that location, the position may go to a unit living on another site. This may cause the title of Landholder of some land to be inherited by a unit living somewhere else. That might be a problem, because then you lose your landholders.

===Premature Succession===

There are cases where [SUCCESSION:BY_POSITION] is applied prematurely: at the moment a position is first created and becomes appointable or assumable, rather than after a current holder leaves. In this situation, the succession mechanism assigns a holder immediately, without any player interaction.

When a position becomes available for the first time, the game checks whether a valid successor-by-position exists. If so, that unit is assigned instantly. It can affect positions that would normally be appointed or elected by the player, causing succession to trigger before the player has any opportunity to intervene.

This behavior occurs only in Fortress mode, but can be applied both on [SITE]-positions as well in civ-positions. That last one however is a bit harder to control. Example: [[Advanced entity position mechanics#The Archduke|The Archduke]]

This premature succession only occurs the first time a position becomes available (i.e. when it is created and becomes appointable or assumable). Even if the position remains vacant and the conditions for succession improve later, premature succession will not trigger again. From that point onward, only normal succession rules apply.

Using premature succession, a position that has [ELECTED], [APPOINTED_BY], or both, can be filled directly.
Notably, positions that combine [ELECTED] and [APPOINTED_BY] are normally impossible to fill through regular mechanics. Premature succession bypasses both election and appointment entirely, making this combination uniquely reachable through this mechanism.

No initial election takes place, and no subsequent elections will ever occur for that position. Succession always takes precedence over election, both in premature succession and in normal succession cases.

This behavior applies only in Fortress mode, not during world generation. World-gen uses simplified and more efficient mechanics, and this interaction does not occur there. Premature succession can affect both site-level and civilization-level positions.

====Multiple succession chains====

Multiple succession chains may be defined and are resolved in the order they appear in the raws.

If a position has both:
* a direct succession chain (A → C), and
* a multi-step chain (A → B → C),

and intermediate positions are vacant, resolution proceeds according to raw order. A common outcome is:
# The direct succession (A → C) is applied first, assigning A to C.
# The remaining chain then advances (A → B).
# If C still has empty slots, the final step (B → C) may occur.

If position B is already filled, behavior depends entirely on raw definition order:
* nothing may happen, or
* B may move to C first, followed by A moving to B.
====Working triggers====
Premature succession is triggered when a succeedable position is created under the following conditions:
* The succeedable position is created because its [REQUIRES_POPULATION] threshold is reached. This applies even if the position is not [APPOINTED_BY]. Premature succession takes priority over automatic assumption (e.g. the mayor declaring themselves within a day).
** The position must either be assumable or appointed by an existing position. When said appointer-position also just has been created, the premature succession of the succeedable position happenes, even when the appointer-position is empty.
* The succeedable position can be [APPOINTED_BY] another position of the same level (site or civ) that has just been created because its [REQUIRES_POPULATION] was reached.
* The succeedable position can be appointed by another [SITE] [AS_NEEDED] position that has just been created and filled.
* The succeedable (site or civ) position is [APPOINTED_BY] the [LAND_HOLDER] position, which has just been created due to site elevation. This typically resolves when the diplomat leaves the map, at which point the landholder position becomes active.
* If all other requirements are met, premature succession can occur immediately after unpausing following embark, for positions with [REQUIRES_POPULATION:7].

====Non-working triggers====
Premature succession does '''not''' occur in the following cases:
* An [AS_NEEDED] succeedable position slot is manually created by the player while its succeeding position is already filled. [AS_NEEDED] positions must always be appointed after creation.
* The succeeding position is filled after the succeedable position becomes available. The moment of creation is the decisive trigger; filling the source position later is too late.
* The succeedable position can be appointed by another site or civ position with a fixed number of slots that has just been appointed. In this case, the succeedable position is just available for appointment itself, nothing more
* Any situation occurring during world generation.
* The succeeding position is [REPLACED_BY] the succeedable position. In this case, replacement removes the unit from the source position first, leaving no holder available for the succession mechanism to use.rst, leaving no holder available for the succession mechanism to use.
* The position is [APPOINTED_BY] a civ-level position, that just became a citizen of your fortress. It must be noted that those civ-level positions were active all that time and the succeedable position could be appointed even before. The monarchs arrival does not trigger premature succession

=Losing a position=

A unit can lose a position when:
* It dies
* It succeeds another position, even if it has nothing to do with the previous position.
* It is assigned to another SQUAD-holding position
* It is convicted of a crime.
* Another unit is ELECTED for the position
* Its position becomes replaced
* Another unit is appointed by the player, or the position is left vacant.
* It has assumed another position, as this always leaves the previous position vacant.

=Embarkment=
Two types of positions are automatically filled by embark.
* Positions without [APPOINTED_BY] or [ELECTED] (assumable). All these positions, even with a NUMBER higher than 1, are all filled with one to three dwarves. Contrary to assumption, this doesn't take into account any limitations. REJECTED_CLASS, ALLOWED_CLASS, REJECTED_CREATURE, ALLOWED_CREATURE and GENDER are applied, but without the normal spread you may expect with assumptions. Also it doesn't look at [SUCCESSION] and [SQUAD] limitations.
* Positions that are elected are filled-in by the normal election rules.

Positions that have a defined appointer are never initially filled at embark.

All positions that don't have [REQUIRES_POPULATION] or with a [REQUIRES_POPULATION] of 7 or lower, will be available at embark.

=Land Holders=

A Landholder is a '''special civ-level noble''' who gets a certain piece of land to hold, when that land is elevated to a certain level, determined by the tag [LAND_HOLDER] and by the landholder triggers in the game's settings. In vanilla, these are the baron, the count and the duke.

A unit gaining the landholder position does not migrate to that specific named land. In world-gen, they stay just where they are, probably at the capital. In fortress mode, you can suggest a citizen for the role. So for the time being that works.

Succession is then a real issue. If you use BY_HEIR, its solved when that landholder has children living at your site. But when its not the case, the title just goes to anyone randomly. Succession BY_POSITION works, but only in the civ-chain, and there's no way to guarantee a civ-holder is at your site at that time. Even with 'automatic spread' positions, it goes to one of them randomly.

==Functioning of the regular landholder chain==

The distinct difference between a landholder and a regular civ-level noble, is that a landholder may gain the position of landholder "of (sitename)" They are then seen as ruler of a particular site.

For a land_holder position to function as such, it has a few requirements:
* NUMBER:AS_NEEDED
* The first landholder-number of 1 is defined.
* No SITE (so civ) tag in that position.
*REPLACED_BY the next level landholder
If a landholder is defined with differentiating properties, it will function like a regular noble. A higher-up landholder that lacks the required tokens or connections will then not be used in elevation.

If a fortress meets the trigger for a new LAND_HOLDER tier when a caravan leaves, then the next time the outpost liaison or equivalent arrives, they will offer to make you an official colony, which will allow you to select all positions for that LAND_HOLDER level. Each time they appear, the outpost liaison will only promote your fortress one tier up the LAND_HOLDER track.

The landholder's LAND_NAME is not required for the functioning of this system. If omitted, messages will be shown with a more generic text.

==Appointment==

This mechanism differs from the regular methods of position management. It ignores all regular appointment- and election rules, so it more or less functions like automatic assignment. A landholder is, in vanilla, appointed by the monarch. Changing this doesn't seem to do anything. If they are appointed by a site-position, a not-yet-existing civ-position, or not appointed at all: the system keeps working as usual.

A landholder can appoint civ-positions and site positions. This works as expected: the positions only are appointed then when that landholder becomes available on civ-level or when he arrives at that site for site-level positions.

If your rank of landholder is the first of its rank in the realm, and is the sole appointer of some civ-position, then immediately as it gains the title, it will appoint the empty civ-slots. This may happen on your site, but the frequency and certainty is hard to determine.

==Succession==

Succession rules are applied to some extent:
* In world-gen it works according to succession rules, and site-positions can be used here. This means that a site position or a civ-position can inherit a landholder position, and vice versa.
* In fortress mode, once a landholder has been appointed, it then can inherit civ-level positions, and vice versa. This means that your baron can become king.
* Succession rules do not apply within the [LAND_HOLDER] chain; a count will not inherit a baron's land. This is because succession does not work well with the AS_NEEDED token.
* Premature succession works in fortress mode with landholders. If a unit gets a landholder's position and that landholder is the appointer of an as yet empty position, which is defined as succeeding from a third one, then the succession is immediately applied. The landholder themselves can even be the successor of a newly created position.
* A landholder's position is, in fortress mode, not successionable by a site-position or vice versa

===Impossibilities for succession by a site-position===
It would be very beneficial if the landholder can be succeeded by a [SITE]-position. So far, the following tests have not lead to positive results:
* making landholder and site-position both non-[DUTY_BOUND]
* make the site-position be [APPOINTED_BY] the landholder and/or the monarch
* give landholder and site-position [REJECTED_CREATURE]
* Let the monarch live at your site when succession could happen.
* Let the site-position be [REPLACED_BY] the landholder.

If the vanilla [SUCCESSION:BY_HEIR]-tag is omitted, a seemingly random unit somewhere in the realm is assigned this position.

==Nomination==

The player is able to nominate a unit to become the LAND_HOLDER, but this only works with units of [LAND_HOLDER] level 1. The player can select all units, only limited by the PRECEDENCE of the current units' positions.

A unit that has a position with a PRECEDENCE lower or equal to that of the landholder's position, cannot be selected. This means that a baron (or count) from another site or the monarch cannot be selected, because their precedence is lower or equal.

The GENDER token does not work here: also units with the wrong gender (sorry) can be selected.

==Levels==
In mods, up to 10 levels of LAND_HOLDER may be defined.

If a landholder is replaced by a wrong landholder number (1 replaced by 3), then the number 3 is still correctly attached to the settlement.

If the current landholder has the highest available landholder number, then the next elevation will not happen - the diplomat will not elevate your fortress to a higher position, even if that position might be REPLACED_BY a lower landholder.

These chains do work:
* 1 -> 2a - > 2b -> 3
* 1 -> 3 -> 2 -> 4

These chains do not work:
* 2 -> 3 (need to start at 1)
* 1 -> 4 -> 2 -> 3 (stops after 4 as the highest)
* 1a -> 2, 1b -> 2 (only 1a and 2 work, 1b is not used)

==Moving landholders==

It may happen that a land-holder no longer lives at the site which they are the landholder of, specifically when the current landholder dies, leaving the title to an heir living somewhere else.

To prevent this from happening, you can make their succession from heir and make sure that their kids live at your site. Or, you can make their position succeeded by another civ position, and make it so that this civ position is somehow available on your site. But if multiple of these positions exist, it cannot be guaranteed that a citizen of your fortress will inherit the title.

In world gen, a landholder lacking the DUTY_BOUND-token will also move to the site they like, according to legends mode.

==Replacement by a generic civ-position==

If a landholder is replaced by an AS_NEEDED non-landholder civ-position, then this will work: the current landholder loses that title upon settlement-elevation and gains that civ-title. However, the civ-title lacks the landholder-property of being attached to the land. It will not show the name of the settlement alongside the position's name. So no "minister of Shovelmounts"

If a landholder is replaced by a general AS_NEEDED civ-position, that itself is also replaced by a generic AS_NEEDED civ-position, then firstly the elevation is executed and also the unit gains that new position. However, he immediately loses it, because an AS_NEEDED position that is replaced by another position can be filled initially, but units wont be able to hold that title.

==Landholder with fixed number==

A landholder's position that has a fixed number will be created and filled directly when the civilisation is born, so this position slot is then not available for the regular landholder-mechanic and will also not be used. That landholder will thus not be attached to a settlement.

It doesn't matter if the landholder's position is connected to the regular landholder's-chain with the REPLACE_BY token.

==Responsibilities==

When given a certain [RESPONSIBILITY], a landholder may function as a regular civ-level noble. If the position has [TRADE] or [OUTPOST_NEGOTIATING] responsibilities, then the landholder functions both as a diplomat and as an actual land holder. A landholder with the [MILITARY_STRATEGY] responsibility will travel around taming creatures in world-gen, according to legends mode.

Besides that, the responsibilities work the same as with any other on-site living position-holder, civ or otherwise.

=Military=
==Squad management==
In the vanilla game, the Squad interface only becomes available after a militia commander has been appointed. Until then, the window displays:{{DFtext|You must appoint somebody first to create a squad.}}

What’s surprising is how this is determined internally. In the entity raw definition, '''only the last two positions that include a [SQUAD] token are checked''' to decide whether the interface is accessible at all. As a result, if your hierarchy defines commanders A through E, appointing '''Commander D or E''' unlocks squad formation, while appointing A–C does nothing.

In other words, squad availability is not tied to ''having a militia commander'', but to ''which specific positions happen to be last in the raw list''—a notably hacky implementation.

These 'last two' are always the last two '''available positions.''' So if they get [REPLACED_BY] or become available because of [REQUIRES_POPULATION], the game adapts to those.

==Squad assignment==

Squads can be assigned, even if the leader position has no holder.

A specific unit can only have one position associated with a squad. If it gains another 'squad holding position', it is unassigned from the first one. This does not work with a 0-squad, so only 1+squads are taken into consideration. This technique can possibly be used to distribute all positions equally among all citizens. It does however not work with election and assumption.

If a civ-level position is associated with a squad and it gets a site-level squad-holding position assigned, it loses the current civ-position.

Squads can get really messed up, if you make the position (or multiple) either elected or not-elected and not-appointed, then this can cause the game to assign multiple squads to the same unit. Automatic assignment and election does not take squads into account, but the nobles screen does. This can cause the positions to be cleared as the game figures out that they have more than one position, and immediately get elected or assumed again.

Positions that cannot have a squad-position:
* A site- or civ-position with a [SUCCESSION] token cannot be appointed a squad-holding-position. The other way around, however, does work. For example, if a site-position with a [SUCCESSION]-token is appointed to a unit that has already a position with [SQUAD]. But when that squad position is assigned to another unit, it cannot be assigned back.
* A position with [SUCCESSION] can also not be assigned as a '''member''' of a squad.
* A squad-holding position with a formed squad cannot be appointed to another squad holding position.

If a position has at least one squad member, it cannot be left vacant. First, the squad has to be disbanded, then the position may be cleared.

==0-squads==
A 0-Squad is defined in a position as [SQUAD:0:member:members]. It does not seem to do anything useful as of now.
* It cannot be used to activate the [[Squad|military interface]]
* It does not restrict the assignment of [SUCCESSION] positions.
* Assigning this position does not clear any previously held squad position.
* The [[Leader]] and [[Tactician]] skill are not marked as relevant skills and are not taken into account in elections.
* It cannot be formed as a squad.

=Further testing=
The following questions may need additional testing. Feel free to add or answer
* Everything regarding COMMANDING and army-structure
** [http://www.bay12forums.com/smf/index.php?topic=175437.msg8331668#msg8331668]
** [http://www.bay12forums.com/smf/index.php?topic=165213.msg8335682#msg8335682]
** [http://www.bay12forums.com/smf/index.php?topic=174584.msg8026854#msg8026854]
* Stuff about the monarch, its arrival and its entourage.

=Oddities (Bugs)=
Almost everything on this page could be called an oddity. Because of their unexpected usability, some may also be referred to as “undocumented features.” Others, however, are simply odd and not particularly useful, yet I hesitate to call them “bugs.”
* If a certain threshold is reached that makes an elected position electable, and the triggering event that initiates this evaluation is an assumption, then the resulting assumption is also referred to in the messages as an election

=Examples=

===The Founder===
The founder is a single dwarf, appointed at embark. They will be the only one ever to have this position and are not replaceable. When they lose their position some way, the position will not be assumed by another dwarf.
{{gamedata|title=The Founder|
[POSITION:THE_FOUNDER]
[NAME:the founder:founders]
[NUMBER:1]
[SITE]
[ALLOWED_CREATURE:DWARF:ALL] - will only be filled at embark, but not assumable later.
[REJECTED_CREATURE:DWARF:ALL] - will only be filled at embark, but not assumable later.
[SUCCESSION:BY_POSITION:THE_FOUNDER] - not unassignable, also cannot be assigned to a [SQUAD] position.
[PRECEDENCE:200]
Non APPOINTED_BY
Non ELECTED
Optional: Add responsibilities to make the game select a unit with certain skills.
}}
===Marriage bar===
Dwarven matrons are held in great honour. Upon marriage, a female dwarf is no longer expected to perform menial labour. All dwarven males hold this position by default, granting their spouses exemption from menial work.

The position becomes available with the arrival of the first migrants; otherwise, on embark, it would be assumed by females. Its succession rule is non-functional, but this prevents the player from unassigning the position. A squad size of 1 and the succession rules together prevent a unit from assuming the position more than once.

With precedence set to NONE, the position name is hidden, while LAND_NAME remains visible on the nobles screen. All married females receive the suffix “, Mrs.” and are marked as Nobles.

The practical usefulness of this position is debatable, but it serves as a clear demonstration of several mechanics.
{{gamedata|title=Mrs. Urist|

[POSITION:MRS_URIST]
[NUMBER:300]
[SITE]
[ALLOWED_CREATURE:DWARF:MALE]
Not APPOINTED_BY
Not ELECTED
[LAND_NAME:Dwarven male]
[NAME:dwarven male:dwarven male]
[PRECEDENCE:NONE]
[SPOUSE_FEMALE:, Mrs.:spouses]
[MENIAL_WORK_EXEMPTION_SPOUSE]
[REQUIRES_POPULATION:8]
[SUCCESSION:BY_POSITION:MONARCH]
[SQUAD:1:member:members]
}}
===The Archduke===
The archduke is the leader of the civilization, but exists only from landholder 4-level. Until then, its position remains vacant. When a settlement is elevated to tier 4 (grand duke), the grand duke can appoint the ruler of the civilisation, the archduke. Because of 'Premature Succession', they themself inherit that position immediately, but only when in fortress mode. Its heir then becomes grand duke.
{{gamedata|title=The Archduke| no POSITION:MONARCH or other PRECEDENCE:1

[POSITION:THE_ARCHDUKE]
[NAME:archduke:archdukes]
[NAME_MALE:archduke:archdukes]
[NAME_FEMALE:archduchess:archduchesses]
[LAND_NAME:a archduchy]
[NUMBER:1]
[PRECEDENCE:1]
[SUCCESSION:BY_POSITION:GRAND_DUKE]
[APPOINTED_BY:GRAND_DUKE]
(add additional monarch-stuff, like spouse name, demands etc.)

[POSITION:GRAND_DUKE]
[NAME:grand duke:grand dukes]
[NAME_MALE:grand duke:grand dukes]
[NAME_FEMALE:grand duchess:grand duchesses]
[NUMBER:AS_NEEDED]
[LAND_HOLDER:4]
// Optional ...
[PRECEDENCE:19]
[LAND_NAME:a archduchy]
[RESPONSIBILITY:LAW_MAKING]
[RESPONSIBILITY:RECEIVE_DIPLOMATS]
[SUCCESSION:BY_HEIR]
[APPOINTED_BY:THE_ARCHDUKE]
(add additional landholder-stuff)

!!add to [POSITION:DUKE]
[REPLACED_BY:GRAND_DUKE]

}}
{{Category|Modding}}
{{Category|Entities}}
{{Category|Guides}}

Position token

2026-03-12T09:39:22Z

Joostheger: added new found to replaced_by. /* Position tokens */

{{Quality|Fine}}
{{av}}
{{Modding}}
Position tokens define [[noble]] positions for civilizations and site governments, inside [[entity token]]s. In the vanilla game, position token definitions can be found in <code>[[Game folder|<Dwarf Fortress>]]\data\vanilla\vanilla_entities\objects\entity_default.txt</code>.

__TOC__
{{clear}}

==Code==
A position is defined with a position 'code', as an argument in the [POSITION]-tag. The same code may be used multiple times, they don't have to be unique. This code is used as reference by APPOINTED_BY, SUCCESSION:BY_POSITION, REPLACE_BY and COMMANDER. 'MONARCH' is an example of this code.

==Position tokens==
These tokens belong in an entity definition, applying to a position (such as monarch) and should follow the [POSITION:POSITION_NAME] token.

{| {{prettytable}}
|- bgcolor="#dddddd"
! Token
! Arguments
! Description

|-
| {{text anchor|ACCOUNT_EXEMPT}}
|
| The position holder is not subjected to the [[Dwarven economy|economy]]. Less than relevant right now.

|-
| {{text anchor|ALLOWED_CLASS}}
| {{token|CREATURE_CLASS|creature}} token
| rowspan=2 | ALLOWED_CLASS: Only creatures with the specified [CREATURE_CLASS] token may be appointed to this position. Multiple entries are allowed. ALLOWED_CREATURE: Restricts the position to the specified creature and caste. Multiple entries are allowed. These tokens only apply within the entity’s own race (including its castes).
In world generation, they limit which units may be assigned to the position, but they do not prevent other creature types from acquiring the position through alternative means (for example, via a coup).
In fortress mode, these tokens are enforced during manual appointment and succession.
During world generation, if all allowed castes have a POP_RATIO of 0, a unit of an allowed caste will still be generated to fill the position.

|-
| {{text anchor|ALLOWED_CREATURE}}
| CREATURE:CASTE

|-
| {{text anchor|APPOINTED_BY}}
| position
| This position can only be chosen for the task from the nobles screen, and is available only if there is an *argument* present. For example, the GENERAL is [APPOINTED_BY:MONARCH]. Contrast [ELECTED]. Being appointed by a MONARCH seems to handle a lot of worldgen stuff, and interferes with fort mode titles. Multiple entries are allowed. If you have neither an ELECTED-token nor a APPOINTED_BY-token, the holder may always be changed (like the expedition leader).
''Read more: [[Advanced_Entity_Position_Mechanics#Appointment]]''

|-
| {{text anchor|BRAG_ON_KILL}}
|
| A creature that kills a member of this position will be sure to talk about it a lot.

|-
| {{text anchor|CHAT_WORTHY}}
|
| In adventure mode, when referencing locations, an NPC may mention this position holder living there or having done some deed there; it also means that the position exists in world-gen, rather than being created only at the end of world-gen.

|-
| {{text anchor|COLOR}}
| [[Color]]
| Creatures of this position will have this [[Color]], instead of their profession color, e.g. [COLOR:5:0:1]. It is also applied to the name of the citizen in the units-screen.

|-
| {{text anchor|COMMANDER}}
| position:ALL
| This position will act as a commander of the specified position{{verify}}. E.g. GENERAL is [COMMANDER:LIEUTENANT:ALL]. Unknown if values other than ALL work. Multiple entries are allowed.
''Read more: [[Army]]''

|-
| {{text anchor|CONQUERED_SITE}}
|
| This position is a puppet ruler, left behind in a conquered site.

|-
| {{text anchor|DEMAND_MAX}}
| number (0-100)
| How many demands the position can make of the population at one time.

|-
| {{text anchor|DESCRIPTION}}
| string. Readable up to 470 characters in the nobles' screen.
| description of this position in the nobles screen.

|-
| {{text anchor|DETERMINES_COIN_DESIGN}}
|
| The site's (or civ's) minted [[coin]]s, if any, will have images that reflect the personality of this position holder.

|-
| {{text anchor|DO_NOT_CULL}}
|
| The position won't be culled from Legends as "unimportant" during world generation.

|-
| {{text anchor|DUTY_BOUND}}
|
| Members of this position will never agree to 'join' your character during adventure mode. They also don't settle anywhere else but in the capital, and will not [[immigration|emigrate]] from their site. If they are not DUTY_BOUND, they will live anywhere as they like.

|-
| {{text anchor|ELECTED}}
|
| The population will periodically select the most skill-eligible creature to fill this position for site-level positions at the player's fort. For responsibilities or positions that use more than one skill, no skill takes priority in electing a creature: an accomplished comedian is more qualified for the TRADE responsibility than a skilled appraiser. A creature may be elected to multiple positions at the same time. Contrast [APPOINTED_BY].
''More info: [[Elections]]''
''Read more: [[Advanced_Entity_Position_Mechanics#Elections]]''

|-
| {{text anchor|EXECUTION_SKILL}}
| weapon skill
| A mandatory sub-tag of [RESPONSIBILITY:EXECUTIONS]. Determines the weapon chosen by the executioner for their work.

|-
| {{text anchor|EXPORTED_IN_LEGENDS}}
|
| The various members who have filled this role will be listed in the civilisation's history.

|-
| {{text anchor|FLASHES}}
|
| The creature holding this position will visibly flash, like legendary citizens. Represents a properly noble station by default.

|-
| {{text anchor|GENDER}}
| male/female
| The position can only be held by the specified gender. Currently bugged {{bug|2714}}

|-
| {{text anchor|KILL_QUEST}}
|
| The position can assign quests to adventurers.

|-
| {{text anchor|LAND_HOLDER}}
| importance tier (1-10)
| This is an alternative to SITE, allowing positions to be created at civ-level 'as needed' for all sites that meet the requirements to have them, which are the values set in [[Difficulty#Land_holder|land holder difficulty]] [[settings]]. The character is tied permanently to a particular site, but also operates at the civ-level.
''Read more: [[Advanced_Entity_Position_Mechanics#land holders]]''

|-
| {{text anchor|LAND_NAME}}
| string. Readable up to 21 characters in the nobles' screen.
| The name the area takes on when under the control of a LAND_HOLDER. E.g. for the DUKE, [LAND_NAME:a duchy]. If the position is not a [[LAND_HOLDER]], the land_name is still displayed left of the position in the nobles menu.

|-
| {{text anchor|MANDATE_MAX}}
| number (0-100)
| The maximum number of mandates the position can make at once.

|-
| {{text anchor|MENIAL_WORK_EXEMPTION}}
|
| The position holder cannot be assigned labors. It only works for [SITE]-positions.

|-
| {{text anchor|MENIAL_WORK_EXEMPTION_SPOUSE}}
|
| The spouse of the position holder doesn't have to work, either - see above.
|-
| {{text anchor|MILITARY_SCREEN_ONLY}}
|
| This position cannot be appointed from the nobles screen. Intended for militia captains and other squad leaders to reduce clutter. Currently nonfunctional{{bug|8965}}

|-
| {{text anchor|NAME}}
| singular:plural. Readable up to 21 characters in the nobles' screen and up to 30 in the unit list.
| The name of the position.

|-
| {{text anchor|NAME_MALE}}
| singular:plural. Readable up to 21 characters in the nobles' screen and up to 30 in the unit list.
| If the creature holding the position is male, this is the position's name. E.g. for MONARCH, [NAME_MALE:king:kings]

|-
| {{text anchor|NAME_FEMALE}}
| singular:plural. Readable up to 21 characters in the nobles' screen and up to 30 in the unit list.
| If the creature holding the position is female, this is the position's name. E.g. for MONARCH, [NAME_FEMALE:queen:queens]

|-
| {{text anchor|NUMBER}}
|
* number/AS_NEEDED
| How many of the position there should be. If the [SITE] token exists, this is per site, otherwise this is per civilisation. AS_NEEDED applies mainly to positions involved with the military command chain; this is used to allow armies to expand to whatever size they need to be. Other non-military positions like the land_holders or the [[messenger]] with NUMBER:AS_NEEDED will also be appointed.
The problem with [[Lieutenant]]s and [[Captain]]s not being created, is their AS_NEEDED number. They are only then created when they're needed, and that has some pretty unusual conditions. When a fixed number is used, they are appointed with the creation of the civ.
If the NUMBER is set at a fixed value higher than 1, the position is always filled up full. If the position is available on embark, it is completely filled up with only the first dwarf.

|-
| {{text anchor|PRECEDENCE}}
| number (0-30000)/NONE
| How important the position is in society; a lower number is more important and displayed higher in the Nobles menu. For MONARCH it's 1, for MILITIA_CAPTAIN it's 200.

The game marks the first non-[SITE] position with [PRECEDENCE:1] as the ruler, for both embark screen and mountainhome purposes. When it is empty, [REPLACED_BY] another position, or not yet created because of [REQUIRES_POPULATION], the screen just says 'None' as the holders' name.

Landholders can become the ruler, if they are the first defined position with precedence of 1. civ-position can also be created without precedence. Positions may have the same precedence and will be appointed, although the effect is unknown. Precedence has no effect on who's doing the job, if both positions have the same responsibilities.

|-
| {{text anchor|PUNISHMENT_EXEMPTION}}
|
| The position holder will not be held accountable for his or her crimes. Currently nonfunctional.{{bug|4589}}{{verify|seems to prevent punishment when they are convicted of actual crime}}

|-
| {{text anchor|QUEST_GIVER}}
|
| The position holder can give quests in Adventure mode. Functionality in 0.31.13 and later is uncertain.

|-
| {{text anchor|REJECTED_CLASS}}
| CREATURE_CLASS Token
| Creatures of the specified class cannot be appointed to this position. Multiple entries are allowed

|-
| {{text anchor|REJECTED_CREATURE}}
| CREATURE:CASTE
| Restricts position holders by CREATURE type. Multiple entries are allowed. It doesn't seem to work in world-gen. When checking Legends mode, units are seen assigned this position regardless of their creature-type or caste. It does work in Fortress mode.

|-
| {{text anchor|REPLACED_BY}}
| position
| This position is absorbed by another down the line. For example, expedition leader is [REPLACED_BY:MAYOR]. Only a single entry is allowed.

It can work with both [REQUIRES_POPULATION] and [REQUIRES_MARKET].

The tag differs in function for landholders, see [[Advanced_entity_position_mechanics]]

|-
| {{text anchor|REQUIRED_BEDROOM}}
| number (0-1000000)
| The position holder requires a bedroom with at least this value.

|-
| {{text anchor|REQUIRED_BOXES}}
| number (0-100)
| The position holder requires at least this many boxes.

|-
| {{text anchor|REQUIRED_CABINETS}}
| number (0-100)
| The position holder requires at least this many cabinets.

|-
| {{text anchor|REQUIRED_DINING}}
| number (0-1000000)
| The position holder requires a dining room with at least this value.

|-
| {{text anchor|REQUIRED_OFFICE}}
| number (0-1000000)
| The position holder requires an office with at least this value.

|-
| {{text anchor|REQUIRED_RACKS}}
| number (0-100)
| The position holder requires at least this many weapon racks.

|-
| {{text anchor|REQUIRED_STANDS}}
| number (0-100)
| The position holder requires at least this many armour stands.

|-
| {{text anchor|REQUIRED_TOMB}}
| number (0-1000000)
| The position holder requires a tomb with at least this value.

|-
| {{text anchor|REQUIRES_MARKET}}
|
| Does not have anything directly to do with [[trade depot|trade depots]]. It means that in minor sites (such as hillocks) the position will not appear, while in major sites (such as dwarf fortresses) it will. Depending on its economical position in the region, a [[hamlet]] may build a market and develop into a [[Town]] eventually. That is when this position becomes available. It only works in combination with the [SITE]-token.

|-
| {{text anchor|REQUIRES_POPULATION}}
| number
| The position requires the population to be at least this number before it becomes available, or before the position holder will move in.

|-
| {{text anchor|RESPONSIBILITY}}
| responsibility
| The position holder does a thing. See the table below for suitable arguments. A position does not need to have a responsibility.

|-
| {{text anchor|RULES_FROM_LOCATION}}
|
| If there is a special location set aside for rulers, such as a human castle/mead hall, the position holder will always be found at that particular location. Does nothing for dwarven nobles, because at present, dwarves have no such special locations.

|-
| {{text anchor|SITE}}
|
| Every site government will have the defined number of this position instead of the whole civilization; provided that other criteria (if any) are met. Unless LAND_HOLDER is present instead, the defined number of the position will be created only for the civilization as a whole.

|-
| {{text anchor|SLEEP_PRETENSION}}
|
| The position holder will get upset if someone with a higher PRECEDENCE holds quarters with a greater value than their own.

|-
| {{text anchor|SPECIAL_BURIAL}}
|
| The civilization will inter the corpse of the position holder in a special grave, either in catacombs or in monuments. If that grave is disturbed, the position holder can return as a [[mummy]]. {{verify}}

|-
| {{text anchor|SPOUSE}}
| singular:plural. Readable up to 30 characters in the unit list.
| The name of the position holder's spouse.

|-
| {{text anchor|SPOUSE_FEMALE}}
| singular:plural. Readable up to 30 characters in the unit list.
| If the spouse of the creature holding the position is female, this is the spouse's position name.

|-
| {{text anchor|SPOUSE_MALE}}
| singular:plural. Readable up to 30 characters in the unit list.
| If the spouse of the creature holding the position is male, this is the spouse's position name.

|-
| {{text anchor|SQUAD}}
| number:singular:plural
| The position holder is authorized to form a military squad, led by themselves using the [[leader]] and [[military tactics]] skills. The number denotes the maximum headcount. The noun used to describe the subordinates (e.g. royal guard) is used in adventure mode for the adventurer. This token is used together with [RESPONSIBILITY:LAW_ENFORCEMENT] for giving [[quest]]s to adventurers as [[Hearthperson|hearthpeople]]. Further details: [[Advanced_entity_position_mechanics#Military]]

|-
| {{text anchor|SUCCESSION}}
|
* BY_HEIR / BY_POSITION:position
| How a new position holder is chosen. A single position can have multiple BY_POSITION tokens. See [[Noble]] for more information on how succession is handled in the game.
The SUCCESSION-Tag is also considered when a new positions opens up, for example when a required population number is reached. If a valid successor is available, they will be the one taking that position initially, without appointment or election.

|}

== Responsibilities ==
{| {{prettytable}}
|- bgcolor="#dddddd"
! Argument
! Description

|-
| {{text anchor|ACCOUNTING}}
| Found on [[bookkeeper]]. Position will use [[record keeper]] skill to keep track of stocks.

|-
| {{text anchor|ADVISE_LEADERS}}
|

|-
| {{text anchor|ATTACK_ENEMIES}}
| Found on elven [[ranger captain]] and human warrior. Effect unknown.{{verify}}

|-
| {{text anchor|BUILD_MORALE}}
| Found on [[champion]]. Citizens get a special thought for "talking to a pillar of society" when speaking to this noble.

|-
| {{text anchor|BUILDING_SAFETY}}
|

|-
| {{text anchor|COLLECT_TAXES}}
| Currently unused - was originally assigned to the tax collector.

|-
| {{text anchor|CONSTRUCTION_PERMITS}}
|

|-
| {{text anchor|DELIVER_MESSAGES}}
| Found on [[messenger]]. Position travels to other sites and uses [[social skill]]s.
|

|-
| {{text anchor|EQUIPMENT_MANIFESTS}}
| Currently unused - was originally assigned to the arsenal dwarf.

|-
| {{text anchor|ESCORT_TAX_COLLECTOR}}
| Currently unused - was originally assigned to the Royal Guards (squad members beneath the Hammerer).

|-
| {{text anchor|ESPIONAGE}}
| Found on [[dungeon master]] and the [[Elf|elven]] [[General|princess]] and uses the [[schemer]] skill.

|-
| {{text anchor|ESTABLISH_COLONY_TRADE_AGREEMENTS}}
| Found on [[outpost liaison]]. Position travels with the caravan and uses [[social skill]]s to make trade agreements with any settlements that it visits, provided they are domestic, report the news and promote {{token|LAND_HOLDER|e}} positions. Also reports recent news. Presumably has no effect at site level. Crucially, it does not visit foreign settlements, but the civ-level TRADE position does the exact same thing in its position. They arrive the same time as the caravan arrives, and this can thus be modded by setting {{token|ACTIVE_SEASON|e}}

|-
| {{text anchor|EXECUTIONS}}
| Found on [[hammerer]]. Position executes death penalty judgements with a weapon of the appropriate skill. Cannot be combined with LAW_ENFORCEMENT, resulting in the "Invalid Officer"-error.

|-
| {{text anchor|FIRE_SAFETY}}
|

|-
| {{text anchor|FOOD_SUPPLY}}
|

|-
| {{text anchor|HEALTH_MANAGEMENT}}
| Found on [[chief medical dwarf]]. Position will use [[diagnostician]] skill to evaluate [[wounds]] and schedule [[Health care|treatment]], reported in each citizen's Health tab.

|-
| {{text anchor|JUDGE}}
|

|-
| {{text anchor|LAW_ENFORCEMENT}}
| Found on [[sheriff]]/[[captain of the guard]]. Position and its subordinates are in charge of punishing criminals. A {{token|SITE|position}} position holding this responsibility plus the {{token|SQUAD|position}} token (or allowing the entity to have a {{token|SITE_VARIABLE_POSITIONS|e}} with this responsibility) is required for an adventurer from a given civilization to start as a [[hearthperson]], [[Captain of the guard|fortress guard]], etc. Cannot be combined with EXECUTIONS, resulting in the "Invalid Officer"-error.

|-
| {{text anchor|LAW_MAKING}}
| Found on [[monarch]]s and [[:Category:Aristocrats|nobles]]. Will be referred to as the leader of the site in adventure mode and they may designate the site as being the capital city for civ-level positions. This position is in charge of creating procedural positions, corresponding to either {{token|VARIABLE_POSITIONS|e}} or {{token|SITE_VARIABLE_POSITIONS|e}}. Position-holders that have attained [[immortality]] may issue oppressive edicts to protect themselves against suspicion.

|-
| {{text anchor|MAINTAIN_BRIDGES}}
|

|-
| {{text anchor|MAINTAIN_ROADS}}
|

|-
| {{text anchor|MAINTAIN_SEWERS}}
|

|-
| {{text anchor|MAINTAIN_TUNNELS}}
|

|-
| {{text anchor|MAKE_INTRODUCTIONS}}
| Position will make a 'social call' to an established foreign settlement, complimenting or insulting them depending on relations and reporting the news.

|-
| {{text anchor|MAKE_PEACE_AGREEMENTS}}
| Found on diplomat. Position negotiates peace treaties in order to end wars.

|-
| {{text anchor|MAKE_TOPIC_AGREEMENTS}}
| Found on [[diplomat]]. Position negotiates special agreements, such as tree cutting quotas. Used when elevating a settlement in the {{token|LAND_HOLDER|position}} chain up from level 1.

|-
| {{text anchor|MANAGE_ANIMALS}}
| Found on [[dungeon master]].

|-
| {{text anchor|MANAGE_LEADER_HOUSEHOLD_CLEANLINESS}}
|

|-
| {{text anchor|MANAGE_LEADER_HOUSEHOLD_DRINKS}}
|

|-
| {{text anchor|MANAGE_LEADER_HOUSEHOLD_FOOD}}
|

|-
| {{text anchor|MANAGE_PRODUCTION}}
| Found on [[manager]]. Position enables the use of workshop profiles and uses the [[organizer]] skill to process work orders entered in the job manager after the fortress population reaches 20.

|-
| {{text anchor|MEET_WORKERS}}
| Found on [[expedition leader]]/[[mayor]]. Position uses the various [[social skill]]s to hold meetings with unhappy citizens and try to pacify them with happy thoughts. In adventure mode, [SITE] positions with this responsibility handle petitions to make the player a performer for the local government.

|-
| {{text anchor|MILITARY_GOALS}}
| Found on [[monarch]]/[[:Category:Aristocrats|landholder]]/[[:Category:Elected Nobles|leaders]]. Character is in charge of going to war and making peace for the government they work for. Without a position with this responsibility at civ level the civilization will not be able to make peace and its sites will wage war on each other constantly, and as a result, all viable civilizations must have one leader with this tag at civ level. This appears not to be a problem for [[kobold]]s, presumably due to the {{token|SKULKING|e}}. If no position has this responsibility in fortress mode, players are unable to start [[missions]].

|-
| {{text anchor|MILITARY_STRATEGY}}
| Found on [[general]]/[[militia commander]]. Means that they will command the armies of their site or civilization. Issues the orders for the teams conducting raids or other operations away from the fortress. During worldgen, position will go on expeditions to tame exotic creatures. Counterintuitively not by the TAME_EXOTICS-position. The destinations of these expeditions are determined by the entities USE_(...)_ANIMALS-tokens.

|-
| {{text anchor|OVERSEE_LEADER_HOUSEHOLD}}
|

|-
| {{text anchor|PATROL_TERRITORY}}
| Found on elven ranger captain. Effect unknown.{{verify}}

|-
| {{text anchor|PREPARE_LEADER_MEALS}}
|

|-
| {{text anchor|RECEIVE_DIPLOMATS}}
| Found on [[monarch]]/[[:Category:Aristocrats|landholder]]/[[:Category:Elected Nobles|leaders]]. Position uses the various social skills to hold meetings with incoming diplomats and liaisons.

|-
| {{text anchor|RELIGION}}
| Found on elven [[druid]] and uses [[social skill]]s. Position informs you about worship cults{{verify}}

|-
| {{text anchor|SORT_AMMUNITION}}
| Currently unused - was originally assigned to the arsenal dwarf.

|-
| {{text anchor|TAME_EXOTICS}}
| Position will tame animals with the {{token|PET_EXOTIC}} token. Currently unused - was originally assigned to the dungeon master. Expeditions to tame exotic creatures will be done by the MILITARY_STRATEGY-position

|-
| {{text anchor|TRADE}}
| Found on [[broker]]. Position will use Appraisal skill to display value estimates and the various Social skills to trade at the depot. When applied to other civilizations, this position will arrive with the caravan to make trade agreements (like the Human Guild Representative from older versions) and behaves otherwise like the civ's own ESTABLISH_COLONY_TRADE_AGREEMENTS position holder. They arrive the same time as the caravan arrive and this can thus be modded by setting {{token|ACTIVE_SEASON|e}}

|-
| {{text anchor|UPGRADE_SQUAD_EQUIPMENT}}
| Currently unused - was originally assigned to the arsenal dwarf.

|}

== Related tokens ==
The following two ENTITY tokens are not actually position tokens, but bear mentioning on this page because they can modify the way that a civilization's positions behave:

{| {{prettytable}}
|- bgcolor="#dddddd"
! Token
! Arguments
! Description

|-
| {{text anchor|VARIABLE_POSITIONS}}
| Position responsibility or ALL
| Allows a responsibility to be taken up by a dynamically generated position (such as Law-maker).

|}

== Why won't my positions appear? ==
The way DF determines what positions will actually ''appear'' in your fortress is somewhat counter-intuitive and fairly limiting. This guide should help you understand what you can do to actually get your positions working properly.

There are five tokens governing which positions appear in your fortress - LAND_HOLDER, REQUIRES_POPULATION, APPOINTED_BY, ELECTED, and REPLACED_BY. The first two determine when your fortress is eligible for a new position, the next two determine how a new position for which your fortress is eligible can be added, and the fifth allows you to clear up obsolete positions. Unfortunately, they also interact in some strange ways that makes creating interesting position structures difficult.

When you start a new fortress, DF compiles a list of your initial positions. To do this, it looks at the requirements for each position - any position whose only requirement is less than seven dwarves (either because they have no requirement tokens, or because their only requirement tokens are [REQUIRES_POPULATION: =< 7] or [LAND_HOLDER:some trigger whose only requirement is some number of dwarves equal to or less than 7]). Most importantly, ''any'' position whose only requirement is a LAND_HOLDER requirement, regardless of what the trigger for that requirement is, will be added if another eligible starting position is REPLACED_BY it. '''A non-LAND_HOLDER position that is REPLACED_BY a LAND_HOLDER position will never appear.''' With this list compiled, the game culls all positions that are REPLACED_BY another eligible position, and then culls all positions that have the APPOINTED_BY token. '''You may not embark with any appointed positions.''' Any remaining positions are then filled by a dwarf chosen at random.

'''Positions do not automatically appear when you reach their requirements.''' For example, if you remove the ELECTED token from the Mayor, then the Mayor will never appear, even once you reach their required number of dwarves. '''For a position that does not appear at embark to appear in your fortress, it must be APPOINTED_BY another position or ELECTED.'''

Naturally, this is more complicated than it looks. '''APPOINTED_BY positions must be appointed by another position already in your fortress, or a civ-level position. Only LAND_HOLDER positions may be appointed by civ-level positions.''' LAND_HOLDER positions that are APPOINTED_BY civ-level positions are inherently tied to civ-level tokens with the ESTABLISH_COLONY_TRADE_AGREEMENTS responsibility. If a fortress meets the LAND_HOLDER_TRIGGER for a new LAND_HOLDER tier when a caravan leaves, then the next time the outpost liaison or equivalent arrives, they will offer to make you an official colony, which will allow you to select all positions for that LAND_HOLDER level. '''Each time they appear, the outpost liaison will only promote your fortress one tier up the LAND_HOLDER track.''' The biggest problem with this system is that you may set your LAND_HOLDER_TRIGGERS such that you are eligible for the first tier of LAND_HOLDER positions at embark. '''If you are eligible for the first tier of LAND_HOLDER positions at embark, then all first-tier positions will appear twice - once at embark, and again when the outpost liaison comes to appoint you to the first tier.'''

If civ-positions are neither APPOINTED_BY nor ELECTED, they still will be filled.

Read more: [[Advanced_Entity_Position_Mechanics]]

{{Category|Modding}}
{{Category|Tokens}}
[[ru:Position token]]

Advanced entity position mechanics

2026-03-12T09:35:28Z

Joostheger: found a way to combine REPLACED_BY and REQUIRES_MARKET /* [REPLACED_BY] and [REQUIRES_POPULATION] */

{{Quality|Fine}}
{{Modding}}

= Introduction =

[http://www.bay12forums.com/smf/index.php?topic=182239.0 Discussion thread on the forum]

This page documents observed and tested behavior of entity positions in Dwarf Fortress that is not fully described elsewhere on the wiki. It focuses on advanced interactions between position tokens, including appointment, succession, election, and responsibility handling, across both civilization-level and site-level entities.

The mechanics described here are based on empirical testing in world generation and fortress mode, supplemented where necessary by raw analysis. In several cases, the game’s behavior is determined by evaluation order and interaction between multiple tags, rather than by individual tokens in isolation.

This page is intended for modders and advanced players who are designing or debugging custom entity position structures. It does not restate basic position mechanics, but instead highlights edge cases, non-obvious interactions, and behaviors that may appear inconsistent or undocumented.

Unless stated otherwise, the described behavior applies to current versions of the game and may differ from older releases.

==What is an entity? What is a position?==
An [[entity]] is an organizational structure that can have relationships with other entities, usually known as a [[civilization]] or a "[[site]] government" in the game, but merchant [[guild]]s, religious organizations, necromancer towers, and [[bandit]] groups are also entities. An entity can have positions - in most cases, these are hardcoded and generated by the game, but as for civilizations and sites, the [[raw file]]s can be customised.

A position is a special relationship between a unit and an entity. The unit holding a position has a larger influence over that entity than other citizens. Positions are mostly known as [[nobles]], but in this article. the technical term is used.

=Position levels (Site/Civ) and their interaction=
There are two basic types of positions that are customizable: '''civ(ilization)''' level and '''site level'''. Positions with the tag [SITE] are at site level, positions without the tag [SITE] are at 'civ level'. These two types of nobles can be considered '''loosely related systems'''. There are a few places where they can interact with each other.

Civ-level positions are in charge of the civilization as a whole, managing national [[trade]], laws, and [[war]]s. These are, for example, the vanilla [[monarch]], [[diplomat]] and [[general]]. (Note that the general doesn't do anything in either mode in the current version.)

'''[LAND_HOLDER]''' nobles are also positions at civ-level. These units are members of the national government, but have gained authority over some land or site. Once they do, they move to that place, but their position is still regarded as a civ-level position.

Site-level position holders are members of a site government (subsidiary to the civilization), and manage local affairs in that location. These are, for example, the [[mayor]], the [[sheriff]] and the [[broker]].

==Table of interaction between different position levels==
In this table, the possible interactions between different position levels are summarized.
The header row shows the positions defining the tokens.

The left column shows the position type that is referred to.
Example:
{| {{prettytable}}
|- bgcolor="#ddd"
! referred position-type
! LAND_HOLDER
|-
| civilization
| (baron is) APPOINTED_BY:MONARCH
|}
color coding: 
* Exists in vanilla
* Possible with mods
* Not possible
* possible to some extent.
* not yet fully investigated.
{| {{prettytable}}
|- bgcolor="#ddd"
! referred position-type
! Civilization
! SITE
! LAND_HOLDER
! CONQUERED_SITE

|-
| Civilization
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION '''(1)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION

|-
| SITE
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION '''(2)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY '''(3)''' COMMANDER REPLACED_BY SUCCESSION '''(4)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION

|-
| LAND_HOLDER
| APPOINTED_BY COMMANDER REPLACED_BY '''(6)''' SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION '''(5)'''
| APPOINTED_BY COMMANDER REPLACED_BY '''(7)''' SUCCESSION '''(8)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION

|-
| CONQUERED_SITE
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
|}

Remarks:
# Works only in world-gen, if a unit with that civ-position is present at the site.
# Works only in world-gen, the site-position holding unit will then move to the capital.
# Is completely ignored
# Works only in world-gen.
# Works only in world-gen.
# Won't appear at all
# This is necessary for the landholder chain to work properly, it doesn’t work otherwise.
# This works only outside of the landholder chain, so when landholders are simply regarded as civ-level nobles. might also work in world-gen
#

== Other interactions ==

Unfortunately, interactions with positions of other entities don't seem possible, such as APPOINTED_BY: HIGH_PRIEST. With [VARIABLE_POSITIONS], positions are automatically created with codes like CUSTOM_LAW_MAKER_2, but interaction with these positions don't seem to work, either. For more info on those, see [[Variable positions]]

=General=

==Civ-level nobles living at your site==
Nobles from your civilization can come to live at your fortress. This happens in vanilla with landholders such as [[Baron]], [[Count]] and [[Duke]], with the Monarch, but sometimes also with non-landed LAND_HOLDERS.

When a civ-level noble becomes a [[citizen]] at your location, their position is shown among the site-level positions in your [[nobles screen]]. They appear to function as a site-level noble. They may have [[demand]]s, [[mandate]]s, [[squad]]s and the like. They can appoint nobles at the site-level.

If they have certain [RESPONSIBILITY]ies, they do the tasks that go with them.

==Fortress mode, world-gen and their differences==
Their are a few differences in how positions function between fortress mode (normal play mode) and the world generation (world-gen).

In '''fortress mode''', the player has some control over the appointment of nobles, limited by elections, automatic filled-in positions and succession rules. Pre-fortress mode, which is referred to as '''world-gen''', the game will always attempt to assign nobles whenever possible. It is subjected to the same rules as in fortress-mode, but there are some exceptions. In '''[[World activities]]''', which is the thing that happens in the world while you play fortress mode, it seems as if the same rules are applied as fortress mode.

A difference between player-fortress-mode and world-gen, is causes by visibility (see below). Positions that are not visible by the player and thus not available for assignment, will be available in world-gen and will thus be automatically assigned.

In fortress mode, a position that is both [ELECTED] and [APPOINTED_BY], cannot be appointed by the player and is also not elected, and can thus not be filled. But in world-gen sites however, these positions are automatically filled.

Positions with [AS_NEEDED] are almost never created and filled in world-gen (depending on their [RESPONSIBILITY]ies), but can always be used in player mode.

A position can, in fortress mode, be filled by the same unit. A unit can gain multiple positions in fortress mode, for example because of [[elections]]. This will not happen in world-gen mode: a unit can only have one position. See also remarks on 'embark' and 'Losing a position'.

In world-gen, [SUCCESSION] between civ-levels and [SITE-]levels may happen. This will not happen in fortress mode, or even off-site in [[World activities]].

In fortress mode, premature SUCCESSION may happen. This will not happen in world-gen mode.

==Units holding multiple positions in multiple entities==
A unit can hold multiple positions in its civilisation or in its site-entity, however this does not happen in world-gen. Only at player-managed sites can units be holding multiple positions at once. (It is probably not possible for a unit to hold a position in two different civilisations or two different sites.)

In world-gen, if there are too many positions to be filled, they simply stay empty until more units are available. E.G, a unit at a site might inherit a civ-level position and still remain a member of the local government. When this happens however, they move to the capital. If a unit gains a new position, either inherited or otherwise, it drops the previous one. If a unit assumes a civ-position in fortress mode, it leaves the current position.

If a unit holds the same (site-)position multiple times, it has no additional effect.

If a unit holds multiple different positions of the same entity, it has all those positions' responsibilities and properties, stacked up. Presumably, the demands for those combined positions are determined by the highest.

A unit holding a position with a succession token can be assigned another position with a (different) succession token.

A unit holding a position with a squad-position cannot hold another squad-position. It is dropped from the first, when it gets its second assigned.
A unit holding a position with a succession token cannot be assigned to a squad-position - the unit is simply not available. It works the other way around, though.

=Specific Tags and functions=
==[PRECEDENCE]==
The first defined position with precedence of 1 counts as the ruler of the civ. See also: [[Position_token#PRECEDENCE|PRECEDENCE]].

If the precedence is omitted or has a negative value, the game sets 0 as precedence, which seems to have no effect whatsoever.

When a unit has multiple positions, the name of the position with the highest rank in precedence is shown behind the unit's name.

If you omit precedence entirely, or set it to [PRECEDENCE:NONE], the position name will not be shown after the unit’s name. Your *Urist Mason* will remain simply *Mason*. This can be useful for positions that are unimportant or purely functional. The position will also not appear in the civilisation overview of your site on the world map. The position name is shown in messages, but remains hidden on the nobles screen as well. To make it visible there, use [LAND_NAME].

==[RESPONSIBILITY]ies==
Both civ and [SITE] positions can carry responsibilities. However, not all responsibilities are active for both types: some function only for civ positions, others only for site positions. When a civ noble arrives at a site and takes up residence, they do not perform responsibilities that are intended for SITE nobles. As a result, these responsibilities neither trigger their associated tasks nor unlock related game mechanics. For example, a civ-level manager living in a fortress will not perform management duties there and doesn't unlock the management-screen, even with an assigned office.
This behavior applies to the following [SITE]-level responsibilities:
* [RESPONSIBILITY:ACCOUNTING]
* [RESPONSIBILITY:BUILD_MORALE]
* [RESPONSIBILITY:HEALTH_MANAGEMENT]
* [RESPONSIBILITY:LAW_ENFORCEMENT]
* [RESPONSIBILITY:MANAGE_PRODUCTION]
* [RESPONSIBILITY:MEET_WORKERS]
* [RESPONSIBILITY:TRADE] (functions differently)
Other responsibilities may be affected as well, but have not yet been fully tested.

===World-gen effects of the [RESPONSIBILITY] of available positions ===
It is possible to cause civs and individual sites to change their behavior substantially when they reach a certain size, by controlling nobles.
* If a site can only appoint a position with [MILITARY_GOALS] after reaching a particular size, that site will not send armies on missions until the required size is reached.
* A civ-level [LAW_MAKING] position is required for the civilization to have any kind of cohesion. Without it, sites will be constantly embroiled in territorial disputes and civil wars will be commonplace.
* [MILITARY_STRATEGY] positions go out and tame wild animals. This makes your civ gain those animals as domesticated and also brings them in sieges.
* The [[Personality_facet|Personality]] of the position's holder determines how they lead the civ.

===[DELIVERS_MESSAGES]===
The only [AS_NEEDED]-position that is created in worldgen based on responsibility is that of the site-level responsibility [DELIVERS_MESSAGES].

===Outpost Liaisons and Diplomats===
Civ-positions with the responsibility [ESTABLISH_COLONY_TRADE_AGREEMENTS] ([[Outpost_Liaison|Outpost Liaison]]s) will meet with the site-noble who has responsibility for [RECEIVE_DIPLOMATS] and the highest rank of precedence (i.e. the lowest precedence value). Usually this is the [[Expedition_leader|Expedition leader]].

Once a [LAND_HOLDER] is assigned to the site, civ-positions with the responsibility [MAKE_TOPIC_AGREEMENTS] ([[Diplomat]]s) will meet with '''civ'''-level nobles present at the site who have the [RECEIVE_DIPLOMATS] responsibility. If multiple eligible nobles are available, one is selected at random. If no eligible noble is present, the diplomat leaves angrily. If the landholder is no longer present at the site, diplomats will not arrive at all.

It appears that Outpost Liaisons and Diplomats are chosen for a diplomatic mission based on availability. When multiple candidates exist, the position defined last in the raws is most often selected.

===[TRADE]===
Civ-level nobles with [TRADE] will arrive with the caravan, just as the Outpost Liaison. Their behavior is no longer active in the vanilla game, but the mechanics are still present. See [[40d:Guild_representative|Guild representative]] for more details. This civ-noble will only meet with the SITE noble with [TRADE], usually the [[Broker]].

If two civ-nobles exist with both [TRADE] and [ESTABLISH_COLONY_TRADE_AGREEMENTS], they both arrive at the same time. Even if both tokens are assigned to a single position, if more than one instance of that position exists, two of them will arrive. However in that case, somehow the elevation of the site and appointment of landholder isn't offered.

If the SITE-noble they intend to meet has both [TRADE] and [RECEIVE_DIPLOMATS], only one meeting will proceed and the other is cancelled. However, when two SITE-nobles are available, each with either [TRADE] or [RECEIVE_DIPLOMATS], both meetings will proceed and both civ-nobles will attempt to negotiate a trade agreement. It is not known what happens if these agreements are accepted or refused.

In the trade depot, the last defined position with the [TRADE] responsibility is shown as broker. However when requesting a trader, the first defined position with [TRADE] will actually go there to do the trade.

==[NUMBER]==
A position might be defined with a number. In that case, as many as defined can be available. If the positions become available, in world-gen and when embarking, they are all filled-in completely.

If the ruling position (with PRECEDENCE of 1) has a NUMBER higher than 1, a random unit of the ones holding these positions is shown as ruler in the embark screen.

A [NUMBER] of 0 (zero) has the same effect as 1.

===Automatic spreading of assumed, non-singular positions===
If there are civ positions that have a NUMBER higher then '1' and which are assumed (not APPOINTED_BY or ELECTED) but are '''not DUTY_BOUND''', these are automatically spread among the civilisation, based on population. If there are a number of '''20''' available slots of that position, they spread among a civilization with a combined population of, for example, 1000 of which your fortress has 100 (10%), '''2''' of your fortress' citizens will assume that position.
This may probably also work with elected and appointed positions, but that may be depending on the death of the current holders and this needs more testing. Assumption works within a day, anyway.

===[AS_NEEDED]===
These positions can be created automatically by the game in world-gen. This, however, only works with:
* [LAND_HOLDER]'s
* squad commanders (needs more testing)
* Messengers at sites

For all other types of positions, they're not created in world-gen, even if they are defined with RESPONSIBILITY's. For example, even in war, the game wouldn't create a MILITARY_GOALS position, if they have AS_NEEDED as number.

However, in fortress mode / player mode, these positions can be created by the player at will.

Positions with AS_NEEDED need to be created first, before any symbols are assignable as 'symbols' (objects) for the position holder to carry or wear.

Positions with AS_NEEDED cannot be created and then ELECTED in fortress mode. It only works with APPOINTED_BY.

==[REPLACED_BY], [REQUIRES_POPULATION], [REQUIRES_MARKET]==

The token [REPLACED_BY:position] means that once the replacing position meets its requirements for activation, the 'to-be-replaced' position will disappear. This is defined in [REQUIRES_POPULATION] or [REQUIRES_MARKET]. The tags are closely related to each other and seem to only have a meaningful function if combined. Nobles with [REQUIRES_POPULATION] require the population to have a specific size. Nobles with [REQUIRES_MARKET] are only activated in market sites, such as fortresses or towns. [REQUIRES_POPULATION] and [REQUIRES_MARKET] can be combined, activating that position once both requirements are met.

The [REQUIRES_MARKET] can be used to differentiate positions between hamlets and hillocks, and larger sites. IThe market always is build the year after the site is founded. So a position that is to be replaced, will be gone immediately.

The [REQUIRES_POPULATION]-tag works on the civ-level as well as on site-level, but those systems are in this mechanic strictly separated. Site-level positions cannot be replaced by civ-level positions and visa versa. This makes sense, because they both depend on their own population-count. When using REQUIRES_POPULATION on civ-level, it counts the total population of the civilisation.

See also: [[Advanced_entity_position_mechanics#Evaluation_of_Positions|Evaluation of positions]]

===Effect of replacement (and on [LAND_HOLDER]s)===

Replacement is immediate and complete - the current holding unit loses the position, even before SUCCESSION_BY_POSITION rules are applied. A position with a number of 1 will replace all the slots of a position with a higher number of slots.

Even if the next position is available but not visible, replacement still takes place. If a position is replaced, it is completely gone - it cannot be appointed, succeeded, elected or assumed any longer.
The unit immediately loses its position.

In legends, replacement is mentioned as: "(unit name) ceased to be (position name)" The replacement of an AS_NEEDED position empties the position's slot forever. In fortress mode, it may seem as if you can create new slots and appoint new units in the nobles screen, but this is reversed as soon as you close the window.

The landholder chain uses [REPLACED_BY] differently. It does not clear the position completely, but uses it for succession to the next level's position. [REPLACE_BY] is required to let that system work properly. This also means that the way in which landholders succeed (replace + as_needed) does not work in any other way.

Replacement between LAND_HOLDERS and other site- or civ positions does not work in any way. Only the vanilla replacement sequence between levels of LAND_HOLDERs does work. If the token is omitted for landholders, the landholder chain is broken, so replacement is required for the landholder system to work.

[REQUIRES_POPULATION] also does not work for [LAND_HOLDER], when you set [NUMBER] to 1. The position is not created when the required population is reached.

===What doesn't work===

'''Attention: If a position cannot be appointed, for example because of 'mutual appointment', it still exists according to replacement mechanics and will replace other positions if so defined. If a certain position(a) will be replaced by the baron's assistant, which can only be appointed by the [LAND_HOLDER] baron, than that position(s) still will be replaced from the start of the game, even if no baron or their assistant is ever present.'''

A position that is replaced by a somehow non-fillable position is still replaced. This counts for mutual-appointing positions, replacement by not-yet-assigned landholders, replacement by AS_NEEDED positions, or replacement by not-yet-appointed positions.

Replacement does not work if the replaced position is a [LAND_HOLDER], even with civ-positions. In that case, the LAND_HOLDER's position is not replaced. It does not matter if AS_NEEDED is used, or a fixed number, and it also does not matter what type of position the replacer is. So this only works (correctly) with positions that become available by REQUIRES_POPULATION.

==[CONQUERED_SITE]==

This tag determines which position is used to assign a [[Forced administrator]].

In legends mode, this is visible as an event describing the reconquest of the site: a new group is formed and the forced administrator is installed as its ruler.

All positions defined with this tag are assigned during this process, meaning multiple positions can be appointed at once.

The holder of a position marked with [CONQUERED_SITE] cannot appoint any other [SITE] positions.

Combining [CONQUERED_SITE] with [SITE] causes the position to function both as a forced administrator and as a normal site position available in fortress mode. However, this provides no meaningful additional mechanics and is effectively inferior to using [SITE] alone:
* [APPOINTED_BY] lines are completely ignored, meaning that the roles are automatically assumed.
* [SUCCESSION] is likewise ignored.
* the [CONQUERED_SITE]-position cannot appoint other [CONQUERED_SITE], [SITE] or combined positions.

There have been remarks that reclaiming a fortress is unplayable because of the lack of regular nobles. Unfortunately, it seems that it can't be fixed by modding.

=Availability and visibility=
==Availability of (new) positions==
Warning: Do not mistake "availability" for "visibility"!

Of all the possible positions existing in your site's entity, there may only be some available.
* Positions with [REQUIRES_POPULATION] require the population to have a specific size.
* Positions with [REQUIRES_MARKET] will only appear in "large" sites (which may have different rules for different site types). This tag has no effect in fort mode.
* Positions that are appointed by positions that have an AS_NEEDED number. The appointable positions only become available after an appointer position-slot is created. This works also on civ-level. If a position is appointed by a Land-holder, it only becomes available, when that level of landholder is created.

Only the replaced positions are culled and are no longer available.
A position that requires a certain population will become available, even if it doesn't have [APPOINTED_BY] or [ELECTED]. In that case, see 'automatic assignment' and 'assumption'

In fortress mode, in some cases 'succession' is evaluated immediately after a position becomes available. See: Succession.
==Visibility of positions==
A position might be available, but can still be invisible for the player in the [[nobles screen]]. The positions with their respective holders are visible for players:
* All site-positions that are already filled-in (even if they could not be re-filled-in considering current conditions)
* Site positions that are appointable by a filled-in site position
* Site positions that are appointable by a filled-in civ position, when that civ positions holder becomes a citizen of your fortress.
* Civ positions of units that are also a citizen of your fortress.
If a position becomes available, for example because a certain pop number has been reached, or if it is available from the start(like expedition leader), as long as it cannot be appointed, it still is INVISIBLE for the player.

It might strike someone as odd if a position becomes filled automatically in fortress mode when that position is not even visible. This might be the case if the current holder of a non-appointable position dies or succeeds another position. Regardless of player visibility, these positions will be automatically filled in if the necessary requisitions are met. It might happen with the expedition leader.

A situation with a non-visible but available position, is for example when a position is solely appointed by the expedition leader, when the expedition leader's position is left vacant. It can no longer be appointed by the player and is invisible. Then, it gets automatically assumed, proving that the position still was available.

A position that is both [APPOINTED_BY] and [ELECTED] is visible, but players cannot interact with it.

={{text anchor|Evaluation of Positions}}=
The game does not continuously check whether positions should become available, elected or be [REPLACE_BY]. This is well-known behavior—for example with the [[mayor]], who does not appear automatically when the required population ([REQUIRES_POPULATION]) is reached. Instead, positions must somehow be evaluated. This applies in several other situations as well

'''Cases that require a trigger:'''
* Election of a newly created position
* Election after the current holder dies
* Automatic assumption of a newly created position (this may take up to a day)
* New citizens (such as migrants) considering available positions
* Premature succession of a newly created position

'''Cases that do not wait for a trigger:'''
* Succession following the death of the previous holder
* Automatic assumption of existing positions that have become vacant

'''Triggers that cause the game to reevaluate noble positions:'''
* Succession of a [SITE]-position due to the death of the current holder
* [[Advanced_entity_position_mechanics#Election_Day|Election Day]]
* Automatic assumption of a [SITE]-position that becomes vacant
* (Re)assigning any site position manually
* Settlement elevation on the LAND_HOLDER track (e.g. gaining a [[Baron]] or [[Count]])

=Gaining a position=
There are several ways a unit can gain a position:
* Appointment: A unit is appointed by another unit or by the player.
* Election: A unit is elected by and among the members of the entity
* Assumption: A position is neither elected or appointed: a random unit just simply 'takes' the position
* Succession: a unit is the valid successor of this position(A), either by its current position(B) or because they are that position(A)-holder's heir.

Available positions will automatically be assigned to a random civ member when a new site/civ is created.

==Who can take a position==

* If so defined, a unit needs to be the right caste and/or class - it does not seem to work with creature types.
* The unit needs to be an adult member of the site or its parent civ's government; that is also CAN_LEARN or INTELLIGENT (SLOW_LEARNER cannot take positions) or otherwise is able to think.

==Appointment==

Positions that have an [APPOINTED_BY:position] token require that position to exist, to be available and appointed. Any position that is APPOINTED_BY can be appointed if the appointer's position is filled in.
For site-positions to be appointed, it is required that the appointer is present at that location.

If the appointing unit is temporarily not present, or if that position is not filled, positions depending on it cannot be appointed. This is the case with [[militia captains]], when the [[militia commander]] is on a [[mission]].

A site position cannot appoint a civ position ''or'' LAND_HOLDER in any way whatsoever.

Civ-level positions can appoint other civ-level positions and site-level positions can appoint other site-level positions.

Contrary to what has been said elsewhere, civ-level nobles also can appoint site-level nobles. They need to be at the site to do so. Landholders can appoint both site-level and civ-level nobles. These systems are therefore not as separate as was assumed.

'''Mutual appointment''' cannot take place. If these are the only requisites of the position, then the positions will never appear or get filled. These unfillable positions can be put to good use, for example, to replace a position that is no longer needed without creating a new one.

'''Self appointment''' doesn't normally work. If you have a position that is only appointed by itself, it is never appointed and also cannot be assumed. However, if the position has a number higher than 1, and is filled by multiple units (for example by another position that is now empty), than those units can re-assign or appoint each other from that their shared position.

If an APPOINTED_BY token refers to a non-existing position's code, the effects are as if the appointment token doesn't exist at all.

===Automatic appointment in world-gen and on the civ level===

Outside of fortress mode, the game will always attempt to appoint nobles whenever possible, as long as these positions are '''available''', even if they are invisible to the player.
It shows this message in legends: "(unit name) has been appointed to the position of (position name)"

In world-gen, all positions become available and are automatically appointed, taking population- and appointment-requirements into consideration.

Positions that are REPLACED_BY are culled and won't be filled.

If a citizen of your fortress holds a civ-level position that can appoint another civ-level position, the appointment will happen automatically and without player intervention. It may happen that another citizen of your fortress is appointed by that unit, creating civ-level position holders in your fortress, but it is unknown what is required to force this effect.

===Manual appointments by players in fortress mode===
In fortress mode, the positions that need to be appointed stay empty on embark. and it is the player's job to appoint those. A player can appoint a unit to any available position, according to the hereabove mentioned conditions. The player takes the role of the automatic appointment-system, but has no direct control over elections, successions and replacement. There are some differences in what is possible at world-gen sites and at player-controlled sites.

* A position that is appointed by a unit present as a fortress citizen, can be appointed, re-appointed or left vacant. This means also by civ-level nobles living as a citizen in your fortress; not when they are only visiting, like the diplomat.
* A position whose appointing positions are all either vacant or [REPLACED_BY] can no longer be appointed. If the position is already filled, it cannot be reappointed or vacated; the current holder simply remains in office.
* A position that is APPOINTED_BY a unit present as the land_holder of your site, can be appointed, reassigned or left vacant.
* A position that has SUCCESSION BY_HEIR or BY_POSITION can 'initially' be appointed and also re-appointed or left vacant, but as soon as the [[nobles]] screen closes, ''it can no longer be replaced or left vacant''. From then on, the succession-rules determine who gains that position when the current holder loses the position. This works even if the SUCCESSION:BY_POSITION-position is vacant or replaced.
* A position that is ELECTED nor APPOINTED_BY, can always be (re-)appointed by the player. This is the case with the [[Expedition leader]]. If it is left vacant however, it cannot be appointed, but will be assumed shortly after.
* A position that is both ELECTED and APPOINTED_BY, cannot be appointed by the player. Contrary to world-gen sites, its slot is visible, but it doesn't show the +-sign. This is either by AS_NEEDED or by a fixed number. Even if the position somehow gets filled (re)assignment is never possible
* A player can appoint a number of units to a position, as much as the NUMBER token dictates. If it is AS_NEEDED, the player may create as many slots as they like, also contrary to world-gen sites.
* A civ-position can never be appointed, even if the appointing civ noble is a citizen of your fortress. A civ position also never can be re-assigned or left vacant, would that position be defined as appointed by a site-position.

==Election==
Read more in [[Elections]]. The message that is shown is: "(creature name) has been elected to the position of (position name)"

In worldgen, there is no functional difference between ELECTED and non-appointment, except that elected nobles tend to have high social skills and/or skills related to the position, while non-elected ones are assigned randomly. See: [[Elections]]

A succession goes before an election.

A position that is both ELECTED and APPOINTED_BY never gets elected. Even if the appointees' position somehow gets filled, (re)-elections won't happen. So, it doesn't seem possible to have an elected position become available when a certain other position becomes filled.

An ELECTED civ-(or LAND_HOLDER) position at your site will never be (re)-elected in fortress mode. So real (re-)election only works with SITE-positions.

=== {{text anchor|Election Day}} ===
Election Day takes place on the 17th of Summer. On this day, a full reevaluation is performed, including all currently elected positions, which are subject to re-election. Contrary to the information on [[Elections]], nothing occurs at the start of a season.

Positions that are both [APPOINTED_BY] and [ELECTED] will not be re-elected on Election Day when assigned through [SUCCESSION].

=== Election Eligiblity ===
Any citizen may stand for election. Eligibility cannot be restricted using [ACCEPTED_CREATURE], [REJECTED_CREATURE], [ACCEPTED_CLASS], [REJECTED_CLASS], or [GENDER]. Units currently having a [SUCCESSION]-position even may be elected for a position with a [SQUAD]-token, which is otherwise impossible to assign or even succeed.

=== Skills ===
In elections, skills are taken into account for the tokens of the position which is elected.
{| class="wikitable"
|+ Relevant skills per position token
|-
! Position Token !! Relevant skills
|-
| Responsibility [[Position_token#DELIVER_MESSAGES|[DELIVER_MESSAGES]]] || [[Ambusher]], [[Observer]] and [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#ACCOUNTING|[ACCOUNTING]]] || [[Record_keeper|Record keeper]]
|-
| Responsibility [[Position_token#ESPIONAGE|[ESPIONAGE]]] || [[Schemer]]
|-
| Responsibility [[Position_token#HEALTH_MANAGEMENT|[HEALTH_MANAGEMENT]]] || [[Diagnostician|Diagnostician]]
|-
| Responsibility [[Position_token#MAKE_INTRODUCTIONS|[MAKE_INTRODUCTIONS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#MAKE_PEACE_AGREEMENTS|[MAKE_PEACE_AGREEMENTS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#MAKE_TOPIC_AGREEMENTS|[MAKE_TOPIC_AGREEMENTS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#MANAGE_PRODUCTION|[MANAGE_PRODUCTION]]] || [[Organizer]]
|-
| Responsibility [[Position_token#MEET_WORKERS|[MEET_WORKERS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#RECEIVE_DIPLOMATS|[RECEIVE_DIPLOMATS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#RELIGION|[RELIGION]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#TAME_EXOTICS|[TAME_EXOTICS]]] || [[Animal_trainer|Animal trainer]]
|-
| Responsibility [[Position_token#TRADE|[TRADE]]] || [[Social_skill|Social skills]] and [[Appraiser|Appraiser]]
|-
| [[Position_token#SQUAD|[SQUAD]]]-token || [[Tactician]] and [[Leader]]
|}

==Assumption==

A position that is not APPOINTED_BY nor ELECTED, or is appointed by positions that are not available in your site or civ, will be assumable by a random dwarf. If it has responsibilities that require certain skills, then these are taken into consideration on embark, but not when the position is assumed during the actual game.

Normally, one to three units will take the into consideration to assume a position. Most of the time when there are multiple open positions, only a single unit will assume all of them. However, a position that has REJECTED_CREATURE, REJECTED_CLASS, ALLOWED_CREATURE or ALLOWED_CLASS will be filled with all different units, even if the creature or class mentioned is irrelevant. It seems that this forces the game to loop over all the available units.

The message that is shown in Legends mode is: "(unit name) has assumed the position of (position name)". This may also take place in fortress mode, which then shows this message to the player.

If an assumable position becomes empty, it will be assumed within a day. This is the case when you leave the position of expedition-leader vacant. It also happens with entities.

Assumable positions that become empty will not be assumed if that position has a valid [SUCCESSION] -successor. In that case, the successor inherits the position.

Even positions that are somehow invisible because they cannot be directly APPOINTED_BY players, can be assumed.

When you embark, the assumable positions are automatically assigned to a random unit. If there are multiple of these positions at embark, they all are assigned to the same unit. If there are enough positions available, multiple units may gain a position, but often no more than three different ones.

If a dwarf in fortress mode assumes a position, that already has another position, it will leave the current position empty. When that position also is assumed, then this will continue until all positions have a dwarf appointed to them, with no other position.

A unit that already has a position with a [SUCCESSION] token won't take assumable positions into consideration that have a [SQUAD] token. This can be used by the modder to prevent unwanted loss of current positions.

A position that has an appointer which got replaced because of REPLACED_BY, will not become assumable. Also, positions that have an AS_NEEDED appointer that is not yet filled (or ever), will also not be assumed.

==Succession==

If a position-holder dies or advances to a new position via succession, the position will be granted to another unit based on the [SUCCESSION] tag. If they have an heir or the succeeding position exists, that unit will be assigned. If not, a new one will be appointed according to the usual rules. The message that is shown is: "(creature name) being the rightful heir, has inherited the position of (position name)"

The succeeding creature will also lose its previous position. When succession is defined using BY_POSITION, the unit naturally loses the referenced position. However, it also loses any other positions it may hold. If a unit could simultaneously inherit multiple positions, the last-defined succession overrides the earlier one, clearing the previously acquired position

Succession works both at site-level and at civ-level, both in world-gen and in fortress-mode. Succession by position on the civ-level is also visible and functional in fortress-mode. If both civ-level nobles are a citizen of your fortress, succession is applied visually. Vanilla example: The [[druid]] is succeeded by the [[acolyte]]. This means that as soon as the druid dies, the acolyte takes over.

When a position that is succeeded by position becomes available, immediately it is checked if a position-successor is available and the position is filled with that unit. Even if this is an [ELECTED] position, succession goes first. When elections eventually do happen, succession plays no role.

It is possible to assign multiple levels of [SUCCESSION:BY_POSITION] in different positions, creating a line of positions where the death of one causes all those "below" them to advance.

A position can have multiple tokens with position-succession. It looks to be random which one is used. It is not always:
* The first or last defined token
* The first or last appointed unit
* the oldest or youngest
* one with a higher or lower precedence
* a unit with relevant skills

When a position is defined with a Succession-type, that unit cannot have another position that has a Squad-type. If the succession-position itself has a squad, than it can be assigned another position with a squad, but then it will loose the previous succesion position. See further details by "Squad"

Assumed positions can also be succeeded by position, if the current holder dies.

If the successor is an AS_NEEDED position, the used unit will leave a vacant position-slot on its removal by succession. This empty slot remains a real slot, which will only be cleaned up if you (un)appoint a unit to this position-series. It isn't cleaned up after regular position validation.

A civ-level position of a unit living at your site might be inherited by a unit holding that does not currently live at your site. This, unfortunately, moves that position to a unit off site. This may also happen with the landholder of your site, for example when it is succeeded by another civ-level position. This currently poses an unsolved challenge.

===Eligibility for succession===
Succession is restricted by the tokens [ACCEPTED_CREATURE], [REJECTED_CREATURE], [ACCEPTED_CLASS], [REJECTED_CLASS] and [GENDER].

===Site and civ combined succession===

Succession can work when combining site positions with civ-level positions or land_holders, but only in world-gen mode. In fortress mode, it only works with combining the same level of nobles, with Landholders regarded as civ-level. So, in fortress mode, a site's position cannot succeed a landholder's position and it cannot succeed another type of civ-level position, and vice versa.

This won't work even if the positions:
* are AS_NEEDED or having a fixed number.
* Are LAND_HOLDERs.

===Succession [BY_HEIR]===

When a heir is needed for succession, all children and then other relatives are validated. They cannot take the position if their status does not allow it, for example if they have become a member of another civilisation. See: "Who can take a position". If the unit has no valid heir on that location, the position may go to a unit living on another site. This may cause the title of Landholder of some land to be inherited by a unit living somewhere else. That might be a problem, because then you lose your landholders.

===Premature Succession===

There are cases where [SUCCESSION:BY_POSITION] is applied prematurely: at the moment a position is first created and becomes appointable or assumable, rather than after a current holder leaves. In this situation, the succession mechanism assigns a holder immediately, without any player interaction.

When a position becomes available for the first time, the game checks whether a valid successor-by-position exists. If so, that unit is assigned instantly. It can affect positions that would normally be appointed or elected by the player, causing succession to trigger before the player has any opportunity to intervene.

This behavior occurs only in Fortress mode, but can be applied both on [SITE]-positions as well in civ-positions. That last one however is a bit harder to control. Example: [[Advanced entity position mechanics#The Archduke|The Archduke]]

This premature succession only occurs the first time a position becomes available (i.e. when it is created and becomes appointable or assumable). Even if the position remains vacant and the conditions for succession improve later, premature succession will not trigger again. From that point onward, only normal succession rules apply.

Using premature succession, a position that has [ELECTED], [APPOINTED_BY], or both, can be filled directly.
Notably, positions that combine [ELECTED] and [APPOINTED_BY] are normally impossible to fill through regular mechanics. Premature succession bypasses both election and appointment entirely, making this combination uniquely reachable through this mechanism.

No initial election takes place, and no subsequent elections will ever occur for that position. Succession always takes precedence over election, both in premature succession and in normal succession cases.

This behavior applies only in Fortress mode, not during world generation. World-gen uses simplified and more efficient mechanics, and this interaction does not occur there. Premature succession can affect both site-level and civilization-level positions.

====Multiple succession chains====

Multiple succession chains may be defined and are resolved in the order they appear in the raws.

If a position has both:
* a direct succession chain (A → C), and
* a multi-step chain (A → B → C),

and intermediate positions are vacant, resolution proceeds according to raw order. A common outcome is:
# The direct succession (A → C) is applied first, assigning A to C.
# The remaining chain then advances (A → B).
# If C still has empty slots, the final step (B → C) may occur.

If position B is already filled, behavior depends entirely on raw definition order:
* nothing may happen, or
* B may move to C first, followed by A moving to B.
====Working triggers====
Premature succession is triggered when a succeedable position is created under the following conditions:
* The succeedable position is created because its [REQUIRES_POPULATION] threshold is reached. This applies even if the position is not [APPOINTED_BY]. Premature succession takes priority over automatic assumption (e.g. the mayor declaring themselves within a day).
** The position must either be assumable or appointed by an existing position. When said appointer-position also just has been created, the premature succession of the succeedable position happenes, even when the appointer-position is empty.
* The succeedable position can be [APPOINTED_BY] another position of the same level (site or civ) that has just been created because its [REQUIRES_POPULATION] was reached.
* The succeedable position can be appointed by another [SITE] [AS_NEEDED] position that has just been created and filled.
* The succeedable (site or civ) position is [APPOINTED_BY] the [LAND_HOLDER] position, which has just been created due to site elevation. This typically resolves when the diplomat leaves the map, at which point the landholder position becomes active.
* If all other requirements are met, premature succession can occur immediately after unpausing following embark, for positions with [REQUIRES_POPULATION:7].

====Non-working triggers====
Premature succession does '''not''' occur in the following cases:
* An [AS_NEEDED] succeedable position slot is manually created by the player while its succeeding position is already filled. [AS_NEEDED] positions must always be appointed after creation.
* The succeeding position is filled after the succeedable position becomes available. The moment of creation is the decisive trigger; filling the source position later is too late.
* The succeedable position can be appointed by another site or civ position with a fixed number of slots that has just been appointed. In this case, the succeedable position is just available for appointment itself, nothing more
* Any situation occurring during world generation.
* The succeeding position is [REPLACED_BY] the succeedable position. In this case, replacement removes the unit from the source position first, leaving no holder available for the succession mechanism to use.rst, leaving no holder available for the succession mechanism to use.
* The position is [APPOINTED_BY] a civ-level position, that just became a citizen of your fortress. It must be noted that those civ-level positions were active all that time and the succeedable position could be appointed even before. The monarchs arrival does not trigger premature succession

=Losing a position=

A unit can lose a position when:
* It dies
* It succeeds another position, even if it has nothing to do with the previous position.
* It is assigned to another SQUAD-holding position
* It is convicted of a crime.
* Another unit is ELECTED for the position
* Its position becomes replaced
* Another unit is appointed by the player, or the position is left vacant.
* It has assumed another position, as this always leaves the previous position vacant.

=Embarkment=
Two types of positions are automatically filled by embark.
* Positions without [APPOINTED_BY] or [ELECTED] (assumable). All these positions, even with a NUMBER higher than 1, are all filled with one to three dwarves. Contrary to assumption, this doesn't take into account any limitations. REJECTED_CLASS, ALLOWED_CLASS, REJECTED_CREATURE, ALLOWED_CREATURE and GENDER are applied, but without the normal spread you may expect with assumptions. Also it doesn't look at [SUCCESSION] and [SQUAD] limitations.
* Positions that are elected are filled-in by the normal election rules.

Positions that have a defined appointer are never initially filled at embark.

All positions that don't have [REQUIRES_POPULATION] or with a [REQUIRES_POPULATION] of 7 or lower, will be available at embark.

=Land Holders=

A Landholder is a '''special civ-level noble''' who gets a certain piece of land to hold, when that land is elevated to a certain level, determined by the tag [LAND_HOLDER] and by the landholder triggers in the game's settings. In vanilla, these are the baron, the count and the duke.

A unit gaining the landholder position does not migrate to that specific named land. In world-gen, they stay just where they are, probably at the capital. In fortress mode, you can suggest a citizen for the role. So for the time being that works.

Succession is then a real issue. If you use BY_HEIR, its solved when that landholder has children living at your site. But when its not the case, the title just goes to anyone randomly. Succession BY_POSITION works, but only in the civ-chain, and there's no way to guarantee a civ-holder is at your site at that time. Even with 'automatic spread' positions, it goes to one of them randomly.

==Functioning of the regular landholder chain==

The distinct difference between a landholder and a regular civ-level noble, is that a landholder may gain the position of landholder "of (sitename)" They are then seen as ruler of a particular site.

For a land_holder position to function as such, it has a few requirements:
* NUMBER:AS_NEEDED
* The first landholder-number of 1 is defined.
* No SITE (so civ) tag in that position.
*REPLACED_BY the next level landholder
If a landholder is defined with differentiating properties, it will function like a regular noble. A higher-up landholder that lacks the required tokens or connections will then not be used in elevation.

If a fortress meets the trigger for a new LAND_HOLDER tier when a caravan leaves, then the next time the outpost liaison or equivalent arrives, they will offer to make you an official colony, which will allow you to select all positions for that LAND_HOLDER level. Each time they appear, the outpost liaison will only promote your fortress one tier up the LAND_HOLDER track.

The landholder's LAND_NAME is not required for the functioning of this system. If omitted, messages will be shown with a more generic text.

==Appointment==

This mechanism differs from the regular methods of position management. It ignores all regular appointment- and election rules, so it more or less functions like automatic assignment. A landholder is, in vanilla, appointed by the monarch. Changing this doesn't seem to do anything. If they are appointed by a site-position, a not-yet-existing civ-position, or not appointed at all: the system keeps working as usual.

A landholder can appoint civ-positions and site positions. This works as expected: the positions only are appointed then when that landholder becomes available on civ-level or when he arrives at that site for site-level positions.

If your rank of landholder is the first of its rank in the realm, and is the sole appointer of some civ-position, then immediately as it gains the title, it will appoint the empty civ-slots. This may happen on your site, but the frequency and certainty is hard to determine.

==Succession==

Succession rules are applied to some extent:
* In world-gen it works according to succession rules, and site-positions can be used here. This means that a site position or a civ-position can inherit a landholder position, and vice versa.
* In fortress mode, once a landholder has been appointed, it then can inherit civ-level positions, and vice versa. This means that your baron can become king.
* Succession rules do not apply within the [LAND_HOLDER] chain; a count will not inherit a baron's land. This is because succession does not work well with the AS_NEEDED token.
* Premature succession works in fortress mode with landholders. If a unit gets a landholder's position and that landholder is the appointer of an as yet empty position, which is defined as succeeding from a third one, then the succession is immediately applied. The landholder themselves can even be the successor of a newly created position.
* A landholder's position is, in fortress mode, not successionable by a site-position or vice versa

===Impossibilities for succession by a site-position===
It would be very beneficial if the landholder can be succeeded by a [SITE]-position. So far, the following tests have not lead to positive results:
* making landholder and site-position both non-[DUTY_BOUND]
* make the site-position be [APPOINTED_BY] the landholder and/or the monarch
* give landholder and site-position [REJECTED_CREATURE]
* Let the monarch live at your site when succession could happen.
* Let the site-position be [REPLACED_BY] the landholder.

If the vanilla [SUCCESSION:BY_HEIR]-tag is omitted, a seemingly random unit somewhere in the realm is assigned this position.

==Nomination==

The player is able to nominate a unit to become the LAND_HOLDER, but this only works with units of [LAND_HOLDER] level 1. The player can select all units, only limited by the PRECEDENCE of the current units' positions.

A unit that has a position with a PRECEDENCE lower or equal to that of the landholder's position, cannot be selected. This means that a baron (or count) from another site or the monarch cannot be selected, because their precedence is lower or equal.

The GENDER token does not work here: also units with the wrong gender (sorry) can be selected.

==Levels==
In mods, up to 10 levels of LAND_HOLDER may be defined.

If a landholder is replaced by a wrong landholder number (1 replaced by 3), then the number 3 is still correctly attached to the settlement.

If the current landholder has the highest available landholder number, then the next elevation will not happen - the diplomat will not elevate your fortress to a higher position, even if that position might be REPLACED_BY a lower landholder.

These chains do work:
* 1 -> 2a - > 2b -> 3
* 1 -> 3 -> 2 -> 4

These chains do not work:
* 2 -> 3 (need to start at 1)
* 1 -> 4 -> 2 -> 3 (stops after 4 as the highest)
* 1a -> 2, 1b -> 2 (only 1a and 2 work, 1b is not used)

==Moving landholders==

It may happen that a land-holder no longer lives at the site which they are the landholder of, specifically when the current landholder dies, leaving the title to an heir living somewhere else.

To prevent this from happening, you can make their succession from heir and make sure that their kids live at your site. Or, you can make their position succeeded by another civ position, and make it so that this civ position is somehow available on your site. But if multiple of these positions exist, it cannot be guaranteed that a citizen of your fortress will inherit the title.

In world gen, a landholder lacking the DUTY_BOUND-token will also move to the site they like, according to legends mode.

==Replacement by a generic civ-position==

If a landholder is replaced by an AS_NEEDED non-landholder civ-position, then this will work: the current landholder loses that title upon settlement-elevation and gains that civ-title. However, the civ-title lacks the landholder-property of being attached to the land. It will not show the name of the settlement alongside the position's name. So no "minister of Shovelmounts"

If a landholder is replaced by a general AS_NEEDED civ-position, that itself is also replaced by a generic AS_NEEDED civ-position, then firstly the elevation is executed and also the unit gains that new position. However, he immediately loses it, because an AS_NEEDED position that is replaced by another position can be filled initially, but units wont be able to hold that title.

==Landholder with fixed number==

A landholder's position that has a fixed number will be created and filled directly when the civilisation is born, so this position slot is then not available for the regular landholder-mechanic and will also not be used. That landholder will thus not be attached to a settlement.

It doesn't matter if the landholder's position is connected to the regular landholder's-chain with the REPLACE_BY token.

==Responsibilities==

When given a certain [RESPONSIBILITY], a landholder may function as a regular civ-level noble. If the position has [TRADE] or [OUTPOST_NEGOTIATING] responsibilities, then the landholder functions both as a diplomat and as an actual land holder. A landholder with the [MILITARY_STRATEGY] responsibility will travel around taming creatures in world-gen, according to legends mode.

Besides that, the responsibilities work the same as with any other on-site living position-holder, civ or otherwise.

=Military=
==Squad management==
In the vanilla game, the Squad interface only becomes available after a militia commander has been appointed. Until then, the window displays:{{DFtext|You must appoint somebody first to create a squad.}}

What’s surprising is how this is determined internally. In the entity raw definition, '''only the last two positions that include a [SQUAD] token are checked''' to decide whether the interface is accessible at all. As a result, if your hierarchy defines commanders A through E, appointing '''Commander D or E''' unlocks squad formation, while appointing A–C does nothing.

In other words, squad availability is not tied to ''having a militia commander'', but to ''which specific positions happen to be last in the raw list''—a notably hacky implementation.

These 'last two' are always the last two '''available positions.''' So if they get [REPLACED_BY] or become available because of [REQUIRES_POPULATION], the game adapts to those.

==Squad assignment==

Squads can be assigned, even if the leader position has no holder.

A specific unit can only have one position associated with a squad. If it gains another 'squad holding position', it is unassigned from the first one. This does not work with a 0-squad, so only 1+squads are taken into consideration. This technique can possibly be used to distribute all positions equally among all citizens. It does however not work with election and assumption.

If a civ-level position is associated with a squad and it gets a site-level squad-holding position assigned, it loses the current civ-position.

Squads can get really messed up, if you make the position (or multiple) either elected or not-elected and not-appointed, then this can cause the game to assign multiple squads to the same unit. Automatic assignment and election does not take squads into account, but the nobles screen does. This can cause the positions to be cleared as the game figures out that they have more than one position, and immediately get elected or assumed again.

Positions that cannot have a squad-position:
* A site- or civ-position with a [SUCCESSION] token cannot be appointed a squad-holding-position. The other way around, however, does work. For example, if a site-position with a [SUCCESSION]-token is appointed to a unit that has already a position with [SQUAD]. But when that squad position is assigned to another unit, it cannot be assigned back.
* A position with [SUCCESSION] can also not be assigned as a '''member''' of a squad.
* A squad-holding position with a formed squad cannot be appointed to another squad holding position.

If a position has at least one squad member, it cannot be left vacant. First, the squad has to be disbanded, then the position may be cleared.

==0-squads==
A 0-Squad is defined in a position as [SQUAD:0:member:members]. It does not seem to do anything useful as of now.
* It cannot be used to activate the [[Squad|military interface]]
* It does not restrict the assignment of [SUCCESSION] positions.
* Assigning this position does not clear any previously held squad position.
* The [[Leader]] and [[Tactician]] skill are not marked as relevant skills and are not taken into account in elections.
* It cannot be formed as a squad.

=Further testing=
The following questions may need additional testing. Feel free to add or answer
* Everything regarding COMMANDING and army-structure
** [http://www.bay12forums.com/smf/index.php?topic=175437.msg8331668#msg8331668]
** [http://www.bay12forums.com/smf/index.php?topic=165213.msg8335682#msg8335682]
** [http://www.bay12forums.com/smf/index.php?topic=174584.msg8026854#msg8026854]
* Everything regarding CONQUERED_SITE, but it is presumably just like site. But what if you combine SITE or LAND_HOLDER with it?
* Stuff about the monarch, its arrival and its entourage.

=Oddities (Bugs)=
Almost everything on this page could be called an oddity. Because of their unexpected usability, some may also be referred to as “undocumented features.” Others, however, are simply odd and not particularly useful, yet I hesitate to call them “bugs.”
* If a certain threshold is reached that makes an elected position electable, and the triggering event that initiates this evaluation is an assumption, then the resulting assumption is also referred to in the messages as an election

=Examples=

===The Founder===
The founder is a single dwarf, appointed at embark. They will be the only one ever to have this position and are not replaceable. When they lose their position some way, the position will not be assumed by another dwarf.
{{gamedata|title=The Founder|
[POSITION:THE_FOUNDER]
[NAME:the founder:founders]
[NUMBER:1]
[SITE]
[ALLOWED_CREATURE:DWARF:ALL] - will only be filled at embark, but not assumable later.
[REJECTED_CREATURE:DWARF:ALL] - will only be filled at embark, but not assumable later.
[SUCCESSION:BY_POSITION:THE_FOUNDER] - not unassignable, also cannot be assigned to a [SQUAD] position.
[PRECEDENCE:200]
Non APPOINTED_BY
Non ELECTED
Optional: Add responsibilities to make the game select a unit with certain skills.
}}
===Marriage bar===
Dwarven matrons are held in great honour. Upon marriage, a female dwarf is no longer expected to perform menial labour. All dwarven males hold this position by default, granting their spouses exemption from menial work.

The position becomes available with the arrival of the first migrants; otherwise, on embark, it would be assumed by females. Its succession rule is non-functional, but this prevents the player from unassigning the position. A squad size of 1 and the succession rules together prevent a unit from assuming the position more than once.

With precedence set to NONE, the position name is hidden, while LAND_NAME remains visible on the nobles screen. All married females receive the suffix “, Mrs.” and are marked as Nobles.

The practical usefulness of this position is debatable, but it serves as a clear demonstration of several mechanics.
{{gamedata|title=Mrs. Urist|

[POSITION:MRS_URIST]
[NUMBER:300]
[SITE]
[ALLOWED_CREATURE:DWARF:MALE]
Not APPOINTED_BY
Not ELECTED
[LAND_NAME:Dwarven male]
[NAME:dwarven male:dwarven male]
[PRECEDENCE:NONE]
[SPOUSE_FEMALE:, Mrs.:spouses]
[MENIAL_WORK_EXEMPTION_SPOUSE]
[REQUIRES_POPULATION:8]
[SUCCESSION:BY_POSITION:MONARCH]
[SQUAD:1:member:members]
}}
===The Archduke===
The archduke is the leader of the civilization, but exists only from landholder 4-level. Until then, its position remains vacant. When a settlement is elevated to tier 4 (grand duke), the grand duke can appoint the ruler of the civilisation, the archduke. Because of 'Premature Succession', they themself inherit that position immediately, but only when in fortress mode. Its heir then becomes grand duke.
{{gamedata|title=The Archduke| no POSITION:MONARCH or other PRECEDENCE:1

[POSITION:THE_ARCHDUKE]
[NAME:archduke:archdukes]
[NAME_MALE:archduke:archdukes]
[NAME_FEMALE:archduchess:archduchesses]
[LAND_NAME:a archduchy]
[NUMBER:1]
[PRECEDENCE:1]
[SUCCESSION:BY_POSITION:GRAND_DUKE]
[APPOINTED_BY:GRAND_DUKE]
(add additional monarch-stuff, like spouse name, demands etc.)

[POSITION:GRAND_DUKE]
[NAME:grand duke:grand dukes]
[NAME_MALE:grand duke:grand dukes]
[NAME_FEMALE:grand duchess:grand duchesses]
[NUMBER:AS_NEEDED]
[LAND_HOLDER:4]
// Optional ...
[PRECEDENCE:19]
[LAND_NAME:a archduchy]
[RESPONSIBILITY:LAW_MAKING]
[RESPONSIBILITY:RECEIVE_DIPLOMATS]
[SUCCESSION:BY_HEIR]
[APPOINTED_BY:THE_ARCHDUKE]
(add additional landholder-stuff)

!!add to [POSITION:DUKE]
[REPLACED_BY:GRAND_DUKE]

}}
{{Category|Modding}}
{{Category|Entities}}
{{Category|Guides}}

Advanced entity position mechanics

2026-03-12T09:27:49Z

Joostheger: /* Succession */

{{Quality|Fine}}
{{Modding}}

= Introduction =

[http://www.bay12forums.com/smf/index.php?topic=182239.0 Discussion thread on the forum]

This page documents observed and tested behavior of entity positions in Dwarf Fortress that is not fully described elsewhere on the wiki. It focuses on advanced interactions between position tokens, including appointment, succession, election, and responsibility handling, across both civilization-level and site-level entities.

The mechanics described here are based on empirical testing in world generation and fortress mode, supplemented where necessary by raw analysis. In several cases, the game’s behavior is determined by evaluation order and interaction between multiple tags, rather than by individual tokens in isolation.

This page is intended for modders and advanced players who are designing or debugging custom entity position structures. It does not restate basic position mechanics, but instead highlights edge cases, non-obvious interactions, and behaviors that may appear inconsistent or undocumented.

Unless stated otherwise, the described behavior applies to current versions of the game and may differ from older releases.

==What is an entity? What is a position?==
An [[entity]] is an organizational structure that can have relationships with other entities, usually known as a [[civilization]] or a "[[site]] government" in the game, but merchant [[guild]]s, religious organizations, necromancer towers, and [[bandit]] groups are also entities. An entity can have positions - in most cases, these are hardcoded and generated by the game, but as for civilizations and sites, the [[raw file]]s can be customised.

A position is a special relationship between a unit and an entity. The unit holding a position has a larger influence over that entity than other citizens. Positions are mostly known as [[nobles]], but in this article. the technical term is used.

=Position levels (Site/Civ) and their interaction=
There are two basic types of positions that are customizable: '''civ(ilization)''' level and '''site level'''. Positions with the tag [SITE] are at site level, positions without the tag [SITE] are at 'civ level'. These two types of nobles can be considered '''loosely related systems'''. There are a few places where they can interact with each other.

Civ-level positions are in charge of the civilization as a whole, managing national [[trade]], laws, and [[war]]s. These are, for example, the vanilla [[monarch]], [[diplomat]] and [[general]]. (Note that the general doesn't do anything in either mode in the current version.)

'''[LAND_HOLDER]''' nobles are also positions at civ-level. These units are members of the national government, but have gained authority over some land or site. Once they do, they move to that place, but their position is still regarded as a civ-level position.

Site-level position holders are members of a site government (subsidiary to the civilization), and manage local affairs in that location. These are, for example, the [[mayor]], the [[sheriff]] and the [[broker]].

==Table of interaction between different position levels==
In this table, the possible interactions between different position levels are summarized.
The header row shows the positions defining the tokens.

The left column shows the position type that is referred to.
Example:
{| {{prettytable}}
|- bgcolor="#ddd"
! referred position-type
! LAND_HOLDER
|-
| civilization
| (baron is) APPOINTED_BY:MONARCH
|}
color coding: 
* Exists in vanilla
* Possible with mods
* Not possible
* possible to some extent.
* not yet fully investigated.
{| {{prettytable}}
|- bgcolor="#ddd"
! referred position-type
! Civilization
! SITE
! LAND_HOLDER
! CONQUERED_SITE

|-
| Civilization
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION '''(1)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION

|-
| SITE
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION '''(2)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY '''(3)''' COMMANDER REPLACED_BY SUCCESSION '''(4)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION

|-
| LAND_HOLDER
| APPOINTED_BY COMMANDER REPLACED_BY '''(6)''' SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION '''(5)'''
| APPOINTED_BY COMMANDER REPLACED_BY '''(7)''' SUCCESSION '''(8)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION

|-
| CONQUERED_SITE
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
|}

Remarks:
# Works only in world-gen, if a unit with that civ-position is present at the site.
# Works only in world-gen, the site-position holding unit will then move to the capital.
# Is completely ignored
# Works only in world-gen.
# Works only in world-gen.
# Won't appear at all
# This is necessary for the landholder chain to work properly, it doesn’t work otherwise.
# This works only outside of the landholder chain, so when landholders are simply regarded as civ-level nobles. might also work in world-gen
#

== Other interactions ==

Unfortunately, interactions with positions of other entities don't seem possible, such as APPOINTED_BY: HIGH_PRIEST. With [VARIABLE_POSITIONS], positions are automatically created with codes like CUSTOM_LAW_MAKER_2, but interaction with these positions don't seem to work, either. For more info on those, see [[Variable positions]]

=General=

==Civ-level nobles living at your site==
Nobles from your civilization can come to live at your fortress. This happens in vanilla with landholders such as [[Baron]], [[Count]] and [[Duke]], with the Monarch, but sometimes also with non-landed LAND_HOLDERS.

When a civ-level noble becomes a [[citizen]] at your location, their position is shown among the site-level positions in your [[nobles screen]]. They appear to function as a site-level noble. They may have [[demand]]s, [[mandate]]s, [[squad]]s and the like. They can appoint nobles at the site-level.

If they have certain [RESPONSIBILITY]ies, they do the tasks that go with them.

==Fortress mode, world-gen and their differences==
Their are a few differences in how positions function between fortress mode (normal play mode) and the world generation (world-gen).

In '''fortress mode''', the player has some control over the appointment of nobles, limited by elections, automatic filled-in positions and succession rules. Pre-fortress mode, which is referred to as '''world-gen''', the game will always attempt to assign nobles whenever possible. It is subjected to the same rules as in fortress-mode, but there are some exceptions. In '''[[World activities]]''', which is the thing that happens in the world while you play fortress mode, it seems as if the same rules are applied as fortress mode.

A difference between player-fortress-mode and world-gen, is causes by visibility (see below). Positions that are not visible by the player and thus not available for assignment, will be available in world-gen and will thus be automatically assigned.

In fortress mode, a position that is both [ELECTED] and [APPOINTED_BY], cannot be appointed by the player and is also not elected, and can thus not be filled. But in world-gen sites however, these positions are automatically filled.

Positions with [AS_NEEDED] are almost never created and filled in world-gen (depending on their [RESPONSIBILITY]ies), but can always be used in player mode.

A position can, in fortress mode, be filled by the same unit. A unit can gain multiple positions in fortress mode, for example because of [[elections]]. This will not happen in world-gen mode: a unit can only have one position. See also remarks on 'embark' and 'Losing a position'.

In world-gen, [SUCCESSION] between civ-levels and [SITE-]levels may happen. This will not happen in fortress mode, or even off-site in [[World activities]].

In fortress mode, premature SUCCESSION may happen. This will not happen in world-gen mode.

==Units holding multiple positions in multiple entities==
A unit can hold multiple positions in its civilisation or in its site-entity, however this does not happen in world-gen. Only at player-managed sites can units be holding multiple positions at once. (It is probably not possible for a unit to hold a position in two different civilisations or two different sites.)

In world-gen, if there are too many positions to be filled, they simply stay empty until more units are available. E.G, a unit at a site might inherit a civ-level position and still remain a member of the local government. When this happens however, they move to the capital. If a unit gains a new position, either inherited or otherwise, it drops the previous one. If a unit assumes a civ-position in fortress mode, it leaves the current position.

If a unit holds the same (site-)position multiple times, it has no additional effect.

If a unit holds multiple different positions of the same entity, it has all those positions' responsibilities and properties, stacked up. Presumably, the demands for those combined positions are determined by the highest.

A unit holding a position with a succession token can be assigned another position with a (different) succession token.

A unit holding a position with a squad-position cannot hold another squad-position. It is dropped from the first, when it gets its second assigned.
A unit holding a position with a succession token cannot be assigned to a squad-position - the unit is simply not available. It works the other way around, though.

=Specific Tags and functions=
==[PRECEDENCE]==
The first defined position with precedence of 1 counts as the ruler of the civ. See also: [[Position_token#PRECEDENCE|PRECEDENCE]].

If the precedence is omitted or has a negative value, the game sets 0 as precedence, which seems to have no effect whatsoever.

When a unit has multiple positions, the name of the position with the highest rank in precedence is shown behind the unit's name.

If you omit precedence entirely, or set it to [PRECEDENCE:NONE], the position name will not be shown after the unit’s name. Your *Urist Mason* will remain simply *Mason*. This can be useful for positions that are unimportant or purely functional. The position will also not appear in the civilisation overview of your site on the world map. The position name is shown in messages, but remains hidden on the nobles screen as well. To make it visible there, use [LAND_NAME].

==[RESPONSIBILITY]ies==
Both civ and [SITE] positions can carry responsibilities. However, not all responsibilities are active for both types: some function only for civ positions, others only for site positions. When a civ noble arrives at a site and takes up residence, they do not perform responsibilities that are intended for SITE nobles. As a result, these responsibilities neither trigger their associated tasks nor unlock related game mechanics. For example, a civ-level manager living in a fortress will not perform management duties there and doesn't unlock the management-screen, even with an assigned office.
This behavior applies to the following [SITE]-level responsibilities:
* [RESPONSIBILITY:ACCOUNTING]
* [RESPONSIBILITY:BUILD_MORALE]
* [RESPONSIBILITY:HEALTH_MANAGEMENT]
* [RESPONSIBILITY:LAW_ENFORCEMENT]
* [RESPONSIBILITY:MANAGE_PRODUCTION]
* [RESPONSIBILITY:MEET_WORKERS]
* [RESPONSIBILITY:TRADE] (functions differently)
Other responsibilities may be affected as well, but have not yet been fully tested.

===World-gen effects of the [RESPONSIBILITY] of available positions ===
It is possible to cause civs and individual sites to change their behavior substantially when they reach a certain size, by controlling nobles.
* If a site can only appoint a position with [MILITARY_GOALS] after reaching a particular size, that site will not send armies on missions until the required size is reached.
* A civ-level [LAW_MAKING] position is required for the civilization to have any kind of cohesion. Without it, sites will be constantly embroiled in territorial disputes and civil wars will be commonplace.
* [MILITARY_STRATEGY] positions go out and tame wild animals. This makes your civ gain those animals as domesticated and also brings them in sieges.
* The [[Personality_facet|Personality]] of the position's holder determines how they lead the civ.

===[DELIVERS_MESSAGES]===
The only [AS_NEEDED]-position that is created in worldgen based on responsibility is that of the site-level responsibility [DELIVERS_MESSAGES].

===Outpost Liaisons and Diplomats===
Civ-positions with the responsibility [ESTABLISH_COLONY_TRADE_AGREEMENTS] ([[Outpost_Liaison|Outpost Liaison]]s) will meet with the site-noble who has responsibility for [RECEIVE_DIPLOMATS] and the highest rank of precedence (i.e. the lowest precedence value). Usually this is the [[Expedition_leader|Expedition leader]].

Once a [LAND_HOLDER] is assigned to the site, civ-positions with the responsibility [MAKE_TOPIC_AGREEMENTS] ([[Diplomat]]s) will meet with '''civ'''-level nobles present at the site who have the [RECEIVE_DIPLOMATS] responsibility. If multiple eligible nobles are available, one is selected at random. If no eligible noble is present, the diplomat leaves angrily. If the landholder is no longer present at the site, diplomats will not arrive at all.

It appears that Outpost Liaisons and Diplomats are chosen for a diplomatic mission based on availability. When multiple candidates exist, the position defined last in the raws is most often selected.

===[TRADE]===
Civ-level nobles with [TRADE] will arrive with the caravan, just as the Outpost Liaison. Their behavior is no longer active in the vanilla game, but the mechanics are still present. See [[40d:Guild_representative|Guild representative]] for more details. This civ-noble will only meet with the SITE noble with [TRADE], usually the [[Broker]].

If two civ-nobles exist with both [TRADE] and [ESTABLISH_COLONY_TRADE_AGREEMENTS], they both arrive at the same time. Even if both tokens are assigned to a single position, if more than one instance of that position exists, two of them will arrive. However in that case, somehow the elevation of the site and appointment of landholder isn't offered.

If the SITE-noble they intend to meet has both [TRADE] and [RECEIVE_DIPLOMATS], only one meeting will proceed and the other is cancelled. However, when two SITE-nobles are available, each with either [TRADE] or [RECEIVE_DIPLOMATS], both meetings will proceed and both civ-nobles will attempt to negotiate a trade agreement. It is not known what happens if these agreements are accepted or refused.

In the trade depot, the last defined position with the [TRADE] responsibility is shown as broker. However when requesting a trader, the first defined position with [TRADE] will actually go there to do the trade.

==[NUMBER]==
A position might be defined with a number. In that case, as many as defined can be available. If the positions become available, in world-gen and when embarking, they are all filled-in completely.

If the ruling position (with PRECEDENCE of 1) has a NUMBER higher than 1, a random unit of the ones holding these positions is shown as ruler in the embark screen.

A [NUMBER] of 0 (zero) has the same effect as 1.

===Automatic spreading of assumed, non-singular positions===
If there are civ positions that have a NUMBER higher then '1' and which are assumed (not APPOINTED_BY or ELECTED) but are '''not DUTY_BOUND''', these are automatically spread among the civilisation, based on population. If there are a number of '''20''' available slots of that position, they spread among a civilization with a combined population of, for example, 1000 of which your fortress has 100 (10%), '''2''' of your fortress' citizens will assume that position.
This may probably also work with elected and appointed positions, but that may be depending on the death of the current holders and this needs more testing. Assumption works within a day, anyway.

===[AS_NEEDED]===
These positions can be created automatically by the game in world-gen. This, however, only works with:
* [LAND_HOLDER]'s
* squad commanders (needs more testing)
* Messengers at sites

For all other types of positions, they're not created in world-gen, even if they are defined with RESPONSIBILITY's. For example, even in war, the game wouldn't create a MILITARY_GOALS position, if they have AS_NEEDED as number.

However, in fortress mode / player mode, these positions can be created by the player at will.

Positions with AS_NEEDED need to be created first, before any symbols are assignable as 'symbols' (objects) for the position holder to carry or wear.

Positions with AS_NEEDED cannot be created and then ELECTED in fortress mode. It only works with APPOINTED_BY.

==[REPLACED_BY] and [REQUIRES_POPULATION]==

The token REPLACED_BY:position means that once the replacing position reaches its required population-number, the 'to-be-replaced' position will disappear. This is defined in REQUIRES_POPULATION. These tags are closely related to each other and seem to only have a meaningful function if combined. Nobles with REQUIRES_POPULATION require the population to have a specific size.

This works on the civ-level as well as on site-level, but those systems are in this mechanic strictly separated. Site-level positions cannot be replaced by civ-level positions and visa versa. This makes sense, because they both depend on their own population-count. When using REQUIRES_POPULATION on civ-level, it counts the total population of the civilisation.

See also: [[Advanced_entity_position_mechanics#Evaluation_of_Positions|Evaluation of positions]]

===Effect of replacement (and on [LAND_HOLDER]s)===

Replacement is immediate and complete - the current holding unit loses the position, even before SUCCESSION_BY_POSITION rules are applied. A position with a number of 1 will replace all the slots of a position with a higher number of slots.

Even if the next position is available but not visible, replacement still takes place. If a position is replaced, it is completely gone - it cannot be appointed, succeeded, elected or assumed any longer.
The unit immediately loses its position.

In legends, replacement is mentioned as: "(unit name) ceased to be (position name)" The replacement of an AS_NEEDED position empties the position's slot forever. In fortress mode, it may seem as if you can create new slots and appoint new units in the nobles screen, but this is reversed as soon as you close the window.

The landholder chain uses [REPLACED_BY] differently. It does not clear the position completely, but uses it for succession to the next level's position. [REPLACE_BY] is required to let that system work properly. This also means that the way in which landholders succeed (replace + as_needed) does not work in any other way.

Replacement between LAND_HOLDERS and other site- or civ positions does not work in any way. Only the vanilla replacement sequence between levels of LAND_HOLDERs does work. If the token is omitted for landholders, the landholder chain is broken, so replacement is required for the landholder system to work.

[REQUIRES_POPULATION] also does not work for [LAND_HOLDER], when you set [NUMBER] to 1. The position is not created when the required population is reached.

===What doesn't work===

'''Attention: If a position cannot be appointed, for example because of 'mutual appointment', it still exists according to replacement mechanics and will replace other positions if so defined. If a certain position(a) will be replaced by the baron's assistant, which can only be appointed by the [LAND_HOLDER] baron, than that position(s) still will be replaced from the start of the game, even if no baron or their assistant is ever present.'''

A position that is replaced by a somehow non-fillable position is still replaced. This counts for mutual-appointing positions, replacement by not-yet-assigned landholders, replacement by AS_NEEDED positions, or replacement by not-yet-appointed positions.

Replacement does not work if the replaced position is a [LAND_HOLDER], even with civ-positions. In that case, the LAND_HOLDER's position is not replaced. It does not matter if AS_NEEDED is used, or a fixed number, and it also does not matter what type of position the replacer is. So this only works (correctly) with positions that become available by REQUIRES_POPULATION.

==[CONQUERED_SITE]==

This tag determines which position is used to assign a [[Forced administrator]].

In legends mode, this is visible as an event describing the reconquest of the site: a new group is formed and the forced administrator is installed as its ruler.

All positions defined with this tag are assigned during this process, meaning multiple positions can be appointed at once.

The holder of a position marked with [CONQUERED_SITE] cannot appoint any other [SITE] positions.

Combining [CONQUERED_SITE] with [SITE] causes the position to function both as a forced administrator and as a normal site position available in fortress mode. However, this provides no meaningful additional mechanics and is effectively inferior to using [SITE] alone:
* [APPOINTED_BY] lines are completely ignored, meaning that the roles are automatically assumed.
* [SUCCESSION] is likewise ignored.
* the [CONQUERED_SITE]-position cannot appoint other [CONQUERED_SITE], [SITE] or combined positions.

There have been remarks that reclaiming a fortress is unplayable because of the lack of regular nobles. Unfortunately, it seems that it can't be fixed by modding.

=Availability and visibility=
==Availability of (new) positions==
Warning: Do not mistake "availability" for "visibility"!

Of all the possible positions existing in your site's entity, there may only be some available.
* Positions with [REQUIRES_POPULATION] require the population to have a specific size.
* Positions with [REQUIRES_MARKET] will only appear in "large" sites (which may have different rules for different site types). This tag has no effect in fort mode.
* Positions that are appointed by positions that have an AS_NEEDED number. The appointable positions only become available after an appointer position-slot is created. This works also on civ-level. If a position is appointed by a Land-holder, it only becomes available, when that level of landholder is created.

Only the replaced positions are culled and are no longer available.
A position that requires a certain population will become available, even if it doesn't have [APPOINTED_BY] or [ELECTED]. In that case, see 'automatic assignment' and 'assumption'

In fortress mode, in some cases 'succession' is evaluated immediately after a position becomes available. See: Succession.
==Visibility of positions==
A position might be available, but can still be invisible for the player in the [[nobles screen]]. The positions with their respective holders are visible for players:
* All site-positions that are already filled-in (even if they could not be re-filled-in considering current conditions)
* Site positions that are appointable by a filled-in site position
* Site positions that are appointable by a filled-in civ position, when that civ positions holder becomes a citizen of your fortress.
* Civ positions of units that are also a citizen of your fortress.
If a position becomes available, for example because a certain pop number has been reached, or if it is available from the start(like expedition leader), as long as it cannot be appointed, it still is INVISIBLE for the player.

It might strike someone as odd if a position becomes filled automatically in fortress mode when that position is not even visible. This might be the case if the current holder of a non-appointable position dies or succeeds another position. Regardless of player visibility, these positions will be automatically filled in if the necessary requisitions are met. It might happen with the expedition leader.

A situation with a non-visible but available position, is for example when a position is solely appointed by the expedition leader, when the expedition leader's position is left vacant. It can no longer be appointed by the player and is invisible. Then, it gets automatically assumed, proving that the position still was available.

A position that is both [APPOINTED_BY] and [ELECTED] is visible, but players cannot interact with it.

={{text anchor|Evaluation of Positions}}=
The game does not continuously check whether positions should become available, elected or be [REPLACE_BY]. This is well-known behavior—for example with the [[mayor]], who does not appear automatically when the required population ([REQUIRES_POPULATION]) is reached. Instead, positions must somehow be evaluated. This applies in several other situations as well

'''Cases that require a trigger:'''
* Election of a newly created position
* Election after the current holder dies
* Automatic assumption of a newly created position (this may take up to a day)
* New citizens (such as migrants) considering available positions
* Premature succession of a newly created position

'''Cases that do not wait for a trigger:'''
* Succession following the death of the previous holder
* Automatic assumption of existing positions that have become vacant

'''Triggers that cause the game to reevaluate noble positions:'''
* Succession of a [SITE]-position due to the death of the current holder
* [[Advanced_entity_position_mechanics#Election_Day|Election Day]]
* Automatic assumption of a [SITE]-position that becomes vacant
* (Re)assigning any site position manually
* Settlement elevation on the LAND_HOLDER track (e.g. gaining a [[Baron]] or [[Count]])

=Gaining a position=
There are several ways a unit can gain a position:
* Appointment: A unit is appointed by another unit or by the player.
* Election: A unit is elected by and among the members of the entity
* Assumption: A position is neither elected or appointed: a random unit just simply 'takes' the position
* Succession: a unit is the valid successor of this position(A), either by its current position(B) or because they are that position(A)-holder's heir.

Available positions will automatically be assigned to a random civ member when a new site/civ is created.

==Who can take a position==

* If so defined, a unit needs to be the right caste and/or class - it does not seem to work with creature types.
* The unit needs to be an adult member of the site or its parent civ's government; that is also CAN_LEARN or INTELLIGENT (SLOW_LEARNER cannot take positions) or otherwise is able to think.

==Appointment==

Positions that have an [APPOINTED_BY:position] token require that position to exist, to be available and appointed. Any position that is APPOINTED_BY can be appointed if the appointer's position is filled in.
For site-positions to be appointed, it is required that the appointer is present at that location.

If the appointing unit is temporarily not present, or if that position is not filled, positions depending on it cannot be appointed. This is the case with [[militia captains]], when the [[militia commander]] is on a [[mission]].

A site position cannot appoint a civ position ''or'' LAND_HOLDER in any way whatsoever.

Civ-level positions can appoint other civ-level positions and site-level positions can appoint other site-level positions.

Contrary to what has been said elsewhere, civ-level nobles also can appoint site-level nobles. They need to be at the site to do so. Landholders can appoint both site-level and civ-level nobles. These systems are therefore not as separate as was assumed.

'''Mutual appointment''' cannot take place. If these are the only requisites of the position, then the positions will never appear or get filled. These unfillable positions can be put to good use, for example, to replace a position that is no longer needed without creating a new one.

'''Self appointment''' doesn't normally work. If you have a position that is only appointed by itself, it is never appointed and also cannot be assumed. However, if the position has a number higher than 1, and is filled by multiple units (for example by another position that is now empty), than those units can re-assign or appoint each other from that their shared position.

If an APPOINTED_BY token refers to a non-existing position's code, the effects are as if the appointment token doesn't exist at all.

===Automatic appointment in world-gen and on the civ level===

Outside of fortress mode, the game will always attempt to appoint nobles whenever possible, as long as these positions are '''available''', even if they are invisible to the player.
It shows this message in legends: "(unit name) has been appointed to the position of (position name)"

In world-gen, all positions become available and are automatically appointed, taking population- and appointment-requirements into consideration.

Positions that are REPLACED_BY are culled and won't be filled.

If a citizen of your fortress holds a civ-level position that can appoint another civ-level position, the appointment will happen automatically and without player intervention. It may happen that another citizen of your fortress is appointed by that unit, creating civ-level position holders in your fortress, but it is unknown what is required to force this effect.

===Manual appointments by players in fortress mode===
In fortress mode, the positions that need to be appointed stay empty on embark. and it is the player's job to appoint those. A player can appoint a unit to any available position, according to the hereabove mentioned conditions. The player takes the role of the automatic appointment-system, but has no direct control over elections, successions and replacement. There are some differences in what is possible at world-gen sites and at player-controlled sites.

* A position that is appointed by a unit present as a fortress citizen, can be appointed, re-appointed or left vacant. This means also by civ-level nobles living as a citizen in your fortress; not when they are only visiting, like the diplomat.
* A position whose appointing positions are all either vacant or [REPLACED_BY] can no longer be appointed. If the position is already filled, it cannot be reappointed or vacated; the current holder simply remains in office.
* A position that is APPOINTED_BY a unit present as the land_holder of your site, can be appointed, reassigned or left vacant.
* A position that has SUCCESSION BY_HEIR or BY_POSITION can 'initially' be appointed and also re-appointed or left vacant, but as soon as the [[nobles]] screen closes, ''it can no longer be replaced or left vacant''. From then on, the succession-rules determine who gains that position when the current holder loses the position. This works even if the SUCCESSION:BY_POSITION-position is vacant or replaced.
* A position that is ELECTED nor APPOINTED_BY, can always be (re-)appointed by the player. This is the case with the [[Expedition leader]]. If it is left vacant however, it cannot be appointed, but will be assumed shortly after.
* A position that is both ELECTED and APPOINTED_BY, cannot be appointed by the player. Contrary to world-gen sites, its slot is visible, but it doesn't show the +-sign. This is either by AS_NEEDED or by a fixed number. Even if the position somehow gets filled (re)assignment is never possible
* A player can appoint a number of units to a position, as much as the NUMBER token dictates. If it is AS_NEEDED, the player may create as many slots as they like, also contrary to world-gen sites.
* A civ-position can never be appointed, even if the appointing civ noble is a citizen of your fortress. A civ position also never can be re-assigned or left vacant, would that position be defined as appointed by a site-position.

==Election==
Read more in [[Elections]]. The message that is shown is: "(creature name) has been elected to the position of (position name)"

In worldgen, there is no functional difference between ELECTED and non-appointment, except that elected nobles tend to have high social skills and/or skills related to the position, while non-elected ones are assigned randomly. See: [[Elections]]

A succession goes before an election.

A position that is both ELECTED and APPOINTED_BY never gets elected. Even if the appointees' position somehow gets filled, (re)-elections won't happen. So, it doesn't seem possible to have an elected position become available when a certain other position becomes filled.

An ELECTED civ-(or LAND_HOLDER) position at your site will never be (re)-elected in fortress mode. So real (re-)election only works with SITE-positions.

=== {{text anchor|Election Day}} ===
Election Day takes place on the 17th of Summer. On this day, a full reevaluation is performed, including all currently elected positions, which are subject to re-election. Contrary to the information on [[Elections]], nothing occurs at the start of a season.

Positions that are both [APPOINTED_BY] and [ELECTED] will not be re-elected on Election Day when assigned through [SUCCESSION].

=== Election Eligiblity ===
Any citizen may stand for election. Eligibility cannot be restricted using [ACCEPTED_CREATURE], [REJECTED_CREATURE], [ACCEPTED_CLASS], [REJECTED_CLASS], or [GENDER]. Units currently having a [SUCCESSION]-position even may be elected for a position with a [SQUAD]-token, which is otherwise impossible to assign or even succeed.

=== Skills ===
In elections, skills are taken into account for the tokens of the position which is elected.
{| class="wikitable"
|+ Relevant skills per position token
|-
! Position Token !! Relevant skills
|-
| Responsibility [[Position_token#DELIVER_MESSAGES|[DELIVER_MESSAGES]]] || [[Ambusher]], [[Observer]] and [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#ACCOUNTING|[ACCOUNTING]]] || [[Record_keeper|Record keeper]]
|-
| Responsibility [[Position_token#ESPIONAGE|[ESPIONAGE]]] || [[Schemer]]
|-
| Responsibility [[Position_token#HEALTH_MANAGEMENT|[HEALTH_MANAGEMENT]]] || [[Diagnostician|Diagnostician]]
|-
| Responsibility [[Position_token#MAKE_INTRODUCTIONS|[MAKE_INTRODUCTIONS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#MAKE_PEACE_AGREEMENTS|[MAKE_PEACE_AGREEMENTS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#MAKE_TOPIC_AGREEMENTS|[MAKE_TOPIC_AGREEMENTS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#MANAGE_PRODUCTION|[MANAGE_PRODUCTION]]] || [[Organizer]]
|-
| Responsibility [[Position_token#MEET_WORKERS|[MEET_WORKERS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#RECEIVE_DIPLOMATS|[RECEIVE_DIPLOMATS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#RELIGION|[RELIGION]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#TAME_EXOTICS|[TAME_EXOTICS]]] || [[Animal_trainer|Animal trainer]]
|-
| Responsibility [[Position_token#TRADE|[TRADE]]] || [[Social_skill|Social skills]] and [[Appraiser|Appraiser]]
|-
| [[Position_token#SQUAD|[SQUAD]]]-token || [[Tactician]] and [[Leader]]
|}

==Assumption==

A position that is not APPOINTED_BY nor ELECTED, or is appointed by positions that are not available in your site or civ, will be assumable by a random dwarf. If it has responsibilities that require certain skills, then these are taken into consideration on embark, but not when the position is assumed during the actual game.

Normally, one to three units will take the into consideration to assume a position. Most of the time when there are multiple open positions, only a single unit will assume all of them. However, a position that has REJECTED_CREATURE, REJECTED_CLASS, ALLOWED_CREATURE or ALLOWED_CLASS will be filled with all different units, even if the creature or class mentioned is irrelevant. It seems that this forces the game to loop over all the available units.

The message that is shown in Legends mode is: "(unit name) has assumed the position of (position name)". This may also take place in fortress mode, which then shows this message to the player.

If an assumable position becomes empty, it will be assumed within a day. This is the case when you leave the position of expedition-leader vacant. It also happens with entities.

Assumable positions that become empty will not be assumed if that position has a valid [SUCCESSION] -successor. In that case, the successor inherits the position.

Even positions that are somehow invisible because they cannot be directly APPOINTED_BY players, can be assumed.

When you embark, the assumable positions are automatically assigned to a random unit. If there are multiple of these positions at embark, they all are assigned to the same unit. If there are enough positions available, multiple units may gain a position, but often no more than three different ones.

If a dwarf in fortress mode assumes a position, that already has another position, it will leave the current position empty. When that position also is assumed, then this will continue until all positions have a dwarf appointed to them, with no other position.

A unit that already has a position with a [SUCCESSION] token won't take assumable positions into consideration that have a [SQUAD] token. This can be used by the modder to prevent unwanted loss of current positions.

A position that has an appointer which got replaced because of REPLACED_BY, will not become assumable. Also, positions that have an AS_NEEDED appointer that is not yet filled (or ever), will also not be assumed.

==Succession==

If a position-holder dies or advances to a new position via succession, the position will be granted to another unit based on the [SUCCESSION] tag. If they have an heir or the succeeding position exists, that unit will be assigned. If not, a new one will be appointed according to the usual rules. The message that is shown is: "(creature name) being the rightful heir, has inherited the position of (position name)"

The succeeding creature will also lose its previous position. When succession is defined using BY_POSITION, the unit naturally loses the referenced position. However, it also loses any other positions it may hold. If a unit could simultaneously inherit multiple positions, the last-defined succession overrides the earlier one, clearing the previously acquired position

Succession works both at site-level and at civ-level, both in world-gen and in fortress-mode. Succession by position on the civ-level is also visible and functional in fortress-mode. If both civ-level nobles are a citizen of your fortress, succession is applied visually. Vanilla example: The [[druid]] is succeeded by the [[acolyte]]. This means that as soon as the druid dies, the acolyte takes over.

When a position that is succeeded by position becomes available, immediately it is checked if a position-successor is available and the position is filled with that unit. Even if this is an [ELECTED] position, succession goes first. When elections eventually do happen, succession plays no role.

It is possible to assign multiple levels of [SUCCESSION:BY_POSITION] in different positions, creating a line of positions where the death of one causes all those "below" them to advance.

A position can have multiple tokens with position-succession. It looks to be random which one is used. It is not always:
* The first or last defined token
* The first or last appointed unit
* the oldest or youngest
* one with a higher or lower precedence
* a unit with relevant skills

When a position is defined with a Succession-type, that unit cannot have another position that has a Squad-type. If the succession-position itself has a squad, than it can be assigned another position with a squad, but then it will loose the previous succesion position. See further details by "Squad"

Assumed positions can also be succeeded by position, if the current holder dies.

If the successor is an AS_NEEDED position, the used unit will leave a vacant position-slot on its removal by succession. This empty slot remains a real slot, which will only be cleaned up if you (un)appoint a unit to this position-series. It isn't cleaned up after regular position validation.

A civ-level position of a unit living at your site might be inherited by a unit holding that does not currently live at your site. This, unfortunately, moves that position to a unit off site. This may also happen with the landholder of your site, for example when it is succeeded by another civ-level position. This currently poses an unsolved challenge.

===Eligibility for succession===
Succession is restricted by the tokens [ACCEPTED_CREATURE], [REJECTED_CREATURE], [ACCEPTED_CLASS], [REJECTED_CLASS] and [GENDER].

===Site and civ combined succession===

Succession can work when combining site positions with civ-level positions or land_holders, but only in world-gen mode. In fortress mode, it only works with combining the same level of nobles, with Landholders regarded as civ-level. So, in fortress mode, a site's position cannot succeed a landholder's position and it cannot succeed another type of civ-level position, and vice versa.

This won't work even if the positions:
* are AS_NEEDED or having a fixed number.
* Are LAND_HOLDERs.

===Succession [BY_HEIR]===

When a heir is needed for succession, all children and then other relatives are validated. They cannot take the position if their status does not allow it, for example if they have become a member of another civilisation. See: "Who can take a position". If the unit has no valid heir on that location, the position may go to a unit living on another site. This may cause the title of Landholder of some land to be inherited by a unit living somewhere else. That might be a problem, because then you lose your landholders.

===Premature Succession===

There are cases where [SUCCESSION:BY_POSITION] is applied prematurely: at the moment a position is first created and becomes appointable or assumable, rather than after a current holder leaves. In this situation, the succession mechanism assigns a holder immediately, without any player interaction.

When a position becomes available for the first time, the game checks whether a valid successor-by-position exists. If so, that unit is assigned instantly. It can affect positions that would normally be appointed or elected by the player, causing succession to trigger before the player has any opportunity to intervene.

This behavior occurs only in Fortress mode, but can be applied both on [SITE]-positions as well in civ-positions. That last one however is a bit harder to control. Example: [[Advanced entity position mechanics#The Archduke|The Archduke]]

This premature succession only occurs the first time a position becomes available (i.e. when it is created and becomes appointable or assumable). Even if the position remains vacant and the conditions for succession improve later, premature succession will not trigger again. From that point onward, only normal succession rules apply.

Using premature succession, a position that has [ELECTED], [APPOINTED_BY], or both, can be filled directly.
Notably, positions that combine [ELECTED] and [APPOINTED_BY] are normally impossible to fill through regular mechanics. Premature succession bypasses both election and appointment entirely, making this combination uniquely reachable through this mechanism.

No initial election takes place, and no subsequent elections will ever occur for that position. Succession always takes precedence over election, both in premature succession and in normal succession cases.

This behavior applies only in Fortress mode, not during world generation. World-gen uses simplified and more efficient mechanics, and this interaction does not occur there. Premature succession can affect both site-level and civilization-level positions.

====Multiple succession chains====

Multiple succession chains may be defined and are resolved in the order they appear in the raws.

If a position has both:
* a direct succession chain (A → C), and
* a multi-step chain (A → B → C),

and intermediate positions are vacant, resolution proceeds according to raw order. A common outcome is:
# The direct succession (A → C) is applied first, assigning A to C.
# The remaining chain then advances (A → B).
# If C still has empty slots, the final step (B → C) may occur.

If position B is already filled, behavior depends entirely on raw definition order:
* nothing may happen, or
* B may move to C first, followed by A moving to B.
====Working triggers====
Premature succession is triggered when a succeedable position is created under the following conditions:
* The succeedable position is created because its [REQUIRES_POPULATION] threshold is reached. This applies even if the position is not [APPOINTED_BY]. Premature succession takes priority over automatic assumption (e.g. the mayor declaring themselves within a day).
** The position must either be assumable or appointed by an existing position. When said appointer-position also just has been created, the premature succession of the succeedable position happenes, even when the appointer-position is empty.
* The succeedable position can be [APPOINTED_BY] another position of the same level (site or civ) that has just been created because its [REQUIRES_POPULATION] was reached.
* The succeedable position can be appointed by another [SITE] [AS_NEEDED] position that has just been created and filled.
* The succeedable (site or civ) position is [APPOINTED_BY] the [LAND_HOLDER] position, which has just been created due to site elevation. This typically resolves when the diplomat leaves the map, at which point the landholder position becomes active.
* If all other requirements are met, premature succession can occur immediately after unpausing following embark, for positions with [REQUIRES_POPULATION:7].

====Non-working triggers====
Premature succession does '''not''' occur in the following cases:
* An [AS_NEEDED] succeedable position slot is manually created by the player while its succeeding position is already filled. [AS_NEEDED] positions must always be appointed after creation.
* The succeeding position is filled after the succeedable position becomes available. The moment of creation is the decisive trigger; filling the source position later is too late.
* The succeedable position can be appointed by another site or civ position with a fixed number of slots that has just been appointed. In this case, the succeedable position is just available for appointment itself, nothing more
* Any situation occurring during world generation.
* The succeeding position is [REPLACED_BY] the succeedable position. In this case, replacement removes the unit from the source position first, leaving no holder available for the succession mechanism to use.rst, leaving no holder available for the succession mechanism to use.
* The position is [APPOINTED_BY] a civ-level position, that just became a citizen of your fortress. It must be noted that those civ-level positions were active all that time and the succeedable position could be appointed even before. The monarchs arrival does not trigger premature succession

=Losing a position=

A unit can lose a position when:
* It dies
* It succeeds another position, even if it has nothing to do with the previous position.
* It is assigned to another SQUAD-holding position
* It is convicted of a crime.
* Another unit is ELECTED for the position
* Its position becomes replaced
* Another unit is appointed by the player, or the position is left vacant.
* It has assumed another position, as this always leaves the previous position vacant.

=Embarkment=
Two types of positions are automatically filled by embark.
* Positions without [APPOINTED_BY] or [ELECTED] (assumable). All these positions, even with a NUMBER higher than 1, are all filled with one to three dwarves. Contrary to assumption, this doesn't take into account any limitations. REJECTED_CLASS, ALLOWED_CLASS, REJECTED_CREATURE, ALLOWED_CREATURE and GENDER are applied, but without the normal spread you may expect with assumptions. Also it doesn't look at [SUCCESSION] and [SQUAD] limitations.
* Positions that are elected are filled-in by the normal election rules.

Positions that have a defined appointer are never initially filled at embark.

All positions that don't have [REQUIRES_POPULATION] or with a [REQUIRES_POPULATION] of 7 or lower, will be available at embark.

=Land Holders=

A Landholder is a '''special civ-level noble''' who gets a certain piece of land to hold, when that land is elevated to a certain level, determined by the tag [LAND_HOLDER] and by the landholder triggers in the game's settings. In vanilla, these are the baron, the count and the duke.

A unit gaining the landholder position does not migrate to that specific named land. In world-gen, they stay just where they are, probably at the capital. In fortress mode, you can suggest a citizen for the role. So for the time being that works.

Succession is then a real issue. If you use BY_HEIR, its solved when that landholder has children living at your site. But when its not the case, the title just goes to anyone randomly. Succession BY_POSITION works, but only in the civ-chain, and there's no way to guarantee a civ-holder is at your site at that time. Even with 'automatic spread' positions, it goes to one of them randomly.

==Functioning of the regular landholder chain==

The distinct difference between a landholder and a regular civ-level noble, is that a landholder may gain the position of landholder "of (sitename)" They are then seen as ruler of a particular site.

For a land_holder position to function as such, it has a few requirements:
* NUMBER:AS_NEEDED
* The first landholder-number of 1 is defined.
* No SITE (so civ) tag in that position.
*REPLACED_BY the next level landholder
If a landholder is defined with differentiating properties, it will function like a regular noble. A higher-up landholder that lacks the required tokens or connections will then not be used in elevation.

If a fortress meets the trigger for a new LAND_HOLDER tier when a caravan leaves, then the next time the outpost liaison or equivalent arrives, they will offer to make you an official colony, which will allow you to select all positions for that LAND_HOLDER level. Each time they appear, the outpost liaison will only promote your fortress one tier up the LAND_HOLDER track.

The landholder's LAND_NAME is not required for the functioning of this system. If omitted, messages will be shown with a more generic text.

==Appointment==

This mechanism differs from the regular methods of position management. It ignores all regular appointment- and election rules, so it more or less functions like automatic assignment. A landholder is, in vanilla, appointed by the monarch. Changing this doesn't seem to do anything. If they are appointed by a site-position, a not-yet-existing civ-position, or not appointed at all: the system keeps working as usual.

A landholder can appoint civ-positions and site positions. This works as expected: the positions only are appointed then when that landholder becomes available on civ-level or when he arrives at that site for site-level positions.

If your rank of landholder is the first of its rank in the realm, and is the sole appointer of some civ-position, then immediately as it gains the title, it will appoint the empty civ-slots. This may happen on your site, but the frequency and certainty is hard to determine.

==Succession==

Succession rules are applied to some extent:
* In world-gen it works according to succession rules, and site-positions can be used here. This means that a site position or a civ-position can inherit a landholder position, and vice versa.
* In fortress mode, once a landholder has been appointed, it then can inherit civ-level positions, and vice versa. This means that your baron can become king.
* Succession rules do not apply within the [LAND_HOLDER] chain; a count will not inherit a baron's land. This is because succession does not work well with the AS_NEEDED token.
* Premature succession works in fortress mode with landholders. If a unit gets a landholder's position and that landholder is the appointer of an as yet empty position, which is defined as succeeding from a third one, then the succession is immediately applied. The landholder themselves can even be the successor of a newly created position.
* A landholder's position is, in fortress mode, not successionable by a site-position or vice versa

===Impossibilities for succession by a site-position===
It would be very beneficial if the landholder can be succeeded by a [SITE]-position. So far, the following tests have not lead to positive results:
* making landholder and site-position both non-[DUTY_BOUND]
* make the site-position be [APPOINTED_BY] the landholder and/or the monarch
* give landholder and site-position [REJECTED_CREATURE]
* Let the monarch live at your site when succession could happen.
* Let the site-position be [REPLACED_BY] the landholder.

If the vanilla [SUCCESSION:BY_HEIR]-tag is omitted, a seemingly random unit somewhere in the realm is assigned this position.

==Nomination==

The player is able to nominate a unit to become the LAND_HOLDER, but this only works with units of [LAND_HOLDER] level 1. The player can select all units, only limited by the PRECEDENCE of the current units' positions.

A unit that has a position with a PRECEDENCE lower or equal to that of the landholder's position, cannot be selected. This means that a baron (or count) from another site or the monarch cannot be selected, because their precedence is lower or equal.

The GENDER token does not work here: also units with the wrong gender (sorry) can be selected.

==Levels==
In mods, up to 10 levels of LAND_HOLDER may be defined.

If a landholder is replaced by a wrong landholder number (1 replaced by 3), then the number 3 is still correctly attached to the settlement.

If the current landholder has the highest available landholder number, then the next elevation will not happen - the diplomat will not elevate your fortress to a higher position, even if that position might be REPLACED_BY a lower landholder.

These chains do work:
* 1 -> 2a - > 2b -> 3
* 1 -> 3 -> 2 -> 4

These chains do not work:
* 2 -> 3 (need to start at 1)
* 1 -> 4 -> 2 -> 3 (stops after 4 as the highest)
* 1a -> 2, 1b -> 2 (only 1a and 2 work, 1b is not used)

==Moving landholders==

It may happen that a land-holder no longer lives at the site which they are the landholder of, specifically when the current landholder dies, leaving the title to an heir living somewhere else.

To prevent this from happening, you can make their succession from heir and make sure that their kids live at your site. Or, you can make their position succeeded by another civ position, and make it so that this civ position is somehow available on your site. But if multiple of these positions exist, it cannot be guaranteed that a citizen of your fortress will inherit the title.

In world gen, a landholder lacking the DUTY_BOUND-token will also move to the site they like, according to legends mode.

==Replacement by a generic civ-position==

If a landholder is replaced by an AS_NEEDED non-landholder civ-position, then this will work: the current landholder loses that title upon settlement-elevation and gains that civ-title. However, the civ-title lacks the landholder-property of being attached to the land. It will not show the name of the settlement alongside the position's name. So no "minister of Shovelmounts"

If a landholder is replaced by a general AS_NEEDED civ-position, that itself is also replaced by a generic AS_NEEDED civ-position, then firstly the elevation is executed and also the unit gains that new position. However, he immediately loses it, because an AS_NEEDED position that is replaced by another position can be filled initially, but units wont be able to hold that title.

==Landholder with fixed number==

A landholder's position that has a fixed number will be created and filled directly when the civilisation is born, so this position slot is then not available for the regular landholder-mechanic and will also not be used. That landholder will thus not be attached to a settlement.

It doesn't matter if the landholder's position is connected to the regular landholder's-chain with the REPLACE_BY token.

==Responsibilities==

When given a certain [RESPONSIBILITY], a landholder may function as a regular civ-level noble. If the position has [TRADE] or [OUTPOST_NEGOTIATING] responsibilities, then the landholder functions both as a diplomat and as an actual land holder. A landholder with the [MILITARY_STRATEGY] responsibility will travel around taming creatures in world-gen, according to legends mode.

Besides that, the responsibilities work the same as with any other on-site living position-holder, civ or otherwise.

=Military=
==Squad management==
In the vanilla game, the Squad interface only becomes available after a militia commander has been appointed. Until then, the window displays:{{DFtext|You must appoint somebody first to create a squad.}}

What’s surprising is how this is determined internally. In the entity raw definition, '''only the last two positions that include a [SQUAD] token are checked''' to decide whether the interface is accessible at all. As a result, if your hierarchy defines commanders A through E, appointing '''Commander D or E''' unlocks squad formation, while appointing A–C does nothing.

In other words, squad availability is not tied to ''having a militia commander'', but to ''which specific positions happen to be last in the raw list''—a notably hacky implementation.

These 'last two' are always the last two '''available positions.''' So if they get [REPLACED_BY] or become available because of [REQUIRES_POPULATION], the game adapts to those.

==Squad assignment==

Squads can be assigned, even if the leader position has no holder.

A specific unit can only have one position associated with a squad. If it gains another 'squad holding position', it is unassigned from the first one. This does not work with a 0-squad, so only 1+squads are taken into consideration. This technique can possibly be used to distribute all positions equally among all citizens. It does however not work with election and assumption.

If a civ-level position is associated with a squad and it gets a site-level squad-holding position assigned, it loses the current civ-position.

Squads can get really messed up, if you make the position (or multiple) either elected or not-elected and not-appointed, then this can cause the game to assign multiple squads to the same unit. Automatic assignment and election does not take squads into account, but the nobles screen does. This can cause the positions to be cleared as the game figures out that they have more than one position, and immediately get elected or assumed again.

Positions that cannot have a squad-position:
* A site- or civ-position with a [SUCCESSION] token cannot be appointed a squad-holding-position. The other way around, however, does work. For example, if a site-position with a [SUCCESSION]-token is appointed to a unit that has already a position with [SQUAD]. But when that squad position is assigned to another unit, it cannot be assigned back.
* A position with [SUCCESSION] can also not be assigned as a '''member''' of a squad.
* A squad-holding position with a formed squad cannot be appointed to another squad holding position.

If a position has at least one squad member, it cannot be left vacant. First, the squad has to be disbanded, then the position may be cleared.

==0-squads==
A 0-Squad is defined in a position as [SQUAD:0:member:members]. It does not seem to do anything useful as of now.
* It cannot be used to activate the [[Squad|military interface]]
* It does not restrict the assignment of [SUCCESSION] positions.
* Assigning this position does not clear any previously held squad position.
* The [[Leader]] and [[Tactician]] skill are not marked as relevant skills and are not taken into account in elections.
* It cannot be formed as a squad.

=Further testing=
The following questions may need additional testing. Feel free to add or answer
* Everything regarding COMMANDING and army-structure
** [http://www.bay12forums.com/smf/index.php?topic=175437.msg8331668#msg8331668]
** [http://www.bay12forums.com/smf/index.php?topic=165213.msg8335682#msg8335682]
** [http://www.bay12forums.com/smf/index.php?topic=174584.msg8026854#msg8026854]
* Everything regarding CONQUERED_SITE, but it is presumably just like site. But what if you combine SITE or LAND_HOLDER with it?
* Stuff about the monarch, its arrival and its entourage.

=Oddities (Bugs)=
Almost everything on this page could be called an oddity. Because of their unexpected usability, some may also be referred to as “undocumented features.” Others, however, are simply odd and not particularly useful, yet I hesitate to call them “bugs.”
* If a certain threshold is reached that makes an elected position electable, and the triggering event that initiates this evaluation is an assumption, then the resulting assumption is also referred to in the messages as an election

=Examples=

===The Founder===
The founder is a single dwarf, appointed at embark. They will be the only one ever to have this position and are not replaceable. When they lose their position some way, the position will not be assumed by another dwarf.
{{gamedata|title=The Founder|
[POSITION:THE_FOUNDER]
[NAME:the founder:founders]
[NUMBER:1]
[SITE]
[ALLOWED_CREATURE:DWARF:ALL] - will only be filled at embark, but not assumable later.
[REJECTED_CREATURE:DWARF:ALL] - will only be filled at embark, but not assumable later.
[SUCCESSION:BY_POSITION:THE_FOUNDER] - not unassignable, also cannot be assigned to a [SQUAD] position.
[PRECEDENCE:200]
Non APPOINTED_BY
Non ELECTED
Optional: Add responsibilities to make the game select a unit with certain skills.
}}
===Marriage bar===
Dwarven matrons are held in great honour. Upon marriage, a female dwarf is no longer expected to perform menial labour. All dwarven males hold this position by default, granting their spouses exemption from menial work.

The position becomes available with the arrival of the first migrants; otherwise, on embark, it would be assumed by females. Its succession rule is non-functional, but this prevents the player from unassigning the position. A squad size of 1 and the succession rules together prevent a unit from assuming the position more than once.

With precedence set to NONE, the position name is hidden, while LAND_NAME remains visible on the nobles screen. All married females receive the suffix “, Mrs.” and are marked as Nobles.

The practical usefulness of this position is debatable, but it serves as a clear demonstration of several mechanics.
{{gamedata|title=Mrs. Urist|

[POSITION:MRS_URIST]
[NUMBER:300]
[SITE]
[ALLOWED_CREATURE:DWARF:MALE]
Not APPOINTED_BY
Not ELECTED
[LAND_NAME:Dwarven male]
[NAME:dwarven male:dwarven male]
[PRECEDENCE:NONE]
[SPOUSE_FEMALE:, Mrs.:spouses]
[MENIAL_WORK_EXEMPTION_SPOUSE]
[REQUIRES_POPULATION:8]
[SUCCESSION:BY_POSITION:MONARCH]
[SQUAD:1:member:members]
}}
===The Archduke===
The archduke is the leader of the civilization, but exists only from landholder 4-level. Until then, its position remains vacant. When a settlement is elevated to tier 4 (grand duke), the grand duke can appoint the ruler of the civilisation, the archduke. Because of 'Premature Succession', they themself inherit that position immediately, but only when in fortress mode. Its heir then becomes grand duke.
{{gamedata|title=The Archduke| no POSITION:MONARCH or other PRECEDENCE:1

[POSITION:THE_ARCHDUKE]
[NAME:archduke:archdukes]
[NAME_MALE:archduke:archdukes]
[NAME_FEMALE:archduchess:archduchesses]
[LAND_NAME:a archduchy]
[NUMBER:1]
[PRECEDENCE:1]
[SUCCESSION:BY_POSITION:GRAND_DUKE]
[APPOINTED_BY:GRAND_DUKE]
(add additional monarch-stuff, like spouse name, demands etc.)

[POSITION:GRAND_DUKE]
[NAME:grand duke:grand dukes]
[NAME_MALE:grand duke:grand dukes]
[NAME_FEMALE:grand duchess:grand duchesses]
[NUMBER:AS_NEEDED]
[LAND_HOLDER:4]
// Optional ...
[PRECEDENCE:19]
[LAND_NAME:a archduchy]
[RESPONSIBILITY:LAW_MAKING]
[RESPONSIBILITY:RECEIVE_DIPLOMATS]
[SUCCESSION:BY_HEIR]
[APPOINTED_BY:THE_ARCHDUKE]
(add additional landholder-stuff)

!!add to [POSITION:DUKE]
[REPLACED_BY:GRAND_DUKE]

}}
{{Category|Modding}}
{{Category|Entities}}
{{Category|Guides}}

Mayor

2026-03-09T09:10:38Z

Joostheger: Preparing a candidate is a perfectly legal way, and has nothing to do with rigging /* Ppreparing a candidate */

{{Quality|Superior}}
{{av}}
{{Noble
| noble= Mayor
| office= Decent Office
| quarters= Decent Quarters
| dining= Decent Dining Room
| chests=2
| cabinets=1
| racks=1
| stands=1
| mandates=1
| demands=2
| arrival=
* 50 population
* Elected
| function=
* Meet with foreign dignitaries
* Talk with unhappy citizens}}
The '''mayor''' is a [[noble]] whose job it is to speak with unhappy citizens, and (until a [[baron]] is appointed) entertain foreign [[diplomat]]s. They are automatically elected from the most social [[dwarf]], most likely the [[expedition leader]], once the population reaches 50. A new mayor may be elected from time to time as your dwarves' [[social skill]]s change.

== Mayoral nobility ==
[[File:Goblin_slaying_Mayor.png‎|thumb|left|A dwarven mayor conducting a "meeting" with some goblin "liaisons".]]A mayor or expedition leader is required to appoint other nobles. Should your leader suffer an [[unfortunate accident]], you will have to wait for a new leader to be elected before appointing nobles.

Mayors are classy individuals, who require certain living standards in their rooms and furniture. They may [[demand]] certain types of furniture in their rooms and will get unhappy if you don't comply. They can [[mandate]] the production of certain goods, and receive a happy thought if you comply. If the mandated items are not produced in time, the mayor will receive an unhappy thought and will order the [[Justice|punishment]] of whoever they consider responsible. Likewise, they can prohibit the export of certain goods instead of mandating their construction, resulting in dwarves being punished for trade violations.

Mayors are not replaced by [[baron]]s, [[duke]]s, [[count]]s or [[monarch]]s; if one of these nobles arrives, or if a citizen of your fortress is promoted to one of these positions, the mayor will still issue mandates and require quarters.

== Mayoral elections ==

If you don't have a mayor, then the first [[elections|election]] will be triggered at the beginning of any season when you have 50 or more dwarves (including [[children]]). Also, if you have have 50 dwarves and no mayor, ''any'' change in the [[nobles]]' screen (including selecting "leave vacant") will trigger an election ''immediately''. (This can be used to "force" an election if one is not triggered normally.)

Once you have a mayor, elections take place at exactly 4:00 PM on the 17th day of [[calendar|summer]] (specifically, 20000 season-ticks after the beginning of that season). Mayors elected in summer serve for that one year duration, but can be re-elected at that time.

When an election happens, it's usually the dwarf with the highest [[social skill]]s who gets elected. In previous versions [[children]] had nothing to do but socialize, and did, therefore, gain lots of social skill, which carries over when a child becomes an adult at age 18, and so an 18-year-old mayor was not a rare sight. But in the current version, children prefer playing over socializing, and thus will only rarely become a mayor (with the possible exceptions of migrant children who already had high social skill on arrival, and of unhappy children constantly complaining).

The mayor doesn't actually need to be a dwarf, any [[Citizenship|citizen]] can be elected - however, dwarves currently on a [[mission]], or otherwise absent from the fortress, cannot. Prime candidates for mayor include [[vampire]]s (who tend to have high social skills if they have been around for a long time), tamed [[gremlin]]s, and other non-working citizens of your fortress, since they cannot be put to work either and have nothing to do but socialize and gain experience in all* relevant social skills.

: ''(* Not all dwarves can learn [[Social_skill#Conversational_skills|all 10]] social skills. Depending on their [[personality value]]s and [[personality facet]]s, they may be unable to earn [[experience]] one or more; for example, [[liar]] is relatively uncommon. If dwarves arrive at your fortress with scores in a skill they do not qualify to learn, that skill will [[rust]] away from lack of new experience; this includes your starting dwarves. The lack of such skills does not prevent them from being elected, but does put them at a disadvantage, both during an election and then, if elected, in handling some of their [[Social_skill#Conversational_skills|mayoral duties]].)''

=== Preferred candidates ===
There are, perhaps, three main criteria which separate "good" candidates from less desirable ones.

The first is their current role in the fortress, the current skills and services that they provide, be those artistic, industrial or military. If you're going to war, you don't want your one [[armorsmith]] to constantly leave the forge to [[meeting|hold meeting]]s with whiny dwarves and children. Similarly with outstanding military candidates - a mayor can't console anyone while they are at war. Likewise, a distant miner won't dig effectively if constantly walking back and forth to hold a meeting. And so forth - this is personal preference, but it can make a big difference if exactly the "wrong" profession suddenly has new demands placed upon them.

The second is their fitness for the job itself. As mentioned above, a vampire could be elected; there are uses in a fortress for a Vampire (properly isolated), and you don't want to have to choose between your Mayor draining dwarves or being isolated from their duties in consoling unhappy citizens. A simple handicap or physical injury may prevent effective meetings. Or just a lack of some of the social skills, precluding some of the mayoral functions - harder to console unhappy citizens if you're just too cruel to qualify for the [[Consoler]] skill.

But the most significant factor in (un)desirability might be [[mandate]]s, which are temporary mayoral decrees for mandatory production of specific items, or bans on export of same via [[trade]]. Ignoring or overlooking a mandate results in dwarven [[justice]], a potentially fatal outcome, and then all the fallout from that victim's bereaved friends - no thank you. Such mandated items are drawn directly from the [[preference]]s of the mayor, and so are predictable. While it may be not overly burdensome to (not) produce [[figurine]]s, or [[flood gate]]s, or [[buckler]]s for a while, it may be an entirely different matter for [[bed]]s, or [[goblet]]s, or [[breastplate]]s, or [[coffin]]s for the [[ghost|dead]]. Material preferences (e.g. a type of stone, metal, gem, wood, animal, food/drink, etc.) have no bearing on mandates.

The "best" candidate then is a dwarf that has no ''item preferences'' at all, which is uncommon but not too rare - perhaps(?) one in fifteen or twenty or so. No item preferences means no mandates - and that's better for everyone. Just hope that dwarf has solid social skills, or at least a potential for such (see previous).

===Preparing a candidate ===
If an undesirable dwarf is elected, it is far from impossible to "groom" a different dwarf to win the next election.

Elections are based on the Conversational/Social skills of all candidates, with the dwarf with higher social skills winning; but there are limited options for arranging for targeted extra experience in social skills. The simplest is to remove all labors/tasks from the chosen dwarf, and let them socialize in a central [[meeting area]] full time, season after season - all (possible) skills will increase, slowly but surely. The other side of this coin would be to keep all undesirable candidates away from social interaction as much as possible - keep them busy in workshops or far-away mines, or (better) enroll them in full-time [[military]] training. If the player decides to do mass-trading (with as many trade transactions as possible), the [[broker]] will earn significant additional social skill experience due to the high skill gain per trade transaction. This is the best reliable way to try to influence that a certain dwarf will gain the social skills to (eventually) become (and stay!) mayor.

Of course, the brute force method is the ever-popular [[unfortunate accident]], but that requires ''every'' other better-qualified dwarf to meet such an end, which could rapidly thin out otherwise useful citizens. Less extreme would be to send all such contenders off map on a quick [[mission]] just before election time each year, or year round (especially in the case of the Mayor themself, to prevent any experience gain) if your other residents can survive without the emotional support of [[meeting]] with the now-absent mayor.





{{gamedata| [POSITION:MAYOR]
[NAME:mayor:mayors]
[SITE]
[NUMBER:1]
[RESPONSIBILITY:MEET_WORKERS]
[RESPONSIBILITY:RECEIVE_DIPLOMATS]
[RESPONSIBILITY:MILITARY_GOALS]
[REQUIRES_POPULATION:50]
[RULES_FROM_LOCATION]
[ELECTED]
[PRECEDENCE:60]
[FLASHES]
[BRAG_ON_KILL]
[CHAT_WORTHY]
[DO_NOT_CULL]
[KILL_QUEST]
[COLOR:5:0:0]
[ACCOUNT_EXEMPT]
[DUTY_BOUND]
[DEMAND_MAX:2]
[MANDATE_MAX:1]
[REQUIRED_BOXES:2]
[REQUIRED_CABINETS:1]
[REQUIRED_RACKS:1]
[REQUIRED_STANDS:1]
[REQUIRED_OFFICE:500]
[REQUIRED_BEDROOM:500]
[REQUIRED_DINING:500]}}
{{Nobles}}
{{Category|Elected Nobles}}

Mayor

2026-03-09T09:10:05Z

Joostheger: Preparing a candidate is a perfectly legal way, and has nothing to do with rigging. /* Rigging an election */

{{Quality|Superior}}
{{av}}
{{Noble
| noble= Mayor
| office= Decent Office
| quarters= Decent Quarters
| dining= Decent Dining Room
| chests=2
| cabinets=1
| racks=1
| stands=1
| mandates=1
| demands=2
| arrival=
* 50 population
* Elected
| function=
* Meet with foreign dignitaries
* Talk with unhappy citizens}}
The '''mayor''' is a [[noble]] whose job it is to speak with unhappy citizens, and (until a [[baron]] is appointed) entertain foreign [[diplomat]]s. They are automatically elected from the most social [[dwarf]], most likely the [[expedition leader]], once the population reaches 50. A new mayor may be elected from time to time as your dwarves' [[social skill]]s change.

== Mayoral nobility ==
[[File:Goblin_slaying_Mayor.png‎|thumb|left|A dwarven mayor conducting a "meeting" with some goblin "liaisons".]]A mayor or expedition leader is required to appoint other nobles. Should your leader suffer an [[unfortunate accident]], you will have to wait for a new leader to be elected before appointing nobles.

Mayors are classy individuals, who require certain living standards in their rooms and furniture. They may [[demand]] certain types of furniture in their rooms and will get unhappy if you don't comply. They can [[mandate]] the production of certain goods, and receive a happy thought if you comply. If the mandated items are not produced in time, the mayor will receive an unhappy thought and will order the [[Justice|punishment]] of whoever they consider responsible. Likewise, they can prohibit the export of certain goods instead of mandating their construction, resulting in dwarves being punished for trade violations.

Mayors are not replaced by [[baron]]s, [[duke]]s, [[count]]s or [[monarch]]s; if one of these nobles arrives, or if a citizen of your fortress is promoted to one of these positions, the mayor will still issue mandates and require quarters.

== Mayoral elections ==

If you don't have a mayor, then the first [[elections|election]] will be triggered at the beginning of any season when you have 50 or more dwarves (including [[children]]). Also, if you have have 50 dwarves and no mayor, ''any'' change in the [[nobles]]' screen (including selecting "leave vacant") will trigger an election ''immediately''. (This can be used to "force" an election if one is not triggered normally.)

Once you have a mayor, elections take place at exactly 4:00 PM on the 17th day of [[calendar|summer]] (specifically, 20000 season-ticks after the beginning of that season). Mayors elected in summer serve for that one year duration, but can be re-elected at that time.

When an election happens, it's usually the dwarf with the highest [[social skill]]s who gets elected. In previous versions [[children]] had nothing to do but socialize, and did, therefore, gain lots of social skill, which carries over when a child becomes an adult at age 18, and so an 18-year-old mayor was not a rare sight. But in the current version, children prefer playing over socializing, and thus will only rarely become a mayor (with the possible exceptions of migrant children who already had high social skill on arrival, and of unhappy children constantly complaining).

The mayor doesn't actually need to be a dwarf, any [[Citizenship|citizen]] can be elected - however, dwarves currently on a [[mission]], or otherwise absent from the fortress, cannot. Prime candidates for mayor include [[vampire]]s (who tend to have high social skills if they have been around for a long time), tamed [[gremlin]]s, and other non-working citizens of your fortress, since they cannot be put to work either and have nothing to do but socialize and gain experience in all* relevant social skills.

: ''(* Not all dwarves can learn [[Social_skill#Conversational_skills|all 10]] social skills. Depending on their [[personality value]]s and [[personality facet]]s, they may be unable to earn [[experience]] one or more; for example, [[liar]] is relatively uncommon. If dwarves arrive at your fortress with scores in a skill they do not qualify to learn, that skill will [[rust]] away from lack of new experience; this includes your starting dwarves. The lack of such skills does not prevent them from being elected, but does put them at a disadvantage, both during an election and then, if elected, in handling some of their [[Social_skill#Conversational_skills|mayoral duties]].)''

=== Preferred candidates ===
There are, perhaps, three main criteria which separate "good" candidates from less desirable ones.

The first is their current role in the fortress, the current skills and services that they provide, be those artistic, industrial or military. If you're going to war, you don't want your one [[armorsmith]] to constantly leave the forge to [[meeting|hold meeting]]s with whiny dwarves and children. Similarly with outstanding military candidates - a mayor can't console anyone while they are at war. Likewise, a distant miner won't dig effectively if constantly walking back and forth to hold a meeting. And so forth - this is personal preference, but it can make a big difference if exactly the "wrong" profession suddenly has new demands placed upon them.

The second is their fitness for the job itself. As mentioned above, a vampire could be elected; there are uses in a fortress for a Vampire (properly isolated), and you don't want to have to choose between your Mayor draining dwarves or being isolated from their duties in consoling unhappy citizens. A simple handicap or physical injury may prevent effective meetings. Or just a lack of some of the social skills, precluding some of the mayoral functions - harder to console unhappy citizens if you're just too cruel to qualify for the [[Consoler]] skill.

But the most significant factor in (un)desirability might be [[mandate]]s, which are temporary mayoral decrees for mandatory production of specific items, or bans on export of same via [[trade]]. Ignoring or overlooking a mandate results in dwarven [[justice]], a potentially fatal outcome, and then all the fallout from that victim's bereaved friends - no thank you. Such mandated items are drawn directly from the [[preference]]s of the mayor, and so are predictable. While it may be not overly burdensome to (not) produce [[figurine]]s, or [[flood gate]]s, or [[buckler]]s for a while, it may be an entirely different matter for [[bed]]s, or [[goblet]]s, or [[breastplate]]s, or [[coffin]]s for the [[ghost|dead]]. Material preferences (e.g. a type of stone, metal, gem, wood, animal, food/drink, etc.) have no bearing on mandates.

The "best" candidate then is a dwarf that has no ''item preferences'' at all, which is uncommon but not too rare - perhaps(?) one in fifteen or twenty or so. No item preferences means no mandates - and that's better for everyone. Just hope that dwarf has solid social skills, or at least a potential for such (see previous).

===Ppreparing a candidate ===
If an undesirable dwarf is elected, it is far from impossible to "groom" a different dwarf to win the next election.

Elections are based on the Conversational/Social skills of all candidates, with the dwarf with higher social skills winning; but there are limited options for arranging for targeted extra experience in social skills. The simplest is to remove all labors/tasks from the chosen dwarf, and let them socialize in a central [[meeting area]] full time, season after season - all (possible) skills will increase, slowly but surely. The other side of this coin would be to keep all undesirable candidates away from social interaction as much as possible - keep them busy in workshops or far-away mines, or (better) enroll them in full-time [[military]] training. If the player decides to do mass-trading (with as many trade transactions as possible), the [[broker]] will earn significant additional social skill experience due to the high skill gain per trade transaction. This is the best reliable way to try to influence that a certain dwarf will gain the social skills to (eventually) become (and stay!) mayor.

Of course, the brute force method is the ever-popular [[unfortunate accident]], but that requires ''every'' other better-qualified dwarf to meet such an end, which could rapidly thin out otherwise useful citizens. Less extreme would be to send all such contenders off map on a quick [[mission]] just before election time each year, or year round (especially in the case of the Mayor themself, to prevent any experience gain) if your other residents can survive without the emotional support of [[meeting]] with the now-absent mayor.





{{gamedata| [POSITION:MAYOR]
[NAME:mayor:mayors]
[SITE]
[NUMBER:1]
[RESPONSIBILITY:MEET_WORKERS]
[RESPONSIBILITY:RECEIVE_DIPLOMATS]
[RESPONSIBILITY:MILITARY_GOALS]
[REQUIRES_POPULATION:50]
[RULES_FROM_LOCATION]
[ELECTED]
[PRECEDENCE:60]
[FLASHES]
[BRAG_ON_KILL]
[CHAT_WORTHY]
[DO_NOT_CULL]
[KILL_QUEST]
[COLOR:5:0:0]
[ACCOUNT_EXEMPT]
[DUTY_BOUND]
[DEMAND_MAX:2]
[MANDATE_MAX:1]
[REQUIRED_BOXES:2]
[REQUIRED_CABINETS:1]
[REQUIRED_RACKS:1]
[REQUIRED_STANDS:1]
[REQUIRED_OFFICE:500]
[REQUIRED_BEDROOM:500]
[REQUIRED_DINING:500]}}
{{Nobles}}
{{Category|Elected Nobles}}

Mayor

2026-03-09T09:04:43Z

Joostheger: /* Mayoral elections */

{{Quality|Superior}}
{{av}}
{{Noble
| noble= Mayor
| office= Decent Office
| quarters= Decent Quarters
| dining= Decent Dining Room
| chests=2
| cabinets=1
| racks=1
| stands=1
| mandates=1
| demands=2
| arrival=
* 50 population
* Elected
| function=
* Meet with foreign dignitaries
* Talk with unhappy citizens}}
The '''mayor''' is a [[noble]] whose job it is to speak with unhappy citizens, and (until a [[baron]] is appointed) entertain foreign [[diplomat]]s. They are automatically elected from the most social [[dwarf]], most likely the [[expedition leader]], once the population reaches 50. A new mayor may be elected from time to time as your dwarves' [[social skill]]s change.

== Mayoral nobility ==
[[File:Goblin_slaying_Mayor.png‎|thumb|left|A dwarven mayor conducting a "meeting" with some goblin "liaisons".]]A mayor or expedition leader is required to appoint other nobles. Should your leader suffer an [[unfortunate accident]], you will have to wait for a new leader to be elected before appointing nobles.

Mayors are classy individuals, who require certain living standards in their rooms and furniture. They may [[demand]] certain types of furniture in their rooms and will get unhappy if you don't comply. They can [[mandate]] the production of certain goods, and receive a happy thought if you comply. If the mandated items are not produced in time, the mayor will receive an unhappy thought and will order the [[Justice|punishment]] of whoever they consider responsible. Likewise, they can prohibit the export of certain goods instead of mandating their construction, resulting in dwarves being punished for trade violations.

Mayors are not replaced by [[baron]]s, [[duke]]s, [[count]]s or [[monarch]]s; if one of these nobles arrives, or if a citizen of your fortress is promoted to one of these positions, the mayor will still issue mandates and require quarters.

== Mayoral elections ==

If you don't have a mayor, then the first [[elections|election]] will be triggered at the beginning of any season when you have 50 or more dwarves (including [[children]]). Also, if you have have 50 dwarves and no mayor, ''any'' change in the [[nobles]]' screen (including selecting "leave vacant") will trigger an election ''immediately''. (This can be used to "force" an election if one is not triggered normally.)

Once you have a mayor, elections take place at exactly 4:00 PM on the 17th day of [[calendar|summer]] (specifically, 20000 season-ticks after the beginning of that season). Mayors elected in summer serve for that one year duration, but can be re-elected at that time.

When an election happens, it's usually the dwarf with the highest [[social skill]]s who gets elected. In previous versions [[children]] had nothing to do but socialize, and did, therefore, gain lots of social skill, which carries over when a child becomes an adult at age 18, and so an 18-year-old mayor was not a rare sight. But in the current version, children prefer playing over socializing, and thus will only rarely become a mayor (with the possible exceptions of migrant children who already had high social skill on arrival, and of unhappy children constantly complaining).

The mayor doesn't actually need to be a dwarf, any [[Citizenship|citizen]] can be elected - however, dwarves currently on a [[mission]], or otherwise absent from the fortress, cannot. Prime candidates for mayor include [[vampire]]s (who tend to have high social skills if they have been around for a long time), tamed [[gremlin]]s, and other non-working citizens of your fortress, since they cannot be put to work either and have nothing to do but socialize and gain experience in all* relevant social skills.

: ''(* Not all dwarves can learn [[Social_skill#Conversational_skills|all 10]] social skills. Depending on their [[personality value]]s and [[personality facet]]s, they may be unable to earn [[experience]] one or more; for example, [[liar]] is relatively uncommon. If dwarves arrive at your fortress with scores in a skill they do not qualify to learn, that skill will [[rust]] away from lack of new experience; this includes your starting dwarves. The lack of such skills does not prevent them from being elected, but does put them at a disadvantage, both during an election and then, if elected, in handling some of their [[Social_skill#Conversational_skills|mayoral duties]].)''

=== Preferred candidates ===
There are, perhaps, three main criteria which separate "good" candidates from less desirable ones.

The first is their current role in the fortress, the current skills and services that they provide, be those artistic, industrial or military. If you're going to war, you don't want your one [[armorsmith]] to constantly leave the forge to [[meeting|hold meeting]]s with whiny dwarves and children. Similarly with outstanding military candidates - a mayor can't console anyone while they are at war. Likewise, a distant miner won't dig effectively if constantly walking back and forth to hold a meeting. And so forth - this is personal preference, but it can make a big difference if exactly the "wrong" profession suddenly has new demands placed upon them.

The second is their fitness for the job itself. As mentioned above, a vampire could be elected; there are uses in a fortress for a Vampire (properly isolated), and you don't want to have to choose between your Mayor draining dwarves or being isolated from their duties in consoling unhappy citizens. A simple handicap or physical injury may prevent effective meetings. Or just a lack of some of the social skills, precluding some of the mayoral functions - harder to console unhappy citizens if you're just too cruel to qualify for the [[Consoler]] skill.

But the most significant factor in (un)desirability might be [[mandate]]s, which are temporary mayoral decrees for mandatory production of specific items, or bans on export of same via [[trade]]. Ignoring or overlooking a mandate results in dwarven [[justice]], a potentially fatal outcome, and then all the fallout from that victim's bereaved friends - no thank you. Such mandated items are drawn directly from the [[preference]]s of the mayor, and so are predictable. While it may be not overly burdensome to (not) produce [[figurine]]s, or [[flood gate]]s, or [[buckler]]s for a while, it may be an entirely different matter for [[bed]]s, or [[goblet]]s, or [[breastplate]]s, or [[coffin]]s for the [[ghost|dead]]. Material preferences (e.g. a type of stone, metal, gem, wood, animal, food/drink, etc.) have no bearing on mandates.

The "best" candidate then is a dwarf that has no ''item preferences'' at all, which is uncommon but not too rare - perhaps(?) one in fifteen or twenty or so. No item preferences means no mandates - and that's better for everyone. Just hope that dwarf has solid social skills, or at least a potential for such (see previous).

=== Rigging an election ===
If an undesirable dwarf is elected, it is far from impossible to "groom" a different dwarf to win the next election.

Elections are based on the Conversational/Social skills of all candidates, with the dwarf with higher social skills winning; but there are limited options for arranging for targeted extra experience in social skills. The simplest is to remove all labors/tasks from the chosen dwarf, and let them socialize in a central [[meeting area]] full time, season after season - all (possible) skills will increase, slowly but surely. The other side of this coin would be to keep all undesirable candidates away from social interaction as much as possible - keep them busy in workshops or far-away mines, or (better) enroll them in full-time [[military]] training. If the player decides to do mass-trading (with as many trade transactions as possible), the [[broker]] will earn significant additional social skill experience due to the high skill gain per trade transaction. This is the best reliable way to try to influence that a certain dwarf will gain the social skills to (eventually) become (and stay!) mayor.

Of course, the brute force method is the ever-popular [[unfortunate accident]], but that requires ''every'' other better-qualified dwarf to meet such an end, which could rapidly thin out otherwise useful citizens. Less extreme would be to send all such contenders off map on a quick [[mission]] just before election time each year, or year round (especially in the case of the Mayor themself, to prevent any experience gain) if your other residents can survive without the emotional support of [[meeting]] with the now-absent mayor.





{{gamedata| [POSITION:MAYOR]
[NAME:mayor:mayors]
[SITE]
[NUMBER:1]
[RESPONSIBILITY:MEET_WORKERS]
[RESPONSIBILITY:RECEIVE_DIPLOMATS]
[RESPONSIBILITY:MILITARY_GOALS]
[REQUIRES_POPULATION:50]
[RULES_FROM_LOCATION]
[ELECTED]
[PRECEDENCE:60]
[FLASHES]
[BRAG_ON_KILL]
[CHAT_WORTHY]
[DO_NOT_CULL]
[KILL_QUEST]
[COLOR:5:0:0]
[ACCOUNT_EXEMPT]
[DUTY_BOUND]
[DEMAND_MAX:2]
[MANDATE_MAX:1]
[REQUIRED_BOXES:2]
[REQUIRED_CABINETS:1]
[REQUIRED_RACKS:1]
[REQUIRED_STANDS:1]
[REQUIRED_OFFICE:500]
[REQUIRED_BEDROOM:500]
[REQUIRED_DINING:500]}}
{{Nobles}}
{{Category|Elected Nobles}}

Position token

2026-03-08T20:53:30Z

Joostheger: /* Position tokens */

{{Quality|Fine}}
{{av}}
{{Modding}}
Position tokens define [[noble]] positions for civilizations and site governments, inside [[entity token]]s. In the vanilla game, position token definitions can be found in <code>[[Game folder|<Dwarf Fortress>]]\data\vanilla\vanilla_entities\objects\entity_default.txt</code>.

__TOC__
{{clear}}

==Code==
A position is defined with a position 'code', as an argument in the [POSITION]-tag. The same code may be used multiple times, they don't have to be unique. This code is used as reference by APPOINTED_BY, SUCCESSION:BY_POSITION, REPLACE_BY and COMMANDER. 'MONARCH' is an example of this code.

==Position tokens==
These tokens belong in an entity definition, applying to a position (such as monarch) and should follow the [POSITION:POSITION_NAME] token.

{| {{prettytable}}
|- bgcolor="#dddddd"
! Token
! Arguments
! Description

|-
| {{text anchor|ACCOUNT_EXEMPT}}
|
| The position holder is not subjected to the [[Dwarven economy|economy]]. Less than relevant right now.

|-
| {{text anchor|ALLOWED_CLASS}}
| {{token|CREATURE_CLASS|creature}} token
| rowspan=2 | ALLOWED_CLASS: Only creatures with the specified [CREATURE_CLASS] token may be appointed to this position. Multiple entries are allowed. ALLOWED_CREATURE: Restricts the position to the specified creature and caste. Multiple entries are allowed. These tokens only apply within the entity’s own race (including its castes).
In world generation, they limit which units may be assigned to the position, but they do not prevent other creature types from acquiring the position through alternative means (for example, via a coup).
In fortress mode, these tokens are enforced during manual appointment and succession.
During world generation, if all allowed castes have a POP_RATIO of 0, a unit of an allowed caste will still be generated to fill the position.

|-
| {{text anchor|ALLOWED_CREATURE}}
| CREATURE:CASTE

|-
| {{text anchor|APPOINTED_BY}}
| position
| This position can only be chosen for the task from the nobles screen, and is available only if there is an *argument* present. For example, the GENERAL is [APPOINTED_BY:MONARCH]. Contrast [ELECTED]. Being appointed by a MONARCH seems to handle a lot of worldgen stuff, and interferes with fort mode titles. Multiple entries are allowed. If you have neither an ELECTED-token nor a APPOINTED_BY-token, the holder may always be changed (like the expedition leader).
''Read more: [[Advanced_Entity_Position_Mechanics#Appointment]]''

|-
| {{text anchor|BRAG_ON_KILL}}
|
| A creature that kills a member of this position will be sure to talk about it a lot.

|-
| {{text anchor|CHAT_WORTHY}}
|
| In adventure mode, when referencing locations, an NPC may mention this position holder living there or having done some deed there; it also means that the position exists in world-gen, rather than being created only at the end of world-gen.

|-
| {{text anchor|COLOR}}
| [[Color]]
| Creatures of this position will have this [[Color]], instead of their profession color, e.g. [COLOR:5:0:1]. It is also applied to the name of the citizen in the units-screen.

|-
| {{text anchor|COMMANDER}}
| position:ALL
| This position will act as a commander of the specified position{{verify}}. E.g. GENERAL is [COMMANDER:LIEUTENANT:ALL]. Unknown if values other than ALL work. Multiple entries are allowed.
''Read more: [[Army]]''

|-
| {{text anchor|CONQUERED_SITE}}
|
| This position is a puppet ruler, left behind in a conquered site.

|-
| {{text anchor|DEMAND_MAX}}
| number (0-100)
| How many demands the position can make of the population at one time.

|-
| {{text anchor|DESCRIPTION}}
| string. Readable up to 470 characters in the nobles' screen.
| description of this position in the nobles screen.

|-
| {{text anchor|DETERMINES_COIN_DESIGN}}
|
| The site's (or civ's) minted [[coin]]s, if any, will have images that reflect the personality of this position holder.

|-
| {{text anchor|DO_NOT_CULL}}
|
| The position won't be culled from Legends as "unimportant" during world generation.

|-
| {{text anchor|DUTY_BOUND}}
|
| Members of this position will never agree to 'join' your character during adventure mode. They also don't settle anywhere else but in the capital, and will not [[immigration|emigrate]] from their site. If they are not DUTY_BOUND, they will live anywhere as they like.

|-
| {{text anchor|ELECTED}}
|
| The population will periodically select the most skill-eligible creature to fill this position for site-level positions at the player's fort. For responsibilities or positions that use more than one skill, no skill takes priority in electing a creature: an accomplished comedian is more qualified for the TRADE responsibility than a skilled appraiser. A creature may be elected to multiple positions at the same time. Contrast [APPOINTED_BY].
''More info: [[Elections]]''
''Read more: [[Advanced_Entity_Position_Mechanics#Elections]]''

|-
| {{text anchor|EXECUTION_SKILL}}
| weapon skill
| A mandatory sub-tag of [RESPONSIBILITY:EXECUTIONS]. Determines the weapon chosen by the executioner for their work.

|-
| {{text anchor|EXPORTED_IN_LEGENDS}}
|
| The various members who have filled this role will be listed in the civilisation's history.

|-
| {{text anchor|FLASHES}}
|
| The creature holding this position will visibly flash, like legendary citizens. Represents a properly noble station by default.

|-
| {{text anchor|GENDER}}
| male/female
| The position can only be held by the specified gender. Currently bugged {{bug|2714}}

|-
| {{text anchor|KILL_QUEST}}
|
| The position can assign quests to adventurers.

|-
| {{text anchor|LAND_HOLDER}}
| importance tier (1-10)
| This is an alternative to SITE, allowing positions to be created at civ-level 'as needed' for all sites that meet the requirements to have them, which are the values set in [[Difficulty#Land_holder|land holder difficulty]] [[settings]]. The character is tied permanently to a particular site, but also operates at the civ-level.
''Read more: [[Advanced_Entity_Position_Mechanics#land holders]]''

|-
| {{text anchor|LAND_NAME}}
| string. Readable up to 21 characters in the nobles' screen.
| The name the area takes on when under the control of a LAND_HOLDER. E.g. for the DUKE, [LAND_NAME:a duchy]. If the position is not a [[LAND_HOLDER]], the land_name is still displayed left of the position in the nobles menu.

|-
| {{text anchor|MANDATE_MAX}}
| number (0-100)
| The maximum number of mandates the position can make at once.

|-
| {{text anchor|MENIAL_WORK_EXEMPTION}}
|
| The position holder cannot be assigned labors. It only works for [SITE]-positions.

|-
| {{text anchor|MENIAL_WORK_EXEMPTION_SPOUSE}}
|
| The spouse of the position holder doesn't have to work, either - see above.
|-
| {{text anchor|MILITARY_SCREEN_ONLY}}
|
| This position cannot be appointed from the nobles screen. Intended for militia captains and other squad leaders to reduce clutter. Currently nonfunctional{{bug|8965}}

|-
| {{text anchor|NAME}}
| singular:plural. Readable up to 21 characters in the nobles' screen and up to 30 in the unit list.
| The name of the position.

|-
| {{text anchor|NAME_MALE}}
| singular:plural. Readable up to 21 characters in the nobles' screen and up to 30 in the unit list.
| If the creature holding the position is male, this is the position's name. E.g. for MONARCH, [NAME_MALE:king:kings]

|-
| {{text anchor|NAME_FEMALE}}
| singular:plural. Readable up to 21 characters in the nobles' screen and up to 30 in the unit list.
| If the creature holding the position is female, this is the position's name. E.g. for MONARCH, [NAME_FEMALE:queen:queens]

|-
| {{text anchor|NUMBER}}
|
* number/AS_NEEDED
| How many of the position there should be. If the [SITE] token exists, this is per site, otherwise this is per civilisation. AS_NEEDED applies mainly to positions involved with the military command chain; this is used to allow armies to expand to whatever size they need to be. Other non-military positions like the land_holders or the [[messenger]] with NUMBER:AS_NEEDED will also be appointed.
The problem with [[Lieutenant]]s and [[Captain]]s not being created, is their AS_NEEDED number. They are only then created when they're needed, and that has some pretty unusual conditions. When a fixed number is used, they are appointed with the creation of the civ.
If the NUMBER is set at a fixed value higher than 1, the position is always filled up full. If the position is available on embark, it is completely filled up with only the first dwarf.

|-
| {{text anchor|PRECEDENCE}}
| number (0-30000)/NONE
| How important the position is in society; a lower number is more important and displayed higher in the Nobles menu. For MONARCH it's 1, for MILITIA_CAPTAIN it's 200. The game marks the first non-[SITE] position with [PRECEDENCE:1] as the ruler, for both embark screen and mountainhome purposes. When it is empty, [REPLACED_BY] another position, or not yet created because of [REQUIRES_POPULATION], the screen just says 'None' as the holders' name. Landholders can become the ruler, if they are the first defined position with precedence of 1. civ-position can also be created without precedence. Positions may have the same precedence and will be appointed, although the effect is unknown. Precedence has no effect on who's doing the job, if both positions have the same responsibilities.

|-
| {{text anchor|PUNISHMENT_EXEMPTION}}
|
| The position holder will not be held accountable for his or her crimes. Currently nonfunctional.{{bug|4589}}{{verify|seems to prevent punishment when they are convicted of actual crime}}

|-
| {{text anchor|QUEST_GIVER}}
|
| The position holder can give quests in Adventure mode. Functionality in 0.31.13 and later is uncertain.

|-
| {{text anchor|REJECTED_CLASS}}
| CREATURE_CLASS Token
| Creatures of the specified class cannot be appointed to this position. Multiple entries are allowed

|-
| {{text anchor|REJECTED_CREATURE}}
| CREATURE:CASTE
| Restricts position holders by CREATURE type. Multiple entries are allowed. It doesn't seem to work in world-gen. When checking Legends mode, units are seen assigned this position regardless of their creature-type or caste. It does work in Fortress mode.

|-
| {{text anchor|REPLACED_BY}}
| position
| This position is absorbed by another down the line. For example, expedition leader is [REPLACED_BY:MAYOR]. Only a single entry is allowed.

|-
| {{text anchor|REQUIRED_BEDROOM}}
| number (0-1000000)
| The position holder requires a bedroom with at least this value.

|-
| {{text anchor|REQUIRED_BOXES}}
| number (0-100)
| The position holder requires at least this many boxes.

|-
| {{text anchor|REQUIRED_CABINETS}}
| number (0-100)
| The position holder requires at least this many cabinets.

|-
| {{text anchor|REQUIRED_DINING}}
| number (0-1000000)
| The position holder requires a dining room with at least this value.

|-
| {{text anchor|REQUIRED_OFFICE}}
| number (0-1000000)
| The position holder requires an office with at least this value.

|-
| {{text anchor|REQUIRED_RACKS}}
| number (0-100)
| The position holder requires at least this many weapon racks.

|-
| {{text anchor|REQUIRED_STANDS}}
| number (0-100)
| The position holder requires at least this many armour stands.

|-
| {{text anchor|REQUIRED_TOMB}}
| number (0-1000000)
| The position holder requires a tomb with at least this value.

|-
| {{text anchor|REQUIRES_MARKET}}
|
| Does not have anything directly to do with [[trade depot|trade depots]]. It means that in minor sites (such as hillocks) the position will not appear, while in major sites (such as dwarf fortresses) it will. Depending on its economical position in the region, a [[hamlet]] may build a market and develop into a [[Town]] eventually. That is when this position becomes available. It only works in combination with the [SITE]-token.

|-
| {{text anchor|REQUIRES_POPULATION}}
| number
| The position requires the population to be at least this number before it becomes available, or before the position holder will move in.

|-
| {{text anchor|RESPONSIBILITY}}
| responsibility
| The position holder does a thing. See the table below for suitable arguments. A position does not need to have a responsibility.

|-
| {{text anchor|RULES_FROM_LOCATION}}
|
| If there is a special location set aside for rulers, such as a human castle/mead hall, the position holder will always be found at that particular location. Does nothing for dwarven nobles, because at present, dwarves have no such special locations.

|-
| {{text anchor|SITE}}
|
| Every site government will have the defined number of this position instead of the whole civilization; provided that other criteria (if any) are met. Unless LAND_HOLDER is present instead, the defined number of the position will be created only for the civilization as a whole.

|-
| {{text anchor|SLEEP_PRETENSION}}
|
| The position holder will get upset if someone with a higher PRECEDENCE holds quarters with a greater value than their own.

|-
| {{text anchor|SPECIAL_BURIAL}}
|
| The civilization will inter the corpse of the position holder in a special grave, either in catacombs or in monuments. If that grave is disturbed, the position holder can return as a [[mummy]]. {{verify}}

|-
| {{text anchor|SPOUSE}}
| singular:plural. Readable up to 30 characters in the unit list.
| The name of the position holder's spouse.

|-
| {{text anchor|SPOUSE_FEMALE}}
| singular:plural. Readable up to 30 characters in the unit list.
| If the spouse of the creature holding the position is female, this is the spouse's position name.

|-
| {{text anchor|SPOUSE_MALE}}
| singular:plural. Readable up to 30 characters in the unit list.
| If the spouse of the creature holding the position is male, this is the spouse's position name.

|-
| {{text anchor|SQUAD}}
| number:singular:plural
| The position holder is authorized to form a military squad, led by themselves using the [[leader]] and [[military tactics]] skills. The number denotes the maximum headcount. The noun used to describe the subordinates (e.g. royal guard) is used in adventure mode for the adventurer. This token is used together with [RESPONSIBILITY:LAW_ENFORCEMENT] for giving [[quest]]s to adventurers as [[Hearthperson|hearthpeople]]. Further details: [[Advanced_entity_position_mechanics#Military]]

|-
| {{text anchor|SUCCESSION}}
|
* BY_HEIR / BY_POSITION:position
| How a new position holder is chosen. A single position can have multiple BY_POSITION tokens. See [[Noble]] for more information on how succession is handled in the game.
The SUCCESSION-Tag is also considered when a new positions opens up, for example when a required population number is reached. If a valid successor is available, they will be the one taking that position initially, without appointment or election.

|}

== Responsibilities ==
{| {{prettytable}}
|- bgcolor="#dddddd"
! Argument
! Description

|-
| {{text anchor|ACCOUNTING}}
| Found on [[bookkeeper]]. Position will use [[record keeper]] skill to keep track of stocks.

|-
| {{text anchor|ADVISE_LEADERS}}
|

|-
| {{text anchor|ATTACK_ENEMIES}}
| Found on elven [[ranger captain]] and human warrior. Effect unknown.{{verify}}

|-
| {{text anchor|BUILD_MORALE}}
| Found on [[champion]]. Citizens get a special thought for "talking to a pillar of society" when speaking to this noble.

|-
| {{text anchor|BUILDING_SAFETY}}
|

|-
| {{text anchor|COLLECT_TAXES}}
| Currently unused - was originally assigned to the tax collector.

|-
| {{text anchor|CONSTRUCTION_PERMITS}}
|

|-
| {{text anchor|DELIVER_MESSAGES}}
| Found on [[messenger]]. Position travels to other sites and uses [[social skill]]s.
|

|-
| {{text anchor|EQUIPMENT_MANIFESTS}}
| Currently unused - was originally assigned to the arsenal dwarf.

|-
| {{text anchor|ESCORT_TAX_COLLECTOR}}
| Currently unused - was originally assigned to the Royal Guards (squad members beneath the Hammerer).

|-
| {{text anchor|ESPIONAGE}}
| Found on [[dungeon master]] and the [[Elf|elven]] [[General|princess]] and uses the [[schemer]] skill.

|-
| {{text anchor|ESTABLISH_COLONY_TRADE_AGREEMENTS}}
| Found on [[outpost liaison]]. Position travels with the caravan and uses [[social skill]]s to make trade agreements with any settlements that it visits, provided they are domestic, report the news and promote {{token|LAND_HOLDER|e}} positions. Also reports recent news. Presumably has no effect at site level. Crucially, it does not visit foreign settlements, but the civ-level TRADE position does the exact same thing in its position. They arrive the same time as the caravan arrives, and this can thus be modded by setting {{token|ACTIVE_SEASON|e}}

|-
| {{text anchor|EXECUTIONS}}
| Found on [[hammerer]]. Position executes death penalty judgements with a weapon of the appropriate skill. Cannot be combined with LAW_ENFORCEMENT, resulting in the "Invalid Officer"-error.

|-
| {{text anchor|FIRE_SAFETY}}
|

|-
| {{text anchor|FOOD_SUPPLY}}
|

|-
| {{text anchor|HEALTH_MANAGEMENT}}
| Found on [[chief medical dwarf]]. Position will use [[diagnostician]] skill to evaluate [[wounds]] and schedule [[Health care|treatment]], reported in each citizen's Health tab.

|-
| {{text anchor|JUDGE}}
|

|-
| {{text anchor|LAW_ENFORCEMENT}}
| Found on [[sheriff]]/[[captain of the guard]]. Position and its subordinates are in charge of punishing criminals. A {{token|SITE|position}} position holding this responsibility plus the {{token|SQUAD|position}} token (or allowing the entity to have a {{token|SITE_VARIABLE_POSITIONS|e}} with this responsibility) is required for an adventurer from a given civilization to start as a [[hearthperson]], [[Captain of the guard|fortress guard]], etc. Cannot be combined with EXECUTIONS, resulting in the "Invalid Officer"-error.

|-
| {{text anchor|LAW_MAKING}}
| Found on [[monarch]]s and [[:Category:Aristocrats|nobles]]. Will be referred to as the leader of the site in adventure mode and they may designate the site as being the capital city for civ-level positions. This position is in charge of creating procedural positions, corresponding to either {{token|VARIABLE_POSITIONS|e}} or {{token|SITE_VARIABLE_POSITIONS|e}}. Position-holders that have attained [[immortality]] may issue oppressive edicts to protect themselves against suspicion.

|-
| {{text anchor|MAINTAIN_BRIDGES}}
|

|-
| {{text anchor|MAINTAIN_ROADS}}
|

|-
| {{text anchor|MAINTAIN_SEWERS}}
|

|-
| {{text anchor|MAINTAIN_TUNNELS}}
|

|-
| {{text anchor|MAKE_INTRODUCTIONS}}
| Position will make a 'social call' to an established foreign settlement, complimenting or insulting them depending on relations and reporting the news.

|-
| {{text anchor|MAKE_PEACE_AGREEMENTS}}
| Found on diplomat. Position negotiates peace treaties in order to end wars.

|-
| {{text anchor|MAKE_TOPIC_AGREEMENTS}}
| Found on [[diplomat]]. Position negotiates special agreements, such as tree cutting quotas. Used when elevating a settlement in the {{token|LAND_HOLDER|position}} chain up from level 1.

|-
| {{text anchor|MANAGE_ANIMALS}}
| Found on [[dungeon master]].

|-
| {{text anchor|MANAGE_LEADER_HOUSEHOLD_CLEANLINESS}}
|

|-
| {{text anchor|MANAGE_LEADER_HOUSEHOLD_DRINKS}}
|

|-
| {{text anchor|MANAGE_LEADER_HOUSEHOLD_FOOD}}
|

|-
| {{text anchor|MANAGE_PRODUCTION}}
| Found on [[manager]]. Position enables the use of workshop profiles and uses the [[organizer]] skill to process work orders entered in the job manager after the fortress population reaches 20.

|-
| {{text anchor|MEET_WORKERS}}
| Found on [[expedition leader]]/[[mayor]]. Position uses the various [[social skill]]s to hold meetings with unhappy citizens and try to pacify them with happy thoughts. In adventure mode, [SITE] positions with this responsibility handle petitions to make the player a performer for the local government.

|-
| {{text anchor|MILITARY_GOALS}}
| Found on [[monarch]]/[[:Category:Aristocrats|landholder]]/[[:Category:Elected Nobles|leaders]]. Character is in charge of going to war and making peace for the government they work for. Without a position with this responsibility at civ level the civilization will not be able to make peace and its sites will wage war on each other constantly, and as a result, all viable civilizations must have one leader with this tag at civ level. This appears not to be a problem for [[kobold]]s, presumably due to the {{token|SKULKING|e}}. If no position has this responsibility in fortress mode, players are unable to start [[missions]].

|-
| {{text anchor|MILITARY_STRATEGY}}
| Found on [[general]]/[[militia commander]]. Means that they will command the armies of their site or civilization. Issues the orders for the teams conducting raids or other operations away from the fortress. During worldgen, position will go on expeditions to tame exotic creatures. Counterintuitively not by the TAME_EXOTICS-position. The destinations of these expeditions are determined by the entities USE_(...)_ANIMALS-tokens.

|-
| {{text anchor|OVERSEE_LEADER_HOUSEHOLD}}
|

|-
| {{text anchor|PATROL_TERRITORY}}
| Found on elven ranger captain. Effect unknown.{{verify}}

|-
| {{text anchor|PREPARE_LEADER_MEALS}}
|

|-
| {{text anchor|RECEIVE_DIPLOMATS}}
| Found on [[monarch]]/[[:Category:Aristocrats|landholder]]/[[:Category:Elected Nobles|leaders]]. Position uses the various social skills to hold meetings with incoming diplomats and liaisons.

|-
| {{text anchor|RELIGION}}
| Found on elven [[druid]] and uses [[social skill]]s. Position informs you about worship cults{{verify}}

|-
| {{text anchor|SORT_AMMUNITION}}
| Currently unused - was originally assigned to the arsenal dwarf.

|-
| {{text anchor|TAME_EXOTICS}}
| Position will tame animals with the {{token|PET_EXOTIC}} token. Currently unused - was originally assigned to the dungeon master. Expeditions to tame exotic creatures will be done by the MILITARY_STRATEGY-position

|-
| {{text anchor|TRADE}}
| Found on [[broker]]. Position will use Appraisal skill to display value estimates and the various Social skills to trade at the depot. When applied to other civilizations, this position will arrive with the caravan to make trade agreements (like the Human Guild Representative from older versions) and behaves otherwise like the civ's own ESTABLISH_COLONY_TRADE_AGREEMENTS position holder. They arrive the same time as the caravan arrive and this can thus be modded by setting {{token|ACTIVE_SEASON|e}}

|-
| {{text anchor|UPGRADE_SQUAD_EQUIPMENT}}
| Currently unused - was originally assigned to the arsenal dwarf.

|}

== Related tokens ==
The following two ENTITY tokens are not actually position tokens, but bear mentioning on this page because they can modify the way that a civilization's positions behave:

{| {{prettytable}}
|- bgcolor="#dddddd"
! Token
! Arguments
! Description

|-
| {{text anchor|VARIABLE_POSITIONS}}
| Position responsibility or ALL
| Allows a responsibility to be taken up by a dynamically generated position (such as Law-maker).

|}

== Why won't my positions appear? ==
The way DF determines what positions will actually ''appear'' in your fortress is somewhat counter-intuitive and fairly limiting. This guide should help you understand what you can do to actually get your positions working properly.

There are five tokens governing which positions appear in your fortress - LAND_HOLDER, REQUIRES_POPULATION, APPOINTED_BY, ELECTED, and REPLACED_BY. The first two determine when your fortress is eligible for a new position, the next two determine how a new position for which your fortress is eligible can be added, and the fifth allows you to clear up obsolete positions. Unfortunately, they also interact in some strange ways that makes creating interesting position structures difficult.

When you start a new fortress, DF compiles a list of your initial positions. To do this, it looks at the requirements for each position - any position whose only requirement is less than seven dwarves (either because they have no requirement tokens, or because their only requirement tokens are [REQUIRES_POPULATION: =< 7] or [LAND_HOLDER:some trigger whose only requirement is some number of dwarves equal to or less than 7]). Most importantly, ''any'' position whose only requirement is a LAND_HOLDER requirement, regardless of what the trigger for that requirement is, will be added if another eligible starting position is REPLACED_BY it. '''A non-LAND_HOLDER position that is REPLACED_BY a LAND_HOLDER position will never appear.''' With this list compiled, the game culls all positions that are REPLACED_BY another eligible position, and then culls all positions that have the APPOINTED_BY token. '''You may not embark with any appointed positions.''' Any remaining positions are then filled by a dwarf chosen at random.

'''Positions do not automatically appear when you reach their requirements.''' For example, if you remove the ELECTED token from the Mayor, then the Mayor will never appear, even once you reach their required number of dwarves. '''For a position that does not appear at embark to appear in your fortress, it must be APPOINTED_BY another position or ELECTED.'''

Naturally, this is more complicated than it looks. '''APPOINTED_BY positions must be appointed by another position already in your fortress, or a civ-level position. Only LAND_HOLDER positions may be appointed by civ-level positions.''' LAND_HOLDER positions that are APPOINTED_BY civ-level positions are inherently tied to civ-level tokens with the ESTABLISH_COLONY_TRADE_AGREEMENTS responsibility. If a fortress meets the LAND_HOLDER_TRIGGER for a new LAND_HOLDER tier when a caravan leaves, then the next time the outpost liaison or equivalent arrives, they will offer to make you an official colony, which will allow you to select all positions for that LAND_HOLDER level. '''Each time they appear, the outpost liaison will only promote your fortress one tier up the LAND_HOLDER track.''' The biggest problem with this system is that you may set your LAND_HOLDER_TRIGGERS such that you are eligible for the first tier of LAND_HOLDER positions at embark. '''If you are eligible for the first tier of LAND_HOLDER positions at embark, then all first-tier positions will appear twice - once at embark, and again when the outpost liaison comes to appoint you to the first tier.'''

If civ-positions are neither APPOINTED_BY nor ELECTED, they still will be filled.

Read more: [[Advanced_Entity_Position_Mechanics]]

{{Category|Modding}}
{{Category|Tokens}}
[[ru:Position token]]

Position token

2026-03-08T20:52:44Z

Joostheger: /* Position tokens */

{{Quality|Fine}}
{{av}}
{{Modding}}
Position tokens define [[noble]] positions for civilizations and site governments, inside [[entity token]]s. In the vanilla game, position token definitions can be found in <code>[[Game folder|<Dwarf Fortress>]]\data\vanilla\vanilla_entities\objects\entity_default.txt</code>.

__TOC__
{{clear}}

==Code==
A position is defined with a position 'code', as an argument in the [POSITION]-tag. The same code may be used multiple times, they don't have to be unique. This code is used as reference by APPOINTED_BY, SUCCESSION:BY_POSITION, REPLACE_BY and COMMANDER. 'MONARCH' is an example of this code.

==Position tokens==
These tokens belong in an entity definition, applying to a position (such as monarch) and should follow the [POSITION:POSITION_NAME] token.

{| {{prettytable}}
|- bgcolor="#dddddd"
! Token
! Arguments
! Description

|-
| {{text anchor|ACCOUNT_EXEMPT}}
|
| The position holder is not subjected to the [[Dwarven economy|economy]]. Less than relevant right now.

|-
| {{text anchor|ALLOWED_CLASS}}
| {{token|CREATURE_CLASS|creature}} token
| rowspan=2 | ALLOWED_CLASS: Only creatures with the specified [CREATURE_CLASS] token may be appointed to this position. Multiple entries are allowed. ALLOWED_CREATURE: Restricts the position to the specified creature and caste. Multiple entries are allowed. These tokens only apply within the entity’s own race (including its castes).
In world generation, they limit which units may be assigned to the position, but they do not prevent other creature types from acquiring the position through alternative means (for example, via a coup).
In fortress mode, these tokens are enforced during manual appointment and succession.
During world generation, if all allowed castes have a POP_RATIO of 0, a unit of an allowed caste will still be generated to fill the position.

|-
| {{text anchor|ALLOWED_CREATURE}}
| CREATURE:CASTE

|-
| {{text anchor|APPOINTED_BY}}
| position
| This position can only be chosen for the task from the nobles screen, and is available only if there is an *argument* present. For example, the GENERAL is [APPOINTED_BY:MONARCH]. Contrast [ELECTED]. Being appointed by a MONARCH seems to handle a lot of worldgen stuff, and interferes with fort mode titles. Multiple entries are allowed. If you have neither an ELECTED-token nor a APPOINTED_BY-token, the holder may always be changed (like the expedition leader).
''Read more: [[Advanced_Entity_Position_Mechanics#Appointment]]''

|-
| {{text anchor|BRAG_ON_KILL}}
|
| A creature that kills a member of this position will be sure to talk about it a lot.

|-
| {{text anchor|CHAT_WORTHY}}
|
| In adventure mode, when referencing locations, an NPC may mention this position holder living there or having done some deed there; it also means that the position exists in world-gen, rather than being created only at the end of world-gen.

|-
| {{text anchor|COLOR}}
| [[Color]]
| Creatures of this position will have this [[Color]], instead of their profession color, e.g. [COLOR:5:0:1]. It is also applied to the name of the citizen in the units-screen.

|-
| {{text anchor|COMMANDER}}
| position:ALL
| This position will act as a commander of the specified position{{verify}}. E.g. GENERAL is [COMMANDER:LIEUTENANT:ALL]. Unknown if values other than ALL work. Multiple entries are allowed.
''Read more: [[Army]]''

|-
| {{text anchor|CONQUERED_SITE}}
|
| This position is a puppet ruler, left behind in a conquered site.

|-
| {{text anchor|DEMAND_MAX}}
| number (0-100)
| How many demands the position can make of the population at one time.

|-
| {{text anchor|DESCRIPTION}}
| string. Readable up to 470 characters in the nobles' screen.
| description of this position in the nobles screen.

|-
| {{text anchor|DETERMINES_COIN_DESIGN}}
|
| The site's (or civ's) minted [[coin]]s, if any, will have images that reflect the personality of this position holder.

|-
| {{text anchor|DO_NOT_CULL}}
|
| The position won't be culled from Legends as "unimportant" during world generation.

|-
| {{text anchor|DUTY_BOUND}}
|
| Members of this position will never agree to 'join' your character during adventure mode. They also don't settle anywhere else but in the capital, and will not [[immigration|emigrate]] from their site. If they are not DUTY_BOUND, they will live anywhere as they like.

|-
| {{text anchor|ELECTED}}
|
| The population will periodically select the most skill-eligible creature to fill this position for site-level positions at the player's fort. For responsibilities or positions that use more than one skill, no skill takes priority in electing a creature: an accomplished comedian is more qualified for the TRADE responsibility than a skilled appraiser. A creature may be elected to multiple positions at the same time. Contrast [APPOINTED_BY].
''More info: [[Elections]]''
''Read more: [[Advanced_Entity_Position_Mechanics#Elections]]''

|-
| {{text anchor|EXECUTION_SKILL}}
| weapon skill
| A mandatory sub-tag of [RESPONSIBILITY:EXECUTIONS]. Determines the weapon chosen by the executioner for their work.

|-
| {{text anchor|EXPORTED_IN_LEGENDS}}
|
| The various members who have filled this role will be listed in the civilisation's history.

|-
| {{text anchor|FLASHES}}
|
| The creature holding this position will visibly flash, like legendary citizens. Represents a properly noble station by default.

|-
| {{text anchor|GENDER}}
| male/female
| The position can only be held by the specified gender. Currently bugged {{bug|2714}}

|-
| {{text anchor|KILL_QUEST}}
|
| The position can assign quests to adventurers.

|-
| {{text anchor|LAND_HOLDER}}
| importance tier (1-10)
| This is an alternative to SITE, allowing positions to be created at civ-level 'as needed' for all sites that meet the requirements to have them, which are the values set in [[Difficulty#Land_holder|land holder difficulty]] [[settings]]. The character is tied permanently to a particular site, but also operates at the civ-level.
''Read more: [[Advanced_Entity_Position_Mechanics#land holders]]''

|-
| {{text anchor|LAND_NAME}}
| string. Readable up to 21 characters in the nobles' screen.
| The name the area takes on when under the control of a LAND_HOLDER. E.g. for the DUKE, [LAND_NAME:a duchy]. If the position is not a [[LAND_HOLDER]], the land_name is still displayed left of the position in the nobles menu.

|-
| {{text anchor|MANDATE_MAX}}
| number (0-100)
| The maximum number of mandates the position can make at once.

|-
| {{text anchor|MENIAL_WORK_EXEMPTION}}
|
| The position holder cannot be assigned labors. It only works for [SITE]-positions.

|-
| {{text anchor|MENIAL_WORK_EXEMPTION_SPOUSE}}
|
| The spouse of the position holder doesn't have to work, either - see above.
|-
| {{text anchor|MILITARY_SCREEN_ONLY}}
|
| This position cannot be appointed from the nobles screen. Intended for militia captains and other squad leaders to reduce clutter. Currently nonfunctional{{bug|8965}}

|-
| {{text anchor|NAME}}
| singular:plural. Readable up to 21 characters in the nobles' screen and up to 30 in the unit list.
| The name of the position.

|-
| {{text anchor|NAME_MALE}}
| singular:plural. Readable up to 21 characters in the nobles' screen and up to 30 in the unit list.
| If the creature holding the position is male, this is the position's name. E.g. for MONARCH, [NAME_MALE:king:kings]

|-
| {{text anchor|NAME_FEMALE}}
| singular:plural. Readable up to 21 characters in the nobles' screen and up to 30 in the unit list.
| If the creature holding the position is female, this is the position's name. E.g. for MONARCH, [NAME_FEMALE:queen:queens]

|-
| {{text anchor|NUMBER}}
|
* number/AS_NEEDED
| How many of the position there should be. If the [SITE] token exists, this is per site, otherwise this is per civilisation. AS_NEEDED applies mainly to positions involved with the military command chain; this is used to allow armies to expand to whatever size they need to be. Other non-military positions like the land_holders or the [[messenger]] with NUMBER:AS_NEEDED will also be appointed.
The problem with [[Lieutenant]]s and [[Captain]]s not being created, is their AS_NEEDED number. They are only then created when they're needed, and that has some pretty unusual conditions. When a fixed number is used, they are appointed with the creation of the civ.
If the NUMBER is set at a fixed value higher than 1, the position is always filled up full. If the position is available on embark, it is completely filled up with only the first dwarf.

|-
| {{text anchor|PRECEDENCE}}
| number (0-30000)/NONE
| How important the position is in society; a lower number is more important and displayed higher in the Nobles menu. For MONARCH it's 1, for MILITIA_CAPTAIN it's 200. The game marks the first non-[SITE] position with [PRECEDENCE:1] as the ruler, for both embark screen and mountainhome purposes. When it is empty, [REPLACED_BY] another position, or not yet created because of [REQUIRES_POPULATION], the screen just says 'None' as the holders' name. Landholders can become the ruler, if they are the first defined position with precedence of 1. civ-position can also be created without precedence. Positions may have the same precedence and will be appointed, although the effect is unknown. Precedence has no effect on who's doing the job, if both positions have the same responsibilities.

|-
| {{text anchor|PUNISHMENT_EXEMPTION}}
|
| The position holder will not be held accountable for his or her crimes. Currently nonfunctional.{{bug|4589}}{{verify|seems to prevent punishment when they are convicted of actual crime}}

|-
| {{text anchor|QUEST_GIVER}}
|
| The position holder can give quests in Adventure mode. Functionality in 0.31.13 and later is uncertain.

|-
| {{text anchor|REJECTED_CLASS}}
| CREATURE_CLASS Token
| Creatures of the specified class cannot be appointed to this position. Multiple entries are allowed

|-
| {{text anchor|REJECTED_CREATURE}}
| CREATURE:CASTE
| Restricts position holders by CREATURE type. Multiple entries are allowed. It doesn't seem to work in world-gen. When checking Legends mode, units are seen assigned this position regardless of their creature-type or caste. It does work in Fortress mode.

|-
| {{text anchor|REPLACED_BY}}
| position
| This position is absorbed by another down the line. For example, expedition leader is [REPLACED_BY:MAYOR]. Only a single entry is allowed.

|-
| {{text anchor|REQUIRED_BEDROOM}}
| number (0-1000000)
| The position holder requires a bedroom with at least this value.

|-
| {{text anchor|REQUIRED_BOXES}}
| number (0-100)
| The position holder requires at least this many boxes.

|-
| {{text anchor|REQUIRED_CABINETS}}
| number (0-100)
| The position holder requires at least this many cabinets.

|-
| {{text anchor|REQUIRED_DINING}}
| number (0-1000000)
| The position holder requires a dining room with at least this value.

|-
| {{text anchor|REQUIRED_OFFICE}}
| number (0-1000000)
| The position holder requires an office with at least this value.

|-
| {{text anchor|REQUIRED_RACKS}}
| number (0-100)
| The position holder requires at least this many weapon racks.

|-
| {{text anchor|REQUIRED_STANDS}}
| number (0-100)
| The position holder requires at least this many armour stands.

|-
| {{text anchor|REQUIRED_TOMB}}
| number (0-1000000)
| The position holder requires a tomb with at least this value.

|-
| {{text anchor|REQUIRES_MARKET}}
|
| Does not have anything directly to do with [[trade depot|trade depots]]. It means that in minor sites (such as hillocks) the position will not appear, while in major sites (such as dwarf fortresses) it will. Depending on its economical position in the region, a [[hamlet]] may build a market and develop into a [[Town]] eventually. That is when this position becomes available.

|-
| {{text anchor|REQUIRES_POPULATION}}
| number
| The position requires the population to be at least this number before it becomes available, or before the position holder will move in.

|-
| {{text anchor|RESPONSIBILITY}}
| responsibility
| The position holder does a thing. See the table below for suitable arguments. A position does not need to have a responsibility.

|-
| {{text anchor|RULES_FROM_LOCATION}}
|
| If there is a special location set aside for rulers, such as a human castle/mead hall, the position holder will always be found at that particular location. Does nothing for dwarven nobles, because at present, dwarves have no such special locations.

|-
| {{text anchor|SITE}}
|
| Every site government will have the defined number of this position instead of the whole civilization; provided that other criteria (if any) are met. Unless LAND_HOLDER is present instead, the defined number of the position will be created only for the civilization as a whole.

|-
| {{text anchor|SLEEP_PRETENSION}}
|
| The position holder will get upset if someone with a higher PRECEDENCE holds quarters with a greater value than their own.

|-
| {{text anchor|SPECIAL_BURIAL}}
|
| The civilization will inter the corpse of the position holder in a special grave, either in catacombs or in monuments. If that grave is disturbed, the position holder can return as a [[mummy]]. {{verify}}

|-
| {{text anchor|SPOUSE}}
| singular:plural. Readable up to 30 characters in the unit list.
| The name of the position holder's spouse.

|-
| {{text anchor|SPOUSE_FEMALE}}
| singular:plural. Readable up to 30 characters in the unit list.
| If the spouse of the creature holding the position is female, this is the spouse's position name.

|-
| {{text anchor|SPOUSE_MALE}}
| singular:plural. Readable up to 30 characters in the unit list.
| If the spouse of the creature holding the position is male, this is the spouse's position name.

|-
| {{text anchor|SQUAD}}
| number:singular:plural
| The position holder is authorized to form a military squad, led by themselves using the [[leader]] and [[military tactics]] skills. The number denotes the maximum headcount. The noun used to describe the subordinates (e.g. royal guard) is used in adventure mode for the adventurer. This token is used together with [RESPONSIBILITY:LAW_ENFORCEMENT] for giving [[quest]]s to adventurers as [[Hearthperson|hearthpeople]]. Further details: [[Advanced_entity_position_mechanics#Military]]

|-
| {{text anchor|SUCCESSION}}
|
* BY_HEIR / BY_POSITION:position
| How a new position holder is chosen. A single position can have multiple BY_POSITION tokens. See [[Noble]] for more information on how succession is handled in the game.
The SUCCESSION-Tag is also considered when a new positions opens up, for example when a required population number is reached. If a valid successor is available, they will be the one taking that position initially, without appointment or election.

|}

== Responsibilities ==
{| {{prettytable}}
|- bgcolor="#dddddd"
! Argument
! Description

|-
| {{text anchor|ACCOUNTING}}
| Found on [[bookkeeper]]. Position will use [[record keeper]] skill to keep track of stocks.

|-
| {{text anchor|ADVISE_LEADERS}}
|

|-
| {{text anchor|ATTACK_ENEMIES}}
| Found on elven [[ranger captain]] and human warrior. Effect unknown.{{verify}}

|-
| {{text anchor|BUILD_MORALE}}
| Found on [[champion]]. Citizens get a special thought for "talking to a pillar of society" when speaking to this noble.

|-
| {{text anchor|BUILDING_SAFETY}}
|

|-
| {{text anchor|COLLECT_TAXES}}
| Currently unused - was originally assigned to the tax collector.

|-
| {{text anchor|CONSTRUCTION_PERMITS}}
|

|-
| {{text anchor|DELIVER_MESSAGES}}
| Found on [[messenger]]. Position travels to other sites and uses [[social skill]]s.
|

|-
| {{text anchor|EQUIPMENT_MANIFESTS}}
| Currently unused - was originally assigned to the arsenal dwarf.

|-
| {{text anchor|ESCORT_TAX_COLLECTOR}}
| Currently unused - was originally assigned to the Royal Guards (squad members beneath the Hammerer).

|-
| {{text anchor|ESPIONAGE}}
| Found on [[dungeon master]] and the [[Elf|elven]] [[General|princess]] and uses the [[schemer]] skill.

|-
| {{text anchor|ESTABLISH_COLONY_TRADE_AGREEMENTS}}
| Found on [[outpost liaison]]. Position travels with the caravan and uses [[social skill]]s to make trade agreements with any settlements that it visits, provided they are domestic, report the news and promote {{token|LAND_HOLDER|e}} positions. Also reports recent news. Presumably has no effect at site level. Crucially, it does not visit foreign settlements, but the civ-level TRADE position does the exact same thing in its position. They arrive the same time as the caravan arrives, and this can thus be modded by setting {{token|ACTIVE_SEASON|e}}

|-
| {{text anchor|EXECUTIONS}}
| Found on [[hammerer]]. Position executes death penalty judgements with a weapon of the appropriate skill. Cannot be combined with LAW_ENFORCEMENT, resulting in the "Invalid Officer"-error.

|-
| {{text anchor|FIRE_SAFETY}}
|

|-
| {{text anchor|FOOD_SUPPLY}}
|

|-
| {{text anchor|HEALTH_MANAGEMENT}}
| Found on [[chief medical dwarf]]. Position will use [[diagnostician]] skill to evaluate [[wounds]] and schedule [[Health care|treatment]], reported in each citizen's Health tab.

|-
| {{text anchor|JUDGE}}
|

|-
| {{text anchor|LAW_ENFORCEMENT}}
| Found on [[sheriff]]/[[captain of the guard]]. Position and its subordinates are in charge of punishing criminals. A {{token|SITE|position}} position holding this responsibility plus the {{token|SQUAD|position}} token (or allowing the entity to have a {{token|SITE_VARIABLE_POSITIONS|e}} with this responsibility) is required for an adventurer from a given civilization to start as a [[hearthperson]], [[Captain of the guard|fortress guard]], etc. Cannot be combined with EXECUTIONS, resulting in the "Invalid Officer"-error.

|-
| {{text anchor|LAW_MAKING}}
| Found on [[monarch]]s and [[:Category:Aristocrats|nobles]]. Will be referred to as the leader of the site in adventure mode and they may designate the site as being the capital city for civ-level positions. This position is in charge of creating procedural positions, corresponding to either {{token|VARIABLE_POSITIONS|e}} or {{token|SITE_VARIABLE_POSITIONS|e}}. Position-holders that have attained [[immortality]] may issue oppressive edicts to protect themselves against suspicion.

|-
| {{text anchor|MAINTAIN_BRIDGES}}
|

|-
| {{text anchor|MAINTAIN_ROADS}}
|

|-
| {{text anchor|MAINTAIN_SEWERS}}
|

|-
| {{text anchor|MAINTAIN_TUNNELS}}
|

|-
| {{text anchor|MAKE_INTRODUCTIONS}}
| Position will make a 'social call' to an established foreign settlement, complimenting or insulting them depending on relations and reporting the news.

|-
| {{text anchor|MAKE_PEACE_AGREEMENTS}}
| Found on diplomat. Position negotiates peace treaties in order to end wars.

|-
| {{text anchor|MAKE_TOPIC_AGREEMENTS}}
| Found on [[diplomat]]. Position negotiates special agreements, such as tree cutting quotas. Used when elevating a settlement in the {{token|LAND_HOLDER|position}} chain up from level 1.

|-
| {{text anchor|MANAGE_ANIMALS}}
| Found on [[dungeon master]].

|-
| {{text anchor|MANAGE_LEADER_HOUSEHOLD_CLEANLINESS}}
|

|-
| {{text anchor|MANAGE_LEADER_HOUSEHOLD_DRINKS}}
|

|-
| {{text anchor|MANAGE_LEADER_HOUSEHOLD_FOOD}}
|

|-
| {{text anchor|MANAGE_PRODUCTION}}
| Found on [[manager]]. Position enables the use of workshop profiles and uses the [[organizer]] skill to process work orders entered in the job manager after the fortress population reaches 20.

|-
| {{text anchor|MEET_WORKERS}}
| Found on [[expedition leader]]/[[mayor]]. Position uses the various [[social skill]]s to hold meetings with unhappy citizens and try to pacify them with happy thoughts. In adventure mode, [SITE] positions with this responsibility handle petitions to make the player a performer for the local government.

|-
| {{text anchor|MILITARY_GOALS}}
| Found on [[monarch]]/[[:Category:Aristocrats|landholder]]/[[:Category:Elected Nobles|leaders]]. Character is in charge of going to war and making peace for the government they work for. Without a position with this responsibility at civ level the civilization will not be able to make peace and its sites will wage war on each other constantly, and as a result, all viable civilizations must have one leader with this tag at civ level. This appears not to be a problem for [[kobold]]s, presumably due to the {{token|SKULKING|e}}. If no position has this responsibility in fortress mode, players are unable to start [[missions]].

|-
| {{text anchor|MILITARY_STRATEGY}}
| Found on [[general]]/[[militia commander]]. Means that they will command the armies of their site or civilization. Issues the orders for the teams conducting raids or other operations away from the fortress. During worldgen, position will go on expeditions to tame exotic creatures. Counterintuitively not by the TAME_EXOTICS-position. The destinations of these expeditions are determined by the entities USE_(...)_ANIMALS-tokens.

|-
| {{text anchor|OVERSEE_LEADER_HOUSEHOLD}}
|

|-
| {{text anchor|PATROL_TERRITORY}}
| Found on elven ranger captain. Effect unknown.{{verify}}

|-
| {{text anchor|PREPARE_LEADER_MEALS}}
|

|-
| {{text anchor|RECEIVE_DIPLOMATS}}
| Found on [[monarch]]/[[:Category:Aristocrats|landholder]]/[[:Category:Elected Nobles|leaders]]. Position uses the various social skills to hold meetings with incoming diplomats and liaisons.

|-
| {{text anchor|RELIGION}}
| Found on elven [[druid]] and uses [[social skill]]s. Position informs you about worship cults{{verify}}

|-
| {{text anchor|SORT_AMMUNITION}}
| Currently unused - was originally assigned to the arsenal dwarf.

|-
| {{text anchor|TAME_EXOTICS}}
| Position will tame animals with the {{token|PET_EXOTIC}} token. Currently unused - was originally assigned to the dungeon master. Expeditions to tame exotic creatures will be done by the MILITARY_STRATEGY-position

|-
| {{text anchor|TRADE}}
| Found on [[broker]]. Position will use Appraisal skill to display value estimates and the various Social skills to trade at the depot. When applied to other civilizations, this position will arrive with the caravan to make trade agreements (like the Human Guild Representative from older versions) and behaves otherwise like the civ's own ESTABLISH_COLONY_TRADE_AGREEMENTS position holder. They arrive the same time as the caravan arrive and this can thus be modded by setting {{token|ACTIVE_SEASON|e}}

|-
| {{text anchor|UPGRADE_SQUAD_EQUIPMENT}}
| Currently unused - was originally assigned to the arsenal dwarf.

|}

== Related tokens ==
The following two ENTITY tokens are not actually position tokens, but bear mentioning on this page because they can modify the way that a civilization's positions behave:

{| {{prettytable}}
|- bgcolor="#dddddd"
! Token
! Arguments
! Description

|-
| {{text anchor|VARIABLE_POSITIONS}}
| Position responsibility or ALL
| Allows a responsibility to be taken up by a dynamically generated position (such as Law-maker).

|}

== Why won't my positions appear? ==
The way DF determines what positions will actually ''appear'' in your fortress is somewhat counter-intuitive and fairly limiting. This guide should help you understand what you can do to actually get your positions working properly.

There are five tokens governing which positions appear in your fortress - LAND_HOLDER, REQUIRES_POPULATION, APPOINTED_BY, ELECTED, and REPLACED_BY. The first two determine when your fortress is eligible for a new position, the next two determine how a new position for which your fortress is eligible can be added, and the fifth allows you to clear up obsolete positions. Unfortunately, they also interact in some strange ways that makes creating interesting position structures difficult.

When you start a new fortress, DF compiles a list of your initial positions. To do this, it looks at the requirements for each position - any position whose only requirement is less than seven dwarves (either because they have no requirement tokens, or because their only requirement tokens are [REQUIRES_POPULATION: =< 7] or [LAND_HOLDER:some trigger whose only requirement is some number of dwarves equal to or less than 7]). Most importantly, ''any'' position whose only requirement is a LAND_HOLDER requirement, regardless of what the trigger for that requirement is, will be added if another eligible starting position is REPLACED_BY it. '''A non-LAND_HOLDER position that is REPLACED_BY a LAND_HOLDER position will never appear.''' With this list compiled, the game culls all positions that are REPLACED_BY another eligible position, and then culls all positions that have the APPOINTED_BY token. '''You may not embark with any appointed positions.''' Any remaining positions are then filled by a dwarf chosen at random.

'''Positions do not automatically appear when you reach their requirements.''' For example, if you remove the ELECTED token from the Mayor, then the Mayor will never appear, even once you reach their required number of dwarves. '''For a position that does not appear at embark to appear in your fortress, it must be APPOINTED_BY another position or ELECTED.'''

Naturally, this is more complicated than it looks. '''APPOINTED_BY positions must be appointed by another position already in your fortress, or a civ-level position. Only LAND_HOLDER positions may be appointed by civ-level positions.''' LAND_HOLDER positions that are APPOINTED_BY civ-level positions are inherently tied to civ-level tokens with the ESTABLISH_COLONY_TRADE_AGREEMENTS responsibility. If a fortress meets the LAND_HOLDER_TRIGGER for a new LAND_HOLDER tier when a caravan leaves, then the next time the outpost liaison or equivalent arrives, they will offer to make you an official colony, which will allow you to select all positions for that LAND_HOLDER level. '''Each time they appear, the outpost liaison will only promote your fortress one tier up the LAND_HOLDER track.''' The biggest problem with this system is that you may set your LAND_HOLDER_TRIGGERS such that you are eligible for the first tier of LAND_HOLDER positions at embark. '''If you are eligible for the first tier of LAND_HOLDER positions at embark, then all first-tier positions will appear twice - once at embark, and again when the outpost liaison comes to appoint you to the first tier.'''

If civ-positions are neither APPOINTED_BY nor ELECTED, they still will be filled.

Read more: [[Advanced_Entity_Position_Mechanics]]

{{Category|Modding}}
{{Category|Tokens}}
[[ru:Position token]]

Intrigue

2026-03-05T13:34:24Z

Joostheger:

{{Quality|Superior}}
{{av}}

The central feature of the 'villains release', '''intrigue''' is a collection of mechanics and tools that enable historical figures to enact [[villain]]ous plots, ensuring a constant stream of [[Fun]] for players. As of .47 interaction with this feature is still somewhat unfinished, with the January 2020 devlog indicating missing elements.

== World gen and world activation ==
The main mechanic works through agreements: [[historical figure]]s reach out to one another and use a variety of tactics (persuasion, blackmail, bribes) to reach an agreement for a variety of things like funding, assassination, stealing. The historical figures keep a list of plots that they want to enact, and also keep track of how to deal with a variety of other figures. They make use of the [[schemer]]-skill.

You can export a villainous network from the historical figures list in legends mode, as shown in the image below:

[[File:Df_legends_villainous_network.png|center|Image showing a villainous network as exported from legends mode. Purple is the location of the leader, red the location of the members, and yellow, the location of corrupt officials.|thumb|800px]]

The civilizations in world generation also have some basic counter-intelligence abilities, and though it's abstract like the rest of world generation, the spy masters and law enforcement position holders, like the villains, have to work in a more-or-less fair fashion to earn their victories. The game keeps track of the evidence they've collected from witnesses, interrogation and surveillance, and this gives them leads on further steps to take, in terms of who to surveil and who to interrogate.

== Fortress mode ==
Members of these villainous networks, known as organisations, will occasionally visit your fortress with the intent of corrupting your residents to take part in plots. Unless you successfully interrogate them through the [[Justice]] screen, there will be no indication that the visitor has nefarious intentions; they may also use one or more pseudonyms, so any names of members acquired from previous interrogations may not be enough to identify them.

Note that trying to interrogate a merchant can cause a wagon to fall apart.

Corruption of residents is based on the initiator and recipient's social skills, much like interrogation, and if the corruption is successful, the recipient will become a part of the organisation, taking their part in whatever plot the organisation intends to enact within your fort.

An interrogator can interview somebody that corrupted them. However, no crime report is generated, nor is the organization added to the counterintelligence screen.

When interrogating a performer you granted long-term residence to as part of a [[Performer#Performance_Troupes|troupe]], they can "confess" this fact. This will show up as "A plot" in the Plots screen, despite it not being a plot at all.

==== Potential plots ====
The following is an incomplete list of potential plots an organisation may enact:
* Infiltrate a [[site]]
* Corrupt a [[noble]] in a site
* Steal an object

== Adventure mode ==
[[File:Adventurer_intrigue_tab.png|thumb|300px|Image showing a villainous network in adventure mode. This network consists of the master, a member (who is the master's childhood friend, incidentally), and two assets, which are position-holders corrupted into providing funds to the network.]]

Intrigue in [[adventurer mode]] is mostly interacted with through the investigation and interrogation menus. There are two major investigatory tactics: Persuasion and Intimidation. Adventurers who wish to investigate benefit from the [[judge of intent]] skill as well. Currently, only asking for schemes will result in proper information appearing in the quest log.

You can interrogate criminals after killing them, at least if they're intelligent undead.

=== Persuasion ===
Persuasion mainly uses the persuade [[skill]]. Complementary to that are the flatterer (for flattering), comedian (for making jokes) and pacifier (for calming down) skills. You will want to make jokes and flatter an NPC to get them into a positive mood. Use pacifier skill to reduce impatience down to patient. After this, investigate using the persuasion tactic.

=== Intimidation ===
Intimidation mainly uses the intimidate [[skill]]. To make intimidation more effective, you can fight with nearby NPCs, or the particular NPC in question. To avoid killing the NPC, make sure that you stay within the [[Level of conflict#Brawl|brawl]] escalation level - the NPC will rapidly become afraid of you. After this, investigate using the intimidation tactic.

== See also ==
*[[Villain]]
*[[Agent]]

{{category|Adventurer mode}}
{{category|Fortress mode}}
{{category|Game mechanics}}
[[ru:Intrigue]]

Schemer

2026-03-05T13:33:03Z

Joostheger: added info from de dev logs

{{migrated article}}
{{Quality|Tattered}}
{{av}}
{{Skill
| color = 3:0
| skill = Schemer
| profession = Unknown
| job name = Unknown
| tasks = Unknown
| attributes =
* Unknown
}}
{{stub}}

'''Schemer''' is a [[skill]] presumably used as part of the [[intrigue]] system. It represents a character’s ability to manipulate, detect, and counter covert political activity.

The [[dungeon master]] [[noble]] favors this skill, though its practical use in fortresses is not fully understood. Migrants may arrive with experience in scheming, making them interesting candidates for the position. However, some reports suggest that hostile agents can also infiltrate settlements with unusually high schemer skill.

It appears to be possible to slowly train the skill by [[Justice#Interrogation|interrogating]] dwarves.

In the wider world, skilled schemers may conduct complex intrigue operations. These include framing others for crimes, corruptly arranging imprisonment, sabotaging the reputation of individuals or organizations, or undermining diplomatic relations between civilizations. Such actions often rely on manipulating leaders, advisors, or law enforcement, and may involve exploiting the legal system so the victim receives a legitimate punishment.

Scheming also has a defensive role. Skilled practitioners can recognize and counter attempts to influence leaders or officials through intrigue, helping to protect positions of power from manipulation.

Within a fortress, the skill can be trained slowly through interrogations, though the full range of fortress-related uses remains unclear.

{{Skills}}

Personality goal

2026-02-24T09:34:30Z

Joostheger:

{{Quality|Superior}}
{{av}}
[[File:personality_v50_preview.png|thumb|262px|right|Randomly generated personality of a [[miner]].]]

Some creatures dream of accomplishing certain '''goals''' in their life, and these goals can, presumably, affect their behavior. If a creature has such goals, they will be listed in the "Values" sub-tab of the "Personality" tab of their character sheet. Dwarves will receive a happy thought upon completion of their goals, receiving the notation of "and this dream was realized" in the personality description following their original goals. Goals would apparently ''not'' currently be limited to one per creature, but for some sort of oversight: [http://www.bay12forums.com/smf/index.php?topic=169696.msg8083871#msg8083871]. A creature needs the ability to [[Learning|learn]] in order to have a goal in life.

According to Toady, syndromes can cause creatures to re-evaluate their goals in worldgen; the boost to anxiety and distrust given to necromancers makes it more likely for them to develop the goal of ruling the world. [http://www.bay12forums.com/smf/index.php?topic=169696.msg8275328#msg8275328]

{| class="wikitable anchortable"
! Token
! Description
! Gameplay effects
|-
! style="background-color:#EDCF10" | {{text anchor|START_A_FAMILY}}
| dreams of raising a family
| Dream realized upon giving birth/fathering an infant.
|-
! style="background-color:#FFE111" | {{text anchor|RULE_THE_WORLD}}
| dreams of ruling the world
|-
! style="background-color:#EDCF10" | {{text anchor|CREATE_A_GREAT_WORK_OF_ART}}
| dreams of creating a great work of art
| Dream realized upon creation of Artifact or Masterpiece.
|-
! style="background-color:#FFE111" | {{text anchor|CRAFT_A_MASTERWORK}}
| dreams of crafting a masterwork someday
| Dream realized upon creation of Artifact or Masterpiece.
|-
! style="background-color:#EDCF10" | {{text anchor|BRING_PEACE_TO_THE_WORLD}}
| dreams of bringing lasting peace to the world
|-
! style="background-color:#FFE111" | {{text anchor|BECOME_A_LEGENDARY_WARRIOR}}
| dreams of becoming a legendary warrior
|-
! style="background-color:#EDCF10" | {{text anchor|MASTER_A_SKILL}}
| dreams of mastering a skill
| Dream realized upon reaching Legendary skill status.
|-
! style="background-color:#FFE111" | {{text anchor|FALL_IN_LOVE}}
| dreams of falling in love
|-
! style="background-color:#EDCF10" | {{text anchor|SEE_THE_GREAT_NATURAL_SITES}}
| dreams of seeing the great natural places of the world
|-
! style="background-color:#FFE111" | {{text anchor|IMMORTALITY}}
| has become obsessed with his/her own [[Immortality|mortality]]
| Leads to [[necromancer|necromancy]], which renders the seeker immune to death by old age. Creatures like [[goblin]]s and [[elf|elves]], who are immortal from the start, cannot have this goal.
Judging from the string dump, these personality facets may lead to choosing this goal:
* High Pride (being too proud to give in to death)
* High Vanity (being too vain to give in to death)
* High Ambition (having ambitions for which death was only a small obstacle)
* High Envy propensity (due to envy of those that live on)
* High Anxiety propensity (due to panic about what happens after death)
* Low Bravery (due to fear of death)
|-
! style="background-color:#EDCF10" | {{text anchor|MAKE_A_GREAT_DISCOVERY}}
| dreams of making a great discovery
| Dream realized upon discovering a [[topic]].
|-
! style="background-color:#FFE111" | {{text anchor|ATTAIN_RANK_IN_SOCIETY}}
| dreams of attaining rank in society
| Dream realized upon becoming a baron (and possibly other noble positions).
|-
! style="background-color:#EDCF10" | {{text anchor|BATHE_WORLD_IN_CHAOS}}
|dreams of bathing the world in chaos
|-
! style="background-color:#FFE111" | {{text anchor|STAY_ALIVE}}
|
|-
! style="background-color:#EDCF10" | {{text anchor|MAINTAIN_ENTITY_STATUS}}
|
|}

{{Category|Dwarves}}
{{Category|Modding}}
{{Category|Tokens}}

Talk:Variable positions

2026-02-17T21:11:16Z

Joostheger:

Variable positions

2026-02-17T21:05:48Z

Joostheger: removed as requested.

{{Quality|Fine}}
{{Modding}}
{{stub}}
This page documents the variable positions that entities create when neccesary. This is - in vanilla - the case for [[human]] and [[goblin]] [[Civilization|civilizations]], but also for merchants' companies, guilds, mercenary groups, [[Religion|religious groups]] and [[Criminal|criminal]]s.

= Introduction =
Initially none of the positions marked as variable do exist for an entity. The positions will only exist for a given entity, if they are either created during world-gen, world activities(?) or by memory hacking or scripting (ie. with Lua). Ie. in vanilla all human civilizations have at the beginning of the world-generation no positions at all, neither on the site nor civ level, as all positions of the vanilla human civs are marked as variable (variable positions: all). When a variable (civ level) position is created, the position is only created for that civilization (entity) and not for any other entities of the same type. Ie. the creation of a law-giver for one human civ does not create law-givers for other human civs.

Also presumably all site-level positions for each entity are created on a per site basis, meaning the creation of a site ruler for one site (of a civ) does not also create the site ruler positions for any other site (of that civ).

The existence of a variable position does not mean that the position will also be filled by a historical figure. But during world-gen the creation of a position will usually be followed up with the position being filled. Ie. the human historical figure who forced the creation of a law-giver position, will usually become the first law-giver.

For the succession rules of a variable position (after the position has been initially filled by a historical figure), presumably, the same rules as for non-variable positions apply.

(Disclaimer: The following only applies during world-gen and normal world activities. Scripting and memory hacking can circumvent the normal limitations, but with currently unknown results).

For civ level entities, if the law-giving position is a variable position, the law-giving position does not (seem to) have any further requirements to be created (ie. no other position being already created). Ie. this position can be created by force (or popular support etc.) by any historical figure of that civ. But for all other variable (civ-level) positions the law-giving position must exist as usually the historical figure, who is the law-giver, does create the other variable positions (for various reason).

Something similar is probably the case for site level positions. Ie. if the ruler of a site is a variable position, that position needs to be created, before any other site-level variable positions can be created. And the site ruler can afterwards create other variable positions for that site. It is not yet clear if a site level ruling position can be created before a civ level ruling (law-giving) position is created (or exists). This also means that it should be possible, via memory-hacking or scripting, to create (and fill) the variable site level positions (for a player site), at least after the civ level law-giving position has been created (and the law-giving position has been filled), so that a human player site gets the maximum possible human site level positions (with the normal appointment rules for the succession/reappointment of the positions), without having to edit the raw files (as outlined in the human civ page), prior to creating a world, to make the variable positions of human civilisations to "static" ones.

Presumably for guilds (Merchant Guild and others), mercenary groups, religious orders (and criminals) also a "leader" position needs to be created by a historical figure, before other variable positions for that entity can be created.

== General Info ==
So far, no restrictions on allowed_class or allowed_creature have been found and also the rejected_creature and rejected_class entries are always empty. Squad_size is 0, except when a variable position (in the following sections) explictly states otherwise (ie. squad size for CUSTOM_BANDIT_LEADER, CUSTOM_LAW_MAKER and CUSTOM_LAW_MAKER_2 is 20). Also most other entries (of entity_position entry under "own") not mentioned in their section have standard values (ie. are empty). The best_appointment_precedence of all positions is 30001. Also the execution skill is always set to "-1" even for the CUSTOM_OFFICIAL_9, whose sole responsiblity is executions.

Also variable positions are usually only created (with the exception, if they replace another position), if the position will have at least one responsibility the already created (existing) positions for that entity does not have, regardless of whether there are any more prerequisites for a variable position to be created.

== Sources to process ==
See spoiler-sections of those posts.
* https://www.bay12forums.com/smf/index.php?topic=178697.msg8295235#msg8295235
* https://www.bay12forums.com/smf/index.php?topic=175434.msg8084095#msg8084095
* https://www.bay12forums.com/smf/index.php?topic=175434.msg8083631#msg8083631 (first answer)

= Civilizations =
If all positions of a civ are variable, then the CUSTOM_LAW_MAKER position needs to be created (in world-gen), before other positions (of the possible positions) can be created. After the creation (and filling) of the law-maker positions, the other variable positions (both CUSTOM_OFFICIALS_i and CUSTOM_MARKET_OFFICIALS_i, where i stands for a non-zero natural number) can be created in any order. These other positions are then always appointed by the law-maker of the civ. The law-maker position itself uses succession by heir.

In contrast to e.g the positions of the dwarven civilizations, where the site nobility positions (eg. baron, duke) do get added to the own position list (vector) of the civilization, the CUSTOM_LAW_MAKER (and CUSTOM_LAW_MAKER_2) positions (of a site government) are not added to the own position list (at least for civs with all variable positions). The "own" positions list (of the civ entity) only exclusively contains the variable positions of the civ, which are all created by the civ, and no positions which are the "ruler" of a site (even if the variable site position was appointed by the law maker of the civ). Also the "site" positions list is empty (or at least no entries were found so far).

The following table gives an overview over the different possible rulers of a human or goblin civilization.

{|class="sortable wikitable" style="text-align:center;"
|- style="background:#F2F2F2;"
!Position!!Name!!succession type!!Responsibilities!!Demands!!Mandates!!Precedence!!is diplomat!!human!!goblin

|-
!CUSTOM_LAW_MAKER
|master
|none
|law making, military goals, military strategy
|3
|2
|1
|no
|no
|yes

|-
!CUSTOM_LAW_MAKER
|master
|none
|law making, military goals,
|3
|2
|1
|yes
|no
|yes

|-
!CUSTOM_LAW_MAKER
|law-giver
|by heir
|law making, make peace agreements, military goals, military strategy
|3
|2
|1
|no
|yes
|no

|-
!CUSTOM_LAW_MAKER
|law-giver
|by heir
|law making, make peace agreements, military goals
|3
|2
|1
|yes
|yes
|no

|}

Note that the ruler (law-giver or master) is not a diplomat, if and only if the ruler has the military strategy responsibility. Also note that the master of a goblin civilization does not have peace agreements as a responsibility.

The following table gives an overview of the possible non-ruling civ-level positions:

{| class="sortable wikitable" style="text-align:center;"
|- style="background:#F2F2F2;"
!Position!!Name prefix!!Name5!!Responsibilities!!Demands!!Mandates!!Precedence!!Number!!Flags11!!Flags22!!Color!!human!!goblin

|-
!CUSTOM_OFFICIAL_1
|yes3
|"keeper of the seal" / chancellor
|receive diplomats, make introductions and make topic agreements; optional: espionage
|3
|2
|20
|1
|yes
|no
|(5,0,1)
|yes
|yes

|-
!CUSTOM_OFFICIAL_2
|yes3
|justiciar
|law enforcement, collect taxes
|3
|2
|60
|1
|yes
|no
|(5,0,1)
|yes
|no

|-
!CUSTOM_OFFICIAL_3
|yes
|treasurer
|trade, accounting
|2
|1
|70
|1
|yes
|no
|(5,0,1)
|yes
|no

|-
!CUSTOM_OFFICIAL_4
|yes
|advisor/counselor
|advise leaders
|2
|1
|55
|1
|yes
|no
|(5,0,1)
|yes
|yes

|-
!CUSTOM_OFFICIAL_5
|yes3
|chamberlain
|oversee leader household
|1
|0
|80
|1
|yes
|no
|(5,0,1)
|yes
|yes

|-
!CUSTOM_OFFICIAL_6
|no
|master of beasts
|tame exotics, manage animals
|1
|0
|90
|1
|yes
|no
|(5,0,1)
|yes
|yes

|-
!CUSTOM_OFFICIAL_7
|yes
|butler / cup-bearer
|manage leader household food and drinks
|0
|0
|300
|1
|yes
|no
|(5,0,1)
|yes
|no

|-
!CUSTOM_OFFICIAL_8
|yes
|doctor
|health management
|0
|0
|310
|1
|yes
|no
|(5,0,1)
|yes
|no

|-
!CUSTOM_OFFICIAL_9
|yes
|executioner
|executions
|0
|0
|320
|1
|yes
|no
|(5,0,1)
|yes
|yes

|-
!CUSTOM_OFFICIAL_10
|yes
|chef
|prepare leader meals
|0
|0
|330
|1
|yes
|no
|(5,0,1)
|yes
|no

|-
!CUSTOM_OFFICIAL_11
|yes
|housekeeper
|manage leader household cleanliness
|0
|0
|340
|1
|yes
|no
|(5,0,1)
|yes
|no

|-
!CUSTOM_MILITARY_STRATEGY
|no
|general/(field) marshal / constable
|military strategy
|3
|2
|50
|1
|yes
|yes
|(5,0,1)
|yes
|yes

|-
!CUSTOM_MILITARY_GOALS4
|no
|war leader
|military goals, optional: military strategy
|3
|2
|45
|1
|yes
|yes
|(5,0,1)
|no
|no
|}
: ''Note'':
:* 1) These are the standard official flags: duty_bound, has_responsibilities, do_not_cull, has_met_pop_req, color, menial_work_exemption, has_received_positions and has_met_market_req.
:* 2) These are the following additional flags: flashes, brag_on_kill, chat_worthy, kill_quest, account_exempt, punishment_exemption, quest_giver and special_burial.
:* 3): Name prefix can be empty.
:* 4) These would be the values for the CUSTOM_MILITARY_GOALS position, but on the civ-level that position is not created, as the military goals responsibility is already performed by the law-giver/master (and for the military strategy responsibility the CUSTOM_MILITARY_STRATEGY position is created instead). But a CUSTOM_MILITARY_GOALS position would be created, if the civ leader would not have the military goals responsibility. The CUSTOM_MILITARY_GOALS position is - in vanilla - only created for site governments and then only, if the site leader is the FORCED_ADMINISTRATOR.
:* 5): Name prefixes are: high, head, chief and royal.

In the above table the responsibility "espionage" of the CUSTOM_OFFICIAL_1 is optional. Only if the CUSTOM_OFFICIAL_1 is created with the "espionage" responsibility such officials can also be created for the site governments (as all other responsibility are already performed by the standard custom site ruler). Also, the columns "human" and "goblin" dictate whether human and/or goblin civilizations can have the positions.

= Site Governments =
If all positions of a civ (and with that of a site government) are variable, then a leader position for the site government needs to be created (in world-gen), before other positions (of the possible variable positions) can be created. The created position is usually the CUSTOM_LAW_MAKER, but other positions have been found, ie. CUSTOM_BANDIT_LEADER and FORCED_ADMINISTRATOR.

Note that human and goblin civilizations can also create further site positions, if the current site leader is the CUSTOM_BANDIT_LEADER (both) or FORCED_ADMINISTRATOR (only encountered/found in case of humans). All other races (eg. dwarves and elves) cannot.

Also a CUSTOM_LAW_MAKER can be created for a site government (of a human civilization) before a CUSTOM_LAW_MAKER for the civilization has been created.

Also note that not all site government entities need to be a child of a civilization entity, if they are not, then the CUSTOM_BANDIT_LEADER is used as a site-ruler (regardless of race, ie. even dwarven and the rare elven site government without connection to a civ will use the CUSTOM_BANDIT_LEADER as initial ruler/leader).

The following table gives an overview of the possible leader positions:

{| class="sortable wikitable" style="text-align:center;"
|- style="background:#F2F2F2;"
!Position!!Name!!Responsibilities!!squad8 size!!Demands!!Mandates!!Precedence!!goblin!!human!!elf!!dwarf!!flags!!appointment type

|-
!CUSTOM_BANDIT_LEADER1
|Boss, Captain, Chief, Chieftain, Commander, Leader, Master, Overlord, Ringleader or Warlord
|law making, law enforcement, receive diplomats, make introductions, make topic agreements, military strategy, military goals
|20
|2
|1
|55 or 10 (rare)
|yes
|yes
|yes
|yes
|standard bandit leader
|elected

|-
!FORCED_ADMINISTRATOR
|administrator
|law making, receive diplomats, meet workers, make topic agreements
|0
|3
|2
|100
|yes
|yes
|yes
|yes2
|forced admin
|none3

|-
!FORCED_ADMINISTRATOR4
|administrator
|law making, receive diplomats, meet workers, make topic agreements
|0
|3
|2
|65
|no
|no
|no
|yes
|dwarf forced admin
|none3

|-
!CUSTOM_LAW_MAKER5
|law-giver
|law making, make peace agreements, military goals; optional6: military strategy
|0
|3
|2
|1
|no
|yes
|no
|no
|civ law-giver
|by heir

|-
!CUSTOM_LAW_MAKER6
|lord
|law making, law enforcement, receive diplomats, make introductions, make peace agreements, make topic agreements, military strategy, military goals
|20
|3
|2
|1
|no
|yes
|no
|no
|standard leader
|by heir

|-
!CUSTOM_LAW_MAKER
|lord
|law making, law enforcement, receive diplomats, make introductions, make peace agreements, make topic agreements, military strategy, military goals
|20
|3
|2
|40
|yes
|yes
|no
|no
|standard leader
|by heir

|-
!CUSTOM_LAW_MAKER
|baron
|law making, law enforcement, receive diplomats, make introductions, make peace agreements, make topic agreements, military strategy, military goals
|20
|3
|2
|41
|no
|yes
|no
|no
|standard leader
|by heir; appointed by law-giver (civ)

|-
!CUSTOM_LAW_MAKER_27
|baron
|law making, law enforcement, receive diplomats, make introductions, make peace agreements, make topic agreements, military strategy, military goals
|20
|3
|2
|35
|no
|yes
|no
|no
|standard leader
|by heir; optional: appointed9

|}

: ''Notes'':
:* 1): Only leader position, if the entity (site-government) is not a child of a civilization, but can also appear, if the entity has a parent civ. Only site leader position of goblins, where other site positions will be created (both cases: with civ and without civ).
:* 2): 2 of the 53 forced administrator positions of dwarves (in a large 250 year histor world-gen world with many civs) used this forced administrator (rather than the one defined in the raws). No site official positions found for goblins so far, if the leader was a forced administrator.
:* 3): The position has no appointed_by defined, nor any form of succession by position or heir. And the position is also not elected. So how and if a forced admin gets refilled, in case of death of the previous position holder, is unclear.
:* 4): This is the forced administrator as defined in the (vanilla) dwarf raws.
:* 5): Was created once in a large 250 year history world-gen world with many civs. The parent civ did not have a law-maker position created. But this definition is not always used, if the law-maker position of the parent civ has not been created. Also the site-entity was the original owner/creator of the site.
:* 6): This position can get created for a newly formed site-entity, if a site-entity has created the law-maker position and afterwards the site-entity gets conquered by another entity (of the same civ) and at the time of conquest no law-giver was created (yet) for the civ.
:* 7: Can be created (and replaces the former site ruler), if the ruler (of a human site entity) was either a FORCED_ADMINISTRATOR or a CUSTOM_LAW_MAKER with the name "lord".
:* 8): If the squad size is greater than zero, then the squad members are called soldiers (CUSTOM_BANDIT_LEADER) or hearthpeople (otherwise).
:* 9): Always appointed by the law-giver of the civilization, if the previous site leader was a forced administrator. Otherwise the appointed_by (and appointed_by_civ) definition is either empty or set to the law-giver of the civ, eg. a CUSTOM_LAW_MAKER_2, which replaces a CUSTOM_LAW_MAKER, can be appointed (in which case appointed by the law-giver of the civ) or not be appointed at all.
:* "by heir" in the appointment type definition entry means, that the succession is by heir. If nothing else is mentioned in the table cell, then the position did get filled immediatly upon creation of the position and the first position holder was not appointed by the civ-leader, otherwise the first position holder was appointed by the civ-leader.
:* "standard bandit leader" entry in "flags" table cell means the same flags as the CUSTOM_BANDIT_LEADER of bandit groups are set.
:* "forced admin" entry in "flags" table cell: is_law_maker, duty_bound, has_responsibitities, flashes, brag_on_kill, chat_worthy, do_not_cull, kill_quest, is_leader, is_diplomat, exported_in_legends, determines_coin_design, account_exempt, color, rules_from_location, menial_work_exemption, sleep_pretesion, punishment_exemption, has_received_positions, quest_giver, special_burial.
:* "dwarf forced admin" entry in "flags" table cell: is_law_maker, duty_bound, has_responsibitities, flashes, brag_on_kill, chat_worthy, do_not_cull, kill_quest, is_leader, is_diplomat, exported_in_legends, determines_coin_design, account_exempt, color, menial_work_exemption, sleep_pretesion, punishment_exemption, has_received_positions, special_burial.
:* "standard leader" entry in "flags" table cell: is_law_maker, duty_bound, has_responsibilities, flashes, brag_on_kill, chat_worthy, do_not_cull, kill_quest, is_leader, exported_in_legends, determines_coin_design, account_exempt, color, rules_from_location, menial_work_exemption, punishment_exemption, has_received_positions, quest_giver, special_burial.
:* "civ law-giver" entry in "flags" table cell means that the flags of the CUSTOM_LAW_MAKER (civ level) are set, where the is_diplomat flag is only set, if (and only if) the law-giver does not have the military strategy responsibility. Also in this case the is_diplomat flag is only set, if the "law-giver" (of the site entity) does not have the military strategy responsibility.
:* Remark to forced administrator: The only differences between the forced administrator (only usable by the dwarves and defined in the raws) and the other forced administrator are, that the forced administrator of the dwarves is not a quest giver, does not rule from a location and has a different precedence.
:* The color of all leaders is the standard noble color (5,0,1), except for the forced administrators, who uses a different color entry (5,0,0).

If a leader does exist for a site entity, other variable positions can be created for that entity. In rare cases a variable official (or market official) position can even be created, if the requirements are not met (at least one of the flags has_met_pop_req and has_met_market_req is false for the position entry).

The following table gives an overview of the non-ruler variable positions of a site government.

{| class="sortable wikitable" style="text-align:center;"
|- style="background:#F2F2F2;"
!Position!!Name prefix1!!Name!!Name suffix2!!Responsibilities!!Demands!!Mandates!!Precedence!!Number!!Color!!human!!goblin!!add. flags3

|-
!CUSTOM_MARKET_OFFICIAL_1
|no
|sewer
|always
|maintain sewers
|0
|0
|500
|1
|(5,0,1)
|yes
|no
|no

|-
!CUSTOM_MARKET_OFFICIAL_2
|no
|grain / harvest
|always
|food supply
|1
|0
|450
|1
|(5,0,1)
|yes
|no
|no

|-
!CUSTOM_MARKET_OFFICIAL_3
|no
|fire
|always
|fire safety
|0
|0
|475
|1
|(5,0,1)
|yes
|no
|no

|-
!CUSTOM_MARKET_OFFICIAL_4
|no
|judge / magistrate / justice
|no
|judge
|1
|0
|350
|1
|(5,0,1)
|yes
|no
|no

|-
!CUSTOM_MARKET_OFFICIAL_5
|no
|building
|always
|construction permits, building safety
|1
|0
|460
|1
|(5,0,1)
|yes
|no
|no

|-
!CUSTOM_MARKET_OFFICIAL_6
|no
|road
|always
|maintain roads, bridges and tunnels
|1
|0
|375
|1
|(5,0,1)
|yes
|no
|no

|-
!CUSTOM_OFFICIAL_16,7,8
|optional
|"keeper of the seal" / chancellor
|no
|espionage
|3
|2
|20
|1
|(5,0,1)
|yes
|yes
|no

|-
!CUSTOM_OFFICIAL_27,9
|optional
|justiciar
|no
|collect taxes
|3
|2
|60
|1
|(5,0,1)
|yes
|no
|no

|-
!CUSTOM_OFFICIAL_3
|always
|treasurer
|no
|trade, accounting
|2
|1
|70
|1
|(5,0,1)
|yes
|no
|no

|-
!CUSTOM_OFFICIAL_4
|always
|advisor / counselor
|no
|advise leaders
|2
|1
|55
|1
|(5,0,1)
|yes
|yes
|no

|-
!CUSTOM_OFFICIAL_5
|optional
|chamberlain
|no
|oversee leader houshold
|1
|0
|80
|1
|(5,0,1)
|yes
|yes
|no

|-
!CUSTOM_OFFICIAL_6
|no
|master of beasts
|no
|tame exotics, manage animals
|1
|0
|90
|1
|(5,0,1)
|yes
|yes
|no

|-
!CUSTOM_OFFICIAL_7
|always
|butler / cup-bearer
|no
|manage leader houshold food and drinks
|0
|0
|300
|1
|(5,0,1)
|yes
|no
|no

|-
!CUSTOM_OFFICIAL_8
|always
|doctor
|no
|health management
|0
|0
|310
|1
|(5,0,1)
|yes
|no
|no

|-
!CUSTOM_OFFICIAL_9
|always
|executioner
|no
|executions
|0
|0
|320
|1
|(5,0,1)
|yes
|yes
|no

|-
!CUSTOM_OFFICIAL_10
|always
|chef
|no
|prepare leader meals
|0
|0
|330
|1
|(5,0,1)
|yes
|no
|no

|-
!CUSTOM_OFFICIAL_11
|always
|housekeeper
|no
|manage leader houshold cleanliness
|0
|0
|340
|1
|(5,0,1)
|yes
|no
|no

|-
!CUSTOM_MILITARY_STRATEGY4
|no
|general/(field) marshal / constable
|no
|military strategy
|3
|2
|50
|1
|(5,0,1)
|yes
|no
|yes

|-
!CUSTOM_MILITARY_GOALS5
|no
|war leader
|no
|military goals, optional: military strategy
|3
|2
|45
|1
|(5,0,1)
|yes
|no
|yes

|}

: ''Notes'':
:* 1): The possible name prefixes are "chief", "head" and "high" (always) and also "royal", if the site leader has the name "law-giver". The name prefix can be empty, if the cell entry is "optional". A name prefix will always be present, if the cell entry is "always".
:* 2): The possible name suffixes are "administrator", "caretaker", "commissioner", "master" and "official". A name suffix will always be present, if the cell entry is "always".
:* 3): The additional flags are: flashes, brag_on_kill, chat_worthy, kill_quest, account_exempt, punishment_exemption, quest_giver and special_burial.
:* 4): Only ever created, if the first site leader was a FORCED_ADMINISTRATOR. Can even be created, if the FORCED_ADMINISTRATOR has already been replaced by a CUSTOM_LAW_MAKER_2.
:* 5): Only created, either after the CUSTOM_MILITARY_GOALS position was created and the CUSTOM_MILITARY_GOALS position was not created with the military strategy responsibility or if the leader has the name law-giver (and does not have the military strategy responsibility). Can even be created, if the first site leader was a FORCED_ADMINISTRATOR, who has already been replaced by a CUSTOM_LAW_MAKER_2.
:* 6): If the leader name is not law-giver (and the first site leader was not a FORCED_ADMINISTRATOR), then a CUSTOM_OFFICIAL_1 has the espionage responsibilty. All CUSTOM_OFFICIAL_1 of a civ (regardless of whether the CUSTOM_OFFICIAL_1 belongs to a site government or the civ government) will either have the espionage responsibility or do not have the espionage responsibility.
:* 7): If the leader has the name law-giver then this official position has the responsibilities (and also optional resp.) as given in the civ table for the official position and not the responsibilities as in this table. Ie. that is the only case where a CUSTOM_OFFICIAL_1 can be created for a site government without the espionage responsibility.
:* 8): The CUSTOM_OFFICIAL_1 has always the responsibility make introductions, if the first site leader/ruler was a FORCED_ADMINISTRATOR, even if the FORCED_ADMINISTRATOR has already been replaced (by a CUSTOM_LAW_MAKER_2).
:* 9): The CUSTOM_OFFICIAL_2 has always the responsibility law enforcement, if the first site leader/ruler was a FORCED_ADMINISTRATOR, even if the FORCED_ADMINISTRATOR has already been replaced (by a CUSTOM_LAW_MAKER_2).
:* In the above table the columns "human" and "goblin" donate, whether a site government of a human civilization or of a goblin civilization can have that position (or at least, if the position was encountered so far). Note so far only goblin site governments with a CUSTOM_BANDIT_LEADER did have further positions created.
:* In addtion to the above table the "best_appointment_precedence" is 30001. Also the following flags are set (true) for all officials, regardless, of whether belonging to a human or goblin site government: duty_bound, has_responsibilities, do_not_cull, color, menial_work_exemption and has_received_positions.
:* All of the positions are appointed by the current ruler of the site (ie. CUSTOM_LAW_MAKER, CUSTOM_BANDIT_LEADER, FORCED_ADMINISTRATOR), except the CUSTOM_MILITARY_STRATEGY position will be appointed by the CUSTOM_MILITARY_GOALS position, if the CUSTOM_MILITARY_GOALS position was created prior and the current ruler of the site government is a forced administrator.

Additionally the position entry usually has the flag active set and the flag is_replaced is false, otherwise the position would no longer be active (and might have been replaced).

= Bandits =
Bandits use the entity types 4 and 7, which are nomadic groups (type 4) and outcasts (type 7). It must also be noted that some CUSTOM_BANDIT_LEADER positions are used by site governments (typically goblin site governments) both with and without a parent civilization (site government is not a child of an entity of type 0).

The following table gives an overview over the possible variable positions used by bandits (some further info on bandit leaders is below the table).

{|class="sortable wikitable" style="text-align:center;"
|- style="background:#F2F2F2;"
!Position!!Name!!appointment type!!Responsibilities!!squad size!!Demands!!Mandates!!Precedence!!Number!!add. flags1!!rules from location!!entity type

|-
!CUSTOM_BANDIT_LEADER
|Boss, Captain, Chief, Chieftain, Commander, Leader, Master, Overlord, Ringleader or Warlord
|elected
|law making, law enforcement, receive diplomats, make introduction, make peace agreements, make topic agreements, military strategy and military goals
|20
|2
|1
|55
|1
|yes
|no
|nomadic, outcast

|-
!CUSTOM_BANDIT_LEADER2
|Boss, Captain, Chief, Chieftain, Commander, Leader, Master, Overlord, Ringleader or Warlord
|elected
|law making, law enforcement, receive diplomats, make introduction, make peace agreements, make topic agreements, military strategy and military goals
|20
|2
|1
|10
|1
|yes
|no
|nomadic

|-
!CUSTOM_OUTCAST_LT
|lieutenant
|appointed by bandit leader
|patrol territory, attack enemies
|0
|1
|0
|160
| -1
|no
|no
|outcast

|-
!CUSTOM_OUTCAST_FACTOR
|representative
|appointed by bandit leader
|trade and accounting
|0
|1
|0
|70
| -1
|yes (except is_law_maker)
|yes
|outcast

|}
: ''Notes'':
:* 1): Additional flags are: is_law_maker, flashes, brag_on_kill, chat_worthy, kill_quest, account_exempt and quest_giver
:* 2): Only difference to the other CUSTOM_BANDIT_LEADER is the increased precedence of 10, encountered in 11 of 148 bandit leaders (148 of 175 nomadic groups had leaders). The reason is of yet unknown, except that the CUSTOM_BANDIT_LEADER is also used by the goblin civilization (and some site governments, without an entity link to a parent civ, had a nomadic group with a custom bandit leader as a child entity).
:* Further note the common flags of these positions are: duty_bound, has_responsibilities, do_not_cull, is_leader, has_met_pop_req, menial_work_exemption, has_received_positions and has_met_market_req.
:* The entity type in the above table refers to the (as displayed by dfhack's gm-editor, when viewing an entity).

Additionally the bandit leader (CUSTOM_BANDIT_LEADER) always has a squad size of 20 and the squad members are refered to as "bandits".

= Religious Entities =
Some religious entities, which are considered "child"-entities of civilizations (no religious entity which was not a "child" of a civ entity has been found so far), also have variable positions - the other religious entities have no positions at all.
If a religious entity rules a site (always monastery?), then the only variable position (of that entity) seems to be the CUSTOM_LAW_MAKER and the name of the position seems to be always "abbot".
Otherwise the variable positions PRIEST, HIGH_PRIEST and HIGHEST_PRIEST can be created for that religious entity, where any such entity, if it has a position, will always have the PRIEST as position. Afterwards, the position HIGH_PRIEST can be created and at last - after the HIGH_PRIEST was created - the HIGHEST_PRIEST can be created. The names of these position are randomly created (more about the name generation is currently out-of-scope, ie. why a PRIEST might be called "sacred squid", "holy burial", "sacred rumor", "holy lemon" or "sacred paper" is out-of-scope at least for this wiki article). No temple is needed in an associated site for a religious entity (not ruling from a monastery) to create a priest, high priest or highest priest position.

An overview on the positions of religious entities is given in the following table:

{|class="sortable wikitable" style="text-align:center;"
|- style="background:#F2F2F2;"
!Position!!name prefix!!name!!appointment type5!!Responsibilities!!Precedence!!Demands!!Mandates!!number!!missing common flags1!!additional flags2

|-
!CUSTOM_LAW_MAKER3
|
|abbot
|heir
|law making, law enforcement, receive diplomats, make introductions, make peace agreements, make topic agreements, military strategy, military goals
|100
|3
|2
|1
|is_diplomat
|all

|-
!PRIEST
|holy or sacred
|random4
|elected
|religion
|200
|0
|0
| -1
|none
|no

|-
!HIGH_PRIEST
|high, first or exalted
|random4
|elected
|law_making, receive diplomats and make topic agreements
|50
|3
|2
| -1
|none
|all (except determines_coin_design)

|-
!HIGHEST_PRIEST
|absolute or most sacred/high/exalted
|random4
|elected
|law_making, receive diplomats and make topic agreements
|1
|5
|3
|1
|none
|all (except determines_coin_design)

|}

Notes:
1): The common flags are: duty_bound, has_responsibilities, chat_worthy, do_not_cull, is_leader, is_diplomat, has_met_pop_req, rules_from_location, menial_work_exemption, punishment_exemption, has_received_positions and has_met_market_req. So if one of the flags is mentioned in a column, then the position does not have that flag.

2): The additional flags (in this case) are: is_law_maker, flashes, brag_on_kill, kill_quest, exported_in_legends, account_exempt, quest_giver, special_burial.

3): Is always the only position for that religious entity. And so far any such entity, which was found, always governed/ruled a monastery.

4): The name is one of the possible "name prefixes" for the position written before a completely random word, which may or may not depend on the religious spheres/domains worshipped by that religion.

5): The appointment/succession type is actually determined by flags, ie. elected and succession_by_heir. One of the flags is also true for these positions (but not explicitly mentioned in the common/additional flags).

Additional notes: The PRIEST, HIGH_PRIEST and HIGHEST_PRIEST have a variable color entry, but the color-flag (of the position entry) is false, so it is unclear whether currently the color entry has any effect.

= Mercenary Group =

All mercenary entities will have at least one position (the CUSTOM_MERCENARY_LEADER). The only other possible position is the CUSTOM_MERCENARY_TREASURER.

Basic information about both positions are found in the table below (and the explanations below the table).

{|class="sortable wikitable" style="text-align:center;"
|- style="background:#F2F2F2;"
!Position!!Name!!appointment type!!Responsibilities!!Precedence!!Demands!!Mandates!!number!! imp. flags1

|-
!CUSTOM_MERCENARY_LEADER
|usually "warlord", "leader", "general" or "overlord" but very unusual names are possible (see below table)
|elected
|law making, law enforcement, receive diplomats, make introductions, make peace agreements, make topic agreements, military strategy, military goals
|50
|2
|1
|1
|yes

|-
!CUSTOM_MERCENARY_TREASURER
|treasurer
|elected
|trade and accounting
|160
|1
|0
|1
|no

|}

Notes: 1): The imp. flags are flashes, brag_on_kill, chat_worthy, punishment_exemption, kill_quest and quest giver.

Both positions also have the is_leader flag and the following flags: duty_bound, has_responsibilities, has_met_pop_req, menial_work_exemption, has_received_positions and has_met_market_req.

For the mercenary leader also illustrous names such as lord twinkle, lord duty, lord savant, maze commander or secret commander can be created. In these cases the name seems to be generated by either adding a random word after the word lord or adding a random word before commander.

= Guilds =
All guilds will always have all four of the variable positions mentioned in this section. Note that "merchant guilds" are merchant companies and an entirely separate entity.

The following table gives an overview of the four guild positions.

{|class="sortable wikitable" style="text-align:center;"
|- style="background:#F2F2F2;"
!Position!!Name!!appointment type!!Responsibilities!!precedence!!demands!!mandates!!number!!add. flags1

|-
!CUSTOM_GUILD_LEADER
|dean/doyen
|law making, law enforcement, receive diplomats, make introductions, make peace agreements, make topic agreements, military strategy, military goals
|elected
|50
|2
|1
|1
|yes

|-
!CUSTOM_GUILD_ALDERPERSON
|alderperson
|meet workers, manage production
|elected
|150
|1
|0
|1
|no

|-
!CUSTOM_GUILD_STEWARD
|steward or treasurer
|trade
|elected
|160
|1
|0
|1
|no

|-
!CUSTOM_GUILD_CLERK
|clerk, bookkeeper, recordkeeper
|accounting
|elected
|170
|1
|0
|1
|no

|}

Notes:
1): The additional flags are: is_law_maker, flashes, brag_on_kill; chat_worthy, do_not_cull, kill_quest, account_exempt, rules_from_location, punishment_exemption and quest_giver.

All positions have the following flags in common:
duty_bound, has_responsibilities, do_not_cull, is_leader, has_met_pop_req, menial_work_exemption, has_received_positions, has_met_market_positions.

= Merchant Company =
Every merchant company will have a leader (CUSTOM_COMPANY_LEADER). Furthermore a merchant company can have a CUSTOM_COMPANY_FACTOR, to which an unlimited number of history figures can be assigned to (ie. a company can have multiple governors).

An overview of both positions is given by the following table:

{|class="sortable wikitable" style="text-align:center;"
|- style="background:#F2F2F2;"
!Position!!name!!appointment type!!Responsibilities!!Precedence!!Demands!!Mandates!!number!!additional flag

|-
!CUSTOM_COMPANY_LEADER
|master or head
|elected or succession by heir
|law making, law enforcement, receive diplomats, make introductions, make peace agreements, make topic agreements, military goals, military strategy
|50
|2
|1
|1
|is_law_maker

|-
!CUSTOM_COMPANY_FACTOR
|agent, factor, administrator or governor
|appointed by company leader
|trade and accounting
|200
|1
|0
| -1
|none

|}

Both positions have the following flags in common:
duty_bound, has_responsibilities, flashes, brag_on_kill, chat_worthy, do_not_cull, kill_quest, is_leader, account_exempt, has_met_pop_req, rules_from_location, menial_work_exemption, punishment_exemption, has_received_positions, quest_giver and has_met_market_req.

Also note that in contrast to many other variable positions (of different entities) for the CUSTOM_COMPANY_LEADER both an election based appointment (or succession) and an succesion by heir is possible, but each merchant company will only have an elected leader or a leader (with inheritance).

= Raw tokens =
The tokens that manage the creation of positions are [[Entity_token#SITE_VARIABLE_POSITIONS|SITE_VARIABLE_POSITIONS]] and [[Entity_token#VARIABLE_POSITIONS|VARIABLE_POSITIONS]].

SITE_VARIABLE_POSITIONS allows for the creation of lords, hearthpersons, and [[boss]]es, and [VARIABLE_POSITIONS] allows creation of Law-makers.

Advanced entity position mechanics

2026-02-17T21:02:30Z

Joostheger: /* Working triggers */

{{Quality|Fine}}
{{Modding}}

= Introduction =

[http://www.bay12forums.com/smf/index.php?topic=182239.0 Discussion thread on the forum]

This page documents observed and tested behavior of entity positions in Dwarf Fortress that is not fully described elsewhere on the wiki. It focuses on advanced interactions between position tokens, including appointment, succession, election, and responsibility handling, across both civilization-level and site-level entities.

The mechanics described here are based on empirical testing in world generation and fortress mode, supplemented where necessary by raw analysis. In several cases, the game’s behavior is determined by evaluation order and interaction between multiple tags, rather than by individual tokens in isolation.

This page is intended for modders and advanced players who are designing or debugging custom entity position structures. It does not restate basic position mechanics, but instead highlights edge cases, non-obvious interactions, and behaviors that may appear inconsistent or undocumented.

Unless stated otherwise, the described behavior applies to current versions of the game and may differ from older releases.

==What is an entity? What is a position?==
An [[entity]] is an organizational structure that can have relationships with other entities, usually known as a [[civilization]] or a "[[site]] government" in the game, but merchant [[guild]]s, religious organizations, necromancer towers, and [[bandit]] groups are also entities. An entity can have positions - in most cases, these are hardcoded and generated by the game, but as for civilizations and sites, the [[raw file]]s can be customised.

A position is a special relationship between a unit and an entity. The unit holding a position has a larger influence over that entity than other citizens. Positions are mostly known as [[nobles]], but in this article. the technical term is used.

=Position levels (Site/Civ) and their interaction=
There are two basic types of positions that are customizable: '''civ(ilization)''' level and '''site level'''. Positions with the tag [SITE] are at site level, positions without the tag [SITE] are at 'civ level'. These two types of nobles can be considered '''loosely related systems'''. There are a few places where they can interact with each other.

Civ-level positions are in charge of the civilization as a whole, managing national [[trade]], laws, and [[war]]s. These are, for example, the vanilla [[monarch]], [[diplomat]] and [[general]]. (Note that the general doesn't do anything in either mode in the current version.)

'''[LAND_HOLDER]''' nobles are also positions at civ-level. These units are members of the national government, but have gained authority over some land or site. Once they do, they move to that place, but their position is still regarded as a civ-level position.

Site-level position holders are members of a site government (subsidiary to the civilization), and manage local affairs in that location. These are, for example, the [[mayor]], the [[sheriff]] and the [[broker]].

==Table of interaction between different position levels==
In this table, the possible interactions between different position levels are summarized.
The header row shows the positions defining the tokens.

The left column shows the position type that is referred to.
Example:
{| {{prettytable}}
|- bgcolor="#ddd"
! referred position-type
! LAND_HOLDER
|-
| civilization
| (baron is) APPOINTED_BY:MONARCH
|}
color coding: 
* Exists in vanilla
* Possible with mods
* Not possible
* possible to some extent.
* not yet fully investigated.
{| {{prettytable}}
|- bgcolor="#ddd"
! referred position-type
! Civilization
! SITE
! LAND_HOLDER
! CONQUERED_SITE

|-
| Civilization
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION '''(1)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION

|-
| SITE
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION '''(2)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY '''(3)''' COMMANDER REPLACED_BY SUCCESSION '''(4)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION

|-
| LAND_HOLDER
| APPOINTED_BY COMMANDER REPLACED_BY '''(6)''' SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION '''(5)'''
| APPOINTED_BY COMMANDER REPLACED_BY '''(7)''' SUCCESSION '''(8)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION

|-
| CONQUERED_SITE
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
|}

Remarks:
# Works only in world-gen, if a unit with that civ-position is present at the site.
# Works only in world-gen, the site-position holding unit will then move to the capital.
# Is completely ignored
# Works only in world-gen.
# Works only in world-gen.
# Won't appear at all
# This is necessary for the landholder chain to work properly, it doesn’t work otherwise.
# This works only outside of the landholder chain, so when landholders are simply regarded as civ-level nobles. might also work in world-gen
#

== Other interactions ==

Unfortunately, interactions with positions of other entities don't seem possible, such as APPOINTED_BY: HIGH_PRIEST. With [VARIABLE_POSITIONS], positions are automatically created with codes like CUSTOM_LAW_MAKER_2, but interaction with these positions don't seem to work, either. For more info on those, see [[Variable positions]]

=General=

==Civ-level nobles living at your site==
Nobles from your civilization can come to live at your fortress. This happens in vanilla with landholders such as [[Baron]], [[Count]] and [[Duke]], with the Monarch, but sometimes also with non-landed LAND_HOLDERS.

When a civ-level noble becomes a [[citizen]] at your location, their position is shown among the site-level positions in your [[nobles screen]]. They appear to function as a site-level noble. They may have [[demand]]s, [[mandate]]s, [[squad]]s and the like. They can appoint nobles at the site-level.

If they have certain [RESPONSIBILITY]ies, they do the tasks that go with them.

==Fortress mode, world-gen and their differences==
Their are a few differences in how positions function between fortress mode (normal play mode) and the world generation (world-gen).

In '''fortress mode''', the player has some control over the appointment of nobles, limited by elections, automatic filled-in positions and succession rules. Pre-fortress mode, which is referred to as '''world-gen''', the game will always attempt to assign nobles whenever possible. It is subjected to the same rules as in fortress-mode, but there are some exceptions. In '''[[World activities]]''', which is the thing that happens in the world while you play fortress mode, it seems as if the same rules are applied as fortress mode.

A difference between player-fortress-mode and world-gen, is causes by visibility (see below). Positions that are not visible by the player and thus not available for assignment, will be available in world-gen and will thus be automatically assigned.

In fortress mode, a position that is both [ELECTED] and [APPOINTED_BY], cannot be appointed by the player and is also not elected, and can thus not be filled. But in world-gen sites however, these positions are automatically filled.

Positions with [AS_NEEDED] are almost never created and filled in world-gen (depending on their [RESPONSIBILITY]ies), but can always be used in player mode.

A position can, in fortress mode, be filled by the same unit. A unit can gain multiple positions in fortress mode, for example because of [[elections]]. This will not happen in world-gen mode: a unit can only have one position. See also remarks on 'embark' and 'Losing a position'.

In world-gen, [SUCCESSION] between civ-levels and [SITE-]levels may happen. This will not happen in fortress mode, or even off-site in [[World activities]].

In fortress mode, premature SUCCESSION may happen. This will not happen in world-gen mode.

==Units holding multiple positions in multiple entities==
A unit can hold multiple positions in its civilisation or in its site-entity, however this does not happen in world-gen. Only at player-managed sites can units be holding multiple positions at once. (It is probably not possible for a unit to hold a position in two different civilisations or two different sites.)

In world-gen, if there are too many positions to be filled, they simply stay empty until more units are available. E.G, a unit at a site might inherit a civ-level position and still remain a member of the local government. When this happens however, they move to the capital. If a unit gains a new position, either inherited or otherwise, it drops the previous one. If a unit assumes a civ-position in fortress mode, it leaves the current position.

If a unit holds the same (site-)position multiple times, it has no additional effect.

If a unit holds multiple different positions of the same entity, it has all those positions' responsibilities and properties, stacked up. Presumably, the demands for those combined positions are determined by the highest.

A unit holding a position with a succession token can be assigned another position with a (different) succession token.

A unit holding a position with a squad-position cannot hold another squad-position. It is dropped from the first, when it gets its second assigned.
A unit holding a position with a succession token cannot be assigned to a squad-position - the unit is simply not available. It works the other way around, though.

=Specific Tags and functions=
==[PRECEDENCE]==
The first defined position with precedence of 1 counts as the ruler of the civ. See also: [[Position_token#PRECEDENCE|PRECEDENCE]].

If the precedence is omitted or has a negative value, the game sets 0 as precedence, which seems to have no effect whatsoever.

When a unit has multiple positions, the name of the position with the highest rank in precedence is shown behind the unit's name.

If you omit precedence entirely, or set it to [PRECEDENCE:NONE], the position name will not be shown after the unit’s name. Your *Urist Mason* will remain simply *Mason*. This can be useful for positions that are unimportant or purely functional. The position will also not appear in the civilisation overview of your site on the world map. The position name is shown in messages, but remains hidden on the nobles screen as well. To make it visible there, use [LAND_NAME].

==[RESPONSIBILITY]ies==
Both civ and [SITE] positions can carry responsibilities. However, not all responsibilities are active for both types: some function only for civ positions, others only for site positions. When a civ noble arrives at a site and takes up residence, they do not perform responsibilities that are intended for SITE nobles. As a result, these responsibilities neither trigger their associated tasks nor unlock related game mechanics. For example, a civ-level manager living in a fortress will not perform management duties there and doesn't unlock the management-screen, even with an assigned office.
This behavior applies to the following [SITE]-level responsibilities:
* [RESPONSIBILITY:ACCOUNTING]
* [RESPONSIBILITY:BUILD_MORALE]
* [RESPONSIBILITY:HEALTH_MANAGEMENT]
* [RESPONSIBILITY:LAW_ENFORCEMENT]
* [RESPONSIBILITY:MANAGE_PRODUCTION]
* [RESPONSIBILITY:MEET_WORKERS]
* [RESPONSIBILITY:TRADE] (functions differently)
Other responsibilities may be affected as well, but have not yet been fully tested.

===World-gen effects of the [RESPONSIBILITY] of available positions ===
It is possible to cause civs and individual sites to change their behavior substantially when they reach a certain size, by controlling nobles.
* If a site can only appoint a position with [MILITARY_GOALS] after reaching a particular size, that site will not send armies on missions until the required size is reached.
* A civ-level [LAW_MAKING] position is required for the civilization to have any kind of cohesion. Without it, sites will be constantly embroiled in territorial disputes and civil wars will be commonplace.
* [MILITARY_STRATEGY] positions go out and tame wild animals. This makes your civ gain those animals as domesticated and also brings them in sieges.
* The [[Personality_facet|Personality]] of the position's holder determines how they lead the civ.

===[DELIVERS_MESSAGES]===
The only [AS_NEEDED]-position that is created in worldgen based on responsibility is that of the site-level responsibility [DELIVERS_MESSAGES].

===Outpost Liaisons and Diplomats===
Civ-positions with the responsibility [ESTABLISH_COLONY_TRADE_AGREEMENTS] ([[Outpost_Liaison|Outpost Liaison]]s) will meet with the site-noble who has responsibility for [RECEIVE_DIPLOMATS] and the highest rank of precedence (i.e. the lowest precedence value). Usually this is the [[Expedition_leader|Expedition leader]].

Once a [LAND_HOLDER] is assigned to the site, civ-positions with the responsibility [MAKE_TOPIC_AGREEMENTS] ([[Diplomat]]s) will meet with '''civ'''-level nobles present at the site who have the [RECEIVE_DIPLOMATS] responsibility. If multiple eligible nobles are available, one is selected at random. If no eligible noble is present, the diplomat leaves angrily. If the landholder is no longer present at the site, diplomats will not arrive at all.

It appears that Outpost Liaisons and Diplomats are chosen for a diplomatic mission based on availability. When multiple candidates exist, the position defined last in the raws is most often selected.

===[TRADE]===
Civ-level nobles with [TRADE] will arrive with the caravan, just as the Outpost Liaison. Their behavior is no longer active in the vanilla game, but the mechanics are still present. See [[40d:Guild_representative|Guild representative]] for more details. This civ-noble will only meet with the SITE noble with [TRADE], usually the [[Broker]].

If two civ-nobles exist with both [TRADE] and [ESTABLISH_COLONY_TRADE_AGREEMENTS], they both arrive at the same time. Even if both tokens are assigned to a single position, if more than one instance of that position exists, two of them will arrive. However in that case, somehow the elevation of the site and appointment of landholder isn't offered.

If the SITE-noble they intend to meet has both [TRADE] and [RECEIVE_DIPLOMATS], only one meeting will proceed and the other is cancelled. However, when two SITE-nobles are available, each with either [TRADE] or [RECEIVE_DIPLOMATS], both meetings will proceed and both civ-nobles will attempt to negotiate a trade agreement. It is not known what happens if these agreements are accepted or refused.

In the trade depot, the last defined position with the [TRADE] responsibility is shown as broker. However when requesting a trader, the first defined position with [TRADE] will actually go there to do the trade.

==[NUMBER]==
A position might be defined with a number. In that case, as many as defined can be available. If the positions become available, in world-gen and when embarking, they are all filled-in completely.

If the ruling position (with PRECEDENCE of 1) has a NUMBER higher than 1, a random unit of the ones holding these positions is shown as ruler in the embark screen.

A [NUMBER] of 0 (zero) has the same effect as 1.

===Automatic spreading of assumed, non-singular positions===
If there are civ positions that have a NUMBER higher then '1' and which are assumed (not APPOINTED_BY or ELECTED) but are '''not DUTY_BOUND''', these are automatically spread among the civilisation, based on population. If there are a number of '''20''' available slots of that position, they spread among a civilization with a combined population of, for example, 1000 of which your fortress has 100 (10%), '''2''' of your fortress' citizens will assume that position.
This may probably also work with elected and appointed positions, but that may be depending on the death of the current holders and this needs more testing. Assumption works within a day, anyway.

===[AS_NEEDED]===
These positions can be created automatically by the game in world-gen. This, however, only works with:
* [LAND_HOLDER]'s
* squad commanders (needs more testing)
* Messengers at sites

For all other types of positions, they're not created in world-gen, even if they are defined with RESPONSIBILITY's. For example, even in war, the game wouldn't create a MILITARY_GOALS position, if they have AS_NEEDED as number.

However, in fortress mode / player mode, these positions can be created by the player at will.

Positions with AS_NEEDED need to be created first, before any symbols are assignable as 'symbols' (objects) for the position holder to carry or wear.

Positions with AS_NEEDED cannot be created and then ELECTED in fortress mode. It only works with APPOINTED_BY.

==[REPLACED_BY] and [REQUIRES_POPULATION]==

The token REPLACED_BY:position means that once the replacing position reaches its required population-number, the 'to-be-replaced' position will disappear. This is defined in REQUIRES_POPULATION. These tags are closely related to each other and seem to only have a meaningful function if combined. Nobles with REQUIRES_POPULATION require the population to have a specific size.

This works on the civ-level as well as on site-level, but those systems are in this mechanic strictly separated. Site-level positions cannot be replaced by civ-level positions and visa versa. This makes sense, because they both depend on their own population-count. When using REQUIRES_POPULATION on civ-level, it counts the total population of the civilisation.

See also: [[Advanced_entity_position_mechanics#Evaluation_of_Positions|Evaluation of positions]]

===Effect of replacement (and on [LAND_HOLDER]s)===

Replacement is immediate and complete - the current holding unit loses the position, even before SUCCESSION_BY_POSITION rules are applied. A position with a number of 1 will replace all the slots of a position with a higher number of slots.

Even if the next position is available but not visible, replacement still takes place. If a position is replaced, it is completely gone - it cannot be appointed, succeeded, elected or assumed any longer.
The unit immediately loses its position.

In legends, replacement is mentioned as: "(unit name) ceased to be (position name)" The replacement of an AS_NEEDED position empties the position's slot forever. In fortress mode, it may seem as if you can create new slots and appoint new units in the nobles screen, but this is reversed as soon as you close the window.

The landholder chain uses [REPLACED_BY] differently. It does not clear the position completely, but uses it for succession to the next level's position. [REPLACE_BY] is required to let that system work properly. This also means that the way in which landholders succeed (replace + as_needed) does not work in any other way.

Replacement between LAND_HOLDERS and other site- or civ positions does not work in any way. Only the vanilla replacement sequence between levels of LAND_HOLDERs does work. If the token is omitted for landholders, the landholder chain is broken, so replacement is required for the landholder system to work.

[REQUIRES_POPULATION] also does not work for [LAND_HOLDER], when you set [NUMBER] to 1. The position is not created when the required population is reached.

===What doesn't work===

'''Attention: If a position cannot be appointed, for example because of 'mutual appointment', it still exists according to replacement mechanics and will replace other positions if so defined. If a certain position(a) will be replaced by the baron's assistant, which can only be appointed by the [LAND_HOLDER] baron, than that position(s) still will be replaced from the start of the game, even if no baron or their assistant is ever present.'''

A position that is replaced by a somehow non-fillable position is still replaced. This counts for mutual-appointing positions, replacement by not-yet-assigned landholders, replacement by AS_NEEDED positions, or replacement by not-yet-appointed positions.

Replacement does not work if the replaced position is a [LAND_HOLDER], even with civ-positions. In that case, the LAND_HOLDER's position is not replaced. It does not matter if AS_NEEDED is used, or a fixed number, and it also does not matter what type of position the replacer is. So this only works (correctly) with positions that become available by REQUIRES_POPULATION.

==[CONQUERED_SITE]==

This tag determines which position is used to assign a [[Forced administrator]].

In legends mode, this is visible as an event describing the reconquest of the site: a new group is formed and the forced administrator is installed as its ruler.

All positions defined with this tag are assigned during this process, meaning multiple positions can be appointed at once.

The holder of a position marked with [CONQUERED_SITE] cannot appoint any other [SITE] positions.

Combining [CONQUERED_SITE] with [SITE] causes the position to function both as a forced administrator and as a normal site position available in fortress mode. However, this provides no meaningful additional mechanics and is effectively inferior to using [SITE] alone:
* [APPOINTED_BY] lines are completely ignored, meaning that the roles are automatically assumed.
* [SUCCESSION] is likewise ignored.
* the [CONQUERED_SITE]-position cannot appoint other [CONQUERED_SITE], [SITE] or combined positions.

There have been remarks that reclaiming a fortress is unplayable because of the lack of regular nobles. Unfortunately, it seems that it can't be fixed by modding.

=Availability and visibility=
==Availability of (new) positions==
Warning: Do not mistake "availability" for "visibility"!

Of all the possible positions existing in your site's entity, there may only be some available.
* Positions with [REQUIRES_POPULATION] require the population to have a specific size.
* Positions with [REQUIRES_MARKET] will only appear in "large" sites (which may have different rules for different site types). This tag has no effect in fort mode.
* Positions that are appointed by positions that have an AS_NEEDED number. The appointable positions only become available after an appointer position-slot is created. This works also on civ-level. If a position is appointed by a Land-holder, it only becomes available, when that level of landholder is created.

Only the replaced positions are culled and are no longer available.
A position that requires a certain population will become available, even if it doesn't have [APPOINTED_BY] or [ELECTED]. In that case, see 'automatic assignment' and 'assumption'

In fortress mode, in some cases 'succession' is evaluated immediately after a position becomes available. See: Succession.
==Visibility of positions==
A position might be available, but can still be invisible for the player in the [[nobles screen]]. The positions with their respective holders are visible for players:
* All site-positions that are already filled-in (even if they could not be re-filled-in considering current conditions)
* Site positions that are appointable by a filled-in site position
* Site positions that are appointable by a filled-in civ position, when that civ positions holder becomes a citizen of your fortress.
* Civ positions of units that are also a citizen of your fortress.
If a position becomes available, for example because a certain pop number has been reached, or if it is available from the start(like expedition leader), as long as it cannot be appointed, it still is INVISIBLE for the player.

It might strike someone as odd if a position becomes filled automatically in fortress mode when that position is not even visible. This might be the case if the current holder of a non-appointable position dies or succeeds another position. Regardless of player visibility, these positions will be automatically filled in if the necessary requisitions are met. It might happen with the expedition leader.

A situation with a non-visible but available position, is for example when a position is solely appointed by the expedition leader, when the expedition leader's position is left vacant. It can no longer be appointed by the player and is invisible. Then, it gets automatically assumed, proving that the position still was available.

A position that is both [APPOINTED_BY] and [ELECTED] is visible, but players cannot interact with it.

={{text anchor|Evaluation of Positions}}=
The game does not continuously check whether positions should become available, elected or be [REPLACE_BY]. This is well-known behavior—for example with the [[mayor]], who does not appear automatically when the required population ([REQUIRES_POPULATION]) is reached. Instead, positions must somehow be evaluated. This applies in several other situations as well

'''Cases that require a trigger:'''
* Election of a newly created position
* Election after the current holder dies
* Automatic assumption of a newly created position (this may take up to a day)
* New citizens (such as migrants) considering available positions
* Premature succession of a newly created position

'''Cases that do not wait for a trigger:'''
* Succession following the death of the previous holder
* Automatic assumption of existing positions that have become vacant

'''Triggers that cause the game to reevaluate noble positions:'''
* Succession of a [SITE]-position due to the death of the current holder
* [[Advanced_entity_position_mechanics#Election_Day|Election Day]]
* Automatic assumption of a [SITE]-position that becomes vacant
* (Re)assigning any site position manually
* Settlement elevation on the LAND_HOLDER track (e.g. gaining a [[Baron]] or [[Count]])

=Gaining a position=
There are several ways a unit can gain a position:
* Appointment: A unit is appointed by another unit or by the player.
* Election: A unit is elected by and among the members of the entity
* Assumption: A position is neither elected or appointed: a random unit just simply 'takes' the position
* Succession: a unit is the valid successor of this position(A), either by its current position(B) or because they are that position(A)-holder's heir.

Available positions will automatically be assigned to a random civ member when a new site/civ is created.

==Who can take a position==

* If so defined, a unit needs to be the right caste and/or class - it does not seem to work with creature types.
* The unit needs to be an adult member of the site or its parent civ's government; that is also CAN_LEARN or INTELLIGENT (SLOW_LEARNER cannot take positions) or otherwise is able to think.

==Appointment==

Positions that have an [APPOINTED_BY:position] token require that position to exist, to be available and appointed. Any position that is APPOINTED_BY can be appointed if the appointer's position is filled in.
For site-positions to be appointed, it is required that the appointer is present at that location.

If the appointing unit is temporarily not present, or if that position is not filled, positions depending on it cannot be appointed. This is the case with [[militia captains]], when the [[militia commander]] is on a [[mission]].

A site position cannot appoint a civ position ''or'' LAND_HOLDER in any way whatsoever.

Civ-level positions can appoint other civ-level positions and site-level positions can appoint other site-level positions.

Contrary to what has been said elsewhere, civ-level nobles also can appoint site-level nobles. They need to be at the site to do so. Landholders can appoint both site-level and civ-level nobles. These systems are therefore not as separate as was assumed.

'''Mutual appointment''' cannot take place. If these are the only requisites of the position, then the positions will never appear or get filled. These unfillable positions can be put to good use, for example, to replace a position that is no longer needed without creating a new one.

'''Self appointment''' doesn't normally work. If you have a position that is only appointed by itself, it is never appointed and also cannot be assumed. However, if the position has a number higher than 1, and is filled by multiple units (for example by another position that is now empty), than those units can re-assign or appoint each other from that their shared position.

If an APPOINTED_BY token refers to a non-existing position's code, the effects are as if the appointment token doesn't exist at all.

===Automatic appointment in world-gen and on the civ level===

Outside of fortress mode, the game will always attempt to appoint nobles whenever possible, as long as these positions are '''available''', even if they are invisible to the player.
It shows this message in legends: "(unit name) has been appointed to the position of (position name)"

In world-gen, all positions become available and are automatically appointed, taking population- and appointment-requirements into consideration.

Positions that are REPLACED_BY are culled and won't be filled.

If a citizen of your fortress holds a civ-level position that can appoint another civ-level position, the appointment will happen automatically and without player intervention. It may happen that another citizen of your fortress is appointed by that unit, creating civ-level position holders in your fortress, but it is unknown what is required to force this effect.

===Manual appointments by players in fortress mode===
In fortress mode, the positions that need to be appointed stay empty on embark. and it is the player's job to appoint those. A player can appoint a unit to any available position, according to the hereabove mentioned conditions. The player takes the role of the automatic appointment-system, but has no direct control over elections, successions and replacement. There are some differences in what is possible at world-gen sites and at player-controlled sites.

* A position that is appointed by a unit present as a fortress citizen, can be appointed, re-appointed or left vacant. This means also by civ-level nobles living as a citizen in your fortress; not when they are only visiting, like the diplomat.
* A position whose appointing positions are all either vacant or [REPLACED_BY] can no longer be appointed. If the position is already filled, it cannot be reappointed or vacated; the current holder simply remains in office.
* A position that is APPOINTED_BY a unit present as the land_holder of your site, can be appointed, reassigned or left vacant.
* A position that has SUCCESSION BY_HEIR or BY_POSITION can 'initially' be appointed and also re-appointed or left vacant, but as soon as the [[nobles]] screen closes, ''it can no longer be replaced or left vacant''. From then on, the succession-rules determine who gains that position when the current holder loses the position. This works even if the SUCCESSION:BY_POSITION-position is vacant or replaced.
* A position that is ELECTED nor APPOINTED_BY, can always be (re-)appointed by the player. This is the case with the [[Expedition leader]]. If it is left vacant however, it cannot be appointed, but will be assumed shortly after.
* A position that is both ELECTED and APPOINTED_BY, cannot be appointed by the player. Contrary to world-gen sites, its slot is visible, but it doesn't show the +-sign. This is either by AS_NEEDED or by a fixed number. Even if the position somehow gets filled (re)assignment is never possible
* A player can appoint a number of units to a position, as much as the NUMBER token dictates. If it is AS_NEEDED, the player may create as many slots as they like, also contrary to world-gen sites.
* A civ-position can never be appointed, even if the appointing civ noble is a citizen of your fortress. A civ position also never can be re-assigned or left vacant, would that position be defined as appointed by a site-position.

==Election==
Read more in [[Elections]]. The message that is shown is: "(creature name) has been elected to the position of (position name)"

In worldgen, there is no functional difference between ELECTED and non-appointment, except that elected nobles tend to have high social skills and/or skills related to the position, while non-elected ones are assigned randomly. See: [[Elections]]

A succession goes before an election.

A position that is both ELECTED and APPOINTED_BY never gets elected. Even if the appointees' position somehow gets filled, (re)-elections won't happen. So, it doesn't seem possible to have an elected position become available when a certain other position becomes filled.

An ELECTED civ-(or LAND_HOLDER) position at your site will never be (re)-elected in fortress mode. So real (re-)election only works with SITE-positions.

=== {{text anchor|Election Day}} ===
Election Day takes place on the 17th of Summer. On this day, a full reevaluation is performed, including all currently elected positions, which are subject to re-election. Contrary to the information on [[Elections]], nothing occurs at the start of a season.

Positions that are both [APPOINTED_BY] and [ELECTED] will not be re-elected on Election Day when assigned through [SUCCESSION].

=== Election Eligiblity ===
Any citizen may stand for election. Eligibility cannot be restricted using [ACCEPTED_CREATURE], [REJECTED_CREATURE], [ACCEPTED_CLASS], [REJECTED_CLASS], or [GENDER]. Units currently having a [SUCCESSION]-position even may be elected for a position with a [SQUAD]-token, which is otherwise impossible to assign or even succeed.

=== Skills ===
In elections, skills are taken into account for the tokens of the position which is elected.
{| class="wikitable"
|+ Relevant skills per position token
|-
! Position Token !! Relevant skills
|-
| Responsibility [[Position_token#DELIVER_MESSAGES|[DELIVER_MESSAGES]]] || [[Ambusher]], [[Observer]] and [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#ACCOUNTING|[ACCOUNTING]]] || [[Record_keeper|Record keeper]]
|-
| Responsibility [[Position_token#ESPIONAGE|[ESPIONAGE]]] || [[Schemer]]
|-
| Responsibility [[Position_token#HEALTH_MANAGEMENT|[HEALTH_MANAGEMENT]]] || [[Diagnostician|Diagnostician]]
|-
| Responsibility [[Position_token#MAKE_INTRODUCTIONS|[MAKE_INTRODUCTIONS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#MAKE_PEACE_AGREEMENTS|[MAKE_PEACE_AGREEMENTS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#MAKE_TOPIC_AGREEMENTS|[MAKE_TOPIC_AGREEMENTS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#MANAGE_PRODUCTION|[MANAGE_PRODUCTION]]] || [[Organizer]]
|-
| Responsibility [[Position_token#MEET_WORKERS|[MEET_WORKERS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#RECEIVE_DIPLOMATS|[RECEIVE_DIPLOMATS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#RELIGION|[RELIGION]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#TAME_EXOTICS|[TAME_EXOTICS]]] || [[Animal_trainer|Animal trainer]]
|-
| Responsibility [[Position_token#TRADE|[TRADE]]] || [[Social_skill|Social skills]] and [[Appraiser|Appraiser]]
|-
| [[Position_token#SQUAD|[SQUAD]]]-token || [[Tactician]] and [[Leader]]
|}

==Assumption==

A position that is not APPOINTED_BY nor ELECTED, or is appointed by positions that are not available in your site or civ, will be assumable by a random dwarf. If it has responsibilities that require certain skills, then these are taken into consideration on embark, but not when the position is assumed during the actual game.

Normally, one to three units will take the into consideration to assume a position. Most of the time when there are multiple open positions, only a single unit will assume all of them. However, a position that has REJECTED_CREATURE, REJECTED_CLASS, ALLOWED_CREATURE or ALLOWED_CLASS will be filled with all different units, even if the creature or class mentioned is irrelevant. It seems that this forces the game to loop over all the available units.

The message that is shown in Legends mode is: "(unit name) has assumed the position of (position name)". This may also take place in fortress mode, which then shows this message to the player.

If an assumable position becomes empty, it will be assumed within a day. This is the case when you leave the position of expedition-leader vacant. It also happens with entities.

Assumable positions that become empty will not be assumed if that position has a valid [SUCCESSION] -successor. In that case, the successor inherits the position.

Even positions that are somehow invisible because they cannot be directly APPOINTED_BY players, can be assumed.

When you embark, the assumable positions are automatically assigned to a random unit. If there are multiple of these positions at embark, they all are assigned to the same unit. If there are enough positions available, multiple units may gain a position, but often no more than three different ones.

If a dwarf in fortress mode assumes a position, that already has another position, it will leave the current position empty. When that position also is assumed, then this will continue until all positions have a dwarf appointed to them, with no other position.

A unit that already has a position with a [SUCCESSION] token won't take assumable positions into consideration that have a [SQUAD] token. This can be used by the modder to prevent unwanted loss of current positions.

A position that has an appointer which got replaced because of REPLACED_BY, will not become assumable. Also, positions that have an AS_NEEDED appointer that is not yet filled (or ever), will also not be assumed.

==Succession==

If a position-holder dies or advances to a new position via succession, the position will be granted to another unit based on the [SUCCESSION] tag. If they have an heir or the succeeding position exists, that unit will be assigned. If not, a new one will be appointed according to the usual rules. The message that is shown is: "(creature name) being the rightful heir, has inherited the position of (position name)"

The succeeding creature will also lose its previous position. When succession is defined using BY_POSITION, the unit naturally loses the referenced position. However, it also loses any other positions it may hold. If a unit could simultaneously inherit multiple positions, the last-defined succession overrides the earlier one, clearing the previously acquired position

Succession works both at site-level and at civ-level, both in world-gen and in fortress-mode. Succession by position on the civ-level is also visible and functional in fortress-mode. If both civ-level nobles are a citizen of your fortress, succession is applied visually. Vanilla example: The [[druid]] is succeeded by the [[acolyte]]. This means that as soon as the druid dies, the acolyte takes over.

When a position that is succeeded by position becomes available, immediately it is checked if a position-successor is available and the position is filled with that unit. Even if this is an [ELECTED] position, succession goes first. When elections eventually do happen, succession plays no role.

It is possible to assign multiple levels of [SUCCESSION:BY_POSITION] in different positions, creating a line of positions where the death of one causes all those "below" them to advance.

A position can have multiple tokens with position-succession. It looks to be random which one is used. It is not always:
* The first or last defined token
* The first or last appointed unit
* the oldest or youngest
* one with a higher or lower precedence
* a unit with relevant skills

When a position is defined with a Succession-type, that unit cannot have another position that has a Squad-type. If the succession-position itself has a squad, than it can be assigned another position with a squad, but then it will loose the previous succesion position. See further details by "Squad"

Assumed positions can also be succeeded by position, if the current holder dies.

If the successor is an AS_NEEDED position, the used unit will leave a vacant position-slot on its removal by succession. This empty slot remains a real slot, which will only be cleaned up if you (un)appoint a unit to this position-series. It isn't cleaned up after regular position validation.

A civ-level position of a unit living at your site might be inherited by a unit holding that does not currently live at your site. This, unfortunately, moves that position to a unit off site. This may also happen with the landholder of your site, for example when it is succeeded by another civ-level position. This currently poses an unsolved challenge.

===Eligibility for succession===
Succession is restricted by the tokens [ACCEPTED_CREATURE], [REJECTED_CREATURE], [ACCEPTED_CLASS], [REJECTED_CLASS] and [GENDER].

===Site and civ combined succession===

Succession can work when combining site positions with civ-level positions or land_holders, but only in world-gen mode. In fortress mode, it only works with combining the same level of nobles, with Landholders regarded as civ-level. So, in fortress mode, a site's position cannot succeed a landholder's position and it cannot succeed another type of civ-level position, and vice versa.

This won't work even if the positions:
* are AS_NEEDED or having a fixed number.
* Are LAND_HOLDERs.

===Succession [BY_HEIR]===

When a heir is needed for succession, all children and then other relatives are validated. They cannot take the position if their status does not allow it, for example if they have become a member of another civilisation. See: "Who can take a position". If the unit has no valid heir on that location, the position may go to a unit living on another site. This may cause the title of Landholder of some land to be inherited by a unit living somewhere else. That might be a problem, because then you lose your landholders.

===Premature Succession===

There are cases where [SUCCESSION:BY_POSITION] is applied prematurely: at the moment a position is first created and becomes appointable or assumable, rather than after a current holder leaves. In this situation, the succession mechanism assigns a holder immediately, without any player interaction.

When a position becomes available for the first time, the game checks whether a valid successor-by-position exists. If so, that unit is assigned instantly. It can affect positions that would normally be appointed or elected by the player, causing succession to trigger before the player has any opportunity to intervene.

This behavior occurs only in Fortress mode, but can be applied both on [SITE]-positions as well in civ-positions. That last one however is a bit harder to control. Example: [[Advanced entity position mechanics#The Archduke|The Archduke]]

This premature succession only occurs the first time a position becomes available (i.e. when it is created and becomes appointable or assumable). Even if the position remains vacant and the conditions for succession improve later, premature succession will not trigger again. From that point onward, only normal succession rules apply.

Using premature succession, a position that has [ELECTED], [APPOINTED_BY], or both, can be filled directly.
Notably, positions that combine [ELECTED] and [APPOINTED_BY] are normally impossible to fill through regular mechanics. Premature succession bypasses both election and appointment entirely, making this combination uniquely reachable through this mechanism.

No initial election takes place, and no subsequent elections will ever occur for that position. Succession always takes precedence over election, both in premature succession and in normal succession cases.

This behavior applies only in Fortress mode, not during world generation. World-gen uses simplified and more efficient mechanics, and this interaction does not occur there. Premature succession can affect both site-level and civilization-level positions.

====Multiple succession chains====

Multiple succession chains may be defined and are resolved in the order they appear in the raws.

If a position has both:
* a direct succession chain (A → C), and
* a multi-step chain (A → B → C),

and intermediate positions are vacant, resolution proceeds according to raw order. A common outcome is:
# The direct succession (A → C) is applied first, assigning A to C.
# The remaining chain then advances (A → B).
# If C still has empty slots, the final step (B → C) may occur.

If position B is already filled, behavior depends entirely on raw definition order:
* nothing may happen, or
* B may move to C first, followed by A moving to B.
====Working triggers====
Premature succession is triggered when a succeedable position is created under the following conditions:
* The succeedable position is created because its [REQUIRES_POPULATION] threshold is reached. This applies even if the position is not [APPOINTED_BY]. Premature succession takes priority over automatic assumption (e.g. the mayor declaring themselves within a day).
** The position must either be assumable or appointed by an existing position. When said appointer-position also just has been created, the premature succession of the succeedable position happenes, even when the appointer-position is empty.
* The succeedable position can be [APPOINTED_BY] another position of the same level (site or civ) that has just been created because its [REQUIRES_POPULATION] was reached.
* The succeedable position can be appointed by another [SITE] [AS_NEEDED] position that has just been created and filled.
* The succeedable (site or civ) position is [APPOINTED_BY] the [LAND_HOLDER] position, which has just been created due to site elevation. This typically resolves when the diplomat leaves the map, at which point the landholder position becomes active.
* If all other requirements are met, premature succession can occur immediately after unpausing following embark, for positions with [REQUIRES_POPULATION:7].

====Non-working triggers====
Premature succession does '''not''' occur in the following cases:
* An [AS_NEEDED] succeedable position slot is manually created by the player while its succeeding position is already filled. [AS_NEEDED] positions must always be appointed after creation.
* The succeeding position is filled after the succeedable position becomes available. The moment of creation is the decisive trigger; filling the source position later is too late.
* The succeedable position can be appointed by another site or civ position with a fixed number of slots that has just been appointed. In this case, the succeedable position is just available for appointment itself, nothing more
* Any situation occurring during world generation.
* The succeeding position is [REPLACED_BY] the succeedable position. In this case, replacement removes the unit from the source position first, leaving no holder available for the succession mechanism to use.rst, leaving no holder available for the succession mechanism to use.
* The position is [APPOINTED_BY] a civ-level position, that just became a citizen of your fortress. It must be noted that those civ-level positions were active all that time and the succeedable position could be appointed even before. The monarchs arrival does not trigger premature succession

=Losing a position=

A unit can lose a position when:
* It dies
* It succeeds another position, even if it has nothing to do with the previous position.
* It is assigned to another SQUAD-holding position
* It is convicted of a crime.
* Another unit is ELECTED for the position
* Its position becomes replaced
* Another unit is appointed by the player, or the position is left vacant.
* It has assumed another position, as this always leaves the previous position vacant.

=Embarkment=
Two types of positions are automatically filled by embark.
* Positions without [APPOINTED_BY] or [ELECTED] (assumable). All these positions, even with a NUMBER higher than 1, are all filled with one to three dwarves. Contrary to assumption, this doesn't take into account any limitations. REJECTED_CLASS, ALLOWED_CLASS, REJECTED_CREATURE, ALLOWED_CREATURE and GENDER are applied, but without the normal spread you may expect with assumptions. Also it doesn't look at [SUCCESSION] and [SQUAD] limitations.
* Positions that are elected are filled-in by the normal election rules.

Positions that have a defined appointer are never initially filled at embark.

All positions that don't have [REQUIRES_POPULATION] or with a [REQUIRES_POPULATION] of 7 or lower, will be available at embark.

=Land Holders=

A Landholder is a '''special civ-level noble''' who gets a certain piece of land to hold, when that land is elevated to a certain level, determined by the tag [LAND_HOLDER] and by the landholder triggers in the game's settings. In vanilla, these are the baron, the count and the duke.

A unit gaining the landholder position does not migrate to that specific named land. In world-gen, they stay just where they are, probably at the capital. In fortress mode, you can suggest a citizen for the role. So for the time being that works.

Succession is then a real issue. If you use BY_HEIR, its solved when that landholder has children living at your site. But when its not the case, the title just goes to anyone randomly. Succession BY_POSITION works, but only in the civ-chain, and there's no way to guarantee a civ-holder is at your site at that time. Even with 'automatic spread' positions, it goes to one of them randomly.

==Functioning of the regular landholder chain==

The distinct difference between a landholder and a regular civ-level noble, is that a landholder may gain the position of landholder "of (sitename)" They are then seen as ruler of a particular site.

For a land_holder position to function as such, it has a few requirements:
* NUMBER:AS_NEEDED
* The first landholder-number of 1 is defined.
* No SITE (so civ) tag in that position.
*REPLACED_BY the next level landholder
If a landholder is defined with differentiating properties, it will function like a regular noble. A higher-up landholder that lacks the required tokens or connections will then not be used in elevation.

If a fortress meets the trigger for a new LAND_HOLDER tier when a caravan leaves, then the next time the outpost liaison or equivalent arrives, they will offer to make you an official colony, which will allow you to select all positions for that LAND_HOLDER level. Each time they appear, the outpost liaison will only promote your fortress one tier up the LAND_HOLDER track.

The landholder's LAND_NAME is not required for the functioning of this system. If omitted, messages will be shown with a more generic text.

==Appointment==

This mechanism differs from the regular methods of position management. It ignores all regular appointment- and election rules, so it more or less functions like automatic assignment. A landholder is, in vanilla, appointed by the monarch. Changing this doesn't seem to do anything. If they are appointed by a site-position, a not-yet-existing civ-position, or not appointed at all: the system keeps working as usual.

A landholder can appoint civ-positions and site positions. This works as expected: the positions only are appointed then when that landholder becomes available on civ-level or when he arrives at that site for site-level positions.

If your rank of landholder is the first of its rank in the realm, and is the sole appointer of some civ-position, then immediately as it gains the title, it will appoint the empty civ-slots. This may happen on your site, but the frequency and certainty is hard to determine.

==Succession==

Succession rules are applied to some extent:
* In world-gen it works according to succession rules, and site-positions can be used here. This means that a site position or a civ-position can inherit a landholder position, and vice versa.
* In fortress mode, once a landholder has been appointed, it then can inherit civ-level positions, and vice versa. This means that your baron can become king.
* Succession rules do not apply within the [LAND_HOLDER] chain; a count will not inherit a baron's land. This is because succession does not work well with the AS_NEEDED token.
* Premature succession works in fortress mode with landholders. If a unit gets a landholder's position and that landholder is the appointer of an as yet empty position, which is defined as succeeding from a third one, then the succession is immediately applied. The landholder themselves can even be the successor of a newly created position.
* A landholder's position is, in fortress mode, not successionable by a site-position or vice versa

===Impossibilities for succession by a site-position===
It would be very beneficial if the landholder can be succeeded by a [SITE]-position. So far, the following tests have not lead to positive results:
* making landholder and site-position both non-[DUTY_BOUND]
* make the site-position be [APPOINTED_BY] the landholder and/or the monarch
* give landholder and site-position [REJECTED_CREATURE]
* Let the monarch live at your site when succession could happen.
* Let the site-position be [REPLACED_BY] the landholder.

==Nomination==

The player is able to nominate a unit to become the LAND_HOLDER, but this only works with units of [LAND_HOLDER] level 1. The player can select all units, only limited by the PRECEDENCE of the current units' positions.

A unit that has a position with a PRECEDENCE lower or equal to that of the landholder's position, cannot be selected. This means that a baron (or count) from another site or the monarch cannot be selected, because their precedence is lower or equal.

The GENDER token does not work here: also units with the wrong gender (sorry) can be selected.

==Levels==
In mods, up to 10 levels of LAND_HOLDER may be defined.

If a landholder is replaced by a wrong landholder number (1 replaced by 3), then the number 3 is still correctly attached to the settlement.

If the current landholder has the highest available landholder number, then the next elevation will not happen - the diplomat will not elevate your fortress to a higher position, even if that position might be REPLACED_BY a lower landholder.

These chains do work:
* 1 -> 2a - > 2b -> 3
* 1 -> 3 -> 2 -> 4

These chains do not work:
* 2 -> 3 (need to start at 1)
* 1 -> 4 -> 2 -> 3 (stops after 4 as the highest)
* 1a -> 2, 1b -> 2 (only 1a and 2 work, 1b is not used)

==Moving landholders==

It may happen that a land-holder no longer lives at the site which they are the landholder of, specifically when the current landholder dies, leaving the title to an heir living somewhere else.

To prevent this from happening, you can make their succession from heir and make sure that their kids live at your site. Or, you can make their position succeeded by another civ position, and make it so that this civ position is somehow available on your site. But if multiple of these positions exist, it cannot be guaranteed that a citizen of your fortress will inherit the title.

In world gen, a landholder lacking the DUTY_BOUND-token will also move to the site they like, according to legends mode.

==Replacement by a generic civ-position==

If a landholder is replaced by an AS_NEEDED non-landholder civ-position, then this will work: the current landholder loses that title upon settlement-elevation and gains that civ-title. However, the civ-title lacks the landholder-property of being attached to the land. It will not show the name of the settlement alongside the position's name. So no "minister of Shovelmounts"

If a landholder is replaced by a general AS_NEEDED civ-position, that itself is also replaced by a generic AS_NEEDED civ-position, then firstly the elevation is executed and also the unit gains that new position. However, he immediately loses it, because an AS_NEEDED position that is replaced by another position can be filled initially, but units wont be able to hold that title.

==Landholder with fixed number==

A landholder's position that has a fixed number will be created and filled directly when the civilisation is born, so this position slot is then not available for the regular landholder-mechanic and will also not be used. That landholder will thus not be attached to a settlement.

It doesn't matter if the landholder's position is connected to the regular landholder's-chain with the REPLACE_BY token.

==Responsibilities==

When given a certain [RESPONSIBILITY], a landholder may function as a regular civ-level noble. If the position has [TRADE] or [OUTPOST_NEGOTIATING] responsibilities, then the landholder functions both as a diplomat and as an actual land holder. A landholder with the [MILITARY_STRATEGY] responsibility will travel around taming creatures in world-gen, according to legends mode.

Besides that, the responsibilities work the same as with any other on-site living position-holder, civ or otherwise.

=Military=
==Squad management==
In the vanilla game, the Squad interface only becomes available after a militia commander has been appointed. Until then, the window displays:{{DFtext|You must appoint somebody first to create a squad.}}

What’s surprising is how this is determined internally. In the entity raw definition, '''only the last two positions that include a [SQUAD] token are checked''' to decide whether the interface is accessible at all. As a result, if your hierarchy defines commanders A through E, appointing '''Commander D or E''' unlocks squad formation, while appointing A–C does nothing.

In other words, squad availability is not tied to ''having a militia commander'', but to ''which specific positions happen to be last in the raw list''—a notably hacky implementation.

These 'last two' are always the last two '''available positions.''' So if they get [REPLACED_BY] or become available because of [REQUIRES_POPULATION], the game adapts to those.

==Squad assignment==

Squads can be assigned, even if the leader position has no holder.

A specific unit can only have one position associated with a squad. If it gains another 'squad holding position', it is unassigned from the first one. This does not work with a 0-squad, so only 1+squads are taken into consideration. This technique can possibly be used to distribute all positions equally among all citizens. It does however not work with election and assumption.

If a civ-level position is associated with a squad and it gets a site-level squad-holding position assigned, it loses the current civ-position.

Squads can get really messed up, if you make the position (or multiple) either elected or not-elected and not-appointed, then this can cause the game to assign multiple squads to the same unit. Automatic assignment and election does not take squads into account, but the nobles screen does. This can cause the positions to be cleared as the game figures out that they have more than one position, and immediately get elected or assumed again.

Positions that cannot have a squad-position:
* A site- or civ-position with a [SUCCESSION] token cannot be appointed a squad-holding-position. The other way around, however, does work. For example, if a site-position with a [SUCCESSION]-token is appointed to a unit that has already a position with [SQUAD]. But when that squad position is assigned to another unit, it cannot be assigned back.
* A position with [SUCCESSION] can also not be assigned as a '''member''' of a squad.
* A squad-holding position with a formed squad cannot be appointed to another squad holding position.

If a position has at least one squad member, it cannot be left vacant. First, the squad has to be disbanded, then the position may be cleared.

==0-squads==
A 0-Squad is defined in a position as [SQUAD:0:member:members]. It does not seem to do anything useful as of now.
* It cannot be used to activate the [[Squad|military interface]]
* It does not restrict the assignment of [SUCCESSION] positions.
* Assigning this position does not clear any previously held squad position.
* The [[Leader]] and [[Tactician]] skill are not marked as relevant skills and are not taken into account in elections.
* It cannot be formed as a squad.

=Further testing=
The following questions may need additional testing. Feel free to add or answer
* Everything regarding COMMANDING and army-structure
** [http://www.bay12forums.com/smf/index.php?topic=175437.msg8331668#msg8331668]
** [http://www.bay12forums.com/smf/index.php?topic=165213.msg8335682#msg8335682]
** [http://www.bay12forums.com/smf/index.php?topic=174584.msg8026854#msg8026854]
* Everything regarding CONQUERED_SITE, but it is presumably just like site. But what if you combine SITE or LAND_HOLDER with it?
* Stuff about the monarch, its arrival and its entourage.

=Oddities (Bugs)=
Almost everything on this page could be called an oddity. Because of their unexpected usability, some may also be referred to as “undocumented features.” Others, however, are simply odd and not particularly useful, yet I hesitate to call them “bugs.”
* If a certain threshold is reached that makes an elected position electable, and the triggering event that initiates this evaluation is an assumption, then the resulting assumption is also referred to in the messages as an election

=Examples=

===The Founder===
The founder is a single dwarf, appointed at embark. They will be the only one ever to have this position and are not replaceable. When they lose their position some way, the position will not be assumed by another dwarf.
{{gamedata|title=The Founder|
[POSITION:THE_FOUNDER]
[NAME:the founder:founders]
[NUMBER:1]
[SITE]
[ALLOWED_CREATURE:DWARF:ALL] - will only be filled at embark, but not assumable later.
[REJECTED_CREATURE:DWARF:ALL] - will only be filled at embark, but not assumable later.
[SUCCESSION:BY_POSITION:THE_FOUNDER] - not unassignable, also cannot be assigned to a [SQUAD] position.
[PRECEDENCE:200]
Non APPOINTED_BY
Non ELECTED
Optional: Add responsibilities to make the game select a unit with certain skills.
}}
===Marriage bar===
Dwarven matrons are held in great honour. Upon marriage, a female dwarf is no longer expected to perform menial labour. All dwarven males hold this position by default, granting their spouses exemption from menial work.

The position becomes available with the arrival of the first migrants; otherwise, on embark, it would be assumed by females. Its succession rule is non-functional, but this prevents the player from unassigning the position. A squad size of 1 and the succession rules together prevent a unit from assuming the position more than once.

With precedence set to NONE, the position name is hidden, while LAND_NAME remains visible on the nobles screen. All married females receive the suffix “, Mrs.” and are marked as Nobles.

The practical usefulness of this position is debatable, but it serves as a clear demonstration of several mechanics.
{{gamedata|title=Mrs. Urist|

[POSITION:MRS_URIST]
[NUMBER:300]
[SITE]
[ALLOWED_CREATURE:DWARF:MALE]
Not APPOINTED_BY
Not ELECTED
[LAND_NAME:Dwarven male]
[NAME:dwarven male:dwarven male]
[PRECEDENCE:NONE]
[SPOUSE_FEMALE:, Mrs.:spouses]
[MENIAL_WORK_EXEMPTION_SPOUSE]
[REQUIRES_POPULATION:8]
[SUCCESSION:BY_POSITION:MONARCH]
[SQUAD:1:member:members]
}}
===The Archduke===
The archduke is the leader of the civilization, but exists only from landholder 4-level. Until then, its position remains vacant. When a settlement is elevated to tier 4 (grand duke), the grand duke can appoint the ruler of the civilisation, the archduke. Because of 'Premature Succession', they themself inherit that position immediately, but only when in fortress mode. Its heir then becomes grand duke.
{{gamedata|title=The Archduke| no POSITION:MONARCH or other PRECEDENCE:1

[POSITION:THE_ARCHDUKE]
[NAME:archduke:archdukes]
[NAME_MALE:archduke:archdukes]
[NAME_FEMALE:archduchess:archduchesses]
[LAND_NAME:a archduchy]
[NUMBER:1]
[PRECEDENCE:1]
[SUCCESSION:BY_POSITION:GRAND_DUKE]
[APPOINTED_BY:GRAND_DUKE]
(add additional monarch-stuff, like spouse name, demands etc.)

[POSITION:GRAND_DUKE]
[NAME:grand duke:grand dukes]
[NAME_MALE:grand duke:grand dukes]
[NAME_FEMALE:grand duchess:grand duchesses]
[NUMBER:AS_NEEDED]
[LAND_HOLDER:4]
// Optional ...
[PRECEDENCE:19]
[LAND_NAME:a archduchy]
[RESPONSIBILITY:LAW_MAKING]
[RESPONSIBILITY:RECEIVE_DIPLOMATS]
[SUCCESSION:BY_HEIR]
[APPOINTED_BY:THE_ARCHDUKE]
(add additional landholder-stuff)

!!add to [POSITION:DUKE]
[REPLACED_BY:GRAND_DUKE]

}}
{{Category|Modding}}
{{Category|Entities}}
{{Category|Guides}}

Talk:Variable positions

2026-02-12T14:52:08Z

Joostheger:

Talk:Variable positions

2026-02-12T12:22:35Z

Joostheger: Created page with "----Hi! nice work so far! A few points: * I really wonder where the differences between human and goblins are coming from. Do you have any idea? I almost know for sure that th..."

Variable positions

2026-02-12T12:10:26Z

Joostheger: fixed wrong collumns /* Bandits */

{{Quality|Fine}}
{{Modding}}
{{stub}}
This page documents the variable positions that entities create when neccesary. This is - in vanilla - the case for [[human]] and [[goblin]] [[Civilization|civilizations]], but also for merchants' companies, guilds, mercenary groups, [[Religion|religious groups]] and [[Criminal|criminal]]s.

= Introduction =
Initially none of the positions marked as variable do exist for an entity. The positions will only exist for a given entity, if they are either created during world-gen, world activities(?) or by memory hacking or scripting (ie. with Lua). Ie. in vanilla all human civilizations have at the beginning of the world-generation no positions at all, neither on the site nor civ level, as all positions of the vanilla human civs are marked as variable (variable positions: all). When a variable (civ level) position is created, the position is only created for that civilization (entity) and not for any other entities of the same type. Ie. the creation of a law-giver for one human civ does not create law-givers for other human civs.

Also presumably all site-level positions for each entity are created on a per site basis, meaning the creation of a site ruler for one site (of a civ) does not also create the site ruler positions for any other site (of that civ).

The existence of a variable position does not mean that the position will also be filled by a historical figure. But during world-gen the creation of a position will usually be followed up with the position being filled. Ie. the human historical figure who forced the creation of a law-giver position, will usually become the first law-giver.

For the succession rules of a variable position (after the position has been initially filled by a historical figure), presumably, the same rules as for non-variable positions apply.

(Disclaimer: The following only applies during world-gen and normal world activities. Scripting and memory hacking can circumvent the normal limitations, but with currently unknown results).

For civ level entities, if the law-giving position is a variable position, the law-giving position does not (seem to) have any further requirements to be created (ie. no other position being already created). Ie. this position can be created by force (or popular support etc.) by any historical figure of that civ. But for all other variable (civ-level) positions the law-giving position must exist as usually the historical figure, who is the law-giver, does create the other variable positions (for various reason).

Something similar is probably the case for site level positions. Ie. if the ruler of a site is a variable position, that position needs to be created, before any other site-level variable positions can be created. And the site ruler can afterwards create other variable positions for that site. It is not yet clear if a site level ruling position can be created before a civ level ruling (law-giving) position is created (or exists). This also means that it should be possible, via memory-hacking or scripting, to create (and fill) the variable site level positions (for a player site), at least after the civ level law-giving position has been created (and the law-giving position has been filled), so that a human player site gets the maximum possible human site level positions (with the normal appointment rules for the succession/reappointment of the positions), without having to edit the raw files (as outlined in the human civ page), prior to creating a world, to make the variable positions of human civilisations to "static" ones.

Presumably for guilds (Merchant Guild and others), mercenary groups, religious orders (and criminals) also a "leader" position needs to be created by a historical figure, before other variable positions for that entity can be created.

== General Info ==
So far, no restrictions on allowed_class or allowed_creature have been found and also the rejected_creature and rejected_class entries are always empty. Squad_size is 0, except when a variable position (in the following sections) explictly states otherwise (ie. squad size for CUSTOM_BANDIT_LEADER, CUSTOM_LAW_MAKER and CUSTOM_LAW_MAKER_2 is 20). Also most other entries (of entity_position entry under "own") not mentioned in their section have standard values (ie. are empty). The best_appointment_precedence of all positions is 30001. Also the execution skill is always set to "-1" even for the CUSTOM_OFFICIAL_9, whose sole responsiblity is executions.

Also variable positions are usually only created (with the exception, if they replace another position), if the position will have at least one responsibility the already created (existing) positions for that entity does not have, regardless of whether there are any more prerequisites for a variable position to be created.






== Sources to process ==
See spoiler-sections of those posts.
* https://www.bay12forums.com/smf/index.php?topic=178697.msg8295235#msg8295235
* https://www.bay12forums.com/smf/index.php?topic=175434.msg8084095#msg8084095
* https://www.bay12forums.com/smf/index.php?topic=175434.msg8083631#msg8083631 (first answer)

= Civilizations =
If all positions of a civ are variable, then the CUSTOM_LAW_MAKER position needs to be created (in world-gen), before other positions (of the possible positions) can be created. After the creation (and filling) of the law-maker positions, the other variable positions (both CUSTOM_OFFICIALS_i and CUSTOM_MARKET_OFFICIALS_i, where i stands for a non-zero natural number) can be created in any order. These other positions are then always appointed by the law-maker of the civ. The law-maker position itself uses succession by heir.

In contrast to e.g the positions of the dwarven civilizations, where the site nobility positions (eg. baron, duke) do get added to the own position list (vector) of the civilization, the CUSTOM_LAW_MAKER (and CUSTOM_LAW_MAKER_2) positions (of a site government) are not added to the own position list (at least for civs with all variable positions). The "own" positions list (of the civ entity) only exclusively contains the variable positions of the civ, which are all created by the civ, and no positions which are the "ruler" of a site (even if the variable site position was appointed by the law maker of the civ). Also the "site" positions list is empty (or at least no entries were found so far).

The following table gives an overview over the different possible rulers of a human or goblin civilization.

{|class="sortable wikitable" style="text-align:center;"
|- style="background:#F2F2F2;"
!Position!!Name!!succession type!!Responsibilities!!Demands!!Mandates!!Precedence!!is diplomat!!human!!goblin

|-
!CUSTOM_LAW_MAKER
|master
|none
|law making, military goals, military strategy
|3
|2
|1
|no
|no
|yes

|-
!CUSTOM_LAW_MAKER
|master
|none
|law making, military goals,
|3
|2
|1
|yes
|no
|yes

|-
!CUSTOM_LAW_MAKER
|law-giver
|by heir
|law making, make peace agreements, military goals, military strategy
|3
|2
|1
|no
|yes
|no

|-
!CUSTOM_LAW_MAKER
|law-giver
|by heir
|law making, make peace agreements, military goals
|3
|2
|1
|yes
|yes
|no

|}

Note that the ruler (law-giver or master) is not a diplomat, if and only if the ruler has the military strategy responsibility. Also note that the master of a goblin civilization does not have peace agreements as responsibilities.

The following table gives an overview of the possible non-ruling civ-level positions:

{| class="sortable wikitable" style="text-align:center;"
|- style="background:#F2F2F2;"
!Position!!Name prefix!!Name5!!Responsibilities!!Demands!!Mandates!!Precedence!!Number!!Flags11!!Flags22!!Color!!human!!goblin

|-
!CUSTOM_OFFICIAL_1
|yes3
|"keeper of the seal" / chancellor
|receive diplomats, make introductionsa and make topic agreements; optional: espionage
|3
|2
|20
|1
|yes
|no
|(5,0,1)
|yes
|yes

|-
!CUSTOM_OFFICIAL_2
|yes3
|justiciar
|law enforcement, collect taxes
|3
|2
|60
|1
|yes
|no
|(5,0,1)
|yes
|no

|-
!CUSTOM_OFFICIAL_3
|yes
|treasurer
|trade, accounting
|2
|1
|70
|1
|yes
|no
|(5,0,1)
|yes
|no

|-
!CUSTOM_OFFICIAL_4
|yes
|advisor/counselor
|advise leaders
|2
|1
|55
|1
|yes
|no
|(5,0,1)
|yes
|yes

|-
!CUSTOM_OFFICIAL_5
|yes3
|chamberlain
|oversee leader houshold
|1
|0
|80
|1
|yes
|no
|(5,0,1)
|yes
|yes

|-
!CUSTOM_OFFICIAL_6
|no
|master of beasts
|tame exotics, manage animals
|1
|0
|90
|1
|yes
|no
|(5,0,1)
|yes
|yes

|-
!CUSTOM_OFFICIAL_7
|yes
|butler / cup-bearer
|manage leader houshold food and drinks
|0
|0
|300
|1
|yes
|no
|(5,0,1)
|yes
|no

|-
!CUSTOM_OFFICIAL_8
|yes
|doctor
|health management
|0
|0
|310
|1
|yes
|no
|(5,0,1)
|yes
|no

|-
!CUSTOM_OFFICIAL_9
|yes
|executioner
|executions
|0
|0
|320
|1
|yes
|no
|(5,0,1)
|yes
|yes

|-
!CUSTOM_OFFICIAL_10
|yes
|chef
|prepare leader meals
|0
|0
|330
|1
|yes
|no
|(5,0,1)
|yes
|no

|-
!CUSTOM_OFFICIAL_11
|yes
|housekeeper
|manage leader houshold cleanliness
|0
|0
|340
|1
|yes
|no
|(5,0,1)
|yes
|no

|-
!CUSTOM_MILITARY_STRATEGY
|no
|general/(field) marshal / constable
|military strategy
|3
|2
|50
|1
|yes
|yes
|(5,0,1)
|yes
|yes

|-
!CUSTOM_MILITARY_GOALS4
|no
|war leader
|military goals, optional: military strategy
|3
|2
|45
|1
|yes
|yes
|(5,0,1)
|no
|no
|}
: ''Note'':
:* 1) These are the standard official flags: duty_bound, has_responsibilities, do_not_cull, has_met_pop_req, color, menial_work_exemption, has_received_positions and has_met_market_req.
:* 2) These are the following additional flags: flashes, brag_on_kill, chat_worthy, kill_quest, account_exempt, punishment_exemption, quest_giver andspecial_burial.
:* 3): Name prefix can be empty.
:* 4) These would be the values for the CUSTOM_MILITARY_GOALS position, but on the civ-level that position is not created, as the military goals responsibility is already performed by the law-giver/master (and for the military strategy responsibility the CUSTOM_MILITARY_STRATEGY position is created instead). But a CUSTOM_MILITARY_GOALS position would be created, if the civ-leader would not have the military goals responsibility. The CUSTOM_MILITARY_GOALS position is - in vanilla - only created for site governments and then only, if the site leader is the FORCED_ADMINISTRATOR.
:* 5): Name prefixes are: high, head, chief and royal.

In the above table the responsibility "espionage" of the CUSTOM_OFFICIAL_1 is optional. Only if the CUSTOM_OFFICIAL_1 is created with the "espionage" responsibility such officials can also be created for the site governments (as all other responsibility are already performed by the standard custom site ruler). Also, the columns "human" and "goblin" dictate whether human and/or goblin civilizations can have the positions.

= Site Governments =
If all positions of a civ (and with that of a site government) are variable, then a leader position for the site government needs to be created (in world-gen), before other positions (of the possible variable positions) can be created. The created position is usually the CUSTOM_LAW_MAKER, but other positions have been found, ie. CUSTOM_BANDIT_LEADER and FORCED_ADMINISTRATOR.

Note that human and goblin civilizations can also create further site positions, if the current site leader is the FORCED_ADMINISTRATOR. All other races (eg. dwarves and elves) cannot.

The following table gives an overview of the non-ruler variable positions of a site government.

{| class="sortable wikitable" style="text-align:center;"
|- style="background:#F2F2F2;"
!Position!!Name first!!Name second !!Responsibilities!!Demands!!Mandates!!Precedence!!Number!!Color!!human!!goblin!!add. flags1

|-
!CUSTOM_MARKET_OFFICIAL_1
|sewer
|master / administrator / caretaker / commissioner / official
|maintain sewers
|0
|0
|500
|1
|(5,0,1)
|yes
|no
|no

|-
!CUSTOM_MARKET_OFFICIAL_2
|grain / harvest
|official / administrator / caretaker / commissioner
|food supply
|1
|0
|450
|1
|(5,0,1)
|yes
|no
|no

|-
!CUSTOM_MARKET_OFFICIAL_3
|fire
|administrator / official / commissioner
|fire safety
|0
|0
|475
|1
|(5,0,1)
|yes
|no
|no

|-
!CUSTOM_MARKET_OFFICIAL_4
|
|judge / magistrate / justice
|judge
|1
|0
|350
|1
|(5,0,1)
|yes
|no
|no

|-
!CUSTOM_MARKET_OFFICIAL_5
|building
|caretaker / administrator / official / commissioner
|construction permits, building safety
|1
|0
|460
|1
|(5,0,1)
|yes
|no
|no

|-
!CUSTOM_MARKET_OFFICIAL_6
|road
|administrator / official / commissioner
|maintain roads, bridges and tunnels
|1
|0
|375
|1
|(5,0,1)
|yes
|no
|no

|-
!CUSTOM_OFFICIAL_1
|(high / head / chief)
|"keeper of the seal" / chancellor
|espionage
|3
|2
|20
|1
|(5,0,1)
|yes
|yes
|no

|-
!CUSTOM_OFFICIAL_2
|(chief / head / high)
|justiciar
|collect taxes
|3
|2
|60
|1
|(5,0,1)
|yes
|no
|no

|-
!CUSTOM_OFFICIAL_3
|chief / high / head
|treasurer
|trade, accounting
|2
|1
|70
|1
|(5,0,1)
|yes
|no
|no

|-
!CUSTOM_OFFICIAL_4
|chief / high / head
|advisor / counselor
|advise leaders
|2
|1
|55
|1
|(5,0,1)
|yes
|yes
|no

|-
!CUSTOM_OFFICIAL_5
|(chief / high / head)
|chamberlain
|oversee leader houshold
|1
|0
|80
|1
|(5,0,1)
|yes
|yes
|no

|-
!CUSTOM_OFFICIAL_6
|
|master of beasts
|tame exotics, manage animals
|1
|0
|90
|1
|(5,0,1)
|yes
|yes
|no

|-
!CUSTOM_OFFICIAL_7
|chief / head / high
|butler / cup-bearer
|manage leader houshold food and drinks
|0
|0
|300
|1
|(5,0,1)
|yes
|no
|no

|-
!CUSTOM_OFFICIAL_8
|chief / high / head
|doctor
|health management
|0
|0
|310
|1
|(5,0,1)
|yes
|no
|no

|-
!CUSTOM_OFFICIAL_9
|head / high / chief
|executioner
|executions
|0
|0
|320
|1
|(5,0,1)
|yes
|yes
|no

|-
!CUSTOM_OFFICIAL_10
|chief / high / head
|chef
|prepare leader meals
|0
|0
|330
|1
|(5,0,1)
|yes
|no
|no

|-
!CUSTOM_OFFICIAL_11
|chief / head / high
|housekeeper
|manage leader houshold cleanliness
|0
|0
|340
|1
|(5,0,1)
|yes
|no
|no

|-
!CUSTOM_MILITARY_STRATEGY2
|
|general/(field) marshal / constable
|military strategy
|3
|2
|50
|1
|(5,0,1)
|yes
|no
|yes

|-
!CUSTOM_MILITARY_GOALS2
|
|war leader
|military goals, optional: military strategy
|3
|2
|45
|1
|(5,0,1)
|yes
|no
|yes

|}

: ''Notes'':
:* 1): The additional flags are: flashes, brag_on_kill, chat_worthy, kill_quest, account_exempt, punishment_exemption, quest_giver and special_burial.
:* 2): Only ever created, if the current site leader is a FORCED_ADMINISTRATOR.
:* In the above table the columns "human" and "goblin" donate, whether a site government of a human civilization or of a goblin civilization can have that position (or at least, if the position was encountered so far). Also the custom officials (CUSTOM_OFFICIAL_1 etc.), in contrast to market officials (CUSTOM_MARKET_OFFICIAL_1 etc.), seem to only be generated, if a) the parent civ did generate the position and b) the official has a responsibility that the site-ruler does not have.
:* In addtion to the above table the "best_appointment_precedence" is 30001. Also the following flags are set (true) for all officials, regardless, of whether belonging to a human or goblin site government: duty_bound, has_responsibilities, do_not_cull, has_met_pop_req, color, menial_work_exemption, has_received_positions and has_met_market_req.

Additionally the position entry usually has the flag active set and the flag is_replaced is false, otherwise the position would no longer be active (and might have been replaced).

= Bandits =
Bandits use the entity types 4 and 7, which are nomadic groups (type 4) and outcasts (type 7). It must also be noted that some CUSTOM_BANDIT_LEADER positions are used by site governments (typically goblin site governments) both with and without a parent civilization (site government is not a child of an entity of type 0).

The following table gives an overview over the possible variable positions used by bandits (some further info on bandit leaders is below the table).

{|class="sortable wikitable" style="text-align:center;"
|- style="background:#F2F2F2;"
!Position!!Name!!appointment type!!Responsibilities!!squad size!!Demands!!Mandates!!Precedence!!Number!!add. flags1!!rules from location!!entity type

|-
!CUSTOM_BANDIT_LEADER
|Boss, Captain, Chief, Chieftain, Commander, Leader, Master, Overlord, Ringleader or Warlord
|elected
|law making, law enforcement, receive diplomats, make introduction, make peace agreements, make topic agreements, military strategy and military goals
|20
|2
|1
|55
|1
|yes
|no
|nomadic, outcast

|-
!CUSTOM_BANDIT_LEADER2
|Boss, Captain, Chief, Chieftain, Commander, Leader, Master, Overlord, Ringleader or Warlord
|elected
|law making, law enforcement, receive diplomats, make introduction, make peace agreements, make topic agreements, military strategy and military goals
|20
|2
|1
|10
|1
|yes
|no
|nomadic

|-
!CUSTOM_OUTCAST_LT
|lieutenant
|appointed by bandit leader
|patrol territory, attack enemies
|0
|1
|0
|160
| -1
|no
|no
|outcast

|-
!CUSTOM_OUTCAST_FACTOR
|representative
|appointed by bandit leader
|trade and accounting
|0
|1
|0
|70
| -1
|yes (except is_law_maker)
|yes
|outcast

|}
: ''Notes'':
:* 1): Additional flags are: is_law_maker, flashes, brag_on_kill, chat_worthy, kill_quest, account_exempt and quest_giver
:* 2): Only difference to the other CUSTOM_BANDIT_LEADER is the increased precedence of 10, encountered in 11 of 148 bandit leaders (148 of 175 nomadic groups had leaders). The reason is of yet unknown, except that the CUSTOM_BANDIT_LEADER is also used by the goblin civilization (and some site governments, without an entity link to a parent civ, had a nomadic group with a custom bandit leader as a child entity).
:* Further note the common flags of these positions are: duty_bound, has_responsibilities, do_not_cull, is_leader, has_met_pop_req, menial_work_exemption, has_received_positions and has_met_market_req.
:* The entity type in the above table refers to the (as displayed by dfhack's gm-editor, when viewing an entity).

Additionally the bandit leader (CUSTOM_BANDIT_LEADER) always has a squad size of 20 and the squad members are refered to as "bandits".

= Religious Entities =
Some religious entities, which are considered "child"-entities of civilizations (no religious entity which was not a "child" of a civ entity has been found so far), also have variable positions.
If a religious entity rules a site (always monastery?), then the only variable position (of that entity) seems to be the CUSTOM_LAW_MAKER and the name of the position seems to be always "abbot".
Otherwise the variable positions PRIEST, HIGH_PRIEST and HIGHEST_PRIEST can be created for that religious entity, where any such entity, if it has a position, will always have the PRIEST as position. Afterwards, the position HIGH_PRIEST can be created and at last - after the HIGH_PRIEST was created - the HIGHEST_PRIEST can be created. The names of these position are randomly created (more about the name generation is currently out-of-scope, ie. why a PRIEST might be called "sacred squid", "holy burial", "sacred rumor", "holy lemon" or "sacred paper" is out-of-scope at least for this wiki-article). No temple is needed in an associated site for a religious entity (not ruling from a monastery) to create a priest, high priest or highest priest position.

An overview on the positions of religious entities is given in the following table:

{|class="sortable wikitable" style="text-align:center;"
|- style="background:#F2F2F2;"
!Position!!name prefix!!name!!appointment type5!!Responsibilities!!Precedence!!Demands!!Mandates!!number!!missing common flags1!!additional flags2

|-
!CUSTOM_LAW_MAKER3
|
|abbot
|heir
|law making, law enforcement, receive diplomats, make introductions, make peace agreements, make topic agreements, military strategy, military goals
|100
|3
|2
|1
|is_diplomat
|all

|-
!PRIEST
|holy or sacred
|random4
|elected
|religion
|200
|0
|0
| -1
|none
|no

|-
!HIGH_PRIEST
|high, first or exalted
|random4
|elected
|law_making, receive diplomats and make topic agreements
|50
|3
|2
| -1
|none
|all (except determines_coin_design)

|-
!HIGHEST_PRIEST
|absolute or most sacred/high/exalted
|random4
|elected
|law_making, receive diplomats and make topic agreements
|1
|5
|3
|1
|none
|all (except determines_coin_design)

|}

Notes:
1): The common flags are: duty_bound, has_responsibilities, chat_worty, do_not_cull, is_leader, is_diplomat, has_met_pop_req, rules_from_location, menial_work_exemption, punishment_exemption, has_received_positions and has_met_market_req. So if one of the flags is mentioned in a column, then the position does not have that flag.

2): The additional flags (in this case) are: is_law_maker, flashes, brag_on_kill, kill_quest, exported_in_legends, account_exempt, quest_giver, special_burial.

3): Is always the only position for that religious entity. And so far any such entity, which was found, always governed/ruled a monastary.

4): The name is one of the possible "name prefix" for the position written before a completly random word, which may or may not depend on the religious spheres/domains worshipped by that religion.

5): The appointment/succession type is actually determined by flags, ie. elected and succession_by_heir. One of the flags is also true for these positions (but not explictly mentioned in the common/additional flags).

Additional notes: The PRIEST, HIGH_PRIEST and HIGHEST_PRIEST have a variable color entry, but the color-flag (of the position entry) is false, so it is unclear, whether currently the color entry has any effect.

= Mercenary Group =

All mercenary entities will have at least one position (the CUSTOM_MERCENARY_LEADER). The only other possible position is the CUSTOM_MERCENARY_TREASURER.

Basic information about both positions are found in the table below (and the explanations below the table).

{|class="sortable wikitable" style="text-align:center;"
|- style="background:#F2F2F2;"
!Position!!Name!!appointment type!!Responsibilities!!Precedence!!Demands!!Mandates!!number!! imp. flags1

|-
!CUSTOM_MERCENARY_LEADER
|usually "warlord", "leader", "general" or "overlord" but very unusual names are possible (see below table)
|elected
|law making, law enforcement, receive diplomats, make introductions, make peace agreements, make topic agreements, military strategy, military goals
|50
|2
|1
|1
|yes

|-
!CUSTOM_MERCENARY_TREASURER
|treasurer
|elected
|trade and accounting
|160
|1
|0
|1
|no

|}

Notes: 1): The imp. flags are flashes, brag_on_kill, chat_worthy, punishment_exemption, kill_quest and quest giver.

Both positions also have the is_leader flag and the following flags: duty_bound, has_responsibilities, has_met_pop_req, menial_work_exemption, has_received_positions and has_met_market_req.

For the mercenary leader also illustrous names such as lord twinkle, lord duty, lord savant, maze commander or secret commander can be created. In these cases the name seems to be generated by either adding a random word after the word lord or adding a random word before commander.

= Guilds =
All guilds will always have all four of the variable positions mentioned in this section. Note that "merchant guilds" are merchant companies and an entirely separate entity.

The following table gives an overview of the four guild positions.

{|class="sortable wikitable" style="text-align:center;"
|- style="background:#F2F2F2;"
!Position!!Name!!appointment type!!Responsibilities!!precedence!!demands!!mandates!!number!!add. flags1

|-
!CUSTOM_GUILD_LEADER
|dean/doyen
|law making, law enforcement, receive diplomats, make introductions, make peace agreements, make topic agreements, military strategy, military goals
|elected
|50
|2
|1
|1
|yes

|-
!CUSTOM_GUILD_ALDERPERSON
|alderperson
|meet workers, manage production
|elected
|150
|1
|0
|1
|no

|-
!CUSTOM_GUILD_STEWARD
|steward or treasurer
|trade
|elected
|160
|1
|0
|1
|no

|-
!CUSTOM_GUILD_CLERK
|clerk, bookkeeper, recordkeeper
|accounting
|elected
|170
|1
|0
|1
|no

|}

Notes:
1): The additional flags are: is_law_maker, flashes, brag_on_kill; chat_worthy, do_not_cull, kill_quest, account_exempt, rules_from_location, punishment_exemption and quest_giver.

All positions have the following flags in common:
duty_bound, has_responsibilities, do_not_cull, is_leader, has_met_pop_req, menial_work_exemption, has_received_positions, has_met_market_positions.

= Merchant Company =
Every merchant company will have a leader (CUSTOM_COMPANY_LEADER). Furthermore a merchant company can have a CUSTOM_COMPANY_FACTOR, to which an unlimited number of history figures can be assigned to (ie. a company can have multiple governors).

An overview of both positions is given by the following table:

{|class="sortable wikitable" style="text-align:center;"
|- style="background:#F2F2F2;"
!Position!!name!!appointment type!!Responsibilities!!Precedence!!Demands!!Mandates!!number!!additional flag

|-
!CUSTOM_COMPANY_LEADER
|master or head
|elected or succession by heir
|law making, law enforcement, receive diplomats, make introductions, make peace agreements, make topic agreements, military goals, military strategy
|50
|2
|1
|1
|is_law_maker

|-
!CUSTOM_COMPANY_FACTOR
|agent, factor, administrator or governor
|appointed by company leader
|trade and accounting
|200
|1
|0
| -1
|none

|}

Both positions have the following flags in common:
duty_bound, has_responsibilities, flashes, brag_on_kill, chat_worthy, do_not_cull, kill_quest, is_leader, account_exempt, has_met_pop_req, rules_from_location, menial_work_exemption, punishment_exemption, has_received_positions, quest_giver and has_met_market_req.

Also note that in contrast to many other variable positions (of different entities) for the CUSTOM_COMPANY_LEADER both an election based appointment (or succession) and an succesion by heir is possible, but each merchant company will only have an elected leader or a leader (with inheritance).

= Raw tokens =
The tokens that manage the creation of positions are [[Entity_token#SITE_VARIABLE_POSITIONS|SITE_VARIABLE_POSITIONS]] and [[Entity_token#VARIABLE_POSITIONS|VARIABLE_POSITIONS]].

SITE_VARIABLE_POSITIONS allows for the creation of lords, hearthpersons, and [[boss]]es, and [VARIABLE_POSITIONS] allows creation of Law-makers.

Position token

2026-02-12T10:41:59Z

Joostheger: /* Position tokens */

{{Quality|Fine}}
{{av}}
{{Modding}}
Position tokens define [[noble]] positions for civilizations and site governments, inside [[entity token]]s. In the vanilla game, position token definitions can be found in <code>[[Game folder|<Dwarf Fortress>]]\data\vanilla\vanilla_entities\objects\entity_default.txt</code>.

__TOC__
{{clear}}

==Code==
A position is defined with a position 'code', as an argument in the [POSITION]-tag. The same code may be used multiple times, they don't have to be unique. This code is used as reference by APPOINTED_BY, SUCCESSION:BY_POSITION, REPLACE_BY and COMMANDER. 'MONARCH' is an example of this code.

==Position tokens==
These tokens belong in an entity definition, applying to a position (such as monarch) and should follow the [POSITION:POSITION_NAME] token.

{| {{prettytable}}
|- bgcolor="#dddddd"
! Token
! Arguments
! Description

|-
| {{text anchor|ACCOUNT_EXEMPT}}
|
| The position holder is not subjected to the [[Dwarven economy|economy]]. Less than relevant right now.

|-
| {{text anchor|ALLOWED_CLASS}}
| {{token|CREATURE_CLASS|creature}} token
| rowspan=2 | ALLOWED_CLASS: Only creatures with the specified [CREATURE_CLASS] token may be appointed to this position. Multiple entries are allowed. ALLOWED_CREATURE: Restricts the position to the specified creature and caste. Multiple entries are allowed. These tokens only apply within the entity’s own race (including its castes).
In world generation, they limit which units may be assigned to the position, but they do not prevent other creature types from acquiring the position through alternative means (for example, via a coup).
In fortress mode, these tokens are enforced during manual appointment and succession.
During world generation, if all allowed castes have a POP_RATIO of 0, a unit of an allowed caste will still be generated to fill the position.

|-
| {{text anchor|ALLOWED_CREATURE}}
| CREATURE:CASTE

|-
| {{text anchor|APPOINTED_BY}}
| position
| This position can only be chosen for the task from the nobles screen, and is available only if there is an *argument* present. For example, the GENERAL is [APPOINTED_BY:MONARCH]. Contrast [ELECTED]. Being appointed by a MONARCH seems to handle a lot of worldgen stuff, and interferes with fort mode titles. Multiple entries are allowed. If you have neither an ELECTED-token nor a APPOINTED_BY-token, the holder may always be changed (like the expedition leader).
''Read more: [[Advanced_Entity_Position_Mechanics#Appointment]]''

|-
| {{text anchor|BRAG_ON_KILL}}
|
| A creature that kills a member of this position will be sure to talk about it a lot.

|-
| {{text anchor|CHAT_WORTHY}}
|
| In adventure mode, when referencing locations, an NPC may mention this position holder living there or having done some deed there; it also means that the position exists in world-gen, rather than being created only at the end of world-gen.

|-
| {{text anchor|COLOR}}
| [[Color]]
| Creatures of this position will have this [[Color]], instead of their profession color, e.g. [COLOR:5:0:1]. It is also applied to the name of the citizen in the units-screen.

|-
| {{text anchor|COMMANDER}}
| position:ALL
| This position will act as a commander of the specified position{{verify}}. E.g. GENERAL is [COMMANDER:LIEUTENANT:ALL]. Unknown if values other than ALL work. Multiple entries are allowed.
''Read more: [[Army]]''

|-
| {{text anchor|CONQUERED_SITE}}
|
| This position is a puppet ruler, left behind in a conquered site.

|-
| {{text anchor|DEMAND_MAX}}
| number (0-100)
| How many demands the position can make of the population at one time.

|-
| {{text anchor|DESCRIPTION}}
| string. Readable up to 470 characters in the nobles' screen.
| description of this position in the nobles screen.

|-
| {{text anchor|DETERMINES_COIN_DESIGN}}
|
| The site's (or civ's) minted [[coin]]s, if any, will have images that reflect the personality of this position holder.

|-
| {{text anchor|DO_NOT_CULL}}
|
| The position won't be culled from Legends as "unimportant" during world generation.

|-
| {{text anchor|DUTY_BOUND}}
|
| Members of this position will never agree to 'join' your character during adventure mode. They also don't settle anywhere else but in the capital, and will not [[immigration|emigrate]] from their site. If they are not DUTY_BOUND, they will live anywhere as they like.

|-
| {{text anchor|ELECTED}}
|
| The population will periodically select the most skill-eligible creature to fill this position for site-level positions at the player's fort. For responsibilities or positions that use more than one skill, no skill takes priority in electing a creature: an accomplished comedian is more qualified for the TRADE responsibility than a skilled appraiser. A creature may be elected to multiple positions at the same time. Contrast [APPOINTED_BY].
''More info: [[Elections]]''
''Read more: [[Advanced_Entity_Position_Mechanics#Elections]]''

|-
| {{text anchor|EXECUTION_SKILL}}
| weapon skill
| A mandatory sub-tag of [RESPONSIBILITY:EXECUTIONS]. Determines the weapon chosen by the executioner for their work.

|-
| {{text anchor|EXPORTED_IN_LEGENDS}}
|
| The various members who have filled this role will be listed in the civilisation's history.

|-
| {{text anchor|FLASHES}}
|
| The creature holding this position will visibly flash, like legendary citizens. Represents a properly noble station by default.

|-
| {{text anchor|GENDER}}
| male/female
| The position can only be held by the specified gender. Currently bugged {{bug|2714}}

|-
| {{text anchor|KILL_QUEST}}
|
| The position can assign quests to adventurers.

|-
| {{text anchor|LAND_HOLDER}}
| importance tier (1-10)
| This is an alternative to SITE, allowing positions to be created at civ-level 'as needed' for all sites that meet the requirements to have them, which are the values set in [[Difficulty#Land_holder|land holder difficulty]] [[settings]]. The character is tied permanently to a particular site, but also operates at the civ-level.
''Read more: [[Advanced_Entity_Position_Mechanics#land holders]]''

|-
| {{text anchor|LAND_NAME}}
| string. Readable up to 21 characters in the nobles' screen.
| The name the area takes on when under the control of a LAND_HOLDER. E.g. for the DUKE, [LAND_NAME:a duchy]. If the position is not a [[LAND_HOLDER]], the land_name is still displayed left of the position in the nobles menu.

|-
| {{text anchor|MANDATE_MAX}}
| number (0-100)
| The maximum number of mandates the position can make at once.

|-
| {{text anchor|MENIAL_WORK_EXEMPTION}}
|
| The position holder cannot be assigned labors. It only works for [SITE]-positions.

|-
| {{text anchor|MENIAL_WORK_EXEMPTION_SPOUSE}}
|
| The spouse of the position holder doesn't have to work, either - see above.
|-
| {{text anchor|MILITARY_SCREEN_ONLY}}
|
| This position cannot be appointed from the nobles screen. Intended for militia captains and other squad leaders to reduce clutter. Currently nonfunctional{{bug|8965}}

|-
| {{text anchor|NAME}}
| singular:plural. Readable up to 21 characters in the nobles' screen and up to 30 in the unit list.
| The name of the position.

|-
| {{text anchor|NAME_MALE}}
| singular:plural. Readable up to 21 characters in the nobles' screen and up to 30 in the unit list.
| If the creature holding the position is male, this is the position's name. E.g. for MONARCH, [NAME_MALE:king:kings]

|-
| {{text anchor|NAME_FEMALE}}
| singular:plural. Readable up to 21 characters in the nobles' screen and up to 30 in the unit list.
| If the creature holding the position is female, this is the position's name. E.g. for MONARCH, [NAME_FEMALE:queen:queens]

|-
| {{text anchor|NUMBER}}
|
* number/AS_NEEDED
| How many of the position there should be. If the [SITE] token exists, this is per site, otherwise this is per civilisation. AS_NEEDED applies mainly to positions involved with the military command chain; this is used to allow armies to expand to whatever size they need to be. Other non-military positions like the land_holders or the [[messenger]] with NUMBER:AS_NEEDED will also be appointed.
The problem with [[Lieutenant]]s and [[Captain]]s not being created, is their AS_NEEDED number. They are only then created when they're needed, and that has some pretty unusual conditions. When a fixed number is used, they are appointed with the creation of the civ.
If the NUMBER is set at a fixed value higher than 1, the position is always filled up full. If the position is available on embark, it is completely filled up with only the first dwarf.

|-
| {{text anchor|PRECEDENCE}}
| number (0-30000)/NONE
| How important the position is in society; a lower number is more important and displayed higher in the Nobles menu. For MONARCH it's 1, for MILITIA_CAPTAIN it's 200. The game marks the first non-[SITE] position with [PRECEDENCE:1] as the ruler, for both embark screen and mountainhome purposes. When it is empty, [REPLACED_BY] another position, or not yet created because of [REQUIRES_POPULATION], the screen just says 'None' as the holders' name. Landholders can become the ruler, if they are the first defined position with precedence of 1. civ-position can also be created without precedence. Positions may have the same precedence and will be appointed, although the effect is unknown. Precedence has no effect on who's doing the job, if both positions have the same responsibilities.

|-
| {{text anchor|PUNISHMENT_EXEMPTION}}
|
| The position holder will not be held accountable for his or her crimes. Currently nonfunctional.{{bug|4589}}{{verify|seems to prevent punishment when they are convicted of actual crime}}

|-
| {{text anchor|QUEST_GIVER}}
|
| The position holder can give quests in Adventure mode. Functionality in 0.31.13 and later is uncertain.

|-
| {{text anchor|REJECTED_CLASS}}
| CREATURE_CLASS Token
| Creatures of the specified class cannot be appointed to this position. Multiple entries are allowed

|-
| {{text anchor|REJECTED_CREATURE}}
| CREATURE:CASTE
| Restricts position holders by CREATURE type. Multiple entries are allowed. It doesn't seem to work in world-gen. When checking Legends mode, units are seen assigned this position regardless of their creature-type or caste. It does work in Fortress mode.

|-
| {{text anchor|REPLACED_BY}}
| position
| This position is absorbed by another down the line. For example, expedition leader is [REPLACED_BY:MAYOR]. Only a single entry is allowed.

|-
| {{text anchor|REQUIRED_BEDROOM}}
| number (0-1000000)
| The position holder requires a bedroom with at least this value.

|-
| {{text anchor|REQUIRED_BOXES}}
| number (0-100)
| The position holder requires at least this many boxes.

|-
| {{text anchor|REQUIRED_CABINETS}}
| number (0-100)
| The position holder requires at least this many cabinets.

|-
| {{text anchor|REQUIRED_DINING}}
| number (0-1000000)
| The position holder requires a dining room with at least this value.

|-
| {{text anchor|REQUIRED_OFFICE}}
| number (0-1000000)
| The position holder requires an office with at least this value.

|-
| {{text anchor|REQUIRED_RACKS}}
| number (0-100)
| The position holder requires at least this many weapon racks.

|-
| {{text anchor|REQUIRED_STANDS}}
| number (0-100)
| The position holder requires at least this many armour stands.

|-
| {{text anchor|REQUIRED_TOMB}}
| number (0-1000000)
| The position holder requires a tomb with at least this value.

|-
| {{text anchor|REQUIRES_MARKET}}
|
| Does not have anything directly to do with markets. It means that in minor sites (such as hillocks) the position will not appear, while in major sites (such as dwarf fortresses) it will.

|-
| {{text anchor|REQUIRES_POPULATION}}
| number
| The position requires the population to be at least this number before it becomes available, or before the position holder will move in.

|-
| {{text anchor|RESPONSIBILITY}}
| responsibility
| The position holder does a thing. See the table below for suitable arguments. A position does not need to have a responsibility.

|-
| {{text anchor|RULES_FROM_LOCATION}}
|
| If there is a special location set aside for rulers, such as a human castle/mead hall, the position holder will always be found at that particular location. Does nothing for dwarven nobles, because at present, dwarves have no such special locations.

|-
| {{text anchor|SITE}}
|
| Every site government will have the defined number of this position instead of the whole civilization; provided that other criteria (if any) are met. Unless LAND_HOLDER is present instead, the defined number of the position will be created only for the civilization as a whole.

|-
| {{text anchor|SLEEP_PRETENSION}}
|
| The position holder will get upset if someone with a higher PRECEDENCE holds quarters with a greater value than their own.

|-
| {{text anchor|SPECIAL_BURIAL}}
|
| The civilization will inter the corpse of the position holder in a special grave, either in catacombs or in monuments. If that grave is disturbed, the position holder can return as a [[mummy]]. {{verify}}

|-
| {{text anchor|SPOUSE}}
| singular:plural. Readable up to 30 characters in the unit list.
| The name of the position holder's spouse.

|-
| {{text anchor|SPOUSE_FEMALE}}
| singular:plural. Readable up to 30 characters in the unit list.
| If the spouse of the creature holding the position is female, this is the spouse's position name.

|-
| {{text anchor|SPOUSE_MALE}}
| singular:plural. Readable up to 30 characters in the unit list.
| If the spouse of the creature holding the position is male, this is the spouse's position name.

|-
| {{text anchor|SQUAD}}
| number:singular:plural
| The position holder is authorized to form a military squad, led by themselves using the [[leader]] and [[military tactics]] skills. The number denotes the maximum headcount. The noun used to describe the subordinates (e.g. royal guard) is used in adventure mode for the adventurer. This token is used together with [RESPONSIBILITY:LAW_ENFORCEMENT] for giving [[quest]]s to adventurers as [[Hearthperson|hearthpeople]]. Further details: [[Advanced_entity_position_mechanics#Military]]

|-
| {{text anchor|SUCCESSION}}
|
* BY_HEIR / BY_POSITION:position
| How a new position holder is chosen. A single position can have multiple BY_POSITION tokens. See [[Noble]] for more information on how succession is handled in the game.
The SUCCESSION-Tag is also considered when a new positions opens up, for example when a required population number is reached. If a valid successor is available, they will be the one taking that position initially, without appointment or election.

|}

== Responsibilities ==
{| {{prettytable}}
|- bgcolor="#dddddd"
! Argument
! Description

|-
| {{text anchor|ACCOUNTING}}
| Found on [[bookkeeper]]. Position will use [[record keeper]] skill to keep track of stocks.

|-
| {{text anchor|ADVISE_LEADERS}}
|

|-
| {{text anchor|ATTACK_ENEMIES}}
| Found on elven [[ranger captain]] and human warrior. Effect unknown.{{verify}}

|-
| {{text anchor|BUILD_MORALE}}
| Found on [[champion]]. Citizens get a special thought for "talking to a pillar of society" when speaking to this noble.

|-
| {{text anchor|BUILDING_SAFETY}}
|

|-
| {{text anchor|COLLECT_TAXES}}
| Currently unused - was originally assigned to the tax collector.

|-
| {{text anchor|CONSTRUCTION_PERMITS}}
|

|-
| {{text anchor|DELIVER_MESSAGES}}
| Found on [[messenger]]. Position travels to other sites and uses [[social skill]]s.
|

|-
| {{text anchor|EQUIPMENT_MANIFESTS}}
| Currently unused - was originally assigned to the arsenal dwarf.

|-
| {{text anchor|ESCORT_TAX_COLLECTOR}}
| Currently unused - was originally assigned to the Royal Guards (squad members beneath the Hammerer).

|-
| {{text anchor|ESPIONAGE}}
| Found on [[dungeon master]] and the [[Elf|elven]] [[General|princess]] and uses the [[schemer]] skill.

|-
| {{text anchor|ESTABLISH_COLONY_TRADE_AGREEMENTS}}
| Found on [[outpost liaison]]. Position travels with the caravan and uses [[social skill]]s to make trade agreements with any settlements that it visits, provided they are domestic, report the news and promote {{token|LAND_HOLDER|e}} positions. Also reports recent news. Presumably has no effect at site level. Crucially, it does not visit foreign settlements, but the civ-level TRADE position does the exact same thing in its position. They arrive the same time as the caravan arrives, and this can thus be modded by setting {{token|ACTIVE_SEASON|e}}

|-
| {{text anchor|EXECUTIONS}}
| Found on [[hammerer]]. Position executes death penalty judgements with a weapon of the appropriate skill. Cannot be combined with LAW_ENFORCEMENT, resulting in the "Invalid Officer"-error.

|-
| {{text anchor|FIRE_SAFETY}}
|

|-
| {{text anchor|FOOD_SUPPLY}}
|

|-
| {{text anchor|HEALTH_MANAGEMENT}}
| Found on [[chief medical dwarf]]. Position will use [[diagnostician]] skill to evaluate [[wounds]] and schedule [[Health care|treatment]], reported in each citizen's Health tab.

|-
| {{text anchor|JUDGE}}
|

|-
| {{text anchor|LAW_ENFORCEMENT}}
| Found on [[sheriff]]/[[captain of the guard]]. Position and its subordinates are in charge of punishing criminals. A {{token|SITE|position}} position holding this responsibility plus the {{token|SQUAD|position}} token (or allowing the entity to have a {{token|SITE_VARIABLE_POSITIONS|e}} with this responsibility) is required for an adventurer from a given civilization to start as a [[hearthperson]], [[Captain of the guard|fortress guard]], etc. Cannot be combined with EXECUTIONS, resulting in the "Invalid Officer"-error.

|-
| {{text anchor|LAW_MAKING}}
| Found on [[monarch]]s and [[:Category:Aristocrats|nobles]]. Will be referred to as the leader of the site in adventure mode and they may designate the site as being the capital city for civ-level positions. This position is in charge of creating procedural positions, corresponding to either {{token|VARIABLE_POSITIONS|e}} or {{token|SITE_VARIABLE_POSITIONS|e}}. Position-holders that have attained [[immortality]] may issue oppressive edicts to protect themselves against suspicion.

|-
| {{text anchor|MAINTAIN_BRIDGES}}
|

|-
| {{text anchor|MAINTAIN_ROADS}}
|

|-
| {{text anchor|MAINTAIN_SEWERS}}
|

|-
| {{text anchor|MAINTAIN_TUNNELS}}
|

|-
| {{text anchor|MAKE_INTRODUCTIONS}}
| Position will make a 'social call' to an established foreign settlement, complimenting or insulting them depending on relations and reporting the news.

|-
| {{text anchor|MAKE_PEACE_AGREEMENTS}}
| Found on diplomat. Position negotiates peace treaties in order to end wars.

|-
| {{text anchor|MAKE_TOPIC_AGREEMENTS}}
| Found on [[diplomat]]. Position negotiates special agreements, such as tree cutting quotas. Used when elevating a settlement in the {{token|LAND_HOLDER|position}} chain up from level 1.

|-
| {{text anchor|MANAGE_ANIMALS}}
| Found on [[dungeon master]].

|-
| {{text anchor|MANAGE_LEADER_HOUSEHOLD_CLEANLINESS}}
|

|-
| {{text anchor|MANAGE_LEADER_HOUSEHOLD_DRINKS}}
|

|-
| {{text anchor|MANAGE_LEADER_HOUSEHOLD_FOOD}}
|

|-
| {{text anchor|MANAGE_PRODUCTION}}
| Found on [[manager]]. Position enables the use of workshop profiles and uses the [[organizer]] skill to process work orders entered in the job manager after the fortress population reaches 20.

|-
| {{text anchor|MEET_WORKERS}}
| Found on [[expedition leader]]/[[mayor]]. Position uses the various [[social skill]]s to hold meetings with unhappy citizens and try to pacify them with happy thoughts. In adventure mode, [SITE] positions with this responsibility handle petitions to make the player a performer for the local government.

|-
| {{text anchor|MILITARY_GOALS}}
| Found on [[monarch]]/[[:Category:Aristocrats|landholder]]/[[:Category:Elected Nobles|leaders]]. Character is in charge of going to war and making peace for the government they work for. Without a position with this responsibility at civ level the civilization will not be able to make peace and its sites will wage war on each other constantly, and as a result, all viable civilizations must have one leader with this tag at civ level. This appears not to be a problem for [[kobold]]s, presumably due to the {{token|SKULKING|e}}. If no position has this responsibility in fortress mode, players are unable to start [[missions]].

|-
| {{text anchor|MILITARY_STRATEGY}}
| Found on [[general]]/[[militia commander]]. Means that they will command the armies of their site or civilization. Issues the orders for the teams conducting raids or other operations away from the fortress. During worldgen, position will go on expeditions to tame exotic creatures. Counterintuitively not by the TAME_EXOTICS-position. The destinations of these expeditions are determined by the entities USE_(...)_ANIMALS-tokens.

|-
| {{text anchor|OVERSEE_LEADER_HOUSEHOLD}}
|

|-
| {{text anchor|PATROL_TERRITORY}}
| Found on elven ranger captain. Effect unknown.{{verify}}

|-
| {{text anchor|PREPARE_LEADER_MEALS}}
|

|-
| {{text anchor|RECEIVE_DIPLOMATS}}
| Found on [[monarch]]/[[:Category:Aristocrats|landholder]]/[[:Category:Elected Nobles|leaders]]. Position uses the various social skills to hold meetings with incoming diplomats and liaisons.

|-
| {{text anchor|RELIGION}}
| Found on elven [[druid]] and uses [[social skill]]s. Position informs you about worship cults{{verify}}

|-
| {{text anchor|SORT_AMMUNITION}}
| Currently unused - was originally assigned to the arsenal dwarf.

|-
| {{text anchor|TAME_EXOTICS}}
| Position will tame animals with the {{token|PET_EXOTIC}} token. Currently unused - was originally assigned to the dungeon master. Expeditions to tame exotic creatures will be done by the MILITARY_STRATEGY-position

|-
| {{text anchor|TRADE}}
| Found on [[broker]]. Position will use Appraisal skill to display value estimates and the various Social skills to trade at the depot. When applied to other civilizations, this position will arrive with the caravan to make trade agreements (like the Human Guild Representative from older versions) and behaves otherwise like the civ's own ESTABLISH_COLONY_TRADE_AGREEMENTS position holder. They arrive the same time as the caravan arrive and this can thus be modded by setting {{token|ACTIVE_SEASON|e}}

|-
| {{text anchor|UPGRADE_SQUAD_EQUIPMENT}}
| Currently unused - was originally assigned to the arsenal dwarf.

|}

== Related tokens ==
The following two ENTITY tokens are not actually position tokens, but bear mentioning on this page because they can modify the way that a civilization's positions behave:

{| {{prettytable}}
|- bgcolor="#dddddd"
! Token
! Arguments
! Description

|-
| {{text anchor|VARIABLE_POSITIONS}}
| Position responsibility or ALL
| Allows a responsibility to be taken up by a dynamically generated position (such as Law-maker).

|}

== Why won't my positions appear? ==
The way DF determines what positions will actually ''appear'' in your fortress is somewhat counter-intuitive and fairly limiting. This guide should help you understand what you can do to actually get your positions working properly.

There are five tokens governing which positions appear in your fortress - LAND_HOLDER, REQUIRES_POPULATION, APPOINTED_BY, ELECTED, and REPLACED_BY. The first two determine when your fortress is eligible for a new position, the next two determine how a new position for which your fortress is eligible can be added, and the fifth allows you to clear up obsolete positions. Unfortunately, they also interact in some strange ways that makes creating interesting position structures difficult.

When you start a new fortress, DF compiles a list of your initial positions. To do this, it looks at the requirements for each position - any position whose only requirement is less than seven dwarves (either because they have no requirement tokens, or because their only requirement tokens are [REQUIRES_POPULATION: =< 7] or [LAND_HOLDER:some trigger whose only requirement is some number of dwarves equal to or less than 7]). Most importantly, ''any'' position whose only requirement is a LAND_HOLDER requirement, regardless of what the trigger for that requirement is, will be added if another eligible starting position is REPLACED_BY it. '''A non-LAND_HOLDER position that is REPLACED_BY a LAND_HOLDER position will never appear.''' With this list compiled, the game culls all positions that are REPLACED_BY another eligible position, and then culls all positions that have the APPOINTED_BY token. '''You may not embark with any appointed positions.''' Any remaining positions are then filled by a dwarf chosen at random.

'''Positions do not automatically appear when you reach their requirements.''' For example, if you remove the ELECTED token from the Mayor, then the Mayor will never appear, even once you reach their required number of dwarves. '''For a position that does not appear at embark to appear in your fortress, it must be APPOINTED_BY another position or ELECTED.'''

Naturally, this is more complicated than it looks. '''APPOINTED_BY positions must be appointed by another position already in your fortress, or a civ-level position. Only LAND_HOLDER positions may be appointed by civ-level positions.''' LAND_HOLDER positions that are APPOINTED_BY civ-level positions are inherently tied to civ-level tokens with the ESTABLISH_COLONY_TRADE_AGREEMENTS responsibility. If a fortress meets the LAND_HOLDER_TRIGGER for a new LAND_HOLDER tier when a caravan leaves, then the next time the outpost liaison or equivalent arrives, they will offer to make you an official colony, which will allow you to select all positions for that LAND_HOLDER level. '''Each time they appear, the outpost liaison will only promote your fortress one tier up the LAND_HOLDER track.''' The biggest problem with this system is that you may set your LAND_HOLDER_TRIGGERS such that you are eligible for the first tier of LAND_HOLDER positions at embark. '''If you are eligible for the first tier of LAND_HOLDER positions at embark, then all first-tier positions will appear twice - once at embark, and again when the outpost liaison comes to appoint you to the first tier.'''

If civ-positions are neither APPOINTED_BY nor ELECTED, they still will be filled.

Read more: [[Advanced_Entity_Position_Mechanics]]

{{Category|Modding}}
{{Category|Tokens}}
[[ru:Position token]]

Talk:Army

2026-02-12T09:08:48Z

Joostheger:

Could we get a screenshot of different types of army on the Adventure travel map?

[[User:DPhKraken|DPhKraken]] ([[User talk:DPhKraken|talk]]) 22:16, 3 December 2024 (UTC)

I have tried to force a lieutenant to be appointed, but to no avail. I removed all other commanders and limit stricktly that this was the only position that had even a squad. I made the civ much more aggresive, nothing worked.
[[User:Joostheger|Joostheger]] ([[User talk:Joostheger|talk]]) 09:08, 12 February 2026 (UTC)

Position token

2026-02-12T09:05:53Z

Joostheger: /* Position tokens */

{{Quality|Fine}}
{{av}}
{{Modding}}
Position tokens define [[noble]] positions for civilizations and site governments, inside [[entity token]]s. In the vanilla game, position token definitions can be found in <code>[[Game folder|<Dwarf Fortress>]]\data\vanilla\vanilla_entities\objects\entity_default.txt</code>.

__TOC__
{{clear}}

==Code==
A position is defined with a position 'code', as an argument in the [POSITION]-tag. The same code may be used multiple times, they don't have to be unique. This code is used as reference by APPOINTED_BY, SUCCESSION:BY_POSITION, REPLACE_BY and COMMANDER. 'MONARCH' is an example of this code.

==Position tokens==
These tokens belong in an entity definition, applying to a position (such as monarch) and should follow the [POSITION:POSITION_NAME] token.

{| {{prettytable}}
|- bgcolor="#dddddd"
! Token
! Arguments
! Description

|-
| {{text anchor|ACCOUNT_EXEMPT}}
|
| The position holder is not subjected to the [[Dwarven economy|economy]]. Less than relevant right now.

|-
| {{text anchor|ALLOWED_CLASS}}
| {{token|CREATURE_CLASS|creature}} token
| rowspan=2 | ALLOWED_CLASS: Only creatures with the specified {{token|CREATURE_CLASS|creature}} token can be appointed to this position. Multiple entries are allowed. ALLOWED_CREATURE: Restricts the position to only the defined [[caste]]. Multiple entries are allowed. Only works with a creature (and caste) of the entity's current race, but does not prevent other creature-types from gaining that position, at least not in world-gen.

|-
| {{text anchor|ALLOWED_CREATURE}}
| CREATURE:CASTE

|-
| {{text anchor|APPOINTED_BY}}
| position
| This position can only be chosen for the task from the nobles screen, and is available only if there is an *argument* present. For example, the GENERAL is [APPOINTED_BY:MONARCH]. Contrast [ELECTED]. Being appointed by a MONARCH seems to handle a lot of worldgen stuff, and interferes with fort mode titles. Multiple entries are allowed. If you have neither an ELECTED-token nor a APPOINTED_BY-token, the holder may always be changed (like the expedition leader).
''Read more: [[Advanced_Entity_Position_Mechanics#Appointment]]''

|-
| {{text anchor|BRAG_ON_KILL}}
|
| A creature that kills a member of this position will be sure to talk about it a lot.

|-
| {{text anchor|CHAT_WORTHY}}
|
| In adventure mode, when referencing locations, an NPC may mention this position holder living there or having done some deed there; it also means that the position exists in world-gen, rather than being created only at the end of world-gen.

|-
| {{text anchor|COLOR}}
| [[Color]]
| Creatures of this position will have this [[Color]], instead of their profession color, e.g. [COLOR:5:0:1]. It is also applied to the name of the citizen in the units-screen.

|-
| {{text anchor|COMMANDER}}
| position:ALL
| This position will act as a commander of the specified position{{verify}}. E.g. GENERAL is [COMMANDER:LIEUTENANT:ALL]. Unknown if values other than ALL work. Multiple entries are allowed.
''Read more: [[Army]]''

|-
| {{text anchor|CONQUERED_SITE}}
|
| This position is a puppet ruler, left behind in a conquered site.

|-
| {{text anchor|DEMAND_MAX}}
| number (0-100)
| How many demands the position can make of the population at one time.

|-
| {{text anchor|DESCRIPTION}}
| string. Readable up to 470 characters in the nobles' screen.
| description of this position in the nobles screen.

|-
| {{text anchor|DETERMINES_COIN_DESIGN}}
|
| The site's (or civ's) minted [[coin]]s, if any, will have images that reflect the personality of this position holder.

|-
| {{text anchor|DO_NOT_CULL}}
|
| The position won't be culled from Legends as "unimportant" during world generation.

|-
| {{text anchor|DUTY_BOUND}}
|
| Members of this position will never agree to 'join' your character during adventure mode. They also don't settle anywhere else but in the capital, and will not [[immigration|emigrate]] from their site. If they are not DUTY_BOUND, they will live anywhere as they like.

|-
| {{text anchor|ELECTED}}
|
| The population will periodically select the most skill-eligible creature to fill this position for site-level positions at the player's fort. For responsibilities or positions that use more than one skill, no skill takes priority in electing a creature: an accomplished comedian is more qualified for the TRADE responsibility than a skilled appraiser. A creature may be elected to multiple positions at the same time. Contrast [APPOINTED_BY].
''More info: [[Elections]]''
''Read more: [[Advanced_Entity_Position_Mechanics#Elections]]''

|-
| {{text anchor|EXECUTION_SKILL}}
| weapon skill
| A mandatory sub-tag of [RESPONSIBILITY:EXECUTIONS]. Determines the weapon chosen by the executioner for their work.

|-
| {{text anchor|EXPORTED_IN_LEGENDS}}
|
| The various members who have filled this role will be listed in the civilisation's history.

|-
| {{text anchor|FLASHES}}
|
| The creature holding this position will visibly flash, like legendary citizens. Represents a properly noble station by default.

|-
| {{text anchor|GENDER}}
| male/female
| The position can only be held by the specified gender. Currently bugged {{bug|2714}}

|-
| {{text anchor|KILL_QUEST}}
|
| The position can assign quests to adventurers.

|-
| {{text anchor|LAND_HOLDER}}
| importance tier (1-10)
| This is an alternative to SITE, allowing positions to be created at civ-level 'as needed' for all sites that meet the requirements to have them, which are the values set in [[Difficulty#Land_holder|land holder difficulty]] [[settings]]. The character is tied permanently to a particular site, but also operates at the civ-level.
''Read more: [[Advanced_Entity_Position_Mechanics#land holders]]''

|-
| {{text anchor|LAND_NAME}}
| string. Readable up to 21 characters in the nobles' screen.
| The name the area takes on when under the control of a LAND_HOLDER. E.g. for the DUKE, [LAND_NAME:a duchy]. If the position is not a [[LAND_HOLDER]], the land_name is still displayed left of the position in the nobles menu.

|-
| {{text anchor|MANDATE_MAX}}
| number (0-100)
| The maximum number of mandates the position can make at once.

|-
| {{text anchor|MENIAL_WORK_EXEMPTION}}
|
| The position holder cannot be assigned labors. It only works for [SITE]-positions.

|-
| {{text anchor|MENIAL_WORK_EXEMPTION_SPOUSE}}
|
| The spouse of the position holder doesn't have to work, either - see above.
|-
| {{text anchor|MILITARY_SCREEN_ONLY}}
|
| This position cannot be appointed from the nobles screen. Intended for militia captains and other squad leaders to reduce clutter. Currently nonfunctional{{bug|8965}}

|-
| {{text anchor|NAME}}
| singular:plural. Readable up to 21 characters in the nobles' screen and up to 30 in the unit list.
| The name of the position.

|-
| {{text anchor|NAME_MALE}}
| singular:plural. Readable up to 21 characters in the nobles' screen and up to 30 in the unit list.
| If the creature holding the position is male, this is the position's name. E.g. for MONARCH, [NAME_MALE:king:kings]

|-
| {{text anchor|NAME_FEMALE}}
| singular:plural. Readable up to 21 characters in the nobles' screen and up to 30 in the unit list.
| If the creature holding the position is female, this is the position's name. E.g. for MONARCH, [NAME_FEMALE:queen:queens]

|-
| {{text anchor|NUMBER}}
|
* number/AS_NEEDED
| How many of the position there should be. If the [SITE] token exists, this is per site, otherwise this is per civilisation. AS_NEEDED applies mainly to positions involved with the military command chain; this is used to allow armies to expand to whatever size they need to be. Other non-military positions like the land_holders or the [[messenger]] with NUMBER:AS_NEEDED will also be appointed.
The problem with [[Lieutenant]]s and [[Captain]]s not being created, is their AS_NEEDED number. They are only then created when they're needed, and that has some pretty unusual conditions. When a fixed number is used, they are appointed with the creation of the civ.
If the NUMBER is set at a fixed value higher than 1, the position is always filled up full. If the position is available on embark, it is completely filled up with only the first dwarf.

|-
| {{text anchor|PRECEDENCE}}
| number (0-30000)/NONE
| How important the position is in society; a lower number is more important and displayed higher in the Nobles menu. For MONARCH it's 1, for MILITIA_CAPTAIN it's 200. The game marks the first non-[SITE] position with [PRECEDENCE:1] as the ruler, for both embark screen and mountainhome purposes. When it is empty, [REPLACED_BY] another position, or not yet created because of [REQUIRES_POPULATION], the screen just says 'None' as the holders' name. Landholders can become the ruler, if they are the first defined position with precedence of 1. civ-position can also be created without precedence. Positions may have the same precedence and will be appointed, although the effect is unknown. Precedence has no effect on who's doing the job, if both positions have the same responsibilities.

|-
| {{text anchor|PUNISHMENT_EXEMPTION}}
|
| The position holder will not be held accountable for his or her crimes. Currently nonfunctional.{{bug|4589}}{{verify|seems to prevent punishment when they are convicted of actual crime}}

|-
| {{text anchor|QUEST_GIVER}}
|
| The position holder can give quests in Adventure mode. Functionality in 0.31.13 and later is uncertain.

|-
| {{text anchor|REJECTED_CLASS}}
| CREATURE_CLASS Token
| Creatures of the specified class cannot be appointed to this position. Multiple entries are allowed

|-
| {{text anchor|REJECTED_CREATURE}}
| CREATURE:CASTE
| Restricts position holders by CREATURE type. Multiple entries are allowed. It doesn't seem to work in world-gen. When checking Legends mode, units are seen assigned this position regardless of their creature-type or caste. It does work in Fortress mode.

|-
| {{text anchor|REPLACED_BY}}
| position
| This position is absorbed by another down the line. For example, expedition leader is [REPLACED_BY:MAYOR]. Only a single entry is allowed.

|-
| {{text anchor|REQUIRED_BEDROOM}}
| number (0-1000000)
| The position holder requires a bedroom with at least this value.

|-
| {{text anchor|REQUIRED_BOXES}}
| number (0-100)
| The position holder requires at least this many boxes.

|-
| {{text anchor|REQUIRED_CABINETS}}
| number (0-100)
| The position holder requires at least this many cabinets.

|-
| {{text anchor|REQUIRED_DINING}}
| number (0-1000000)
| The position holder requires a dining room with at least this value.

|-
| {{text anchor|REQUIRED_OFFICE}}
| number (0-1000000)
| The position holder requires an office with at least this value.

|-
| {{text anchor|REQUIRED_RACKS}}
| number (0-100)
| The position holder requires at least this many weapon racks.

|-
| {{text anchor|REQUIRED_STANDS}}
| number (0-100)
| The position holder requires at least this many armour stands.

|-
| {{text anchor|REQUIRED_TOMB}}
| number (0-1000000)
| The position holder requires a tomb with at least this value.

|-
| {{text anchor|REQUIRES_MARKET}}
|
| Does not have anything directly to do with markets. It means that in minor sites (such as hillocks) the position will not appear, while in major sites (such as dwarf fortresses) it will.

|-
| {{text anchor|REQUIRES_POPULATION}}
| number
| The position requires the population to be at least this number before it becomes available, or before the position holder will move in.

|-
| {{text anchor|RESPONSIBILITY}}
| responsibility
| The position holder does a thing. See the table below for suitable arguments. A position does not need to have a responsibility.

|-
| {{text anchor|RULES_FROM_LOCATION}}
|
| If there is a special location set aside for rulers, such as a human castle/mead hall, the position holder will always be found at that particular location. Does nothing for dwarven nobles, because at present, dwarves have no such special locations.

|-
| {{text anchor|SITE}}
|
| Every site government will have the defined number of this position instead of the whole civilization; provided that other criteria (if any) are met. Unless LAND_HOLDER is present instead, the defined number of the position will be created only for the civilization as a whole.

|-
| {{text anchor|SLEEP_PRETENSION}}
|
| The position holder will get upset if someone with a higher PRECEDENCE holds quarters with a greater value than their own.

|-
| {{text anchor|SPECIAL_BURIAL}}
|
| The civilization will inter the corpse of the position holder in a special grave, either in catacombs or in monuments. If that grave is disturbed, the position holder can return as a [[mummy]]. {{verify}}

|-
| {{text anchor|SPOUSE}}
| singular:plural. Readable up to 30 characters in the unit list.
| The name of the position holder's spouse.

|-
| {{text anchor|SPOUSE_FEMALE}}
| singular:plural. Readable up to 30 characters in the unit list.
| If the spouse of the creature holding the position is female, this is the spouse's position name.

|-
| {{text anchor|SPOUSE_MALE}}
| singular:plural. Readable up to 30 characters in the unit list.
| If the spouse of the creature holding the position is male, this is the spouse's position name.

|-
| {{text anchor|SQUAD}}
| number:singular:plural
| The position holder is authorized to form a military squad, led by themselves using the [[leader]] and [[military tactics]] skills. The number denotes the maximum headcount. The noun used to describe the subordinates (e.g. royal guard) is used in adventure mode for the adventurer. This token is used together with [RESPONSIBILITY:LAW_ENFORCEMENT] for giving [[quest]]s to adventurers as [[Hearthperson|hearthpeople]]. Further details: [[Advanced_entity_position_mechanics#Military]]

|-
| {{text anchor|SUCCESSION}}
|
* BY_HEIR / BY_POSITION:position
| How a new position holder is chosen. A single position can have multiple BY_POSITION tokens. See [[Noble]] for more information on how succession is handled in the game.
The SUCCESSION-Tag is also considered when a new positions opens up, for example when a required population number is reached. If a valid successor is available, they will be the one taking that position initially, without appointment or election.

|}

== Responsibilities ==
{| {{prettytable}}
|- bgcolor="#dddddd"
! Argument
! Description

|-
| {{text anchor|ACCOUNTING}}
| Found on [[bookkeeper]]. Position will use [[record keeper]] skill to keep track of stocks.

|-
| {{text anchor|ADVISE_LEADERS}}
|

|-
| {{text anchor|ATTACK_ENEMIES}}
| Found on elven [[ranger captain]] and human warrior. Effect unknown.{{verify}}

|-
| {{text anchor|BUILD_MORALE}}
| Found on [[champion]]. Citizens get a special thought for "talking to a pillar of society" when speaking to this noble.

|-
| {{text anchor|BUILDING_SAFETY}}
|

|-
| {{text anchor|COLLECT_TAXES}}
| Currently unused - was originally assigned to the tax collector.

|-
| {{text anchor|CONSTRUCTION_PERMITS}}
|

|-
| {{text anchor|DELIVER_MESSAGES}}
| Found on [[messenger]]. Position travels to other sites and uses [[social skill]]s.
|

|-
| {{text anchor|EQUIPMENT_MANIFESTS}}
| Currently unused - was originally assigned to the arsenal dwarf.

|-
| {{text anchor|ESCORT_TAX_COLLECTOR}}
| Currently unused - was originally assigned to the Royal Guards (squad members beneath the Hammerer).

|-
| {{text anchor|ESPIONAGE}}
| Found on [[dungeon master]] and the [[Elf|elven]] [[General|princess]] and uses the [[schemer]] skill.

|-
| {{text anchor|ESTABLISH_COLONY_TRADE_AGREEMENTS}}
| Found on [[outpost liaison]]. Position travels with the caravan and uses [[social skill]]s to make trade agreements with any settlements that it visits, provided they are domestic, report the news and promote {{token|LAND_HOLDER|e}} positions. Also reports recent news. Presumably has no effect at site level. Crucially, it does not visit foreign settlements, but the civ-level TRADE position does the exact same thing in its position. They arrive the same time as the caravan arrives, and this can thus be modded by setting {{token|ACTIVE_SEASON|e}}

|-
| {{text anchor|EXECUTIONS}}
| Found on [[hammerer]]. Position executes death penalty judgements with a weapon of the appropriate skill. Cannot be combined with LAW_ENFORCEMENT, resulting in the "Invalid Officer"-error.

|-
| {{text anchor|FIRE_SAFETY}}
|

|-
| {{text anchor|FOOD_SUPPLY}}
|

|-
| {{text anchor|HEALTH_MANAGEMENT}}
| Found on [[chief medical dwarf]]. Position will use [[diagnostician]] skill to evaluate [[wounds]] and schedule [[Health care|treatment]], reported in each citizen's Health tab.

|-
| {{text anchor|JUDGE}}
|

|-
| {{text anchor|LAW_ENFORCEMENT}}
| Found on [[sheriff]]/[[captain of the guard]]. Position and its subordinates are in charge of punishing criminals. A {{token|SITE|position}} position holding this responsibility plus the {{token|SQUAD|position}} token (or allowing the entity to have a {{token|SITE_VARIABLE_POSITIONS|e}} with this responsibility) is required for an adventurer from a given civilization to start as a [[hearthperson]], [[Captain of the guard|fortress guard]], etc. Cannot be combined with EXECUTIONS, resulting in the "Invalid Officer"-error.

|-
| {{text anchor|LAW_MAKING}}
| Found on [[monarch]]s and [[:Category:Aristocrats|nobles]]. Will be referred to as the leader of the site in adventure mode and they may designate the site as being the capital city for civ-level positions. This position is in charge of creating procedural positions, corresponding to either {{token|VARIABLE_POSITIONS|e}} or {{token|SITE_VARIABLE_POSITIONS|e}}. Position-holders that have attained [[immortality]] may issue oppressive edicts to protect themselves against suspicion.

|-
| {{text anchor|MAINTAIN_BRIDGES}}
|

|-
| {{text anchor|MAINTAIN_ROADS}}
|

|-
| {{text anchor|MAINTAIN_SEWERS}}
|

|-
| {{text anchor|MAINTAIN_TUNNELS}}
|

|-
| {{text anchor|MAKE_INTRODUCTIONS}}
| Position will make a 'social call' to an established foreign settlement, complimenting or insulting them depending on relations and reporting the news.

|-
| {{text anchor|MAKE_PEACE_AGREEMENTS}}
| Found on diplomat. Position negotiates peace treaties in order to end wars.

|-
| {{text anchor|MAKE_TOPIC_AGREEMENTS}}
| Found on [[diplomat]]. Position negotiates special agreements, such as tree cutting quotas. Used when elevating a settlement in the {{token|LAND_HOLDER|position}} chain up from level 1.

|-
| {{text anchor|MANAGE_ANIMALS}}
| Found on [[dungeon master]].

|-
| {{text anchor|MANAGE_LEADER_HOUSEHOLD_CLEANLINESS}}
|

|-
| {{text anchor|MANAGE_LEADER_HOUSEHOLD_DRINKS}}
|

|-
| {{text anchor|MANAGE_LEADER_HOUSEHOLD_FOOD}}
|

|-
| {{text anchor|MANAGE_PRODUCTION}}
| Found on [[manager]]. Position enables the use of workshop profiles and uses the [[organizer]] skill to process work orders entered in the job manager after the fortress population reaches 20.

|-
| {{text anchor|MEET_WORKERS}}
| Found on [[expedition leader]]/[[mayor]]. Position uses the various [[social skill]]s to hold meetings with unhappy citizens and try to pacify them with happy thoughts. In adventure mode, [SITE] positions with this responsibility handle petitions to make the player a performer for the local government.

|-
| {{text anchor|MILITARY_GOALS}}
| Found on [[monarch]]/[[:Category:Aristocrats|landholder]]/[[:Category:Elected Nobles|leaders]]. Character is in charge of going to war and making peace for the government they work for. Without a position with this responsibility at civ level the civilization will not be able to make peace and its sites will wage war on each other constantly, and as a result, all viable civilizations must have one leader with this tag at civ level. This appears not to be a problem for [[kobold]]s, presumably due to the {{token|SKULKING|e}}. If no position has this responsibility in fortress mode, players are unable to start [[missions]].

|-
| {{text anchor|MILITARY_STRATEGY}}
| Found on [[general]]/[[militia commander]]. Means that they will command the armies of their site or civilization. Issues the orders for the teams conducting raids or other operations away from the fortress. During worldgen, position will go on expeditions to tame exotic creatures. Counterintuitively not by the TAME_EXOTICS-position. The destinations of these expeditions are determined by the entities USE_(...)_ANIMALS-tokens.

|-
| {{text anchor|OVERSEE_LEADER_HOUSEHOLD}}
|

|-
| {{text anchor|PATROL_TERRITORY}}
| Found on elven ranger captain. Effect unknown.{{verify}}

|-
| {{text anchor|PREPARE_LEADER_MEALS}}
|

|-
| {{text anchor|RECEIVE_DIPLOMATS}}
| Found on [[monarch]]/[[:Category:Aristocrats|landholder]]/[[:Category:Elected Nobles|leaders]]. Position uses the various social skills to hold meetings with incoming diplomats and liaisons.

|-
| {{text anchor|RELIGION}}
| Found on elven [[druid]] and uses [[social skill]]s. Position informs you about worship cults{{verify}}

|-
| {{text anchor|SORT_AMMUNITION}}
| Currently unused - was originally assigned to the arsenal dwarf.

|-
| {{text anchor|TAME_EXOTICS}}
| Position will tame animals with the {{token|PET_EXOTIC}} token. Currently unused - was originally assigned to the dungeon master. Expeditions to tame exotic creatures will be done by the MILITARY_STRATEGY-position

|-
| {{text anchor|TRADE}}
| Found on [[broker]]. Position will use Appraisal skill to display value estimates and the various Social skills to trade at the depot. When applied to other civilizations, this position will arrive with the caravan to make trade agreements (like the Human Guild Representative from older versions) and behaves otherwise like the civ's own ESTABLISH_COLONY_TRADE_AGREEMENTS position holder. They arrive the same time as the caravan arrive and this can thus be modded by setting {{token|ACTIVE_SEASON|e}}

|-
| {{text anchor|UPGRADE_SQUAD_EQUIPMENT}}
| Currently unused - was originally assigned to the arsenal dwarf.

|}

== Related tokens ==
The following two ENTITY tokens are not actually position tokens, but bear mentioning on this page because they can modify the way that a civilization's positions behave:

{| {{prettytable}}
|- bgcolor="#dddddd"
! Token
! Arguments
! Description

|-
| {{text anchor|VARIABLE_POSITIONS}}
| Position responsibility or ALL
| Allows a responsibility to be taken up by a dynamically generated position (such as Law-maker).

|}

== Why won't my positions appear? ==
The way DF determines what positions will actually ''appear'' in your fortress is somewhat counter-intuitive and fairly limiting. This guide should help you understand what you can do to actually get your positions working properly.

There are five tokens governing which positions appear in your fortress - LAND_HOLDER, REQUIRES_POPULATION, APPOINTED_BY, ELECTED, and REPLACED_BY. The first two determine when your fortress is eligible for a new position, the next two determine how a new position for which your fortress is eligible can be added, and the fifth allows you to clear up obsolete positions. Unfortunately, they also interact in some strange ways that makes creating interesting position structures difficult.

When you start a new fortress, DF compiles a list of your initial positions. To do this, it looks at the requirements for each position - any position whose only requirement is less than seven dwarves (either because they have no requirement tokens, or because their only requirement tokens are [REQUIRES_POPULATION: =< 7] or [LAND_HOLDER:some trigger whose only requirement is some number of dwarves equal to or less than 7]). Most importantly, ''any'' position whose only requirement is a LAND_HOLDER requirement, regardless of what the trigger for that requirement is, will be added if another eligible starting position is REPLACED_BY it. '''A non-LAND_HOLDER position that is REPLACED_BY a LAND_HOLDER position will never appear.''' With this list compiled, the game culls all positions that are REPLACED_BY another eligible position, and then culls all positions that have the APPOINTED_BY token. '''You may not embark with any appointed positions.''' Any remaining positions are then filled by a dwarf chosen at random.

'''Positions do not automatically appear when you reach their requirements.''' For example, if you remove the ELECTED token from the Mayor, then the Mayor will never appear, even once you reach their required number of dwarves. '''For a position that does not appear at embark to appear in your fortress, it must be APPOINTED_BY another position or ELECTED.'''

Naturally, this is more complicated than it looks. '''APPOINTED_BY positions must be appointed by another position already in your fortress, or a civ-level position. Only LAND_HOLDER positions may be appointed by civ-level positions.''' LAND_HOLDER positions that are APPOINTED_BY civ-level positions are inherently tied to civ-level tokens with the ESTABLISH_COLONY_TRADE_AGREEMENTS responsibility. If a fortress meets the LAND_HOLDER_TRIGGER for a new LAND_HOLDER tier when a caravan leaves, then the next time the outpost liaison or equivalent arrives, they will offer to make you an official colony, which will allow you to select all positions for that LAND_HOLDER level. '''Each time they appear, the outpost liaison will only promote your fortress one tier up the LAND_HOLDER track.''' The biggest problem with this system is that you may set your LAND_HOLDER_TRIGGERS such that you are eligible for the first tier of LAND_HOLDER positions at embark. '''If you are eligible for the first tier of LAND_HOLDER positions at embark, then all first-tier positions will appear twice - once at embark, and again when the outpost liaison comes to appoint you to the first tier.'''

If civ-positions are neither APPOINTED_BY nor ELECTED, they still will be filled.

Read more: [[Advanced_Entity_Position_Mechanics]]

{{Category|Modding}}
{{Category|Tokens}}
[[ru:Position token]]

Talk:Advanced entity position mechanics

2026-02-12T08:50:36Z

Joostheger:

Advanced entity position mechanics

2026-02-12T08:48:26Z

Joostheger: /* [CONQUERED_SITE] */

{{Quality|Fine}}
{{Modding}}

= Introduction =

[http://www.bay12forums.com/smf/index.php?topic=182239.0 Discussion thread on the forum]

This page documents observed and tested behavior of entity positions in Dwarf Fortress that is not fully described elsewhere on the wiki. It focuses on advanced interactions between position tokens, including appointment, succession, election, and responsibility handling, across both civilization-level and site-level entities.

The mechanics described here are based on empirical testing in world generation and fortress mode, supplemented where necessary by raw analysis. In several cases, the game’s behavior is determined by evaluation order and interaction between multiple tags, rather than by individual tokens in isolation.

This page is intended for modders and advanced players who are designing or debugging custom entity position structures. It does not restate basic position mechanics, but instead highlights edge cases, non-obvious interactions, and behaviors that may appear inconsistent or undocumented.

Unless stated otherwise, the described behavior applies to current versions of the game and may differ from older releases.

==What is an entity? What is a position?==
An [[entity]] is an organizational structure that can have relationships with other entities, usually known as a [[civilization]] or a "[[site]] government" in the game, but merchant [[guild]]s, religious organizations, necromancer towers, and [[bandit]] groups are also entities. An entity can have positions - in most cases, these are hardcoded and generated by the game, but as for civilizations and sites, the [[raw file]]s can be customised.

A position is a special relationship between a unit and an entity. The unit holding a position has a larger influence over that entity than other citizens. Positions are mostly known as [[nobles]], but in this article. the technical term is used.

=Position levels (Site/Civ) and their interaction=
There are two basic types of positions that are customizable: '''civ(ilization)''' level and '''site level'''. Positions with the tag [SITE] are at site level, positions without the tag [SITE] are at 'civ level'. These two types of nobles can be considered '''loosely related systems'''. There are a few places where they can interact with each other.

Civ-level positions are in charge of the civilization as a whole, managing national [[trade]], laws, and [[war]]s. These are, for example, the vanilla [[monarch]], [[diplomat]] and [[general]]. (Note that the general doesn't do anything in either mode in the current version.)

'''[LAND_HOLDER]''' nobles are also positions at civ-level. These units are members of the national government, but have gained authority over some land or site. Once they do, they move to that place, but their position is still regarded as a civ-level position.

Site-level position holders are members of a site government (subsidiary to the civilization), and manage local affairs in that location. These are, for example, the [[mayor]], the [[sheriff]] and the [[broker]].

==Table of interaction between different position levels==
In this table, the possible interactions between different position levels are summarized.
The header row shows the positions defining the tokens.

The left column shows the position type that is referred to.
Example:
{| {{prettytable}}
|- bgcolor="#ddd"
! referred position-type
! LAND_HOLDER
|-
| civilization
| (baron is) APPOINTED_BY:MONARCH
|}
color coding: 
* Exists in vanilla
* Possible with mods
* Not possible
* possible to some extent.
* not yet fully investigated.
{| {{prettytable}}
|- bgcolor="#ddd"
! referred position-type
! Civilization
! SITE
! LAND_HOLDER
! CONQUERED_SITE

|-
| Civilization
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION '''(1)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION

|-
| SITE
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION '''(2)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY '''(3)''' COMMANDER REPLACED_BY SUCCESSION '''(4)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION

|-
| LAND_HOLDER
| APPOINTED_BY COMMANDER REPLACED_BY '''(6)''' SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION '''(5)'''
| APPOINTED_BY COMMANDER REPLACED_BY '''(7)''' SUCCESSION '''(8)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION

|-
| CONQUERED_SITE
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
|}

Remarks:
# Works only in world-gen, if a unit with that civ-position is present at the site.
# Works only in world-gen, the site-position holding unit will then move to the capital.
# Is completely ignored
# Works only in world-gen.
# Works only in world-gen.
# Won't appear at all
# This is necessary for the landholder chain to work properly, it doesn’t work otherwise.
# This works only outside of the landholder chain, so when landholders are simply regarded as civ-level nobles. might also work in world-gen
#

== Other interactions ==

Unfortunately, interactions with positions of other entities don't seem possible, such as APPOINTED_BY: HIGH_PRIEST. With [VARIABLE_POSITIONS], positions are automatically created with codes like CUSTOM_LAW_MAKER_2, but interaction with these positions don't seem to work, either. For more info on those, see [[Variable positions]]

=General=

==Civ-level nobles living at your site==
Nobles from your civilization can come to live at your fortress. This happens in vanilla with landholders such as [[Baron]], [[Count]] and [[Duke]], with the Monarch, but sometimes also with non-landed LAND_HOLDERS.

When a civ-level noble becomes a [[citizen]] at your location, their position is shown among the site-level positions in your [[nobles screen]]. They appear to function as a site-level noble. They may have [[demand]]s, [[mandate]]s, [[squad]]s and the like. They can appoint nobles at the site-level.

If they have certain [RESPONSIBILITY]ies, they do the tasks that go with them.

==Fortress mode, world-gen and their differences==
Their are a few differences in how positions function between fortress mode (normal play mode) and the world generation (world-gen).

In '''fortress mode''', the player has some control over the appointment of nobles, limited by elections, automatic filled-in positions and succession rules. Pre-fortress mode, which is referred to as '''world-gen''', the game will always attempt to assign nobles whenever possible. It is subjected to the same rules as in fortress-mode, but there are some exceptions. In '''[[World activities]]''', which is the thing that happens in the world while you play fortress mode, it seems as if the same rules are applied as fortress mode.

A difference between player-fortress-mode and world-gen, is causes by visibility (see below). Positions that are not visible by the player and thus not available for assignment, will be available in world-gen and will thus be automatically assigned.

In fortress mode, a position that is both [ELECTED] and [APPOINTED_BY], cannot be appointed by the player and is also not elected, and can thus not be filled. But in world-gen sites however, these positions are automatically filled.

Positions with [AS_NEEDED] are almost never created and filled in world-gen (depending on their [RESPONSIBILITY]ies), but can always be used in player mode.

A position can, in fortress mode, be filled by the same unit. A unit can gain multiple positions in fortress mode, for example because of [[elections]]. This will not happen in world-gen mode: a unit can only have one position. See also remarks on 'embark' and 'Losing a position'.

In world-gen, [SUCCESSION] between civ-levels and [SITE-]levels may happen. This will not happen in fortress mode, or even off-site in [[World activities]].

In fortress mode, premature SUCCESSION may happen. This will not happen in world-gen mode.

==Units holding multiple positions in multiple entities==
A unit can hold multiple positions in its civilisation or in its site-entity, however this does not happen in world-gen. Only at player-managed sites can units be holding multiple positions at once. (It is probably not possible for a unit to hold a position in two different civilisations or two different sites.)

In world-gen, if there are too many positions to be filled, they simply stay empty until more units are available. E.G, a unit at a site might inherit a civ-level position and still remain a member of the local government. When this happens however, they move to the capital. If a unit gains a new position, either inherited or otherwise, it drops the previous one. If a unit assumes a civ-position in fortress mode, it leaves the current position.

If a unit holds the same (site-)position multiple times, it has no additional effect.

If a unit holds multiple different positions of the same entity, it has all those positions' responsibilities and properties, stacked up. Presumably, the demands for those combined positions are determined by the highest.

A unit holding a position with a succession token can be assigned another position with a (different) succession token.

A unit holding a position with a squad-position cannot hold another squad-position. It is dropped from the first, when it gets its second assigned.
A unit holding a position with a succession token cannot be assigned to a squad-position - the unit is simply not available. It works the other way around, though.

=Specific Tags and functions=
==[PRECEDENCE]==
The first defined position with precedence of 1 counts as the ruler of the civ. See also: [[Position_token#PRECEDENCE|PRECEDENCE]].

If the precedence is omitted or has a negative value, the game sets 0 as precedence, which seems to have no effect whatsoever.

When a unit has multiple positions, the name of the position with the highest rank in precedence is shown behind the unit's name.

If you omit precedence entirely, or set it to [PRECEDENCE:NONE], the position name will not be shown after the unit’s name. Your *Urist Mason* will remain simply *Mason*. This can be useful for positions that are unimportant or purely functional. The position will also not appear in the civilisation overview of your site on the world map. The position name is shown in messages, but remains hidden on the nobles screen as well. To make it visible there, use [LAND_NAME].

==[RESPONSIBILITY]ies==
Both civ and [SITE] positions can carry responsibilities. However, not all responsibilities are active for both types: some function only for civ positions, others only for site positions. When a civ noble arrives at a site and takes up residence, they do not perform responsibilities that are intended for SITE nobles. As a result, these responsibilities neither trigger their associated tasks nor unlock related game mechanics. For example, a civ-level manager living in a fortress will not perform management duties there and doesn't unlock the management-screen, even with an assigned office.
This behavior applies to the following [SITE]-level responsibilities:
* [RESPONSIBILITY:ACCOUNTING]
* [RESPONSIBILITY:BUILD_MORALE]
* [RESPONSIBILITY:HEALTH_MANAGEMENT]
* [RESPONSIBILITY:LAW_ENFORCEMENT]
* [RESPONSIBILITY:MANAGE_PRODUCTION]
* [RESPONSIBILITY:MEET_WORKERS]
* [RESPONSIBILITY:TRADE] (functions differently)
Other responsibilities may be affected as well, but have not yet been fully tested.

===World-gen effects of the [RESPONSIBILITY] of available positions ===
It is possible to cause civs and individual sites to change their behavior substantially when they reach a certain size, by controlling nobles.
* If a site can only appoint a position with [MILITARY_GOALS] after reaching a particular size, that site will not send armies on missions until the required size is reached.
* A civ-level [LAW_MAKING] position is required for the civilization to have any kind of cohesion. Without it, sites will be constantly embroiled in territorial disputes and civil wars will be commonplace.
* [MILITARY_STRATEGY] positions go out and tame wild animals. This makes your civ gain those animals as domesticated and also brings them in sieges.
* The [[Personality_facet|Personality]] of the position's holder determines how they lead the civ.

===[DELIVERS_MESSAGES]===
The only [AS_NEEDED]-position that is created in worldgen based on responsibility is that of the site-level responsibility [DELIVERS_MESSAGES].

===Outpost Liaisons and Diplomats===
Civ-positions with the responsibility [ESTABLISH_COLONY_TRADE_AGREEMENTS] ([[Outpost_Liaison|Outpost Liaison]]s) will meet with the site-noble who has responsibility for [RECEIVE_DIPLOMATS] and the highest rank of precedence (i.e. the lowest precedence value). Usually this is the [[Expedition_leader|Expedition leader]].

Once a [LAND_HOLDER] is assigned to the site, civ-positions with the responsibility [MAKE_TOPIC_AGREEMENTS] ([[Diplomat]]s) will meet with '''civ'''-level nobles present at the site who have the [RECEIVE_DIPLOMATS] responsibility. If multiple eligible nobles are available, one is selected at random. If no eligible noble is present, the diplomat leaves angrily. If the landholder is no longer present at the site, diplomats will not arrive at all.

It appears that Outpost Liaisons and Diplomats are chosen for a diplomatic mission based on availability. When multiple candidates exist, the position defined last in the raws is most often selected.

===[TRADE]===
Civ-level nobles with [TRADE] will arrive with the caravan, just as the Outpost Liaison. Their behavior is no longer active in the vanilla game, but the mechanics are still present. See [[40d:Guild_representative|Guild representative]] for more details. This civ-noble will only meet with the SITE noble with [TRADE], usually the [[Broker]].

If two civ-nobles exist with both [TRADE] and [ESTABLISH_COLONY_TRADE_AGREEMENTS], they both arrive at the same time. Even if both tokens are assigned to a single position, if more than one instance of that position exists, two of them will arrive. However in that case, somehow the elevation of the site and appointment of landholder isn't offered.

If the SITE-noble they intend to meet has both [TRADE] and [RECEIVE_DIPLOMATS], only one meeting will proceed and the other is cancelled. However, when two SITE-nobles are available, each with either [TRADE] or [RECEIVE_DIPLOMATS], both meetings will proceed and both civ-nobles will attempt to negotiate a trade agreement. It is not known what happens if these agreements are accepted or refused.

In the trade depot, the last defined position with the [TRADE] responsibility is shown as broker. However when requesting a trader, the first defined position with [TRADE] will actually go there to do the trade.

==[NUMBER]==
A position might be defined with a number. In that case, as many as defined can be available. If the positions become available, in world-gen and when embarking, they are all filled-in completely.

If the ruling position (with PRECEDENCE of 1) has a NUMBER higher than 1, a random unit of the ones holding these positions is shown as ruler in the embark screen.

A [NUMBER] of 0 (zero) has the same effect as 1.

===Automatic spreading of assumed, non-singular positions===
If there are civ positions that have a NUMBER higher then '1' and which are assumed (not APPOINTED_BY or ELECTED) but are '''not DUTY_BOUND''', these are automatically spread among the civilisation, based on population. If there are a number of '''20''' available slots of that position, they spread among a civilization with a combined population of, for example, 1000 of which your fortress has 100 (10%), '''2''' of your fortress' citizens will assume that position.
This may probably also work with elected and appointed positions, but that may be depending on the death of the current holders and this needs more testing. Assumption works within a day, anyway.

===[AS_NEEDED]===
These positions can be created automatically by the game in world-gen. This, however, only works with:
* [LAND_HOLDER]'s
* squad commanders (needs more testing)
* Messengers at sites

For all other types of positions, they're not created in world-gen, even if they are defined with RESPONSIBILITY's. For example, even in war, the game wouldn't create a MILITARY_GOALS position, if they have AS_NEEDED as number.

However, in fortress mode / player mode, these positions can be created by the player at will.

Positions with AS_NEEDED need to be created first, before any symbols are assignable as 'symbols' (objects) for the position holder to carry or wear.

Positions with AS_NEEDED cannot be created and then ELECTED in fortress mode. It only works with APPOINTED_BY.

==[REPLACED_BY] and [REQUIRES_POPULATION]==

The token REPLACED_BY:position means that once the replacing position reaches its required population-number, the 'to-be-replaced' position will disappear. This is defined in REQUIRES_POPULATION. These tags are closely related to each other and seem to only have a meaningful function if combined. Nobles with REQUIRES_POPULATION require the population to have a specific size.

This works on the civ-level as well as on site-level, but those systems are in this mechanic strictly separated. Site-level positions cannot be replaced by civ-level positions and visa versa. This makes sense, because they both depend on their own population-count. When using REQUIRES_POPULATION on civ-level, it counts the total population of the civilisation.

See also: [[Advanced_entity_position_mechanics#Evaluation_of_Positions|Evaluation of positions]]

===Effect of replacement (and on [LAND_HOLDER]s)===

Replacement is immediate and complete - the current holding unit loses the position, even before SUCCESSION_BY_POSITION rules are applied. A position with a number of 1 will replace all the slots of a position with a higher number of slots.

Even if the next position is available but not visible, replacement still takes place. If a position is replaced, it is completely gone - it cannot be appointed, succeeded, elected or assumed any longer.
The unit immediately loses its position.

In legends, replacement is mentioned as: "(unit name) ceased to be (position name)" The replacement of an AS_NEEDED position empties the position's slot forever. In fortress mode, it may seem as if you can create new slots and appoint new units in the nobles screen, but this is reversed as soon as you close the window.

The landholder chain uses [REPLACED_BY] differently. It does not clear the position completely, but uses it for succession to the next level's position. [REPLACE_BY] is required to let that system work properly. This also means that the way in which landholders succeed (replace + as_needed) does not work in any other way.

Replacement between LAND_HOLDERS and other site- or civ positions does not work in any way. Only the vanilla replacement sequence between levels of LAND_HOLDERs does work. If the token is omitted for landholders, the landholder chain is broken, so replacement is required for the landholder system to work.

[REQUIRES_POPULATION] also does not work for [LAND_HOLDER], when you set [NUMBER] to 1. The position is not created when the required population is reached.

===What doesn't work===

'''Attention: If a position cannot be appointed, for example because of 'mutual appointment', it still exists according to replacement mechanics and will replace other positions if so defined. If a certain position(a) will be replaced by the baron's assistant, which can only be appointed by the [LAND_HOLDER] baron, than that position(s) still will be replaced from the start of the game, even if no baron or their assistant is ever present.'''

A position that is replaced by a somehow non-fillable position is still replaced. This counts for mutual-appointing positions, replacement by not-yet-assigned landholders, replacement by AS_NEEDED positions, or replacement by not-yet-appointed positions.

Replacement does not work if the replaced position is a [LAND_HOLDER], even with civ-positions. In that case, the LAND_HOLDER's position is not replaced. It does not matter if AS_NEEDED is used, or a fixed number, and it also does not matter what type of position the replacer is. So this only works (correctly) with positions that become available by REQUIRES_POPULATION.

==[CONQUERED_SITE]==

This tag determines which position is used to assign a [[Forced administrator]].

In legends mode, this is visible as an event describing the reconquest of the site: a new group is formed and the forced administrator is installed as its ruler.

All positions defined with this tag are assigned during this process, meaning multiple positions can be appointed at once.

The holder of a position marked with [CONQUERED_SITE] cannot appoint any other [SITE] positions.

Combining [CONQUERED_SITE] with [SITE] causes the position to function both as a forced administrator and as a normal site position available in fortress mode. However, this provides no meaningful additional mechanics and is effectively inferior to using [SITE] alone:
* [APPOINTED_BY] lines are completely ignored, meaning that the roles are automatically assumed.
* [SUCCESSION] is likewise ignored.
* the [CONQUERED_SITE]-position cannot appoint other [CONQUERED_SITE], [SITE] or combined positions.

There have been remarks that reclaiming a fortress is unplayable because of the lack of regular nobles. Unfortunately, it seems that it can't be fixed by modding.

=Availability and visibility=
==Availability of (new) positions==
Warning: Do not mistake "availability" for "visibility"!

Of all the possible positions existing in your site's entity, there may only be some available.
* Positions with [REQUIRES_POPULATION] require the population to have a specific size.
* Positions with [REQUIRES_MARKET] will only appear in "large" sites (which may have different rules for different site types). This tag has no effect in fort mode.
* Positions that are appointed by positions that have an AS_NEEDED number. The appointable positions only become available after an appointer position-slot is created. This works also on civ-level. If a position is appointed by a Land-holder, it only becomes available, when that level of landholder is created.

Only the replaced positions are culled and are no longer available.
A position that requires a certain population will become available, even if it doesn't have [APPOINTED_BY] or [ELECTED]. In that case, see 'automatic assignment' and 'assumption'

In fortress mode, in some cases 'succession' is evaluated immediately after a position becomes available. See: Succession.
==Visibility of positions==
A position might be available, but can still be invisible for the player in the [[nobles screen]]. The positions with their respective holders are visible for players:
* All site-positions that are already filled-in (even if they could not be re-filled-in considering current conditions)
* Site positions that are appointable by a filled-in site position
* Site positions that are appointable by a filled-in civ position, when that civ positions holder becomes a citizen of your fortress.
* Civ positions of units that are also a citizen of your fortress.
If a position becomes available, for example because a certain pop number has been reached, or if it is available from the start(like expedition leader), as long as it cannot be appointed, it still is INVISIBLE for the player.

It might strike someone as odd if a position becomes filled automatically in fortress mode when that position is not even visible. This might be the case if the current holder of a non-appointable position dies or succeeds another position. Regardless of player visibility, these positions will be automatically filled in if the necessary requisitions are met. It might happen with the expedition leader.

A situation with a non-visible but available position, is for example when a position is solely appointed by the expedition leader, when the expedition leader's position is left vacant. It can no longer be appointed by the player and is invisible. Then, it gets automatically assumed, proving that the position still was available.

A position that is both [APPOINTED_BY] and [ELECTED] is visible, but players cannot interact with it.

={{text anchor|Evaluation of Positions}}=
The game does not continuously check whether positions should become available, elected or be [REPLACE_BY]. This is well-known behavior—for example with the [[mayor]], who does not appear automatically when the required population ([REQUIRES_POPULATION]) is reached. Instead, positions must somehow be evaluated. This applies in several other situations as well

'''Cases that require a trigger:'''
* Election of a newly created position
* Election after the current holder dies
* Automatic assumption of a newly created position (this may take up to a day)
* New citizens (such as migrants) considering available positions
* Premature succession of a newly created position

'''Cases that do not wait for a trigger:'''
* Succession following the death of the previous holder
* Automatic assumption of existing positions that have become vacant

'''Triggers that cause the game to reevaluate noble positions:'''
* Succession of a [SITE]-position due to the death of the current holder
* [[Advanced_entity_position_mechanics#Election_Day|Election Day]]
* Automatic assumption of a [SITE]-position that becomes vacant
* (Re)assigning any site position manually
* Settlement elevation on the LAND_HOLDER track (e.g. gaining a [[Baron]] or [[Count]])

=Gaining a position=
There are several ways a unit can gain a position:
* Appointment: A unit is appointed by another unit or by the player.
* Election: A unit is elected by and among the members of the entity
* Assumption: A position is neither elected or appointed: a random unit just simply 'takes' the position
* Succession: a unit is the valid successor of this position(A), either by its current position(B) or because they are that position(A)-holder's heir.

Available positions will automatically be assigned to a random civ member when a new site/civ is created.

==Who can take a position==

* If so defined, a unit needs to be the right caste and/or class - it does not seem to work with creature types.
* The unit needs to be an adult member of the site or its parent civ's government; that is also CAN_LEARN or INTELLIGENT (SLOW_LEARNER cannot take positions) or otherwise is able to think.

==Appointment==

Positions that have an [APPOINTED_BY:position] token require that position to exist, to be available and appointed. Any position that is APPOINTED_BY can be appointed if the appointer's position is filled in.
For site-positions to be appointed, it is required that the appointer is present at that location.

If the appointing unit is temporarily not present, or if that position is not filled, positions depending on it cannot be appointed. This is the case with [[militia captains]], when the [[militia commander]] is on a [[mission]].

A site position cannot appoint a civ position ''or'' LAND_HOLDER in any way whatsoever.

Civ-level positions can appoint other civ-level positions and site-level positions can appoint other site-level positions.

Contrary to what has been said elsewhere, civ-level nobles also can appoint site-level nobles. They need to be at the site to do so. Landholders can appoint both site-level and civ-level nobles. These systems are therefore not as separate as was assumed.

'''Mutual appointment''' cannot take place. If these are the only requisites of the position, then the positions will never appear or get filled. These unfillable positions can be put to good use, for example, to replace a position that is no longer needed without creating a new one.

'''Self appointment''' doesn't normally work. If you have a position that is only appointed by itself, it is never appointed and also cannot be assumed. However, if the position has a number higher than 1, and is filled by multiple units (for example by another position that is now empty), than those units can re-assign or appoint each other from that their shared position.

If an APPOINTED_BY token refers to a non-existing position's code, the effects are as if the appointment token doesn't exist at all.

===Automatic appointment in world-gen and on the civ level===

Outside of fortress mode, the game will always attempt to appoint nobles whenever possible, as long as these positions are '''available''', even if they are invisible to the player.
It shows this message in legends: "(unit name) has been appointed to the position of (position name)"

In world-gen, all positions become available and are automatically appointed, taking population- and appointment-requirements into consideration.

Positions that are REPLACED_BY are culled and won't be filled.

If a citizen of your fortress holds a civ-level position that can appoint another civ-level position, the appointment will happen automatically and without player intervention. It may happen that another citizen of your fortress is appointed by that unit, creating civ-level position holders in your fortress, but it is unknown what is required to force this effect.

===Manual appointments by players in fortress mode===
In fortress mode, the positions that need to be appointed stay empty on embark. and it is the player's job to appoint those. A player can appoint a unit to any available position, according to the hereabove mentioned conditions. The player takes the role of the automatic appointment-system, but has no direct control over elections, successions and replacement. There are some differences in what is possible at world-gen sites and at player-controlled sites.

* A position that is appointed by a unit present as a fortress citizen, can be appointed, re-appointed or left vacant. This means also by civ-level nobles living as a citizen in your fortress; not when they are only visiting, like the diplomat.
* A position whose appointing positions are all either vacant or [REPLACED_BY] can no longer be appointed. If the position is already filled, it cannot be reappointed or vacated; the current holder simply remains in office.
* A position that is APPOINTED_BY a unit present as the land_holder of your site, can be appointed, reassigned or left vacant.
* A position that has SUCCESSION BY_HEIR or BY_POSITION can 'initially' be appointed and also re-appointed or left vacant, but as soon as the [[nobles]] screen closes, ''it can no longer be replaced or left vacant''. From then on, the succession-rules determine who gains that position when the current holder loses the position. This works even if the SUCCESSION:BY_POSITION-position is vacant or replaced.
* A position that is ELECTED nor APPOINTED_BY, can always be (re-)appointed by the player. This is the case with the [[Expedition leader]]. If it is left vacant however, it cannot be appointed, but will be assumed shortly after.
* A position that is both ELECTED and APPOINTED_BY, cannot be appointed by the player. Contrary to world-gen sites, its slot is visible, but it doesn't show the +-sign. This is either by AS_NEEDED or by a fixed number. Even if the position somehow gets filled (re)assignment is never possible
* A player can appoint a number of units to a position, as much as the NUMBER token dictates. If it is AS_NEEDED, the player may create as many slots as they like, also contrary to world-gen sites.
* A civ-position can never be appointed, even if the appointing civ noble is a citizen of your fortress. A civ position also never can be re-assigned or left vacant, would that position be defined as appointed by a site-position.

==Election==
Read more in [[Elections]]. The message that is shown is: "(creature name) has been elected to the position of (position name)"

In worldgen, there is no functional difference between ELECTED and non-appointment, except that elected nobles tend to have high social skills and/or skills related to the position, while non-elected ones are assigned randomly. See: [[Elections]]

A succession goes before an election.

A position that is both ELECTED and APPOINTED_BY never gets elected. Even if the appointees' position somehow gets filled, (re)-elections won't happen. So, it doesn't seem possible to have an elected position become available when a certain other position becomes filled.

An ELECTED civ-(or LAND_HOLDER) position at your site will never be (re)-elected in fortress mode. So real (re-)election only works with SITE-positions.

=== {{text anchor|Election Day}} ===
Election Day takes place on the 17th of Summer. On this day, a full reevaluation is performed, including all currently elected positions, which are subject to re-election. Contrary to the information on [[Elections]], nothing occurs at the start of a season.

Positions that are both [APPOINTED_BY] and [ELECTED] will not be re-elected on Election Day when assigned through [SUCCESSION].

=== Election Eligiblity ===
Any citizen may stand for election. Eligibility cannot be restricted using [ACCEPTED_CREATURE], [REJECTED_CREATURE], [ACCEPTED_CLASS], [REJECTED_CLASS], or [GENDER]. Units currently having a [SUCCESSION]-position even may be elected for a position with a [SQUAD]-token, which is otherwise impossible to assign or even succeed.

=== Skills ===
In elections, skills are taken into account for the tokens of the position which is elected.
{| class="wikitable"
|+ Relevant skills per position token
|-
! Position Token !! Relevant skills
|-
| Responsibility [[Position_token#DELIVER_MESSAGES|[DELIVER_MESSAGES]]] || [[Ambusher]], [[Observer]] and [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#ACCOUNTING|[ACCOUNTING]]] || [[Record_keeper|Record keeper]]
|-
| Responsibility [[Position_token#ESPIONAGE|[ESPIONAGE]]] || [[Schemer]]
|-
| Responsibility [[Position_token#HEALTH_MANAGEMENT|[HEALTH_MANAGEMENT]]] || [[Diagnostician|Diagnostician]]
|-
| Responsibility [[Position_token#MAKE_INTRODUCTIONS|[MAKE_INTRODUCTIONS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#MAKE_PEACE_AGREEMENTS|[MAKE_PEACE_AGREEMENTS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#MAKE_TOPIC_AGREEMENTS|[MAKE_TOPIC_AGREEMENTS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#MANAGE_PRODUCTION|[MANAGE_PRODUCTION]]] || [[Organizer]]
|-
| Responsibility [[Position_token#MEET_WORKERS|[MEET_WORKERS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#RECEIVE_DIPLOMATS|[RECEIVE_DIPLOMATS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#RELIGION|[RELIGION]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#TAME_EXOTICS|[TAME_EXOTICS]]] || [[Animal_trainer|Animal trainer]]
|-
| Responsibility [[Position_token#TRADE|[TRADE]]] || [[Social_skill|Social skills]] and [[Appraiser|Appraiser]]
|-
| [[Position_token#SQUAD|[SQUAD]]]-token || [[Tactician]] and [[Leader]]
|}

==Assumption==

A position that is not APPOINTED_BY nor ELECTED, or is appointed by positions that are not available in your site or civ, will be assumable by a random dwarf. If it has responsibilities that require certain skills, then these are taken into consideration on embark, but not when the position is assumed during the actual game.

Normally, one to three units will take the into consideration to assume a position. Most of the time when there are multiple open positions, only a single unit will assume all of them. However, a position that has REJECTED_CREATURE, REJECTED_CLASS, ALLOWED_CREATURE or ALLOWED_CLASS will be filled with all different units, even if the creature or class mentioned is irrelevant. It seems that this forces the game to loop over all the available units.

The message that is shown in Legends mode is: "(unit name) has assumed the position of (position name)". This may also take place in fortress mode, which then shows this message to the player.

If an assumable position becomes empty, it will be assumed within a day. This is the case when you leave the position of expedition-leader vacant. It also happens with entities.

Assumable positions that become empty will not be assumed if that position has a valid [SUCCESSION] -successor. In that case, the successor inherits the position.

Even positions that are somehow invisible because they cannot be directly APPOINTED_BY players, can be assumed.

When you embark, the assumable positions are automatically assigned to a random unit. If there are multiple of these positions at embark, they all are assigned to the same unit. If there are enough positions available, multiple units may gain a position, but often no more than three different ones.

If a dwarf in fortress mode assumes a position, that already has another position, it will leave the current position empty. When that position also is assumed, then this will continue until all positions have a dwarf appointed to them, with no other position.

A unit that already has a position with a [SUCCESSION] token won't take assumable positions into consideration that have a [SQUAD] token. This can be used by the modder to prevent unwanted loss of current positions.

A position that has an appointer which got replaced because of REPLACED_BY, will not become assumable. Also, positions that have an AS_NEEDED appointer that is not yet filled (or ever), will also not be assumed.

==Succession==

If a position-holder dies or advances to a new position via succession, the position will be granted to another unit based on the [SUCCESSION] tag. If they have an heir or the succeeding position exists, that unit will be assigned. If not, a new one will be appointed according to the usual rules. The message that is shown is: "(creature name) being the rightful heir, has inherited the position of (position name)"

The succeeding creature will also lose its previous position. When succession is defined using BY_POSITION, the unit naturally loses the referenced position. However, it also loses any other positions it may hold. If a unit could simultaneously inherit multiple positions, the last-defined succession overrides the earlier one, clearing the previously acquired position

Succession works both at site-level and at civ-level, both in world-gen and in fortress-mode. Succession by position on the civ-level is also visible and functional in fortress-mode. If both civ-level nobles are a citizen of your fortress, succession is applied visually. Vanilla example: The [[druid]] is succeeded by the [[acolyte]]. This means that as soon as the druid dies, the acolyte takes over.

When a position that is succeeded by position becomes available, immediately it is checked if a position-successor is available and the position is filled with that unit. Even if this is an [ELECTED] position, succession goes first. When elections eventually do happen, succession plays no role.

It is possible to assign multiple levels of [SUCCESSION:BY_POSITION] in different positions, creating a line of positions where the death of one causes all those "below" them to advance.

A position can have multiple tokens with position-succession. It looks to be random which one is used. It is not always:
* The first or last defined token
* The first or last appointed unit
* the oldest or youngest
* one with a higher or lower precedence
* a unit with relevant skills

When a position is defined with a Succession-type, that unit cannot have another position that has a Squad-type. If the succession-position itself has a squad, than it can be assigned another position with a squad, but then it will loose the previous succesion position. See further details by "Squad"

Assumed positions can also be succeeded by position, if the current holder dies.

If the successor is an AS_NEEDED position, the used unit will leave a vacant position-slot on its removal by succession. This empty slot remains a real slot, which will only be cleaned up if you (un)appoint a unit to this position-series. It isn't cleaned up after regular position validation.

A civ-level position of a unit living at your site might be inherited by a unit holding that does not currently live at your site. This, unfortunately, moves that position to a unit off site. This may also happen with the landholder of your site, for example when it is succeeded by another civ-level position. This currently poses an unsolved challenge.

===Eligibility for succession===
Succession is restricted by the tokens [ACCEPTED_CREATURE], [REJECTED_CREATURE], [ACCEPTED_CLASS], [REJECTED_CLASS] and [GENDER].

===Site and civ combined succession===

Succession can work when combining site positions with civ-level positions or land_holders, but only in world-gen mode. In fortress mode, it only works with combining the same level of nobles, with Landholders regarded as civ-level. So, in fortress mode, a site's position cannot succeed a landholder's position and it cannot succeed another type of civ-level position, and vice versa.

This won't work even if the positions:
* are AS_NEEDED or having a fixed number.
* Are LAND_HOLDERs.

===Succession [BY_HEIR]===

When a heir is needed for succession, all children and then other relatives are validated. They cannot take the position if their status does not allow it, for example if they have become a member of another civilisation. See: "Who can take a position". If the unit has no valid heir on that location, the position may go to a unit living on another site. This may cause the title of Landholder of some land to be inherited by a unit living somewhere else. That might be a problem, because then you lose your landholders.

===Premature Succession===

There are cases where [SUCCESSION:BY_POSITION] is applied prematurely: at the moment a position is first created and becomes appointable or assumable, rather than after a current holder leaves. In this situation, the succession mechanism assigns a holder immediately, without any player interaction.

When a position becomes available for the first time, the game checks whether a valid successor-by-position exists. If so, that unit is assigned instantly. It can affect positions that would normally be appointed or elected by the player, causing succession to trigger before the player has any opportunity to intervene.

This behavior occurs only in Fortress mode, but can be applied both on [SITE]-positions as well in civ-positions. That last one however is a bit harder to control. Example: [[Advanced entity position mechanics#The Archduke|The Archduke]]

This premature succession only occurs the first time a position becomes available (i.e. when it is created and becomes appointable or assumable). Even if the position remains vacant and the conditions for succession improve later, premature succession will not trigger again. From that point onward, only normal succession rules apply.

Using premature succession, a position that has [ELECTED], [APPOINTED_BY], or both, can be filled directly.
Notably, positions that combine [ELECTED] and [APPOINTED_BY] are normally impossible to fill through regular mechanics. Premature succession bypasses both election and appointment entirely, making this combination uniquely reachable through this mechanism.

No initial election takes place, and no subsequent elections will ever occur for that position. Succession always takes precedence over election, both in premature succession and in normal succession cases.

This behavior applies only in Fortress mode, not during world generation. World-gen uses simplified and more efficient mechanics, and this interaction does not occur there. Premature succession can affect both site-level and civilization-level positions.

====Multiple succession chains====

Multiple succession chains may be defined and are resolved in the order they appear in the raws.

If a position has both:
* a direct succession chain (A → C), and
* a multi-step chain (A → B → C),

and intermediate positions are vacant, resolution proceeds according to raw order. A common outcome is:
# The direct succession (A → C) is applied first, assigning A to C.
# The remaining chain then advances (A → B).
# If C still has empty slots, the final step (B → C) may occur.

If position B is already filled, behavior depends entirely on raw definition order:
* nothing may happen, or
* B may move to C first, followed by A moving to B.
====Working triggers====
Premature succession is triggered when a succeedable position is created under the following conditions:
* The succeedable position is created because its [REQUIRES_POPULATION] threshold is reached. This applies even if the position is not [APPOINTED_BY]. Premature succession takes priority over automatic assumption (e.g. the mayor declaring themselves within a day).
* The succeedable position can be [APPOINTED_BY] another position of the same level (site or civ) that has just been created because its [REQUIRES_POPULATION] was reached.
* The succeedable position can be appointed by another [SITE] [AS_NEEDED] position that has just been created and filled.
* The succeedable (site or civ) position is [APPOINTED_BY] the [LAND_HOLDER] position, which has just been created due to site elevation. This typically resolves when the diplomat leaves the map, at which point the landholder position becomes active.
* If all other requirements are met, premature succession can occur immediately after unpausing following embark, for positions with [REQUIRES_POPULATION:7].
====Non-working triggers====
Premature succession does '''not''' occur in the following cases:
* An [AS_NEEDED] succeedable position slot is manually created by the player while its succeeding position is already filled. [AS_NEEDED] positions must always be appointed after creation.
* The succeeding position is filled after the succeedable position becomes available. The moment of creation is the decisive trigger; filling the source position later is too late.
* The succeedable position can be appointed by another site or civ position with a fixed number of slots that has just been appointed. In this case, the succeedable position is just available for appointment itself, nothing more
* Any situation occurring during world generation.
* The succeeding position is [REPLACED_BY] the succeedable position. In this case, replacement removes the unit from the source position first, leaving no holder available for the succession mechanism to use.rst, leaving no holder available for the succession mechanism to use.
* The position is [APPOINTED_BY] a civ-level position, that just became a citizen of your fortress. It must be noted that those civ-level positions were active all that time and the succeedable position could be appointed even before. The monarchs arrival does not trigger premature succession

=Losing a position=

A unit can lose a position when:
* It dies
* It succeeds another position, even if it has nothing to do with the previous position.
* It is assigned to another SQUAD-holding position
* It is convicted of a crime.
* Another unit is ELECTED for the position
* Its position becomes replaced
* Another unit is appointed by the player, or the position is left vacant.
* It has assumed another position, as this always leaves the previous position vacant.

=Embarkment=
Two types of positions are automatically filled by embark.
* Positions without [APPOINTED_BY] or [ELECTED] (assumable). All these positions, even with a NUMBER higher than 1, are all filled with one to three dwarves. Contrary to assumption, this doesn't take into account any limitations. REJECTED_CLASS, ALLOWED_CLASS, REJECTED_CREATURE, ALLOWED_CREATURE and GENDER are applied, but without the normal spread you may expect with assumptions. Also it doesn't look at [SUCCESSION] and [SQUAD] limitations.
* Positions that are elected are filled-in by the normal election rules.

Positions that have a defined appointer are never initially filled at embark.

All positions that don't have [REQUIRES_POPULATION] or with a [REQUIRES_POPULATION] of 7 or lower, will be available at embark.

=Land Holders=

A Landholder is a '''special civ-level noble''' who gets a certain piece of land to hold, when that land is elevated to a certain level, determined by the tag [LAND_HOLDER] and by the landholder triggers in the game's settings. In vanilla, these are the baron, the count and the duke.

A unit gaining the landholder position does not migrate to that specific named land. In world-gen, they stay just where they are, probably at the capital. In fortress mode, you can suggest a citizen for the role. So for the time being that works.

Succession is then a real issue. If you use BY_HEIR, its solved when that landholder has children living at your site. But when its not the case, the title just goes to anyone randomly. Succession BY_POSITION works, but only in the civ-chain, and there's no way to guarantee a civ-holder is at your site at that time. Even with 'automatic spread' positions, it goes to one of them randomly.

==Functioning of the regular landholder chain==

The distinct difference between a landholder and a regular civ-level noble, is that a landholder may gain the position of landholder "of (sitename)" They are then seen as ruler of a particular site.

For a land_holder position to function as such, it has a few requirements:
* NUMBER:AS_NEEDED
* The first landholder-number of 1 is defined.
* No SITE (so civ) tag in that position.
*REPLACED_BY the next level landholder
If a landholder is defined with differentiating properties, it will function like a regular noble. A higher-up landholder that lacks the required tokens or connections will then not be used in elevation.

If a fortress meets the trigger for a new LAND_HOLDER tier when a caravan leaves, then the next time the outpost liaison or equivalent arrives, they will offer to make you an official colony, which will allow you to select all positions for that LAND_HOLDER level. Each time they appear, the outpost liaison will only promote your fortress one tier up the LAND_HOLDER track.

The landholder's LAND_NAME is not required for the functioning of this system. If omitted, messages will be shown with a more generic text.

==Appointment==

This mechanism differs from the regular methods of position management. It ignores all regular appointment- and election rules, so it more or less functions like automatic assignment. A landholder is, in vanilla, appointed by the monarch. Changing this doesn't seem to do anything. If they are appointed by a site-position, a not-yet-existing civ-position, or not appointed at all: the system keeps working as usual.

A landholder can appoint civ-positions and site positions. This works as expected: the positions only are appointed then when that landholder becomes available on civ-level or when he arrives at that site for site-level positions.

If your rank of landholder is the first of its rank in the realm, and is the sole appointer of some civ-position, then immediately as it gains the title, it will appoint the empty civ-slots. This may happen on your site, but the frequency and certainty is hard to determine.

==Succession==

Succession rules are applied to some extent:
* In world-gen it works according to succession rules, and site-positions can be used here. This means that a site position or a civ-position can inherit a landholder position, and vice versa.
* In fortress mode, once a landholder has been appointed, it then can inherit civ-level positions, and vice versa. This means that your baron can become king.
* Succession rules do not apply within the [LAND_HOLDER] chain; a count will not inherit a baron's land. This is because succession does not work well with the AS_NEEDED token.
* Premature succession works in fortress mode with landholders. If a unit gets a landholder's position and that landholder is the appointer of an as yet empty position, which is defined as succeeding from a third one, then the succession is immediately applied. The landholder themselves can even be the successor of a newly created position.
* A landholder's position is, in fortress mode, not successionable by a site-position or vice versa

===Impossibilities for succession by a site-position===
It would be very beneficial if the landholder can be succeeded by a [SITE]-position. So far, the following tests have not lead to positive results:
* making landholder and site-position both non-[DUTY_BOUND]
* make the site-position be [APPOINTED_BY] the landholder and/or the monarch
* give landholder and site-position [REJECTED_CREATURE]
* Let the monarch live at your site when succession could happen.
* Let the site-position be [REPLACED_BY] the landholder.

==Nomination==

The player is able to nominate a unit to become the LAND_HOLDER, but this only works with units of [LAND_HOLDER] level 1. The player can select all units, only limited by the PRECEDENCE of the current units' positions.

A unit that has a position with a PRECEDENCE lower or equal to that of the landholder's position, cannot be selected. This means that a baron (or count) from another site or the monarch cannot be selected, because their precedence is lower or equal.

The GENDER token does not work here: also units with the wrong gender (sorry) can be selected.

==Levels==
In mods, up to 10 levels of LAND_HOLDER may be defined.

If a landholder is replaced by a wrong landholder number (1 replaced by 3), then the number 3 is still correctly attached to the settlement.

If the current landholder has the highest available landholder number, then the next elevation will not happen - the diplomat will not elevate your fortress to a higher position, even if that position might be REPLACED_BY a lower landholder.

These chains do work:
* 1 -> 2a - > 2b -> 3
* 1 -> 3 -> 2 -> 4

These chains do not work:
* 2 -> 3 (need to start at 1)
* 1 -> 4 -> 2 -> 3 (stops after 4 as the highest)
* 1a -> 2, 1b -> 2 (only 1a and 2 work, 1b is not used)

==Moving landholders==

It may happen that a land-holder no longer lives at the site which they are the landholder of, specifically when the current landholder dies, leaving the title to an heir living somewhere else.

To prevent this from happening, you can make their succession from heir and make sure that their kids live at your site. Or, you can make their position succeeded by another civ position, and make it so that this civ position is somehow available on your site. But if multiple of these positions exist, it cannot be guaranteed that a citizen of your fortress will inherit the title.

In world gen, a landholder lacking the DUTY_BOUND-token will also move to the site they like, according to legends mode.

==Replacement by a generic civ-position==

If a landholder is replaced by an AS_NEEDED non-landholder civ-position, then this will work: the current landholder loses that title upon settlement-elevation and gains that civ-title. However, the civ-title lacks the landholder-property of being attached to the land. It will not show the name of the settlement alongside the position's name. So no "minister of Shovelmounts"

If a landholder is replaced by a general AS_NEEDED civ-position, that itself is also replaced by a generic AS_NEEDED civ-position, then firstly the elevation is executed and also the unit gains that new position. However, he immediately loses it, because an AS_NEEDED position that is replaced by another position can be filled initially, but units wont be able to hold that title.

==Landholder with fixed number==

A landholder's position that has a fixed number will be created and filled directly when the civilisation is born, so this position slot is then not available for the regular landholder-mechanic and will also not be used. That landholder will thus not be attached to a settlement.

It doesn't matter if the landholder's position is connected to the regular landholder's-chain with the REPLACE_BY token.

==Responsibilities==

When given a certain [RESPONSIBILITY], a landholder may function as a regular civ-level noble. If the position has [TRADE] or [OUTPOST_NEGOTIATING] responsibilities, then the landholder functions both as a diplomat and as an actual land holder. A landholder with the [MILITARY_STRATEGY] responsibility will travel around taming creatures in world-gen, according to legends mode.

Besides that, the responsibilities work the same as with any other on-site living position-holder, civ or otherwise.

=Military=
==Squad management==
In the vanilla game, the Squad interface only becomes available after a militia commander has been appointed. Until then, the window displays:{{DFtext|You must appoint somebody first to create a squad.}}

What’s surprising is how this is determined internally. In the entity raw definition, '''only the last two positions that include a [SQUAD] token are checked''' to decide whether the interface is accessible at all. As a result, if your hierarchy defines commanders A through E, appointing '''Commander D or E''' unlocks squad formation, while appointing A–C does nothing.

In other words, squad availability is not tied to ''having a militia commander'', but to ''which specific positions happen to be last in the raw list''—a notably hacky implementation.

These 'last two' are always the last two '''available positions.''' So if they get [REPLACED_BY] or become available because of [REQUIRES_POPULATION], the game adapts to those.

==Squad assignment==

Squads can be assigned, even if the leader position has no holder.

A specific unit can only have one position associated with a squad. If it gains another 'squad holding position', it is unassigned from the first one. This does not work with a 0-squad, so only 1+squads are taken into consideration. This technique can possibly be used to distribute all positions equally among all citizens. It does however not work with election and assumption.

If a civ-level position is associated with a squad and it gets a site-level squad-holding position assigned, it loses the current civ-position.

Squads can get really messed up, if you make the position (or multiple) either elected or not-elected and not-appointed, then this can cause the game to assign multiple squads to the same unit. Automatic assignment and election does not take squads into account, but the nobles screen does. This can cause the positions to be cleared as the game figures out that they have more than one position, and immediately get elected or assumed again.

Positions that cannot have a squad-position:
* A site- or civ-position with a [SUCCESSION] token cannot be appointed a squad-holding-position. The other way around, however, does work. For example, if a site-position with a [SUCCESSION]-token is appointed to a unit that has already a position with [SQUAD]. But when that squad position is assigned to another unit, it cannot be assigned back.
* A position with [SUCCESSION] can also not be assigned as a '''member''' of a squad.
* A squad-holding position with a formed squad cannot be appointed to another squad holding position.

If a position has at least one squad member, it cannot be left vacant. First, the squad has to be disbanded, then the position may be cleared.

==0-squads==
A 0-Squad is defined in a position as [SQUAD:0:member:members]. It does not seem to do anything useful as of now.
* It cannot be used to activate the [[Squad|military interface]]
* It does not restrict the assignment of [SUCCESSION] positions.
* Assigning this position does not clear any previously held squad position.
* The [[Leader]] and [[Tactician]] skill are not marked as relevant skills and are not taken into account in elections.
* It cannot be formed as a squad.

=Further testing=
The following questions may need additional testing. Feel free to add or answer
* Everything regarding COMMANDING and army-structure
** [http://www.bay12forums.com/smf/index.php?topic=175437.msg8331668#msg8331668]
** [http://www.bay12forums.com/smf/index.php?topic=165213.msg8335682#msg8335682]
** [http://www.bay12forums.com/smf/index.php?topic=174584.msg8026854#msg8026854]
* Everything regarding CONQUERED_SITE, but it is presumably just like site. But what if you combine SITE or LAND_HOLDER with it?
* Stuff about the monarch, its arrival and its entourage.

=Oddities (Bugs)=
Almost everything on this page could be called an oddity. Because of their unexpected usability, some may also be referred to as “undocumented features.” Others, however, are simply odd and not particularly useful, yet I hesitate to call them “bugs.”
* If a certain threshold is reached that makes an elected position electable, and the triggering event that initiates this evaluation is an assumption, then the resulting assumption is also referred to in the messages as an election

=Examples=

===The Founder===
The founder is a single dwarf, appointed at embark. They will be the only one ever to have this position and are not replaceable. When they lose their position some way, the position will not be assumed by another dwarf.
{{gamedata|title=The Founder|
[POSITION:THE_FOUNDER]
[NAME:the founder:founders]
[NUMBER:1]
[SITE]
[ALLOWED_CREATURE:DWARF:ALL] - will only be filled at embark, but not assumable later.
[REJECTED_CREATURE:DWARF:ALL] - will only be filled at embark, but not assumable later.
[SUCCESSION:BY_POSITION:THE_FOUNDER] - not unassignable, also cannot be assigned to a [SQUAD] position.
[PRECEDENCE:200]
Non APPOINTED_BY
Non ELECTED
Optional: Add responsibilities to make the game select a unit with certain skills.
}}
===Marriage bar===
Dwarven matrons are held in great honour. Upon marriage, a female dwarf is no longer expected to perform menial labour. All dwarven males hold this position by default, granting their spouses exemption from menial work.

The position becomes available with the arrival of the first migrants; otherwise, on embark, it would be assumed by females. Its succession rule is non-functional, but this prevents the player from unassigning the position. A squad size of 1 and the succession rules together prevent a unit from assuming the position more than once.

With precedence set to NONE, the position name is hidden, while LAND_NAME remains visible on the nobles screen. All married females receive the suffix “, Mrs.” and are marked as Nobles.

The practical usefulness of this position is debatable, but it serves as a clear demonstration of several mechanics.
{{gamedata|title=Mrs. Urist|

[POSITION:MRS_URIST]
[NUMBER:300]
[SITE]
[ALLOWED_CREATURE:DWARF:MALE]
Not APPOINTED_BY
Not ELECTED
[LAND_NAME:Dwarven male]
[NAME:dwarven male:dwarven male]
[PRECEDENCE:NONE]
[SPOUSE_FEMALE:, Mrs.:spouses]
[MENIAL_WORK_EXEMPTION_SPOUSE]
[REQUIRES_POPULATION:8]
[SUCCESSION:BY_POSITION:MONARCH]
[SQUAD:1:member:members]
}}
===The Archduke===
The archduke is the leader of the civilization, but exists only from landholder 4-level. Until then, its position remains vacant. When a settlement is elevated to tier 4 (grand duke), the grand duke can appoint the ruler of the civilisation, the archduke. Because of 'Premature Succession', they themself inherit that position immediately, but only when in fortress mode. Its heir then becomes grand duke.
{{gamedata|title=The Archduke| no POSITION:MONARCH or other PRECEDENCE:1

[POSITION:THE_ARCHDUKE]
[NAME:archduke:archdukes]
[NAME_MALE:archduke:archdukes]
[NAME_FEMALE:archduchess:archduchesses]
[LAND_NAME:a archduchy]
[NUMBER:1]
[PRECEDENCE:1]
[SUCCESSION:BY_POSITION:GRAND_DUKE]
[APPOINTED_BY:GRAND_DUKE]
(add additional monarch-stuff, like spouse name, demands etc.)

[POSITION:GRAND_DUKE]
[NAME:grand duke:grand dukes]
[NAME_MALE:grand duke:grand dukes]
[NAME_FEMALE:grand duchess:grand duchesses]
[NUMBER:AS_NEEDED]
[LAND_HOLDER:4]
// Optional ...
[PRECEDENCE:19]
[LAND_NAME:a archduchy]
[RESPONSIBILITY:LAW_MAKING]
[RESPONSIBILITY:RECEIVE_DIPLOMATS]
[SUCCESSION:BY_HEIR]
[APPOINTED_BY:THE_ARCHDUKE]
(add additional landholder-stuff)

!!add to [POSITION:DUKE]
[REPLACED_BY:GRAND_DUKE]

}}
{{Category|Modding}}
{{Category|Entities}}
{{Category|Guides}}

Advanced entity position mechanics

2026-02-12T08:35:10Z

Joostheger:

{{Quality|Fine}}
{{Modding}}

= Introduction =

[http://www.bay12forums.com/smf/index.php?topic=182239.0 Discussion thread on the forum]

This page documents observed and tested behavior of entity positions in Dwarf Fortress that is not fully described elsewhere on the wiki. It focuses on advanced interactions between position tokens, including appointment, succession, election, and responsibility handling, across both civilization-level and site-level entities.

The mechanics described here are based on empirical testing in world generation and fortress mode, supplemented where necessary by raw analysis. In several cases, the game’s behavior is determined by evaluation order and interaction between multiple tags, rather than by individual tokens in isolation.

This page is intended for modders and advanced players who are designing or debugging custom entity position structures. It does not restate basic position mechanics, but instead highlights edge cases, non-obvious interactions, and behaviors that may appear inconsistent or undocumented.

Unless stated otherwise, the described behavior applies to current versions of the game and may differ from older releases.

==What is an entity? What is a position?==
An [[entity]] is an organizational structure that can have relationships with other entities, usually known as a [[civilization]] or a "[[site]] government" in the game, but merchant [[guild]]s, religious organizations, necromancer towers, and [[bandit]] groups are also entities. An entity can have positions - in most cases, these are hardcoded and generated by the game, but as for civilizations and sites, the [[raw file]]s can be customised.

A position is a special relationship between a unit and an entity. The unit holding a position has a larger influence over that entity than other citizens. Positions are mostly known as [[nobles]], but in this article. the technical term is used.

=Position levels (Site/Civ) and their interaction=
There are two basic types of positions that are customizable: '''civ(ilization)''' level and '''site level'''. Positions with the tag [SITE] are at site level, positions without the tag [SITE] are at 'civ level'. These two types of nobles can be considered '''loosely related systems'''. There are a few places where they can interact with each other.

Civ-level positions are in charge of the civilization as a whole, managing national [[trade]], laws, and [[war]]s. These are, for example, the vanilla [[monarch]], [[diplomat]] and [[general]]. (Note that the general doesn't do anything in either mode in the current version.)

'''[LAND_HOLDER]''' nobles are also positions at civ-level. These units are members of the national government, but have gained authority over some land or site. Once they do, they move to that place, but their position is still regarded as a civ-level position.

Site-level position holders are members of a site government (subsidiary to the civilization), and manage local affairs in that location. These are, for example, the [[mayor]], the [[sheriff]] and the [[broker]].

==Table of interaction between different position levels==
In this table, the possible interactions between different position levels are summarized.
The header row shows the positions defining the tokens.

The left column shows the position type that is referred to.
Example:
{| {{prettytable}}
|- bgcolor="#ddd"
! referred position-type
! LAND_HOLDER
|-
| civilization
| (baron is) APPOINTED_BY:MONARCH
|}
color coding: 
* Exists in vanilla
* Possible with mods
* Not possible
* possible to some extent.
* not yet fully investigated.
{| {{prettytable}}
|- bgcolor="#ddd"
! referred position-type
! Civilization
! SITE
! LAND_HOLDER
! CONQUERED_SITE

|-
| Civilization
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION '''(1)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION

|-
| SITE
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION '''(2)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY '''(3)''' COMMANDER REPLACED_BY SUCCESSION '''(4)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION

|-
| LAND_HOLDER
| APPOINTED_BY COMMANDER REPLACED_BY '''(6)''' SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION '''(5)'''
| APPOINTED_BY COMMANDER REPLACED_BY '''(7)''' SUCCESSION '''(8)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION

|-
| CONQUERED_SITE
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
|}

Remarks:
# Works only in world-gen, if a unit with that civ-position is present at the site.
# Works only in world-gen, the site-position holding unit will then move to the capital.
# Is completely ignored
# Works only in world-gen.
# Works only in world-gen.
# Won't appear at all
# This is necessary for the landholder chain to work properly, it doesn’t work otherwise.
# This works only outside of the landholder chain, so when landholders are simply regarded as civ-level nobles. might also work in world-gen
#

== Other interactions ==

Unfortunately, interactions with positions of other entities don't seem possible, such as APPOINTED_BY: HIGH_PRIEST. With [VARIABLE_POSITIONS], positions are automatically created with codes like CUSTOM_LAW_MAKER_2, but interaction with these positions don't seem to work, either. For more info on those, see [[Variable positions]]

=General=

==Civ-level nobles living at your site==
Nobles from your civilization can come to live at your fortress. This happens in vanilla with landholders such as [[Baron]], [[Count]] and [[Duke]], with the Monarch, but sometimes also with non-landed LAND_HOLDERS.

When a civ-level noble becomes a [[citizen]] at your location, their position is shown among the site-level positions in your [[nobles screen]]. They appear to function as a site-level noble. They may have [[demand]]s, [[mandate]]s, [[squad]]s and the like. They can appoint nobles at the site-level.

If they have certain [RESPONSIBILITY]ies, they do the tasks that go with them.

==Fortress mode, world-gen and their differences==
Their are a few differences in how positions function between fortress mode (normal play mode) and the world generation (world-gen).

In '''fortress mode''', the player has some control over the appointment of nobles, limited by elections, automatic filled-in positions and succession rules. Pre-fortress mode, which is referred to as '''world-gen''', the game will always attempt to assign nobles whenever possible. It is subjected to the same rules as in fortress-mode, but there are some exceptions. In '''[[World activities]]''', which is the thing that happens in the world while you play fortress mode, it seems as if the same rules are applied as fortress mode.

A difference between player-fortress-mode and world-gen, is causes by visibility (see below). Positions that are not visible by the player and thus not available for assignment, will be available in world-gen and will thus be automatically assigned.

In fortress mode, a position that is both [ELECTED] and [APPOINTED_BY], cannot be appointed by the player and is also not elected, and can thus not be filled. But in world-gen sites however, these positions are automatically filled.

Positions with [AS_NEEDED] are almost never created and filled in world-gen (depending on their [RESPONSIBILITY]ies), but can always be used in player mode.

A position can, in fortress mode, be filled by the same unit. A unit can gain multiple positions in fortress mode, for example because of [[elections]]. This will not happen in world-gen mode: a unit can only have one position. See also remarks on 'embark' and 'Losing a position'.

In world-gen, [SUCCESSION] between civ-levels and [SITE-]levels may happen. This will not happen in fortress mode, or even off-site in [[World activities]].

In fortress mode, premature SUCCESSION may happen. This will not happen in world-gen mode.

==Units holding multiple positions in multiple entities==
A unit can hold multiple positions in its civilisation or in its site-entity, however this does not happen in world-gen. Only at player-managed sites can units be holding multiple positions at once. (It is probably not possible for a unit to hold a position in two different civilisations or two different sites.)

In world-gen, if there are too many positions to be filled, they simply stay empty until more units are available. E.G, a unit at a site might inherit a civ-level position and still remain a member of the local government. When this happens however, they move to the capital. If a unit gains a new position, either inherited or otherwise, it drops the previous one. If a unit assumes a civ-position in fortress mode, it leaves the current position.

If a unit holds the same (site-)position multiple times, it has no additional effect.

If a unit holds multiple different positions of the same entity, it has all those positions' responsibilities and properties, stacked up. Presumably, the demands for those combined positions are determined by the highest.

A unit holding a position with a succession token can be assigned another position with a (different) succession token.

A unit holding a position with a squad-position cannot hold another squad-position. It is dropped from the first, when it gets its second assigned.
A unit holding a position with a succession token cannot be assigned to a squad-position - the unit is simply not available. It works the other way around, though.

=Specific Tags and functions=
==[PRECEDENCE]==
The first defined position with precedence of 1 counts as the ruler of the civ. See also: [[Position_token#PRECEDENCE|PRECEDENCE]].

If the precedence is omitted or has a negative value, the game sets 0 as precedence, which seems to have no effect whatsoever.

When a unit has multiple positions, the name of the position with the highest rank in precedence is shown behind the unit's name.

If you omit precedence entirely, or set it to [PRECEDENCE:NONE], the position name will not be shown after the unit’s name. Your *Urist Mason* will remain simply *Mason*. This can be useful for positions that are unimportant or purely functional. The position will also not appear in the civilisation overview of your site on the world map. The position name is shown in messages, but remains hidden on the nobles screen as well. To make it visible there, use [LAND_NAME].

==[RESPONSIBILITY]ies==
Both civ and [SITE] positions can carry responsibilities. However, not all responsibilities are active for both types: some function only for civ positions, others only for site positions. When a civ noble arrives at a site and takes up residence, they do not perform responsibilities that are intended for SITE nobles. As a result, these responsibilities neither trigger their associated tasks nor unlock related game mechanics. For example, a civ-level manager living in a fortress will not perform management duties there and doesn't unlock the management-screen, even with an assigned office.
This behavior applies to the following [SITE]-level responsibilities:
* [RESPONSIBILITY:ACCOUNTING]
* [RESPONSIBILITY:BUILD_MORALE]
* [RESPONSIBILITY:HEALTH_MANAGEMENT]
* [RESPONSIBILITY:LAW_ENFORCEMENT]
* [RESPONSIBILITY:MANAGE_PRODUCTION]
* [RESPONSIBILITY:MEET_WORKERS]
* [RESPONSIBILITY:TRADE] (functions differently)
Other responsibilities may be affected as well, but have not yet been fully tested.

===World-gen effects of the [RESPONSIBILITY] of available positions ===
It is possible to cause civs and individual sites to change their behavior substantially when they reach a certain size, by controlling nobles.
* If a site can only appoint a position with [MILITARY_GOALS] after reaching a particular size, that site will not send armies on missions until the required size is reached.
* A civ-level [LAW_MAKING] position is required for the civilization to have any kind of cohesion. Without it, sites will be constantly embroiled in territorial disputes and civil wars will be commonplace.
* [MILITARY_STRATEGY] positions go out and tame wild animals. This makes your civ gain those animals as domesticated and also brings them in sieges.
* The [[Personality_facet|Personality]] of the position's holder determines how they lead the civ.

===[DELIVERS_MESSAGES]===
The only [AS_NEEDED]-position that is created in worldgen based on responsibility is that of the site-level responsibility [DELIVERS_MESSAGES].

===Outpost Liaisons and Diplomats===
Civ-positions with the responsibility [ESTABLISH_COLONY_TRADE_AGREEMENTS] ([[Outpost_Liaison|Outpost Liaison]]s) will meet with the site-noble who has responsibility for [RECEIVE_DIPLOMATS] and the highest rank of precedence (i.e. the lowest precedence value). Usually this is the [[Expedition_leader|Expedition leader]].

Once a [LAND_HOLDER] is assigned to the site, civ-positions with the responsibility [MAKE_TOPIC_AGREEMENTS] ([[Diplomat]]s) will meet with '''civ'''-level nobles present at the site who have the [RECEIVE_DIPLOMATS] responsibility. If multiple eligible nobles are available, one is selected at random. If no eligible noble is present, the diplomat leaves angrily. If the landholder is no longer present at the site, diplomats will not arrive at all.

It appears that Outpost Liaisons and Diplomats are chosen for a diplomatic mission based on availability. When multiple candidates exist, the position defined last in the raws is most often selected.

===[TRADE]===
Civ-level nobles with [TRADE] will arrive with the caravan, just as the Outpost Liaison. Their behavior is no longer active in the vanilla game, but the mechanics are still present. See [[40d:Guild_representative|Guild representative]] for more details. This civ-noble will only meet with the SITE noble with [TRADE], usually the [[Broker]].

If two civ-nobles exist with both [TRADE] and [ESTABLISH_COLONY_TRADE_AGREEMENTS], they both arrive at the same time. Even if both tokens are assigned to a single position, if more than one instance of that position exists, two of them will arrive. However in that case, somehow the elevation of the site and appointment of landholder isn't offered.

If the SITE-noble they intend to meet has both [TRADE] and [RECEIVE_DIPLOMATS], only one meeting will proceed and the other is cancelled. However, when two SITE-nobles are available, each with either [TRADE] or [RECEIVE_DIPLOMATS], both meetings will proceed and both civ-nobles will attempt to negotiate a trade agreement. It is not known what happens if these agreements are accepted or refused.

In the trade depot, the last defined position with the [TRADE] responsibility is shown as broker. However when requesting a trader, the first defined position with [TRADE] will actually go there to do the trade.

==[NUMBER]==
A position might be defined with a number. In that case, as many as defined can be available. If the positions become available, in world-gen and when embarking, they are all filled-in completely.

If the ruling position (with PRECEDENCE of 1) has a NUMBER higher than 1, a random unit of the ones holding these positions is shown as ruler in the embark screen.

A [NUMBER] of 0 (zero) has the same effect as 1.

===Automatic spreading of assumed, non-singular positions===
If there are civ positions that have a NUMBER higher then '1' and which are assumed (not APPOINTED_BY or ELECTED) but are '''not DUTY_BOUND''', these are automatically spread among the civilisation, based on population. If there are a number of '''20''' available slots of that position, they spread among a civilization with a combined population of, for example, 1000 of which your fortress has 100 (10%), '''2''' of your fortress' citizens will assume that position.
This may probably also work with elected and appointed positions, but that may be depending on the death of the current holders and this needs more testing. Assumption works within a day, anyway.

===[AS_NEEDED]===
These positions can be created automatically by the game in world-gen. This, however, only works with:
* [LAND_HOLDER]'s
* squad commanders (needs more testing)
* Messengers at sites

For all other types of positions, they're not created in world-gen, even if they are defined with RESPONSIBILITY's. For example, even in war, the game wouldn't create a MILITARY_GOALS position, if they have AS_NEEDED as number.

However, in fortress mode / player mode, these positions can be created by the player at will.

Positions with AS_NEEDED need to be created first, before any symbols are assignable as 'symbols' (objects) for the position holder to carry or wear.

Positions with AS_NEEDED cannot be created and then ELECTED in fortress mode. It only works with APPOINTED_BY.

==[REPLACED_BY] and [REQUIRES_POPULATION]==

The token REPLACED_BY:position means that once the replacing position reaches its required population-number, the 'to-be-replaced' position will disappear. This is defined in REQUIRES_POPULATION. These tags are closely related to each other and seem to only have a meaningful function if combined. Nobles with REQUIRES_POPULATION require the population to have a specific size.

This works on the civ-level as well as on site-level, but those systems are in this mechanic strictly separated. Site-level positions cannot be replaced by civ-level positions and visa versa. This makes sense, because they both depend on their own population-count. When using REQUIRES_POPULATION on civ-level, it counts the total population of the civilisation.

See also: [[Advanced_entity_position_mechanics#Evaluation_of_Positions|Evaluation of positions]]

===Effect of replacement (and on [LAND_HOLDER]s)===

Replacement is immediate and complete - the current holding unit loses the position, even before SUCCESSION_BY_POSITION rules are applied. A position with a number of 1 will replace all the slots of a position with a higher number of slots.

Even if the next position is available but not visible, replacement still takes place. If a position is replaced, it is completely gone - it cannot be appointed, succeeded, elected or assumed any longer.
The unit immediately loses its position.

In legends, replacement is mentioned as: "(unit name) ceased to be (position name)" The replacement of an AS_NEEDED position empties the position's slot forever. In fortress mode, it may seem as if you can create new slots and appoint new units in the nobles screen, but this is reversed as soon as you close the window.

The landholder chain uses [REPLACED_BY] differently. It does not clear the position completely, but uses it for succession to the next level's position. [REPLACE_BY] is required to let that system work properly. This also means that the way in which landholders succeed (replace + as_needed) does not work in any other way.

Replacement between LAND_HOLDERS and other site- or civ positions does not work in any way. Only the vanilla replacement sequence between levels of LAND_HOLDERs does work. If the token is omitted for landholders, the landholder chain is broken, so replacement is required for the landholder system to work.

[REQUIRES_POPULATION] also does not work for [LAND_HOLDER], when you set [NUMBER] to 1. The position is not created when the required population is reached.

===What doesn't work===

'''Attention: If a position cannot be appointed, for example because of 'mutual appointment', it still exists according to replacement mechanics and will replace other positions if so defined. If a certain position(a) will be replaced by the baron's assistant, which can only be appointed by the [LAND_HOLDER] baron, than that position(s) still will be replaced from the start of the game, even if no baron or their assistant is ever present.'''

A position that is replaced by a somehow non-fillable position is still replaced. This counts for mutual-appointing positions, replacement by not-yet-assigned landholders, replacement by AS_NEEDED positions, or replacement by not-yet-appointed positions.

Replacement does not work if the replaced position is a [LAND_HOLDER], even with civ-positions. In that case, the LAND_HOLDER's position is not replaced. It does not matter if AS_NEEDED is used, or a fixed number, and it also does not matter what type of position the replacer is. So this only works (correctly) with positions that become available by REQUIRES_POPULATION.

==[CONQUERED_SITE]==

=Availability and visibility=
==Availability of (new) positions==
Warning: Do not mistake "availability" for "visibility"!

Of all the possible positions existing in your site's entity, there may only be some available.
* Positions with [REQUIRES_POPULATION] require the population to have a specific size.
* Positions with [REQUIRES_MARKET] will only appear in "large" sites (which may have different rules for different site types). This tag has no effect in fort mode.
* Positions that are appointed by positions that have an AS_NEEDED number. The appointable positions only become available after an appointer position-slot is created. This works also on civ-level. If a position is appointed by a Land-holder, it only becomes available, when that level of landholder is created.

Only the replaced positions are culled and are no longer available.
A position that requires a certain population will become available, even if it doesn't have [APPOINTED_BY] or [ELECTED]. In that case, see 'automatic assignment' and 'assumption'

In fortress mode, in some cases 'succession' is evaluated immediately after a position becomes available. See: Succession.
==Visibility of positions==
A position might be available, but can still be invisible for the player in the [[nobles screen]]. The positions with their respective holders are visible for players:
* All site-positions that are already filled-in (even if they could not be re-filled-in considering current conditions)
* Site positions that are appointable by a filled-in site position
* Site positions that are appointable by a filled-in civ position, when that civ positions holder becomes a citizen of your fortress.
* Civ positions of units that are also a citizen of your fortress.
If a position becomes available, for example because a certain pop number has been reached, or if it is available from the start(like expedition leader), as long as it cannot be appointed, it still is INVISIBLE for the player.

It might strike someone as odd if a position becomes filled automatically in fortress mode when that position is not even visible. This might be the case if the current holder of a non-appointable position dies or succeeds another position. Regardless of player visibility, these positions will be automatically filled in if the necessary requisitions are met. It might happen with the expedition leader.

A situation with a non-visible but available position, is for example when a position is solely appointed by the expedition leader, when the expedition leader's position is left vacant. It can no longer be appointed by the player and is invisible. Then, it gets automatically assumed, proving that the position still was available.

A position that is both [APPOINTED_BY] and [ELECTED] is visible, but players cannot interact with it.

={{text anchor|Evaluation of Positions}}=
The game does not continuously check whether positions should become available, elected or be [REPLACE_BY]. This is well-known behavior—for example with the [[mayor]], who does not appear automatically when the required population ([REQUIRES_POPULATION]) is reached. Instead, positions must somehow be evaluated. This applies in several other situations as well

'''Cases that require a trigger:'''
* Election of a newly created position
* Election after the current holder dies
* Automatic assumption of a newly created position (this may take up to a day)
* New citizens (such as migrants) considering available positions
* Premature succession of a newly created position

'''Cases that do not wait for a trigger:'''
* Succession following the death of the previous holder
* Automatic assumption of existing positions that have become vacant

'''Triggers that cause the game to reevaluate noble positions:'''
* Succession of a [SITE]-position due to the death of the current holder
* [[Advanced_entity_position_mechanics#Election_Day|Election Day]]
* Automatic assumption of a [SITE]-position that becomes vacant
* (Re)assigning any site position manually
* Settlement elevation on the LAND_HOLDER track (e.g. gaining a [[Baron]] or [[Count]])

=Gaining a position=
There are several ways a unit can gain a position:
* Appointment: A unit is appointed by another unit or by the player.
* Election: A unit is elected by and among the members of the entity
* Assumption: A position is neither elected or appointed: a random unit just simply 'takes' the position
* Succession: a unit is the valid successor of this position(A), either by its current position(B) or because they are that position(A)-holder's heir.

Available positions will automatically be assigned to a random civ member when a new site/civ is created.

==Who can take a position==

* If so defined, a unit needs to be the right caste and/or class - it does not seem to work with creature types.
* The unit needs to be an adult member of the site or its parent civ's government; that is also CAN_LEARN or INTELLIGENT (SLOW_LEARNER cannot take positions) or otherwise is able to think.

==Appointment==

Positions that have an [APPOINTED_BY:position] token require that position to exist, to be available and appointed. Any position that is APPOINTED_BY can be appointed if the appointer's position is filled in.
For site-positions to be appointed, it is required that the appointer is present at that location.

If the appointing unit is temporarily not present, or if that position is not filled, positions depending on it cannot be appointed. This is the case with [[militia captains]], when the [[militia commander]] is on a [[mission]].

A site position cannot appoint a civ position ''or'' LAND_HOLDER in any way whatsoever.

Civ-level positions can appoint other civ-level positions and site-level positions can appoint other site-level positions.

Contrary to what has been said elsewhere, civ-level nobles also can appoint site-level nobles. They need to be at the site to do so. Landholders can appoint both site-level and civ-level nobles. These systems are therefore not as separate as was assumed.

'''Mutual appointment''' cannot take place. If these are the only requisites of the position, then the positions will never appear or get filled. These unfillable positions can be put to good use, for example, to replace a position that is no longer needed without creating a new one.

'''Self appointment''' doesn't normally work. If you have a position that is only appointed by itself, it is never appointed and also cannot be assumed. However, if the position has a number higher than 1, and is filled by multiple units (for example by another position that is now empty), than those units can re-assign or appoint each other from that their shared position.

If an APPOINTED_BY token refers to a non-existing position's code, the effects are as if the appointment token doesn't exist at all.

===Automatic appointment in world-gen and on the civ level===

Outside of fortress mode, the game will always attempt to appoint nobles whenever possible, as long as these positions are '''available''', even if they are invisible to the player.
It shows this message in legends: "(unit name) has been appointed to the position of (position name)"

In world-gen, all positions become available and are automatically appointed, taking population- and appointment-requirements into consideration.

Positions that are REPLACED_BY are culled and won't be filled.

If a citizen of your fortress holds a civ-level position that can appoint another civ-level position, the appointment will happen automatically and without player intervention. It may happen that another citizen of your fortress is appointed by that unit, creating civ-level position holders in your fortress, but it is unknown what is required to force this effect.

===Manual appointments by players in fortress mode===
In fortress mode, the positions that need to be appointed stay empty on embark. and it is the player's job to appoint those. A player can appoint a unit to any available position, according to the hereabove mentioned conditions. The player takes the role of the automatic appointment-system, but has no direct control over elections, successions and replacement. There are some differences in what is possible at world-gen sites and at player-controlled sites.

* A position that is appointed by a unit present as a fortress citizen, can be appointed, re-appointed or left vacant. This means also by civ-level nobles living as a citizen in your fortress; not when they are only visiting, like the diplomat.
* A position whose appointing positions are all either vacant or [REPLACED_BY] can no longer be appointed. If the position is already filled, it cannot be reappointed or vacated; the current holder simply remains in office.
* A position that is APPOINTED_BY a unit present as the land_holder of your site, can be appointed, reassigned or left vacant.
* A position that has SUCCESSION BY_HEIR or BY_POSITION can 'initially' be appointed and also re-appointed or left vacant, but as soon as the [[nobles]] screen closes, ''it can no longer be replaced or left vacant''. From then on, the succession-rules determine who gains that position when the current holder loses the position. This works even if the SUCCESSION:BY_POSITION-position is vacant or replaced.
* A position that is ELECTED nor APPOINTED_BY, can always be (re-)appointed by the player. This is the case with the [[Expedition leader]]. If it is left vacant however, it cannot be appointed, but will be assumed shortly after.
* A position that is both ELECTED and APPOINTED_BY, cannot be appointed by the player. Contrary to world-gen sites, its slot is visible, but it doesn't show the +-sign. This is either by AS_NEEDED or by a fixed number. Even if the position somehow gets filled (re)assignment is never possible
* A player can appoint a number of units to a position, as much as the NUMBER token dictates. If it is AS_NEEDED, the player may create as many slots as they like, also contrary to world-gen sites.
* A civ-position can never be appointed, even if the appointing civ noble is a citizen of your fortress. A civ position also never can be re-assigned or left vacant, would that position be defined as appointed by a site-position.

==Election==
Read more in [[Elections]]. The message that is shown is: "(creature name) has been elected to the position of (position name)"

In worldgen, there is no functional difference between ELECTED and non-appointment, except that elected nobles tend to have high social skills and/or skills related to the position, while non-elected ones are assigned randomly. See: [[Elections]]

A succession goes before an election.

A position that is both ELECTED and APPOINTED_BY never gets elected. Even if the appointees' position somehow gets filled, (re)-elections won't happen. So, it doesn't seem possible to have an elected position become available when a certain other position becomes filled.

An ELECTED civ-(or LAND_HOLDER) position at your site will never be (re)-elected in fortress mode. So real (re-)election only works with SITE-positions.

=== {{text anchor|Election Day}} ===
Election Day takes place on the 17th of Summer. On this day, a full reevaluation is performed, including all currently elected positions, which are subject to re-election. Contrary to the information on [[Elections]], nothing occurs at the start of a season.

Positions that are both [APPOINTED_BY] and [ELECTED] will not be re-elected on Election Day when assigned through [SUCCESSION].

=== Election Eligiblity ===
Any citizen may stand for election. Eligibility cannot be restricted using [ACCEPTED_CREATURE], [REJECTED_CREATURE], [ACCEPTED_CLASS], [REJECTED_CLASS], or [GENDER]. Units currently having a [SUCCESSION]-position even may be elected for a position with a [SQUAD]-token, which is otherwise impossible to assign or even succeed.

=== Skills ===
In elections, skills are taken into account for the tokens of the position which is elected.
{| class="wikitable"
|+ Relevant skills per position token
|-
! Position Token !! Relevant skills
|-
| Responsibility [[Position_token#DELIVER_MESSAGES|[DELIVER_MESSAGES]]] || [[Ambusher]], [[Observer]] and [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#ACCOUNTING|[ACCOUNTING]]] || [[Record_keeper|Record keeper]]
|-
| Responsibility [[Position_token#ESPIONAGE|[ESPIONAGE]]] || [[Schemer]]
|-
| Responsibility [[Position_token#HEALTH_MANAGEMENT|[HEALTH_MANAGEMENT]]] || [[Diagnostician|Diagnostician]]
|-
| Responsibility [[Position_token#MAKE_INTRODUCTIONS|[MAKE_INTRODUCTIONS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#MAKE_PEACE_AGREEMENTS|[MAKE_PEACE_AGREEMENTS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#MAKE_TOPIC_AGREEMENTS|[MAKE_TOPIC_AGREEMENTS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#MANAGE_PRODUCTION|[MANAGE_PRODUCTION]]] || [[Organizer]]
|-
| Responsibility [[Position_token#MEET_WORKERS|[MEET_WORKERS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#RECEIVE_DIPLOMATS|[RECEIVE_DIPLOMATS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#RELIGION|[RELIGION]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#TAME_EXOTICS|[TAME_EXOTICS]]] || [[Animal_trainer|Animal trainer]]
|-
| Responsibility [[Position_token#TRADE|[TRADE]]] || [[Social_skill|Social skills]] and [[Appraiser|Appraiser]]
|-
| [[Position_token#SQUAD|[SQUAD]]]-token || [[Tactician]] and [[Leader]]
|}

==Assumption==

A position that is not APPOINTED_BY nor ELECTED, or is appointed by positions that are not available in your site or civ, will be assumable by a random dwarf. If it has responsibilities that require certain skills, then these are taken into consideration on embark, but not when the position is assumed during the actual game.

Normally, one to three units will take the into consideration to assume a position. Most of the time when there are multiple open positions, only a single unit will assume all of them. However, a position that has REJECTED_CREATURE, REJECTED_CLASS, ALLOWED_CREATURE or ALLOWED_CLASS will be filled with all different units, even if the creature or class mentioned is irrelevant. It seems that this forces the game to loop over all the available units.

The message that is shown in Legends mode is: "(unit name) has assumed the position of (position name)". This may also take place in fortress mode, which then shows this message to the player.

If an assumable position becomes empty, it will be assumed within a day. This is the case when you leave the position of expedition-leader vacant. It also happens with entities.

Assumable positions that become empty will not be assumed if that position has a valid [SUCCESSION] -successor. In that case, the successor inherits the position.

Even positions that are somehow invisible because they cannot be directly APPOINTED_BY players, can be assumed.

When you embark, the assumable positions are automatically assigned to a random unit. If there are multiple of these positions at embark, they all are assigned to the same unit. If there are enough positions available, multiple units may gain a position, but often no more than three different ones.

If a dwarf in fortress mode assumes a position, that already has another position, it will leave the current position empty. When that position also is assumed, then this will continue until all positions have a dwarf appointed to them, with no other position.

A unit that already has a position with a [SUCCESSION] token won't take assumable positions into consideration that have a [SQUAD] token. This can be used by the modder to prevent unwanted loss of current positions.

A position that has an appointer which got replaced because of REPLACED_BY, will not become assumable. Also, positions that have an AS_NEEDED appointer that is not yet filled (or ever), will also not be assumed.

==Succession==

If a position-holder dies or advances to a new position via succession, the position will be granted to another unit based on the [SUCCESSION] tag. If they have an heir or the succeeding position exists, that unit will be assigned. If not, a new one will be appointed according to the usual rules. The message that is shown is: "(creature name) being the rightful heir, has inherited the position of (position name)"

The succeeding creature will also lose its previous position. When succession is defined using BY_POSITION, the unit naturally loses the referenced position. However, it also loses any other positions it may hold. If a unit could simultaneously inherit multiple positions, the last-defined succession overrides the earlier one, clearing the previously acquired position

Succession works both at site-level and at civ-level, both in world-gen and in fortress-mode. Succession by position on the civ-level is also visible and functional in fortress-mode. If both civ-level nobles are a citizen of your fortress, succession is applied visually. Vanilla example: The [[druid]] is succeeded by the [[acolyte]]. This means that as soon as the druid dies, the acolyte takes over.

When a position that is succeeded by position becomes available, immediately it is checked if a position-successor is available and the position is filled with that unit. Even if this is an [ELECTED] position, succession goes first. When elections eventually do happen, succession plays no role.

It is possible to assign multiple levels of [SUCCESSION:BY_POSITION] in different positions, creating a line of positions where the death of one causes all those "below" them to advance.

A position can have multiple tokens with position-succession. It looks to be random which one is used. It is not always:
* The first or last defined token
* The first or last appointed unit
* the oldest or youngest
* one with a higher or lower precedence
* a unit with relevant skills

When a position is defined with a Succession-type, that unit cannot have another position that has a Squad-type. If the succession-position itself has a squad, than it can be assigned another position with a squad, but then it will loose the previous succesion position. See further details by "Squad"

Assumed positions can also be succeeded by position, if the current holder dies.

If the successor is an AS_NEEDED position, the used unit will leave a vacant position-slot on its removal by succession. This empty slot remains a real slot, which will only be cleaned up if you (un)appoint a unit to this position-series. It isn't cleaned up after regular position validation.

A civ-level position of a unit living at your site might be inherited by a unit holding that does not currently live at your site. This, unfortunately, moves that position to a unit off site. This may also happen with the landholder of your site, for example when it is succeeded by another civ-level position. This currently poses an unsolved challenge.

===Eligibility for succession===
Succession is restricted by the tokens [ACCEPTED_CREATURE], [REJECTED_CREATURE], [ACCEPTED_CLASS], [REJECTED_CLASS] and [GENDER].

===Site and civ combined succession===

Succession can work when combining site positions with civ-level positions or land_holders, but only in world-gen mode. In fortress mode, it only works with combining the same level of nobles, with Landholders regarded as civ-level. So, in fortress mode, a site's position cannot succeed a landholder's position and it cannot succeed another type of civ-level position, and vice versa.

This won't work even if the positions:
* are AS_NEEDED or having a fixed number.
* Are LAND_HOLDERs.

===Succession [BY_HEIR]===

When a heir is needed for succession, all children and then other relatives are validated. They cannot take the position if their status does not allow it, for example if they have become a member of another civilisation. See: "Who can take a position". If the unit has no valid heir on that location, the position may go to a unit living on another site. This may cause the title of Landholder of some land to be inherited by a unit living somewhere else. That might be a problem, because then you lose your landholders.

===Premature Succession===

There are cases where [SUCCESSION:BY_POSITION] is applied prematurely: at the moment a position is first created and becomes appointable or assumable, rather than after a current holder leaves. In this situation, the succession mechanism assigns a holder immediately, without any player interaction.

When a position becomes available for the first time, the game checks whether a valid successor-by-position exists. If so, that unit is assigned instantly. It can affect positions that would normally be appointed or elected by the player, causing succession to trigger before the player has any opportunity to intervene.

This behavior occurs only in Fortress mode, but can be applied both on [SITE]-positions as well in civ-positions. That last one however is a bit harder to control. Example: [[Advanced entity position mechanics#The Archduke|The Archduke]]

This premature succession only occurs the first time a position becomes available (i.e. when it is created and becomes appointable or assumable). Even if the position remains vacant and the conditions for succession improve later, premature succession will not trigger again. From that point onward, only normal succession rules apply.

Using premature succession, a position that has [ELECTED], [APPOINTED_BY], or both, can be filled directly.
Notably, positions that combine [ELECTED] and [APPOINTED_BY] are normally impossible to fill through regular mechanics. Premature succession bypasses both election and appointment entirely, making this combination uniquely reachable through this mechanism.

No initial election takes place, and no subsequent elections will ever occur for that position. Succession always takes precedence over election, both in premature succession and in normal succession cases.

This behavior applies only in Fortress mode, not during world generation. World-gen uses simplified and more efficient mechanics, and this interaction does not occur there. Premature succession can affect both site-level and civilization-level positions.

====Multiple succession chains====

Multiple succession chains may be defined and are resolved in the order they appear in the raws.

If a position has both:
* a direct succession chain (A → C), and
* a multi-step chain (A → B → C),

and intermediate positions are vacant, resolution proceeds according to raw order. A common outcome is:
# The direct succession (A → C) is applied first, assigning A to C.
# The remaining chain then advances (A → B).
# If C still has empty slots, the final step (B → C) may occur.

If position B is already filled, behavior depends entirely on raw definition order:
* nothing may happen, or
* B may move to C first, followed by A moving to B.
====Working triggers====
Premature succession is triggered when a succeedable position is created under the following conditions:
* The succeedable position is created because its [REQUIRES_POPULATION] threshold is reached. This applies even if the position is not [APPOINTED_BY]. Premature succession takes priority over automatic assumption (e.g. the mayor declaring themselves within a day).
* The succeedable position can be [APPOINTED_BY] another position of the same level (site or civ) that has just been created because its [REQUIRES_POPULATION] was reached.
* The succeedable position can be appointed by another [SITE] [AS_NEEDED] position that has just been created and filled.
* The succeedable (site or civ) position is [APPOINTED_BY] the [LAND_HOLDER] position, which has just been created due to site elevation. This typically resolves when the diplomat leaves the map, at which point the landholder position becomes active.
* If all other requirements are met, premature succession can occur immediately after unpausing following embark, for positions with [REQUIRES_POPULATION:7].
====Non-working triggers====
Premature succession does '''not''' occur in the following cases:
* An [AS_NEEDED] succeedable position slot is manually created by the player while its succeeding position is already filled. [AS_NEEDED] positions must always be appointed after creation.
* The succeeding position is filled after the succeedable position becomes available. The moment of creation is the decisive trigger; filling the source position later is too late.
* The succeedable position can be appointed by another site or civ position with a fixed number of slots that has just been appointed. In this case, the succeedable position is just available for appointment itself, nothing more
* Any situation occurring during world generation.
* The succeeding position is [REPLACED_BY] the succeedable position. In this case, replacement removes the unit from the source position first, leaving no holder available for the succession mechanism to use.rst, leaving no holder available for the succession mechanism to use.
* The position is [APPOINTED_BY] a civ-level position, that just became a citizen of your fortress. It must be noted that those civ-level positions were active all that time and the succeedable position could be appointed even before. The monarchs arrival does not trigger premature succession

=Losing a position=

A unit can lose a position when:
* It dies
* It succeeds another position, even if it has nothing to do with the previous position.
* It is assigned to another SQUAD-holding position
* It is convicted of a crime.
* Another unit is ELECTED for the position
* Its position becomes replaced
* Another unit is appointed by the player, or the position is left vacant.
* It has assumed another position, as this always leaves the previous position vacant.

=Embarkment=
Two types of positions are automatically filled by embark.
* Positions without [APPOINTED_BY] or [ELECTED] (assumable). All these positions, even with a NUMBER higher than 1, are all filled with one to three dwarves. Contrary to assumption, this doesn't take into account any limitations. REJECTED_CLASS, ALLOWED_CLASS, REJECTED_CREATURE, ALLOWED_CREATURE and GENDER are applied, but without the normal spread you may expect with assumptions. Also it doesn't look at [SUCCESSION] and [SQUAD] limitations.
* Positions that are elected are filled-in by the normal election rules.

Positions that have a defined appointer are never initially filled at embark.

All positions that don't have [REQUIRES_POPULATION] or with a [REQUIRES_POPULATION] of 7 or lower, will be available at embark.

=Land Holders=

A Landholder is a '''special civ-level noble''' who gets a certain piece of land to hold, when that land is elevated to a certain level, determined by the tag [LAND_HOLDER] and by the landholder triggers in the game's settings. In vanilla, these are the baron, the count and the duke.

A unit gaining the landholder position does not migrate to that specific named land. In world-gen, they stay just where they are, probably at the capital. In fortress mode, you can suggest a citizen for the role. So for the time being that works.

Succession is then a real issue. If you use BY_HEIR, its solved when that landholder has children living at your site. But when its not the case, the title just goes to anyone randomly. Succession BY_POSITION works, but only in the civ-chain, and there's no way to guarantee a civ-holder is at your site at that time. Even with 'automatic spread' positions, it goes to one of them randomly.

==Functioning of the regular landholder chain==

The distinct difference between a landholder and a regular civ-level noble, is that a landholder may gain the position of landholder "of (sitename)" They are then seen as ruler of a particular site.

For a land_holder position to function as such, it has a few requirements:
* NUMBER:AS_NEEDED
* The first landholder-number of 1 is defined.
* No SITE (so civ) tag in that position.
*REPLACED_BY the next level landholder
If a landholder is defined with differentiating properties, it will function like a regular noble. A higher-up landholder that lacks the required tokens or connections will then not be used in elevation.

If a fortress meets the trigger for a new LAND_HOLDER tier when a caravan leaves, then the next time the outpost liaison or equivalent arrives, they will offer to make you an official colony, which will allow you to select all positions for that LAND_HOLDER level. Each time they appear, the outpost liaison will only promote your fortress one tier up the LAND_HOLDER track.

The landholder's LAND_NAME is not required for the functioning of this system. If omitted, messages will be shown with a more generic text.

==Appointment==

This mechanism differs from the regular methods of position management. It ignores all regular appointment- and election rules, so it more or less functions like automatic assignment. A landholder is, in vanilla, appointed by the monarch. Changing this doesn't seem to do anything. If they are appointed by a site-position, a not-yet-existing civ-position, or not appointed at all: the system keeps working as usual.

A landholder can appoint civ-positions and site positions. This works as expected: the positions only are appointed then when that landholder becomes available on civ-level or when he arrives at that site for site-level positions.

If your rank of landholder is the first of its rank in the realm, and is the sole appointer of some civ-position, then immediately as it gains the title, it will appoint the empty civ-slots. This may happen on your site, but the frequency and certainty is hard to determine.

==Succession==

Succession rules are applied to some extent:
* In world-gen it works according to succession rules, and site-positions can be used here. This means that a site position or a civ-position can inherit a landholder position, and vice versa.
* In fortress mode, once a landholder has been appointed, it then can inherit civ-level positions, and vice versa. This means that your baron can become king.
* Succession rules do not apply within the [LAND_HOLDER] chain; a count will not inherit a baron's land. This is because succession does not work well with the AS_NEEDED token.
* Premature succession works in fortress mode with landholders. If a unit gets a landholder's position and that landholder is the appointer of an as yet empty position, which is defined as succeeding from a third one, then the succession is immediately applied. The landholder themselves can even be the successor of a newly created position.
* A landholder's position is, in fortress mode, not successionable by a site-position or vice versa

===Impossibilities for succession by a site-position===
It would be very beneficial if the landholder can be succeeded by a [SITE]-position. So far, the following tests have not lead to positive results:
* making landholder and site-position both non-[DUTY_BOUND]
* make the site-position be [APPOINTED_BY] the landholder and/or the monarch
* give landholder and site-position [REJECTED_CREATURE]
* Let the monarch live at your site when succession could happen.
* Let the site-position be [REPLACED_BY] the landholder.

==Nomination==

The player is able to nominate a unit to become the LAND_HOLDER, but this only works with units of [LAND_HOLDER] level 1. The player can select all units, only limited by the PRECEDENCE of the current units' positions.

A unit that has a position with a PRECEDENCE lower or equal to that of the landholder's position, cannot be selected. This means that a baron (or count) from another site or the monarch cannot be selected, because their precedence is lower or equal.

The GENDER token does not work here: also units with the wrong gender (sorry) can be selected.

==Levels==
In mods, up to 10 levels of LAND_HOLDER may be defined.

If a landholder is replaced by a wrong landholder number (1 replaced by 3), then the number 3 is still correctly attached to the settlement.

If the current landholder has the highest available landholder number, then the next elevation will not happen - the diplomat will not elevate your fortress to a higher position, even if that position might be REPLACED_BY a lower landholder.

These chains do work:
* 1 -> 2a - > 2b -> 3
* 1 -> 3 -> 2 -> 4

These chains do not work:
* 2 -> 3 (need to start at 1)
* 1 -> 4 -> 2 -> 3 (stops after 4 as the highest)
* 1a -> 2, 1b -> 2 (only 1a and 2 work, 1b is not used)

==Moving landholders==

It may happen that a land-holder no longer lives at the site which they are the landholder of, specifically when the current landholder dies, leaving the title to an heir living somewhere else.

To prevent this from happening, you can make their succession from heir and make sure that their kids live at your site. Or, you can make their position succeeded by another civ position, and make it so that this civ position is somehow available on your site. But if multiple of these positions exist, it cannot be guaranteed that a citizen of your fortress will inherit the title.

In world gen, a landholder lacking the DUTY_BOUND-token will also move to the site they like, according to legends mode.

==Replacement by a generic civ-position==

If a landholder is replaced by an AS_NEEDED non-landholder civ-position, then this will work: the current landholder loses that title upon settlement-elevation and gains that civ-title. However, the civ-title lacks the landholder-property of being attached to the land. It will not show the name of the settlement alongside the position's name. So no "minister of Shovelmounts"

If a landholder is replaced by a general AS_NEEDED civ-position, that itself is also replaced by a generic AS_NEEDED civ-position, then firstly the elevation is executed and also the unit gains that new position. However, he immediately loses it, because an AS_NEEDED position that is replaced by another position can be filled initially, but units wont be able to hold that title.

==Landholder with fixed number==

A landholder's position that has a fixed number will be created and filled directly when the civilisation is born, so this position slot is then not available for the regular landholder-mechanic and will also not be used. That landholder will thus not be attached to a settlement.

It doesn't matter if the landholder's position is connected to the regular landholder's-chain with the REPLACE_BY token.

==Responsibilities==

When given a certain [RESPONSIBILITY], a landholder may function as a regular civ-level noble. If the position has [TRADE] or [OUTPOST_NEGOTIATING] responsibilities, then the landholder functions both as a diplomat and as an actual land holder. A landholder with the [MILITARY_STRATEGY] responsibility will travel around taming creatures in world-gen, according to legends mode.

Besides that, the responsibilities work the same as with any other on-site living position-holder, civ or otherwise.

=Military=
==Squad management==
In the vanilla game, the Squad interface only becomes available after a militia commander has been appointed. Until then, the window displays:{{DFtext|You must appoint somebody first to create a squad.}}

What’s surprising is how this is determined internally. In the entity raw definition, '''only the last two positions that include a [SQUAD] token are checked''' to decide whether the interface is accessible at all. As a result, if your hierarchy defines commanders A through E, appointing '''Commander D or E''' unlocks squad formation, while appointing A–C does nothing.

In other words, squad availability is not tied to ''having a militia commander'', but to ''which specific positions happen to be last in the raw list''—a notably hacky implementation.

These 'last two' are always the last two '''available positions.''' So if they get [REPLACED_BY] or become available because of [REQUIRES_POPULATION], the game adapts to those.

==Squad assignment==

Squads can be assigned, even if the leader position has no holder.

A specific unit can only have one position associated with a squad. If it gains another 'squad holding position', it is unassigned from the first one. This does not work with a 0-squad, so only 1+squads are taken into consideration. This technique can possibly be used to distribute all positions equally among all citizens. It does however not work with election and assumption.

If a civ-level position is associated with a squad and it gets a site-level squad-holding position assigned, it loses the current civ-position.

Squads can get really messed up, if you make the position (or multiple) either elected or not-elected and not-appointed, then this can cause the game to assign multiple squads to the same unit. Automatic assignment and election does not take squads into account, but the nobles screen does. This can cause the positions to be cleared as the game figures out that they have more than one position, and immediately get elected or assumed again.

Positions that cannot have a squad-position:
* A site- or civ-position with a [SUCCESSION] token cannot be appointed a squad-holding-position. The other way around, however, does work. For example, if a site-position with a [SUCCESSION]-token is appointed to a unit that has already a position with [SQUAD]. But when that squad position is assigned to another unit, it cannot be assigned back.
* A position with [SUCCESSION] can also not be assigned as a '''member''' of a squad.
* A squad-holding position with a formed squad cannot be appointed to another squad holding position.

If a position has at least one squad member, it cannot be left vacant. First, the squad has to be disbanded, then the position may be cleared.

==0-squads==
A 0-Squad is defined in a position as [SQUAD:0:member:members]. It does not seem to do anything useful as of now.
* It cannot be used to activate the [[Squad|military interface]]
* It does not restrict the assignment of [SUCCESSION] positions.
* Assigning this position does not clear any previously held squad position.
* The [[Leader]] and [[Tactician]] skill are not marked as relevant skills and are not taken into account in elections.
* It cannot be formed as a squad.

=Further testing=
The following questions may need additional testing. Feel free to add or answer
* Everything regarding COMMANDING and army-structure
** [http://www.bay12forums.com/smf/index.php?topic=175437.msg8331668#msg8331668]
** [http://www.bay12forums.com/smf/index.php?topic=165213.msg8335682#msg8335682]
** [http://www.bay12forums.com/smf/index.php?topic=174584.msg8026854#msg8026854]
* Everything regarding CONQUERED_SITE, but it is presumably just like site. But what if you combine SITE or LAND_HOLDER with it?
* Stuff about the monarch, its arrival and its entourage.

=Oddities (Bugs)=
Almost everything on this page could be called an oddity. Because of their unexpected usability, some may also be referred to as “undocumented features.” Others, however, are simply odd and not particularly useful, yet I hesitate to call them “bugs.”
* If a certain threshold is reached that makes an elected position electable, and the triggering event that initiates this evaluation is an assumption, then the resulting assumption is also referred to in the messages as an election

=Examples=

===The Founder===
The founder is a single dwarf, appointed at embark. They will be the only one ever to have this position and are not replaceable. When they lose their position some way, the position will not be assumed by another dwarf.
{{gamedata|title=The Founder|
[POSITION:THE_FOUNDER]
[NAME:the founder:founders]
[NUMBER:1]
[SITE]
[ALLOWED_CREATURE:DWARF:ALL] - will only be filled at embark, but not assumable later.
[REJECTED_CREATURE:DWARF:ALL] - will only be filled at embark, but not assumable later.
[SUCCESSION:BY_POSITION:THE_FOUNDER] - not unassignable, also cannot be assigned to a [SQUAD] position.
[PRECEDENCE:200]
Non APPOINTED_BY
Non ELECTED
Optional: Add responsibilities to make the game select a unit with certain skills.
}}
===Marriage bar===
Dwarven matrons are held in great honour. Upon marriage, a female dwarf is no longer expected to perform menial labour. All dwarven males hold this position by default, granting their spouses exemption from menial work.

The position becomes available with the arrival of the first migrants; otherwise, on embark, it would be assumed by females. Its succession rule is non-functional, but this prevents the player from unassigning the position. A squad size of 1 and the succession rules together prevent a unit from assuming the position more than once.

With precedence set to NONE, the position name is hidden, while LAND_NAME remains visible on the nobles screen. All married females receive the suffix “, Mrs.” and are marked as Nobles.

The practical usefulness of this position is debatable, but it serves as a clear demonstration of several mechanics.
{{gamedata|title=Mrs. Urist|

[POSITION:MRS_URIST]
[NUMBER:300]
[SITE]
[ALLOWED_CREATURE:DWARF:MALE]
Not APPOINTED_BY
Not ELECTED
[LAND_NAME:Dwarven male]
[NAME:dwarven male:dwarven male]
[PRECEDENCE:NONE]
[SPOUSE_FEMALE:, Mrs.:spouses]
[MENIAL_WORK_EXEMPTION_SPOUSE]
[REQUIRES_POPULATION:8]
[SUCCESSION:BY_POSITION:MONARCH]
[SQUAD:1:member:members]
}}
===The Archduke===
The archduke is the leader of the civilization, but exists only from landholder 4-level. Until then, its position remains vacant. When a settlement is elevated to tier 4 (grand duke), the grand duke can appoint the ruler of the civilisation, the archduke. Because of 'Premature Succession', they themself inherit that position immediately, but only when in fortress mode. Its heir then becomes grand duke.
{{gamedata|title=The Archduke| no POSITION:MONARCH or other PRECEDENCE:1

[POSITION:THE_ARCHDUKE]
[NAME:archduke:archdukes]
[NAME_MALE:archduke:archdukes]
[NAME_FEMALE:archduchess:archduchesses]
[LAND_NAME:a archduchy]
[NUMBER:1]
[PRECEDENCE:1]
[SUCCESSION:BY_POSITION:GRAND_DUKE]
[APPOINTED_BY:GRAND_DUKE]
(add additional monarch-stuff, like spouse name, demands etc.)

[POSITION:GRAND_DUKE]
[NAME:grand duke:grand dukes]
[NAME_MALE:grand duke:grand dukes]
[NAME_FEMALE:grand duchess:grand duchesses]
[NUMBER:AS_NEEDED]
[LAND_HOLDER:4]
// Optional ...
[PRECEDENCE:19]
[LAND_NAME:a archduchy]
[RESPONSIBILITY:LAW_MAKING]
[RESPONSIBILITY:RECEIVE_DIPLOMATS]
[SUCCESSION:BY_HEIR]
[APPOINTED_BY:THE_ARCHDUKE]
(add additional landholder-stuff)

!!add to [POSITION:DUKE]
[REPLACED_BY:GRAND_DUKE]

}}
{{Category|Modding}}
{{Category|Entities}}
{{Category|Guides}}

Advanced entity position mechanics

2026-02-12T08:31:02Z

Joostheger: /* Specific Tags */

{{Quality|Fine}}
{{Modding}}

= Introduction =

[http://www.bay12forums.com/smf/index.php?topic=182239.0 Discussion thread on the forum]

This page documents observed and tested behavior of entity positions in Dwarf Fortress that is not fully described elsewhere on the wiki. It focuses on advanced interactions between position tokens, including appointment, succession, election, and responsibility handling, across both civilization-level and site-level entities.

The mechanics described here are based on empirical testing in world generation and fortress mode, supplemented where necessary by raw analysis. In several cases, the game’s behavior is determined by evaluation order and interaction between multiple tags, rather than by individual tokens in isolation.

This page is intended for modders and advanced players who are designing or debugging custom entity position structures. It does not restate basic position mechanics, but instead highlights edge cases, non-obvious interactions, and behaviors that may appear inconsistent or undocumented.

Unless stated otherwise, the described behavior applies to current versions of the game and may differ from older releases.

==What is an entity? What is a position?==
An [[entity]] is an organizational structure that can have relationships with other entities, usually known as a [[civilization]] or a "[[site]] government" in the game, but merchant [[guild]]s, religious organizations, necromancer towers, and [[bandit]] groups are also entities. An entity can have positions - in most cases, these are hardcoded and generated by the game, but as for civilizations and sites, the [[raw file]]s can be customised.

A position is a special relationship between a unit and an entity. The unit holding a position has a larger influence over that entity than other citizens. Positions are mostly known as [[nobles]], but in this article. the technical term is used.

=Position levels (Site/Civ) and their interaction=
There are two basic types of positions that are customizable: '''civ(ilization)''' level and '''site level'''. Positions with the tag [SITE] are at site level, positions without the tag [SITE] are at 'civ level'. These two types of nobles can be considered '''loosely related systems'''. There are a few places where they can interact with each other.

Civ-level positions are in charge of the civilization as a whole, managing national [[trade]], laws, and [[war]]s. These are, for example, the vanilla [[monarch]], [[diplomat]] and [[general]]. (Note that the general doesn't do anything in either mode in the current version.)

'''[LAND_HOLDER]''' nobles are also positions at civ-level. These units are members of the national government, but have gained authority over some land or site. Once they do, they move to that place, but their position is still regarded as a civ-level position.

Site-level position holders are members of a site government (subsidiary to the civilization), and manage local affairs in that location. These are, for example, the [[mayor]], the [[sheriff]] and the [[broker]].

==Table of interaction between different position levels==
In this table, the possible interactions between different position levels are summarized.
The header row shows the positions defining the tokens.

The left column shows the position type that is referred to.
Example:
{| {{prettytable}}
|- bgcolor="#ddd"
! referred position-type
! LAND_HOLDER
|-
| civilization
| (baron is) APPOINTED_BY:MONARCH
|}
color coding: 
* Exists in vanilla
* Possible with mods
* Not possible
* possible to some extent.
* not yet fully investigated.
{| {{prettytable}}
|- bgcolor="#ddd"
! referred position-type
! Civilization
! SITE
! LAND_HOLDER
! CONQUERED_SITE

|-
| Civilization
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION '''(1)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION

|-
| SITE
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION '''(2)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY '''(3)''' COMMANDER REPLACED_BY SUCCESSION '''(4)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION

|-
| LAND_HOLDER
| APPOINTED_BY COMMANDER REPLACED_BY '''(6)''' SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION '''(5)'''
| APPOINTED_BY COMMANDER REPLACED_BY '''(7)''' SUCCESSION '''(8)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION

|-
| CONQUERED_SITE
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
|}

Remarks:
# Works only in world-gen, if a unit with that civ-position is present at the site.
# Works only in world-gen, the site-position holding unit will then move to the capital.
# Is completely ignored
# Works only in world-gen.
# Works only in world-gen.
# Won't appear at all
# This is necessary for the landholder chain to work properly, it doesn’t work otherwise.
# This works only outside of the landholder chain, so when landholders are simply regarded as civ-level nobles. might also work in world-gen
#

== Other interactions ==

Unfortunately, interactions with positions of other entities don't seem possible, such as APPOINTED_BY: HIGH_PRIEST. With [VARIABLE_POSITIONS], positions are automatically created with codes like CUSTOM_LAW_MAKER_2, but interaction with these positions don't seem to work, either. For more info on those, see [[Variable positions]]

=General=

==Civ-level nobles living at your site==
Nobles from your civilization can come to live at your fortress. This happens in vanilla with landholders such as [[Baron]], [[Count]] and [[Duke]], with the Monarch, but sometimes also with non-landed LAND_HOLDERS.

When a civ-level noble becomes a [[citizen]] at your location, their position is shown among the site-level positions in your [[nobles screen]]. They appear to function as a site-level noble. They may have [[demand]]s, [[mandate]]s, [[squad]]s and the like. They can appoint nobles at the site-level.

If they have certain [RESPONSIBILITY]ies, they do the tasks that go with them.

==Fortress mode, world-gen and their differences==
Their are a few differences in how positions function between fortress mode (normal play mode) and the world generation (world-gen).

In '''fortress mode''', the player has some control over the appointment of nobles, limited by elections, automatic filled-in positions and succession rules. Pre-fortress mode, which is referred to as '''world-gen''', the game will always attempt to assign nobles whenever possible. It is subjected to the same rules as in fortress-mode, but there are some exceptions. In '''[[World activities]]''', which is the thing that happens in the world while you play fortress mode, it seems as if the same rules are applied as fortress mode.

A difference between player-fortress-mode and world-gen, is causes by visibility (see below). Positions that are not visible by the player and thus not available for assignment, will be available in world-gen and will thus be automatically assigned.

In fortress mode, a position that is both [ELECTED] and [APPOINTED_BY], cannot be appointed by the player and is also not elected, and can thus not be filled. But in world-gen sites however, these positions are automatically filled.

Positions with [AS_NEEDED] are almost never created and filled in world-gen (depending on their [RESPONSIBILITY]ies), but can always be used in player mode.

A position can, in fortress mode, be filled by the same unit. A unit can gain multiple positions in fortress mode, for example because of [[elections]]. This will not happen in world-gen mode: a unit can only have one position. See also remarks on 'embark' and 'Losing a position'.

In world-gen, [SUCCESSION] between civ-levels and [SITE-]levels may happen. This will not happen in fortress mode, or even off-site in [[World activities]].

In fortress mode, premature SUCCESSION may happen. This will not happen in world-gen mode.

==Units holding multiple positions in multiple entities==
A unit can hold multiple positions in its civilisation or in its site-entity, however this does not happen in world-gen. Only at player-managed sites can units be holding multiple positions at once. (It is probably not possible for a unit to hold a position in two different civilisations or two different sites.)

In world-gen, if there are too many positions to be filled, they simply stay empty until more units are available. E.G, a unit at a site might inherit a civ-level position and still remain a member of the local government. When this happens however, they move to the capital. If a unit gains a new position, either inherited or otherwise, it drops the previous one. If a unit assumes a civ-position in fortress mode, it leaves the current position.

If a unit holds the same (site-)position multiple times, it has no additional effect.

If a unit holds multiple different positions of the same entity, it has all those positions' responsibilities and properties, stacked up. Presumably, the demands for those combined positions are determined by the highest.

A unit holding a position with a succession token can be assigned another position with a (different) succession token.

A unit holding a position with a squad-position cannot hold another squad-position. It is dropped from the first, when it gets its second assigned.
A unit holding a position with a succession token cannot be assigned to a squad-position - the unit is simply not available. It works the other way around, though.

=Specific Tags and functions=
==[PRECEDENCE]==
The first defined position with precedence of 1 counts as the ruler of the civ. See also: [[Position_token#PRECEDENCE|PRECEDENCE]].

If the precedence is omitted or has a negative value, the game sets 0 as precedence, which seems to have no effect whatsoever.

When a unit has multiple positions, the name of the position with the highest rank in precedence is shown behind the unit's name.

If you omit precedence entirely, or set it to [PRECEDENCE:NONE], the position name will not be shown after the unit’s name. Your *Urist Mason* will remain simply *Mason*. This can be useful for positions that are unimportant or purely functional. The position will also not appear in the civilisation overview of your site on the world map. The position name is shown in messages, but remains hidden on the nobles screen as well. To make it visible there, use [LAND_NAME].

==[RESPONSIBILITY]ies==
Both civ and [SITE] positions can carry responsibilities. However, not all responsibilities are active for both types: some function only for civ positions, others only for site positions. When a civ noble arrives at a site and takes up residence, they do not perform responsibilities that are intended for SITE nobles. As a result, these responsibilities neither trigger their associated tasks nor unlock related game mechanics. For example, a civ-level manager living in a fortress will not perform management duties there and doesn't unlock the management-screen, even with an assigned office.
This behavior applies to the following [SITE]-level responsibilities:
* [RESPONSIBILITY:ACCOUNTING]
* [RESPONSIBILITY:BUILD_MORALE]
* [RESPONSIBILITY:HEALTH_MANAGEMENT]
* [RESPONSIBILITY:LAW_ENFORCEMENT]
* [RESPONSIBILITY:MANAGE_PRODUCTION]
* [RESPONSIBILITY:MEET_WORKERS]
* [RESPONSIBILITY:TRADE] (functions differently)
Other responsibilities may be affected as well, but have not yet been fully tested.

==[DELIVERS_MESSAGES]==
The only [AS_NEEDED]-position that is created in worldgen based on responsibility is that of the site-level responsibility [DELIVERS_MESSAGES].

==Outpost Liaisons and Diplomats==
Civ-positions with the responsibility [ESTABLISH_COLONY_TRADE_AGREEMENTS] ([[Outpost_Liaison|Outpost Liaison]]s) will meet with the site-noble who has responsibility for [RECEIVE_DIPLOMATS] and the highest rank of precedence (i.e. the lowest precedence value). Usually this is the [[Expedition_leader|Expedition leader]].

Once a [LAND_HOLDER] is assigned to the site, civ-positions with the responsibility [MAKE_TOPIC_AGREEMENTS] ([[Diplomat]]s) will meet with '''civ'''-level nobles present at the site who have the [RECEIVE_DIPLOMATS] responsibility. If multiple eligible nobles are available, one is selected at random. If no eligible noble is present, the diplomat leaves angrily. If the landholder is no longer present at the site, diplomats will not arrive at all.

It appears that Outpost Liaisons and Diplomats are chosen for a diplomatic mission based on availability. When multiple candidates exist, the position defined last in the raws is most often selected.

==[TRADE]==
Civ-level nobles with [TRADE] will arrive with the caravan, just as the Outpost Liaison. Their behavior is no longer active in the vanilla game, but the mechanics are still present. See [[40d:Guild_representative|Guild representative]] for more details. This civ-noble will only meet with the SITE noble with [TRADE], usually the [[Broker]].

If two civ-nobles exist with both [TRADE] and [ESTABLISH_COLONY_TRADE_AGREEMENTS], they both arrive at the same time. Even if both tokens are assigned to a single position, if more than one instance of that position exists, two of them will arrive. However in that case, somehow the elevation of the site and appointment of landholder isn't offered.

If the SITE-noble they intend to meet has both [TRADE] and [RECEIVE_DIPLOMATS], only one meeting will proceed and the other is cancelled. However, when two SITE-nobles are available, each with either [TRADE] or [RECEIVE_DIPLOMATS], both meetings will proceed and both civ-nobles will attempt to negotiate a trade agreement. It is not known what happens if these agreements are accepted or refused.

In the trade depot, the last defined position with the [TRADE] responsibility is shown as broker. However when requesting a trader, the first defined position with [TRADE] will actually go there to do the trade.

==World-gen effects of the [RESPONSIBILITY] of available positions ==
It is possible to cause civs and individual sites to change their behavior substantially when they reach a certain size, by controlling nobles.
* If a site can only appoint a position with [MILITARY_GOALS] after reaching a particular size, that site will not send armies on missions until the required size is reached.
* A civ-level [LAW_MAKING] position is required for the civilization to have any kind of cohesion. Without it, sites will be constantly embroiled in territorial disputes and civil wars will be commonplace.
* [MILITARY_STRATEGY] positions go out and tame wild animals. This makes your civ gain those animals as domesticated and also brings them in sieges.
* The [[Personality_facet|Personality]] of the position's holder determines how they lead the civ.

=Availability and visibility=
==Availability of (new) positions==
Warning: Do not mistake "availability" for "visibility"!

Of all the possible positions existing in your site's entity, there may only be some available.
* Positions with [REQUIRES_POPULATION] require the population to have a specific size.
* Positions with [REQUIRES_MARKET] will only appear in "large" sites (which may have different rules for different site types). This tag has no effect in fort mode.
* Positions that are appointed by positions that have an AS_NEEDED number. The appointable positions only become available after an appointer position-slot is created. This works also on civ-level. If a position is appointed by a Land-holder, it only becomes available, when that level of landholder is created.

Only the replaced positions are culled and are no longer available.
A position that requires a certain population will become available, even if it doesn't have [APPOINTED_BY] or [ELECTED]. In that case, see 'automatic assignment' and 'assumption'

In fortress mode, in some cases 'succession' is evaluated immediately after a position becomes available. See: Succession.
==Visibility of positions==
A position might be available, but can still be invisible for the player in the [[nobles screen]]. The positions with their respective holders are visible for players:
* All site-positions that are already filled-in (even if they could not be re-filled-in considering current conditions)
* Site positions that are appointable by a filled-in site position
* Site positions that are appointable by a filled-in civ position, when that civ positions holder becomes a citizen of your fortress.
* Civ positions of units that are also a citizen of your fortress.
If a position becomes available, for example because a certain pop number has been reached, or if it is available from the start(like expedition leader), as long as it cannot be appointed, it still is INVISIBLE for the player.

It might strike someone as odd if a position becomes filled automatically in fortress mode when that position is not even visible. This might be the case if the current holder of a non-appointable position dies or succeeds another position. Regardless of player visibility, these positions will be automatically filled in if the necessary requisitions are met. It might happen with the expedition leader.

A situation with a non-visible but available position, is for example when a position is solely appointed by the expedition leader, when the expedition leader's position is left vacant. It can no longer be appointed by the player and is invisible. Then, it gets automatically assumed, proving that the position still was available.

A position that is both [APPOINTED_BY] and [ELECTED] is visible, but players cannot interact with it.

=[NUMBER]=
A position might be defined with a number. In that case, as many as defined can be available. If the positions become available, in world-gen and when embarking, they are all filled-in completely.

If the ruling position (with PRECEDENCE of 1) has a NUMBER higher than 1, a random unit of the ones holding these positions is shown as ruler in the embark screen.

A [NUMBER] of 0 (zero) has the same effect as 1.

==Automatic spreading of assumed, non-singular positions==
If there are civ positions that have a NUMBER higher then '1' and which are assumed (not APPOINTED_BY or ELECTED) but are '''not DUTY_BOUND''', these are automatically spread among the civilisation, based on population. If there are a number of '''20''' available slots of that position, they spread among a civilization with a combined population of, for example, 1000 of which your fortress has 100 (10%), '''2''' of your fortress' citizens will assume that position.
This may probably also work with elected and appointed positions, but that may be depending on the death of the current holders and this needs more testing. Assumption works within a day, anyway.

==[AS_NEEDED]==
These positions can be created automatically by the game in world-gen. This, however, only works with:
* [LAND_HOLDER]'s
* squad commanders (needs more testing)
* Messengers at sites

For all other types of positions, they're not created in world-gen, even if they are defined with RESPONSIBILITY's. For example, even in war, the game wouldn't create a MILITARY_GOALS position, if they have AS_NEEDED as number.

However, in fortress mode / player mode, these positions can be created by the player at will.

Positions with AS_NEEDED need to be created first, before any symbols are assignable as 'symbols' (objects) for the position holder to carry or wear.

Positions with AS_NEEDED cannot be created and then ELECTED in fortress mode. It only works with APPOINTED_BY.

=Replacement and Required Population=

The token REPLACED_BY:position means that once the replacing position reaches its required population-number, the 'to-be-replaced' position will disappear. This is defined in REQUIRES_POPULATION. These tags are closely related to each other and seem to only have a meaningful function if combined. Nobles with REQUIRES_POPULATION require the population to have a specific size.

This works on the civ-level as well as on site-level, but those systems are in this mechanic strictly separated. Site-level positions cannot be replaced by civ-level positions and visa versa. This makes sense, because they both depend on their own population-count. When using REQUIRES_POPULATION on civ-level, it counts the total population of the civilisation.

See also: [[Advanced_entity_position_mechanics#Evaluation_of_Positions|Evaluation of positions]]

==Effect of replacement (and on [LAND_HOLDER]s)==

Replacement is immediate and complete - the current holding unit loses the position, even before SUCCESSION_BY_POSITION rules are applied. A position with a number of 1 will replace all the slots of a position with a higher number of slots.

Even if the next position is available but not visible, replacement still takes place. If a position is replaced, it is completely gone - it cannot be appointed, succeeded, elected or assumed any longer.
The unit immediately loses its position.

In legends, replacement is mentioned as: "(unit name) ceased to be (position name)" The replacement of an AS_NEEDED position empties the position's slot forever. In fortress mode, it may seem as if you can create new slots and appoint new units in the nobles screen, but this is reversed as soon as you close the window.

The landholder chain uses [REPLACED_BY] differently. It does not clear the position completely, but uses it for succession to the next level's position. [REPLACE_BY] is required to let that system work properly. This also means that the way in which landholders succeed (replace + as_needed) does not work in any other way.

Replacement between LAND_HOLDERS and other site- or civ positions does not work in any way. Only the vanilla replacement sequence between levels of LAND_HOLDERs does work. If the token is omitted for landholders, the landholder chain is broken, so replacement is required for the landholder system to work.

[REQUIRES_POPULATION] also does not work for [LAND_HOLDER], when you set [NUMBER] to 1. The position is not created when the required population is reached.

==What doesn't work==

'''Attention: If a position cannot be appointed, for example because of 'mutual appointment', it still exists according to replacement mechanics and will replace other positions if so defined. If a certain position(a) will be replaced by the baron's assistant, which can only be appointed by the [LAND_HOLDER] baron, than that position(s) still will be replaced from the start of the game, even if no baron or their assistant is ever present.'''

A position that is replaced by a somehow non-fillable position is still replaced. This counts for mutual-appointing positions, replacement by not-yet-assigned landholders, replacement by AS_NEEDED positions, or replacement by not-yet-appointed positions.

Replacement does not work if the replaced position is a [LAND_HOLDER], even with civ-positions. In that case, the LAND_HOLDER's position is not replaced. It does not matter if AS_NEEDED is used, or a fixed number, and it also does not matter what type of position the replacer is. So this only works (correctly) with positions that become available by REQUIRES_POPULATION.

={{text anchor|Evaluation of Positions}}=
The game does not continuously check whether positions should become available, elected or be [REPLACE_BY]. This is well-known behavior—for example with the [[mayor]], who does not appear automatically when the required population ([REQUIRES_POPULATION]) is reached. Instead, positions must somehow be evaluated. This applies in several other situations as well

'''Cases that require a trigger:'''
* Election of a newly created position
* Election after the current holder dies
* Automatic assumption of a newly created position (this may take up to a day)
* New citizens (such as migrants) considering available positions
* Premature succession of a newly created position

'''Cases that do not wait for a trigger:'''
* Succession following the death of the previous holder
* Automatic assumption of existing positions that have become vacant

'''Triggers that cause the game to reevaluate noble positions:'''
* Succession of a [SITE]-position due to the death of the current holder
* [[Advanced_entity_position_mechanics#Election_Day|Election Day]]
* Automatic assumption of a [SITE]-position that becomes vacant
* (Re)assigning any site position manually
* Settlement elevation on the LAND_HOLDER track (e.g. gaining a [[Baron]] or [[Count]])

=Gaining a position=
There are several ways a unit can gain a position:
* Appointment: A unit is appointed by another unit or by the player.
* Election: A unit is elected by and among the members of the entity
* Assumption: A position is neither elected or appointed: a random unit just simply 'takes' the position
* Succession: a unit is the valid successor of this position(A), either by its current position(B) or because they are that position(A)-holder's heir.

Available positions will automatically be assigned to a random civ member when a new site/civ is created.

==Who can take a position==

* If so defined, a unit needs to be the right caste and/or class - it does not seem to work with creature types.
* The unit needs to be an adult member of the site or its parent civ's government; that is also CAN_LEARN or INTELLIGENT (SLOW_LEARNER cannot take positions) or otherwise is able to think.

==Appointment==

Positions that have an [APPOINTED_BY:position] token require that position to exist, to be available and appointed. Any position that is APPOINTED_BY can be appointed if the appointer's position is filled in.
For site-positions to be appointed, it is required that the appointer is present at that location.

If the appointing unit is temporarily not present, or if that position is not filled, positions depending on it cannot be appointed. This is the case with [[militia captains]], when the [[militia commander]] is on a [[mission]].

A site position cannot appoint a civ position ''or'' LAND_HOLDER in any way whatsoever.

Civ-level positions can appoint other civ-level positions and site-level positions can appoint other site-level positions.

Contrary to what has been said elsewhere, civ-level nobles also can appoint site-level nobles. They need to be at the site to do so. Landholders can appoint both site-level and civ-level nobles. These systems are therefore not as separate as was assumed.

'''Mutual appointment''' cannot take place. If these are the only requisites of the position, then the positions will never appear or get filled. These unfillable positions can be put to good use, for example, to replace a position that is no longer needed without creating a new one.

'''Self appointment''' doesn't normally work. If you have a position that is only appointed by itself, it is never appointed and also cannot be assumed. However, if the position has a number higher than 1, and is filled by multiple units (for example by another position that is now empty), than those units can re-assign or appoint each other from that their shared position.

If an APPOINTED_BY token refers to a non-existing position's code, the effects are as if the appointment token doesn't exist at all.

===Automatic appointment in world-gen and on the civ level===

Outside of fortress mode, the game will always attempt to appoint nobles whenever possible, as long as these positions are '''available''', even if they are invisible to the player.
It shows this message in legends: "(unit name) has been appointed to the position of (position name)"

In world-gen, all positions become available and are automatically appointed, taking population- and appointment-requirements into consideration.

Positions that are REPLACED_BY are culled and won't be filled.

If a citizen of your fortress holds a civ-level position that can appoint another civ-level position, the appointment will happen automatically and without player intervention. It may happen that another citizen of your fortress is appointed by that unit, creating civ-level position holders in your fortress, but it is unknown what is required to force this effect.

===Manual appointments by players in fortress mode===
In fortress mode, the positions that need to be appointed stay empty on embark. and it is the player's job to appoint those. A player can appoint a unit to any available position, according to the hereabove mentioned conditions. The player takes the role of the automatic appointment-system, but has no direct control over elections, successions and replacement. There are some differences in what is possible at world-gen sites and at player-controlled sites.

* A position that is appointed by a unit present as a fortress citizen, can be appointed, re-appointed or left vacant. This means also by civ-level nobles living as a citizen in your fortress; not when they are only visiting, like the diplomat.
* A position whose appointing positions are all either vacant or [REPLACED_BY] can no longer be appointed. If the position is already filled, it cannot be reappointed or vacated; the current holder simply remains in office.
* A position that is APPOINTED_BY a unit present as the land_holder of your site, can be appointed, reassigned or left vacant.
* A position that has SUCCESSION BY_HEIR or BY_POSITION can 'initially' be appointed and also re-appointed or left vacant, but as soon as the [[nobles]] screen closes, ''it can no longer be replaced or left vacant''. From then on, the succession-rules determine who gains that position when the current holder loses the position. This works even if the SUCCESSION:BY_POSITION-position is vacant or replaced.
* A position that is ELECTED nor APPOINTED_BY, can always be (re-)appointed by the player. This is the case with the [[Expedition leader]]. If it is left vacant however, it cannot be appointed, but will be assumed shortly after.
* A position that is both ELECTED and APPOINTED_BY, cannot be appointed by the player. Contrary to world-gen sites, its slot is visible, but it doesn't show the +-sign. This is either by AS_NEEDED or by a fixed number. Even if the position somehow gets filled (re)assignment is never possible
* A player can appoint a number of units to a position, as much as the NUMBER token dictates. If it is AS_NEEDED, the player may create as many slots as they like, also contrary to world-gen sites.
* A civ-position can never be appointed, even if the appointing civ noble is a citizen of your fortress. A civ position also never can be re-assigned or left vacant, would that position be defined as appointed by a site-position.

==Election==
Read more in [[Elections]]. The message that is shown is: "(creature name) has been elected to the position of (position name)"

In worldgen, there is no functional difference between ELECTED and non-appointment, except that elected nobles tend to have high social skills and/or skills related to the position, while non-elected ones are assigned randomly. See: [[Elections]]

A succession goes before an election.

A position that is both ELECTED and APPOINTED_BY never gets elected. Even if the appointees' position somehow gets filled, (re)-elections won't happen. So, it doesn't seem possible to have an elected position become available when a certain other position becomes filled.

An ELECTED civ-(or LAND_HOLDER) position at your site will never be (re)-elected in fortress mode. So real (re-)election only works with SITE-positions.

=== {{text anchor|Election Day}} ===
Election Day takes place on the 17th of Summer. On this day, a full reevaluation is performed, including all currently elected positions, which are subject to re-election. Contrary to the information on [[Elections]], nothing occurs at the start of a season.

Positions that are both [APPOINTED_BY] and [ELECTED] will not be re-elected on Election Day when assigned through [SUCCESSION].

=== Election Eligiblity ===
Any citizen may stand for election. Eligibility cannot be restricted using [ACCEPTED_CREATURE], [REJECTED_CREATURE], [ACCEPTED_CLASS], [REJECTED_CLASS], or [GENDER]. Units currently having a [SUCCESSION]-position even may be elected for a position with a [SQUAD]-token, which is otherwise impossible to assign or even succeed.

=== Skills ===
In elections, skills are taken into account for the tokens of the position which is elected.
{| class="wikitable"
|+ Relevant skills per position token
|-
! Position Token !! Relevant skills
|-
| Responsibility [[Position_token#DELIVER_MESSAGES|[DELIVER_MESSAGES]]] || [[Ambusher]], [[Observer]] and [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#ACCOUNTING|[ACCOUNTING]]] || [[Record_keeper|Record keeper]]
|-
| Responsibility [[Position_token#ESPIONAGE|[ESPIONAGE]]] || [[Schemer]]
|-
| Responsibility [[Position_token#HEALTH_MANAGEMENT|[HEALTH_MANAGEMENT]]] || [[Diagnostician|Diagnostician]]
|-
| Responsibility [[Position_token#MAKE_INTRODUCTIONS|[MAKE_INTRODUCTIONS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#MAKE_PEACE_AGREEMENTS|[MAKE_PEACE_AGREEMENTS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#MAKE_TOPIC_AGREEMENTS|[MAKE_TOPIC_AGREEMENTS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#MANAGE_PRODUCTION|[MANAGE_PRODUCTION]]] || [[Organizer]]
|-
| Responsibility [[Position_token#MEET_WORKERS|[MEET_WORKERS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#RECEIVE_DIPLOMATS|[RECEIVE_DIPLOMATS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#RELIGION|[RELIGION]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#TAME_EXOTICS|[TAME_EXOTICS]]] || [[Animal_trainer|Animal trainer]]
|-
| Responsibility [[Position_token#TRADE|[TRADE]]] || [[Social_skill|Social skills]] and [[Appraiser|Appraiser]]
|-
| [[Position_token#SQUAD|[SQUAD]]]-token || [[Tactician]] and [[Leader]]
|}

==Assumption==

A position that is not APPOINTED_BY nor ELECTED, or is appointed by positions that are not available in your site or civ, will be assumable by a random dwarf. If it has responsibilities that require certain skills, then these are taken into consideration on embark, but not when the position is assumed during the actual game.

Normally, one to three units will take the into consideration to assume a position. Most of the time when there are multiple open positions, only a single unit will assume all of them. However, a position that has REJECTED_CREATURE, REJECTED_CLASS, ALLOWED_CREATURE or ALLOWED_CLASS will be filled with all different units, even if the creature or class mentioned is irrelevant. It seems that this forces the game to loop over all the available units.

The message that is shown in Legends mode is: "(unit name) has assumed the position of (position name)". This may also take place in fortress mode, which then shows this message to the player.

If an assumable position becomes empty, it will be assumed within a day. This is the case when you leave the position of expedition-leader vacant. It also happens with entities.

Assumable positions that become empty will not be assumed if that position has a valid [SUCCESSION] -successor. In that case, the successor inherits the position.

Even positions that are somehow invisible because they cannot be directly APPOINTED_BY players, can be assumed.

When you embark, the assumable positions are automatically assigned to a random unit. If there are multiple of these positions at embark, they all are assigned to the same unit. If there are enough positions available, multiple units may gain a position, but often no more than three different ones.

If a dwarf in fortress mode assumes a position, that already has another position, it will leave the current position empty. When that position also is assumed, then this will continue until all positions have a dwarf appointed to them, with no other position.

A unit that already has a position with a [SUCCESSION] token won't take assumable positions into consideration that have a [SQUAD] token. This can be used by the modder to prevent unwanted loss of current positions.

A position that has an appointer which got replaced because of REPLACED_BY, will not become assumable. Also, positions that have an AS_NEEDED appointer that is not yet filled (or ever), will also not be assumed.

==Succession==

If a position-holder dies or advances to a new position via succession, the position will be granted to another unit based on the [SUCCESSION] tag. If they have an heir or the succeeding position exists, that unit will be assigned. If not, a new one will be appointed according to the usual rules. The message that is shown is: "(creature name) being the rightful heir, has inherited the position of (position name)"

The succeeding creature will also lose its previous position. When succession is defined using BY_POSITION, the unit naturally loses the referenced position. However, it also loses any other positions it may hold. If a unit could simultaneously inherit multiple positions, the last-defined succession overrides the earlier one, clearing the previously acquired position

Succession works both at site-level and at civ-level, both in world-gen and in fortress-mode. Succession by position on the civ-level is also visible and functional in fortress-mode. If both civ-level nobles are a citizen of your fortress, succession is applied visually. Vanilla example: The [[druid]] is succeeded by the [[acolyte]]. This means that as soon as the druid dies, the acolyte takes over.

When a position that is succeeded by position becomes available, immediately it is checked if a position-successor is available and the position is filled with that unit. Even if this is an [ELECTED] position, succession goes first. When elections eventually do happen, succession plays no role.

It is possible to assign multiple levels of [SUCCESSION:BY_POSITION] in different positions, creating a line of positions where the death of one causes all those "below" them to advance.

A position can have multiple tokens with position-succession. It looks to be random which one is used. It is not always:
* The first or last defined token
* The first or last appointed unit
* the oldest or youngest
* one with a higher or lower precedence
* a unit with relevant skills

When a position is defined with a Succession-type, that unit cannot have another position that has a Squad-type. If the succession-position itself has a squad, than it can be assigned another position with a squad, but then it will loose the previous succesion position. See further details by "Squad"

Assumed positions can also be succeeded by position, if the current holder dies.

If the successor is an AS_NEEDED position, the used unit will leave a vacant position-slot on its removal by succession. This empty slot remains a real slot, which will only be cleaned up if you (un)appoint a unit to this position-series. It isn't cleaned up after regular position validation.

A civ-level position of a unit living at your site might be inherited by a unit holding that does not currently live at your site. This, unfortunately, moves that position to a unit off site. This may also happen with the landholder of your site, for example when it is succeeded by another civ-level position. This currently poses an unsolved challenge.

===Eligibility for succession===
Succession is restricted by the tokens [ACCEPTED_CREATURE], [REJECTED_CREATURE], [ACCEPTED_CLASS], [REJECTED_CLASS] and [GENDER].

===Site and civ combined succession===

Succession can work when combining site positions with civ-level positions or land_holders, but only in world-gen mode. In fortress mode, it only works with combining the same level of nobles, with Landholders regarded as civ-level. So, in fortress mode, a site's position cannot succeed a landholder's position and it cannot succeed another type of civ-level position, and vice versa.

This won't work even if the positions:
* are AS_NEEDED or having a fixed number.
* Are LAND_HOLDERs.

===Succession [BY_HEIR]===

When a heir is needed for succession, all children and then other relatives are validated. They cannot take the position if their status does not allow it, for example if they have become a member of another civilisation. See: "Who can take a position". If the unit has no valid heir on that location, the position may go to a unit living on another site. This may cause the title of Landholder of some land to be inherited by a unit living somewhere else. That might be a problem, because then you lose your landholders.

===Premature Succession===

There are cases where [SUCCESSION:BY_POSITION] is applied prematurely: at the moment a position is first created and becomes appointable or assumable, rather than after a current holder leaves. In this situation, the succession mechanism assigns a holder immediately, without any player interaction.

When a position becomes available for the first time, the game checks whether a valid successor-by-position exists. If so, that unit is assigned instantly. It can affect positions that would normally be appointed or elected by the player, causing succession to trigger before the player has any opportunity to intervene.

This behavior occurs only in Fortress mode, but can be applied both on [SITE]-positions as well in civ-positions. That last one however is a bit harder to control. Example: [[Advanced entity position mechanics#The Archduke|The Archduke]]

This premature succession only occurs the first time a position becomes available (i.e. when it is created and becomes appointable or assumable). Even if the position remains vacant and the conditions for succession improve later, premature succession will not trigger again. From that point onward, only normal succession rules apply.

Using premature succession, a position that has [ELECTED], [APPOINTED_BY], or both, can be filled directly.
Notably, positions that combine [ELECTED] and [APPOINTED_BY] are normally impossible to fill through regular mechanics. Premature succession bypasses both election and appointment entirely, making this combination uniquely reachable through this mechanism.

No initial election takes place, and no subsequent elections will ever occur for that position. Succession always takes precedence over election, both in premature succession and in normal succession cases.

This behavior applies only in Fortress mode, not during world generation. World-gen uses simplified and more efficient mechanics, and this interaction does not occur there. Premature succession can affect both site-level and civilization-level positions.

====Multiple succession chains====

Multiple succession chains may be defined and are resolved in the order they appear in the raws.

If a position has both:
* a direct succession chain (A → C), and
* a multi-step chain (A → B → C),

and intermediate positions are vacant, resolution proceeds according to raw order. A common outcome is:
# The direct succession (A → C) is applied first, assigning A to C.
# The remaining chain then advances (A → B).
# If C still has empty slots, the final step (B → C) may occur.

If position B is already filled, behavior depends entirely on raw definition order:
* nothing may happen, or
* B may move to C first, followed by A moving to B.
====Working triggers====
Premature succession is triggered when a succeedable position is created under the following conditions:
* The succeedable position is created because its [REQUIRES_POPULATION] threshold is reached. This applies even if the position is not [APPOINTED_BY]. Premature succession takes priority over automatic assumption (e.g. the mayor declaring themselves within a day).
* The succeedable position can be [APPOINTED_BY] another position of the same level (site or civ) that has just been created because its [REQUIRES_POPULATION] was reached.
* The succeedable position can be appointed by another [SITE] [AS_NEEDED] position that has just been created and filled.
* The succeedable (site or civ) position is [APPOINTED_BY] the [LAND_HOLDER] position, which has just been created due to site elevation. This typically resolves when the diplomat leaves the map, at which point the landholder position becomes active.
* If all other requirements are met, premature succession can occur immediately after unpausing following embark, for positions with [REQUIRES_POPULATION:7].
====Non-working triggers====
Premature succession does '''not''' occur in the following cases:
* An [AS_NEEDED] succeedable position slot is manually created by the player while its succeeding position is already filled. [AS_NEEDED] positions must always be appointed after creation.
* The succeeding position is filled after the succeedable position becomes available. The moment of creation is the decisive trigger; filling the source position later is too late.
* The succeedable position can be appointed by another site or civ position with a fixed number of slots that has just been appointed. In this case, the succeedable position is just available for appointment itself, nothing more
* Any situation occurring during world generation.
* The succeeding position is [REPLACED_BY] the succeedable position. In this case, replacement removes the unit from the source position first, leaving no holder available for the succession mechanism to use.rst, leaving no holder available for the succession mechanism to use.
* The position is [APPOINTED_BY] a civ-level position, that just became a citizen of your fortress. It must be noted that those civ-level positions were active all that time and the succeedable position could be appointed even before. The monarchs arrival does not trigger premature succession

=Losing a position=

A unit can lose a position when:
* It dies
* It succeeds another position, even if it has nothing to do with the previous position.
* It is assigned to another SQUAD-holding position
* It is convicted of a crime.
* Another unit is ELECTED for the position
* Its position becomes replaced
* Another unit is appointed by the player, or the position is left vacant.
* It has assumed another position, as this always leaves the previous position vacant.

=Embarkment=
Two types of positions are automatically filled by embark.
* Positions without [APPOINTED_BY] or [ELECTED] (assumable). All these positions, even with a NUMBER higher than 1, are all filled with one to three dwarves. Contrary to assumption, this doesn't take into account any limitations. REJECTED_CLASS, ALLOWED_CLASS, REJECTED_CREATURE, ALLOWED_CREATURE and GENDER are applied, but without the normal spread you may expect with assumptions. Also it doesn't look at [SUCCESSION] and [SQUAD] limitations.
* Positions that are elected are filled-in by the normal election rules.

Positions that have a defined appointer are never initially filled at embark.

All positions that don't have [REQUIRES_POPULATION] or with a [REQUIRES_POPULATION] of 7 or lower, will be available at embark.

=Land Holders=

A Landholder is a '''special civ-level noble''' who gets a certain piece of land to hold, when that land is elevated to a certain level, determined by the tag [LAND_HOLDER] and by the landholder triggers in the game's settings. In vanilla, these are the baron, the count and the duke.

A unit gaining the landholder position does not migrate to that specific named land. In world-gen, they stay just where they are, probably at the capital. In fortress mode, you can suggest a citizen for the role. So for the time being that works.

Succession is then a real issue. If you use BY_HEIR, its solved when that landholder has children living at your site. But when its not the case, the title just goes to anyone randomly. Succession BY_POSITION works, but only in the civ-chain, and there's no way to guarantee a civ-holder is at your site at that time. Even with 'automatic spread' positions, it goes to one of them randomly.

==Functioning of the regular landholder chain==

The distinct difference between a landholder and a regular civ-level noble, is that a landholder may gain the position of landholder "of (sitename)" They are then seen as ruler of a particular site.

For a land_holder position to function as such, it has a few requirements:
* NUMBER:AS_NEEDED
* The first landholder-number of 1 is defined.
* No SITE (so civ) tag in that position.
*REPLACED_BY the next level landholder
If a landholder is defined with differentiating properties, it will function like a regular noble. A higher-up landholder that lacks the required tokens or connections will then not be used in elevation.

If a fortress meets the trigger for a new LAND_HOLDER tier when a caravan leaves, then the next time the outpost liaison or equivalent arrives, they will offer to make you an official colony, which will allow you to select all positions for that LAND_HOLDER level. Each time they appear, the outpost liaison will only promote your fortress one tier up the LAND_HOLDER track.

The landholder's LAND_NAME is not required for the functioning of this system. If omitted, messages will be shown with a more generic text.

==Appointment==

This mechanism differs from the regular methods of position management. It ignores all regular appointment- and election rules, so it more or less functions like automatic assignment. A landholder is, in vanilla, appointed by the monarch. Changing this doesn't seem to do anything. If they are appointed by a site-position, a not-yet-existing civ-position, or not appointed at all: the system keeps working as usual.

A landholder can appoint civ-positions and site positions. This works as expected: the positions only are appointed then when that landholder becomes available on civ-level or when he arrives at that site for site-level positions.

If your rank of landholder is the first of its rank in the realm, and is the sole appointer of some civ-position, then immediately as it gains the title, it will appoint the empty civ-slots. This may happen on your site, but the frequency and certainty is hard to determine.

==Succession==

Succession rules are applied to some extent:
* In world-gen it works according to succession rules, and site-positions can be used here. This means that a site position or a civ-position can inherit a landholder position, and vice versa.
* In fortress mode, once a landholder has been appointed, it then can inherit civ-level positions, and vice versa. This means that your baron can become king.
* Succession rules do not apply within the [LAND_HOLDER] chain; a count will not inherit a baron's land. This is because succession does not work well with the AS_NEEDED token.
* Premature succession works in fortress mode with landholders. If a unit gets a landholder's position and that landholder is the appointer of an as yet empty position, which is defined as succeeding from a third one, then the succession is immediately applied. The landholder themselves can even be the successor of a newly created position.
* A landholder's position is, in fortress mode, not successionable by a site-position or vice versa

===Impossibilities for succession by a site-position===
It would be very beneficial if the landholder can be succeeded by a [SITE]-position. So far, the following tests have not lead to positive results:
* making landholder and site-position both non-[DUTY_BOUND]
* make the site-position be [APPOINTED_BY] the landholder and/or the monarch
* give landholder and site-position [REJECTED_CREATURE]
* Let the monarch live at your site when succession could happen.
* Let the site-position be [REPLACED_BY] the landholder.

==Nomination==

The player is able to nominate a unit to become the LAND_HOLDER, but this only works with units of [LAND_HOLDER] level 1. The player can select all units, only limited by the PRECEDENCE of the current units' positions.

A unit that has a position with a PRECEDENCE lower or equal to that of the landholder's position, cannot be selected. This means that a baron (or count) from another site or the monarch cannot be selected, because their precedence is lower or equal.

The GENDER token does not work here: also units with the wrong gender (sorry) can be selected.

==Levels==
In mods, up to 10 levels of LAND_HOLDER may be defined.

If a landholder is replaced by a wrong landholder number (1 replaced by 3), then the number 3 is still correctly attached to the settlement.

If the current landholder has the highest available landholder number, then the next elevation will not happen - the diplomat will not elevate your fortress to a higher position, even if that position might be REPLACED_BY a lower landholder.

These chains do work:
* 1 -> 2a - > 2b -> 3
* 1 -> 3 -> 2 -> 4

These chains do not work:
* 2 -> 3 (need to start at 1)
* 1 -> 4 -> 2 -> 3 (stops after 4 as the highest)
* 1a -> 2, 1b -> 2 (only 1a and 2 work, 1b is not used)

==Moving landholders==

It may happen that a land-holder no longer lives at the site which they are the landholder of, specifically when the current landholder dies, leaving the title to an heir living somewhere else.

To prevent this from happening, you can make their succession from heir and make sure that their kids live at your site. Or, you can make their position succeeded by another civ position, and make it so that this civ position is somehow available on your site. But if multiple of these positions exist, it cannot be guaranteed that a citizen of your fortress will inherit the title.

In world gen, a landholder lacking the DUTY_BOUND-token will also move to the site they like, according to legends mode.

==Replacement by a generic civ-position==

If a landholder is replaced by an AS_NEEDED non-landholder civ-position, then this will work: the current landholder loses that title upon settlement-elevation and gains that civ-title. However, the civ-title lacks the landholder-property of being attached to the land. It will not show the name of the settlement alongside the position's name. So no "minister of Shovelmounts"

If a landholder is replaced by a general AS_NEEDED civ-position, that itself is also replaced by a generic AS_NEEDED civ-position, then firstly the elevation is executed and also the unit gains that new position. However, he immediately loses it, because an AS_NEEDED position that is replaced by another position can be filled initially, but units wont be able to hold that title.

==Landholder with fixed number==

A landholder's position that has a fixed number will be created and filled directly when the civilisation is born, so this position slot is then not available for the regular landholder-mechanic and will also not be used. That landholder will thus not be attached to a settlement.

It doesn't matter if the landholder's position is connected to the regular landholder's-chain with the REPLACE_BY token.

==Responsibilities==

When given a certain [RESPONSIBILITY], a landholder may function as a regular civ-level noble. If the position has [TRADE] or [OUTPOST_NEGOTIATING] responsibilities, then the landholder functions both as a diplomat and as an actual land holder. A landholder with the [MILITARY_STRATEGY] responsibility will travel around taming creatures in world-gen, according to legends mode.

Besides that, the responsibilities work the same as with any other on-site living position-holder, civ or otherwise.

=Military=
==Squad management==
In the vanilla game, the Squad interface only becomes available after a militia commander has been appointed. Until then, the window displays:{{DFtext|You must appoint somebody first to create a squad.}}

What’s surprising is how this is determined internally. In the entity raw definition, '''only the last two positions that include a [SQUAD] token are checked''' to decide whether the interface is accessible at all. As a result, if your hierarchy defines commanders A through E, appointing '''Commander D or E''' unlocks squad formation, while appointing A–C does nothing.

In other words, squad availability is not tied to ''having a militia commander'', but to ''which specific positions happen to be last in the raw list''—a notably hacky implementation.

These 'last two' are always the last two '''available positions.''' So if they get [REPLACED_BY] or become available because of [REQUIRES_POPULATION], the game adapts to those.

==Squad assignment==

Squads can be assigned, even if the leader position has no holder.

A specific unit can only have one position associated with a squad. If it gains another 'squad holding position', it is unassigned from the first one. This does not work with a 0-squad, so only 1+squads are taken into consideration. This technique can possibly be used to distribute all positions equally among all citizens. It does however not work with election and assumption.

If a civ-level position is associated with a squad and it gets a site-level squad-holding position assigned, it loses the current civ-position.

Squads can get really messed up, if you make the position (or multiple) either elected or not-elected and not-appointed, then this can cause the game to assign multiple squads to the same unit. Automatic assignment and election does not take squads into account, but the nobles screen does. This can cause the positions to be cleared as the game figures out that they have more than one position, and immediately get elected or assumed again.

Positions that cannot have a squad-position:
* A site- or civ-position with a [SUCCESSION] token cannot be appointed a squad-holding-position. The other way around, however, does work. For example, if a site-position with a [SUCCESSION]-token is appointed to a unit that has already a position with [SQUAD]. But when that squad position is assigned to another unit, it cannot be assigned back.
* A position with [SUCCESSION] can also not be assigned as a '''member''' of a squad.
* A squad-holding position with a formed squad cannot be appointed to another squad holding position.

If a position has at least one squad member, it cannot be left vacant. First, the squad has to be disbanded, then the position may be cleared.

==0-squads==
A 0-Squad is defined in a position as [SQUAD:0:member:members]. It does not seem to do anything useful as of now.
* It cannot be used to activate the [[Squad|military interface]]
* It does not restrict the assignment of [SUCCESSION] positions.
* Assigning this position does not clear any previously held squad position.
* The [[Leader]] and [[Tactician]] skill are not marked as relevant skills and are not taken into account in elections.
* It cannot be formed as a squad.

=Further testing=
The following questions may need additional testing. Feel free to add or answer
* Everything regarding COMMANDING and army-structure
** [http://www.bay12forums.com/smf/index.php?topic=175437.msg8331668#msg8331668]
** [http://www.bay12forums.com/smf/index.php?topic=165213.msg8335682#msg8335682]
** [http://www.bay12forums.com/smf/index.php?topic=174584.msg8026854#msg8026854]
* Everything regarding CONQUERED_SITE, but it is presumably just like site. But what if you combine SITE or LAND_HOLDER with it?
* Stuff about the monarch, its arrival and its entourage.

=Oddities (Bugs)=
Almost everything on this page could be called an oddity. Because of their unexpected usability, some may also be referred to as “undocumented features.” Others, however, are simply odd and not particularly useful, yet I hesitate to call them “bugs.”
* If a certain threshold is reached that makes an elected position electable, and the triggering event that initiates this evaluation is an assumption, then the resulting assumption is also referred to in the messages as an election

=Examples=

===The Founder===
The founder is a single dwarf, appointed at embark. They will be the only one ever to have this position and are not replaceable. When they lose their position some way, the position will not be assumed by another dwarf.
{{gamedata|title=The Founder|
[POSITION:THE_FOUNDER]
[NAME:the founder:founders]
[NUMBER:1]
[SITE]
[ALLOWED_CREATURE:DWARF:ALL] - will only be filled at embark, but not assumable later.
[REJECTED_CREATURE:DWARF:ALL] - will only be filled at embark, but not assumable later.
[SUCCESSION:BY_POSITION:THE_FOUNDER] - not unassignable, also cannot be assigned to a [SQUAD] position.
[PRECEDENCE:200]
Non APPOINTED_BY
Non ELECTED
Optional: Add responsibilities to make the game select a unit with certain skills.
}}
===Marriage bar===
Dwarven matrons are held in great honour. Upon marriage, a female dwarf is no longer expected to perform menial labour. All dwarven males hold this position by default, granting their spouses exemption from menial work.

The position becomes available with the arrival of the first migrants; otherwise, on embark, it would be assumed by females. Its succession rule is non-functional, but this prevents the player from unassigning the position. A squad size of 1 and the succession rules together prevent a unit from assuming the position more than once.

With precedence set to NONE, the position name is hidden, while LAND_NAME remains visible on the nobles screen. All married females receive the suffix “, Mrs.” and are marked as Nobles.

The practical usefulness of this position is debatable, but it serves as a clear demonstration of several mechanics.
{{gamedata|title=Mrs. Urist|

[POSITION:MRS_URIST]
[NUMBER:300]
[SITE]
[ALLOWED_CREATURE:DWARF:MALE]
Not APPOINTED_BY
Not ELECTED
[LAND_NAME:Dwarven male]
[NAME:dwarven male:dwarven male]
[PRECEDENCE:NONE]
[SPOUSE_FEMALE:, Mrs.:spouses]
[MENIAL_WORK_EXEMPTION_SPOUSE]
[REQUIRES_POPULATION:8]
[SUCCESSION:BY_POSITION:MONARCH]
[SQUAD:1:member:members]
}}
===The Archduke===
The archduke is the leader of the civilization, but exists only from landholder 4-level. Until then, its position remains vacant. When a settlement is elevated to tier 4 (grand duke), the grand duke can appoint the ruler of the civilisation, the archduke. Because of 'Premature Succession', they themself inherit that position immediately, but only when in fortress mode. Its heir then becomes grand duke.
{{gamedata|title=The Archduke| no POSITION:MONARCH or other PRECEDENCE:1

[POSITION:THE_ARCHDUKE]
[NAME:archduke:archdukes]
[NAME_MALE:archduke:archdukes]
[NAME_FEMALE:archduchess:archduchesses]
[LAND_NAME:a archduchy]
[NUMBER:1]
[PRECEDENCE:1]
[SUCCESSION:BY_POSITION:GRAND_DUKE]
[APPOINTED_BY:GRAND_DUKE]
(add additional monarch-stuff, like spouse name, demands etc.)

[POSITION:GRAND_DUKE]
[NAME:grand duke:grand dukes]
[NAME_MALE:grand duke:grand dukes]
[NAME_FEMALE:grand duchess:grand duchesses]
[NUMBER:AS_NEEDED]
[LAND_HOLDER:4]
// Optional ...
[PRECEDENCE:19]
[LAND_NAME:a archduchy]
[RESPONSIBILITY:LAW_MAKING]
[RESPONSIBILITY:RECEIVE_DIPLOMATS]
[SUCCESSION:BY_HEIR]
[APPOINTED_BY:THE_ARCHDUKE]
(add additional landholder-stuff)

!!add to [POSITION:DUKE]
[REPLACED_BY:GRAND_DUKE]

}}
{{Category|Modding}}
{{Category|Entities}}
{{Category|Guides}}

Advanced entity position mechanics

2026-02-12T08:30:44Z

Joostheger: /* [RESPONSIBILITY]ies */

{{Quality|Fine}}
{{Modding}}

= Introduction =

[http://www.bay12forums.com/smf/index.php?topic=182239.0 Discussion thread on the forum]

This page documents observed and tested behavior of entity positions in Dwarf Fortress that is not fully described elsewhere on the wiki. It focuses on advanced interactions between position tokens, including appointment, succession, election, and responsibility handling, across both civilization-level and site-level entities.

The mechanics described here are based on empirical testing in world generation and fortress mode, supplemented where necessary by raw analysis. In several cases, the game’s behavior is determined by evaluation order and interaction between multiple tags, rather than by individual tokens in isolation.

This page is intended for modders and advanced players who are designing or debugging custom entity position structures. It does not restate basic position mechanics, but instead highlights edge cases, non-obvious interactions, and behaviors that may appear inconsistent or undocumented.

Unless stated otherwise, the described behavior applies to current versions of the game and may differ from older releases.

==What is an entity? What is a position?==
An [[entity]] is an organizational structure that can have relationships with other entities, usually known as a [[civilization]] or a "[[site]] government" in the game, but merchant [[guild]]s, religious organizations, necromancer towers, and [[bandit]] groups are also entities. An entity can have positions - in most cases, these are hardcoded and generated by the game, but as for civilizations and sites, the [[raw file]]s can be customised.

A position is a special relationship between a unit and an entity. The unit holding a position has a larger influence over that entity than other citizens. Positions are mostly known as [[nobles]], but in this article. the technical term is used.

=Position levels (Site/Civ) and their interaction=
There are two basic types of positions that are customizable: '''civ(ilization)''' level and '''site level'''. Positions with the tag [SITE] are at site level, positions without the tag [SITE] are at 'civ level'. These two types of nobles can be considered '''loosely related systems'''. There are a few places where they can interact with each other.

Civ-level positions are in charge of the civilization as a whole, managing national [[trade]], laws, and [[war]]s. These are, for example, the vanilla [[monarch]], [[diplomat]] and [[general]]. (Note that the general doesn't do anything in either mode in the current version.)

'''[LAND_HOLDER]''' nobles are also positions at civ-level. These units are members of the national government, but have gained authority over some land or site. Once they do, they move to that place, but their position is still regarded as a civ-level position.

Site-level position holders are members of a site government (subsidiary to the civilization), and manage local affairs in that location. These are, for example, the [[mayor]], the [[sheriff]] and the [[broker]].

==Table of interaction between different position levels==
In this table, the possible interactions between different position levels are summarized.
The header row shows the positions defining the tokens.

The left column shows the position type that is referred to.
Example:
{| {{prettytable}}
|- bgcolor="#ddd"
! referred position-type
! LAND_HOLDER
|-
| civilization
| (baron is) APPOINTED_BY:MONARCH
|}
color coding: 
* Exists in vanilla
* Possible with mods
* Not possible
* possible to some extent.
* not yet fully investigated.
{| {{prettytable}}
|- bgcolor="#ddd"
! referred position-type
! Civilization
! SITE
! LAND_HOLDER
! CONQUERED_SITE

|-
| Civilization
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION '''(1)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION

|-
| SITE
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION '''(2)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY '''(3)''' COMMANDER REPLACED_BY SUCCESSION '''(4)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION

|-
| LAND_HOLDER
| APPOINTED_BY COMMANDER REPLACED_BY '''(6)''' SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION '''(5)'''
| APPOINTED_BY COMMANDER REPLACED_BY '''(7)''' SUCCESSION '''(8)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION

|-
| CONQUERED_SITE
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
|}

Remarks:
# Works only in world-gen, if a unit with that civ-position is present at the site.
# Works only in world-gen, the site-position holding unit will then move to the capital.
# Is completely ignored
# Works only in world-gen.
# Works only in world-gen.
# Won't appear at all
# This is necessary for the landholder chain to work properly, it doesn’t work otherwise.
# This works only outside of the landholder chain, so when landholders are simply regarded as civ-level nobles. might also work in world-gen
#

== Other interactions ==

Unfortunately, interactions with positions of other entities don't seem possible, such as APPOINTED_BY: HIGH_PRIEST. With [VARIABLE_POSITIONS], positions are automatically created with codes like CUSTOM_LAW_MAKER_2, but interaction with these positions don't seem to work, either. For more info on those, see [[Variable positions]]

=General=

==Civ-level nobles living at your site==
Nobles from your civilization can come to live at your fortress. This happens in vanilla with landholders such as [[Baron]], [[Count]] and [[Duke]], with the Monarch, but sometimes also with non-landed LAND_HOLDERS.

When a civ-level noble becomes a [[citizen]] at your location, their position is shown among the site-level positions in your [[nobles screen]]. They appear to function as a site-level noble. They may have [[demand]]s, [[mandate]]s, [[squad]]s and the like. They can appoint nobles at the site-level.

If they have certain [RESPONSIBILITY]ies, they do the tasks that go with them.

==Fortress mode, world-gen and their differences==
Their are a few differences in how positions function between fortress mode (normal play mode) and the world generation (world-gen).

In '''fortress mode''', the player has some control over the appointment of nobles, limited by elections, automatic filled-in positions and succession rules. Pre-fortress mode, which is referred to as '''world-gen''', the game will always attempt to assign nobles whenever possible. It is subjected to the same rules as in fortress-mode, but there are some exceptions. In '''[[World activities]]''', which is the thing that happens in the world while you play fortress mode, it seems as if the same rules are applied as fortress mode.

A difference between player-fortress-mode and world-gen, is causes by visibility (see below). Positions that are not visible by the player and thus not available for assignment, will be available in world-gen and will thus be automatically assigned.

In fortress mode, a position that is both [ELECTED] and [APPOINTED_BY], cannot be appointed by the player and is also not elected, and can thus not be filled. But in world-gen sites however, these positions are automatically filled.

Positions with [AS_NEEDED] are almost never created and filled in world-gen (depending on their [RESPONSIBILITY]ies), but can always be used in player mode.

A position can, in fortress mode, be filled by the same unit. A unit can gain multiple positions in fortress mode, for example because of [[elections]]. This will not happen in world-gen mode: a unit can only have one position. See also remarks on 'embark' and 'Losing a position'.

In world-gen, [SUCCESSION] between civ-levels and [SITE-]levels may happen. This will not happen in fortress mode, or even off-site in [[World activities]].

In fortress mode, premature SUCCESSION may happen. This will not happen in world-gen mode.

==Units holding multiple positions in multiple entities==
A unit can hold multiple positions in its civilisation or in its site-entity, however this does not happen in world-gen. Only at player-managed sites can units be holding multiple positions at once. (It is probably not possible for a unit to hold a position in two different civilisations or two different sites.)

In world-gen, if there are too many positions to be filled, they simply stay empty until more units are available. E.G, a unit at a site might inherit a civ-level position and still remain a member of the local government. When this happens however, they move to the capital. If a unit gains a new position, either inherited or otherwise, it drops the previous one. If a unit assumes a civ-position in fortress mode, it leaves the current position.

If a unit holds the same (site-)position multiple times, it has no additional effect.

If a unit holds multiple different positions of the same entity, it has all those positions' responsibilities and properties, stacked up. Presumably, the demands for those combined positions are determined by the highest.

A unit holding a position with a succession token can be assigned another position with a (different) succession token.

A unit holding a position with a squad-position cannot hold another squad-position. It is dropped from the first, when it gets its second assigned.
A unit holding a position with a succession token cannot be assigned to a squad-position - the unit is simply not available. It works the other way around, though.

=Specific Tags=
==[PRECEDENCE]==
The first defined position with precedence of 1 counts as the ruler of the civ. See also: [[Position_token#PRECEDENCE|PRECEDENCE]].

If the precedence is omitted or has a negative value, the game sets 0 as precedence, which seems to have no effect whatsoever.

When a unit has multiple positions, the name of the position with the highest rank in precedence is shown behind the unit's name.

If you omit precedence entirely, or set it to [PRECEDENCE:NONE], the position name will not be shown after the unit’s name. Your *Urist Mason* will remain simply *Mason*. This can be useful for positions that are unimportant or purely functional. The position will also not appear in the civilisation overview of your site on the world map. The position name is shown in messages, but remains hidden on the nobles screen as well. To make it visible there, use [LAND_NAME].

==[RESPONSIBILITY]ies==
Both civ and [SITE] positions can carry responsibilities. However, not all responsibilities are active for both types: some function only for civ positions, others only for site positions. When a civ noble arrives at a site and takes up residence, they do not perform responsibilities that are intended for SITE nobles. As a result, these responsibilities neither trigger their associated tasks nor unlock related game mechanics. For example, a civ-level manager living in a fortress will not perform management duties there and doesn't unlock the management-screen, even with an assigned office.
This behavior applies to the following [SITE]-level responsibilities:
* [RESPONSIBILITY:ACCOUNTING]
* [RESPONSIBILITY:BUILD_MORALE]
* [RESPONSIBILITY:HEALTH_MANAGEMENT]
* [RESPONSIBILITY:LAW_ENFORCEMENT]
* [RESPONSIBILITY:MANAGE_PRODUCTION]
* [RESPONSIBILITY:MEET_WORKERS]
* [RESPONSIBILITY:TRADE] (functions differently)
Other responsibilities may be affected as well, but have not yet been fully tested.

==[DELIVERS_MESSAGES]==
The only [AS_NEEDED]-position that is created in worldgen based on responsibility is that of the site-level responsibility [DELIVERS_MESSAGES].

==Outpost Liaisons and Diplomats==
Civ-positions with the responsibility [ESTABLISH_COLONY_TRADE_AGREEMENTS] ([[Outpost_Liaison|Outpost Liaison]]s) will meet with the site-noble who has responsibility for [RECEIVE_DIPLOMATS] and the highest rank of precedence (i.e. the lowest precedence value). Usually this is the [[Expedition_leader|Expedition leader]].

Once a [LAND_HOLDER] is assigned to the site, civ-positions with the responsibility [MAKE_TOPIC_AGREEMENTS] ([[Diplomat]]s) will meet with '''civ'''-level nobles present at the site who have the [RECEIVE_DIPLOMATS] responsibility. If multiple eligible nobles are available, one is selected at random. If no eligible noble is present, the diplomat leaves angrily. If the landholder is no longer present at the site, diplomats will not arrive at all.

It appears that Outpost Liaisons and Diplomats are chosen for a diplomatic mission based on availability. When multiple candidates exist, the position defined last in the raws is most often selected.

==[TRADE]==
Civ-level nobles with [TRADE] will arrive with the caravan, just as the Outpost Liaison. Their behavior is no longer active in the vanilla game, but the mechanics are still present. See [[40d:Guild_representative|Guild representative]] for more details. This civ-noble will only meet with the SITE noble with [TRADE], usually the [[Broker]].

If two civ-nobles exist with both [TRADE] and [ESTABLISH_COLONY_TRADE_AGREEMENTS], they both arrive at the same time. Even if both tokens are assigned to a single position, if more than one instance of that position exists, two of them will arrive. However in that case, somehow the elevation of the site and appointment of landholder isn't offered.

If the SITE-noble they intend to meet has both [TRADE] and [RECEIVE_DIPLOMATS], only one meeting will proceed and the other is cancelled. However, when two SITE-nobles are available, each with either [TRADE] or [RECEIVE_DIPLOMATS], both meetings will proceed and both civ-nobles will attempt to negotiate a trade agreement. It is not known what happens if these agreements are accepted or refused.

In the trade depot, the last defined position with the [TRADE] responsibility is shown as broker. However when requesting a trader, the first defined position with [TRADE] will actually go there to do the trade.

==World-gen effects of the [RESPONSIBILITY] of available positions ==
It is possible to cause civs and individual sites to change their behavior substantially when they reach a certain size, by controlling nobles.
* If a site can only appoint a position with [MILITARY_GOALS] after reaching a particular size, that site will not send armies on missions until the required size is reached.
* A civ-level [LAW_MAKING] position is required for the civilization to have any kind of cohesion. Without it, sites will be constantly embroiled in territorial disputes and civil wars will be commonplace.
* [MILITARY_STRATEGY] positions go out and tame wild animals. This makes your civ gain those animals as domesticated and also brings them in sieges.
* The [[Personality_facet|Personality]] of the position's holder determines how they lead the civ.

=Availability and visibility=
==Availability of (new) positions==
Warning: Do not mistake "availability" for "visibility"!

Of all the possible positions existing in your site's entity, there may only be some available.
* Positions with [REQUIRES_POPULATION] require the population to have a specific size.
* Positions with [REQUIRES_MARKET] will only appear in "large" sites (which may have different rules for different site types). This tag has no effect in fort mode.
* Positions that are appointed by positions that have an AS_NEEDED number. The appointable positions only become available after an appointer position-slot is created. This works also on civ-level. If a position is appointed by a Land-holder, it only becomes available, when that level of landholder is created.

Only the replaced positions are culled and are no longer available.
A position that requires a certain population will become available, even if it doesn't have [APPOINTED_BY] or [ELECTED]. In that case, see 'automatic assignment' and 'assumption'

In fortress mode, in some cases 'succession' is evaluated immediately after a position becomes available. See: Succession.
==Visibility of positions==
A position might be available, but can still be invisible for the player in the [[nobles screen]]. The positions with their respective holders are visible for players:
* All site-positions that are already filled-in (even if they could not be re-filled-in considering current conditions)
* Site positions that are appointable by a filled-in site position
* Site positions that are appointable by a filled-in civ position, when that civ positions holder becomes a citizen of your fortress.
* Civ positions of units that are also a citizen of your fortress.
If a position becomes available, for example because a certain pop number has been reached, or if it is available from the start(like expedition leader), as long as it cannot be appointed, it still is INVISIBLE for the player.

It might strike someone as odd if a position becomes filled automatically in fortress mode when that position is not even visible. This might be the case if the current holder of a non-appointable position dies or succeeds another position. Regardless of player visibility, these positions will be automatically filled in if the necessary requisitions are met. It might happen with the expedition leader.

A situation with a non-visible but available position, is for example when a position is solely appointed by the expedition leader, when the expedition leader's position is left vacant. It can no longer be appointed by the player and is invisible. Then, it gets automatically assumed, proving that the position still was available.

A position that is both [APPOINTED_BY] and [ELECTED] is visible, but players cannot interact with it.

=[NUMBER]=
A position might be defined with a number. In that case, as many as defined can be available. If the positions become available, in world-gen and when embarking, they are all filled-in completely.

If the ruling position (with PRECEDENCE of 1) has a NUMBER higher than 1, a random unit of the ones holding these positions is shown as ruler in the embark screen.

A [NUMBER] of 0 (zero) has the same effect as 1.

==Automatic spreading of assumed, non-singular positions==
If there are civ positions that have a NUMBER higher then '1' and which are assumed (not APPOINTED_BY or ELECTED) but are '''not DUTY_BOUND''', these are automatically spread among the civilisation, based on population. If there are a number of '''20''' available slots of that position, they spread among a civilization with a combined population of, for example, 1000 of which your fortress has 100 (10%), '''2''' of your fortress' citizens will assume that position.
This may probably also work with elected and appointed positions, but that may be depending on the death of the current holders and this needs more testing. Assumption works within a day, anyway.

==[AS_NEEDED]==
These positions can be created automatically by the game in world-gen. This, however, only works with:
* [LAND_HOLDER]'s
* squad commanders (needs more testing)
* Messengers at sites

For all other types of positions, they're not created in world-gen, even if they are defined with RESPONSIBILITY's. For example, even in war, the game wouldn't create a MILITARY_GOALS position, if they have AS_NEEDED as number.

However, in fortress mode / player mode, these positions can be created by the player at will.

Positions with AS_NEEDED need to be created first, before any symbols are assignable as 'symbols' (objects) for the position holder to carry or wear.

Positions with AS_NEEDED cannot be created and then ELECTED in fortress mode. It only works with APPOINTED_BY.

=Replacement and Required Population=

The token REPLACED_BY:position means that once the replacing position reaches its required population-number, the 'to-be-replaced' position will disappear. This is defined in REQUIRES_POPULATION. These tags are closely related to each other and seem to only have a meaningful function if combined. Nobles with REQUIRES_POPULATION require the population to have a specific size.

This works on the civ-level as well as on site-level, but those systems are in this mechanic strictly separated. Site-level positions cannot be replaced by civ-level positions and visa versa. This makes sense, because they both depend on their own population-count. When using REQUIRES_POPULATION on civ-level, it counts the total population of the civilisation.

See also: [[Advanced_entity_position_mechanics#Evaluation_of_Positions|Evaluation of positions]]

==Effect of replacement (and on [LAND_HOLDER]s)==

Replacement is immediate and complete - the current holding unit loses the position, even before SUCCESSION_BY_POSITION rules are applied. A position with a number of 1 will replace all the slots of a position with a higher number of slots.

Even if the next position is available but not visible, replacement still takes place. If a position is replaced, it is completely gone - it cannot be appointed, succeeded, elected or assumed any longer.
The unit immediately loses its position.

In legends, replacement is mentioned as: "(unit name) ceased to be (position name)" The replacement of an AS_NEEDED position empties the position's slot forever. In fortress mode, it may seem as if you can create new slots and appoint new units in the nobles screen, but this is reversed as soon as you close the window.

The landholder chain uses [REPLACED_BY] differently. It does not clear the position completely, but uses it for succession to the next level's position. [REPLACE_BY] is required to let that system work properly. This also means that the way in which landholders succeed (replace + as_needed) does not work in any other way.

Replacement between LAND_HOLDERS and other site- or civ positions does not work in any way. Only the vanilla replacement sequence between levels of LAND_HOLDERs does work. If the token is omitted for landholders, the landholder chain is broken, so replacement is required for the landholder system to work.

[REQUIRES_POPULATION] also does not work for [LAND_HOLDER], when you set [NUMBER] to 1. The position is not created when the required population is reached.

==What doesn't work==

'''Attention: If a position cannot be appointed, for example because of 'mutual appointment', it still exists according to replacement mechanics and will replace other positions if so defined. If a certain position(a) will be replaced by the baron's assistant, which can only be appointed by the [LAND_HOLDER] baron, than that position(s) still will be replaced from the start of the game, even if no baron or their assistant is ever present.'''

A position that is replaced by a somehow non-fillable position is still replaced. This counts for mutual-appointing positions, replacement by not-yet-assigned landholders, replacement by AS_NEEDED positions, or replacement by not-yet-appointed positions.

Replacement does not work if the replaced position is a [LAND_HOLDER], even with civ-positions. In that case, the LAND_HOLDER's position is not replaced. It does not matter if AS_NEEDED is used, or a fixed number, and it also does not matter what type of position the replacer is. So this only works (correctly) with positions that become available by REQUIRES_POPULATION.

={{text anchor|Evaluation of Positions}}=
The game does not continuously check whether positions should become available, elected or be [REPLACE_BY]. This is well-known behavior—for example with the [[mayor]], who does not appear automatically when the required population ([REQUIRES_POPULATION]) is reached. Instead, positions must somehow be evaluated. This applies in several other situations as well

'''Cases that require a trigger:'''
* Election of a newly created position
* Election after the current holder dies
* Automatic assumption of a newly created position (this may take up to a day)
* New citizens (such as migrants) considering available positions
* Premature succession of a newly created position

'''Cases that do not wait for a trigger:'''
* Succession following the death of the previous holder
* Automatic assumption of existing positions that have become vacant

'''Triggers that cause the game to reevaluate noble positions:'''
* Succession of a [SITE]-position due to the death of the current holder
* [[Advanced_entity_position_mechanics#Election_Day|Election Day]]
* Automatic assumption of a [SITE]-position that becomes vacant
* (Re)assigning any site position manually
* Settlement elevation on the LAND_HOLDER track (e.g. gaining a [[Baron]] or [[Count]])

=Gaining a position=
There are several ways a unit can gain a position:
* Appointment: A unit is appointed by another unit or by the player.
* Election: A unit is elected by and among the members of the entity
* Assumption: A position is neither elected or appointed: a random unit just simply 'takes' the position
* Succession: a unit is the valid successor of this position(A), either by its current position(B) or because they are that position(A)-holder's heir.

Available positions will automatically be assigned to a random civ member when a new site/civ is created.

==Who can take a position==

* If so defined, a unit needs to be the right caste and/or class - it does not seem to work with creature types.
* The unit needs to be an adult member of the site or its parent civ's government; that is also CAN_LEARN or INTELLIGENT (SLOW_LEARNER cannot take positions) or otherwise is able to think.

==Appointment==

Positions that have an [APPOINTED_BY:position] token require that position to exist, to be available and appointed. Any position that is APPOINTED_BY can be appointed if the appointer's position is filled in.
For site-positions to be appointed, it is required that the appointer is present at that location.

If the appointing unit is temporarily not present, or if that position is not filled, positions depending on it cannot be appointed. This is the case with [[militia captains]], when the [[militia commander]] is on a [[mission]].

A site position cannot appoint a civ position ''or'' LAND_HOLDER in any way whatsoever.

Civ-level positions can appoint other civ-level positions and site-level positions can appoint other site-level positions.

Contrary to what has been said elsewhere, civ-level nobles also can appoint site-level nobles. They need to be at the site to do so. Landholders can appoint both site-level and civ-level nobles. These systems are therefore not as separate as was assumed.

'''Mutual appointment''' cannot take place. If these are the only requisites of the position, then the positions will never appear or get filled. These unfillable positions can be put to good use, for example, to replace a position that is no longer needed without creating a new one.

'''Self appointment''' doesn't normally work. If you have a position that is only appointed by itself, it is never appointed and also cannot be assumed. However, if the position has a number higher than 1, and is filled by multiple units (for example by another position that is now empty), than those units can re-assign or appoint each other from that their shared position.

If an APPOINTED_BY token refers to a non-existing position's code, the effects are as if the appointment token doesn't exist at all.

===Automatic appointment in world-gen and on the civ level===

Outside of fortress mode, the game will always attempt to appoint nobles whenever possible, as long as these positions are '''available''', even if they are invisible to the player.
It shows this message in legends: "(unit name) has been appointed to the position of (position name)"

In world-gen, all positions become available and are automatically appointed, taking population- and appointment-requirements into consideration.

Positions that are REPLACED_BY are culled and won't be filled.

If a citizen of your fortress holds a civ-level position that can appoint another civ-level position, the appointment will happen automatically and without player intervention. It may happen that another citizen of your fortress is appointed by that unit, creating civ-level position holders in your fortress, but it is unknown what is required to force this effect.

===Manual appointments by players in fortress mode===
In fortress mode, the positions that need to be appointed stay empty on embark. and it is the player's job to appoint those. A player can appoint a unit to any available position, according to the hereabove mentioned conditions. The player takes the role of the automatic appointment-system, but has no direct control over elections, successions and replacement. There are some differences in what is possible at world-gen sites and at player-controlled sites.

* A position that is appointed by a unit present as a fortress citizen, can be appointed, re-appointed or left vacant. This means also by civ-level nobles living as a citizen in your fortress; not when they are only visiting, like the diplomat.
* A position whose appointing positions are all either vacant or [REPLACED_BY] can no longer be appointed. If the position is already filled, it cannot be reappointed or vacated; the current holder simply remains in office.
* A position that is APPOINTED_BY a unit present as the land_holder of your site, can be appointed, reassigned or left vacant.
* A position that has SUCCESSION BY_HEIR or BY_POSITION can 'initially' be appointed and also re-appointed or left vacant, but as soon as the [[nobles]] screen closes, ''it can no longer be replaced or left vacant''. From then on, the succession-rules determine who gains that position when the current holder loses the position. This works even if the SUCCESSION:BY_POSITION-position is vacant or replaced.
* A position that is ELECTED nor APPOINTED_BY, can always be (re-)appointed by the player. This is the case with the [[Expedition leader]]. If it is left vacant however, it cannot be appointed, but will be assumed shortly after.
* A position that is both ELECTED and APPOINTED_BY, cannot be appointed by the player. Contrary to world-gen sites, its slot is visible, but it doesn't show the +-sign. This is either by AS_NEEDED or by a fixed number. Even if the position somehow gets filled (re)assignment is never possible
* A player can appoint a number of units to a position, as much as the NUMBER token dictates. If it is AS_NEEDED, the player may create as many slots as they like, also contrary to world-gen sites.
* A civ-position can never be appointed, even if the appointing civ noble is a citizen of your fortress. A civ position also never can be re-assigned or left vacant, would that position be defined as appointed by a site-position.

==Election==
Read more in [[Elections]]. The message that is shown is: "(creature name) has been elected to the position of (position name)"

In worldgen, there is no functional difference between ELECTED and non-appointment, except that elected nobles tend to have high social skills and/or skills related to the position, while non-elected ones are assigned randomly. See: [[Elections]]

A succession goes before an election.

A position that is both ELECTED and APPOINTED_BY never gets elected. Even if the appointees' position somehow gets filled, (re)-elections won't happen. So, it doesn't seem possible to have an elected position become available when a certain other position becomes filled.

An ELECTED civ-(or LAND_HOLDER) position at your site will never be (re)-elected in fortress mode. So real (re-)election only works with SITE-positions.

=== {{text anchor|Election Day}} ===
Election Day takes place on the 17th of Summer. On this day, a full reevaluation is performed, including all currently elected positions, which are subject to re-election. Contrary to the information on [[Elections]], nothing occurs at the start of a season.

Positions that are both [APPOINTED_BY] and [ELECTED] will not be re-elected on Election Day when assigned through [SUCCESSION].

=== Election Eligiblity ===
Any citizen may stand for election. Eligibility cannot be restricted using [ACCEPTED_CREATURE], [REJECTED_CREATURE], [ACCEPTED_CLASS], [REJECTED_CLASS], or [GENDER]. Units currently having a [SUCCESSION]-position even may be elected for a position with a [SQUAD]-token, which is otherwise impossible to assign or even succeed.

=== Skills ===
In elections, skills are taken into account for the tokens of the position which is elected.
{| class="wikitable"
|+ Relevant skills per position token
|-
! Position Token !! Relevant skills
|-
| Responsibility [[Position_token#DELIVER_MESSAGES|[DELIVER_MESSAGES]]] || [[Ambusher]], [[Observer]] and [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#ACCOUNTING|[ACCOUNTING]]] || [[Record_keeper|Record keeper]]
|-
| Responsibility [[Position_token#ESPIONAGE|[ESPIONAGE]]] || [[Schemer]]
|-
| Responsibility [[Position_token#HEALTH_MANAGEMENT|[HEALTH_MANAGEMENT]]] || [[Diagnostician|Diagnostician]]
|-
| Responsibility [[Position_token#MAKE_INTRODUCTIONS|[MAKE_INTRODUCTIONS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#MAKE_PEACE_AGREEMENTS|[MAKE_PEACE_AGREEMENTS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#MAKE_TOPIC_AGREEMENTS|[MAKE_TOPIC_AGREEMENTS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#MANAGE_PRODUCTION|[MANAGE_PRODUCTION]]] || [[Organizer]]
|-
| Responsibility [[Position_token#MEET_WORKERS|[MEET_WORKERS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#RECEIVE_DIPLOMATS|[RECEIVE_DIPLOMATS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#RELIGION|[RELIGION]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#TAME_EXOTICS|[TAME_EXOTICS]]] || [[Animal_trainer|Animal trainer]]
|-
| Responsibility [[Position_token#TRADE|[TRADE]]] || [[Social_skill|Social skills]] and [[Appraiser|Appraiser]]
|-
| [[Position_token#SQUAD|[SQUAD]]]-token || [[Tactician]] and [[Leader]]
|}

==Assumption==

A position that is not APPOINTED_BY nor ELECTED, or is appointed by positions that are not available in your site or civ, will be assumable by a random dwarf. If it has responsibilities that require certain skills, then these are taken into consideration on embark, but not when the position is assumed during the actual game.

Normally, one to three units will take the into consideration to assume a position. Most of the time when there are multiple open positions, only a single unit will assume all of them. However, a position that has REJECTED_CREATURE, REJECTED_CLASS, ALLOWED_CREATURE or ALLOWED_CLASS will be filled with all different units, even if the creature or class mentioned is irrelevant. It seems that this forces the game to loop over all the available units.

The message that is shown in Legends mode is: "(unit name) has assumed the position of (position name)". This may also take place in fortress mode, which then shows this message to the player.

If an assumable position becomes empty, it will be assumed within a day. This is the case when you leave the position of expedition-leader vacant. It also happens with entities.

Assumable positions that become empty will not be assumed if that position has a valid [SUCCESSION] -successor. In that case, the successor inherits the position.

Even positions that are somehow invisible because they cannot be directly APPOINTED_BY players, can be assumed.

When you embark, the assumable positions are automatically assigned to a random unit. If there are multiple of these positions at embark, they all are assigned to the same unit. If there are enough positions available, multiple units may gain a position, but often no more than three different ones.

If a dwarf in fortress mode assumes a position, that already has another position, it will leave the current position empty. When that position also is assumed, then this will continue until all positions have a dwarf appointed to them, with no other position.

A unit that already has a position with a [SUCCESSION] token won't take assumable positions into consideration that have a [SQUAD] token. This can be used by the modder to prevent unwanted loss of current positions.

A position that has an appointer which got replaced because of REPLACED_BY, will not become assumable. Also, positions that have an AS_NEEDED appointer that is not yet filled (or ever), will also not be assumed.

==Succession==

If a position-holder dies or advances to a new position via succession, the position will be granted to another unit based on the [SUCCESSION] tag. If they have an heir or the succeeding position exists, that unit will be assigned. If not, a new one will be appointed according to the usual rules. The message that is shown is: "(creature name) being the rightful heir, has inherited the position of (position name)"

The succeeding creature will also lose its previous position. When succession is defined using BY_POSITION, the unit naturally loses the referenced position. However, it also loses any other positions it may hold. If a unit could simultaneously inherit multiple positions, the last-defined succession overrides the earlier one, clearing the previously acquired position

Succession works both at site-level and at civ-level, both in world-gen and in fortress-mode. Succession by position on the civ-level is also visible and functional in fortress-mode. If both civ-level nobles are a citizen of your fortress, succession is applied visually. Vanilla example: The [[druid]] is succeeded by the [[acolyte]]. This means that as soon as the druid dies, the acolyte takes over.

When a position that is succeeded by position becomes available, immediately it is checked if a position-successor is available and the position is filled with that unit. Even if this is an [ELECTED] position, succession goes first. When elections eventually do happen, succession plays no role.

It is possible to assign multiple levels of [SUCCESSION:BY_POSITION] in different positions, creating a line of positions where the death of one causes all those "below" them to advance.

A position can have multiple tokens with position-succession. It looks to be random which one is used. It is not always:
* The first or last defined token
* The first or last appointed unit
* the oldest or youngest
* one with a higher or lower precedence
* a unit with relevant skills

When a position is defined with a Succession-type, that unit cannot have another position that has a Squad-type. If the succession-position itself has a squad, than it can be assigned another position with a squad, but then it will loose the previous succesion position. See further details by "Squad"

Assumed positions can also be succeeded by position, if the current holder dies.

If the successor is an AS_NEEDED position, the used unit will leave a vacant position-slot on its removal by succession. This empty slot remains a real slot, which will only be cleaned up if you (un)appoint a unit to this position-series. It isn't cleaned up after regular position validation.

A civ-level position of a unit living at your site might be inherited by a unit holding that does not currently live at your site. This, unfortunately, moves that position to a unit off site. This may also happen with the landholder of your site, for example when it is succeeded by another civ-level position. This currently poses an unsolved challenge.

===Eligibility for succession===
Succession is restricted by the tokens [ACCEPTED_CREATURE], [REJECTED_CREATURE], [ACCEPTED_CLASS], [REJECTED_CLASS] and [GENDER].

===Site and civ combined succession===

Succession can work when combining site positions with civ-level positions or land_holders, but only in world-gen mode. In fortress mode, it only works with combining the same level of nobles, with Landholders regarded as civ-level. So, in fortress mode, a site's position cannot succeed a landholder's position and it cannot succeed another type of civ-level position, and vice versa.

This won't work even if the positions:
* are AS_NEEDED or having a fixed number.
* Are LAND_HOLDERs.

===Succession [BY_HEIR]===

When a heir is needed for succession, all children and then other relatives are validated. They cannot take the position if their status does not allow it, for example if they have become a member of another civilisation. See: "Who can take a position". If the unit has no valid heir on that location, the position may go to a unit living on another site. This may cause the title of Landholder of some land to be inherited by a unit living somewhere else. That might be a problem, because then you lose your landholders.

===Premature Succession===

There are cases where [SUCCESSION:BY_POSITION] is applied prematurely: at the moment a position is first created and becomes appointable or assumable, rather than after a current holder leaves. In this situation, the succession mechanism assigns a holder immediately, without any player interaction.

When a position becomes available for the first time, the game checks whether a valid successor-by-position exists. If so, that unit is assigned instantly. It can affect positions that would normally be appointed or elected by the player, causing succession to trigger before the player has any opportunity to intervene.

This behavior occurs only in Fortress mode, but can be applied both on [SITE]-positions as well in civ-positions. That last one however is a bit harder to control. Example: [[Advanced entity position mechanics#The Archduke|The Archduke]]

This premature succession only occurs the first time a position becomes available (i.e. when it is created and becomes appointable or assumable). Even if the position remains vacant and the conditions for succession improve later, premature succession will not trigger again. From that point onward, only normal succession rules apply.

Using premature succession, a position that has [ELECTED], [APPOINTED_BY], or both, can be filled directly.
Notably, positions that combine [ELECTED] and [APPOINTED_BY] are normally impossible to fill through regular mechanics. Premature succession bypasses both election and appointment entirely, making this combination uniquely reachable through this mechanism.

No initial election takes place, and no subsequent elections will ever occur for that position. Succession always takes precedence over election, both in premature succession and in normal succession cases.

This behavior applies only in Fortress mode, not during world generation. World-gen uses simplified and more efficient mechanics, and this interaction does not occur there. Premature succession can affect both site-level and civilization-level positions.

====Multiple succession chains====

Multiple succession chains may be defined and are resolved in the order they appear in the raws.

If a position has both:
* a direct succession chain (A → C), and
* a multi-step chain (A → B → C),

and intermediate positions are vacant, resolution proceeds according to raw order. A common outcome is:
# The direct succession (A → C) is applied first, assigning A to C.
# The remaining chain then advances (A → B).
# If C still has empty slots, the final step (B → C) may occur.

If position B is already filled, behavior depends entirely on raw definition order:
* nothing may happen, or
* B may move to C first, followed by A moving to B.
====Working triggers====
Premature succession is triggered when a succeedable position is created under the following conditions:
* The succeedable position is created because its [REQUIRES_POPULATION] threshold is reached. This applies even if the position is not [APPOINTED_BY]. Premature succession takes priority over automatic assumption (e.g. the mayor declaring themselves within a day).
* The succeedable position can be [APPOINTED_BY] another position of the same level (site or civ) that has just been created because its [REQUIRES_POPULATION] was reached.
* The succeedable position can be appointed by another [SITE] [AS_NEEDED] position that has just been created and filled.
* The succeedable (site or civ) position is [APPOINTED_BY] the [LAND_HOLDER] position, which has just been created due to site elevation. This typically resolves when the diplomat leaves the map, at which point the landholder position becomes active.
* If all other requirements are met, premature succession can occur immediately after unpausing following embark, for positions with [REQUIRES_POPULATION:7].
====Non-working triggers====
Premature succession does '''not''' occur in the following cases:
* An [AS_NEEDED] succeedable position slot is manually created by the player while its succeeding position is already filled. [AS_NEEDED] positions must always be appointed after creation.
* The succeeding position is filled after the succeedable position becomes available. The moment of creation is the decisive trigger; filling the source position later is too late.
* The succeedable position can be appointed by another site or civ position with a fixed number of slots that has just been appointed. In this case, the succeedable position is just available for appointment itself, nothing more
* Any situation occurring during world generation.
* The succeeding position is [REPLACED_BY] the succeedable position. In this case, replacement removes the unit from the source position first, leaving no holder available for the succession mechanism to use.rst, leaving no holder available for the succession mechanism to use.
* The position is [APPOINTED_BY] a civ-level position, that just became a citizen of your fortress. It must be noted that those civ-level positions were active all that time and the succeedable position could be appointed even before. The monarchs arrival does not trigger premature succession

=Losing a position=

A unit can lose a position when:
* It dies
* It succeeds another position, even if it has nothing to do with the previous position.
* It is assigned to another SQUAD-holding position
* It is convicted of a crime.
* Another unit is ELECTED for the position
* Its position becomes replaced
* Another unit is appointed by the player, or the position is left vacant.
* It has assumed another position, as this always leaves the previous position vacant.

=Embarkment=
Two types of positions are automatically filled by embark.
* Positions without [APPOINTED_BY] or [ELECTED] (assumable). All these positions, even with a NUMBER higher than 1, are all filled with one to three dwarves. Contrary to assumption, this doesn't take into account any limitations. REJECTED_CLASS, ALLOWED_CLASS, REJECTED_CREATURE, ALLOWED_CREATURE and GENDER are applied, but without the normal spread you may expect with assumptions. Also it doesn't look at [SUCCESSION] and [SQUAD] limitations.
* Positions that are elected are filled-in by the normal election rules.

Positions that have a defined appointer are never initially filled at embark.

All positions that don't have [REQUIRES_POPULATION] or with a [REQUIRES_POPULATION] of 7 or lower, will be available at embark.

=Land Holders=

A Landholder is a '''special civ-level noble''' who gets a certain piece of land to hold, when that land is elevated to a certain level, determined by the tag [LAND_HOLDER] and by the landholder triggers in the game's settings. In vanilla, these are the baron, the count and the duke.

A unit gaining the landholder position does not migrate to that specific named land. In world-gen, they stay just where they are, probably at the capital. In fortress mode, you can suggest a citizen for the role. So for the time being that works.

Succession is then a real issue. If you use BY_HEIR, its solved when that landholder has children living at your site. But when its not the case, the title just goes to anyone randomly. Succession BY_POSITION works, but only in the civ-chain, and there's no way to guarantee a civ-holder is at your site at that time. Even with 'automatic spread' positions, it goes to one of them randomly.

==Functioning of the regular landholder chain==

The distinct difference between a landholder and a regular civ-level noble, is that a landholder may gain the position of landholder "of (sitename)" They are then seen as ruler of a particular site.

For a land_holder position to function as such, it has a few requirements:
* NUMBER:AS_NEEDED
* The first landholder-number of 1 is defined.
* No SITE (so civ) tag in that position.
*REPLACED_BY the next level landholder
If a landholder is defined with differentiating properties, it will function like a regular noble. A higher-up landholder that lacks the required tokens or connections will then not be used in elevation.

If a fortress meets the trigger for a new LAND_HOLDER tier when a caravan leaves, then the next time the outpost liaison or equivalent arrives, they will offer to make you an official colony, which will allow you to select all positions for that LAND_HOLDER level. Each time they appear, the outpost liaison will only promote your fortress one tier up the LAND_HOLDER track.

The landholder's LAND_NAME is not required for the functioning of this system. If omitted, messages will be shown with a more generic text.

==Appointment==

This mechanism differs from the regular methods of position management. It ignores all regular appointment- and election rules, so it more or less functions like automatic assignment. A landholder is, in vanilla, appointed by the monarch. Changing this doesn't seem to do anything. If they are appointed by a site-position, a not-yet-existing civ-position, or not appointed at all: the system keeps working as usual.

A landholder can appoint civ-positions and site positions. This works as expected: the positions only are appointed then when that landholder becomes available on civ-level or when he arrives at that site for site-level positions.

If your rank of landholder is the first of its rank in the realm, and is the sole appointer of some civ-position, then immediately as it gains the title, it will appoint the empty civ-slots. This may happen on your site, but the frequency and certainty is hard to determine.

==Succession==

Succession rules are applied to some extent:
* In world-gen it works according to succession rules, and site-positions can be used here. This means that a site position or a civ-position can inherit a landholder position, and vice versa.
* In fortress mode, once a landholder has been appointed, it then can inherit civ-level positions, and vice versa. This means that your baron can become king.
* Succession rules do not apply within the [LAND_HOLDER] chain; a count will not inherit a baron's land. This is because succession does not work well with the AS_NEEDED token.
* Premature succession works in fortress mode with landholders. If a unit gets a landholder's position and that landholder is the appointer of an as yet empty position, which is defined as succeeding from a third one, then the succession is immediately applied. The landholder themselves can even be the successor of a newly created position.
* A landholder's position is, in fortress mode, not successionable by a site-position or vice versa

===Impossibilities for succession by a site-position===
It would be very beneficial if the landholder can be succeeded by a [SITE]-position. So far, the following tests have not lead to positive results:
* making landholder and site-position both non-[DUTY_BOUND]
* make the site-position be [APPOINTED_BY] the landholder and/or the monarch
* give landholder and site-position [REJECTED_CREATURE]
* Let the monarch live at your site when succession could happen.
* Let the site-position be [REPLACED_BY] the landholder.

==Nomination==

The player is able to nominate a unit to become the LAND_HOLDER, but this only works with units of [LAND_HOLDER] level 1. The player can select all units, only limited by the PRECEDENCE of the current units' positions.

A unit that has a position with a PRECEDENCE lower or equal to that of the landholder's position, cannot be selected. This means that a baron (or count) from another site or the monarch cannot be selected, because their precedence is lower or equal.

The GENDER token does not work here: also units with the wrong gender (sorry) can be selected.

==Levels==
In mods, up to 10 levels of LAND_HOLDER may be defined.

If a landholder is replaced by a wrong landholder number (1 replaced by 3), then the number 3 is still correctly attached to the settlement.

If the current landholder has the highest available landholder number, then the next elevation will not happen - the diplomat will not elevate your fortress to a higher position, even if that position might be REPLACED_BY a lower landholder.

These chains do work:
* 1 -> 2a - > 2b -> 3
* 1 -> 3 -> 2 -> 4

These chains do not work:
* 2 -> 3 (need to start at 1)
* 1 -> 4 -> 2 -> 3 (stops after 4 as the highest)
* 1a -> 2, 1b -> 2 (only 1a and 2 work, 1b is not used)

==Moving landholders==

It may happen that a land-holder no longer lives at the site which they are the landholder of, specifically when the current landholder dies, leaving the title to an heir living somewhere else.

To prevent this from happening, you can make their succession from heir and make sure that their kids live at your site. Or, you can make their position succeeded by another civ position, and make it so that this civ position is somehow available on your site. But if multiple of these positions exist, it cannot be guaranteed that a citizen of your fortress will inherit the title.

In world gen, a landholder lacking the DUTY_BOUND-token will also move to the site they like, according to legends mode.

==Replacement by a generic civ-position==

If a landholder is replaced by an AS_NEEDED non-landholder civ-position, then this will work: the current landholder loses that title upon settlement-elevation and gains that civ-title. However, the civ-title lacks the landholder-property of being attached to the land. It will not show the name of the settlement alongside the position's name. So no "minister of Shovelmounts"

If a landholder is replaced by a general AS_NEEDED civ-position, that itself is also replaced by a generic AS_NEEDED civ-position, then firstly the elevation is executed and also the unit gains that new position. However, he immediately loses it, because an AS_NEEDED position that is replaced by another position can be filled initially, but units wont be able to hold that title.

==Landholder with fixed number==

A landholder's position that has a fixed number will be created and filled directly when the civilisation is born, so this position slot is then not available for the regular landholder-mechanic and will also not be used. That landholder will thus not be attached to a settlement.

It doesn't matter if the landholder's position is connected to the regular landholder's-chain with the REPLACE_BY token.

==Responsibilities==

When given a certain [RESPONSIBILITY], a landholder may function as a regular civ-level noble. If the position has [TRADE] or [OUTPOST_NEGOTIATING] responsibilities, then the landholder functions both as a diplomat and as an actual land holder. A landholder with the [MILITARY_STRATEGY] responsibility will travel around taming creatures in world-gen, according to legends mode.

Besides that, the responsibilities work the same as with any other on-site living position-holder, civ or otherwise.

=Military=
==Squad management==
In the vanilla game, the Squad interface only becomes available after a militia commander has been appointed. Until then, the window displays:{{DFtext|You must appoint somebody first to create a squad.}}

What’s surprising is how this is determined internally. In the entity raw definition, '''only the last two positions that include a [SQUAD] token are checked''' to decide whether the interface is accessible at all. As a result, if your hierarchy defines commanders A through E, appointing '''Commander D or E''' unlocks squad formation, while appointing A–C does nothing.

In other words, squad availability is not tied to ''having a militia commander'', but to ''which specific positions happen to be last in the raw list''—a notably hacky implementation.

These 'last two' are always the last two '''available positions.''' So if they get [REPLACED_BY] or become available because of [REQUIRES_POPULATION], the game adapts to those.

==Squad assignment==

Squads can be assigned, even if the leader position has no holder.

A specific unit can only have one position associated with a squad. If it gains another 'squad holding position', it is unassigned from the first one. This does not work with a 0-squad, so only 1+squads are taken into consideration. This technique can possibly be used to distribute all positions equally among all citizens. It does however not work with election and assumption.

If a civ-level position is associated with a squad and it gets a site-level squad-holding position assigned, it loses the current civ-position.

Squads can get really messed up, if you make the position (or multiple) either elected or not-elected and not-appointed, then this can cause the game to assign multiple squads to the same unit. Automatic assignment and election does not take squads into account, but the nobles screen does. This can cause the positions to be cleared as the game figures out that they have more than one position, and immediately get elected or assumed again.

Positions that cannot have a squad-position:
* A site- or civ-position with a [SUCCESSION] token cannot be appointed a squad-holding-position. The other way around, however, does work. For example, if a site-position with a [SUCCESSION]-token is appointed to a unit that has already a position with [SQUAD]. But when that squad position is assigned to another unit, it cannot be assigned back.
* A position with [SUCCESSION] can also not be assigned as a '''member''' of a squad.
* A squad-holding position with a formed squad cannot be appointed to another squad holding position.

If a position has at least one squad member, it cannot be left vacant. First, the squad has to be disbanded, then the position may be cleared.

==0-squads==
A 0-Squad is defined in a position as [SQUAD:0:member:members]. It does not seem to do anything useful as of now.
* It cannot be used to activate the [[Squad|military interface]]
* It does not restrict the assignment of [SUCCESSION] positions.
* Assigning this position does not clear any previously held squad position.
* The [[Leader]] and [[Tactician]] skill are not marked as relevant skills and are not taken into account in elections.
* It cannot be formed as a squad.

=Further testing=
The following questions may need additional testing. Feel free to add or answer
* Everything regarding COMMANDING and army-structure
** [http://www.bay12forums.com/smf/index.php?topic=175437.msg8331668#msg8331668]
** [http://www.bay12forums.com/smf/index.php?topic=165213.msg8335682#msg8335682]
** [http://www.bay12forums.com/smf/index.php?topic=174584.msg8026854#msg8026854]
* Everything regarding CONQUERED_SITE, but it is presumably just like site. But what if you combine SITE or LAND_HOLDER with it?
* Stuff about the monarch, its arrival and its entourage.

=Oddities (Bugs)=
Almost everything on this page could be called an oddity. Because of their unexpected usability, some may also be referred to as “undocumented features.” Others, however, are simply odd and not particularly useful, yet I hesitate to call them “bugs.”
* If a certain threshold is reached that makes an elected position electable, and the triggering event that initiates this evaluation is an assumption, then the resulting assumption is also referred to in the messages as an election

=Examples=

===The Founder===
The founder is a single dwarf, appointed at embark. They will be the only one ever to have this position and are not replaceable. When they lose their position some way, the position will not be assumed by another dwarf.
{{gamedata|title=The Founder|
[POSITION:THE_FOUNDER]
[NAME:the founder:founders]
[NUMBER:1]
[SITE]
[ALLOWED_CREATURE:DWARF:ALL] - will only be filled at embark, but not assumable later.
[REJECTED_CREATURE:DWARF:ALL] - will only be filled at embark, but not assumable later.
[SUCCESSION:BY_POSITION:THE_FOUNDER] - not unassignable, also cannot be assigned to a [SQUAD] position.
[PRECEDENCE:200]
Non APPOINTED_BY
Non ELECTED
Optional: Add responsibilities to make the game select a unit with certain skills.
}}
===Marriage bar===
Dwarven matrons are held in great honour. Upon marriage, a female dwarf is no longer expected to perform menial labour. All dwarven males hold this position by default, granting their spouses exemption from menial work.

The position becomes available with the arrival of the first migrants; otherwise, on embark, it would be assumed by females. Its succession rule is non-functional, but this prevents the player from unassigning the position. A squad size of 1 and the succession rules together prevent a unit from assuming the position more than once.

With precedence set to NONE, the position name is hidden, while LAND_NAME remains visible on the nobles screen. All married females receive the suffix “, Mrs.” and are marked as Nobles.

The practical usefulness of this position is debatable, but it serves as a clear demonstration of several mechanics.
{{gamedata|title=Mrs. Urist|

[POSITION:MRS_URIST]
[NUMBER:300]
[SITE]
[ALLOWED_CREATURE:DWARF:MALE]
Not APPOINTED_BY
Not ELECTED
[LAND_NAME:Dwarven male]
[NAME:dwarven male:dwarven male]
[PRECEDENCE:NONE]
[SPOUSE_FEMALE:, Mrs.:spouses]
[MENIAL_WORK_EXEMPTION_SPOUSE]
[REQUIRES_POPULATION:8]
[SUCCESSION:BY_POSITION:MONARCH]
[SQUAD:1:member:members]
}}
===The Archduke===
The archduke is the leader of the civilization, but exists only from landholder 4-level. Until then, its position remains vacant. When a settlement is elevated to tier 4 (grand duke), the grand duke can appoint the ruler of the civilisation, the archduke. Because of 'Premature Succession', they themself inherit that position immediately, but only when in fortress mode. Its heir then becomes grand duke.
{{gamedata|title=The Archduke| no POSITION:MONARCH or other PRECEDENCE:1

[POSITION:THE_ARCHDUKE]
[NAME:archduke:archdukes]
[NAME_MALE:archduke:archdukes]
[NAME_FEMALE:archduchess:archduchesses]
[LAND_NAME:a archduchy]
[NUMBER:1]
[PRECEDENCE:1]
[SUCCESSION:BY_POSITION:GRAND_DUKE]
[APPOINTED_BY:GRAND_DUKE]
(add additional monarch-stuff, like spouse name, demands etc.)

[POSITION:GRAND_DUKE]
[NAME:grand duke:grand dukes]
[NAME_MALE:grand duke:grand dukes]
[NAME_FEMALE:grand duchess:grand duchesses]
[NUMBER:AS_NEEDED]
[LAND_HOLDER:4]
// Optional ...
[PRECEDENCE:19]
[LAND_NAME:a archduchy]
[RESPONSIBILITY:LAW_MAKING]
[RESPONSIBILITY:RECEIVE_DIPLOMATS]
[SUCCESSION:BY_HEIR]
[APPOINTED_BY:THE_ARCHDUKE]
(add additional landholder-stuff)

!!add to [POSITION:DUKE]
[REPLACED_BY:GRAND_DUKE]

}}
{{Category|Modding}}
{{Category|Entities}}
{{Category|Guides}}

Advanced entity position mechanics

2026-02-12T08:30:36Z

Joostheger: /* [PRECEDENCE] */

{{Quality|Fine}}
{{Modding}}

= Introduction =

[http://www.bay12forums.com/smf/index.php?topic=182239.0 Discussion thread on the forum]

This page documents observed and tested behavior of entity positions in Dwarf Fortress that is not fully described elsewhere on the wiki. It focuses on advanced interactions between position tokens, including appointment, succession, election, and responsibility handling, across both civilization-level and site-level entities.

The mechanics described here are based on empirical testing in world generation and fortress mode, supplemented where necessary by raw analysis. In several cases, the game’s behavior is determined by evaluation order and interaction between multiple tags, rather than by individual tokens in isolation.

This page is intended for modders and advanced players who are designing or debugging custom entity position structures. It does not restate basic position mechanics, but instead highlights edge cases, non-obvious interactions, and behaviors that may appear inconsistent or undocumented.

Unless stated otherwise, the described behavior applies to current versions of the game and may differ from older releases.

==What is an entity? What is a position?==
An [[entity]] is an organizational structure that can have relationships with other entities, usually known as a [[civilization]] or a "[[site]] government" in the game, but merchant [[guild]]s, religious organizations, necromancer towers, and [[bandit]] groups are also entities. An entity can have positions - in most cases, these are hardcoded and generated by the game, but as for civilizations and sites, the [[raw file]]s can be customised.

A position is a special relationship between a unit and an entity. The unit holding a position has a larger influence over that entity than other citizens. Positions are mostly known as [[nobles]], but in this article. the technical term is used.

=Position levels (Site/Civ) and their interaction=
There are two basic types of positions that are customizable: '''civ(ilization)''' level and '''site level'''. Positions with the tag [SITE] are at site level, positions without the tag [SITE] are at 'civ level'. These two types of nobles can be considered '''loosely related systems'''. There are a few places where they can interact with each other.

Civ-level positions are in charge of the civilization as a whole, managing national [[trade]], laws, and [[war]]s. These are, for example, the vanilla [[monarch]], [[diplomat]] and [[general]]. (Note that the general doesn't do anything in either mode in the current version.)

'''[LAND_HOLDER]''' nobles are also positions at civ-level. These units are members of the national government, but have gained authority over some land or site. Once they do, they move to that place, but their position is still regarded as a civ-level position.

Site-level position holders are members of a site government (subsidiary to the civilization), and manage local affairs in that location. These are, for example, the [[mayor]], the [[sheriff]] and the [[broker]].

==Table of interaction between different position levels==
In this table, the possible interactions between different position levels are summarized.
The header row shows the positions defining the tokens.

The left column shows the position type that is referred to.
Example:
{| {{prettytable}}
|- bgcolor="#ddd"
! referred position-type
! LAND_HOLDER
|-
| civilization
| (baron is) APPOINTED_BY:MONARCH
|}
color coding: 
* Exists in vanilla
* Possible with mods
* Not possible
* possible to some extent.
* not yet fully investigated.
{| {{prettytable}}
|- bgcolor="#ddd"
! referred position-type
! Civilization
! SITE
! LAND_HOLDER
! CONQUERED_SITE

|-
| Civilization
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION '''(1)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION

|-
| SITE
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION '''(2)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY '''(3)''' COMMANDER REPLACED_BY SUCCESSION '''(4)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION

|-
| LAND_HOLDER
| APPOINTED_BY COMMANDER REPLACED_BY '''(6)''' SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION '''(5)'''
| APPOINTED_BY COMMANDER REPLACED_BY '''(7)''' SUCCESSION '''(8)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION

|-
| CONQUERED_SITE
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
|}

Remarks:
# Works only in world-gen, if a unit with that civ-position is present at the site.
# Works only in world-gen, the site-position holding unit will then move to the capital.
# Is completely ignored
# Works only in world-gen.
# Works only in world-gen.
# Won't appear at all
# This is necessary for the landholder chain to work properly, it doesn’t work otherwise.
# This works only outside of the landholder chain, so when landholders are simply regarded as civ-level nobles. might also work in world-gen
#

== Other interactions ==

Unfortunately, interactions with positions of other entities don't seem possible, such as APPOINTED_BY: HIGH_PRIEST. With [VARIABLE_POSITIONS], positions are automatically created with codes like CUSTOM_LAW_MAKER_2, but interaction with these positions don't seem to work, either. For more info on those, see [[Variable positions]]

=General=

==Civ-level nobles living at your site==
Nobles from your civilization can come to live at your fortress. This happens in vanilla with landholders such as [[Baron]], [[Count]] and [[Duke]], with the Monarch, but sometimes also with non-landed LAND_HOLDERS.

When a civ-level noble becomes a [[citizen]] at your location, their position is shown among the site-level positions in your [[nobles screen]]. They appear to function as a site-level noble. They may have [[demand]]s, [[mandate]]s, [[squad]]s and the like. They can appoint nobles at the site-level.

If they have certain [RESPONSIBILITY]ies, they do the tasks that go with them.

==Fortress mode, world-gen and their differences==
Their are a few differences in how positions function between fortress mode (normal play mode) and the world generation (world-gen).

In '''fortress mode''', the player has some control over the appointment of nobles, limited by elections, automatic filled-in positions and succession rules. Pre-fortress mode, which is referred to as '''world-gen''', the game will always attempt to assign nobles whenever possible. It is subjected to the same rules as in fortress-mode, but there are some exceptions. In '''[[World activities]]''', which is the thing that happens in the world while you play fortress mode, it seems as if the same rules are applied as fortress mode.

A difference between player-fortress-mode and world-gen, is causes by visibility (see below). Positions that are not visible by the player and thus not available for assignment, will be available in world-gen and will thus be automatically assigned.

In fortress mode, a position that is both [ELECTED] and [APPOINTED_BY], cannot be appointed by the player and is also not elected, and can thus not be filled. But in world-gen sites however, these positions are automatically filled.

Positions with [AS_NEEDED] are almost never created and filled in world-gen (depending on their [RESPONSIBILITY]ies), but can always be used in player mode.

A position can, in fortress mode, be filled by the same unit. A unit can gain multiple positions in fortress mode, for example because of [[elections]]. This will not happen in world-gen mode: a unit can only have one position. See also remarks on 'embark' and 'Losing a position'.

In world-gen, [SUCCESSION] between civ-levels and [SITE-]levels may happen. This will not happen in fortress mode, or even off-site in [[World activities]].

In fortress mode, premature SUCCESSION may happen. This will not happen in world-gen mode.

==Units holding multiple positions in multiple entities==
A unit can hold multiple positions in its civilisation or in its site-entity, however this does not happen in world-gen. Only at player-managed sites can units be holding multiple positions at once. (It is probably not possible for a unit to hold a position in two different civilisations or two different sites.)

In world-gen, if there are too many positions to be filled, they simply stay empty until more units are available. E.G, a unit at a site might inherit a civ-level position and still remain a member of the local government. When this happens however, they move to the capital. If a unit gains a new position, either inherited or otherwise, it drops the previous one. If a unit assumes a civ-position in fortress mode, it leaves the current position.

If a unit holds the same (site-)position multiple times, it has no additional effect.

If a unit holds multiple different positions of the same entity, it has all those positions' responsibilities and properties, stacked up. Presumably, the demands for those combined positions are determined by the highest.

A unit holding a position with a succession token can be assigned another position with a (different) succession token.

A unit holding a position with a squad-position cannot hold another squad-position. It is dropped from the first, when it gets its second assigned.
A unit holding a position with a succession token cannot be assigned to a squad-position - the unit is simply not available. It works the other way around, though.

=Specific Tags=
==[PRECEDENCE]==
The first defined position with precedence of 1 counts as the ruler of the civ. See also: [[Position_token#PRECEDENCE|PRECEDENCE]].

If the precedence is omitted or has a negative value, the game sets 0 as precedence, which seems to have no effect whatsoever.

When a unit has multiple positions, the name of the position with the highest rank in precedence is shown behind the unit's name.

If you omit precedence entirely, or set it to [PRECEDENCE:NONE], the position name will not be shown after the unit’s name. Your *Urist Mason* will remain simply *Mason*. This can be useful for positions that are unimportant or purely functional. The position will also not appear in the civilisation overview of your site on the world map. The position name is shown in messages, but remains hidden on the nobles screen as well. To make it visible there, use [LAND_NAME].

=[RESPONSIBILITY]ies=
Both civ and [SITE] positions can carry responsibilities. However, not all responsibilities are active for both types: some function only for civ positions, others only for site positions. When a civ noble arrives at a site and takes up residence, they do not perform responsibilities that are intended for SITE nobles. As a result, these responsibilities neither trigger their associated tasks nor unlock related game mechanics. For example, a civ-level manager living in a fortress will not perform management duties there and doesn't unlock the management-screen, even with an assigned office.
This behavior applies to the following [SITE]-level responsibilities:
* [RESPONSIBILITY:ACCOUNTING]
* [RESPONSIBILITY:BUILD_MORALE]
* [RESPONSIBILITY:HEALTH_MANAGEMENT]
* [RESPONSIBILITY:LAW_ENFORCEMENT]
* [RESPONSIBILITY:MANAGE_PRODUCTION]
* [RESPONSIBILITY:MEET_WORKERS]
* [RESPONSIBILITY:TRADE] (functions differently)
Other responsibilities may be affected as well, but have not yet been fully tested.

==[DELIVERS_MESSAGES]==
The only [AS_NEEDED]-position that is created in worldgen based on responsibility is that of the site-level responsibility [DELIVERS_MESSAGES].

==Outpost Liaisons and Diplomats==
Civ-positions with the responsibility [ESTABLISH_COLONY_TRADE_AGREEMENTS] ([[Outpost_Liaison|Outpost Liaison]]s) will meet with the site-noble who has responsibility for [RECEIVE_DIPLOMATS] and the highest rank of precedence (i.e. the lowest precedence value). Usually this is the [[Expedition_leader|Expedition leader]].

Once a [LAND_HOLDER] is assigned to the site, civ-positions with the responsibility [MAKE_TOPIC_AGREEMENTS] ([[Diplomat]]s) will meet with '''civ'''-level nobles present at the site who have the [RECEIVE_DIPLOMATS] responsibility. If multiple eligible nobles are available, one is selected at random. If no eligible noble is present, the diplomat leaves angrily. If the landholder is no longer present at the site, diplomats will not arrive at all.

It appears that Outpost Liaisons and Diplomats are chosen for a diplomatic mission based on availability. When multiple candidates exist, the position defined last in the raws is most often selected.

==[TRADE]==
Civ-level nobles with [TRADE] will arrive with the caravan, just as the Outpost Liaison. Their behavior is no longer active in the vanilla game, but the mechanics are still present. See [[40d:Guild_representative|Guild representative]] for more details. This civ-noble will only meet with the SITE noble with [TRADE], usually the [[Broker]].

If two civ-nobles exist with both [TRADE] and [ESTABLISH_COLONY_TRADE_AGREEMENTS], they both arrive at the same time. Even if both tokens are assigned to a single position, if more than one instance of that position exists, two of them will arrive. However in that case, somehow the elevation of the site and appointment of landholder isn't offered.

If the SITE-noble they intend to meet has both [TRADE] and [RECEIVE_DIPLOMATS], only one meeting will proceed and the other is cancelled. However, when two SITE-nobles are available, each with either [TRADE] or [RECEIVE_DIPLOMATS], both meetings will proceed and both civ-nobles will attempt to negotiate a trade agreement. It is not known what happens if these agreements are accepted or refused.

In the trade depot, the last defined position with the [TRADE] responsibility is shown as broker. However when requesting a trader, the first defined position with [TRADE] will actually go there to do the trade.

==World-gen effects of the [RESPONSIBILITY] of available positions ==
It is possible to cause civs and individual sites to change their behavior substantially when they reach a certain size, by controlling nobles.
* If a site can only appoint a position with [MILITARY_GOALS] after reaching a particular size, that site will not send armies on missions until the required size is reached.
* A civ-level [LAW_MAKING] position is required for the civilization to have any kind of cohesion. Without it, sites will be constantly embroiled in territorial disputes and civil wars will be commonplace.
* [MILITARY_STRATEGY] positions go out and tame wild animals. This makes your civ gain those animals as domesticated and also brings them in sieges.
* The [[Personality_facet|Personality]] of the position's holder determines how they lead the civ.

=Availability and visibility=
==Availability of (new) positions==
Warning: Do not mistake "availability" for "visibility"!

Of all the possible positions existing in your site's entity, there may only be some available.
* Positions with [REQUIRES_POPULATION] require the population to have a specific size.
* Positions with [REQUIRES_MARKET] will only appear in "large" sites (which may have different rules for different site types). This tag has no effect in fort mode.
* Positions that are appointed by positions that have an AS_NEEDED number. The appointable positions only become available after an appointer position-slot is created. This works also on civ-level. If a position is appointed by a Land-holder, it only becomes available, when that level of landholder is created.

Only the replaced positions are culled and are no longer available.
A position that requires a certain population will become available, even if it doesn't have [APPOINTED_BY] or [ELECTED]. In that case, see 'automatic assignment' and 'assumption'

In fortress mode, in some cases 'succession' is evaluated immediately after a position becomes available. See: Succession.
==Visibility of positions==
A position might be available, but can still be invisible for the player in the [[nobles screen]]. The positions with their respective holders are visible for players:
* All site-positions that are already filled-in (even if they could not be re-filled-in considering current conditions)
* Site positions that are appointable by a filled-in site position
* Site positions that are appointable by a filled-in civ position, when that civ positions holder becomes a citizen of your fortress.
* Civ positions of units that are also a citizen of your fortress.
If a position becomes available, for example because a certain pop number has been reached, or if it is available from the start(like expedition leader), as long as it cannot be appointed, it still is INVISIBLE for the player.

It might strike someone as odd if a position becomes filled automatically in fortress mode when that position is not even visible. This might be the case if the current holder of a non-appointable position dies or succeeds another position. Regardless of player visibility, these positions will be automatically filled in if the necessary requisitions are met. It might happen with the expedition leader.

A situation with a non-visible but available position, is for example when a position is solely appointed by the expedition leader, when the expedition leader's position is left vacant. It can no longer be appointed by the player and is invisible. Then, it gets automatically assumed, proving that the position still was available.

A position that is both [APPOINTED_BY] and [ELECTED] is visible, but players cannot interact with it.

=[NUMBER]=
A position might be defined with a number. In that case, as many as defined can be available. If the positions become available, in world-gen and when embarking, they are all filled-in completely.

If the ruling position (with PRECEDENCE of 1) has a NUMBER higher than 1, a random unit of the ones holding these positions is shown as ruler in the embark screen.

A [NUMBER] of 0 (zero) has the same effect as 1.

==Automatic spreading of assumed, non-singular positions==
If there are civ positions that have a NUMBER higher then '1' and which are assumed (not APPOINTED_BY or ELECTED) but are '''not DUTY_BOUND''', these are automatically spread among the civilisation, based on population. If there are a number of '''20''' available slots of that position, they spread among a civilization with a combined population of, for example, 1000 of which your fortress has 100 (10%), '''2''' of your fortress' citizens will assume that position.
This may probably also work with elected and appointed positions, but that may be depending on the death of the current holders and this needs more testing. Assumption works within a day, anyway.

==[AS_NEEDED]==
These positions can be created automatically by the game in world-gen. This, however, only works with:
* [LAND_HOLDER]'s
* squad commanders (needs more testing)
* Messengers at sites

For all other types of positions, they're not created in world-gen, even if they are defined with RESPONSIBILITY's. For example, even in war, the game wouldn't create a MILITARY_GOALS position, if they have AS_NEEDED as number.

However, in fortress mode / player mode, these positions can be created by the player at will.

Positions with AS_NEEDED need to be created first, before any symbols are assignable as 'symbols' (objects) for the position holder to carry or wear.

Positions with AS_NEEDED cannot be created and then ELECTED in fortress mode. It only works with APPOINTED_BY.

=Replacement and Required Population=

The token REPLACED_BY:position means that once the replacing position reaches its required population-number, the 'to-be-replaced' position will disappear. This is defined in REQUIRES_POPULATION. These tags are closely related to each other and seem to only have a meaningful function if combined. Nobles with REQUIRES_POPULATION require the population to have a specific size.

This works on the civ-level as well as on site-level, but those systems are in this mechanic strictly separated. Site-level positions cannot be replaced by civ-level positions and visa versa. This makes sense, because they both depend on their own population-count. When using REQUIRES_POPULATION on civ-level, it counts the total population of the civilisation.

See also: [[Advanced_entity_position_mechanics#Evaluation_of_Positions|Evaluation of positions]]

==Effect of replacement (and on [LAND_HOLDER]s)==

Replacement is immediate and complete - the current holding unit loses the position, even before SUCCESSION_BY_POSITION rules are applied. A position with a number of 1 will replace all the slots of a position with a higher number of slots.

Even if the next position is available but not visible, replacement still takes place. If a position is replaced, it is completely gone - it cannot be appointed, succeeded, elected or assumed any longer.
The unit immediately loses its position.

In legends, replacement is mentioned as: "(unit name) ceased to be (position name)" The replacement of an AS_NEEDED position empties the position's slot forever. In fortress mode, it may seem as if you can create new slots and appoint new units in the nobles screen, but this is reversed as soon as you close the window.

The landholder chain uses [REPLACED_BY] differently. It does not clear the position completely, but uses it for succession to the next level's position. [REPLACE_BY] is required to let that system work properly. This also means that the way in which landholders succeed (replace + as_needed) does not work in any other way.

Replacement between LAND_HOLDERS and other site- or civ positions does not work in any way. Only the vanilla replacement sequence between levels of LAND_HOLDERs does work. If the token is omitted for landholders, the landholder chain is broken, so replacement is required for the landholder system to work.

[REQUIRES_POPULATION] also does not work for [LAND_HOLDER], when you set [NUMBER] to 1. The position is not created when the required population is reached.

==What doesn't work==

'''Attention: If a position cannot be appointed, for example because of 'mutual appointment', it still exists according to replacement mechanics and will replace other positions if so defined. If a certain position(a) will be replaced by the baron's assistant, which can only be appointed by the [LAND_HOLDER] baron, than that position(s) still will be replaced from the start of the game, even if no baron or their assistant is ever present.'''

A position that is replaced by a somehow non-fillable position is still replaced. This counts for mutual-appointing positions, replacement by not-yet-assigned landholders, replacement by AS_NEEDED positions, or replacement by not-yet-appointed positions.

Replacement does not work if the replaced position is a [LAND_HOLDER], even with civ-positions. In that case, the LAND_HOLDER's position is not replaced. It does not matter if AS_NEEDED is used, or a fixed number, and it also does not matter what type of position the replacer is. So this only works (correctly) with positions that become available by REQUIRES_POPULATION.

={{text anchor|Evaluation of Positions}}=
The game does not continuously check whether positions should become available, elected or be [REPLACE_BY]. This is well-known behavior—for example with the [[mayor]], who does not appear automatically when the required population ([REQUIRES_POPULATION]) is reached. Instead, positions must somehow be evaluated. This applies in several other situations as well

'''Cases that require a trigger:'''
* Election of a newly created position
* Election after the current holder dies
* Automatic assumption of a newly created position (this may take up to a day)
* New citizens (such as migrants) considering available positions
* Premature succession of a newly created position

'''Cases that do not wait for a trigger:'''
* Succession following the death of the previous holder
* Automatic assumption of existing positions that have become vacant

'''Triggers that cause the game to reevaluate noble positions:'''
* Succession of a [SITE]-position due to the death of the current holder
* [[Advanced_entity_position_mechanics#Election_Day|Election Day]]
* Automatic assumption of a [SITE]-position that becomes vacant
* (Re)assigning any site position manually
* Settlement elevation on the LAND_HOLDER track (e.g. gaining a [[Baron]] or [[Count]])

=Gaining a position=
There are several ways a unit can gain a position:
* Appointment: A unit is appointed by another unit or by the player.
* Election: A unit is elected by and among the members of the entity
* Assumption: A position is neither elected or appointed: a random unit just simply 'takes' the position
* Succession: a unit is the valid successor of this position(A), either by its current position(B) or because they are that position(A)-holder's heir.

Available positions will automatically be assigned to a random civ member when a new site/civ is created.

==Who can take a position==

* If so defined, a unit needs to be the right caste and/or class - it does not seem to work with creature types.
* The unit needs to be an adult member of the site or its parent civ's government; that is also CAN_LEARN or INTELLIGENT (SLOW_LEARNER cannot take positions) or otherwise is able to think.

==Appointment==

Positions that have an [APPOINTED_BY:position] token require that position to exist, to be available and appointed. Any position that is APPOINTED_BY can be appointed if the appointer's position is filled in.
For site-positions to be appointed, it is required that the appointer is present at that location.

If the appointing unit is temporarily not present, or if that position is not filled, positions depending on it cannot be appointed. This is the case with [[militia captains]], when the [[militia commander]] is on a [[mission]].

A site position cannot appoint a civ position ''or'' LAND_HOLDER in any way whatsoever.

Civ-level positions can appoint other civ-level positions and site-level positions can appoint other site-level positions.

Contrary to what has been said elsewhere, civ-level nobles also can appoint site-level nobles. They need to be at the site to do so. Landholders can appoint both site-level and civ-level nobles. These systems are therefore not as separate as was assumed.

'''Mutual appointment''' cannot take place. If these are the only requisites of the position, then the positions will never appear or get filled. These unfillable positions can be put to good use, for example, to replace a position that is no longer needed without creating a new one.

'''Self appointment''' doesn't normally work. If you have a position that is only appointed by itself, it is never appointed and also cannot be assumed. However, if the position has a number higher than 1, and is filled by multiple units (for example by another position that is now empty), than those units can re-assign or appoint each other from that their shared position.

If an APPOINTED_BY token refers to a non-existing position's code, the effects are as if the appointment token doesn't exist at all.

===Automatic appointment in world-gen and on the civ level===

Outside of fortress mode, the game will always attempt to appoint nobles whenever possible, as long as these positions are '''available''', even if they are invisible to the player.
It shows this message in legends: "(unit name) has been appointed to the position of (position name)"

In world-gen, all positions become available and are automatically appointed, taking population- and appointment-requirements into consideration.

Positions that are REPLACED_BY are culled and won't be filled.

If a citizen of your fortress holds a civ-level position that can appoint another civ-level position, the appointment will happen automatically and without player intervention. It may happen that another citizen of your fortress is appointed by that unit, creating civ-level position holders in your fortress, but it is unknown what is required to force this effect.

===Manual appointments by players in fortress mode===
In fortress mode, the positions that need to be appointed stay empty on embark. and it is the player's job to appoint those. A player can appoint a unit to any available position, according to the hereabove mentioned conditions. The player takes the role of the automatic appointment-system, but has no direct control over elections, successions and replacement. There are some differences in what is possible at world-gen sites and at player-controlled sites.

* A position that is appointed by a unit present as a fortress citizen, can be appointed, re-appointed or left vacant. This means also by civ-level nobles living as a citizen in your fortress; not when they are only visiting, like the diplomat.
* A position whose appointing positions are all either vacant or [REPLACED_BY] can no longer be appointed. If the position is already filled, it cannot be reappointed or vacated; the current holder simply remains in office.
* A position that is APPOINTED_BY a unit present as the land_holder of your site, can be appointed, reassigned or left vacant.
* A position that has SUCCESSION BY_HEIR or BY_POSITION can 'initially' be appointed and also re-appointed or left vacant, but as soon as the [[nobles]] screen closes, ''it can no longer be replaced or left vacant''. From then on, the succession-rules determine who gains that position when the current holder loses the position. This works even if the SUCCESSION:BY_POSITION-position is vacant or replaced.
* A position that is ELECTED nor APPOINTED_BY, can always be (re-)appointed by the player. This is the case with the [[Expedition leader]]. If it is left vacant however, it cannot be appointed, but will be assumed shortly after.
* A position that is both ELECTED and APPOINTED_BY, cannot be appointed by the player. Contrary to world-gen sites, its slot is visible, but it doesn't show the +-sign. This is either by AS_NEEDED or by a fixed number. Even if the position somehow gets filled (re)assignment is never possible
* A player can appoint a number of units to a position, as much as the NUMBER token dictates. If it is AS_NEEDED, the player may create as many slots as they like, also contrary to world-gen sites.
* A civ-position can never be appointed, even if the appointing civ noble is a citizen of your fortress. A civ position also never can be re-assigned or left vacant, would that position be defined as appointed by a site-position.

==Election==
Read more in [[Elections]]. The message that is shown is: "(creature name) has been elected to the position of (position name)"

In worldgen, there is no functional difference between ELECTED and non-appointment, except that elected nobles tend to have high social skills and/or skills related to the position, while non-elected ones are assigned randomly. See: [[Elections]]

A succession goes before an election.

A position that is both ELECTED and APPOINTED_BY never gets elected. Even if the appointees' position somehow gets filled, (re)-elections won't happen. So, it doesn't seem possible to have an elected position become available when a certain other position becomes filled.

An ELECTED civ-(or LAND_HOLDER) position at your site will never be (re)-elected in fortress mode. So real (re-)election only works with SITE-positions.

=== {{text anchor|Election Day}} ===
Election Day takes place on the 17th of Summer. On this day, a full reevaluation is performed, including all currently elected positions, which are subject to re-election. Contrary to the information on [[Elections]], nothing occurs at the start of a season.

Positions that are both [APPOINTED_BY] and [ELECTED] will not be re-elected on Election Day when assigned through [SUCCESSION].

=== Election Eligiblity ===
Any citizen may stand for election. Eligibility cannot be restricted using [ACCEPTED_CREATURE], [REJECTED_CREATURE], [ACCEPTED_CLASS], [REJECTED_CLASS], or [GENDER]. Units currently having a [SUCCESSION]-position even may be elected for a position with a [SQUAD]-token, which is otherwise impossible to assign or even succeed.

=== Skills ===
In elections, skills are taken into account for the tokens of the position which is elected.
{| class="wikitable"
|+ Relevant skills per position token
|-
! Position Token !! Relevant skills
|-
| Responsibility [[Position_token#DELIVER_MESSAGES|[DELIVER_MESSAGES]]] || [[Ambusher]], [[Observer]] and [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#ACCOUNTING|[ACCOUNTING]]] || [[Record_keeper|Record keeper]]
|-
| Responsibility [[Position_token#ESPIONAGE|[ESPIONAGE]]] || [[Schemer]]
|-
| Responsibility [[Position_token#HEALTH_MANAGEMENT|[HEALTH_MANAGEMENT]]] || [[Diagnostician|Diagnostician]]
|-
| Responsibility [[Position_token#MAKE_INTRODUCTIONS|[MAKE_INTRODUCTIONS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#MAKE_PEACE_AGREEMENTS|[MAKE_PEACE_AGREEMENTS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#MAKE_TOPIC_AGREEMENTS|[MAKE_TOPIC_AGREEMENTS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#MANAGE_PRODUCTION|[MANAGE_PRODUCTION]]] || [[Organizer]]
|-
| Responsibility [[Position_token#MEET_WORKERS|[MEET_WORKERS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#RECEIVE_DIPLOMATS|[RECEIVE_DIPLOMATS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#RELIGION|[RELIGION]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#TAME_EXOTICS|[TAME_EXOTICS]]] || [[Animal_trainer|Animal trainer]]
|-
| Responsibility [[Position_token#TRADE|[TRADE]]] || [[Social_skill|Social skills]] and [[Appraiser|Appraiser]]
|-
| [[Position_token#SQUAD|[SQUAD]]]-token || [[Tactician]] and [[Leader]]
|}

==Assumption==

A position that is not APPOINTED_BY nor ELECTED, or is appointed by positions that are not available in your site or civ, will be assumable by a random dwarf. If it has responsibilities that require certain skills, then these are taken into consideration on embark, but not when the position is assumed during the actual game.

Normally, one to three units will take the into consideration to assume a position. Most of the time when there are multiple open positions, only a single unit will assume all of them. However, a position that has REJECTED_CREATURE, REJECTED_CLASS, ALLOWED_CREATURE or ALLOWED_CLASS will be filled with all different units, even if the creature or class mentioned is irrelevant. It seems that this forces the game to loop over all the available units.

The message that is shown in Legends mode is: "(unit name) has assumed the position of (position name)". This may also take place in fortress mode, which then shows this message to the player.

If an assumable position becomes empty, it will be assumed within a day. This is the case when you leave the position of expedition-leader vacant. It also happens with entities.

Assumable positions that become empty will not be assumed if that position has a valid [SUCCESSION] -successor. In that case, the successor inherits the position.

Even positions that are somehow invisible because they cannot be directly APPOINTED_BY players, can be assumed.

When you embark, the assumable positions are automatically assigned to a random unit. If there are multiple of these positions at embark, they all are assigned to the same unit. If there are enough positions available, multiple units may gain a position, but often no more than three different ones.

If a dwarf in fortress mode assumes a position, that already has another position, it will leave the current position empty. When that position also is assumed, then this will continue until all positions have a dwarf appointed to them, with no other position.

A unit that already has a position with a [SUCCESSION] token won't take assumable positions into consideration that have a [SQUAD] token. This can be used by the modder to prevent unwanted loss of current positions.

A position that has an appointer which got replaced because of REPLACED_BY, will not become assumable. Also, positions that have an AS_NEEDED appointer that is not yet filled (or ever), will also not be assumed.

==Succession==

If a position-holder dies or advances to a new position via succession, the position will be granted to another unit based on the [SUCCESSION] tag. If they have an heir or the succeeding position exists, that unit will be assigned. If not, a new one will be appointed according to the usual rules. The message that is shown is: "(creature name) being the rightful heir, has inherited the position of (position name)"

The succeeding creature will also lose its previous position. When succession is defined using BY_POSITION, the unit naturally loses the referenced position. However, it also loses any other positions it may hold. If a unit could simultaneously inherit multiple positions, the last-defined succession overrides the earlier one, clearing the previously acquired position

Succession works both at site-level and at civ-level, both in world-gen and in fortress-mode. Succession by position on the civ-level is also visible and functional in fortress-mode. If both civ-level nobles are a citizen of your fortress, succession is applied visually. Vanilla example: The [[druid]] is succeeded by the [[acolyte]]. This means that as soon as the druid dies, the acolyte takes over.

When a position that is succeeded by position becomes available, immediately it is checked if a position-successor is available and the position is filled with that unit. Even if this is an [ELECTED] position, succession goes first. When elections eventually do happen, succession plays no role.

It is possible to assign multiple levels of [SUCCESSION:BY_POSITION] in different positions, creating a line of positions where the death of one causes all those "below" them to advance.

A position can have multiple tokens with position-succession. It looks to be random which one is used. It is not always:
* The first or last defined token
* The first or last appointed unit
* the oldest or youngest
* one with a higher or lower precedence
* a unit with relevant skills

When a position is defined with a Succession-type, that unit cannot have another position that has a Squad-type. If the succession-position itself has a squad, than it can be assigned another position with a squad, but then it will loose the previous succesion position. See further details by "Squad"

Assumed positions can also be succeeded by position, if the current holder dies.

If the successor is an AS_NEEDED position, the used unit will leave a vacant position-slot on its removal by succession. This empty slot remains a real slot, which will only be cleaned up if you (un)appoint a unit to this position-series. It isn't cleaned up after regular position validation.

A civ-level position of a unit living at your site might be inherited by a unit holding that does not currently live at your site. This, unfortunately, moves that position to a unit off site. This may also happen with the landholder of your site, for example when it is succeeded by another civ-level position. This currently poses an unsolved challenge.

===Eligibility for succession===
Succession is restricted by the tokens [ACCEPTED_CREATURE], [REJECTED_CREATURE], [ACCEPTED_CLASS], [REJECTED_CLASS] and [GENDER].

===Site and civ combined succession===

Succession can work when combining site positions with civ-level positions or land_holders, but only in world-gen mode. In fortress mode, it only works with combining the same level of nobles, with Landholders regarded as civ-level. So, in fortress mode, a site's position cannot succeed a landholder's position and it cannot succeed another type of civ-level position, and vice versa.

This won't work even if the positions:
* are AS_NEEDED or having a fixed number.
* Are LAND_HOLDERs.

===Succession [BY_HEIR]===

When a heir is needed for succession, all children and then other relatives are validated. They cannot take the position if their status does not allow it, for example if they have become a member of another civilisation. See: "Who can take a position". If the unit has no valid heir on that location, the position may go to a unit living on another site. This may cause the title of Landholder of some land to be inherited by a unit living somewhere else. That might be a problem, because then you lose your landholders.

===Premature Succession===

There are cases where [SUCCESSION:BY_POSITION] is applied prematurely: at the moment a position is first created and becomes appointable or assumable, rather than after a current holder leaves. In this situation, the succession mechanism assigns a holder immediately, without any player interaction.

When a position becomes available for the first time, the game checks whether a valid successor-by-position exists. If so, that unit is assigned instantly. It can affect positions that would normally be appointed or elected by the player, causing succession to trigger before the player has any opportunity to intervene.

This behavior occurs only in Fortress mode, but can be applied both on [SITE]-positions as well in civ-positions. That last one however is a bit harder to control. Example: [[Advanced entity position mechanics#The Archduke|The Archduke]]

This premature succession only occurs the first time a position becomes available (i.e. when it is created and becomes appointable or assumable). Even if the position remains vacant and the conditions for succession improve later, premature succession will not trigger again. From that point onward, only normal succession rules apply.

Using premature succession, a position that has [ELECTED], [APPOINTED_BY], or both, can be filled directly.
Notably, positions that combine [ELECTED] and [APPOINTED_BY] are normally impossible to fill through regular mechanics. Premature succession bypasses both election and appointment entirely, making this combination uniquely reachable through this mechanism.

No initial election takes place, and no subsequent elections will ever occur for that position. Succession always takes precedence over election, both in premature succession and in normal succession cases.

This behavior applies only in Fortress mode, not during world generation. World-gen uses simplified and more efficient mechanics, and this interaction does not occur there. Premature succession can affect both site-level and civilization-level positions.

====Multiple succession chains====

Multiple succession chains may be defined and are resolved in the order they appear in the raws.

If a position has both:
* a direct succession chain (A → C), and
* a multi-step chain (A → B → C),

and intermediate positions are vacant, resolution proceeds according to raw order. A common outcome is:
# The direct succession (A → C) is applied first, assigning A to C.
# The remaining chain then advances (A → B).
# If C still has empty slots, the final step (B → C) may occur.

If position B is already filled, behavior depends entirely on raw definition order:
* nothing may happen, or
* B may move to C first, followed by A moving to B.
====Working triggers====
Premature succession is triggered when a succeedable position is created under the following conditions:
* The succeedable position is created because its [REQUIRES_POPULATION] threshold is reached. This applies even if the position is not [APPOINTED_BY]. Premature succession takes priority over automatic assumption (e.g. the mayor declaring themselves within a day).
* The succeedable position can be [APPOINTED_BY] another position of the same level (site or civ) that has just been created because its [REQUIRES_POPULATION] was reached.
* The succeedable position can be appointed by another [SITE] [AS_NEEDED] position that has just been created and filled.
* The succeedable (site or civ) position is [APPOINTED_BY] the [LAND_HOLDER] position, which has just been created due to site elevation. This typically resolves when the diplomat leaves the map, at which point the landholder position becomes active.
* If all other requirements are met, premature succession can occur immediately after unpausing following embark, for positions with [REQUIRES_POPULATION:7].
====Non-working triggers====
Premature succession does '''not''' occur in the following cases:
* An [AS_NEEDED] succeedable position slot is manually created by the player while its succeeding position is already filled. [AS_NEEDED] positions must always be appointed after creation.
* The succeeding position is filled after the succeedable position becomes available. The moment of creation is the decisive trigger; filling the source position later is too late.
* The succeedable position can be appointed by another site or civ position with a fixed number of slots that has just been appointed. In this case, the succeedable position is just available for appointment itself, nothing more
* Any situation occurring during world generation.
* The succeeding position is [REPLACED_BY] the succeedable position. In this case, replacement removes the unit from the source position first, leaving no holder available for the succession mechanism to use.rst, leaving no holder available for the succession mechanism to use.
* The position is [APPOINTED_BY] a civ-level position, that just became a citizen of your fortress. It must be noted that those civ-level positions were active all that time and the succeedable position could be appointed even before. The monarchs arrival does not trigger premature succession

=Losing a position=

A unit can lose a position when:
* It dies
* It succeeds another position, even if it has nothing to do with the previous position.
* It is assigned to another SQUAD-holding position
* It is convicted of a crime.
* Another unit is ELECTED for the position
* Its position becomes replaced
* Another unit is appointed by the player, or the position is left vacant.
* It has assumed another position, as this always leaves the previous position vacant.

=Embarkment=
Two types of positions are automatically filled by embark.
* Positions without [APPOINTED_BY] or [ELECTED] (assumable). All these positions, even with a NUMBER higher than 1, are all filled with one to three dwarves. Contrary to assumption, this doesn't take into account any limitations. REJECTED_CLASS, ALLOWED_CLASS, REJECTED_CREATURE, ALLOWED_CREATURE and GENDER are applied, but without the normal spread you may expect with assumptions. Also it doesn't look at [SUCCESSION] and [SQUAD] limitations.
* Positions that are elected are filled-in by the normal election rules.

Positions that have a defined appointer are never initially filled at embark.

All positions that don't have [REQUIRES_POPULATION] or with a [REQUIRES_POPULATION] of 7 or lower, will be available at embark.

=Land Holders=

A Landholder is a '''special civ-level noble''' who gets a certain piece of land to hold, when that land is elevated to a certain level, determined by the tag [LAND_HOLDER] and by the landholder triggers in the game's settings. In vanilla, these are the baron, the count and the duke.

A unit gaining the landholder position does not migrate to that specific named land. In world-gen, they stay just where they are, probably at the capital. In fortress mode, you can suggest a citizen for the role. So for the time being that works.

Succession is then a real issue. If you use BY_HEIR, its solved when that landholder has children living at your site. But when its not the case, the title just goes to anyone randomly. Succession BY_POSITION works, but only in the civ-chain, and there's no way to guarantee a civ-holder is at your site at that time. Even with 'automatic spread' positions, it goes to one of them randomly.

==Functioning of the regular landholder chain==

The distinct difference between a landholder and a regular civ-level noble, is that a landholder may gain the position of landholder "of (sitename)" They are then seen as ruler of a particular site.

For a land_holder position to function as such, it has a few requirements:
* NUMBER:AS_NEEDED
* The first landholder-number of 1 is defined.
* No SITE (so civ) tag in that position.
*REPLACED_BY the next level landholder
If a landholder is defined with differentiating properties, it will function like a regular noble. A higher-up landholder that lacks the required tokens or connections will then not be used in elevation.

If a fortress meets the trigger for a new LAND_HOLDER tier when a caravan leaves, then the next time the outpost liaison or equivalent arrives, they will offer to make you an official colony, which will allow you to select all positions for that LAND_HOLDER level. Each time they appear, the outpost liaison will only promote your fortress one tier up the LAND_HOLDER track.

The landholder's LAND_NAME is not required for the functioning of this system. If omitted, messages will be shown with a more generic text.

==Appointment==

This mechanism differs from the regular methods of position management. It ignores all regular appointment- and election rules, so it more or less functions like automatic assignment. A landholder is, in vanilla, appointed by the monarch. Changing this doesn't seem to do anything. If they are appointed by a site-position, a not-yet-existing civ-position, or not appointed at all: the system keeps working as usual.

A landholder can appoint civ-positions and site positions. This works as expected: the positions only are appointed then when that landholder becomes available on civ-level or when he arrives at that site for site-level positions.

If your rank of landholder is the first of its rank in the realm, and is the sole appointer of some civ-position, then immediately as it gains the title, it will appoint the empty civ-slots. This may happen on your site, but the frequency and certainty is hard to determine.

==Succession==

Succession rules are applied to some extent:
* In world-gen it works according to succession rules, and site-positions can be used here. This means that a site position or a civ-position can inherit a landholder position, and vice versa.
* In fortress mode, once a landholder has been appointed, it then can inherit civ-level positions, and vice versa. This means that your baron can become king.
* Succession rules do not apply within the [LAND_HOLDER] chain; a count will not inherit a baron's land. This is because succession does not work well with the AS_NEEDED token.
* Premature succession works in fortress mode with landholders. If a unit gets a landholder's position and that landholder is the appointer of an as yet empty position, which is defined as succeeding from a third one, then the succession is immediately applied. The landholder themselves can even be the successor of a newly created position.
* A landholder's position is, in fortress mode, not successionable by a site-position or vice versa

===Impossibilities for succession by a site-position===
It would be very beneficial if the landholder can be succeeded by a [SITE]-position. So far, the following tests have not lead to positive results:
* making landholder and site-position both non-[DUTY_BOUND]
* make the site-position be [APPOINTED_BY] the landholder and/or the monarch
* give landholder and site-position [REJECTED_CREATURE]
* Let the monarch live at your site when succession could happen.
* Let the site-position be [REPLACED_BY] the landholder.

==Nomination==

The player is able to nominate a unit to become the LAND_HOLDER, but this only works with units of [LAND_HOLDER] level 1. The player can select all units, only limited by the PRECEDENCE of the current units' positions.

A unit that has a position with a PRECEDENCE lower or equal to that of the landholder's position, cannot be selected. This means that a baron (or count) from another site or the monarch cannot be selected, because their precedence is lower or equal.

The GENDER token does not work here: also units with the wrong gender (sorry) can be selected.

==Levels==
In mods, up to 10 levels of LAND_HOLDER may be defined.

If a landholder is replaced by a wrong landholder number (1 replaced by 3), then the number 3 is still correctly attached to the settlement.

If the current landholder has the highest available landholder number, then the next elevation will not happen - the diplomat will not elevate your fortress to a higher position, even if that position might be REPLACED_BY a lower landholder.

These chains do work:
* 1 -> 2a - > 2b -> 3
* 1 -> 3 -> 2 -> 4

These chains do not work:
* 2 -> 3 (need to start at 1)
* 1 -> 4 -> 2 -> 3 (stops after 4 as the highest)
* 1a -> 2, 1b -> 2 (only 1a and 2 work, 1b is not used)

==Moving landholders==

It may happen that a land-holder no longer lives at the site which they are the landholder of, specifically when the current landholder dies, leaving the title to an heir living somewhere else.

To prevent this from happening, you can make their succession from heir and make sure that their kids live at your site. Or, you can make their position succeeded by another civ position, and make it so that this civ position is somehow available on your site. But if multiple of these positions exist, it cannot be guaranteed that a citizen of your fortress will inherit the title.

In world gen, a landholder lacking the DUTY_BOUND-token will also move to the site they like, according to legends mode.

==Replacement by a generic civ-position==

If a landholder is replaced by an AS_NEEDED non-landholder civ-position, then this will work: the current landholder loses that title upon settlement-elevation and gains that civ-title. However, the civ-title lacks the landholder-property of being attached to the land. It will not show the name of the settlement alongside the position's name. So no "minister of Shovelmounts"

If a landholder is replaced by a general AS_NEEDED civ-position, that itself is also replaced by a generic AS_NEEDED civ-position, then firstly the elevation is executed and also the unit gains that new position. However, he immediately loses it, because an AS_NEEDED position that is replaced by another position can be filled initially, but units wont be able to hold that title.

==Landholder with fixed number==

A landholder's position that has a fixed number will be created and filled directly when the civilisation is born, so this position slot is then not available for the regular landholder-mechanic and will also not be used. That landholder will thus not be attached to a settlement.

It doesn't matter if the landholder's position is connected to the regular landholder's-chain with the REPLACE_BY token.

==Responsibilities==

When given a certain [RESPONSIBILITY], a landholder may function as a regular civ-level noble. If the position has [TRADE] or [OUTPOST_NEGOTIATING] responsibilities, then the landholder functions both as a diplomat and as an actual land holder. A landholder with the [MILITARY_STRATEGY] responsibility will travel around taming creatures in world-gen, according to legends mode.

Besides that, the responsibilities work the same as with any other on-site living position-holder, civ or otherwise.

=Military=
==Squad management==
In the vanilla game, the Squad interface only becomes available after a militia commander has been appointed. Until then, the window displays:{{DFtext|You must appoint somebody first to create a squad.}}

What’s surprising is how this is determined internally. In the entity raw definition, '''only the last two positions that include a [SQUAD] token are checked''' to decide whether the interface is accessible at all. As a result, if your hierarchy defines commanders A through E, appointing '''Commander D or E''' unlocks squad formation, while appointing A–C does nothing.

In other words, squad availability is not tied to ''having a militia commander'', but to ''which specific positions happen to be last in the raw list''—a notably hacky implementation.

These 'last two' are always the last two '''available positions.''' So if they get [REPLACED_BY] or become available because of [REQUIRES_POPULATION], the game adapts to those.

==Squad assignment==

Squads can be assigned, even if the leader position has no holder.

A specific unit can only have one position associated with a squad. If it gains another 'squad holding position', it is unassigned from the first one. This does not work with a 0-squad, so only 1+squads are taken into consideration. This technique can possibly be used to distribute all positions equally among all citizens. It does however not work with election and assumption.

If a civ-level position is associated with a squad and it gets a site-level squad-holding position assigned, it loses the current civ-position.

Squads can get really messed up, if you make the position (or multiple) either elected or not-elected and not-appointed, then this can cause the game to assign multiple squads to the same unit. Automatic assignment and election does not take squads into account, but the nobles screen does. This can cause the positions to be cleared as the game figures out that they have more than one position, and immediately get elected or assumed again.

Positions that cannot have a squad-position:
* A site- or civ-position with a [SUCCESSION] token cannot be appointed a squad-holding-position. The other way around, however, does work. For example, if a site-position with a [SUCCESSION]-token is appointed to a unit that has already a position with [SQUAD]. But when that squad position is assigned to another unit, it cannot be assigned back.
* A position with [SUCCESSION] can also not be assigned as a '''member''' of a squad.
* A squad-holding position with a formed squad cannot be appointed to another squad holding position.

If a position has at least one squad member, it cannot be left vacant. First, the squad has to be disbanded, then the position may be cleared.

==0-squads==
A 0-Squad is defined in a position as [SQUAD:0:member:members]. It does not seem to do anything useful as of now.
* It cannot be used to activate the [[Squad|military interface]]
* It does not restrict the assignment of [SUCCESSION] positions.
* Assigning this position does not clear any previously held squad position.
* The [[Leader]] and [[Tactician]] skill are not marked as relevant skills and are not taken into account in elections.
* It cannot be formed as a squad.

=Further testing=
The following questions may need additional testing. Feel free to add or answer
* Everything regarding COMMANDING and army-structure
** [http://www.bay12forums.com/smf/index.php?topic=175437.msg8331668#msg8331668]
** [http://www.bay12forums.com/smf/index.php?topic=165213.msg8335682#msg8335682]
** [http://www.bay12forums.com/smf/index.php?topic=174584.msg8026854#msg8026854]
* Everything regarding CONQUERED_SITE, but it is presumably just like site. But what if you combine SITE or LAND_HOLDER with it?
* Stuff about the monarch, its arrival and its entourage.

=Oddities (Bugs)=
Almost everything on this page could be called an oddity. Because of their unexpected usability, some may also be referred to as “undocumented features.” Others, however, are simply odd and not particularly useful, yet I hesitate to call them “bugs.”
* If a certain threshold is reached that makes an elected position electable, and the triggering event that initiates this evaluation is an assumption, then the resulting assumption is also referred to in the messages as an election

=Examples=

===The Founder===
The founder is a single dwarf, appointed at embark. They will be the only one ever to have this position and are not replaceable. When they lose their position some way, the position will not be assumed by another dwarf.
{{gamedata|title=The Founder|
[POSITION:THE_FOUNDER]
[NAME:the founder:founders]
[NUMBER:1]
[SITE]
[ALLOWED_CREATURE:DWARF:ALL] - will only be filled at embark, but not assumable later.
[REJECTED_CREATURE:DWARF:ALL] - will only be filled at embark, but not assumable later.
[SUCCESSION:BY_POSITION:THE_FOUNDER] - not unassignable, also cannot be assigned to a [SQUAD] position.
[PRECEDENCE:200]
Non APPOINTED_BY
Non ELECTED
Optional: Add responsibilities to make the game select a unit with certain skills.
}}
===Marriage bar===
Dwarven matrons are held in great honour. Upon marriage, a female dwarf is no longer expected to perform menial labour. All dwarven males hold this position by default, granting their spouses exemption from menial work.

The position becomes available with the arrival of the first migrants; otherwise, on embark, it would be assumed by females. Its succession rule is non-functional, but this prevents the player from unassigning the position. A squad size of 1 and the succession rules together prevent a unit from assuming the position more than once.

With precedence set to NONE, the position name is hidden, while LAND_NAME remains visible on the nobles screen. All married females receive the suffix “, Mrs.” and are marked as Nobles.

The practical usefulness of this position is debatable, but it serves as a clear demonstration of several mechanics.
{{gamedata|title=Mrs. Urist|

[POSITION:MRS_URIST]
[NUMBER:300]
[SITE]
[ALLOWED_CREATURE:DWARF:MALE]
Not APPOINTED_BY
Not ELECTED
[LAND_NAME:Dwarven male]
[NAME:dwarven male:dwarven male]
[PRECEDENCE:NONE]
[SPOUSE_FEMALE:, Mrs.:spouses]
[MENIAL_WORK_EXEMPTION_SPOUSE]
[REQUIRES_POPULATION:8]
[SUCCESSION:BY_POSITION:MONARCH]
[SQUAD:1:member:members]
}}
===The Archduke===
The archduke is the leader of the civilization, but exists only from landholder 4-level. Until then, its position remains vacant. When a settlement is elevated to tier 4 (grand duke), the grand duke can appoint the ruler of the civilisation, the archduke. Because of 'Premature Succession', they themself inherit that position immediately, but only when in fortress mode. Its heir then becomes grand duke.
{{gamedata|title=The Archduke| no POSITION:MONARCH or other PRECEDENCE:1

[POSITION:THE_ARCHDUKE]
[NAME:archduke:archdukes]
[NAME_MALE:archduke:archdukes]
[NAME_FEMALE:archduchess:archduchesses]
[LAND_NAME:a archduchy]
[NUMBER:1]
[PRECEDENCE:1]
[SUCCESSION:BY_POSITION:GRAND_DUKE]
[APPOINTED_BY:GRAND_DUKE]
(add additional monarch-stuff, like spouse name, demands etc.)

[POSITION:GRAND_DUKE]
[NAME:grand duke:grand dukes]
[NAME_MALE:grand duke:grand dukes]
[NAME_FEMALE:grand duchess:grand duchesses]
[NUMBER:AS_NEEDED]
[LAND_HOLDER:4]
// Optional ...
[PRECEDENCE:19]
[LAND_NAME:a archduchy]
[RESPONSIBILITY:LAW_MAKING]
[RESPONSIBILITY:RECEIVE_DIPLOMATS]
[SUCCESSION:BY_HEIR]
[APPOINTED_BY:THE_ARCHDUKE]
(add additional landholder-stuff)

!!add to [POSITION:DUKE]
[REPLACED_BY:GRAND_DUKE]

}}
{{Category|Modding}}
{{Category|Entities}}
{{Category|Guides}}

Advanced entity position mechanics

2026-02-12T08:29:50Z

Joostheger: /* Table of interaction between different position levels */

{{Quality|Fine}}
{{Modding}}

= Introduction =

[http://www.bay12forums.com/smf/index.php?topic=182239.0 Discussion thread on the forum]

This page documents observed and tested behavior of entity positions in Dwarf Fortress that is not fully described elsewhere on the wiki. It focuses on advanced interactions between position tokens, including appointment, succession, election, and responsibility handling, across both civilization-level and site-level entities.

The mechanics described here are based on empirical testing in world generation and fortress mode, supplemented where necessary by raw analysis. In several cases, the game’s behavior is determined by evaluation order and interaction between multiple tags, rather than by individual tokens in isolation.

This page is intended for modders and advanced players who are designing or debugging custom entity position structures. It does not restate basic position mechanics, but instead highlights edge cases, non-obvious interactions, and behaviors that may appear inconsistent or undocumented.

Unless stated otherwise, the described behavior applies to current versions of the game and may differ from older releases.

==What is an entity? What is a position?==
An [[entity]] is an organizational structure that can have relationships with other entities, usually known as a [[civilization]] or a "[[site]] government" in the game, but merchant [[guild]]s, religious organizations, necromancer towers, and [[bandit]] groups are also entities. An entity can have positions - in most cases, these are hardcoded and generated by the game, but as for civilizations and sites, the [[raw file]]s can be customised.

A position is a special relationship between a unit and an entity. The unit holding a position has a larger influence over that entity than other citizens. Positions are mostly known as [[nobles]], but in this article. the technical term is used.

=Position levels (Site/Civ) and their interaction=
There are two basic types of positions that are customizable: '''civ(ilization)''' level and '''site level'''. Positions with the tag [SITE] are at site level, positions without the tag [SITE] are at 'civ level'. These two types of nobles can be considered '''loosely related systems'''. There are a few places where they can interact with each other.

Civ-level positions are in charge of the civilization as a whole, managing national [[trade]], laws, and [[war]]s. These are, for example, the vanilla [[monarch]], [[diplomat]] and [[general]]. (Note that the general doesn't do anything in either mode in the current version.)

'''[LAND_HOLDER]''' nobles are also positions at civ-level. These units are members of the national government, but have gained authority over some land or site. Once they do, they move to that place, but their position is still regarded as a civ-level position.

Site-level position holders are members of a site government (subsidiary to the civilization), and manage local affairs in that location. These are, for example, the [[mayor]], the [[sheriff]] and the [[broker]].

==Table of interaction between different position levels==
In this table, the possible interactions between different position levels are summarized.
The header row shows the positions defining the tokens.

The left column shows the position type that is referred to.
Example:
{| {{prettytable}}
|- bgcolor="#ddd"
! referred position-type
! LAND_HOLDER
|-
| civilization
| (baron is) APPOINTED_BY:MONARCH
|}
color coding: 
* Exists in vanilla
* Possible with mods
* Not possible
* possible to some extent.
* not yet fully investigated.
{| {{prettytable}}
|- bgcolor="#ddd"
! referred position-type
! Civilization
! SITE
! LAND_HOLDER
! CONQUERED_SITE

|-
| Civilization
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION '''(1)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION

|-
| SITE
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION '''(2)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY '''(3)''' COMMANDER REPLACED_BY SUCCESSION '''(4)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION

|-
| LAND_HOLDER
| APPOINTED_BY COMMANDER REPLACED_BY '''(6)''' SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION '''(5)'''
| APPOINTED_BY COMMANDER REPLACED_BY '''(7)''' SUCCESSION '''(8)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION

|-
| CONQUERED_SITE
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
|}

Remarks:
# Works only in world-gen, if a unit with that civ-position is present at the site.
# Works only in world-gen, the site-position holding unit will then move to the capital.
# Is completely ignored
# Works only in world-gen.
# Works only in world-gen.
# Won't appear at all
# This is necessary for the landholder chain to work properly, it doesn’t work otherwise.
# This works only outside of the landholder chain, so when landholders are simply regarded as civ-level nobles. might also work in world-gen
#

== Other interactions ==

Unfortunately, interactions with positions of other entities don't seem possible, such as APPOINTED_BY: HIGH_PRIEST. With [VARIABLE_POSITIONS], positions are automatically created with codes like CUSTOM_LAW_MAKER_2, but interaction with these positions don't seem to work, either. For more info on those, see [[Variable positions]]

=General=

==Civ-level nobles living at your site==
Nobles from your civilization can come to live at your fortress. This happens in vanilla with landholders such as [[Baron]], [[Count]] and [[Duke]], with the Monarch, but sometimes also with non-landed LAND_HOLDERS.

When a civ-level noble becomes a [[citizen]] at your location, their position is shown among the site-level positions in your [[nobles screen]]. They appear to function as a site-level noble. They may have [[demand]]s, [[mandate]]s, [[squad]]s and the like. They can appoint nobles at the site-level.

If they have certain [RESPONSIBILITY]ies, they do the tasks that go with them.

==Fortress mode, world-gen and their differences==
Their are a few differences in how positions function between fortress mode (normal play mode) and the world generation (world-gen).

In '''fortress mode''', the player has some control over the appointment of nobles, limited by elections, automatic filled-in positions and succession rules. Pre-fortress mode, which is referred to as '''world-gen''', the game will always attempt to assign nobles whenever possible. It is subjected to the same rules as in fortress-mode, but there are some exceptions. In '''[[World activities]]''', which is the thing that happens in the world while you play fortress mode, it seems as if the same rules are applied as fortress mode.

A difference between player-fortress-mode and world-gen, is causes by visibility (see below). Positions that are not visible by the player and thus not available for assignment, will be available in world-gen and will thus be automatically assigned.

In fortress mode, a position that is both [ELECTED] and [APPOINTED_BY], cannot be appointed by the player and is also not elected, and can thus not be filled. But in world-gen sites however, these positions are automatically filled.

Positions with [AS_NEEDED] are almost never created and filled in world-gen (depending on their [RESPONSIBILITY]ies), but can always be used in player mode.

A position can, in fortress mode, be filled by the same unit. A unit can gain multiple positions in fortress mode, for example because of [[elections]]. This will not happen in world-gen mode: a unit can only have one position. See also remarks on 'embark' and 'Losing a position'.

In world-gen, [SUCCESSION] between civ-levels and [SITE-]levels may happen. This will not happen in fortress mode, or even off-site in [[World activities]].

In fortress mode, premature SUCCESSION may happen. This will not happen in world-gen mode.

==Units holding multiple positions in multiple entities==
A unit can hold multiple positions in its civilisation or in its site-entity, however this does not happen in world-gen. Only at player-managed sites can units be holding multiple positions at once. (It is probably not possible for a unit to hold a position in two different civilisations or two different sites.)

In world-gen, if there are too many positions to be filled, they simply stay empty until more units are available. E.G, a unit at a site might inherit a civ-level position and still remain a member of the local government. When this happens however, they move to the capital. If a unit gains a new position, either inherited or otherwise, it drops the previous one. If a unit assumes a civ-position in fortress mode, it leaves the current position.

If a unit holds the same (site-)position multiple times, it has no additional effect.

If a unit holds multiple different positions of the same entity, it has all those positions' responsibilities and properties, stacked up. Presumably, the demands for those combined positions are determined by the highest.

A unit holding a position with a succession token can be assigned another position with a (different) succession token.

A unit holding a position with a squad-position cannot hold another squad-position. It is dropped from the first, when it gets its second assigned.
A unit holding a position with a succession token cannot be assigned to a squad-position - the unit is simply not available. It works the other way around, though.

=[PRECEDENCE]=
The first defined position with precedence of 1 counts as the ruler of the civ. See also: [[Position_token#PRECEDENCE|PRECEDENCE]].

If the precedence is omitted or has a negative value, the game sets 0 as precedence, which seems to have no effect whatsoever.

When a unit has multiple positions, the name of the position with the highest rank in precedence is shown behind the unit's name.

If you omit precedence entirely, or set it to [PRECEDENCE:NONE], the position name will not be shown after the unit’s name. Your *Urist Mason* will remain simply *Mason*. This can be useful for positions that are unimportant or purely functional. The position will also not appear in the civilisation overview of your site on the world map. The position name is shown in messages, but remains hidden on the nobles screen as well. To make it visible there, use [LAND_NAME].

=[RESPONSIBILITY]ies=
Both civ and [SITE] positions can carry responsibilities. However, not all responsibilities are active for both types: some function only for civ positions, others only for site positions. When a civ noble arrives at a site and takes up residence, they do not perform responsibilities that are intended for SITE nobles. As a result, these responsibilities neither trigger their associated tasks nor unlock related game mechanics. For example, a civ-level manager living in a fortress will not perform management duties there and doesn't unlock the management-screen, even with an assigned office.
This behavior applies to the following [SITE]-level responsibilities:
* [RESPONSIBILITY:ACCOUNTING]
* [RESPONSIBILITY:BUILD_MORALE]
* [RESPONSIBILITY:HEALTH_MANAGEMENT]
* [RESPONSIBILITY:LAW_ENFORCEMENT]
* [RESPONSIBILITY:MANAGE_PRODUCTION]
* [RESPONSIBILITY:MEET_WORKERS]
* [RESPONSIBILITY:TRADE] (functions differently)
Other responsibilities may be affected as well, but have not yet been fully tested.

==[DELIVERS_MESSAGES]==
The only [AS_NEEDED]-position that is created in worldgen based on responsibility is that of the site-level responsibility [DELIVERS_MESSAGES].

==Outpost Liaisons and Diplomats==
Civ-positions with the responsibility [ESTABLISH_COLONY_TRADE_AGREEMENTS] ([[Outpost_Liaison|Outpost Liaison]]s) will meet with the site-noble who has responsibility for [RECEIVE_DIPLOMATS] and the highest rank of precedence (i.e. the lowest precedence value). Usually this is the [[Expedition_leader|Expedition leader]].

Once a [LAND_HOLDER] is assigned to the site, civ-positions with the responsibility [MAKE_TOPIC_AGREEMENTS] ([[Diplomat]]s) will meet with '''civ'''-level nobles present at the site who have the [RECEIVE_DIPLOMATS] responsibility. If multiple eligible nobles are available, one is selected at random. If no eligible noble is present, the diplomat leaves angrily. If the landholder is no longer present at the site, diplomats will not arrive at all.

It appears that Outpost Liaisons and Diplomats are chosen for a diplomatic mission based on availability. When multiple candidates exist, the position defined last in the raws is most often selected.

==[TRADE]==
Civ-level nobles with [TRADE] will arrive with the caravan, just as the Outpost Liaison. Their behavior is no longer active in the vanilla game, but the mechanics are still present. See [[40d:Guild_representative|Guild representative]] for more details. This civ-noble will only meet with the SITE noble with [TRADE], usually the [[Broker]].

If two civ-nobles exist with both [TRADE] and [ESTABLISH_COLONY_TRADE_AGREEMENTS], they both arrive at the same time. Even if both tokens are assigned to a single position, if more than one instance of that position exists, two of them will arrive. However in that case, somehow the elevation of the site and appointment of landholder isn't offered.

If the SITE-noble they intend to meet has both [TRADE] and [RECEIVE_DIPLOMATS], only one meeting will proceed and the other is cancelled. However, when two SITE-nobles are available, each with either [TRADE] or [RECEIVE_DIPLOMATS], both meetings will proceed and both civ-nobles will attempt to negotiate a trade agreement. It is not known what happens if these agreements are accepted or refused.

In the trade depot, the last defined position with the [TRADE] responsibility is shown as broker. However when requesting a trader, the first defined position with [TRADE] will actually go there to do the trade.

==World-gen effects of the [RESPONSIBILITY] of available positions ==
It is possible to cause civs and individual sites to change their behavior substantially when they reach a certain size, by controlling nobles.
* If a site can only appoint a position with [MILITARY_GOALS] after reaching a particular size, that site will not send armies on missions until the required size is reached.
* A civ-level [LAW_MAKING] position is required for the civilization to have any kind of cohesion. Without it, sites will be constantly embroiled in territorial disputes and civil wars will be commonplace.
* [MILITARY_STRATEGY] positions go out and tame wild animals. This makes your civ gain those animals as domesticated and also brings them in sieges.
* The [[Personality_facet|Personality]] of the position's holder determines how they lead the civ.

=Availability and visibility=
==Availability of (new) positions==
Warning: Do not mistake "availability" for "visibility"!

Of all the possible positions existing in your site's entity, there may only be some available.
* Positions with [REQUIRES_POPULATION] require the population to have a specific size.
* Positions with [REQUIRES_MARKET] will only appear in "large" sites (which may have different rules for different site types). This tag has no effect in fort mode.
* Positions that are appointed by positions that have an AS_NEEDED number. The appointable positions only become available after an appointer position-slot is created. This works also on civ-level. If a position is appointed by a Land-holder, it only becomes available, when that level of landholder is created.

Only the replaced positions are culled and are no longer available.
A position that requires a certain population will become available, even if it doesn't have [APPOINTED_BY] or [ELECTED]. In that case, see 'automatic assignment' and 'assumption'

In fortress mode, in some cases 'succession' is evaluated immediately after a position becomes available. See: Succession.
==Visibility of positions==
A position might be available, but can still be invisible for the player in the [[nobles screen]]. The positions with their respective holders are visible for players:
* All site-positions that are already filled-in (even if they could not be re-filled-in considering current conditions)
* Site positions that are appointable by a filled-in site position
* Site positions that are appointable by a filled-in civ position, when that civ positions holder becomes a citizen of your fortress.
* Civ positions of units that are also a citizen of your fortress.
If a position becomes available, for example because a certain pop number has been reached, or if it is available from the start(like expedition leader), as long as it cannot be appointed, it still is INVISIBLE for the player.

It might strike someone as odd if a position becomes filled automatically in fortress mode when that position is not even visible. This might be the case if the current holder of a non-appointable position dies or succeeds another position. Regardless of player visibility, these positions will be automatically filled in if the necessary requisitions are met. It might happen with the expedition leader.

A situation with a non-visible but available position, is for example when a position is solely appointed by the expedition leader, when the expedition leader's position is left vacant. It can no longer be appointed by the player and is invisible. Then, it gets automatically assumed, proving that the position still was available.

A position that is both [APPOINTED_BY] and [ELECTED] is visible, but players cannot interact with it.

=[NUMBER]=
A position might be defined with a number. In that case, as many as defined can be available. If the positions become available, in world-gen and when embarking, they are all filled-in completely.

If the ruling position (with PRECEDENCE of 1) has a NUMBER higher than 1, a random unit of the ones holding these positions is shown as ruler in the embark screen.

A [NUMBER] of 0 (zero) has the same effect as 1.

==Automatic spreading of assumed, non-singular positions==
If there are civ positions that have a NUMBER higher then '1' and which are assumed (not APPOINTED_BY or ELECTED) but are '''not DUTY_BOUND''', these are automatically spread among the civilisation, based on population. If there are a number of '''20''' available slots of that position, they spread among a civilization with a combined population of, for example, 1000 of which your fortress has 100 (10%), '''2''' of your fortress' citizens will assume that position.
This may probably also work with elected and appointed positions, but that may be depending on the death of the current holders and this needs more testing. Assumption works within a day, anyway.

==[AS_NEEDED]==
These positions can be created automatically by the game in world-gen. This, however, only works with:
* [LAND_HOLDER]'s
* squad commanders (needs more testing)
* Messengers at sites

For all other types of positions, they're not created in world-gen, even if they are defined with RESPONSIBILITY's. For example, even in war, the game wouldn't create a MILITARY_GOALS position, if they have AS_NEEDED as number.

However, in fortress mode / player mode, these positions can be created by the player at will.

Positions with AS_NEEDED need to be created first, before any symbols are assignable as 'symbols' (objects) for the position holder to carry or wear.

Positions with AS_NEEDED cannot be created and then ELECTED in fortress mode. It only works with APPOINTED_BY.

=Replacement and Required Population=

The token REPLACED_BY:position means that once the replacing position reaches its required population-number, the 'to-be-replaced' position will disappear. This is defined in REQUIRES_POPULATION. These tags are closely related to each other and seem to only have a meaningful function if combined. Nobles with REQUIRES_POPULATION require the population to have a specific size.

This works on the civ-level as well as on site-level, but those systems are in this mechanic strictly separated. Site-level positions cannot be replaced by civ-level positions and visa versa. This makes sense, because they both depend on their own population-count. When using REQUIRES_POPULATION on civ-level, it counts the total population of the civilisation.

See also: [[Advanced_entity_position_mechanics#Evaluation_of_Positions|Evaluation of positions]]

==Effect of replacement (and on [LAND_HOLDER]s)==

Replacement is immediate and complete - the current holding unit loses the position, even before SUCCESSION_BY_POSITION rules are applied. A position with a number of 1 will replace all the slots of a position with a higher number of slots.

Even if the next position is available but not visible, replacement still takes place. If a position is replaced, it is completely gone - it cannot be appointed, succeeded, elected or assumed any longer.
The unit immediately loses its position.

In legends, replacement is mentioned as: "(unit name) ceased to be (position name)" The replacement of an AS_NEEDED position empties the position's slot forever. In fortress mode, it may seem as if you can create new slots and appoint new units in the nobles screen, but this is reversed as soon as you close the window.

The landholder chain uses [REPLACED_BY] differently. It does not clear the position completely, but uses it for succession to the next level's position. [REPLACE_BY] is required to let that system work properly. This also means that the way in which landholders succeed (replace + as_needed) does not work in any other way.

Replacement between LAND_HOLDERS and other site- or civ positions does not work in any way. Only the vanilla replacement sequence between levels of LAND_HOLDERs does work. If the token is omitted for landholders, the landholder chain is broken, so replacement is required for the landholder system to work.

[REQUIRES_POPULATION] also does not work for [LAND_HOLDER], when you set [NUMBER] to 1. The position is not created when the required population is reached.

==What doesn't work==

'''Attention: If a position cannot be appointed, for example because of 'mutual appointment', it still exists according to replacement mechanics and will replace other positions if so defined. If a certain position(a) will be replaced by the baron's assistant, which can only be appointed by the [LAND_HOLDER] baron, than that position(s) still will be replaced from the start of the game, even if no baron or their assistant is ever present.'''

A position that is replaced by a somehow non-fillable position is still replaced. This counts for mutual-appointing positions, replacement by not-yet-assigned landholders, replacement by AS_NEEDED positions, or replacement by not-yet-appointed positions.

Replacement does not work if the replaced position is a [LAND_HOLDER], even with civ-positions. In that case, the LAND_HOLDER's position is not replaced. It does not matter if AS_NEEDED is used, or a fixed number, and it also does not matter what type of position the replacer is. So this only works (correctly) with positions that become available by REQUIRES_POPULATION.

={{text anchor|Evaluation of Positions}}=
The game does not continuously check whether positions should become available, elected or be [REPLACE_BY]. This is well-known behavior—for example with the [[mayor]], who does not appear automatically when the required population ([REQUIRES_POPULATION]) is reached. Instead, positions must somehow be evaluated. This applies in several other situations as well

'''Cases that require a trigger:'''
* Election of a newly created position
* Election after the current holder dies
* Automatic assumption of a newly created position (this may take up to a day)
* New citizens (such as migrants) considering available positions
* Premature succession of a newly created position

'''Cases that do not wait for a trigger:'''
* Succession following the death of the previous holder
* Automatic assumption of existing positions that have become vacant

'''Triggers that cause the game to reevaluate noble positions:'''
* Succession of a [SITE]-position due to the death of the current holder
* [[Advanced_entity_position_mechanics#Election_Day|Election Day]]
* Automatic assumption of a [SITE]-position that becomes vacant
* (Re)assigning any site position manually
* Settlement elevation on the LAND_HOLDER track (e.g. gaining a [[Baron]] or [[Count]])

=Gaining a position=
There are several ways a unit can gain a position:
* Appointment: A unit is appointed by another unit or by the player.
* Election: A unit is elected by and among the members of the entity
* Assumption: A position is neither elected or appointed: a random unit just simply 'takes' the position
* Succession: a unit is the valid successor of this position(A), either by its current position(B) or because they are that position(A)-holder's heir.

Available positions will automatically be assigned to a random civ member when a new site/civ is created.

==Who can take a position==

* If so defined, a unit needs to be the right caste and/or class - it does not seem to work with creature types.
* The unit needs to be an adult member of the site or its parent civ's government; that is also CAN_LEARN or INTELLIGENT (SLOW_LEARNER cannot take positions) or otherwise is able to think.

==Appointment==

Positions that have an [APPOINTED_BY:position] token require that position to exist, to be available and appointed. Any position that is APPOINTED_BY can be appointed if the appointer's position is filled in.
For site-positions to be appointed, it is required that the appointer is present at that location.

If the appointing unit is temporarily not present, or if that position is not filled, positions depending on it cannot be appointed. This is the case with [[militia captains]], when the [[militia commander]] is on a [[mission]].

A site position cannot appoint a civ position ''or'' LAND_HOLDER in any way whatsoever.

Civ-level positions can appoint other civ-level positions and site-level positions can appoint other site-level positions.

Contrary to what has been said elsewhere, civ-level nobles also can appoint site-level nobles. They need to be at the site to do so. Landholders can appoint both site-level and civ-level nobles. These systems are therefore not as separate as was assumed.

'''Mutual appointment''' cannot take place. If these are the only requisites of the position, then the positions will never appear or get filled. These unfillable positions can be put to good use, for example, to replace a position that is no longer needed without creating a new one.

'''Self appointment''' doesn't normally work. If you have a position that is only appointed by itself, it is never appointed and also cannot be assumed. However, if the position has a number higher than 1, and is filled by multiple units (for example by another position that is now empty), than those units can re-assign or appoint each other from that their shared position.

If an APPOINTED_BY token refers to a non-existing position's code, the effects are as if the appointment token doesn't exist at all.

===Automatic appointment in world-gen and on the civ level===

Outside of fortress mode, the game will always attempt to appoint nobles whenever possible, as long as these positions are '''available''', even if they are invisible to the player.
It shows this message in legends: "(unit name) has been appointed to the position of (position name)"

In world-gen, all positions become available and are automatically appointed, taking population- and appointment-requirements into consideration.

Positions that are REPLACED_BY are culled and won't be filled.

If a citizen of your fortress holds a civ-level position that can appoint another civ-level position, the appointment will happen automatically and without player intervention. It may happen that another citizen of your fortress is appointed by that unit, creating civ-level position holders in your fortress, but it is unknown what is required to force this effect.

===Manual appointments by players in fortress mode===
In fortress mode, the positions that need to be appointed stay empty on embark. and it is the player's job to appoint those. A player can appoint a unit to any available position, according to the hereabove mentioned conditions. The player takes the role of the automatic appointment-system, but has no direct control over elections, successions and replacement. There are some differences in what is possible at world-gen sites and at player-controlled sites.

* A position that is appointed by a unit present as a fortress citizen, can be appointed, re-appointed or left vacant. This means also by civ-level nobles living as a citizen in your fortress; not when they are only visiting, like the diplomat.
* A position whose appointing positions are all either vacant or [REPLACED_BY] can no longer be appointed. If the position is already filled, it cannot be reappointed or vacated; the current holder simply remains in office.
* A position that is APPOINTED_BY a unit present as the land_holder of your site, can be appointed, reassigned or left vacant.
* A position that has SUCCESSION BY_HEIR or BY_POSITION can 'initially' be appointed and also re-appointed or left vacant, but as soon as the [[nobles]] screen closes, ''it can no longer be replaced or left vacant''. From then on, the succession-rules determine who gains that position when the current holder loses the position. This works even if the SUCCESSION:BY_POSITION-position is vacant or replaced.
* A position that is ELECTED nor APPOINTED_BY, can always be (re-)appointed by the player. This is the case with the [[Expedition leader]]. If it is left vacant however, it cannot be appointed, but will be assumed shortly after.
* A position that is both ELECTED and APPOINTED_BY, cannot be appointed by the player. Contrary to world-gen sites, its slot is visible, but it doesn't show the +-sign. This is either by AS_NEEDED or by a fixed number. Even if the position somehow gets filled (re)assignment is never possible
* A player can appoint a number of units to a position, as much as the NUMBER token dictates. If it is AS_NEEDED, the player may create as many slots as they like, also contrary to world-gen sites.
* A civ-position can never be appointed, even if the appointing civ noble is a citizen of your fortress. A civ position also never can be re-assigned or left vacant, would that position be defined as appointed by a site-position.

==Election==
Read more in [[Elections]]. The message that is shown is: "(creature name) has been elected to the position of (position name)"

In worldgen, there is no functional difference between ELECTED and non-appointment, except that elected nobles tend to have high social skills and/or skills related to the position, while non-elected ones are assigned randomly. See: [[Elections]]

A succession goes before an election.

A position that is both ELECTED and APPOINTED_BY never gets elected. Even if the appointees' position somehow gets filled, (re)-elections won't happen. So, it doesn't seem possible to have an elected position become available when a certain other position becomes filled.

An ELECTED civ-(or LAND_HOLDER) position at your site will never be (re)-elected in fortress mode. So real (re-)election only works with SITE-positions.

=== {{text anchor|Election Day}} ===
Election Day takes place on the 17th of Summer. On this day, a full reevaluation is performed, including all currently elected positions, which are subject to re-election. Contrary to the information on [[Elections]], nothing occurs at the start of a season.

Positions that are both [APPOINTED_BY] and [ELECTED] will not be re-elected on Election Day when assigned through [SUCCESSION].

=== Election Eligiblity ===
Any citizen may stand for election. Eligibility cannot be restricted using [ACCEPTED_CREATURE], [REJECTED_CREATURE], [ACCEPTED_CLASS], [REJECTED_CLASS], or [GENDER]. Units currently having a [SUCCESSION]-position even may be elected for a position with a [SQUAD]-token, which is otherwise impossible to assign or even succeed.

=== Skills ===
In elections, skills are taken into account for the tokens of the position which is elected.
{| class="wikitable"
|+ Relevant skills per position token
|-
! Position Token !! Relevant skills
|-
| Responsibility [[Position_token#DELIVER_MESSAGES|[DELIVER_MESSAGES]]] || [[Ambusher]], [[Observer]] and [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#ACCOUNTING|[ACCOUNTING]]] || [[Record_keeper|Record keeper]]
|-
| Responsibility [[Position_token#ESPIONAGE|[ESPIONAGE]]] || [[Schemer]]
|-
| Responsibility [[Position_token#HEALTH_MANAGEMENT|[HEALTH_MANAGEMENT]]] || [[Diagnostician|Diagnostician]]
|-
| Responsibility [[Position_token#MAKE_INTRODUCTIONS|[MAKE_INTRODUCTIONS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#MAKE_PEACE_AGREEMENTS|[MAKE_PEACE_AGREEMENTS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#MAKE_TOPIC_AGREEMENTS|[MAKE_TOPIC_AGREEMENTS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#MANAGE_PRODUCTION|[MANAGE_PRODUCTION]]] || [[Organizer]]
|-
| Responsibility [[Position_token#MEET_WORKERS|[MEET_WORKERS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#RECEIVE_DIPLOMATS|[RECEIVE_DIPLOMATS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#RELIGION|[RELIGION]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#TAME_EXOTICS|[TAME_EXOTICS]]] || [[Animal_trainer|Animal trainer]]
|-
| Responsibility [[Position_token#TRADE|[TRADE]]] || [[Social_skill|Social skills]] and [[Appraiser|Appraiser]]
|-
| [[Position_token#SQUAD|[SQUAD]]]-token || [[Tactician]] and [[Leader]]
|}

==Assumption==

A position that is not APPOINTED_BY nor ELECTED, or is appointed by positions that are not available in your site or civ, will be assumable by a random dwarf. If it has responsibilities that require certain skills, then these are taken into consideration on embark, but not when the position is assumed during the actual game.

Normally, one to three units will take the into consideration to assume a position. Most of the time when there are multiple open positions, only a single unit will assume all of them. However, a position that has REJECTED_CREATURE, REJECTED_CLASS, ALLOWED_CREATURE or ALLOWED_CLASS will be filled with all different units, even if the creature or class mentioned is irrelevant. It seems that this forces the game to loop over all the available units.

The message that is shown in Legends mode is: "(unit name) has assumed the position of (position name)". This may also take place in fortress mode, which then shows this message to the player.

If an assumable position becomes empty, it will be assumed within a day. This is the case when you leave the position of expedition-leader vacant. It also happens with entities.

Assumable positions that become empty will not be assumed if that position has a valid [SUCCESSION] -successor. In that case, the successor inherits the position.

Even positions that are somehow invisible because they cannot be directly APPOINTED_BY players, can be assumed.

When you embark, the assumable positions are automatically assigned to a random unit. If there are multiple of these positions at embark, they all are assigned to the same unit. If there are enough positions available, multiple units may gain a position, but often no more than three different ones.

If a dwarf in fortress mode assumes a position, that already has another position, it will leave the current position empty. When that position also is assumed, then this will continue until all positions have a dwarf appointed to them, with no other position.

A unit that already has a position with a [SUCCESSION] token won't take assumable positions into consideration that have a [SQUAD] token. This can be used by the modder to prevent unwanted loss of current positions.

A position that has an appointer which got replaced because of REPLACED_BY, will not become assumable. Also, positions that have an AS_NEEDED appointer that is not yet filled (or ever), will also not be assumed.

==Succession==

If a position-holder dies or advances to a new position via succession, the position will be granted to another unit based on the [SUCCESSION] tag. If they have an heir or the succeeding position exists, that unit will be assigned. If not, a new one will be appointed according to the usual rules. The message that is shown is: "(creature name) being the rightful heir, has inherited the position of (position name)"

The succeeding creature will also lose its previous position. When succession is defined using BY_POSITION, the unit naturally loses the referenced position. However, it also loses any other positions it may hold. If a unit could simultaneously inherit multiple positions, the last-defined succession overrides the earlier one, clearing the previously acquired position

Succession works both at site-level and at civ-level, both in world-gen and in fortress-mode. Succession by position on the civ-level is also visible and functional in fortress-mode. If both civ-level nobles are a citizen of your fortress, succession is applied visually. Vanilla example: The [[druid]] is succeeded by the [[acolyte]]. This means that as soon as the druid dies, the acolyte takes over.

When a position that is succeeded by position becomes available, immediately it is checked if a position-successor is available and the position is filled with that unit. Even if this is an [ELECTED] position, succession goes first. When elections eventually do happen, succession plays no role.

It is possible to assign multiple levels of [SUCCESSION:BY_POSITION] in different positions, creating a line of positions where the death of one causes all those "below" them to advance.

A position can have multiple tokens with position-succession. It looks to be random which one is used. It is not always:
* The first or last defined token
* The first or last appointed unit
* the oldest or youngest
* one with a higher or lower precedence
* a unit with relevant skills

When a position is defined with a Succession-type, that unit cannot have another position that has a Squad-type. If the succession-position itself has a squad, than it can be assigned another position with a squad, but then it will loose the previous succesion position. See further details by "Squad"

Assumed positions can also be succeeded by position, if the current holder dies.

If the successor is an AS_NEEDED position, the used unit will leave a vacant position-slot on its removal by succession. This empty slot remains a real slot, which will only be cleaned up if you (un)appoint a unit to this position-series. It isn't cleaned up after regular position validation.

A civ-level position of a unit living at your site might be inherited by a unit holding that does not currently live at your site. This, unfortunately, moves that position to a unit off site. This may also happen with the landholder of your site, for example when it is succeeded by another civ-level position. This currently poses an unsolved challenge.

===Eligibility for succession===
Succession is restricted by the tokens [ACCEPTED_CREATURE], [REJECTED_CREATURE], [ACCEPTED_CLASS], [REJECTED_CLASS] and [GENDER].

===Site and civ combined succession===

Succession can work when combining site positions with civ-level positions or land_holders, but only in world-gen mode. In fortress mode, it only works with combining the same level of nobles, with Landholders regarded as civ-level. So, in fortress mode, a site's position cannot succeed a landholder's position and it cannot succeed another type of civ-level position, and vice versa.

This won't work even if the positions:
* are AS_NEEDED or having a fixed number.
* Are LAND_HOLDERs.

===Succession [BY_HEIR]===

When a heir is needed for succession, all children and then other relatives are validated. They cannot take the position if their status does not allow it, for example if they have become a member of another civilisation. See: "Who can take a position". If the unit has no valid heir on that location, the position may go to a unit living on another site. This may cause the title of Landholder of some land to be inherited by a unit living somewhere else. That might be a problem, because then you lose your landholders.

===Premature Succession===

There are cases where [SUCCESSION:BY_POSITION] is applied prematurely: at the moment a position is first created and becomes appointable or assumable, rather than after a current holder leaves. In this situation, the succession mechanism assigns a holder immediately, without any player interaction.

When a position becomes available for the first time, the game checks whether a valid successor-by-position exists. If so, that unit is assigned instantly. It can affect positions that would normally be appointed or elected by the player, causing succession to trigger before the player has any opportunity to intervene.

This behavior occurs only in Fortress mode, but can be applied both on [SITE]-positions as well in civ-positions. That last one however is a bit harder to control. Example: [[Advanced entity position mechanics#The Archduke|The Archduke]]

This premature succession only occurs the first time a position becomes available (i.e. when it is created and becomes appointable or assumable). Even if the position remains vacant and the conditions for succession improve later, premature succession will not trigger again. From that point onward, only normal succession rules apply.

Using premature succession, a position that has [ELECTED], [APPOINTED_BY], or both, can be filled directly.
Notably, positions that combine [ELECTED] and [APPOINTED_BY] are normally impossible to fill through regular mechanics. Premature succession bypasses both election and appointment entirely, making this combination uniquely reachable through this mechanism.

No initial election takes place, and no subsequent elections will ever occur for that position. Succession always takes precedence over election, both in premature succession and in normal succession cases.

This behavior applies only in Fortress mode, not during world generation. World-gen uses simplified and more efficient mechanics, and this interaction does not occur there. Premature succession can affect both site-level and civilization-level positions.

====Multiple succession chains====

Multiple succession chains may be defined and are resolved in the order they appear in the raws.

If a position has both:
* a direct succession chain (A → C), and
* a multi-step chain (A → B → C),

and intermediate positions are vacant, resolution proceeds according to raw order. A common outcome is:
# The direct succession (A → C) is applied first, assigning A to C.
# The remaining chain then advances (A → B).
# If C still has empty slots, the final step (B → C) may occur.

If position B is already filled, behavior depends entirely on raw definition order:
* nothing may happen, or
* B may move to C first, followed by A moving to B.
====Working triggers====
Premature succession is triggered when a succeedable position is created under the following conditions:
* The succeedable position is created because its [REQUIRES_POPULATION] threshold is reached. This applies even if the position is not [APPOINTED_BY]. Premature succession takes priority over automatic assumption (e.g. the mayor declaring themselves within a day).
* The succeedable position can be [APPOINTED_BY] another position of the same level (site or civ) that has just been created because its [REQUIRES_POPULATION] was reached.
* The succeedable position can be appointed by another [SITE] [AS_NEEDED] position that has just been created and filled.
* The succeedable (site or civ) position is [APPOINTED_BY] the [LAND_HOLDER] position, which has just been created due to site elevation. This typically resolves when the diplomat leaves the map, at which point the landholder position becomes active.
* If all other requirements are met, premature succession can occur immediately after unpausing following embark, for positions with [REQUIRES_POPULATION:7].
====Non-working triggers====
Premature succession does '''not''' occur in the following cases:
* An [AS_NEEDED] succeedable position slot is manually created by the player while its succeeding position is already filled. [AS_NEEDED] positions must always be appointed after creation.
* The succeeding position is filled after the succeedable position becomes available. The moment of creation is the decisive trigger; filling the source position later is too late.
* The succeedable position can be appointed by another site or civ position with a fixed number of slots that has just been appointed. In this case, the succeedable position is just available for appointment itself, nothing more
* Any situation occurring during world generation.
* The succeeding position is [REPLACED_BY] the succeedable position. In this case, replacement removes the unit from the source position first, leaving no holder available for the succession mechanism to use.rst, leaving no holder available for the succession mechanism to use.
* The position is [APPOINTED_BY] a civ-level position, that just became a citizen of your fortress. It must be noted that those civ-level positions were active all that time and the succeedable position could be appointed even before. The monarchs arrival does not trigger premature succession

=Losing a position=

A unit can lose a position when:
* It dies
* It succeeds another position, even if it has nothing to do with the previous position.
* It is assigned to another SQUAD-holding position
* It is convicted of a crime.
* Another unit is ELECTED for the position
* Its position becomes replaced
* Another unit is appointed by the player, or the position is left vacant.
* It has assumed another position, as this always leaves the previous position vacant.

=Embarkment=
Two types of positions are automatically filled by embark.
* Positions without [APPOINTED_BY] or [ELECTED] (assumable). All these positions, even with a NUMBER higher than 1, are all filled with one to three dwarves. Contrary to assumption, this doesn't take into account any limitations. REJECTED_CLASS, ALLOWED_CLASS, REJECTED_CREATURE, ALLOWED_CREATURE and GENDER are applied, but without the normal spread you may expect with assumptions. Also it doesn't look at [SUCCESSION] and [SQUAD] limitations.
* Positions that are elected are filled-in by the normal election rules.

Positions that have a defined appointer are never initially filled at embark.

All positions that don't have [REQUIRES_POPULATION] or with a [REQUIRES_POPULATION] of 7 or lower, will be available at embark.

=Land Holders=

A Landholder is a '''special civ-level noble''' who gets a certain piece of land to hold, when that land is elevated to a certain level, determined by the tag [LAND_HOLDER] and by the landholder triggers in the game's settings. In vanilla, these are the baron, the count and the duke.

A unit gaining the landholder position does not migrate to that specific named land. In world-gen, they stay just where they are, probably at the capital. In fortress mode, you can suggest a citizen for the role. So for the time being that works.

Succession is then a real issue. If you use BY_HEIR, its solved when that landholder has children living at your site. But when its not the case, the title just goes to anyone randomly. Succession BY_POSITION works, but only in the civ-chain, and there's no way to guarantee a civ-holder is at your site at that time. Even with 'automatic spread' positions, it goes to one of them randomly.

==Functioning of the regular landholder chain==

The distinct difference between a landholder and a regular civ-level noble, is that a landholder may gain the position of landholder "of (sitename)" They are then seen as ruler of a particular site.

For a land_holder position to function as such, it has a few requirements:
* NUMBER:AS_NEEDED
* The first landholder-number of 1 is defined.
* No SITE (so civ) tag in that position.
*REPLACED_BY the next level landholder
If a landholder is defined with differentiating properties, it will function like a regular noble. A higher-up landholder that lacks the required tokens or connections will then not be used in elevation.

If a fortress meets the trigger for a new LAND_HOLDER tier when a caravan leaves, then the next time the outpost liaison or equivalent arrives, they will offer to make you an official colony, which will allow you to select all positions for that LAND_HOLDER level. Each time they appear, the outpost liaison will only promote your fortress one tier up the LAND_HOLDER track.

The landholder's LAND_NAME is not required for the functioning of this system. If omitted, messages will be shown with a more generic text.

==Appointment==

This mechanism differs from the regular methods of position management. It ignores all regular appointment- and election rules, so it more or less functions like automatic assignment. A landholder is, in vanilla, appointed by the monarch. Changing this doesn't seem to do anything. If they are appointed by a site-position, a not-yet-existing civ-position, or not appointed at all: the system keeps working as usual.

A landholder can appoint civ-positions and site positions. This works as expected: the positions only are appointed then when that landholder becomes available on civ-level or when he arrives at that site for site-level positions.

If your rank of landholder is the first of its rank in the realm, and is the sole appointer of some civ-position, then immediately as it gains the title, it will appoint the empty civ-slots. This may happen on your site, but the frequency and certainty is hard to determine.

==Succession==

Succession rules are applied to some extent:
* In world-gen it works according to succession rules, and site-positions can be used here. This means that a site position or a civ-position can inherit a landholder position, and vice versa.
* In fortress mode, once a landholder has been appointed, it then can inherit civ-level positions, and vice versa. This means that your baron can become king.
* Succession rules do not apply within the [LAND_HOLDER] chain; a count will not inherit a baron's land. This is because succession does not work well with the AS_NEEDED token.
* Premature succession works in fortress mode with landholders. If a unit gets a landholder's position and that landholder is the appointer of an as yet empty position, which is defined as succeeding from a third one, then the succession is immediately applied. The landholder themselves can even be the successor of a newly created position.
* A landholder's position is, in fortress mode, not successionable by a site-position or vice versa

===Impossibilities for succession by a site-position===
It would be very beneficial if the landholder can be succeeded by a [SITE]-position. So far, the following tests have not lead to positive results:
* making landholder and site-position both non-[DUTY_BOUND]
* make the site-position be [APPOINTED_BY] the landholder and/or the monarch
* give landholder and site-position [REJECTED_CREATURE]
* Let the monarch live at your site when succession could happen.
* Let the site-position be [REPLACED_BY] the landholder.

==Nomination==

The player is able to nominate a unit to become the LAND_HOLDER, but this only works with units of [LAND_HOLDER] level 1. The player can select all units, only limited by the PRECEDENCE of the current units' positions.

A unit that has a position with a PRECEDENCE lower or equal to that of the landholder's position, cannot be selected. This means that a baron (or count) from another site or the monarch cannot be selected, because their precedence is lower or equal.

The GENDER token does not work here: also units with the wrong gender (sorry) can be selected.

==Levels==
In mods, up to 10 levels of LAND_HOLDER may be defined.

If a landholder is replaced by a wrong landholder number (1 replaced by 3), then the number 3 is still correctly attached to the settlement.

If the current landholder has the highest available landholder number, then the next elevation will not happen - the diplomat will not elevate your fortress to a higher position, even if that position might be REPLACED_BY a lower landholder.

These chains do work:
* 1 -> 2a - > 2b -> 3
* 1 -> 3 -> 2 -> 4

These chains do not work:
* 2 -> 3 (need to start at 1)
* 1 -> 4 -> 2 -> 3 (stops after 4 as the highest)
* 1a -> 2, 1b -> 2 (only 1a and 2 work, 1b is not used)

==Moving landholders==

It may happen that a land-holder no longer lives at the site which they are the landholder of, specifically when the current landholder dies, leaving the title to an heir living somewhere else.

To prevent this from happening, you can make their succession from heir and make sure that their kids live at your site. Or, you can make their position succeeded by another civ position, and make it so that this civ position is somehow available on your site. But if multiple of these positions exist, it cannot be guaranteed that a citizen of your fortress will inherit the title.

In world gen, a landholder lacking the DUTY_BOUND-token will also move to the site they like, according to legends mode.

==Replacement by a generic civ-position==

If a landholder is replaced by an AS_NEEDED non-landholder civ-position, then this will work: the current landholder loses that title upon settlement-elevation and gains that civ-title. However, the civ-title lacks the landholder-property of being attached to the land. It will not show the name of the settlement alongside the position's name. So no "minister of Shovelmounts"

If a landholder is replaced by a general AS_NEEDED civ-position, that itself is also replaced by a generic AS_NEEDED civ-position, then firstly the elevation is executed and also the unit gains that new position. However, he immediately loses it, because an AS_NEEDED position that is replaced by another position can be filled initially, but units wont be able to hold that title.

==Landholder with fixed number==

A landholder's position that has a fixed number will be created and filled directly when the civilisation is born, so this position slot is then not available for the regular landholder-mechanic and will also not be used. That landholder will thus not be attached to a settlement.

It doesn't matter if the landholder's position is connected to the regular landholder's-chain with the REPLACE_BY token.

==Responsibilities==

When given a certain [RESPONSIBILITY], a landholder may function as a regular civ-level noble. If the position has [TRADE] or [OUTPOST_NEGOTIATING] responsibilities, then the landholder functions both as a diplomat and as an actual land holder. A landholder with the [MILITARY_STRATEGY] responsibility will travel around taming creatures in world-gen, according to legends mode.

Besides that, the responsibilities work the same as with any other on-site living position-holder, civ or otherwise.

=Military=
==Squad management==
In the vanilla game, the Squad interface only becomes available after a militia commander has been appointed. Until then, the window displays:{{DFtext|You must appoint somebody first to create a squad.}}

What’s surprising is how this is determined internally. In the entity raw definition, '''only the last two positions that include a [SQUAD] token are checked''' to decide whether the interface is accessible at all. As a result, if your hierarchy defines commanders A through E, appointing '''Commander D or E''' unlocks squad formation, while appointing A–C does nothing.

In other words, squad availability is not tied to ''having a militia commander'', but to ''which specific positions happen to be last in the raw list''—a notably hacky implementation.

These 'last two' are always the last two '''available positions.''' So if they get [REPLACED_BY] or become available because of [REQUIRES_POPULATION], the game adapts to those.

==Squad assignment==

Squads can be assigned, even if the leader position has no holder.

A specific unit can only have one position associated with a squad. If it gains another 'squad holding position', it is unassigned from the first one. This does not work with a 0-squad, so only 1+squads are taken into consideration. This technique can possibly be used to distribute all positions equally among all citizens. It does however not work with election and assumption.

If a civ-level position is associated with a squad and it gets a site-level squad-holding position assigned, it loses the current civ-position.

Squads can get really messed up, if you make the position (or multiple) either elected or not-elected and not-appointed, then this can cause the game to assign multiple squads to the same unit. Automatic assignment and election does not take squads into account, but the nobles screen does. This can cause the positions to be cleared as the game figures out that they have more than one position, and immediately get elected or assumed again.

Positions that cannot have a squad-position:
* A site- or civ-position with a [SUCCESSION] token cannot be appointed a squad-holding-position. The other way around, however, does work. For example, if a site-position with a [SUCCESSION]-token is appointed to a unit that has already a position with [SQUAD]. But when that squad position is assigned to another unit, it cannot be assigned back.
* A position with [SUCCESSION] can also not be assigned as a '''member''' of a squad.
* A squad-holding position with a formed squad cannot be appointed to another squad holding position.

If a position has at least one squad member, it cannot be left vacant. First, the squad has to be disbanded, then the position may be cleared.

==0-squads==
A 0-Squad is defined in a position as [SQUAD:0:member:members]. It does not seem to do anything useful as of now.
* It cannot be used to activate the [[Squad|military interface]]
* It does not restrict the assignment of [SUCCESSION] positions.
* Assigning this position does not clear any previously held squad position.
* The [[Leader]] and [[Tactician]] skill are not marked as relevant skills and are not taken into account in elections.
* It cannot be formed as a squad.

=Further testing=
The following questions may need additional testing. Feel free to add or answer
* Everything regarding COMMANDING and army-structure
** [http://www.bay12forums.com/smf/index.php?topic=175437.msg8331668#msg8331668]
** [http://www.bay12forums.com/smf/index.php?topic=165213.msg8335682#msg8335682]
** [http://www.bay12forums.com/smf/index.php?topic=174584.msg8026854#msg8026854]
* Everything regarding CONQUERED_SITE, but it is presumably just like site. But what if you combine SITE or LAND_HOLDER with it?
* Stuff about the monarch, its arrival and its entourage.

=Oddities (Bugs)=
Almost everything on this page could be called an oddity. Because of their unexpected usability, some may also be referred to as “undocumented features.” Others, however, are simply odd and not particularly useful, yet I hesitate to call them “bugs.”
* If a certain threshold is reached that makes an elected position electable, and the triggering event that initiates this evaluation is an assumption, then the resulting assumption is also referred to in the messages as an election

=Examples=

===The Founder===
The founder is a single dwarf, appointed at embark. They will be the only one ever to have this position and are not replaceable. When they lose their position some way, the position will not be assumed by another dwarf.
{{gamedata|title=The Founder|
[POSITION:THE_FOUNDER]
[NAME:the founder:founders]
[NUMBER:1]
[SITE]
[ALLOWED_CREATURE:DWARF:ALL] - will only be filled at embark, but not assumable later.
[REJECTED_CREATURE:DWARF:ALL] - will only be filled at embark, but not assumable later.
[SUCCESSION:BY_POSITION:THE_FOUNDER] - not unassignable, also cannot be assigned to a [SQUAD] position.
[PRECEDENCE:200]
Non APPOINTED_BY
Non ELECTED
Optional: Add responsibilities to make the game select a unit with certain skills.
}}
===Marriage bar===
Dwarven matrons are held in great honour. Upon marriage, a female dwarf is no longer expected to perform menial labour. All dwarven males hold this position by default, granting their spouses exemption from menial work.

The position becomes available with the arrival of the first migrants; otherwise, on embark, it would be assumed by females. Its succession rule is non-functional, but this prevents the player from unassigning the position. A squad size of 1 and the succession rules together prevent a unit from assuming the position more than once.

With precedence set to NONE, the position name is hidden, while LAND_NAME remains visible on the nobles screen. All married females receive the suffix “, Mrs.” and are marked as Nobles.

The practical usefulness of this position is debatable, but it serves as a clear demonstration of several mechanics.
{{gamedata|title=Mrs. Urist|

[POSITION:MRS_URIST]
[NUMBER:300]
[SITE]
[ALLOWED_CREATURE:DWARF:MALE]
Not APPOINTED_BY
Not ELECTED
[LAND_NAME:Dwarven male]
[NAME:dwarven male:dwarven male]
[PRECEDENCE:NONE]
[SPOUSE_FEMALE:, Mrs.:spouses]
[MENIAL_WORK_EXEMPTION_SPOUSE]
[REQUIRES_POPULATION:8]
[SUCCESSION:BY_POSITION:MONARCH]
[SQUAD:1:member:members]
}}
===The Archduke===
The archduke is the leader of the civilization, but exists only from landholder 4-level. Until then, its position remains vacant. When a settlement is elevated to tier 4 (grand duke), the grand duke can appoint the ruler of the civilisation, the archduke. Because of 'Premature Succession', they themself inherit that position immediately, but only when in fortress mode. Its heir then becomes grand duke.
{{gamedata|title=The Archduke| no POSITION:MONARCH or other PRECEDENCE:1

[POSITION:THE_ARCHDUKE]
[NAME:archduke:archdukes]
[NAME_MALE:archduke:archdukes]
[NAME_FEMALE:archduchess:archduchesses]
[LAND_NAME:a archduchy]
[NUMBER:1]
[PRECEDENCE:1]
[SUCCESSION:BY_POSITION:GRAND_DUKE]
[APPOINTED_BY:GRAND_DUKE]
(add additional monarch-stuff, like spouse name, demands etc.)

[POSITION:GRAND_DUKE]
[NAME:grand duke:grand dukes]
[NAME_MALE:grand duke:grand dukes]
[NAME_FEMALE:grand duchess:grand duchesses]
[NUMBER:AS_NEEDED]
[LAND_HOLDER:4]
// Optional ...
[PRECEDENCE:19]
[LAND_NAME:a archduchy]
[RESPONSIBILITY:LAW_MAKING]
[RESPONSIBILITY:RECEIVE_DIPLOMATS]
[SUCCESSION:BY_HEIR]
[APPOINTED_BY:THE_ARCHDUKE]
(add additional landholder-stuff)

!!add to [POSITION:DUKE]
[REPLACED_BY:GRAND_DUKE]

}}
{{Category|Modding}}
{{Category|Entities}}
{{Category|Guides}}

Advanced entity position mechanics

2026-02-10T10:37:47Z

Joostheger: /* The Archduke */

{{Quality|Fine}}
{{Modding}}

= Introduction =

[http://www.bay12forums.com/smf/index.php?topic=182239.0 Discussion thread on the forum]

This page documents observed and tested behavior of entity positions in Dwarf Fortress that is not fully described elsewhere on the wiki. It focuses on advanced interactions between position tokens, including appointment, succession, election, and responsibility handling, across both civilization-level and site-level entities.

The mechanics described here are based on empirical testing in world generation and fortress mode, supplemented where necessary by raw analysis. In several cases, the game’s behavior is determined by evaluation order and interaction between multiple tags, rather than by individual tokens in isolation.

This page is intended for modders and advanced players who are designing or debugging custom entity position structures. It does not restate basic position mechanics, but instead highlights edge cases, non-obvious interactions, and behaviors that may appear inconsistent or undocumented.

Unless stated otherwise, the described behavior applies to current versions of the game and may differ from older releases.

==What is an entity? What is a position?==
An [[entity]] is an organizational structure that can have relationships with other entities, usually known as a [[civilization]] or a "[[site]] government" in the game, but merchant [[guild]]s, religious organizations, necromancer towers, and [[bandit]] groups are also entities. An entity can have positions - in most cases, these are hardcoded and generated by the game, but as for civilizations and sites, the [[raw file]]s can be customised.

A position is a special relationship between a unit and an entity. The unit holding a position has a larger influence over that entity than other citizens. Positions are mostly known as [[nobles]], but in this article. the technical term is used.

=Position levels (Site/Civ) and their interaction=
There are two basic types of positions that are customizable: '''civ(ilization)''' level and '''site level'''. Positions with the tag [SITE] are at site level, positions without the tag [SITE] are at 'civ level'. These two types of nobles can be considered '''loosely related systems'''. There are a few places where they can interact with each other.

Civ-level positions are in charge of the civilization as a whole, managing national [[trade]], laws, and [[war]]s. These are, for example, the vanilla [[monarch]], [[diplomat]] and [[general]]. (Note that the general doesn't do anything in either mode in the current version.)

'''[LAND_HOLDER]''' nobles are also positions at civ-level. These units are members of the national government, but have gained authority over some land or site. Once they do, they move to that place, but their position is still regarded as a civ-level position.

Site-level position holders are members of a site government (subsidiary to the civilization), and manage local affairs in that location. These are, for example, the [[mayor]], the [[sheriff]] and the [[broker]].

==Table of interaction between different position levels==
In this table, the possible interactions between different position levels are summarized.
The header row shows the positions defining the tokens.

The left column shows the position type that is referred to.
Example:
{| {{prettytable}}
|- bgcolor="#ddd"
! referred position-type
! LAND_HOLDER
|-
| civilization
| (baron is) APPOINTED_BY:MONARCH
|}
color coding: 
* Exists in vanilla
* Possible with mods
* Not possible
* possible to some extent.
* not yet fully investigated.
{| {{prettytable}}
|- bgcolor="#ddd"
! referred position-type
! Civilization
! SITE
! LAND_HOLDER
! CONQUERED_SITE

|-
| Civilization
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION '''(1)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION

|-
| SITE
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION '''(2)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY '''(3)''' COMMANDER REPLACED_BY SUCCESSION '''(4)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION

|-
| LAND_HOLDER
| APPOINTED_BY COMMANDER REPLACED_BY '''(6)''' SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION '''(5)'''
| APPOINTED_BY COMMANDER REPLACED_BY '''(7)''' SUCCESSION '''(8)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION

|-
| CONQUERED_SITE
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
|}

Remarks:
# Works only in world-gen, if a unit with that civ-position is present at the site.
# Works only in world-gen, the site-position holding unit will then move to the capital.
# Is completely ignored
# Works only in world-gen.
# Works only in world-gen.
# Won't appear at all
# This is necessary for the landholder chain to work properly, it doesn’t work otherwise.
# This works only outside of the landholder chain, so when landholders are simply regarded as civ-level nobles. might also work in world-gen
#

== Other interactions ==

Unfortunately, interactions with positions of other entities don't seem possible, such as APPOINTED_BY: HIGH_PRIEST. With [VARIABLE_POSITIONS], positions are automatically created with codes like CUSTOM_LAW_MAKER_2, but interaction with these positions don't seem to work, either. For more info on those, see [[Variable positions]]

=General=

==Civ-level nobles living at your site==
Nobles from your civilization can come to live at your fortress. This happens in vanilla with landholders such as [[Baron]], [[Count]] and [[Duke]], with the Monarch, but sometimes also with non-landed LAND_HOLDERS.

When a civ-level noble becomes a [[citizen]] at your location, their position is shown among the site-level positions in your [[nobles screen]]. They appear to function as a site-level noble. They may have [[demand]]s, [[mandate]]s, [[squad]]s and the like. They can appoint nobles at the site-level.

If they have certain [RESPONSIBILITY]ies, they do the tasks that go with them.

==Fortress mode, world-gen and their differences==
Their are a few differences in how positions function between fortress mode (normal play mode) and the world generation (world-gen).

In '''fortress mode''', the player has some control over the appointment of nobles, limited by elections, automatic filled-in positions and succession rules. Pre-fortress mode, which is referred to as '''world-gen''', the game will always attempt to assign nobles whenever possible. It is subjected to the same rules as in fortress-mode, but there are some exceptions. In '''[[World activities]]''', which is the thing that happens in the world while you play fortress mode, it seems as if the same rules are applied as fortress mode.

A difference between player-fortress-mode and world-gen, is causes by visibility (see below). Positions that are not visible by the player and thus not available for assignment, will be available in world-gen and will thus be automatically assigned.

In fortress mode, a position that is both [ELECTED] and [APPOINTED_BY], cannot be appointed by the player and is also not elected, and can thus not be filled. But in world-gen sites however, these positions are automatically filled.

Positions with [AS_NEEDED] are almost never created and filled in world-gen (depending on their [RESPONSIBILITY]ies), but can always be used in player mode.

A position can, in fortress mode, be filled by the same unit. A unit can gain multiple positions in fortress mode, for example because of [[elections]]. This will not happen in world-gen mode: a unit can only have one position. See also remarks on 'embark' and 'Losing a position'.

In world-gen, [SUCCESSION] between civ-levels and [SITE-]levels may happen. This will not happen in fortress mode, or even off-site in [[World activities]].

In fortress mode, premature SUCCESSION may happen. This will not happen in world-gen mode.

==Units holding multiple positions in multiple entities==
A unit can hold multiple positions in its civilisation or in its site-entity, however this does not happen in world-gen. Only at player-managed sites can units be holding multiple positions at once. (It is probably not possible for a unit to hold a position in two different civilisations or two different sites.)

In world-gen, if there are too many positions to be filled, they simply stay empty until more units are available. E.G, a unit at a site might inherit a civ-level position and still remain a member of the local government. When this happens however, they move to the capital. If a unit gains a new position, either inherited or otherwise, it drops the previous one. If a unit assumes a civ-position in fortress mode, it leaves the current position.

If a unit holds the same (site-)position multiple times, it has no additional effect.

If a unit holds multiple different positions of the same entity, it has all those positions' responsibilities and properties, stacked up. Presumably, the demands for those combined positions are determined by the highest.

A unit holding a position with a succession token can be assigned another position with a (different) succession token.

A unit holding a position with a squad-position cannot hold another squad-position. It is dropped from the first, when it gets its second assigned.
A unit holding a position with a succession token cannot be assigned to a squad-position - the unit is simply not available. It works the other way around, though.

=[PRECEDENCE]=
The first defined position with precedence of 1 counts as the ruler of the civ. See also: [[Position_token#PRECEDENCE|PRECEDENCE]].

If the precedence is omitted or has a negative value, the game sets 0 as precedence, which seems to have no effect whatsoever.

When a unit has multiple positions, the name of the position with the highest rank in precedence is shown behind the unit's name.

If you omit precedence entirely, or set it to [PRECEDENCE:NONE], the position name will not be shown after the unit’s name. Your *Urist Mason* will remain simply *Mason*. This can be useful for positions that are unimportant or purely functional. The position will also not appear in the civilisation overview of your site on the world map. The position name is shown in messages, but remains hidden on the nobles screen as well. To make it visible there, use [LAND_NAME].

=[RESPONSIBILITY]ies=
Both civ and [SITE] positions can carry responsibilities. However, not all responsibilities are active for both types: some function only for civ positions, others only for site positions. When a civ noble arrives at a site and takes up residence, they do not perform responsibilities that are intended for SITE nobles. As a result, these responsibilities neither trigger their associated tasks nor unlock related game mechanics. For example, a civ-level manager living in a fortress will not perform management duties there and doesn't unlock the management-screen, even with an assigned office.
This behavior applies to the following [SITE]-level responsibilities:
* [RESPONSIBILITY:ACCOUNTING]
* [RESPONSIBILITY:BUILD_MORALE]
* [RESPONSIBILITY:HEALTH_MANAGEMENT]
* [RESPONSIBILITY:LAW_ENFORCEMENT]
* [RESPONSIBILITY:MANAGE_PRODUCTION]
* [RESPONSIBILITY:MEET_WORKERS]
* [RESPONSIBILITY:TRADE] (functions differently)
Other responsibilities may be affected as well, but have not yet been fully tested.

==[DELIVERS_MESSAGES]==
The only [AS_NEEDED]-position that is created in worldgen based on responsibility is that of the site-level responsibility [DELIVERS_MESSAGES].

==Outpost Liaisons and Diplomats==
Civ-positions with the responsibility [ESTABLISH_COLONY_TRADE_AGREEMENTS] ([[Outpost_Liaison|Outpost Liaison]]s) will meet with the site-noble who has responsibility for [RECEIVE_DIPLOMATS] and the highest rank of precedence (i.e. the lowest precedence value). Usually this is the [[Expedition_leader|Expedition leader]].

Once a [LAND_HOLDER] is assigned to the site, civ-positions with the responsibility [MAKE_TOPIC_AGREEMENTS] ([[Diplomat]]s) will meet with '''civ'''-level nobles present at the site who have the [RECEIVE_DIPLOMATS] responsibility. If multiple eligible nobles are available, one is selected at random. If no eligible noble is present, the diplomat leaves angrily. If the landholder is no longer present at the site, diplomats will not arrive at all.

It appears that Outpost Liaisons and Diplomats are chosen for a diplomatic mission based on availability. When multiple candidates exist, the position defined last in the raws is most often selected.

==[TRADE]==
Civ-level nobles with [TRADE] will arrive with the caravan, just as the Outpost Liaison. Their behavior is no longer active in the vanilla game, but the mechanics are still present. See [[40d:Guild_representative|Guild representative]] for more details. This civ-noble will only meet with the SITE noble with [TRADE], usually the [[Broker]].

If two civ-nobles exist with both [TRADE] and [ESTABLISH_COLONY_TRADE_AGREEMENTS], they both arrive at the same time. Even if both tokens are assigned to a single position, if more than one instance of that position exists, two of them will arrive. However in that case, somehow the elevation of the site and appointment of landholder isn't offered.

If the SITE-noble they intend to meet has both [TRADE] and [RECEIVE_DIPLOMATS], only one meeting will proceed and the other is cancelled. However, when two SITE-nobles are available, each with either [TRADE] or [RECEIVE_DIPLOMATS], both meetings will proceed and both civ-nobles will attempt to negotiate a trade agreement. It is not known what happens if these agreements are accepted or refused.

In the trade depot, the last defined position with the [TRADE] responsibility is shown as broker. However when requesting a trader, the first defined position with [TRADE] will actually go there to do the trade.

==World-gen effects of the [RESPONSIBILITY] of available positions ==
It is possible to cause civs and individual sites to change their behavior substantially when they reach a certain size, by controlling nobles.
* If a site can only appoint a position with [MILITARY_GOALS] after reaching a particular size, that site will not send armies on missions until the required size is reached.
* A civ-level [LAW_MAKING] position is required for the civilization to have any kind of cohesion. Without it, sites will be constantly embroiled in territorial disputes and civil wars will be commonplace.
* [MILITARY_STRATEGY] positions go out and tame wild animals. This makes your civ gain those animals as domesticated and also brings them in sieges.
* The [[Personality_facet|Personality]] of the position's holder determines how they lead the civ.

=Availability and visibility=
==Availability of (new) positions==
Warning: Do not mistake "availability" for "visibility"!

Of all the possible positions existing in your site's entity, there may only be some available.
* Positions with [REQUIRES_POPULATION] require the population to have a specific size.
* Positions with [REQUIRES_MARKET] will only appear in "large" sites (which may have different rules for different site types). This tag has no effect in fort mode.
* Positions that are appointed by positions that have an AS_NEEDED number. The appointable positions only become available after an appointer position-slot is created. This works also on civ-level. If a position is appointed by a Land-holder, it only becomes available, when that level of landholder is created.

Only the replaced positions are culled and are no longer available.
A position that requires a certain population will become available, even if it doesn't have [APPOINTED_BY] or [ELECTED]. In that case, see 'automatic assignment' and 'assumption'

In fortress mode, in some cases 'succession' is evaluated immediately after a position becomes available. See: Succession.
==Visibility of positions==
A position might be available, but can still be invisible for the player in the [[nobles screen]]. The positions with their respective holders are visible for players:
* All site-positions that are already filled-in (even if they could not be re-filled-in considering current conditions)
* Site positions that are appointable by a filled-in site position
* Site positions that are appointable by a filled-in civ position, when that civ positions holder becomes a citizen of your fortress.
* Civ positions of units that are also a citizen of your fortress.
If a position becomes available, for example because a certain pop number has been reached, or if it is available from the start(like expedition leader), as long as it cannot be appointed, it still is INVISIBLE for the player.

It might strike someone as odd if a position becomes filled automatically in fortress mode when that position is not even visible. This might be the case if the current holder of a non-appointable position dies or succeeds another position. Regardless of player visibility, these positions will be automatically filled in if the necessary requisitions are met. It might happen with the expedition leader.

A situation with a non-visible but available position, is for example when a position is solely appointed by the expedition leader, when the expedition leader's position is left vacant. It can no longer be appointed by the player and is invisible. Then, it gets automatically assumed, proving that the position still was available.

A position that is both [APPOINTED_BY] and [ELECTED] is visible, but players cannot interact with it.

=[NUMBER]=
A position might be defined with a number. In that case, as many as defined can be available. If the positions become available, in world-gen and when embarking, they are all filled-in completely.

If the ruling position (with PRECEDENCE of 1) has a NUMBER higher than 1, a random unit of the ones holding these positions is shown as ruler in the embark screen.

A [NUMBER] of 0 (zero) has the same effect as 1.

==Automatic spreading of assumed, non-singular positions==
If there are civ positions that have a NUMBER higher then '1' and which are assumed (not APPOINTED_BY or ELECTED) but are '''not DUTY_BOUND''', these are automatically spread among the civilisation, based on population. If there are a number of '''20''' available slots of that position, they spread among a civilization with a combined population of, for example, 1000 of which your fortress has 100 (10%), '''2''' of your fortress' citizens will assume that position.
This may probably also work with elected and appointed positions, but that may be depending on the death of the current holders and this needs more testing. Assumption works within a day, anyway.

==[AS_NEEDED]==
These positions can be created automatically by the game in world-gen. This, however, only works with:
* [LAND_HOLDER]'s
* squad commanders (needs more testing)
* Messengers at sites

For all other types of positions, they're not created in world-gen, even if they are defined with RESPONSIBILITY's. For example, even in war, the game wouldn't create a MILITARY_GOALS position, if they have AS_NEEDED as number.

However, in fortress mode / player mode, these positions can be created by the player at will.

Positions with AS_NEEDED need to be created first, before any symbols are assignable as 'symbols' (objects) for the position holder to carry or wear.

Positions with AS_NEEDED cannot be created and then ELECTED in fortress mode. It only works with APPOINTED_BY.

=Replacement and Required Population=

The token REPLACED_BY:position means that once the replacing position reaches its required population-number, the 'to-be-replaced' position will disappear. This is defined in REQUIRES_POPULATION. These tags are closely related to each other and seem to only have a meaningful function if combined. Nobles with REQUIRES_POPULATION require the population to have a specific size.

This works on the civ-level as well as on site-level, but those systems are in this mechanic strictly separated. Site-level positions cannot be replaced by civ-level positions and visa versa. This makes sense, because they both depend on their own population-count. When using REQUIRES_POPULATION on civ-level, it counts the total population of the civilisation.

See also: [[Advanced_entity_position_mechanics#Evaluation_of_Positions|Evaluation of positions]]

==Effect of replacement (and on [LAND_HOLDER]s)==

Replacement is immediate and complete - the current holding unit loses the position, even before SUCCESSION_BY_POSITION rules are applied. A position with a number of 1 will replace all the slots of a position with a higher number of slots.

Even if the next position is available but not visible, replacement still takes place. If a position is replaced, it is completely gone - it cannot be appointed, succeeded, elected or assumed any longer.
The unit immediately loses its position.

In legends, replacement is mentioned as: "(unit name) ceased to be (position name)" The replacement of an AS_NEEDED position empties the position's slot forever. In fortress mode, it may seem as if you can create new slots and appoint new units in the nobles screen, but this is reversed as soon as you close the window.

The landholder chain uses [REPLACED_BY] differently. It does not clear the position completely, but uses it for succession to the next level's position. [REPLACE_BY] is required to let that system work properly. This also means that the way in which landholders succeed (replace + as_needed) does not work in any other way.

Replacement between LAND_HOLDERS and other site- or civ positions does not work in any way. Only the vanilla replacement sequence between levels of LAND_HOLDERs does work. If the token is omitted for landholders, the landholder chain is broken, so replacement is required for the landholder system to work.

[REQUIRES_POPULATION] also does not work for [LAND_HOLDER], when you set [NUMBER] to 1. The position is not created when the required population is reached.

==What doesn't work==

'''Attention: If a position cannot be appointed, for example because of 'mutual appointment', it still exists according to replacement mechanics and will replace other positions if so defined. If a certain position(a) will be replaced by the baron's assistant, which can only be appointed by the [LAND_HOLDER] baron, than that position(s) still will be replaced from the start of the game, even if no baron or their assistant is ever present.'''

A position that is replaced by a somehow not-fillable position, is still replaced. This counts for mutual-appointing positions, replacement by not-yet-assigned landholders, replacement by AS_NEEDED positions, or replacement by not-yet-appointed positions.

Replacement does not work if the replaced position is a [LAND_HOLDER], even with civ-positions. In that case, the LAND_HOLDER's position is not replaced. It does not matter if AS_NEEDED is used, or a fixed number, and it also does not matter what type of position the replacer is. So this only works (correctly) with positions that become available by REQUIRES_POPULATION.

={{text anchor|Evaluation of Positions}}=
The game does not continuously check whether positions should become available, elected or be [REPLACE_BY]. This is well-known behavior—for example with the [[mayor]], who does not appear automatically when the required population ([REQUIRES_POPULATION]) is reached. Instead, positions must somehow be evaluated. This applies in several other situations as well

'''Cases that require a trigger:'''
* Election of a newly created position
* Election after the current holder dies
* Automatic assumption of a newly created position (this may take up to a day)
* New citizens (such as migrants) considering available positions
* Premature succession of a newly created position

'''Cases that do not wait for a trigger:'''
* Succession following the death of the previous holder
* Automatic assumption of existing positions that have become vacant

'''Triggers that cause the game to reevaluate noble positions:'''
* Succession of a [SITE]-position due to the death of the current holder
* [[Advanced_entity_position_mechanics#Election_Day|Election Day]]
* Automatic assumption of a [SITE]-position that becomes vacant
* (Re)assigning any site position manually
* Settlement elevation on the LAND_HOLDER track (e.g. gaining a [[Baron]] or [[Count]])

=Gaining a position=
There are several ways a unit can gain a position:
* Appointment: A unit is appointed by another unit or by the player.
* Election: A unit is elected by and among the members of the entity
* Assumption: A position is neither elected or appointed: a random unit just simply 'takes' the position
* Succession: a unit is the valid successor of this position(A), either by its current position(B) or because they are that position(A)-holder's heir.

Available positions will automatically be assigned to a random civ member when a new site/civ is created.

==Who can take a position==

* If so defined, a unit needs to be the right caste and/or class - it does not seem to work with creature types.
* The unit needs to be an adult member of the site or its parent civ-government; that is also CAN_LEARN or INTELLIGENT (SLOW_LEARNER cannot take positions) or otherwise is able to think.

==Appointment==

Positions that have an [APPOINTED_BY:position] token require that position to exist, to be available and appointed. Any position that is APPOINTED_BY can be appointed if the appointer's position is filled in.
For site-positions to be appointed, it is required that the appointer is present at that location.

If the appointing unit is temporarily not present, or if that position is not filled, positions depending on it cannot be appointed. This is the case with [[militia captains]], when the [[militia commander]] is on a [[mission]].

A site position cannot appoint a civ position ''or'' LAND_HOLDER in any way whatsoever.

Civ-level positions can appoint other civ-level positions and site-level positions can appoint other site-level positions.

Contrary to what has been said elsewhere, civ-level nobles also can appoint site-level nobles. They need to be at the site to do so. Landholders can appoint both site-level and civ-level nobles. These systems are therefore not as separate as was assumed.

'''Mutual appointment''' cannot take place. If these are the only requisites of the position, then the positions will never appear or get filled. These unfillable positions can be put to good use, for example, to replace a position that is no longer needed without creating a new one.

'''Self appointment''' doesn't normally work. If you have a position that is only appointed by itself, it is never appointed and also cannot be assumed. However, if the position has a number higher than 1, and is filled by multiple units (for example by another position that is now empty), than those units can re-assign or appoint each other from that their shared position.

If an APPOINTED_BY token refers to a non-existing position's code, the effects are as if the appointment token doesn't exist at all.

===Automatic appointment in world-gen and on the civ level===

Outside of fortress mode, the game will always attempt to appoint nobles whenever possible, as long as these positions are '''available''', even if they are invisible to the player.
It shows this message in legends: "(unit name) has been appointed to the position of (position name)"

In world-gen, all positions become available and are automatically appointed, taking population- and appointment-requirements into consideration.

Positions that are REPLACED_BY are culled and won't be filled.

If a citizen of your fortress holds a civ-level position that can appoint another civ-level position, the appointment will happen automatically and without player intervention. It may happen that another citizen of your fortress is appointed by that unit, creating civ-level position holders in your fortress, but it is unknown what is required to force this effect.

===Manual appointments by players in fortress mode===
In fortress mode, the positions that need to be appointed stay empty on embark. and it is the player's job to appoint those. A player can appoint a unit to any available position, according to the hereabove mentioned conditions. The player takes the role of the automatic appointment-system, but has no direct control over elections, successions and replacement. There are some differences in what is possible at world-gen sites and at player-controlled sites.

* A position that is appointed by a unit present as a fortress citizen, can be appointed, re-appointed or left vacant. This means also by civ-level nobles living as a citizen in your fortress; not when they are only visiting, like the diplomat.
* A position whose appointing positions are all either vacant or [REPLACED_BY] can no longer be appointed. If the position is already filled, it cannot be reappointed or vacated; the current holder simply remains in office.
* A position that is APPOINTED_BY a unit present as the land_holder of your site, can be appointed, reassigned or left vacant.
* A position that has SUCCESSION BY_HEIR or BY_POSITION can 'initially' be appointed and also re-appointed or left vacant, but as soon as the [[nobles]] screen closes, ''it can no longer be replaced or left vacant''. From then on, the succession-rules determine who gains that position when the current holder loses the position. This works even if the SUCCESSION:BY_POSITION-position is vacant or replaced.
* A position that is ELECTED nor APPOINTED_BY, can always be (re-)appointed by the player. This is the case with the [[Expedition leader]]. If it is left vacant however, it cannot be appointed, but will be assumed shortly after.
* A position that is both ELECTED and APPOINTED_BY, cannot be appointed by the player. Contrary to world-gen sites, its slot is visible, but it doesn't show the +-sign. This is either by AS_NEEDED or by a fixed number. Even if the position somehow gets filled (re)assignment is never possible
* A player can appoint a number of units to a position, as much as the NUMBER token dictates. If it is AS_NEEDED, the player may create as many slots as they like, also contrary to world-gen sites.
* A civ-position can never be appointed, even if the appointing civ noble is a citizen of your fortress. A civ position also never can be re-assigned or left vacant, would that position be defined as appointed by a site-position.

==Election==
Read more in [[Elections]]. The message that is shown is: "(creature name) has been elected to the position of (position name)"

In worldgen, there is no functional difference between ELECTED and non-appointment, except that elected nobles tend to have high social skills and/or skills related to the position, while non-elected ones are assigned randomly. See: [[Elections]]

A succession goes before an election.

A position that is both ELECTED and APPOINTED_BY never gets elected. Even if the appointees' position somehow gets filled, (re)-elections won't happen. So, it doesn't seem possible to have an elected position become available when a certain other position becomes filled.

An ELECTED civ-(or LAND_HOLDER) position at your site will never be (re)-elected in fortress mode. So real (re-)election only works with SITE-positions.

=== {{text anchor|Election Day}} ===
Election Day takes place on the 17th of Summer. On this day, a full reevaluation is performed, including all currently elected positions, which are subject to re-election. Contrary to the information on [[Elections]], nothing occurs at the start of a season.

Positions that are both [APPOINTED_BY] and [ELECTED] will not be re-elected on Election Day when assigned through [SUCCESSION].

=== Election Eligiblity ===
Any citizen may stand for election. Eligibility cannot be restricted using [ACCEPTED_CREATURE], [REJECTED_CREATURE], [ACCEPTED_CLASS], [REJECTED_CLASS], or [GENDER]. Units currently having a [SUCCESSION]-position even may be elected for a position with a [SQUAD]-token, which is otherwise impossible to assign or even succeed.

=== Skills ===
In elections, skills are taken into account for the tokens of the position which is elected.
{| class="wikitable"
|+ Relevant skills per position token
|-
! Position Token !! Relevant skills
|-
| Responsibility [[Position_token#DELIVER_MESSAGES|[DELIVER_MESSAGES]]] || [[Ambusher]], [[Observer]] and [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#ACCOUNTING|[ACCOUNTING]]] || [[Record_keeper|Record keeper]]
|-
| Responsibility [[Position_token#ESPIONAGE|[ESPIONAGE]]] || [[Schemer]]
|-
| Responsibility [[Position_token#HEALTH_MANAGEMENT|[HEALTH_MANAGEMENT]]] || [[Diagnostician|Diagnostician]]
|-
| Responsibility [[Position_token#MAKE_INTRODUCTIONS|[MAKE_INTRODUCTIONS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#MAKE_PEACE_AGREEMENTS|[MAKE_PEACE_AGREEMENTS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#MAKE_TOPIC_AGREEMENTS|[MAKE_TOPIC_AGREEMENTS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#MANAGE_PRODUCTION|[MANAGE_PRODUCTION]]] || [[Organizer]]
|-
| Responsibility [[Position_token#MEET_WORKERS|[MEET_WORKERS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#RECEIVE_DIPLOMATS|[RECEIVE_DIPLOMATS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#RELIGION|[RELIGION]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#TAME_EXOTICS|[TAME_EXOTICS]]] || [[Animal_trainer|Animal trainer]]
|-
| Responsibility [[Position_token#TRADE|[TRADE]]] || [[Social_skill|Social skills]] and [[Appraiser|Appraiser]]
|-
| [[Position_token#SQUAD|[SQUAD]]]-token || [[Tactician]] and [[Leader]]
|}

==Assumption==

A position that is not APPOINTED_BY nor ELECTED, or is appointed by positions that are not available in your site or civ, will be assumable by a random dwarf. If it has responsibilities that require certain skills, then these are taken into consideration on embark, but not when the position is assumed during the actual game.

Normally, one to three units will take the into consideration to assume a position. Most of the time when there are multiple open positions, only a single unit will assume all of them. However, a position that has REJECTED_CREATURE, REJECTED_CLASS, ALLOWED_CREATURE or ALLOWED_CLASS will be filled with all different units, even if the creature or class mentioned is irrelevant. It seems that this forces the game to loop over all the available units.

The message that is shown in Legends mode is: "(unit name) has assumed the position of (position name)". This may also take place in fortress mode, which then shows this message to the player.

If an assumable position becomes empty, it will be assumed within a day. This is the case when you leave the position of expedition-leader vacant. It also happens with entities.

Assumable positions that become empty will not be assumed if that position has a valid [SUCCESSION] -successor. In that case, the successor inherits the position.

Even positions that are somehow invisible because they cannot be directly APPOINTED_BY players, can be assumed.

When you embark, the assumable positions are automatically assigned to a random unit. If there are multiple of these positions at embark, they all are assigned to the same unit. If there are enough positions available, multiple units may gain a position, but often no more than three different ones.

If a dwarf in fortress mode assumes a position, that already has another position, it will leave the current position empty. When that position also is assumed, then this will continue until all positions have a dwarf appointed to them, with no other position.

A unit that already has a position with a [SUCCESSION] token won't take assumable positions into consideration that have a [SQUAD] token. This can be used by the modder to prevent unwanted loss of current positions.

A position that has an appointer which got replaced because of REPLACED_BY, will not become assumable. Also, positions that have an AS_NEEDED appointer that is not yet filled (or ever), will also not be assumed.

==Succession==

If a position-holder dies or advances to a new position via succession, the position will be granted to another unit based on the [SUCCESSION] tag. If they have an heir or the succeeding position exists, that unit will be assigned. If not, a new one will be appointed according to the usual rules. The message that is shown is: "(creature name) being the rightful heir, has inherited the position of (position name)"

The succeeding creature will also lose its previous position. When succession is defined using BY_POSITION, the unit naturally loses the referenced position. However, it also loses any other positions it may hold. If a unit could simultaneously inherit multiple positions, the last-defined succession overrides the earlier one, clearing the previously acquired position

Succession works both at site-level and at civ-level, both in world-gen and in fortress-mode. Succession by position on the civ-level is also visible and functional in fortress-mode. If both civ-level nobles are a citizen of your fortress, succession is applied visually. Vanilla example: The [[druid]] is succeeded by the [[acolyte]]. This means that as soon as the druid dies, the acolyte takes over.

When a position that is succeeded by position becomes available, immediately it is checked if a position-successor is available and the position is filled with that unit. Even if this is an [ELECTED] position, succession goes first. When elections eventually do happen, succession plays no role.

It is possible to assign multiple levels of [SUCCESSION:BY_POSITION] in different positions, creating a line of positions where the death of one causes all those "below" them to advance.

A position can have multiple tokens with position-succession. It looks to be random which one is used. It is not always:
* The first or last defined token
* The first or last appointed unit
* the oldest or youngest
* one with a higher or lower precedence
* a unit with relevant skills

When a position is defined with a Succession-type, that unit cannot have another position that has a Squad-type. If the succession-position itself has a squad, than it can be assigned another position with a squad, but then it will loose the previous succesion position. See further details by "Squad"

Assumed positions can also be succeeded by position, if the current holder dies.

If the successor is an AS_NEEDED position, the used unit will leave a vacant position-slot on its removal by succession. This empty slot remains a real slot, which will only be cleaned up if you (un)appoint a unit to this position-series. It isn't cleaned up after regular position validation.

A civ-level position of a unit living at your site might be inherited by a unit holding that does not currently live at your site. This, unfortunately, moves that position to a unit off site. This may also happen with the landholder of your site, for example when it is succeeded by another civ-level position. This currently poses an unsolved challenge.

===Eligibility for succession===
Succession is restricted by the tokens [ACCEPTED_CREATURE], [REJECTED_CREATURE], [ACCEPTED_CLASS], [REJECTED_CLASS] and [GENDER].

===Site and civ combined succession===

Succession can work when combining site positions with civ-level positions or land_holders, but only in world-gen mode. In fortress mode, it only works with combining the same level of nobles, with Landholders regarded as civ-level. So, in fortress mode, a site's position cannot succeed a landholder's position and it cannot succeed another type of civ-level position, and vice versa.

This won't work even if the positions:
* are AS_NEEDED or having a fixed number.
* Are LAND_HOLDERs.

===Succession [BY_HEIR]===

When a heir is needed for succession, all children and then other relatives are validated. They cannot take the position if their status does not allow it, for example if they have become a member of another civilisation. See: "Who can take a position". If the unit has no valid heir on that location, the position may go to a unit living on another site. This may cause the title of Landholder of some land to be inherited by a unit living somewhere else. That might be a problem, because then you lose your landholders.

===Premature Succession===

There are cases where [SUCCESSION:BY_POSITION] is applied prematurely: at the moment a position is first created and becomes appointable or assumable, rather than after a current holder leaves. In this situation, the succession mechanism assigns a holder immediately, without any player interaction.

When a position becomes available for the first time, the game checks whether a valid successor-by-position exists. If so, that unit is assigned instantly. It can affect positions that would normally be appointed or elected by the player, causing succession to trigger before the player has any opportunity to intervene.

This behavior occurs only in Fortress mode, but can be applied both on [SITE]-positions as well in civ-positions. That last one however is a bit harder to control. Example: [[Advanced entity position mechanics#The Archduke|The Archduke]]

This premature succession only occurs the first time a position becomes available (i.e. when it is created and becomes appointable or assumable). Even if the position remains vacant and the conditions for succession improve later, premature succession will not trigger again. From that point onward, only normal succession rules apply.

Using premature succession, a position that has [ELECTED], [APPOINTED_BY], or both, can be filled directly.
Notably, positions that combine [ELECTED] and [APPOINTED_BY] are normally impossible to fill through regular mechanics. Premature succession bypasses both election and appointment entirely, making this combination uniquely reachable through this mechanism.

No initial election takes place, and no subsequent elections will ever occur for that position. Succession always takes precedence over election, both in premature succession and in normal succession cases.

This behavior applies only in Fortress mode, not during world generation. World-gen uses simplified and more efficient mechanics, and this interaction does not occur there. Premature succession can affect both site-level and civilization-level positions.

====Multiple succession chains====

Multiple succession chains may be defined and are resolved in the order they appear in the raws.

If a position has both:
* a direct succession chain (A → C), and
* a multi-step chain (A → B → C),

and intermediate positions are vacant, resolution proceeds according to raw order. A common outcome is:
# The direct succession (A → C) is applied first, assigning A to C.
# The remaining chain then advances (A → B).
# If C still has empty slots, the final step (B → C) may occur.

If position B is already filled, behavior depends entirely on raw definition order:
* nothing may happen, or
* B may move to C first, followed by A moving to B.
====Working triggers====
Premature succession is triggered when a succeedable position is created under the following conditions:
* The succeedable position is created because its [REQUIRES_POPULATION] threshold is reached. This applies even if the position is not [APPOINTED_BY]. Premature succession takes priority over automatic assumption (e.g. the mayor declaring themselves within a day).
* The succeedable position can be [APPOINTED_BY] another position of the same level (site or civ) that has just been created because its [REQUIRES_POPULATION] was reached.
* The succeedable position can be appointed by another [SITE] [AS_NEEDED] position that has just been created and filled.
* The succeedable (site or civ) position is [APPOINTED_BY] the [LAND_HOLDER] position, which has just been created due to site elevation. This typically resolves when the diplomat leaves the map, at which point the landholder position becomes active.
* If all other requirements are met, premature succession can occur immediately after unpausing following embark, for positions with [REQUIRES_POPULATION:7].
====Non-working triggers====
Premature succession does '''not''' occur in the following cases:
* An [AS_NEEDED] succeedable position slot is manually created by the player while its succeeding position is already filled. [AS_NEEDED] positions must always be appointed after creation.
* The succeeding position is filled after the succeedable position becomes available. The moment of creation is the decisive trigger; filling the source position later is too late.
* The succeedable position can be appointed by another site or civ position with a fixed number of slots that has just been appointed. In this case, the succeedable position is just available for appointment itself, nothing more
* Any situation occurring during world generation.
* The succeeding position is [REPLACED_BY] the succeedable position. In this case, replacement removes the unit from the source position first, leaving no holder available for the succession mechanism to use.rst, leaving no holder available for the succession mechanism to use.
* The position is [APPOINTED_BY] a civ-level position, that just became a citizen of your fortress. It must be noted that those civ-level positions were active all that time and the succeedable position could be appointed even before. The monarchs arrival does not trigger premature succession

=Losing a position=

A unit can lose a position when:
* It dies
* It succeeds another position, even if it has nothing to do with the previous position.
* It is assigned to another SQUAD-holding position
* It is convicted of a crime.
* Another unit is ELECTED for the position
* Its position becomes replaced
* Another unit is appointed by the player, or the position is left vacant.
* It has assumed another position, as this always leaves the previous position vacant.

=Embarkment=
Two types of positions are automatically filled by embark.
* Positions without [APPOINTED_BY] or [ELECTED] (assumable). All these positions, even with a NUMBER higher than 1, are all filled with one to three dwarves. Contrary to assumption, this doesn't take into account any limitations. REJECTED_CLASS, ALLOWED_CLASS, REJECTED_CREATURE, ALLOWED_CREATURE and GENDER are applied, but without the normal spread you may expect with assumptions. Also it doesn't look at [SUCCESSION] and [SQUAD] limitations.
* Positions that are elected are filled-in by the normal election rules.

Positions that have a defined appointer are never initially filled at embark.

All positions that don't have [REQUIRES_POPULATION] or with a [REQUIRES_POPULATION] of 7 or lower, will be available at embark.

=Land Holders=

A Landholder is a '''special civ-level noble''' who gets a certain piece of land to hold, when that land is elevated to a certain level, determined by the tag [LAND_HOLDER] and by the landholder triggers in the game's settings. In vanilla, these are the baron, the count and the duke.

A unit gaining the landholder position does not migrate to that specific named land. In world-gen, they stay just where they are, probably at the capital. In fortress mode, you can suggest a citizen for the role. So for the time being that works.

Succession is then a real issue. If you use BY_HEIR, its solved when that landholder has children living at your site. But when its not the case, the title just goes to anyone randomly. Succession BY_POSITION works, but only in the civ-chain, and there's no way to guarantee a civ-holder is at your site at that time. Even with 'automatic spread' positions, it goes to one of them randomly.

==Functioning of the regular landholder chain==

The distinct difference between a landholder and a regular civ-level noble, is that a landholder may gain the position of landholder "of (sitename)" They are then seen as ruler of a particular site.

For a land_holder position to function as such, it has a few requirements:
* NUMBER:AS_NEEDED
* The first landholder-number of 1 is defined.
* No SITE (so civ) tag in that position.
*REPLACED_BY the next level landholder
If a landholder is defined with differentiating properties, it will function like a regular noble. A higher-up landholder that lacks the required tokens or connections will then not be used in elevation.

If a fortress meets the trigger for a new LAND_HOLDER tier when a caravan leaves, then the next time the outpost liaison or equivalent arrives, they will offer to make you an official colony, which will allow you to select all positions for that LAND_HOLDER level. Each time they appear, the outpost liaison will only promote your fortress one tier up the LAND_HOLDER track.

The landholder's LAND_NAME is not required for the functioning of this system. If omitted, messages will be shown with a more generic text.

==Appointment==

This mechanism differs from the regular methods of position management. It ignores all regular appointment- and election rules, so it more or less functions like automatic assignment. A landholder is, in vanilla, appointed by the monarch. Changing this doesn't seem to do anything. If they are appointed by a site-position, a not-yet-existing civ-position, or not appointed at all: the system keeps working as usual.

A landholder can appoint civ-positions and site positions. This works as expected: the positions only are appointed then when that landholder becomes available on civ-level or when he arrives at that site for site-level positions.

If your rank of landholder is the first of its rank in the realm, and is the sole appointer of some civ-position, then immediately as it gains the title, it will appoint the empty civ-slots. This may happen on your site, but the frequency and certainty is hard to determine.

==Succession==

Succession rules are applied to some extent:
* In world-gen it works according to succession rules, and site-positions can be used here. This means that a site position or a civ-position can inherit a landholder position, and vice versa.
* In fortress mode, once a landholder has been appointed, it then can inherit civ-level positions, and vice versa. This means that your baron can become king.
* Succession rules do not apply within the [LAND_HOLDER] chain; a count will not inherit a baron's land. This is because succession does not work well with the AS_NEEDED token.
* Premature succession works in fortress mode with landholders. If a unit gets a landholder's position and that landholder is the appointer of an as yet empty position, which is defined as succeeding from a third one, then the succession is immediately applied. The landholder themselves can even be the successor of a newly created position.
* A landholder's position is, in fortress mode, not successionable by a site-position or vice versa

===Impossibilities for succession by a site-position===
It would be very beneficial if the landholder can be succeeded by a [SITE]-position. So far, the following tests have not lead to positive results:
* making landholder and site-position both non-[DUTY_BOUND]
* make the site-position be [APPOINTED_BY] the landholder and/or the monarch
* give landholder and site-position [REJECTED_CREATURE]
* Let the monarch live at your site when succession could happen.
* Let the site-position be [REPLACED_BY] the landholder.

==Nomination==

The player is able to nominate a unit to become the LAND_HOLDER, but this only works with units of [LAND_HOLDER] level 1. The player can select all units, only limited by the PRECEDENCE of the current units' positions.

A unit that has a position with a PRECEDENCE lower or equal to that of the landholder's position, cannot be selected. This means that a baron (or count) from another site or the monarch cannot be selected, because their precedence is lower or equal.

The GENDER token does not work here: also units with the wrong gender (sorry) can be selected.

==Levels==
In mods, up to 10 levels of LAND_HOLDER may be defined.

If a landholder is replaced by a wrong landholder number (1 replaced by 3), then the number 3 is still correctly attached to the settlement.

If the current landholder has the highest available landholder number, then the next elevation will not happen - the diplomat will not elevate your fortress to a higher position, even if that position might be REPLACED_BY a lower landholder.

These chains do work:
* 1 -> 2a - > 2b -> 3
* 1 -> 3 -> 2 -> 4

These chains do not work:
* 2 -> 3 (need to start at 1)
* 1 -> 4 -> 2 -> 3 (stops after 4 as the highest)
* 1a -> 2, 1b -> 2 (only 1a and 2 work, 1b is not used)

==Moving landholders==

It may happen that a land-holder no longer lives at the site which they are the landholder of, specifically when the current landholder dies, leaving the title to an heir living somewhere else.

To prevent this from happening, you can make their succession from heir and make sure that their kids live at your site. Or, you can make their position succeeded by another civ position, and make it so that this civ position is somehow available on your site. But if multiple of these positions exist, it cannot be guaranteed that a citizen of your fortress will inherit the title.

In world gen, a landholder lacking the DUTY_BOUND-token will also move to the site they like, according to legends mode.

==Replacement by a generic civ-position==

If a landholder is replaced by an AS_NEEDED non-landholder civ-position, then this will work: the current landholder loses that title upon settlement-elevation and gains that civ-title. However, the civ-title lacks the landholder-property of being attached to the land. It will not show the name of the settlement alongside the position's name. So no "minister of Shovelmounts"

If a landholder is replaced by a general AS_NEEDED civ-position, that itself is also replaced by a generic AS_NEEDED civ-position, then firstly the elevation is executed and also the unit gains that new position. However, he immediately loses it, because an AS_NEEDED position that is replaced by another position can be filled initially, but units wont be able to hold that title.

==Landholder with fixed number==

A landholder's position that has a fixed number will be created and filled directly when the civilisation is born, so this position slot is then not available for the regular landholder-mechanic and will also not be used. That landholder will thus not be attached to a settlement.

It doesn't matter if the landholder's position is connected to the regular landholder's-chain with the REPLACE_BY token.

==Responsibilities==

When given a certain [RESPONSIBILITY], a landholder may function as a regular civ-level noble. If the position has [TRADE] or [OUTPOST_NEGOTIATING] responsibilities, then the landholder functions both as a diplomat and as an actual land holder. A landholder with the [MILITARY_STRATEGY] responsibility will travel around taming creatures in world-gen, according to legends mode.

Besides that, the responsibilities work the same as with any other on-site living position-holder, civ or otherwise.

=Military=
==Squad management==
In the vanilla game, the Squad interface only becomes available after a militia commander has been appointed. Until then, the window displays:{{DFtext|You must appoint somebody first to create a squad.}}

What’s surprising is how this is determined internally. In the entity raw definition, '''only the last two positions that include a [SQUAD] token are checked''' to decide whether the interface is accessible at all. As a result, if your hierarchy defines commanders A through E, appointing '''Commander D or E''' unlocks squad formation, while appointing A–C does nothing.

In other words, squad availability is not tied to ''having a militia commander'', but to ''which specific positions happen to be last in the raw list''—a notably hacky implementation.

These 'last two' are always the last two '''available positions.''' So if they get [REPLACED_BY] or become available because of [REQUIRES_POPULATION], the game adapts to those.

==Squad assignment==

Squads can be assigned, even if the leader position has no holder.

A specific unit can only have one position associated with a squad. If it gains another 'squad holding position', it is unassigned from the first one. This does not work with a 0-squad, so only 1+squads are taken into consideration. This technique can possibly be used to distribute all positions equally among all citizens. It does however not work with election and assumption.

If a civ-level position is associated with a squad and it gets a site-level squad-holding position assigned, it loses the current civ-position.

Squads can get really messed up, if you make the position (or multiple) either elected or not-elected and not-appointed, then this can cause the game to assign multiple squads to the same unit. Automatic assignment and election does not take squads into account, but the nobles screen does. This can cause the positions to be cleared as the game figures out that they have more than one position, and immediately get elected or assumed again.

Positions that cannot have a squad-position:
* A site- or civ-position with a [SUCCESSION] token cannot be appointed a squad-holding-position. The other way around, however, does work. For example, if a site-position with a [SUCCESSION]-token is appointed to a unit that has already a position with [SQUAD]. But when that squad position is assigned to another unit, it cannot be assigned back.
* A position with [SUCCESSION] can also not be assigned as a '''member''' of a squad.
* A squad-holding position with a formed squad cannot be appointed to another squad holding position.

If a position has at least one squad member, it cannot be left vacant. First, the squad has to be disbanded, then the position may be cleared.

==0-squads==
A 0-Squad is defined in a position as [SQUAD:0:member:members]. It does not seem to do anything useful as of now.
* It cannot be used to activate the [[Squad|military interface]]
* It does not restrict the assignment of [SUCCESSION] positions.
* Assigning this position does not clear any previously held squad position.
* The [[Leader]] and [[Tactician]] skill are not marked as relevant skills and are not taken into account in elections.
* It cannot be formed as a squad.

=Further testing=
The following questions may need additional testing. Feel free to add or answer
* Everything regarding COMMANDING and army-structure
** [http://www.bay12forums.com/smf/index.php?topic=175437.msg8331668#msg8331668]
** [http://www.bay12forums.com/smf/index.php?topic=165213.msg8335682#msg8335682]
** [http://www.bay12forums.com/smf/index.php?topic=174584.msg8026854#msg8026854]
* Everything regarding CONQUERED_SITE, but it is presumably just like site. But what if you combine SITE or LAND_HOLDER with it?
* Stuff about the monarch, its arrival and its entourage.

=Oddities (Bugs)=
Almost everything on this page could be called an oddity. Because of their unexpected usability, some may also be referred to as “undocumented features.” Others, however, are simply odd and not particularly useful, yet I hesitate to call them “bugs.”
* If a certain threshold is reached that makes an elected position electable, and the triggering event that initiates this evaluation is an assumption, then the resulting assumption is also referred to in the messages as an election

=Examples=

===The Founder===
The founder is a single dwarf, appointed at embark. They will be the only one ever to have this position and are not replaceable. When they lose their position some way, the position will not be assumed by another dwarf.
{{gamedata|title=The Founder|
[POSITION:THE_FOUNDER]
[NAME:the founder:founders]
[NUMBER:1]
[SITE]
[ALLOWED_CREATURE:DWARF:ALL] - will only be filled at embark, but not assumable later.
[REJECTED_CREATURE:DWARF:ALL] - will only be filled at embark, but not assumable later.
[SUCCESSION:BY_POSITION:THE_FOUNDER] - not unassignable, also cannot be assigned to a [SQUAD] position.
[PRECEDENCE:200]
Non APPOINTED_BY
Non ELECTED
Optional: Add responsibilities to make the game select a unit with certain skills.
}}
===Marriage bar===
Dwarven matrons are held in great honour. Upon marriage, a female dwarf is no longer expected to perform menial labour. All dwarven males hold this position by default, granting their spouses exemption from menial work.

The position becomes available with the arrival of the first migrants; otherwise, on embark, it would be assumed by females. Its succession rule is non-functional, but this prevents the player from unassigning the position. A squad size of 1 and the succession rules together prevent a unit from assuming the position more than once.

With precedence set to NONE, the position name is hidden, while LAND_NAME remains visible on the nobles screen. All married females receive the suffix “, Mrs.” and are marked as Nobles.

The practical usefulness of this position is debatable, but it serves as a clear demonstration of several mechanics.
{{gamedata|title=Mrs. Urist|

[POSITION:MRS_URIST]
[NUMBER:300]
[SITE]
[ALLOWED_CREATURE:DWARF:MALE]
Not APPOINTED_BY
Not ELECTED
[LAND_NAME:Dwarven male]
[NAME:dwarven male:dwarven male]
[PRECEDENCE:NONE]
[SPOUSE_FEMALE:, Mrs.:spouses]
[MENIAL_WORK_EXEMPTION_SPOUSE]
[REQUIRES_POPULATION:8]
[SUCCESSION:BY_POSITION:MONARCH]
[SQUAD:1:member:members]
}}
===The Archduke===
The archduke is the leader of the civilization, but exists only from landholder 4-level. Until then, its position remains vacant. When a settlement is elevated to tier 4 (grand duke), the grand duke can appoint the ruler of the civilisation, the archduke. Because of 'Premature Succession', they themself inherents that position immediately, but only when in fortress mode. Its heir then becomes grand duke.
{{gamedata|title=The Archduke| no POSITION:MONARCH or other PRECEDENCE:1

[POSITION:THE_ARCHDUKE]
[NAME:archduke:archdukes]
[NAME_MALE:archduke:archdukes]
[NAME_FEMALE:archduchess:archduchesses]
[LAND_NAME:a archduchy]
[NUMBER:1]
[PRECEDENCE:1]
[SUCCESSION:BY_POSITION:GRAND_DUKE]
[APPOINTED_BY:GRAND_DUKE]
(add additional monarch-stuff, like spouse name, demands etc.)

[POSITION:GRAND_DUKE]
[NAME:grand duke:grand dukes]
[NAME_MALE:grand duke:grand dukes]
[NAME_FEMALE:grand duchess:grand duchesses]
[NUMBER:AS_NEEDED]
[LAND_HOLDER:4]
// Optional ...
[PRECEDENCE:19]
[LAND_NAME:a archduchy]
[RESPONSIBILITY:LAW_MAKING]
[RESPONSIBILITY:RECEIVE_DIPLOMATS]
[SUCCESSION:BY_HEIR]
[APPOINTED_BY:THE_ARCHDUKE]
(add additional landholder-stuff)

!!add to [POSITION:DUKE]
[REPLACED_BY:GRAND_DUKE]

}}
{{Category|Modding}}
{{Category|Entities}}
{{Category|Guides}}

Advanced entity position mechanics

2026-02-10T10:36:39Z

Joostheger: /* The Archduke */

{{Quality|Fine}}
{{Modding}}

= Introduction =

[http://www.bay12forums.com/smf/index.php?topic=182239.0 Discussion thread on the forum]

This page documents observed and tested behavior of entity positions in Dwarf Fortress that is not fully described elsewhere on the wiki. It focuses on advanced interactions between position tokens, including appointment, succession, election, and responsibility handling, across both civilization-level and site-level entities.

The mechanics described here are based on empirical testing in world generation and fortress mode, supplemented where necessary by raw analysis. In several cases, the game’s behavior is determined by evaluation order and interaction between multiple tags, rather than by individual tokens in isolation.

This page is intended for modders and advanced players who are designing or debugging custom entity position structures. It does not restate basic position mechanics, but instead highlights edge cases, non-obvious interactions, and behaviors that may appear inconsistent or undocumented.

Unless stated otherwise, the described behavior applies to current versions of the game and may differ from older releases.

==What is an entity? What is a position?==
An [[entity]] is an organizational structure that can have relationships with other entities, usually known as a [[civilization]] or a "[[site]] government" in the game, but merchant [[guild]]s, religious organizations, necromancer towers, and [[bandit]] groups are also entities. An entity can have positions - in most cases, these are hardcoded and generated by the game, but as for civilizations and sites, the [[raw file]]s can be customised.

A position is a special relationship between a unit and an entity. The unit holding a position has a larger influence over that entity than other citizens. Positions are mostly known as [[nobles]], but in this article. the technical term is used.

=Position levels (Site/Civ) and their interaction=
There are two basic types of positions that are customizable: '''civ(ilization)''' level and '''site level'''. Positions with the tag [SITE] are at site level, positions without the tag [SITE] are at 'civ level'. These two types of nobles can be considered '''loosely related systems'''. There are a few places where they can interact with each other.

Civ-level positions are in charge of the civilization as a whole, managing national [[trade]], laws, and [[war]]s. These are, for example, the vanilla [[monarch]], [[diplomat]] and [[general]]. (Note that the general doesn't do anything in either mode in the current version.)

'''[LAND_HOLDER]''' nobles are also positions at civ-level. These units are members of the national government, but have gained authority over some land or site. Once they do, they move to that place, but their position is still regarded as a civ-level position.

Site-level position holders are members of a site government (subsidiary to the civilization), and manage local affairs in that location. These are, for example, the [[mayor]], the [[sheriff]] and the [[broker]].

==Table of interaction between different position levels==
In this table, the possible interactions between different position levels are summarized.
The header row shows the positions defining the tokens.

The left column shows the position type that is referred to.
Example:
{| {{prettytable}}
|- bgcolor="#ddd"
! referred position-type
! LAND_HOLDER
|-
| civilization
| (baron is) APPOINTED_BY:MONARCH
|}
color coding: 
* Exists in vanilla
* Possible with mods
* Not possible
* possible to some extent.
* not yet fully investigated.
{| {{prettytable}}
|- bgcolor="#ddd"
! referred position-type
! Civilization
! SITE
! LAND_HOLDER
! CONQUERED_SITE

|-
| Civilization
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION '''(1)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION

|-
| SITE
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION '''(2)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY '''(3)''' COMMANDER REPLACED_BY SUCCESSION '''(4)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION

|-
| LAND_HOLDER
| APPOINTED_BY COMMANDER REPLACED_BY '''(6)''' SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION '''(5)'''
| APPOINTED_BY COMMANDER REPLACED_BY '''(7)''' SUCCESSION '''(8)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION

|-
| CONQUERED_SITE
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
|}

Remarks:
# Works only in world-gen, if a unit with that civ-position is present at the site.
# Works only in world-gen, the site-position holding unit will then move to the capital.
# Is completely ignored
# Works only in world-gen.
# Works only in world-gen.
# Won't appear at all
# This is necessary for the landholder chain to work properly, it doesn’t work otherwise.
# This works only outside of the landholder chain, so when landholders are simply regarded as civ-level nobles. might also work in world-gen
#

== Other interactions ==

Unfortunately, interactions with positions of other entities don't seem possible, such as APPOINTED_BY: HIGH_PRIEST. With [VARIABLE_POSITIONS], positions are automatically created with codes like CUSTOM_LAW_MAKER_2, but interaction with these positions don't seem to work, either. For more info on those, see [[Variable positions]]

=General=

==Civ-level nobles living at your site==
Nobles from your civilization can come to live at your fortress. This happens in vanilla with landholders such as [[Baron]], [[Count]] and [[Duke]], with the Monarch, but sometimes also with non-landed LAND_HOLDERS.

When a civ-level noble becomes a [[citizen]] at your location, their position is shown among the site-level positions in your [[nobles screen]]. They appear to function as a site-level noble. They may have [[demand]]s, [[mandate]]s, [[squad]]s and the like. They can appoint nobles at the site-level.

If they have certain [RESPONSIBILITY]ies, they do the tasks that go with them.

==Fortress mode, world-gen and their differences==
Their are a few differences in how positions function between fortress mode (normal play mode) and the world generation (world-gen).

In '''fortress mode''', the player has some control over the appointment of nobles, limited by elections, automatic filled-in positions and succession rules. Pre-fortress mode, which is referred to as '''world-gen''', the game will always attempt to assign nobles whenever possible. It is subjected to the same rules as in fortress-mode, but there are some exceptions. In '''[[World activities]]''', which is the thing that happens in the world while you play fortress mode, it seems as if the same rules are applied as fortress mode.

A difference between player-fortress-mode and world-gen, is causes by visibility (see below). Positions that are not visible by the player and thus not available for assignment, will be available in world-gen and will thus be automatically assigned.

In fortress mode, a position that is both [ELECTED] and [APPOINTED_BY], cannot be appointed by the player and is also not elected, and can thus not be filled. But in world-gen sites however, these positions are automatically filled.

Positions with [AS_NEEDED] are almost never created and filled in world-gen (depending on their [RESPONSIBILITY]ies), but can always be used in player mode.

A position can, in fortress mode, be filled by the same unit. A unit can gain multiple positions in fortress mode, for example because of [[elections]]. This will not happen in world-gen mode: a unit can only have one position. See also remarks on 'embark' and 'Losing a position'.

In world-gen, [SUCCESSION] between civ-levels and [SITE-]levels may happen. This will not happen in fortress mode, or even off-site in [[World activities]].

In fortress mode, premature SUCCESSION may happen. This will not happen in world-gen mode.

==Units holding multiple positions in multiple entities==
A unit can hold multiple positions in its civilisation or in its site-entity, however this does not happen in world-gen. Only at player-managed sites can units be holding multiple positions at once. (It is probably not possible for a unit to hold a position in two different civilisations or two different sites.)

In world-gen, if there are too many positions to be filled, they simply stay empty until more units are available. E.G, a unit at a site might inherit a civ-level position and still remain a member of the local government. When this happens however, they move to the capital. If a unit gains a new position, either inherited or otherwise, it drops the previous one. If a unit assumes a civ-position in fortress mode, it leaves the current position.

If a unit holds the same (site-)position multiple times, it has no additional effect.

If a unit holds multiple different positions of the same entity, it has all those positions' responsibilities and properties, stacked up. Presumably, the demands for those combined positions are determined by the highest.

A unit holding a position with a succession token can be assigned another position with a (different) succession token.

A unit holding a position with a squad-position cannot hold another squad-position. It is dropped from the first, when it gets its second assigned.
A unit holding a position with a succession token cannot be assigned to a squad-position - the unit is simply not available. It works the other way around, though.

=[PRECEDENCE]=
The first defined position with precedence of 1 counts as the ruler of the civ. See also: [[Position_token#PRECEDENCE|PRECEDENCE]].

If the precedence is omitted or has a negative value, the game sets 0 as precedence, which seems to have no effect whatsoever.

When a unit has multiple positions, the name of the position with the highest rank in precedence is shown behind the unit's name.

If you omit precedence entirely, or set it to [PRECEDENCE:NONE], the position name will not be shown after the unit’s name. Your *Urist Mason* will remain simply *Mason*. This can be useful for positions that are unimportant or purely functional. The position will also not appear in the civilisation overview of your site on the world map. The position name is shown in messages, but remains hidden on the nobles screen as well. To make it visible there, use [LAND_NAME].

=[RESPONSIBILITY]ies=
Both civ and [SITE] positions can carry responsibilities. However, not all responsibilities are active for both types: some function only for civ positions, others only for site positions. When a civ noble arrives at a site and takes up residence, they do not perform responsibilities that are intended for SITE nobles. As a result, these responsibilities neither trigger their associated tasks nor unlock related game mechanics. For example, a civ-level manager living in a fortress will not perform management duties there and doesn't unlock the management-screen, even with an assigned office.
This behavior applies to the following [SITE]-level responsibilities:
* [RESPONSIBILITY:ACCOUNTING]
* [RESPONSIBILITY:BUILD_MORALE]
* [RESPONSIBILITY:HEALTH_MANAGEMENT]
* [RESPONSIBILITY:LAW_ENFORCEMENT]
* [RESPONSIBILITY:MANAGE_PRODUCTION]
* [RESPONSIBILITY:MEET_WORKERS]
* [RESPONSIBILITY:TRADE] (functions differently)
Other responsibilities may be affected as well, but have not yet been fully tested.

==[DELIVERS_MESSAGES]==
The only [AS_NEEDED]-position that is created in worldgen based on responsibility is that of the site-level responsibility [DELIVERS_MESSAGES].

==Outpost Liaisons and Diplomats==
Civ-positions with the responsibility [ESTABLISH_COLONY_TRADE_AGREEMENTS] ([[Outpost_Liaison|Outpost Liaison]]s) will meet with the site-noble who has responsibility for [RECEIVE_DIPLOMATS] and the highest rank of precedence (i.e. the lowest precedence value). Usually this is the [[Expedition_leader|Expedition leader]].

Once a [LAND_HOLDER] is assigned to the site, civ-positions with the responsibility [MAKE_TOPIC_AGREEMENTS] ([[Diplomat]]s) will meet with '''civ'''-level nobles present at the site who have the [RECEIVE_DIPLOMATS] responsibility. If multiple eligible nobles are available, one is selected at random. If no eligible noble is present, the diplomat leaves angrily. If the landholder is no longer present at the site, diplomats will not arrive at all.

It appears that Outpost Liaisons and Diplomats are chosen for a diplomatic mission based on availability. When multiple candidates exist, the position defined last in the raws is most often selected.

==[TRADE]==
Civ-level nobles with [TRADE] will arrive with the caravan, just as the Outpost Liaison. Their behavior is no longer active in the vanilla game, but the mechanics are still present. See [[40d:Guild_representative|Guild representative]] for more details. This civ-noble will only meet with the SITE noble with [TRADE], usually the [[Broker]].

If two civ-nobles exist with both [TRADE] and [ESTABLISH_COLONY_TRADE_AGREEMENTS], they both arrive at the same time. Even if both tokens are assigned to a single position, if more than one instance of that position exists, two of them will arrive. However in that case, somehow the elevation of the site and appointment of landholder isn't offered.

If the SITE-noble they intend to meet has both [TRADE] and [RECEIVE_DIPLOMATS], only one meeting will proceed and the other is cancelled. However, when two SITE-nobles are available, each with either [TRADE] or [RECEIVE_DIPLOMATS], both meetings will proceed and both civ-nobles will attempt to negotiate a trade agreement. It is not known what happens if these agreements are accepted or refused.

In the trade depot, the last defined position with the [TRADE] responsibility is shown as broker. However when requesting a trader, the first defined position with [TRADE] will actually go there to do the trade.

==World-gen effects of the [RESPONSIBILITY] of available positions ==
It is possible to cause civs and individual sites to change their behavior substantially when they reach a certain size, by controlling nobles.
* If a site can only appoint a position with [MILITARY_GOALS] after reaching a particular size, that site will not send armies on missions until the required size is reached.
* A civ-level [LAW_MAKING] position is required for the civilization to have any kind of cohesion. Without it, sites will be constantly embroiled in territorial disputes and civil wars will be commonplace.
* [MILITARY_STRATEGY] positions go out and tame wild animals. This makes your civ gain those animals as domesticated and also brings them in sieges.
* The [[Personality_facet|Personality]] of the position's holder determines how they lead the civ.

=Availability and visibility=
==Availability of (new) positions==
Warning: Do not mistake "availability" for "visibility"!

Of all the possible positions existing in your site's entity, there may only be some available.
* Positions with [REQUIRES_POPULATION] require the population to have a specific size.
* Positions with [REQUIRES_MARKET] will only appear in "large" sites (which may have different rules for different site types). This tag has no effect in fort mode.
* Positions that are appointed by positions that have an AS_NEEDED number. The appointable positions only become available after an appointer position-slot is created. This works also on civ-level. If a position is appointed by a Land-holder, it only becomes available, when that level of landholder is created.

Only the replaced positions are culled and are no longer available.
A position that requires a certain population will become available, even if it doesn't have [APPOINTED_BY] or [ELECTED]. In that case, see 'automatic assignment' and 'assumption'

In fortress mode, in some cases 'succession' is evaluated immediately after a position becomes available. See: Succession.
==Visibility of positions==
A position might be available, but can still be invisible for the player in the [[nobles screen]]. The positions with their respective holders are visible for players:
* All site-positions that are already filled-in (even if they could not be re-filled-in considering current conditions)
* Site positions that are appointable by a filled-in site position
* Site positions that are appointable by a filled-in civ position, when that civ positions holder becomes a citizen of your fortress.
* Civ positions of units that are also a citizen of your fortress.
If a position becomes available, for example because a certain pop number has been reached, or if it is available from the start(like expedition leader), as long as it cannot be appointed, it still is INVISIBLE for the player.

It might strike someone as odd if a position becomes filled automatically in fortress mode when that position is not even visible. This might be the case if the current holder of a non-appointable position dies or succeeds another position. Regardless of player visibility, these positions will be automatically filled in if the necessary requisitions are met. It might happen with the expedition leader.

A situation with a non-visible but available position, is for example when a position is solely appointed by the expedition leader, when the expedition leader's position is left vacant. It can no longer be appointed by the player and is invisible. Then, it gets automatically assumed, proving that the position still was available.

A position that is both [APPOINTED_BY] and [ELECTED] is visible, but players cannot interact with it.

=[NUMBER]=
A position might be defined with a number. In that case, as many as defined can be available. If the positions become available, in world-gen and when embarking, they are all filled-in completely.

If the ruling position (with PRECEDENCE of 1) has a NUMBER higher than 1, a random unit of the ones holding these positions is shown as ruler in the embark screen.

A [NUMBER] of 0 (zero) has the same effect as 1.

==Automatic spreading of assumed, non-singular positions==
If there are civ positions that have a NUMBER higher then '1' and which are assumed (not APPOINTED_BY or ELECTED) but are '''not DUTY_BOUND''', these are automatically spread among the civilisation, based on population. If there are a number of '''20''' available slots of that position, they spread among a civilization with a combined population of, for example, 1000 of which your fortress has 100 (10%), '''2''' of your fortress' citizens will assume that position.
This may probably also work with elected and appointed positions, but that may be depending on the death of the current holders and this needs more testing. Assumption works within a day, anyway.

==[AS_NEEDED]==
These positions can be created automatically by the game in world-gen. This, however, only works with:
* [LAND_HOLDER]'s
* squad commanders (needs more testing)
* Messengers at sites

For all other types of positions, they're not created in world-gen, even if they are defined with RESPONSIBILITY's. For example, even in war, the game wouldn't create a MILITARY_GOALS position, if they have AS_NEEDED as number.

However, in fortress mode / player mode, these positions can be created by the player at will.

Positions with AS_NEEDED need to be created first, before any symbols are assignable as 'symbols' (objects) for the position holder to carry or wear.

Positions with AS_NEEDED cannot be created and then ELECTED in fortress mode. It only works with APPOINTED_BY.

=Replacement and Required Population=

The token REPLACED_BY:position means that once the replacing position reaches its required population-number, the 'to-be-replaced' position will disappear. This is defined in REQUIRES_POPULATION. These tags are closely related to each other and seem to only have a meaningful function if combined. Nobles with REQUIRES_POPULATION require the population to have a specific size.

This works on the civ-level as well as on site-level, but those systems are in this mechanic strictly separated. Site-level positions cannot be replaced by civ-level positions and visa versa. This makes sense, because they both depend on their own population-count. When using REQUIRES_POPULATION on civ-level, it counts the total population of the civilisation.

See also: [[Advanced_entity_position_mechanics#Evaluation_of_Positions|Evaluation of positions]]

==Effect of replacement (and on [LAND_HOLDER]s)==

Replacement is immediate and complete - the current holding unit loses the position, even before SUCCESSION_BY_POSITION rules are applied. A position with a number of 1 will replace all the slots of a position with a higher number of slots.

Even if the next position is available but not visible, replacement still takes place. If a position is replaced, it is completely gone - it cannot be appointed, succeeded, elected or assumed any longer.
The unit immediately loses its position.

In legends, replacement is mentioned as: "(unit name) ceased to be (position name)" The replacement of an AS_NEEDED position empties the position's slot forever. In fortress mode, it may seem as if you can create new slots and appoint new units in the nobles screen, but this is reversed as soon as you close the window.

The landholder chain uses [REPLACED_BY] differently. It does not clear the position completely, but uses it for succession to the next level's position. [REPLACE_BY] is required to let that system work properly. This also means that the way in which landholders succeed (replace + as_needed) does not work in any other way.

Replacement between LAND_HOLDERS and other site- or civ positions does not work in any way. Only the vanilla replacement sequence between levels of LAND_HOLDERs does work. If the token is omitted for landholders, the landholder chain is broken, so replacement is required for the landholder system to work.

[REQUIRES_POPULATION] also does not work for [LAND_HOLDER], when you set [NUMBER] to 1. The position is not created when the required population is reached.

==What doesn't work==

'''Attention: If a position cannot be appointed, for example because of 'mutual appointment', it still exists according to replacement mechanics and will replace other positions if so defined. If a certain position(a) will be replaced by the baron's assistant, which can only be appointed by the [LAND_HOLDER] baron, than that position(s) still will be replaced from the start of the game, even if no baron or their assistant is ever present.'''

A position that is replaced by a somehow not-fillable position, is still replaced. This counts for mutual-appointing positions, replacement by not-yet-assigned landholders, replacement by AS_NEEDED positions, or replacement by not-yet-appointed positions.

Replacement does not work if the replaced position is a [LAND_HOLDER], even with civ-positions. In that case, the LAND_HOLDER's position is not replaced. It does not matter if AS_NEEDED is used, or a fixed number, and it also does not matter what type of position the replacer is. So this only works (correctly) with positions that become available by REQUIRES_POPULATION.

={{text anchor|Evaluation of Positions}}=
The game does not continuously check whether positions should become available, elected or be [REPLACE_BY]. This is well-known behavior—for example with the [[mayor]], who does not appear automatically when the required population ([REQUIRES_POPULATION]) is reached. Instead, positions must somehow be evaluated. This applies in several other situations as well

'''Cases that require a trigger:'''
* Election of a newly created position
* Election after the current holder dies
* Automatic assumption of a newly created position (this may take up to a day)
* New citizens (such as migrants) considering available positions
* Premature succession of a newly created position

'''Cases that do not wait for a trigger:'''
* Succession following the death of the previous holder
* Automatic assumption of existing positions that have become vacant

'''Triggers that cause the game to reevaluate noble positions:'''
* Succession of a [SITE]-position due to the death of the current holder
* [[Advanced_entity_position_mechanics#Election_Day|Election Day]]
* Automatic assumption of a [SITE]-position that becomes vacant
* (Re)assigning any site position manually
* Settlement elevation on the LAND_HOLDER track (e.g. gaining a [[Baron]] or [[Count]])

=Gaining a position=
There are several ways a unit can gain a position:
* Appointment: A unit is appointed by another unit or by the player.
* Election: A unit is elected by and among the members of the entity
* Assumption: A position is neither elected or appointed: a random unit just simply 'takes' the position
* Succession: a unit is the valid successor of this position(A), either by its current position(B) or because they are that position(A)-holder's heir.

Available positions will automatically be assigned to a random civ member when a new site/civ is created.

==Who can take a position==

* If so defined, a unit needs to be the right caste and/or class - it does not seem to work with creature types.
* The unit needs to be an adult member of the site or its parent civ-government; that is also CAN_LEARN or INTELLIGENT (SLOW_LEARNER cannot take positions) or otherwise is able to think.

==Appointment==

Positions that have an [APPOINTED_BY:position] token require that position to exist, to be available and appointed. Any position that is APPOINTED_BY can be appointed if the appointer's position is filled in.
For site-positions to be appointed, it is required that the appointer is present at that location.

If the appointing unit is temporarily not present, or if that position is not filled, positions depending on it cannot be appointed. This is the case with [[militia captains]], when the [[militia commander]] is on a [[mission]].

A site position cannot appoint a civ position ''or'' LAND_HOLDER in any way whatsoever.

Civ-level positions can appoint other civ-level positions and site-level positions can appoint other site-level positions.

Contrary to what has been said elsewhere, civ-level nobles also can appoint site-level nobles. They need to be at the site to do so. Landholders can appoint both site-level and civ-level nobles. These systems are therefore not as separate as was assumed.

'''Mutual appointment''' cannot take place. If these are the only requisites of the position, then the positions will never appear or get filled. These unfillable positions can be put to good use, for example, to replace a position that is no longer needed without creating a new one.

'''Self appointment''' doesn't normally work. If you have a position that is only appointed by itself, it is never appointed and also cannot be assumed. However, if the position has a number higher than 1, and is filled by multiple units (for example by another position that is now empty), than those units can re-assign or appoint each other from that their shared position.

If an APPOINTED_BY token refers to a non-existing position's code, the effects are as if the appointment token doesn't exist at all.

===Automatic appointment in world-gen and on the civ level===

Outside of fortress mode, the game will always attempt to appoint nobles whenever possible, as long as these positions are '''available''', even if they are invisible to the player.
It shows this message in legends: "(unit name) has been appointed to the position of (position name)"

In world-gen, all positions become available and are automatically appointed, taking population- and appointment-requirements into consideration.

Positions that are REPLACED_BY are culled and won't be filled.

If a citizen of your fortress holds a civ-level position that can appoint another civ-level position, the appointment will happen automatically and without player intervention. It may happen that another citizen of your fortress is appointed by that unit, creating civ-level position holders in your fortress, but it is unknown what is required to force this effect.

===Manual appointments by players in fortress mode===
In fortress mode, the positions that need to be appointed stay empty on embark. and it is the player's job to appoint those. A player can appoint a unit to any available position, according to the hereabove mentioned conditions. The player takes the role of the automatic appointment-system, but has no direct control over elections, successions and replacement. There are some differences in what is possible at world-gen sites and at player-controlled sites.

* A position that is appointed by a unit present as a fortress citizen, can be appointed, re-appointed or left vacant. This means also by civ-level nobles living as a citizen in your fortress; not when they are only visiting, like the diplomat.
* A position whose appointing positions are all either vacant or [REPLACED_BY] can no longer be appointed. If the position is already filled, it cannot be reappointed or vacated; the current holder simply remains in office.
* A position that is APPOINTED_BY a unit present as the land_holder of your site, can be appointed, reassigned or left vacant.
* A position that has SUCCESSION BY_HEIR or BY_POSITION can 'initially' be appointed and also re-appointed or left vacant, but as soon as the [[nobles]] screen closes, ''it can no longer be replaced or left vacant''. From then on, the succession-rules determine who gains that position when the current holder loses the position. This works even if the SUCCESSION:BY_POSITION-position is vacant or replaced.
* A position that is ELECTED nor APPOINTED_BY, can always be (re-)appointed by the player. This is the case with the [[Expedition leader]]. If it is left vacant however, it cannot be appointed, but will be assumed shortly after.
* A position that is both ELECTED and APPOINTED_BY, cannot be appointed by the player. Contrary to world-gen sites, its slot is visible, but it doesn't show the +-sign. This is either by AS_NEEDED or by a fixed number. Even if the position somehow gets filled (re)assignment is never possible
* A player can appoint a number of units to a position, as much as the NUMBER token dictates. If it is AS_NEEDED, the player may create as many slots as they like, also contrary to world-gen sites.
* A civ-position can never be appointed, even if the appointing civ noble is a citizen of your fortress. A civ position also never can be re-assigned or left vacant, would that position be defined as appointed by a site-position.

==Election==
Read more in [[Elections]]. The message that is shown is: "(creature name) has been elected to the position of (position name)"

In worldgen, there is no functional difference between ELECTED and non-appointment, except that elected nobles tend to have high social skills and/or skills related to the position, while non-elected ones are assigned randomly. See: [[Elections]]

A succession goes before an election.

A position that is both ELECTED and APPOINTED_BY never gets elected. Even if the appointees' position somehow gets filled, (re)-elections won't happen. So, it doesn't seem possible to have an elected position become available when a certain other position becomes filled.

An ELECTED civ-(or LAND_HOLDER) position at your site will never be (re)-elected in fortress mode. So real (re-)election only works with SITE-positions.

=== {{text anchor|Election Day}} ===
Election Day takes place on the 17th of Summer. On this day, a full reevaluation is performed, including all currently elected positions, which are subject to re-election. Contrary to the information on [[Elections]], nothing occurs at the start of a season.

Positions that are both [APPOINTED_BY] and [ELECTED] will not be re-elected on Election Day when assigned through [SUCCESSION].

=== Election Eligiblity ===
Any citizen may stand for election. Eligibility cannot be restricted using [ACCEPTED_CREATURE], [REJECTED_CREATURE], [ACCEPTED_CLASS], [REJECTED_CLASS], or [GENDER]. Units currently having a [SUCCESSION]-position even may be elected for a position with a [SQUAD]-token, which is otherwise impossible to assign or even succeed.

=== Skills ===
In elections, skills are taken into account for the tokens of the position which is elected.
{| class="wikitable"
|+ Relevant skills per position token
|-
! Position Token !! Relevant skills
|-
| Responsibility [[Position_token#DELIVER_MESSAGES|[DELIVER_MESSAGES]]] || [[Ambusher]], [[Observer]] and [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#ACCOUNTING|[ACCOUNTING]]] || [[Record_keeper|Record keeper]]
|-
| Responsibility [[Position_token#ESPIONAGE|[ESPIONAGE]]] || [[Schemer]]
|-
| Responsibility [[Position_token#HEALTH_MANAGEMENT|[HEALTH_MANAGEMENT]]] || [[Diagnostician|Diagnostician]]
|-
| Responsibility [[Position_token#MAKE_INTRODUCTIONS|[MAKE_INTRODUCTIONS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#MAKE_PEACE_AGREEMENTS|[MAKE_PEACE_AGREEMENTS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#MAKE_TOPIC_AGREEMENTS|[MAKE_TOPIC_AGREEMENTS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#MANAGE_PRODUCTION|[MANAGE_PRODUCTION]]] || [[Organizer]]
|-
| Responsibility [[Position_token#MEET_WORKERS|[MEET_WORKERS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#RECEIVE_DIPLOMATS|[RECEIVE_DIPLOMATS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#RELIGION|[RELIGION]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#TAME_EXOTICS|[TAME_EXOTICS]]] || [[Animal_trainer|Animal trainer]]
|-
| Responsibility [[Position_token#TRADE|[TRADE]]] || [[Social_skill|Social skills]] and [[Appraiser|Appraiser]]
|-
| [[Position_token#SQUAD|[SQUAD]]]-token || [[Tactician]] and [[Leader]]
|}

==Assumption==

A position that is not APPOINTED_BY nor ELECTED, or is appointed by positions that are not available in your site or civ, will be assumable by a random dwarf. If it has responsibilities that require certain skills, then these are taken into consideration on embark, but not when the position is assumed during the actual game.

Normally, one to three units will take the into consideration to assume a position. Most of the time when there are multiple open positions, only a single unit will assume all of them. However, a position that has REJECTED_CREATURE, REJECTED_CLASS, ALLOWED_CREATURE or ALLOWED_CLASS will be filled with all different units, even if the creature or class mentioned is irrelevant. It seems that this forces the game to loop over all the available units.

The message that is shown in Legends mode is: "(unit name) has assumed the position of (position name)". This may also take place in fortress mode, which then shows this message to the player.

If an assumable position becomes empty, it will be assumed within a day. This is the case when you leave the position of expedition-leader vacant. It also happens with entities.

Assumable positions that become empty will not be assumed if that position has a valid [SUCCESSION] -successor. In that case, the successor inherits the position.

Even positions that are somehow invisible because they cannot be directly APPOINTED_BY players, can be assumed.

When you embark, the assumable positions are automatically assigned to a random unit. If there are multiple of these positions at embark, they all are assigned to the same unit. If there are enough positions available, multiple units may gain a position, but often no more than three different ones.

If a dwarf in fortress mode assumes a position, that already has another position, it will leave the current position empty. When that position also is assumed, then this will continue until all positions have a dwarf appointed to them, with no other position.

A unit that already has a position with a [SUCCESSION] token won't take assumable positions into consideration that have a [SQUAD] token. This can be used by the modder to prevent unwanted loss of current positions.

A position that has an appointer which got replaced because of REPLACED_BY, will not become assumable. Also, positions that have an AS_NEEDED appointer that is not yet filled (or ever), will also not be assumed.

==Succession==

If a position-holder dies or advances to a new position via succession, the position will be granted to another unit based on the [SUCCESSION] tag. If they have an heir or the succeeding position exists, that unit will be assigned. If not, a new one will be appointed according to the usual rules. The message that is shown is: "(creature name) being the rightful heir, has inherited the position of (position name)"

The succeeding creature will also lose its previous position. When succession is defined using BY_POSITION, the unit naturally loses the referenced position. However, it also loses any other positions it may hold. If a unit could simultaneously inherit multiple positions, the last-defined succession overrides the earlier one, clearing the previously acquired position

Succession works both at site-level and at civ-level, both in world-gen and in fortress-mode. Succession by position on the civ-level is also visible and functional in fortress-mode. If both civ-level nobles are a citizen of your fortress, succession is applied visually. Vanilla example: The [[druid]] is succeeded by the [[acolyte]]. This means that as soon as the druid dies, the acolyte takes over.

When a position that is succeeded by position becomes available, immediately it is checked if a position-successor is available and the position is filled with that unit. Even if this is an [ELECTED] position, succession goes first. When elections eventually do happen, succession plays no role.

It is possible to assign multiple levels of [SUCCESSION:BY_POSITION] in different positions, creating a line of positions where the death of one causes all those "below" them to advance.

A position can have multiple tokens with position-succession. It looks to be random which one is used. It is not always:
* The first or last defined token
* The first or last appointed unit
* the oldest or youngest
* one with a higher or lower precedence
* a unit with relevant skills

When a position is defined with a Succession-type, that unit cannot have another position that has a Squad-type. If the succession-position itself has a squad, than it can be assigned another position with a squad, but then it will loose the previous succesion position. See further details by "Squad"

Assumed positions can also be succeeded by position, if the current holder dies.

If the successor is an AS_NEEDED position, the used unit will leave a vacant position-slot on its removal by succession. This empty slot remains a real slot, which will only be cleaned up if you (un)appoint a unit to this position-series. It isn't cleaned up after regular position validation.

A civ-level position of a unit living at your site might be inherited by a unit holding that does not currently live at your site. This, unfortunately, moves that position to a unit off site. This may also happen with the landholder of your site, for example when it is succeeded by another civ-level position. This currently poses an unsolved challenge.

===Eligibility for succession===
Succession is restricted by the tokens [ACCEPTED_CREATURE], [REJECTED_CREATURE], [ACCEPTED_CLASS], [REJECTED_CLASS] and [GENDER].

===Site and civ combined succession===

Succession can work when combining site positions with civ-level positions or land_holders, but only in world-gen mode. In fortress mode, it only works with combining the same level of nobles, with Landholders regarded as civ-level. So, in fortress mode, a site's position cannot succeed a landholder's position and it cannot succeed another type of civ-level position, and vice versa.

This won't work even if the positions:
* are AS_NEEDED or having a fixed number.
* Are LAND_HOLDERs.

===Succession [BY_HEIR]===

When a heir is needed for succession, all children and then other relatives are validated. They cannot take the position if their status does not allow it, for example if they have become a member of another civilisation. See: "Who can take a position". If the unit has no valid heir on that location, the position may go to a unit living on another site. This may cause the title of Landholder of some land to be inherited by a unit living somewhere else. That might be a problem, because then you lose your landholders.

===Premature Succession===

There are cases where [SUCCESSION:BY_POSITION] is applied prematurely: at the moment a position is first created and becomes appointable or assumable, rather than after a current holder leaves. In this situation, the succession mechanism assigns a holder immediately, without any player interaction.

When a position becomes available for the first time, the game checks whether a valid successor-by-position exists. If so, that unit is assigned instantly. It can affect positions that would normally be appointed or elected by the player, causing succession to trigger before the player has any opportunity to intervene.

This behavior occurs only in Fortress mode, but can be applied both on [SITE]-positions as well in civ-positions. That last one however is a bit harder to control. Example: [[Advanced entity position mechanics#The Archduke|The Archduke]]

This premature succession only occurs the first time a position becomes available (i.e. when it is created and becomes appointable or assumable). Even if the position remains vacant and the conditions for succession improve later, premature succession will not trigger again. From that point onward, only normal succession rules apply.

Using premature succession, a position that has [ELECTED], [APPOINTED_BY], or both, can be filled directly.
Notably, positions that combine [ELECTED] and [APPOINTED_BY] are normally impossible to fill through regular mechanics. Premature succession bypasses both election and appointment entirely, making this combination uniquely reachable through this mechanism.

No initial election takes place, and no subsequent elections will ever occur for that position. Succession always takes precedence over election, both in premature succession and in normal succession cases.

This behavior applies only in Fortress mode, not during world generation. World-gen uses simplified and more efficient mechanics, and this interaction does not occur there. Premature succession can affect both site-level and civilization-level positions.

====Multiple succession chains====

Multiple succession chains may be defined and are resolved in the order they appear in the raws.

If a position has both:
* a direct succession chain (A → C), and
* a multi-step chain (A → B → C),

and intermediate positions are vacant, resolution proceeds according to raw order. A common outcome is:
# The direct succession (A → C) is applied first, assigning A to C.
# The remaining chain then advances (A → B).
# If C still has empty slots, the final step (B → C) may occur.

If position B is already filled, behavior depends entirely on raw definition order:
* nothing may happen, or
* B may move to C first, followed by A moving to B.
====Working triggers====
Premature succession is triggered when a succeedable position is created under the following conditions:
* The succeedable position is created because its [REQUIRES_POPULATION] threshold is reached. This applies even if the position is not [APPOINTED_BY]. Premature succession takes priority over automatic assumption (e.g. the mayor declaring themselves within a day).
* The succeedable position can be [APPOINTED_BY] another position of the same level (site or civ) that has just been created because its [REQUIRES_POPULATION] was reached.
* The succeedable position can be appointed by another [SITE] [AS_NEEDED] position that has just been created and filled.
* The succeedable (site or civ) position is [APPOINTED_BY] the [LAND_HOLDER] position, which has just been created due to site elevation. This typically resolves when the diplomat leaves the map, at which point the landholder position becomes active.
* If all other requirements are met, premature succession can occur immediately after unpausing following embark, for positions with [REQUIRES_POPULATION:7].
====Non-working triggers====
Premature succession does '''not''' occur in the following cases:
* An [AS_NEEDED] succeedable position slot is manually created by the player while its succeeding position is already filled. [AS_NEEDED] positions must always be appointed after creation.
* The succeeding position is filled after the succeedable position becomes available. The moment of creation is the decisive trigger; filling the source position later is too late.
* The succeedable position can be appointed by another site or civ position with a fixed number of slots that has just been appointed. In this case, the succeedable position is just available for appointment itself, nothing more
* Any situation occurring during world generation.
* The succeeding position is [REPLACED_BY] the succeedable position. In this case, replacement removes the unit from the source position first, leaving no holder available for the succession mechanism to use.rst, leaving no holder available for the succession mechanism to use.
* The position is [APPOINTED_BY] a civ-level position, that just became a citizen of your fortress. It must be noted that those civ-level positions were active all that time and the succeedable position could be appointed even before. The monarchs arrival does not trigger premature succession

=Losing a position=

A unit can lose a position when:
* It dies
* It succeeds another position, even if it has nothing to do with the previous position.
* It is assigned to another SQUAD-holding position
* It is convicted of a crime.
* Another unit is ELECTED for the position
* Its position becomes replaced
* Another unit is appointed by the player, or the position is left vacant.
* It has assumed another position, as this always leaves the previous position vacant.

=Embarkment=
Two types of positions are automatically filled by embark.
* Positions without [APPOINTED_BY] or [ELECTED] (assumable). All these positions, even with a NUMBER higher than 1, are all filled with one to three dwarves. Contrary to assumption, this doesn't take into account any limitations. REJECTED_CLASS, ALLOWED_CLASS, REJECTED_CREATURE, ALLOWED_CREATURE and GENDER are applied, but without the normal spread you may expect with assumptions. Also it doesn't look at [SUCCESSION] and [SQUAD] limitations.
* Positions that are elected are filled-in by the normal election rules.

Positions that have a defined appointer are never initially filled at embark.

All positions that don't have [REQUIRES_POPULATION] or with a [REQUIRES_POPULATION] of 7 or lower, will be available at embark.

=Land Holders=

A Landholder is a '''special civ-level noble''' who gets a certain piece of land to hold, when that land is elevated to a certain level, determined by the tag [LAND_HOLDER] and by the landholder triggers in the game's settings. In vanilla, these are the baron, the count and the duke.

A unit gaining the landholder position does not migrate to that specific named land. In world-gen, they stay just where they are, probably at the capital. In fortress mode, you can suggest a citizen for the role. So for the time being that works.

Succession is then a real issue. If you use BY_HEIR, its solved when that landholder has children living at your site. But when its not the case, the title just goes to anyone randomly. Succession BY_POSITION works, but only in the civ-chain, and there's no way to guarantee a civ-holder is at your site at that time. Even with 'automatic spread' positions, it goes to one of them randomly.

==Functioning of the regular landholder chain==

The distinct difference between a landholder and a regular civ-level noble, is that a landholder may gain the position of landholder "of (sitename)" They are then seen as ruler of a particular site.

For a land_holder position to function as such, it has a few requirements:
* NUMBER:AS_NEEDED
* The first landholder-number of 1 is defined.
* No SITE (so civ) tag in that position.
*REPLACED_BY the next level landholder
If a landholder is defined with differentiating properties, it will function like a regular noble. A higher-up landholder that lacks the required tokens or connections will then not be used in elevation.

If a fortress meets the trigger for a new LAND_HOLDER tier when a caravan leaves, then the next time the outpost liaison or equivalent arrives, they will offer to make you an official colony, which will allow you to select all positions for that LAND_HOLDER level. Each time they appear, the outpost liaison will only promote your fortress one tier up the LAND_HOLDER track.

The landholder's LAND_NAME is not required for the functioning of this system. If omitted, messages will be shown with a more generic text.

==Appointment==

This mechanism differs from the regular methods of position management. It ignores all regular appointment- and election rules, so it more or less functions like automatic assignment. A landholder is, in vanilla, appointed by the monarch. Changing this doesn't seem to do anything. If they are appointed by a site-position, a not-yet-existing civ-position, or not appointed at all: the system keeps working as usual.

A landholder can appoint civ-positions and site positions. This works as expected: the positions only are appointed then when that landholder becomes available on civ-level or when he arrives at that site for site-level positions.

If your rank of landholder is the first of its rank in the realm, and is the sole appointer of some civ-position, then immediately as it gains the title, it will appoint the empty civ-slots. This may happen on your site, but the frequency and certainty is hard to determine.

==Succession==

Succession rules are applied to some extent:
* In world-gen it works according to succession rules, and site-positions can be used here. This means that a site position or a civ-position can inherit a landholder position, and vice versa.
* In fortress mode, once a landholder has been appointed, it then can inherit civ-level positions, and vice versa. This means that your baron can become king.
* Succession rules do not apply within the [LAND_HOLDER] chain; a count will not inherit a baron's land. This is because succession does not work well with the AS_NEEDED token.
* Premature succession works in fortress mode with landholders. If a unit gets a landholder's position and that landholder is the appointer of an as yet empty position, which is defined as succeeding from a third one, then the succession is immediately applied. The landholder themselves can even be the successor of a newly created position.
* A landholder's position is, in fortress mode, not successionable by a site-position or vice versa

===Impossibilities for succession by a site-position===
It would be very beneficial if the landholder can be succeeded by a [SITE]-position. So far, the following tests have not lead to positive results:
* making landholder and site-position both non-[DUTY_BOUND]
* make the site-position be [APPOINTED_BY] the landholder and/or the monarch
* give landholder and site-position [REJECTED_CREATURE]
* Let the monarch live at your site when succession could happen.
* Let the site-position be [REPLACED_BY] the landholder.

==Nomination==

The player is able to nominate a unit to become the LAND_HOLDER, but this only works with units of [LAND_HOLDER] level 1. The player can select all units, only limited by the PRECEDENCE of the current units' positions.

A unit that has a position with a PRECEDENCE lower or equal to that of the landholder's position, cannot be selected. This means that a baron (or count) from another site or the monarch cannot be selected, because their precedence is lower or equal.

The GENDER token does not work here: also units with the wrong gender (sorry) can be selected.

==Levels==
In mods, up to 10 levels of LAND_HOLDER may be defined.

If a landholder is replaced by a wrong landholder number (1 replaced by 3), then the number 3 is still correctly attached to the settlement.

If the current landholder has the highest available landholder number, then the next elevation will not happen - the diplomat will not elevate your fortress to a higher position, even if that position might be REPLACED_BY a lower landholder.

These chains do work:
* 1 -> 2a - > 2b -> 3
* 1 -> 3 -> 2 -> 4

These chains do not work:
* 2 -> 3 (need to start at 1)
* 1 -> 4 -> 2 -> 3 (stops after 4 as the highest)
* 1a -> 2, 1b -> 2 (only 1a and 2 work, 1b is not used)

==Moving landholders==

It may happen that a land-holder no longer lives at the site which they are the landholder of, specifically when the current landholder dies, leaving the title to an heir living somewhere else.

To prevent this from happening, you can make their succession from heir and make sure that their kids live at your site. Or, you can make their position succeeded by another civ position, and make it so that this civ position is somehow available on your site. But if multiple of these positions exist, it cannot be guaranteed that a citizen of your fortress will inherit the title.

In world gen, a landholder lacking the DUTY_BOUND-token will also move to the site they like, according to legends mode.

==Replacement by a generic civ-position==

If a landholder is replaced by an AS_NEEDED non-landholder civ-position, then this will work: the current landholder loses that title upon settlement-elevation and gains that civ-title. However, the civ-title lacks the landholder-property of being attached to the land. It will not show the name of the settlement alongside the position's name. So no "minister of Shovelmounts"

If a landholder is replaced by a general AS_NEEDED civ-position, that itself is also replaced by a generic AS_NEEDED civ-position, then firstly the elevation is executed and also the unit gains that new position. However, he immediately loses it, because an AS_NEEDED position that is replaced by another position can be filled initially, but units wont be able to hold that title.

==Landholder with fixed number==

A landholder's position that has a fixed number will be created and filled directly when the civilisation is born, so this position slot is then not available for the regular landholder-mechanic and will also not be used. That landholder will thus not be attached to a settlement.

It doesn't matter if the landholder's position is connected to the regular landholder's-chain with the REPLACE_BY token.

==Responsibilities==

When given a certain [RESPONSIBILITY], a landholder may function as a regular civ-level noble. If the position has [TRADE] or [OUTPOST_NEGOTIATING] responsibilities, then the landholder functions both as a diplomat and as an actual land holder. A landholder with the [MILITARY_STRATEGY] responsibility will travel around taming creatures in world-gen, according to legends mode.

Besides that, the responsibilities work the same as with any other on-site living position-holder, civ or otherwise.

=Military=
==Squad management==
In the vanilla game, the Squad interface only becomes available after a militia commander has been appointed. Until then, the window displays:{{DFtext|You must appoint somebody first to create a squad.}}

What’s surprising is how this is determined internally. In the entity raw definition, '''only the last two positions that include a [SQUAD] token are checked''' to decide whether the interface is accessible at all. As a result, if your hierarchy defines commanders A through E, appointing '''Commander D or E''' unlocks squad formation, while appointing A–C does nothing.

In other words, squad availability is not tied to ''having a militia commander'', but to ''which specific positions happen to be last in the raw list''—a notably hacky implementation.

These 'last two' are always the last two '''available positions.''' So if they get [REPLACED_BY] or become available because of [REQUIRES_POPULATION], the game adapts to those.

==Squad assignment==

Squads can be assigned, even if the leader position has no holder.

A specific unit can only have one position associated with a squad. If it gains another 'squad holding position', it is unassigned from the first one. This does not work with a 0-squad, so only 1+squads are taken into consideration. This technique can possibly be used to distribute all positions equally among all citizens. It does however not work with election and assumption.

If a civ-level position is associated with a squad and it gets a site-level squad-holding position assigned, it loses the current civ-position.

Squads can get really messed up, if you make the position (or multiple) either elected or not-elected and not-appointed, then this can cause the game to assign multiple squads to the same unit. Automatic assignment and election does not take squads into account, but the nobles screen does. This can cause the positions to be cleared as the game figures out that they have more than one position, and immediately get elected or assumed again.

Positions that cannot have a squad-position:
* A site- or civ-position with a [SUCCESSION] token cannot be appointed a squad-holding-position. The other way around, however, does work. For example, if a site-position with a [SUCCESSION]-token is appointed to a unit that has already a position with [SQUAD]. But when that squad position is assigned to another unit, it cannot be assigned back.
* A position with [SUCCESSION] can also not be assigned as a '''member''' of a squad.
* A squad-holding position with a formed squad cannot be appointed to another squad holding position.

If a position has at least one squad member, it cannot be left vacant. First, the squad has to be disbanded, then the position may be cleared.

==0-squads==
A 0-Squad is defined in a position as [SQUAD:0:member:members]. It does not seem to do anything useful as of now.
* It cannot be used to activate the [[Squad|military interface]]
* It does not restrict the assignment of [SUCCESSION] positions.
* Assigning this position does not clear any previously held squad position.
* The [[Leader]] and [[Tactician]] skill are not marked as relevant skills and are not taken into account in elections.
* It cannot be formed as a squad.

=Further testing=
The following questions may need additional testing. Feel free to add or answer
* Everything regarding COMMANDING and army-structure
** [http://www.bay12forums.com/smf/index.php?topic=175437.msg8331668#msg8331668]
** [http://www.bay12forums.com/smf/index.php?topic=165213.msg8335682#msg8335682]
** [http://www.bay12forums.com/smf/index.php?topic=174584.msg8026854#msg8026854]
* Everything regarding CONQUERED_SITE, but it is presumably just like site. But what if you combine SITE or LAND_HOLDER with it?
* Stuff about the monarch, its arrival and its entourage.

=Oddities (Bugs)=
Almost everything on this page could be called an oddity. Because of their unexpected usability, some may also be referred to as “undocumented features.” Others, however, are simply odd and not particularly useful, yet I hesitate to call them “bugs.”
* If a certain threshold is reached that makes an elected position electable, and the triggering event that initiates this evaluation is an assumption, then the resulting assumption is also referred to in the messages as an election

=Examples=

===The Founder===
The founder is a single dwarf, appointed at embark. They will be the only one ever to have this position and are not replaceable. When they lose their position some way, the position will not be assumed by another dwarf.
{{gamedata|title=The Founder|
[POSITION:THE_FOUNDER]
[NAME:the founder:founders]
[NUMBER:1]
[SITE]
[ALLOWED_CREATURE:DWARF:ALL] - will only be filled at embark, but not assumable later.
[REJECTED_CREATURE:DWARF:ALL] - will only be filled at embark, but not assumable later.
[SUCCESSION:BY_POSITION:THE_FOUNDER] - not unassignable, also cannot be assigned to a [SQUAD] position.
[PRECEDENCE:200]
Non APPOINTED_BY
Non ELECTED
Optional: Add responsibilities to make the game select a unit with certain skills.
}}
===Marriage bar===
Dwarven matrons are held in great honour. Upon marriage, a female dwarf is no longer expected to perform menial labour. All dwarven males hold this position by default, granting their spouses exemption from menial work.

The position becomes available with the arrival of the first migrants; otherwise, on embark, it would be assumed by females. Its succession rule is non-functional, but this prevents the player from unassigning the position. A squad size of 1 and the succession rules together prevent a unit from assuming the position more than once.

With precedence set to NONE, the position name is hidden, while LAND_NAME remains visible on the nobles screen. All married females receive the suffix “, Mrs.” and are marked as Nobles.

The practical usefulness of this position is debatable, but it serves as a clear demonstration of several mechanics.
{{gamedata|title=Mrs. Urist|

[POSITION:MRS_URIST]
[NUMBER:300]
[SITE]
[ALLOWED_CREATURE:DWARF:MALE]
Not APPOINTED_BY
Not ELECTED
[LAND_NAME:Dwarven male]
[NAME:dwarven male:dwarven male]
[PRECEDENCE:NONE]
[SPOUSE_FEMALE:, Mrs.:spouses]
[MENIAL_WORK_EXEMPTION_SPOUSE]
[REQUIRES_POPULATION:8]
[SUCCESSION:BY_POSITION:MONARCH]
[SQUAD:1:member:members]
}}
===The Archduke===
The archduke is the leader of the civilization, but exists only from landholder 4-level. Until then, its position remains vacant. When a settlement is elevated to tier 4 (grand duke), the grand duke can appoint the ruler of the civilisation, the archduke. Because of 'Premature Succession', they themself inherents that position immediately, but only when in fortress mode. Its heir then becomes grand duke.
{{gamedata|title=The Archduke| no POSITION:MONARCH

[POSITION:THE_ARCHDUKE]
[NAME:archduke:archdukes]
[NAME_MALE:archduke:archdukes]
[NAME_FEMALE:archduchess:archduchesses]
[LAND_NAME:a archduchy]
[NUMBER:1]
[PRECEDENCE:1]
[SUCCESSION:BY_POSITION:GRAND_DUKE]
[APPOINTED_BY:GRAND_DUKE]
(add additional monarch-stuff, like spouse name, demands etc.)

[POSITION:GRAND_DUKE]
[NAME:grand duke:grand dukes]
[NAME_MALE:grand duke:grand dukes]
[NAME_FEMALE:grand duchess:grand duchesses]
[NUMBER:AS_NEEDED]
[LAND_HOLDER:4]
// Optional ...
[PRECEDENCE:19]
[LAND_NAME:a archduchy]
[RESPONSIBILITY:LAW_MAKING]
[RESPONSIBILITY:RECEIVE_DIPLOMATS]
[SUCCESSION:BY_HEIR]
[APPOINTED_BY:THE_ARCHDUKE]
(add additional landholder-stuff)

!!add to [POSITION:DUKE]
[REPLACED_BY:GRAND_DUKE]

}}
{{Category|Modding}}
{{Category|Entities}}
{{Category|Guides}}

Advanced entity position mechanics

2026-02-10T10:35:57Z

Joostheger: /* Premature Succession */

{{Quality|Fine}}
{{Modding}}

= Introduction =

[http://www.bay12forums.com/smf/index.php?topic=182239.0 Discussion thread on the forum]

This page documents observed and tested behavior of entity positions in Dwarf Fortress that is not fully described elsewhere on the wiki. It focuses on advanced interactions between position tokens, including appointment, succession, election, and responsibility handling, across both civilization-level and site-level entities.

The mechanics described here are based on empirical testing in world generation and fortress mode, supplemented where necessary by raw analysis. In several cases, the game’s behavior is determined by evaluation order and interaction between multiple tags, rather than by individual tokens in isolation.

This page is intended for modders and advanced players who are designing or debugging custom entity position structures. It does not restate basic position mechanics, but instead highlights edge cases, non-obvious interactions, and behaviors that may appear inconsistent or undocumented.

Unless stated otherwise, the described behavior applies to current versions of the game and may differ from older releases.

==What is an entity? What is a position?==
An [[entity]] is an organizational structure that can have relationships with other entities, usually known as a [[civilization]] or a "[[site]] government" in the game, but merchant [[guild]]s, religious organizations, necromancer towers, and [[bandit]] groups are also entities. An entity can have positions - in most cases, these are hardcoded and generated by the game, but as for civilizations and sites, the [[raw file]]s can be customised.

A position is a special relationship between a unit and an entity. The unit holding a position has a larger influence over that entity than other citizens. Positions are mostly known as [[nobles]], but in this article. the technical term is used.

=Position levels (Site/Civ) and their interaction=
There are two basic types of positions that are customizable: '''civ(ilization)''' level and '''site level'''. Positions with the tag [SITE] are at site level, positions without the tag [SITE] are at 'civ level'. These two types of nobles can be considered '''loosely related systems'''. There are a few places where they can interact with each other.

Civ-level positions are in charge of the civilization as a whole, managing national [[trade]], laws, and [[war]]s. These are, for example, the vanilla [[monarch]], [[diplomat]] and [[general]]. (Note that the general doesn't do anything in either mode in the current version.)

'''[LAND_HOLDER]''' nobles are also positions at civ-level. These units are members of the national government, but have gained authority over some land or site. Once they do, they move to that place, but their position is still regarded as a civ-level position.

Site-level position holders are members of a site government (subsidiary to the civilization), and manage local affairs in that location. These are, for example, the [[mayor]], the [[sheriff]] and the [[broker]].

==Table of interaction between different position levels==
In this table, the possible interactions between different position levels are summarized.
The header row shows the positions defining the tokens.

The left column shows the position type that is referred to.
Example:
{| {{prettytable}}
|- bgcolor="#ddd"
! referred position-type
! LAND_HOLDER
|-
| civilization
| (baron is) APPOINTED_BY:MONARCH
|}
color coding: 
* Exists in vanilla
* Possible with mods
* Not possible
* possible to some extent.
* not yet fully investigated.
{| {{prettytable}}
|- bgcolor="#ddd"
! referred position-type
! Civilization
! SITE
! LAND_HOLDER
! CONQUERED_SITE

|-
| Civilization
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION '''(1)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION

|-
| SITE
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION '''(2)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY '''(3)''' COMMANDER REPLACED_BY SUCCESSION '''(4)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION

|-
| LAND_HOLDER
| APPOINTED_BY COMMANDER REPLACED_BY '''(6)''' SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION '''(5)'''
| APPOINTED_BY COMMANDER REPLACED_BY '''(7)''' SUCCESSION '''(8)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION

|-
| CONQUERED_SITE
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
|}

Remarks:
# Works only in world-gen, if a unit with that civ-position is present at the site.
# Works only in world-gen, the site-position holding unit will then move to the capital.
# Is completely ignored
# Works only in world-gen.
# Works only in world-gen.
# Won't appear at all
# This is necessary for the landholder chain to work properly, it doesn’t work otherwise.
# This works only outside of the landholder chain, so when landholders are simply regarded as civ-level nobles. might also work in world-gen
#

== Other interactions ==

Unfortunately, interactions with positions of other entities don't seem possible, such as APPOINTED_BY: HIGH_PRIEST. With [VARIABLE_POSITIONS], positions are automatically created with codes like CUSTOM_LAW_MAKER_2, but interaction with these positions don't seem to work, either. For more info on those, see [[Variable positions]]

=General=

==Civ-level nobles living at your site==
Nobles from your civilization can come to live at your fortress. This happens in vanilla with landholders such as [[Baron]], [[Count]] and [[Duke]], with the Monarch, but sometimes also with non-landed LAND_HOLDERS.

When a civ-level noble becomes a [[citizen]] at your location, their position is shown among the site-level positions in your [[nobles screen]]. They appear to function as a site-level noble. They may have [[demand]]s, [[mandate]]s, [[squad]]s and the like. They can appoint nobles at the site-level.

If they have certain [RESPONSIBILITY]ies, they do the tasks that go with them.

==Fortress mode, world-gen and their differences==
Their are a few differences in how positions function between fortress mode (normal play mode) and the world generation (world-gen).

In '''fortress mode''', the player has some control over the appointment of nobles, limited by elections, automatic filled-in positions and succession rules. Pre-fortress mode, which is referred to as '''world-gen''', the game will always attempt to assign nobles whenever possible. It is subjected to the same rules as in fortress-mode, but there are some exceptions. In '''[[World activities]]''', which is the thing that happens in the world while you play fortress mode, it seems as if the same rules are applied as fortress mode.

A difference between player-fortress-mode and world-gen, is causes by visibility (see below). Positions that are not visible by the player and thus not available for assignment, will be available in world-gen and will thus be automatically assigned.

In fortress mode, a position that is both [ELECTED] and [APPOINTED_BY], cannot be appointed by the player and is also not elected, and can thus not be filled. But in world-gen sites however, these positions are automatically filled.

Positions with [AS_NEEDED] are almost never created and filled in world-gen (depending on their [RESPONSIBILITY]ies), but can always be used in player mode.

A position can, in fortress mode, be filled by the same unit. A unit can gain multiple positions in fortress mode, for example because of [[elections]]. This will not happen in world-gen mode: a unit can only have one position. See also remarks on 'embark' and 'Losing a position'.

In world-gen, [SUCCESSION] between civ-levels and [SITE-]levels may happen. This will not happen in fortress mode, or even off-site in [[World activities]].

In fortress mode, premature SUCCESSION may happen. This will not happen in world-gen mode.

==Units holding multiple positions in multiple entities==
A unit can hold multiple positions in its civilisation or in its site-entity, however this does not happen in world-gen. Only at player-managed sites can units be holding multiple positions at once. (It is probably not possible for a unit to hold a position in two different civilisations or two different sites.)

In world-gen, if there are too many positions to be filled, they simply stay empty until more units are available. E.G, a unit at a site might inherit a civ-level position and still remain a member of the local government. When this happens however, they move to the capital. If a unit gains a new position, either inherited or otherwise, it drops the previous one. If a unit assumes a civ-position in fortress mode, it leaves the current position.

If a unit holds the same (site-)position multiple times, it has no additional effect.

If a unit holds multiple different positions of the same entity, it has all those positions' responsibilities and properties, stacked up. Presumably, the demands for those combined positions are determined by the highest.

A unit holding a position with a succession token can be assigned another position with a (different) succession token.

A unit holding a position with a squad-position cannot hold another squad-position. It is dropped from the first, when it gets its second assigned.
A unit holding a position with a succession token cannot be assigned to a squad-position - the unit is simply not available. It works the other way around, though.

=[PRECEDENCE]=
The first defined position with precedence of 1 counts as the ruler of the civ. See also: [[Position_token#PRECEDENCE|PRECEDENCE]].

If the precedence is omitted or has a negative value, the game sets 0 as precedence, which seems to have no effect whatsoever.

When a unit has multiple positions, the name of the position with the highest rank in precedence is shown behind the unit's name.

If you omit precedence entirely, or set it to [PRECEDENCE:NONE], the position name will not be shown after the unit’s name. Your *Urist Mason* will remain simply *Mason*. This can be useful for positions that are unimportant or purely functional. The position will also not appear in the civilisation overview of your site on the world map. The position name is shown in messages, but remains hidden on the nobles screen as well. To make it visible there, use [LAND_NAME].

=[RESPONSIBILITY]ies=
Both civ and [SITE] positions can carry responsibilities. However, not all responsibilities are active for both types: some function only for civ positions, others only for site positions. When a civ noble arrives at a site and takes up residence, they do not perform responsibilities that are intended for SITE nobles. As a result, these responsibilities neither trigger their associated tasks nor unlock related game mechanics. For example, a civ-level manager living in a fortress will not perform management duties there and doesn't unlock the management-screen, even with an assigned office.
This behavior applies to the following [SITE]-level responsibilities:
* [RESPONSIBILITY:ACCOUNTING]
* [RESPONSIBILITY:BUILD_MORALE]
* [RESPONSIBILITY:HEALTH_MANAGEMENT]
* [RESPONSIBILITY:LAW_ENFORCEMENT]
* [RESPONSIBILITY:MANAGE_PRODUCTION]
* [RESPONSIBILITY:MEET_WORKERS]
* [RESPONSIBILITY:TRADE] (functions differently)
Other responsibilities may be affected as well, but have not yet been fully tested.

==[DELIVERS_MESSAGES]==
The only [AS_NEEDED]-position that is created in worldgen based on responsibility is that of the site-level responsibility [DELIVERS_MESSAGES].

==Outpost Liaisons and Diplomats==
Civ-positions with the responsibility [ESTABLISH_COLONY_TRADE_AGREEMENTS] ([[Outpost_Liaison|Outpost Liaison]]s) will meet with the site-noble who has responsibility for [RECEIVE_DIPLOMATS] and the highest rank of precedence (i.e. the lowest precedence value). Usually this is the [[Expedition_leader|Expedition leader]].

Once a [LAND_HOLDER] is assigned to the site, civ-positions with the responsibility [MAKE_TOPIC_AGREEMENTS] ([[Diplomat]]s) will meet with '''civ'''-level nobles present at the site who have the [RECEIVE_DIPLOMATS] responsibility. If multiple eligible nobles are available, one is selected at random. If no eligible noble is present, the diplomat leaves angrily. If the landholder is no longer present at the site, diplomats will not arrive at all.

It appears that Outpost Liaisons and Diplomats are chosen for a diplomatic mission based on availability. When multiple candidates exist, the position defined last in the raws is most often selected.

==[TRADE]==
Civ-level nobles with [TRADE] will arrive with the caravan, just as the Outpost Liaison. Their behavior is no longer active in the vanilla game, but the mechanics are still present. See [[40d:Guild_representative|Guild representative]] for more details. This civ-noble will only meet with the SITE noble with [TRADE], usually the [[Broker]].

If two civ-nobles exist with both [TRADE] and [ESTABLISH_COLONY_TRADE_AGREEMENTS], they both arrive at the same time. Even if both tokens are assigned to a single position, if more than one instance of that position exists, two of them will arrive. However in that case, somehow the elevation of the site and appointment of landholder isn't offered.

If the SITE-noble they intend to meet has both [TRADE] and [RECEIVE_DIPLOMATS], only one meeting will proceed and the other is cancelled. However, when two SITE-nobles are available, each with either [TRADE] or [RECEIVE_DIPLOMATS], both meetings will proceed and both civ-nobles will attempt to negotiate a trade agreement. It is not known what happens if these agreements are accepted or refused.

In the trade depot, the last defined position with the [TRADE] responsibility is shown as broker. However when requesting a trader, the first defined position with [TRADE] will actually go there to do the trade.

==World-gen effects of the [RESPONSIBILITY] of available positions ==
It is possible to cause civs and individual sites to change their behavior substantially when they reach a certain size, by controlling nobles.
* If a site can only appoint a position with [MILITARY_GOALS] after reaching a particular size, that site will not send armies on missions until the required size is reached.
* A civ-level [LAW_MAKING] position is required for the civilization to have any kind of cohesion. Without it, sites will be constantly embroiled in territorial disputes and civil wars will be commonplace.
* [MILITARY_STRATEGY] positions go out and tame wild animals. This makes your civ gain those animals as domesticated and also brings them in sieges.
* The [[Personality_facet|Personality]] of the position's holder determines how they lead the civ.

=Availability and visibility=
==Availability of (new) positions==
Warning: Do not mistake "availability" for "visibility"!

Of all the possible positions existing in your site's entity, there may only be some available.
* Positions with [REQUIRES_POPULATION] require the population to have a specific size.
* Positions with [REQUIRES_MARKET] will only appear in "large" sites (which may have different rules for different site types). This tag has no effect in fort mode.
* Positions that are appointed by positions that have an AS_NEEDED number. The appointable positions only become available after an appointer position-slot is created. This works also on civ-level. If a position is appointed by a Land-holder, it only becomes available, when that level of landholder is created.

Only the replaced positions are culled and are no longer available.
A position that requires a certain population will become available, even if it doesn't have [APPOINTED_BY] or [ELECTED]. In that case, see 'automatic assignment' and 'assumption'

In fortress mode, in some cases 'succession' is evaluated immediately after a position becomes available. See: Succession.
==Visibility of positions==
A position might be available, but can still be invisible for the player in the [[nobles screen]]. The positions with their respective holders are visible for players:
* All site-positions that are already filled-in (even if they could not be re-filled-in considering current conditions)
* Site positions that are appointable by a filled-in site position
* Site positions that are appointable by a filled-in civ position, when that civ positions holder becomes a citizen of your fortress.
* Civ positions of units that are also a citizen of your fortress.
If a position becomes available, for example because a certain pop number has been reached, or if it is available from the start(like expedition leader), as long as it cannot be appointed, it still is INVISIBLE for the player.

It might strike someone as odd if a position becomes filled automatically in fortress mode when that position is not even visible. This might be the case if the current holder of a non-appointable position dies or succeeds another position. Regardless of player visibility, these positions will be automatically filled in if the necessary requisitions are met. It might happen with the expedition leader.

A situation with a non-visible but available position, is for example when a position is solely appointed by the expedition leader, when the expedition leader's position is left vacant. It can no longer be appointed by the player and is invisible. Then, it gets automatically assumed, proving that the position still was available.

A position that is both [APPOINTED_BY] and [ELECTED] is visible, but players cannot interact with it.

=[NUMBER]=
A position might be defined with a number. In that case, as many as defined can be available. If the positions become available, in world-gen and when embarking, they are all filled-in completely.

If the ruling position (with PRECEDENCE of 1) has a NUMBER higher than 1, a random unit of the ones holding these positions is shown as ruler in the embark screen.

A [NUMBER] of 0 (zero) has the same effect as 1.

==Automatic spreading of assumed, non-singular positions==
If there are civ positions that have a NUMBER higher then '1' and which are assumed (not APPOINTED_BY or ELECTED) but are '''not DUTY_BOUND''', these are automatically spread among the civilisation, based on population. If there are a number of '''20''' available slots of that position, they spread among a civilization with a combined population of, for example, 1000 of which your fortress has 100 (10%), '''2''' of your fortress' citizens will assume that position.
This may probably also work with elected and appointed positions, but that may be depending on the death of the current holders and this needs more testing. Assumption works within a day, anyway.

==[AS_NEEDED]==
These positions can be created automatically by the game in world-gen. This, however, only works with:
* [LAND_HOLDER]'s
* squad commanders (needs more testing)
* Messengers at sites

For all other types of positions, they're not created in world-gen, even if they are defined with RESPONSIBILITY's. For example, even in war, the game wouldn't create a MILITARY_GOALS position, if they have AS_NEEDED as number.

However, in fortress mode / player mode, these positions can be created by the player at will.

Positions with AS_NEEDED need to be created first, before any symbols are assignable as 'symbols' (objects) for the position holder to carry or wear.

Positions with AS_NEEDED cannot be created and then ELECTED in fortress mode. It only works with APPOINTED_BY.

=Replacement and Required Population=

The token REPLACED_BY:position means that once the replacing position reaches its required population-number, the 'to-be-replaced' position will disappear. This is defined in REQUIRES_POPULATION. These tags are closely related to each other and seem to only have a meaningful function if combined. Nobles with REQUIRES_POPULATION require the population to have a specific size.

This works on the civ-level as well as on site-level, but those systems are in this mechanic strictly separated. Site-level positions cannot be replaced by civ-level positions and visa versa. This makes sense, because they both depend on their own population-count. When using REQUIRES_POPULATION on civ-level, it counts the total population of the civilisation.

See also: [[Advanced_entity_position_mechanics#Evaluation_of_Positions|Evaluation of positions]]

==Effect of replacement (and on [LAND_HOLDER]s)==

Replacement is immediate and complete - the current holding unit loses the position, even before SUCCESSION_BY_POSITION rules are applied. A position with a number of 1 will replace all the slots of a position with a higher number of slots.

Even if the next position is available but not visible, replacement still takes place. If a position is replaced, it is completely gone - it cannot be appointed, succeeded, elected or assumed any longer.
The unit immediately loses its position.

In legends, replacement is mentioned as: "(unit name) ceased to be (position name)" The replacement of an AS_NEEDED position empties the position's slot forever. In fortress mode, it may seem as if you can create new slots and appoint new units in the nobles screen, but this is reversed as soon as you close the window.

The landholder chain uses [REPLACED_BY] differently. It does not clear the position completely, but uses it for succession to the next level's position. [REPLACE_BY] is required to let that system work properly. This also means that the way in which landholders succeed (replace + as_needed) does not work in any other way.

Replacement between LAND_HOLDERS and other site- or civ positions does not work in any way. Only the vanilla replacement sequence between levels of LAND_HOLDERs does work. If the token is omitted for landholders, the landholder chain is broken, so replacement is required for the landholder system to work.

[REQUIRES_POPULATION] also does not work for [LAND_HOLDER], when you set [NUMBER] to 1. The position is not created when the required population is reached.

==What doesn't work==

'''Attention: If a position cannot be appointed, for example because of 'mutual appointment', it still exists according to replacement mechanics and will replace other positions if so defined. If a certain position(a) will be replaced by the baron's assistant, which can only be appointed by the [LAND_HOLDER] baron, than that position(s) still will be replaced from the start of the game, even if no baron or their assistant is ever present.'''

A position that is replaced by a somehow not-fillable position, is still replaced. This counts for mutual-appointing positions, replacement by not-yet-assigned landholders, replacement by AS_NEEDED positions, or replacement by not-yet-appointed positions.

Replacement does not work if the replaced position is a [LAND_HOLDER], even with civ-positions. In that case, the LAND_HOLDER's position is not replaced. It does not matter if AS_NEEDED is used, or a fixed number, and it also does not matter what type of position the replacer is. So this only works (correctly) with positions that become available by REQUIRES_POPULATION.

={{text anchor|Evaluation of Positions}}=
The game does not continuously check whether positions should become available, elected or be [REPLACE_BY]. This is well-known behavior—for example with the [[mayor]], who does not appear automatically when the required population ([REQUIRES_POPULATION]) is reached. Instead, positions must somehow be evaluated. This applies in several other situations as well

'''Cases that require a trigger:'''
* Election of a newly created position
* Election after the current holder dies
* Automatic assumption of a newly created position (this may take up to a day)
* New citizens (such as migrants) considering available positions
* Premature succession of a newly created position

'''Cases that do not wait for a trigger:'''
* Succession following the death of the previous holder
* Automatic assumption of existing positions that have become vacant

'''Triggers that cause the game to reevaluate noble positions:'''
* Succession of a [SITE]-position due to the death of the current holder
* [[Advanced_entity_position_mechanics#Election_Day|Election Day]]
* Automatic assumption of a [SITE]-position that becomes vacant
* (Re)assigning any site position manually
* Settlement elevation on the LAND_HOLDER track (e.g. gaining a [[Baron]] or [[Count]])

=Gaining a position=
There are several ways a unit can gain a position:
* Appointment: A unit is appointed by another unit or by the player.
* Election: A unit is elected by and among the members of the entity
* Assumption: A position is neither elected or appointed: a random unit just simply 'takes' the position
* Succession: a unit is the valid successor of this position(A), either by its current position(B) or because they are that position(A)-holder's heir.

Available positions will automatically be assigned to a random civ member when a new site/civ is created.

==Who can take a position==

* If so defined, a unit needs to be the right caste and/or class - it does not seem to work with creature types.
* The unit needs to be an adult member of the site or its parent civ-government; that is also CAN_LEARN or INTELLIGENT (SLOW_LEARNER cannot take positions) or otherwise is able to think.

==Appointment==

Positions that have an [APPOINTED_BY:position] token require that position to exist, to be available and appointed. Any position that is APPOINTED_BY can be appointed if the appointer's position is filled in.
For site-positions to be appointed, it is required that the appointer is present at that location.

If the appointing unit is temporarily not present, or if that position is not filled, positions depending on it cannot be appointed. This is the case with [[militia captains]], when the [[militia commander]] is on a [[mission]].

A site position cannot appoint a civ position ''or'' LAND_HOLDER in any way whatsoever.

Civ-level positions can appoint other civ-level positions and site-level positions can appoint other site-level positions.

Contrary to what has been said elsewhere, civ-level nobles also can appoint site-level nobles. They need to be at the site to do so. Landholders can appoint both site-level and civ-level nobles. These systems are therefore not as separate as was assumed.

'''Mutual appointment''' cannot take place. If these are the only requisites of the position, then the positions will never appear or get filled. These unfillable positions can be put to good use, for example, to replace a position that is no longer needed without creating a new one.

'''Self appointment''' doesn't normally work. If you have a position that is only appointed by itself, it is never appointed and also cannot be assumed. However, if the position has a number higher than 1, and is filled by multiple units (for example by another position that is now empty), than those units can re-assign or appoint each other from that their shared position.

If an APPOINTED_BY token refers to a non-existing position's code, the effects are as if the appointment token doesn't exist at all.

===Automatic appointment in world-gen and on the civ level===

Outside of fortress mode, the game will always attempt to appoint nobles whenever possible, as long as these positions are '''available''', even if they are invisible to the player.
It shows this message in legends: "(unit name) has been appointed to the position of (position name)"

In world-gen, all positions become available and are automatically appointed, taking population- and appointment-requirements into consideration.

Positions that are REPLACED_BY are culled and won't be filled.

If a citizen of your fortress holds a civ-level position that can appoint another civ-level position, the appointment will happen automatically and without player intervention. It may happen that another citizen of your fortress is appointed by that unit, creating civ-level position holders in your fortress, but it is unknown what is required to force this effect.

===Manual appointments by players in fortress mode===
In fortress mode, the positions that need to be appointed stay empty on embark. and it is the player's job to appoint those. A player can appoint a unit to any available position, according to the hereabove mentioned conditions. The player takes the role of the automatic appointment-system, but has no direct control over elections, successions and replacement. There are some differences in what is possible at world-gen sites and at player-controlled sites.

* A position that is appointed by a unit present as a fortress citizen, can be appointed, re-appointed or left vacant. This means also by civ-level nobles living as a citizen in your fortress; not when they are only visiting, like the diplomat.
* A position whose appointing positions are all either vacant or [REPLACED_BY] can no longer be appointed. If the position is already filled, it cannot be reappointed or vacated; the current holder simply remains in office.
* A position that is APPOINTED_BY a unit present as the land_holder of your site, can be appointed, reassigned or left vacant.
* A position that has SUCCESSION BY_HEIR or BY_POSITION can 'initially' be appointed and also re-appointed or left vacant, but as soon as the [[nobles]] screen closes, ''it can no longer be replaced or left vacant''. From then on, the succession-rules determine who gains that position when the current holder loses the position. This works even if the SUCCESSION:BY_POSITION-position is vacant or replaced.
* A position that is ELECTED nor APPOINTED_BY, can always be (re-)appointed by the player. This is the case with the [[Expedition leader]]. If it is left vacant however, it cannot be appointed, but will be assumed shortly after.
* A position that is both ELECTED and APPOINTED_BY, cannot be appointed by the player. Contrary to world-gen sites, its slot is visible, but it doesn't show the +-sign. This is either by AS_NEEDED or by a fixed number. Even if the position somehow gets filled (re)assignment is never possible
* A player can appoint a number of units to a position, as much as the NUMBER token dictates. If it is AS_NEEDED, the player may create as many slots as they like, also contrary to world-gen sites.
* A civ-position can never be appointed, even if the appointing civ noble is a citizen of your fortress. A civ position also never can be re-assigned or left vacant, would that position be defined as appointed by a site-position.

==Election==
Read more in [[Elections]]. The message that is shown is: "(creature name) has been elected to the position of (position name)"

In worldgen, there is no functional difference between ELECTED and non-appointment, except that elected nobles tend to have high social skills and/or skills related to the position, while non-elected ones are assigned randomly. See: [[Elections]]

A succession goes before an election.

A position that is both ELECTED and APPOINTED_BY never gets elected. Even if the appointees' position somehow gets filled, (re)-elections won't happen. So, it doesn't seem possible to have an elected position become available when a certain other position becomes filled.

An ELECTED civ-(or LAND_HOLDER) position at your site will never be (re)-elected in fortress mode. So real (re-)election only works with SITE-positions.

=== {{text anchor|Election Day}} ===
Election Day takes place on the 17th of Summer. On this day, a full reevaluation is performed, including all currently elected positions, which are subject to re-election. Contrary to the information on [[Elections]], nothing occurs at the start of a season.

Positions that are both [APPOINTED_BY] and [ELECTED] will not be re-elected on Election Day when assigned through [SUCCESSION].

=== Election Eligiblity ===
Any citizen may stand for election. Eligibility cannot be restricted using [ACCEPTED_CREATURE], [REJECTED_CREATURE], [ACCEPTED_CLASS], [REJECTED_CLASS], or [GENDER]. Units currently having a [SUCCESSION]-position even may be elected for a position with a [SQUAD]-token, which is otherwise impossible to assign or even succeed.

=== Skills ===
In elections, skills are taken into account for the tokens of the position which is elected.
{| class="wikitable"
|+ Relevant skills per position token
|-
! Position Token !! Relevant skills
|-
| Responsibility [[Position_token#DELIVER_MESSAGES|[DELIVER_MESSAGES]]] || [[Ambusher]], [[Observer]] and [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#ACCOUNTING|[ACCOUNTING]]] || [[Record_keeper|Record keeper]]
|-
| Responsibility [[Position_token#ESPIONAGE|[ESPIONAGE]]] || [[Schemer]]
|-
| Responsibility [[Position_token#HEALTH_MANAGEMENT|[HEALTH_MANAGEMENT]]] || [[Diagnostician|Diagnostician]]
|-
| Responsibility [[Position_token#MAKE_INTRODUCTIONS|[MAKE_INTRODUCTIONS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#MAKE_PEACE_AGREEMENTS|[MAKE_PEACE_AGREEMENTS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#MAKE_TOPIC_AGREEMENTS|[MAKE_TOPIC_AGREEMENTS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#MANAGE_PRODUCTION|[MANAGE_PRODUCTION]]] || [[Organizer]]
|-
| Responsibility [[Position_token#MEET_WORKERS|[MEET_WORKERS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#RECEIVE_DIPLOMATS|[RECEIVE_DIPLOMATS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#RELIGION|[RELIGION]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#TAME_EXOTICS|[TAME_EXOTICS]]] || [[Animal_trainer|Animal trainer]]
|-
| Responsibility [[Position_token#TRADE|[TRADE]]] || [[Social_skill|Social skills]] and [[Appraiser|Appraiser]]
|-
| [[Position_token#SQUAD|[SQUAD]]]-token || [[Tactician]] and [[Leader]]
|}

==Assumption==

A position that is not APPOINTED_BY nor ELECTED, or is appointed by positions that are not available in your site or civ, will be assumable by a random dwarf. If it has responsibilities that require certain skills, then these are taken into consideration on embark, but not when the position is assumed during the actual game.

Normally, one to three units will take the into consideration to assume a position. Most of the time when there are multiple open positions, only a single unit will assume all of them. However, a position that has REJECTED_CREATURE, REJECTED_CLASS, ALLOWED_CREATURE or ALLOWED_CLASS will be filled with all different units, even if the creature or class mentioned is irrelevant. It seems that this forces the game to loop over all the available units.

The message that is shown in Legends mode is: "(unit name) has assumed the position of (position name)". This may also take place in fortress mode, which then shows this message to the player.

If an assumable position becomes empty, it will be assumed within a day. This is the case when you leave the position of expedition-leader vacant. It also happens with entities.

Assumable positions that become empty will not be assumed if that position has a valid [SUCCESSION] -successor. In that case, the successor inherits the position.

Even positions that are somehow invisible because they cannot be directly APPOINTED_BY players, can be assumed.

When you embark, the assumable positions are automatically assigned to a random unit. If there are multiple of these positions at embark, they all are assigned to the same unit. If there are enough positions available, multiple units may gain a position, but often no more than three different ones.

If a dwarf in fortress mode assumes a position, that already has another position, it will leave the current position empty. When that position also is assumed, then this will continue until all positions have a dwarf appointed to them, with no other position.

A unit that already has a position with a [SUCCESSION] token won't take assumable positions into consideration that have a [SQUAD] token. This can be used by the modder to prevent unwanted loss of current positions.

A position that has an appointer which got replaced because of REPLACED_BY, will not become assumable. Also, positions that have an AS_NEEDED appointer that is not yet filled (or ever), will also not be assumed.

==Succession==

If a position-holder dies or advances to a new position via succession, the position will be granted to another unit based on the [SUCCESSION] tag. If they have an heir or the succeeding position exists, that unit will be assigned. If not, a new one will be appointed according to the usual rules. The message that is shown is: "(creature name) being the rightful heir, has inherited the position of (position name)"

The succeeding creature will also lose its previous position. When succession is defined using BY_POSITION, the unit naturally loses the referenced position. However, it also loses any other positions it may hold. If a unit could simultaneously inherit multiple positions, the last-defined succession overrides the earlier one, clearing the previously acquired position

Succession works both at site-level and at civ-level, both in world-gen and in fortress-mode. Succession by position on the civ-level is also visible and functional in fortress-mode. If both civ-level nobles are a citizen of your fortress, succession is applied visually. Vanilla example: The [[druid]] is succeeded by the [[acolyte]]. This means that as soon as the druid dies, the acolyte takes over.

When a position that is succeeded by position becomes available, immediately it is checked if a position-successor is available and the position is filled with that unit. Even if this is an [ELECTED] position, succession goes first. When elections eventually do happen, succession plays no role.

It is possible to assign multiple levels of [SUCCESSION:BY_POSITION] in different positions, creating a line of positions where the death of one causes all those "below" them to advance.

A position can have multiple tokens with position-succession. It looks to be random which one is used. It is not always:
* The first or last defined token
* The first or last appointed unit
* the oldest or youngest
* one with a higher or lower precedence
* a unit with relevant skills

When a position is defined with a Succession-type, that unit cannot have another position that has a Squad-type. If the succession-position itself has a squad, than it can be assigned another position with a squad, but then it will loose the previous succesion position. See further details by "Squad"

Assumed positions can also be succeeded by position, if the current holder dies.

If the successor is an AS_NEEDED position, the used unit will leave a vacant position-slot on its removal by succession. This empty slot remains a real slot, which will only be cleaned up if you (un)appoint a unit to this position-series. It isn't cleaned up after regular position validation.

A civ-level position of a unit living at your site might be inherited by a unit holding that does not currently live at your site. This, unfortunately, moves that position to a unit off site. This may also happen with the landholder of your site, for example when it is succeeded by another civ-level position. This currently poses an unsolved challenge.

===Eligibility for succession===
Succession is restricted by the tokens [ACCEPTED_CREATURE], [REJECTED_CREATURE], [ACCEPTED_CLASS], [REJECTED_CLASS] and [GENDER].

===Site and civ combined succession===

Succession can work when combining site positions with civ-level positions or land_holders, but only in world-gen mode. In fortress mode, it only works with combining the same level of nobles, with Landholders regarded as civ-level. So, in fortress mode, a site's position cannot succeed a landholder's position and it cannot succeed another type of civ-level position, and vice versa.

This won't work even if the positions:
* are AS_NEEDED or having a fixed number.
* Are LAND_HOLDERs.

===Succession [BY_HEIR]===

When a heir is needed for succession, all children and then other relatives are validated. They cannot take the position if their status does not allow it, for example if they have become a member of another civilisation. See: "Who can take a position". If the unit has no valid heir on that location, the position may go to a unit living on another site. This may cause the title of Landholder of some land to be inherited by a unit living somewhere else. That might be a problem, because then you lose your landholders.

===Premature Succession===

There are cases where [SUCCESSION:BY_POSITION] is applied prematurely: at the moment a position is first created and becomes appointable or assumable, rather than after a current holder leaves. In this situation, the succession mechanism assigns a holder immediately, without any player interaction.

When a position becomes available for the first time, the game checks whether a valid successor-by-position exists. If so, that unit is assigned instantly. It can affect positions that would normally be appointed or elected by the player, causing succession to trigger before the player has any opportunity to intervene.

This behavior occurs only in Fortress mode, but can be applied both on [SITE]-positions as well in civ-positions. That last one however is a bit harder to control. Example: [[Advanced entity position mechanics#The Archduke|The Archduke]]

This premature succession only occurs the first time a position becomes available (i.e. when it is created and becomes appointable or assumable). Even if the position remains vacant and the conditions for succession improve later, premature succession will not trigger again. From that point onward, only normal succession rules apply.

Using premature succession, a position that has [ELECTED], [APPOINTED_BY], or both, can be filled directly.
Notably, positions that combine [ELECTED] and [APPOINTED_BY] are normally impossible to fill through regular mechanics. Premature succession bypasses both election and appointment entirely, making this combination uniquely reachable through this mechanism.

No initial election takes place, and no subsequent elections will ever occur for that position. Succession always takes precedence over election, both in premature succession and in normal succession cases.

This behavior applies only in Fortress mode, not during world generation. World-gen uses simplified and more efficient mechanics, and this interaction does not occur there. Premature succession can affect both site-level and civilization-level positions.

====Multiple succession chains====

Multiple succession chains may be defined and are resolved in the order they appear in the raws.

If a position has both:
* a direct succession chain (A → C), and
* a multi-step chain (A → B → C),

and intermediate positions are vacant, resolution proceeds according to raw order. A common outcome is:
# The direct succession (A → C) is applied first, assigning A to C.
# The remaining chain then advances (A → B).
# If C still has empty slots, the final step (B → C) may occur.

If position B is already filled, behavior depends entirely on raw definition order:
* nothing may happen, or
* B may move to C first, followed by A moving to B.
====Working triggers====
Premature succession is triggered when a succeedable position is created under the following conditions:
* The succeedable position is created because its [REQUIRES_POPULATION] threshold is reached. This applies even if the position is not [APPOINTED_BY]. Premature succession takes priority over automatic assumption (e.g. the mayor declaring themselves within a day).
* The succeedable position can be [APPOINTED_BY] another position of the same level (site or civ) that has just been created because its [REQUIRES_POPULATION] was reached.
* The succeedable position can be appointed by another [SITE] [AS_NEEDED] position that has just been created and filled.
* The succeedable (site or civ) position is [APPOINTED_BY] the [LAND_HOLDER] position, which has just been created due to site elevation. This typically resolves when the diplomat leaves the map, at which point the landholder position becomes active.
* If all other requirements are met, premature succession can occur immediately after unpausing following embark, for positions with [REQUIRES_POPULATION:7].
====Non-working triggers====
Premature succession does '''not''' occur in the following cases:
* An [AS_NEEDED] succeedable position slot is manually created by the player while its succeeding position is already filled. [AS_NEEDED] positions must always be appointed after creation.
* The succeeding position is filled after the succeedable position becomes available. The moment of creation is the decisive trigger; filling the source position later is too late.
* The succeedable position can be appointed by another site or civ position with a fixed number of slots that has just been appointed. In this case, the succeedable position is just available for appointment itself, nothing more
* Any situation occurring during world generation.
* The succeeding position is [REPLACED_BY] the succeedable position. In this case, replacement removes the unit from the source position first, leaving no holder available for the succession mechanism to use.rst, leaving no holder available for the succession mechanism to use.
* The position is [APPOINTED_BY] a civ-level position, that just became a citizen of your fortress. It must be noted that those civ-level positions were active all that time and the succeedable position could be appointed even before. The monarchs arrival does not trigger premature succession

=Losing a position=

A unit can lose a position when:
* It dies
* It succeeds another position, even if it has nothing to do with the previous position.
* It is assigned to another SQUAD-holding position
* It is convicted of a crime.
* Another unit is ELECTED for the position
* Its position becomes replaced
* Another unit is appointed by the player, or the position is left vacant.
* It has assumed another position, as this always leaves the previous position vacant.

=Embarkment=
Two types of positions are automatically filled by embark.
* Positions without [APPOINTED_BY] or [ELECTED] (assumable). All these positions, even with a NUMBER higher than 1, are all filled with one to three dwarves. Contrary to assumption, this doesn't take into account any limitations. REJECTED_CLASS, ALLOWED_CLASS, REJECTED_CREATURE, ALLOWED_CREATURE and GENDER are applied, but without the normal spread you may expect with assumptions. Also it doesn't look at [SUCCESSION] and [SQUAD] limitations.
* Positions that are elected are filled-in by the normal election rules.

Positions that have a defined appointer are never initially filled at embark.

All positions that don't have [REQUIRES_POPULATION] or with a [REQUIRES_POPULATION] of 7 or lower, will be available at embark.

=Land Holders=

A Landholder is a '''special civ-level noble''' who gets a certain piece of land to hold, when that land is elevated to a certain level, determined by the tag [LAND_HOLDER] and by the landholder triggers in the game's settings. In vanilla, these are the baron, the count and the duke.

A unit gaining the landholder position does not migrate to that specific named land. In world-gen, they stay just where they are, probably at the capital. In fortress mode, you can suggest a citizen for the role. So for the time being that works.

Succession is then a real issue. If you use BY_HEIR, its solved when that landholder has children living at your site. But when its not the case, the title just goes to anyone randomly. Succession BY_POSITION works, but only in the civ-chain, and there's no way to guarantee a civ-holder is at your site at that time. Even with 'automatic spread' positions, it goes to one of them randomly.

==Functioning of the regular landholder chain==

The distinct difference between a landholder and a regular civ-level noble, is that a landholder may gain the position of landholder "of (sitename)" They are then seen as ruler of a particular site.

For a land_holder position to function as such, it has a few requirements:
* NUMBER:AS_NEEDED
* The first landholder-number of 1 is defined.
* No SITE (so civ) tag in that position.
*REPLACED_BY the next level landholder
If a landholder is defined with differentiating properties, it will function like a regular noble. A higher-up landholder that lacks the required tokens or connections will then not be used in elevation.

If a fortress meets the trigger for a new LAND_HOLDER tier when a caravan leaves, then the next time the outpost liaison or equivalent arrives, they will offer to make you an official colony, which will allow you to select all positions for that LAND_HOLDER level. Each time they appear, the outpost liaison will only promote your fortress one tier up the LAND_HOLDER track.

The landholder's LAND_NAME is not required for the functioning of this system. If omitted, messages will be shown with a more generic text.

==Appointment==

This mechanism differs from the regular methods of position management. It ignores all regular appointment- and election rules, so it more or less functions like automatic assignment. A landholder is, in vanilla, appointed by the monarch. Changing this doesn't seem to do anything. If they are appointed by a site-position, a not-yet-existing civ-position, or not appointed at all: the system keeps working as usual.

A landholder can appoint civ-positions and site positions. This works as expected: the positions only are appointed then when that landholder becomes available on civ-level or when he arrives at that site for site-level positions.

If your rank of landholder is the first of its rank in the realm, and is the sole appointer of some civ-position, then immediately as it gains the title, it will appoint the empty civ-slots. This may happen on your site, but the frequency and certainty is hard to determine.

==Succession==

Succession rules are applied to some extent:
* In world-gen it works according to succession rules, and site-positions can be used here. This means that a site position or a civ-position can inherit a landholder position, and vice versa.
* In fortress mode, once a landholder has been appointed, it then can inherit civ-level positions, and vice versa. This means that your baron can become king.
* Succession rules do not apply within the [LAND_HOLDER] chain; a count will not inherit a baron's land. This is because succession does not work well with the AS_NEEDED token.
* Premature succession works in fortress mode with landholders. If a unit gets a landholder's position and that landholder is the appointer of an as yet empty position, which is defined as succeeding from a third one, then the succession is immediately applied. The landholder themselves can even be the successor of a newly created position.
* A landholder's position is, in fortress mode, not successionable by a site-position or vice versa

===Impossibilities for succession by a site-position===
It would be very beneficial if the landholder can be succeeded by a [SITE]-position. So far, the following tests have not lead to positive results:
* making landholder and site-position both non-[DUTY_BOUND]
* make the site-position be [APPOINTED_BY] the landholder and/or the monarch
* give landholder and site-position [REJECTED_CREATURE]
* Let the monarch live at your site when succession could happen.
* Let the site-position be [REPLACED_BY] the landholder.

==Nomination==

The player is able to nominate a unit to become the LAND_HOLDER, but this only works with units of [LAND_HOLDER] level 1. The player can select all units, only limited by the PRECEDENCE of the current units' positions.

A unit that has a position with a PRECEDENCE lower or equal to that of the landholder's position, cannot be selected. This means that a baron (or count) from another site or the monarch cannot be selected, because their precedence is lower or equal.

The GENDER token does not work here: also units with the wrong gender (sorry) can be selected.

==Levels==
In mods, up to 10 levels of LAND_HOLDER may be defined.

If a landholder is replaced by a wrong landholder number (1 replaced by 3), then the number 3 is still correctly attached to the settlement.

If the current landholder has the highest available landholder number, then the next elevation will not happen - the diplomat will not elevate your fortress to a higher position, even if that position might be REPLACED_BY a lower landholder.

These chains do work:
* 1 -> 2a - > 2b -> 3
* 1 -> 3 -> 2 -> 4

These chains do not work:
* 2 -> 3 (need to start at 1)
* 1 -> 4 -> 2 -> 3 (stops after 4 as the highest)
* 1a -> 2, 1b -> 2 (only 1a and 2 work, 1b is not used)

==Moving landholders==

It may happen that a land-holder no longer lives at the site which they are the landholder of, specifically when the current landholder dies, leaving the title to an heir living somewhere else.

To prevent this from happening, you can make their succession from heir and make sure that their kids live at your site. Or, you can make their position succeeded by another civ position, and make it so that this civ position is somehow available on your site. But if multiple of these positions exist, it cannot be guaranteed that a citizen of your fortress will inherit the title.

In world gen, a landholder lacking the DUTY_BOUND-token will also move to the site they like, according to legends mode.

==Replacement by a generic civ-position==

If a landholder is replaced by an AS_NEEDED non-landholder civ-position, then this will work: the current landholder loses that title upon settlement-elevation and gains that civ-title. However, the civ-title lacks the landholder-property of being attached to the land. It will not show the name of the settlement alongside the position's name. So no "minister of Shovelmounts"

If a landholder is replaced by a general AS_NEEDED civ-position, that itself is also replaced by a generic AS_NEEDED civ-position, then firstly the elevation is executed and also the unit gains that new position. However, he immediately loses it, because an AS_NEEDED position that is replaced by another position can be filled initially, but units wont be able to hold that title.

==Landholder with fixed number==

A landholder's position that has a fixed number will be created and filled directly when the civilisation is born, so this position slot is then not available for the regular landholder-mechanic and will also not be used. That landholder will thus not be attached to a settlement.

It doesn't matter if the landholder's position is connected to the regular landholder's-chain with the REPLACE_BY token.

==Responsibilities==

When given a certain [RESPONSIBILITY], a landholder may function as a regular civ-level noble. If the position has [TRADE] or [OUTPOST_NEGOTIATING] responsibilities, then the landholder functions both as a diplomat and as an actual land holder. A landholder with the [MILITARY_STRATEGY] responsibility will travel around taming creatures in world-gen, according to legends mode.

Besides that, the responsibilities work the same as with any other on-site living position-holder, civ or otherwise.

=Military=
==Squad management==
In the vanilla game, the Squad interface only becomes available after a militia commander has been appointed. Until then, the window displays:{{DFtext|You must appoint somebody first to create a squad.}}

What’s surprising is how this is determined internally. In the entity raw definition, '''only the last two positions that include a [SQUAD] token are checked''' to decide whether the interface is accessible at all. As a result, if your hierarchy defines commanders A through E, appointing '''Commander D or E''' unlocks squad formation, while appointing A–C does nothing.

In other words, squad availability is not tied to ''having a militia commander'', but to ''which specific positions happen to be last in the raw list''—a notably hacky implementation.

These 'last two' are always the last two '''available positions.''' So if they get [REPLACED_BY] or become available because of [REQUIRES_POPULATION], the game adapts to those.

==Squad assignment==

Squads can be assigned, even if the leader position has no holder.

A specific unit can only have one position associated with a squad. If it gains another 'squad holding position', it is unassigned from the first one. This does not work with a 0-squad, so only 1+squads are taken into consideration. This technique can possibly be used to distribute all positions equally among all citizens. It does however not work with election and assumption.

If a civ-level position is associated with a squad and it gets a site-level squad-holding position assigned, it loses the current civ-position.

Squads can get really messed up, if you make the position (or multiple) either elected or not-elected and not-appointed, then this can cause the game to assign multiple squads to the same unit. Automatic assignment and election does not take squads into account, but the nobles screen does. This can cause the positions to be cleared as the game figures out that they have more than one position, and immediately get elected or assumed again.

Positions that cannot have a squad-position:
* A site- or civ-position with a [SUCCESSION] token cannot be appointed a squad-holding-position. The other way around, however, does work. For example, if a site-position with a [SUCCESSION]-token is appointed to a unit that has already a position with [SQUAD]. But when that squad position is assigned to another unit, it cannot be assigned back.
* A position with [SUCCESSION] can also not be assigned as a '''member''' of a squad.
* A squad-holding position with a formed squad cannot be appointed to another squad holding position.

If a position has at least one squad member, it cannot be left vacant. First, the squad has to be disbanded, then the position may be cleared.

==0-squads==
A 0-Squad is defined in a position as [SQUAD:0:member:members]. It does not seem to do anything useful as of now.
* It cannot be used to activate the [[Squad|military interface]]
* It does not restrict the assignment of [SUCCESSION] positions.
* Assigning this position does not clear any previously held squad position.
* The [[Leader]] and [[Tactician]] skill are not marked as relevant skills and are not taken into account in elections.
* It cannot be formed as a squad.

=Further testing=
The following questions may need additional testing. Feel free to add or answer
* Everything regarding COMMANDING and army-structure
** [http://www.bay12forums.com/smf/index.php?topic=175437.msg8331668#msg8331668]
** [http://www.bay12forums.com/smf/index.php?topic=165213.msg8335682#msg8335682]
** [http://www.bay12forums.com/smf/index.php?topic=174584.msg8026854#msg8026854]
* Everything regarding CONQUERED_SITE, but it is presumably just like site. But what if you combine SITE or LAND_HOLDER with it?
* Stuff about the monarch, its arrival and its entourage.

=Oddities (Bugs)=
Almost everything on this page could be called an oddity. Because of their unexpected usability, some may also be referred to as “undocumented features.” Others, however, are simply odd and not particularly useful, yet I hesitate to call them “bugs.”
* If a certain threshold is reached that makes an elected position electable, and the triggering event that initiates this evaluation is an assumption, then the resulting assumption is also referred to in the messages as an election

=Examples=

===The Founder===
The founder is a single dwarf, appointed at embark. They will be the only one ever to have this position and are not replaceable. When they lose their position some way, the position will not be assumed by another dwarf.
{{gamedata|title=The Founder|
[POSITION:THE_FOUNDER]
[NAME:the founder:founders]
[NUMBER:1]
[SITE]
[ALLOWED_CREATURE:DWARF:ALL] - will only be filled at embark, but not assumable later.
[REJECTED_CREATURE:DWARF:ALL] - will only be filled at embark, but not assumable later.
[SUCCESSION:BY_POSITION:THE_FOUNDER] - not unassignable, also cannot be assigned to a [SQUAD] position.
[PRECEDENCE:200]
Non APPOINTED_BY
Non ELECTED
Optional: Add responsibilities to make the game select a unit with certain skills.
}}
===Marriage bar===
Dwarven matrons are held in great honour. Upon marriage, a female dwarf is no longer expected to perform menial labour. All dwarven males hold this position by default, granting their spouses exemption from menial work.

The position becomes available with the arrival of the first migrants; otherwise, on embark, it would be assumed by females. Its succession rule is non-functional, but this prevents the player from unassigning the position. A squad size of 1 and the succession rules together prevent a unit from assuming the position more than once.

With precedence set to NONE, the position name is hidden, while LAND_NAME remains visible on the nobles screen. All married females receive the suffix “, Mrs.” and are marked as Nobles.

The practical usefulness of this position is debatable, but it serves as a clear demonstration of several mechanics.
{{gamedata|title=Mrs. Urist|

[POSITION:MRS_URIST]
[NUMBER:300]
[SITE]
[ALLOWED_CREATURE:DWARF:MALE]
Not APPOINTED_BY
Not ELECTED
[LAND_NAME:Dwarven male]
[NAME:dwarven male:dwarven male]
[PRECEDENCE:NONE]
[SPOUSE_FEMALE:, Mrs.:spouses]
[MENIAL_WORK_EXEMPTION_SPOUSE]
[REQUIRES_POPULATION:8]
[SUCCESSION:BY_POSITION:MONARCH]
[SQUAD:1:member:members]
}}
===The Archduke===
The archduke is the leader of the civilization, but exists only from landholder 4-level. Until then, its position remains vacant. When a settlement is elevated to tier 4 (grand duke), the grand duke can appoint the ruler of the civilisation, the archduke. Because of 'Premature Succession', they themself inherents that position immediately. Its heir then becomes grand duke.
{{gamedata|title=The Archduke| no POSITION:MONARCH

[POSITION:THE_ARCHDUKE]
[NAME:archduke:archdukes]
[NAME_MALE:archduke:archdukes]
[NAME_FEMALE:archduchess:archduchesses]
[LAND_NAME:a archduchy]
[NUMBER:1]
[PRECEDENCE:1]
[SUCCESSION:BY_POSITION:GRAND_DUKE]
[APPOINTED_BY:GRAND_DUKE]
(add additional monarch-stuff, like spouse name, demands etc.)

[POSITION:GRAND_DUKE]
[NAME:grand duke:grand dukes]
[NAME_MALE:grand duke:grand dukes]
[NAME_FEMALE:grand duchess:grand duchesses]
[NUMBER:AS_NEEDED]
[LAND_HOLDER:4]
// Optional ...
[PRECEDENCE:19]
[LAND_NAME:a archduchy]
[RESPONSIBILITY:LAW_MAKING]
[RESPONSIBILITY:RECEIVE_DIPLOMATS]
[SUCCESSION:BY_HEIR]
[APPOINTED_BY:THE_ARCHDUKE]
(add additional landholder-stuff)

!!add to [POSITION:DUKE]
[REPLACED_BY:GRAND_DUKE]

}}
{{Category|Modding}}
{{Category|Entities}}
{{Category|Guides}}

Advanced entity position mechanics

2026-02-10T10:33:50Z

Joostheger: /* Examples */

{{Quality|Fine}}
{{Modding}}

= Introduction =

[http://www.bay12forums.com/smf/index.php?topic=182239.0 Discussion thread on the forum]

This page documents observed and tested behavior of entity positions in Dwarf Fortress that is not fully described elsewhere on the wiki. It focuses on advanced interactions between position tokens, including appointment, succession, election, and responsibility handling, across both civilization-level and site-level entities.

The mechanics described here are based on empirical testing in world generation and fortress mode, supplemented where necessary by raw analysis. In several cases, the game’s behavior is determined by evaluation order and interaction between multiple tags, rather than by individual tokens in isolation.

This page is intended for modders and advanced players who are designing or debugging custom entity position structures. It does not restate basic position mechanics, but instead highlights edge cases, non-obvious interactions, and behaviors that may appear inconsistent or undocumented.

Unless stated otherwise, the described behavior applies to current versions of the game and may differ from older releases.

==What is an entity? What is a position?==
An [[entity]] is an organizational structure that can have relationships with other entities, usually known as a [[civilization]] or a "[[site]] government" in the game, but merchant [[guild]]s, religious organizations, necromancer towers, and [[bandit]] groups are also entities. An entity can have positions - in most cases, these are hardcoded and generated by the game, but as for civilizations and sites, the [[raw file]]s can be customised.

A position is a special relationship between a unit and an entity. The unit holding a position has a larger influence over that entity than other citizens. Positions are mostly known as [[nobles]], but in this article. the technical term is used.

=Position levels (Site/Civ) and their interaction=
There are two basic types of positions that are customizable: '''civ(ilization)''' level and '''site level'''. Positions with the tag [SITE] are at site level, positions without the tag [SITE] are at 'civ level'. These two types of nobles can be considered '''loosely related systems'''. There are a few places where they can interact with each other.

Civ-level positions are in charge of the civilization as a whole, managing national [[trade]], laws, and [[war]]s. These are, for example, the vanilla [[monarch]], [[diplomat]] and [[general]]. (Note that the general doesn't do anything in either mode in the current version.)

'''[LAND_HOLDER]''' nobles are also positions at civ-level. These units are members of the national government, but have gained authority over some land or site. Once they do, they move to that place, but their position is still regarded as a civ-level position.

Site-level position holders are members of a site government (subsidiary to the civilization), and manage local affairs in that location. These are, for example, the [[mayor]], the [[sheriff]] and the [[broker]].

==Table of interaction between different position levels==
In this table, the possible interactions between different position levels are summarized.
The header row shows the positions defining the tokens.

The left column shows the position type that is referred to.
Example:
{| {{prettytable}}
|- bgcolor="#ddd"
! referred position-type
! LAND_HOLDER
|-
| civilization
| (baron is) APPOINTED_BY:MONARCH
|}
color coding: 
* Exists in vanilla
* Possible with mods
* Not possible
* possible to some extent.
* not yet fully investigated.
{| {{prettytable}}
|- bgcolor="#ddd"
! referred position-type
! Civilization
! SITE
! LAND_HOLDER
! CONQUERED_SITE

|-
| Civilization
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION '''(1)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION

|-
| SITE
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION '''(2)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY '''(3)''' COMMANDER REPLACED_BY SUCCESSION '''(4)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION

|-
| LAND_HOLDER
| APPOINTED_BY COMMANDER REPLACED_BY '''(6)''' SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION '''(5)'''
| APPOINTED_BY COMMANDER REPLACED_BY '''(7)''' SUCCESSION '''(8)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION

|-
| CONQUERED_SITE
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
|}

Remarks:
# Works only in world-gen, if a unit with that civ-position is present at the site.
# Works only in world-gen, the site-position holding unit will then move to the capital.
# Is completely ignored
# Works only in world-gen.
# Works only in world-gen.
# Won't appear at all
# This is necessary for the landholder chain to work properly, it doesn’t work otherwise.
# This works only outside of the landholder chain, so when landholders are simply regarded as civ-level nobles. might also work in world-gen
#

== Other interactions ==

Unfortunately, interactions with positions of other entities don't seem possible, such as APPOINTED_BY: HIGH_PRIEST. With [VARIABLE_POSITIONS], positions are automatically created with codes like CUSTOM_LAW_MAKER_2, but interaction with these positions don't seem to work, either. For more info on those, see [[Variable positions]]

=General=

==Civ-level nobles living at your site==
Nobles from your civilization can come to live at your fortress. This happens in vanilla with landholders such as [[Baron]], [[Count]] and [[Duke]], with the Monarch, but sometimes also with non-landed LAND_HOLDERS.

When a civ-level noble becomes a [[citizen]] at your location, their position is shown among the site-level positions in your [[nobles screen]]. They appear to function as a site-level noble. They may have [[demand]]s, [[mandate]]s, [[squad]]s and the like. They can appoint nobles at the site-level.

If they have certain [RESPONSIBILITY]ies, they do the tasks that go with them.

==Fortress mode, world-gen and their differences==
Their are a few differences in how positions function between fortress mode (normal play mode) and the world generation (world-gen).

In '''fortress mode''', the player has some control over the appointment of nobles, limited by elections, automatic filled-in positions and succession rules. Pre-fortress mode, which is referred to as '''world-gen''', the game will always attempt to assign nobles whenever possible. It is subjected to the same rules as in fortress-mode, but there are some exceptions. In '''[[World activities]]''', which is the thing that happens in the world while you play fortress mode, it seems as if the same rules are applied as fortress mode.

A difference between player-fortress-mode and world-gen, is causes by visibility (see below). Positions that are not visible by the player and thus not available for assignment, will be available in world-gen and will thus be automatically assigned.

In fortress mode, a position that is both [ELECTED] and [APPOINTED_BY], cannot be appointed by the player and is also not elected, and can thus not be filled. But in world-gen sites however, these positions are automatically filled.

Positions with [AS_NEEDED] are almost never created and filled in world-gen (depending on their [RESPONSIBILITY]ies), but can always be used in player mode.

A position can, in fortress mode, be filled by the same unit. A unit can gain multiple positions in fortress mode, for example because of [[elections]]. This will not happen in world-gen mode: a unit can only have one position. See also remarks on 'embark' and 'Losing a position'.

In world-gen, [SUCCESSION] between civ-levels and [SITE-]levels may happen. This will not happen in fortress mode, or even off-site in [[World activities]].

In fortress mode, premature SUCCESSION may happen. This will not happen in world-gen mode.

==Units holding multiple positions in multiple entities==
A unit can hold multiple positions in its civilisation or in its site-entity, however this does not happen in world-gen. Only at player-managed sites can units be holding multiple positions at once. (It is probably not possible for a unit to hold a position in two different civilisations or two different sites.)

In world-gen, if there are too many positions to be filled, they simply stay empty until more units are available. E.G, a unit at a site might inherit a civ-level position and still remain a member of the local government. When this happens however, they move to the capital. If a unit gains a new position, either inherited or otherwise, it drops the previous one. If a unit assumes a civ-position in fortress mode, it leaves the current position.

If a unit holds the same (site-)position multiple times, it has no additional effect.

If a unit holds multiple different positions of the same entity, it has all those positions' responsibilities and properties, stacked up. Presumably, the demands for those combined positions are determined by the highest.

A unit holding a position with a succession token can be assigned another position with a (different) succession token.

A unit holding a position with a squad-position cannot hold another squad-position. It is dropped from the first, when it gets its second assigned.
A unit holding a position with a succession token cannot be assigned to a squad-position - the unit is simply not available. It works the other way around, though.

=[PRECEDENCE]=
The first defined position with precedence of 1 counts as the ruler of the civ. See also: [[Position_token#PRECEDENCE|PRECEDENCE]].

If the precedence is omitted or has a negative value, the game sets 0 as precedence, which seems to have no effect whatsoever.

When a unit has multiple positions, the name of the position with the highest rank in precedence is shown behind the unit's name.

If you omit precedence entirely, or set it to [PRECEDENCE:NONE], the position name will not be shown after the unit’s name. Your *Urist Mason* will remain simply *Mason*. This can be useful for positions that are unimportant or purely functional. The position will also not appear in the civilisation overview of your site on the world map. The position name is shown in messages, but remains hidden on the nobles screen as well. To make it visible there, use [LAND_NAME].

=[RESPONSIBILITY]ies=
Both civ and [SITE] positions can carry responsibilities. However, not all responsibilities are active for both types: some function only for civ positions, others only for site positions. When a civ noble arrives at a site and takes up residence, they do not perform responsibilities that are intended for SITE nobles. As a result, these responsibilities neither trigger their associated tasks nor unlock related game mechanics. For example, a civ-level manager living in a fortress will not perform management duties there and doesn't unlock the management-screen, even with an assigned office.
This behavior applies to the following [SITE]-level responsibilities:
* [RESPONSIBILITY:ACCOUNTING]
* [RESPONSIBILITY:BUILD_MORALE]
* [RESPONSIBILITY:HEALTH_MANAGEMENT]
* [RESPONSIBILITY:LAW_ENFORCEMENT]
* [RESPONSIBILITY:MANAGE_PRODUCTION]
* [RESPONSIBILITY:MEET_WORKERS]
* [RESPONSIBILITY:TRADE] (functions differently)
Other responsibilities may be affected as well, but have not yet been fully tested.

==[DELIVERS_MESSAGES]==
The only [AS_NEEDED]-position that is created in worldgen based on responsibility is that of the site-level responsibility [DELIVERS_MESSAGES].

==Outpost Liaisons and Diplomats==
Civ-positions with the responsibility [ESTABLISH_COLONY_TRADE_AGREEMENTS] ([[Outpost_Liaison|Outpost Liaison]]s) will meet with the site-noble who has responsibility for [RECEIVE_DIPLOMATS] and the highest rank of precedence (i.e. the lowest precedence value). Usually this is the [[Expedition_leader|Expedition leader]].

Once a [LAND_HOLDER] is assigned to the site, civ-positions with the responsibility [MAKE_TOPIC_AGREEMENTS] ([[Diplomat]]s) will meet with '''civ'''-level nobles present at the site who have the [RECEIVE_DIPLOMATS] responsibility. If multiple eligible nobles are available, one is selected at random. If no eligible noble is present, the diplomat leaves angrily. If the landholder is no longer present at the site, diplomats will not arrive at all.

It appears that Outpost Liaisons and Diplomats are chosen for a diplomatic mission based on availability. When multiple candidates exist, the position defined last in the raws is most often selected.

==[TRADE]==
Civ-level nobles with [TRADE] will arrive with the caravan, just as the Outpost Liaison. Their behavior is no longer active in the vanilla game, but the mechanics are still present. See [[40d:Guild_representative|Guild representative]] for more details. This civ-noble will only meet with the SITE noble with [TRADE], usually the [[Broker]].

If two civ-nobles exist with both [TRADE] and [ESTABLISH_COLONY_TRADE_AGREEMENTS], they both arrive at the same time. Even if both tokens are assigned to a single position, if more than one instance of that position exists, two of them will arrive. However in that case, somehow the elevation of the site and appointment of landholder isn't offered.

If the SITE-noble they intend to meet has both [TRADE] and [RECEIVE_DIPLOMATS], only one meeting will proceed and the other is cancelled. However, when two SITE-nobles are available, each with either [TRADE] or [RECEIVE_DIPLOMATS], both meetings will proceed and both civ-nobles will attempt to negotiate a trade agreement. It is not known what happens if these agreements are accepted or refused.

In the trade depot, the last defined position with the [TRADE] responsibility is shown as broker. However when requesting a trader, the first defined position with [TRADE] will actually go there to do the trade.

==World-gen effects of the [RESPONSIBILITY] of available positions ==
It is possible to cause civs and individual sites to change their behavior substantially when they reach a certain size, by controlling nobles.
* If a site can only appoint a position with [MILITARY_GOALS] after reaching a particular size, that site will not send armies on missions until the required size is reached.
* A civ-level [LAW_MAKING] position is required for the civilization to have any kind of cohesion. Without it, sites will be constantly embroiled in territorial disputes and civil wars will be commonplace.
* [MILITARY_STRATEGY] positions go out and tame wild animals. This makes your civ gain those animals as domesticated and also brings them in sieges.
* The [[Personality_facet|Personality]] of the position's holder determines how they lead the civ.

=Availability and visibility=
==Availability of (new) positions==
Warning: Do not mistake "availability" for "visibility"!

Of all the possible positions existing in your site's entity, there may only be some available.
* Positions with [REQUIRES_POPULATION] require the population to have a specific size.
* Positions with [REQUIRES_MARKET] will only appear in "large" sites (which may have different rules for different site types). This tag has no effect in fort mode.
* Positions that are appointed by positions that have an AS_NEEDED number. The appointable positions only become available after an appointer position-slot is created. This works also on civ-level. If a position is appointed by a Land-holder, it only becomes available, when that level of landholder is created.

Only the replaced positions are culled and are no longer available.
A position that requires a certain population will become available, even if it doesn't have [APPOINTED_BY] or [ELECTED]. In that case, see 'automatic assignment' and 'assumption'

In fortress mode, in some cases 'succession' is evaluated immediately after a position becomes available. See: Succession.
==Visibility of positions==
A position might be available, but can still be invisible for the player in the [[nobles screen]]. The positions with their respective holders are visible for players:
* All site-positions that are already filled-in (even if they could not be re-filled-in considering current conditions)
* Site positions that are appointable by a filled-in site position
* Site positions that are appointable by a filled-in civ position, when that civ positions holder becomes a citizen of your fortress.
* Civ positions of units that are also a citizen of your fortress.
If a position becomes available, for example because a certain pop number has been reached, or if it is available from the start(like expedition leader), as long as it cannot be appointed, it still is INVISIBLE for the player.

It might strike someone as odd if a position becomes filled automatically in fortress mode when that position is not even visible. This might be the case if the current holder of a non-appointable position dies or succeeds another position. Regardless of player visibility, these positions will be automatically filled in if the necessary requisitions are met. It might happen with the expedition leader.

A situation with a non-visible but available position, is for example when a position is solely appointed by the expedition leader, when the expedition leader's position is left vacant. It can no longer be appointed by the player and is invisible. Then, it gets automatically assumed, proving that the position still was available.

A position that is both [APPOINTED_BY] and [ELECTED] is visible, but players cannot interact with it.

=[NUMBER]=
A position might be defined with a number. In that case, as many as defined can be available. If the positions become available, in world-gen and when embarking, they are all filled-in completely.

If the ruling position (with PRECEDENCE of 1) has a NUMBER higher than 1, a random unit of the ones holding these positions is shown as ruler in the embark screen.

A [NUMBER] of 0 (zero) has the same effect as 1.

==Automatic spreading of assumed, non-singular positions==
If there are civ positions that have a NUMBER higher then '1' and which are assumed (not APPOINTED_BY or ELECTED) but are '''not DUTY_BOUND''', these are automatically spread among the civilisation, based on population. If there are a number of '''20''' available slots of that position, they spread among a civilization with a combined population of, for example, 1000 of which your fortress has 100 (10%), '''2''' of your fortress' citizens will assume that position.
This may probably also work with elected and appointed positions, but that may be depending on the death of the current holders and this needs more testing. Assumption works within a day, anyway.

==[AS_NEEDED]==
These positions can be created automatically by the game in world-gen. This, however, only works with:
* [LAND_HOLDER]'s
* squad commanders (needs more testing)
* Messengers at sites

For all other types of positions, they're not created in world-gen, even if they are defined with RESPONSIBILITY's. For example, even in war, the game wouldn't create a MILITARY_GOALS position, if they have AS_NEEDED as number.

However, in fortress mode / player mode, these positions can be created by the player at will.

Positions with AS_NEEDED need to be created first, before any symbols are assignable as 'symbols' (objects) for the position holder to carry or wear.

Positions with AS_NEEDED cannot be created and then ELECTED in fortress mode. It only works with APPOINTED_BY.

=Replacement and Required Population=

The token REPLACED_BY:position means that once the replacing position reaches its required population-number, the 'to-be-replaced' position will disappear. This is defined in REQUIRES_POPULATION. These tags are closely related to each other and seem to only have a meaningful function if combined. Nobles with REQUIRES_POPULATION require the population to have a specific size.

This works on the civ-level as well as on site-level, but those systems are in this mechanic strictly separated. Site-level positions cannot be replaced by civ-level positions and visa versa. This makes sense, because they both depend on their own population-count. When using REQUIRES_POPULATION on civ-level, it counts the total population of the civilisation.

See also: [[Advanced_entity_position_mechanics#Evaluation_of_Positions|Evaluation of positions]]

==Effect of replacement (and on [LAND_HOLDER]s)==

Replacement is immediate and complete - the current holding unit loses the position, even before SUCCESSION_BY_POSITION rules are applied. A position with a number of 1 will replace all the slots of a position with a higher number of slots.

Even if the next position is available but not visible, replacement still takes place. If a position is replaced, it is completely gone - it cannot be appointed, succeeded, elected or assumed any longer.
The unit immediately loses its position.

In legends, replacement is mentioned as: "(unit name) ceased to be (position name)" The replacement of an AS_NEEDED position empties the position's slot forever. In fortress mode, it may seem as if you can create new slots and appoint new units in the nobles screen, but this is reversed as soon as you close the window.

The landholder chain uses [REPLACED_BY] differently. It does not clear the position completely, but uses it for succession to the next level's position. [REPLACE_BY] is required to let that system work properly. This also means that the way in which landholders succeed (replace + as_needed) does not work in any other way.

Replacement between LAND_HOLDERS and other site- or civ positions does not work in any way. Only the vanilla replacement sequence between levels of LAND_HOLDERs does work. If the token is omitted for landholders, the landholder chain is broken, so replacement is required for the landholder system to work.

[REQUIRES_POPULATION] also does not work for [LAND_HOLDER], when you set [NUMBER] to 1. The position is not created when the required population is reached.

==What doesn't work==

'''Attention: If a position cannot be appointed, for example because of 'mutual appointment', it still exists according to replacement mechanics and will replace other positions if so defined. If a certain position(a) will be replaced by the baron's assistant, which can only be appointed by the [LAND_HOLDER] baron, than that position(s) still will be replaced from the start of the game, even if no baron or their assistant is ever present.'''

A position that is replaced by a somehow not-fillable position, is still replaced. This counts for mutual-appointing positions, replacement by not-yet-assigned landholders, replacement by AS_NEEDED positions, or replacement by not-yet-appointed positions.

Replacement does not work if the replaced position is a [LAND_HOLDER], even with civ-positions. In that case, the LAND_HOLDER's position is not replaced. It does not matter if AS_NEEDED is used, or a fixed number, and it also does not matter what type of position the replacer is. So this only works (correctly) with positions that become available by REQUIRES_POPULATION.

={{text anchor|Evaluation of Positions}}=
The game does not continuously check whether positions should become available, elected or be [REPLACE_BY]. This is well-known behavior—for example with the [[mayor]], who does not appear automatically when the required population ([REQUIRES_POPULATION]) is reached. Instead, positions must somehow be evaluated. This applies in several other situations as well

'''Cases that require a trigger:'''
* Election of a newly created position
* Election after the current holder dies
* Automatic assumption of a newly created position (this may take up to a day)
* New citizens (such as migrants) considering available positions
* Premature succession of a newly created position

'''Cases that do not wait for a trigger:'''
* Succession following the death of the previous holder
* Automatic assumption of existing positions that have become vacant

'''Triggers that cause the game to reevaluate noble positions:'''
* Succession of a [SITE]-position due to the death of the current holder
* [[Advanced_entity_position_mechanics#Election_Day|Election Day]]
* Automatic assumption of a [SITE]-position that becomes vacant
* (Re)assigning any site position manually
* Settlement elevation on the LAND_HOLDER track (e.g. gaining a [[Baron]] or [[Count]])

=Gaining a position=
There are several ways a unit can gain a position:
* Appointment: A unit is appointed by another unit or by the player.
* Election: A unit is elected by and among the members of the entity
* Assumption: A position is neither elected or appointed: a random unit just simply 'takes' the position
* Succession: a unit is the valid successor of this position(A), either by its current position(B) or because they are that position(A)-holder's heir.

Available positions will automatically be assigned to a random civ member when a new site/civ is created.

==Who can take a position==

* If so defined, a unit needs to be the right caste and/or class - it does not seem to work with creature types.
* The unit needs to be an adult member of the site or its parent civ-government; that is also CAN_LEARN or INTELLIGENT (SLOW_LEARNER cannot take positions) or otherwise is able to think.

==Appointment==

Positions that have an [APPOINTED_BY:position] token require that position to exist, to be available and appointed. Any position that is APPOINTED_BY can be appointed if the appointer's position is filled in.
For site-positions to be appointed, it is required that the appointer is present at that location.

If the appointing unit is temporarily not present, or if that position is not filled, positions depending on it cannot be appointed. This is the case with [[militia captains]], when the [[militia commander]] is on a [[mission]].

A site position cannot appoint a civ position ''or'' LAND_HOLDER in any way whatsoever.

Civ-level positions can appoint other civ-level positions and site-level positions can appoint other site-level positions.

Contrary to what has been said elsewhere, civ-level nobles also can appoint site-level nobles. They need to be at the site to do so. Landholders can appoint both site-level and civ-level nobles. These systems are therefore not as separate as was assumed.

'''Mutual appointment''' cannot take place. If these are the only requisites of the position, then the positions will never appear or get filled. These unfillable positions can be put to good use, for example, to replace a position that is no longer needed without creating a new one.

'''Self appointment''' doesn't normally work. If you have a position that is only appointed by itself, it is never appointed and also cannot be assumed. However, if the position has a number higher than 1, and is filled by multiple units (for example by another position that is now empty), than those units can re-assign or appoint each other from that their shared position.

If an APPOINTED_BY token refers to a non-existing position's code, the effects are as if the appointment token doesn't exist at all.

===Automatic appointment in world-gen and on the civ level===

Outside of fortress mode, the game will always attempt to appoint nobles whenever possible, as long as these positions are '''available''', even if they are invisible to the player.
It shows this message in legends: "(unit name) has been appointed to the position of (position name)"

In world-gen, all positions become available and are automatically appointed, taking population- and appointment-requirements into consideration.

Positions that are REPLACED_BY are culled and won't be filled.

If a citizen of your fortress holds a civ-level position that can appoint another civ-level position, the appointment will happen automatically and without player intervention. It may happen that another citizen of your fortress is appointed by that unit, creating civ-level position holders in your fortress, but it is unknown what is required to force this effect.

===Manual appointments by players in fortress mode===
In fortress mode, the positions that need to be appointed stay empty on embark. and it is the player's job to appoint those. A player can appoint a unit to any available position, according to the hereabove mentioned conditions. The player takes the role of the automatic appointment-system, but has no direct control over elections, successions and replacement. There are some differences in what is possible at world-gen sites and at player-controlled sites.

* A position that is appointed by a unit present as a fortress citizen, can be appointed, re-appointed or left vacant. This means also by civ-level nobles living as a citizen in your fortress; not when they are only visiting, like the diplomat.
* A position whose appointing positions are all either vacant or [REPLACED_BY] can no longer be appointed. If the position is already filled, it cannot be reappointed or vacated; the current holder simply remains in office.
* A position that is APPOINTED_BY a unit present as the land_holder of your site, can be appointed, reassigned or left vacant.
* A position that has SUCCESSION BY_HEIR or BY_POSITION can 'initially' be appointed and also re-appointed or left vacant, but as soon as the [[nobles]] screen closes, ''it can no longer be replaced or left vacant''. From then on, the succession-rules determine who gains that position when the current holder loses the position. This works even if the SUCCESSION:BY_POSITION-position is vacant or replaced.
* A position that is ELECTED nor APPOINTED_BY, can always be (re-)appointed by the player. This is the case with the [[Expedition leader]]. If it is left vacant however, it cannot be appointed, but will be assumed shortly after.
* A position that is both ELECTED and APPOINTED_BY, cannot be appointed by the player. Contrary to world-gen sites, its slot is visible, but it doesn't show the +-sign. This is either by AS_NEEDED or by a fixed number. Even if the position somehow gets filled (re)assignment is never possible
* A player can appoint a number of units to a position, as much as the NUMBER token dictates. If it is AS_NEEDED, the player may create as many slots as they like, also contrary to world-gen sites.
* A civ-position can never be appointed, even if the appointing civ noble is a citizen of your fortress. A civ position also never can be re-assigned or left vacant, would that position be defined as appointed by a site-position.

==Election==
Read more in [[Elections]]. The message that is shown is: "(creature name) has been elected to the position of (position name)"

In worldgen, there is no functional difference between ELECTED and non-appointment, except that elected nobles tend to have high social skills and/or skills related to the position, while non-elected ones are assigned randomly. See: [[Elections]]

A succession goes before an election.

A position that is both ELECTED and APPOINTED_BY never gets elected. Even if the appointees' position somehow gets filled, (re)-elections won't happen. So, it doesn't seem possible to have an elected position become available when a certain other position becomes filled.

An ELECTED civ-(or LAND_HOLDER) position at your site will never be (re)-elected in fortress mode. So real (re-)election only works with SITE-positions.

=== {{text anchor|Election Day}} ===
Election Day takes place on the 17th of Summer. On this day, a full reevaluation is performed, including all currently elected positions, which are subject to re-election. Contrary to the information on [[Elections]], nothing occurs at the start of a season.

Positions that are both [APPOINTED_BY] and [ELECTED] will not be re-elected on Election Day when assigned through [SUCCESSION].

=== Election Eligiblity ===
Any citizen may stand for election. Eligibility cannot be restricted using [ACCEPTED_CREATURE], [REJECTED_CREATURE], [ACCEPTED_CLASS], [REJECTED_CLASS], or [GENDER]. Units currently having a [SUCCESSION]-position even may be elected for a position with a [SQUAD]-token, which is otherwise impossible to assign or even succeed.

=== Skills ===
In elections, skills are taken into account for the tokens of the position which is elected.
{| class="wikitable"
|+ Relevant skills per position token
|-
! Position Token !! Relevant skills
|-
| Responsibility [[Position_token#DELIVER_MESSAGES|[DELIVER_MESSAGES]]] || [[Ambusher]], [[Observer]] and [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#ACCOUNTING|[ACCOUNTING]]] || [[Record_keeper|Record keeper]]
|-
| Responsibility [[Position_token#ESPIONAGE|[ESPIONAGE]]] || [[Schemer]]
|-
| Responsibility [[Position_token#HEALTH_MANAGEMENT|[HEALTH_MANAGEMENT]]] || [[Diagnostician|Diagnostician]]
|-
| Responsibility [[Position_token#MAKE_INTRODUCTIONS|[MAKE_INTRODUCTIONS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#MAKE_PEACE_AGREEMENTS|[MAKE_PEACE_AGREEMENTS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#MAKE_TOPIC_AGREEMENTS|[MAKE_TOPIC_AGREEMENTS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#MANAGE_PRODUCTION|[MANAGE_PRODUCTION]]] || [[Organizer]]
|-
| Responsibility [[Position_token#MEET_WORKERS|[MEET_WORKERS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#RECEIVE_DIPLOMATS|[RECEIVE_DIPLOMATS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#RELIGION|[RELIGION]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#TAME_EXOTICS|[TAME_EXOTICS]]] || [[Animal_trainer|Animal trainer]]
|-
| Responsibility [[Position_token#TRADE|[TRADE]]] || [[Social_skill|Social skills]] and [[Appraiser|Appraiser]]
|-
| [[Position_token#SQUAD|[SQUAD]]]-token || [[Tactician]] and [[Leader]]
|}

==Assumption==

A position that is not APPOINTED_BY nor ELECTED, or is appointed by positions that are not available in your site or civ, will be assumable by a random dwarf. If it has responsibilities that require certain skills, then these are taken into consideration on embark, but not when the position is assumed during the actual game.

Normally, one to three units will take the into consideration to assume a position. Most of the time when there are multiple open positions, only a single unit will assume all of them. However, a position that has REJECTED_CREATURE, REJECTED_CLASS, ALLOWED_CREATURE or ALLOWED_CLASS will be filled with all different units, even if the creature or class mentioned is irrelevant. It seems that this forces the game to loop over all the available units.

The message that is shown in Legends mode is: "(unit name) has assumed the position of (position name)". This may also take place in fortress mode, which then shows this message to the player.

If an assumable position becomes empty, it will be assumed within a day. This is the case when you leave the position of expedition-leader vacant. It also happens with entities.

Assumable positions that become empty will not be assumed if that position has a valid [SUCCESSION] -successor. In that case, the successor inherits the position.

Even positions that are somehow invisible because they cannot be directly APPOINTED_BY players, can be assumed.

When you embark, the assumable positions are automatically assigned to a random unit. If there are multiple of these positions at embark, they all are assigned to the same unit. If there are enough positions available, multiple units may gain a position, but often no more than three different ones.

If a dwarf in fortress mode assumes a position, that already has another position, it will leave the current position empty. When that position also is assumed, then this will continue until all positions have a dwarf appointed to them, with no other position.

A unit that already has a position with a [SUCCESSION] token won't take assumable positions into consideration that have a [SQUAD] token. This can be used by the modder to prevent unwanted loss of current positions.

A position that has an appointer which got replaced because of REPLACED_BY, will not become assumable. Also, positions that have an AS_NEEDED appointer that is not yet filled (or ever), will also not be assumed.

==Succession==

If a position-holder dies or advances to a new position via succession, the position will be granted to another unit based on the [SUCCESSION] tag. If they have an heir or the succeeding position exists, that unit will be assigned. If not, a new one will be appointed according to the usual rules. The message that is shown is: "(creature name) being the rightful heir, has inherited the position of (position name)"

The succeeding creature will also lose its previous position. When succession is defined using BY_POSITION, the unit naturally loses the referenced position. However, it also loses any other positions it may hold. If a unit could simultaneously inherit multiple positions, the last-defined succession overrides the earlier one, clearing the previously acquired position

Succession works both at site-level and at civ-level, both in world-gen and in fortress-mode. Succession by position on the civ-level is also visible and functional in fortress-mode. If both civ-level nobles are a citizen of your fortress, succession is applied visually. Vanilla example: The [[druid]] is succeeded by the [[acolyte]]. This means that as soon as the druid dies, the acolyte takes over.

When a position that is succeeded by position becomes available, immediately it is checked if a position-successor is available and the position is filled with that unit. Even if this is an [ELECTED] position, succession goes first. When elections eventually do happen, succession plays no role.

It is possible to assign multiple levels of [SUCCESSION:BY_POSITION] in different positions, creating a line of positions where the death of one causes all those "below" them to advance.

A position can have multiple tokens with position-succession. It looks to be random which one is used. It is not always:
* The first or last defined token
* The first or last appointed unit
* the oldest or youngest
* one with a higher or lower precedence
* a unit with relevant skills

When a position is defined with a Succession-type, that unit cannot have another position that has a Squad-type. If the succession-position itself has a squad, than it can be assigned another position with a squad, but then it will loose the previous succesion position. See further details by "Squad"

Assumed positions can also be succeeded by position, if the current holder dies.

If the successor is an AS_NEEDED position, the used unit will leave a vacant position-slot on its removal by succession. This empty slot remains a real slot, which will only be cleaned up if you (un)appoint a unit to this position-series. It isn't cleaned up after regular position validation.

A civ-level position of a unit living at your site might be inherited by a unit holding that does not currently live at your site. This, unfortunately, moves that position to a unit off site. This may also happen with the landholder of your site, for example when it is succeeded by another civ-level position. This currently poses an unsolved challenge.

===Eligibility for succession===
Succession is restricted by the tokens [ACCEPTED_CREATURE], [REJECTED_CREATURE], [ACCEPTED_CLASS], [REJECTED_CLASS] and [GENDER].

===Site and civ combined succession===

Succession can work when combining site positions with civ-level positions or land_holders, but only in world-gen mode. In fortress mode, it only works with combining the same level of nobles, with Landholders regarded as civ-level. So, in fortress mode, a site's position cannot succeed a landholder's position and it cannot succeed another type of civ-level position, and vice versa.

This won't work even if the positions:
* are AS_NEEDED or having a fixed number.
* Are LAND_HOLDERs.

===Succession [BY_HEIR]===

When a heir is needed for succession, all children and then other relatives are validated. They cannot take the position if their status does not allow it, for example if they have become a member of another civilisation. See: "Who can take a position". If the unit has no valid heir on that location, the position may go to a unit living on another site. This may cause the title of Landholder of some land to be inherited by a unit living somewhere else. That might be a problem, because then you lose your landholders.

===Premature Succession===

There are cases where [SUCCESSION:BY_POSITION] is applied prematurely: at the moment a position is first created and becomes appointable or assumable, rather than after a current holder leaves. In this situation, the succession mechanism assigns a holder immediately, without any player interaction.

When a position becomes available for the first time, the game checks whether a valid successor-by-position exists. If so, that unit is assigned instantly. It can affect positions that would normally be appointed or elected by the player, causing succession to trigger before the player has any opportunity to intervene.

This behavior occurs only in Fortress mode, but can be applied both on [SITE]-positions as well in civ-positions. That last one however is a bit harder to control.

This premature succession only occurs the first time a position becomes available (i.e. when it is created and becomes appointable or assumable). Even if the position remains vacant and the conditions for succession improve later, premature succession will not trigger again. From that point onward, only normal succession rules apply.

Using premature succession, a position that has [ELECTED], [APPOINTED_BY], or both, can be filled directly.
Notably, positions that combine [ELECTED] and [APPOINTED_BY] are normally impossible to fill through regular mechanics. Premature succession bypasses both election and appointment entirely, making this combination uniquely reachable through this mechanism.

No initial election takes place, and no subsequent elections will ever occur for that position. Succession always takes precedence over election, both in premature succession and in normal succession cases.

This behavior applies only in Fortress mode, not during world generation. World-gen uses simplified and more efficient mechanics, and this interaction does not occur there. Premature succession can affect both site-level and civilization-level positions.

====Multiple succession chains====

Multiple succession chains may be defined and are resolved in the order they appear in the raws.

If a position has both:
* a direct succession chain (A → C), and
* a multi-step chain (A → B → C),

and intermediate positions are vacant, resolution proceeds according to raw order. A common outcome is:
# The direct succession (A → C) is applied first, assigning A to C.
# The remaining chain then advances (A → B).
# If C still has empty slots, the final step (B → C) may occur.

If position B is already filled, behavior depends entirely on raw definition order:
* nothing may happen, or
* B may move to C first, followed by A moving to B.
====Working triggers====
Premature succession is triggered when a succeedable position is created under the following conditions:
* The succeedable position is created because its [REQUIRES_POPULATION] threshold is reached. This applies even if the position is not [APPOINTED_BY]. Premature succession takes priority over automatic assumption (e.g. the mayor declaring themselves within a day).
* The succeedable position can be [APPOINTED_BY] another position of the same level (site or civ) that has just been created because its [REQUIRES_POPULATION] was reached.
* The succeedable position can be appointed by another [SITE] [AS_NEEDED] position that has just been created and filled.
* The succeedable (site or civ) position is [APPOINTED_BY] the [LAND_HOLDER] position, which has just been created due to site elevation. This typically resolves when the diplomat leaves the map, at which point the landholder position becomes active.
* If all other requirements are met, premature succession can occur immediately after unpausing following embark, for positions with [REQUIRES_POPULATION:7].
====Non-working triggers====
Premature succession does '''not''' occur in the following cases:
* An [AS_NEEDED] succeedable position slot is manually created by the player while its succeeding position is already filled. [AS_NEEDED] positions must always be appointed after creation.
* The succeeding position is filled after the succeedable position becomes available. The moment of creation is the decisive trigger; filling the source position later is too late.
* The succeedable position can be appointed by another site or civ position with a fixed number of slots that has just been appointed. In this case, the succeedable position is just available for appointment itself, nothing more
* Any situation occurring during world generation.
* The succeeding position is [REPLACED_BY] the succeedable position. In this case, replacement removes the unit from the source position first, leaving no holder available for the succession mechanism to use.rst, leaving no holder available for the succession mechanism to use.
* The position is [APPOINTED_BY] a civ-level position, that just became a citizen of your fortress. It must be noted that those civ-level positions were active all that time and the succeedable position could be appointed even before. The monarchs arrival does not trigger premature succession

=Losing a position=

A unit can lose a position when:
* It dies
* It succeeds another position, even if it has nothing to do with the previous position.
* It is assigned to another SQUAD-holding position
* It is convicted of a crime.
* Another unit is ELECTED for the position
* Its position becomes replaced
* Another unit is appointed by the player, or the position is left vacant.
* It has assumed another position, as this always leaves the previous position vacant.

=Embarkment=
Two types of positions are automatically filled by embark.
* Positions without [APPOINTED_BY] or [ELECTED] (assumable). All these positions, even with a NUMBER higher than 1, are all filled with one to three dwarves. Contrary to assumption, this doesn't take into account any limitations. REJECTED_CLASS, ALLOWED_CLASS, REJECTED_CREATURE, ALLOWED_CREATURE and GENDER are applied, but without the normal spread you may expect with assumptions. Also it doesn't look at [SUCCESSION] and [SQUAD] limitations.
* Positions that are elected are filled-in by the normal election rules.

Positions that have a defined appointer are never initially filled at embark.

All positions that don't have [REQUIRES_POPULATION] or with a [REQUIRES_POPULATION] of 7 or lower, will be available at embark.

=Land Holders=

A Landholder is a '''special civ-level noble''' who gets a certain piece of land to hold, when that land is elevated to a certain level, determined by the tag [LAND_HOLDER] and by the landholder triggers in the game's settings. In vanilla, these are the baron, the count and the duke.

A unit gaining the landholder position does not migrate to that specific named land. In world-gen, they stay just where they are, probably at the capital. In fortress mode, you can suggest a citizen for the role. So for the time being that works.

Succession is then a real issue. If you use BY_HEIR, its solved when that landholder has children living at your site. But when its not the case, the title just goes to anyone randomly. Succession BY_POSITION works, but only in the civ-chain, and there's no way to guarantee a civ-holder is at your site at that time. Even with 'automatic spread' positions, it goes to one of them randomly.

==Functioning of the regular landholder chain==

The distinct difference between a landholder and a regular civ-level noble, is that a landholder may gain the position of landholder "of (sitename)" They are then seen as ruler of a particular site.

For a land_holder position to function as such, it has a few requirements:
* NUMBER:AS_NEEDED
* The first landholder-number of 1 is defined.
* No SITE (so civ) tag in that position.
*REPLACED_BY the next level landholder
If a landholder is defined with differentiating properties, it will function like a regular noble. A higher-up landholder that lacks the required tokens or connections will then not be used in elevation.

If a fortress meets the trigger for a new LAND_HOLDER tier when a caravan leaves, then the next time the outpost liaison or equivalent arrives, they will offer to make you an official colony, which will allow you to select all positions for that LAND_HOLDER level. Each time they appear, the outpost liaison will only promote your fortress one tier up the LAND_HOLDER track.

The landholder's LAND_NAME is not required for the functioning of this system. If omitted, messages will be shown with a more generic text.

==Appointment==

This mechanism differs from the regular methods of position management. It ignores all regular appointment- and election rules, so it more or less functions like automatic assignment. A landholder is, in vanilla, appointed by the monarch. Changing this doesn't seem to do anything. If they are appointed by a site-position, a not-yet-existing civ-position, or not appointed at all: the system keeps working as usual.

A landholder can appoint civ-positions and site positions. This works as expected: the positions only are appointed then when that landholder becomes available on civ-level or when he arrives at that site for site-level positions.

If your rank of landholder is the first of its rank in the realm, and is the sole appointer of some civ-position, then immediately as it gains the title, it will appoint the empty civ-slots. This may happen on your site, but the frequency and certainty is hard to determine.

==Succession==

Succession rules are applied to some extent:
* In world-gen it works according to succession rules, and site-positions can be used here. This means that a site position or a civ-position can inherit a landholder position, and vice versa.
* In fortress mode, once a landholder has been appointed, it then can inherit civ-level positions, and vice versa. This means that your baron can become king.
* Succession rules do not apply within the [LAND_HOLDER] chain; a count will not inherit a baron's land. This is because succession does not work well with the AS_NEEDED token.
* Premature succession works in fortress mode with landholders. If a unit gets a landholder's position and that landholder is the appointer of an as yet empty position, which is defined as succeeding from a third one, then the succession is immediately applied. The landholder themselves can even be the successor of a newly created position.
* A landholder's position is, in fortress mode, not successionable by a site-position or vice versa

===Impossibilities for succession by a site-position===
It would be very beneficial if the landholder can be succeeded by a [SITE]-position. So far, the following tests have not lead to positive results:
* making landholder and site-position both non-[DUTY_BOUND]
* make the site-position be [APPOINTED_BY] the landholder and/or the monarch
* give landholder and site-position [REJECTED_CREATURE]
* Let the monarch live at your site when succession could happen.
* Let the site-position be [REPLACED_BY] the landholder.

==Nomination==

The player is able to nominate a unit to become the LAND_HOLDER, but this only works with units of [LAND_HOLDER] level 1. The player can select all units, only limited by the PRECEDENCE of the current units' positions.

A unit that has a position with a PRECEDENCE lower or equal to that of the landholder's position, cannot be selected. This means that a baron (or count) from another site or the monarch cannot be selected, because their precedence is lower or equal.

The GENDER token does not work here: also units with the wrong gender (sorry) can be selected.

==Levels==
In mods, up to 10 levels of LAND_HOLDER may be defined.

If a landholder is replaced by a wrong landholder number (1 replaced by 3), then the number 3 is still correctly attached to the settlement.

If the current landholder has the highest available landholder number, then the next elevation will not happen - the diplomat will not elevate your fortress to a higher position, even if that position might be REPLACED_BY a lower landholder.

These chains do work:
* 1 -> 2a - > 2b -> 3
* 1 -> 3 -> 2 -> 4

These chains do not work:
* 2 -> 3 (need to start at 1)
* 1 -> 4 -> 2 -> 3 (stops after 4 as the highest)
* 1a -> 2, 1b -> 2 (only 1a and 2 work, 1b is not used)

==Moving landholders==

It may happen that a land-holder no longer lives at the site which they are the landholder of, specifically when the current landholder dies, leaving the title to an heir living somewhere else.

To prevent this from happening, you can make their succession from heir and make sure that their kids live at your site. Or, you can make their position succeeded by another civ position, and make it so that this civ position is somehow available on your site. But if multiple of these positions exist, it cannot be guaranteed that a citizen of your fortress will inherit the title.

In world gen, a landholder lacking the DUTY_BOUND-token will also move to the site they like, according to legends mode.

==Replacement by a generic civ-position==

If a landholder is replaced by an AS_NEEDED non-landholder civ-position, then this will work: the current landholder loses that title upon settlement-elevation and gains that civ-title. However, the civ-title lacks the landholder-property of being attached to the land. It will not show the name of the settlement alongside the position's name. So no "minister of Shovelmounts"

If a landholder is replaced by a general AS_NEEDED civ-position, that itself is also replaced by a generic AS_NEEDED civ-position, then firstly the elevation is executed and also the unit gains that new position. However, he immediately loses it, because an AS_NEEDED position that is replaced by another position can be filled initially, but units wont be able to hold that title.

==Landholder with fixed number==

A landholder's position that has a fixed number will be created and filled directly when the civilisation is born, so this position slot is then not available for the regular landholder-mechanic and will also not be used. That landholder will thus not be attached to a settlement.

It doesn't matter if the landholder's position is connected to the regular landholder's-chain with the REPLACE_BY token.

==Responsibilities==

When given a certain [RESPONSIBILITY], a landholder may function as a regular civ-level noble. If the position has [TRADE] or [OUTPOST_NEGOTIATING] responsibilities, then the landholder functions both as a diplomat and as an actual land holder. A landholder with the [MILITARY_STRATEGY] responsibility will travel around taming creatures in world-gen, according to legends mode.

Besides that, the responsibilities work the same as with any other on-site living position-holder, civ or otherwise.

=Military=
==Squad management==
In the vanilla game, the Squad interface only becomes available after a militia commander has been appointed. Until then, the window displays:{{DFtext|You must appoint somebody first to create a squad.}}

What’s surprising is how this is determined internally. In the entity raw definition, '''only the last two positions that include a [SQUAD] token are checked''' to decide whether the interface is accessible at all. As a result, if your hierarchy defines commanders A through E, appointing '''Commander D or E''' unlocks squad formation, while appointing A–C does nothing.

In other words, squad availability is not tied to ''having a militia commander'', but to ''which specific positions happen to be last in the raw list''—a notably hacky implementation.

These 'last two' are always the last two '''available positions.''' So if they get [REPLACED_BY] or become available because of [REQUIRES_POPULATION], the game adapts to those.

==Squad assignment==

Squads can be assigned, even if the leader position has no holder.

A specific unit can only have one position associated with a squad. If it gains another 'squad holding position', it is unassigned from the first one. This does not work with a 0-squad, so only 1+squads are taken into consideration. This technique can possibly be used to distribute all positions equally among all citizens. It does however not work with election and assumption.

If a civ-level position is associated with a squad and it gets a site-level squad-holding position assigned, it loses the current civ-position.

Squads can get really messed up, if you make the position (or multiple) either elected or not-elected and not-appointed, then this can cause the game to assign multiple squads to the same unit. Automatic assignment and election does not take squads into account, but the nobles screen does. This can cause the positions to be cleared as the game figures out that they have more than one position, and immediately get elected or assumed again.

Positions that cannot have a squad-position:
* A site- or civ-position with a [SUCCESSION] token cannot be appointed a squad-holding-position. The other way around, however, does work. For example, if a site-position with a [SUCCESSION]-token is appointed to a unit that has already a position with [SQUAD]. But when that squad position is assigned to another unit, it cannot be assigned back.
* A position with [SUCCESSION] can also not be assigned as a '''member''' of a squad.
* A squad-holding position with a formed squad cannot be appointed to another squad holding position.

If a position has at least one squad member, it cannot be left vacant. First, the squad has to be disbanded, then the position may be cleared.

==0-squads==
A 0-Squad is defined in a position as [SQUAD:0:member:members]. It does not seem to do anything useful as of now.
* It cannot be used to activate the [[Squad|military interface]]
* It does not restrict the assignment of [SUCCESSION] positions.
* Assigning this position does not clear any previously held squad position.
* The [[Leader]] and [[Tactician]] skill are not marked as relevant skills and are not taken into account in elections.
* It cannot be formed as a squad.

=Further testing=
The following questions may need additional testing. Feel free to add or answer
* Everything regarding COMMANDING and army-structure
** [http://www.bay12forums.com/smf/index.php?topic=175437.msg8331668#msg8331668]
** [http://www.bay12forums.com/smf/index.php?topic=165213.msg8335682#msg8335682]
** [http://www.bay12forums.com/smf/index.php?topic=174584.msg8026854#msg8026854]
* Everything regarding CONQUERED_SITE, but it is presumably just like site. But what if you combine SITE or LAND_HOLDER with it?
* Stuff about the monarch, its arrival and its entourage.

=Oddities (Bugs)=
Almost everything on this page could be called an oddity. Because of their unexpected usability, some may also be referred to as “undocumented features.” Others, however, are simply odd and not particularly useful, yet I hesitate to call them “bugs.”
* If a certain threshold is reached that makes an elected position electable, and the triggering event that initiates this evaluation is an assumption, then the resulting assumption is also referred to in the messages as an election

=Examples=

===The Founder===
The founder is a single dwarf, appointed at embark. They will be the only one ever to have this position and are not replaceable. When they lose their position some way, the position will not be assumed by another dwarf.
{{gamedata|title=The Founder|
[POSITION:THE_FOUNDER]
[NAME:the founder:founders]
[NUMBER:1]
[SITE]
[ALLOWED_CREATURE:DWARF:ALL] - will only be filled at embark, but not assumable later.
[REJECTED_CREATURE:DWARF:ALL] - will only be filled at embark, but not assumable later.
[SUCCESSION:BY_POSITION:THE_FOUNDER] - not unassignable, also cannot be assigned to a [SQUAD] position.
[PRECEDENCE:200]
Non APPOINTED_BY
Non ELECTED
Optional: Add responsibilities to make the game select a unit with certain skills.
}}
===Marriage bar===
Dwarven matrons are held in great honour. Upon marriage, a female dwarf is no longer expected to perform menial labour. All dwarven males hold this position by default, granting their spouses exemption from menial work.

The position becomes available with the arrival of the first migrants; otherwise, on embark, it would be assumed by females. Its succession rule is non-functional, but this prevents the player from unassigning the position. A squad size of 1 and the succession rules together prevent a unit from assuming the position more than once.

With precedence set to NONE, the position name is hidden, while LAND_NAME remains visible on the nobles screen. All married females receive the suffix “, Mrs.” and are marked as Nobles.

The practical usefulness of this position is debatable, but it serves as a clear demonstration of several mechanics.
{{gamedata|title=Mrs. Urist|

[POSITION:MRS_URIST]
[NUMBER:300]
[SITE]
[ALLOWED_CREATURE:DWARF:MALE]
Not APPOINTED_BY
Not ELECTED
[LAND_NAME:Dwarven male]
[NAME:dwarven male:dwarven male]
[PRECEDENCE:NONE]
[SPOUSE_FEMALE:, Mrs.:spouses]
[MENIAL_WORK_EXEMPTION_SPOUSE]
[REQUIRES_POPULATION:8]
[SUCCESSION:BY_POSITION:MONARCH]
[SQUAD:1:member:members]
}}
===The Archduke===
The archduke is the leader of the civilization, but exists only from landholder 4-level. Until then, its position remains vacant. When a settlement is elevated to tier 4 (grand duke), the grand duke can appoint the ruler of the civilisation, the archduke. Because of 'Premature Succession', they themself inherents that position immediately. Its heir then becomes grand duke.
{{gamedata|title=The Archduke| no POSITION:MONARCH

[POSITION:THE_ARCHDUKE]
[NAME:archduke:archdukes]
[NAME_MALE:archduke:archdukes]
[NAME_FEMALE:archduchess:archduchesses]
[LAND_NAME:a archduchy]
[NUMBER:1]
[PRECEDENCE:1]
[SUCCESSION:BY_POSITION:GRAND_DUKE]
[APPOINTED_BY:GRAND_DUKE]
(add additional monarch-stuff, like spouse name, demands etc.)

[POSITION:GRAND_DUKE]
[NAME:grand duke:grand dukes]
[NAME_MALE:grand duke:grand dukes]
[NAME_FEMALE:grand duchess:grand duchesses]
[NUMBER:AS_NEEDED]
[LAND_HOLDER:4]
// Optional ...
[PRECEDENCE:19]
[LAND_NAME:a archduchy]
[RESPONSIBILITY:LAW_MAKING]
[RESPONSIBILITY:RECEIVE_DIPLOMATS]
[SUCCESSION:BY_HEIR]
[APPOINTED_BY:THE_ARCHDUKE]
(add additional landholder-stuff)

!!add to [POSITION:DUKE]
[REPLACED_BY:GRAND_DUKE]

}}
{{Category|Modding}}
{{Category|Entities}}
{{Category|Guides}}

Advanced entity position mechanics

2026-02-10T10:19:52Z

Joostheger: /* Premature Succession */

{{Quality|Fine}}
{{Modding}}

= Introduction =

[http://www.bay12forums.com/smf/index.php?topic=182239.0 Discussion thread on the forum]

This page documents observed and tested behavior of entity positions in Dwarf Fortress that is not fully described elsewhere on the wiki. It focuses on advanced interactions between position tokens, including appointment, succession, election, and responsibility handling, across both civilization-level and site-level entities.

The mechanics described here are based on empirical testing in world generation and fortress mode, supplemented where necessary by raw analysis. In several cases, the game’s behavior is determined by evaluation order and interaction between multiple tags, rather than by individual tokens in isolation.

This page is intended for modders and advanced players who are designing or debugging custom entity position structures. It does not restate basic position mechanics, but instead highlights edge cases, non-obvious interactions, and behaviors that may appear inconsistent or undocumented.

Unless stated otherwise, the described behavior applies to current versions of the game and may differ from older releases.

==What is an entity? What is a position?==
An [[entity]] is an organizational structure that can have relationships with other entities, usually known as a [[civilization]] or a "[[site]] government" in the game, but merchant [[guild]]s, religious organizations, necromancer towers, and [[bandit]] groups are also entities. An entity can have positions - in most cases, these are hardcoded and generated by the game, but as for civilizations and sites, the [[raw file]]s can be customised.

A position is a special relationship between a unit and an entity. The unit holding a position has a larger influence over that entity than other citizens. Positions are mostly known as [[nobles]], but in this article. the technical term is used.

=Position levels (Site/Civ) and their interaction=
There are two basic types of positions that are customizable: '''civ(ilization)''' level and '''site level'''. Positions with the tag [SITE] are at site level, positions without the tag [SITE] are at 'civ level'. These two types of nobles can be considered '''loosely related systems'''. There are a few places where they can interact with each other.

Civ-level positions are in charge of the civilization as a whole, managing national [[trade]], laws, and [[war]]s. These are, for example, the vanilla [[monarch]], [[diplomat]] and [[general]]. (Note that the general doesn't do anything in either mode in the current version.)

'''[LAND_HOLDER]''' nobles are also positions at civ-level. These units are members of the national government, but have gained authority over some land or site. Once they do, they move to that place, but their position is still regarded as a civ-level position.

Site-level position holders are members of a site government (subsidiary to the civilization), and manage local affairs in that location. These are, for example, the [[mayor]], the [[sheriff]] and the [[broker]].

==Table of interaction between different position levels==
In this table, the possible interactions between different position levels are summarized.
The header row shows the positions defining the tokens.

The left column shows the position type that is referred to.
Example:
{| {{prettytable}}
|- bgcolor="#ddd"
! referred position-type
! LAND_HOLDER
|-
| civilization
| (baron is) APPOINTED_BY:MONARCH
|}
color coding: 
* Exists in vanilla
* Possible with mods
* Not possible
* possible to some extent.
* not yet fully investigated.
{| {{prettytable}}
|- bgcolor="#ddd"
! referred position-type
! Civilization
! SITE
! LAND_HOLDER
! CONQUERED_SITE

|-
| Civilization
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION '''(1)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION

|-
| SITE
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION '''(2)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY '''(3)''' COMMANDER REPLACED_BY SUCCESSION '''(4)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION

|-
| LAND_HOLDER
| APPOINTED_BY COMMANDER REPLACED_BY '''(6)''' SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION '''(5)'''
| APPOINTED_BY COMMANDER REPLACED_BY '''(7)''' SUCCESSION '''(8)'''
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION

|-
| CONQUERED_SITE
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
| APPOINTED_BY COMMANDER REPLACED_BY SUCCESSION
|}

Remarks:
# Works only in world-gen, if a unit with that civ-position is present at the site.
# Works only in world-gen, the site-position holding unit will then move to the capital.
# Is completely ignored
# Works only in world-gen.
# Works only in world-gen.
# Won't appear at all
# This is necessary for the landholder chain to work properly, it doesn’t work otherwise.
# This works only outside of the landholder chain, so when landholders are simply regarded as civ-level nobles. might also work in world-gen
#

== Other interactions ==

Unfortunately, interactions with positions of other entities don't seem possible, such as APPOINTED_BY: HIGH_PRIEST. With [VARIABLE_POSITIONS], positions are automatically created with codes like CUSTOM_LAW_MAKER_2, but interaction with these positions don't seem to work, either. For more info on those, see [[Variable positions]]

=General=

==Civ-level nobles living at your site==
Nobles from your civilization can come to live at your fortress. This happens in vanilla with landholders such as [[Baron]], [[Count]] and [[Duke]], with the Monarch, but sometimes also with non-landed LAND_HOLDERS.

When a civ-level noble becomes a [[citizen]] at your location, their position is shown among the site-level positions in your [[nobles screen]]. They appear to function as a site-level noble. They may have [[demand]]s, [[mandate]]s, [[squad]]s and the like. They can appoint nobles at the site-level.

If they have certain [RESPONSIBILITY]ies, they do the tasks that go with them.

==Fortress mode, world-gen and their differences==
Their are a few differences in how positions function between fortress mode (normal play mode) and the world generation (world-gen).

In '''fortress mode''', the player has some control over the appointment of nobles, limited by elections, automatic filled-in positions and succession rules. Pre-fortress mode, which is referred to as '''world-gen''', the game will always attempt to assign nobles whenever possible. It is subjected to the same rules as in fortress-mode, but there are some exceptions. In '''[[World activities]]''', which is the thing that happens in the world while you play fortress mode, it seems as if the same rules are applied as fortress mode.

A difference between player-fortress-mode and world-gen, is causes by visibility (see below). Positions that are not visible by the player and thus not available for assignment, will be available in world-gen and will thus be automatically assigned.

In fortress mode, a position that is both [ELECTED] and [APPOINTED_BY], cannot be appointed by the player and is also not elected, and can thus not be filled. But in world-gen sites however, these positions are automatically filled.

Positions with [AS_NEEDED] are almost never created and filled in world-gen (depending on their [RESPONSIBILITY]ies), but can always be used in player mode.

A position can, in fortress mode, be filled by the same unit. A unit can gain multiple positions in fortress mode, for example because of [[elections]]. This will not happen in world-gen mode: a unit can only have one position. See also remarks on 'embark' and 'Losing a position'.

In world-gen, [SUCCESSION] between civ-levels and [SITE-]levels may happen. This will not happen in fortress mode, or even off-site in [[World activities]].

In fortress mode, premature SUCCESSION may happen. This will not happen in world-gen mode.

==Units holding multiple positions in multiple entities==
A unit can hold multiple positions in its civilisation or in its site-entity, however this does not happen in world-gen. Only at player-managed sites can units be holding multiple positions at once. (It is probably not possible for a unit to hold a position in two different civilisations or two different sites.)

In world-gen, if there are too many positions to be filled, they simply stay empty until more units are available. E.G, a unit at a site might inherit a civ-level position and still remain a member of the local government. When this happens however, they move to the capital. If a unit gains a new position, either inherited or otherwise, it drops the previous one. If a unit assumes a civ-position in fortress mode, it leaves the current position.

If a unit holds the same (site-)position multiple times, it has no additional effect.

If a unit holds multiple different positions of the same entity, it has all those positions' responsibilities and properties, stacked up. Presumably, the demands for those combined positions are determined by the highest.

A unit holding a position with a succession token can be assigned another position with a (different) succession token.

A unit holding a position with a squad-position cannot hold another squad-position. It is dropped from the first, when it gets its second assigned.
A unit holding a position with a succession token cannot be assigned to a squad-position - the unit is simply not available. It works the other way around, though.

=[PRECEDENCE]=
The first defined position with precedence of 1 counts as the ruler of the civ. See also: [[Position_token#PRECEDENCE|PRECEDENCE]].

If the precedence is omitted or has a negative value, the game sets 0 as precedence, which seems to have no effect whatsoever.

When a unit has multiple positions, the name of the position with the highest rank in precedence is shown behind the unit's name.

If you omit precedence entirely, or set it to [PRECEDENCE:NONE], the position name will not be shown after the unit’s name. Your *Urist Mason* will remain simply *Mason*. This can be useful for positions that are unimportant or purely functional. The position will also not appear in the civilisation overview of your site on the world map. The position name is shown in messages, but remains hidden on the nobles screen as well. To make it visible there, use [LAND_NAME].

=[RESPONSIBILITY]ies=
Both civ and [SITE] positions can carry responsibilities. However, not all responsibilities are active for both types: some function only for civ positions, others only for site positions. When a civ noble arrives at a site and takes up residence, they do not perform responsibilities that are intended for SITE nobles. As a result, these responsibilities neither trigger their associated tasks nor unlock related game mechanics. For example, a civ-level manager living in a fortress will not perform management duties there and doesn't unlock the management-screen, even with an assigned office.
This behavior applies to the following [SITE]-level responsibilities:
* [RESPONSIBILITY:ACCOUNTING]
* [RESPONSIBILITY:BUILD_MORALE]
* [RESPONSIBILITY:HEALTH_MANAGEMENT]
* [RESPONSIBILITY:LAW_ENFORCEMENT]
* [RESPONSIBILITY:MANAGE_PRODUCTION]
* [RESPONSIBILITY:MEET_WORKERS]
* [RESPONSIBILITY:TRADE] (functions differently)
Other responsibilities may be affected as well, but have not yet been fully tested.

==[DELIVERS_MESSAGES]==
The only [AS_NEEDED]-position that is created in worldgen based on responsibility is that of the site-level responsibility [DELIVERS_MESSAGES].

==Outpost Liaisons and Diplomats==
Civ-positions with the responsibility [ESTABLISH_COLONY_TRADE_AGREEMENTS] ([[Outpost_Liaison|Outpost Liaison]]s) will meet with the site-noble who has responsibility for [RECEIVE_DIPLOMATS] and the highest rank of precedence (i.e. the lowest precedence value). Usually this is the [[Expedition_leader|Expedition leader]].

Once a [LAND_HOLDER] is assigned to the site, civ-positions with the responsibility [MAKE_TOPIC_AGREEMENTS] ([[Diplomat]]s) will meet with '''civ'''-level nobles present at the site who have the [RECEIVE_DIPLOMATS] responsibility. If multiple eligible nobles are available, one is selected at random. If no eligible noble is present, the diplomat leaves angrily. If the landholder is no longer present at the site, diplomats will not arrive at all.

It appears that Outpost Liaisons and Diplomats are chosen for a diplomatic mission based on availability. When multiple candidates exist, the position defined last in the raws is most often selected.

==[TRADE]==
Civ-level nobles with [TRADE] will arrive with the caravan, just as the Outpost Liaison. Their behavior is no longer active in the vanilla game, but the mechanics are still present. See [[40d:Guild_representative|Guild representative]] for more details. This civ-noble will only meet with the SITE noble with [TRADE], usually the [[Broker]].

If two civ-nobles exist with both [TRADE] and [ESTABLISH_COLONY_TRADE_AGREEMENTS], they both arrive at the same time. Even if both tokens are assigned to a single position, if more than one instance of that position exists, two of them will arrive. However in that case, somehow the elevation of the site and appointment of landholder isn't offered.

If the SITE-noble they intend to meet has both [TRADE] and [RECEIVE_DIPLOMATS], only one meeting will proceed and the other is cancelled. However, when two SITE-nobles are available, each with either [TRADE] or [RECEIVE_DIPLOMATS], both meetings will proceed and both civ-nobles will attempt to negotiate a trade agreement. It is not known what happens if these agreements are accepted or refused.

In the trade depot, the last defined position with the [TRADE] responsibility is shown as broker. However when requesting a trader, the first defined position with [TRADE] will actually go there to do the trade.

==World-gen effects of the [RESPONSIBILITY] of available positions ==
It is possible to cause civs and individual sites to change their behavior substantially when they reach a certain size, by controlling nobles.
* If a site can only appoint a position with [MILITARY_GOALS] after reaching a particular size, that site will not send armies on missions until the required size is reached.
* A civ-level [LAW_MAKING] position is required for the civilization to have any kind of cohesion. Without it, sites will be constantly embroiled in territorial disputes and civil wars will be commonplace.
* [MILITARY_STRATEGY] positions go out and tame wild animals. This makes your civ gain those animals as domesticated and also brings them in sieges.
* The [[Personality_facet|Personality]] of the position's holder determines how they lead the civ.

=Availability and visibility=
==Availability of (new) positions==
Warning: Do not mistake "availability" for "visibility"!

Of all the possible positions existing in your site's entity, there may only be some available.
* Positions with [REQUIRES_POPULATION] require the population to have a specific size.
* Positions with [REQUIRES_MARKET] will only appear in "large" sites (which may have different rules for different site types). This tag has no effect in fort mode.
* Positions that are appointed by positions that have an AS_NEEDED number. The appointable positions only become available after an appointer position-slot is created. This works also on civ-level. If a position is appointed by a Land-holder, it only becomes available, when that level of landholder is created.

Only the replaced positions are culled and are no longer available.
A position that requires a certain population will become available, even if it doesn't have [APPOINTED_BY] or [ELECTED]. In that case, see 'automatic assignment' and 'assumption'

In fortress mode, in some cases 'succession' is evaluated immediately after a position becomes available. See: Succession.
==Visibility of positions==
A position might be available, but can still be invisible for the player in the [[nobles screen]]. The positions with their respective holders are visible for players:
* All site-positions that are already filled-in (even if they could not be re-filled-in considering current conditions)
* Site positions that are appointable by a filled-in site position
* Site positions that are appointable by a filled-in civ position, when that civ positions holder becomes a citizen of your fortress.
* Civ positions of units that are also a citizen of your fortress.
If a position becomes available, for example because a certain pop number has been reached, or if it is available from the start(like expedition leader), as long as it cannot be appointed, it still is INVISIBLE for the player.

It might strike someone as odd if a position becomes filled automatically in fortress mode when that position is not even visible. This might be the case if the current holder of a non-appointable position dies or succeeds another position. Regardless of player visibility, these positions will be automatically filled in if the necessary requisitions are met. It might happen with the expedition leader.

A situation with a non-visible but available position, is for example when a position is solely appointed by the expedition leader, when the expedition leader's position is left vacant. It can no longer be appointed by the player and is invisible. Then, it gets automatically assumed, proving that the position still was available.

A position that is both [APPOINTED_BY] and [ELECTED] is visible, but players cannot interact with it.

=[NUMBER]=
A position might be defined with a number. In that case, as many as defined can be available. If the positions become available, in world-gen and when embarking, they are all filled-in completely.

If the ruling position (with PRECEDENCE of 1) has a NUMBER higher than 1, a random unit of the ones holding these positions is shown as ruler in the embark screen.

A [NUMBER] of 0 (zero) has the same effect as 1.

==Automatic spreading of assumed, non-singular positions==
If there are civ positions that have a NUMBER higher then '1' and which are assumed (not APPOINTED_BY or ELECTED) but are '''not DUTY_BOUND''', these are automatically spread among the civilisation, based on population. If there are a number of '''20''' available slots of that position, they spread among a civilization with a combined population of, for example, 1000 of which your fortress has 100 (10%), '''2''' of your fortress' citizens will assume that position.
This may probably also work with elected and appointed positions, but that may be depending on the death of the current holders and this needs more testing. Assumption works within a day, anyway.

==[AS_NEEDED]==
These positions can be created automatically by the game in world-gen. This, however, only works with:
* [LAND_HOLDER]'s
* squad commanders (needs more testing)
* Messengers at sites

For all other types of positions, they're not created in world-gen, even if they are defined with RESPONSIBILITY's. For example, even in war, the game wouldn't create a MILITARY_GOALS position, if they have AS_NEEDED as number.

However, in fortress mode / player mode, these positions can be created by the player at will.

Positions with AS_NEEDED need to be created first, before any symbols are assignable as 'symbols' (objects) for the position holder to carry or wear.

Positions with AS_NEEDED cannot be created and then ELECTED in fortress mode. It only works with APPOINTED_BY.

=Replacement and Required Population=

The token REPLACED_BY:position means that once the replacing position reaches its required population-number, the 'to-be-replaced' position will disappear. This is defined in REQUIRES_POPULATION. These tags are closely related to each other and seem to only have a meaningful function if combined. Nobles with REQUIRES_POPULATION require the population to have a specific size.

This works on the civ-level as well as on site-level, but those systems are in this mechanic strictly separated. Site-level positions cannot be replaced by civ-level positions and visa versa. This makes sense, because they both depend on their own population-count. When using REQUIRES_POPULATION on civ-level, it counts the total population of the civilisation.

See also: [[Advanced_entity_position_mechanics#Evaluation_of_Positions|Evaluation of positions]]

==Effect of replacement (and on [LAND_HOLDER]s)==

Replacement is immediate and complete - the current holding unit loses the position, even before SUCCESSION_BY_POSITION rules are applied. A position with a number of 1 will replace all the slots of a position with a higher number of slots.

Even if the next position is available but not visible, replacement still takes place. If a position is replaced, it is completely gone - it cannot be appointed, succeeded, elected or assumed any longer.
The unit immediately loses its position.

In legends, replacement is mentioned as: "(unit name) ceased to be (position name)" The replacement of an AS_NEEDED position empties the position's slot forever. In fortress mode, it may seem as if you can create new slots and appoint new units in the nobles screen, but this is reversed as soon as you close the window.

The landholder chain uses [REPLACED_BY] differently. It does not clear the position completely, but uses it for succession to the next level's position. [REPLACE_BY] is required to let that system work properly. This also means that the way in which landholders succeed (replace + as_needed) does not work in any other way.

Replacement between LAND_HOLDERS and other site- or civ positions does not work in any way. Only the vanilla replacement sequence between levels of LAND_HOLDERs does work. If the token is omitted for landholders, the landholder chain is broken, so replacement is required for the landholder system to work.

[REQUIRES_POPULATION] also does not work for [LAND_HOLDER], when you set [NUMBER] to 1. The position is not created when the required population is reached.

==What doesn't work==

'''Attention: If a position cannot be appointed, for example because of 'mutual appointment', it still exists according to replacement mechanics and will replace other positions if so defined. If a certain position(a) will be replaced by the baron's assistant, which can only be appointed by the [LAND_HOLDER] baron, than that position(s) still will be replaced from the start of the game, even if no baron or their assistant is ever present.'''

A position that is replaced by a somehow not-fillable position, is still replaced. This counts for mutual-appointing positions, replacement by not-yet-assigned landholders, replacement by AS_NEEDED positions, or replacement by not-yet-appointed positions.

Replacement does not work if the replaced position is a [LAND_HOLDER], even with civ-positions. In that case, the LAND_HOLDER's position is not replaced. It does not matter if AS_NEEDED is used, or a fixed number, and it also does not matter what type of position the replacer is. So this only works (correctly) with positions that become available by REQUIRES_POPULATION.

={{text anchor|Evaluation of Positions}}=
The game does not continuously check whether positions should become available, elected or be [REPLACE_BY]. This is well-known behavior—for example with the [[mayor]], who does not appear automatically when the required population ([REQUIRES_POPULATION]) is reached. Instead, positions must somehow be evaluated. This applies in several other situations as well

'''Cases that require a trigger:'''
* Election of a newly created position
* Election after the current holder dies
* Automatic assumption of a newly created position (this may take up to a day)
* New citizens (such as migrants) considering available positions
* Premature succession of a newly created position

'''Cases that do not wait for a trigger:'''
* Succession following the death of the previous holder
* Automatic assumption of existing positions that have become vacant

'''Triggers that cause the game to reevaluate noble positions:'''
* Succession of a [SITE]-position due to the death of the current holder
* [[Advanced_entity_position_mechanics#Election_Day|Election Day]]
* Automatic assumption of a [SITE]-position that becomes vacant
* (Re)assigning any site position manually
* Settlement elevation on the LAND_HOLDER track (e.g. gaining a [[Baron]] or [[Count]])

=Gaining a position=
There are several ways a unit can gain a position:
* Appointment: A unit is appointed by another unit or by the player.
* Election: A unit is elected by and among the members of the entity
* Assumption: A position is neither elected or appointed: a random unit just simply 'takes' the position
* Succession: a unit is the valid successor of this position(A), either by its current position(B) or because they are that position(A)-holder's heir.

Available positions will automatically be assigned to a random civ member when a new site/civ is created.

==Who can take a position==

* If so defined, a unit needs to be the right caste and/or class - it does not seem to work with creature types.
* The unit needs to be an adult member of the site or its parent civ-government; that is also CAN_LEARN or INTELLIGENT (SLOW_LEARNER cannot take positions) or otherwise is able to think.

==Appointment==

Positions that have an [APPOINTED_BY:position] token require that position to exist, to be available and appointed. Any position that is APPOINTED_BY can be appointed if the appointer's position is filled in.
For site-positions to be appointed, it is required that the appointer is present at that location.

If the appointing unit is temporarily not present, or if that position is not filled, positions depending on it cannot be appointed. This is the case with [[militia captains]], when the [[militia commander]] is on a [[mission]].

A site position cannot appoint a civ position ''or'' LAND_HOLDER in any way whatsoever.

Civ-level positions can appoint other civ-level positions and site-level positions can appoint other site-level positions.

Contrary to what has been said elsewhere, civ-level nobles also can appoint site-level nobles. They need to be at the site to do so. Landholders can appoint both site-level and civ-level nobles. These systems are therefore not as separate as was assumed.

'''Mutual appointment''' cannot take place. If these are the only requisites of the position, then the positions will never appear or get filled. These unfillable positions can be put to good use, for example, to replace a position that is no longer needed without creating a new one.

'''Self appointment''' doesn't normally work. If you have a position that is only appointed by itself, it is never appointed and also cannot be assumed. However, if the position has a number higher than 1, and is filled by multiple units (for example by another position that is now empty), than those units can re-assign or appoint each other from that their shared position.

If an APPOINTED_BY token refers to a non-existing position's code, the effects are as if the appointment token doesn't exist at all.

===Automatic appointment in world-gen and on the civ level===

Outside of fortress mode, the game will always attempt to appoint nobles whenever possible, as long as these positions are '''available''', even if they are invisible to the player.
It shows this message in legends: "(unit name) has been appointed to the position of (position name)"

In world-gen, all positions become available and are automatically appointed, taking population- and appointment-requirements into consideration.

Positions that are REPLACED_BY are culled and won't be filled.

If a citizen of your fortress holds a civ-level position that can appoint another civ-level position, the appointment will happen automatically and without player intervention. It may happen that another citizen of your fortress is appointed by that unit, creating civ-level position holders in your fortress, but it is unknown what is required to force this effect.

===Manual appointments by players in fortress mode===
In fortress mode, the positions that need to be appointed stay empty on embark. and it is the player's job to appoint those. A player can appoint a unit to any available position, according to the hereabove mentioned conditions. The player takes the role of the automatic appointment-system, but has no direct control over elections, successions and replacement. There are some differences in what is possible at world-gen sites and at player-controlled sites.

* A position that is appointed by a unit present as a fortress citizen, can be appointed, re-appointed or left vacant. This means also by civ-level nobles living as a citizen in your fortress; not when they are only visiting, like the diplomat.
* A position whose appointing positions are all either vacant or [REPLACED_BY] can no longer be appointed. If the position is already filled, it cannot be reappointed or vacated; the current holder simply remains in office.
* A position that is APPOINTED_BY a unit present as the land_holder of your site, can be appointed, reassigned or left vacant.
* A position that has SUCCESSION BY_HEIR or BY_POSITION can 'initially' be appointed and also re-appointed or left vacant, but as soon as the [[nobles]] screen closes, ''it can no longer be replaced or left vacant''. From then on, the succession-rules determine who gains that position when the current holder loses the position. This works even if the SUCCESSION:BY_POSITION-position is vacant or replaced.
* A position that is ELECTED nor APPOINTED_BY, can always be (re-)appointed by the player. This is the case with the [[Expedition leader]]. If it is left vacant however, it cannot be appointed, but will be assumed shortly after.
* A position that is both ELECTED and APPOINTED_BY, cannot be appointed by the player. Contrary to world-gen sites, its slot is visible, but it doesn't show the +-sign. This is either by AS_NEEDED or by a fixed number. Even if the position somehow gets filled (re)assignment is never possible
* A player can appoint a number of units to a position, as much as the NUMBER token dictates. If it is AS_NEEDED, the player may create as many slots as they like, also contrary to world-gen sites.
* A civ-position can never be appointed, even if the appointing civ noble is a citizen of your fortress. A civ position also never can be re-assigned or left vacant, would that position be defined as appointed by a site-position.

==Election==
Read more in [[Elections]]. The message that is shown is: "(creature name) has been elected to the position of (position name)"

In worldgen, there is no functional difference between ELECTED and non-appointment, except that elected nobles tend to have high social skills and/or skills related to the position, while non-elected ones are assigned randomly. See: [[Elections]]

A succession goes before an election.

A position that is both ELECTED and APPOINTED_BY never gets elected. Even if the appointees' position somehow gets filled, (re)-elections won't happen. So, it doesn't seem possible to have an elected position become available when a certain other position becomes filled.

An ELECTED civ-(or LAND_HOLDER) position at your site will never be (re)-elected in fortress mode. So real (re-)election only works with SITE-positions.

=== {{text anchor|Election Day}} ===
Election Day takes place on the 17th of Summer. On this day, a full reevaluation is performed, including all currently elected positions, which are subject to re-election. Contrary to the information on [[Elections]], nothing occurs at the start of a season.

Positions that are both [APPOINTED_BY] and [ELECTED] will not be re-elected on Election Day when assigned through [SUCCESSION].

=== Election Eligiblity ===
Any citizen may stand for election. Eligibility cannot be restricted using [ACCEPTED_CREATURE], [REJECTED_CREATURE], [ACCEPTED_CLASS], [REJECTED_CLASS], or [GENDER]. Units currently having a [SUCCESSION]-position even may be elected for a position with a [SQUAD]-token, which is otherwise impossible to assign or even succeed.

=== Skills ===
In elections, skills are taken into account for the tokens of the position which is elected.
{| class="wikitable"
|+ Relevant skills per position token
|-
! Position Token !! Relevant skills
|-
| Responsibility [[Position_token#DELIVER_MESSAGES|[DELIVER_MESSAGES]]] || [[Ambusher]], [[Observer]] and [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#ACCOUNTING|[ACCOUNTING]]] || [[Record_keeper|Record keeper]]
|-
| Responsibility [[Position_token#ESPIONAGE|[ESPIONAGE]]] || [[Schemer]]
|-
| Responsibility [[Position_token#HEALTH_MANAGEMENT|[HEALTH_MANAGEMENT]]] || [[Diagnostician|Diagnostician]]
|-
| Responsibility [[Position_token#MAKE_INTRODUCTIONS|[MAKE_INTRODUCTIONS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#MAKE_PEACE_AGREEMENTS|[MAKE_PEACE_AGREEMENTS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#MAKE_TOPIC_AGREEMENTS|[MAKE_TOPIC_AGREEMENTS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#MANAGE_PRODUCTION|[MANAGE_PRODUCTION]]] || [[Organizer]]
|-
| Responsibility [[Position_token#MEET_WORKERS|[MEET_WORKERS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#RECEIVE_DIPLOMATS|[RECEIVE_DIPLOMATS]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#RELIGION|[RELIGION]]] || [[Social_skill|Social skills]]
|-
| Responsibility [[Position_token#TAME_EXOTICS|[TAME_EXOTICS]]] || [[Animal_trainer|Animal trainer]]
|-
| Responsibility [[Position_token#TRADE|[TRADE]]] || [[Social_skill|Social skills]] and [[Appraiser|Appraiser]]
|-
| [[Position_token#SQUAD|[SQUAD]]]-token || [[Tactician]] and [[Leader]]
|}

==Assumption==

A position that is not APPOINTED_BY nor ELECTED, or is appointed by positions that are not available in your site or civ, will be assumable by a random dwarf. If it has responsibilities that require certain skills, then these are taken into consideration on embark, but not when the position is assumed during the actual game.

Normally, one to three units will take the into consideration to assume a position. Most of the time when there are multiple open positions, only a single unit will assume all of them. However, a position that has REJECTED_CREATURE, REJECTED_CLASS, ALLOWED_CREATURE or ALLOWED_CLASS will be filled with all different units, even if the creature or class mentioned is irrelevant. It seems that this forces the game to loop over all the available units.

The message that is shown in Legends mode is: "(unit name) has assumed the position of (position name)". This may also take place in fortress mode, which then shows this message to the player.

If an assumable position becomes empty, it will be assumed within a day. This is the case when you leave the position of expedition-leader vacant. It also happens with entities.

Assumable positions that become empty will not be assumed if that position has a valid [SUCCESSION] -successor. In that case, the successor inherits the position.

Even positions that are somehow invisible because they cannot be directly APPOINTED_BY players, can be assumed.

When you embark, the assumable positions are automatically assigned to a random unit. If there are multiple of these positions at embark, they all are assigned to the same unit. If there are enough positions available, multiple units may gain a position, but often no more than three different ones.

If a dwarf in fortress mode assumes a position, that already has another position, it will leave the current position empty. When that position also is assumed, then this will continue until all positions have a dwarf appointed to them, with no other position.

A unit that already has a position with a [SUCCESSION] token won't take assumable positions into consideration that have a [SQUAD] token. This can be used by the modder to prevent unwanted loss of current positions.

A position that has an appointer which got replaced because of REPLACED_BY, will not become assumable. Also, positions that have an AS_NEEDED appointer that is not yet filled (or ever), will also not be assumed.

==Succession==

If a position-holder dies or advances to a new position via succession, the position will be granted to another unit based on the [SUCCESSION] tag. If they have an heir or the succeeding position exists, that unit will be assigned. If not, a new one will be appointed according to the usual rules. The message that is shown is: "(creature name) being the rightful heir, has inherited the position of (position name)"

The succeeding creature will also lose its previous position. When succession is defined using BY_POSITION, the unit naturally loses the referenced position. However, it also loses any other positions it may hold. If a unit could simultaneously inherit multiple positions, the last-defined succession overrides the earlier one, clearing the previously acquired position

Succession works both at site-level and at civ-level, both in world-gen and in fortress-mode. Succession by position on the civ-level is also visible and functional in fortress-mode. If both civ-level nobles are a citizen of your fortress, succession is applied visually. Vanilla example: The [[druid]] is succeeded by the [[acolyte]]. This means that as soon as the druid dies, the acolyte takes over.

When a position that is succeeded by position becomes available, immediately it is checked if a position-successor is available and the position is filled with that unit. Even if this is an [ELECTED] position, succession goes first. When elections eventually do happen, succession plays no role.

It is possible to assign multiple levels of [SUCCESSION:BY_POSITION] in different positions, creating a line of positions where the death of one causes all those "below" them to advance.

A position can have multiple tokens with position-succession. It looks to be random which one is used. It is not always:
* The first or last defined token
* The first or last appointed unit
* the oldest or youngest
* one with a higher or lower precedence
* a unit with relevant skills

When a position is defined with a Succession-type, that unit cannot have another position that has a Squad-type. If the succession-position itself has a squad, than it can be assigned another position with a squad, but then it will loose the previous succesion position. See further details by "Squad"

Assumed positions can also be succeeded by position, if the current holder dies.

If the successor is an AS_NEEDED position, the used unit will leave a vacant position-slot on its removal by succession. This empty slot remains a real slot, which will only be cleaned up if you (un)appoint a unit to this position-series. It isn't cleaned up after regular position validation.

A civ-level position of a unit living at your site might be inherited by a unit holding that does not currently live at your site. This, unfortunately, moves that position to a unit off site. This may also happen with the landholder of your site, for example when it is succeeded by another civ-level position. This currently poses an unsolved challenge.

===Eligibility for succession===
Succession is restricted by the tokens [ACCEPTED_CREATURE], [REJECTED_CREATURE], [ACCEPTED_CLASS], [REJECTED_CLASS] and [GENDER].

===Site and civ combined succession===

Succession can work when combining site positions with civ-level positions or land_holders, but only in world-gen mode. In fortress mode, it only works with combining the same level of nobles, with Landholders regarded as civ-level. So, in fortress mode, a site's position cannot succeed a landholder's position and it cannot succeed another type of civ-level position, and vice versa.

This won't work even if the positions:
* are AS_NEEDED or having a fixed number.
* Are LAND_HOLDERs.

===Succession [BY_HEIR]===

When a heir is needed for succession, all children and then other relatives are validated. They cannot take the position if their status does not allow it, for example if they have become a member of another civilisation. See: "Who can take a position". If the unit has no valid heir on that location, the position may go to a unit living on another site. This may cause the title of Landholder of some land to be inherited by a unit living somewhere else. That might be a problem, because then you lose your landholders.

===Premature Succession===

There are cases where [SUCCESSION:BY_POSITION] is applied prematurely: at the moment a position is first created and becomes appointable or assumable, rather than after a current holder leaves. In this situation, the succession mechanism assigns a holder immediately, without any player interaction.

When a position becomes available for the first time, the game checks whether a valid successor-by-position exists. If so, that unit is assigned instantly. It can affect positions that would normally be appointed or elected by the player, causing succession to trigger before the player has any opportunity to intervene.

This behavior occurs only in Fortress mode, but can be applied both on [SITE]-positions as well in civ-positions. That last one however is a bit harder to control.

This premature succession only occurs the first time a position becomes available (i.e. when it is created and becomes appointable or assumable). Even if the position remains vacant and the conditions for succession improve later, premature succession will not trigger again. From that point onward, only normal succession rules apply.

Using premature succession, a position that has [ELECTED], [APPOINTED_BY], or both, can be filled directly.
Notably, positions that combine [ELECTED] and [APPOINTED_BY] are normally impossible to fill through regular mechanics. Premature succession bypasses both election and appointment entirely, making this combination uniquely reachable through this mechanism.

No initial election takes place, and no subsequent elections will ever occur for that position. Succession always takes precedence over election, both in premature succession and in normal succession cases.

This behavior applies only in Fortress mode, not during world generation. World-gen uses simplified and more efficient mechanics, and this interaction does not occur there. Premature succession can affect both site-level and civilization-level positions.

====Multiple succession chains====

Multiple succession chains may be defined and are resolved in the order they appear in the raws.

If a position has both:
* a direct succession chain (A → C), and
* a multi-step chain (A → B → C),

and intermediate positions are vacant, resolution proceeds according to raw order. A common outcome is:
# The direct succession (A → C) is applied first, assigning A to C.
# The remaining chain then advances (A → B).
# If C still has empty slots, the final step (B → C) may occur.

If position B is already filled, behavior depends entirely on raw definition order:
* nothing may happen, or
* B may move to C first, followed by A moving to B.
====Working triggers====
Premature succession is triggered when a succeedable position is created under the following conditions:
* The succeedable position is created because its [REQUIRES_POPULATION] threshold is reached. This applies even if the position is not [APPOINTED_BY]. Premature succession takes priority over automatic assumption (e.g. the mayor declaring themselves within a day).
* The succeedable position can be [APPOINTED_BY] another position of the same level (site or civ) that has just been created because its [REQUIRES_POPULATION] was reached.
* The succeedable position can be appointed by another [SITE] [AS_NEEDED] position that has just been created and filled.
* The succeedable (site or civ) position is [APPOINTED_BY] the [LAND_HOLDER] position, which has just been created due to site elevation. This typically resolves when the diplomat leaves the map, at which point the landholder position becomes active.
* If all other requirements are met, premature succession can occur immediately after unpausing following embark, for positions with [REQUIRES_POPULATION:7].
====Non-working triggers====
Premature succession does '''not''' occur in the following cases:
* An [AS_NEEDED] succeedable position slot is manually created by the player while its succeeding position is already filled. [AS_NEEDED] positions must always be appointed after creation.
* The succeeding position is filled after the succeedable position becomes available. The moment of creation is the decisive trigger; filling the source position later is too late.
* The succeedable position can be appointed by another site or civ position with a fixed number of slots that has just been appointed. In this case, the succeedable position is just available for appointment itself, nothing more
* Any situation occurring during world generation.
* The succeeding position is [REPLACED_BY] the succeedable position. In this case, replacement removes the unit from the source position first, leaving no holder available for the succession mechanism to use.rst, leaving no holder available for the succession mechanism to use.
* The position is [APPOINTED_BY] a civ-level position, that just became a citizen of your fortress. It must be noted that those civ-level positions were active all that time and the succeedable position could be appointed even before. The monarchs arrival does not trigger premature succession

=Losing a position=

A unit can lose a position when:
* It dies
* It succeeds another position, even if it has nothing to do with the previous position.
* It is assigned to another SQUAD-holding position
* It is convicted of a crime.
* Another unit is ELECTED for the position
* Its position becomes replaced
* Another unit is appointed by the player, or the position is left vacant.
* It has assumed another position, as this always leaves the previous position vacant.

=Embarkment=
Two types of positions are automatically filled by embark.
* Positions without [APPOINTED_BY] or [ELECTED] (assumable). All these positions, even with a NUMBER higher than 1, are all filled with one to three dwarves. Contrary to assumption, this doesn't take into account any limitations. REJECTED_CLASS, ALLOWED_CLASS, REJECTED_CREATURE, ALLOWED_CREATURE and GENDER are applied, but without the normal spread you may expect with assumptions. Also it doesn't look at [SUCCESSION] and [SQUAD] limitations.
* Positions that are elected are filled-in by the normal election rules.

Positions that have a defined appointer are never initially filled at embark.

All positions that don't have [REQUIRES_POPULATION] or with a [REQUIRES_POPULATION] of 7 or lower, will be available at embark.

=Land Holders=

A Landholder is a '''special civ-level noble''' who gets a certain piece of land to hold, when that land is elevated to a certain level, determined by the tag [LAND_HOLDER] and by the landholder triggers in the game's settings. In vanilla, these are the baron, the count and the duke.

A unit gaining the landholder position does not migrate to that specific named land. In world-gen, they stay just where they are, probably at the capital. In fortress mode, you can suggest a citizen for the role. So for the time being that works.

Succession is then a real issue. If you use BY_HEIR, its solved when that landholder has children living at your site. But when its not the case, the title just goes to anyone randomly. Succession BY_POSITION works, but only in the civ-chain, and there's no way to guarantee a civ-holder is at your site at that time. Even with 'automatic spread' positions, it goes to one of them randomly.

==Functioning of the regular landholder chain==

The distinct difference between a landholder and a regular civ-level noble, is that a landholder may gain the position of landholder "of (sitename)" They are then seen as ruler of a particular site.

For a land_holder position to function as such, it has a few requirements:
* NUMBER:AS_NEEDED
* The first landholder-number of 1 is defined.
* No SITE (so civ) tag in that position.
*REPLACED_BY the next level landholder
If a landholder is defined with differentiating properties, it will function like a regular noble. A higher-up landholder that lacks the required tokens or connections will then not be used in elevation.

If a fortress meets the trigger for a new LAND_HOLDER tier when a caravan leaves, then the next time the outpost liaison or equivalent arrives, they will offer to make you an official colony, which will allow you to select all positions for that LAND_HOLDER level. Each time they appear, the outpost liaison will only promote your fortress one tier up the LAND_HOLDER track.

The landholder's LAND_NAME is not required for the functioning of this system. If omitted, messages will be shown with a more generic text.

==Appointment==

This mechanism differs from the regular methods of position management. It ignores all regular appointment- and election rules, so it more or less functions like automatic assignment. A landholder is, in vanilla, appointed by the monarch. Changing this doesn't seem to do anything. If they are appointed by a site-position, a not-yet-existing civ-position, or not appointed at all: the system keeps working as usual.

A landholder can appoint civ-positions and site positions. This works as expected: the positions only are appointed then when that landholder becomes available on civ-level or when he arrives at that site for site-level positions.

If your rank of landholder is the first of its rank in the realm, and is the sole appointer of some civ-position, then immediately as it gains the title, it will appoint the empty civ-slots. This may happen on your site, but the frequency and certainty is hard to determine.

==Succession==

Succession rules are applied to some extent:
* In world-gen it works according to succession rules, and site-positions can be used here. This means that a site position or a civ-position can inherit a landholder position, and vice versa.
* In fortress mode, once a landholder has been appointed, it then can inherit civ-level positions, and vice versa. This means that your baron can become king.
* Succession rules do not apply within the [LAND_HOLDER] chain; a count will not inherit a baron's land. This is because succession does not work well with the AS_NEEDED token.
* Premature succession works in fortress mode with landholders. If a unit gets a landholder's position and that landholder is the appointer of an as yet empty position, which is defined as succeeding from a third one, then the succession is immediately applied. The landholder themselves can even be the successor of a newly created position.
* A landholder's position is, in fortress mode, not successionable by a site-position or vice versa

===Impossibilities for succession by a site-position===
It would be very beneficial if the landholder can be succeeded by a [SITE]-position. So far, the following tests have not lead to positive results:
* making landholder and site-position both non-[DUTY_BOUND]
* make the site-position be [APPOINTED_BY] the landholder and/or the monarch
* give landholder and site-position [REJECTED_CREATURE]
* Let the monarch live at your site when succession could happen.
* Let the site-position be [REPLACED_BY] the landholder.

==Nomination==

The player is able to nominate a unit to become the LAND_HOLDER, but this only works with units of [LAND_HOLDER] level 1. The player can select all units, only limited by the PRECEDENCE of the current units' positions.

A unit that has a position with a PRECEDENCE lower or equal to that of the landholder's position, cannot be selected. This means that a baron (or count) from another site or the monarch cannot be selected, because their precedence is lower or equal.

The GENDER token does not work here: also units with the wrong gender (sorry) can be selected.

==Levels==
In mods, up to 10 levels of LAND_HOLDER may be defined.

If a landholder is replaced by a wrong landholder number (1 replaced by 3), then the number 3 is still correctly attached to the settlement.

If the current landholder has the highest available landholder number, then the next elevation will not happen - the diplomat will not elevate your fortress to a higher position, even if that position might be REPLACED_BY a lower landholder.

These chains do work:
* 1 -> 2a - > 2b -> 3
* 1 -> 3 -> 2 -> 4

These chains do not work:
* 2 -> 3 (need to start at 1)
* 1 -> 4 -> 2 -> 3 (stops after 4 as the highest)
* 1a -> 2, 1b -> 2 (only 1a and 2 work, 1b is not used)

==Moving landholders==

It may happen that a land-holder no longer lives at the site which they are the landholder of, specifically when the current landholder dies, leaving the title to an heir living somewhere else.

To prevent this from happening, you can make their succession from heir and make sure that their kids live at your site. Or, you can make their position succeeded by another civ position, and make it so that this civ position is somehow available on your site. But if multiple of these positions exist, it cannot be guaranteed that a citizen of your fortress will inherit the title.

In world gen, a landholder lacking the DUTY_BOUND-token will also move to the site they like, according to legends mode.

==Replacement by a generic civ-position==

If a landholder is replaced by an AS_NEEDED non-landholder civ-position, then this will work: the current landholder loses that title upon settlement-elevation and gains that civ-title. However, the civ-title lacks the landholder-property of being attached to the land. It will not show the name of the settlement alongside the position's name. So no "minister of Shovelmounts"

If a landholder is replaced by a general AS_NEEDED civ-position, that itself is also replaced by a generic AS_NEEDED civ-position, then firstly the elevation is executed and also the unit gains that new position. However, he immediately loses it, because an AS_NEEDED position that is replaced by another position can be filled initially, but units wont be able to hold that title.

==Landholder with fixed number==

A landholder's position that has a fixed number will be created and filled directly when the civilisation is born, so this position slot is then not available for the regular landholder-mechanic and will also not be used. That landholder will thus not be attached to a settlement.

It doesn't matter if the landholder's position is connected to the regular landholder's-chain with the REPLACE_BY token.

==Responsibilities==

When given a certain [RESPONSIBILITY], a landholder may function as a regular civ-level noble. If the position has [TRADE] or [OUTPOST_NEGOTIATING] responsibilities, then the landholder functions both as a diplomat and as an actual land holder. A landholder with the [MILITARY_STRATEGY] responsibility will travel around taming creatures in world-gen, according to legends mode.

Besides that, the responsibilities work the same as with any other on-site living position-holder, civ or otherwise.

=Military=
==Squad management==
In the vanilla game, the Squad interface only becomes available after a militia commander has been appointed. Until then, the window displays:{{DFtext|You must appoint somebody first to create a squad.}}

What’s surprising is how this is determined internally. In the entity raw definition, '''only the last two positions that include a [SQUAD] token are checked''' to decide whether the interface is accessible at all. As a result, if your hierarchy defines commanders A through E, appointing '''Commander D or E''' unlocks squad formation, while appointing A–C does nothing.

In other words, squad availability is not tied to ''having a militia commander'', but to ''which specific positions happen to be last in the raw list''—a notably hacky implementation.

These 'last two' are always the last two '''available positions.''' So if they get [REPLACED_BY] or become available because of [REQUIRES_POPULATION], the game adapts to those.

==Squad assignment==

Squads can be assigned, even if the leader position has no holder.

A specific unit can only have one position associated with a squad. If it gains another 'squad holding position', it is unassigned from the first one. This does not work with a 0-squad, so only 1+squads are taken into consideration. This technique can possibly be used to distribute all positions equally among all citizens. It does however not work with election and assumption.

If a civ-level position is associated with a squad and it gets a site-level squad-holding position assigned, it loses the current civ-position.

Squads can get really messed up, if you make the position (or multiple) either elected or not-elected and not-appointed, then this can cause the game to assign multiple squads to the same unit. Automatic assignment and election does not take squads into account, but the nobles screen does. This can cause the positions to be cleared as the game figures out that they have more than one position, and immediately get elected or assumed again.

Positions that cannot have a squad-position:
* A site- or civ-position with a [SUCCESSION] token cannot be appointed a squad-holding-position. The other way around, however, does work. For example, if a site-position with a [SUCCESSION]-token is appointed to a unit that has already a position with [SQUAD]. But when that squad position is assigned to another unit, it cannot be assigned back.
* A position with [SUCCESSION] can also not be assigned as a '''member''' of a squad.
* A squad-holding position with a formed squad cannot be appointed to another squad holding position.

If a position has at least one squad member, it cannot be left vacant. First, the squad has to be disbanded, then the position may be cleared.

==0-squads==
A 0-Squad is defined in a position as [SQUAD:0:member:members]. It does not seem to do anything useful as of now.
* It cannot be used to activate the [[Squad|military interface]]
* It does not restrict the assignment of [SUCCESSION] positions.
* Assigning this position does not clear any previously held squad position.
* The [[Leader]] and [[Tactician]] skill are not marked as relevant skills and are not taken into account in elections.
* It cannot be formed as a squad.

=Further testing=
The following questions may need additional testing. Feel free to add or answer
* Everything regarding COMMANDING and army-structure
** [http://www.bay12forums.com/smf/index.php?topic=175437.msg8331668#msg8331668]
** [http://www.bay12forums.com/smf/index.php?topic=165213.msg8335682#msg8335682]
** [http://www.bay12forums.com/smf/index.php?topic=174584.msg8026854#msg8026854]
* Everything regarding CONQUERED_SITE, but it is presumably just like site. But what if you combine SITE or LAND_HOLDER with it?
* Stuff about the monarch, its arrival and its entourage.

=Oddities (Bugs)=
Almost everything on this page could be called an oddity. Because of their unexpected usability, some may also be referred to as “undocumented features.” Others, however, are simply odd and not particularly useful, yet I hesitate to call them “bugs.”
* If a certain threshold is reached that makes an elected position electable, and the triggering event that initiates this evaluation is an assumption, then the resulting assumption is also referred to in the messages as an election

=Examples=

===The Founder===
The founder is a single dwarf, appointed at embark. They will be the only one ever to have this position and are not replaceable. When they lose their position some way, the position will not be assumed by another dwarf.
{{gamedata|title=The Founder|
[POSITION:THE_FOUNDER]
[NAME:the founder:founders]
[NUMBER:1]
[SITE]
[ALLOWED_CREATURE:DWARF:ALL] - will only be filled at embark, but not assumable later.
[REJECTED_CREATURE:DWARF:ALL] - will only be filled at embark, but not assumable later.
[SUCCESSION:BY_POSITION:THE_FOUNDER] - not unassignable, also cannot be assigned to a [SQUAD] position.
[PRECEDENCE:200]
Non APPOINTED_BY
Non ELECTED
Optional: Add responsibilities to make the game select a unit with certain skills.
}}
===Marriage bar===
Dwarven matrons are held in great honour. Upon marriage, a female dwarf is no longer expected to perform menial labour. All dwarven males hold this position by default, granting their spouses exemption from menial work.

The position becomes available with the arrival of the first migrants; otherwise, on embark, it would be assumed by females. Its succession rule is non-functional, but this prevents the player from unassigning the position. A squad size of 1 and the succession rules together prevent a unit from assuming the position more than once.

With precedence set to NONE, the position name is hidden, while LAND_NAME remains visible on the nobles screen. All married females receive the suffix “, Mrs.” and are marked as Nobles.

The practical usefulness of this position is debatable, but it serves as a clear demonstration of several mechanics.
{{gamedata|title=Mrs. Urist|

[POSITION:MRS_URIST]
[NUMBER:300]
[SITE]
[ALLOWED_CREATURE:DWARF:MALE]
Not APPOINTED_BY
Not ELECTED
[LAND_NAME:Dwarven male]
[NAME:dwarven male:dwarven male]
[PRECEDENCE:NONE]
[SPOUSE_FEMALE:, Mrs.:spouses]
[MENIAL_WORK_EXEMPTION_SPOUSE]
[REQUIRES_POPULATION:8]
[SUCCESSION:BY_POSITION:MONARCH]
[SQUAD:1:member:members]
}}
{{Category|Modding}}
{{Category|Entities}}
{{Category|Guides}}