Picture Pointer Patch Tutorial

Picture Pointer Tutorial - By Jaffer

Given the age of the patch, I'm sure everyone that uses RM2K3 has heard of Cherry's picture pointer patch.  However, there are still people that either don't know how to use it, or how to use it effectively.

So I've decided to write this tutorial on the uses of picture pointing and how it can severely cut down the size of your code AND the amount of pictures you use in RM2K3.  While picture limit is a lesser problem with 126 picture patches, having to display less pictures may help the speed of your game.

The Basics:
So, the first thing you need to know how to do is how to actually USE this patch.  Well, there are two functions this patch has:
Picture Numbering by Variable
Picture Numbering by Variable with Picture Name by Variable

So, the more simple application, Picture Numbering by Variable will be discussed first.
When you open a Picture menu, the first thing present is "Picture Number."  This is generally a number between 1 and 50, or 1 and 126 with a full picture patch applied.  RM does not natively have a variable reference option for pictures, but this patch adds that ability in.  So reference a picture number by variable, you simple do:

10000 + Variable ID = Picture Number
For example, if you wish to use Variable #259 to store the ID of the picture, you would use "10259" in the Picture Number box to achieve this.  If you want to use variable #4744, you would put "14744" in the picture number box.  Do note that this will pass the variables value into the picture number, so if this is out of range (over OR under the picture limit) your game WILL crash.  So, whatever variable you use, make sure to make it dedicated to picture ID#.  Do note: you can also input "10259" into "Erase Picture" command to erase the picture with the ID number stored in Variable #259.  You can also move pictures this way.

Effective Use of Picture ID# as a Variable:
Lets say you're making a special Shop in which you can only purchase items once.  Each item display is a picture, and there are thirty sperate items in the shop.  Customarily, you'd have to have THIRTY Conditional statements in order to erase the picture (or, you could move it to grey it out,) but regardless, it would take quite a bit of work, and time.  It'll also be a very large block of code.  So lets try this with Picture Pointing!

Variable[0001] = Cursor Position.  This value is between 1 and 30, and will dictate which item you're pointing at to erase OR move this picture after purchasing.  To handle the condition of whether or not you can actually buy said item, you will use a seperate variable reference in order to evade mass conditional branches.
Variable[0002] = Picture ID#.  This is the value we will use in order to erase the picture we're buying.
Variable[0010] -> Variable[0039] will be the variables holding the number of this item you can still buy.  If this is 0, the picture is greyed out or erased.
Variable[0004] = Reference Variable. This variable will do a fair bit of processing to check item quantities.

So, to make this even more devious, we'll pad it a bit.  Picture #1 is the menu background.  Picture #2 is the cursor.  Picture #3 is the description. 

Pictures #4 -> #33 are your picture displays.

Alright.  Now, the player selects any random item to buy.  Lets say, item #27 on the list.  By math, we can conclude that this is picture #30. (3 + 27 = 30)
So, firstly, to erase this picture, or any picture in this list, we will do as follows:
Picture ID#[0002] = Cursor Position
Picture ID#[0002] + 3 (the amount of pictures displayed before the purchasable items)
Erase Picture: 10002 (or Move Picture 10002).

This'll erase/grey out the image.  Now, lets say you can purchase an item a few times.  If you do not know how to properly use Varible References, you need to learn this.  It's the most pertinent skill needed to use this patch.

Reference Variable[0004] = Cursor Position
Reference Variable[0004] + 9 (the number directly before your first variable to check, since 9 + 1 = 10, which is the first variable)
Reference Variable[0004] = Value in Reference [Reference Variable[0004]]  -- Yes, you're setting it to the value the variable itself is indexing!  You may want to use another variable for this, it just depends on your preference.

If Reference Variable >= 1
> Reference Variable[0004] = Cursor Position
> Reference Variable[0004] + 9
> Value in Index [Reference Variable[0004]] - 1
> Reference Variable[0004] = Value in Reference [Reference Variable[0004]]
> If Reference Variable == 0
>> Picture ID#[0002] = Cursor Position
>> Picture ID#[0002] + 3
>> Erase Picture: 10002 (or move it)
> End
Else
> Play Sound "Not available" // Any error sound since this item is sold out
End

In this small snippet of code, you just covered what would usually take 30 Conditional Branches to accomplish.  See how effective this is?  And simply referencing ID#s is just the tip of the iceberg.

The Use of Picture Number by Reference:

And now, the more advanced (and in my opinion, the more useful) application of this patch: Picture Name Referencing.
To reference a picture by name and ID (no, you cannot simply reference a picture name, it has to do both ID AND Name), you use the format:
50000 + Variable ID = Picture Number (You put this into the Picture Number Box!)
50000 + Variable ID + 1 = Picture Name Variable

So, as an initial precaution, your variables MUST BE ORDERED LIKE THIS:
Variable[XXXX] = Picture ID#
Variable[XXXX + 1] = Picture Name Reference
So, if [0323] is your Picture ID, then [0324] is your picture name reference, and there is no changing this!

So, back to our previous example of a shop, it would also take 30 Conditional Branches to simply display what is and is not purchasable!  That's no good.
So, if you want to reduce this to just a snippet of code, you will first need to do some formatting.
Picture Names:
Now, the "limitation" of this patch (which is caused by RM, most likely) is that your picture reference can only modify the name to an INTEGER VALUE.  It must be positive between 0 and 9999, and all of your pictures must be formatted to use this.  So, lets say the items in this shop are labeled SpecialItem. 

Originally, you probably named them SpecialItem1, SpecialItem2 ... SpecialItem30 (or just named them by their item name), but now we're gonna format them to use this patch.  The names will now be:
SpecialItem0001
SpecialItem0002
...
SpecialItem0030

Or, in basic form:
(NamePrefix)(ID# as a FOUR DIGIT INTEGER).  As noted in the patch documentation, if you call a picture "Hello" through picture reference with a variable number of 1337, then it will try to open H1337 NOT Hello1337.  Be weary of this, and make sure to put XXXX as a four digit integer after the picture name prefix (the prefix would most generally just be the type of item, like say Consumable0000, Weapon0032, KeyItem0999)

Note that the range of this operation is dictated by how many pictures you have.  So, if you try to call SpecialItem0093, your game WILL crash because in this example, SpecialItem0030 should be the largest.
Continuing on, we're going to use the original variables, with a minor addition:
Variable[0001] = Cursor Position.  This value is between 1 and 30, and will dictate which item you're pointing at to erase OR move this picture after purchasing.  To handle the condition of whether or not you can actually buy said item, you will use a separate variable reference in order to evade mass conditional branches.

Variable[0002] = Picture ID#.  This is the value we will use in order to erase the picture we're buying.
Variable[0003] = Picture Number.  This is dictate which specific picture is called.
Variable[0010] -> Variable[0039] will be the variables holding the number of this item you can still buy.  If this is 0, the picture is greyed out or erased.
Variable[0004] = Reference Variable. This variable will do a fair bit of processing to check item quantities.
Variable[0005] = Cycle Counter.  This variable will count the cycles that the loop we will be using does.

So now, we're going to combine some flow control with some Picture Pointer Magic.

Cycle Counter[0005] = 1
Picture ID#[0002] = 4 (the first picture used)
Cursor Position = 1 (simple menu initialization)
Loop
> Reference Variable[0004] = Value of Variable [Cycle Counter[0005]]
> Picture Number[0003] = Reference Variable[0004]
> Reference Variable[0004] + 9 // This will point to the specific item in this slot
> Reference Variable[0004] = Value in Reference [Reference Variable[0004]]
> If Reference Variable[0004] >= 1
>> Show Picture 50002 :: Special Item0000 :: Color 100, 100, 100, 100 (this will show the picture as its default color)
> Else
>> Show Picture 50002 :: Special Item0000 :: Color 50, 50, 50, 100 (this will show the item as greyed out.  You could also put Erase Picture 10002)
> End
> If Picture ID#[0002] == 33 // We put this BEFORE the variable increment to avoid errors
>> Break out of Loop
> End
> Cycle Counter[0005] + 1
> Picture ID#[0002] + 1
>
End of Loop

Like this, the code will show the correct picture.  HOWEVER, something VERY important is missing!  The X and Y Coordinates!  Without these, you would not show the Picture at its correct position.  So lets first look at this in the "Easy Way".

Cycle Counter[0005] = 1
Picture ID#[0002] = 4 (the first picture used)
Cursor Position = 1 (simple menu initialization)
Picture X[0006] = 40
Picture Y[0007] = 24
Loop
> Reference Variable[0004] = Value of Variable [Cycle Counter[0005]]
> Picture Number[0003] = Reference Variable[0004]
> Reference Variable[0004] + 9 // This will point to the specific item in this slot
> Reference Variable[0004] = Value in Reference [Reference Variable[0004]]
> If Reference Variable[0004] >= 1
>> Show Picture 50002 :: Special Item0000 :: X = Picture X[0006], Y = Picture Y[0007] :: Color 100, 100, 100, 100 (this will show the picture as its default color)
> Else
>> Show Picture 50002 :: Special Item0000 :: X = Picture X[0006], Y = Picture Y[0007] :: Color 50, 50, 50, 100 (this will show the item as greyed out.  You could also put Erase Picture 10002)
> End
> If Picture ID#[0002] == 33 // We put this BEFORE the variable increment to avoid errors
>> Break out of Loop
> End
> Cycle Counter[0005] + 1
> Picture ID#[0002] + 1
> Picture Y + 8 (This will move the next picture down 8 pixels.  It doesn't necessarily need this value, butfor examples sake)
>
End of Loop

You could also add variables to dictate the coordinates of these.  Make sure the variables are sequential, though.  You could do either:
Variable[0101] => Variable[0150] or => Variable[0237] (depending on how many pictures you have) are the X coordinates, then Variables[0151] => Variable[0200] for the Y's, or Variable[0238] => Variable[0363] (again, depending on how many pictures you have).  You could also alternate, such that Odd Variables are X coordinates and even Variables are Y coordinates.  To reference the coordinate position for an Alternating style, you would do this:

Picture X[0006] = Picture ID#[0002]
Picture X[0006] - 1
Picture X[0006] * 2
Picture X[0006] + 101 // Whatever the initial picture coordinate is at
Picture Y[0007] = Picture X[0006]
Picture Y[0007] + 1
Picture X[0006] = Value in Reference [Picture X[0006]]
Picture Y[0007] = Value in Reference [Picture Y[0007]]

If you use the style where you list all the X's, then all the Y's.
Picture X[0006] = Picture ID#[0002]
Picture Y[0007] = Picture ID#[0002]
Picture X[0006] + 100 // one before the first picture coordinate value
Picture Y[0007] + 150 // one before the first picture coordinate value
Picture X[0006] = Value in Reference [Picture X[0006]]
Picture Y[0007] = Value in Reference [Picture Y[0007]]

This will change your code a bit.

Cycle Counter[0005] = 1
Picture ID#[0002] = 4 (the first picture used)
Cursor Position = 1 (simple menu initialization)
Picture X[0006] = 40
Picture Y[0007] = 24
Loop
> Reference Variable[0004] = Value of Variable [Cycle Counter[0005]]
> Picture Number[0003] = Reference Variable[0004]
> Reference Variable[0004] + 9 // This will point to the specific item in this slot
> Reference Variable[0004] = Value in Reference [Reference Variable[0004]]
> Picture X[0006] = Picture ID#[0002]  // Place the specific algorithm to find the variable.  This is for alternating.
> Picture X[0006] - 1
> Picture X[0006] * 2
> Picture X[0006] + 101 // Whatever the initial picture coordinate is at
> Picture Y[0007] = Picture X[0006]
> Picture Y[0007] + 1
> Picture X[0006] = Value in Reference [Picture X[0006]]
> Picture Y[0007] = Value in Reference [Picture Y[0007]]
> If Reference Variable[0004] >= 1
>> Show Picture 50002 :: Special Item0000 :: X = Picture X[0006], Y = Picture Y[0007] :: Color 100, 100, 100, 100 (this will show the picture as its default color)
> Else
>> Show Picture 50002 :: Special Item0000 :: X = Picture X[0006], Y = Picture Y[0007] :: Color 50, 50, 50, 100 (this will show the item as greyed out.  You could also put Erase Picture 10002)
> End
> If Picture ID#[0002] == 33 // We put this BEFORE the variable increment to avoid errors
>> Break out of Loop
> End
> Cycle Counter[0005] + 1
> Picture ID#[0002] + 1
>
End of Loop

This will allow you to display multiple pictures at any different coordinate set (which you would probably predefine).

So, why exactly would you want to display something at different coordinates?  Well, a prime example is a menu system that needs to displays multiple HPs, MPs, and the like.  If you structure it well, you could easily show every single number on the menu with a single Loop Cycle!  Veeeery easy, very fast.  I will add such an example to this Tutorial later on.