Other great resources: Official JS API docs, Scripting Forum

Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 14 Next »

Include library scripts in to your main script...

 

Syntax

var returnValue = include(file);

Parameters

ParameterTypeMandatoryDescriptionGame verison
fileString(tick)

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.

ValueTypeDescriptionGame version
undefinedUndefined

The file was successfully included.

Note: undefined type-coerces to false in an if statement.

3.1 Betas 1 & 2 only
trueBooleanThe file was successfully included.3.1 Beta 4 and above
falseBooleanThere was a problem including the file (most likely path or file not found).3.1 Beta 1

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

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.

Error handling
// 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:

someFile.js (the file that will be included)
var b = a + 1;
Main script
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

Including a file
if (include("multiplay/skirmish/foo.js") !== false) {
  // foo.js was loaded successfully
}
Using a variable to define the path...
var path = "multiplay/skirmish/";
 
include(path+"foo.js");
include(path+"bar.js");
include(path+"moo.js");
Availability STABLE

Requires:

  • Warzone 3.1 Beta 1 and above.
  • Return value improved in 3.1 Beta 4
Contents

Jump to:

 

  • No labels