Crew Advancement

Overview
Crew advancement is the system that allows you to guide the progress of your companion runners by selecting between mutually-exclusive "power-up" options.



Crew advancement was added in Dragonfall: Director's Cut. It is one of the most complex systems in the game, and requires both using the editor and manually editing text files. Only use crew advancement if your campaign needs it. In particular, note that you do not need crew advancement to accomplish the following.
 * Create custom runners
 * Have runners automatically gain better stats and equipment as the game progresses
 * Allow runners to participate in conversations during runs

If you're still interested, read on!

Pre-requisites
This tutorial assumes that you are already comfortable with the following tasks.
 * Creating scaled character sheets
 * Creating scaled equipment sheets
 * Creating character instances (templates)
 * Manually editing game data text files

Reference
If you'd like to walk along with an existing example, here are the relevant files for a sample from Hong Kong. data/chars/crew_gobbet_lv2.ch_sht.txt data/chars/crew_gobbet_lv2_gear.eq_sht.txt data/chars/crew_lv2_gobbet.ch_inst.txt data/chars/gobbet_spiritualist_2.cvf.txt data/chars/gobbet_territoriality_2.cvf.txt data/stories/story.story.txt

Create instanced characters
To start, make the character, equipment, and instance sheets for your crew members. Note that their levels will need to start at 1 even if they will not be recruitable until a higher level. Levels may go as high as 6, but only need to go as high as your campaign supports.

Note: The Hong Kong character sheets define a crew_id field in the character sheet which is not auto-generated in the editor. You may need to define this yourself. For example:

crew_id: "Dorbi"

Enable crew advancement
Select the scene(s) where you want to allow crew advancement. Typically this will be a player hub without any combat, so players can upgrade their crew and shop for equipment at the same time. In the Scene Properties, check the box for "Scene Can Open Team Advancement Window".

In your Content Pack Properties, select "Use Advancement" and define a variable for crew advancement. Hong Kong uses CharacterScaleAmount for this, so I will use that in all of my examples.



The number you assign to this value will be added to step up from the Level 1 sheets. So if you enter 0 here, crew will be at Level 1; if you enter 1, crew will be at Level 2, and so on.

You should also enter CharacterScaleAmount as a global variable. It can be set and queried just like any other global variable. Typically, you will increment it after completing a certain number of runs.

Define your crew
On Content Pack Properties, click Update Crew to view your list of Crew Members.



To add a new crew member, do the following.
 * Click "Plus" next to Crew Members to create a new entry.
 * Edit their Crew Properties to give them an Id, Name, and Title. I like to make the Id and Name both match the crew_id on the character sheet. I believe that "Description Bio" is unused and can be skipped.
 * Add any prerequisites you like to the bottom pane. These can be used to check whether you have met the runner, whether they have been permanently killed, etc. You will usually use global variables here. If you don't list prerequisites here, the runner will always be available.
 * Check "Hide When Unavailable" if you wish to hide the runner from the crew advancement screen. This can be handy for "secret" runners.
 * Keep the default Scale Variable of CharacterScaleAmount.

Note: As of the writing of this tutorial, you must have at least 2 crew members defined in order to use the crew advancement window. However, it's fine for only a single crew member to be visible on the screen.

Set up your crew advancement nodes
Click the "+" icon next to the Node List. Select this character's Level 1 instance template. Repeat this step for all other available levels.

The "Node Properties" will automatically appear for each level of the character. It shouldn't be necessary to edit anything here.

As of this writing, you can't use the Active Variants pane within the editor. Get ready to edit some text files!

Create character variant files
These go in the data/chars directory. The naming convention is charname_trackname_levelnumber.cvf.txt. For example, gobbet_spiritualist_2.cvf.txt

It's easiest to create these by copying and editing the ones in the Hong Kong content pack. Make sure that the crew_id matches the one you defined earlier in the character sheet.

Note that you can have one crew members variant intentionally alter another crew member by matching the Crew Id here to that of the other member. Racter's crew variants uses this method to modify Koschei.

Add variants to the story
Exit the editor. This is an excellent time to make a backup copy of your content pack.

Open stories/story.story.txt in a text editor. Search for crew_list and you should see the crew members you declared earlier and the active_nodes for each crew level.

To add the variants, just insert a crew_variants line into each node. The final block should look like this:

active_nodes { name: "LV2" scale_level: 1 crew_variants: "Gobbet_Territoriality_1" crew_variants: "Gobbet_Spiritualist_1" associated_char_sheet: "Crew_Lv2_Gobbet" node_idx: 1 }

Now, restart the editor and go back to the Update Crew screen. You should see the new variants appear in the middle-right pane.

So, what exactly can I do with crew variants?
Lots of stuff! Check out the Hong Kong source. Here are some examples.

Add items
By far the easiest type of advancement. It looks like this:

equipment_to_add { prefab_name: "TotemRat (Steal)" }

prefab_name just means the item name. These can be existing items like grenades and health kits, or new custom items that you've created. Note that an "item" may actually be a spell or spell-like ability.

Upgrade equipment
Typically, this is done by removing an old item and adding an improved version. It looks like this:

equipment_to_add { prefab_name: "Weapon_RacterDrone_Koschei_Melee 3 (Bleed)" } equipment_to_remove { prefab_name: "Weapon_RacterDrone_Koschei_Melee 3" }

Implant cyberware
Just define the slot to insert and the item to add.

cyberware_left_arm: "(Arm) Shiawase Magnet Arm"

Upgrade stats
As of this writing, this appears to be bugged. Going by the example in Hong Kong, it should look like this:

character_mod { stats { move_speed: 1 }   skills { }   specializations { }   vulnerabilities { } }

If you figure out how to make this work, please edit this wiki with instructions! As a work-around, consider another solution like adding an item with a passive stat bonus.

Adding new item abilities
Examples include Duncan's bean bag attack. The basic idea is that choosing the upgrade adds a tag to the crew member, and then you can check for that tag as a pre-requisite for using the ability. This is the most complicated type of advancement. It's probably easiest to see in example, so check out these files in Hong Kong:

data/items/ar 1 semopal vz88v.item (or any other rifle item) data/modes/single (rifle).mode.txt data/abilities/underslung beanbag (duncan).ab.txt data/crew/duncan_crowdcontrol_1.cvf.txt

All rifles theoretically have the ability to make an "underslung beanbag" attack, but only a properly-upgraded Duncan will have the Duncan_CrowdControl_1 tag present to unlock it.

Similarly, Duncan and Gaichu have abilities unlocked on their armors.

For reference, the code format is:

general_tags_to_add: "CharacterName_PowerName_PlaceOnTrack"

Note the tag here is just a suggested format, based on HBS formatting.

Bugs
The following bugs exist as of version 3.0.8 of Shadowrun Hong Kong. All have been reported to Harebrained Schemes.

Game Freezes when Saving (Fixed)
Fixed in Hong Kong Extended Edition version 3.1.1.

This bug triggers if you perform a manual save (PDA -> Save Game -> Create New Save). The game will not save, and the crew advance icon will disappear. Additionally, your game may enter a strange state where the PDA will not open and your PC will be unable to interact with props and actors.

This bug does not occur for autosaves or quicksaves. It also can be avoided if you first click on another save game in the list before clicking on Create New Save. Nobody knows why.

Stat Upgrades Do Not Work
As noted above, character_mod crew advance choices do nothing. (Including the ones in the official Hong Kong campaign.) This may be because character mods are designed to go on the character instance instead of the character sheet. As a work-around, you can add an item or cyberware with the stat increases you want.

Crew Portraits Do Not Switch
You may notice that, when switching between crew members in the crew advance window (such as by clicking on their portraits or clicking the arrows), the ability choices update but the name and portrait remain the same. This happens if both of the following are true:
 * Level 6 advance options are not visible.
 * Crew members have not selected all available upgrades.

There is no known work-around, other than adding dummy upgrades to fill out the crew upgrade options up to LV6. If you take this approach, note that they need to be VISIBLE as well; picking "hide when unavailable" on the higher-level nodes will still cause this bug to appear.

Crew Prerequisites Update Incorrectly
Editing one character's pre-requisites in the Crew Advance window of the editor will cause ALL crew members' prerequisites to be set to the same thing. To avoid this bug, you must manually edit the crew advance settings in /data/stories/story.story.txt. Search for use_crew_advancement to find the relevant section.

Miscellaneous Notes
Crew advancement choices seem to be "sticky" across multiple launches of the debugger. So if you debug a scene, advance your characters, and then debug that scene again, the advance option will no longer display. You can exit and re-start the game to make it appear again. (Conversely, this feature can be handy if you want to test a piece of combat and don't want to re-upgrade your teammates each time you debug.)

When editing text files outside of the editor, it will sometimes (not always) be necessary to exit and restart the editor and/or game client in order for it to detect the changes. This is a great troubleshooting step if your changes aren't appearing in the game or you notice odd behavior.

If you define  in both a character's character sheet and their instance, then their variant will be applied twice! This means that, for example, if the cvf.txt for this level grants an item, they will receive two copies of that item. That probably isn't what you want. If you notice duplicate items, check and verify that you are only defining  on the character sheets.

Conclusion
The crew system takes a lot of work to set up, but can significantly enhance your campaign. It helps players feel like they're in control of their team, guiding their progress and shaping their combat style to better support their primary character. The concepts can be a little challenging to grasp at first, but once you've figured out how to create one upgradeable crew member, it can be very fast and fun to add more.