GameMaker Studio 2 Mathematical Scripts

This is collection of general utility and mathematical objects and functions for GameMaker Studio 2 (Version 2.3) in the form of a local asset package. I've written these functions for my own use over the years, and I expect to add more over time.

All source code is available for free at my GitHub page, released under the MIT license. I encourage you to download it, use it in your own projects, and modify the source code as much as you like.

Each script in this package defines a single function. Most functions are standalone and are meant to be taken à la carte, but some of the more mathematically complicated functions depend on other scripts, indicated in a @requires tag. All function names begin with an underscore in order to distinguish them from built-in functions. All object names begin with the obj_ prefix. Some include methods, which are always defined in the object's Create event.

The scripts included in the package are reasonably well-documented within the source code. The following is a brief description of the included functions, divided into rough categories.

Number Theory Functions

A variety of scripts dealing with sequences, functions, and sets, which may have some uses for managing data structures. For example, the various pairing and inverse pairing functions can be used to store pairs of numbers as single numbers in data structures (like stacks and queues) and then recovered.

• _base_to_decimal() -- Converts a number from an array of base-b digits to decimal. The inverse of _decimal_to_base().
• _ceil() -- Generalized ceiling function which accepts a step size argument.
• _decimal_to_base() -- Converts a number from decimal to an array of base-b digits. The inverse of _base_to_decimal().
• _factorial() -- Calculates the factorial (n!) of a nonnegative integer.
• _floor() -- Generalized floor function which accepts a step size argument.
• _frac() -- Generalized fractional part function which accepts a step size argument.
• _integer_pair_to_natural() -- Maps an ordered pair of integers to a unique natural number (by composing _nautral_pair_to_natural() on _integer_to_natural()). This is the inverse of _natural_to_integer_pair().
• _integer_to_natural() -- Maps an integer to a unique natural number using the zig-zagging bijection from (0, 1, -1, 2, -2, ...) to (0, 1, 2, 3, 4, ...). This is the inverse of _natural_to_integer().
• _k_tuples() -- Generates an array of all possible base-b k-tuples, in ascending (or descending) order.
• _natural_to_integer() -- Maps a natural number to a unique integer using the zig-zagging bijection from (0, 1, 2, 3, 4, ...) to (0, 1, -1, 2, -2, ...). This is the inverse of _integer_to_natural().
• _natural_to_integer_pair() --Maps a natural number to a unique ordered pair of integers (by composing _nautral_to_integer() on _natural_to_natural_pair()). This is the inverse of `_integer_pair_to_natural`.
• _natural_to_natural_pair() -- Maps a natural number to a unique ordered pair of natural numbers using the inverse Cantor pairing function. This is the inverse of _natural_pair_to_natural().
• _natural_pair_to_natural() --Maps an ordered pair of natural numbers to a unique natural number using the Cantor pairing function. This is the inverse of _natural_to_natural_pair().
• _round() -- Generalized rounding function which accepts a step size argument.

Array Functions

Common array functions (such as searching and counting).

• _array_count() -- Counts the number of occurrences of a specified value in an array.
• _array_function() -- Applies a given function to every element of a given array, and returns an array of results.
• _array_index() -- Finds the first index at which a specified value occurs in an array (or -1 if not found). An optional argument allows the search to begin from a specified index.
•  _array_max() -- Returns the maximum value (or the index of the maximum value) in an array.
• _array_min() -- Returns the minimum value (or the index of the minimum value) in an array.
• _array_reverse() -- Reverses the order of elements in an array.
• _invert_permutation() -- Generates a permutation array to invert a given permutation array.
• _linspace() -- Generates an array with a specified number of equally-spaced values that cover a specified range.
• _permute() -- Permutes the elements of an array according to a given permutation array.
• _range() -- Generates an array of equally-spaced values over a specified range with a specified step size.

Computational Mathematics Functions

Numerical algorithms for computational mathematics, including things like root finding and interpolation.

• _cubic_spline_coefficients() -- Calculates vectors of polynomial coefficients for the natural cubic spline interpolating a given data set.
• _cubic_spline_evaluate() -- Evaluates a piecewise cubic polynomial at a specific value given a given set of coefficient vectors and intervals.
• _root_bisection() -- Finds the root of a continuous function on a specified interval using the bisection method. This requires that the function change sign over the interval.
• _root_newton() -- Finds the root of a differentiable function using Newton's method. This requires an initial guess and a derivative function.
• _smooth_step() -- A piecewise function that increases smoothly from 0 to 1 over the interval [0, 1].

Linear Algebra Functions

Common linear algebra algorithms for dealing with matrices and vectors. In all functions, vectors are considered to be 1D arrays while matrices are 2D arrays (i.e. arrays of arrays).

• _coordinate_remap() -- Remaps a coordinate from one rectangular region to another.
• _linear_solve() -- Solves a linear system of the form Ax = b (using Gaussian elimination with partial pivoting).
• _matrix_multiply() -- Performs matrix-matrix, matrix-vector, and vector-vector multiplication.
• _matrix_trace() -- Calculates the trace (sum of diagonal elements) of a square matrix.
• _matrix_transpose() -- Transposes a 2D matrix.
• _tridiagonal_solve() -- Solves a tridiagonal system (using the Thomas algorithm).
• _triangular_solve() -- Solves an upper or lower triangular system (using forward or back substitution).
• _unit_vector() -- Defines a unit direction vector between two coordinates.
• _vector_angle() -- Calculates the acute angle between two vectors.
• _vector_distance() -- Calculates the Lp-distance between two vectors.
• _vector_norm() -- Calculates the Lp-norm of a vector.
• _vector_rotate() -- Rotates a 2D vector by a specified angle.
• _vector_scale() -- Scales a vector to maintain its direction while giving it a specified norm.

Random Functions

Functions which involve randomization.

• _random_round() -- Rounds a number either up or down to an integer value with a probability based on its fractional part.
• _random_weighted_index() -- Chooses a random array index with probabilities defined by a given weight array.
• _random_sample() -- Draws a set of random samples from an array, either with or without replacement.

Cellular Automata Functions

Functions for cellular automata (CA) models. Most models are defined using a Wolfram code, an integer index that uniquely defines all possible input/output pairs for a given state space. Wolfram codes are generally indexed to correspond to a descending sequence of k-tuples, which can be generated using the _k_tuples() function from the Number Theory Functions section.

• _ca_elementary() --Evaluates an elementary CA on a 1D array, based on a rule defined by its Wolfram code.
• _ca_wolfram_decode() -- Converts a Wolfram code into an explicit list of ordered output tuples. The inverse of _ca_wolfram_encode().
• _ca_wolfram_encode() -- Generates the Wolfram code for a given complete list of output tuples. The inverse of _ca_wolfram_decode().

Graph Objects and Functions

Objects and functions for representing graphs and networks (as abstract data structures on the "Instances" layer). The graph objects are meant to act as abstract data structures, and so are included in the scripts/graph group alongside the graph functions.

Three main objects, obj_graph, obj_vertex, and obj_edge are defined to represent a graph, its vertices, and its edges, respectively. The main graph object consists mostly of a vertex array and an edge array, but also defines some methods for common graph algorithms (like finding shortest paths). Graphs can technically be defined manually, but it is recommended to instead make use of the included _create_graph() function, which automatically defines all necessary objects from an adjacency list representation and returns the resulting graph object.

It is assumed that all vertices and edges belong to only one graph. Edges are directed, so if you would like for connections to be bidirectional, you must include one edge in each direction.

• _create_graph() -- A function for generating a graph object with accompanying vertex and edge objects from a list of vertex indices and an adjacency list. Optional arguments allow the vertex and edge attributes to be defined.
• obj_graph -- The main graph object. On destruction, it automatically destroys all associated vertices and edges.
  • obj_graph.v -- List of vertex objects.
  • obj_graph.e -- List of edge objects.
  • obj_graph.adjacency_list() -- Returns the adjacency list of the graph, as a list of lists of vertex indices.
  • obj_graph.adjacency_matrix() -- Returns the adjacency matrix of the graph, as a matrix for which element (i,j) indicates the number of edges (or the total weight of edges) from vertex i to vertex j.
  • obj_graph.all_distances() -- Finds the distance from one vertex to every other vertex in the graph (using Dijkstra's algorithm) based on the `cost` attributes of the edges.
  • obj_graph.connected() -- Determines whether the graph is (strongly) connected, or whether a given pair of vertices is (strongly) connected.
  • obj_graph.distance() -- Finds the distance between two vertices (using Dijkstra's algorithm) based on the `cost` attributes of the edges.
  • obj_graph.shortest_path() -- Finds the shortest path between a pair of vertices (using Dijkstra's algorithm) based on the cost attributes of the edges. Returns the cost of the path, the sequence of vertices, and the sequence of edges.
• obj_vertex -- Vertex object.
  • obj_vertex.e_in -- List of incoming edge objects.
  • obj_vertex.e_out -- List of outgoing edge objects.
  • obj_vertex.supply -- Supply value, for potential use in network flows problems.
• obj_edge -- Edge object.
  • obj_edge.tail -- Origin vertex object.
  • obj_edge.head -- Destination vertex object.
  • obj_edge.cost -- Cost value, for use in minimum-cost path calculation.
  • obj_edge.capacity -- Capacity value, for potential use in network flows problems.

File Handling

Functions for handling files, to cover some basic tasks that aren't built into GameMaker Studio.

• _ini_keys() -- Finds all keys in a given section of an INI file.
• _ini_sections() -- Finds all sections in a given INI file.