This page has an associated video tutorial. See Modding with an Iron Fist: Episode 2: Scripting ( http://www.youtube.com/watch?v=fxPmLLQtqIQ )

Every map in Project Ironfist can have an associated script file. Everything is possible with scripting, from changing player's heroes in ways you can't using only the map editor, to creating intricate quests for players to solve.

Scripting in Project Ironfist uses the Lua programming language, and is inspired by how scripting is done in Heroes V. This tutorial will show you how to get started creating basic map scripts. For general information on how to program in Lua, see the Lua tutorial, http://lua-users.org/wiki/ForTutorial. See the Scripting Examples for ideas on how to build scripts for your map, and the Scripting Documentation for a reference on all available scripting features.

Making a Script File

After you create your map, you will need to find its filename. Go the the MAPS folder and find the corresponding file. Your script file must have that filename, plus the ".lua" suffix. For example, a map named "Sorrow's End" which uses features from the expansion will be saved in a file named "SorrowEn.MX2", and thus its corresponding script file must be named "SorrowEn.MX2.lua".

The root directory of our Project Ironfist installation should contain a "SCRIPTS" folder. If not, then create one. All script files should be placed in that folder.

An Example Script

Callbacks are key to building scripts in Project Ironfist, as they allow you to attach your code to in-game events. You define the actions you want inside the callback functions in your lua script. Here's an example which causes a message box saying "Hello, world!" to appear at the start of the map.

function OnMapStart()
  MessageBox("Hello, world!"); 
end; 

You can see the list of callbacks in Scripting Documentation.

Map Variables

In order to save local variables, define a list mapVariables at the beginning of your script. That list should contain the names of all the variables you wish to save. Variables can have any type except user data (i.e.: no hero or player objects). Tables are also supported. Example:

          Sarakin_has_visited_Sorrows_End = 1;

     randomString = "yadayada";

     shrineVisited = {false, false, false, false, false};

          mapVariables = {"Sarakin_has_visited_Sorrows_End", "randomString", "shrineVisited"};

Those variables will then persist through saves and loads.

As of Ironfist 1.3.0, all tables used as map variables may only have string keys.

Sharing code between map scripts

It's possible to re-use the same chunk of code in different map scripts without copying it to each map script using so called "modules".  They should be placed inside "SCRIPTS/MODULES" folder.

Here's an example where a module file "testmodule.lua" is used in a map script "testmap.MX2.lua".

tesmodule.lua:

     local mymodule = {}

     --- Here we declare a "public" function available for users of our module

     function mymodule.ShowMessage(text)

          MessageBox(text);

     end

     -- Return the module

     return mymodule

testmap.MX2.lua:

           --- We load our module here. It should be placed inside SCRIPTS/MODULES folder

     testmodule = require("scripts.modules.testmodule")

     function OnMapStart()

         testmodule.ShowMessage("Wow!");

     end

When running testmap.MX2 map with this script a message will be shown when the map starts.

Module naming convention

If you are going to share your module with other people please follow the module filename naming convention as described below:

     yourmodulename_<version>.lua

For example your first module is mymodule_1.lua

If you ever update your module, it's strongly adviced that you change the version number and share your module with a new filename (example - mymodule_2.lua or mymodule_1b.lua...)

That way maps that used version 1 of your module won't break if you update the module. They will still be using an older version module while newer maps can use a newer version module.

WARNING: Never use dots in your module name and version names!