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.
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);
.
<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>
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 |
- Sprite rotation and scaling
- OOB socket.io implementation for network play
The bat signal, or ben@benergize.com.