Difference between revisions of "Module:Test/data/doc"

From RimWorld Wiki
Jump to navigation Jump to search
m
m (category)
 
(9 intermediate revisions by one other user not shown)
Line 1: Line 1:
== Herein lie the (current) ad hoc rules for getting from an XML to a Lua table ==
+
== Transformation rules ==
 +
 
 +
=== RimWorld version ===
 +
Version is added to the beginning of each generated Lua table.
 +
 
 +
<pre>
 +
return {
 +
 
 +
  version = "1.2.2753",
 +
  ...
 +
</pre>
  
 
=== Elements with attributes ===
 
=== Elements with attributes ===
Move into key with exact name. Attributes become subkeys. A bit ugly but simple.
+
Create a new subelement and move all of the attributes to their own subelements within it.
 +
 
 +
=== *Def elements ===
 +
<defName> is used as part of the index for the main Def table.
  
=== Def keys ===
+
Additional attributes added: "DLC", "FileName".
defName is used as an index for the main Def table. defName remains as a subkey to the table.
 
  
 
<pre>
 
<pre>
Line 14: Line 26:
 
</pre>
 
</pre>
  
becomes
+
transforms to:
  
 
<pre>
 
<pre>
["Hare"] = {
+
["ThingDef:Hare"] = {
   ["ParentName"] = "BaseHare",
+
   ["_attrib_"] = {
   ["defName"] = "Hare",
+
    ["ParentName"] = "BaseHare",
   ["label"] = "hare",
+
    ["FileName"] = "Races_Animal_Hares.xml",
 +
    ["DLC"] = "Core",
 +
  },
 +
   ["defName"] = "Snowhare",
 +
   ["label"] = "snowhare",
 
   ...
 
   ...
 
</pre>
 
</pre>
  
Parent Def that gets inherited (Name becomes the key, no defName):
+
Parent (abstract) Def:
  
 
<pre>
 
<pre>
Line 34: Line 50:
 
</pre>
 
</pre>
  
becomes
+
transforms to:
  
 
<pre>
 
<pre>
["BaseHare"] = {
+
["ThingDef:BaseHare"] = {
   ["Abstract"] = true,
+
   ["_attrib_"] = {
  ["ParentName"] = "AnimalThingBase",
+
    ["Abstract"] = "True",
   ["statBases"] = {
+
    ["ParentName"] = "AnimalThingBase",
    ["MoveSpeed"] = 6.0,
+
    ["Name"] = "BaseHare",
    ["MarketValue"] = 50,
+
    ["FileName"] = "Races_Animal_Hares.xml",
    ...
+
    ["DLC"] = "Core",
 +
   },
 +
    ["statBases"] = {
 +
      ["MoveSpeed"] = 6.0,
 +
      ["MarketValue"] = 50,
 +
  ...
 
</pre>
 
</pre>
  
=== <nowiki><li></nowiki> elements enclosing simple values ===
+
=== List elements without children ===
 
Get transformed into ordered lists (numerically indexed Lua tables).
 
Get transformed into ordered lists (numerically indexed Lua tables).
  
Line 56: Line 77:
 
</pre>
 
</pre>
  
becomes
+
transforms to:
  
 
<pre>
 
<pre>
Line 67: Line 88:
 
Note: a comma after the last item in a list is not flagged as an error in Lua.
 
Note: a comma after the last item in a list is not flagged as an error in Lua.
  
=== <nowiki><li></nowiki> elements enclosing multiple items ===
+
=== List elements with children ===
  
 
<pre>
 
<pre>
Line 86: Line 107:
 
</pre>
 
</pre>
  
becomes
+
transforms to:
  
 
<pre>
 
<pre>
Line 104: Line 125:
 
},
 
},
 
</pre>
 
</pre>
 +
 +
=== List elements with a single attribute Class ===
 +
The value of the "Class" attribute is used to rename the <nowiki><li></nowiki>.
 +
 +
<pre>
 +
<comps>
 +
  <li Class="CompProperties_Glower">
 +
    <glowRadius>10</glowRadius>
 +
...
 +
</pre>
 +
 +
transforms to:
 +
 +
<pre>
 +
comps = {
 +
  CompProperties_Glower = {
 +
    glowRadius = 10,
 +
...
 +
</pre>
 +
 +
=== Components ===
 +
 +
It would be useful to have some of the more used components. They can then be queried for additional functionality that some game objects have.
 +
 +
They can be numbered tables or, as in some of the examples above, string indexed. String indexes, in general, are simpler to use. Numeric tables I have to search through.
 +
 +
See [[#List elements with a single attribute Class]]
  
 
=== Ranges (1~2) ===
 
=== Ranges (1~2) ===
: TODO
+
<pre><overdoseSeverityOffset>0.18~0.35</overdoseSeverityOffset></pre>
 +
transforms to:
 +
<pre>overdoseSeverityOffset = { ["<"]=0.18, [">"]=0.35 },</pre>
  
 
=== Curve points ===
 
=== Curve points ===
Line 124: Line 174:
 
</pre>
 
</pre>
  
becomes
+
transforms to:
  
 
<pre>
 
<pre>
Line 137: Line 187:
 
</pre>
 
</pre>
  
=== Components ===
+
=== Descriptions ===
  
It would be useful to have some of the more used components. They can then be queried for additional functionality that some game objects have.
+
Because of some exceptions in Royalty Defs, <description> content has to be wrapped in double square brackets (Lua multiline syntax).
  
They can be numbered tables or, as in some of the examples above, string indexed. String indexes, in general, are simpler to use. Numeric tables I have to search through.
+
=== MayRequire attribute ===
 +
Removed.
  
 
== Issues ==
 
== Issues ==
  
* One data file or smaller ones split by categories (buildings, races, items, etc.).
+
=== One (data) file to rule them all ===
* A pro for separation might be that not everything has to be loaded to get relevant data (load only relevant files).
+
One data file or smaller ones split by categories (buildings, races, items, etc.).
* Until a more final version of the data is seen, the size of the whole thing is a bit unknown but shouldn't be too big to prevent the "one file" option. A definite pro for the one file option is the simplicity of updating - upload one file, done. If versioning is to be done, one file option is also better. Consider: parsing files for earlier versions, multiply by several pages of data for each version.
+
 
* Some pieces of the puzzle are in game code so until more files are processed, can't say what else will pop up.
+
Single:
* Can't keep semi-manually processing the xml files... it's lunacy.
+
* simplicity
 +
** versioning
 +
** uploading
 +
 
 +
Split:
 +
* dynamic loading
 +
 
 +
=== Inheritance (interaction with parser) ===
 +
Inheritance can be handled by the parser or the module. If the parser handles it, then for any change the dataset needs to be recreated so I'm leaning towards letting the module take care of that. In this case the only purpose of the parser is to filter data and transform it into something Lua can use.
 +
 
 +
== TODO ==
 +
* Implement filtering for components (any list item that follows the same pattern)
 +
 
 +
<includeonly>[[Category:Module]]</includeonly>
 +
<noinclude>[[Category:Module documentation]]</noinclude>

Latest revision as of 22:59, 22 October 2022

Transformation rules[edit]

RimWorld version[edit]

Version is added to the beginning of each generated Lua table.

return {

  version = "1.2.2753",
  ...

Elements with attributes[edit]

Create a new subelement and move all of the attributes to their own subelements within it.

*Def elements[edit]

<defName> is used as part of the index for the main Def table.

Additional attributes added: "DLC", "FileName".

<ThingDef ParentName="BaseHare">
  <defName>Snowhare</defName>
  <label>snowhare</label>
  ...

transforms to:

["ThingDef:Hare"] = {
  ["_attrib_"] = {
    ["ParentName"] = "BaseHare",
    ["FileName"] = "Races_Animal_Hares.xml",
    ["DLC"] = "Core",
  },
  ["defName"] = "Snowhare",
  ["label"] = "snowhare",
  ...

Parent (abstract) Def:

<ThingDef Abstract="True" ParentName="AnimalThingBase" Name="BaseHare">
  <statBases>
    <MoveSpeed>6.0</MoveSpeed>
    <MarketValue>50</MarketValue>
    ...

transforms to:

["ThingDef:BaseHare"] = {
  ["_attrib_"] = {
    ["Abstract"] = "True",
    ["ParentName"] = "AnimalThingBase",
    ["Name"] = "BaseHare",
    ["FileName"] = "Races_Animal_Hares.xml",
    ["DLC"] = "Core",
  },
    ["statBases"] = {
      ["MoveSpeed"] = 6.0,
      ["MarketValue"] = 50,
  ...

List elements without children[edit]

Get transformed into ordered lists (numerically indexed Lua tables).

<tradeTags>
  <li>AnimalUncommon</li>
  <li>AnimalFighter</li>
</tradeTags>

transforms to:

["tradeTags"] = {
  "AnimalUncommon",
  "AnimalFighter",
},

Note: a comma after the last item in a list is not flagged as an error in Lua.

List elements with children[edit]

<lifeStageAges>
  <li>
    <def>AnimalBaby</def>
    <minAge>0</minAge>
  </li>
  <li>
    <def>AnimalJuvenile</def>
    <minAge>0.25</minAge>
  </li>
  <li>
    <def>AnimalAdult</def>
    <minAge>0.5</minAge>
  </li>
</lifeStageAges>

transforms to:

["lifeStageAges"] = {
  {
    ["def"] = "AnimalBaby",
    ["minAge"] = 0,
  },
  {
    ["def"] = "AnimalJuvenile",
    ["minAge"] = 0.25,
  },
  {
    ["def"] = "AnimalAdult",
    ["minAge"] = 0.5,
  },
},

List elements with a single attribute Class[edit]

The value of the "Class" attribute is used to rename the <li>.

<comps>
  <li Class="CompProperties_Glower">
    <glowRadius>10</glowRadius>
...

transforms to:

comps = {
  CompProperties_Glower = {
    glowRadius = 10,
...

Components[edit]

It would be useful to have some of the more used components. They can then be queried for additional functionality that some game objects have.

They can be numbered tables or, as in some of the examples above, string indexed. String indexes, in general, are simpler to use. Numeric tables I have to search through.

See #List elements with a single attribute Class

Ranges (1~2)[edit]

<overdoseSeverityOffset>0.18~0.35</overdoseSeverityOffset>

transforms to:

overdoseSeverityOffset = { ["<"]=0.18, [">"]=0.35 },

Curve points[edit]

Curves pop up in a lot of places so additional support functions for those might be in order.

Min, max, maybe average... things like that. Some (like litterSizeCurve) have a fixed amount of points (correction: even for litterSizeCurve this is not true) so you could just retrieve the first one or last (fourth), but this is not the case for all of them and is a bit ugly. Whatever the case, additional processing with wiki syntax would have to be used. This is bad (and to be avoided if possible).

<litterSizeCurve>
  <points>
    <li>(1.0, 0)</li>
    <li>(1.5, 1)</li>
    <li>(2.0, 1)</li>
    <li>(2.5, 0)</li>
</points>

transforms to:

["litterSizeCurve"] = {
  ["points"] = {
    {0.5, 0},
    {1, 1},
    {1.5, 1},
    {2.0, 0},
  },
},

Descriptions[edit]

Because of some exceptions in Royalty Defs, <description> content has to be wrapped in double square brackets (Lua multiline syntax).

MayRequire attribute[edit]

Removed.

Issues[edit]

One (data) file to rule them all[edit]

One data file or smaller ones split by categories (buildings, races, items, etc.).

Single:

  • simplicity
    • versioning
    • uploading

Split:

  • dynamic loading

Inheritance (interaction with parser)[edit]

Inheritance can be handled by the parser or the module. If the parser handles it, then for any change the dataset needs to be recreated so I'm leaning towards letting the module take care of that. In this case the only purpose of the parser is to filter data and transform it into something Lua can use.

TODO[edit]

  • Implement filtering for components (any list item that follows the same pattern)