VSLib Developer Guide - Chat Triggers

8.6K
0

Sharing is temporarily disabled

Left 4 Dead 2 Guide

November 2015

Hello, World! (Chat Triggers Crash Course)

What kind of introductory document would this be if it didn't have the classic Hello, World example? Instead of showing a Hello World function, let's hit home: consider a situation where the player aims at a random entity and types !move into the chatbox. We can get all the bots in the game to move to that entity simply by coding the following (explanations will come after):

function ChatTriggers::move ( player, args, text )
{
local aimedEntity = player.GetLookingEntity();
if (aimedEntity != InvalidEntity)
{
foreach ( bot in Players.Bots() )
bot.BotMoveToOther ( aimedEntity );
}
}

The VSLib ChatTriggers namespace is special; functions in that table are called according to chatbox input (hence the term ChatTriggers). The function ChatTriggers::move will fire whenever someone types !move into the chatbox. VSLib will automatically call the function, passing several important arguments: the player argument is the player who typed !move, args will contain any secondary parameters (more on that later), and text will contain the original chatbox text. The rest should be self-explanatory; the command player.GetLookingEntity() will return the entity the chatbox user is looking at. If the aimedEntity is valid, then loop through all the bots and move the bots to the aimed entity.

Chat Triggers Basics

Chat triggers allow you to interact with your players. Creating a trigger is very easy. Simply follow this template:

function ChatTriggers::YourTrigger ( player, args, text )
{
// your code here
}

Replace "YourTrigger" with whatever you want. The player variable holds the player who typed the command, args contains any secondary arguments, and text contains the original text. We will go over all of them in this document.

For example, in this code, typing !helloworld into the chatbox will output a message:

function ChatTriggers::helloworld (player, args, text)
{
Utils.SayToAllDel( "Hello, world! %s fired a chat trigger!", player.GetName() );
}

Passing Parameters

Using ChatTrigger Arguments

Sometimes, you want players to be able to enter data. Here's an example on how to use arguments:

// Ask them a simple question hehehe....
Utils.SayToAll ( "5 + 5 = ?" );
function ChatTriggers::ans ( player, args, text )
{
local theirAnswer = GetArgument(1); // Get the first parameter
if (theirAnswer == "10")
Utils.SayToAllDel( "Correct!!!" );
}

In the above example, they will receive a chatbox message that asks them what 5 + 5 equals. Then, anyone can type !ans 10 to answer the question. If they enter the correct answer (i.e. 10) into the chatbox, it will print "Correct!!!" into the chatbox. It seems pretty complicated, but it's actually very simple. Let's consider another example:

Utils.SayToAll ( "Enter any two numbers that equal 10. Type !ans followed by two numbers. E.g. !ans 5 2" );
function ChatTriggers::ans ( player, args, text )
{
local firstNumber = GetArgument(1); // Get the first parameter
local secondNumber = GetArgument(2); // Get the second parameter
// Make sure that they entered two answers
if (firstNumber == null || secondNumber == null)
{
Utils.SayToAllDel( "You need to enter two numbers!" );
return;
}
// Convert their answers to numbers
firstNumber = firstNumber.tointeger();
secondNumber = secondNumber.tointeger();
// See if their answers add up to ten
if (firstNumber + secondNumber == 10)
{
Utils.SayToAllDel( "Correct! %i + %i = 10!", firstNumber, secondNumber );
}
else
{
Utils.SayToAllDel( "WRONG! %i + %i is not 10!", firstNumber, secondNumber );
}
}

Here's what that looks like:

Hopefully that makes more sense. Give the above example a good analysis if you do not understand. GetArgument() will return any parameters passed (in this case, 7 and 3). If you wanted to, you can also access the args array manually. args[0] holds "7", and args[1] holds "3". If you wanted to, you can even pass words and retrieve them with GetArgument, like so:

function ChatTriggers::foo ( player, args, text )
{
local firstParam = args[0]; // Get the first parameter
// Make sure that they entered something
if (firstParam == null)
{
Utils.SayToAllDel( "You need to enter something!" );
return;
}
if (firstParam == "apple")
Utils.SayToAllDel( "HOW DID YOU KNOW o_o" );
}

Simple (if you've been testing along)! The best way to get acquainted with the ChatTrigger system is to get out there and experiment!

Passing In Sentences

Sometimes, you want to retrieve an entire sentence (not just single words or numbers). With VSLib, that's also pretty easy. Utils.CombineArray(args) will return a string for you. For example, if you enter !ans hello world, CombineArray will return "hello world" (without the quotes of course) if you pass the args array to it. It's pretty handy when you need to ask players some open-ended questions!

Limiting Usage of Chat Triggers

There may be times when you want a chat trigger to work and times when you don't want it to work. All you have to do is return null when you don't want to respond to a command request. This is useful for a number of things. For example, if you have a !radio feature in your map / mutation, and the player doesn't have the radio in their inventory, you don't want to activate the radio of course, so you can just return null.

If you wanted to create temporary chat triggers (ones that can be added, removed, and re-used), then you can use EasyLogic::AddChatTrigger like so:

function MyFuncYeah ( player, args, text )
{
// hehehehe
Utils.SpawnZombieNearPlayer( player, WITCH, 100, 32 );
}
// Here's how you can add a temporary chat trigger
EasyLogic.AddChatTrigger ( "spawnwitch", MyFuncYeah ); // Add a !spawnwitch command
// And here's how you can remove a temporary chat trigger
EasyLogic.RemoveChatTrigger ( "spawnwitch" );

There shouldn't be too much need for temporary chat triggers (since you can just return null from a permanent chat trigger when you don't want to respond to a request). However, use whatever floats your boat.