XML Auto-Documentation

Started by milon, July 15, 2016, 02:55:38 PM

Previous topic - Next topic

Dingo

I didn't even know this existed. I'll spend some free time trying to make XMLs for it this week.

Nimrod

Quote from: Dingo on September 27, 2016, 12:24:59 AM
I didn't even know this existed. I'll spend some free time trying to make XMLs for it this week.

lol, I found yours and then saw the sticky one :)

Anyway, good work and thank you!

jecrell

So the HeDiffDef has no children? Is that right?
...Psst. Still there? If you'd like to support
me and my works, do check out my Patreon.
Someday, I could work for RimWorld full time!

https://www.patreon.com/jecrell

kaptain_kavern

I'm not sure about the precise english terms so I may be wrong, but doesn't all the ones listed under HediffDef<defName> are Hediffdef's children ?

milon

Everything under HediffDef<defName> is a child or property of a <defName> which is itself a child of <HediffDef>.  I track <defName> and <li> *with* their parents because they are the most common tags and show up EVERYWHERE.  It would be a nightmare to read otherwise.  (I'm not convinced this is the best way to represent it.  I'm open to suggestions for improvement!)

milon


milon

Updated to the official Alpha 16 (0.16.1393 rev540)

jjcm04

I like this, but I am a real noob when it comes to xml. I did read on what Xml is and a tutorial on the basics, but I don't understand like workerclass ? what is it and can I make my own. perlin frequency?, stuff like that, so I also would need notes with the examples to explain in detail. I know.. I know, it's a lot of work, but I am sure you have thought about this for people who want to get into modding RimWorld, but have no prior knowledge of Xml or .dll files (how to use them, code them for RimWorld) I know that these <> in Unity is how you get a component of a gameobject like getcomponent<rigidbody>. Sorry for being a total noob. I hope I  am/not the only one who needs verbal help with code examples.

milon

No worries - everyone is a noob at least once.  ;)

First, the difference (for RimWorld only) between XML and DLL: XML is used only to define content, such as what a Simple Meal is: graphic, value, flammability, nutrition, etc.  You can find virtually every object/mood/template/etc defined in the XML somewhere.  DLL is for coding RimWorld's systems and functions, such as temperature mechanics, how lighting works, how to generate a batch of raiders, how to draw a pawn's inventory on-screen, etc.

DLL isn't something I have touched, and I don't plan to.  But there's guides floating around if you dig for them.  All DLL stuff is coded in C#, by the way.

XML in general is basically the idea of HTML formatting, but with no predefined tags.  You can use any tag you like as long as the structure is valid.  Applied to RimWorld, it has to follow certain guidelines that RimWorld expects.  For example, you can't create a new kind of animal and neglect to define a graphic for it - that would cause an error.

The best way to learn the XML is to look at RimWorld's own Core files (see your mods folder) to see examples.  It's not feasible for me to break down and learn each tag in order to write a guide.  This document is auto-created by a script I wrote that just grabs every known Core usage of each XML tag.  It even lists source files so you can go look up how they work in the XML file.  I'm sure myself and others will contribute XML modding knowledge to the wiki once RimWorld is stable, but right now the XML changes from one release to another - this is the reason mods break & have to be updated each release.

Hope that helps!  Let me know if you have other questions.

Bonus for reading this far:
I also wrote a little script to join all Core XML files into 1 file for learning (to CTRL+F for examples of a given tag).  This is a learning tool and is NOT meant to replace anything in your Core folder.  But use it if that sounds helpful!
https://www.dropbox.com/s/twt386qtukeppzn/CoreXML%20A16.xml?dl=0

jjcm04

Quote from: milon on January 07, 2017, 12:50:19 PM
No worries - everyone is a noob at least once.  ;)

First, the difference (for RimWorld only) between XML and DLL: XML is used only to define content, such as what a Simple Meal is: graphic, value, flammability, nutrition, etc.  You can find virtually every object/mood/template/etc defined in the XML somewhere.  DLL is for coding RimWorld's systems and functions, such as temperature mechanics, how lighting works, how to generate a batch of raiders, how to draw a pawn's inventory on-screen, etc.

DLL isn't something I have touched, and I don't plan to.  But there's guides floating around if you dig for them.  All DLL stuff is coded in C#, by the way.

XML in general is basically the idea of HTML formatting, but with no predefined tags.  You can use any tag you like as long as the structure is valid.  Applied to RimWorld, it has to follow certain guidelines that RimWorld expects.  For example, you can't create a new kind of animal and neglect to define a graphic for it - that would cause an error.

The best way to learn the XML is to look at RimWorld's own Core files (see your mods folder) to see examples.  It's not feasible for me to break down and learn each tag in order to write a guide.  This document is auto-created by a script I wrote that just grabs every known Core usage of each XML tag.  It even lists source files so you can go look up how they work in the XML file.  I'm sure myself and others will contribute XML modding knowledge to the wiki once RimWorld is stable, but right now the XML changes from one release to another - this is the reason mods break & have to be updated each release.

Hope that helps!  Let me know if you have other questions.

Bonus for reading this far:
I also wrote a little script to join all Core XML files into 1 file for learning (to CTRL+F for examples of a given tag).  This is a learning tool and is NOT meant to replace anything in your Core folder.  But use it if that sounds helpful!
https://www.dropbox.com/s/twt386qtukeppzn/CoreXML%20A16.xml?dl=0
Thank you! I really appreciate this. For any docs that I have found for .dll, normally doesn't relate to RimWorld, but more for building libraries, like MCCORLIB for the Microsoft Core Library, and I do have a C++ book (The Dummies Series), but this would be fore making a general library. I would need the exact minimum I need to make a RimWorld .dll, like which files I really need to include.

When it comes to the Xml, I have looked at some base-game files and can't find exactly which tags I need so I don't receive the error "Can't find typeDef" (or some idea of that error), What file would I need to mod in order to "fix/resolve" that error. Thanks Again so much for your help.

milon

#40
Glad to help. I'll try to take this a little further:

On DLL modding: DLL stands for Dynamic Link Library. As such, a dll file is a bunch of compiled code, much like an .exe file. The difference between an exe and a dll is that an exe is meant to be run directly while a dll isn't. The dll contains a bunch of functions and acts as a "helper" to whatever exe calls the dll. A dll can be coded in any language. In RimWorld, they must be coded in C# and certain standards must be followed (remember, the same code has to work on Windows, Mac, and Linux).  This means other languages like C++ won't help you much, beyond deepening your language of programming in general.  If you want to create new systems/functions/features, then C# coding is the only way to go.

For XML stuff, directory structure is important. You can't define a sound effect in a file that sits in the research folder. The concept of ParentName (see OP) is important too. You have to define your Thing from scratch for it to be recognized in RimWorld.

The way I got started is the same way I suggest you get started: copy a chunk of the Core mod into a new mod folder. Change one thing, like the description text, and start a new game using your mod. Did it work? If not, try to figure it out. Look at other mods and see what's different about yours. If you can't figure it out, post in Mods/Help.  In no time you'll be modding up a storm. :)

For those other XML tags that you don't understand yet, refer to the auto-doc. It lists all the ways Core uses each tag & attribute, so you can see a mostly complete list of options. If you still can't figure it out, don't delete it (it's probably important) - just keep them the way Core uses them.

pablous

Hi milon, i am a noob too like jjcm04. Thanks for your usefull comment.
Is it difficult to create a mod to add one event? If i want to make the mod i need to learn how to use XML or DLL? thx

milon

It depends on what you want to do with the event.  I personally haven't looked into events very much, so it's hard for me to say.  In general, if you're using existing mechanics and creating new content, you can do XML-only.  But if you want new mechanics or new behaviors, then you need to code that in C# and compile it into a DLL (way beyond me).

If I wanted to create an event, I'd look in the help file for the word event and see what XML tags I find.  Then I'd look at the Core examples to see how it works.  I might also download a basic event-adding mod or two and see how they work.  Then I'd try to figure out how I could make a slightly different event and package it as a mod.  Test, tweak, and repeat until it works (or until I've given up :P ).

Good luck!

PS - Feel free to start a new thread under Mods/Help with specific questions.  You'll get better help there than I can offer you.  ;)

Spdskatr

The XML Autodoc doesn't have documentation for CompProperties, only that they use it. Shouldn't we add compProperties documentation as well? Or has this already been done?
My mods

If 666 is evil, does that make 25.8069758011 the root of all evil?

milon

Sorry for the belated reply - I haven't had time to dig into the XML to see what you're referring to. If you're asking for specific documentation of what it does, that would defeat the purpose of it being an Auto Doc. If you're asking for more detailed analysis/use of compProperties, could you elaborate a bit on what you're looking for?