Unit - Meteor Scripting Functions

int createUnit(string unitFilename, vector2 pos, float dir)

Create a unit (server only).

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

deleteUnit

void deleteUnit(int objectID)

Delete a unit (server only).

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

Does not work for players.

createUnit

array<int> getNearUnits(vector2 pos, float radius)

Get all units in a circle.

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.

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.

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

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.

setUnitDisplayName

string setUnitDisplayName(int objectID)

Set a unit's display name (server only).

setUnitDisplayName(1234, "Miller");

This function cannot be used for players.

getUnitDisplayName

string getUnitDescription(int objectID)

Get the description of a unit (e.g. "Bird")

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

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

In most cases you should use getUnitDisplayName instead.

getUnitDisplayName getUnitFilename

string getUnitFilename(int objectID)

Get the filename of a unit (e.g. "BIRD.INI")

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

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

For players the player character filename is returned.

int getUnitSide(int objectID)

Get the side of a unit.

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

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.

getSideName

string getSideName(int sideNumber)

Get the name for a side number

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

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

getUnitSide

vector2 getUnitSize(int objectID, float dir=0)

Get the size of a unit in pixels.

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

getUnitTypeSize

vector2 getUnitTypeSize(string unitFilename, float dir=1)

Get the size of a unit type in pixels.

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

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

getUnitSize

void setUnitForceActive(int objectID, bool forceActive)

Enable/disable unit force active (server only).

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

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

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

getUnitActive

bool getUnitForceActive(int objectID)

Get unit force active status.

setUnitForceActive

void setDamage(int objectID, float damage)

Set unit or player damage (server only).

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

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

getDamage

float getDamage(int objectID)

Get unit or player damage.

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

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

getDamage

int getUnitTarget(int objectID)

Get a unit's target (server only).

print(getUnitTarget(1234));

Return value is -1 if no current target.

onUnitTargetChanged

void setUnitSight(int objectID, int sight)

Set unit sight (server only).

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

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

sight is in pixels

getUnitSight

int getUnitSight(int objectID)

Get unit sight.

sight is in pixels

setUnitSight

int getUnitClass(int objectID)

Get a unit class for unit.

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

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.

getUnitTypeClass

int getUnitTypeClass(string unitFilename)

Get a unit class for unit's type.

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

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.

getUnitClass

int getNextUnitID()

Get the next unit ID to be allocated.

// global scope
int lowestScriptedUnitID = 0;

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