ambiera home ambiera home

Scripting with irrEdit

Scripting in irrEdit is simple. You can write your code directly into the script editor window and press 'execute'. The language used for this is Squirrel, it looks like C, C++ or Java. Error messages and texts written via the 'print' command will be visible in the '3D Engine Log' window. If you want to add a menu or toolbar item which should call a script function when clicked by the user, simply create a autostart script and register your function as menu or tool icon there, as described in editorRegisterMenuEntry or editorRegisterToolbarEntry.


The following routines are available in irrEdit:


Editor related:

editorAddSceneNode
editorFocusPosition
editorGetFileNameFromDialog
editorGetSelectedSceneNode
editorGetSelectedTexture
editorUpdateAllWindows
editorRegisterMenuEntry
editorRegisterToolbarEntry
editorSetSelectedSceneNode


Irrlicht related:

irrAddSceneNode
irrGetChildSceneNode
irrGetRootSceneNode
irrGetSceneNodeChildCount
irrGetSceneNodeFromName
irrGetSceneNodeMaterialCount
irrGetSceneNodeMaterialProperty
irrGetSceneNodeProperty
irrGetSceneNodeType
irrLoadTexture
irrRemoveSceneNode
irrSetSceneNodeMaterialProperty
irrSetSceneNodeProperty
irrSetWorkingDirectory
irrPlayMusic
irrPlaySound


Other:

vector3d - a vector class
Standard Library (basic functions for math, I/O, etc)


editorAddSceneNode(type)
editorAddSceneNode(type, x, y, z)

Creates a new scene node of type (must be a string) at position x, y, z, applies the default editor settings to it, selects it and updates all editor views. This is just like if the user used the 'edit->insert' command from the editor menu. If you simply want to create a scene node in the scene graph just use irrAddSceneNode instead.

The parameter 'type' must be one of these strings:

"cube", "sphere", "text", "waterSurface", "terrain", "skyBox", "shadowVolume", "octTree", "mesh", "light", "empty", "dummyTransformation", "camera", "cameraMaya", "cameraFPS", "billBoard", "animatedMesh", "particleSystem".

x,y,z is the position where the scene node will be created. If not used, the position will be the default editor position.

Returns: The new scene node.

Examples:

local count = 3;
local size = 12;
for (local x=0; x<count; ++x) for (local y=0; y<count; ++y) for (local z=0; z<count; ++z) editorAddSceneNode("cube", x*size, y*size, z*size);
This example will create 27 cubes placed in a hypercube.

editorAddSceneNode("billBoard");
This example will create a billBoard placed directly on front of the 3d camera in the main view.

 


editorFocusPosition(position)

Lets the cameras of all view ports focus the given position.

Example:

editorFocusPosition(vector3d(0,10,20));
Lets all cameras focus the position (0,10,20)

 


editorGetSelectedSceneNode()

Returns the currently selected scene node or 0 if nothing selected.

Example:

local s = editorGetSelectedSceneNode();

if (s) print("Name of the selected node is: '" + irrGetSceneNodeProperty(s, "Name") + "'"); else print("nothing selected");
This example prints the name of the currently selected scene node.

 


editorGetSelectedTexture()

Returns the currently selected texture from the texture manager window.

Example:

local t = editorGetSelectedTexture();
local s = irrAddSceneNode("cube");

irrSetSceneNodeMaterialProperty(s, 0, "Texture1", t);
if (t == "") print("added no texture"); else print("set texture to: " + t );
editorUpdateAllWindows();
Creates a new cube and applies the currently selected texture to it.

 


editorGetFileNameFromDialog()
editorGetFileNameFromDialog(message)
editorGetFileNameFromDialog(message, fileExtensions)
editorGetFileNameFromDialog(message, fileExtensions, isOpenDialog)

Shows a file selection dialog prompting the user to select a file and returns the selected filename or an empty string if the user cancelled.

Parameters:

  • message: Message text displayed in the window caption area.
  • fileExtensions: Possible file extension list, "*.*" by default if not used. The file extension string must be in the wxWidgets used format, like "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif" or "*.mesh;*.xml"
  • isOpenDialog: If true, the dialog presents itself as open file dialog, otherwise as save file dialog. This is true by default.

Example:

local s = editorGetFileNameFromDialog("please select something");

if (s != "")
print ("user selected " + s);
else
print("user cancelled selection");
This example prompts the user to select a filename and prints which file was selected when finished.

 


editorUpdateAllWindows()

Updates all windows of the editor. Same as selecting the command Edit->UpdateAllWindows or pressing F5 in the editor.

Example:

irrAddSceneNode("cube");
editorUpdateAllWindows();
This example creates a new cube without default settings and updates the editor windows to show the new scene node in all windows.

 


editorRegisterMenuEntry(function, text)

Registers a new entry in the menu under 'Tools' using the text provided in the 'text' parameter. When the menu command is selected by the user, the global function provided in the 'function' parameter will be executed.
Please note that editorRegisterMenuEntry only works when executed by a script run in the autostart mode, which means a script placed in the \scripts directory and with a file name starting with 'autostart' and with the extension '.nut'.

Example:

function printHello()
{
print("Hello\n");
}

editorRegisterMenuEntry("printHello", "Print Hello into the log");
Putting this script in a file named for example 'scripts\autostart_printhello.nut' and starting the editor will add a new menu entry into the Tool menu which will print 'Hello'

 


editorRegisterToolbarEntry(function, toolTipText)
editorRegisterToolbarEntry(function, toolTipText, iconBitmap)

Registers a new entry in the tool bar using the tooltip text provided in the 'toolTipText' parameter and an optional icon file. When the toolbar command is clicked by the user, the global function provided in the 'function' parameter will be executed.
Please note that editorRegisterToolbarEntry only works when executed by a script run in the autostart mode, which means a script placed in the \scripts directory and with a file name starting with 'autostart' and with the extension '.nut'.

Example:

function printHello()
{
print("Hello\n");
}

editorRegisterToolbarEntry("printHello",
"Print Hello into the log", "resources\\move.bmp");
Putting this script in a file named for example 'scripts\autostart_printhello.nut' and starting the editor will add a new toolbar icon which will print 'Hello' when clicked

 


editorSetSelectedSceneNode(node)

Sets a selected scene node. Set node to 0 to select nothing.

Example:

local s = irrAddSceneNode("sphere");
editorSetSelectedSceneNode(s);
Adds a scene node and selects it in the editor.

 


irrGetChildSceneNode(parentSceneNode, childIndex)

Returns the child scene node of a parent scene node. ChildIndex must be >= 0 and < irrGetSceneNodeChildCount.

Example:

local root = irrGetRootSceneNode();
local count = irrGetSceneNodeChildCount(root);

for(local i=0; i<count; ++i)
{
local child = irrGetChildSceneNode(root, i);
print("node:" + irrGetSceneNodeProperty(child, "Name") + "\n\n");
}
This example prints the name of all child scene nodes of the root. If you are using this in the editor, please note that more scene nodes will be printed out than visible in the scene graph explorer, because the editor adds invisible scene nodes to the scene graph, for example cameras or arrows and others. You can distinguish these nodes from the editor nodes if it has the property "IsDebugObject" set to true.

 


irrGetRootSceneNode()

Returns the root scene node. You cannot remove it and it does not make a lot of sense to change its attributes, but you can use it as starting point to iterate the whole scene graph. Take a look at irrGetSceneNodeChildCount for an example.

Returns: The root scene node.


irrGetSceneNodeChildCount(sceneNode)

Returns the amount of children of a scene node. Please note that if you call this in the editor, the amount of children can be higher than shown in the scene graph explorer, because the editor adds invisible scene nodes to the scene graph, for example cameras or arrows and others. You can distinguish these nodes from the editor nodes if it has the property "IsDebugObject" set to true.

Example:

local root = irrGetRootSceneNode();
local count = irrGetSceneNodeChildCount(root);

print("Scene nodes in the top level of the scene graph:" + count);
This example will return '6' in the standard scene of the editor altough there are only 2 children of the root (skybox and cube): The editor also added a camera and 3 nodes for the movement arrows.

 


irrAddSceneNode(type)
irrAddSceneNode(type, x, y, z)

Creates a new scene node of type (must be a string) at position x, y, z. Note that this function will create the scene node directly in the engine. The editor won't update automaticly to refelect the changes after this and no default materials will be applied to the scene node. If you want to do so, use editorAddSceneNode instead. Alternatively, you also could call editorUpdateAllWindows after using this method to let the editor show the new scene node at least. The parameter 'type' must be one of these strings:

"cube", "sphere", "text", "waterSurface", "terrain", "skyBox", "shadowVolume", "octTree", "mesh", "light", "empty", "dummyTransformation", "camera", "cameraMaya", "cameraFPS", "billBoard", "animatedMesh", "particleSystem".

x,y,z is the position where the scene node will be created. If not used, the position will be the default editor position.

Returns: The new scene node.

Examples:

irrAddSceneNode("billBoard");
This example will create a billBoard placed at (0,0,0)

irrAddSceneNode("cube", 10, 10, 10);
This example will create a billBoard placed at (10,10,10)

 


irrGetSceneNodeFromName(name)

Searches the whole scene graph for a scene node with this name. Please note that the name is case sensitive. If it is found, it is returned, otherwise null is returned.

Example:

local s = irrGetSceneNodeFromName("testCube");

if (s) print("found node.\n"); 
   else
     print("not found the node.\n")
Searches for a scene node with name 'testCube' and prints some text.

 


irrGetSceneNodeMaterialCount(sceneNode)

Returns the amount of materials of the scene node.

Example:

local s = irrAddSceneNode("cube");
local n = irrGetSceneNodeMaterialCount(s); print("the scene node has " + n + " materials");
irrRemoveSceneNode(s);
Prints the amount of materials in a newly added cube scene node and deletes the scene node afterwards.

 


irrGetSceneNodeMaterialProperty(sceneNode, materialIndex, propertyName)

Returns the property of the material of a scene node.
Parameters:

  • sceneNode: A scene node.
  • materialIndex: The index of the material. Must be a value greater or equal 0 and smaller than irrGetSceneNodeMaterialCount().
  • propertyName: The propertyName in a material. This is also the name displayed in the editor in the left column. Possible values are: "Type", "Ambient", "Diffuse", "Emissive", "Specular", "Shininess", "Param1", "Param2", "Texture1", "Texture2", "Texture3", "Texture4", "Wireframe", "GouraudShading", "Lightning", "ZBuffer", "ZWriteEnable", "BackfaceCulling", "BilinearFilter", "TrilinearFilter", "AnisotropicFilter", "FogEnable", "NormalizeNormals".

Example:

local s = editorAddSceneNode("cube");
local t = irrGetSceneNodeMaterialProperty(s, 0, "Texture1");

print("texture of the new cube is: " + t);
Prints the name of the texture set by the editor in new cube scene nodes. Prints something like 'texture of the new cube is: textures/editor_defaults/default_texture.png'

 


irrGetSceneNodeProperty(sceneNode, propertyName)

Gets the property value of a scene node. The propertyName is also the name displayed in the editor in the left column. Possible names depend on the scene node type, but usually names like 'Type', 'Name', 'Id', 'Position', 'Rotation', 'Scale', 'Visible', 'AutomaticCulling', 'DebugDataVisible' and 'IsDebugObject' are available at least. Please note that the name is case sensitive.

Example:

local s = editorAddSceneNode("cube");

local size = irrGetSceneNodeProperty(s, "Size");
local position = irrGetSceneNodeProperty(s, "Position");
print("Created cube of size " + size + " at " + position);
Prints something like "Created cube of size 10 at (-2.15537, -0.751433, -15.6934)"

 


irrLoadTexture(filename)

Loads a texture into the texture cache. Returns true if sucessful and false if not.

Example:

if (irrLoadTexture("textures/walls/smallmetalpipe_1-1.jpg"))
print("yipee, it worked.");

editorUpdateAllWindows(); // show changes in texture manager window
Loads a texture and ensures the texture window shows the texture.


irrRemoveSceneNode(sceneNode)

Removes the scene node from the scene, deleting it. Doesn't work for the root scene node.

Example:

irrRemoveSceneNode( irrGetSceneNodeFromName("testCube") );
Deletes a scene node with the name 'testCube' if it exists. Call editorUpdateAllWindows(); after this if you are in the editor to reflect the changes.


irrSetSceneNodeMaterialProperty(sceneNode, materialIndex, propertyName, value)

Returns the property of the material of a scene node.
Parameters:

  • sceneNode: A scene node.
  • materialIndex: The index of the material. Must be a value greater or equal 0 and smaller than irrGetSceneNodeMaterialCount().
  • propertyName: The propertyName in a material. This is also the name displayed in the editor in the left column. Possible values are: "Type", "Ambient", "Diffuse", "Emissive", "Specular", "Shininess", "Param1", "Param2", "Texture1", "Texture2", "Texture3", "Texture4", "Wireframe", "GouraudShading", "Lightning", "ZBuffer", "ZWriteEnable", "BackfaceCulling", "BilinearFilter", "TrilinearFilter", "AnisotropicFilter", "FogEnable", "NormalizeNormals".
  • value: New value of the material property

Example:

local s = irrAddSceneNode("cube");
local t = irrSetSceneNodeMaterialProperty(s, 0, "Wireframe", "true");
editorUpdateAllWindows();
Creates a new scene cube node and makes it be displayed in wireframe mode.
 

irrSetSceneNodeProperty(sceneNode, propertyName, value)
irrSetSceneNodeProperty(sceneNode, propertyName, x, y, z)

Sets the property value of a scene node. The propertyName is also the name displayed in the editor in the left column. Possible names depend on the scene node type, but usually names like 'Name', 'Id', 'Position', 'Rotation', 'Scale', 'Visible', 'AutomaticCulling', 'DebugDataVisible' and 'IsDebugObject' are available at least. Please note that the name is case sensitive.

Examples:

local s = irrAddSceneNode("cube");
irrSetSceneNodeProperty(s, "Size", 20);
editorUpdateAllWindows();
Creates a cube scene node and changes its size to 20.

local s = editorAddSceneNode("cube");
irrSetSceneNodeProperty(s, "Rotation", 20, 90, 0);
editorUpdateAllWindows();
Creates a cube scene node and changes its rotation to (20, 90, 0)

 


irrGetSceneNodeType(sceneNode)

Returbs the type of a scene node.

Examples:

local s = irrGetSceneNodeFromName("testCube");
print(irrGetSceneNodeType(s));
Will print 'cube' if there is a cube scene node with the name 'testCube'.

 


irrSetWorkingDirectory(directory)

Change the working directory. This is useful in the editor for example so the engine does not need to stay in the same directory as your application or game. Example: If your application is running in C:\SDKS\irrlicht-1.1\bin\Win32-VisualStudio and is loading all media files from there, then open the scripting window and execute

irrSetWorkingDirectory("C:\\SDKS\\irrlicht-1.1\\bin\\Win32-VisualStudio");

so irrEdit can load all media files as if it where your application. You can also put this line into a file, name it autostart_somename.nut and place it into the 'scripts' directory of irredit, so it will be executed when irrEdit starts up.


irrPlayMusic(musicFilename)

Plays streamed music via the internal sound engine. The music file name should be something like "music.mp3" or "somesong.ogg". Specifying an empty string will stop the music.
(C++ only note: This method will only work if a sound engine has been set for the scene manager using setSoundEngine().)

Examples:

irrPlayMusic("music/music.mp3")
Plays the music sound via the internal sound engine.

irrPlayMusic("")
Stops the music if it is played.

irrPlaySound(musicfilename)

Plays a sound via the internal sound engine. The music file name should be something like "sound.wav".
(C++ only note: This method will only work if a sound engine has been set for the scene manager using setSoundEngine().)

Examples:

irrPlaySound("sounds/finished.wav")
Plays a sound via the internal sound engine.

vector3d()
vector3d(x,y,z)

A class for holding 3 float coordinates - x, y, and z. Also provides helper methods:

  • +, -: Addition and substraction of vectors
  • getLength() for calculating the length
  • normalize() for making the vector length of 1
  • string conversion

Examples:

local v = vector3d();
print(v);
prints (0, 0, 0)

local v1 = vector3d(10,0,0);
local v2 = vector3d(0,20,0);
local v3 = v1 + v2;

v3.normalize();
print(v3 + " Lenght:" + v3.getLength())
prints (0.447214, 0.894427, 0) Lenght:1

 

Other routines available (for details please see the Squirrel Standard Library):

Math: abs(x); acos(x); asin(x); atan(x); atan2(x, y); ceil(x); cos(x); exp(x); fabs(x); floor(x); log(x); log10(x); pow(x, y); rand(); sin(x); sqrt(x); srand(seed); tan(x); PI RAND_MAX

System: clock(); date([time], [format]); getenv(varaname); remove(path); rename(oldname, newname); system(cmd); time();

Strings: format(formatstr, ...); lstrip(str); regexp(pattern); rstrip(str); split(str, separators); strip(str); capture(str, [start]); match(str); search(str, [start]);

Blob: dofile(path, [raiseerror]); loadfile(path, [raiseerror]); writeclosuretofile(destpath, closure); eos(); flush(); len(); readblob(size); readn(type); seek(seek, [origin]); tell(); writeblob(blob); writen(n, type);

I/O: dofile(path, [raiseerror]); loadfile(path, [raiseerror]); writeclosuretofile(destpath, closure);