DS Maps

A ds_map is a data structure that stores data in linked pairs consisting of a key and a corresponding value.

The ds_map data structure is an exceptionally useful one as it lets you store key and value pairs. For example, a character in your game can have a quantity of different items (keys) and for each individual item he can have a number of them (values), like in an RPG where you can have 10 health potions, 5 mana potions and 100 gold. Maps maintain such pairs all together in the one place and you can add pairs to the map and search for the value corresponding to certain keys as well using some simple functions. There are a couple of things you should know about maps before you use them, however! Maps are not sorted in any (recognisable) way, meaning that to find a certain key you may have to iterate through the whole thing (which is very slow). There is also no way to hold two keys that are the same, nor can you assign one key two values.

NOTE: The ds_map functions have changed since previous versions of GameMaker so imported games may not work or behave as you expect.

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 maps.

There are two further functions available for saving and loading a ds_map. These functions will encrypt the map and store it in a secure location on the target platform, so you can use this to save In App Purchase details, passwords, sensitive game information, etc...

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

GML Code Example

map_index[? key]

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

JSON And Ds_maps

One of the uses that ds_maps have is when working with JSON, and so there are a few special functions that are specific to that:

There are also a couple of complimentary functions for ds_lists:

NOTE: While these functions permit you to add lists and maps within a map, they are useless for anything other than JSON, and nested maps and lists will not be read correctly if written to disk or accessed in any other way.

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

These examples are submitted by the community. Upvote the examples you think are most helpful.

Very simple ds_map loop by /u/gmlscripts on December 11, 2016

GML Code

// Very simple ds_map loop

var my_map = ds_map_create();
my_map[? "hello"] = "world";
my_map[? "goodbye"] = "cruel world";
my_map[? "you say"] = "goodbye";
my_map[? "i say"] = "hello";

for (var key = ds_map_find_first(my_map); key != undefined; key = ds_map_find_next(my_map, key)) {
    show_debug_message(key + " => " + my_map[? key]);

Edited On December 11, 2016

Looping a DS Map by /u/net8floz on December 08, 2016

GML Code

//While not always the fastest sometimes you may need to loop through a DS Map
//and I've found two common ways
//Approach 1:
var my_map = ds_map_create();
my_map[? "foo"] = "bar";
my_map[? "something"] = "else";
var map_size = ds_map_size(my_map);

var current_key = ds_map_find_first(my_map);

for(var i=0;i<map_size;i++){
    var map_item = my_map[? current_key];
    current_key = ds_map_find_next(my_map,current_key);

//Approach 2: This way I think might be faster
var my_map = ds_map_create();
var my_map_keys = ds_list_create();

my_map[? "foo"] = "bar";

my_map[? "other"] = "something_else";

var list_size = ds_list_size(my_map_keys);

for(var i=0;i<list_size;i++){
    var map_item = my_map[? my_map_keys[i]];

Edited On December 08, 2016

No Edits Suggested

Is this page unclear or not descriptive enough? Suggest an edit to the page and with enough upvotes your changes will be made.

No Questions Have Been Ask

Do you have a question about this page? Ask it Here