Globals - MSUTeam/MSU GitHub Wiki

• isNull
• isEqual
• getMember
• getField
• isIn
• isKindOf
• asWeakTableRef
• regexMatch
• isBBObject
• deepClone
• deepEquals
• getEntityByUID

File path: scripts/config/msu/globals.nut Global functions are situated directly within the ::MSU namespace.

::MSU.isNull( _object )
// _obj is any data type

Return true if _object is null or an instance of the Battle Brothers WeakTableRef class whose table is null. Returns false otherwise.

::MSU.isEqual( _1, _2 )
// _1 and _2 can be any data type

Returns true if _1 and _2 are equal. Properly handles instances of the vanilla WeakTableRef class. If either parameter is an instance of WeakTableRef it will use the table which the instance has a reference to. It is highly recommended to use this function instead of == or != when comparing BB classes as they could be WeakTableRef instances.

::MSU.getMember( _object, _key )
// _object is a bb object or WeakTableRef
// _key is a key in _object

Returns the value of _key in _object, with proper handling for when _object is a WeakTableRef.

::MSU.getField( _object, _key )
// _object is a bb object or WeakTableRef
// _key is a key in _object

Returns the value of _key in _object.m, with proper handling for when _object is a WeakTableRef.

::MSU.isIn( _key, _object, _chain = false )
// _key is any variable, but most likely a string
// _object is a table, array, or class instance (especially an instance of WeakTableRef)
// _chain is a Boolean

Returns true if _key is contained in _object. If _chain is true and _object is a table (or BB class e.g. player) it will look up the chain of inheritance and return if _key is contained in any parent. For instances of WeakTableRef it looks inside the table the instance stores a reference to. For arrays it returns array.find(_key) != null. Other than the extension to arrays, the behavior is otherwise identical to the squirrel in keyword.

The primary use case of this function is when it is unknown whether an object is a BB class table or an instance of WeakTableRef. For example:

// if `_targetEntity` is an instance of `WeakTableRef`
// containing a reference to a BB "player" class
::logInfo("getLevel" in _targetEntity) // prints false
::logInfo("Level" in _targetEntity.m) // prints true
::logInfo("Faces" in _targetEntity.m) // prints false

::logInfo(::MSU.isIn("getLevel", _targetEntity)) // prints true
::logInfo(::MSU.isIn("Level", _targetEntity.m)) // prints true
::logInfo(::MSU.isIn("Faces", _targetEntity.m)) // prints false
::logInfo(::MSU.isIn("Faces", _targetEntity.m, true)) // prints true because "Faces" exists in human.nut which player.nut inherits from

::MSU.isKindOf( _object, _className )
// _object is a bb object or a WeakTableRef
// _className is a string

Returns true if _object is a BB instance of the BB class _className.
Returns false otherwise.

This is superior to both mod_hooks mods_isClass and vanilla isKindOf because it properly handles a WeakTableRef.

::MSU.asWeakTableRef( _object )
// _object is a BB object or a WeakTableRef

Returns a WeakTableRef to _object. If _object is already a WeakTableRef then returns _object.

::MSU.regexMatch( _capture, _string, _group )
// _capture is a regexp().capture(_string) return array
// _string is the _string used to produce _capture
// _group is an integer

Used to simplify getting a specific group from a regex capture with groups. Returns the string from _string corresponding to group _group from _capture. Returns null if it doesn't exist.

::MSU.isBBObject( _object, _allowWeakTableRef = true )
// _object can be any kind of variable
// _allowWeakTableRef is a boolean

Used to check if a variable is a BBObject. Returns a boolean. if _allowWeakTableRef is true, it will call .get() on the variable if it is an instance of ::WeakTableRef.

::MSU.deepClone( _object )
// _object can be any type

Recursively clones _object, iterating over the values in _object if it is an array or table. If it is an instance, clone is called on the object. For all other types the value is passed.

::MSU.deepEquals( _a, _b )
// _a and _b can be any type

Recursively checks the equality of each value in _a and _b and returns true if all the values are equal. Note that for reference types e.g. arrays/tables/instances it checks the equality of their contents, not their reference.

::MSU.getEntityByUID( _uid )
// _uid is an integer

Returns the entity with the MSU generated UID _uid if such an entity exists. Returns null otherwise.