VC Arrays

Arrays in Vice City

There are currently three methods of creating arrays. The first one (Barton Waterduck's method) has been largely depricated now due to the fact that, although simple to use in his builders (using psuedo commands), the generated code was large and complicated.

Barton Waterduck's Arrays

Example of array code in the builder (note: this feature was introduced about v1.3):

DEFINE ARRAY $my_array size 2 type INTEGER
// Integer arrays were also used for storing ingame objects.

:label_my_code_0
0004: $my_array_index = 0

:label_my_code_1
GET_ARRAY $my_array
// Get the data from the array at position $my_array_index.
// Do whatever with it.
$my_array += 1
SET_ARRAY $my_array
$my_array += 1
0002: jump ££label_my_code_1

Example of this code compiled and decomplied:

:label_my_array_get_0
00D6: if 0
        $my_array_index == 0
004D: jump_if_false ££label_my_array_get_1
      $my_array = $my_array_data_0
0051: return

:label_my_array_get_1
00D6: if 0
        $my_array_index == 1
004D: jump_if_false ££label_my_array_get_2
      $my_array = $my_array_data_1
0051: return

:label_my_array_get_2
0051: return

:label_my_array_set_0
00D6: if 0
        $my_array_index == 0
004D: jump_if_false ££label_my_array_get_1
      $my_array_data_0 = $my_array
0051: return

:label_my_array_set_1
00D6: if 0
        $my_array_index == 1
004D: jump_if_false ££label_my_array_get_2
      $my_array_data_1 = $my_array
0051: return

:label_my_array_set_2
0051: return

:label_my_code_1
0050: gosub ££label_my_array_get_0
// Get the data from the array at position $my_array_index.

$my_array += 1
// Do whatever with it.

0050: gosub ££label_my_array_get_1
// Store it again

$my_array += 1
0002: jump ££label_my_code_1

This method of array is still most notably used in PatrickW's Marina Carpark Mod.

CyQ's Arrays

The second method of simulating arrays is CyQ's method. This uses one exploit of the SCM scripting engine in that parameters can be (in almost every OpCode, alot of the defining OpCodes are strangely limited) variables. It also uses the fact that an address, once compiled, is merely an offset from the start of the file (or mission). CyQ arrays calculate the address of a piece of code, store it in a variable then jump to the contents of that variable.

Note: This method requires detailed SCM knowledge to use due to the byte counting and files including this can (reputably) not be decompiled properly (at least by MB). A basic example which you can use to make arrays is explained below:

To retrieve data. $var0 - $var2 are the globals where the data is stored. 0@ is the local variable we will work on in the script.

:getlabel
008B:  0@ =  $var0   //these are the values we want to return from the array
0051:  return
008B:  0@ =  $var1   //the space that the 008B and the 0051 opcodes take up in total is 10 bytes because:
0051:  return     //opcode(2 bytes) + ptype(1 byte) + localvar(2 bytes) + ptype(1 byte) + var(2 bytes) + opcode(2 bytes) = 10
008B:  0@ =  $var2
0051:  return

<Here is where the code will start>
008B:  1@ = $index    //if we want the second value then $index = 1 (because for the first value $index = 0)
0012:  1@ *= 10        //10 * 1 = 10 (10 because the 008B + 0051 opcodes take up 10 bytes in this case)
000A:  1@ +=  ££getlabel //add the value of ££label to 1@
0050:  gosub 1@       //gosub to ££label + 10, so 0@ returns $var1 (the variable numbers match their array index).
<Here is where your processing happens>

To store data.

:setlabel
0088:  $var0 =  0@   //these are the values we want to store to the array.
0051:  return
0088:  $var1 =  0@ 
0051:  return
0088:  $var2 =  0@
0051:  return

<Here is where your processing happens>
008B:  1@ = $index  
0012:  1@ *= 10     
000A:  1@ +=  ££setlabel 
0050:  gosub 1@     // Same as before only we save the data not retrieve it.
<Here is where the code will end>

This method creates an offset from a label based on the index passed to it and a constant representing the number of bytes per short code block when compiled (for more detail on this please see the Vice City SCM Format article). The drawback with this method is that you have to create all the variable writing blocks yourself (although with copy and paste this doesn't take long).

This method of array (and other implementations of the variable jumping exploit) are most notably found in the original Myriad Islands VC SCM (ironically written by Barton Waterduck).

Y_Less's Arrays

Possibly the most difficult and complex implementation of arrays, it is the most accurate representation of arrays (with the index actually changing the array pointer) but it was more created as a 'this is possible' piece than an actual feasable piece.

It uses standard variable storage to store special numbers at consecutive points in the variable block. These numbers, once as HEX characters in memory will look like compiled SCM code which will be runable and will bypass the Mission Builder limitation of restricting DMA variables to remain within the variable block. The code in here contains the array index and when code updates the pointer, the actual DMA address of the variable is altered (this is after preprocessing of the index value, similar to multiplying and adding an address in CyQ's arrays).

The concepts behind it however (code rewriting, still in development by y-less) are more useful with uses such as variable text and code hooking.

The most notable use of code rewriting (as these arrays are never used in real life) is Demarest's Darkpactor code, which uses code developed by him and y-less to rewrite threads to run the darkpact code, unlike in older versions where you had to physically swap SCMs after adding the code.