Upgrade Trainworks Tutorial - brandonandzeus/Trainworks2 GitHub Wiki

Switching from Trainworks V1 to Trainworks V2.

If you already have code written for Trainworks prior to November 2023 or already have a mod written for Monster Train using Trainworks Modding Tools this page is for you.

Why switch?

There have been a number of improvements (speed and design-wise) and bug fixes to the modding framework.

  • Support for many things added in the DLC that weren't included before. Unit synthesis builder objects are now a part of CharacterDataBuilder.
  • Various Bug fixes for known issues especially with custom clans and enhancers. See the following issues from the original repo:
  • New builders are outlined below.

However, the upgrade is opt-in, meaning you will have to switch the following using statements in your code to use the newer Builders. This is done to not change the behavior of existing mods. For instance, some mods may have depended on certain behavior or attempted to fix bugs in the framework within their own mod, so to not break existing mods the newer code is opt-in.

using Trainworks.Builders > using Trainworks.BuildersV2
using Trainworks.Constants > using Trainworks.ConstantsV2

However, this isn't a drop-in replacement. API changes will break existing code, hence the newer namespaces. Most of the breaking changes were done to keep the framework consistent or prevent logic errors in code. Some Builders may require a unique ID where it did not previously (to generate localization keys). Here I will attempt to list all of the incompatible changes or renamed properties or inform of new properties to make the code more concise. Bolded changes are potentially breaking API changes.

CardDataBuilder

  • Removed Property LinkedClass. Use ClanID instead. Having both was a confusing interface to indicate whether or not the card was clanless.
  • Removed Property FallbackData. Unnecessary this should set itself.
  • Removed functions SetClan (Use ClanID property instead) and AddToCardPool (use CardPoolIDs property instead).
  • Added InitialKeyboardTarget and RequireDLC.
  • New property StartingUpgradeBuilders which is a convenience builder for StartingUpgrades.

CardEffectDataBuilder

  • Property EffectStateName is no longer settable. Use Property EffectStateType instead. This is to prevent bugs like this from occurring. The framework will now compute the appropriate class name from the Type info passed in. (Essentially, Vanilla Effects will output the class name, and Custom Effects will output the fully qualified class name with assembly info).
  • Property ParamStatusEffects is no longer an Array. It is now a List. Setting the parameter is now less typing. That is, instead of 
    ParamStatusEffects = new StatusEffectStackData[] {
   new StatusEffectStackData {...}
}
    The code is now 
    ParamStatusEffects = {
    new StatusEffectStackData {...}
}
  • Property AdditionalTooltips is no longer an Array. It too is now a list.
  • Property ParamSubtype now defaults to Subtype_None. This was actually a required Param for many CardEffects to work and can not default to null or empty string.
  • Property TargetCharacterSubtype also defaults to Subtype_None. for the same reasons above.
  • Removed function AddStatusEffect You can simply append the status effect to the end of the list.
  • New Property ParamCardUpgradeDataBuilder Convenience builder for ParamCardUpgradeData. If this is set, then it overrides the value of ParamCardUpgradeData
  • New Property ParamCharacterDataBuilder for the same reasons as above.
  • Added Property ParamAdditionalCharacterData, ParamCharacterDataPool, ParamCharacterDataPoolBuilder.

CardPoolDataBuilder

  • No changes

CardTraitDataBuilder

  • Property TraitStateName is no longer settable. Use TraitStateType instead. See: EffectStateName in CardEffectDataBuilder for details why.
  • Property ParamStatusEffects is a list now. See CardEffectDataBuilder for the reason.
  • Fixed Bug CardTraits previously had their ParamCardData set to the CardData of where the trait was applied. This is a bug in Trainworks V1 that prevents Custom Cards with Traits that do something with ParamCardData not to work as expected.
  • Property ParamSubtype defaults to Subtype_None.
  • Property ParamTeamType defaults to Team.Type.Heroes.
  • Property ParamFloat defaults to 1f.
  • Added property ParamCardUpgradeData and convenience builder ParamCardUpgradeDataBuilder.
  • Added property TraitIsRemovable.
  • Added property StackMode.

CardTriggerEffectDataBuilder

  • New required Property TriggerID. This must be set to ensure unique localization keys are generated. If this is not set, an exception will be thrown. This is to prevent bugs like this from happening.
  • Added convenience static function MakeCardTrigger.

CardUpgradeDataBuilder

  • New required Property UpgradeID.. Previously UpgradeTitle was required; it no longer is since that property is not always required.
  • Renamed UpgradeIconPath to AssetPath. This keeps consistency with other Builders.
  • Added new properties IsUnique, LickedPactDuplicateRarity, SourceSynthesisUnit, and IsUnitSynthesisUpgrade

IMPORTANT When migrating set UpgradeID to what UpgradeTitleKey was, add this code after you've built the upgrade. GameDataMigrationManager.MigrateOldCardUpgradeID(UpgradeID, builtCardUpgrade.GetID()) This will preserve runs from the older CardUpgradeDataBuilder

CardUpgradeMaskDataBuilder

  • New required Property CardUpgradeMaskID. Not a hard requirement to set this and will throw a warning if unset, but technically the object should have a name.

CardUpgradeTreeDataBuilder

  • No major changes

ChampionCardDataBuilder

  • Property StarterCardData renamed to StarterCardID. This is to keep properties across builders consistent.

CharacterDataBuilder

  • Property StartingStatusEffects is now a list.
  • Removed Property FallbackData.
  • Added Property CharacterChatterDataBuilder.
  • Added new properties BlockVisualSizeIncrease, BypassPactCrystalsUpgradeDataList, PactCrystalsRequiredCount, PactCrystalsVariantData, RemoveTriggersOnRelentlessChange, ValidBossAttackPhase,

CharacterChatterDataBuilder

  • NEW thanks to ThreeFishes for the original implementation that was adopted.

CharacterTriggerDataBuilder

  • New required Property TriggerID. This must be set to ensure unique localization keys are generated. If this is not set, an exception will be thrown. This is to prevent bugs like this from happening.

ClassDataBuilder

  • Removed Properties MainClassStartingCards and SubClassStartingCards`. These are unused in the Builder and in the Monster Train source code.
  • Added new properties CorruptionEnabled, StarterCardUpgrade, StarterCardUpgradeBuilder, RandomDraftEnhancerPool, RandomDraftEnhancerPoolBuilder.

CollectableRelicDataBuilder

  • Removed Property LinkedClass Use ClanID instead. Having both was a confusing interface to indicate whether or not the relic was clanless.
  • Added new properties IgnoreForNoRelicAchievement, DivineVariant, RelicLoreTooltipStyle, and RequiredDLC.

DraftRewardDataBuilder

  • Renamed _RewardTitleKey, _RewardDescriptionKey, and _RewardSpritePath to NameKey, DescriptionKey, and AssetPath respectively. This is to keep consistency among other Builders.
  • Removed SaveManager property.
  • Removed the leading _ in property names ShowCancelOverride, ShowRewardFlowInEvent, CollectSFXCuename, and MerchantServiceIndex.
  • NameKey and DescriptionKey are now set automatically by DraftRewardID.
  • Added new property Crystals.
  • It is not required to call BuildAndRegister for this builder. Calling Build() will automatically register the DraftRewardData. This is to allow ease of use in using this builder within other builders.

EnhancerDataBuilder

  • Bug Fix Use CustomEnhancerManager to query for Enhancers. The new class uses this Manager to register Enhancers. The older Builder/Manager has a bug, in which, the EnhancerData wasn't added to the GameData, causing Spell/Unit Merchants to fail to load and showing the fallback merchant when the game was reloaded.
  • Renamed ID to EnhancerID. This is to keep things consistent among builders. EnhancerID now sets NameKey and DescriptionKey.
  • Name and Description are no longer set by default.
  • Added UnlockLevel
  • Added UpgradeBuilder for convenience if set overrides Upgrade.

EnhancerPoolBuilder

  • NEW

MutatorDataBuilder

  • NEW

RandomChampionPoolBuilder

  • NEW

RelicEffectConditionBuilder

  • ParamSubtype now defaults to Subtype_None.

RelicEffectDataBuilder

  • Property RelicEffectClassName is no longer settable. Use RelicEffectClassType instead. See: EffectStateName in CardEffectDataBuilder for details on why.
  • Properties TooltipBodyKey and TooltipTitleKey are no longer set by default. These shouldn't be too commonly used, and using the Class Name is a bad identifier to use since the strings can be much longer than just the class name. Again See: EffectStateName in CardEffectDataBuilder
  • AdditionalTooltips is now a List instead of an Array. This is to keep consistency with CardEffectDataBuilder.
  • ParamCharacterSubtype now defaults to Subtype_None.
  • Added CardTriggers.
  • Added ParamCardUpgradeDataBuilder.
  • Added ParamCardFilterBuilder.
  • Added ParamCardPoolBuilder
  • Added ParamEnhancerPool and ParamEnhancerPoolBuilder.
  • Added ParamRandomChampionPool and convenience builder ParamRandomChampionPoolBuilder.
  • Added ExcludedTraitBuilders convenience builder for ExcludedTraits.

RewardNodeDataBuilder

  • Renamed TooltipTitleKey and TooltipBodyKey to NameKey and DescriptionKey respectively.
  • Property RewardNodeID now sets NameKey and DescriptionKey.
  • Renamed RequiredClass to RequiredClassID this is now the ID of the Clan. This was done to keep consistency across Builders.
  • Added UseFormattedOverrideTooltipTitle, DlcHellhorgedCrystalsCost, and RequiredDLC

RoomModifierDataBuilder

  • New Soft-Required Property RoomModifierID. Previously RoomModifierClassName was used to set the localization keys. Using the class name to generate the key isn't a good design since it may be a long string especially if the RoomModifier is a custom class. If unset a warning message is printed.
  • Properties ExtraTooltipBodyKey and ExtraTooltipTitleKey are no longer set by default. This should fix this issue
  • ParamStatusEffects is now a list rather than an Array.
  • Removed Property Icon. Please use Property IconPath instead. This change was made to keep consistency with other Builders.
  • Removed function AddStartingStatusEffect. Just append to ParamStatusEffects instead.
  • ParamSubtype now defaults to Subtype_None.
  • Added ParamCardUpgradeData and ParamCardUpgradeDataBuilder.

ScenarioDataBuilder (and dependencies)

  • NEW

SinsDataBuilder

  • NEW

SpChallengeDataBuilder

  • NEW

StatusEffectDataBuilder

  • StatusEffectStateName is no longer settable. See the notes of EffectStateName in CardEffectDataBuilder
  • Renamed StatusId to StatusID. This is to keep consistency with other Builders.
  • Setting Property StatusID will now generate a localization key in StatusIDKey.
  • Added Properties Name and Description.
  • Added Property AdditionalTriggerStages.
  • Added Properties RemoveAtEndOfTurnIfTriggered, ShowOnPyreHeart, and VFXDisplayType.

SubtypeDataBuilder

  • Removed the leading '_' from all Properties.
  • Added property IsPyre.

TrialDataBuilder

  • NEW