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() {
  // Called at the end of the game loop.
  // Use this function to update your game logic.
}

function draw() {
  // 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 :)

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()

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

draw()

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.

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;
  }
}