Test Arena Developer's Guide

The following section is arranged as follows.

• GLOBAL Object

• Drawable Objects

• TEST_ARENA Object

• Test Arena Page States

GLOBAL object (global.js)

The global.js file provides a number of useful functionalities for error logging and some convenience methods for performing tasks such as appending information to div elements.

One that may be the most immedietely useful when writing and debugging your game is the eventLog's logMessage function.

		var type = "status"|"warning"|"error"|other
		var message = "An error occured"
		GLOBAL.eventLog.logMessage(type, message)

This function will...

1. Apply a color to the message based on the type. Green for status, orange for warning, red for error, and the inherited color for any other value.

2. Flash your message at the top of the page for 3 seconds or until a new message is logged.

3. Add that message to the page's event log.

Several other functions are available in the GLOBAL object defined in this file. Open the file to discover them.

Drawable Objects (drawable.js)

The drawable.js file defines several convenience objects that implement the constructor pattern.

The constructor for each type takes a single options object as an argument. The options available to each type are specified below.

All of the below types have their own overridden version of the draw() method. This makes it very convenient to simply store all your drawable objects in a structure, then have your GAME.drawBoard() method loop through that structure and call draw() on each of them.

See https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API/Tutorial for more information and clarifications on the options below.

Required options are indicated with a *

• drawableObject: The most basic drawable element.

  All other drawables derive from this object and share all of the following options.

  • x * : The x position (pixels) of this object's top left corner on the canvas.

  • y *: The y position (pixels) of this object's top left corner on the canvas.

  • width *: The pixel difference between the top left and top right corner.

  • height *: The pixel difference between the top left and bottom left corner.

• drawableRectangle: Add a few more options onto drawableObject to support borders.

  Extra Options:

  • borderWidth: Defaults to 1 (px)

  • fillStyle: Defaults to 'white'

  • strokeStyle: Defaults to 'black'

• drawableImage: dd a few more options onto drawableObject to support loading an image from a file, and mapping a specific region of that image to a particular region on the canvas.

  Extra Options:

  • imageSrc *: url to the image file.

  • loadedCallback *: A function to call when the image has been loaded into memory and is ready for use.

  • sourceX, sourceY, sourceWidth, sourceHeight

    • These properties allow you to crop a specific region of the entire source image to be drawn into the canvas space specified by the x, y, width, and height options.

    • If not specified, these default to the values of the x, y, width, height attributes respecively.

    • See canvas drawImage documentation for more information regarding how this works.

  • visible A boolean attribute indicating whether this image should be drawn to the canvas upon calls to draw().

    • Defaults to true.

    • You will likely programmatically alter this attribute as your game is running.

• drawableSprite: Extends the drawableImage object to allow automatic looping through a horizontal sprite sheet.

  This is accomplished by dividing your entire image into a number of frames.

  Extra Options:

  • indexStart: Indicates the frame index to start at. Defaults to 0.

  • numberOfFrames: Divide your image into this number of equal width frames. Defaults to 1.

  • ticksPerFrame: Number of calls to draw() before changing to the next frame.

    • Defaults to 1.

    • You'll need to play around with this for your particular sprites but we found values between 8 and 12 to be useful for the running, attack, and defend sprites in Save The Island.

  • loop: A boolean attribute indicating whether the sprite should return back to frame index 0 after finishing looping through all of the frames in the sprite sheet.

  Note regarding drawableSprite.draw()

  • When numberOfFrames == 1, it is drawn exactly as a drawableImage would be, passing the sourceX, sourceY, sourceWidth, sourceHeight, x, y, width, height properties along to context.drawImage(...) without modification.

  • When numberOfFrames > 1

    • the sourceWidth used in the context.drawImage call is computed as sourceWidth / numberOfFrames. Thus the sourceWidth should always be set to the actual width of the entire spritesheet.

    • sourceX is ignored and computed as currentFrameIndex * sourceWidth / numberOfFrames

TEST_ARENA Object (testArena.js)

The testArena.js file defines and maintains a global TEST_ARENA object. The following attributes of this object may be useful for game developers.

• canvas: A reference to the HTML5 Canvas element of the Test Arena.

  • This is the same as document.getElementById("GameCanvas");

• context: A 2D drawing context of the HTML5 Canvas.

  • This is the same as document.getElementById("GameCanvas").getContext('2d');

• scale: A numeric variable indicating the relative width of the canvas element on the page

  • The default canvas size is set to 1050 x 650 px by TEST_ARENA.resizeCanvas()

  • This scale property is set to the current canvas width divided by 1050 and should be used when calculating the scaled sizes of your sprites and animations.

  • If using any of the drawable objects in drawable.js, you likely do not need to worry about scaling as they will be automatically scaled in the draw methods of these objects.

• state: One of the Test Arena Page States.

Test Arena Page States

The Test Arena never reloads the page; instead, based on the results of various AJAX requests, and user interaction with the GUI, the testArena.js file handles the transitions between the following states.

• pageLoaded: When the page is first loaded, as well as after any HTTP or client javascript errors and exceptions are thrown.

  • The "Play a Game" or "Share a Bot" forms are available to the user.

• uploaded: After the user has successfully uploaded bot(s).

  • The "Start Game" button is displayed.

  • NOTE: This state is also triggered if the user clicks "Kill Game" on an already running game. Based on experience from the tournament it may be beneficial to replace the button text with "Restart Game" or do something else to clearly indicate to the user that they are playing again with the same configuration, even if they make changes to the upload bots form in the meantime.

• loadingGame: After the user has clicked "Start Game".

  • The upload form and "Start Game" button are hidden and the "Kill Game" button is displayed.

  • On the server side the GameManager and bots are started.

  • Client side, the Test Arena begins making periodic AJAX requests to the server for the latest JSON Game States generated by your Game java class. These AJAX requests will continue until the game has ended.

• gameStarted: After the initialGameState has been received from your Game java class and before your Game javascript file has processed it.

  • No UI transitions occur. The Test Arena keeps listening for more game states.

• gameFinished: After the finalGameState has been completely processed by your Game javascript file.

  • NOTE: This appears to be functionally equivalent to just transitioning back to the uploaded state. Future developers should consider removing this state as its no longer seems to serve a unique purpose.