# Game Mode: migration.lst

This file contains information on the tags used in, and how to build, a migration.lst file. Before we get to how you build such a file though, let's first answer a few questions on the migration file in general.

## What the Character Migration File Does

The character migration tool works behind the scenes to smoothly load characters from older versions of PCGen into the current version. The file's primary purpose is to allow a character to be automatically updated to reflect changes in the relevant data sets.

## Building a Character Migration File

The migration file consists of lines of lst code, each defining a separate and specific migration item. Each line begines with the LST Object tag followed by supporting tags. These tags are described below. The LST objects currently supported include Sources, Abilities, and Equipment. The syntax for a migration line is as follows:

Migration Line Syntax

`<Old Object Key>` <tab> `<New Object Key>` <tab> `<Version Tags>`

## Migration File Tags

The tags used in the migration.lst file consist of two sets of tags.

Version Identification Tags

Source and Object Migration Line Tags

Examples of Complete Migration Lines.

### Version Identification Tags

The following tags identify the minimum and maximum versions for both the stable and developmental, of PCGen supported by the associated migration line.

*** New 6.01.03

Tag Name: MAXDEVVER:x

Variables Used (x): Text (Version number)

What it does:

- Specifies the developmental version of PCGen (e.g. alpha, beta) when the associated lst object was last coded in the old format.
- This tag is optional and if included must be later than `MAXVER`.

Example:

`MAXDEVVER:6.01.07`

The associated lst object was coded for PCGen developmental version 6.01.07 or earlier.

*** New 6.01.03

Tag Name: MAXVER:x

Variables Used (x): Text (Version number)

What it does:

- Specifies the production version of PCGen when the associated lst object was last coded in the old format.
- This tag is mandatory.

Example:

`MAXVER:6.0.1`

The associated lst object was coded for PCGen production version 6.0.1 or earlier.

*** New 6.01.03

Tag Name: MINDEVVER:x

Variables Used (x): Text (Version number)

What it does:

- Specifies the developmental version of PCGen (e.g. alpha, beta) when the associated lst object was first coded in the old format.
- This tag is optional and if included must be later than `MINVER`.

Example:

`MINDEVVER:6.01.01`

The associated lst object was coded for PCGen developmental version 6.01.01 or later.

*** New 6.01.03

Tag Name: MINVER:x

Variables Used (x): Text (Version number)

What it does:

- Specifies the production version of PCGen that the associated lst object was first coded in the old format.
- This tag is optional and if included must be earlier than `MAXVER`.

Example:

`MINVER:6.0.0`

The associated lst object was coded for PCGen production version 6.0.0 or later.

### Source and Object Migration Line Tags

*** New 6.01.03

Tag Name: ABILITY:x|y

Variables Used (x): Text (Old Ability Category)

Variables Used (y): Text (Old Ability Key)

What it does:

- This tag begins an ability migration line and is used to identify the old ability key as part of the migration to a new ability key.
- The `ABILITY` tag is used in conjunction with the NEWKEY, NEWCATEGORY, and version tags.

Example:

`ABILITY:Special Ability|Animal Fury`

*** New 6.01.03

Tag Name: EQUIPMENT:x

Variables Used (x): Text (Old Equipment Key)

What it does:

- This tag begins a equipment migration line and is used to identify the old equipment key as part of the migration to a new equipment key.
- The `EQUIPMENT` tag is used in conjunction with the NEWKEY and version tags.

Example:

`Kasari Gusoku`

*** New 6.01.03

Tag Name: NEWCATEGORY:x

Variables Used (x): Text (New Ability Category)

What it does:

- This tag is used in an ability migration line to identify the new category for the associated ability object when the ability category changes.
- If this tag is not included in the ability migration line the ability category will not change for the associated ability.

Example:

`NEWCATEGORY:Spell-like Ability`

*** New 6.01.03

Tag Name: NEWKEY:x

Variables Used (x): Text (New Key)

What it does:

This tag is used in a migration line to identify the new key (i.e. Source, Ability, and Equipment) for the associated LST object.

Example:

`NEWKEY:Guide To Pathfinder Society Organised Play`

`NEWKEY:Animal Fury ~ Rage Power`

`NEWKEY:Kusari Gusoku`

*** New 6.02.01

Tag Name: RACE:x

Variables Used (x): Text (Old Race Key)

What it does:

- This tag begins a race migration line and is used to identify the old race key as part of the migration to a new race key.
- The `RACE` tag is used in conjunction with the NEWKEY and version tags.

Example:

`RACE:Misspelt Key`

*** New 6.01.03

Tag Name: SOURCE:x

Variables Used (x): Text (Old Source key)

What it does:

- This tag begins a source migration line and is used to identify the old source key as part of the migration to a new source key.
- The `SOURCE` tag is used in conjunction with the NEWKEY and version tags.

Example:

`SOURCE:Paizo - Guide To Pathfinder Society Organised Play 4.0`

### Migration Line Examples

The examples included below are displayed in multiple lines for easy readability. In the actual migration file all tags would be included on the same line and separated by tabs.

Ability Example:

`ABILITY:Special Ability|Animal Fury`

`NEWKEY:Animal Fury ~ Rage Power`

`MAXVER:6.00.01`

`MAXDEVVER:6.01.02`

When any character last saved in v6.00.00 or earlier (or 6.01.01 in the dev line) is loaded if it has a "Special Ability" with the key "Animal Fury" the ability will be mapped to the new key "Animal Fury ~ Rage Power".

Equipment Example:

`EQUIPMENT:Kasari Gusoku`

`NEWKEY:Kusari Gusoku`

`MAXVER:6.1.8`

If a character has the equipment "Kasari Gusoku" when last saved in PCGen 6.1.8 or earlier, it will instead load "Kusari Gusoku" now.

Source Example:

`SOURCE:Paizo - Guide To Pathfinder Society Organised Play 4.0`

`NEWKEY:Guide To Pathfinder Society Organised Play`

`MAXVER:6.0.1`

`MAXDEVVER:6.1.7`

If a character used the source "Paizo - Guide To Pathfinder Society Organised Play 4.0" when last saved in PCGen 6.0.1 or earlier (or 6.1.7 in the dev line) for it will instead load "Guide To Pathfinder Society Organised Play" now.