Function

From LuaSTG Wiki
Jump to navigation Jump to search

Function node defines a function and assigns it to a local or global variable. Because it can have children nodes, we can put ifs, repeats, tasks, create bullets/enemies and code nodes under it, which will be executed every time the function is called.


Parameter List[edit | edit source]

Every function has a parameter list. A parameter list may contain zero or more parameters. Upon defining the function (function definition), besides giving a name to the function variable itself, we need to give a name to each parameter of the function, if there is any. Upon calling the function (function call/invocation), we need to give a value to each of the parameter the function has.

In Lua/LuaSTG, When the number of values we give to a function is less than its number of parameters, the rest of the parameters will be filled with nil starting from the right; when the number of values we give to a function is more than its number of parameters, the rest of the parameters will simply be ignored.

Returning Values[edit | edit source]

Same as raw Lua, a function node can have a return statement by putting a Lua code node with "return value" under it, where value is the value you want to return.

In general, functions can return values of any data type. A function may return one or more values. As an example, we may return the following items:

  1. A single number: "return a + 1". The expression a + 1 evaluates to a single number, and the function will return the number.
  2. A list: "return {1, 2}". The expression {1, 2} creates a temporary list with first entry 1 and second entry 2.
  3. Two or more numbers: "return 1, 2". This example returns two numbers, but more expressions can be appended if separated by commas.

For the case with two or more numbers, suppose a function func() has this return statement "return 1, 2", we can write "local x, y = func()" to create two variables to accept the return values. That is, this statement assigns 1 to x and 2 to y.

Unlike some languages like Java or C, the type of return value of a function does not need to be specified in function definitions in Lua. The type of return value is determined at runtime.

Examples of Use[edit | edit source]

Example 1[edit | edit source]

We will first look at the following example of function node.

Create function example 1.png

We have created a function that takes in a reference to a unit and return the angle from its position to the player's position, and we can use that to create aimed bullets. Alternatively, we could have just called the function Angle(self, player) directly in Angle attribute of the create bullet node, or set the Aim to player attribute as true instead.

The above function node will get translated to Lua code "local function AngleToPlayer(unit) return Angle(unit, player) end" when the script is run.

Example 2[edit | edit source]

As another example, take a look at the following stage script.

Create Function Example 2.png

When the script is run, two waves of enemies will be created, with 10 enemies in each wave moving towards different directions.

Recommendations[edit | edit source]

  1. Function node can be put at the very start of a script, or inside a spell/stage task, depending on where you want to call it. If you know how to, it is also an option to copy the function into a separate file and include it in data.
  2. Try to give your function a descriptive name of what it does, and be specific about the name you choose. For example, a function that fires an aimed bullet may be better named by createAimedBullet instead of createSingleBullet.
  3. Try to follow one of the variable naming conventions, like using underscore naming convention for all functions.
  4. It is a good programming practice to use functions as a tool to break large segments of code down into small pieces of functions, each one of them only does a single thing, if that is possible. This allows the code to be re-used when needed, simply by calling the function; at the same time, you can more easily understand what particular function a piece of code does. It should be noted, however, that because many stage scripts will only be used once, this is not a strict programming practice to follow as we are using LuaSTG to make scripts. It is a good idea to do so if you foresee that a function will be used again later on.
  5. If the parameter list of a function gets too long at some point, you may consider using a Lua list to pass in parameters. In this way you may also use Lua list indexing to access those parameters with strings, or just assign them with [1], [2], [3]...
  6. It is possible to create tasks in functions. This is handy in many situations where we may want to assign tasks that do the same thing to different kinds of objects.