Difference between revisions of "User:Dninemfive"

From RimWorld Wiki
Jump to navigation Jump to search
m (it truly is a classic)
(IfModLoaded -> IfModActive)
 
(18 intermediate revisions by 3 users not shown)
Line 5: Line 5:
 
= Sandbox =
 
= Sandbox =
  
== Plague Gun (1.1)/Introduction ==
+
== Introduction to reading Def classes ==
 +
This article is intended for XML modders who don't want to work with C# (even though it's [[Plague Gun (1.1)|much less imposing than you think]]) but want to know what exactly they can write in their defs.
  
This tutorial is a rewrite of the [[Plague Gun/Introduction|original]] by Jecrell ({{LudeonThread|33219}}), updated to 1.1 by dninemfive.
+
=== Definitions ===
 +
'''Fields''' are variables in C# class defintions defined at the top of classes (when decompiled). For example, <source lang="csharp">
 +
    public class ExampleDef : Def {
 +
    public bool exampleBool = true;
 +
    public int exampleInteger = 1;
 +
    public float exampleFloat = 1.2f;
 +
    public bool exampleNonInitializedField;
 +
    public RaceProperties exampleClass;
 +
}
 +
</source>
  
=== Introduction ===
+
'''Nodes''' are XML entries, for example <source lang="xml">
 +
<ExampleDef ExampleAnnotation="ExampleValue">
 +
    <exampleBool>true</exampleBool?
 +
    <exampleInteger>1</exampleInteger>
 +
    <exampleFloat>1.2</exampleFloat>
 +
    <exampleNonInitializedField>false</exampleNonInitializedField>
 +
    <exampleClass>
 +
        <intelligence>Animal</intelligence>
 +
        <fleshType>Mechanoid</fleshType>
 +
        <hasGenders>false</hasGenders>
 +
    </exampleClass>
 +
</ExampleDef>
 +
</source>
  
In this tutorial we will be using most of the tools available to a Rimworld modder to create a custom weapon, known as the Plague Gun.
+
== Royalty compatibility ==
 +
After the release of Royalty, mods are governed by rules 13b and c of the [https://ludeon.com/forums/index.php?topic=40838.0 Ludeon community rules]. Unfortunately, these are inconsistently applied and end up being vaguer than intended, but a good TL;DR to follow would be:
 +
# Don't use any code flagged as Royalty only. They will throw errors when loaded for people without Royalty, so these are easy to tell.
 +
#* The page lists explicit exceptions; at the time of writing, only gendered apparel and <code>Sketch</code>es are exempt.
 +
# Avoid using features added in 1.1 or later. Unfortunately, not all Royalty-specific code is flagged and it's ambiguous whether some features are permitted.
 +
# Avoid making anything included in Royalty, broadly defined. Another unfortunate ambiguity is the nuance in this rule - it's currently unclear whether some Royalty features, like shield projectors, count as "royalty features" for this purpose as old mods which included them have not been banned but no new ones have yet been made.
 +
# If in doubt, set your mod to require Royalty to install on Steam, and you'll be fine.
 +
=== MayRequire ===
 +
You can use the <code>MayRequire</code> annotation on XML nodes to disable Royalty-specific features when Royalty is not installed.
 +
=== ModLister.RoyaltyInstalled ===
 +
In C#, the canonical check for whether Royalty is installed is <code>ModLister.RoyaltyInstalled</code>. Notably, this check whether the Steam user ''owns'' Royalty, rather than whether it's enabled in the load order.
 +
=== IfModActive===
 +
You can use the <code>IfModActive</code> and <code>IfModNotActive</code> attributes in <code>LoadFolders.xml</code> to conditionally load defs, treating Royalty as a mod.
 +
<source lang="xml">
 +
<loadFolders>
 +
  <default>
 +
    <li>/</li>
 +
    <li IfModActive="Royalty">RoyaltyDefs</li>
 +
  </default>
 +
</loadFolders>
 +
</source>
 +
=== Other Options ===
 +
If you set your mod to require [https://github.com/dninemfive/d9framework D9 Framework], you can use <code>PatchOperationFindPackage</code> (with the packageId <code>Ludeon.RimWorld.Royalty</code>) or <code>PatchOperationRoyaltyInstalled</code> to check whether Royalty is installed, with the former checking whether it's enabled and the latter checking if the user owns it. Using the vanilla <code>PatchOperationFindMod</code> would not be sufficient because it would be enabled if any local mod was called Royalty.
  
This weapon will, when its shots hit a living target, have a chance to apply the Plague hediff ("health difference") to that target.
+
== Framework Mods ==
 +
''intended to be a comprehensive list of mods which add features for XML users''
 +
* [O21] Toolbox
 +
* Advanced Animal Frameworks
 +
* BiomesKit
 +
* D9 Framework
 +
* HugsLib ''(I think)''
 +
* JecsTools
 +
* OgsTools
 +
* Universal Fermenter
  
To do this, we will create XML `ThingDefs` for the gun and projectile, create a C# assembly which determines what happens when the projectile hits a target, and link that behavior back to the XML.
+
== Version Control Intro ==
  
This tutorial will assume a basic familiarity with XML and C# syntax. It should be simple enough to follow if you're only a beginner.  
+
An introduction to using Github for version control, with an eye toward Rimworld modding. Will go through my particular setup, and various tips and tricks, like:
 +
* Having a separate dev folder from the Rimworld mods folder
 +
* Build events copying from the dev folder into the build folder
 +
* .gitignore settings
 +
&c
  
If you have no XML or C# experience, there are good tutorials for XML [https://www.w3schools.com/xml/ here] and C# [https://www.learncs.org/ here].
+
== Example Comp Project ==
  
=== The Completed Mod ===
+
This project will teach players how to use <code>ThingComp</code>s, load textures in C#, and make gizmos.
  
TODO: fork and update the repo, link here.
+
== Introduction to core mods ==
  
=== See Also ===
+
This project will teach players how to use basic Harmony patches and demonstrate the use of <code>MapComponent</code>s (or maybe game/world ones, idk)
 
 
Will be filled in once I have separate pages for these.
 
 
 
== Plague Gun (1.1)/Required Items ==
 
 
 
{| class="wikitable"
 
|-
 
| [https://notepad-plus-plus.org/ Notepad++] or [https://atom.io Atom] or{{br}}[https://www.sublimetext.com/ Sublimetext] or [https://code.visualstudio.com/ VSCode] || Use any text editor that allows you to edit XML files and use "Find in Files" for referencing.
 
|-
 
| [https://visualstudio.microsoft.com/vs/community/ Visual Studio Community] || Use this or any other C# compiler to turn scripts into .dll files that RimWorld can use.
 
|-
 
| [https://github.com/0xd4d/dnSpy/releases dnSpy] or [https://github.com/icsharpcode/ILSpy/releases ILSpy]|| This is for referencing the game's decompiled C# scripts.
 
|}
 
 
 
=== More In-Depth ===
 
 
 
For more details, see [[Modding Tutorials/Recommended software|here]].
 
 
 
=== See Also ===
 
 
 
Will be filled in once I have separate pages for these.
 

Latest revision as of 07:51, 17 November 2021

Hello! I'm a modder who's trying to clean up the modding tutorials pages, which are quite out-of-date. So far, I've rewritten the classic Plague Gun tutorial.

If you've been helped by my contributions on this site please check out my mods on Github and Steam.

Sandbox[edit]

Introduction to reading Def classes[edit]

This article is intended for XML modders who don't want to work with C# (even though it's much less imposing than you think) but want to know what exactly they can write in their defs.

Definitions[edit]

Fields are variables in C# class defintions defined at the top of classes (when decompiled). For example,

    public class ExampleDef : Def {
    public bool exampleBool = true;
    public int exampleInteger = 1;
    public float exampleFloat = 1.2f;
    public bool exampleNonInitializedField;
    public RaceProperties exampleClass;
}

Nodes are XML entries, for example

<ExampleDef ExampleAnnotation="ExampleValue">
    <exampleBool>true</exampleBool?
    <exampleInteger>1</exampleInteger>
    <exampleFloat>1.2</exampleFloat>
    <exampleNonInitializedField>false</exampleNonInitializedField>
    <exampleClass>
        <intelligence>Animal</intelligence>
        <fleshType>Mechanoid</fleshType>
        <hasGenders>false</hasGenders>
    </exampleClass>
</ExampleDef>

Royalty compatibility[edit]

After the release of Royalty, mods are governed by rules 13b and c of the Ludeon community rules. Unfortunately, these are inconsistently applied and end up being vaguer than intended, but a good TL;DR to follow would be:

  1. Don't use any code flagged as Royalty only. They will throw errors when loaded for people without Royalty, so these are easy to tell.
    • The page lists explicit exceptions; at the time of writing, only gendered apparel and Sketches are exempt.
  2. Avoid using features added in 1.1 or later. Unfortunately, not all Royalty-specific code is flagged and it's ambiguous whether some features are permitted.
  3. Avoid making anything included in Royalty, broadly defined. Another unfortunate ambiguity is the nuance in this rule - it's currently unclear whether some Royalty features, like shield projectors, count as "royalty features" for this purpose as old mods which included them have not been banned but no new ones have yet been made.
  4. If in doubt, set your mod to require Royalty to install on Steam, and you'll be fine.

MayRequire[edit]

You can use the MayRequire annotation on XML nodes to disable Royalty-specific features when Royalty is not installed.

ModLister.RoyaltyInstalled[edit]

In C#, the canonical check for whether Royalty is installed is ModLister.RoyaltyInstalled. Notably, this check whether the Steam user owns Royalty, rather than whether it's enabled in the load order.

IfModActive[edit]

You can use the IfModActive and IfModNotActive attributes in LoadFolders.xml to conditionally load defs, treating Royalty as a mod.

<loadFolders>
  <default>
    <li>/</li>
    <li IfModActive="Royalty">RoyaltyDefs</li>
  </default>
</loadFolders>

Other Options[edit]

If you set your mod to require D9 Framework, you can use PatchOperationFindPackage (with the packageId Ludeon.RimWorld.Royalty) or PatchOperationRoyaltyInstalled to check whether Royalty is installed, with the former checking whether it's enabled and the latter checking if the user owns it. Using the vanilla PatchOperationFindMod would not be sufficient because it would be enabled if any local mod was called Royalty.

Framework Mods[edit]

intended to be a comprehensive list of mods which add features for XML users

  • [O21] Toolbox
  • Advanced Animal Frameworks
  • BiomesKit
  • D9 Framework
  • HugsLib (I think)
  • JecsTools
  • OgsTools
  • Universal Fermenter

Version Control Intro[edit]

An introduction to using Github for version control, with an eye toward Rimworld modding. Will go through my particular setup, and various tips and tricks, like:

  • Having a separate dev folder from the Rimworld mods folder
  • Build events copying from the dev folder into the build folder
  • .gitignore settings

&c

Example Comp Project[edit]

This project will teach players how to use ThingComps, load textures in C#, and make gizmos.

Introduction to core mods[edit]

This project will teach players how to use basic Harmony patches and demonstrate the use of MapComponents (or maybe game/world ones, idk)