Modding JA2 with LUA Scripts

Externalisation by Script Files



In Spring '2007, Sergeant_Kolja and Acy Forsythe came to the idea, to further drive the externalisation process.
The JA2 1.13 developers team attempts to make JA2 1.13 a game which is very easy to be modified. Currently, a lot of very valuable work was done to externalize 'static' game parts like items, City locations, rough game behavior and so on into XML and INI files.


The idea to use a Scripting language is the next logical process. Scripting can be used to loosely connect former hard coded and hard connected game mechanics as well as to insert completely new behaviour. Let me show a very simple example:


When you liberate Drassan Airport, you hit on internal trigger inside the hard coded game mechanics. This trigger
does two things:

  1. evaluating the airport triggers condition (C-Language)
  2. if you already tried to visit BRs shop (evaluating an earlier Laptop trigger) it will writing You an predefined email (C-Language)
  3. enabling BRs shop (C-Language)


A script could disconnect this and tie it together again. So with the script the game would act:

  1. evaluating the airport triggers condition (+ evaluating an earlier Laptop trigger) (C-Language)
  2. call Script 'liberated_drassan_airport', with some info about earlier triggers and stats (C-Language)
  3. if You already tried to visit BRs shop: writing You an email, text can be predefined or generated (Src-Language)
  4. enabling BRs shop (Src-Language)


In this stage, we see no difference between original game and the new, script-able one. Now imagine an arbitrary Mod:

  1. evaluating the airport triggers condition (+ evaluating an earlier Laptop trigger) (C-Language)
  2. call Script 'liberated_drassan_airport', with some info about earlier triggers and stats (C-Language)
  3. if You already tried to visit BRs shop and if SAM is still not liberated: writing You an email, text is generated with some placeholders from reputation and current balance (Scr-Language)
  4. writing You an email "please help us to liberate the coastal harbor, too" (Scr-Language)
  5. enabling Pablo to be greased to give the Key-card for a basic equipment box (Scr-Language)
The modified Game will, as You see, not enable the BRs shop, because whether the Airspace nor the Harbor is safe enough. But You'll be equipped with some basic equipment if You give Pablo enough cash. This would be a complete new aspect of the game without changing the C Code (after we inserted the interpreter). We only combine already existing Email, Pablo Greasing, Orta Rocket Scientist Greasing, locked Boxes, giving Items.


After well proved implementation of such 'global behaviour' scripting, we could advance to script internal Game mechanics like AI, damage system and so on. But this would require (in my Eyes) a scripting system which is able to precompile all scripts upon start. It wouldn't be a good idea to start loading and interpreting on each single shot.



There are some topics to discuss:


and last, but not least


what is the benefit of scripting?

As stated in the introduction, there where better support for new mods, as well as for reanimating the old mods (I'm still dreaming of SOG'69-1.13 and DL-1.13, who doesn't?).

Acy said

This could also be the answer to the Modders balance issue certain mod makers brought up. They can have a script that overrides the INI file. Players could still change the script, but it will be a bit more cryptic than an INI file. Not out of spite, but out of neccessity to make coding it as simple as possible.


do we want to have it?

As stated in the developers internal email discussion of April 2007: YES! (or at least: nobody said anything against it)


what are the requirements for the scripting system?



The scripting system must be able to do following things in general:

calling from everywhere

I expect this is only a formal topic. But later, I will collect some detailed points here. F.i., where we must call it.


reading variables

A scripting language has usually one of the following mechanisms to get values:

writing variables

This is a harder requirement. I know:

calling foo

All we know is, we must be able to do so and some Scripting systems can bind DLLs or LIBs. So I imagine, we must slightly change some ingame interfaces and shift the selected functions whether into separate Lib's or into DLLs. Then we are able to call them from C/C++ as well as from Scripts.

Other ways are SOAP or COM. Since the game code already exist, it is not easy to implement them afterwards. But it could finally a bit easier because the Class Interface does not necessarily need splitting the code - it could simply use some 'extern' statements to classic code.


Under all circumstances we need to call:

calling from Everywhere, continued


Here comes a list of ingame points which must invoke / trigger our scripts:


Language selection

The Scripting language the 1.13 has choosen is LUA, (Overview). In fact, LUA is currently used by successful, professional games. .