I4 Module API

I4 modules must conform to the following API in order to be successfully loaded and used by the I4 runtime.

Life Cycle

API Functions

Event Functions

Events

// event module needs to initialized
_global.EVENT_MODULE_INITALIZE         = 0;

// event module needs to finalize
_global.EVENT_MODULE_FINALIZE          = 1;

// user requested advancement, but it failed
_global.EVENT_NAVIGATION_ADVANCEFAILED = 2;

// event module should layout itself
_global.EVENT_MODULE_PAINT             = 3;

States

// module is not used right now
_global.MODULE_LIFECYCLE_UNLOADED           = 0;

// module has a loadModule executed on it
// but the preloader has not finished
_global.MODULE_LIFECYCLE_LOADING            = 1;

// loaded by runtime, means that the runtime is setting it up
// initalize is called under this state, and the preloader has finished
_global.MODULE_LIFECYCLE_LOADED             = 2;

// loaded and running, but not finalizable
_global.MODULE_LIFECYCLE_RUNNING            = 3;

// module will be okay if it needs to be finalized
// module sets it by calling selfFinalizable
_global.MODULE_LIFECYCLE_RUNNINGFINALIZABLE = 4;

// work is done, used in the autoadvance mode
// so that a module says, "i'm done" by calling selfFinalize
_global.MODULE_LIFECYCLE_FINALIZED          = 5;

Example without autoAdvance (autoAdvance = false)

Step

Who

What

1

Runtime

i4load's the module

2

Runtime

Sets module.lifeCycleState to MODULE_LIFECYCLE_LOADED

3

Runtime

Calls eventHandler with Initialize and waits for function to return

4

Module

Does any init work

5

Runtime

On return, calls gotoAndPlay on the module

6

Module

Does whatever it wants, and sets FINALIZEABLE

7

Runtime

User clicks on the next button

8

Runtime

Calls eventHandler with finalize

9

Module

Finishes its work, writes some variables

10

Runtime

Unloads module

Example with autoAdvance

Step

Who

What

1

Runtime

if4loadŐs the module

2

Runtime

Sets module.lifeCycleState to MODULE_LIFECYCLE_LOADED

3

Runtime

Calls eventHalder with initalize and waits for function to return

4

Module

Does any init work

5

Runtime

On return, calls gotoAndPlay on the module

6

Module

Does whatever it wants

7

Module

Is ready to advance, calls selfFinalize()

8

Runtime

Calls eventHandler with finalize

9

Module

Finishes its work, writes some variables

10

Runtime

Unloads module

Database APIs

The I4 database is simple and designed to be easy to use for module writers. For the most part, interaction with this API is transparent. All constants are automatically associated with values in the regular name space.

Thus, for constants such as a title for a module, they will become this.title. The mapping is as follows:

XML

Module

<const type="integer" name="xpos" value="43" /> this.xpos = 43
<const type="composite" name="layout">
   <const type="integer" name="xpos" value="534" />
   <const type="integer value="115" />
</const>


this.layout.xpos = 534
this.layout.xscale = 115

To write values to the database, you must use the setValue API. A full description of the API functions are as follows:

API Functions

Example


Start Frame Labels

The first frame of a module must contain the initialize and finalize functions. The runtime after it has called initialize will then jump the module to its startLabel. If this is unspecified in the XML, the runtime will jump to the frame named "start" as a default, otherwise the runtime will jump to the specified target.

<module type="vas" instance="health1" startLabel="someOtherLabel">


Interface Invisibility

If a module wishes to not have the interface displayed during its execution, it may specific the noInterface attribute on the module tag. This attribute only works for individual modules, and not predictably for grouped modules.

<module type="vas" instance="health1" noInterface="true">


Reserved Words

These following words may not be used as constants for a module:


Complete API List

Runtime

// Gets an array of all the running modules (i.e. currentModules)
// includeNonModules -- boolean, optional, weather or not to include modules other than MODULE_TYPE_MODULE
_global.getCurrentModules = function(includeNonModules)

// transforms a XML module name into it's systemlevel name
// you should only need to use this if you're interacting with the XML directly
_global.userModuleToSystem = function(module)

// send an event to modules (either a single module or an array)
// set modules[0]="runtime" to raise a runtime event
_global.sendEventToModules = function(modules, event, text)

// allocate a new safe Flash level
_global.allocNewLevel = function(base)

Loader

Loads an I4 module

_global.i4Load = function(toLoad, baseClip)
toLoad -- module to load
baseClip -- target to load into

Unloads an I4 module

_global.i4Unload = function(clipName, fakeUnload)
clipName -- optional, if specified unloads only that clip, otherwise unloads all getCurrentModules clips
fakeUnload -- optional, does everything except the actual unload   

Navigation

n/a - no module level functions exist

UrlClient

// Sends this machine's manifest to the URL
_global.urlClient = function(theURL)

XmlSocketClient (in development)

function XmlSocketClient_connect(location,port)
function XmlSocketClient_disconnect()
function XmlSocketClient_sendData(varName, namespace)

Encryption (in development)

//  Return next random integer between 0 and n inclusive
LERandom.nextInt(n)

// Base64 encodes a string
function base64Encode(str)

// Base64 decodes a string
function base64Decode(str)

CacheManager (in development)

// write the current in-memory dataset to disk
function _cacheManager_writeManifest()


Database

// sets a value
_global._setValue = function(variableName, variableValue)

// gets a value
_global._getValue = function(variableName)

// gets a list of all the variables that have the word subPart in it
_global.getKeyNames = function(subPart)

// returns the access type of a variable
_global.getFieldAccess = function(variableName)

// returns the field's type
_global.getFieldType = function(variableName)