Native Functions

Native Functions

> LeekScript Tutorial

Now let's talk about LeekScript functions!

Functions are an essential part of programming. They let you store a series of actions that you can reuse whenever you like.

In Leek Wars, there are two kinds of functions:

We'll only talk about native functions for now.

What are they?

Native functions are the functions that LeekScript makes available to you. They're what let you get lots of information about the fight. They're also how you control your leek's actions.

Functions are easy to recognize thanks to their syntax:

functionName(parameters);

You've already seen some in the starter AI, in the chapter on the Editor. As a reminder:

// Four very useful functions var enemy = getNearestEnemy(); setWeapon(WEAPON_PISTOL); moveToward(enemy); useWeapon(enemy);

getNearestEnemy, setWeapon, moveToward and useWeapon are four functions that LeekScript makes available to you.

Even a basic grasp of their names can help you understand what a function is for without having to check the documentation. Function names are usually self-explanatory and show what they're used for.

The return value

What is a function's "return value"? Not every function has one, but a function can return a piece of information.

That's the case in this example:

var enemy = getNearestEnemy();

If you paid attention in the previous chapter, you understand that an "enemy" variable is created. And that, at the same time, it's assigned a value with the equals sign '='.

But what exactly is assigned to it? That's where the getNearestEnemy function comes in. This function returns the id of the nearest enemy.

So when your leek executes this code, it calls the getNearestEnemy function. The function returns the id of the nearest leek, which is then stored in the "enemy" variable.

If you're curious, you can add a debug:

var enemy = getNearestEnemy(); debug(enemy);

If you run this code in a 1v1 test fight, you should see the number 1, or 0. Leek ids in a fight are nothing more than numbers. In a fight with 4 leeks, they would be numbered from 0 to 3.

As you can see, debug is a native LeekScript function. You may be wondering why we put the "enemy" variable between the parentheses. We're getting there.

Parameters

That's what we call what goes between the parentheses: parameters. These little critters are really useful. What a function does depends on its parameters.

Back to the debug function: it displays a message in the fight logs. And you're the one who decides what that message says, thanks to a parameter.

If you pass the value 5 as a parameter to debug, the message will be "5". If you pass the text "I love leek soup" to debug, the message will be "I love leek soup".

Here's what happens with these functions:

var enemy = getNearestEnemy(); setWeapon(WEAPON_PISTOL); moveToward(enemy); useWeapon(enemy);

setWeapon makes your leek equip a weapon. To tell it which weapon to equip, you pass the weapon's id as a parameter. Here it's "WEAPON_PISTOL", a constant that refers to the Pistol weapon. This constant corresponds to the number 37, the pistol's id. You could write 37 instead of WEAPON_PISTOL and it would have the same effect. But using the constant makes the code easier to understand, and saves you from having to memorize the id of every weapon and chip.

moveToward moves your leek toward another one. To do that, the function needs the id of a target leek. That's where you bring out your "enemy" variable again. Remember that it now contains the id of your nearest opponent. By passing this variable to moveToward, you'll head toward that nasty leek.

With useWeapon, your leek will try to shoot at a leek. In the same way, you tell the function that you want to shoot at your enemy.

No return value, no parameters

Some functions don't return a value, and don't expect one either. But that doesn't make them useless!

Take the pause function, for example. It pauses the fight when you watch it. (It has no impact on the fight itself: it's the same as manually pressing the "Pause" button, or the "P" key on your keyboard, while watching a fight.) The function doesn't expect any parameters either. So you can't influence its behavior.

But let's get back to return values. Look at this code:

var enemy = getNearestEnemy(); moveToward(enemy);

What if I told you that moveToward has a return value? You don't have to retrieve a function's return value. moveToward returns the number of movement points used. If you're two cells away from your opponent, the function will only move you one cell. Once you're right next to your opponent, you can't move any closer, unless you walk on their head. In that case, not all of your movement points will be used. If you only used one, the function will return the integer "1".

For example:

var enemy = getNearestEnemy(); var mpUsed = moveToward(enemy); debug("I moved " + mpUsed + " cells!");

So if you're not interested in this information, there's no need to retrieve it. The same goes for getNearestEnemy, for example, but you'll admit it would be pretty pointless to call that function without retrieving its return value.

Conclusion

Native functions will be useful to you, really, really useful. Without them, you might as well say you can't do anything with your leek.

This concept is extremely important, and you'll realize its full power in the chapter on custom functions.

Feel free to take a look at the Functions in depth chapter. You'll learn how to read the documentation, which contains an exhaustive list of the functions available to you in Leek Wars (see also the Functions page).