Tutorial:Hamster Ball

File:HamsterBall.png

Screenshot of the hamster ball.

This game is a very simple example of how to add a resource (in this case a simple image) to the engine and then move that around with the arrow keys. Here is the entire source, in case you haven't downloaded it:

-- Tutorial 1: Hamster Ball
-- Add an image to the game and move it around using 
-- the arrow keys.
-- compatible with löve 0.6.0

function love.load()
   hamster = love.graphics.newImage("hamster.png")
   x = 50
   y = 50
   speed = 100
end

function love.update(dt)
   if love.keyboard.isDown("right") then
      x = x + (speed * dt)
   elseif love.keyboard.isDown("left") then
      x = x - (speed * dt)
   end

   if love.keyboard.isDown("down") then
      y = y + (speed * dt)
   elseif love.keyboard.isDown("up") then
      y = y - (speed * dt)
   end
end

function love.draw()
   love.graphics.draw(hamster, x, y)
end

It's not the most complicated program in the world, but we have to start somewhere. Keep in mind that everything after the -- characters in the code is a comment and will be ignored by the program.

-- You can write whatever you want here!

Alright, next you need to know that for things to work you need to have a function called load. This is where the game is initiated and where everything begins. Although they aren't strictly required, it's best to also include love.update() and love.draw() for now. The meaning of the various functions will be described shortly.

-- This is an empty program
function love.load()
end

function love.update(dt)
end

function love.draw()
end

Alright, let's get down to explaining what the specific code for this game does.

The load function looks like this:

function love.load()
   hamster = love.graphics.newImage("hamster.png")
   x = 50
   y = 50
   speed = 100
end

What we are doing here is adding the file hamster.png to our game assigning that image to a variable called hamster. We are also declaring three variables: x, y and speed. These will all play a part in the program later.

The update function looks like this:

function love.update(dt)
   if love.keyboard.isDown("right") then
      x = x + (speed * dt);
   elseif love.keyboard.isDown("left") then
      x = x - (speed * dt);
   end

   if love.keyboard.isDown("down") then
      y = y + (speed * dt);
   elseif love.keyboard.isDown("up") then
      y = y - (speed * dt);
   end
end

First of all you will see that this function accepts a parameter called dt (an abbreviation of "delta-time") which represents the amount of time which has passed since this function was last called. It is in seconds, but because of the speed of todays processors is usually smaller than 1 (values like 0.01 is common). We are using this value to move the hamster ball at the same speed, no matter how fast the player's computer is.

In the function we check whether the keys right, left, up or down are pressed by calling the love.keyboard.isDown(key) function with the appropriate parameters (a full list of the keyboard keys can be found here). If any of the right keys are pressed then the x or y values will be incremented by the appropriate amount (in this case speed times dt which means that the ball will move at a speed of 100 pixels per second; try changing the speed value in the load function to see what happens).

The draw function looks like this:

function love.draw()
   love.graphics.draw(hamster, x, y)
end

Not a lot happening, but this is where the magic is done. The image contained in the hamster variable is drawn at the x and y coordinate.

That is basically it for your first game. Try messing around with the variables in the love.load function to see what effects they have.

Remember that .love files can be opened in standard archiving software, like WinZip or 7zip. They are actually just renamed .zip-files!