From IrrWizard

Contents 1 Introduction 2 Squirrel Basics 3 Game Engine 4 Game Editor (irrEdit) 5 Functions 5.1 GameManager 5.2 SceneManager 5.3 LevelManager 5.4 SoundManager 5.5 Player 6 Sample Script

Introduction

'Squirrel Script' is used to interface with the game engine. All game logic should be written in Squirrel. Squirrel is a high level imperative/OO programming language, designed to be a powerful scripting tool that fits in the size, memory bandwidth, and real-time requirements of applications like games.

Squirrel Basics

For a full list of the features, and an extensive guide to the Squirrel scripting language, visit the Squirrel Website A Squirrel script can be created in notepad and has the extention .nut. The following code will print out 'hello world' in the dos console, ALT+TAB when running the game.

print("hello world"); 

To define a variable, the keyword 'local' is used:

local myNum = 0;
local myString = "hello world";
local myBool = true;

To test for a condition, the 'if' keyword is used:

local myBool = true;

if (myBool)
{
    // code here	
}

Functions can be created in Squirrel as follows:

function OpenDoor(door_ID)
{
    // code here	
}

And called using:

// Open door, name defined in editor
OpenDoor("door_level1");

Game Engine

The game engine uses Managers to handle the various area's of functionality. The main controlling class being the 'GameManager', which in turn calls other Managers, for example SoundManger, LevelManager, SceneManager etc. The scripting system is structured in the same fashion to mirror this. The main point of entry is the GameManager which is refered to as 'gm' within the scripting system. The following classes have been exposed to the scripting system:

GameManager

SceneManager

LevelManager

SoundManager

Player

Each level should be in it's own 'level' folder contained in the 'media' folder of the game project. Inside each level folder should be a 'scripts' folder that contain the squirrel scripts for that level. The Game Engine will expect the following scripts to be present: level_init.nut (Called once when the level loads) level_update.nut (Called each frame during level) level_clear.nut (Called once when level exits) A global script exists in the media/scripts folder called global.nut. Functions defined here are available to all other scripts.

To gain access to functions exposed by the Managers, getting at these can be scripted as follows:

gm.getSceneManager();
gm.getLevelManager();
gm.getSoundManager();
gm.getPlayer();
       

Game Editor (irrEdit)

The game level editor is irrEdit. And allows game assets, level meshes, placeables, particle effects, lightmapping to be modified in realtime using a WYSIWYG editor. An important concept to understand is that both the editor and engine refer to game objects or entities as 'nodes'

In the editor, any game object or node that needs to be exposed to the scripting system, has to have the name property of it's node filled in. For example the 'door' object in the editor will have it's name set to "door". Then you can gain access to the door in the script by specifiying it's name. "door"

Functions

Here are a list of the functions currently exposed to the scripting system, more will be added as part of an ongoing process.

GameManager

getSceneManager - Allows access to the Scene Manager

SceneManagerInterface getSceneManager()

gm.getSceneManager(); 

getSoundManager - Allows access to the Sound Manager

SoundManagerInterface getSoundManager()

gm.getSoundManager(); 

getLevelManager - Allows access to the Level Manager

LevelManagerInterface getLevelManager()

gm.getLevelManager(); 

getPlayer - Allows access to the Game Player

PlayerInterface getPlayer()

gm.getPlayer();

SceneManager

setCurrentNode - Sets the current node, all subsequent function calls from the SceneManager interface will refer to this node until the current node is changed.

bool setCurrentNode(string name)

gm.getSceneManager().setCurrentNode("door"); 

getCurrentNode - Gets the current node.

int getCurrentNode()

local node = gm.getSceneManager().getCurrentNode(); 

getPosition - Gets the position of the current node as a vector3. A point in 3D space X, Y, Z

vector3 getPosition()

local pos = gm.getSceneManager().getPosition(); 

getRotation - Gets the rotation of the current node as a vector3

vector3 getRotation()

local rot = gm.getSceneManager().getRotation(); 

getScale - Gets the scale of the current node as a vector3

vector3 getScale()

local scale = gm.getSceneManager().getScale(); 

getDistance - Gets the distance from the current not to the specified target nodes position, which should be a vector3, for exampe the players position

int getDistance(vector3 position)

local dist = gm.getSceneManager().getDistance(gm.getPlayer().getPosition()); 

getCameraPosition Gets the position of the camera as a point in 3D space, vector3

vector3 getCameraPosition()

local pos = gm.getSceneManager().getCameraPosition();

getCameraRotation Gets the rotation of the camera as a vector3

vector3 getCameraRotation()

local rot = gm.getSceneManager().getCameraRotation(); 

getCameraTarget Gets the vector3 position of where the camera is looking at in 3D space

vector3 getCameraTarget()

local target = gm.getSceneManager().getCameraTarget(); 

getFrameNr Gets the current frame number of the current animation playing

int getFrameNr()

local target = gm.getSceneManager().getFrameNr(); 

moveNode() Moves the current node. 1st parameter is dirrection, second distance, and third is speed. The speed and distance are arbitary values, the best way to get to desired distance and speed is to experiment with these numbers. The values supplied opens door upwards by approx the distance of the door itself, and quite slowly. 1 FORWARDS 2 BACKWARDS 3 UP 4 DOWN 5 RIGHT 6 LEFT

bool moveNode(int direction, int distance, int speed)

// moveNode(direction, distance, speed) 
gm.getSceneManager().moveNode(3, 300, 10000); 

bool setPosition(vector3 position)

bool setRotation(vector3 rotation)

bool setScale(vector3 scale)

bool setFrameLoop(int begin, int end)

bool setFrameType(int type)

bool setCameraTarget(vector3 target)

Flag1

Flag2

Flag3

Flag4

Flag5

Activated

AnimationEnd

LevelManager

bool loadLevel(string levelName, vector3 position)

bool loadScene(string sceneName, vector3 position)

bool loadSkyBox(string up, string, down, string left, string right, string forward, string backward)

void setFog(int RED, int BLUE, int GREEN, int ALPHA, int density)

SoundManager

bool playSound(stirng sound)

bool playSong(string song)

void stopSong()

Player

vector3 getPosition()

int getHealth()

void setHealth()

bool isJumping()

bool isRunning()

bool isAction()

bool setDebug()

Sample Script

Below is a sample script that opens a door (level_update.nut)

// set the current node to the door
gm.getSceneManager().setCurrentNode("door");

// Open door using static mesh, and moveNode function
// 1 = FORWARDS 2 = BACKWRDS 3 = UP 4 = DOWN 5 = RIGHT 6 = LEFT
// If player gets close enough the door will activate 
if (gm.getSceneManager().getDistance(gm.getPlayer().getPosition()) < 5000) 
{
       // play the animation of the lever
       gm.getSceneManager().setFrameLoop(3000, 7000);

       // play sound effect
       gm.getSoundManager().playSound("media/sounds/portcullis_open.wav");

       // moveNode(direction, distance, speed) 
       gm.getSceneManager().moveNode(3, 300, 10000);
      
       print("door open");
}