VirtualNetwork+ Scripting Reference

getTitle() => String

This function should return a string that will be used as the network's title.

getSubtitle() => String

This function should return a string that will be used as the network's subtitle.

getDescription() => String

This function should return a string that will be used as the network's description. Surround text with asterisks to make it bold, or underscores to make it italic. Insert newlines with a \n character.

initializeTestRun(Integer testRun)

This function will be called at the beginning of each test run, and should fully initialize the network using the API functions listed below. The testRun argument specifies the current test run, starting at 1.

onCycleFinished()

This function will be called at the end of each cycle.

createHost(String name, Integer x, Integer y, Integer width, Integer height) => Host

Create a host in the network with the specified name, position, and size. The X coordinate increases toward the top-right corner of the screen, while the Y coordinate increases toward the top-left corner of the screen.

Returns a host handle that can be passed to other API functions.

createLink(Host firstHostHandle, Integer firstID, Host secondHostHandle, Integer secondID) => Link

Create a link between the specified hosts using the specified link IDs. The two hosts must visibly align so that a link could be created, and must be spaced with exactly two grid units between them.

Instead of a numeric value, you may use the constant LINK_ID_NONE to create a one-way or impassable link.

Returns a link handle that can be passed to other API functions.

modifyLink(Link linkHandle, Integer firstID, Integer secondID)

Change the link IDs of the specified link to the specified values.

Example: Create two hosts and a link connecting them.

var inboxHost = createHost("inbox", 5, 0, 3, 3);
var outboxHost = createHost("outbox", 10, 0, 3, 3);
createLink(inboxHost, 800, outboxHost, -1);

createNormalFile(Host hostHandle, Integer id, Integer icon, Array contents) => File

Create a normal, movable file in the specified host with the specified ID, icon, and contents. The file's contents should be an array of integers and strings, which correspond to number and keyword values respectively.

The allowed values for icon are FILE_ICON_DATA, FILE_ICON_TEXT, FILE_ICON_USER, FILE_ICON_ARCHIVE, FILE_ICON_FOLDER, FILE_ICON_SECURE, FILE_ICON_MOVIE, and FILE_ICON_MUSIC.

Returns a file handle that can be passed to other API functions.

createLockedFile(Host hostHandle, Integer id, Integer icon, Array contents) => File

Similar to createNormalFile, except that the created file cannot be moved out of its initial host. A file ID can only be used more than once in a network if all files with that ID are locked.

Returns a file handle that can be passed to other API functions.

setFileColumnCount(File fileHandle, Integer columnCount)

Enable column mode for the specified file's display window, which will automatically wrap the file contents after the specified number of values.

setFileInitiallyCollapsed(File fileHandle)

Set the specified file's display window to be initially collapsed when connecting to the network or switching to a different test run.

Example: Create a normal file in the player host with two values (a keyword and a number) and set it to be initially collapsed.

var playerFile = createNormalFile(getPlayerHost(), 300, "data", ["ABC", 123]);
setFileInitiallyCollapsed(playerFile);

createRegister(Host hostHandle, Integer x, Integer y, String name) => Register

Create a hardware register in the specified host with the specified position and name. A hardware register's name must consist of exactly four alphanumeric characters.

Returns a hardware register handle that can be passed to other API functions.

setRegisterReadCallback(Register registerHandle, Function readCallback)

Set the specified function as the read callback for the specified hardware register. When an EXA attempts to read from the register the read callback will be called and whatever value it returns will be read by the EXA. A read callback should return either an integer or a string.

setRegisterWriteCallback(Register registerHandle, Function writeCallback)

Set the specified function as the write callback for the specified hardware register. When an EXA attempts to write to the register the write callback will be called and whatever value it wrote will be passed to the callback as either an integer or a string.

Example: Create a hardware register that can store a single value.

var targetHost = createHost("target", 5, 0, 3, 3);
var registerHandle = createRegister(targetHost, 7, 2, "TEST");
var registerValue = 0;

setRegisterReadCallback(registerHandle, function() {
    return registerValue;
});

setRegisterWriteCallback(registerHandle, function(value) {
    registerValue = value;
});

requireCreateFile(Host hostHandle, Array contents, String description)

Create a goal that requires a file with the specified contents to be created in the specified host. To require a file to be brought back to the player's host, use the result of getPlayerHost for the hostHandle argument.

requireMoveFile(File fileHandle, Host hostHandle, String description)

Create a goal that requires the specified file to be moved to the specified host.

requireChangeFile(File fileHandle, Array contents, String description)

Create a goal that requires the specified file to be changed to have the specified contents.

requireMoveAndChangeFile(File fileHandle, Host hostHandle, Array contents, String description)

Create a goal that requires the specified file to be moved to the specified host and changed to have the specified contents.

requireDeleteFile(File fileHandle, String description)

Create a goal that requires the specified file to be deleted from the network.

requireCustomGoal(String description) => Goal

Create a custom goal that can be marked as completed or failed from a hardware register callback.

Returns a custom goal handle that can be passed to other API functions.

setCustomGoalCompleted(Goal goalHandle)

Mark the specified custom goal as completed.

setCustomGoalFailed(Goal goalHandle)

Mark the specified custom goal as failed.

mergeRequirements(Integer requirementCount, String description)

Merge the requirementCount most recently created requirements into a single requirement. Merged requirements will display the progress of their sub-requirements as a fraction (such as "4/6").

Example: Create four files and a goal requiring them to be deleted.

var targetHost = createHost("target", 5, 0, 3, 3);
for (var i = 0; i < 4; i++) {
    var fileHandle = createNormalFile(targetHost, 200 + i, "data", [i]);
    requireDeleteFile(fileHandle, "");
}

mergeRequirements(4, "Delete all files in the *target* host.");

Example: Create a register and goal requiring it to be written to.

var targetHost = createHost("target", 5, 0, 3, 3);
var registerHandle = createRegister(targetHost, 7, 2, "TEST");
var goalHandle = requireCustomGoal("Write any value to the #TEST register.");

setRegisterWriteCallback(registerHandle, function(value) {
    setCustomGoalCompleted(goalHandle);
});

createTable(String title, Integer x, Integer y, String description)

Create an input / output table with the specified title and position, in addition to a goal with the specified description that requires all output columns in the table to be completed correctly.

A network may only contain a single input/output table.

addTableInput(String label, Array values, Register registerHandle)

Add an input column to the input / output table with the specified label and input values. When an EXA reads from the specified register, it will read the next input value from this column.

addTableOutput(String label, Array values, Register registerHandle)

Add an output column to the input / output table with the specified label and expected values. When an EXA writes to the specified register, it will append the output value to this column and compare it to the corresponding expected value.

Example: Create an input / output table and associated goal requiring the input values to be doubled and written to the output register.

var inputValues = [];
var outputValues = [];
for (var i = 0; i < 30; i++) {
    inputValues[i] = randomInt(1000, 5000);
    outputValues[i] = inputValues[i] * 2;
}

var targetHost = createHost("target", 5, 0, 3, 3);
createTable("I/O LOG", 108, 0, "Transfer the specified values.");
addTableInput("INPUT", inputValues, createRegister(targetHost, 7, 2, "INPT"));
addTableOutput("OUTPUT", outputValues, createRegister(targetHost, 7, 0, "OUTP"));

createWindow(String title, Integer x, Integer y, Integer width, Integer height) => Window

Create an output window with the specified title, position, and size. Output windows can display arbitrary text, and are typically used to provide additional feedback in networks utilizing hardware registers.

Returns an output window handle that can be passed to other API functions.

printWindow(Window windowHandle, String text)

Print the specified line of text to the specified window. Lines that are longer than the window is wide will be automatically truncated.

clearWindow(Window windowHandle)

Clear the contents of the specified window.

randomInt(Integer min, Integer max) => Integer

Returns a random number between min and max, inclusive.

randomBool(Number probability) => Boolean

Returns a boolean that is true with the specified probability, where a value of 0 will always return false and a value of 1 will always return true.

randomChoice(Array choices) => Object

Returns a random value from the specified array.

randomName() => String

Returns a random name.

randomAddress() => String

Returns a random residential address.

getPlayerHost() => Host

Returns a host handle for the player's host, which is created automatically and cannot be altered.

convertTextToKeywords(String text) => Array

Returns an array of keywords generated by splitting the specified multiword string on spaces (which are omitted) and punctuation (which are included). Useful for creating the contents of text-based files.

printConsole(Object object)

Open the in-network debug console and print the textual representation of the specified object to it.

The debug console is only intended for debugging scripts and displaying errors. If you want to display information about the network you should use output windows instead of the debug console.