{"id":7412,"date":"2026-05-05T20:43:49","date_gmt":"2026-05-06T00:43:49","guid":{"rendered":"https:\/\/www.caskeys.com\/dc\/?p=7412"},"modified":"2026-05-30T10:34:07","modified_gmt":"2026-05-30T14:34:07","slug":"using-openbor-arrays","status":"publish","type":"post","link":"https:\/\/www.caskeys.com\/dc\/using-openbor-arrays\/","title":{"rendered":"Using OpenBOR Arrays"},"content":{"rendered":"\n

<\/p>\n\n\n\n

Introduction<\/h2>\n\n\n\n

OpenBOR Script includes array support, but despite the C-like syntax, OpenBOR arrays have their own behavior, strengths, and quirks. They are not scoped data structures in the usual sense, but instead behave much more like heap-allocated objects you access through handles. This gives OpenBOR arrays tremendous flexibility, but also means they require active care and cleanup.<\/p>\n\n\n\n

To make things more interesting, OpenBOR arrays are really two storage systems sharing the same API. One is a true indexed array straight out of C – close to the metal and built for raw performance at the cost of flexibility. The other is a doubly linked list with hash acceleration – not as fast as an indexed array, but more human-friendly to use and open to unstructured data. Which one you use depends entirely on the type of key you pass to functions like get()<\/code>, set()<\/code>, delete()<\/code>, and related helpers.<\/p>\n\n\n\n

Which one is best depends on your needs in the moment. After reading this guide, you should have a stronger understanding of which one to employ and when.<\/p>\n\n\n\n

Defining Terms<\/h2>\n\n\n\n

Before getting into specifics, it helps to understand what arrays and lists are in general programming terms. OpenBOR supports both concepts, but exposes them through the same \u201carray\u201d interface. We will use code samples suited to OpenBOR, but the basic principles explained here are mostly universal.<\/p>\n\n\n\n

Array<\/h3>\n\n\n\n

An array is a container that stores multiple values under one name. Instead of creating separate variables for every related value, you store them together and access each one by position.<\/p>\n\n\n\n

For example, instead of this:<\/p>\n\n\n

\nvoid item_0 = "apple";\nvoid item_1 = "banana";\nvoid item_2 = "cherry";\n<\/pre><\/div>\n\n\n
you could use an array:<\/p>\n\n\n
\nvoid items = array(3);\n\nset(items, 0, "apple");\nset(items, 1, "banana");\nset(items, 2, "cherry");\n<\/pre><\/div>\n\n\n
Then you can retrieve a value by its index:<\/p>\n\n\n
\nvoid item = get(items, 1); \/\/ banana\n<\/pre><\/div>\n\n\n
The number used to access the value is called an index<\/strong>. Most programming languages, including OpenBOR Script, use zero-based indexing<\/strong>, which means the first element is index 0<\/code>, the second is index 1<\/code>, and so on. <\/p>\n\n\n\n
\"\"<\/a><\/figure>\n\n\n\n
High Performance, Poor Flexibility<\/h4>\n\n\n\n
Traditional arrays are a lot like drag racers – they offer maximum performance at the cost of flexibility. Array elements occupy a single contiguous block of memory, which allows hardware-level acceleration 1<\/a><\/sup> and direct access by index. Once the engine knows the starting location of the array and the index you asked for, it can calculate exactly where that element lives.<\/p>\n\n\n\n
This means arrays are not just fast, but consistently fast. It doesn\u2019t matter how many elements are in an array or which element you are looking for. Finding that element always takes the same amount of time. We call this constant time complexity<\/em>, or O(1).<\/p>\n\n\n
\nvoid baby_bear = array(100);\nvoid mama_bear = array(10000);\nvoid poppa_bear = array(100000);\n\n\/* Same access time for each. *\/\nset(baby_bear, 99, "apple");\nset(mama_bear, 9999, "banana");\nset(poppa_bear, 99999, "cherry");\n\n\/* Still same access time. *\/\nvoid some_value_a = get(baby_bear, 99);\nvoid some_value_b = get(mama_bear, 9999);\nvoid some_value_c = get(poppa_bear, 99999);\n<\/pre><\/div>\n\n\n
The tradeoff is that arrays do not grow or shrink freely. Adding or removing elements requires creating a new array of the correct size and copying the old contents over. That is why arrays are extremely fast when their size and layout are known ahead of time, but less convenient when the structure needs to change constantly. <\/p>\n\n\n\n
Think of looking for a set of books about one subject. An array is like having every book on the same shelf, lined up in order. Once you know the shelf and the book number, you can go straight to it. Separate variables are more like having those books scattered across the library – easier to shelve, much harder to find.<\/p>\n\n\n\n
OpenBOR Arrays<\/h4>\n\n\n\n
OpenBOR\u2019s array implementation is very similar to C-style arrays, but with a management layer that allows growth, inserts, and size reflection. These features are useful, but they can also be a double-edged sword. We\u2019ll get to the details further below, including how they work and when you should or shouldn\u2019t use them.<\/p>\n\n\n\n
The important takeaway for now is that OpenBOR indexed arrays behave like traditional single-dimension C-style arrays from the script writer\u2019s perspective. They share the same advantages of O(1) access speed and efficient indexed storage.<\/p>\n\n\n\n
\"OpenBOR<\/a>
Simplified illustration of OpenBOR\u2019s indexed array layout and access. In actuality, the array elements contain pointers to structures that house the payload rather than the payload value itself, but the effect is still the same. Simple offset calculations and hardware acceleration provide maximum performance.<\/figcaption><\/figure>\n\n\n\n
Lists<\/h3>\n\n\n\n
Lists are another kind of container, but they are built differently from arrays. Instead of storing every value in one contiguous block of memory, a list stores values in individual structures, called nodes. Each node contains the value, plus one or more pointers that tell the engine where to find the next node.<\/p>\n\n\n\n
Doubly linked lists go one step further. Each node points both forward and backward, so the engine can move to the next node or the previous node.<\/p>\n\n\n\n
High Flexibility, Lower Performance<\/h4>\n\n\n\n
Lists are a lot like a train. Each car is separate, but linked to the cars before and after it. Adding or removing a car does not require rebuilding the entire train. You just connect or disconnect the nearby cars.<\/p>\n\n\n\n
That flexibility is the main advantage. Lists can grow naturally, and inserting or removing entries is usually less disruptive than resizing an array. Lists are also able to use non-integer keys, and they don\u2019t require identifiers to be numeric, contiguous, or sequential. Again think of a train. It doesn’t matter where the grain car or box car is, nor what their names are, as long as the links are present.<\/p>\n\n\n\n
The tradeoff is lookup speed and memory overhead. Because each node is a separate object, values are scattered around memory instead of packed together. To find a specific entry, the engine may have to walk through nodes until it finds a match. Each node also needs extra memory for its links. <\/p>\n\n\n\n
Unlike arrays, lists are affected by their size. Because finding a node requires walking the list, the more nodes you have to walk through, the more time is needed. This is called linear time complexity<\/em>, or O(n), where n is the number of nodes checked before reaching the target.<\/p>\n\n\n\n
OpenBOR Lists<\/h4>\n\n\n\n
OpenBOR uses a doubly linked list structure when you access an array with a string key. From the script side, it still looks like an array:<\/p>\n\n\n
\nset(my_array, "health", 100);\nset(my_array, "sprite_path", "data\/chars\/player\/icon.png");\n<\/pre><\/div>\n\n\n
Under the hood, OpenBOR creates a doubly linked list of named nodes instead of writing into the indexed storage block. Each named entry lives in the list, and the list keeps a cursor so functions like reset()<\/code>, next()<\/code>, previous()<\/code>, key()<\/code>, and value()<\/code> can walk through the entries.<\/p>\n\n\n\n
To reduce the performance cost of list lookup, OpenBOR\u2019s implementation also adds hash acceleration. The string key is converted into a small numeric hash, and that hash selects one of 256 possible buckets. Instead of checking every named node, OpenBOR only checks the nodes in the matching bucket.<\/p>\n\n\n\n
This is much better than a full list scan. The engine still has to process the string key, find the bucket, and compare entries inside that bucket until it finds the exact key, but in most use cases, the number of string comparisons needed will be minimal.<\/p>\n\n\n\n
The important takeaway is that string-keyed OpenBOR arrays are essentially turbocharged doubly linked lists. They are still not on par with indexed arrays for raw speed, but they are reasonably fast, flexible, readable, and useful for data that does not fit neatly into fixed numeric slots.<\/p>\n\n\n\n
\"\"<\/a>
Simplified illustration of OpenBOR\u2019s string-key access. In actuality, the node values contain pointers to structures that house the payload rather than the payload value itself, but effect is still the same. Hash acceleration gives reasonable performance, and the double linked list provides maximum flexibility.<\/figcaption><\/figure>\n\n\n\n
Why Use an Array?<\/h2>\n\n\n\n
Arrays and lists give you organizational and performance advantages when working with groups of related values. Instead of managing a pile of separate variables, you can keep related data together under one handle and access each value by key or index.<\/p>\n\n\n\n
In the case of indexed arrays, you also get extra speed from hardware acceleration – an important consideration when working in hot paths.<\/p>\n\n\n\n
Example:<\/p>\n\n\n
\n#define PLAYER_DATA_HEALTH 0\n#define PLAYER_DATA_MP     1\n#define PLAYER_DATA_SCORE  2\n\n\/* Define an array with three elements. *\/\nvoid player_data = array(3);\n\n\/* Populate elements. *\/\nset(player_data, PLAYER_DATA_HEALTH, 100);\nset(player_data, PLAYER_DATA_MP, 50);\nset(player_data, PLAYER_DATA_SCORE, 0);\n\n\/* Get values from elements. *\/\nint health = get(player_data, PLAYER_DATA_HEALTH);\nint mp     = get(player_data, PLAYER_DATA_MP);\nint score  = get(player_data, PLAYER_DATA_SCORE);\n<\/pre><\/div>\n\n\n
This gives you one organized structure instead of three unrelated variables. Note use of named constants for indexes. This isn’t required, but it is best practice.<\/p>\n\n\n\n
Arrays are especially useful when you need to iterate or scan a collection of data, and even more so when you need to handle multidimensional structures (like a grid). <\/p>\n\n\n\n
\"Pocket<\/a>
Pocket Dimensional Clash select screen. The grid style character selection and the visible grid on screen are handled by multidimensional arrays arranged into a table of columns (parent array), and rows (child array). The row elements in turn each point to locations in a separate model system that contain the data needed to draw icons and display info.<\/figcaption><\/figure>\n\n\n\n
As a practical example, consider a shadow trail (after-images) script. While active, you’ll want to store n sets of locations along with current sprite in use as the entity moves and animates. Then you play them back to the screen to create a trail of after-images.<\/p>\n\n\n
\n
\"\"<\/a>
Shadow trail after-images<\/figcaption><\/figure>\n<\/div>\n\n\n
In its simplest form, that means at least two functions resident in hot paths. One running on each entity you want shadow trails enabled to record data. Then another in the global update run against each entity present to get the recorded data for drawing after-image sprites on screen.<\/p>\n\n\n\n
Let’s assume you want six shadow trail after-images. You could do something like this (don’t worry if it looks like we’re jumping to the deep end, the following is just a bit of illustration to demonstrate the point):<\/p>\n\n\n
\nvoid shadowtrail_store_bad(void acting_entity) {\n    \n    \/* Guards *\/\n    if(!acting_entity \n        || typeof(acting_entity) != openborconstant("VT_PTR")) {\n        shutdown(1, "\\n\\n ERROR: shadowtrail_store_bad(" + acting_entity + ") - Missing or invalid parameter.\\n");\n    }\n    \n    \/* We'll need elapsed time + sprite duration.*\/\n    float expire_time = openborvariant("elapsed_time") + 100;\n\n    \/* Get entity properties *\/\n\n    void current_sprite = getentityproperty(acting_entity, "sprite");\n    float x_pos =   getentityproperty(acting_entity, "x");\n    float y_pos =   getentityproperty(acting_entity, "y");\n    float z_pos =   getentityproperty(acting_entity, "z");\n    \n    \n    \/* Get ring buffer index, initialize to 0 if necessary *\/\n\n    int key_index = getentityvar(acting_entity, "shadowtrail_key_index");\n\n    if(key_index == NULL()) {\n        key_index = 0;\n    }\n\n    key_index = key_index % TRAIL_COUNT;\n \n    \/* Store sprite and position in entity vars with generated string keys. *\/\n\n    setentityvar(acting_entity, "trail_x_"      + key_index, x_pos);\n    setentityvar(acting_entity, "trail_y_"      + key_index, y_pos);\n    setentityvar(acting_entity, "trail_z_"      + key_index, z_pos);\n    setentityvar(acting_entity, "trail_sprite_" + key_index, current_sprite);\n    setentityvar(acting_entity, "trail_time_"   + key_index, expire_time);\n    \n    \/* Increment the ring buffer index for the next trail frame. *\/\n\n    key_index++;\n    setentityvar(acting_entity, "shadowtrail_key_index", key_index);\n}\n<\/pre><\/div>\n\n\n
Then in a global update, we loop over entities and draw any active shadow trails like this:<\/p>\n\n\n
\nvoid shadowtrail_draw_bad(void acting_entity) {\n    \n    \/* Guards *\/\n    if(!acting_entity \n        || typeof(acting_entity) != openborconstant("VT_PTR")) {\n        shutdown(1, "\\n\\n ERROR: shadowtrail_draw_bad(" + acting_entity + ") - Missing or invalid parameter.\\n");\n    }\n\n    \/* Draw each trail sprite from the ring buffer with appropriate offsets. *\/\n    int i = 0;\n    void trail_sprite = NULL();\n    float trail_x = 0.0;\n    float trail_y = 0.0;\n    float trail_z = 0.0;\n    int expire_time = 0;\n    int sort_id = 0;\n    int elapsed_time = openborvariant("elapsed_time");\n    \n    \/* Scan indexes for valid trail segments *\/\n    for(i = 0; i < TRAIL_COUNT; i++) {        \n\n        \/* \n        * Get the trail sprite for this segment. \n        * Make sure it's a valid pointer before \n        * trying to draw. If it's not valid, this \n        * segment is either uninitialized or cleared, \n        * so we skip it.\n        *\/\n\n        trail_sprite = getentityvar(acting_entity, "trail_sprite_" + i);\n        \n        if(!trail_sprite || typeof(trail_sprite) != openborconstant("VT_PTR")) {\n            continue;\n        }\n\n        \/* \n        * Check time. If expired or not set, clear the trail \n        * segment and skip to next iteration.\n        *\/\n\n        expire_time = getentityvar(acting_entity, "trail_time_" + i);\n\n        if(typeof(expire_time) != openborconstant("VT_INTEGER") \n        || expire_time <= elapsed_time) {\n        \n            setentityvar(acting_entity, "trail_time_" + i, NULL());\n            setentityvar(acting_entity, "trail_sprite_" + i, NULL());\n            setentityvar(acting_entity, "trail_x_" + i, NULL());\n            setentityvar(acting_entity, "trail_y_" + i, NULL());\n            setentityvar(acting_entity, "trail_z_" + i, NULL());\n            continue;\n        }\n        \n        \/*\n        * Retrieve the position and whatever other data \n        * we need for this trail segment.\n        *\/\n\n        trail_x = getentityvar(acting_entity, "trail_x_" + i);\n        trail_y = getentityvar(acting_entity, "trail_y_" + i);\n        trail_z = getentityvar(acting_entity, "trail_z_" + i);\n        \n        \/*\n        * Older trails go further back, all go one step\n        * behind the current entity z to prevent overlap.\n        *\/\n\n        sort_id = i - 1;\n\n        \/*\n        * Draw the trail sprite at its position.\n        *\/\n\n        drawsprite(trail_sprite, trail_x, trail_y, trail_z, sort_id);        \n    }\n}\n<\/pre><\/div>\n\n\n
Doesn’t look too bad, right? It\u2019s simple, straightforward, and works. We assemble some variable names, store data, and then iterate back over them to draw the sprites on screen that make up our shadow trail of afterimages. In actuality however, this common method is an anti-pattern with some severe issues. Chiefly, the live name assembly.<\/p>\n\n\n\n
Every time the functions run, we have to assemble variable names like \"trail_x_\" + i<\/code> and \"trail_sprite_\" + i<\/code> piecemeal, and each one incurs an expensive multi-step process.<\/p>\n\n\n\n
    \n
  1. Convert numeric values into strings.<\/li>\n\n\n\n
  2. Concatenate strings to a single larger string.<\/li>\n\n\n\n
  3. Hash the finished string.<\/li>\n\n\n\n
  4. Use the hash to locate the named variable entry.<\/li>\n<\/ol>\n\n\n\n
    That’s a lot of extra work running in the hot paths.<\/p>\n\n\n\n
    Not only that, but because each variable is assembled separately, the shadow trail drawing function has to constantly check every afterimage slot for every entity whether or not it uses shadow trails, all while performing those expensive string operations to do it. We could add an “active” flag, but that’s just one more bespoke string to deal with. Finally, the example here is quite minimal. Real shadow trails will need a lot more properties for visual effect elements, palettes, etc., each one adding more and more to the complexity and runtime load.<\/p>\n\n\n\n
    The Better Way<\/h3>\n\n\n\n
    Instead of all the extra overhead, why not use functionality designed specifically for these sorts of use cases? Let’s try again with an array. We’ll store one array handle on the entity, then keep all trail data in the array’s elements using a technique called flattening, with named constants to identify the elements (again, we’ll go over all of these methods in detail later, this is just an example):<\/p>\n\n\n
    \n#define SHADOWTRAIL_VARKEY_DATA       "shadowtrail_data"\n#define SHADOW_TRAIL_DURATION        100 \/\/ Duration for each trail segment in centiseconds.\n\n#define SHADOWTRAIL_COUNT             6 \/\/ Number of trail segments to store and draw (ring buffer size).\n\n#define SHADOWTRAIL_DATA_CURSOR       0 \/\/ Ring buffer cursor\/index.\n#define SHADOWTRAIL_DATA_START        1 \/\/ Offset in the data array where trail segment entries begin.\n\n\/*\n* Element offsets from SHADOWTRAIL_DATA_START.\n*\/\n#define SHADOWTRAIL_ENTRY_X          0  \/\/ X position of the stored trail segment.\n#define SHADOWTRAIL_ENTRY_Y          1  \/\/ Y position of the stored trail segment.\n#define SHADOWTRAIL_ENTRY_Z          2  \/\/ Z position of the stored trail segment.\n#define SHADOWTRAIL_ENTRY_SPRITE     3  \/\/ Sprite of the stored trail segment.\n#define SHADOWTRAIL_ENTRY_TIME       4  \/\/ Expiration time of the stored trail segment.\n#define SHADOWTRAIL_ENTRY_SIZE       5  \/\/ Size of each entry in the data array.\n\nvoid shadowtrail_store_good(void acting_entity) {\n    \n    \/* Guards *\/\n    if(!acting_entity \n        || typeof(acting_entity) != openborconstant("VT_PTR")) {\n        shutdown(1, "\\n\\n ERROR: shadowtrail_store_good(" + acting_entity + ") - Missing or invalid parameter.\\n");\n    }\n\n    \/*\n    * Retrieve the trail data array from the entity.\n    * If it doesn't exist yet, initialize it with the \n    * appropriate size and structure, then store it back \n    * in the entity variable.\n    *\/\n    void trail_data = getentityvar(acting_entity, SHADOWTRAIL_VARKEY_DATA);\n\n    if(!trail_data || typeof(trail_data) != openborconstant("VT_PTR")) {\n\n        \/*\n        * No trail data array found for this entity, so we \n        * need to initialize it.\n        *\/\n\n        \/* \n        * Calculate the total size of the trail data array \n        * based on the number of segments and entry size. \n        * Full explanation below in the code comments where \n        * we store the data.\n        *\/\n        int list_size = SHADOWTRAIL_DATA_START + (SHADOWTRAIL_COUNT * SHADOWTRAIL_ENTRY_SIZE);\n\n        \/*\n        * Allocate the trail data array with the calculated \n        * size and store its pointer in the entity variable.\n        *\/\n        trail_data = array(list_size);\n        set(trail_data, SHADOWTRAIL_DATA_CURSOR, 0);\n        setentityvar(acting_entity, SHADOWTRAIL_VARKEY_DATA, trail_data);\n    }\n\n    \/* We'll need elapsed time + duration. *\/\n    int expire_time = openborvariant("elapsed_time") + SHADOW_TRAIL_DURATION;\n\n    \/* Get current sprite and position of the entity. *\/\n    void current_sprite = getentityproperty(acting_entity, "sprite");\n    float x_pos = getentityproperty(acting_entity, "x");\n    float y_pos = getentityproperty(acting_entity, "y");\n    float z_pos = getentityproperty(acting_entity, "z");\n    int entry_index = 0;\n\n    \/* Get ring buffer index, initialize to 0 if necessary. *\/\n    int cursor = get(trail_data, SHADOWTRAIL_DATA_CURSOR);\n\n    if(typeof(cursor) != openborconstant("VT_INTEGER")) {\n        cursor = 0;\n    }\n\n    cursor = cursor % SHADOWTRAIL_COUNT;\n\n    \/* \n    * Flatten the grid data into a singular array\n    * through index offset math.\n    *\/\n    entry_index = SHADOWTRAIL_DATA_START + (cursor * SHADOWTRAIL_ENTRY_SIZE);\n\n    set(trail_data, entry_index + SHADOWTRAIL_ENTRY_X, x_pos);\n    set(trail_data, entry_index + SHADOWTRAIL_ENTRY_Y, y_pos);\n    set(trail_data, entry_index + SHADOWTRAIL_ENTRY_Z, z_pos);\n    set(trail_data, entry_index + SHADOWTRAIL_ENTRY_SPRITE, current_sprite);\n    set(trail_data, entry_index + SHADOWTRAIL_ENTRY_TIME, expire_time); \/\/ Store expiration time\n\n    \/* Increment the cursor for the next trail segment. *\/\n    cursor++;\n    set(trail_data, SHADOWTRAIL_DATA_CURSOR, cursor);\n}\n<\/pre><\/div>\n\n\n
    Then draw with this function.<\/p>\n\n\n
    \nvoid shadowtrail_draw_good(void acting_entity) {\n    \n    \/* Guards *\/\n    if(!acting_entity || typeof(acting_entity) != openborconstant("VT_PTR")) {\n        shutdown(1, "\\n\\n ERROR: shadowtrail_draw_good(" + acting_entity + ") - Missing or invalid parameter.\\n");\n    }\n\n    \/*\n    * Retrieve the trail data array from the entity.\n    * If it doesn't exist or is invalid, we can't draw \n    * any trails, so we just exit.\n    *\/\n    void trail_data = getentityvar(acting_entity, SHADOWTRAIL_VARKEY_DATA);\n\n    if(!trail_data || typeof(trail_data) != openborconstant("VT_PTR")) {\n        return;\n    }\n\n    int i = 0;  \/\/ Main loop index for iterating through trail segments.\n    int j = 0;  \/\/ Inner loop index for clearing expired trail segments when we find them.\n    int entry_index = 0;\n    void trail_sprite = NULL();\n    float trail_x = 0.0;\n    float trail_y = 0.0;\n    float trail_z = 0.0;\n    int sort_id = 0;\n    int expire_time = 0;\n    int elapsed_time = openborvariant("elapsed_time");\n    \n    \/* Scan through all possible trail segments in the ring buffer. *\/\n    for(i = 0; i < SHADOWTRAIL_COUNT; i++) {\n\n        \/* See store function for index calculation. *\/\n        entry_index = SHADOWTRAIL_DATA_START + (i * SHADOWTRAIL_ENTRY_SIZE);\n\n        \/* \n        * Get the trail sprite for this segment. \n        * Make sure it's a valid pointer before \n        * trying to draw. If it's not valid, this \n        * segment is either uninitialized or cleared, \n        * so we skip it.\n        *\/\n       \n        trail_sprite = get(trail_data, entry_index + SHADOWTRAIL_ENTRY_SPRITE);\n\n        if(!trail_sprite || typeof(trail_sprite) != openborconstant("VT_PTR")) {\n            continue;\n        }\n\n        \/* \n        * Check if the trail segment has expired. \n        * If it has, we clear the data for this \n        * segment and skip to next iteration. \n        *\/\n\n        expire_time = get(trail_data, entry_index + SHADOWTRAIL_ENTRY_TIME);\n        \n        if(typeof(expire_time) != openborconstant("VT_INTEGER") \n            || expire_time <= elapsed_time) {\n\n            \/* Clear the trail segment data for this entry. *\/\n            for(j = 0; j < SHADOWTRAIL_ENTRY_SIZE; j++) {\n                set(trail_data, entry_index + j, NULL());\n            }\n\n            continue;\n        }\n\n        \/*\n        * Retrieve the position and whatever other data \n        * we need for this trail segment.\n        *\/\n\n        trail_x = get(trail_data, entry_index + SHADOWTRAIL_ENTRY_X);\n        trail_y = get(trail_data, entry_index + SHADOWTRAIL_ENTRY_Y);\n        trail_z = get(trail_data, entry_index + SHADOWTRAIL_ENTRY_Z);\n\n        \/*\n        * Older trails go further back, all go one step\n        * behind the current entity z to prevent overlap.\n        *\/\n        \n        sort_id = i - 1;\n\n        \/*\n        * Draw the trail sprite at its position.\n        *\/\n\n        drawsprite(trail_sprite, trail_x, trail_y, trail_z, sort_id);        \n    }\n}\n<\/pre><\/div>\n\n\n
    At first glance these functions look a lot more complex, and they do require freeing an array when the entity is removed (more on that later), but that\u2019s only because the code is explicit. This pattern will execute many times faster, consume less memory, and also be simpler to maintain.<\/p>\n\n\n\n
    Why It’s Better<\/strong><\/h4>\n\n\n\n
    Using an array gives us several advantages before we even consider the array’s own performance.<\/p>\n\n\n\n
    To start, we\u2019re polling just one string-keyed entity variable to find the trail data array, and there’s no concatenation at all:<\/p>\n\n\n
    \n#define SHADOWTRAIL_VARKEY_DATA "shadowtrail_data"\n\nvoid trail_data = getentityvar(acting_entity, SHADOWTRAIL_VARKEY_DATA);\n<\/pre><\/div>\n\n\n
    After that, all repeated work happens inside one indexed array using integer offsets. Instead of inventing a new variable name for every trail value, the script calculates where each record begins. Because we are working with integers and not strings, these calculations are already faster by an order of magnitude. Then we are able to minimize that work even more by splitting its logic into smaller parts and only repeating the necessary components to get each element’s index:<\/p>\n\n\n
    \nentry_index = SHADOWTRAIL_DATA_START + (i * SHADOWTRAIL_ENTRY_SIZE);\n\ntrail_sprite = get(trail_data, entry_index + SHADOWTRAIL_ENTRY_SPRITE);\ntrail_x = get(trail_data, entry_index + SHADOWTRAIL_ENTRY_X);\ntrail_y = get(trail_data, entry_index + SHADOWTRAIL_ENTRY_Y);\ntrail_z = get(trail_data, entry_index + SHADOWTRAIL_ENTRY_Z);\n<\/pre><\/div>\n\n\n
    This keeps related data together, avoids repeated string concatenation, avoids scattering values across many entity variables, and gives the engine direct numeric indexes to work with. <\/p>\n\n\n\n
    Now consider the array itself. Since we used indexed keys, OpenBOR can store the data in a traditional C array-like container. So not only have we eliminated extra overhead, we enabled hardware-level acceleration to boot.<\/p>\n\n\n\n
    Lastly, the array pattern makes maintenance and expansion easier. When it’s time to add delays, alpha, scale, palette, or drawmethod data to each trail segment, you add another field constant and increase SHADOWTRAIL_ENTRY_SIZE<\/code>. The layout stays centralized instead of spreading more generated variable names through your code.<\/p>\n\n\n\n
    Walk-through<\/h2>\n\n\n\n
    No matter which type of array you use, or where you use it, there are only four basic things you can do to an array and its individual elements during the array\u2019s lifecycle. <\/p>\n\n\n\n
      \n
    1. Create<\/li>\n\n\n\n
    2. Read<\/li>\n\n\n\n
    3. Update<\/li>\n\n\n\n
    4. Delete<\/li>\n<\/ol>\n\n\n\n
      Anyone with a database background will recognize that immediately as CRUD. That’s it, that’s all. Just those four actions. Everything above and below is just mixing and matching CRUD. Not so scary right? <\/p>\n\n\n\n
      All we really need to do is decide when and how we run those actions. Let’s walk through the steps for each type of array, in (C)reate<\/strong>, (U)pdate<\/strong>, (R)ead<\/strong>, (D)elete<\/strong> order.<\/p>\n\n\n\n
      Indexed<\/h3>\n\n\n\n
      Indexed arrays, or simply arrays, rely on a few core functions: <\/p>\n\n\n\n