As of late 2021, we are in the process of updating Stencylpedia and fixing up outdated & broken content. Thanks for your patience!

36,135

Views

Beginner

Level

7

Comments

Maps

by captaincomic (Updated on 2016-04-20)


Contents

  • What are Maps?
  • Creating Maps
  • Operations
  • Maps as Game Attributes

What are Maps?

Maps (also known as dictionaries) let you store and access data using names as keys. Unlike lists, which are ordered and use numbers as keys, maps don't care about order and let you use textual names as keys.

For example, if you wanted to make a Map that associated Stencyl members with post counts, it'd look like this.

Maps can also mix and match different types as values.

Or, you could get fancier and use Maps as the data itself.

Maps vs. Lists

Maps are useful when you want to...

  • Store many things but don't care about the order.
  • Want to access things instantly.
  • Prefer to refer to things by name.

Lists are better if you want to...

  • Store things in a particular order.
  • Sort or search for specific items in the list.

Creating Maps

How do you create a Map in the first place? Maps can be attributes, so like any attribute, there are two ways of doing this.

  1. Configuring the attribute with initial data.
  2. Creating the map at runtime inside a behavior and setting the attribute's value to that newly created map.

Assume that for both cases, we have created a Map Attribute called "myMap"

Method 1: Configuring a Map attribute

After attaching a behavior with a Map attribute to either an Actor or a Scene, you'll see this interface for adding initial data to the Map.

Method 2: Creating a Map using blocks

Alternatively, you can create a new Map using blocks and begin filling it up.

Operations

All blocks related to maps are located under Attributes > Maps.

Operations

  • Set [KEY] to [VALUE] for [MAP]
  • Remove [KEY] from [MAP]
  • Remove all items from [MAP]

Getters

  • Value of [KEY] from [MAP]
  • [MAP] has [KEY]?
  • [MAP] has [VALUE]?
  • Number of items in [MAP]
  • [MAP] is empty?
  • Keys of [MAP] as list

Create/Copy

  • Create new map
  • Copy of [MAP]

Looping

  • For each [KEY] in [MAP]

Maps as Game Attributes

Maps can be used as Game Attributes. This can be useful for defining tables and other large collections of data to use throughout the game.

Creating a Map as a Game Attribute

Maps can be created as Game Attributes and pre-populated the same way as other Maps, namely only with Numbers and Text.

Note: You may also dump Lists & Maps into Maps at runtime as well as any other kind of data. If you plan to save your Maps out (via Game Attributes), there are restrictions. Skip down to "Saving & Maps" under Caveats.

Setting the Value of a Game Attribute to a Map

As you may expect, you can set the value of a Game Attribute to a Map.

Note: Assigning values simply gets the Game Attribute to "point" to your Map. No copying is done, so modifying it modifies the one and only "copy" of that Map.

Gotcha: Saving & Maps

Be careful when saving out Maps as Game Attributes. Just like Lists, they can only contain contain Numbers, Text, and nested Lists or Maps.

Print Article Edit Article How to Edit an Article
Disclaimer: Use comments to provide feedback and point out issues with the article (typo, wrong info, etc.). If you're seeking help for your game, please ask a question on the forums. Thanks!

7 Comments

kingdarkeyes
This page does not match the most recent version at https://github.com/Stencyl/stencylp edia/blob/master/chapter-5/maps.md. The last two example images showing how maps are laid out should be switched
0 4 years, 5 months ago
WitlessWonderer
I think you're two final example maps are mixed up. You have the map that contains maps and then you have the map that has different types. I think you might want it the other way around.
2 8 years, 9 months ago
Tebbo
This is exactly what I needed!
Now we can create hierarchies without funky naming conventions. This will simplify so much.

1 9 years, 11 months ago
PhaserRave
Brilliant! Great work.
1 9 years, 11 months ago
MrMyaghi
I have had no problem saving an instance of an image in a slot in a game list (my save file), so far. Will I run into trouble later?
1 9 years, 11 months ago
kitanga
Is it possible to have a list inside a map.
3 9 years, 11 months ago
sandsoftimer
Excellent....... I think through map we could not only store data but also sort them
0 9 years, 11 months ago

Sign In to Comment