Resonant Crystals are miscellaneous objects the player can have in inventory to enhance a Shout as it is used.
By default, Bards College Expansion includes one for each base game and DLC shout, as well as one for each Shout introduced by Bards College Expansion itself. Resonant Crystals can be injected in to support additional Shouts added by mods, in addition, new Resonant Crystals can be injected for Shouts that already have one - allowing the player to pick and choose which enhancement crystal they want to use for each shout!
Effectively, this system will apply perks or magic effects based on what particular Shout words the player has unlocked or uses. As the mod author, you are setting up the records to tell Bards College Expansion which spells/perks to apply based on which Shout records.
The below walkthrough will show you how to create the necessary records.
This tutorial does not cover creating new spells, magic effects, or perks - which might be required to get the enhancement effect you're after for your Shout enhancement. For that, we recommend you try and reverse engineer the spells and effects used in Bards College Expansion for these enhancements, after the tutorial, you will understand how to find those records so you can dissect them.
There are other tutorials online for creating new abilities and magic effects you can find on Youtube or with groups like Arcane University.
The core record that ties everything together is a Misc Object with a script on it that holds references to everything else involved.
Advanced: For those of you looking to add support for mod-added Shouts, without parenting to those other mods, it can absolutely be done by using some of the "File" and "ID" fields explained below!
- In an Object Window, go to Items > MiscItem, and filter for kgcBard_ShoutEnhancement_Template. Duplicate that record and give it a unique Editor ID.
- Open the duplicated record and change the portion of the name after the dash to something describing what your enhancement does. This is for the player to find it in their inventory.
- Double-click the script to open the Properties window. There are a large number of properties here, not all are required, and some are pseudo redundant for special use cases, below will describe each property and how it's used.
- EchoActor - This can point to an actor record that will spawned when the player is challenging an Echo to unlock this (see quest of Songs and Shouts to see how this system plays out in game). This is useful for creating a version of the Echo that can specifically use the Shout this enhancement is for - see the actor records that start with kgcBard_ResonantEchoPedestal for examples.
- EnhancementAbility_L1 - This is meant to be used with Spells of Type Ability. If set, when the player uses the first word of the Shout this spell will be added to the player via Game.GetPlayer().AddSpell. If the player removes the crystal from their inventory, this spell will be removed via Game.GetPlayer().RemoveSpell.
- EnhancementAbility_L2 - Same as L1 version, only will be applied when player uses the second word of the Shout.
- EnhancementAbility_L3 - Same as L1 version, only will be applied when player uses the third word of the Shout.
- [Recommended] EnhancementDescription - This is a spell that applies a magic effect whose only job is to provide a description to the player in the Active Effects section of the Magic menu. It is applied to the player while they carry the Resonant Crystal in their inventory.
-- To create one of these, find one of the Magic Effects with EnhancementDesc in the editor ID from Bards College Expansion and duplicate it. Update the Name and Magic item description fields for your new Enhancement
-- Next find the corresponding Spell with EnhancementDesc in the editor ID from Bards College Expansion and duplicate it. Then update the Name and change the Magic Effect to point to the new one you created.
- EnhancementPerk_L1 - If the player has the first word of this Shout unlocked, they will receive this perk when the Crystal is added to their inventory via Game.GetPlayer().AddPerk, and removed again if the Crystal is removed from their inventory via Game.GetPlayer().RemovePerk.
- EnhancementPerk_L2 - Same as L1 version, only the perk will only be added if player also has the 2nd word unlocked.
- EnhancementPerk_L3 - Same as L1 version, only the perk will only be added if player also has the 3rd word unlocked.
- EnhancementSpell_L1 - This is meant to be used with Spells of Type Spell and Casting Type Fire and Forget. If set, when the player uses the first word of the Shout this spell will be cast on the player via EnhancementSpell.Cast(Game.GetPlayer()).
- EnhancementSpell_L2 - Same as L1 version, only will be cast when player uses the second word of the Shout.
- EnhancementSpell_L3 - Same as L1 version, only will be cast when player uses the third word of the Shout.
- kg_RequirementForAvailability_Optional - This can be pointed at a MiscObject with one of the following scripts attached to establish requirements for when this Crystal becomes available for unlocking. Until the corresponding requirements are met, this Crystal would be treated as if it didn't exist when the player used the pedastal system to enhance a Shout - this can be used to gate things behind a particular quest completion or the player having a particular mod installed.
-- The scripts available are: kg_QuestRequirement, kg_PluginsRequirement, kg_GlobalRequirement, kg_WordRequirement, or kg_RequirementSet (this last one can allow combining several of the other types together by creating multiple misc items with the corresponding scripts and then referencing those misc items in this script's property).
- [Required] ShoutSpell_L1 - This should point to the Spell that represents the first word spell of the Shout. You can find these referenced on the Shout record.
- [Required] ShoutSpell_L2 - This should point to the Spell that represents the second word spell of the Shout. You can find these referenced on the Shout record.
- [Required] ShoutSpell_L3 - This should point to the Spell that represents the third word spell of the Shout. You can find these referenced on the Shout record.
Advanced: Alternatively to the ShoutSpell entries, you can use the ShoutSpellFile and ShoutSpellID fields instead to dynamically load them from a mod. For these you would enter the full filename of the mod for the File, and the decimal version of the Form ID for that spell from that plugin. To get the decimal version, load that mod and look at the Form ID for the corresponding spell, drop the first two characters, and then run the other 6 through an online Hex to Decimal conversion.
- [Required] ShoutWord_L1 - This should point to the Word of Power that represents the first word of the Shout. You can find these referenced on the Shout record.
- [Required] ShoutWord_L2 - This should point to the Word of Power that represents the second word of the Shout. You can find these referenced on the Shout record.
- [Required] ShoutWord_L3 - This should point to the Word of Power that represents the third word of the Shout. You can find these referenced on the Shout record.
Advanced: Just like the ShoutSpell alternative entries described above, the ShoutWords can similarly be loaded dynamically. See info box under the ShoutSpell sections for how to fill these out.
- [Required] TargetShout - The Shout record this enhancement is for.
Advanced: Just like the ShoutWord and ShoutSpell, you can use the filename and decimal form ID instead to load dynamically from a mod. See info box under the ShoutSpell sections for how to fill these out.
- Outside of the Required properties, you'll generally want at least one of the Perk, Spell, or Enhancement sets filled out to act as the actual enhancement to the Shout. Without one of those, this will have no actual effect for the player.
- Once the properties are set, press OK to close the form and save the changes.
Now all that's left is to register it with Bards College Expansion to inject it into the system.
- If this is the first Resonant Crystal you are creating for your plugin, create a new Formlist and add as the first entry: the keyword record "kgcBard_FLID_ShoutEnhancements", otherwise open the formlist you used previously.
- Add your Resonant Crystal misc item record below the "kgcBard_FLID_ShoutEnhancements" keyword in the Formlist.
- Press OK to close the formlist and save the changes.
- If this is the first time you're injecting content to Bards College Expansion for your plugin, find the Misc Item record "kgcBard_AddonConfigTemplate" and duplicate it, then give your duplicate a unique Editor ID. Otherwise, find your AddonConfig record and open it.
- Double-click the properties on the form and add your formlist from step 1 to the MyItems property if it's not already there.
- If you've not created a version global: in an object window, under Miscellaneous > Global, create a new record with the Constant check-box ticked, and the value set to 1.
- If this is your first time creating this record, you'll also need to fill out the sAddonFilename with the file name of your plugin. As well as point the MyVersionNumber property of the script to the global created in step 6.
If you update your Addon in the future, be sure to increase the number of this Global in your Addon so that Bards College Expansion knows to check your MyItems formlists for changes.
- If you don't already have an Addon Quest for this plugin, go to Character > Quest and find the record "kgcBard_BaseContentAddon", duplicate it and give yours a unique Editor ID. Then go to the Scripts tab, open the script properties and change the AddonConfigForm property to point to the misc item you created in step 6, and the gCurrentVersion property to point to the global you created in step 7.
That's it! You're ready to test.
- Load a save with Bards College Expansion completed past at least the quest Of Songs and Shouts and go to Sanctuary.
- Place a Resonant Crystal on the Crystal Stand pedestal and imbue it with a Dragon Soul.
- Equip the Shout the effect you created is for and use it on the Crystal.
- Defeat the Echo that spawns. It's corpse should have the Resonant Crystal expected. If you created a Resonant Crystal for a Shout that has multiple, you will receive one at random from the pool. Repeating the Resonant Crystal process will give a different one each time until the player has seen each at least once.
- After you loot the correct Crystal, check under Magic > Active Effects to confirm your EnhancementDescription is showing up as expected.
You're done!