Welcome to japascript (funny name, I know), where all kinds of wacky stuff can be done!
You start off by choosing an event type from the left, then clicking the commands from the right. This will place them in the center, where they’ll eventually be ran in sequential order. You are able to select where you want to place these commands by clicking on the lines, the command will be inserted at the line selected. You can then edit the parameters to these commands, making them do what you want. Within each parameter, you are allowed to use ‘expressions’, which can do a lot of things you can’t normally do.
For more information, continue reading this documentation.
To see the same documentation on Google Docs, see
here.
Event types are separated by ‘scope’, the range in which the event can be triggered. There are three types of scopes: global (can be triggered anywhere), room (can be triggered within a room), and block (can be triggered while touching a block). Each has different event types, with global and room sharing many event types.
Global/Room Event Types
-
onTick
- Runs each frame the game is played.
- If multi-run is not true, then it will only run once, akin to onStart/onEnter.
- Please avoid excessive use of this event type as to avoid performance issues.
-
onStart/onEnter
- Exclusive for global/room scope respectively.
- Runs upon starting the level/entering a room.
-
onJump
- Runs whenever the player jumps.
- Wall-jumps count.
-
onDash
- Runs whenever the player starts a dash.
-
onKeyDown
- Runs whenever a key is pressed
- Gives a special variable ‘key’. See the Special Variable list for more details.
-
onKeyUp
- Runs whenever a key is released
- Gives a special variable ‘key’. See the Special Variable list for more details.
Block Event Types
-
onTouch
- Runs whenever something (player or dynamic blocks) is touching the block.
- Gives a special variable cause. See the Special Variable list for more details.
-
onTouchLeft/Right/Top/Bottom
- Run whenever something (player or dynamic blocks) is touching the left/right/top/bottom side of the block.
- Will only work with solid blocks.
- Gives a special variable cause. See the Special Variable list for more details.
Event Options
For each event, there are some options that can influence how they function. Some options are exclusive to events of block scope.
General Options
- multiRun: Allows the event to be ran multiple times.
-
multiRunDelay: The delay between when an event is allowed to run again, in seconds.
- This option is only available if multiRun is true.
Block Scope Exclusive Options
- playerTrigger: If true, allows the player to trigger this event.
- blockTrigger: If true, allows dynamic blocks to trigger this event.
Commands are split into three types: control, variable, and gameplay. Control commands control the flow of commands, variable commands affect the variables in the event, and gameplay commands affect the level and the player.
Each parameter has a variable type after it in square brackets. This is the required variable for this parameter. You are not allowed to input a value that is not the specified type, otherwise, it will give an error.
Note that a “...” before the parameter name indicates that the parameter can have an indefinite amount of inputs. Additional inputs can be added/removed using the buttons labeled “+” and “-”.
Control Commands
-
wait(time[num])
- Halt the script for ‘time’ seconds.
-
if(condition[bool])
- If condition is true, then run following commands, otherwise, skip.
-
elseIf(condition[bool])
- Used in conjunction with if() to create an extra condition.
- If previous conditions have all been false, and the current condition is true, then run following commands, otherwise, skip.
- Will give a INVALID_ELSE_IF_COMMAND error if it is not preceded by a if() command.
- Can technically be placed after an else(), but it is not advised, as it will be treated as if the else() was given a true statement, making elseIf() always skip following commands.
-
else()
- Used in conjunction with if() to create a negative condition.
- If all previous conditions are false, then run following commands, otherwise, skip.
- Will give a INVALID_ELSE_COMMAND error if it is not preceded by a if() command.
-
end()
-
Terminates the latest control command.
- An example of proper usage of if(), elseIf(), and else() follows.
if(condition1)
[commands]
elseIf(condition2)
[commands]
elseIf(condition3)
[commands]
else()
[commands]
end()
- If the command is not successfully matched with a control command, then it’ll give a UNMATCHED_END_COMMAND error.
-
while(condition[bool])
- Repeatedly run following commands while the condition is true.
- Infinite loops are allowed as long as there exists a pause (via a wait()) in the loop.
- Otherwise, excessive commands ran in a single session (maximum 1000) will result in a MAXIMUM_COMMAND_PER_SESSION_REACHED error.
-
for(varName[str], start[num], end[num], step[num])
- Repeatedly run following commands, setting base variable ‘varName’ to ‘start’ initially, and add ‘step’ to varName until it is equal or greater (or lesser, when step is negative) than ‘end’.
- If ‘step’ is 0, then it will give an INVALID_STEP_FOR_FOR error.
-
forEach(array[array], itemName[str], indexName[str][optional])
- Repeatedly run following commands for each item of ‘array’, setting base variable 'itemName' to each item.
- If 'indexName' is filled, then the index of each item will be stored in base variable ‘indexName’.
-
log(text[any BUT obj])
- Adds a message to the console. The message will appear yellow.
- If 'text' is of type [obj], it will give a "CANNOT_LOG_OBJECT" error.
-
err(text[any BUT obj])
- Adds an error to the console. The message will appear red.
- If 'text' is of type [obj], it will give a "CANNOT_ERR_OBJECT" error.
Variable Commands
-
set(object[obj OR blockRef][optional],property[str],value[any])
- Sets ‘object[property]’ to ‘value’.
- Leave 'object' empty to access base variables.
- If you attempt to alter a special variable (which are all read-only), then it’ll give a CANNOT_SET_READ_ONLY_VARIABLE_[propertyName] error.
- If you attempt to alter a read-only property of the player/a block, then it’ll give a CANNOT_SET_READ_ONLY_PLAYER/BLOCK_PROPERTY_[propertyName] error.
- If you attempt to alter an inherited property of an object/array (ie. “constructor”), then you’ll get a CANNOT_SET_INVALID_VARIABLE_[propertyName] error.
- If you attempt to add a property to an object or array, then you will get a CANNOT_ADD_PROPERTY_TO_OBJECT error.
- If you attempt to change a variable’s type, you will get an INVALID_ASSIGNMENT_TYPE error.
- All these error conditions apply to other instances of assignment.
-
toggle(object[obj OR blockRef][optional],property[str])
- Toggles 'object[property]'.
- ‘object[property]’ must be of type [bool], otherwise, it will give a NON_BOOL_IN_TOGGLE error.
- Leave 'object' empty to access base variables.
-
gradient(object[obj OR blockRef][optional],property[str],target[num OR str],t[num],v0[num])
- Gradually set ‘object[property]’ to ‘target’ over ‘t’ seconds starting at a rate of change of ‘v0’.
- If ‘object[property]’ and ‘target’ have different types, it will give a MISMATCHED_TYPES_FOR_GRADIENT error.
- If ‘target’ is not a number or a color string, it will result in an INVALID_TYPE_FOR_GRADIENT error.
-
isColliding(varName[str],objectA[obj],objectB[obj])
- Sets 'varName' as true if 'objectA' and 'objectB' are colliding.
- False if otherwise.
- If given an array of [blockRef], it will select index 0.
- objectA and objectB must be either [block], [blockRef], or the player, otherwise, it’ll give an INVALID_OBJECT_IN_IS_COLLIDING error.
-
math(varName[str],funcName[str],...arguments[num])
- Sets ‘varName’ to the result of calling Math[funcName](...arguments).
- Or the value of Math[funcName] if it is a constant.
- For more information on the Math object in JS, see here.
- If given an invalid ‘funcName’, it will give a INVALID_FUNCTION/CONSTANT_IN_MATH error.
Gameplay Commands
-
moveBlock(blocks[blockRef],x[num],y[num],t[num,xv[num][optional],yv[num][optional])
- Move 'blocks' a distance of ‘x’ and ‘y’ units, in 't' seconds, with an initial velocity of 'xv' and 'yv' units/s.
- Leave xv/yv blank for constant speed.
-
moveBlockTo(blocks[blockRef],x[num],y[num],d[num],t[num],v[num][optional])
- Move the top left corner of 'blocks' towards the coordinates (x,y) a distance of 'd' units, in 't' seconds, with an initial velocity of 'v' units/s towards the target.
- Leave d blank to move directly to (x,y).
- Leave v blank for constant speed.
-
rotateBlock(blocks[blockRef],x[num],y[num],dθ[num],t[num],ω[num][optional])
- Rotate 'blocks' about coordinates (x,y) ‘dθ’ degrees clockwise (negative for counter-clockwise), in 't' seconds, with an initial angular velocity of 'ω' degrees/s.
- Leave ω blank for constant angular speed.
-
scaleBlock(blocks[blockRef],factor[num],x[num],y[num],t[num],v[num][optional])
- Scale 'blocks' by a factor of 'factor' with the focus at coordinates (x,y), in 't' seconds, with an initial scaling rate of 'v' block size/s.
- Leave v blank for constant rate.
-
addBlock(blocks[block], var[str][optional])
- Add 'blocks' to the level.
- If 'var' is filled, then set base variable 'var' to added blocks.
-
removeBlock(blocks[blockRef])
- Removes 'blocks' from the level.
-
killPlayer()
Within all commands, you are allowed to use expressions in their parameters. Expressions allow one to access variables, do basic arithmetics, and a variety of other things.
Variable Types
Each variable has a specific type, and each command also requires specific types as input. Note that you are not allowed to change a variable’s type.
Below is a list of all types.
- [num]: Numbers.
- [bool]: Boolean, as in true or false.
- [str]: String, like letters and stuff. Note that when used as a variable/property name, numbers are also allowed.
- [array]: Array, a list of variables.
- [obj]: Object, a collection of variables identified by a key.
- [block]: Block, a template of a block that does not exist in the level. Can also be an array of [block]. Note: When selecting multiple [block] via the block selector, it gives an array of [block].
- [blockRef]: Block Reference, an existing block. Can also be an array of [blockRef]. Note: When selecting multiple [blockRef] via the block selector, it gives an array of [blockRef].
String Literals
One can write a string into an expression by enclosing a series of symbols with matching quotes, single (‘) or double (“).
Special Variables
All events are given a set of special variable to read and/or manipulate. Some event types can also give additional special variable.
Note that all special variables (but not all their properties) are read-only.
General Special Variables
Note that some properties of certain variables may be omitted due to lack of possible use.
-
player[obj]: The player object.
- x[num]: The player’s x position.
- y[num]: The player’s y position.
- xv[num]: The player’s x velocity.
- yv[num]: The player’s y velocity.
- xa[num]: The player’s x acceleration.
- ya[num]: The player’s y acceleration.
- targetSize[num]: The player’s target size (that the player will eventually grow/shrink to).
- size[num]: The player’s current size.
- isDead[bool][readOnly]: Whether the player’s dead or not.
- g[num]: The player’s gravitational acceleration multiplier.
- xg[bool]: Whether the player’s gravity is horizontal or not.
- maxJump[num]: The player’s maximum jump amount.
- currentJump[num]: The player’s current jump amount.
- canWallJump[bool][readOnly]: Whether the player is able to wall-jump.
-
wallJumpDir[num][readOnly]: The direction of the wall the player can wall-jump off of.
- 0 for left, 1 for right, 2, for above, 3 for below.
- maxDash[num]: The player’s maximum dash amount.
- currentDash[num]: The player’s current dash amount.
- dashTimer[num]: Time left until dash ends in ms.
- Note: When using this to initiate a dash, the dash speed is the player's xv and yv.
- moveSpeed[num]: The player’s move speed multiplier.
- friction[bool]: Whether the player’s affected by friction or not.
- gameSpeed[num]: The game speed multiplier.
- isPlayer[bool][readOnly]: Is true.
- currentRoom[str]: The room the player resides in.
-
switchLocal[obj]: Status of all local switches.
- Is an object of the form: {roomName: array, …}.
- The switch states for each room are accessed via switchLocal[roomName][id].
- Properties are added to the array when the player first toggles the corresponding switch.
-
switchGlobal[array]: Status of all global switches.
- The switch states are accessed via switchGlobal[id].
- Properties are added to the array when the player first toggles the corresponding switch.
- coins[num]: Number of coins the player has.
- jumpOn[bool]: State of jump blocks.
- ran[bool]: Whether the event has ran at least once.
-
source[blockRef]/[str]: What the event is contained in.
- In global scope, the source is undefined.
- In room scope, the source is a [str] of the room name.
- In block scope, the source is a [blockRef] of the containing block.
-
global[obj]: An object shared between every event.
- Does not give a CANNOT_ADD_PROPERTY_TO_OBJECT error when adding properties.
Special Variables Exclusive to Certain Event Types
-
key[str]: The key used to trigger the event.
- Exclusive to the onKeyDown and onKeyUp event type.
-
Is the JS code of the key used.
- Not to be confused with keyCode.
- For a list of all key’s code, check out this site.
-
cause[obj]/[blockRef]: The object that triggered the event.
- Exclusive to onTouch and its directional variants.
- It can either be the player, or a dynamic block.
For block properties, they are as seen in the property edit menu in the level editor and vary with block type. This documentation will not be listing them all out, as they can be seen easily within the editor itself.
Operators
All operators are binary (as in, taking in two values) except for “~” and “!”, which are unary and only take one value (like so: ‘~numValue’, ‘!boolValue’).
Only some operators can take objects and arrays as inputs, and all others do not. They are indicated with [YesObj].
Below is a list of all valid operators in japascript, in order of priority.
-
“-”: Negative operator [Unary]
- Not to be confused with the subtraction operator, which uses the same symbol, but this non-distinction is actually quite intuitive.
- “!”: Boolean NOT operator [Unary][YesObj]
- "**": Exponentiation operator
- "%": Modulo operator
- "*": Multiplication operator
- "/": Division operator
- "+": Addition operator
-
"-": Subtraction operator
- This cannot be used as an unary negative operator. You must use “~” as the unary negative operator.
- ">=": Greater than or equal operator
- "<=": Less than or equal operator
- ">": Greater than operator
- "<": Less than operator
- "==": Equality operator [YesObj]
- "!=": Inequality operator [YesObj]
- "&&": Boolean AND operator [YesObj]
- "||": Boolean OR operator [YesObj]
The order of operators can be overridden with parenthesis “()”. Things within parenthesis will be evaluated first, no matter what.
Accessing Properties
To access properties of an object or array, you can use dot notation or square bracket notation.
To use dot notation, write the name of object/array, then write a dot and the property name, like so: object.property.
To use square bracket notation, write the name of the object/array, then write the property name in square brackets, like so: object["property"].
Square brackets also acts like parenthesis, so it allows one to use an expression in place of a property name.
In fact, "[" and "]" are actually completely equivalent to ".(" and ")" respectively. (Yes this means that you can write stuff like "(1+1]", but why would you do that).
All errors occur in runtime, as in, they’ll only occur as the script is running. During gameplay, if any error occurs, then it will halt the event and have it displayed in the in-game console, in this format:
ERROR_TYPE
at scope source(if applicable) eventType line #
Below is a list of all error types in japascript.
- INVALID_[inputType]_INPUT: Occurs when a command’s input does not match with the required input type.
-
NONEXISTENT_BLOCK_REF: Occurs when a [blockRef] references a block that does not exist
- This usually means that the original reference block has been deleted.
- UNKNOWN_SYMBOL_[symbol]: Occurs when an unrecognized symbol is in the expression.
- UNEXPECTED_VALUE_[value]: Occurs when a value is placed directly after another value.
- UNEXPECTED_OPERATION_[operation]: Occurs when an operation is placed directly after another operation.
- UNEXPECTED_UNARY_OPERATION_[operation]: Occurs when an unary operation is placed directly after a value.
- UNMATCHED_BRACKETS: Occurs when parenthesis “()” or square brackets “[]” does not correctly match.
- [operation]_MISSING_LHS: Occurs when an operation does not have a left-hand side.
- [operation]_MISSING_RHS: Occurs when an operation does not have a right-hand side.
- INVALID_LHS_FOR_[operation]: Occurs when an operator that does not take objects or arrays is given an object or array on the left-hand side.
- INVALID_RHS_FOR_[operation]: Occurs when an operator that does not take objects or arrays is given an object or array on the right-hand side.
- INVALID_STRING: Occurs when the expression contains quotes that do not match any other quotes to for a string.
- UNDEFINED_[VARIABLE/PROPERTY]_[varName]: Occurs when you attempt to access a variable/property that does not exist
- CANNOT_ACCESS_UNALLOWED_[PLAYER/BLOCK]_PROPERTY_[propertyName]: Occurs when you attempt to access a property of the player/a block that not listed in this documentation nor in the block edit menu.
- CANNOT_SET_SPECIAL_VARIABLE_[propertyName]: Occurs when you attempt to alter a special variable.
- CANNOT_SET_READ_ONLY_[PLAYER/BLOCK]_PROPERTY_[propertyName]: Occurs when you attempt to alter a read-only property of the player/a block.
- CANNOT_SET_INVALID_VARIABLE_[propertyName]: Occurs when you attempt to alter an inherited property of an object/array.
- CANNOT_ADD_PROPERTY_TO_OBJECT: Occurs when you attempt to add a property to an object/array.
- INVALID_ASSIGNMENT_TYPE: Occurs when you attempt to change a variable’s type.
- NON_BOOL_IN_TOGGLE: Occurs when a non [bool] is inputted in toggle().
- UNMATCHED_END_COMMAND: Occurs when there exists an end() command that does not match with a control command.
- INVALID_ELSE_COMMAND: Occurs when an else() command is not preceded by a if() command.
- INVALID_ELSE_IF_COMMAND: Occurs when an elseIf() command is not preceded by a if() command.
- INVALID_STEP_FOR_FOR: Occurs when a for() command has a ‘step’ of 0.
- INVALID_OBJECT_IN_IS_COLLIDING: Occurs when isColliding() is given an invalid object (non-player and non-block).
- MISMATCHED_TYPES_FOR_GRADIENT: Occurs when gradient() is given mismatched initial and target types.
- INVALID_TYPE_FOR_GRADIENT: Occurs when gradient() is given an invalid target value.
-
MAXIMUM_COMMAND_PER_SESSION_REACHED: Occurs when commands executed within a single session exceeds 1000.
- This typically indicates an infinite loop.