Editing Advanced Entity Position Mechanics

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

= Introduction = 

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

This article is the result of an investigation into the mechanisms involved in entity positions. It can be useful for modders or advanced players to understand how this part of ''Dwarf Fortress'' works.

==What is an entity?==
An entity is an organizational structure. It can have relationships with other entities. An entity is usually known as a [[civilization]] or a "site government", but merchant guilds, religious organizations, and bandit groups are also entities. An entity can have positions. In most cases these are hardcoded and generated by the game, but with civilizations and sites they can be customized with the raw entities.

==What is a position?==
A position is a special relationship between a unit and an entity. The unit holding a position has a larger influence over that entity as 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.

Citizen-level positions are in charge of the civilization as a whole, managing national trade, laws, and wars. These are, for example, the vanilla [[monarch]], [[princes]], [[diplomat]] and [[general]].

'''LAND_HOLDERS''' nobles are also positions at civ-level. These units are members of the national government, but have gained hold 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.
Example:  
{| {{prettytable}}
|- bgcolor="#ddd"
! referred position-type
! LAND_HOLDER
|-
| civilization
|  <span style="color:green">(baron is) APPOINTED_BY:MONARCH</span>
|}
color coding: </br>
* <span style="color:green">Exists in vanilla</span></br>
* <span style="color:blue">Possible in mods</span></br>
* <span style="color:red">Not possible</span></br>
* <span style="color:orange">possible to some extend.</span></br>
* <span style="color:gray">not yet fully investigated.</span></br>
{| {{prettytable}}
|- bgcolor="#ddd"
! referred position-type
! Civilization
! SITE
! LAND_HOLDER
! CONQUERED_SITE

|-
| civilization
| <span style="color:green">APPOINTED_BY</span> </br> <span style="color:green">COMMANDER</span> </br> <span style="color:blue">REPLACED_BY</span> </br> <span style="color:green">SUCCESSION</span>
| <span style="color:blue">APPOINTED_BY</span> </br> <span style="color:gray">COMMANDER</span> </br> <span style="color:red">REPLACED_BY</span> </br> <span style="color:orange">SUCCESSION '''(1)'''</span>
| <span style="color:green">APPOINTED_BY</span> </br> <span style="color:gray">COMMANDER</span> </br> <span style="color:red">REPLACED_BY</span> </br> <span style="color:blue">SUCCESSION</span>
| <span style="color:gray">APPOINTED_BY</span> </br> <span style="color:gray">COMMANDER</span> </br> <span style="color:gray">REPLACED_BY</span> </br> <span style="color:gray">SUCCESSION</span>

|-
| SITE
| <span style="color:red">APPOINTED_BY</span> </br> <span style="color:gray">COMMANDER</span> </br> <span style="color:red">REPLACED_BY</span> </br> <span style="color:orange">SUCCESSION '''(2)'''</span>
| <span style="color:green">APPOINTED_BY</span> </br> <span style="color:green">COMMANDER</span> </br> <span style="color:green">REPLACED_BY</span> </br> <span style="color:blue">SUCCESSION</span>
| <span style="color:red">APPOINTED_BY '''(3)'''</span> </br> <span style="color:gray">COMMANDER</span> </br> <span style="color:red">REPLACED_BY</span> </br> <span style="color:orange">SUCCESSION '''(4)'''</span>
| <span style="color:gray">APPOINTED_BY</span> </br> <span style="color:gray">COMMANDER</span> </br> <span style="color:gray">REPLACED_BY</span> </br> <span style="color:gray">SUCCESSION</span>

|-
| LAND_HOLDER
| <span style="color:blue">APPOINTED_BY</span> </br> <span style="color:gray">COMMANDER</span> </br> <span style="color:red">REPLACED_BY '''(6)'''</span> </br> <span style="color:blue">SUCCESSION</span>
| <span style="color:green">APPOINTED_BY</span> </br> <span style="color:gray">COMMANDER</span> </br> <span style="color:red">REPLACED_BY</span> </br> <span style="color:orange">SUCCESSION '''(5)'''</span>
| <span style="color:orange">APPOINTED_BY</span> </br> <span style="color:gray">COMMANDER</span> </br> <span style="color:green">REPLACED_BY '''(7)'''</span> </br> <span style="color:orange">SUCCESSION '''(8)'''</span>
| <span style="color:gray">APPOINTED_BY</span> </br> <span style="color:gray">COMMANDER</span> </br> <span style="color:gray">REPLACED_BY</span> </br> <span style="color:gray">SUCCESSION</span>

|-
| <span style="color:gray">CONQUERED_SITE</span>
| <span style="color:gray">APPOINTED_BY </br> COMMANDER </br> REPLACED_BY </br> SUCCESSION</span>
| <span style="color:gray">APPOINTED_BY </br> COMMANDER </br> REPLACED_BY </br> SUCCESSION</span>
| <span style="color:gray">APPOINTED_BY </br> COMMANDER </br> REPLACED_BY </br> SUCCESSION</span>
| <span style="color:gray">APPOINTED_BY </br> COMMANDER </br> REPLACED_BY </br> SUCCESSION</span>
|}

Remarks:
# Works only in world-gen, if an 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.
# wont appear at all
# This is neccesary for the landholder-chain to work property. It doensn't work otherwise.
# This works only outsite of the landholder-chain, so when landholders are simply regarded as civ-level nobles. might also work in world-gen
# 

==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, his position is shown among the site-level positions in your [[nobles screen]]. They appear to function as a site-level noble. They may have demands, mandates, squads and the like. They can appoint nobles at the site-level.

If they have certain RESPONSIBILITY's, they do the tasks that go with them.

=General=
==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 refered 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 Automation''', 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 its RESPONSIBILITY's), but can always be used in player mode.

A positions can in fortress mode be filled by the same unit. A unit can gain multiple positions in fortess-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 'Loosing a position'.

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

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 site-entity, however this does not happen in world-gen. Only at player-managed sites units can 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. 

In world-gen, a unit at a site might inherit a civ-level position and still remains a member of the local government. When this happens however, they move to the capital.

In world-gen, 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, he has all those positions responsibilities and properties stacked up. It is presumable that 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.

=RESPONSIBILITY=
If a civ-noble having certain responsibilities arrives at a site and start to live there, it will perform the tasks coming with that responsibility. This means that a civ-manager will do management while he's a citizen of your fortress.

The only AS_NEEDED-position that is created in world-gen is that of the responsibility DELIVERS_MESSAGES, of a site level.

==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. 

=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 a AS_NEEDED number. The appointable positions only become available after a appoiner-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 doesnt 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
* 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 reached or if it is available from the start(like expedition leader), als long as it cannot be appointed, it still is INVISIBLE for the player. 

It might strike as odd, may a position becomes filled automaticly in fortress mode, when that position is not even visible. This might be the case if the current holder of a non-appoinable position dies or succeeds another position. Regardless of player-visibility, these positions will be automaticly filled in if the nescesary 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 expedion leader, when the expedion 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. 

=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 'head of state' in the embark screen.
==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 automaticly 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 eachother and seem to only have a meaningfull function if combined. Nobles with REQUIRES_POPULATION require the population to have a specific size. 

This works on 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. 

==Effect of replacement==

Replacement is immediate. The current holding unit looses the position. Even before succession_by_position-rules are applied. 

Replacement is also complete. 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 looses its position.

In legends, replacement is mentioned as: "(unit name) ceeded to be (position name)"

The replacement of a AS_NEEDED position empties the positions 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 made undone, as soon as you close the window. 

==Evaluation of replacement and required_population==

The game does not constantly check if positions need to become available or need to be replaced. This is know behaviour with for example the mayor. He won't appear automaticly if the needed population is reached. The positions need to be "evaluated". It is not known when this will be done without any player interaction. Players can trigger the evaluation-mechanism by (re)assigning any random site position. 

==LAND_HOLDER replacement==

The landholder-chain uses replacement differently. It does not empty 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 land-holders, the land-holder-chain is broken, so replacement is required for the landholder-system to work.

REQUIRES_POPULATION does not work in the landholder-chain. 

==What does not work==

Attention: If a position cannot be appointed, for example because of 'mutual appointment', it still exists according to replacements 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 his 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, 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.

=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 he is 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 the be the right caste and/or class. It does not seem to work with creature-types. 
* The unit needs to be a member of that site or its parent civ-government. 
* It needs to be CAN_LEARN or INTELLIGENT (SLOW_LEARNER cannot take positions) or otherwise be able to think.
* It needs to be an adult.

==Appointment==

Positions that have a [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 temporary 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 anyway, whatsoever. 

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

''In contrary of what it said in the wiki so far, it is tested and confirmed, that civ-level nobles also CAN appoint site-level nobles. They need to be at that 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.

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

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

Outside of fortress-mode, the game will always attempt to appoint nobles whenever possible, als 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 word-gen all, positions become available and are automaticly appointed, taking population- and appointment-requirements in consideration. 

Positions that are REPLACED_BY are culled and wont be filled.

If a citizen of your fortress holds a civ-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 a player in fortress mode===
In fortress mode, the positions that need to be appointed stay empty on embark and it is for the player 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. The player 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 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-appoined or left vacant, but as soon as the [[nobles screen'' closes, it cannot longer be replaced or left vacant. From then on, the succession-rules determine who gains that position when the current holder looses the position.
* 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 assumed shortly after. 
* A position that is both ELECTED and appointed by, cannot be appointed by the player. In contrary to world-gen sites. It's slot is visible, but it doesnt show the +-sign. This is either by AS_NEEDED as 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 if he likes, also in contrary of 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.

An election goes before succession. 

A position that is also APPOINTED_BY gets never elected. Even if the position somehow gets filled, (re)-elections wont happen. So, it doesn't seem possible to have a elected position become available from a certain land_holder's level. 

A 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. 

When a settlement gets up a level in the LANDHOLDER-track, an election is happening, in which the current electable positions undergo a new election-round.

==Assumption==

A position that is not APPOINTED_BY nor ELECTED, or is appointed by positions that are not available in your site or civ, it will be assumable by a random dwarf. If it has responsibilities that require certain skills, then these are taken into consideration. (verify)

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

If a 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 civ-entities. 

Assumable positions that have become empty will not be assumed if that position has a valid SUCCESSION -successor. In that case, the successor inherrits 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 this positions at embark, they all are assigned to the same unit.  

A position that has an appointer, which got replaced because of REPLACED_BY, it will not become assumable. Also positions that have a AS_NEEDED appointer that is not yet filled (or ever), wil 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. De succeeding dwarf will also lose its previous position. The message that is shown, is: "(creature name) being the rightful heir, has inherited the position of (position name)"

Succession works both at site-level as at civ-level, both in world-gen and in fortress-mode. Succession by position on 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. 

It is possible to assign multiple levels of SUCCESSION:BY_POSITION, 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 seems to be random which one is used. 
Its is not always:
* The first or last defined token
* The first or last appointed unit
Not yet tested:
* Age, unit-id or other possible variables
* The precedence of the succeeding-position

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-one. See further details by "Squad"

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

If the successor is a 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 unfortinately moves you civ-noble off site.
This may also happen with the land-holder of your site, for example when it is succeeded by another civ-level position. 
Its needs further testing, if the landholder somehow can be called back. 

===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 cannot be combined.  There 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 wont work even if the positions:
* are AS_NEEDED or having a fixed number.
* Are LAND_HOLDER

===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 the position. For example if they have become the 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 some cases where succession by position is applied too early, when a position initially becomes available. It is filled in by the succession-mechanism, without player interaction. This is probably a bug, but it can be exploited to create some interesting textures. When a position first becomes available, the game will check whether there is a valid successor-by-position. Then this unit is immediately assigned for this new position. If this happens in Fortress mode with a position that can also be appointed by a unit present, succession is activated before the player has a chance to appoint a holder.
Using premature succession, a ELECTED + APPOINTED_BY position can be filled, but assignment or elections wont happen. It seems to have no other benefits. 

This only applies to Fortress mode, not in world-gen, but can be used with both site and civ-level nobles. 

This applies to:
* The successable position is created, because the REQUIRES_POPULATION is reached
* The successable position can be APPOINTED_BY another position of the same level (site/civ), that has just been created because that ones REQUIRES_POPULATION was reached.
* The successable position can be appointed by another SITE - AS_NEEDED-position, that has just been created and filled.
* The successable (site/civ) position is APPOINTED_BY the LAND_HOLDER-position, that has just been created because your site's level is elevated. It happens when the diplomat leaves the area. Presumably because landholders are also AS_NEEDED.
	
It is not applied when:
* An AS_NEEDED successable position-slot is just created by the player, that has a filled succeeding position. (AS_NEEDED- positions always need to be appointed after they are created)
* The successing position is filled after the successable position becomes available. Then its too late. 
* The position can be appointed by another position(site/civ) with a fixed number, that is just appointed.
* Anything world-gen
* The succeeding position is replaced by the succesable position. In that case, the unit is first removed by the replacement, before the succession-mechanism had the chance to use that unit.

===What does not work===

* A circular succession-loop let the game crash.
* Succession plays no role during elections. Elections have priority

=Losing a position=

A unit can lose a position, when
* It dies
* It succeeds another position
* It is assigned to another SQUAD-holding position
* It commits a crime and is convicted.
* 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 a civ-level-position, as this always leaves the previous position vacant.

=Embarkment=

Two types of positions are automaticly filled by embark. 
* Positions without appointed_by or elected. All these positions, even with a NUMBER higher than 1, are all filled with the same, single, random dwarf.
* Positions that are elected are filled-in by the normal election rules.

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

=Land Holders=

A Land-holder is a '''special civ-level noble''' who gets a certain piece of land to hold, when that land gains a certain level. This is 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. 

==Functioning of the regular landholder-chain==

The distinct difference between an 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_holders position to function as so, 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 land-holder 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 landholders 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 assingment. A landholder is in vanilla appointed by the monarch. Changing this doesn't seem to do anything. If he is appointed by a site-position, a not-yet-existing civ-position, or not appointed at all: the system keeps working regularly. 

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 he gains the title, he 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 extend:
* In world-gen it does work according to succession rules, and site-positions can be used here.  This means that a site-position or a civ-position can inherit a landholders-positon and vice versa.
* In fortress-mode, once a landholder has been appointed, it then can inherit civ-level positions, and vica 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 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

==Nomination==

The player is able to nominate a unit to become the land_holder. This only works with 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 as that of the landholders-position, cannot be selected. This means that a baron (or count) from another site or the monarch or cannot be selected, because their precenence is lower or equal. 

The token GENDER 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 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)

==Moving landholders==

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

To prevent this from happening, you can make his succession from heir and make sure that his kids live at your site. Or, you can make his 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 he likes, according to legends mode. 

==Replacement by a generic civ-position==

If a landholder is replaced by a 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 wil 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 immideatly looses it. Because a 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 Landholders 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 landholders position is connected to the regular landholder's-chain by the REPLACE_BY-token. 

==Responsibilities==

When given a certain RESPONSIBILITY, a landholder may function as regular civ-level nobles. If the position has responsibility TRADE or OUTPOST_NEGOTIATING, then the landholder functions both as diplomat and as 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 at your site living position-holder, civ or otherwise. 

=Army-stuff=

==Squad assignment==

Squads can be assigned, even if the leader position has no holder. This seems to be the case if the number is fixed (1) or if the position is assigned by a non-military position.

A specific unit can only have one position associated with a squad. If it gains another 'squad holding position', it is unassigned of the first one. This does not work with a 0-squad, so only 1+squads are taken into consideration; so 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 in 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 immidiatly get elected or assumed again. 

Positions that cannot have a squad-position:
* A site- or civ-position with a defined successor cannot be appointed a squad-holding-position. 
* The other way around however does work. If a site-position with a successor is appointed to a unit that has already a squad-holding position, it does work. But when that squad position is assigned to another unit, it cannot be assigned back. 
* A squad-holding position with a formed squad cannot be appointed to another squad holding position.

If a position had some squad-members, it cannot be left vacant. First, the squad has to be disbanded, then the position may be cleared.

=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?
* What are the exact requirements for a position to function as militia commander, so that squads can be created? I've not figured out this exactly. 
* Stuff about the monarch, its arrival and its entourage.
* It seems that the monarch cannot be appointed manager. Why exactly? Precedence? 
* can replaced positions be recreated?


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