Arrays in JScript (XSISDK)

Table of contents

Tips regarding the Array object in JScript

Most large JScript scripts will eventually

More documentation

The reference gives a lot of information about arrays,

Jscript Array versus Safearray

The standard format for Arrays in the COM world is the "SAFEARRAY". This type of Array is commonly associated with VBScript so it is often calls a VBArray.

JScript has its own Array object which is easy to use and more object oriented than the VBScript Array API. However only JScript can create or modify this type of array.

JScript arrays are always flat, with only a single dimension, they are similar to a vector class in C++. You can create arrays of arrays to simulate higher dimensions. SAFEARRAYS can be multi-dimensional.

Passing a JScript Array into XSI

XSI can read JScript Arrays, so almost all APIs let you pass a JScript Array instead of a SAFEARRAY. (Internally XSI will convert the array to a SAFEARRAY). This makes it possible to have some pretty convenient syntax in JScript.

For example, the third argument to this command is a JScript array that XSI will automatically turn into a list of objects.

AddCustomOp( "JScriptSplatter",
 [oSphere.ActivePrimitive, oSphere.posy]  ) ;

Getting a JScript Array from XSI

XSI will never construct a JScript Array, so any API that actually returns an array will always return a SAFEARRAY.

JScript offers the VBArray object that makes it possible to read a SAFEARRAY, including a multidimensional array. However this object does not let you modify or create a SAFEARRAY.

A search in the reference for "VBArray" will produce many examples of its use.

Grid Data

The GridData object can be a convenient way to build a 2D SAFEARRAY from within JScript.

Communicating with C++ API

If you return a CValueArray from a C++ custom command it will be turned into a VBScript SafeArray. So you need to use the VBArray object to read its content in JScript.

However the good news is that you can pass a JScript array to a C++ custom command (as an argument) and XSI will automatically convert it to a CValueArray.


On Linux the Array.Push method is not defined, because it was only introduced with version 5.6 of JScript. The workaround is to add this code at the bottom of any script that wants to use that method:

// @cc_on
// @if (@_jscript_version <= 5.5)
var push = function(){
	for( var i = 0; arguments[ i ] != null; i++ )
		this[this.length++] = arguments[ i ];
	return( this );
Array.prototype.push = push;
// @end

This page was last modified 08:02, 31 Aug 2007.
This page has been accessed 14450 times.

© Copyright 2009 Autodesk Inc. All Rights Reserved. Privacy Policy | Legal Notices and Trademarks | Report Piracy