Game Boulder

Welcome to Game Boulder! This is a very easy to use WIP JS game engine. This project is inspired by GameMaker and GameMaker. There's no documentation right now, but when Game Boulder is further along, I'll write one and put out some videos. A very simple demo of the engine can be found here.

How to use

Download GameBoulder.min.js and import it with a script tag (<script src = '/path/to/GameBoulder.min.js'></script>).

Create an instance of the engine with var game = new GameEngine("#canvas",24);.

Boilerplate

<canvas id = 'canvas'></canvas>
<script src 'GameBoulder.min.js'></script>

<script>
//Create a new instance of the engine using the canvas above, running at 24 fps
var game = new GameEngine("#canvas",24);
</script>

Reference

This is an incomplete reference, but what's here is accurate and should be enough to get started.

Type	Property	Description
EngineResource	GameEngine(String canvasSelector || Object HTMLCanvasElement, fps=24)	ID selector for canvas, game FPS
array	GameEngine.rooms	Array of all rooms in the game, accessible to the engine.
array	GameEngine.sprites	Array of all registered sprites.
array	GameEngine.resources	Array of all registered files
array	GameEngine.objects	Array of all registered objects.
array	GameEngine.sounds	Array of all registered sounds (EngineResources, not files)
array	GameEngine.tiles	Array of all registered tiles
array	GameEngine.backgrounds	Array of all registered backgrounds
function	GameEngine.generateID	Generates a new unique ID
function	GameEngine.checkKey(String KeyEvent.type)	Function to check if key is currently being held
function	GameEngine.checkMouse(Number mouseButton)	Function to check if mouse button is currently being held
function	GameEngine.getEngineResources(Number any=-1 || String name || Number ID)	Returns EngineResources across all categories. If a name or ID is specified, only resources matching that name or ID will be returned.
function	GameEngine.getSprite(Number ID=-1 || String name || EngineResource Sprite)	Returns a registered Sprite resource from a name, ID, or object. Note that Instances created using Instance() will not be retrieved.
function	GameEngine.getObject(Number ID=-1 || String name || EngineResource GameObject)	Returns a registered Object resource from a name, ID, or object. Note that Instances created using Instance() will not be retrieved.
function	GameEngine.addRoom(EngineResource Room)	Function to add rooms to game registry. This is done automatically when a room is created.
function	GameEngine.getRoom(Number ID || String roomName)	Get a room object from either an ID or name
function	GameEngine.getCurrentRoom()	Gets the currently active game room
function	GameEngine.setCurrentRoom(Number ID || String roomName)	Switches game to a room
function	GameEngine.importTiles(JSON tileData)	Import tileset from JSON. Useful for designing rooms in-game
function	GameEngine.begin()	Start the game loop
function	GameEngine.getIntersecting(x1,y1,x2,y2)	Get if two rectangles are intersecting based on their coordinates
function	GameEngine.mDistance(Number x1, Number y1, Number x2, Number y2)	Returns Manhattan distance given two sets of coordinates.
function	GameEngine.distance(Number x1, Number y1, Number x2, Number y2, Boolean precise=true)	Returns Pythagorean distance given two sets of coordinates, or, if precise is false, return Manhattan distance.
function	GameEngine.getPointDirection(Number direction, Number distance)	Returns an array of the X and Y coordinates given a direction and distance (ie, direction 270 and distance 1 yields Array [0,1]).
function	GameEngine.getPointDir(Number direction, Number distance)	Alias of GameEngine.getPointDirection
function	GameEngine.getDirectionFromPoints(Number x1, Number y1, Number x2, Number y2)	Returns the angle in degrees from coordinate x1,y1 to coordinate x2,y2.
function	GameEngine.choose(Array toChooseFrom)	Chooses a random element from an array.
function	GameEngine.random(Number min=0, Number max=1)	Returns a random number between min and max.
function	GameEngine.irandom(Number min=0, Number max=1)	Returns a random integer between min and max.
function	GameEngine.degToRad(Number degrees)	Converts the provided degrees into radians.
function	GameEngine.radToDeg(Number radians)	Converts the provided radians into degrees.
object	GameEngine.draw	Collection of drawing functions to draw somewhere in a room, based on the view position, not the canvas position.
function	GameEngine.draw.rect(Number x, Number y, Boolean fill=false, Number color=-1 || String color="")	Draws a filled or unfilled rectangle at a given point in the room. Not supplying a color will draw it at whatever the current canvas context fill or stroke color is.
function	GameEngine.draw.text(String text, Number x, Number y, Boolean fill=false, Number color=-1 || String color="")	Draws a filled or unfilled text at a given point in the room. Not supplying a color will draw it at whatever the current canvas context fill or stroke color is.
function	GameEngine.draw.arc(Number x, Number y, Number startAngle, Number endAngle, Boolean counterClockWise=false, Number color=-1 || String color="")	Draws an arc at a given point in the room. Note that angles are in degrees, not radians. Not supplying a color will draw it at whatever the current canvas context fill or stroke color is.
function	GameEngine.draw.ellipse(Number x, Number y, Number radiusX, Number radiusY, Number rotation, Number startAngle, Number endAngle, Boolean counterClockWise=false, Number color=-1 || String color="")	Draws an ellipse at a given point in the room. Note that angles are in degrees, not radians. Not supplying a color will draw it at whatever the current canvas context fill or stroke color is.
function	GameEngine.draw.image(HTMLImageElement image, Number dx, Number dy) || (HTMLImageElement image, Number dx, Number dy, Number dWidth, Number dHeight) || (HTMLImageElement image, Number sx, Number sy, Number sWidth, Number sHeight, Number dx, Number dy, Number dWidth, Number dHeight)	Draws an image at a given point in the room. See the MDN for a more detailed reference on the arguments.
function	GameEngine.draw.line(Array coordinates[Array [Number x, Number y],...], Number width=1, Number color=1 || String color="")	Draws a line or lines between all coordinates provided in the coordinates argument. Not supplying a color will draw it at whatever the current canvas context fill or stroke color is.
number	GameEngine.currentRoom	Array index of current active game room.
number	GameEngine.fps	Framerate at which the game will run
object	GameEngine.debug	Debug flags
object	GameEngine.engine	Object containing utilities and canvas data
object	GameEngine.engine.ctx	Reference to 2D context. Can be used to draw to the canvas natively.
object	GameEngine.engine.importResource(String fileName, forceNewResource=false)	Adds a file resource to the game's resource registry. This is mainly called internally.
string	GameEngine.status	Current gamestate
EngineResource	GameObject(String name, Number x=0, Number y=0, EngineResource Sprite=-1, Function onstep=-1, Function ondraw=-1, Boolean visible=true, Boolean active=true, Array collisionBox=false || Boolean collisionBox=false, Number depth=0)	Building block of game interactivity.
array	GameObject.collisionBox	Coordinates to use when checking for collisions. Defaults to sprite width/height or 16x16 if no sprite is specified. collisionBox entries are [x,y,width,height].
boolean	GameObject.visible	Whether the object should draw a sprite and perform its draw event
function	GameObject.onstep()	Custom event to execute every game step (frame)
function	GameObject.getCoordinates(Boolean object=true)	Returns an object with the values of this objects x1, x2, y1, and y2, based on its location and collision box.
function	GameObject.getCoords(Boolean object=true)	Alias of GameObject.getCoordinates.
function	GameObject.getCollisions(solidOnly=false, offsetX = 0, offsetY = 0)	Returns an array of all objects this object is currently overlapping with. Solid only specifies whether to check for collisions with all objects, or just ones marked solid. offsetX and offsetY indicate offsets from the current location of the collisionBox.
function	GameObject.wrap(wrapX=true,wrapY=true)	Checks to see if an object is outside of the room, and if it is, will move the object to the other side. Specifying wrapX and wrapY will determine which axes the object should wrap on.
function	GameObject.ondraw()	Custom event to execute every game draw (frame)
function	GameObject.ondestroy()	Custom event to execute when the GameObject is destroyed via destroy()
function	GameObject.onkeypress(KeyboardEvent ev)	Custom event to handle key presses. This recieves input events from native JavaScript event listeners. The first argument provides the data from the event.
function	GameObject.onkeyup(KeyboardEvent ev)	Custom event to handle key releases. This recieves input events from native JavaScript event listeners. The first argument provides the data from the event.
function	GameObject.onkeydown(KeyboardEvent ev)	Custom event to handle key downs. This recieves input events from native JavaScript event listeners. The first argument provides the data from the event.
function	GameObject.onmousedown(KeyboardEvent ev, Boolean local)	Custom event to handle mouse presses. This recieves input events from native JavaScript event listeners. The first argument provides the data from the event. The local argument indicates whether the mouse event occured over the objects collision box.
function	GameObject.onmouseup(KeyboardEvent ev, Boolean local)	Custom event to handle mouse releases. This recieves input events from native JavaScript event listeners. The first argument provides the data from the event. The local argument indicates whether the mouse event occured over the objects collision box.
function	GameObject.onmousemove(KeyboardEvent ev, Boolean local)	Custom event to handle mouse movement. This recieves input events from native JavaScript event listeners. The first argument provides the data from the event. The local argument indicates whether the mouse event occured over the objects collision box.
function	GameObject.oncontextmenu(KeyboardEvent ev, Boolean local)	Custom event to handle right clicks. This recieves input events from native JavaScript event listeners. The first argument provides the data from the event. The local argument indicates whether the mouse event occured over the objects collision box.
function	GameObject.generatePath(Number x, Number y, Number gridWidth, number gridHeight)	Generate a path to a given location on a certain grid, avoiding solid objects. Note that this is an extremely performance-heavy function and should only be called when needed. Using a larger gridWidth/gridHeight decreases the performance cost, but lowers the path resolution..
function	GameObject.pathStep(Number speed=0)	Take a step to/towards the next step in the path generated by generatePath(). A speed of 0 will make the object jump to its next coordinate. A non-zero speed will make the object execute moveTowardsPoint() towards its next path coordinate.
function	GameObject.moveTowardsPoint(Number x, Number y, Number speed)	Move towards given coordinates, ignoring objects in the way
function	GameObject.moveInDirection(Number direction, Number speed)	Move at a given speed in a given direction (degrees)
function	GameObject.moveContactSolid(Number direction, Number maxDistance=-1)	Move this GameObject in a given direction until it has come in contact with a solid object. If it does not reach a solid object in less than the maxDistance, it will not move. A maxDistance of -1 will move the object until it finds a solidObject, or until it is outside of the room. Returns false if no solid is contacted.
function	GameObject.snapToGrid(Number gridWidth=room.gridWidth, Number gridHeight=room.gridHeight)	Snaps the GameObject's x and y coordinates to a specified grid.
function	GameObject.getOutsideRoom()	Returns true if the outside of the current room's bounds.
function	GameObject.getOutsideView()	Returns true if the outside of the current view's bounds.
function	GameObject.setSprite(String spriteName || Number ID || EngineResource Sprite, Number frameX=-1, Number frameY=-1, Number speed=-1, Number scaleX=-1, Number scaleY=-1)	Changes the GameObject's sprite IF the sprite is different from the object's current sprite. Specifying -1 for any of the optional arguments will leave the value unchanged for the current sprite.
function	GameObject.setDepth(Number z=0)	Set the position in the draw order (z-index)
function	GameObject.destroy()	Remove this object from the current room
function	GameObject.deactivate()	Prevent this object from performing any of its actions or drawing without removing it from the room.
function	GameObject.activate()	Reactivate the object
number	GameObject.x	X coordinate of object in room
number	GameObject.y	Y coordinate of object in room
number	GameObject.xstart	The X starting coordinate of an object, set when the object is created.
number	GameObject.ystart	The Y starting coordinate of an object, set when the object is created.
number	GameObject.xprevious	The X position this object occupied prior to its current position.
number	GameObject.yprevious	The Y position this object occupied prior to its current position.
number	GameObject.sprite	EngineResource Sprite to draw at the GameObject's position in the room
number	GameObject.hspeed	Horizontal speed
number	GameObject.vspeed	Vertical speed
number	GameObject.friction	Friction to apply to object's movements
number	GameObject.gravity	Gravity to apply to object
number	GameObject.gravityDirection	Direction of gravity to apply
number	GameObject.fallSpeed	The current speed at which an object is falling in the direction of its specified gravity.
number	GameObject.terminalVelocity	The maximum fallSpeed an object can achieve.
number	GameObject.id	Internal unique ID
object	GameObject.path	Path generated by generatePath()
object	GameObject.tags	Object containing tag data related to the object. Tag data can be used to apply identifying properties to an object.
function	GameObject.tags.list()	Returns all tags for the current GameObject.
function	GameObject.tags.has(String tagName)	Checks to see if the GameObject has a specific tag. Returns true if the tag is found, and false if it is not.
function	GameObject.tags.get(String tagName)	Gets the index of the tag in the GameObjects tag array.
function	GameObject.tags.add(String tagName)	Adds a tag to the GameObject. Returns false if the tag is already present.
function	GameObject.tags.push(String tagName)	Alias of GameObject.tags.add
function	GameObject.tags.remove(String tagName)	Removes a tag from the GameObject. Returns the new list of tags.
string	GameObject.name	String used to identify the object in a room
EngineResource	Instance(String EngineResource.name || Number EngineResource.id || Object EngineResource || Object object	Creates a deep copy of an EngineResource. Note that no references are passed to the new object with the exception of HTML resources. For performance reasons, it is recommended that you use the Instance resource sparingly, and instead create instances using constructor functions.
EngineResource	Room(String roomName, Number width = 1280, Number height = 720, Number gridX=32, Number gridY=32, Array roomObjects = [], Array tiles=[], EngineResource Background) || String color)
array	roomObjects	All objects currently in the room
array	Room.tiles	All tiles currently in the room
function	Room.addObject(EngineResource GameObject, Boolean copy=false, sortDepth=true)	Adds an object to this room. Specifying that it should be a copy will create a shallow copy of the object. It is recommended you create constructor functions for objects that need instances. sortDepth will cause the room to adjust the depth order according to the new object's depth. If the object's depth doesn't matter, setting sortDepth to false will slightly improve performance.
function	Room.getObject(String objectName || Number ID)	Get an object in the room given an ID or object name. If there are multiple objects with the name, it will return the first in the room array.
function	Room.getObjects(String objectName || String[] objectName)	Get an array of instances of an object in the room given an object name, or array of object names.
function	Room.getTilesAt(Number x, Number y, Boolean solidOnly = false, Number width = 1, Number height = 1)	Get all tiles at a given location
function	Room.getObjectsAt(Number x, Number y, Boolean solidOnly = false, Number width = 1, Number height = 1, Array ignoreObjects[String objectName || Number ID]=[])	Get all objects at a given location, within a given width. Adding objects to the ignoreObjects argument will exclude them from the search.
function	Room.getAllAt(Number x, Number y, Boolean solidOnly = false, Number width = 1, Number height = 1)	Get all objects and tiles at a given location
function	Room.checkEmpty(Number x, Number y, Boolean solidOnly = false, Number width = 1, Number height = 1)	Check if there is anything at a given location
number	Room.width	Playable room width
number	Room.height	Playable room height
number	Room.gridX	Grid X dimension
number	Room.gridY	Grid Y dimension
number	Room.view.x	X to start drawing from
number	Room.view.y	Y to start drawing from
number	Room.view.width	Width of view to draw to
number	Room.view.height	Height of view to draw to
number	Room.id	Internal unique ID
object	Room.background	EngineResource Background to draw behind room
object	Room.view	Object containing variables related to how the room is displayed on the canvas
string	Room.name	String used to identify the object in a room
string	Room.view.objectName	Object to follow with view
EngineResource	Sprite(String spriteName, Number sheetX = 0, Number sheetY = 0, Number sheetWidth = 16, Number sheetHeight=16, Number drawWidth=16, Number drawHeight=16, Number animationSpeed = 1, Boolean forceNewResource=false)	An image loaded from an image file used to draw tiles, objects, and backgrounds. Sprites can be from sheets, or use entire images. They can be animated, or still.
boolean	Sprite.resource	File resource from image
function	Sprite.draw(Number x, Number y)	Draws the sprite. This is usually called automatically.
function	Sprite.setFrame(Number frameX=0, Number frameY=0)	Jumps the sprite to a given X and Y frame in its animation.
number	Sprite.speed	Animation speed, if applicable
number	Sprite.sheetX	X to start taking sprite from. This is primarily for sprite sheets where the sprite you want to draw may not be at position 0,0. For animations, specify an array of X positions.
number	Sprite.sheetY	Y to start taking sprite from. This is primarily for sprite sheets where the sprite you want to draw may not be at position 0,0. For animations, specify an array of Y positions.
number	Sprite.sheetWidth	Width of sprite on the sheet. This is primarily for sprite sheets where the sprite you want to draw may be smaller than the entire sheet.
number	Sprite.sheetHeight	Height of sprite on the sheet. This is primarily for sprite sheets where the sprite you want to draw may be smaller than the entire sheet.
number	Sprite.drawWidth	Actual width to draw sprite in room. This will scale the sprite.
number	Sprite.drawHeight	Actual height to draw sprite in room. This will scale the sprite.
number	Sprite.scaleX	The X scale at which to draw the sprite. Supplying a negative value will cause the image to flip.
number	Sprite.scaleY	The Y scale at which to draw the sprite. Supplying a negative value will cause the image to flip.
number	Sprite.id	Internal unique ID
string	Sprite.name	String used to identify the sprite
string	Sprite.fileName	Location of file containing image or images
EngineResource	Background(String color, EngineResource Sprite=-1, Boolean tiled=true)	An image or color to be drawn in a room behind all objects and tiles.
string	Background.color	Color to draw to in room, if no sprite is present.
string	Background.colour	Alias of color for our friends across the pond.
number	Background.sprite	EngineResource Sprite to draw in room, either tiled or not.
boolean	Background.tiled	Whether or not to tile the sprite in the room, if it is not larger than the room.
function()	Background.draw	Draw the background. This is usually called automatically.
EngineResource	Tile(String name, EngineResource Sprite=EngineResource Sprite(), Number x=0, Number y=0, Boolean solid=false, Array properties=[])	Decorative element to be drawn in a room. Like an object, these can be pathable, but they cannot have scripts or events attached to them.
array	Tile.properties	Properties to help identify this tile. Useful for water or terrain properties.
boolean	Tile.solid	Whether this tile should affect pathfinding
function	Tile.destroy()	Remove this tile from the current room.
number	Tile.x	X coordinate of tile in room
number	Tile.y	Y coordinate of tile in room
number	Tile.id	Internal unique ID
object	Tile.sprite	EngineResource Sprite to draw at the Tiles position in the room
string	Tile.name	String used to identify the object in a room
EngineResource	Sound(String soundName, String fileName, Number volume=1,Boolean forceNewResource=false)	EngineResource to play audio in game.
boolean	Sound.resource	JS file resource from sound
function	Sound.play(Number volume)	Plays the sound
function	Sound.loop()	Plays the sound, looping on completion
function	Sound.pause()	Pauses the sound, retaining its current playback position
function	Sound.stop()	Stops playing the sound, losing its current playback position
function	Sound.seek(Number time)	Seeks to a point in the sound
function	Sound.setVolume(Number volume)	Set the volume at which to play the sound
function	Sound.mute()	Mutes the sound, remembering previous volume
function	Sound.unmute()	Unmutes the sound, returning its playback to its previous volume
function	Sound.setSpeed(Number speed)	Sets the speed at which to play the sound
number	Sound.id	Internal unique ID
string	Sound.name	String used to identify the Sound
string	Sound.fileName	Location of file containing sound

Upcoming

• Sprite rotation and scaling
• OOB socket.io implementation for network play

How do I get in touch with the guy who made this?

The bat signal, or ben@benergize.com.