This is only for modders who are willing to get their hands dirty in the XML. Please turn away now if you were wanting a utility to do the code work for you.

Background

I've only really started looking at the games XML looking for examples of how the code works within itself. It looks as though you can control an awful lot of information but it is extremely hard finding specific examples.

What I was contemplating was to look at building city improvements to recruit race-specific units. As an example, allowing Ironeers to build stone golems.

The obvious starting point is to see how the game handles something similar. Kingdom races can build Drath units so lets start searching for how this is handled.

I was planning on using EditPad Pro to look at the game XML files to find the relevant examples but this is only a file editor and won't search through the directory structure. What we really need is an XML editor that will allow us to access all the game XML as a library or reference.

One solution is the free open-source Eclipse editor.

Eclipse can allow us to define a structure for both our mod files and also allow us a searchable reference of the game files. Best of both worlds.

Thought I would write this to help modders who aren't used to using Eclipse and want to work their way around a project environment.

Getting and installing Eclipse

Download Eclipse from http://www.eclipse.org/downloads/

You have a range of 'flavours' when downloading Eclipse but you wont need anything fancy for what we are about to do. I just grabbed the Eclipse Classic version when I installed it but it doesn't really matter which one you choose.

Extract the 'eclipse' directory from the zip file (I placed mine in Program Files).

I then created a shortcut of eclipse.exe for easy access from the desk-top. I think the reason Eclipse doesn't have an installer is that you can run multiple versions if you like.

Open eclipse.exe (I create a shortcut of this and have it on my desktop).

Select a workspace location. This is where your files will be stored. I just use the default usually and tell it not to ask again.

Select 'Workbench' from the splash screen

So at this stage you have Eclipse running, but now we need to install the XML plug-in.

Click Help --> Install New Software

In the next screen, Work with: Helios - http://download.eclipse.org/releases/helios from the drop-down list. If you are using a different version then choose that release version. Helios is version 3.6 of Eclipse.

Check box in Web, XML, and Java EE Development

Next

Next

Accept the terms of the license agreement --> Finish

Plug-ins will install (can take a while)

Restart when prompted.

Setting up your work environment

OK. So you've now got Eclipse installed and running.What we want to do is optimise the work area for XML coding. Luckily Eclipse comes with pre-defined layouts (called perspectives) and one of these is for XML.

Select Window --> Open Perspective --> Other --> XML

Setting up your Elemental Project

The project space is really just a collection of files you are working on (or referencing in our case). If I was working on a major mod I would define a project space for that mod, but in this instance I just want to muck around and will most likely end up with a collection of small mod files while I get used to it. I'm just going to set up a project space called 'Elemental'.

Select File --> New --> Project

General --> Project

Title: Elemental

Finish

Now you should see 'Elemental' listed in the Project Explorer within the left hand display.

Preparing your project environment

So far so good. But there is nothing inside the project.

Lets create two folders within the project space. One for our mod files and another for the game's XML reference files.

In the Project Explorer...

Right-click the 'Elemental' project folder and select New --> Folder

Folder name: Mods

Finish

Now make another folder called Resources

Getting your library of XML files

What we want to do is have a copy of the game XML files within the new 'Resources' folder we just created.

Select the newly created 'Resources' folder

Right-click --> Import

General --> File System

Next

From directory: Browse and navigate to the data/English directory (C:\Program Files\Stardock Games\Elemental\data\English)

Into folder should be your Elemental/Resources folder

Select All

Finish

Using the Reference files

Now you have a copy of the XML files used by the game that can be used as references and can be searched. Don't change these. Your changes should be put into your own XML files.

The search facility in Eclipse is nice and powerful. If you know how to use regular expressions you can search using these as well (but regex is not for the faint of heart nor for the easily frustrated!)

Back to our example. I wanted to find how the game files build recruitable Drath units.

I click on Search --> Search and search for the word 'Drath' within the workspace. I get 66 matches within a number of files and can see all the files with the word 'Drath' in them displayed in the bottom panel of the screen.

I'm not interested in the Core Tiles at this stage so I can ignore the files within this folder.

The next file is RecruitableImprovements.xml which contains 10 of the 66 matches. Within the search results I can open the plus symbol to see the context of what it has found. And if I double-click on the file it will open it up into my edit area. This is probably where I would start looking but I won't go into the specific for this tutorial - which is really just to help get modders started using Eclipse.

Tip: There are two ways to look at XML files in the edit area. Below the edit area are two tabs: Design and Source. Design is good you seeing the values within the file structure but I personally find the Source view easier to work with.

When the file is open, all my 'Drath' search results are colour coded for me to find easily.

And so now I'm on my way to working out the method of building recruitable units via city buildings.

Hope you enjoyed this tutorial. Please add or comment if you handle searching and referencing a different way.

Screengrabs

The Eclipse work environment. At the top-right, next to the toolbar, is the XML Perspective activated.

In the main window to the left, the Project Explorer shows the various resources and files associated with the project.

Das_Test.xml is a test mod file open in the edit window that I'm currently working on (Note that this is being viewed in Source mode). This file is also the only file currently in the Mods folder in the Project Explorer. The little red boxes to the right show issues with the XML structure - but the game doesn't worry about these. Clicking each of these will take me to the offending line.

Below the edit window is my current search for 'Drath'. Each file lists how many matches as well as showing the lines within each file.

To the right is the Outline window. I use this to quickly navigate to the command I want to change.

Here is the search dialog that gave the above search results.

Here is my edit window showing what it looks like in Design mode (selected from the tab at the bottom). This may be an easier way to edit the values if you don't want to sift through the source. It is the same file - just displayed differently.

I've double clicked one of the results of the search and it has opened up in the edit window. On the right (where the cursor is hovering) I can see the matches within the context of the whole file and clicking will take me to them. On the left are yellow arrows, also pointing to the matches. And in the main window the search results are highlighted.