Tutorial

Tutorial 1: Setting up a grid object

First ensure that all module JS files are included in your index.html for the engine.


	<!-- Grid API Files -->
        <script type="text/javascript" src="src/MyGame/GridObjects/Grid.js"></script>
        <script type="text/javascript" src="src/MyGame/GridObjects/Grid_Range.js"></script>
        <script type="text/javascript" src="src/MyGame/GridObjects/Grid_Objects.js"></script>
        <script type="text/javascript" src="src/MyGame/GridObjects/Tile.js"></script>

        <!-- Client game code -->
        <script type="text/javascript" src="src/MyGame/DemoOne.js"></script>

Then, in your scene file, initialize a Grid object where you would like it to be initialized. In our example, we have it being initialized in our scene's initialize function. In the example below, we are defining a Grid of size 20 x 14 tiles, with the center of the grid at WC 50 x 40, and each tile having dimensions 5 x 5 WC.

Demo.prototype.initialize = function() {

    this.mGrid = new Grid(20, 14, 50, 40, 5, 5); 

}

Also, you want to have your Grid object being drawn within the scene's draw() function, so that tiles containing textures can be properly drawn as necessary.

DemoOne.prototype.draw = function () {

    gEngine.Core.clearCanvas([0.9, 0.9, 0.9, 1.0]); 
    this.mCamera.setupViewProjection();
    
    this.mGrid.draw(this.mCamera);

};

Now that we have our Grid object defined, its ready to be interacted with. See tutorial 2 to understand some of the different possible interactions.

Tutorial 2: Using your grid object

Tile Properties: All tile editing is done through accessing tiles through the Grid object. In the example below, we are grabbing tile (1, 1) in our created grid. We can grab tiles by fetching the Grid Index corresponding to a given WC position. Then, we can get and set the properties of that tile. Properties include: collision, moves, walls, WC position, visibility, and texture.

DemoOne.prototype.tilePropertyDemo = function() {
  // Getting the tile at index (1, 1)
  var tile1 = this.mGrid.getTileAtIndex(1, 1);

  // Getting the INDEX of the tile at WC position (20, 25)
  var tile2Index = this.mGrid.getTileAtWC(20, 25);

  // Calling various getter functions on retrieved tile.
  tile1.getCollision();
  tile1.getMoves();
  tile1.getWalls();
  tile1.getXposWC();
  tile1.isVisible();

  // Calling various setter functions on retrieved tile.
  tile1.setCollision(true);
  tile1.addWall(Grid.eDirection.eNorth); // Adding a wall to the north side of this tile.
  tile1.setTexture("assets/sometexture.png");
  tile1.setVisible(true); // Need to set tile as visible after assigning a texture.
};

Adding Objects: Objects that have an associated Xform can be added directly to the grid, so that movement and collisions with that object are now managed by the Grid itself. Once an object is added, a numerical ID is returned that can be used in object manipulation functions to access the desired object.

DemoOne.prototype.gridObjectAddDemo = function() {
  var obj = new Renderable(); // Object to add must have an Xform associated with it!

  var id = this.mGrid.addObjectToGrid(obj); // Will add the object to the tile it lies in already if it is within the grid
  // If the object initially lies outside the grid, it will be placed in the first non-collide tile.

  // id contains the corresponding numerical ID for this object.
};

Object Interactions: Once an object is added to the grid, it can be moved through a teleporting-like manner with the changeObjectPosition function, which will move the object to the given tile position as long as that tile position is not collidable. Objects can also be moved using the moveObjectPositionDir function, which will move the object a single space in the desired direction if the tile to move to is not collidable and there isn't a wall blocking it. The objects can also be removed from the grid, but this doesn't remove the object from the world, just from grid control!

DemoOne.prototype.gridObjectManipulateDemo = function() {
  // Assuming id is the number returned by the add in the previous example.

  // This will move the object in the grid corresponding to the id to tile (5, 5)
  this.mGrid.changeObjectPosition(id, 5, 5); 

  // This will move the object corresponding to the given id one space to the north, given there are no obstacles.
  this.mGrid.moveObjectPositionDir(id, Grid.eDirection.eNorth);

  // Removes object corresponding to id from the grid. Note, this does not remove the object from the world!
  this.mGrid.removeObjectFromGrid(id);

};

Range Functions: Many of the edit tile functions can be performed on ranges of tiles to save some time modifying many tiles at once.

DemoOne.prototype.gridRangeManipulateDemo = function() {
  // This will change the tiles between top-left tile (3, 3) and bottom-right tile (6, 1) to the given texture.
  this.mGrid.editRangeTexture(3, 3, 6, 1, "assets/sometexture.png");

  // This will change the tiles between top-left tile (3, 3) and bottom-right tile (6, 1) to be visible.
  this.mGrid.editRangeVisible(3, 3, 6, 1, true);

};