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

Use at any time

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.

You can conditionally load files using "if" statements, etc., for example:

if (someCondition == true) {
  include("path/to/someFile.js");
}

Obviously you need to be careful that you don't include the same file multiple times – that would generally be a bad thing and could well trigger an error during a routine systems check of the nearest NASDA satellite, and we wouldn't want that would we?

Filenames

Included files don't need to have a .js extension, they can have any name and extension you want, so long as they are valid javascript files.

Error handling

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.

// this won't do what you expect:
try {
	include("file/that/doesNotExist.js");
} catch(e) {
	// code here will never run
}
 
// instead use:
if (include("file/that/doesNotExist.js") === false) {
	// code here will run if there is 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.

Context and scope

The include() function will always load scripts in to the global scope in the context of the global object, even if you use include() within a sandbox or closure.

You should treat include()'d files as if they were just an extension of your main script.

Don't get caught out by mistakes like this:

var b = a + 1;

function() {
	var a = 10;
	include("path/to/someFile.js"); // silently fails to load
	console(b); // ReferenceError
}

Because the "someFile.js" gets loaded in to the global scope in the context of the global object, when it tries to reference the variable "a" an error will be thrown, silently breaking the entire included file. Then, when the main script tries outputting the value of variable "b", an error will be thrown because it is not defined.

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");