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, general restriction, 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.

General restriction

A general restriction is used to make a global change on how the owner's active abilities are used. For example, a Jack of All Trades can use each of their abilities once each (and by default, only one per night); an Inventor's abilities are gifted to other players rather than being used by the Inventor themself; and a Multitasking player can combine actions on a single night.

The general restriction section is often missing entirely; it's rarely used. If it is used, it can group its components in the following ways:

A single general restriction

For example, Multitasking.

A targeting/consequence modifier followed by a single general restriction

For example, Weak/Inventor.

Two general restrictions

Multitasking/Inventor and Multitasking/Jack of All Trades are special cases that are considered legal even though they would normally violate the rules.

At present, timing restrictions can't be combined with general restrictions; it's surprisingly hard to generate a role PM for, e.g., an Odd-Night JOAT in an automated way. This restriction may be lifted in the future.

General restrictions are a category of their own because they affect the heading of the list of active abilities (as opposed to appearing before inside it).

Actives

The actives section comes last in the role string, and is used to list all the active abilities a player has. 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.