Skip to content

Float Arrays

Jump to bottom
Alexedishi edited this page Jul 29, 2026 · 3 revisions

Floatarray Utilities Documentation

Overview

Floatarrays are a custom data type implemented through scripted variables, enabling efficient indexed storage similar to float arrays in traditional programming languages.

  • Array name macro: $NAME$
  • Variable prefix: com_fa_ (short for floatarray)
  • Optimized with reduced nesting depth using a pair-based hierarchy

Floatarrays allow you to store values at indexed positions, access them quickly, iterate efficiently through all elements, and clear them when no longer needed. They behave like classic arrays: you can store any value at any index, and values may appear multiple times at different indices.

Large arrays (512 or more entries) may load slowly in the Script Explorer’s Script Variables tab due to the high number of generated variables — avoid opening this tab in scopes where very large arrays are stored.

Script docs

These are following effects and triggers available to use for float arrays:

Below are the helper effects that allow you to create, read, write, iterate, and clear floatarrays. All effects and triggers use the $NAME$ macro parameter to refer to the array. Many effects also use $SIZE$ to select the array size.

  • NAME can be any string, but should be unique
  • SIZE can be any power of 2 from 8 to 512 (larger powers can be generated using the provided python script)

Effects

Triggers

Effect: com_floatarray_initialize

Creates variables com_fa_$NAME$_0 to com_fa_$NAME$_{N-1} initialized to 0 in the current scope.

com_floatarray_initialize = {
    NAME = ...
    SIZE = N
}

Effect: com_floatarray_get

Values in the array can be retrieved in two ways, both return the value in the variable com_fa_return

  • Returns: var:com_fa_return (value at index)

Random-access reads are very fast.

For index by generated value:b

  • Requires: var:com_fa_index (0 to N-1); non-integers return the index of their floor, or the first index for any negative value
com_floatarray_get = {
    NAME = ...
    SIZE = N
}

For specified index:

  • Requires: INDEX as a raw positive integer.
    NAME = ...
    INDEX = N
}

Effect: com_floatarray_set

Values in the array can be set in two ways, both set the value using the variable com_fa_value

  • Requires: var:com_fa_value (value to be set)

Setting a value at a specific index is also very fast.

For index by generated value:

  • Requires: var:com_fa_index (0 to N-1), var:com_fa_value 
com_floatarray_set = {
    NAME = ...
    SIZE = N
}

For specified index:

  • Requires: INDEX as a raw positive integer.
    NAME = ...
    INDEX = N
}

Effect: com_floatarray_set_index

Sets the value of var:com_fa_index to VALUE com_floatarray_set_index = { VALUE = ... }

Effect: com_floatarray_set_value

Sets the value of var:com_fa_value to VALUE com_floatarray_set_value = { VALUE = ... }

Effect: com_floatarray_foreach

  • Sets: var:com_fa_index and var:com_fa_value when iterating

  • BODY is a fully scripted effect, such as "your_scripted_effect = yes" or "add_treasury = var:com_fa_value"

  • The BODY effect is called once per iteration over the array

  • In each iteration:

    • var:com_fa_index is set to the current index of the iteration
    • var:com_fa_value contains the current element at that index (the value retrieved from the array)
    • You can modify var:com_fa_value inside the effect, and the updated value will be stored back in the array at the same index

For iterating over an entire array, foreach is best practice and highly performant. If you plan to iterate many very large arrays frequently, consider performing this work in a monthly or yearly pulse.

com_floatarray_foreach = {
    NAME = ...
    SIZE = N
}

Effect: com_floatarray_clear

Deletes all variables belonging to the array.

com_floatarray_clear = {
    NAME = ...
    SIZE = N
}

Triger: com_floatarray_check_size

Compares the size of the named array against the given value

  • NAME Name of the array
  • OP Comparison operation, e.g. > <=, etc.
  • VALUE Size to compare
com_floatarray_check_size = {
    NAME = ...
    OP = <
    VALUE = N
}

Complete Usage Example

com_test_floatarray = {
    # 1. Initialize array
    com_floatarray_initialize = { NAME = mydata SIZE = 128 }
    
    # 2. Fill array with foreach
    com_floatarray_foreach = {
        NAME = mydata
        BODY = "body_fill = yes"
        SIZE = 128
    }
    
    # 3. Get value from index 5
    com_floatarray_set_index = { VALUE = 5 }
    com_floatarray_get = { NAME = mydata SIZE = 188 }
    # var:returned now contains 5
    
    # 4. Set value at index 5
    com_floatarray_set_index = { VALUE = 5 }
    com_floatarray_set_value = { VALUE = 42 }
    com_floatarray_set = { NAME = mydata SIZE = 188 }
    
    # 5. Initialize sum variable
    set_variable = { name = sum value = 0 }
    
    # 6. Sum all values with foreach
    com_floatarray_foreach = {
        NAME = mydata
        SIZE = 128
        BODY = "body_sum = yes"
    }
    
    # 7. Clear array when done
    com_floatarray_clear = { NAME = mydata SIZE = 128 }
}

# Body effect for foreach - executed for each element
body_fill = {
    set_variable = { name = com_fa_value value = var:com_fa_index }
}

body_sum = {
    change_variable = { name = sum add = var:com_fa_value }
}

File Locations

All generated floatarray scripted effects are defined in: \common\scripted_effects\com_floatarray.txt Static wrapper and utility effects are defined in: \common\scripted_effects\com_floatarray_utils.txt

Generator Script

The Python script that generates all floatarray helper effects is located at: \script\generate_floatarray.py

Default configuration:

if __name__ == "__main__":
    main(sizes=[8, 16, 32, 64, 128, 256, 512])

You can freely configure custom floatarray sizes:

main(sizes=[8, 16, 1024])

Custom output file:

main(sizes=[8, 16, 32, 64, 4096])

There is no maximum floatarray size, but extremely large arrays may impact performance. When processing many large arrays frequently, consider executing such logic on monthly or yearly pulses.

Clone this wiki locally