Code structure

This is a primer on Lua **code structure** for gadgets in Retro Gadgets.

## Setting up your gadget

The CPU will run the entire Lua code from top to bottom, once. Statements will run in the order they're written in, and it's only possible to reference what has already been declared. For example, if you have a method that uses a value stored in the variable player\_x, the following example code in isolation will not work:

```
drawMyPlayer(player_x, player_y)

local player_x = 10
local player_y = 10

```

Before you can use those variables, their declaration needs to come first:

```
local player_x = 10
local player_y = 10

drawMyPlayer(player_x, player_y)

```

Note also that this is only a simplified code example and the method drawMyPlayer is illustrative and not a global that already exists in *Retro Gadgets*.

Since everything on the root of the Lua script is run through once, all of a gadget's setup statements can be placed there. They will run on the first tick of the gadget only.

## Update function

To make code repeat for every tick that a gadget is powered on, *Retro Gadgets* expects a specially named update function like so:

```
local player_x = 10
local player_y = 10

function update()
    drawMyPlayer(player_x, player_y)
end

```

In this case, player\_x and player\_y are set up only at the power up of the gadget and then are not set again. Meanwhile at every single tick of the gadget, the method drawMyPlayer is called to run.

The update function can be declared anywhere in your script, as long as the rule that anything it uses must be declared before it is followed as explained above.

## Other special functions

Just like how Retro Gadgets expects a function specifically named update to run it at every tick, it also expects specifically named functions to work with events. The CPU will have a number of event channels it supports, and for each one of them a function can be defined that will be run when each of those channels gets triggered. The function must be named eventChannelN where N is replaced by the number of the channel one is expecting events on.

For example, if there is a KeyboardChip connected to the CPU's event channel 2:

```
function eventChannel2(sender, event)
    if (event.ButtonDown) then
        log("user pressed " .. event.InputName)
    end
end

```

This will run, and print on the Multitool debug screen, only each time the user presses down a key (which is when the event is triggered).

## Using require()

*Retro Gadgets* supports the require function built into Lua to make it easier to modularize source code into separate files. To use the require function, the file to import must also be present in the gadget's assets, and it must return a table with values to use in the main file. For example:

utils.lua:

```
utils = {}

function utils.min(a, b)
    if (a < b) then return a end
    return b
end

function utils.max(a, b)
    if (a > b) then return a end
    return b
end

return utils

```

This file, named utils.lua returns a table which has been populated with two functions, min and max which return the smallest and the largest of two numbers respectively.

CPU0.lua:

```
local utils = require("utils.lua")

log(tostring(utils.min(2,4)))

```

The CPU0.lua file, which is what will run in our CPU, first imports the table returned by the file utils.lua into its own local variable named utils, then uses the min function from there to print out the smallest number between 2 and 4.