Inspecting a basic game for Playdate
Tags: gamedev, beginners, playdate, lua
Published: 2023-02-25 18:19:02

In the last article, I referred to Playdate's official documentation, [Inside Playdate](https://sdk.play.date/1.13.1/Inside%20Playdate.html#_compiling_a_project), to successfully compile the source code from a sample open-sourced game on Github.

Now I'd like to become more familiar with the source code itself.

Of course, I want to start with something simple.

Thankfully, Inside Playdate features such an example.

## Studying the example `main.lua` file
[This section of Inside Playdate](https://sdk.play.date/1.13.1/Inside%20Playdate.html#basic-playdate-game) features an example `main.lua` file.

I intend to study it one line at a time.

```
import "CoreLibs/object"
import "CoreLibs/graphics"
import "CoreLibs/sprites"
import "CoreLibs/timer"
```

First are several core libraries. A library is a collection of code that makes doing something a lot easier than writing the code yourself.

```
local gfx <const> = playdate.graphics
```

Next is this local constant - a variable that cannot be reassigned. It's name is `gfx`. The document states that this is just for convenience: writing three letters instead of 16 is always preferred.

```
local playerSprite = nil
```

Another local variable, starting value-less.

```
function myGameSetUp()
  ...
end
```

A function with a helpful name.

What's inside?

```
local playerImage = gfx.image.new("Images/playerImage")
```

A local variable.
I see now why the constant `gfx` was a good idea.
But for full understanding, the expression is:
```
playdate.graphics.image.new("Images/playerImage")
```

So, stored in `playerImage` is a literal image file located in the Images folder inside the source code's root directory.

```
assert( playerImage )
```

Using code to validate and confirm the contents of `playerImage`.

```
playerSprite = gfx.sprite.new( playerImage )
```

Again, the long form is:
```
playdate.graphics.sprite.new(playerImage)
```

This creates a sprite from the image?

Interesting that it doesn't just use the image, but creates a sprite from it instead.

```
playerSprite:moveTo( 200, 120 )
```

The use of the colon is new syntax to me.
It seems like `moveTo` is a method of `playerSprite`.
I'm used to a period representing accessor syntax.

This moves the center of the sprite to 200,120 - the center of the screen.

```
playerSprite:add()
```

The comment in the documentation states `This is critical!`.

It seems the sprite may not appear unless this method is invoked...even though the line above technically moved it to a spot on the screen?

```
local backgroundImage = gfx.image.new( "Images/background" )
assert( backgroundImage )
```

These two lines are identical - aside from variable and file names - to what's above for the `playerImage`.

```
gfx.sprite.setBackgroundDrawingCallback(
  function( x, y, width, height )
    backgroundImage:draw( 0, 0 )
  end
)
```

It's odd that sometimes a `.` is used to access a method, and other times a `:` is used. There must be some subtle difference that I'm missing in Lua.

Anyway, this function seems to expect a function as its first argument.

The expected function seems to expect four arguments.

Inside of it, the image is rendered at the top-left of the screen.

```
myGameSetUp()
```

The file invokes the custom function.

```
function playdate.update()
  ...
end
```

This function is a built-in event on the playdate.

I'm familiar with it from Pulp.

```
if playdate.buttonIsPressed( playdate.kButtonUp ) then
  playerSprite:moveBy( 0, -2 )
end

if playdate.buttonIsPressed( playdate.kButtonRight ) then
  playerSprite:moveBy( 2, 0 )
end

if playdate.buttonIsPressed( playdate.kButtonDown ) then
  playerSprite:moveBy( 0, 2 )
end

if playdate.buttonIsPressed( playdate.kButtonLeft ) then
  playerSprite:moveBy( -2, 0 )
end
```

In English:
> If the current button pressed is one of the four d-pad buttons, then move the sprite by two pixels in the appropriate direction

I wonder why the button name is prefixed with a `k`.

There's that `:` again.

```
gfx.sprite.update()
playdate.timer.updateTimers()
```

> Draw sprites and keep timers updated

## More questions
- What's with the `.` and `:` syntax?
- Why the initial `k` in the button names?
- Why sprites vs. images?
- What even is a sprite, technically?
- How would I make one so that I could try out this game?

It seems like I need to research sprites, next.