Show:
API

Matter.Common

Defined in: src/core/Common.js:1

The Matter.Common module contains utility functions that are common to all modules.

Methods

Matter.Common.chain

(funcs...)
Function

Takes n functions as arguments and returns a new function that calls them in order. The arguments applied when calling the new function will also be applied to every function passed. The value of this refers to the last value returned in the chain that was not undefined. Therefore if a passed function does not return a value, the previously returned value is maintained. After all passed functions have been called the new function returns the last returned value (if any). If any of the passed functions are a chain, then the chain will be flattened.

Parameters

  • funcs Function multiple

    The functions to chain.

Returns

Function

A new function that calls the passed functions in order.

Matter.Common.chainPathAfter

(base, path, func)
Function

Chains a function to excute after the original function on the given path relative to base. See also docs for Common.chain.

Parameters

  • base Object

    The base object

  • path String

    The path relative to base

  • func Function

    The function to chain after the original

Returns

Function

The chained function that replaced the original

Matter.Common.chainPathBefore

(base, path, func)
Function

Chains a function to excute before the original function on the given path relative to base. See also docs for Common.chain.

Parameters

  • base Object

    The base object

  • path String

    The path relative to base

  • func Function

    The function to chain before the original

Returns

Function

The chained function that replaced the original

Matter.Common.choose

(choices)
Object

Randomly chooses a value from a list with equal probability. The function uses a seeded random generator.

Parameters

Returns

Object

A random choice object from the array

Matter.Common.clamp

(value, min, max)
Number

Returns the given value clamped between a minimum and maximum value.

Parameters

Returns

Number

The value clamped between min and max inclusive

Matter.Common.clone

(obj, deep)
Object

Creates a new clone of the object, if deep is true references will also be cloned.

Parameters

Returns

obj cloned

Matter.Common.colorToNumber

(colorString)
Number

Converts a CSS hex colour string into an integer.

Parameters

Returns

Number

An integer representing the CSS hex string

Matter.Common.deprecated

(obj, name, warning)

Shows a deprecated console warning when the function on the given object is called. The target function will be replaced with a new function that first shows the warning and then calls the original function.

Parameters

  • obj Object

    The object or module

  • name String

    The property name of the function on obj

  • warning String

    The one-time message to show if the function is called

Matter.Common.extend

(obj, deep)
Object

Extends the object in the first argument using the object in the second argument.

Parameters

Returns

obj extended

Matter.Common.get

(obj, path, [begin], [end])
Object

Gets a value from base relative to the path string.

Parameters

  • obj Object

    The base object

  • path String

    The path relative to base, e.g. 'Foo.Bar.baz'

  • [begin] Number optional

    Path slice begin

  • [end] Number optional

    Path slice end

Returns

The object at the given path

Matter.Common.getDecomp

()
Object

Returns the poly-decomp library module provided through Common.setDecomp, otherwise returns the global decomp if set.

Returns

The poly-decomp library module if provided.

Matter.Common.indexOf

(haystack, needle)
Number

A cross browser compatible indexOf implementation.

Parameters

Returns

Number

The position of needle in haystack, otherwise -1.

Matter.Common.info

(objs...)

Shows a console.info message only if the current Common.logLevel allows it. The message will be prefixed with 'matter-js' to make it easily identifiable.

Parameters

  • objs Object multiple

    The objects to log.

Matter.Common.isArray

(obj)
Boolean

Returns true if the object is an array.

Parameters

Returns

Boolean

True if the object is an array, otherwise false

Matter.Common.isElement

(obj)
Boolean

Returns true if the object is a HTMLElement, otherwise false.

Parameters

Returns

Boolean

True if the object is a HTMLElement, otherwise false

Matter.Common.isFunction

(obj)
Boolean

Returns true if the object is a function.

Parameters

Returns

Boolean

True if the object is a function, otherwise false

Matter.Common.isPlainObject

(obj)
Boolean

Returns true if the object is a plain object.

Parameters

Returns

Boolean

True if the object is a plain object, otherwise false

Matter.Common.isString

(obj)
Boolean

Returns true if the object is a string.

Parameters

Returns

Boolean

True if the object is a string, otherwise false

Matter.Common.keys

(obj)
String[]

Returns the list of keys for the given object.

Parameters

Returns

String[]

keys

Matter.Common.log

(objs...)

Shows a console.log message only if the current Common.logLevel allows it. The message will be prefixed with 'matter-js' to make it easily identifiable.

Parameters

  • objs Object multiple

    The objects to log.

Matter.Common.map

(list, func)
Array

A cross browser compatible array map implementation.

Parameters

Returns

Array

Values from list transformed by func.

Matter.Common.nextId

()
Number

Returns the next unique sequential ID.

Returns

Number

Unique sequential ID

Matter.Common.now

()
Number

Returns the current timestamp since the time origin (e.g. from page load). The result is in milliseconds and will use high-resolution timing if available.

Returns

Number

the current timestamp in milliseconds

Matter.Common.random

(min, max)
Number

Returns a random value between a minimum and a maximum value inclusive. The function uses a seeded random generator.

Parameters

Returns

Number

A random number between min and max inclusive

Matter.Common.set

(obj, path, val, [begin], [end])
Object

Sets a value on base relative to the given path string.

Parameters

  • obj Object

    The base object

  • path String

    The path relative to base, e.g. 'Foo.Bar.baz'

  • val Object

    The value to set

  • [begin] Number optional

    Path slice begin

  • [end] Number optional

    Path slice end

Returns

Pass through val for chaining

Matter.Common.setDecomp

(decomp)

Provide the poly-decomp library module to enable concave vertex decomposition support when using Bodies.fromVertices e.g. Common.setDecomp(require('poly-decomp')).

Parameters

Matter.Common.shuffle

(array)
Array

Shuffles the given array in-place. The function uses a seeded random generator.

Parameters

Returns

Array

array shuffled randomly

Matter.Common.sign

(value)
Number

Returns the sign of the given value.

Parameters

Returns

Number

-1 if negative, +1 if 0 or positive

Matter.Common.topologicalSort

(graph)
Array

Takes a directed graph and returns the partially ordered set of vertices in topological order. Circular dependencies are allowed.

Parameters

Returns

Array

Partially ordered set of vertices in topological order.

Matter.Common.values

(obj)
Array

Returns the list of values for the given object.

Parameters

Returns

Array

Array of the objects property values

Matter.Common.warn

(objs...)

Shows a console.warn message only if the current Common.logLevel allows it. The message will be prefixed with 'matter-js' to make it easily identifiable.

Parameters

  • objs Object multiple

    The objects to log.

Matter.Common.warnOnce

(objs...)

Uses Common.warn to log the given message one time only.

Parameters

  • objs Object multiple

    The objects to log.

Properties / Options

The following properties if specified below are for objects created by Matter.Common.create and may be passed to it as options.

Common.logLevel

Number
static

The console logging level to use, where each level includes all levels above and excludes the levels below. The default level is 'debug' which shows all console messages.

Possible level values are:

  • 0 = None
  • 1 = Debug
  • 2 = Info
  • 3 = Warn
  • 4 = Error

Default: 1