Editing User:Alistaire/Tutorials/Weapons Guns

In this tutorial we will take a look at a specific item and break down its components, link this knowledge with other items and ultimately learn how to create your own items.<br/>

It requires you to have [[User:Alistaire/Tutorials/Folder structure|set up a folder structure]] for your mod.<br/><br/>

=First things first=
===Introduction===

Create a .xml file in your mod's folder. A recommended location and name for this file, starting from your Rimworld download location and "MOD NAME" replaced with your mod's name, is:<br/>
<pre>../Mods/MOD NAME/Defs/ThingDefs/Weapons_Guns.xml</pre><br/>

The first thing in this file should be the following line:<br/>
<pre><?xml version="1.0" encoding="utf-8"?></pre><br/>

After that, the structure of the file consists of '''<ThingDefs>''' and '''<thingDef>''' tags:<br/>
<pre><ThingDefs>
	<thingDef>
	</thingDef>

	(... more <thingDef>s ...)

	<thingDef>
	</thingDef>
</ThingDefs></pre><br/>

Each '''<thingDef>''' contains something's ''def'' (or definition), which can be used to specify each and every modifiable property for a certain ''thing''.<br/>

===Source===

'''It is important that your file follows this structure to the point where the Weapons_Guns.xml file won't work with multiple <ThingDefs> or <thingDef>s outside of <ThingDefs>:'''<br/>
<pre><?xml version="1.0" encoding="utf-8"?>
<ThingDefs>
	<thingDef>
	</thingDef>

	(... more <thingDef>s ...)

	<thingDef>
	</thingDef>
</ThingDefs></pre><br/>

=BaseGun and BaseBullet parent=
===Introduction===

The first thing in Weapons_Guns.xml is a '''<thingDef>''' with a Name and Abstract ''type'':<br/>
<pre><ThingDef Name="BaseGun" Abstract="True"></pre><br/>

The Name type means the contents of this '''<thingDef>''' can be ''inherited'' by (read: copied by) another '''<thingDef>'''. This way you can write everything you're going to repeat a lot throughout the file in a single location, such as the following:<br/>
<pre><category>Item</category></pre><br/>

Which notifies that this '''<thingDef>''' is of the ''Item'' category, as opposed to those of the ''Building'' category. Because there's a lot of ''tags'' repeated throughout every gun, this greatly compacts the XML file.<br/>
The full BaseGun parent only has to be defined once in a file, and can then be inherited (copied) with:<br/>
<pre><ThingDef ParentName="BaseGun"></pre><br/>

'''<thingDef ParentName="X">''' inherits all contents from '''<thingDef Name="X">'''. It is common practice to copy the vanilla BaseGun parent and paste it on top of a mod's Weapons_Guns.xml file.<br/>
Another parent is BaseBullet which holds every standard bullet's commonly repeated properties, such as the property that bullets don't use hitpoints:<br/>
<pre><useHitPoints>False</useHitPoints></pre><br/>

The last '''<thingDef>''' on top of the file is one with the Name type ''BaseHumanGun'' and the ParentName type ''BaseGun''. It inherits the contents of BaseGun and is inherited by everything with '''<thingDef ParentName="BaseHumanGun">''':<br/>
<pre><ThingDef Name="BaseHumanGun" ParentName="BaseGun" Abstract="True"></pre><br/>

===Breakdown===

Let's start off with the first chunks of this code:<br/>
<pre><ThingDef Name="BaseGun" Abstract="True">
</ThingDef>

<ThingDef Name="BaseHumanGun" ParentName="BaseGun" Abstract="True">
</ThingDef>

<ThingDef Name="BaseBullet" Abstract="True">
</ThingDef></pre>

{| class="wikitable"
!colspan="2"|<ThingDef Name="BaseGun" Abstract="True">
|-
| &lt;ThingDef&gt; || The name of this ''tag'', which is read by the game and processed into a correct definition based on this name.<br/>All tags in ''../Mods/Core/Defs/ThingDefs/'' can be of this type.
|-
| Name="BaseGun" || The Name ''type'' of this tag. This tag is a parent with the Name value of "BaseGun".<br/>If you find the only purpose if a <thingDef> is to be inherited from, make sure is has the ''Abstract="True"'' type.
|-
| Abstract="True" || The [https://en.wikipedia.org/wiki/Abstract_type Abstract type] of this tag is True.<br/>This makes it so that the contents of this tag aren't ''instantiated'', which in practice means the contents of it can only be inherited by other tags and won't be loaded into the game because its only purpose is in inheritance, in being a parent.<br/><br/>"Is the only use of this '''<thingDef>''' to be inherited from? Yes: add Abstract="True". No: don't."
|-
!colspan="2"|<ThingDef Name="BaseHumanGun" ParentName="BaseGun" Abstract="True">
|-
| ParentName="BaseGun" || The ParentName type of this tag. This tag inherits from a parent with the Name value of "BaseGun".<br/>If you find the only purpose if a <thingDef> is to be inherited from, make sure is has the ''Abstract="True"'' type.
|}<br/>

The following tags are relatively straightforward:<br/>
<pre><ThingDef Name="BaseGun" Abstract="True">
	<category>Item</category>
	<altitudeLayer>Item</altitudeLayer>
	<useHitPoints>True</useHitPoints>
	<selectable>True</selectable>
	<alwaysHaulable>True</alwaysHaulable>
	<techLevel>Midworld</techLevel>
	<thingCategories>
		<li>WeaponsRanged</li>
	</thingCategories>
	<smeltProducts>
		<Steel>20</Steel>
	</smeltProducts>
	<statBases>
		<MaxHitPoints>100</MaxHitPoints>
		<Flammability>1.0</Flammability>
		<DeteriorationRate>1</DeteriorationRate>
		<SellPriceFactor>0.5</SellPriceFactor>
	</statBases>
	<graphicData>
		<onGroundRandomRotateAngle>35</onGroundRandomRotateAngle>
	</graphicData>
</ThingDef>

<ThingDef Name="BaseHumanGun" ParentName="BaseGun" Abstract="True">
	<weaponTags>
		<li>Gun</li>
	</weaponTags>
</ThingDef>

<ThingDef Name="BaseBullet" Abstract="True">
	<category>Projectile</category>
	<altitudeLayer>Projectile</altitudeLayer>
	<useHitPoints>False</useHitPoints>
	<label>bullet</label>
	<neverMultiSelect>True</neverMultiSelect>
	<graphicData>
		<shaderType>Transparent</shaderType>
	</graphicData>
</ThingDef></pre>

{| class="wikitable"
!colspan="3"|<thingDef>
|-
! Tag !! Values !! Explanation
|-
| &lt;category&gt; || Item<br/>Projectile || The game uses the contents of this tag to load the rest of this '''<thingDef>''' in a specific way.<br/>All accepted values can be found in [[:Category:Defs]].
|-
| &lt;altitudeLayer&gt; || Item<br/>Projectile || The layer this thing is rendered on. Usually the same value as ''category''.<br/>All accepted values can be found in [[:Category:Defs]].
|-
| &lt;useHitPoints&gt; || ''boolean'' || Whether this thing has hitpoints and can be damaged. Bullets aren't damaged, weapons can deteriorate and use hitpoints for that.
|-
| &lt;selectable&gt; || ''boolean'' || Whether this thing can be selected by clicking on it. Bullets can't be selected, so this value defaults to False.
|-
| &lt;alwaysHaulable&gt; || ''boolean'' || Whether this thing can be hauled by anyone. Bullets can't be hauled, so this value defaults to False.
|-
| &lt;neverMultiSelect&gt; || ''boolean'' || Whether clicking twice on this thing '''won't''' select all similar things on screen. Defaults to False, making multiselecting a default behaviour.
|-
| &lt;techLevel&gt; || Midworld<br/>... || What tech level the weapon represents. Different tech levels make it possible for different enemies to spawn with this weapon.
|-
| &lt;thingCategories&gt; || ''thingCatories'' || Any arbitrary category this weapon represents.<br/>Some pawns can only spawn with weapons in the WeaponsRanged and WeaponsMelee categories.
|-
| &lt;smeltProducts&gt; || &lt;''resource defName''&gt; || This tag has another tag as contents, in this case '''<Steel>'''.<br/>This sub-tag's name is that of a resource's defName (see [[:Category:Defs]]).<br/>The contents of the sub-tag are integers above zero, and represent the amount of some resource gained when this weapon is thrown in an [[Electric smelter]].
|-
!colspan="3"|<statBases>
|-
| &lt;MaxHitPoints&gt; || ''integer'' || The hitpoints maximum this weapon has. Weapons deteriorate over time, slowly dropping from this value to 0 at which point it's destroyed.
|-
| &lt;Flammability&gt; || ''decimal'' || A number denoting how hard it is for fire to jump over to this weapon and how much effect this fire will have on its hitpoints.<br/>A thing with a Flammability of 0.0 won't start burning at all, while one with a Flammability of 1.0 will start burning very quickly.
|-
| &lt;DeteriorationRate&gt; || ''decimal'' || A number denoting how much this weapon deteriorates with every unit of deterioration time.<br/>Things with 0.0 DeteriorationRate won't take any damage over time, ones with a value of 2.0 will deteriorate twice as fast as usual.<br/>A DeteriorationRate of 0.0 won't prevent the weapon from taking fire- or explosion damage.
|-
| &lt;SellPriceFactor&gt; || ''decimal'' || A factor denoting how much traders will pay you less for this weapon than they would sell it for (when negotiating at maximal social skill).<br/>The default value of this factor on weaponry is 0.5.
|-
!colspan="3"|<graphicData>
|-
| &lt;onGroundRandomRotateAngle&gt; || ''degrees'' || How many degrees this thing will randomly be rotated at when placed on the ground. This is usually 35 degrees for guns.
|-
| &lt;shaderType&gt; || ... || How the thing is shaded in-game. The meaning and effect of each shader is slightly different, so;<br/>All accepted values can be found in [[:Category:Defs]].
|}<br/>

And the last part is somewhat more complicated:<br/>
<pre><ThingDef Name="BaseGun" Abstract="True">
	<thingClass>ThingWithComps</thingClass>
	<equipmentType>Primary</equipmentType>
	<pathCost>10</pathCost>
	<drawGUIOverlay>true</drawGUIOverlay>
	<tickerType>Never</tickerType>
	<inspectorTabs>
		<li>ITab_Art</li>
	</inspectorTabs>
	<comps>
		<li>
			<compClass>CompForbiddable</compClass>
		</li>
		<li>
			<compClass>CompEquippable</compClass>
		</li>
		<li>
			<compClass>CompQuality</compClass>
		</li>
		<li>
			<compClass>CompArt</compClass>
			<nameMaker>NamerGun</nameMaker>
			<descriptionMaker>ArtWeaponGun</descriptionMaker>
			<minQualityForArtistic>Excellent</minQualityForArtistic>
		</li>
	</comps>
</ThingDef>

<ThingDef Name="BaseBullet" Abstract="True">
	<thingClass>Bullet</thingClass>
	<tickerType>Normal</tickerType>
</ThingDef></pre>

{| class="wikitable"
!colspan="3"|<thingDef>
|-
! Tag !! Values !! Explanation
|-
| &lt;thingClass&gt; || ThingWithComps<br/>Bullet<br/>... || What C# class to call when doing anything with this thing. Unless you know what you're doing, it's suggested to use the same thingClass similar things use.
|-
| &lt;equipmentType&gt; || Primary<br/>Secondary || Any pawn can have a primary and secondary weapon. Guns and melee weapons are usually primary, while grenades are usually secondary.
|-
| &lt;pathCost&gt; || ''int'' || Subtracted from a [[Floors|floor]]'s movement speed when this thing lies on it.<br/>High values make it harder for pawns to walk past this thing, lower values make it easier.
|-
| &lt;drawGUIOverlay&gt; || ''boolean'' || Whether GUI will show up when you select this thing.
|-
| &lt;tickerType%gt; || Never<br/>Normal<br/>... || Whether this thing has a C# Tick() function; whether something happens to the thing every in-game [[Tick]].
|-
| &lt;inspectorTabs&gt; || ''ITab list'' || A list of ITabs that will show up in the inspector when you select this item. These ITabs are for example the "Bills" buttons (ITab_Bills) and the art description (ITab_Art).
|-
!colspan="3"| ''<comps>'' &lt;li&gt; ''</comps>''
|-
| &lt;compClass&gt; || ... || A C# class describing what should happen when the thing is interacted with in a specific way. This class might need additional tags to work.
|-
| &lt;nameMaker&gt; || ... || The defName of a RulePackDef which describes how this thing will be named under specific conditions, which in turn are described in a C# class provided in <compClass>.
|-
| &lt;descriptionMaker&gt; || ... || Similar to the nameMaker, but for generating a description.
|-
| &lt;minQualityForArtistic&gt; || ... || At what [[Quality]] this thing earns an artistic title and description. This behaviour is unique to the CompArt <compClass>, and it won't work with other classes.
|}

===Source===

It's not recommended to edit these parents. A recent copy of them can be taken from ''../Mods/Core/Defs/ThingDefs/Weapons_Guns.xml'', and the RimWorld834Win version is shown below:<br/>
<pre><ThingDef Name="BaseGun" Abstract="True">
	<category>Item</category>
	<thingClass>ThingWithComps</thingClass>
	<equipmentType>Primary</equipmentType>
	<pathCost>10</pathCost>
	<useHitPoints>True</useHitPoints>
	<selectable>True</selectable>
	<graphicData>
		<onGroundRandomRotateAngle>35</onGroundRandomRotateAngle>
	</graphicData>
	<drawGUIOverlay>true</drawGUIOverlay>
	<statBases>
		<MaxHitPoints>100</MaxHitPoints>
		<Flammability>1.0</Flammability>
		<DeteriorationRate>1</DeteriorationRate>
		<SellPriceFactor>0.5</SellPriceFactor>
	</statBases>
	<altitudeLayer>Item</altitudeLayer>
	<alwaysHaulable>True</alwaysHaulable>
	<tickerType>Never</tickerType>
	<techLevel>Midworld</techLevel>
	<thingCategories>
		<li>WeaponsRanged</li>
	</thingCategories>
	<inspectorTabs>
		<li>ITab_Art</li>
	</inspectorTabs>
	<comps>
		<li>
			<compClass>CompForbiddable</compClass>
		</li>
		<li>
			<compClass>CompEquippable</compClass>
		</li>
		<li>
			<compClass>CompQuality</compClass>
		</li>
		<li>
			<compClass>CompArt</compClass>
			<nameMaker>NamerGun</nameMaker>
			<descriptionMaker>ArtWeaponGun</descriptionMaker>
			<minQualityForArtistic>Excellent</minQualityForArtistic>
		</li>
	</comps>
	<smeltProducts>
		<Steel>20</Steel>
	</smeltProducts>
</ThingDef>


<ThingDef Name="BaseHumanGun" ParentName="BaseGun" Abstract="True">
	<weaponTags>
		<li>Gun</li>
	</weaponTags>
</ThingDef>


<ThingDef Name="BaseBullet" Abstract="True">
	<category>Projectile</category>
	<tickerType>Normal</tickerType>
	<altitudeLayer>Projectile</altitudeLayer>
	<thingClass>Bullet</thingClass>
	<label>bullet</label>
	<useHitPoints>False</useHitPoints>
	<neverMultiSelect>True</neverMultiSelect>
	<graphicData>
		<shaderType>Transparent</shaderType>
	</graphicData>
</ThingDef></pre><br/>

=Bullet_Pistol=



=Gun_Pistol=


[[Category:Modding tutorials]]