DS Grids

A ds_grid is basically a type of two-dimensional array. You define the grid by setting its integer width and height, which then sets the total number of "cells" within the grid (the width and height multiplied) and these cells are then used to hold different data values (real numbers or strings).

This type of structure allows you to set and retrieve the value of cells in the grid by giving the x and y index of it (which starts with 0 for both the x and the y axis and goes up to the width - 1 and the height -1). But you can also set the value in specific grid regions, add single values, and retrieve the sum, maximum, minimum, and mean value over a given region, making this data structure the most versatile of all those available to you.

When accessing DS grid data structures, you should always try to use integer values for the cell position, and all non-integer indices will be floored by GameMaker Studio 2 if you do not. If that is not what you require, then you will need to do the rounding yourself previously before passing the index that you wish to check.

NOTE: As with all dynamic resources, data structures take up memory and so should always be destroyed when no longer needed to prevent memory leaks which will slow down and eventually crash your game.

> The following functions exist that deal with DS grids.

  1. ds_grid_create
  2. ds_grid_destroy
  3. ds_grid_width
  4. ds_grid_height
  5. ds_grid_resize
  6. ds_grid_clear
  7. ds_grid_set
  8. ds_grid_set_disk
  9. ds_grid_set_grid_region
  10. ds_grid_set_region
  11. ds_grid_shuffle
  12. ds_grid_sort
  13. ds_grid_get
  14. ds_grid_get_max
  15. ds_grid_get_mean
  16. ds_grid_get_min
  17. ds_grid_get_sum
  18. ds_grid_get_disk_max
  19. ds_grid_get_disk_mean
  20. ds_grid_get_disk_min
  21. ds_grid_get_disk_sum
  22. ds_grid_add
  23. ds_grid_add_region
  24. ds_grid_add_disk
  25. ds_grid_add_grid_region
  26. ds_grid_multiply
  27. ds_grid_multiply_disk
  28. ds_grid_multiply_region
  29. ds_grid_multiply_grid_region
  30. ds_grid_value_exists
  31. ds_grid_value_disk_exists
  32. ds_grid_value_x
  33. ds_grid_value_y
  34. ds_grid_value_disk_x
  35. ds_grid_value_disk_y
  36. ds_grid_copy
  37. ds_grid_read
  38. ds_grid_write

Apart from these specific functions you can all use an expression (called an accessor) to add or modify the contents of your ds_grid. This accessor looks similar to a 2D array with the following syntax:

grid_index[# xpos, ypos]

You can find more information, plus examples, from from the GML Overview page on Accessors.

NOTE: if you need to check if a data structure exists, you can use the ds_exists() function.


© Copyright YoYo Games Ltd. 2017 All Rights Reserved
.