1 Basics
- 1.1 I18N for data items
2 Choices
- 2.1 Choices with sub-selections
  - 2.1.1 I18N for sub-selections
3 Requirements
- 3.1 Basics: Adressing the target of the requirement
- 3.2 <datareq>
- 3.3 <valuereq>
- 3.4 <selreq>
4 Modifications
- 4.1 Common attributes to all modifications
- 4.2 <itemmod> - DataItemModification
  - 4.2.1 DataItemModifications with premade decisions
- 4.3 <valmod> - ValueModifications
- 4.4 <embed>
- 4.5 <allowmod>
- 4.6 <checkmod>

Basics

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

<dataitemname id="identifier" lang="language">
  <choices>
  </choices>
  ..
  <requires>
  </requires>
  ..
  <modifications>
  </modifications>
</dataitemname>

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.

Not all item types will expect all of the mentioned types.

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

<quality id="social_stress"	      karma="8" pos="false" type="NORMAL">
   	<choices>
   		<choice type="TEXT" uuid="93911833-2a2c-418b-b610-4894779879bf"/>
   	</choices>
     <modifications>
       <valmod type="SKILL" ref="con" value="0" set="EDGE_USAGE" />
       <valmod type="SKILL" ref="influence" value="0" set="EDGE_USAGE" />
     </modifications>
</quality>

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:

Key	Meaning	Example for “quality”

Key	Meaning	Example for “quality”
<datatype>.<itemid>	Display name of the item	quality.allergy=Allergy
<datatype>.<itemid>.page	Page reference	quality.allergy.page=74
<datatype>.<itemid>.desc	Fulltext description	quality.allergy.desc=Maybe it\u2019s a runny nose …
<datatype>.<itemid>.short	Short description (rarely used)

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”

<power id="improved_ability"  cost="0.5" hasLevel="true" act="PASSIVE">
  <choices>
    <choice type="SKILL" uuid="05054102-0183-482a-9e2b-84bc8d5f153f" options="athletics,biotech,con,conjuring,cracking,electronics,engineering,influence,outdoors,perception,piloting,stealth" />
  </choices>
  <modifications>
    <valmod type="SKILL" ref="CHOICE" choice="05054102-0183-482a-9e2b-84bc8d5f153f" value="1" />
  </modifications>
  <requires>
    <valuereq type="SKILL" ref="CHOICE" choice="05054102-0183-482a-9e2b-84bc8d5f153f" value="1" apply="CHARACTER"/>
  </requires>
</power>

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

	<quality id="allergy" karma="2" pos="false" type="NORMAL" multi="true">
		<choices>
			<choice type="SUBSELECT" ref="allergen" uuid="55a6dda7-7565-4108-9a04-65b7607081df">
				<subOption id="rare" cost="0" />
				<subOption id="uncommon" cost="3" />
				<subOption id="seasonal" cost="6" />
				<subOption id="common" cost="9" />
			</choice>
			<choice type="SUBSELECT" ref="severity" uuid="b3cd035c-f2c3-4c56-abcd-9a218954d92a">
				<subOption id="mild" cost="0" />
				<subOption id="moderate" cost="3" />
				<subOption id="severe" cost="6" />
				<subOption id="extreme" cost="9" />
			</choice>
			<choice type="TEXT" ref="description" uuid="6a8484c5-043d-4ec7-bbb2-f56d3c51f72b" />
		</choices>
	</quality>

<subOption> elements are data items themselves, which means they can have <modifications> of their own. That usually isn’t expected and likely not supported - consult the developers.

Example of sub-options with modifications

   <quality id="dermal_alteration"     karma="3" pos="true" type="METAGENIC" cat="COMPLEX_TRAITS" >
     <choices>
       <choice type="SUBSELECT" ref="variant" uuid="0180ba51-5b30-471d-bdba-5e2482b8440d">
         <subOption id="bark"    cost="1">
		     <modifications>
		     	<!-- ToDo -->
     		  </modifications>
         </subOption>
         <subOption id="blubber" >
		     <modifications>
		     	<!--  ToDo ? Kälteangriffe -->
     		  </modifications>
         </subOption>
         <subOption id="camouflage_basic" cost="2">
		     <modifications>
     		    <checkmod ref="stealth" type="SKILL" what="BONUS" value="1"/>
     		  </modifications>
         </subOption>
       </choice>
     </choices>
   </quality>

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

Key	Meaning	Example for “quality”

Key	Meaning	Example for “quality”
<datatype>.<itemid>.choice.<ref>	Name of the selection to make	quality.allergy.choice.allergen=Trigger
<datatype>.<itemid>.choice.<ref>.<subOptionId>	Name of the sub-option to display	quality.allergy.choice.allergen.rare=Rare
<datatype>.<itemid>.choice.<ref>.<subOptionId>.desc	Fulltext description of the suboption	quality.allergy.choice.allergen.rare.desc=E.g. Precious metals,e …

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: