Changes between Initial Version and Version 1 of ModdingGuiAndSimulation

Timestamp:

Apr 16, 2016, 11:21:01 AM (8 years ago)

Author:

sanderd17

Comment:

Adding some documentation for modders who build on the public mod

ModdingGuiAndSimulation

@@ +1 @@
+= Preface =
+Mods can overwrite any file in the public mod by just including a file with the same name. However, as files can be big, this is often not the best strategy to follow. It results in a lot of copying of code that needs to be maintained, and can easily cause conflicts with other mods that modify the same file (even if they modify it for different reasons).
+
+Since files are loaded alphabetically (following ASCII order), it's possible to overwrite code defined in a file that has been loaded before. And thus only include a file with minimal code in your mod.
+
+''NOTE'': This guide is mainly for mods that build on a base mod (like the public mod). Not for total-conversion mods, those should define all their own files anyway.
+
+= GUI =
+For general GUI creation information, see [wiki:GUI_-_Scripting_Reference].
+
+The GUI works by including files (XML and JS), and they can include a complete directory. So to add a GUI element, it's often possible by just adding the right XML file in the right directory. And to add code for that GUI element, it's possible by adding the right script in the right directory. Without overwriting any files.
+
+A clear example can be found in the [source:/ps/trunk/binaries/data/mods/public/gui/session/session.xml session.xml] file. Individual scripts are loaded, but also all scripts in the `session` directory are loaded. So adding a script in that directory will add (or replace) code defined in the other scripts. The same is true for XML files which can also be loaded individually or by directory (f.e. it loads the entire [source:/ps/trunk/binaries/data/mods/public/gui/session/selection_panels_left/ selection_panels_left] directory to a certain GUI element in the `session.xml`).
+
+Note that not all GUI files are made that moddable as the session. But a patch to make a certain portion of the GUI more moddable would generally be accepted (and then allow mods to build upon it more easily).
+
+= Simulation =
+For general info about the layout of the simulation code and data, see the [wiki:Mod_Layout#simulation Mod Layout].
+
+== Components ==
+Adding a component is quite simple, and can be done like it's done in the public mod.
+
+But individual [source:/ps/trunk/binaries/data/mods/public/simulation/components/ simulation components] are also made moddable by making the prototypes global objects. So the prototypes can be altered in different files.
+
+**Example**
+
+Say the game has a `PublicComponent.js` component that some function of it must be redefined. Then the file `PublicComponent_MyMod.js` can be created as following.
+
+{{{
+#!javascript
+/**
+ * This replaces the MyFunction function of
+ * the original PublicComponent component
+ */
+PublicComponent.prototype.MyFunction = function()
+{
+    // Replacement code
+}
+}}}
+
+''NOTE'': The `_` in the filename makes sure the new file is loaded after the original file, since `_` is sorted after `.` in the ASCII table.
+
+=== !ReRegisterComponentType ===
+
+The Engine parses the script in various ways. F.e. it parses the XML schemas, and provides an option to listen to certain messages. These things are parsed by the Engine when the script gets registered. The problem is that modifying the prototype doesn't register it automatically.
+
+So if you add a message listener to the function or alter the schema, you must end the file with a {{{ReRegisterComponentType}}} line. Like
+
+{{{
+#!javascript
+MyComponent.prototype.Schema = "...";
+
+/**
+ * This adds a health-changed listener to the component
+ */
+MyComponent.prototype.OnHealthChanged = function(msg)
+{
+    // Added code
+}
+
+Engine.ReRegisterComponentType(IID_MyComponent, "MyComponent", MyComponent);
+}}}
+
+''NOTE:'' !ReRegistering a component does no harm, so it's good to always include that line, even if it's not strictly needed.