PICO-8 introductory tutorial

Hello reader!

I bring you an introductory tutorial to PICO-8.

In this tutorial we are going to:

• Create a player character.
• Apply movement to it.
• Create a simple level for the character to move in.

Please note that this tutorial assumes that you have some basic programming knowledge.

First of all, fire up PICO-8 and enter the console. In order to start off a new project just type.

save [projectname]

In my case it was `save tongull_test` which generated a file tongull_test.p8 . Once generated I typed `load tongull_test` to load the project in memory and then pressed escape to enter the PICO-8 IDE.

Displaying a character on screen

First off, I drew my little character in the sprite editor. I drew 3 sprites, one for when the character is standing still and 2 more for when the character is walking.

If you noticed, each sprite has an index assigned to it. This index is used in code. In order to display my character, I made use of the `_draw()` function which is called once every visible frame(roughly 30fps).

Please note that the _draw() function should be used for drawing objects on screen; logic is handled by the _update() function(more reliably called at 30fps). Inside that function we first call the cls() function which clears the the screen, then we call the spr() function in order to draw our sprite. In this function we will pass the index of the sprite and the X and Y coordinates of where we want to draw it.

In order to test out the application press CTRL+S to save and ESCAPE to enter the console then to run the application type `run [projectname]`

-- Double dash is used to write comments
function _draw()
    cls() -- Clear Screen
    spr(0, 50, 50) -- Sprite Index, x, y
end

Character Movement

Now that I displayed my character, let’s try to move it around! First of all I create an object called player to represent the player character and give it properties I needed.

player = {} -- initialising the object
player.x = 50 -- this will hold the player’s x co-ordinate
player.y = 50 -- this will hold the player’s y co-ordinate
player.sprite = 0 -- the current player sprite
player.speed = 2 -- the speed at which the player is going to move
player.moving = false -- Is used as a marker to see if the player is moving

Now that we have our object ready let’s create a function to handle the movement sprite animation. In the function we will cycle through the sprites to have movement animation.

function moveanim()
    player.moving = true -- Set the marker to indicate that the player is moving
    -- Check if the index is between 0 and 2
    if player.sprite > 2 then
        player.sprite = 0 -- if the index is over 2, reset
    end
end

Now in the `_update()` function we will listen the the user's input via the `btn()` function. In PICO-8 each player has up to 6 inputs(represented by index), 4 of which are directional. For player 1 the arrow keys serve as directional keys. Since our character will be only moving left and right we will use of 0 (left arrow key) and 1 (right arrow key) indexes.

When the left/right keys are pressed, the player x co-ordinate is modified by the player speed. If the x co-ordinate goes beyond the screen boundaries, we will set it to the opposite part of the screen.

In order to Log the X value, we will make use of the `print(text, x,y)` function. In Lua to concatenate string values we use `..` .

function _update() --called at 30fps
    player.moving = false
    if (btn(0)) then -- if left key is pressed
        player.x -= player.speed -- decrease the x by the speed
        if player.x < -10 then -- If the character moves beyond the left bound
            player.x = 128 -- Place character at the other side of the screen
        end
        moveanim() -- Call the move function
    end
    if (btn(1)) then
        player.x += player.speed
        if player.x > 128 then
            player.x = -10
        end
        moveanim()
    end
    if not player.moving then
        player.sprite = 0
    end
end

function _draw()
    cls() -- clear screen
    spr( player.sprite, player.x, player.y) -- draw the sprite using the values of our player object 
    print("x :"..player.x, 0, 0) -- Log the x value
end

Map/Level Editor

Now that our character is moving, but he is moving in empty space. Let's create a level for him to move in!

In order to do that we will make use of the sprite editor to create "tiles" to use in the map editor. The map editor is pretty simple to use, just select a sprite and draw it on the map.

The code is pretty simple too, just make use of the `map(cel_x, cel_y, sx, sy, cel_w, cel_h)` function.

function _draw()
    cls()
    map(0,0,0,20,124,124)
    spr(player.sprite, player.x, player.y)
    print("x:"..player.x, 0, 0)
end 

And there you have it, we have a little game to play around with.

You can see the finished project with an added little intro animation here . The source code is also available on github . Feel free to take a look and play around with it.


See you next time!