Meteor Scripting Functions
UI
vector2 getScreenSize()
Get the screen size in pixels

Example
// Example 1:
print("Screen size is " + getScreenSize().x + " by " + getScreenSize().y);

// Example 2 (see comments):
print("Screen size is " + SCREEN_W + " by " + SCREEN_H);

Comments
Two static float variables SCREEN_W and SCREEN_H are also available.

void screenToWorld(vector2 screenPos)
Convert screen pixel coordinates to a world position.

Example
// print world position at middle of screen
print(screenToWorld(vector2(SCREEN_W * 0.5, SCREEN_H * 0.5)));

Comments
Result may be outside of world/map bounds.

See also
worldToScreen getScreenSize

void worldToScreen(vector2 screenPos)
Convert a world position to screen pixel coordinates.

Example
// print screen position of player
print(worldToScreen(getPos(getPlayer())));

Comments
Result may be outside of screen bounds.

See also
screenToWorld getScreenSize

void gameMessage(string text, string soundName)
Show a game message.

Example
// example 1: default message
gameMessage("You need a key or something", "");

// example 2: message with custom sound
gameMessage("What was that?", "battle");

Comments
Leave soundName empty to use the default message sound.

void drawText(vector2 pos, string text, string colour, bool outline, int fontNumber, int fontSize)
Draws UI text to the screen for the current frame.

Example
void onUpdate(float deltaTime)
{
    if(gameHasFocus())
    {
        // draw red white size 20 text at screen position 100, 100
        drawText(vector2(100,100), "Hello World!", "#FFFFFF", true, FONT_STANDARD, 20);
    }
}

Comments
Call from onUpdate event to draw every frame.
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).
Use outline to make the text easier to read.
Valid fonts are: FONT_STANDARD (Default font), FONT_UAV (UAV style font) or FONT_MONO (Mono/fixed character width font).

See also
fontHeight textWidth

void fontHeight(int fontNumber, int fontSize)
Get the height of a font.

Example
void onUpdate(float deltaTime)
{
    if(gameHasFocus())
    {
        int font = FONT_STANDARD;
        int fontSize = 20;

        vector2 drawPos = vector2(100, 100);

        for(int i=0; i<10; i++)
        {
            drawText(drawPos, "This is line " + (i+1), "#FFFFFF", true, font, fontSize);
        
            // move down one line
            drawPos.y += fontHeight(font, fontSize);
        }
    }
}

See also
drawText textWidth

void textWidth(string text, int fontNumber, int fontSize)
Get the width of a string of text in pixels.

Example
void onUpdate(float deltaTime)
{
    if(gameHasFocus())
    {
        int font = FONT_UAV;
        int fontSize = 15;

        string text = "I am in the middle of the screen";

        vector2 drawPos = vector2(
            (SCREEN_W - textWidth(text, font, fontSize)) * 0.5,
            (SCREEN_H - fontHeight(font, fontSize)) * 0.5 );

        drawText(drawPos, text, "#FFFFFF", true, font, fontSize);
    }
}

See also
drawText fontHeight

void addHint(string hintID, number duration, vector2 position, string text)
Show a hint on the screen at specified position.

Example 1
// show simple hint for 5 seconds
addHint(generateHintID(), 5, vector2(100, 100), "Hello World!");

Example 2
void onUpdate(float deltaTime)
{
    if(gameHasFocus())
    {
        // update same hint every frame
        addHint("Pos_Hint", 0, vector2(10, 10), getPos(getPlayer()));
    }
}

Comments
A hint is a white translucent rectangle containing a line of text and has a drop shadow.
Hints can be used as mouse over tooltips or for simply displaying text.
hintID is a unique string ID of the hint, use generateHintID() to if you prefer generate a unique ID automatically.
text can be updated by calling addHint again with the same hintID.
duration is the number of seconds until hint expires (is removed).
duration is clamped between 0 and 30 seconds.
Hints automatically scroll to fully visible on the screen.

See also
generateHintID removeHint

void removeHint(string hintID)
Remove a hint by hintID.

Example
// show a hint for 30 seconds
string hintID = generateHintID();
addHint(hintID, 30, vector2(100, 100), "Hello World!");

// instantly remove the hint
removeHint(hintID);

See also
addHint generateHintID

string generateHintID()
Generates a unique ID for use with addHint and removeHint

Example
print(generateHintID());

See also
addHint removeHint

void drawRectangle(float x1, float y1, float x2, float y2, string colour, bool fill, float outlineThickness=2)
Draw a rectangle using absolute coordinates.

Example
void onUpdate(float deltaTime)
{
    if(gameHasFocus())
    {
        // draw 100 by 100 transparent black rectangle near upper left corner
        drawRectangle(10, 10, 110, 110, "#00000080", true);
    }
}

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

See also
drawRectangleWH drawRectangleWHCentred

void drawRectangleWH(float x1, float y1, float w, float h, string colour, bool fill, float outlineThickness=2)
Draw a rectangle at the specified top-left position, width and height.

Example
void onUpdate(float deltaTime)
{
    if(gameHasFocus())
    {
        // draw 100 by 100 transparent black rectangle near upper left corner
        drawRectangleWH(10, 10, 100, 100, "#00000080", true);
    }
}

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

See also
drawRectangle drawRectangleWHCentred

void drawRectangleWHCentred(vector2 centrePos, vector2 totalSize, string colour, bool fill, float outlineThickness=2)
Draw a rectangle at the specified centre position and size.

Example
void onUpdate(float deltaTime)
{
    if(gameHasFocus())
    {
        // draw 100 by 100 transparent black rectangle near upper left corner
        drawRectangleWHCentred(vector2(60, 60), vector2(100, 100), "#00000080", true);
    }
}

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

See also
drawRectangle drawRectangleWH

void drawLine(vector2 point1, vector2 point2, string colour, float thickness=2)
Draw a rectangle at the specified centre position and size.

Example
void onUpdate(float deltaTime)
{
    if(gameHasFocus())
    {
        // draw a red line from top-left to bottom right corner.
        drawLine(vector2(0, 0), vector2(SCREEN_W - 1, SCREEN_H -1), "#FF0000");
    }
}

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

int getSpriteNumber(string spriteFilename)
Resolve a sprite filename to a sprite number.

Example
print(getSpriteNumber("ASCOUT.SPR"));

Comments
Returns -1 if the sprite file was not found.
Sprite numbers are local only.

See also
getSpriteFramesCount getSpriteFrameSize drawSprite drawSpriteFrame

int getSpriteFramesCount(int spriteNumber)
Get the number of frames in a sprite.

Example
int spriteNumber = getSpriteNumber("ASCOUT.SPR");
print(getSpriteFramesCount(spriteNumber));

Comments
Returns 0 if the sprite file was not found.

See also
getSpriteNumber getSpriteFrameSize drawSprite drawSpriteFrame

vector2 getSpriteFrameSize(int spriteNumber, int frameNumber)
Get the size of a sprite frame in pixels.

Example
int spriteNumber = getSpriteNumber("ASCOUT.SPR");
print(getSpriteFrameSize(spriteNumber, 0));

Comments
Returns 0,0 if the sprite file or frame was not found.

See also
getSpriteNumber getSpriteFramesCount drawSprite drawSpriteFrame

void drawSprite(vector2 pos, int spriteNumber, float angle=0, vector2 scale=vector2(1,1))
Draw a sprite to the screen UI.

Example
int spriteAirScout = 0;
float airScoutSpriteAngle = 0;

void onWorldStart()
{
    // it is faster not to resolve this every frame
    spriteAirScout = getSpriteNumber("ASCOUT.SPR");
}

void onUpdate(float deltaTime)
{
    if(gameHasFocus())
    {
        if(spriteAirScout != -1)
        {
            airScoutSpriteAngle += (deltaTime * 100);

            // draw sprite in middle of screen
            drawSprite(getScreenSize() * 0.5, spriteAirScout);

            // draw rotated sprite to upper left of screen
            drawSprite(getScreenSize() * 0.3, spriteAirScout, airScoutSpriteAngle);

            // draw rotated scaled sprite to lower right of screen
            drawSprite(getScreenSize() * 0.7, spriteAirScout, 360 - airScoutSpriteAngle, vector2(3,3));
        }
    }
}

Comments
The sprite will animate automatically.

See also
getSpriteNumber getSpriteFramesCount getSpriteFrameSize drawSpriteFrame

void drawSpriteFrame(vector2 pos, int spriteNumber, int frameNumber, float angle=0, vector2 scale=vector2(1,1), string colour="#FFFFFF")
Draw a sprite frame to the screen UI.

Example
int spriteAirScout = 0;

void onWorldStart()
{
    // it is faster not to resolve this every frame
    spriteAirScout = getSpriteNumber("ASCOUT.SPR");
}

void onUpdate(float deltaTime)
{
    if(gameHasFocus())
    {
        if(spriteAirScout != -1)
        {
            if(mouseButtonDown(2))
            {
                // draw frame 0 rotated and using transparency if right mouse button is held
                drawSpriteFrame(mousePos(), spriteAirScout, 0, 180, vector2(1, 1), "#FFFFFF80");
            }
            else
            {
                // draw frame 0 normally
                drawSpriteFrame(mousePos(), spriteAirScout, 0);
            }
        }
    }
}

Comments
Useful to drawing user created UI resources such as buttons or icons where images are grouped into sprite files (e.g. buttons.spr or icons.spr).
angle, scale and colour are optional.

See also
getSpriteNumber getSpriteFramesCount getSpriteFrameSize drawSprite

bool showStringInputDialog(string& value, int maxLen, string prompt)
Show a string input dialog.

Example
string text = "";
if(showStringInputDialog(text, 32, "Enter some text"))
{
    print("You entered \"" + text + "\"");
}
else
{
    print("You pressed Cancel");
}

Comments
result is false if the user pressed No/Cancel.
text is passed a string reference and is set by the function, unfortunately it is not possible to pass an initial value.

See also
showConfirmDialog

bool showConfirmDialog(string prompt)
Show a confirmation dialog.

Example
if(showConfirmDialog("Do you want a hoverboard?"))
{
    giveItem(getPlayer(), "Hoverboard", 1);
}

See also
showStringInputDialog

void showTextViewer(string filenameOrData, bool isFile, string caption)
Display text from a file or from a single string.

Example 1
// show a text file from the base or mod folder
showTextViewer("help\\gamekeys.txt", true, "Keys Help");

Example 2
// show text from a string
string text =
    "This is line 1\n" +
    "This is line 2\n" +
    "This is line 3\n" +
    "This is line 4\n" +
    "\"This is in quotes\"\n";

showTextViewer(text, false, "Window Title");

Comments
filenameOrData is either a filename (must be relative to the base/mod folder root) or actual text.
isFile must be set to true if filenameOrData is a file or false if filenameOrData is actual text.
caption is the window title.


Index