PS.random ( val )

PS.random() returns a random integer.

The val parameter should be an integer greater than or equal to two (2). Values less than 2 are clamped. Non-integral values are floored.

Return value

PS.random() returns a random integer in the range 1 to val, inclusive.

PS.ERROR is returned if an error occurs.

PS.seed ( val )

PS.seed() seeds the pseudo-random number generator used by PS.random().

The val parameter should be an integer greater than or equal to one (1). Values less than 1 are clamped. Non-integral values are floored.

Return value

PS.seed() returns val, or PS.ERROR if an error occurs.

PS.date ( )

PS.date() returns an object indicating the current local date and time.

Return value

PS.date() returns an object with the following properties:

• .time : integer
• .year : integer
• .month : integer
• .date : integer
• .day : integer
• .hour24 : integer
• .hour : integer
• .minute : integer
• .second : integer
• .millisecond : integer
• .zone : integer
• .am_pm : string
• .monthName : string
• .monthShort : string
• .dayName : string
• .dayShort : string
• .monthStr : string
• .dayStr : string
• .hourStr : string
• .minuteStr : string
• .secondStr : string
• .millsecondStr : string
• .timeStr : string
• .abbrev : string
• .formal : string
• .timestamp : string

The .time property indicates the number of milliseconds elapsed since 01 January 1970.

The .year property indicates the current year.

The .month property indicates the current month (1-12).

The .date property indicates the current day of the month (1-31).

The .day property indicates the current day of the week (0-6, with 0 = Sunday).

The .hour24 property indicates the current hour of the day in 24-hour format (0-23).

The .hour property indicates the current hour of the day in 12-hour format (1-12).

The .minute property indicates the minute of the current hour (0-59).

The .second property indicates the second of the current minute (0-59).

The .millisecond property indicates the millisecond of the current second (0-999).

The .zone property indicates the offset of local time from UTC time in minutes.

The .am_pm property is "AM" or "PM" according to the value of the .hour property.

The .monthName property indicates the full name of the current month with initial caps ("January").

The .monthShort property indicates the 3-letter abbreviated name of the current month in all caps ("JAN").

The .dayName property indicates the full name of the current day of the week with initial caps ("Sunday").

The .dayShort property indicates the 3-letter abbreviated name of the current day of the week in all caps ("SUN").

The .monthStr property indicates the current month of the year, expressed as a 2-character string ("02" for February, "10" for October, etc).

The .dayStr property indicates the current day of the month, expressed as a 2-character string ("08", "21", etc).

The .hourStr property indicates the current hour of the day in 12-hour format, espressed as a 2-character string ("03" for 3 o’clock, "11" for 11 o’clock, etc).

The .minuteStr property indicates the current minute, expressed as a 2-character string ("07", "22", etc).

The .secondStr property indicates the current second, expressed as a 2-character string ("04", "51", etc).

The .millisecondStr property indicates the current millsecond, expressed as a 3-character string ("008", "042", "329", etc).

The .timeStr property indicates the current time of day, including the hour (in 12-hour format), minute, second and millisecond, expressed as a 12-character "HH:MM:SS+mmm" string.

The .abbrev property indicates the local date/time (in 12-hour format) as an abbreviated 31-character string ("MON 12 JUN 2020 02:15:32+033 AM").

The .formal property indicates the local date/time (in 12-hour format) as a non-abbreviated, variable-length string ("Monday 12 June 2020 02:15:32+033 AM").

The .timestamp property indicates the current date/time (in 12-hour format) as a 30-character string containing no spaces ("MON_12_JUN_2020@02:15:32+033AM").

PS.elapsed ( )

PS.elasped() returns the time elapsed since engine initialization.

Return value

PS.elapsed() returns an integer indicating the number of milliseconds elapsed since the Perlenspiel engine was initialized.

PS.makeRGB ( r, g, b )

PS.makeRGB() takes red, green and blue color components and returns the corresponding RGB triplet value.

Each parameter must be an integer in the range of 0-255 inclusive. Values outside this range are clamped. Non-integral values are floored.

Return value

PS.makeRGB() returns an integer in the range 0 to 0xFFFFFF inclusive.

PS.ERROR is returned if an error occurs.

PS.unmakeRGB ( rgb, colors )

PS.unmakeRGB() takes an RGB triplet and returns the corresponding red, green and blue color components.

The rgb parameter should be an RGB triplet in the range 0 to 0xFFFFFF inclusive. Values outside this range are clamped. Non-integral values are floored.

The colors parameter should be a valid reference to either an array or an object.

If colors is an array reference, the first three elements of the array will be populated with integers in the range of 0-255 inclusive, corresponding to the red, green and blue components of rgb:

• array[0] = red : integer
• array[1] = green : integer
• array[2] = blue : integer

Values previously assigned to the first three array elements are lost. Any elements beyond the first three are not changed.

If colors is an object reference, the .rgb property of the object is set to the value of rgb, and the .r, .g and .b properties are populated with integers in the range of 0-255 inclusive, corresponding to the red, green and blue components of rgb:

• .rgb : integer
• .r : integer
• .g : integer
• .b : integer

Any values previously assigned to these properties are lost. Any other properties in the object are not changed.

Return value

PS.unmakeRGB() returns the array or object passed in the colors parameter, modified as explained above.

PS.ERROR is returned if an error occurs.

PS.applyRect ( left, top, width, height, exec, ... )

PS.applyRect() applies a specified function to every bead within a rectangular region of the grid.

The required left, top, width and height parameters specify the zero-based dimensions of a rectangular region inside the grid.

If left is less than zero (0) or PS.DEFAULT, the value zero (0) is used. If left equals or exceeds the grid width, nothing happens.

If top is less than zero (0) or PS.DEFAULT, the value zero (0) is used. If top equals or exceeds the grid height, nothing happens.

If width is less than 1, nothing happens. If (left + width) is greater than the grid width or PS.DEFAULT, the value (grid_width - left) is used.

If height is less than 1, nothing happens. If (top + height) is greater than the grid height or PS.DEFAULT, the value (grid_height - top) is used.

The required exec parameter should be a reference to a JavaScript function that accepts at least two arguments specifying the zero-based x and y coordinates of a bead on the grid, respectively.

Any parameters supplied to PS.applyRect() after the exec parameter are passed as additional arguments to the exec function.

The exec function can return any value. If the function fails, it should return PS.ERROR.

Usage

PS.applyRect() is easily used with any of Perlenspiel's bead commands. Just specify the name of the command for the exec parameter, followed by the same parameters you would normally pass to the command following the x and y parameters.

You can also use PS.applyRect() with bead functions you write yourself. The first two arguments of your function must specify the zero-based x and y position of the bead of the grid, respectively. Any number of additional arguments can be used.

Return value

PS.applyRect() returns the result of applying the exec function to the bead in the last column and row of the specified rectangle.

If top equals or exceeds the grid height, left equals or exceeds the grid width, or either width or height are less than one (1), nothing happens and the value PS.DONE is returned.

PS.ERROR is returned immediately if an error occurs when applying the exec function to any bead.

PS.hex ( value, padding )

PS.hex() converts a number to a hexadecimal string, with optional padding.

The required value parameter can be any number. Non-integral values are floored.

The optional padding parameter should be a integer greater than or equal to one (1) indicating the minimum number of hexadecimal digits desired in the string. Values less than one are clamped. Non-integral values are floored.

If padding is PS.DEFAULT or not supplied, a minimum padding of two (2) is applied.

Return value

PS.hex() returns a string representing the absolute value of value as a hexadecimal number, with a “0x” prefix.

PS.ERROR is returned if an error occurs.

PS.keyRepeat ( repeat, init, delay )

PS.keyRepeat() inspects and changes the auto-repeat behavior of the keyboard.

The optional repeat parameter enables or disables key repeating. If repeat is true, any non-zero number, PS.DEFAULT or not supplied, key repeating is enabled. If repeat is false or zero (0), key repeating is disabled. If repeat is PS.CURRENT, the repeat behavior is not changed.

The optional init parameter specifies the initial time delay before key repeating begins, expressed in 1/60ths of a second. It should be an integer greater than or equal to one (1). Values less than one are clamped. Non-integral values are floored.

If init is PS.DEFAULT or not supplied, the default value (30, or 1/2 second) is used. If init is PS.CURRENT, the initial delay is not changed.

The optional delay parameter specifies the time delay between successive key repeats, expressed in 1/60ths of a second. It should be an integer greater than or equal to one (1). Values less than one are clamped. Non-integral values are floored.

If delay is PS.DEFAULT or not supplied, the default value (6, or 1/10 second) is used. If delay is PS.CURRENT, the delay is not changed.

Usage notes

1. The default values of init and delay are similar to typical OS values, and should not be changed unless a specific effect is needed.

2. Specifying an init value less than the delay value is not recommended.

Return value

PS.keyRepeat() returns an object with the following properties:

• .repeat : boolean
• .init : integer
• .delay : integer

The .repeat property is true if key repeating is enabled, else false.

The .init and .delay properties are integers specifying the initial and successive key repeat delays, respectively, expressed in 1/60ths of a second.

PS.ERROR is returned if an error occurs.