Meteor 2 Script Commands

Sets the texture of a sector on the map.  SectorId is the sector's ID number to change, TextureName is the filename of the texture (with no path).  Holding a mouse over a sector (while in Sector Mode) will display that sector's ID number.

Example
SC_SetSectorTexture(1,"grass01.pcx");

Return's the specified sector's texture name as a string.

Example
char *TextureName[256];
strcpy( TextureName, SC_GetSectorTexture(10) );
SC_MessageBox("Sector 10's texture is %s", TextureName);

Sets a sector's hidden flag.  When a sector is hidden it effectively does not exist within the game.  inSectorId is the ID number of the sector to change, value can be 1 for hidden or 0 for not hidden.

Examples
SC_SetSectorHidden(10,1);     // Hides sector ID 10
SC_SetSectorHidden(10,0);     // Shows sector ID 10

Once a sector trigger is used it is disabled by default (so it won't run again).  Using this function a sector's trigger can be re-enabled (or disabled for that matter).

Notes
Setting a sector's required item in the Map Editor also affects if scripts are run (this is not for doors only).

Example
if( SC_GetItemCount("Hot Dinner") < 300)
{
    SC_GameMessage("You need 300 hot dinners to make this script work!");

    // re-enable this trigger for next time
    SC_SetSectorTriggerEnabled(10,1);
}

Gets the status of a sector's event trigger.

Example
int x;
x = SC_GetSectorTriggerEnabled( 10);    // get the enabled status of the script trigger for sector ID 10

Opens a door sector just  as if the player had walked into it.  This is really handy for as it allows objects on waypoints to open doors.  If you attempt to run this on a non-door sector then it will abort automatically.

Notes
There is currently no way to close a door.

Sets a sectors damage (acid).

Example
SC_SetSectorDamage(10,5);

Gets a sectors damage (acid).

Return Values
Returns the sectors acid damage value.  If the sector was not found then this function will return 0.

Example
int x;
x = SC_GetSectorDamage(10); // returns the damage value for sector id 10

Sets a sector's damage interval (acid).  100=1 second and 50=0.5 seconds and so on.

Example
SC_SetSectorDamageInterval( 10, 100); // sets the damage interval of sector 10 to 1 second (100 milliseconds)

Gets a sectors damage interval.

Return Values
Returns the sectors acid damage interval.  If the sector was not found then this function will return 0.

Example
int x;
x = SC_GetSectorDamageInterval(10); // returns the damage interval for sector id 10

Adds a new game object and returns the new object's ID.

Parameters
ObjectName = the filename of the object (i.e. "sheep.ob").
PosX and PosY = the map coordinates to place the object.
angle = the angle the object should face (use -1 for random angle)
AiType = the AI type the object should use, these are defined as constants (AI_ROAMING, AI_GUARDING, AI_NONE or AI_IDLE).
side = the side ID for the object (refer to base\game.ini for side numbers).
OverrideName = the name you want to give this object (like "Tom" or "Jerry").  Just pass an empty string "" to inherit the race name.
moving = If this object is moving then use 1 else 0.
locked = set to 1 to lock the vehicle (if applicable), else 0.
MultiplayerRespawn = This object respawns in multiplayer.

Return Values
This function returns the ID number of the new object.  There is no way of telling that it actually worked (i.e. if the map was full of objects already!).

Example
SC_AddObject("sheep.ob", 100, 100, -1, AI_ROAMING, 0, "Larry the Lamb", 1, 0);

Binds a game object to a waypoint.  ObjectId is the ID of the game object, WaypointId is the ID of the map waypoint.

Return Values
Returns 1 on success or 0 if an error occoured

Example
SC_BindObjectToWaypoint(10,2);     Binds object ID 10 to waypoint ID 2

This function works in exactly the same way as SC_BindObjectToWaypoint (above) except that the object is soft bound.  Soft bound objects are released (unbound) from their waypoints if they get stuck.

Sets an object's hidden flag.  When an object is hidden it effectively does not exist within the game.  ObjectId is the ID number of the object to change, value can be 1 for hidden or 0 for not hidden.

Examples
SC_SetObjectHidden(10,1);     Hides object ID 10
SC_SetObjectHidden(10,0);     Shows object ID 10

Gets the hidden status of an object.

Return Values
1 = hidden, 0 = not hidden or object not found

Example
x = SC_GetObjectHidden( 10); // gets the hidden status of object ID 10

This function shows an object in a similar way to using SC_SetObjectHidden(???,0); except that the object appears to teleport (plays directional teleport sound and applies teleport damage to the landing area).

Note that you do not need to call SC_SetObjectHidden(??,0); as well as this function.

Example
SC_ShowObjectTeleport(10);     Shows object 10 with that "teleport in" effect.

Gets the side number for the specified object. See SC_SetObjectSide below for an explanation of sides.

Sets the side number of an individual object.  ObjectId is the id of the object to change, value is the side value to set.  See base\game.ini for a list of side numbers, these are generally as follows:

0 = Neutral
1 = Allies
2 = Enemy
3 = GNV
4 = ROD

Example
SC_SetObjectSide(1,2);    changes the side of object 1 to Allies

Gets the map coordinates for the specified object.  ObjectId is the ID of the object, x and y are 2 integer pointers that will be populated with the object's coordinates when this function is called.

Example
int PosX, PosY;
SC_GetObjectCoords( 10, &PosX, &PosY);   // The variables PosX and PosY now contain object ID 10's coordinates.

Sets the map coordinates of an object.  ObjectId is the ID of the object to set, x and y are the new coordinates.  Note that map coordinates are shown in the Map Editor status bar when moving the mouse over the terrain window.

Example
SC_SetObjectCoords( 10, 1000, 1000);   // Move object ID 10 to coordinates 1000,1000.

Returns the angle of the specified object.  ObjectId is the ID of the object, the angle value is returned by this function.  Note that angles range from 0 to 255 with 64 representing a right angle etc.

Example
int angle;
angle = SC_GetObjectAngle( 10);   // The variable angle now contains the object ID 10's angle.

Return Value
The object's angle (between 0 to 255).

Sets the angle of the specified object.  ObjectId is the object to affect, angle is the new angle.  Note that angles range from 0 to 255 with 64 representing a right angle etc.

Example
SC_SetObjectAngle( 10, 128);   // Face object ID South.

Gets the number of hits an object has.  An object's hits value (or current health).  ObjectId is the ID of the object, the hits value is returned by this function.

Example
int hits;
hits = SC_GetObjectHits( 10);    // The variable hits now contains object ID 10's hits value.

Return Value
The object's current hits (health).

Set's an objects hits (health).  ObjectId is the ID of the object to affect, value is the new hits value.

Example
SC_SetObjectHits( 10, 100);  // Set object ID 10's hits to 100.

Returns the value of an object's indestructible flag.  Returns 1 if the object is indestructible, else 0.

Example
int x;
x = SC_GetObjectIndestructible(10);    // The variable x now contains object ID 10's indestructible flag.

Return Value
The object's indestructible flag.

Sets an object's indestructible flag, set value to 1 to make an object indestructible or 0 or destructible.

Note that making predefined indestructible objects (like drain covers) destructible may cause problems as their hits are set to -1.  However this is fine for objects which were set as indestructible earlier in a script.

Example
SC_SetObjectIndestructible(10,1);    // Make object 10 indestructible.

Gets an object's current speed.

Example
x = SC_GetObjectCurrentSpeed(10);

Set's an object's current speed.

Example
SC_SetObjectSpeed(10,4); // sets object 10's speed to 4

Returns an object ID's max speed value.

Example
int x;
x = SC_GetObjectMaxSpeed( 10);

Return Value
The object's current maximum speed.

By default each game object's max speed is inherited from its "speed" value in the Object Editor.  This function allows this value to be set on a per game object basis.  Therefore a particular game object can move faster or slower than its normal speed.  Set value to the desired value.

Example
SC_SetObjectMaxSpeed( 10, 3);     // Object id 10 now moves at 3 pixels per game cycle.

Returns the default max speed of an object.  This is handy if you want to reset an object's speed after previously changing it.  ObjectId is the ID of the object.

Examples
int x;
x = SC_GetObjectDefaultMaxSpeed( 10); // get default speed of object ID 10
SC_SetObjectMaxSpeed( 10, x);  // set object ID 10's speed back to default

...or to set the default speed in a single line...

SC_SetObjectMaxSpeed( 10, SC_GetObjectDefaultMaxSpeed(10) );

Gets an object ID's AI type.  Return values are either AI_NONE, AI_ROAMING, AI_GUARDING or AI_IDLE.  If the object is not found then AI_NONE is returned.

Example
int x;
x = SC_GetObjectAiType( 10);

Return Value
The object's AI type (AI_NONE, AI_ROAMING, AI_GUARDING or AI_IDLE).

Sets an object ID's terrain type.  ObjectId is the id of the object, value can be AI_NONE, AI_ROAMING, AI_GUARDING or AI_IDLE (these are defined as constants).

Example
void SC_SetObjectAiType( 10, AI_ROAMING);   // Put object ID 10 in roaming AI mode.

Gets the locked status of a vehicle (locked vehicles can not be entered by the player), ObjectId is the ID of the object to check.

Example
int IsLocked;
IsLocked = SC_GetObjectLocked( 10); // gets locked status of object ID 10

Sets the locked status of a vehicle (locked vehicles can not be entered by the player), ObjectId is the ID of the object to check, value is the "locked" flag (1 = locked, 0 = unlocked);

Notes
An object's initial locked status can be set in the Map Editor (Object Properties), this routine allows this locked status to be changed at runtime.

Example
SC_SetObjectLocked( 10, 0); // unlocks object ID 10

Gets the active status of an object.  By default objects become active when they are first drawn. Non active objects do not attack, are not targeted and are not displayed on the minimap.

Return Values
1 = object is active
0 = object is not active or does not exist

Example
int IsActive;
IsActive = SC_GetObjectActive( 10); // gets the active status of object ID 10

Sets the active status of an object.  Object ID is the object to affect, value is either 1 or 0 (active or not active).

Notes
See SC_GetObjectActive for an explanation of what "active" means.

Example
SC_SetObjectActive( 10, 1);  // make object ID 10 active

Gets the an object's "NoTarget" value.

While NoTarget is set to 1 the object will not be attacked, the default is 0.

Sets and object's "NoTarget" value.

While NoTarget is set to 1 the object will not be attacked, the default is 0.

Determines whether an object exists (destroyed objects do not exist).

Return Values
0 = The object does not exist or has been destroyed
1 = The object exists and has not been destroyed

Example
if( SC_ObjectExists(10)  == 0)
{
    SC_GameMessage("Object Id 10 does not exist OR has been destroyed"); 
}

Attaches an object to another object.  The "rider" object will sit on top of the "horse" object.  If the horse object has weapons then those will be used instead of the rider's weapons.

Notes
Do not use this for the player object, use SC_PlayerGetInVehicle instead (M2 knows which objects are ride on and will deal with it).

If another object is already riding the "horse" object then they will be killed!

Example
SC_PutObjectOnHorse(1,10); // puts player ID 1 on top of object ID 10

Detaches and object from a ride on object.  If the "rider" object is not riding an object then nothing will happen.

Example
SC_KickObjectOffHorse(10); // player ID 10 gets off their horse!

Makes the specified object bleep their horn.  This is not appropriate for non vehicle objects!

Gets an object type name from a type number.

Notes
Object type numbers are used by some events, such as OnObjectTypeEnter and OnObjectTypeExit.
If the object type is not found then an empty string is returned, i.e. "".

Example

void MyCode()
{
    char ObjectFilename[256];

    strcpy( ObjectFilename, SC_GetObjectTypeName(10) );
    SC_GameMessage("The object type filename for object type 10 is %s", ObjectFilename);
}
 

Gets an object type number for an object filename.

Notes
Object type numbers are used by some events, such as OnObjectTypeEnter and OnObjectTypeExit.
If the object type is not found then 0 is returned (0 is always the "default" object so you can check for it).

Example

void MyCode()
{
    int TypeNumber;

    TypeNumber = SC_GetObjectTypeNumberForName("ChinookHelicopter.ob");
    SC_GameMessage("The object type number for a Chinook is %d", TypeNumber);
}

Tells an object to follow (or stop following) another object.  This function is self explanatory.  Pass ObjectToFollowId as -1 to tell an object to stop following another object.

Resets an object's respawn coordinates to its current location.  This is handy if you have moved an object and want to respawn from the new location rather than its placement coordinates.  This only applies to multiplayer respawning objects (generally vehicles in multiplayer).

Adds a new sprite to the map at the specified x and y coordinates.

SpriteName = the sprite filename (i.e. "objects\\car11_Still.spr")
PosX and PosY = the x and y coordinates for the sprite to appear on the map (aligned to top left of sprite)
angle = the sprite's angle of rotation (this ranges from 0-255 with 64 representing a right angle and so on)
side = the side id of the sprite (this alters the sprites colouring)

Return Values
This function returns the ID of the new sprite.

Example
SC_AddSprite( "objects\\car11_Still.spr", 100, 100, 128, 0);

Sets the hidden flag value of a map sprite (set 1 for hidden, 0 for not hidden).

Example
SC_SetSpriteHidden( 10, 1); // hide sprite 10

Gets the hidden flag value of a map sprite.

Example
int value;
value = SC_GetSpriteHidden(10);

Puts the player "inside" the specified game object.  The object must be an empty vehicle otherwise this function may fail.    The real player object will be hidden accordingly (this function deals with everything).

Example
SC_PlayerGetInVehicle(10);   // The player gets in object ID 10.

Exits the player from the current vehicle.  If the player is not in a vehicle then this will fail.

Set PlaceInCentre to 1 to put the player in the centre of the vehicle (handy if you are hiding the vehicle in the same code block).

Set PlaceInCentre to 0 to allow Meteor to find a suitable place nearby to put the player.  Be warned that if no place can be found then this function may fail (using a value of 1 does not have this pitfall).

Example
SC_PlayerGetOutOfVehicle(1);  // Get out the current vehicle placing the player in the centre of the vehicle's coords.

If the player is in a vehicle then this function returns 1, else it returns 0.

Example
int x;
x = SC_IsPlayerInVehicle();

Changes the player object to the specified "ObjectId".

Notes

• The new object must be present on the map.
• To change the object type (without having a new object on the map) add an object first (see example below).
• This changes the real player object id (it won't change the current vehicle).
• In multiplayer this changes the ID of the player who triggered the script.
• Health is set to that of the new object.
• The old player object is hidden.
• The AI type for the new object will be set to AI_ROAMING.
• The side for the new object will be set to the player's side.

Examples

Change to another object on the map
SC_SetPlayerObjectId(10);

Change object type only (add a new object on the fly)
void ChangeToSheep()
{
    int x, y;
    int NewObjectId;

    // get player coordinates
    SC_GetObjectCoords( SC_GetPlayerObjectId(), &x, &y);

    // add new sheep object at coordinates
    // note that the AI type and side values will be changed when calling SC_SetPlayerObjectId
    NewObjectId = SC_AddObject( "sheep.ob", x, y, 0, AI_ROAMING, SIDE_NEUTRAL, "Just another sheep", 0, 0, 0);

    // bind the player to the new sheep object (the old player is hidden automatically)
    SC_SetPlayerObjectId( NewObjectId);
}

Returns the object ID of the player.  Note that if the player is in a vehicle then the vehicle's ID will be returned so be careful.

Example
int x;
x = SC_GetPlayerObjectId();

Disables or enables player interaction.  When interaction is enabled the "E" key works.  Use this function to control whether or not the "E" key can be used.

Notes
Player interaction is enabled by default at the start of every map.

Parameters
Pass value as 1 to enable player interaction (the default behaviour).
Pass value as 0 to disable player interaction.

Example
SC_SetPlayerInteractionEnabled(0); // disables the E key

Gets the current player interaction value.

Return Values
1 = Player interaction is enabled (the "E" key will work).
0 = Player interaction is disabled (the "E" key will not work).

Example
void ShowInteractionStatus()
{
    int act;

    act = SC_GetPlayerInteractionEnabled();

    if( act)
        SC_GameMessage("The E key is currently enabled");
    else
        SC_GameMessage("The E key is currently disabled");
}

Shows a message dialog box during the game.  MessageText is the text to display in double quotes.  The ",..." (for people who know a bit of C) means that you can pass a "printf" style formatted string.

Examples
SC_MessageBox("Click Ok to continue");
SC_MessageBox("a = %d, str = %s", a, str);

Like SC_MessageBox except that the message appears in a hint on the screen without interrupting the game.  The message is also echoed to the game console.

Example
SC_MessageBox("Press E to get in and out of vehicles");

Like SC_MessageBox and SC_GameMessage except that the message appears in the corner of the screen.  The message is also echoed to game console.

Example
SC_ConsoleMessage("Picked up a first aid kit");

Shows a string input box and returns the string entered.

Parameters
string = a pointer to a "char" buffer of at least MaxLen bytes in length.
MaxLen = the max length of the string in bytes.
caption = The caption to display (can be "printf" style formatted).

Example
char MyString[32];
int result;
result = SC_StringInputBox( MyString, 32, "Please type in your dog's name");

Return Value
0 = user pressed cancel, 1 = user pressed OK

Shows a yes/no dialog and returns the choice selected by the user.

Parameters
caption = The caption to display (can be "printf" style formatted).

Return Value
0 = user pressed no, 1 = user pressed yes

Creates a new toolbar.  Toolbars can be placed anywhere on the game screen and can contain any number of buttons.  A script trigger can be placed behind each button.  Toolbars are visible until they are destroyed using SC_DestroyToolbar.

Up to 5 toolbars may be used at any one time.  These are accessed by a toolbar number ranging from 0 to 4 (not 1 to 5).

Parameters
ToolbarNumber = The toolbar's number from 0 to 4
title = The title displayed above the toolbar
x and y = The initial screen coordinates of the toolbar
docked = The docked flag, 1 means the user can not move the toolbar, 0 means they can.
LocalOnly = Set to 1 for the toolbar to only appear on the activating player's machine during multiplayer games.  Set to 0 to appear on all machines.  This value is essentially ignored in single player games.

Return Values
1 = success, 0 = fail

Notes
Toolbars will not be displayed until one or more buttons have been added using SC_AddToolbarButton.

Example
SC_CreateToolbar( 0, "This is my toolbar", 10, 20, 1);

Destroys the specified toolbar and stops its being drawn.

Parameters
ToolbarNumber = The toolbar's number from 0 to 4
LocalOnly = (see SC_CreateToolbar)

Notes
You don't need to worry about destroying any toolbars/buttons at the end of the map as Meteor will deal with this for you.

Example
SC_DestroyToolbar(0);

Adds a new button or separator to the end of a toolbar.

Parameters
ToolbarNumber = The toolbar's number from 0 to 4
caption = The text for the button (displayed in a mouse tip)
ImageFilename = The button's icon image, this is the filename of an image in the base\images folder (i.e. "objects\\sheep01_01.pcx")
TriggerText = The code to run when this button is pressed, this is exactly the same format as a sector trigger.
LocalOnly = (see SC_CreateToolbar)

Notes
All images are resized down to 18 by 18 no matter what their original dimensions.

Examples (add buttons)
SC_AddToolbarButton( 0, "Button 1", "objects\\sheep01_01.pcx", "run BuySheep");
SC_AddToolbarButton( 0, "Button 1", "objects\\sheep01_01.pcx", "SC_GameMessage(\"baa\");");

Example (add seperator)
SC_AddToolbarButton( 0, "", BUTTON_SEPERATOR, "");

Plays the specified effect name.  The effect name is the relative path of a wave file from the "base\soundfx" directory with no numbers on the end, for example "world\\thunder" (it is important to use \\ and not \ in paths).

Example
SC_PlaySound("races\\birds");

Note that birds1.wav, birds2.wav and birds3.wav will actually create a single sound effect called "birds".  Whenever this effect is played Meteor will pick a random sample from the 3 wav files.

Gets a number for the specified sound effect, this is required if you cant to use SC_PlayDirectionalSoundNumber.

Parameters
EffectName is the sound effect name, for example "world\\thunder".

Return Values
This function returns the sound effect number, if the sound effect is not found then it returns -1.

Example
See the examples for SC_PlayDirectionalNumber below.

Plays a sound from the given map coordinates, also supports looping.

Parameters
SoundNumber is the sound effect number, use SC_GetSoundNumberForName to get this.
x and y are the specified map coords (the sound will fade according to the players location.
InstanceId is used for looping, see the "Looping" notes below.

Looping
To not loop a sound pass InstanceId as NULL (see example below).
To loop a sound keep calling the function as often as you can and pass the same InstanceId string (this can be almost anything you like as long as its unique).  Once the function calls stop the sound will stop too (after a couple of seconds).  Setting up a looping system using script could be tricky as the game needs to run between script actions.

Non looping Example

void MyCode()
{
    SoundNumber = SC_GetSoundNumberForName("world\\thunder");
    SC_PlayDirectionalSound( SoundNumber, 100, 100, NULL);
}

Looping Example

#include "meteor2"

export OnMapStart;
export MyCode;

#define FLAG_ALARM_SOUND 0 // use the first static flag

void OnMapStart()
{
    // store our sound number
    StaticFlags[FLAG_ALARM_SOUND] = SC_GetSoundNumberForName("world\\alarm_d");
}

// call this a lot!
void MyCode()
{
    SC_PlayDirectionalSound( StaticFlags[FLAG_ALARM_SOUND], 100, 100, "MyAlarmSound01");
}

Notes
Use an element of the StaticFlags array to store your sound numbers as scripting does not support global variables due to limitations of SeeR.

Stops the current music (if playing) and plays a music track (looping).  The inMusicFilename can be the filename of a music file in the "music" folder (looks in mod folder first) or a full path to a music file elsewhere (not much use if you are deploying your map).

Supported file formats are MP3, IT, S3M, XM and MOD.

Examples
SC_PlayMusic("1996.mod");
SC_PlayMusic("c:\\MyMusic\\Some Great Band\\Some Great Band - Some Great Track.mp3");

Starts playing the current track from the beginning.

Example
SC_Music_SeekToStart();

Stops and unloads the current playing music track.

Example
SC_StopMusic();

Moves back 5 seconds.

Example
SC_Music_MoveBackwards();

Moves Forward 5 seconds.

Example
SC_Music_MoveForwards();

Pauses or resumes the current music.

Example
SC_TogglePauseMusic();

Gives or takes away a specified amount of a certain item from the player.

Examples
SC_GiveItem("Red Access Card",1);    // Gives the player a Red Access Card
SC_GiveItem("God Mode",15);    // Gives the player 15 seconds of God Mode
SC_GiveItem("Hit Point",-15);     // Takes 15 health away from the player

Notes
This can be used for weapon items too, simply refer to the list of item names in the Items Editor.  It is safe to use this function if you are not sure the player has something as Meteor won't let the item amount drop below zero.

Gets the amount the player has of an inventory item.

Example
int x;
x = SC_GetItemCount("Yellow Keys");  // gets the number of Yellow Keys the player has

Notes
See the Items Editor for a list of item names.

Resets the player's items.

If LocalItemsOnly is set to 0 this will totally wipe out the player's items as if they were starting a new game.  This is suitable for using at the beginning of some missions.  Be careful with this as taking items away can lead to bad feeling and a loss of interest (due to a lack of game progression).

If LocalItemsOnly is set to 1 only level specific items (like keys and god mode etc) will be reset.

Example
SC_ResetAllItems(1);    // Resets all keys and other level specific items.
SC_ResetAllItems(0);    // Resets all items as if the player was starting a new game.

Shows the in-game Personal Messages viewer.   By default the newest (top) message is displayed in the right hand panel.

Example
SC_ShowPda();

Adds a message to the Personal Messages list, subject is the message subject and message is the message body.  Meteor will automatically wrap the message to the window.

Example
SC_AddPdaMessage( "Mission Info", "Beat all the enemy and complete the level");

Like SC_AddPdaMessage except the message text is loaded from the map's briefing file.

SectionName is the name of the section in the briefing file (don't add the [] braces!).
ShowPda tells Meteor whether to automatically display the PDA once the message has been added.  Set to 1 to show the PDA or 0 to simply display a "New PDA Message" notification message.

Note that the subject is included in the briefing file.  Read this for more information about briefing files.

Example
SC_LoadPdaMessage( "GeneralBriefing", 1);   // adds the briefing in section "GeneralBriefing" and opens the PDA viewer.

Removes a single PDA message.

Example
SC_RemovePdaMessage( "Mission Info");

Empties the entire Personal Messages list.

Example
SC_ClearAllPdaMessages();

Ends the current mission and progresses to the next level.

Example
SC_EndCurrentLevel();

Pauses script execution and wait for hunds/100 sec before proceeding.

Example
SC_Wait(100);   // Wait 1 second.

Sets a side's SideId.  Sides with the same SideId will not attack each other.  SideNumber is the number of the side (see table below).  SideId is the SideId value to set.

You should refer to base\game.ini for side numbers.  Generally these are as follows:
0 = Neutral
1 = Allies
2 = Enemy
3 = GNV
4 = ROD

Side Ids are generally as follows:
Neutral = 0
Allies = 1
Enemy = 2
GNV = 2
ROD = 2

By default the Enemy, GNV and ROD sides have the same SideId value (2) meaning that they are allies.

Example
SC_SetSideId(4,100);      // Sets ROD's side id to 100 thus breaking their allegiance with Enemy and GNV.

Notes
In base\game.ini you will notice that the Neutral side has "target" set to 0.  This means that neutral objects will not target other objects AND that they will not be targeted.

Runs a map with no "Mission Completed" message and without changing the music or mission number.  The filename parameter is the map's filename, no path information is required and the the .map map extension may be omitted.

Note that if you are running a mod then Meteor will look in the mod\maps folder before looking in base\maps.

Example
SC_RunMap("01_01_SwallowLake");

Returns a random number, the lower and upper parameters represent the range of the number to be returned.

Example
int x;
x = SC_Random( 10, 20); // set x to a random integer value between 10 and 20

Notes
The result is >= lower or <= upper.  Lower should always be less than upper else you will get unexpected results lol!

Passes the string "string" to the game console.

Examples
SC_PassToConsole("god");
or
SC_PassToConsole("ScriptSymbols");

Notes
Script commands can be run from the Meteor console using "run FunctionName" just like from in a sector tag.  Be careful when passing a "run ????" console command using this function else you could get stuck in a loop.

Plays an animated gif animation from the "base\clips\" folder.  filename is the filename of the animation (i.e. "intro.gif"), SoundName is the name of the sound to play (i.e. "world\\thunder").  If no sound is required then enter the SoundName as NULL.

Examples
SC_PlayMovieClip("intro.gif","misc\\intro");
SC_PlayMovieClip("intro.gif",NULL);

Adds an explosion at the specified coordinates.  An explosion applies damage to the rectangular area defined by x, y, w, h.

Parameters
x, y = The top left coords of the damage area rectangle.
w, h = The width and height of the damage area rectangle.
damage = The amount of damage to apply to objects within the damage rectangle.
OwnerObjectId = The owning object of this explosion (this object will not take damage), use -1 for none.

Example
SC_AddExplosion( 10, 10, 100, 100, 40, -1);

This is a very quick way to open a forcefield.  Normally opening a forcefield would involve drawing a passable sector underneath the forcefield and hiding the forcefield sector.

This function removes the need for that process (it converts your sector for you), it basically does the following:

• Plays an "open forcefield" sound,
• Changes the sector's texture to "FF_Used.pcx".
• Changes the sector's passable type to "passable".
• Changes the sector's bevel to "flat".
• Updates the internal passable map and minimap.

SectorId is the id of the sector to change.

Example
SC_OpenForcefield( 10);   // opens forcefield sector 10

Like SC_OpenForcefield except this takes flat passable sector and turns it into a forcefield.  The texture name for the actual forcefield needs to be specified.

Be careful with this function, especially on multiplayer maps.

This function will be called when the map is first run, it is called just before play begins.

Name Rules
This function's name does not change.

Parameters
This function does not contain any parameters.

Example
void OnMapStart()
{
    SC_GameMessage("The OnMapStart event has been run!");
}

This function is called when object ID ??? gets hurt, this will not be called when healing an object.

Name Rules
??? represents the object ID, for example to run a function when object 10 is hurt call the function OnObjectHurt_10.

Parameters
This function does not contain any parameters.

Example (runs when object ID 10 is hurt)
void OnObjectHurt_10()
{
    SC_GameMessage("Ouch");
}

This function is called when object ID ??? dies.

Name Rules
??? represents the object ID, for example to run a function when object 10 dies call the function OnObjectDie_10.

Parameters
This function does not contain any parameters.

Example (runs when object ID 10 gets killed)
void OnObjectDie_10()
{
    SC_GameOver("A critical unit was killed!");
}

This function is called when an object reaches a specified waypoint.

Name Rules
??? represents the waypoint ID, for example to run a function when waypoint ID 2 is reached call the function OnWaypointReached_2.

Parameters
The ObjectId parameter will be populated with the ID of the object that reached this waypoint (this can be real handy).  Of course this value does not have to be used (but the parameter does need to exist).

Notes
As event triggers can run more than once this function can be very useful for recurring events.

Example
void OnWaypointReached_2(int ObjectId)
{
    if( ObjectId == 10)
    {
         // send object ID 10 up the North track
         SC_BindObjectToWaypoint( ObjectId, 20);
    }
    else
    {
        // all other objects go South
        SC_BindObjectToWaypoint( ObjectId, 30);
    }
}

This function is called when the player enters the specified vehicle.

Name Rules
??? represents the object ID of the vehicle, for example to run a function when the player gets in object ID 10, call the function OnEnterVehicle_10.

Parameters
This function does not contain any parameters.

Notes
The kick the player out a vehicle use the SC_PlayerGetOutOfVehicle.

Examples
void OnEnterVehicle_10()
{
    SC_GameMessage("Press H to use the hooter!");
}

OR

void OnEnterVehicle_10()
{
    // bind object to waypoint when player enters the vehicle.
    // note that the vehicle will automatically move along a waypoint track with "NO AI" while it is bound.
    //  when the player is in a bound vehicle they may not exit until it stops (the E key won't work.
    SC_BindObjectToWaypoint(10, 2);
}

This function is called when the player exits the specified vehicle.

Name Rules
??? represents the object ID of the vehicle, for example to run a function when the player gets out of object ID 10, call the function OnEnterVehicle_10.

Parameters
This function does not contain any parameters.

Example

void OnExitVehicle_10()
{
   SC_GameMessage("You got out of object ID 10");
}

This function is called whenever the player gets in a vehicle.  It contains the ID and type number of the object just entered.  You may make use of either or both of these values.

Parameters
ObjectId is the ID of the object just entered, this could be used for special cases or excludes etc.
ObjectTypeNumber represents the type of object just entered.  To make any use of this number you should use the SC_GetObjectTypeNameForNumber() function as type numbers are not fixed.

Comments
This function is called before "OnEnterVehicle".

Example

void OnObjectTypeEnter( int ObjectId, int ObjectTypeNumber)
{
    // declare a string to store the object type's filename in
    char ObjectFilename[256];

    // get the object type's filename
    strcpy( ObjectFilename, SC_GetObjectTypeNameForNumber(ObjectTypeNumber) );

    if( !stricmp( ObjectFilename, "ChinookHelicpter.ob") )
    {
        SC_GameMessage("You just got inside a Chinook helicopter, the ID of this object is %d", ObjectId);
    }
}

Or you could do things the other way around but this could require more function calls (slower in most cases)...

void OnObjectTypeEnter( int ObjectId, int ObjectTypeNumber)
{
    int ChinookTypeNumber;

    ChinookTypeNumber = SC_GetObjectTypeNumberForName("ChinookHelicopter.ob");

    if( ObjectTypeNumber == ChinookTypeNumber)
    {
        SC_GameMessage("You just got inside a Chinook helicopter, the ID of this object is %d", ObjectId);
    }
}

See base\maps\examples\Test_ObjectEvents.map for a working example using the first method.

This function is exactly like OnObjectTypeEnter expect it is called when the player exits the vehicle.

Comments
This function is called before "OnExitVehicle".

This function is called when an object's fixed laser beam is broken by another object.

Name Rules
??? represents the object ID of the object which has the fixed laser.

Parameters
ObstructingObjectId is the ID of the object which tripped the laser.

There are issues with scripts containing internal static or global variables.  This array of 100 integers can be written to and/or read by your script however you feel fit.  The values that you assign will not change for the duration of the map.

Examples
StaticFlags[0] = 149;
or
StaticFlags[1] = 150;
or
x = StaticFlags[0];

Notes
The number in square brackets must be between 0 and 99 else you will crash the game!

This variable represents the status of the minimap.

This variable is connected directly to an in-game variable so changes to its value have immediate effect and its current value is "real".

0 = Minimap is off
1 = Minimap is on
2 = Minimap is on (transparent)

These values contain the map's dimensions in pixels, you should NOT change these values as it will cause the computer to become unstable.

This the remaining mission time limit in seconds, set to -1 for no time limit.

This variable represents the game type.  Do not change this variables value under any circumstances.  The values used by this variable are defined as the following constants...

GT_NONE
GT_SINGLE
GT_HEAD_TO_HEAD
GT_COOP