moved over from the projectspark.com forums
Let's talk about creating and using an array in Project Spark. I'm going to be using a simplified version of the brain variable array implementation first demonstrated by Myline de Nolia. This is pretty advanced stuff, so don't worry if you don't understand what every tile is doing. Fortunately the Kode required is very short, so you can always use it now and learn how it works later.
What IS an array?
Think of an array as a collection of boxes. In each box, we can store some information. Then later, we can go find that box and retrieve our information. In Project Spark this might be a list of inventory items, a recording of lap times, the names of nearby objects, or anything else. In a lot of ways, an array is similar to an Object Set. If you've worked with Inventory in Project Spark, you know the basic idea of an object set. It's a collection of stuff.
An array is like that, only the "stuff" is information.
Why use an array?
Let's say you have a game with a character that you want to equip a sword from its inventory. The only problem is, there are other items in the inventory too. So you have to search through the inventory to find the sword, and that takes time, even if, for example, you know the sword is the fourth object. Let's compare searching with an object set (like inventory) to search with an array:
An object set of colors: Red, Yellow, Blue, Green, White, Purple, Orange
An array of colors: 1) Red 2) Yellow 3) Blue 4) Green 5) Purple 6) White 7) Orange
What is the sixth color in the object set?
What is the fourth color in the array?
If you're like me, it took a second or two to find Purple, but you found Green almost instantly. To find the sixth item in the set, we count Red - one, Yellow - two, Blue - three, Green - four, White - five, Purple - that's six. To find the fourth color in the array, we quickly scan for the number four and find the color.
In this sense, an array is like an object set where we've written the position numbers on the top of each box. Finding the first box takes the same amount of time as finding the 99th box. Imagine searching your inventory for the item in the 99th position if you had to count one by one from the beginning each time. In some games you might have to do this many times per second. The extra searching time adds up!
What are Brains in Project Spark?
In Project Spark, every object has a brain. Think of the brain as the set of instructions for that object. In some ways it's like the role that object will play in your game. And just as in life, sometimes the same object needs to have multiple roles.
How can we have multiple brains?
This is not a multi-brains tutorial, but you need to know a few things about multi-brains to understand how the array works. Here's a simplified explanation:
My friend Mary is a mother when she is at home. She feeds her kids, reads to them, and helps them pick out clothes to wear. But every morning Mary leaves her house and goes to work. When Mary gets to work, her role is entirely different than it is at home. Mary still has her motherly skills inside of her, but she puts those aside while she is at work. This is an example of how [push brain] works in Project Spark. Mary pushes aside her mom brain and her worker brain takes over. When she is ready to go home, she does a [pop brain] to get rid of her work brain, bringing the previously active motherly brain back into active service.
When Mary gets home, she has a lot of tasks to perform. She cooks dinner, helps the kids with homework, listens to music, and keeps her cat from jumping up on the kitchen counter. Mary has to do all of these tasks at the same time. When her favorite song comes on, Mary can't stop everything and listen until it is over, because dinner might burn. Her music listening brain needs to run at the same time as her cooking brain. This is an example of how [add brain] works in Project Spark. When you add a brain, you create an additional brain that runs at the same time as the other brains. Like Mary, some objects in Project Spark are very busy and can hold up to 100 different brains.
For the array implementation, we will use [add brain] to create new places to store information. Like Mary's skills, those storage locations will all be available at the same time.
Brain Slots? Channels? Huh?
When you add a brain, you can specify a certain channel, a certain slot, or both. The details of what those mean aren't important for our needs, but you should just know that the channel and slot are like the address of where the brain is stored. A channel is like your street name, and a slot is like your house number. If I say "build a new house on Maple Avenue" then the builders will know where to put the house and I can find it later. As we build our array, we will be telling Project Spark to "add a new brain" for each storage location. We'll keep track of the channel address so that we can find those brains later.
What are Brain variables?
Just like you can have a number variable that holds a number, or a text variable that holds a string of text, you can create a brain variable that holds a reference to a specific brain. So in the example of Mary, we could have a variable called "Cooking Brain" that keeps track of her cooking skills brain. She might have a different brain variable called "Homework Brain" that keeps track of her homework helping skills. When Mary reads a math problem saying "There are 180 degrees in a triangle" she can store [number of degrees] = 180 without affecting the oven temperature.
The Kode for that might look like this:
WHEN [once] DO [cooking brain][equals][add brain][COOKING_SKILLS]
WHEN [once] DO [homework brain][equals][add brain][HOMEWORK_SKILLS]
WHEN [detect][math book] DO [homework brain][number of degrees][equals]
WHEN [detect][recipe book] DO [cooking brain][number of degrees][equals]
(See this Kode)
Notice how we can have the same number variable "number of degrees" in the same object (Mary) without having a conflict. Usually you cannot do this in Project Spark, but by using multi-brains we are enabling a special feature. This is called a brain-scoped variable, and it is the key to our array implementation.
Can we see the Array Kode already?
Let's consider the example of Hansel and Gretel walking through the woods. Hansel wants to be sure he can find his way back home, so he drops a bread crumb object every few feet. When it's time to go home, he plans to just follow the objects in reverse order. However, Hansel can only travel as far as his object count allows. Eventually he will run out of crumbs.
Gretel is using an array (a pad of paper) to keep track of her journey. Every few feet Gretel writes down the GPS coordinates of her position. Eventually she will run out of paper just like Hansel will run out of crumbs, but she can store 100 locations on one sheet of paper, where Hansel can only drop a crumb at one location at a time.
In Gretel's brain we have:
WHEN [right trigger][pressed] DO 
WHEN  DO [waypoint number][increment by]
WHEN  DO [write to array][equals][add brain][blank brain][to channel][waypoint number]
WHEN  DO [write to array][waypoint position][equals][Gretel][center]
(See this Kode)
Line 1 - Don't record a waypoint until we hit the Right Trigger. You don't want to fill up your paper while you're standing around. Without this line, we would be recording the position 30 times per second, even if her position never changed.
Line 2 - Increase the [waypoint number] variable each time we record a waypoint. This is our array index, which is the number written on the top of the box that I mentioned earlier. Using this number, we can quickly find the 14th waypoint on the list, if we needed to.
Line 3 - Create a brain variable called [write to array] and point it at a new brain we are adding to the channel called [waypoint number]. By using this number as our channel name, we can easily find this brain later, when it's time to go back home and we need to get the information back out. The brain we are adding is [blank brain], which can be stored in a logic cube, or can be saved to the brain gallery (your choice). If the brain is completely empty, Project Spark ignores it, so we need to add at least one tile. If we create a brain with WHEN [once] DO , there is no Kode running and the brain is effectively empty.
Line 4 - Using the brain variable [write to array] that we've just pointed at this brand new brain, we record Gretel's current position (at the center of her body) in a vector variable called [waypoint position]. Because this vector variable has [write to array] in front of it, we know that we are storing the vector information in the current array location.
Those four lines of Kode are enough to create the array and store waypoints in it. Note that there is a 100 brain limit for each object, so for this demonstration we are limited to 100 waypoints.
Now Gretel has a list of all of the places we pressed the Right Trigger button. Let's draw those points in the world, and number them.
WHEN [for each of][waypoint number]
WHEN  DO [read from array][equals][get brain][in channel][current index]
WHEN  DO [current waypoint position][equals][read from array][waypoint position]
WHEN  DO [draw sphere][current waypoint position][0.1]
WHEN  DO [display][current index][x-large font][at world position][current waypoint position]
(See this Kode)
Line 1- Remember that [waypoint number] was increased each time we added a waypoint, so it tells us the size of our array. We want to look at each of the locations in the array, so we use [for each of] with that number variable.
Line 2 - Create a new brain variable and point it at the brain we are retrieving from the channel at [current index]. The [current index] keeps track of where we are in the [for each of] loop, so it starts at 1, then 2, then 3, 4, etc until it ends at [waypoint number]. So we are saying "get the brain from channel 1 and point this variable at it" the first time through the loop.
Line 3 - This line is optional, but makes everything below it easier to read. We are reading the [waypoint position] back out of the array, and storing it in the vector variable [current waypoint position].
Line 4 - To help Gretel visualize her waypoints, we will draw a small sphere in the location. The radius of the sphere will be 0.1 meters.
Line 5 - To help Gretel know in what order she placed the waypoints, we are displaying the [current index] number in the world at the waypoint. Here we are just displaying the order, but you could do anything with that information. For example, you could have Gretel [move][toward][current waypoint position] or draw a line between the positions to show a path.
So that's it. Fewer than a dozen lines and we can keep track of up to 100 points of information without having to create ANY extra objects.
I don't get it...
If you didn't understand any of that, I recommend you just copy the nine lines above into a default character, and see what happens. Sometimes seeing it in action helps to understand what's going on.
Note: I have uploaded an example level, with Hansel dropping acorns every 1 second he's moving. Gretel records her position every 2 seconds (half as often). I'm also showing how many props Hansel has used for his pathfinding. Gretel uses only 1. I added a little bit of extra Kode to connect Gretel's waypoints with a line.
Hansel and Gretel Array Demo: http://www.projectspark.com/#world?id=6864000
Any questions? I know some people don't like to post questions in the Tutorials forum. I urge you to break habit if you have questions about this topic. I want to find where people need extra help understanding this topic, because I'm going to be recording a video version soon. Thanks (:
Bonus: Here's a video I made showing a more advanced version of this system. Eventually I expanded the system to reverse time for up to 5 minutes: http://youtu.be/BOg-BO0L1Xs