Meteor 2 Scripting Functions
World
string getWorldName()
Get the world name (map title)

Example
print(getWorldName());

int getWorldSeed()
Get the world random seed.

Example
print(getWorldSeed());

See also
setWorldSeed

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.

Example
setWorldSeed(1234);

Comments
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.

See also
setWorldSeed

vector2i getWorldSize()
Get the world (map) size in pixels.

Example
print(getWorldSize());

See also
setWorldSize

void setWorldSize(vector2 worldSize)
Set the world (map) size in pixels.

Example
setWorldSize(vector2(2500, 2500));

See also
getWorldSize

bool getInfiniteMap()
Determine if the map is infinite.

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

See also
setInfiniteMap getPlayerFlyOffMap setPlayerFlyOffMap

void setInfiniteMap(bool infiniteMap)
Enable or disable infinite map. (server only)

Example
// enable infinite map
setInfiniteMap(true);

Comments
Infinite map is disabled by default when the level reloads and restarts.
Enable infinite map to allow all objects to move off and outside of the map without restriction.
The base sector has no collision when off the map.

See also
getInfiniteMap getPlayerFlyOffMap setPlayerFlyOffMap

bool getPlayerFlyOffMap()
Determine if players are allowed to fly aircraft off the map.

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

See also
setPlayerFlyOffMap getInfiniteMap setInfiniteMap

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

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

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

See also
getInfiniteMap getPlayerFlyOffMap setPlayerFlyOffMap

bool isPosOnMap(vector2 pos)
Determine if a position is on the map.

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

Comments
Always returns true if map is infinite.

See also
clampPosToMap isPosNearMap isRectOnMap getMapInfinite

vector2 clampPosToMap(vector2 pos)
Clamp a position to the map.

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

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

See also
isPosOnMap isPosNearMap isRectOnMap getMapInfinite

bool isPosNearMap(vector2 pos, float maxDistanceFromMapEdge)
Determine if a position is near the map.

Example
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)

Comments
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.

See also
isPosOnMap clampPosToMap isRectOnMap getMapInfinite

bool isRectOnMap(vector2 centrePos, vector2 size)
Determine if a rectangular area intesects the map.

Example
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)

Comments
Always returns true if map is infinite.

See also
isPosOnMap clampPosToMap isPosNearMap

int getPosTerrainPassableType(vector2 pos)
Get terrain passable type at exact position (in pixels).

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

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


vector2 findNearEmptyPos(vector2 searchPos, float minRadius, float maxRadius, float areaSize, int terrainType, int maxAttempts)
Find an empty nearby land or water position.

Example 1
// 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_OBJECT, foundPos);
}
else
{
    print("No empty position found");
}

Example 2
// 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());
    }
}

Example 3
// 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());
    }
}

Comments
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.

See also
findNearRandomPos findEmptyPos findRandomPos

vector2 findNearRandomPos(vector2 searchPos, float minDistance, float maxDistance)
Find a random nearby position without any checking.

Example
// 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_OBJECT, nearPos);

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

See also
findNearEmptyPos findEmptyPos findRandomPos

vector2 findEmptyPos(float mapEdgePadding, float areaSize, int terrainType, int maxAttempts)
Find an empty land or water position anywhere on the map.

Example
// 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_OBJECT, foundPos);
}
else
{
    print("No empty position found");
}

Comments
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).

See also
findRandomPos findNearEmptyPos findNearRandomPos

vector2 findRandomPos(float mapEdgePadding)
Find a random position anywhere on the map without any checking.

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

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

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

See also
findRandomEmptyPos findNearEmptyPos findNearRandomPos

bool isRectPassable(vector2 rectCentre, vector2 rectSize, int terrainType)
Check if a rectangle is passable to the specified terrain type.

Example 1
// 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);

Comments
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.

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

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

Example 3
// 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);

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

See also
raycast

bool raycast(vector2 origin, vector2 angle, int maxDistance=-1, RayHitData& outHitData, int ignoreObjectID=-1)
Perform a single raycast check along a line.

Example
// 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");
}

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

See also
checkLineOfSight

void setLightLevel(float level)
Set the world light level (server only)

Example
// Example 1: total darkness
setLightLevel(0);

// Example 2: dark
setLightLevel(getNightLightLevel());

// Example 3: daylight
setLightLevel(1);

See also
getLightLevel getNightLightLevel isNight

float getLightLevel()
Get the world light level.

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

See also
setLightLevel isNight getNightLightLevel

float getNightLightLevel()
Get the night light level threshold value.

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

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

See also
setLightLevel getLightLevel isNight

float isNight()
Is night?

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

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

See also
setLightLevel getLightLevel getNightLightLevel

void setFogDensity(float density)
Set the world fog density (server only)

Example
// Example 1: Very foggy
setFogDensity(0.9);

// Example 2: no fog
setFogDensity(0);

See also
getFogDensity

float getFogDensity()
Get the world fog density.

Example
print("fog density: " + getFogDensity());

See also
setFogDensity

void setAmbientFlag(int flag, float value)
Set an ambient flag for the duration of the mission.

Example
// 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);

Comments
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 (manual only)
AMB_RAIN
AMB_WIND

See also
getAmbientFlag getAmbientValue setAllAmbientFlags

void setAllAmbientFlags(float value)
Set all ambient flags for the duration of the mission.

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

See also
setAmbientFlag getAmbientFlag getAmbientValue

float getAmbientFlag(int flat)
Get an ambient flag value.

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

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

See also
setAmbientFlag setAllAmbientFlags getAmbientValue

float getAmbientValue(int flat)
Get a current ambient flag evaluated value.

Example
// show current evaluated forest value
print(getAmbientFlag(AMB_FOREST));

Comments
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.

See also
setAmbientFlag setAllAmbientFlags getAmbientValue

bool saveMap(string (in maps folder) filename)
Save the map to a .map file.

Example
saveMap("TestMap");

Comments
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.

int getObjectsCount()
Get total number of alive objects on the map.

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

See also
getHumansCount getVehiclesCount

int getHumansCount()
Get total number of alive humans on the map.

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

See also
getObjectsCount getVehiclesCount

int getVehiclesCount()
Get total number of alive vehicles on the map.

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

See also
getObjectsCount getHumansCount

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

Example
// 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(getDisplayName(objects[i]));
}

Comments
radius is in pixels.

See also
getAllObjects

array<int> getAllObjects()
Get all objects.

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

See also
getNearObjects


Index

Generated on the 23 November 2024 at 08:20:45 (UK Time)