FAQ

Frequently asked questions about the AllTheHaxx Lua API.

What is Lua?

Lua is a dynamic scriptlanguage which can be embedded in other discrete programs. It allows to run external Lua-Scripts in the program through an embedded Just-In-Time-Compiler (because we use LuaJIT, normal Lua only offers an interpreter).

What do I need?

Through downloading the AllTheHaxx client the first step is already done. We suggest to use a Lua-capable editor (notepad++, any IDE editor, not the standard windows editor). Also reading this tutorial is really helpful (if not vital; experienced programmer can read through it fast tho).

What can be done with Lua?

We implemented Lua in our script in a way that you can do as many stuff as possible. You can mess around in the LuaConsole (F6) or write your own functions, scripts etc...

How is the System set up?

You can write your own functions or scripts in .lua files and run them through our Lua-GUI in the settings or you can write local functions in the LuaConsole (they won't be saved on closing the client!). Each .lua file has their own "LuaSpace", that means it doesn't clash with other scripts in any way. In our system you can simply bind your written Lua-Functions to an Ingame-Event, such as OnTick, which is called every 50 times per second by the client. Please note : We, the devs, must implement all Ingame-Functions to the Lua-API, so it might occur that there is no specific function for your needs provided, in that case contact the devs through skype or our QuakeNet Channel. Anyway, we try to implement as much updates with new necessary Lua-Functions as possible.

Pros and cons for using Lua?

Pro

• No compilation needed
• You don't need to know C++ or any Teeworlds related coding stuff
• Your written Lua-Stuff won't (usually) crash your client; error messages are printed in Teeworld's console

Contra

• You won't be able to rewrite the whole client to a new thing, you can only change the things that are offered to change and add minor new functionalities to it.
• You have to read through this documentation.
• You have to read through this documentation accurate if you can't programm at all, and we also recommend to checkout another Lua as this one is far from complete (there are great videos!).

Basic Lua Programming

In this chapter we will explain the basic Lua-Syntax (no API-stuff yet!); if you are new to programming in general you should start reading from here; the rest should just look at the syntax and continue. This chapters intention is to refresh your Lua skills.

Comments

A comment in lua starts with two dashes ("--"). Everything behind will be ignored during execution. If you want to outcomment a whole block of code, you can do so by putting --[[ at the start of your comment, and ]] at the end.

Variables

Variables are used to store (and read) data in any way. That's all, Lua is dynamically typed, this means there are no datatypes etc., so you don't need to mind anything. Variables must start with a letter and should indicite what they are storing by their name.

x = 10 		-- the number 10 is now stored in the variable x :)
y = "Text" 	-- y stores now the string "Text"
x = y 		-- x has now the same value as y → x is now "Text"

In General you can store anything you want in variables in Lua, even functions.
Valid operators for variables (and general)
Mathemathical: +, - , *, /, =

Functions

Functions are a seperate part of a script, they only do their stuff if you call them. Otherwise they won't do anything.
Functions can get some input-variables (so called 'parameters') and can return one value or in internal in Lua multiple values (but this is usually not needed).

The structure of a function looks like this:

function Name(ParameterOne)
	-- do stuff here
	return something -- optional, also multireturn is possible!
end

Example:

function Sum(Number1, Number2)
	NumberSum = Number1 + Number2 -- sets the variable NumberSum
	return NumberSum -- returns the variable NumberSum
end

As stated, this won't do anything on its own: You need to call the function. This can be achieved like in this short example programm:

function Sum(Number1, Number2)
	NumberSum = Number1 + Number2 -- sets the variable NumberSum
	return NumberSum -- returns the variable NumberSum
end

x = 5
y = 10
Result = Sum(x, y) -- the function is called, sums both numbers and returns 15; this number then is stored in the variable 'Result'
function HelloWorld() -- no parameters!
	print("Hello world! The sum of "..x.." and "..y.." is "..Result) -- the ".." operator glues two pieces of text (strings)
end

HelloWorld() -- call the function

This simply prints "Hello world! The sum of 5 and 10 is 15" into the Teeworlds-Console. Try it for yourself!

The if-statement

This statement is important when you want something to be done based on a condition.

Send a chatmessage when someone says something in the chat, quit the game if you died 5 times and any other things bound to conditions you can think of.
General syntax:

if Statement then -- "Statement" can for example be 5 ~= 3 (always true)
	-- do stuff...
end

Statements are usually comparisons of variables, numbers, texts, returnvalues from functions or anything else.

Operators

• ==

  This operator in an statement returns true if the data left and right of the operator have the same value, thus are equal!

  x = 10 -- x is now assumed to be 10 in any further examples!
  if x == 5 then
  	print("x is 5!")
  end

  This is a false statement, because x is declared as 10 and 10 is not 5, so the print function will not be called.
  In contrast:

  if x == 10 then
  	print("Yey, x is 10!")
  end

  This is a true statement because x is declared as 10 and 10 is equal to 10, so you will find a nice message in your console by the print function.

• ~=

  This operator is the opposite of ==, it will return true if the equation is not equal
• TODO: Add the rest. While you see this message as a user... Just use google for now.

Loops

TODO: Add the rest. While you see this message as a user... Just use google for now.

Setting Up A Script

Now you know what a function is, what variables are and other useful stuff. Now we can start writing our scripts.

General

In general a script is made out of 2 parts:

• 1: One or multiple functions which do the main work of the script.
• 2: Variables which are used for all functions of that script outside of any function, usually at the top/start of the script
  + some functions needed to initialize the script.

Example:

x = 0 -- we initialize x for all functions
a() -- we initialize the script here by calling the function a()
function a() -- does something with x
	x = x+5 -- add 5 to x
	b() -- call b to print x
end
function b()
	print(x)
end

In the end the following will happen:
x = 0 → function a is called, it increases x by 5 (x is 5 now) and calls b().
b() then simply prints 5 in the console.
Though neither a() nor b() have gotten the variable x as parameters they can acces it because x is available for both, a() and b() (and any other function in this file...). => x is global for both functions.

API Items

This is an important chapter as it's the core of our API.

Events

There are events and other items like functions or variables in our API. We will start with events here.

To understand it we should face the following problem: You write your script with its variables, functions etc.
But how does Teeworlds know when to call them?

That's where events come in:
Teeworlds (as many other games, too) has intern events. These are functions in Teeworlds that are called after a specific thing happened, and they handle this event.
We built our API in a way that allows you to bind your own written Lua-functions a specific event that you need. If this event happens in Teeworlds, your function will be called.

The following events are available in Lua (for now):

TODO: Taken from old docs, i think there are more events now :D

Functions and variables

There are also functions and variables that our API offers to interact with the game.

Custom Types

Last but not least: Custom types. These are used in Teeworlds only, and are very useful for certain things. For example vectors can be used to store coordinates, colors and similar stuff.

Note for vectors: Some Teeworlds functions or variables representing vectors. Now you know how to deal with them.

Support

If you need any help feel free to contact us.

IRC

You can reach dozens of developers (including us) via our IRC channel. Please stick to the rules anyways.

Visit irc.quakenet.net → Channel: #AllTheHaxx
...or simply use the IRC Api in the AllTheHaxx client (F5 → Join)

License

What you can and can't do with this project.

Released under MIT License. TODO: use a different license to fck B|Ice

We have released AllTheHaxx under the MIT License which is stated as:

Copyright © 2011 by _Company_

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.