• If you are citizen of an European Union member nation, you may not use this service unless you are at least 16 years old.

  • You already know Dokkio is an AI-powered assistant to organize & manage your digital files & messages. Very soon, Dokkio will support Outlook as well as One Drive. Check it out today!


Modding JA2 with LUA Scripts

Page history last edited by wanne 12 years, 7 months ago

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:

  • what is the benefit?
  • do we want it?
  • what are the requirements for the scripting system
  • what must be done?
  • who can do it?
  • who will do it?


and last, but not least

  • which Scripting Language shall be used
  • who will maintain the basic scripts to provide original JA2 behaviour?


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:

  • can be called from everywhere in the code (or, alternatively, from a separate launcher thread which gets signalled from everywhere in the code)
  • reading (inheriting) pre-selected game internal variables
  • modifying (setting) pre-selected game internal variables
  • calling prepared game internal C-functions
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:

  • by parameter stack on invocation
  • by reading a file (worst!)
  • by reading a pipe/socket
  • by SOAP (in fact, this is a clean version of reading a socket)
  • by COM containers
  • did I forgot one?
writing variables

This is a harder requirement. I know:

  • by manipulating the C return stack (Perl can do so)
  • by writing a file (worst!)
  • by writing a pipe/socket
  • by SOAP (in fact, this is a clean version again...)
  • by COM containers
  • did I forgot one?
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:

  • NPC Dialog
  • Shop System
  • Email generation system
  • File Attachment generation system
  • not yet created "Enter Keyword for Door Lock" dialogue
  • opening lock evaluation function
  • merging items ability evaluation function
  • 'earn a vehicle' function
  • Deidrana cut-scenes
  • not yet created "Play some movie file in a window" (for customized cut-scenes)
  • force enemy to start an attack or sector search patrol
  • force enemy to withdraw from empty sector
  • enabling shops, setting offer level of shops
  • enabling Bug holes (in SciFi mode)
calling from Everywhere, continued


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

  • Game start
  • Mercs landing in start sector/ hired Mercs landing somewhere
  • 1st Enemy contact in a sector
  • Team/Ego Entering/Leaving/Liberating/Loosing Sector
  • Militia Entering/Leaving/Liberating/Loosing Sector
  • New Day
  • Number of visited/liberated not-a-town sectors changed
  • Number of liberated/lost/re-liberated towns changed
  • Number of enemies killed changed
  • Number of own team mates changed
  • Specific Merc on the team
  • Balance/Income changed
  • each email trigger shall trigger default email generating script, can be extended further
  • Opening any lock (can access to ciphering script, combined with found ciphers, later)
  • PC is pissed of by another Team mate / seeing dead corpses / seeing violence / shall kill innocents / seeing violence against innocents
  • Meet/Trade Pub managers, Mining Managers
  • Meet/Talk/Hire/Kill Terrorists
  • Player triggers any of the classic internal quest flags as:
    • Meet/Talk/Hire/Kill Special NPC like 'Enrico Letter Women', Mike, Hamous etc.
    • Women to Dimitri
    • Carlos hideout 1st visit (Ira), 2nd Visit (Dimitri), 3rd Visit (hiring both leaders)
    • 1st/next talk/grease Airport delivery guy
    • Airport mechanic
    • Pater Walker, Clevelandies, Yanni, Toni & Co, Kingpin & Co, Conrad & Co, Ricci & Co., Leila & Co,
    • ... please complete


Language selection

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

Comments (0)

You don't have permission to comment on this page.