An RGD macro is a script file that you can "run" over a folder. The script can then do something with each RGD file in that folder; it could make changes to each RGD, it could compile a report from various peices of RGD data, or it could do something else. Below is a macro which halves the cost of all units. To run it, load up a mod in mod studio, right click on the attrib\ebps folder and choose "Run macro over the RGDs in this folder". Copy the code into the box which appears and press "Run macro".

function each_file(rgd)
	print("Halving the cost of " ..  rgd.path)
	cost = rgd.GameData.cost_ext.time_cost.cost
	for value in cost
		cost[value] = cost[value] / 2
	end
	rgd:save()
end

The assertive amongst you may notice that the above script looks similar to lua in terms in syntax. You would be correct; RGD macros use a modified Lua 5.1.2. If you are familiar with lua 5.1, then you may want to skip straight to the RGD macro language reference. For the rest of you, here is a simpler macro:

function each_file(rgd)
	rgd.GameData.health_ext.is_invincible = true
	rgd:save()
end

If you haven't guessed yet, each RGD file in the folder is passed into the each_file function. GameData and all the data within can be accessed with rgd.GameData and after you've made your changes, the rgd is saved with rgd:save() .

Yes, every RGD in the folder you choose (and subfolders) is passed into the function. The file path and file name of the RGD are available to the script though, so you choose to only make changes to certain files (eg, only files that have "hq" in the name):

function each_file(rgd)
	if rgd.name:find "hq"
		rgd.GameData.health_ext.is_invincible = true
		rgd:save()
	end
end

Of course, Lua's pattern matching facility allows more complex filtering to be done via filenames: (this one only matches files called hq.rgd, hq_2.rgd to hq_6.rgd)

function each_file(rgd)
	if rgd.name:find "^hq_?[2-6]?%.rgd$" then
		rgd.GameData.health_ext.is_invincible = true
		rgd:save()
	end
end

Assignments are made like so:

rgd.GameData.x.y = z
rgd["GameData"]["x"]["y"] = z

You'll run into an error if GameData.x doesn't exist, so it's safer to do it like this:

if rgd:GET("GameData","x","y") then
	rgd.GameData.x.y = z
end

You can assign values like so:

rgd.GameData.x.a = "fred"   -- string value
rgd.GameData.x.b = 3.14159  -- number value
rgd.GameData.x.c = false    -- true/false value
rgd.GameData.x.d = "$75010" -- UCS value
rgd.GameData.x.e = nil      -- delete a value

The string and number examples should be obvious. The true/false one should be as well, but remember that true and false are lowercase. The UCS one is not so obvious; UCS references are stored as a string with a dollar sign as the first character and then digits, as to differentiate them from normal numbers. The final example is a lua caveat; assigning a value of nil to something will undefine/delete that something. Here are three ways of setting a value:

-- 1:
rgd.GameData.x.y = z
 
-- 2:
var = rgd.GameData.x.y
var = z
 
-- 3:
var = rgd.GameData.x
var.y = z

Only 1 and 3 work, 2 does not. Why does 2 not work? The value of GameData.x.y is stored in var, then the value of z is stored in var. The RGD table is not updated. As a rule of thumb, unless the RGD table is mentioned in the assignment, then it is not updated. Example 1 mentions the table, but example 3 needs a little bit more explaination. At first it looks like GameData.x is copied into var, then var.y is modified, so how can the RGD be updated? One caveat of lua is that tables only exist once, and that assignements do not copy them, but copy a reference to them. So in example 3, var becomes shorthand for rgd.GameData.x rather than making a copy of it. Finally, for your changes to be saved, remember to call rgd:save()

Back to tutorial list

This documentation is provided under the GNU General Public License. All trademarks / copyrights are tm/r/c their respective owners.