Test some code using the box above!
BT-JS is designed to be as easy, simple, and quick to use. However, initially getting set up is often the most difficult part of any project. So here are some simple, step-by-step instructions to get BT-JS set up and ready for use.
Download the latest version of BT-JS (
available here).
Place the "bt-js.js" file somewhere in your website's code. You can place the script wherever you want, however, for ease of use, it's best to put it no more than one directory away from the root (e.g. mywebsite/scripts/bt-js.js).
Reference the "bt-js.js" file in the code for any pages which you plan to use BT-JS for. It's best to reference BT-JS before any scripts which reference BT-JS otherwise you may notice some glitches or errors caused by scripts referencing data which hasn't been collected yet. Here is an example of a
basic webpage templatewhich references scripts.
And that's it! You're all set and ready to start using BT-JS in your scripts!
BT-JS functions and variables can be referenced from any javascript which is in (or is referenced in) the same HTML file which references BT-JS.
Still struggling to figure something out? No worries! Feel free to contact me via any of the methods listed here:
Contact BlenderTimerProperly syncing triggers in BT-JS with triggers in your script can be crucial to a clean website experience. Incorrectly ordered event triggers can lead to odd behavior and/or errors. To help prevent this, BT-JS sends a trigger for events which are used in the background.
For example, when the mouse moves, BT-JS collects information about the cursor (such as it's position, speed, etc.). If this information is requested (such as via the function
cursorInfo
) before BT-JS has collected the information, you may notice some slight glitching and lack of alignment with the true position of the cursor. The BT-JS trigger eliminates this issue.
The BT-JS trigger is not a function which you call but instead a function which BT-JS calls every time it triggers. To prevent unnecessary updating and script running, you can chose which BT-JS trigger to listen to.
To use the BT-JS trigger:
Create a function named
btjs
.
Include a parameter for the function. You can name the parameter anything you want, however, it's best to use something such as
or
(for clarity).
If desired, use an
if
statement to only run your code for the specific triggers(s) you want.
Here is an example of how to use the BT-JS function:
btjs
(
trigger) {}
as
string
(required, case sensitive)
The trigger type.
'cursor'
The trigger sent when BT-JS has just collected cursor information (equivalent to event listener
'mousemove'
).
| Function | Description |
|---|---|
clearCanvas | Clears the entire canvas drawing and path data. |
cursorInfo | A compact, multi-function information retrieval function to get information about the cursor such as its position, its speed, etc. |
drawRect | Creates a rectangle in a canvas (with optional border radius). |
extend | Takes a string and returns the same string extended to the specified length. |
isNumber | Checks a string to see if it is a number or not. |
limit | Returns the same number but no greater or less than the specified upper and lower limits. |
limitDown | Returns the same number but no less than the specified limit. |
limitUp | Returns the same number but no greater than the specified limit. |
moveItem | Moves an item in an array to a new position. |
pointOnCircle | Returns an object with the X and Y position of a specific angle on a circle. |
readCookie | Returns the value of the specified cookie. |
randomNumber | Returns a random number from a low and high limit and with a specified number of decimal places. |
removeAfter | Returns the string with everything after the specified character removed. |
removeBefore | Returns the string with everything before the specified character removed. |
round | Rounds a number to a certain number of decimal places. |
selectRandom | Returns a random item from an array/list. |
sizeCanvas | Makes the drawing area of a canvas the size of its element size. |
sumValues | Adds the values of an array and returns the total sum. |
toFullNumber | Converts an exponent number to a full number string. |
translateTime | Converts a time value (in milliseconds) to a human readable time string. |
toNegative | Takes any number and returns its corresponding negative value (e.g. 3 to -3, -3 to -3). |
toPositive | Takes any number and returns its corresponding positive value (e.g. -3 to 3 or 3 to 3). |
toProperCase | Returns the same string converted to Proper Case. |
toYesNo | Returns a boolean as "Yes" or "No" instead of "true" or "false". |
writeCookie | Writes or overwrites a value to a cookie. |
Moves an item in an array to a new position.
.
moveItem
(
indexFrom,
indexTo,
method,
placeholder)
as
integer
(required)
The index of the item you wish to move.
as
integer
(required)
The index which you wish to move the item to.
as
integer
or
string
(optional)
The method to use when moving the item.
0
"move"
Moves the item from
to
.
1
"swap"
Swaps the item from
with the item from
.
2
"overwrite"
Moves the item but overwrites the item at
with the item moved from
. Note that this will cause the returned array to be 1 item shorter than the original array.
0
or
'move'
as
(optional)
If present, leaves this placeholder item where the moved item was moved from. This is only valid for the
'move'
and
'overwrite'
methods. A small trick is to set this placeholder to the item at
to copy/duplicate an item.
array
[
"item1"
,
"item2"
,
"item3"
]
.
moveItem
(
2
,
0
,
'swap'
)
//Returns: ["item3", "item2", "item1"]
Returns a random item from an array.
.
selectRandom
()
original item type
[
"item1"
,
"item2"
,
"item3"
]
.
selectRandom
()
//Returns: "item2"
Adds the values of an array and returns the total sum.
.
sumValues
()
number
[
1
,
2.5
,
10
]
.
sumValues
()
//Returns: 13.5
Converts a boolean which is
true
"Yes"
false
"No"
.
toYesNo
()
string
true
.
toYesNo
()
//Returns: "Yes"
Retrieves information about the cursor.
cursorInfo
(
info,
element)
as
string
or
number
(required, case insensitive)
The information you want to retrieve.
"x"
"px"
"xp"
"pageX"
0
Returns the X position of the cursor relative to the page.
number
"y"
"py"
"yp"
"pageY"
1
Returns the Y position of the cursor relative to the page.
number
"sx"
"scX"
"scrX"
"screenX"
"xs"
"xSc"
"xScr"
"xScreen"
2
Returns the X position of the cursor relative to the screen.
number
"sy"
"scY"
"scrY"
"screenY"
"ys"
"ySc"
"yScr"
"yScreen"
3
Returns the Y position of the cursor relative to the screen.
number
"lx"
"lpx"
"lastX"
"lastPageX"
4
Returns the X position of the cursor relative to the page from the previous frame-step.
number
"ly"
"lpy"
"lastY"
"lastPageY"
5
Returns the Y position of the cursor relative to the page from the previous frame-step.
number
"lsx"
"lScrX"
"lastScrX"
"lastScreenX"
"lxs"
"lXScr"
"lastXScr"
"lastXScreen"
6
Returns the X position of the cursor relative to the screen from the previous frame-step.
number
"lsy"
"lScrY"
"lastScrY"
"lastScreenY"
"lys"
"lYScr"
"lastYScr"
"lastYScreen"
7
Returns the Y position of the cursor relative to the screen from the previous frame-step.
number
"xv"
"xVel"
"xVelocity"
"vx"
"velX"
"velocityX"
8
Returns the X velocity of the cursor (pixels moved since last frame-step). A positive value means the cursor has moved right. A negative value means the cursor has moved left.
number
"yv"
"yVel"
"yVelocity"
"vy"
"velY"
"velocityY"
9
Returns the Y velocity of the cursor (pixels moved since last frame-step). A positive value means the cursor has moved down. A negative value means the cursor has moved up.
number
"xSp"
"xSpe"
"xSpeed"
"spX"
"speX"
"speedX"
10
Returns the X speed of the cursor (pixels moved since last frame-step).
xSpeed
only differs from
xVelocity
in that
xVelocity
will return a negative value if the cursor has moved left, whereas
xSpeed
will always return a positive value.
number
"ySp"
"ySpe"
"ySpeed"
"spY"
"speY"
"speedY"
11
Returns the Y speed of the cursor (pixels moved since last frame-step).
ySpeed
only differs from
yVelocity
in that
yVelocity
will return a negative value if the cursor has moved up, whereas
ySpeed
will always return a positive value.
number
"eo"
"eleOver"
"elementOver"
"over"
"element"
"target"
12
Returns the element the cursor is positioned/hovering over.
object
"xe"
"xEle"
"xElement"
"ex"
"eleX"
"elementX"
13
Returns the X position of the cursor relative to the element specified in the
parameter. If no element is specified, the function will get the X position relative to the element which the cursor is currently positioned/hovering over (
elementOver
).
number
"ye"
"yEle"
"yElement"
"ey"
"eleY"
"elementY"
14
Returns the Y position of the cursor relative to the element specified in the
parameter. If no element is specified, the function will get the Y position relative to the element which the cursor is currently positioned/hovering over (
elementOver
).
number
"lt"
"lastT"
"lTrigger"
"lastTrigger"
15
Returns the last time the cursor information was updated.
number
(
date)
as
object
(optional)
The element you want to find the cursor position relative to.
cursor
.
elementOver
cursorInfo
(
'ex'
,
document
.
getElementById
(
'myDiv'
)
)
//Returns: 23
Returns the value of the specified cookie.
readCookie
(
name)
cookie value type
as
string
(required)
The name of the cookie.
readCookie
(
"cookiename"
)
//Returns: The value of the cookie
Writes or overwrites a value to a cookie.
writeCookie
(
name,
value,
lifetime)
as
string
(required)
The name of the cookie.
as
string
(required)
The value to write to the cookie.
as
number
(required)
The number of days till the cookie expires.
writeCookie
(
"cookiename"
,
"cookievalue"
,
1
)
//Returns: Creates a cookie
Returns the same number but no greater or less than the specified upper and lower limits.
.
limit
(
lowerLimit,
upperLimit)
number
as
number
(optional)
If the number is below this number, return this number.
0
as
number
(optional)
If the number is above this number, return this number.
1
(
123
)
.
limit
(
0
,
100
)
//Returns: 100
Returns the same number but no less than the specified limit.
.
limitDown
(
limit)
number
as
number
(optional)
If the number is below this number, return this number.
0
(
-32
)
.
limitDown
(
0
)
//Returns: 0
Returns the same number but no greater than the specified limit.
.
limitUp
(
limit)
number
as
number
(optional)
If the number is above this number, return this number.
0
(
23
)
.
limitUp
(
10
)
//Returns: 10
Returns a random number between the
low
and
high
values (including the
low
and
high
values).
randomNumber
(
low,
high,
decimalPlaces,
returnAsString)
number
(default) or
string
(optional)
as
number
(required)
The lowest random number allowed.
as
number
(required)
The highest random number allowed.
as
number
(optional)
The number of decimal places (Max: 100).
0
as
boolean
(optional)
Will return the number as a
string
if
true
(only necessary if you want to preserve more than javascript's default limit of 17 decimal places).
false
randomNumber
(
0
,
10
,
2
)
//Returns: 4.39
Rounds a number to a specified number of decimal places.
.
round
(
decimalPlaces)
number
as
number
or
string
(optional)
The number of decimal places (Max: 100, however, note that javascript will not return more than 17 decimal places for a number).
Using
"smart"
will cut all decimal places if the number is over 1000, will keep no more than 5 decimal places for numbers 0.1-10, and will leave up to 5 numbers after the last zero for numbers under 0.1.
0
(
3.1415926
)
.
round
(
3
)
//Returns: 3.141
Converts an exponent number to a full number string (e.g. 1e6 to 1000000).
.
toFullNumber
()
string
(
123e-8
)
.
toFullNumber
()
//Returns: 0.00000123
Converts a time value (in milliseconds) to a human readable time string.
.
translateTime
(
format)
string
as
string
(optional)
The time string format to return.
%
unit
length
%
%
yr
%
The year value of the time.
%
mo
%
The month value of the time (based on 12 full months in a 365 day year, or about 30.4 days).
%
dy
%
The day value of the time.
%
hr
%
The hour value of the time.
%
min
%
The minute value of the time.
%
sec
%
The second value of the time (can use
%sec%.%ms3%
to get seconds with 3 decimal places).
%
ms
%
The millisecond value of the time.
"%yr2%-%mo2%-%dy2% %hr2%:%min2%:%sec2%.%ms3%"
(
65123
).
translateTime
(
"%min%:%sec2%.%ms3%"
)
//Returns: 1:05.123
Takes any number and returns its corresponding negative value (e.g. 3 returns as -3, -3 returns as -3, 123.45 returns as -123.45, etc.).
.
toNegative
()
number
(
3.141
).
toNegative
()
//Returns: -3.141
Takes any number and returns its corresponding positive value (e.g. -3 returns as 3, 3 returns as 3, -123.45 returns as 123.45, etc.).
.
toPositive
()
number
(
-255
).
toPositive
()
//Returns: 255
Clears/removes the entire canvas drawing and path data.
clearCanvas
(
canvasContext2D
)
clearCanvas
(
ctx
)
//Clears the canvas.
Creates a rectangle in a canvas (with optional border radius). Note that you must use the usual
fill
or
stroke
functions to make the rectangle visible.
drawRect
(
canvasContext2D,
x,
y,
width,
height,
borderRadius)
as
object
(required, canvas context 2d)
The 2d context of the canvas.
as
number
(required)
The X position of the rectangle (top left).
as
number
(required)
The Y position of the rectangle (top left).
as
number
(required)
The width of the rectangle.
as
number
(required)
The height of the rectangle.
as
number
(optional)
The radius of the border roundness.
0
drawRect
(
ctx
,
10
,
10
,
150
,
100
,
5
)
//Creates a rectangle with an X of 10px, a Y of 10px, a width of 150px, a height of 100px, and a border radius of 5px.
Returns an object with the X and Y position of a specific angle on a circle.
pointOnCircle
(
radius,
angle,
x,
y)
as
number
or
string
(required)
The radius of the circle (as a
number
) or the width and height of the circle (as a
string
, e.g.
"100x100"
).
as
number
(required)
The angle (degrees) to return the point for.
as
number
(optional)
The X position of the center of the circle.
0
as
number
(optional)
The Y position of the center of the circle.
0
pointOnCircle
(
50
,
-45
)
.
x
//Returns the X position of a point along a -45° angle on the circle.
Returns an object array with the X and Y position of points equally spaced along a circle.
pointsOnCircle
(
count,
radius,
angle,
x,
y)
as
number
(required)
The number of points along the circle (max: 1,000,000).
as
number
or
string
(required)
The radius of the circle (as a
number
) or the width and height of the circle (as a
string
, e.g.
"100x100"
).
as
number
(required)
The angle (degrees) with which to offset the points.
as
number
(optional)
The X position of the center of the circle.
0
as
number
(optional)
The Y position of the center of the circle.
0
pointsOnCircle
(
12
,
50
,
15
)
//Returns an object array with 12 points along the circle offset by 15 degrees.
Makes the drawing area of a canvas the size of its
canvas
element (i.e. eliminates stretching on the canvas).
sizeCanvas
(
canvas,
widthBias,
heightBias)
as
object
(required, canvas DOM element)
The canvas to size.
as
number
(optional)
Offset the detected width less (e.g. -10) or more (e.g. 10).
0
as
number
(optional)
Offset the detected height less (e.g. -10) or more (e.g. 10).
0
sizeCanvas
(
canvas
)
//Makes the canvas painting size the size of the canvas element.
Takes a string and returns the same string extended to the specified length.
.
extend
(
length,
fillChar,
appendToBeginning)
string
as
number
(required)
The length to extend to (max: 1,000,000). If greater than 0, will include the length of the string and make the string a fixed length (e.g.
"123"
extended to
4
will return
"123."
). If less than 0, will extend from the ending point of the string (e.g.
"123"
extended to
-4
will return
"123...."
).
as
string
(optional)
The character to fill extended space with.
" "
as
boolean
(optional)
Extend from the beginning of the string instead of the end.
false
"1"
.
extend
(
3
,
"0"
,
true
)
//Returns: "001"
Checks a string to see if it is a number or not.
.
isNumber
()
boolean
"-1.234"
.
isNumber
()
//Returns: true
Returns the string with everything after the specified character removed.
.
removeAfter
(
breakChar,
offset,
last,
returnEmptyIfNotFound)
string
as
string
(required)
All text after this character will be removed (the character itself will not be removed).
as
number
(optional)
Offset the point at which all succeeding text is removed.
0
as
boolean
(optional)
If
true
, removes all text after the last index of the break character (default removes after the first index).
false
as
boolean
(optional)
If
true
, returns an empty string
""
if the provided string does not contain the break character (default returns the original string).
false
"Example #123#0"
.
removeAfter
(
"#"
,
-1
,
true
)
//Returns: "Example #123"
Returns the string with everything before the specified character removed.
.
removeBefore
(
breakChar,
offset,
last,
returnEmptyIfNotFound)
string
as
string
(required)
All text before this character will be removed (the character itself will not be removed).
as
number
(optional)
Offset the point at which all preceding text is removed.
0
as
boolean
(optional)
If
true
, removes all text before the last index of the break character (default removes before the first index).
false
as
boolean
(optional)
If
true
, returns an empty string
""
if the provided string does not contain the break character (default returns the original string).
false
"#123 Example"
.
removeBefore
(
" "
,
1
)
//Returns: "Example"
Returns the string converted to Proper Case (first letter capitalized) either for each sentence, each word, or just the first character of the string.
.
toProperCase
(
mode)
string
as
string
or
number
(required, case insensitive)
The mode of the function.
"s"
"s"
"sentence"
"sentences"
0
Capitalize the first letter of every sentence (separated by ".", "!", or "?").
"w"
"word"
"words"
1
Capitalize the first letter of every word (separated by spaces, " ").
"f"
"first"
"firstLetter"
2
Only capitalize the first character of the provided string.
"this is an example"
.
toProperCase
(
'word'
)
//Returns: "This Is An Example"
Contains information about the cursor (also available via
cursorInfo
).
object
x
as
number
The X position of the cursor relative to the page.
y
as
number
The Y position of the cursor relative to the page.
xScreen
as
number
The X position of the cursor relative to the screen.
yScreen
as
number
The Y position of the cursor relative to the screen.
lastX
as
number
The last X position of the cursor relative to the page.
lastY
as
number
The last Y position of the cursor relative to the page.
lastScreenX
as
number
The last X position of the cursor relative to the screen.
lastScreenY
as
number
The last Y position of the cursor relative to the screen.
xVelocity
as
number
The X velocity of the cursor (in pixels moved since last update). A positive value means the cursor was moving right. A negative value means the cursor was moving left.
yVelocity
as
number
The Y velocity of the cursor (in pixels moved since last update). A positive value means the cursor was moving down. A negative value means the cursor was moving up.
xSpeed
as
number
The X speed of the cursor (in pixels moved since last update). Differs from velocity in that it will always return a positive value.
ySpeed
as
number
The Y speed of the cursor (in pixels moved since last update). Differs from velocity in that it will always return a positive value.
eleOver
as
object
The element the cursor is over.
lastTrigger
as
number
(
date)
The last time information was gathered about the cursor (the last update/frame step).
cursor
.
x
//Returns: 123
The author of this version of BT-JS.
string
btjsAuthor
//Returns: "Daniel Roberts (BlenderTimer)"
The date this version of BT-JS was last updated.
string
btjsLastUpdated
//Returns: "January 1, 2030"
The license this version of BT-JS is provided under.
string
btjsLicense
//Returns: "BT-LU"
The link to the license this version of BT-JS is provided under.
string
btjsLicenseLink
//Returns: "https://blendertimer.com/license/bt-lu"
The version of BT-JS.
string
btjsVersion
//Returns: "1.2.3"