World - Meteor 2 Scripting Functions

string getWorldName()

Get the world name (map title)

print(getWorldName());

int getWorldSeed()

Get the world random seed.

print(getWorldSeed());

void setWorldSeed(int seed)

Set the world random seed for new objects.
The random seed is used to generate object names (e.g. character names and vehicle callsigns).
Using a seed ensures that object names will always be the same each time the map is run.
The default seed is generated from the map filename so renaming a map will rename all the people on it.

setWorldSeed(1234);

Changing the seed using script only affects objects created after the game is started because placed objects are created before any script is run.
To overcome this while using a predefined seed, set the "map seed" property in the Map Editor.

setWorldSeed

vector2i getWorldSize()

Get the world (map) size in pixels.

print(getWorldSize());

setWorldSize

void setWorldSize(vector2 worldSize, bool broadcast=true)

Set the world (map) size in pixels.

setWorldSize(vector2(2500, 2500));

getWorldSize

bool getInfiniteMap()

Determine if the map is infinite.

if(getInfiniteMap())
{
print("Map is infinite");
}
else
{
print("Map is not infinite");
}

setInfiniteMap getPlayerFlyOffMap setPlayerFlyOffMap

void setInfiniteMap(bool infiniteMap)

Enable or disable infinite map. (server only)

// enable infinite map
setInfiniteMap(true);

Infinite map mode allows all objects to travel outside of the map.
Warning: When using infinite map mode the base sector has "open" collision physics outside of the map bounds allowing all objects to move without restriction (e.g. boats can drive on grass). Other sectors (created using script) are not affected.
Infinite map is disabled by default when the level reloads and restarts.

getInfiniteMap getPlayerFlyOffMap setPlayerFlyOffMap

bool getPlayerFlyOffMap()

Determine if players are allowed to fly aircraft off the map.

if(getPlayerFlyOffMap())
{
print("Players can fly off map");
}
else
{
print("Players cannot fly off map");
}

setPlayerFlyOffMap getInfiniteMap setInfiniteMap

void setPlayerFlyOffMap(bool playerFlyOffMap)

Enable or disable players being able to fly off and outside of the map. (server only)

// enable player fly off map
setPlayerFlyOffMap(true);

Enable to allow player aircraft to leave the map (in effect to turn around without suddenly stopping at the map bounds).

getInfiniteMap getPlayerFlyOffMap setPlayerFlyOffMap

float getAirHeight()

Get the air render layer height in pixels.

print("Air height is " + getAirHeight());

Objects and effects at or above this height are considered to be in the air and are rendered above ground objects, walls and trees etc.

bool isPosOnMap(vector2 pos)

Determine if a position is on the map.

print(isPosOnMap(vector2(-100, -100))); // false

Always returns true if map is infinite.

clampPosToMap isPosNearMap isRectOnMap getMapInfinite

vector2 clampPosToMap(vector2 pos)

Clamp a position to the map.

print(clampPosToMap(vector2(-100, -100))); // 0, 0

X and Y are clamped individually.
Will clamp to world size even if map is infinite.

isPosOnMap isPosNearMap isRectOnMap getMapInfinite

bool isPosNearMap(vector2 pos, float maxDistanceFromMapEdge)

Determine if a position is near the map.

print(isPosNearMap(vector2(0, -101), 100)); // false (not within 100 pixels from map)
print(isPosNearMap(vector2(0, 100), 100)); // true (within 100 pixels from map)
print(isPosNearMap(vector2(1, 1), 100)); // true (always true if on map)

Always returns true if map is infinite.
maxDistanceFromMapEdge is the max allowed distance from the edge of the map if pos is outside of the map.

isPosOnMap clampPosToMap isRectOnMap getMapInfinite

bool isRectOnMap(vector2 centrePos, vector2 size)

Determine if a rectangular area intesects the map.

print(isRectOnMap(vector2(100,100), vector2(50,50))); // true (within map)
print(isRectOnMap(vector2(25,25), vector2(50,50))); // true (partially on map)
print(isRectOnMap(vector2(-50,-50), vector2(25,25))); // false (entirely off map)

Always returns true if map is infinite.

isPosOnMap clampPosToMap isPosNearMap

int getPosTerrainPassableType(vector2 pos)

Get terrain passable type at exact position (in pixels).

print(getPosTerrainPassableType(vector2(1000,1000)));

Result values:
0 = land
1 = solid
2 = water
3 = clear
4 = above ground
5 = closed

getMaterialNameAtPos

string getMaterialNameAtPos(vector2 pos, bool ignoreShadows=true)

Get material name of uppermost sector the texture at a position (in pixels).

string matName = getMaterialNameAtPos(getPos(PLAYER_OBJECT);
print(matName));

Material name is from textures.ini.
Material is a surface category (e.g. Grass or Ice and not a single texture). Use getTextureNameAtPos to get the texture name.
Out of map bounds will return base sector texture material name.

getMaterialNameLowerHashAtPos getTextureNameAtPos getPosTerrainPassableType

uint getMaterialNameLowerHashAtPos(vector2 pos, bool ignoreShadows=true)

Get material name lower case hash of the uppermost sector texture at a position (in pixels).

uint matHash = getMaterialNameLowerHashAtPos(getPos(PLAYER_OBJECT);
print(matHash));

Same as getMaterialNameAtPos but returns a hash for high speed comparisons (e.g. planting vegetation in a loop).

getMaterialNameAtPos

string getTextureNameAtPos(vector2 pos)

Get texture name of the uppermost sector texture at a position (in pixels).

string texName = getTextureNameAtPos(getPos(PLAYER_OBJECT);
print(matName));

Out of map bounds will return base sector texture name.

getMaterialNameAtPos getMaterialNameLowerHashAtPos

vector2 findNearEmptyPos(vector2 searchPos, float minRadius, float maxRadius, float areaSize, int terrainType, int maxAttempts)

Find an empty nearby land or water position.

// look between 50 and 1200 pixels from player for 30x30 pixel big area on land.
vector2 foundPos = findNearEmptyPos(getPos(PLAYER_OBJECT), 50, 1200, 30, TPT_LAND, 0);

// move player to foundPos
if(foundPos != vector2(0,0))
{
setPos(PLAYER_VEHICLE, foundPos);
}
else
{
print("No empty position found");
}

// create up to 50 blobs near player
for(int i=0; i<50; i++)
{
    vector2 foundPos = findNearEmptyPos(getPos(PLAYER_OBJECT), 100, 2000, 30, TPT_LAND);

    if(foundPos != vector2(0,0))
    {
        createUnit("blob.ob", foundPos, randomDir());
    }
}

// create up to 20 crocodiles near player (in water only)
for(int i=0; i<20; i++)
{
    vector2 foundPos = findNearEmptyPos(getPos(PLAYER_OBJECT), 100, 1000, 30, TPT_WATER);

    if(foundPos != vector2(0,0))
    {
        createUnit("croc.ob", foundPos, randomDir());
    }
}

If no position was found the return value is 0,0.
areaSize is the diameter of the space/clearing required.
terrainType should be set to either TPT_LAND or TPT_WATER.
maxAttempts can be left at 0 (auto based on searchRadius) or be specified.

findNearRandomPos findEmptyPos findRandomPos

vector2 findNearRandomPos(vector2 searchPos, float minDistance, float maxDistance)

Find a random nearby position without any checking.

// find a random position at least 100 but no more than 500 pixels of the player.
vector2 nearPos = findNearRandomPos(getPos(PLAYER_OBJECT), 100, 500);

// move player to nearPos
setPos(PLAYER_VEHICLE, nearPos);

If no position was found the return value is 0,0.

findNearEmptyPos findEmptyPos findRandomPos

vector2 findEmptyPos(float mapEdgePadding, float areaSize, int terrainType, int maxAttempts)

Find an empty land or water position anywhere on the map.

// teleport player to a random empty position at least 20x20 pixels big and at least 100 pixels from the edge of the map.
vector2 foundPos = findEmptyPos(100, 20, TPT_LAND, 0);

if(foundPos != vector2(0,0))
{
setPos(PLAYER_VEHICLE, foundPos);
}
else
{
print("No empty position found");
}

areaSize is the diameter of the space/clearing required.
terrainType should be set to either TPT_LAND or TPT_WATER.
maxAttempts can be left at 0 to use default (1000 attempts).

findRandomPos findNearEmptyPos findNearRandomPos

vector2 findRandomPos(float mapEdgePadding)

Find a random position anywhere on the map without any checking.

// find a random position at least 100 pixels from the edge of the map
vector2 randomPos = findRandomPos(100);

// move player to randomPos
setPos(PLAYER_VEHICLE, randomPos);

If the edge padding value is larger than the map width or height * 0.4 then map centre is returned.

findRandomEmptyPos findNearEmptyPos findNearRandomPos

bool isRectPassable(vector2 rectCentre, vector2 rectSize, int terrainType)

Check if a rectangle is passable to the specified terrain type.

// check location from 10,10 to 110,110 is passable for land-based objects
bool clear = isRectPassable(vector2(10,10), vector2(100,100), TPT_LAND);
print(clear);

Avoid using TPT_SOLID and TPT_CLOSED (these are simply treated as TPT_LAND).

bool checkLineOfSight(vector2 pos1, vector2 pos2, int ignoreObjectID1=-1, int ignoreObjectID2=-1)

Check line of sight is clear between 2 points.

// check line of sight
bool clear = checkLineOfSight(getPos(PLAYER_OBJECT), vector2(0,0));
print(clear);

// check line of sight ignoring player
bool clear = checkLineOfSight(getPos(PLAYER_OBJECT), vector2(0,0), PLAYER_OBJECT);
print(clear);

// check line of sight between player and object ID 10
int enemyID = 10;
bool clear = checkLineOfSight(getPos(PLAYER_OBJECT), getPos(enemyID), PLAYER_OBJECT, enemyID);
print(clear);

Specify ignoreObjectID1 and/or ignoreObjectID2 to avoid self collisions or leave as default (-1) if not required.

raycast

bool raycast(vector2 origin, vector2 angle, int maxDistance=-1, RayHitData& outHitData, int ignoreObjectID=-1)

Perform a single raycast check along a line.

// find object up to 2000 pixels in front of player
vector2 startPos = getPos(PLAYER_OBJECT);
float angle = getDir(PLAYER_OBJECT);
float maxDist = 2000;
RayHitData hitResult;
if(raycast(startPos, angle, maxDist, hitResult, PLAYER_OBJECT) && hitResult.valid)
{
    print("Hit");
    print("pos=" + hitResult.pos);
    print("normal=" + hitResult.normal);
    print("sectorID=" + hitResult.sectorID);
    print("objectID=" + hitResult.objectID);
    print("projectileID=" + hitResult.projectileID);
}
else
{
    print("No hit");
}

Returns true if something was hit.
Set maxDistance to -1 to use the maximum allowed distance (currently 50000 pixels).

checkLineOfSight

void setLightLevel(float level)

Set the world light level (server only)

// total darkness
setLightLevel(0);

// dark
setLightLevel(getNightLightLevel());

// daylight
setLightLevel(1);

getLightLevel getNightLightLevel isNight setLightColour getLightColour

float getLightLevel()

Get the world light level.

print("light level: " + getLightLevel());

setLightLevel isNight getNightLightLevel setLightColour getLightColour

float getNightLightLevel()

Get the night light level threshold value.

print("night light level threshold: " + getNightLightLevel());

This value is currently a fixed constant and cannot be changed.

setLightLevel getLightLevel isNight

float isNight()

Is night?

print("light level: " + getLightLevel());

This function returns true if the light level drops low enough to be considered night, less than getNightLightLevel().

setLightLevel getLightLevel getNightLightLevel

void setLightColour(string colour)

Set the world light colour (server only)

// tint light to orange
setLightColour("#F77D11");

// default light colour
setLightColour("#F77D11");

colour is specfified in HTML style ("#RRGGBB" hex values), colours may also contain 2 additional optional characters for alpha (e.g. "#FFFFFF80" is transparent white).

getLightColour getLightLevel setLightLevel

string getLightColour()

Get the world light colour.

print("light level: " + getLightLevel());

colour is specfified in HTML style ("#RRGGBB" hex values), colours may also contain 2 additional optional characters for alpha (e.g. "#FFFFFF80" is transparent white).

setLightColour setLightLevel getNightLightLevel

void setRain(float intensity)

Set the rain intensity (server only)

// No rain
setRain(0);

// Some rain
setRain(0.5);

// Max rain
setRain(1);

getRain

float getRain()

Get the world rain intensity.

print("Rain intensity: " + getRain());

getRain

void setWindSpeed(float windSpeed)

Set the world wind speed in m/s (server only)

// Calm
setWindSpeed(0);

// Stong breeze
setWindSpeed(12);

// Hurricane
setWindSpeed(33);

getWindSpeed

float getWindSpeed()

Get the world wind speed in m/s.

print("Wind speed m/s: " + getWindSpeed());

setWindSpeed

void setWindDir(float windDir)

Set the world wind direction in degrees (0-360) (server only)

// Wind blows from north to south
setWindDir(0);

// Wind blows from south to north
setWindDir(180);

// Wind blows from west to east
setWindDir(270);

Wind direction is the origin of the wind (e.g. 180 is blowing from south to north)

getWindDir

float getWindDir()

Get the wind direction in degrees (0-360).

print("wind direction: " + getWindDir());

Wind direction is the origin of the wind (e.g. 180 is blowing from south to north)

setWindDir

void setFog(float density)

Set the world fog density (server only)

// no fog
setFog(0);

// Some fog
setFog(0.2);

// Very foggy
setFog(0.9);

getFog

float getFog()

Get the world fog density.

print("fog density: " + getFog());

setFog

void setFogColour(string colour)

Set the world fog colour (server only)

setFogColour("#FFFFFF");

colour is specfified in HTML style ("#RRGGBB" hex values), colours may also contain 2 additional optional characters for alpha (e.g. "#FFFFFF80" is transparent white).
An alias called setFogColor can also be used.

getFogColour

string getFogColour()

Get the world fog colour.

print("fog colour: " + getFogColour());

colour is specfified in HTML style ("#RRGGBB" hex values), colours may also contain 2 additional optional characters for alpha (e.g. "#FFFFFF80" is transparent white).
An alias called getFogColor can also be used.

setFogColour

void setAmbientFlag(int flag, float value)

Set an ambient flag for the duration of the mission (local only).

// force city ambient flag to be 1 until next mission.
setAmbientFlag(AMB_CITY, 1);

// set water and shore to auto (default).
setAmbientFlag(AMB_WATER, -1);
setAmbientFlag(AMB_SHORE, -1);

Ambient flags are used to play ambient sounds and spawn local wildlife around the player.

By default ambient flags are calculated automatically based on the player's current position.
Some flags cannot be calculated automatically and can only be set using setAmbientFlag (e.g. AMB_CITY and AMB_JUNGLE).
Set an ambient flag to -1 (default) to allow the game to work out the current value automatically based on the local player's position.
Set an ambient flag to any value between 0 and 1 to hard set the value for the duration of the current mission.

All ambient flags are reset to -1 (auto) on next mission.

Flags list:
AMB_MEADOW
AMB_FOREST
AMB_JUNGLE (manual only)
AMB_CITY (manual only)
AMB_WATER
AMB_SHORE
AMB_UNDERWATER
AMB_RAIN
AMB_WIND
AMB_STORM (manual only)
AMB_BATTLE (manual only)
AMB_CREEPY (manual only)

getAmbientFlag getAmbientValue setAllAmbientFlags

void setAllAmbientFlags(float value)

Set all ambient flags for the duration of the mission.

// underwater only mission
void onStart()
{
setAllAmbientFlags(0);
setAmbientFlag(AMB_UNDERWATER, 1);
}

setAmbientFlag getAmbientFlag getAmbientValue

float getAmbientFlag(int flat)

Get an ambient flag value.

// show underwater setting
print(getAmbientFlag(AMB_UNDERWATER));

This shows the configured (not current) flag value. Use getAmbientValue to get the current evaluated value.

setAmbientFlag setAllAmbientFlags getAmbientValue

float getAmbientValue(int flat)

Get a current ambient flag evaluated value.

// show current evaluated forest value
print(getAmbientValue(AMB_FOREST));

This gets the current automatically (or forced) value, it will always be between 0 and 1.
For example standing near a body of water should return high values (0 to 1) for AMB_WATER and AMB_SHORE.

setAmbientFlag setAllAmbientFlags getAmbientValue

vector2 getAmbientSoundsGain()

Get the ambient shore pos.

The ambient shore pos is the location of the nearest shore and is used for ambient sound spatialisation.

float getAmbientSoundsGain()

Get the ambient sound gain.

Ambient sound game is specfied in the Options and is value between 0 and 1.

int createTreeSpawner(vector2 pos, float radius, bool circle, float density, bool allowOverlap, uint speciesLowerHash, float seed, int treeSpawnerID=-1, bool broadcast=true)

Create a tree spawner.

// oak trees around player
uint oakTreeHash = createStringHashLowerCase("Tree_Oak01.ini");
createTreeSpawner(getPos(PLAYER_OBJECT), 500, true, 1, false, oakTreeHash, randomSeed(), -1, true);

// random species trees to lower right
uint randomSpeciesHash = createStringHashLowerCase("Default");
createTreeSpawner(getPos(PLAYER_OBJECT) + vector2(500,500), 500, true, 1, false, randomSpeciesHash, randomSeed(), -1, true);

Returns tree spawner ID or -1 if failed to create.
Set circle to false to create a square shaped spawner.

deleteTreeSpawner createStringHashLowerCase randomSeed

void deleteTreeSpawner(int treeSpawnerID, bool broadcast=true)

Delete a tree spawner.

createTreeSpawner

void updateTrees()

Force trees and trees on minimap update.

Thre is no need to call this function after adding/removing tree spawners as it is normally handled automatically.

bool saveMap(string (in maps folder) filename)

Save the map to a .map file.

saveMap("TestMap");

Useful for saving dynamically generated maps.
Filename must be a file only (no paths are allowed).
File will be saved in base\maps (or mod folder\maps).
Existing map files cannot be overwritten so the target filename must not exist.

bool saveMapSectorsOverlay(string (in maps folder) filename)

Save minimap sectors overlay image to .png file.

saveMapSectorsOverlay("MapName_Overlay_Sectors");

Saving the sectors overlay makes the minimap initialise faster on maps containing a large number of sectors/vertices.
Filename must be a file only (no paths are allowed).
File will be saved in base\maps (or mod folder\maps).
Existing files cannot be overwritten so the target filename must not exist.

saveMapTreesOverlay

bool saveMapTreesOverlay(string (in maps folder) filename)

Save minimap trees overlay image to .png file.

saveMapTreesOverlay("MapName_Overlay_Trees");

Saving the trees overlay makes the minimap initialise faster on maps containg a large number of trees and all trees and tree spawners have the same properties each time the map is loaded.
Filename must be a file only (no paths are allowed).
File will be saved in base\maps (or mod folder\maps).
Existing files cannot be overwritten so the target filename must not exist.

saveMapSectorsOverlay

int getObjectsCount()

Get total number of alive objects on the map.

print("All Objects " + getObjectsCount());

getHumansCount getVehiclesCount

int getHumansCount()

Get total number of alive humans on the map.

print("Humans: " + getHumansCount());

getObjectsCount getVehiclesCount

int getVehiclesCount()

Get total number of alive vehicles on the map.

print("Vehicles: " + getVehiclesCount());

getObjectsCount getHumansCount

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

Get all objects in a circle.

// show all objects within 10M of player
array<int> objects = getNearObjects(getPos(PLAYER_OBJECT), metresToPixels(10));
for(uint i=0; i<objects.length(); i++)
{
print(objects[i] + ": " + getDisplayName(objects[i]));
}

radius is in pixels.

getAllObjects

array<int> getAllObjects()

Get all objects.

array<int> objects = getAllObjects();
for(uint i=0; i<objects.length(); i++)
{
print(objects[i] + ": " + getDisplayName(objects[i]));
}

getNearObjects

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

Get all map sprites in a circle.

// show all sprites within 10M of player
array<int> sprites = getNearSprites(getPos(PLAYER_OBJECT), metresToPixels(10));
for(uint i=0; i<sprites.length(); i++)
{
print(sprites[i] + ": " + getSpriteTypeName(sprites[i]));
}

radius is in pixels.

getAllSprites

array<int> getAllSprites()

Get all map sprites.

array<int> sprites = getAllSprites();
for(uint i=0; i<sprites.length(); i++)
{
print(sprites[i] + ": " + getSpriteTypeName(sprites[i]));
}

getNearSprites