Bot Library

From Omni-bot Wiki

Global Bot Functions

AddBot

Adds a bot to the game, and optionally specifies team, class, and name for the bot.

Parameters: ()

Parameters: (team)

Parameters: (team, class)

Parameters: (team, class, name)

Parameters: (table)

Returns: none

Example:

AddBot();
// OR
AddBot(TEAM.AXIS);
// OR
AddBot(TEAM.AXIS, CLASS.SOLDIER);
// OR
AddBot(TEAM.AXIS, CLASS.SOLDIER, "SomeDude");
// OR
// not all fields are valid for all games, here's a quake 4 example
// not all fields are required. any left out will use sensible default values
tbl =
{
    name="SomeDude",
    team=TEAM.STROGG,
    class=CLASS.PLAYER,
    spawnpoint="somespawnpointname",
    model="model_player_kane_strogg",
    skin="base",
};
AddBot(tbl);

See Also: KickBot, KickAll

CalcTrajectory

Calculates a projectile trajectory, and returns the results in a table, or null if no trajectory exists for the parameters given.

Parameters: (Vector3 start position, Vector3 target position, projectile speed, projectile gravity)

Returns: table or null

Example:

mypos = Vector3(10,10,10); // get a valid position from somewhere
targpos = Vector3(20,20,20); // get a valid position from somewhere
projVel = 1000;
projGrav = 0.5;
traj = CalcTrajectory(mypos, targpos, projVel, projGrav);
if(traj)
{
    // if a table was returned, there can be 1 or 2 trajectories stored in it.
    // the 1st trajectory is the most direct trajectory
    // the 2nd trajectory is normally a mortar trajectory with a high degree of arc.
    // both trajectories are a unit length facing vector
    b.TurnToFacing(traj[0]);
    // OR
    b.TurnToFacing(traj[1]);
}

CheatsEnabled

Checks if cheat mode is enabled in the game. Useful for debug or development scripts that use functions that are only available in cheat mode.

Parameters: none

Returns: true if cheats are enabled, false if not

Example:

if(CheatsEnabled())
{
    // do something
}

See Also: EntityKill, ServerCommand

ConfigGet

Gets a config value from omni-bot.cfg.

Parameters: (section, config parameter name, config parameter value)

Returns: config parameter value

Example:

ft = ConfigGet("FireTeam", "enabled", ft);

See Also: ConfigSet

ConfigSet

Sets a config value in omni-bot.cfg.

Parameters: (section, config parameter name, config parameter value)

Returns: none

Example:

ConfigSet("FireTeam", "enabled", 0);

See Also: ConfigGet

Trigger Regions

OnTriggerRegion

Creates one of several types of trigger regions. A trigger region is an area that watches for entities of certain types to touch them and calls script callback functions for enter and exit. Useful if you want an easy way to be notified when certain entities go to certain areas of the map.

This function takes a table as the last parameter to define a number of flexible options for the trigger region. Here is a list of available key/value options for the table.

• Name - Optional name to give the region. Does not need to be unique.
• OnEnter - script function to call when an entity touches the region.
• OnExit - script function to call when an entity stops touching the region.
• TriggerOnClass - Define the class id you want the region to trigger on. This field may also be an indexed table with up to 8 class ids.
• TriggerOnCategory - Category of entities to watch for. This field may also be an indexed table with as many categories as you want to limit the trigger to.
• TriggerOnEntity - A specific entity to trigger on. This field may also be an indexed table with up to 8 entities you want to limit the trigger to.

The following region types are supported. The type is dependent on which parameters of the function are used.

• AABB - Axis aligned bounding box.
• Sphere - A radius around a position.

Triggers may be rendered for reference with /bot drawtriggers 1

Parameters: (AABB, table)

Parameters: (position, radius, table)

Returns: unique serial number of region

Example:

// creates a sphere trigger 256 units in radius around 0,0,0
triggerInfo =
{
	Name="TestTrigger",
	TriggerOnClass=CLASS.ANYPLAYER,
	OnEnter = function(ent)
	{
		print(GetEntName(ent),"entered aabb trigger");
	},
	OnExit = function(ent)
	{
		print(GetEntName(ent),"exited aabb trigger");
	},
};
serial = OnTriggerRegion(Vector3(0,0,0),256,triggerInfo);

See Also: DeleteTriggerRegion, Case Study

DeleteTriggerRegion

Deletes a trigger region previously created with OnTriggerRegion. Because regions aren't required to have unique names, DeleteTriggerRegion will delete all regions that match the provided name. This allows grouping of different trigger regions by shared names.

Parameters: (name)

Parameters: (serial #)

Returns: none

Example:

// creates a sphere trigger 256 units in radius around 0,0,0, then delete it immediately.
triggerInfo =
{
	Name="TestTrigger",
	TriggerOnClass=CLASS.ANYPLAYER,
	OnEnter = function(ent)
	{
		print(GetEntName(ent),"entered aabb trigger");
	},
	OnExit = function(ent)
	{
		print(GetEntName(ent),"exited aabb trigger");
	},
};
serial = OnTriggerRegion(Vector3(0,0,0),256,triggerInfo);

DeleteTriggerRegion(serial);
// OR
DeleteTriggerRegion("TestTrigger");

See Also: OnTriggerRegion

DistanceBetween

Utility function for checking distances between 2 objects. This function takes 2 parameters, but the parameter types can vary.

Parameters: (object1, object2)

For this function, each parameter can be one of the following types.

• Vector3
• GameEntity
• GameId

This provides a flexible and fast function that allows a script to check the distance between a variety of source and destination object, and reduces the need for the script to convert between GameEntity or GameId, or to get the position of the GameEntity itself.

Returns: distance between the objects

Example:

// assume entity1 is a GameEntity from another source, such as GetAllType
if(DistanceBetween(b.GetGameEntity(), entity1))
{
}
// OR
if(DistanceBetween(b.GetGameEntity(), Vector3(10,20,30))
{
}

Debug Functions

DrawDebugLine

Draws a line in the environment. Useful for debugging.

Parameters: (Vector3 start, Vector3 end, color, duration)

Returns: none

Example:

start = Vector3(0,0,0);
end = Vector3(20,20,20);
// draw it in red for 5 seconds
DrawDebugLine(start, end, COLOR.RED, 5);

See Also: DrawDebugAABB, GetEntWorldAABB

DrawDebugAABB

Draws an AABB.

Parameters: (AABB, color, duration)

Returns: none

Example:

AABB box; // initialize it with something
// draw it in red for 5 seconds
DrawDebugAABB(box, COLOR.RED, 5);

See Also: DrawDebugLine, GetEntWorldAABB

DrawDebugAABB

Draws an AABB.

Parameters: (AABB, color, duration)

Returns: none

Example:

AABB box; // initialize it with something
// draw it in red for 5 seconds
DrawDebugAABB(box, COLOR.RED, 5);

See Also: DrawDebugLine, GetEntWorldAABB

EchoToScreen

Prints a message to the screen.

Parameters: (duration, message)

Returns: none

Example:

EchoToScreen(5,"Hello World!");

Error

Prints an error to the games output console.

Parameters: (error message)

Returns: none

Example:

Error("Somethin bad happened");

ShowPaths

Debug Information function. Prints Omni-bot version, revision, and revision date, along with file system paths.

Parameters: none

Returns: none

Example:

ShowPaths();

Log

Writes a string to the omnibot log file.

Parameters: (string)

Returns: none

Example:

Log("Something cool happened");

ExecCommand

This function executes a bot command as if it came from the games input console.

Parameters: (command string)

Returns: none

Example:

ExecCommand("addbot 1 2")

ExecScript

Attempts to execute a script file.

Parameters: (filename)

Returns: true if successful, false if not

Example:

ExecScript("myscript.gm");

RunScript

See: ExecScript

Entity Functions

GetEntBonePosition

Gets the world position of a specific bone on an entity.

Note: This function may not be implemented for all games.

Parameters: (GameEntity/GameId, BoneId)

Returns: Vector3 world bone position, or null if bone not found

Example:

headpos = GetEntBonePosition(someent, BONE.HEAD);
if(headpos)
{
    // got head position
}

GetEntCategory

Checks if the entity belongs to one or more entity categories. This function takes one or more categories, and returns true if the entity belongs to all the provided categories.

Parameters: (GameEntity/GameId, Category, ...)

Returns: true if the entity belongs to all provided categories.

Example:

if(GetEntCategory(someent, CAT.PROJECTILE))
{
} 
if(GetEntCategory(someent, CAT.PLAYER, CAT.VEHICLE))
{
} 

GetEntClass

Gets the class of the entity.

Parameters: (GameEntity/GameId)

Returns: class of entity, or null if there was an error

Example:

cls = GetEntClass(someent);
if(cls == CLASS.SOLDIER)
{
}

GetEntEyePosition

Gets the world eye position of an entity.

Parameters: (GameEntity/GameId)

Returns: Vector3 eye position, or null if there was an error

Example:

eyepos = GetEntEyePosition(someent);
if(eyepos)
{
    // got eye position
}

GetEntFacing

Gets the world facing vector of an entity

Parameters: (GameEntity/GameId)

Returns: Vector3 facing, or null if there was an error

Example:

face = GetEntFacing(someent);
if(face)
{
    // got face vector, as a direction vector
}

GetEntFlags

Checks if the entity has one or more entity flags

Parameters: (GameEntity/GameId, Entity Flag, ...)

Returns: true if the entity has all provided entity flags.

Example:

if(GetEntFlags(someent, ENTFLAG.CROUCHED))
{
} 
if(GetEntFlags(someent, ENTFLAG.CROUCHED, ENTFLAG.RELOADING))
{
} 

GetEntHealthAndArmor

Gets an object that provides access to health and armor of an entity. The object returned by this function is unique, in that it updates itself and the user doesn't need to keep calling it repeatedly from a script that checks it often.

Parameters: (GameEntity/GameId)

Returns: Health/Armor object, or null if bad entity.

Properties available through the object.

• Health - Current Health
• MaxHealth - Max Health
• Armor - Current Armor
• MaxArmor - Max Armor
• IsValid - Whether the entity is still valid. Use when watching the health/armor for an arbitrary entity. IsValid should allow you to assess the lifetime of the entity.

Example:

healthArmor = GetEntHealthAndArmor(someentity);
if(healthArmor)
{
    while(1)
    {
         if(healthArmor.Health < 20)
         {
              b.Say("I'm Hurt!");
         }
         sleep(2);
    }
} 

GetEntOwner

Gets the owner of an entity. Typically used for entities that can be held or carried.

Parameters: (GameEntity/GameId)

Returns: GameId of owner, or null if none or error

Example:

owner = GetEntOwner(someent);

GetEntPowerups

Checks if the entity has one or more powerups. This function takes one or more powerups, and returns true if the entity has all of them.

Parameters: (GameEntity/GameId, PowerUp, ...)

Returns: true if the entity has all powerups.

Example:

if(GetEntPowerups(someent, POWERUP.INVINCIBLE))
{
} 
if(GetEntPowerups(someent, POWERUP.QUADDAMAGE, POWERUP.BERSERK))
{
} 

GetEntTeam

Gets the team id that the entity belongs to.

Parameters: (GameEntity/GameId)

Returns: Team Id of entity, or null if error

Example:

if(GetEntTeam(someent) == TEAM.RED)
{
}

GetEntWorldAABB

Gets the world AABB for an entity.

Parameters: (GameEntity/GameId, AABB<optional>)

If you pass an AABB as the 2nd parameter, that object will be filled in instead of a new AABB returned. This can save memory allocations in a script that calls the function often by re-using the same object.

Returns: true if AABB passed as 2nd parameter and filled in successfully, if no AABB provided, returns AABB for entity. Both return null on an error.

Example:

entAABB = GetEntWorldAABB(someent);
if(entAABB)
{
     // do something
}
// re-use the same AABB later
if(GetEntWorldAABB(someent, entAABB))
{
} 

GetEntityName

Gets the name of an entity.

Parameters: (GameEntity/GameId)

Returns: name of entity, or null if error

Example:

entName = GetEntityName(someent);
if(entName)
{
    if(entName == "SomeName")
    {
         // do something
    }
}

GetEntName

See: GetEntityName

GetEntityLocalSpace

Converts a world position into a local space position of a specified entity.

Parameters: (GameEntity/GameId, Vector3 world position)

Returns: Vector3 local space position, or null if error

Example:

worldpos = Vector3(10,10,10);
localpos = GetEntityLocalSpace(someent, worldpos); 

See Also: GetEntityWorldSpace

GetEntityWorldSpace

Converts a local space position into a world space position of a specified entity.

Parameters: (GameEntity/GameId, Vector3 local position)

Returns: Vector3 world space position, or null if error

Example:

localpos = Vector3(10,10,10);
worldpos = GetEntityWorldSpace(someent, localpos); 

See Also: GetEntityLocalSpace

GetEntPosition

Gets the world position of an entity.

Parameters: (GameEntity/GameId)

Returns: Vector3 world position, or null if error

Example:

p = GetEntPosition(someent);

GetEntRotationMatrix

Gets the Matrix3 full transform of an entity.

Parameters: (GameEntity/GameId, Matrix3<optional>)

If you pass an Matrix3 as the 2nd parameter, that object will be filled in instead of a new Matrix3 returned. This can save memory allocations in a script that calls the function often by re-using the same object.

Returns: true if Matrix3 passed as 2nd parameter and filled in successfully, if no Matrix3 provided, returns Matrix3 for entity. Both return null on an error.

Example:

entMat = GetEntRotationMatrix(someent);
if(entMat)
{
     // do something
}
// re-use the same Matrix3 later
if(GetEntRotationMatrix(someent, entMat))
{
} 

GetEntVelocity

Gets the world velocity of an entity.

Parameters: (GameEntity/GameId)

Returns: Vector3 world velocity, or null if error

Example:

vel = GetEntVelocity(someent);

GetEntityInSphere

Finds an entity within a radius around a point that matches a particular class Id. It is set up so that it can be used in a loop to find all entities.

Parameters: (Vector3 position, radius, classid, start entity<optional>)

Returns: GameEntity found, or null if none found

Example:

p = Vector3(10,10,10);
radius = 20;
ent = GetEntityInSphere(p, radius, CLASS.ANYPLAYER);
dowhile(ent)
{
    // do something with it?
    // get the next one found
    ent = GetEntityInSphere(p, radius, CLASS.ANYPLAYER, ent);
}

GetEntityStat

Generic function for getting information about an entity, by name.

Parameters: (GameEntity/GameId, stat name)

Returns: stat, or null if error or stat doesn't exist. The type depends on the stat.

Example:

kills = GetEntityStat(someent, "kills");
deaths = GetEntityStat(someent, "deaths");
xp = GetEntityStat(bot.GetGameEntity(), "xp");

EntityKill

Kills an entity. Requires cheats to be enabled.

Parameters: (GameEntity/GameId)

Returns: true if successful, false if not

Example:

EntityKill(someentity);

See Also: CheatsEnabled

GetTeamStat

Generic function for getting information about an team, by name.

Parameters: (Team Id, stat name)

Returns: stat, or null if error or stat doesn't exist. The type depends on the stat.

Example:

score = GetTeamStat(TEAM.RED, "score");

GetGameEntityFromId

Converts a GameId to a GameEntity.

Parameters: (GameEntity)

Returns: GameId

Example:

ent = GetGameEntityFromId(2); 

See Also: GetGameIdFromEntity

GetGameIdFromEntity

Converts a GameEntity to a GameId.

Parameters: (GameEntity)

Returns: GameId

Example:

id = GetGameIdFromEntity(someent); 

See Also: GetGameEntityFromId

GetGameName

Gets the name of the currently running game.

Parameters: none

Returns: name of game

Example:

if(GetGameName() == "Quake 4")
{
}

GetModName

Gets the name of the currently running mod.

Parameters: none

Returns: name of mod

Example:

if(GetModName() == "etpub")
{
}

GetGameState

Gets the current state of the game.

Parameters: none

Returns: name of game state

Example:

if(GetGameState() == "Playing")
{
}

GetGameTimeLeft

Gets the current amount of time remaining in the game round.

Parameters: none

Returns: time left, in seconds

Example:

if(GetGameTimeLeft() < 30)
{
}

GetTime

Gets the current time elapsed in the game.

Parameters: none

Returns: time, in seconds

Example:

if(GetTime() > 30)
{
}

GetGoal

Gets a reference to a map goal by name.

Parameters: (name of map goal to get)

Returns: MapGoal if found, null if not

Example:

mg = GetGoal("MAP_FLAG_redflag");

See Also: GetGoals

GetGoals

Gets any number of map goals that match a regular expression. Stores the matching reference in the first table parameter. Does NOT clear the table, so it may be called multiple times to accumulate results.

Parameters: (table, team, expression)

Returns: none

Example:

goals = table();
mg = GetGoals(goals, TEAM.RED, "MAP_FLAG.*");

See Also: GetGoal

GetGravity

Gets the current gravity of the game.

Parameters: none

Returns: gravity

Example:

grav = GetGravity();

GetMapExtents

Gets the AABB map extents. Map extends are the bounds of the entire map.

Parameters: (AABB<optional>)

Returns: If no AABB passed as parameter, function will return the map AABB, otherwise the AABB parameter will be filled in with the results, and the function will return nothing.

Example:

aabb = GetMapExtents();
// or
AABB aabb;
GetMapExtents(aabb);

GetMapName

Get the name of the current map.

Parameters: none

Returns: name of map

Example:

if(GetMapName() == "oasis")
{
}

GetMaxPlayers

Gets the current max players supported by the game.

Parameters: none

Returns: maxplayers

Example:

if(GetMaxPlayers() > 10)
{
}

GetNumPlayers

Gets the current num players in the game.

Parameters: none

Returns: current players

Example:

if(GetNumPlayers() > 5)
{
}

GetNumBots

Gets the current number of bots.

Parameters: none

Returns: current # bots

Example:

if(GetNumBots() > 10)
{
}

GetModVersion

Gets the version of the current mod.

Parameters: none

Returns: version of mod

Example:

if(GetModVersion() == "DOOM 1.3")
{
}

GetPointContents

Gets the contents bits for a given position.

Parameters: (Vector3 position)

Returns: contents bits. Use bitwise manipulators along with constants from the global CONTENT table to check for specific content bits.

Example:

contents = GetPointContents(Vector3(10,10,10));
if(contents & CONTENT.WATER)
{
}

KickAll

Kicks all bots from the game.

Parameters: none

Returns: none

Example:

KickAll();

KickBot

Kicks a bot by name.

Parameters: (name)

Returns: none

Example:

KickBot("Fred");

MinBots

Sets the min bots.

Parameters: (# minbots)

Returns: none

Example:

MinBots(10);

See Also: MaxBots

MaxBots

Sets the max bots.

Parameters: (# maxbots)

Returns: none

Example:

MaxBots(10);

See Also: MinBots

OnTrigger

Registers a script function callback for a given trigger string.

Parameters: (trigger string, script function)

Returns: none

Example:

global myfunc = function()
{
};
OnTrigger( "Allies have built the Old City Water Pump!", myfunc);

See Also: Omni-bot Map Scripting

RegisterDefaultProfile

Registers a default profile that will be loaded for any bot that joins a specified class.

Parameters: (Class Id, script name)

Returns: none

Example:

RegisterDefaultProfile(CLASS.SOLDIER, "def_bot.gm");

ServerCommand

Executes a server command. Requires cheats to be enabled.

Parameters: none

Returns: true if cheats are enabled, false if not

Example:

ServerCommand("map oasis");

See Also: CheatsEnabled

SetAvailableMapGoals

Enables/Disables the available status of one or more map goals that match a regular expression, for a specific team.

Parameters: (Team Id, enable/disable, mapgoal expression string)

Returns: none

Example:

SetAvailableMapGoals( TEAM.ALLIES, false, "ATTACK.*" );

See Also: GetGoal, GetGoals

SetMapGoalProperties

Passes a table full of properties along to all matching map goals to attempt to set their properties.

Parameters: (expression, table of properties)

Returns: none

Example:

// Set the camp time for all attack and defend goals
SetMapGoalProperties( "ATTACK_.*", {mincamptime=15, maxcamptime=30});
SetMapGoalProperties( "DEFEND_.*", {mincamptime=15, maxcamptime=30});

See Also: Omni-bot Map Goals for a list of properties for each map goal type.

SetGoalGroup

Sets the goal or table of goals group name.

Parameters: (goalname or table, groupname)

Returns: none

Example:

SetGoalGroup( "SomeGoalName", "SomeGroupName" );

groupTable =
{
    "ROUTE_route1",
    "ROUTE_route2",
    "someothergoal",
};

SetGoalGroup( groupTable, "MyGroup" );

See Also: Util.DisableGroup, Util.EnableGroup, Util.GetGroup, Util.SetGroup, Util.ShowGroup

TraceLine

Performs a traceline collision test, and returns the results in a table. TraceLine calls are useful for testing visibility, line of sight, or for getting a collision point along a line.

Parameters: (Vector3 start, Vector3 end, AABB, collision mask, ignore user GameId, use PVS)

• Vector3 start - Start position of trace line.
• Vector3 end - End position of trace line.
• AABB - Pass an AABB if you with the line to have volume, otherwise pass null.
• Collision Mask - Mask of collision types to test. See global TRACE table.
• GameId - Ignore this GameId in the traceline. Usually the entity or bot it originates from.
• UsePVS - true to use PVS, false to ignore PVS

Always pass true to UsePVS if you need collision information from the call to TraceLine. UsePVS=false is useful when all you need to know is whether or not something is blocking the path from start to end, it will not give you the collision position. It is slightly faster in most cases to use PVS as an early out test, but doing so limits the amount of useful information you get back from the function. In many cases you don't need this information, so the extra speed is useful.

Returns: table of results

Results table contains the following information.

• fraction - 0.0 to 1.0 The ratio along the line the collision took place. Not always valid if UsePVS=true. Example: 0.5 means ray hit half way between the start and end.
• startsolid - true/false The traceline started inside a solid object. Not always valid if UsePVS=true

Additional properties are available if UsePVS=false and there was a collision.

• entity - May be null, the GameEntity that was hit in the collision.
• normal - The Vector3 normal of the collision point.
• end - The Vector3 world position of the collision.

Example:

// Do a traceline along a bots facing 1024 units out
start = b.GetEyePosition();
end = start + b.GetFacing() * 1024;
tr = TraceLine(start, end, null, TRACE.SHOT, b.GetGameId(), false);

// the fraction value tells us of a collision or not. If it's 1, there was no collision. If less than 1 there was a collision.
if(tr.fraction < 1)
{
    // tr.startsolid
    // tr.entity
    // tr.normal
    // tr.end
}