These functions are global and can be run from anywhere, they aren’t attached to any specific object.
nil LogMsg (string message)
Adds a message to the log. You can see it by bringing up the console, or checking the log.txt file. Lua’s native “print” function is routed to use LogMsg also.
| message | Any text you want to display or log. |
nil LogError (string message)
Like LogMsg but forces the console to pop-up and prints in red. Should be used for serious errors that you want to know about.
Logged to log.txt.
| message | Any text. Note that it prepends the “Error: “ to your message automatically. |
nil Exists (string funcOrVarName)
Allows you to check the global namespace to see if a variable or function name exists. To improve readability, you should probably use FunctionExists or VariableExists instead.
If you’d like to check a specific entity namespace, use <Entity:FunctionExists> and <Entity:VariableExists> instead.
| funcOrVarName | The exact name of the function or variable. |
nil FunctionExists (string funcName)
Allows you to check the global namespace to see if a certain function exists.
If you’d like to check a specific entity namespace, use <Entity:FunctionExists> instead.
| funcName | The exact name of the function. |
nil VariableExists (string varName)
Allows you to check the global namespace to see if a certain function exists.
If you’d like to check a specific entity namespace, use <Entity:VariableExists> instead.
| varName | The exact name of the variable. |
Entity CreateEntity(Map map, Vector2 vPos, string scriptFileName)
Creates an entity on the specified map at vPos and inits it using the script file name specified.
There is an Entity::CreateEntity version that is identical except it allows relative paths (relative to the entity’s script) to be used.
| map | The map to initialize the entity on. If nil is passed in, the currently active map will be used. |
| vPos | The position to create the entity at. |
| scriptFileName | The script it should be initialized with. |
A handle to the Entity created.
boolean RunScript (string name)
Loads a lua script. If loaded by an entity, keep in mind the script will only exist in the entity’s name space, not globally.
Because lua’s other native script loading functions are disabled for security reasons this is the only way to load a script within a script.
Like images, sounds, and other data, scripts are searched for in mounted worlds in reverse order, so “mods” can override scripts if needed.
RunScript("system/sound.lua"); //load the sound module so everybody can use its functions| name | Path and file name. Paths trying to reference outside of the world directory tree will be invalid. |
True if the script was found and loaded.
Schedule (number deliveryMS, number targetID, string message)
Schedules a line of lua script to be run after a delay.
If an entity ID is specified, the script is run from its namespace.
Internally, App::GetGameTick is used, so messages are paused/modified by the current game speed.
You can use backslashes to escape quotes or apostrophes if needed.
If an entity ID is specified and it doesn’t exist at the time of delivery, the message is discarded.
//delete the entity in 100 milliseconds
Schedule(100, this:GetID(), "this:SetDeleteFlag(true);");
//add the fade out and delete brain in 800 ms to "ent"
Schedule(800, ent:GetID(), "this:GetBrainManager():Add(\"FadeOutAndDelete\",'');");
| deliveryMS | How long to wait before delivering in milliseconds. 500 would mean half a second later. |
| targetID | Entity ID of who should run the script, or C_ENTITY_NONE for the global namespace. |
| message | The line of lua code that should be executed. |
BaseEntity CreateEntitySpecial(string name, string parms)
Special kinds of entities like dialogs must be created with this function.
For simplicity, their real class types are not made available to lua, only the <BaseEntity> interface is accessible.
So how can you control them? Primarily through <BaseEntity::Send> with text.
Uh.. Scan the example script files for these words for examples.
| name | The kind of special entity you want to create. |
| parms | Same as using <BaseEntity::Send> but gets sent during initialization. |
A handle to the <BaseEntity> created.
nil Schedule (number deliveryMS, number targetID, string message)
Identical to Schedule except <GetTick> is used for timing. This means messages will be delivered after the delay takes place, regardless of game speed or if the game is paused for dialog.
Entity GetEntityByWorldPos (Vector2 vPos, Entity entityToIgnore, boolean bPixelAccurate)
Returns the Entity handle at the specified position. If there is more than one, it returns the one “on top”.
This function uses all visible layers and the active map for its check.
local pt = ScreenToWorld(GetInputManager:GetMousePos());
local ent = GetEntityByWorldPos(pt, this, true); //get all entities but ignore ourself, be pixel accurate
if (ent != nil) then
LogMsg("The mouse is over entity # " .. ent:GetID());
else
LogMsg("Didn't find anybody.");
end
| vPos | The point in the world we should check, |
| entityToIgnore | If this isn’t nil, we’ll ignore this entity during our checks. |
| bPixelAccurate | If true, we’ll ignore entities that are transparent at the pixel location clicked. (slower) |
The Entity found, or nil if nothing was found.
Entity GetEntityByID (number entityID)
Converts an entityID to an Entity handle. Very fast.
LogMsg("This entity's ID is " .. GetEntityById(ent:GetID()):GetID()); // a ridiculous example| entityID | Every entity has a unique number it can be referenced by. (unique to that gaming session, not saved/loaded) |
The Entity found, or nil if the ID is invalid.
Entity GetEntityByName (string name)
Converts a name to an Entity. Very fast. The entity’s map will be loaded if needed.
local entGun = GetEntityByName("Gun"); //if an entity is named Gun anywhere in the world, we'll get it.| name | The name set in the editor or with Entity::SetName. Names are always unique. |
The Entity found, or nil if the entity can’t be located.
EntityID GetEntityIDByName (string name)
Like GetEntityByName except it returns the entityID instead of the entity.
local entID = GetEntityIDByName("player");
if (entID != C_ENTITY_NONE) then
LogMsg("Found entityID " .. entID .. ". His name is " .. GetEntityByID(entID):GetName());
end| name | The entity’s name set in the editor or with Entity::SetName. Names are always unique. |
The entity’s ID if found, or <C_ENTITY_NONE> if the entity can’t be located.
BaseEntity GetSpecialEntityByName (string name)
Certain non-entity objects can exist and be manipulated at times using the <BaseEntity> handle.
local ent = GetSpecialEntityByName("editor");
if (ent != nil) then ent:SetDeleteFlag(true); end; //kill the editor window if it exists
if (GetSpecialEntityByName("ChoiceDialog") != nil) then LogMsg("A dialog window is active."); end;| name | Special entities usually have pre-defined names. |
The <BaseEntity> found, or nil if nothing is found.
nil ShowMessage (string title, string msg, boolean bForceClassicStyle)
Quick way to pop-up a message box to show the user something. The user must hit OK to continue.
ShowMessage("Error", "You shall not pass!", true);| title | The text at the top of the message box |
| msg | The main text. Use \n to add a line feed |
| bForceClassicStyle | Normally the style will uses the active game dialog style, but by passing true here you can force the boring silver style. |
number Lerp (number originalNum, number targetNum, number lerpAmount)
Lerp (a quasi-acronym for linear interpolation) is a method to make one number change into another number over time.
If you want an effect where a player’s score “counts up” as he gets points, but don’t want it to take two hours when he scores a million, lerping is for you!
displayScore = Lerp(displayScore, actualScore, 0.1); //lerp by ten percent, call every frame
LogMsg("You have " .. displayScore .. " Points!"); //watch as the number counts up
| originalNum | The number to start with |
| targetNum | the number we want to eventually end up with |
| lerpAmount | the percent of the difference to modify the number by |
The modified number.
Vector2 ScreenToWorld (Vector2 vScreenPos)
Converts a screen position (0,0 being the upper left of your monitor) to a world position based on the active map and camera position.
//figure out where the mouse is pointing, in world coordinates
local vPos = ScreenToWorld(GetInputManager:GetMousePos());
LogMsg("The mouse is currently hovering over " .. tostring(vPos) .. " in world coordinates.");
| vScreenPos | The screen position you need converted to world coordinates. |
The position converted to world coordinates.
Vector2 WorldToScreen (Vector2 vWorldPos)
The opposite of ScreenToWorld.
| vWorldPos | The world position you want converted to screen coordinates. May be negative or larger than your monitor size. |
The position converted to screen coordinates.
Vector2 FacingToVector (number facing)
Converts a directional constant ( C_FACING_CONSTANTS ) into a unit vector.
LogMsg("The down direction is unit vector " .. FacingToVector(C_FACING_DOWN));| facing | One of the C_FACING_CONSTANTS constants. |
A Vector2 object containing a unit vector of the direction.
facing VectorToFacing (Vector2 vDirection)
Converts a unit vector into a C_FACING_CONSTANTS facing.
| vDirection | A Vector2 object containing a unit vector. |
The C_FACING_CONSTANTS that bests fits the direction.
string ColorToString (Color color)
Converts a Color to a string format. Useful for saving it through <Entity:Data>.
local colorString = ColorToString(Color(255,255,255,255));
LogMsg("Neat. In string format, that color is " .. colorString);
local myColor = StringToColor(colorString);
LogMsg("We converted it back!");
| color | A Color object. |
A string formatted with the color data.
| C_FACING_CONSTANTS | |
| C_FACING_NONE | Means no facing at all. |
| C_FACING_LEFT | |
| C_FACING_UP_LEFT | |
| C_FACING_UP | |
| C_FACING_UP_RIGHT | |
| C_FACING_RIGHT | |
| C_FACING_DOWN_RIGHT | |
| C_FACING_DOWN | |
| C_FACING_DOWN_LEFT | |
| C_FACING_COUNT | How many directions we support, this will be 8. |
| C_ORIGIN_CONSTANTS | |
| C_ORIGIN_TOP_LEFT | |
| C_ORIGIN_CENTER_LEFT | |
| C_ORIGIN_CENTER | |
| C_ORIGIN_CENTER_RIGHT | |
| C_ORIGIN_BOTTOM_CENTER |