From 5f3156e2b8233d2b3ac4fb7cf0291a865ce0ecc4 Mon Sep 17 00:00:00 2001 From: Michael Hadley Date: Wed, 29 Nov 2017 14:02:45 -0600 Subject: [PATCH] Jsdocs: Tilemap parsing --- v3/src/gameobjects/tilemap/parsers/Parse.js | 24 ++++++++++++------- .../tilemap/parsers/Parse2DArray.js | 18 ++++++++++++-- .../gameobjects/tilemap/parsers/ParseCSV.js | 18 ++++++++++++-- .../tilemap/parsers/parsetiledjson/index.js | 16 +++++++++++-- 4 files changed, 61 insertions(+), 15 deletions(-) diff --git a/v3/src/gameobjects/tilemap/parsers/Parse.js b/v3/src/gameobjects/tilemap/parsers/Parse.js index 42c85f414..8b5fa2317 100644 --- a/v3/src/gameobjects/tilemap/parsers/Parse.js +++ b/v3/src/gameobjects/tilemap/parsers/Parse.js @@ -5,18 +5,24 @@ var ParseTiledJSON = require('./parsetiledjson/'); var Formats = require('../Formats'); /** - * Parses raw data of a given Tilemap format into a new MapData object. + * Parses raw data of a given Tilemap format into a new MapData object. If no recognized data format + * is found, returns `null`. When loading from CSV or a 2D array, you should specify the tileWidth & + * tileHeight. When parsing from a map from Tiled, the tileWidth & tileHeight will be pulled from + * the map data. * * @param {string} name - The name of the tilemap, used to set the name on the MapData. * @param {number} mapFormat - See ../Formats.js. - * @param {array|string|object} data - 2D array, CSV string or Tiled JSON object - * @param {number} tileWidth - Required for 2D array and CSV, but ignored for Tiled JSON. - * @param {number} tileHeight - Required for 2D array and CSV, but ignored for Tiled JSON. - * @param {boolean} [insertNull=false] - If true, instead of placing empty tiles at locations where - * the tile index is -1, this will place null. If you've a large sparsely populated map and the tile - * data doesn't need to change then setting this value to `true` will help with memory consumption. - * However if your map is small, or you need to update the tiles (perhaps the map dynamically - * changes during the game) then leave the default value set. + * @param {array|string|object} data - 2D array, CSV string or Tiled JSON object. + * @param {number} tileWidth - The width of a tile in pixels. Required for 2D array and CSV, but + * ignored for Tiled JSON. + * @param {number} tileHeight - The height of a tile in pixels. Required for 2D array and CSV, but + * ignored for Tiled JSON. + * @param {boolean} insertNull - Controls how empty tiles, tiles with an index of -1, in the map + * data are handled. If `true`, empty locations will get a value of `null`. If `false`, empty + * location will get a Tile object with an index of -1. If you've a large sparsely populated map and + * the tile data doesn't need to change then setting this value to `true` will help with memory + * consumption. However if your map is small or you need to update the tiles dynamically, then leave + * the default value set. */ var Parse = function (name, mapFormat, data, tileWidth, tileHeight, insertNull) { diff --git a/v3/src/gameobjects/tilemap/parsers/Parse2DArray.js b/v3/src/gameobjects/tilemap/parsers/Parse2DArray.js index d8fc6cb8f..4b6e53a05 100644 --- a/v3/src/gameobjects/tilemap/parsers/Parse2DArray.js +++ b/v3/src/gameobjects/tilemap/parsers/Parse2DArray.js @@ -3,7 +3,21 @@ var LayerData = require('../mapdata/LayerData'); var Formats = require('../Formats'); var Tile = require('../Tile'); -var Parse2DArray = function (key, data, tileWidth, tileHeight, insertNull) +/** + * Parses a 2D array of tile indexes into a new MapData object with a single layer. + * + * @param {string} name - The name of the tilemap, used to set the name on the MapData. + * @param {array} data - 2D array, CSV string or Tiled JSON object. + * @param {number} tileWidth - The width of a tile in pixels. + * @param {number} tileHeight - The height of a tile in pixels. + * @param {boolean} insertNull - Controls how empty tiles, tiles with an index of -1, in the map + * data are handled. If `true`, empty locations will get a value of `null`. If `false`, empty + * location will get a Tile object with an index of -1. If you've a large sparsely populated map and + * the tile data doesn't need to change then setting this value to `true` will help with memory + * consumption. However if your map is small or you need to update the tiles dynamically, then leave + * the default value set. + */ +var Parse2DArray = function (name, data, tileWidth, tileHeight, insertNull) { var layerData = new LayerData({ tileWidth: tileWidth, @@ -11,7 +25,7 @@ var Parse2DArray = function (key, data, tileWidth, tileHeight, insertNull) }); var mapData = new MapData({ - name: key, + name: name, tileWidth: tileWidth, tileHeight: tileHeight, format: Formats.TILEMAP_2D_ARRAY, diff --git a/v3/src/gameobjects/tilemap/parsers/ParseCSV.js b/v3/src/gameobjects/tilemap/parsers/ParseCSV.js index 4b2320535..6c143250c 100644 --- a/v3/src/gameobjects/tilemap/parsers/ParseCSV.js +++ b/v3/src/gameobjects/tilemap/parsers/ParseCSV.js @@ -1,14 +1,28 @@ var Formats = require('../Formats'); var Parse2DArray = require('./Parse2DArray'); -var ParseCSV = function (key, data, tileWidth, tileHeight, insertNull) +/** + * Parses a CSV string of tile indexes into a new MapData object with a single layer. + * + * @param {string} name - The name of the tilemap, used to set the name on the MapData. + * @param {string} data - CSV string of tile indexes. + * @param {number} tileWidth - The width of a tile in pixels. + * @param {number} tileHeight - The height of a tile in pixels. + * @param {boolean} insertNull - Controls how empty tiles, tiles with an index of -1, in the map + * data are handled. If `true`, empty locations will get a value of `null`. If `false`, empty + * location will get a Tile object with an index of -1. If you've a large sparsely populated map and + * the tile data doesn't need to change then setting this value to `true` will help with memory + * consumption. However if your map is small or you need to update the tiles dynamically, then leave + * the default value set. + */ +var ParseCSV = function (name, data, tileWidth, tileHeight, insertNull) { var array2D = data .trim() .split('\n') .map(function (row) { return row.split(','); }); - var map = Parse2DArray(key, array2D, tileWidth, tileHeight, insertNull); + var map = Parse2DArray(name, array2D, tileWidth, tileHeight, insertNull); map.format = Formats.TILEMAP_CSV; return map; diff --git a/v3/src/gameobjects/tilemap/parsers/parsetiledjson/index.js b/v3/src/gameobjects/tilemap/parsers/parsetiledjson/index.js index c94031e11..54c630a97 100644 --- a/v3/src/gameobjects/tilemap/parsers/parsetiledjson/index.js +++ b/v3/src/gameobjects/tilemap/parsers/parsetiledjson/index.js @@ -10,7 +10,19 @@ var ParseGID = require('./ParseGID'); var Base64Decode = require('./Base64Decode'); var ParseObject = require('./ParseObject'); -var ParseJSONTiled = function (key, json, insertNull) +/** + * Parses a Tiled JSON object into a new MapData object. + * + * @param {string} name - The name of the tilemap, used to set the name on the MapData. + * @param {object} json - The Tiled JSON object. + * @param {boolean} insertNull - Controls how empty tiles, tiles with an index of -1, in the map + * data are handled. If `true`, empty locations will get a value of `null`. If `false`, empty + * location will get a Tile object with an index of -1. If you've a large sparsely populated map and + * the tile data doesn't need to change then setting this value to `true` will help with memory + * consumption. However if your map is small or you need to update the tiles dynamically, then leave + * the default value set. + */ +var ParseJSONTiled = function (name, json, insertNull) { if (json.orientation !== 'orthogonal') { @@ -22,7 +34,7 @@ var ParseJSONTiled = function (key, json, insertNull) var mapData = new MapData({ width: json.width, height: json.height, - name: key, + name: name, tileWidth: json.tilewidth, tileHeight: json.tileheight, orientation: json.orientation,