Basics

All “Data Items” in Commlink support a common XML structure.

• identifier (MANDATORY) is a machine usable string consisting of letters, numbers and the _ symbol and must start with a letter. Preferable it is the lowercase name of the item, whitespaces replaced with _ .

• lang (OPTIONAL) can limit the data to be used for a specific language, e.g. when an dataitem differs in US and DE rules

• <choices> (OPTIONAL) contain selections of a specific type the user has to make. The decision made in those choices will be available in the following blocks.

• <requires> (OPTIONAL) contains requirement for the data item

• <modifications> (OPTIONAL) contain - Surprise! - modifications that this data item makes to the parent container (e.g. the character or the item)

All this elements are optional, so it is possible that one, only one or all a present.

The concrete data element then has additional attributes or XML elements. E.g. the quality “Social Stress” from the Core Rulebook:

I18N for data items

To get language specific display names, page references and descriptions, translatable I18N keys are derived from the data item. Each data item has a type key (defined by @DataItemTypeKey in the source code annotation). This key is often identical to the Shadowrun name of the data item - e.g. “quality” for qualities (see https://bitbucket.org/rpgframework-cloud/shadowrun-common/src/master/Shadowrun%20Common%20Core/src/main/java/de/rpgframework/shadowrun/Quality.java )

Commlink expects the following i18n keys to be present:

Choices

Choices are meant to be displayed to the user along with a list of possible options to select from. They (usually) require that all options to choose from must be of the same type.

The following attributes are supported:

• type (MANDATORY) refers to the kind of data - e.h. an character attribute, a quality ...

• uuid (MANDATORY) must include a valid UUID that is at least unique within the data item.

• options (OPTIONAL) should be present when you want to limit the choice to some items (e.g. not "pick any skill" but "pick one of the skills electronics or tasking"). It contains a comma-separated list of identifiers.

• ref (OPTIONAL) contains the identifier used for building i18n translation identifiers (see sub-selection example below)

• neg (OPTIONAL) to express a negation of given options ("select any skill but ...")

• count (OPTIONAL) to define how many selections are possible (default is "1").
  Not used for Shadowrun (yet?)

• distribute (OPTIONAL) - a comma separated list of integers, for cases where specific values need to be assigned (“assign +3,+3 and +1 to the following skills …”)

Example: Adept Power “Improved Ability”

Choices with sub-selections

Some data items require the user to make decisions not related to specific data types, but choose from a list of options only related to the data item itself. Like for the “Allergy” quality in SR6, you not only want to enter a name, but you need to pick a trigger and a severity. In this case

• the type needs to be "SUBSELECT"

• the ref-attribute needs to be present and contain an identifier of your choice

If that is given, the <choice> element may have multiple <subOption> elements,

Example of choices with sub-options

Example of sub-options with modifications

I18N for sub-selections

The i18n keys extend the regular data item keys by adding the identifier from the ref-attribute and the identifier from the <subOption> id-attribute

Requirements

With requirements you can define under which circumstances the specific data item is valid to pick for the character. The following definitions are supported:

• <datareq> - defines the requirement regarding the existence of something

• <valuereq> - defines the requirement regarding a rating of something

• <selreq> - defines a list of requirements where it is sufficient that one of the requirements is fulfilled.

Basics: Adressing the target of the requirement

Often it is clear WHAT/WHO is required to fulfill the requirement - to be precise the context matters. If an accessory added to a weapon has a requirement, this usually refers to the weapon it is applied to. Sometimes it may be necessary to define another targets.

The applyTo= attribute, while optional, should be used to explicitly define who is addressed with a requirement. See here for valid values.

<datareq>

Use this tag when you want to express that either a specific data item must be present (or may not be present) in the target or that an attribute has an exact value.

Valid attributes:

• applyTo (OPTIONAL) - see above

• type (MANDATORY) - type of data that is required

• ref (MANDATORY) - identifier of the item

• neg (OPTIONAL) - boolean - valid values are “true” or “false” (default).
  If set to true, the non-existence of the data is required.

Examples:

<valuereq>

This is similiar to <datareq>, but has some additional features that allow you to test for the levels on the referenced field.

Valid attributes:

• applyTo (OPTIONAL) - see above

• type (MANDATORY) - type of data that is required

• ref (MANDATORY) - identifier of the item - or “CHOICE” when referring to an user decision.

• choice (OPTIONAL) - refers to a decision made in a <choice> element

• value (OPTIONAL) - the minimum value of the referenced data.
  Usually an integer number, but in case of gear this can be an item attribute variable (prefixed with a $)

• max (OPTIONAL) - like value but the maximum value

Examples:

<selreq>

Use this select requirement when you want to define a list of requirements where only one of them must be fulfilled.

Modifications

This is the most common building block of Commlinks data items. With modifications you express all changes made to data (characters, gear …)

• <allowmod> - Allow something otherwise forbidden

• <checkmod> - modify tests on attributes, skills, ...

• <costmod> - modify edge costs of actions

• <embed> - put a piece of gear in an accessory slot of the parent item

• <itemmod> - Add some data item (e.g. a quality to the character)

• <recommod> - Recommend the usage of something

• <relevancemod> - Mark the target as being relevant for a specific topic

• <valmod> - Add points to a specific numeric value

Common attributes to all modifications

• type - Type of object that the modification deals with

• apply - To which target will the modification apply (valid values)

• when - If restricted, is this modification only valid during chargen or career? (valid values)
  ( This is not really made use of in Commlink)

• cond - A string that defines the circumstances when the condition applies. Not yet implemented

<itemmod> - DataItemModification

DataItemModifications are used to add something - usually to characters.

Their additional attributes are:

• ref (MANDATORY)- Identifier of the object added (type-Attribute is here mandatory too).
  The keyword “CHOICE” will tell that a previous decision is to be used

• variant (OPTIONAL) - Identifier of a gear variant

• choice (OPTIONAL) - UUID of the previous decision

• remove (OPTIONAL) - Boolean. If set to "true", the item isn't added but removed

• options (OPTIONAL) - for ref="CHOICE", overwrite the <choice options=""> attribute

• mode (OPTIONAL) - Identifier of mode when the modification applies - Not implemented yet

• id (OPTIONAL) - UUID. May be used to identify automatically added elements - e.g. like a lifestyle added to a character - and therefore prevent duplicate additions

DataItemModifications with premade decisions

Some items you want to add somewhere needs to be configured with decisions for <choice> elements. To achieve this, you can add any number of <decision> elements as children to a DataItemModification.

A decision has two attributes: choice (with the referenced choice's UUID) and a value .

Examples

<valmod> - ValueModifications

ValueModifications are special variants of DataItemModifications with additional attributes

• value (MANDATORY) - the numeric value of the attribute/skill to set.

• set (OPTIONAL) - for attributes and skills, define if you want to change the "AUGMENTED" or the "ARTIFICIAL" value - or define a "MAX"imum

• table (OPTIONAL) - a comma-separated list of values. Use the evaluated value-Attribute as an index to lookup the real value

Examples:

<embed>

EmbedModifications are special variants of DataItemModifications with additional attributes

• intoType (MANDATORY) - the type of item to which the item shall be added

• intoRef (MANDATORY) - the identifier of the item to which the item shall be added

• included (OPTIONAL, Default: false) - if TRUE, treat the embedded item as already belonging to the stats

• nocap (OPTIONAL, Default: false) - if TRUE, treat the embedded item as not counting to a capacity limit, should such exist.

• link (OPTIONAL) - A UUID. Only used when ref="LINK"

Examples

<allowmod>

AllowModifications are special variants of DataItemModifications with additional attributes. They are used to allow options otherwise forbidden (like magical skills for mundane users)

• neg (OPTIONAL, Default: false) - Forbid instead of Allow

<checkmod>

EmbedModifications are special variants of ValueModifications with additional attributes. Used mostly to define Edge modifications

• what (OPTIONAL) - Defines what the value influences. Allowed values are:

  • BONUS : Add hits to a roll result

  • DICE : Add dice to the pool

  • REDUCE_THRESHOLD : Reduce the threshold for something

  • EDGE: How much Edge (that can be kept for a longer time) is gained

  • EDGE_ONLY_TEST: How much Edge (that must be spent for the test) is gained

  • USAGE : Making a test is allowed at all

  • EDGE_COST_MALUS: Reduce the cost for Edge Actions

  • EDGE_BOOST: Change the cost for Edge Boosts

  • REPLACE_WITH_WILD: How many dice from the pool should be converted to wild die

  • NOT_SPEND_EDGE : May not spend Edge on this test - ignores the value field

  • NOT_EARN_EDGE : May not gain Edge on this test - ignores the value field

  • OTHER : Has no special effect, but is a placeholder for everything not covered above

Examples: