include()

Syntax

var returnValue = include(file);

Parameters

Parameter	Type	Mandatory	Description	Game verison
file	String		The path (relative to your mods folder), file name and extension of the file that should be included. For example, if you're writing an AI script and want to include a "whatever.js" script that's stored in the same folder as your AI script, you'd specify: include("multiplay/skirmish/whatever.js"); If you were loading a file from the 'challenges/' folder as part of a Challenge Game, it would be something like: include("challenges/whatever.js");	3.1 Beta 1

Return value

In version 3.1 Beta 2 and earlier, this function would return undefined if the file was successfully loaded, however undefined is treated as false in an if statement, and false is the return value used to indicate the file failing to load!

As of 3.1 Beta 4 and above, the function will return true if the file was included, which is far easier to work with. However, if your script supports older versions of the game, then you need to be careful with earlier versions returning undefined instead of true.

Notes

The include() function can be used at any point in the game – so, for example, you can use it to load scripts for new missions as a game progresses.

The include() function deals with it's own error handling – it will return false if there was an error loading the file, it will not thrown an error.

Because include() silently handles errors, you can effectively create mods for your mods. In your main mod include a file that doesn't exist eg. "multiplay/skirmish/mymod.addon.js" – it will silently fail to load. You can then provide another mod that provides the "mymod.addon.js" to change the way your main mod works when it's installed. A variation on this technique is used by Shadow Wolf TJC's Contingency Mod, where you can provide some extra files to change the technology levels in the game.

Example

if (include("multiplay/skirmish/foo.js") !== false) {
  // foo.js was loaded successfully
}

var path = "multiplay/skirmish/";
 
include(path+"foo.js");
include(path+"bar.js");
include(path+"moo.js");