User:BinaryDoubts/RelicTutorial: Difference between revisions

This tutorial covers adding new weapon types to the pool of options for relics, allowing them to spawn as historical relics with boosted stats and special relic-only traits.

 

Weapon objects in Caves of Qud are classified by the skill required to use them. For example, all sword-ish weapon blueprints have <code>Skill="LongBlade"</code> in their <code>MeleeWeapon</code> part. The game checks the weapon's skill (<code>WeaponObject.Skill</code>) to detect if, say, your wielded weapon is a long blade and can be used to trigger Lunge. As a shorthand, whenever this tutorial refers to a weapon's "type," it's referring to the skill required to wield it.

 

The process to add custom weapons as relics depends on what kind of weapon you're adding.

* If the weapon uses a new weapon skill added for a mod (such as Spears, GreatKatanas, FireMagicTomes, etc.), the process is more difficult (but still manageable). Begin at [[#Getting Started]].

* If the weapon uses an existing weapon skill, such as LongBlades or Cudgels, adding it in as a relic option is simple, see below.

 

If the new weapon you've added in <code>ObjectBlueprints.xml</code> uses an existing (base-game) skill, you can insert it into the relic drop tables as an alternative to the default option (which is generally just the most basic form of the weapon for each tier, such as LongSword2, LongSword3, LongSword4, etc.).

 

 

If your weapon variant is two-handed, add this code instead (note the added <code>th</code> at the end of the population's Name):

 

Replace WEAPONCLASS with your weapon's type: LongBlade, ShortBlade, Cudgel, or Axe, and tier with a number from 1-8. For example, if you wanted to add your new weapon as a tier 3 axe relic: <code>Name="BaseRelic_Axe3"</code>. If that new axe was two-handed, you'd instead use <code>Name="BaseRelic_Axe3th"</code>.

 

 

By default, this will give your addition and the original blueprint an equal chance of being chosen when a relic of that tier is generated. If you want it to be more likely, add <code>Weight="2"</code> to your weapon's object tag. If you'd rather entirely replace the standard relic with your own item, remove the <code>Load="Merge"</code> from <code><group Name="Blueprint"></code>.

This tutorial will use the example of a mod called <code>BigSwords</code> that adds the <code>GreatKatana</code> weapon type. Replace <code>BigSwords_GreatKatana</code> with the name used by your new weapon type/skill when copy+pasting code from this page. Finally, if you'd like to understand the relic generation system on a deeper level, reading through <code>RelicGenerator.cs</code> via ILSpy can help explain how the system works on the underlying level.

Relics can spawn from tiers 1-8, so you'll need 8 versions of the table(s), one for each tier. Base (bronze) items cannot spawn as relics so there's no need to create a <code>BaseRelic_BigSwords_GreatKatana</code> (with no number, representing tier 0) population table. Note that the relic population names must follow the format laid out above, but the individual object blueprints can be named however you'd like.

 

 

Note that there isn't a two-handed variant of the tier 1 axe. The <code>BaseRelic_Axe1th</code> population exists to fit the pattern the relic generator uses, but the blueprint it contains is the same 1-handed axe used by the population <code>BaseRelic_Axe1</code>. You can emulate this pattern in your own mod or ignore it and use weights within a single <code>BaseRelic_YourWeaponName1</code> population table to create the same effect (but with controllable odds).

If you don't already have it, create a new XML file in your mod's folder named <code>Relics.xml</code>. Set up a file that looks like this:

<code>GetSubtype</code> is a simple method that boils down multiple item types to their overarching category. ShortBlades, LongBlades, Cudgels, and Axes all return "weapon" as their subtype, while Pistols and Rifles return "ranged." All that's needed for this patch is to check if the provided type string matches our new weapon type, and if so, return "weapon" instead of "curio" (the default result if <code>GetSubtype</code> can't figure out the type). Add a new block of code to your HarmonyPatches namespace:

The last step is modifying the game's HistorySpice.json file so that it knows how to name your relic. You can write your own methods to do this, or (recommended) use Tyrir's [https://steamcommunity.com/workshop/filedetails/?id=3396620647 Hot 'n Spicy History mod] to achieve the same goal. This tutorial will assume you're using the mod, so make sure you're subscribed to it, that it's enabled in-game, and that it's set as a dependency if your mod is published to the Workshop.

When <code>RelicGenerator</code> tries to name a relic, it picks a random name that corresponds to the relic's type from the <code>itemTypes</code> table. You can have any number of synonyms in the list, though most base-game items only have 4-5 options.