Four

Docs

Getting running

Include the four.js file into your html page. This can be done by downloading and including the file into your script, or by using this CDN link.

<script src="https://cdn.jsdelivr.net/gh/hashbangcode/four@main/four.js"></script>

The whole game engine runs through this single file.

Then, start writing your JavaScript code. You'll need an update() and draw() function to update and draw the items in your game.

Here's a basic template of a game.

function init() {
  // Called once at the start of the game.
  // Use this function to set things up.
}

function update(delta) {
  // Called at the end of the game loop.
  // Use this function to update your game logic.
}

function draw(delta) {
  // Called at the start of the game loop.
  // Use this function to draw items on the grid.
}

Other than drawing the boxes, everything else is taken care for you. The game loop update is performed for you.

Get bonus points by naming the game using a pun based on the number four :)

Grid

The grid used in the game as the following structure.

If we want to target the bottom right square we would use the coordinates 3,3.

Variables

The following variables are important to the game.

grid

This is an array of "box" objects that contain information about the position of the box in the grid. The box item contains the following values.

• column : The column count of the grid item.
• row : The row count of the grid item.
• x : The x coordinate of the upper left hand corner of the grid item.
• y : The y coordinate of the upper left hand corner of the grid item.
• width: The width of the grid item.
• height: The height of the grid item.

Core Functions

init()

Run once when the game is setup. You can setup any varaibles that you need for the game to work here.

update(delta)

This is called at the start of the game loop. Add your game logic here and update the elements in your game.

The delta parameter can be used to synchronise the update calls with the current frame. Although the function is called every 60th of a second there will be a small discrepency between one call and the next, which can be corrected by using the delta parameter. The delta shows the difference in time between one call and the next.

One way to calcualte the difference between two frames is to multiply the delta value by 60.

interval = (delta * 60);

Since we are running at 60 frames a second, and the delta will be a float value, the caluclated value 1, plus the difference between one frame and the next.

draw(delta)

Add your drawing functions here. This is where you go through your game logic and call fillBox() function to draw items in your game grid.

The delta parameter works in the same way as the parameter in the update function.

Note that there is nothing technically stopping you from writing drawing functions in the update() function, but the idea is that you separate concerns.

Functions

A number of additional functions exist for you to interact with your game.

fillBox(box, colour)

Fill a box with a colour. Teh colour must be a CSS compatible colour, so any of the named colours or a hex value will work.

displayScore(score)

This function will clear the grid and animate a score on the grid. The numbers scroll from right to left.

wait(seconds)

Pause the execution of the game for a number of seconds.

randomRange(min, max)

Get a random number between two values.

randomElement()

Gets a random element from the grid.

cls()

Clear the entire game grid.

Listening To User Actions

A number of event functions are set up that can be used to perform actions on the grid.

userActionClick(box)

The box parameter here is the box object that was clicked on by the user.

userActionKeyPress(direction)

The direction will be one of 4 direction constants.

• KEYPRESS_LEFT
• KEYPRESS_UP
• KEYPRESS_RIGHT
• KEYPRESS_DOWN

It is common to use a switch statement to interpret these directions.

function userActionKeyPress(direction) {
  switch (direction) {
    case KEYPRESS_LEFT:
      // Left.
      break;
    case KEYPRESS_UP:
      // Up.
      break;
    case KEYPRESS_RIGHT:
      // Right.
      break;
    case KEYPRESS_DOWN:
      // Down.
      break;
    default:
      // Do nothing.
      break;
  }
}