SC2Mapster

Disclaimer & How To Use

Pick each functions make it easier to loop through arrays and nested loops and makes things more descriptive (ie. Pick Each 7 Array Items or Pick Each 8 Heros, with values being accessable through Picked Array Item or Picked Hero, etc, etc).

A disclaimer though. I assume this is the same method blizzard uses for their pick each loops. If so, using those loops or this function is 5x slower than a normal for each loop. I don't recommend nesting more than 3-4 pick each functions using this and if you are more comfortable using for each loops by all means use them. That being said, there should be little to no difference using this over a standard Pick Each Integer function.

Once you have defined the function, use it the same way you would use a normal "pick each" loop function. Note if you need to nest them, you need to define a new preset type. You still cannot nest 2 of the same type of pick eaches. Ex.

Pick Each Item and do
   Pick Each Item and do

will not work.

Creating Custom Pick Each Functions

If you’ve created a map or mod, you may be familiar with the Pick Each Integer (or its kin) functions. These are handy functions that allow you to pick each variable from X to Y, and then recall the “Picked Integer” in your function. For example:

Pick Each Player and do
Actions
     Pick Each Integer from 1 to 9 and do
     Actions
-	Create 1 Marine for Player (Picked Player) at Point (point[Picked Integer]).

But sometimes you have a multi-dimensional array and if you’ve used Pick Each functions before, you know you cant nest them.

Example nesting that doesn’t work

<point> Point = [9][30];
Pick Each Player and do
Actions
     Pick Each Integer from 0 to 9 and do
     Actions
                    Pick Each Integer from 0 to 29 and do
                    Actions
	Create 1 Marine for Player (Picked Player) at Point (point[Picked Integer][Picked Integer]).

Now many of you are probably saying at this point, "Well, I can just nest For Each statements". While that is entirely possible, if you ever come back to your code, do you know what variable [x][y][z] is referencing? This tutorial is here to help solve that problem.

By the time we’re done, youll be able to setup something similar to the following

Pick Each Player and do
Actions
     Pick Each 10 PointX’s  do
     Actions
                    Pick Each 30 PointY’s and do
                    Actions
	Create 1 Marine for Player (Picked Player) at Point (point[Picked PointX][Picked PointY]).

Getting Started

What we’re going to be creating today is a custom pick each function that’s highly flexible, and can help simplify the readability of your code. We’ll be creating a “Pick Each Preset” function. While we cant nest individual presets, we CAN create new presets that CAN be nested! Haha! However, this requires a little bit of knowledge about presets, functions, actions, and data tables. Lets get started.

Open up the trigger editor and create a new folder named “Loops”. This will house our pick each functions. It doesn’t matter if you create a new library or if you put this in the trigger editor. Whichever way is most comfortable for you to use. They’re essentially the same.

With our new folder created, right click on it and click “New Preset Type”. Name it “Pickable Presets”. This will be the name for our custom pick each functions. Click on the new preset type and add a new field called “Team”. We can add more later.

Now right click on our Loops folder and create a function definition. Name it “Picked Preset”. We’ll get back to this in a minute. Right click the folder again and add some action definitions. We’re going to need 5. “Pick Each Preset”, “Preset Loop Begin”, “Preset Loop End”, “Preset Loop Current” and “Preset Loop Step”. Look familiar? If you’ve played with the native library, you’ll recognize this as being similar to the Pick Each Integer function.

Continuing on: Now that we have our functions and presets defined, we’re ready to get started.

Click the "Pick Each Preset" function you just created a set the following options: Creating Custom Pick Each Functions If you’ve created a map or mod, you may be familiar with the Pick Each Integer (or its kin) functions. These are handy functions that allow you to pick each variable from X to Y, and then recall the “Picked Integer” in your function. For example:

Pick Each Player and do Actions Pick Each Integer from 1 to 9 and do Actions - Create 1 Marine for Player (Picked Player) at Point (point[Picked Integer]).

But sometimes you have a multi-dimensional array and if you’ve used Pick Each functions before, you know you cant nest them.

For example this doesn’t work: <point> Point = [9][30]; Pick Each Player and do Actions Pick Each Integer from 0 to 9 and do Actions Pick Each Integer from 0 to 29 and do Actions Create 1 Marine for Player (Picked Player) at Point (point[Picked Integer][Picked Integer]).

By the time we’re done, youll be able to setup something similar to the following Pick Each Player and do Actions Pick Each 10 PointX’s do Actions Pick Each 30 PointY’s and do Actions Create 1 Marine for Player (Picked Player) at Point (point[Picked PointX][Picked PointY]).

What we’re going to be creating today is a custom pick each function that’s highly flexible, and can help simplify the readability of your code. We’ll be creating a “Pick Each Preset” function. While we cant nest individual presets, we CAN create new presets that CAN be nested! Haha! However, this requires a little bit of knowledge about presets, functions, actions, and data tables. Lets get started.

Open up the trigger editor and create a new folder named “Loops”. This will house our pick each functions. It doesn’t matter if you create a new library or if you put this in the trigger editor. Whichever way is most comfortable for you to use. They’re essentially the same.

With our new folder created, right click on it and click “New Preset Type”. Name it “Pickable Presets”. This will be the name for our custom pick each functions. Click on the new preset type and add a new field called “X Value” and another called "Y Value". We can add more later.

Now right click on our Loops folder and create a function definition. Name it “Picked Preset”. We’ll get back to this in a minute. Right click the folder again and add some action definitions. We’re going to need 5. “Pick Each Preset”, “Preset Loop Begin”, “Preset Loop End”, “Preset Loop Current” and “Preset Loop Step”. Look familiar? If you’ve played with the native library, you’ll recognize this as being similar to the Pick Each Integer function.

Continuing on: Now that we have our functions and presets defined, we’re ready to get started.

Pick Each Preset

Click the "Pick Each Preset" function you just created and set it up like the following: Note: Under grammar text, select "X" and set it to the limit parameter. Select "Global" and set it to the global parameter. Note: The global parameter is set to our custom preset, "pickable presets"

Pick Each Preset
    Options: Action, Sub-Functions, Loop
    Return Type: (None)
    Parameters
        global = Team <Pickable Presets>
        limit = 0 <Integer>
    Grammar Text: Pick Each of x Global's and do
    Hint Text: Pick each preset is 0 base. Picked Preset will return the current value -1. Ex. Pick each 3 Globals will cause picked preset to return 0, 1 and 2.
    Custom Script Code
    Sub-Function Types
        Actions

Now we need a little scripting to make some magic happen. Click "Custom Script Code" and put in the following:

#AUTOVAR(global,int) = #PARAM(global);
#AUTOVAR(limit,int) = #PARAM(limit);

gf_PresetLoopBegin(#AUTOVAR(global), #AUTOVAR(limit));

while (!gf_PresetLoopDone(#AUTOVAR(global))) {
    #SUBFUNCS(Actions);
    gf_PresetLoopStep(#AUTOVAR(global));
}
gf_PresetLoopEnd(#AUTOVAR(global));

The first #AUTOVAR declarations take our parameters and set them to local variables. This is to prevent our code from putting undue strain on the system.

The third line calls our Preset Loop Begin function. Make sure this name matches up to the id given when you created your other functions. if you following the naming EXACTLY, then you should be fine.

The fourth line, our while statement, calls the preset loop and determines if we've reached the end or not. Note how we pass #AUTOVAR(global) into these functions. This is to make sure our loops dont intefere with each other.

1. SUBFUNCS(Actions); this is where our actions get called. the next line increments our loop count by 1. Again note we pass the global variable into it. the last line does our cleanup work.

Now noticed how we use #PARAM(global). This is retrieving our "global" parameter value. and sending it to our sub-functions which we're about to define proper.

Preset Loop Begin

We're going to be using data tables for our variables. Data tables are great in the aspect they can be global or local, much like variables, however they are THREAD SPECIFIC. This means a local data table is tied to the calling TRIGGER, not the calling FUNCTION. Note we use the "hidden" action flag here. This is so it doesn't clutter up our nice functions.

Setup Preset Loop Begin to look like the following:

Preset Loop Begin
    Options: Action, Hidden
    Return Type: (None)
    Parameters
        pickable <Pickable Presets>
        end = 0 <Integer>
    Grammar Text: Preset Loop Begin(pickable, end)
    Hint Text: (None)
    Custom Script Code
    Local Variables
        p = (String((Integer(pickable)))) <String>
    Actions
        Data Table - Save 0 as (p + "i") in the Local data table
        Data Table - Save end as (p + "e") in the Local data table

Notice how we take the parameter pickable, which is our preset, and convert it to a string and save it to a local variable "p". This is for simplicity sake. "p" in detail is ConvertIntegerToString(ConvertPresetToInteger(pickable)). Remember this. It's done numerous times.

Under actions youll notice we're using the action "Save integer to data table" and we're storing values to our local (thread-specific) data table. The (p + "i") is combining the strings "p" and "i". "i" is our custom reference to our index position. Essentially the data table is storing "pi" and "pe" values. For "pi" we store 0, so we reset the index. For "pe" we store "end", which is our limit defined in our "Pick Each function".

Preset Loop Done

This is where we determine if our loop is done. It should look like the following:

Note: again we use the hidden flag and a global parameter which is our preset type.

Preset Loop Done
    Options: Action, Hidden
    Return Type: Boolean
    Parameters
        global <Pickable Presets>
    Grammar Text: Preset Loop Done(global)
    Hint Text: (None)
    Custom Script Code
    Local Variables
        p = (String((Integer(global)))) <String>
        index = ((p + "i") from the Local data table) <Integer>
        end = ((p + "e") from the Local data table) <Integer>
    Actions
        General - If (Conditions) then do (Actions) else do (Actions)
            If
                index < end
            Then
                General - Return False
            Else
                General - Return True

This is fairly self explanitory. "p" is the same as before. index is a local variable that grabs the (combined strings(var p + "i") from the local data table. end does the same for our limit. Then we have a general if then else statement to determine if we've reached the end of our loop. (Self-Explanitory)

Preset Loop Step

By now you should be familiar with what we're doing. We have our global parameter (which we pass in our preset) and our local converted "p" variable. This time under actions, we save a value to the data table. This is a little simplified, but basically its saving the current value of the datatable item "pi" +1 to the data table value "pi". Its basically "pi";

Preset Loop Step
    Options: Action, Hidden
    Return Type: (None)
    Parameters
        global <Pickable Presets>
    Grammar Text: Preset Loop Step(global)
    Hint Text: (None)
    Custom Script Code
    Local Variables
        p = (String((Integer(global)))) <String>
    Actions
        Data Table - Save (((p + "i") from the Local data table) + 1) as (p + "i") in the Local data table

Preset Loop End

Our last step. Here we clean up our database. This should be self-explanitory by now.

Preset Loop End
    Options: Action, Hidden
    Return Type: (None)
    Parameters
        global <Pickable Presets>
    Grammar Text: Preset Loop End(global)
    Hint Text: (None)
    Custom Script Code
    Local Variables
        p = (String((Integer(global)))) <String>
        index = ((p + "i") from the Local data table) <Integer>
        end = ((p + "e") from the Local data table) <Integer>
    Actions
        Data Table - Remove (p + "i") value from the Local data table
        Data Table - Remove (p + "e") value from the Local data table

Recap

Remember our custom script code from the beginning? After inputting all that data, see if you can recognize what it's doing now. Here's a repaste

#AUTOVAR(global,int) = #PARAM(global);
#AUTOVAR(limit,int) = #PARAM(limit);

gf_PresetLoopBegin(#AUTOVAR(global), #AUTOVAR(limit));

while (!gf_PresetLoopDone(#AUTOVAR(global))) {
    #SUBFUNCS(Actions);
    gf_PresetLoopStep(#AUTOVAR(global));
}
gf_PresetLoopEnd(#AUTOVAR(global));

Utilizing Our New Function

If you're working under a new map (for simplicity sake, lets say you are), go ahead and create a new trigger. Set the event to "Map initilization" and under actions set the following:

        Visibility - Reveal (Entire map) for player 1 for 0.0 seconds and Do Not check cliff level
        General - Pick Each of 2 X Value's and do
            Actions
                General - Wait 1.5 Game Time seconds
                Unit - Create 1 Marine for player ((X Value) + 1) at (Random point in (Playable map area)) using default facing (No Options)
                General - Pick Each of 4 Y Value's and do
                    Actions
                        Unit - Create 1 Immortal for player ((Y Value) + 1) at (Position of (Last Created Unit) using default facing (No Options)

Notice we use our "Pick each preset twice. When we create our marines, we use our X value to assign them to player 1 and 2. For the second, we use our Y value. Now when you run your map, you should see 2 marines and immortals for player 1 and 2, and 2 more immortals for player 3 and 4. This tells us our nested loops are working. Now if you were using a multi-dimensional array of points, or units, or whatever, you could quickly loop through them and still read the code later. This hopefully makes it much easier than:

var a=0
var b=0
var c=0
var d=0
var e=0

For Each a from 0 to 9
For Each b from 0 to 4
For Each c from 0 to 13
For Each d from 0 to 26
For Each e from 0 to 5
   Do Action at variable[a][b][c][d][e]

Now later if you find you need to nest more types, just add a new preset. Remember to use common sense though when applying your custom preset type. If you can use one type that you've already defined, do it.

Hope this helps! Enjoy!

Quote:

lib1_gv_globals[#PARAM(global)] = 0; while (lib1_gv_globals[#PARAM(global)] <= (#PARAM(limit)-1)) {

1. SUBFUNCS(Actions); lib1_gv_globals[#PARAM(global)] = lib1_gv_globals[#PARAM(global)] + 1; }

you should replace whatever is asked more than once with #AUTOVAR's. If user uses function in parameter it will be pasted instead of #PARAM. That's why Blizzard by default create temp storage to ask for value once. If it's something like FindLimitInArrayOf5000 than it will be ran each loop which will cause massive performance loss.
I should also mention, for users sake, that if this is run with Waits inside and other function runs the same in different Trigger/thread it will yield incorrect results.

And i have to criticize, since i know you made it due your recent thread, That's not really the purpose of Pick Each and Macros in general. Idea behind them is to make iterating thru custom collection easier. Like for example for each word in string where you actually preform some logic operations; make the "illusion" of really going thru some custom structure.
In your example you basically done cheaper version of 'pick each integer' which won't really teach anyone how to do use this properly. Not to mention that you didn't even explain what #PARAM is

@Nerfpl: Go If you have recommendations for edits to the code, I more than welcome it. However saying "you should have done x instead of y" doesn't really help anyone. On that note, I have updated the code to reflect using #AUTOVAR's

This was built for circumstances where you loop through a basic array or integer value, and isnt necessarily designed for complex systems. It also presumes a basic knowledge of programming. There are plenty of threads explaining #AUTOVAR and #PARAM, or do I need to explain how to use GUI in my tutorial also?

Also, since you mentioned the waits, are you recommending it run in its own thread?

Quote from Nerfpl: Go

Also, since you mentioned the waits, are you recommending it run in its own thread?

No i mean a wait inside Actions which is perfectly fine from user's perspective.

Quote from ckSynergy: Go

This was built for circumstances where you loop through a basic array or integer value

That's what 'For' loops are which i'm telling you from beginning. If you programming knowledge is basic than you should get used to define common 'int i' etc

Quote from ckSynergy: Go

It also presumes a basic knowledge of programming.

Ur knowledge of programming is below basic. You never define (replaced) #AUTOVAR. It won't work in current form ( hence you didn't even test it (lazy) )

If the purpose of tutorial is "Creating a Custom "Pick Each" Function" then you First explain what is all about. What each of those # does, how does it work, then do simple example based on knowledge reader have learned.

Such tutorial would be obviously good to have, but is done wrong, explain's nothing, gives bad examples, doesn't provide the reason to use this functionality in reasonable way, and it just shows off your "i did it"

Quote from Nerfpl: Go

@ckSynergy: Go Ur knowledge of programming is below basic. You never define (replaced) #AUTOVAR. It won't work in current form ( hence you didn't even test it (lazy) )

Actually, I did test it and it works fine. Nice try at attacking my skill level though and if you want to talk about being lazy, its Your, not Ur.

Quote from Nerfpl: Go

@ckSynergy: Go That's what 'For' loops are which i'm telling you from beginning. If you programming knowledge is basic than you should get used to define common 'int i' etc

If the purpose of tutorial is "Creating a Custom "Pick Each" Function" then you First explain what is all about. What each of those # does, how does it work, then do simple example based on knowledge user have learned.

Such tutorial would be obviously good to have, but is done wrong, explain's nothing, gives bad examples, doesn't provide the reason to use this functionality in reasonable way, and it just shows off your "i did it"

For loops are ok, but when you have several nested, you can lose track of what numbers represent what easily. Again, make recommendations instead of trying to somehow "prove" you're "superior" by attempting to degrade the people that are trying to solve problems.

As for my tutorial, I explained what its for, how it works, and it has an example at the end. If you think its wrong or doesn't give enough detail, feel free to rewrite it or at least explain what needs changing and where.

Quote from ckSynergy: Go

Actually, I did test it and it works great. Nice try at attacking my skill level but until you can show me you can design a better system it's an empty statement and if you want to talk about being lazy, its You're, not Ur.

Well you'r partially right. Proper var definition is #AUTOVAR(name,type). If user makes parameter other than integer it will throw error.

Quote from ckSynergy: Go

Again, make recommendations instead of trying to somehow "prove" you're "superior" by attempting to degrade the people that are trying to solve problems.

Those were recommendations. By "degrading" you mean fact i'm pointing your errors?

@Nerfpl: Go

@ #AUTOVAR: Ah right, forgot the type declaration.

@"Recommendations": Calling someone lazy and their knowledge "below basic" is not a recommendation. I have no problem with people pointing out errors in my code.

Quote from Nerfpl: Go

@ckSynergy: Go No i mean a wait inside Actions which is perfectly fine from user's perspective.

Right, how would you recommend making it thread safe?

Quote from ckSynergy: Go

Right, how would you recommend making it thread safe?

Additional function. Some indexer. So it would be something like

#AUTOVAR(tindex,int) = GetNextIndex();
Then your global would also require to be double array
Index could recycle i at, for example, 32 (or more)

Or something like that. I haven't really put much thought into it.
EDIT: Meh nvm, then you can't get the picked value

Quote from Nerfpl: Go

@ckSynergy: Go

Additional function. Some indexer. So it would be something like

#AUTOVAR(tindex,int) = GetNextIndex();
Then your global would also require to be double array
Index could recycle i at, for example, 32 (or more)

Or something like that. I haven't really put much thought into it. EDIT: Meh nvm, then you can't get the picked value

Yea, thats the problem I was facing. Ideally Id create a local variable inside the calling trigger, but you cant do that from a function/sub-function

Blizzard uses LoopStart and LoopEnd which may suggest they save variable in some table using function id and thread i.
Then LoopGetCurrent returns current value. That's probably also why they use LoopStep and !LoopDone
LoopEnd clears the value to free memory and that's why is 0 outside of the loop

all of those internally have access to function id and thread i they run in. I Guess

Quote from Nerfpl: Go

Blizzard uses LoopStart and LoopEnd which may suggest they save variable in some table using function id and thread i. Then LoopGetCurrent returns current value. That's probably also why they use LoopStep and !LoopDone LoopEnd clears the value to free memory and that's why is 0 outside of the loop

all of those internally have access to function id and thread i they run in. I Guess

Possibly, or at least stores it as local variables inside the function call. I'll see what I can work out with data tables. In the mean time,best say this is a non-thread-safe way of doing Pick Each functions.

@Nerfpl: Go

Got it figured out. Imitating the functions blizzard used and local data tables, was able to modify it so it's thread safe now. I'll update the tutorial accordingly shortly.