MafiaWiki:RoleParser syntax

This wiki uses (or will use, when I've finished writing it) a standard syntax for specifying roles on setup pages and the like. This is known as a "role string", and is parsed into a role PM (or other desired form of output) using {{RoleParser}}. This page documents the syntax of a role string.

Role components

A role string consists of a number of components, separated by slashes. A component is a faction, specific type of role, or role modifier. So for example, Town, Cop, and 1-shot are all components. Generalised groups of modifiers (such as Night Specific) can also be used as components in order to see what a generic role PM would look like, but cannot be used in a setup page.

Note that forming a role string is not simply a case of replacing all the spaces in a role name with slashes; some role components consist of multiple words, as the words always go together to form the role name. So for example, a Werewolf Fruit Vendor would be Werewolf/Fruit Vendor: a Fruit Vendor is a single type of role, not a Vendor role with a Fruit modifier. Likewise, a Town Odd Night Paranoid Gun Owner Tracker would be Town/Odd Night/Paranoid Gun Owner/Tracker. Meanwhile, a Town Weak Doctor would be Town/Weak/Doctor; although the Weak modifier applies to the Doctor role, they're conceptually separable parts of the role.

One special case to note is that of vanilla roles. In a role string, these should be specified using just the faction, e.g. Town (not Town/Vanilla or Vanilla/Townie). The same sort of principle applies to modifier names that are normally specified before the faction name, e.g. a Bulletproof Townie is Town/Bulletproof.

Component grouping

In order for a role string to be parsed into a role PM, it's important to be clear on which components will be grouped with others. For example, is a Town/Loud/Doctor/Cop a combination of a Loud Doctor and a Loud Cop? Or a Loud Doctor and a Cop? In order to resolve this sort of ambiguity, you should ideally order the role string in such a way that it's unambiguous, e.g. Town/Cop/Loud/Doctor or Town/Loud/Cop/Loud/Doctor, but there are nonetheless consistent rules about what will combine with what.

Note that one special case is that of hidden role components such as Paranoid. These will be ignored by the role parser entirely (as they don't appear in the role PM).

The first thing to note is that a role PM is conceptually split into four sections: faction, passives, miscellaneous, and actives. Each of these sections groups components a bit differently.

Faction

The faction – Town, Mafia, Werewolf, or various third-party factions – always comes first in a role string. This is used to calculate the name of the faction itself, any factional abilities (e.g. the Mafia will automatically be given their factional knowledge of who's on their team, their factional communication, and their factional kill), and the win condition. It's possible for a setup to add general overriding rules on how a faction operates, e.g. a Nightless setup will not offer the Mafia a factional kill, and those will be respected if communicated to the role parser as extra parameters. If you need to define your own factions, you can put arbitrary text here as long as you write an override for their win condition and for any factional abilities they might have.

The faction section of a role string is always one component long. So use Survivor rather than Neutral/Survivor, for example.

Passives

The passives section of a role string comes after the faction. It can group its components in the following ways:

A single passive ability

For example, Neighbor or Paranoid Gun Owner.

A timing modifier followed by a single passive ability

For example, Odd Night/Ascetic or 1-shot/Bulletproof. This is also how Backup passive roles are parsed, e.g. Backup/Miller.

A passive, untargeted active, or targeted active role component used to condition a derived passive role

For example, Bulletproof/Enabler, Bus Driver/Enabler or Cop/Enabler.

The passives section ends at the last passive ability that appears in the role string (not counting those which are part of the name of an active role, e.g. in Bulletproof/Activated the "Bulletproof" would not be counted). Passives are shown in the role PM above the list of abilities.

Passive roles whose name traditionally appears before the faction (e.g. Bulletproof, Ascetic) should appear before passive roles whose name traditionally appears after the faction (e.g. Miller, Neighbor) in order for the generated role name to appear in the right order.

Miscellaneous

The miscellaneous section of the role string contains components that affect active abilities, but can't be isolated to a single active ability. There are three main possibilities here:

• Sometimes a modifier applies to all actions a player uses, rather than a single action. For example, a Loud Jack of All Trades will end up being detected by anyone they visit with any ability. This sort of modifier goes into the miscellaneous section. (Note that this can't be the only thing in the miscellaneous section, otherwise it would be parsed as belonging to the first action rather than to all actions together.)
• Some modifiers affect the rules for using actions simultaneously, such as Multitasking, and thus don't apply to a single action.
• Some roles are effectively based on a list of possible actions, in which case the actions become part of the role and change in nature. A Jack of All Trades can use only use each of their action once (even without an explicit 1-shot modifier on them). An Inventor's abilities are gifted to other players rather than being used by the Inventor themself. These are interpreted, effectively, as "global modifiers" that are placed onto each action individually.

The miscellaneous section can contain any number of action modifiers (as long as it also contains something other than an action modifier), up to one modification on simultaneous action use, and up to one global change to how actions behave. They must appear in that order.

Although it's logically reasonable to apply a timing restriction to a role that's based on a list of actions (e.g. an Odd-Night Inventor), this cannot currently be handled by the automated role PM generator. This restriction may be lifted in the future.

Actives

The actives section comes last in the role string, and is used to list all the active abilities a player has, together with modifiers that affect that active ability specifically. This is normally (but not always) the most interesting section of a role PM. It can group its components in the following ways (with each group producing one bullet point in the active abilities list):

A single targeted ability

For example, Cop or Doctor.

A single untargeted ability

For example, Oracle.

A passive, untargeted active, or targeted active role component used to condition a derived active role

For example, Innocent Child/Activated or Roleblocker/Switch. (Note that Activated is written after the modified role, rather than before, so that all derived roles can be parsed in the same way.)

Any number of targeting/consequence modifiers followed by a single targeted ability

For example, Weak/Disloyal/Simple/Rolecop.

A scheduling modifier followed by any of the above

For example, Even Night/Vigilante or Backup/Tracker.