Core

Core

The Core module of FAST is what all other modules build on top of.

Features

• Data Types
• Data Structures
• Events
• Parser
• Functions
• System

Data Types

FAST contains a large number of helpful data types, including wrappers for the built-in data structures to make them easier to work with and interfaces to build new structures from.

• Array
• String
• Data Structures
• Pair
• Surface
• Timer
• Vec2

Array

See also

• ArrayString
• ArrayNumber
• ArrayList

The Array wrapper provides an expanded interface to interact with arrays.

// use an existing array
myArray = new Array([ 10, 20, 40 ]);
// create a new array with the given dimensions
myArray = new Array( 10 );

• sort() - An interface to provide sort functionality for arrays.
• size() - Returns the size of the array.
• swap( a, b ) - Swaps element a and b in the array.
• unique() - Returns an array containing all unique entries in the array.
• concat( a ) - Returns an array containing this array concantated with array a.
• difference( a ) - Returns an array containing this array subtracted by array a.
• union( a ) - Returns an array containing all unique entries when concantated with array a.
• contains( a ) - Returns the first position in the array that contains a, or -1 if it doesn't exist.
• set( a, b ) - Sets index a in the array to b, if it exists in the array.
• get( a ) - Returns index a in the array, or undefined if it doesn't exist.
• toArray() - Returns the array.
• toString( a ) - Returns the array as a string with a as the divider.

ArrayString

Provides an array wrapper with an expanded interface to interact with arrays full of strings. Implements Array.

• sort( ascending ) - Uses quicksort algorithm to alphabetically sort-in-place the array from A-Z when ascending is true, or Z-A when false.

ArrayNumber

Provides an array wrapper with an expanded interface to interact with arrays full of numbers. Implements Array.

• sort( ascending ) - Uses quicksort algorithm to numerically sort-in-place the array in ascending order when ascending is true, or descending when false.
• sum() - Returns the sum of all values in the array.
• average() - Returns the average of all values in the array.
• lowest() - Returns the lowest number in the array.
• highest() - Returns the highest number in the array.

ArrayList

Provides an array wrapper with an expanded interface to interact with arrays like they are lists. Implements Array.

• insert( a, b ) - Inserts a at position b, if it is within array boundaries.
• remove( a ) - Removes index a.
• add( a ) - Adds a to the end of the array, resizing it if necessary. Parameters
• aggressiveness - Default: 1.33. When a resize is triggered, the array will be expand its size by this amount to account for future growth. Values <= 1 will result in the array growing by 1.

String( string )

The String wrapper provides an expanded interface to interact with strings such as formatting.

myString = new String( "Hello World!" );

• formatter( a ) - An overwrittable interface that can be used to format the string when set() is called.
• set( a ) - Sets the string to a as returned from formatter().
• draw( x, y, font, color ) - Draws the string at x, y with the given font and color.
• draw_ext( x, y, font, color, halign, valign ) - Draws the string at x, y with the given font, color and alignments.
• width( a ) - Returns the width of the string in font a.
• height( a ) - Returns the height of the string in font a.
• toArray() - Returns the string as a character array.
• toString() - Returns the string.

StringNumber( string, format )

Implements String.

StringTime( string, decimals, format )

Formats the string as a time with the given number of decimals and format. Implements String.

• decimals - The number of decimals to use.
• format - ex: "$S seconds" ** $H will be converted into the number of hours ** $M will be converted into the number of minutes, sans hours if provided ** $S will be converted into the number of seconds, sans hours and minutes if provided.

Pair( a, b )

A simple garbage-collected, two-value structure. Sets the initial values to a and b.

myPair = ( "Hello", "World!" );

• equals( a, b ) - Returns if the structure a, b values match a, b.
• equals( Pair ) - Returns if the provided Pair matches this one.
• a - the a value.
• b - the b value.

Surface( w, h )

The Surface wrapper provides an expanded interface for dealing with surfaces. They can be set to redraw periodically, or only on request. A surface will always redraw if it is flushed from VRAM.

if ( surface.update() ) {
  surface.set();
    draw_text( 10, 10, "Hello World!" );
  surface.reset();
}
surface.draw( 0, 0 );

• create() - Recreates the surface.
• free() - Frees the surface.
• set() - Sets the surface as the current draw target.
• reset() - Pops the surface if it is the current draw target.
• draw( x, y ) - Draws the surface at x, y.
• update( force ) - Returns true if the surface should be redrawn, and will recreate the surface if it doesn't exist.

Timer( *format, *decimal_places )

The Timer provides the difference between two times in your program. It can be used to get the raw time or, if drawn, as a formatted string. If format and decimal_places are defined, they will override the default "$S" and 1 respectively.

var _timer = new Timer();

show_debug_message( _timer );

• reset() - Resets the timer.
• elapsed() - Returns how much time has elapsed since the timer was last reset().
• toString() - Returns a StringTime formatted string with the time elapsed.

Vec2( x, y )

A garbage-collected, two-dimensional vector structure.

myVec = new Vec2( 2, 5 );

• set( x, y ) - Sets the x and y values of this vector.
• add( Vec2 ) - Adds Vec2 to this one.
• subtract( Vec2 ) - Subtracts Vec2 from this one.
• Multiply( Vec2 ) - Multplies this vectory by Vec2.
• Divide( Vec2 ) - Divides this vector by Vec2.
• dot( Vec2 ) - Returns the dot product of this vector and Vec2.
• toArray() - Returns this vector as an array.
• toString() - Returns this vector as an array as a string.

Data Structures

• DsChain
• DsLinkedList
• DsWalkable
• DsList
• DsTree
• DsMap
• DsQueue
• DsStack
• DsTable

DsChain

A linked-list style interface to build garbage-collected data structures.

• clear() - Clears the data structure.
• empty() - Returns if the data structure is empty.
• size() - Returns the size of the data structure.
• toArray() - Returns the data structure as an array.
• toString() - Returns the data structure as an array as a string.

DsLinkedList( values... )

A garbage-collected, linear-traversable data structure. Adds the values as provided. Implements DsChain.

• clear() - Clears all entries.
• empty() - Returns true if the list is empty.
• first() - Returns the first link in the list.
• size() - Returns the number of links in the list.
• add( a ) - Adds a new link with value a to the end of the list.
• remove( a ) - Removes link a from the list.
• find( a, b ) - Returns the first link that contains value a. If b is specified, starts search there instead of the first link.
• has_next( a ) - Returns if there are further entries after link a.
• next( a ) - Returns the next link after link a. If the end of the list has been reached, will return the first link.
• toArray() - Returns the links in the list as an array.
• toString() - Returns the links in the list as an array converted to a string.

DsWalkable( values... )

A garbage-collected, linear-traversable data structure with state memory. Adds the values as provided. Implements DsChain.

• clear() - Clears all entries.
• empty() - Returns true if the list is empty.
• size() - Returns the number of entries.
• add() - Adds a new entry to the end of the list.
• remove() - Removes the first matching entry.
• start( *at ) - Returns processing to the start of the list. Will start at index *at, if provided.
• first() - Returns the first entry.
• has_next() - Returns if there are further entries.
• next() - Returns the next entry. If the end has been reached, will return to, and return, the first entry.
• toArray() - Returns the entries in the linked list as an array.
• toString() - Returns the linked list as an array converted to a string.

DsList( values... )

A wrapper for the built-in ds_list data structure. Adds the values as provided. Must be destroyed with destroy() to prevent memory leak.

• add( a... ) - Adds the given entries.
• insert( a, b ) - Inserts a at index b.
• remove_value( a ) - Seeks and deletes the first value that matches a.
• remove_index( a ) - Removes index a from the list, if it exists.
• size() - Returns the size of the list.
• empty() - Returns if the list is empty.
• sort( ascending ) - Sorts the list, in ascending order if true.
• swap( a, b ) - Swaps indexes a and b.
• find_value( a ) - Returns the index of the first value that matches a, or -1 if none.
• find_index( a ) - Returns the value found at index a, or undefined if it doesn't exist.
• destroy() - Destroys the internal ds_list.
• toString() - Returns the list as a comma-separated string.

DsTree

A walkable branching data structure with support for custom data types, symbolic links and deep copying. Must be destroyed with destroy() to prevent memory leak.

• seek( a ) - Returns the branch at a.
• lock( a ) - Sets a to be read-only.
• unlock( a ) - Sets a to be writable.
• size( branches ) - Returns the size of the branch, including sub-branches if branches is true.
• get( a, b ) - Returns the value at a, or b if it does not exist.
• set( a, b, c ) - Sets the value at a to b, if c is provided will enforce that data type.
• copy( a ) - Returns a copy of this branch, including sub-branches, or copies this branch, including sub-branches, to branch a if supplied.
• remove( a ) - Removes the branch at a.
• destroy() - Destroys this branch and all sub-branches, excluding symbolic links.
• toString() - Returns this branch as a string, used for debug purposes.

DsMap

A wrapper for the built-in ds_map data structure. Must be destroyed with destroy() to prevent memory leak.

• add( a, b ) - Adds key a with value b, will not replace a if it already exists.
• replace( a, b ) - Replaces key a with value b, will create key a if it does not exist.
• remove( a ) - Removes key a if it exists.
• empty() - Returns if the map is empty.
• size() - Returns the number of entries in the map.
• find( a, b ) - Returns the value at key a if it exists, and undefined if it does not. If b is provided, will return b if the key does not exist instead.
• first() - Returns the first entry in the map.
• next( a ) - Returns the next key after key a in the map.
• read( a ) - Reads a and converts it into entries in the map.
• toString() - Returns the map as a string which can be read with read()

DsQueue( values... )

A garbage-collected queue, operates on a first-in-first-out basis. Enqueues the values as provided. Implements DsChain.

• enqueue( a... ) - Adds the entries into the queue in order given.
• enqueue_at_head() - Adds the entries into the head of the queue in the order given.
• dequeue() - Removes the entry at the head of the queue and returns it.
• head() - Returns the entry at the head of the queue.
• tail() - Returns the entry at the rear of the queue.
• clear() - Clears the queue.
• empty() - Returns if the queue is empty.
• size() - Returns the number of entries in the queue.
• toArray() - Returns the queue as an array.
• toString() - Returns the queue as an array as a string.

DsStack( values... )

A garbage-collected stack, operates on a first-in-last-out basis. Pushes the values to the stack as provided. Implements DsChain.

• push( a... ) - Pushes the entries onto the stack in the order given.
• pop() - Removes the entry on the top of the stack and returns it.
• top() - Returns the entry on the top of the stack.
• clear() - Clears the stack.
• empty() - Returns if the stack is empty.
• size() - Returns the size of the stack.
• toArray() - Returns the stack as an array.
• toString() - Returns the stack as an array as a string.

DsTable

A data structure that behaves as a map and a list. Must be destroyed with destroy() to prevent memory leak.

• add( a, b ) - Adds key a with value b to the table.
• empty() - Returns if the table is empty.
• size() - Returns the number of entries in the table.
• find_value_by_key( a, b ) - Returns the value at key a, or undefined. If b is provided, will instead return b if the key does not exist.
• find_value_by_index( a, b ) - Returns the value at index a, or undefined. If b is provided, will instead return b if the index does not exist.
• find_index_by_value( a ) - Returns the first index that contains value a, or -1 if it doesn't exist.
• replace_by_key( a, b ) - Replaces the value at key a with b. Key a will be created if it does not exist.
• replace_by_index( a, b ) - Replaces the value at index a with b, if it exists.
• first_key() - Returns the first key in the table.
• next_key( a ) - Returns the key following key a, or undefined if it does not exist.
• destroy() - Destroys the data structures in the table.
• toArray() - Returns the key value pairs as nested arrays.
• toString() - Retursn the table as key value pairs as nested arrays as a string.

Events

The FAST event system allows for configurable timing events without relying on spawning objects. They can be set with a delay, and discard themselves as needed. The following event would be run once, thirty frames later, during the step event, and print Hello World! to the Output.

event = new EventOnce( FAST.STEP, 30, self, function() {
  show_debug_message( "Hello World!" );
});

Events can be created for the following times:

• FAST.CREATE - Will be run when FAST is created. This event is only run once when the program starts.
• FAST.GAME_END - Will be run during the Game End event. This event is only run once when the program ends.
• FAST.ROOM_START - Will be run during the room start event.
• FAST.ROOM_END - Will be run during the room end event.
• FAST.STEP - Will run during the step event.
• FAST.STEP_BEGIN - Will run during the begin step event.
• FAST.STEP_END - Will run during the end step event.

Event( event, frames, parameters, function )

Creates a new event that will be run every number of frames until discard() is called on it.

• discard() - Discards this event.
• toString() - Returns this event as a string, used for debugging.

EventOnce( event, frames, parameters, function )

Creates a new event that will be run after frames has passed, and then be discarded.

• discard() - Discards this event.
• toString() - Returns this event as a string, used for debugging.

Parser

The FAST parser is used to read and format strings. It can perform formatting using the StringFormatter interface, or break them into chunks using the Parser interface.

Parser( string )

Takes the provided string and breaks it into chunks that can be read out similar to a file.

var _parser = new Parser( "Hello World!" );

while ( _parser.has_next() ) {
  show_debug_message( _parser.next() );
  
}

• parse( a ) - Replaces the currently read string with a.
• clear() - Clears the string being parsed.
• reset() - Resets processing to the start of the current string.
• has_next() - Returns true if the current string has not been fully read.
• next() - Returns the next piece of the current string.
• next_line() - Returns the rest of the current string.
• toArray() - Returns the current string processed as an array.
• toString() - Returns the current string.

StringFormatter( format, *functions )

The StringFormatter interface is a powerful formatting tool that can be used alongside the parser to assist with reading complex, instructional strings. It works by providing a format, which is a comma-separated list of rules, and using them to edit strings provided. However, the formatter can also be provided a structure containing the functions which make up the rules which can be called. The FAST database uses it to remove comments, strip white space, and rearrange code into an easier to parse format, while FAST Scripts utlilze the StringFormatter to swap tabs for spaces. The StringFormatter must have destroy() called on it or it will cause a memory leak.

StringFormatter Rules

Rules utilize the structure of "&:rule" where & is a character, and rule is the action that is taken on that character. While rules can be rewritten as needed, by default the StringFormatter provides these common rules:

• strip - Removes this character from the string.
• push - Inserts a \n after this character, continuing on a new line.
• pull - Inserts a \n before this character, pushing it to a new line.
• ignore - Toggles the ignore flag, which ignores all rules until another ignore character is found. For example, ":ignore would cause anything between quotations to be ignored.

var _formatter = new StringFormatter( " :strip,\t:strip" );

var _string = _formatter.format( "  Hello   World!" );

StringFormatter Methods

rules( a ) - Reads a and converts it into new rules. format( a ) - Formats a with the current rules and returns it. destroy() - Cleans up internal data structures. Must be called before being garbage collected, or will cause a memory leak!

Functions

Lastly, FAST includes general purpose functions to fill in some of the missing features in GML.

• Arrays
• File
• Include
• Integer
• String

Array Functions

• array_concat( a... ) - Returns a concantated array build from the provided arrays.
• array_contains( a, b ) - Returns the index of array a that contains b, or -1 if it isn't found.
• array_difference( a, b... ) - Returns array a with b subtracted from it.
• array_unique( a ) - Returns an array containing the unique entries in a.
• array_union( a... ) - Returns an array containing all the unique entires of the provided arrays.
• array_sort( a, start, end, ascending, pivot, compare ) - See internal documentation, provides a general-purpose quicksort algorithm for sort-in-place operations on arrays.
• array_to_string( a, b ) - Returns the contents of array separated by b as a string.

File Functions

• file_get_directory( a, b ) - Returns a DsQueue of all files in directory a. If b is true, includes all files in sub-directories as well.

Include Functions

• include( object ) - Runs the current event from object.

Integer Functions

• integer_wrap( value, a, b ) - Returns value wrapped between a and b.

String Functions

• string_con( a... ) - Returns a concantated string containing a...
• string_explode( a, b, trim ) - Returns an array of string broken up by b. If trim is true, whitespace will be removed from each entry.
• string_explode_reverse( a, b, trim ) - Returns an array of string broken up by b in reverse order. If trim is true, whitespace will be removed from each entry.
• string_find_first( chars, string, start ) - Returns the position of the first character in chars found in string, or 0 if none are found. If start is provided, the search will begin at the following character.
• string_justify( a, b, align, character ) - Returns a with white space added to confirm to a character width of b and an alignment of align (fa_left, fa_center, fa_right). If character is supplied, that will be used instead of " ".
• string_trim( a ) - Returns a with the preceeding and following whitespace removed.
• string_to_real( a ) - Converts a to a number, or 0 if it can not be converted. Supports 0x hexadecimal and 0.0 formats.