User:BinaryDoubts/RelicTutorial: Difference between revisions

(3 intermediate revisions by the same user not shown)

Line 2:

== Weapon Types ==

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="~~LongBlades~~"</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.

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.

== Custom Weapons ==

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 ~~LongBlade~~ or ~~Cudgel~~, adding it in as a relic option is simple, see below.

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

=== Adding Weapon Variants as Relics ===

Line 21:

</syntaxhighlight>

~~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~~>~~. Replace CUSTOMBLUEPRINTNAME with your new weapon's blueprint name (e.g., MyMod_MyCoolAxe3).~~

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):

</group>

</population>

</syntaxhighlight>

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 the ~~object~~ Blueprint ~~tag~~.

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>.

Replace CUSTOMBLUEPRINTNAME with your new weapon's blueprint name (e.g., MyMod_MyCoolAxe3). Note that even though the skill name is plural (Axes, Cudgels), the population name is singular (Axe, Cudgel).

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>.

== Getting Started ==

Line 35:

Line 46:

* New weapon name synonyms added to <code>HistorySpce.json</code> so the relic generator can give your relic weapon an appropriate name

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, ~~I recommend~~ reading through <code>RelicGenerator.cs</code> via ILSpy.

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.

== XML Edits ==

Line 71:

Line 82:

</syntaxhighlight>

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.

==== Relic Axe Population Names by Tier ====

As an example to use in your own mod, here's the list of relic populations for axes. Replace the word "Axe" with your own mod's weapon type.

# BaseRelic_Axe1 / BaseRelicAxe1th

# BaseRelic_Axe2 / BaseRelicAxe2th

# BaseRelic_Axe3 / BaseRelicAxe3th

# BaseRelic_Axe4 / BaseRelicAxe4th

# BaseRelic_Axe5 / BaseRelicAxe5th

# BaseRelic_Axe6 / BaseRelicAxe6th

# BaseRelic_Axe7 / BaseRelicAxe7th

# BaseRelic_Axe8 / BaseRelicAxe8th

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).

=== Relics.xml ===

Line 164:

Line 188:

}

</syntaxhighlight>

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, ~~although~~ most base-game items only have 4.

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.

== Testing ==

@@ Line 2: / Line 2: @@
 == Weapon Types ==
-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="LongBlades"</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.
+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.
 == Custom Weapons ==
 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 LongBlade or Cudgel, adding it in as a relic option is simple, see below.
+* If the weapon uses an existing weapon skill, such as LongBlades or Cudgels, adding it in as a relic option is simple, see below.
 === Adding Weapon Variants as Relics ===
@@ Line 21: / Line 21: @@
 </syntaxhighlight>
-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>. Replace CUSTOMBLUEPRINTNAME with your new weapon's blueprint name (e.g., MyMod_MyCoolAxe3).
+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):
+<syntaxhighlight lang="xml">
+<population Name="BaseRelic_WEAPONCLASS+TIERth" Load="Merge">
+    <group Name="Blueprint" Load="Merge">
+        <object Blueprint="CUSTOMBLUEPRINTNAME" />
+    </group>
+</population>
+</syntaxhighlight>
-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 the object Blueprint tag.
+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>.
+Replace CUSTOMBLUEPRINTNAME with your new weapon's blueprint name (e.g., MyMod_MyCoolAxe3). Note that even though the skill name is plural (Axes, Cudgels), the population name is singular (Axe, Cudgel).
+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>.
 == Getting Started ==
@@ Line 35: / Line 46: @@
 * New weapon name synonyms added to <code>HistorySpce.json</code> so the relic generator can give your relic weapon an appropriate name
-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, I recommend reading through <code>RelicGenerator.cs</code> via ILSpy.
+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.
 == XML Edits ==
@@ Line 71: / Line 82: @@
 </syntaxhighlight>
 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.
+==== Relic Axe Population Names by Tier ====
+As an example to use in your own mod, here's the list of relic populations for axes. Replace the word "Axe" with your own mod's weapon type.
+# BaseRelic_Axe1 / BaseRelicAxe1th
+# BaseRelic_Axe2 / BaseRelicAxe2th
+# BaseRelic_Axe3 / BaseRelicAxe3th
+# BaseRelic_Axe4 / BaseRelicAxe4th
+# BaseRelic_Axe5 / BaseRelicAxe5th
+# BaseRelic_Axe6 / BaseRelicAxe6th
+# BaseRelic_Axe7 / BaseRelicAxe7th
+# BaseRelic_Axe8 / BaseRelicAxe8th
+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).
 === Relics.xml ===
@@ Line 164: / Line 188: @@
 }
 </syntaxhighlight>
-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, although most base-game items only have 4.
+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.
 == Testing ==