Code structure

Setting up your gadget

The CPU will run your entire Lua code from top to bottom, once. Statements will run in the order you write them in, and you can only 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, you can place all of your gadget's setup statements there. They will run on the first tick of the gadget only.

Update function

To make your code repeat for every tick that your 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.

You can declare your update function anywhere in your script, as long as you follow the rule that anything it uses must be declared before it 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. Your CPU will have a number of event channels it supports, and for each one of them you can define a function 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 you're expecting events on.

For example, if you have a KeyboardChip connected to your 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 your source code into separate files. To use the require function, the file you're trying to import must also be present in your gadget's assets, and it must return a table with values you want to use in your 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, minand 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.

Code structure

Setting up your gadget

Update function

Other special functions

Using require()

Using `require()`