Meteor Scripting Functions
Unit
int createUnit(string unitFilename, vector2 pos, float dir)
Create a unit (server only).

Example
// Fly, be free! (create a bird)
createUnit("BIRD.ini", getPos(getPlayer()), randomDir());

See also
deleteUnit

void deleteUnit(int objectID)
Delete a unit (server only).

Example
int bird = createUnit("BIRD.ini", getPos(getPlayer()), randomDir());
deleteUnit(bird);

Comments
Does not work for players.

See also
createUnit

array<int> getNearUnits(vector2 pos, float radius)
Get all units in a circle.

Example
array<int> units = getNearUnits(getPos(getPlayer()), 500);
for(uint i=0; i<units.length(); i++)
{
    print(getUnitDisplayName(units[i]));
}

array<int> getAllUnits()
Get all units.

Example
array<int> units = getAllUnits();
for(uint i=0; i<units.length(); i++)
{
    print(getUnitDisplayName(units[i]));
}

string getUnitDisplayName(int objectID)
Get a unit or player's display name.

Example
// show local player name
print("Your name is " + getUnitDisplayName(getPlayer()));

Comments
Calling the function on a unit that does not have a custom name will return the unit's description.
Passing an invalid objectID will simply return an empty string.

See also
setUnitDisplayName

string setUnitDisplayName(int objectID)
Set a unit's display name (server only).

Example
setUnitDisplayName(1234, "Miller");

Comments
This function cannot be used for players.

See also
getUnitDisplayName

string getUnitDescription(int objectID)
Get the description of a unit (e.g. "Bird")

Example
// Create a bird
int objectID = createUnit("BIRD.ini", getPos(getPlayer()), randomDir());

// display bird description
print(getUnitDescription(objectID));

Comments
In most cases you should use getUnitDisplayName instead.

See also
getUnitDisplayName getUnitFilename

string getUnitFilename(int objectID)
Get the filename of a unit (e.g. "BIRD.INI")

Example
// Create a bird
int objectID = createUnit("BIRD.ini", getPos(getPlayer()), randomDir());

// display bird filename
print(getUnitFilename(objectID));

Comments
For players the player character filename is returned.

int getUnitSide(int objectID)
Get the side of a unit.

Example
// print player side
int playerSide = getUnitSide(getPlayer());
print(playerSide);

Comments
This function works for units and players.

Resulting value is a number which corresponds with one of the following constants:
SIDE_ALLIES
SIDE_ENEMY
SIDE_NEUTRAL
SIDE_CREATURE

If the unit is not found SIDE_NEUTRAL is returned.

See also
getSideName

string getSideName(int sideNumber)
Get the name for a side number

Example
// print player side name
int playerSide = getUnitSide(getPlayer());
print(getSideName(playerSide));

Comments
If the side number is invalid the name for SIDE_NEUTRAL is returned.

See also
getUnitSide

vector2 getUnitSize(int objectID, float dir=0)
Get the size of a unit in pixels.

Example
// print player size
vector2 playerSize = getUnitSize(getPlayer(), 0);
print(playerSize);

See also
getUnitTypeSize

vector2 getUnitTypeSize(string unitFilename, float dir=1)
Get the size of a unit type in pixels.

Example
// print Air Scout size
vector2 airScoutSize = getUnitTypeSize("ASCOUT.ini");
print(airScoutSize);

Comments
Useful alternative to getUnitSize that does not require an existing unit.

See also
getUnitSize

void setUnitForceActive(int objectID, bool forceActive)
Enable/disable unit force active (server only).

Example
// create bird
int activeBird = createUnit("BIRD.ini", getPos(getPlayer()), 0);

// keep bird active when out of view
setUnitForceActive(activeBird, true);

Comments
Setting forceActive prevents a unit from sleeping when out of view.

See also
getUnitActive

bool getUnitForceActive(int objectID)
Get unit force active status.

See also
setUnitForceActive

void setDamage(int objectID, float damage)
Set unit or player damage (server only).

Example
// set player health to 75 (25 percent damage)
setDamage(getPlayer(), 0.25);

Comments
damage is on scale of 0 (no damage) to 1 (wasted).

See also
getDamage

float getDamage(int objectID)
Get unit or player damage.

Example
print("Player damage: " + getDamage(getPlayer()));
print("Player health: " + (1 - getDamage(getPlayer())) * 100);

Comments
damage is on scale of 0 (no damage) to 1 (wasted).

See also
getDamage

int getUnitTarget(int objectID)
Get a unit's target (server only).

Example
print(getUnitTarget(1234));

Comments
Return value is -1 if no current target.

See also
onUnitTargetChanged

void setUnitSight(int objectID, int sight)
Set unit sight (server only).

Example
// create zombie
int zombie = createUnit("Zombie.ini", getPos(getPlayer()), 0);

// set unit sight to 50
setUnitSight(zombie, 50);

Comments
sight is in pixels

See also
getUnitSight

int getUnitSight(int objectID)
Get unit sight.

Comments
sight is in pixels

See also
setUnitSight

int getUnitClass(int objectID)
Get a unit class for unit.

Example
if (getUnitClass(1234) == UT_TANK)
{
    print("It is a tank!");
}

Comments
Possible return values: UT_INFANTRY, UT_CAR, UT_TANK, UT_HELICOPTER, UT_PLANE, UT_BOAT, UT_SUB, UT_GUN
If the unit does not exist UT_INFANTRY is returned.
Does not work for players.

See also
getUnitTypeClass

int getUnitTypeClass(string unitFilename)
Get a unit class for unit's type.

Example
if (getUnitTypeClass("ASCOUT.ini") == UT_PLANE)
{
    print("It is a plane!");
}

Comments
Use this function to get a unit type's (unit filename) class without having to have a unit instance on the map.
Possible return values: UT_INFANTRY, UT_CAR, UT_TANK, UT_HELICOPTER, UT_PLANE, UT_BOAT, UT_SUB, UT_GUN
If the unit type is not found UT_INFANTRY is returned.

See also
getUnitClass

int getNextUnitID()
Get the next unit ID to be allocated.

Example
// global scope
int lowestScriptedUnitID = 0;

// Your onWorldStartEvent
void onWorldStart()
{
    // Any unit higher than lowestScriptedUnitID was created by script.
    lowestScriptedUnitID = getNextUnitID();
}

Index