PalpebratingPesl
Customize your server with custom scripts using PESL
Running scripts
PESL scripts must be placed in config/palpebratingpesl/scripts
and must end with the .pesl
extension.
Running the evalpesl <filename> [args...]
command will run the script. filename
must not contain the .pesl
extension.
It is also possible to run a script after a certain event takes place. This can be specified in config/palpebratingpesl/scripts.json
. Currently, three events are supported.
E.g.:
{
// These scripts run just after the server is starting
"initScripts" : [
"example1"
],
// These scripts run just after the server has started
"serverStartedScripts": [
"example2",
"example4",
"example5"
],
// These scripts run after a reload
"reloadScripts": [
"example3"
]
}
Introduction to scripting
Getting Started
Values
PESL has two kinds of values - Literals, which have a fixed value, and, Variables, whose value can change.
Literals
- Strings - These are a set of characters. These can contain any Unicode character. They are enclosed within double-quotes. E.g.:
"This is a String"
- Numbers - These may or may not have a mantissa. E.g.:
100
,100.54
- Boolean - These can have only two possible values -
true
, orfalse
- Null - These do not have any associated value. They are represented by the
null
keyword - Undefined - These do not have any associated value. They are represented by the
undefined
keyword
Variables
Variables are used to store values. PESL uses the let
key to declare variables.
E.g.:
let someVar = "String variable"
let numberVar = 4212
Operators
Operators are special characters that are used to perform operations on values.
These operators return a number
+
- Used to add two numbers. E.g.:let x = 4 + 5
-
- Used to subtract two numbers. E.g.:let x = 5 - 1
*
- Used to multiply two numbers. E.g.:let x = 2 * 2
/
- Used to divide two numbers. E.g.:let x = 26 / 6.5
These operators return a boolean
!
- Used to negate the value of a boolean. This means thattrue
will becomefalse
and vice-versa. E.g.:let x = !false
>
- Used to check if the value on the left is greater than the value on the right. E.g.:let x = 4 > 2
>=
- Used to check if the value on the left is greater than or equal to the value on the right. E.g.:let x = 4 >= 4
>
- Used to check if the value on the left is lesser than the value on the right. E.g.:let x = 2 < 4
>=
- Used to check if the value on the left is lesser than or equal to the value on the right. E.g.:let x = 4 <= 4
==
- Used to check if the value on the left is strictly equal to the value on the right. E.g.:let x = 1 == 1
&&
- Used to check if the boolean on the left and boolean on the right aretrue
. E.g.:let x = true && true
||
- Used to check if the boolean on the left or boolean on the right aretrue
. E.g.:let x = true || false
^
- Used to check if the boolean on the left and boolean on the right are different. E.g.:let x = true ^ false
Identifiers
Identifiers are names given to functions and variables. PESL identifiers are case sensitive.
let x = 4
and let X = 4
are not the same. Identifiers must begin with an alphabet and can contain any number, any alphabet, and the underscore (_
) character.
The convention for naming identifiers is lowerSnakeCase
. This means that the first letter must be lowercase, and the first letter of each word must be uppercase. While the following convention is not a strict requirement, it does make your code easier to read.
Comments
As of now, PESL does not support comments. This will change in the future.
Expressions
Expressions are a combination of values and operators. E.g.: 4 + 5
. Expressions can also contain variables.
E.g.:
let someVar = 45
let anotherVar = someVar * 4
Assignment
Variables can be reassigned as many times as you wish. E.g.:
let someVar = 45
let anotherVar
let boolVar = false
someVar = 0
anotherVar = 1
boolVar = someVar < anotherVar
Functions
Functions are blocks of code that can be executed at any time. Functions are defined using the function
keyword. They can be run by the following syntax - <functionname>(...)
. The ...
represents arguments. Arguments are separated by commas. They are data that is passed to a function. It may not be always necessary to specify arguments.
E.g.:
function functionWithArguments(str) {
println(str)
}
function functionWithoutArguments() {
functionWithArguments("foo")
}
function functionWithTwoArguments(str1, str2) {
println(str1)
println(str2)
}
println
is also a function. It has one argument. It prints out the value of the argument to the console.
Functions are quite useful at times, as they allow reusing of code. The function body does not have any kind of restrictions on what statements should be there. It is also possible to declare one function inside another!
Functions may also be assigned to variables. This is done without specifying the function name.
let someFunc = function(str) {
println(str)
}
someFunc("Test")
Returning
Functions can also return a value. These functions can be used in expressions.
E.g.:
function multiply(a, b) {
return a * b
}
let x = multiply(4, 5) + 1
Objects
In PESL, Objects are a special kind of value that allows accessing more functions, or objects.
E.g.:
let x = Math.noise(4, 5)
In the above example, Math
is an object that allows accessing noise
, a function.
Arrays
Arrays are a special kind of value that allow storing multiple values in a single variable.
Creating arrays is done with [...]
. The brackets can have any number of values in them.
E.g.: let x = [4, 5, 2, 4]
Accessing arrays is also done using square brackets. The brackets must have a positive number in them. Arrays’ indices start from zero. So, the index of the first element of an array is zero, the second element is one, and so on and so forth.
E.g.: y = x[0]
.
It is also possible to change the values inside an array. This is also done using square brackets. The brackets must have a positive number in them. The number must be the index that you wish to modify.
E.g.: x[0] = 10
Another way to access every element of an array is by iterating through it. This is done using the foreach
keyword.
E.g.:
let x = [0, 4, 5, 2]
foreach (num : x) {
println(num)
}
Conditional statements
Conditional statements are blocks of code that only execute when a certain condition is true. These are specified using the if
keyword. E.g.:
let someVar = 4
if (someVar > 1) {
println("someVar is greater than one")
}
In the above example, someVar > 1
returns a boolean (true
, in this case). The println
function will only be run if the boolean is true
.
It is also possible to run code if the condition is not true
. This is done using the else
keyword. E.g.:
let someVar = 4
if (someVar > 1) {
println("someVar is greater than one")
}
else {
println("someVar is lesser than one")
}
if
statements can also be nested inside each other. E.g.:
let someVar = 4
if (someVar > 1) {
println("someVar is greater than one")
if (someVar == 4) {
println("someVar is 4")
}
}
else {
if (someVar < 0) {
println("someVar is negative")
}
else {
println("someVar is positive")
}
println("someVar is lesser than one")
}
Loops
A Loop is a block of code that continues executing until a certain condition is met.
The syntax for a loop is for([variable declaration];[condition];[update statement])
.
variable declaration
is used to declare a variable (often called the loop variable). E.g.: for (let x = 0;;)
condition
specifies the boolean condition. Until this condition is false
, the loop keeps executing. E.g.: for (let x = 0;x < 6;)
update statement
specifies a statement that will run every time the loop finishes executing. This is often used to update the loop variable. E.g.: for (let x = 0;x < 6;x = x + 1)
The loop variable can also be accessed in the loop. E.g.:
for (let x = 0;x < 6;x = x + 1) {
println(x)
}
The above loop will execute six times.
Builtin Objects and Functions
Objects are represented as words written in UpperCamelCase
.
Functions are represented as functionName() - returntype. [description]
Sponge
getServer()
- servergetMaxPlayers()
- numbergetDefaultWorldName()
- stringgetRunningTimeTicks()
- numbergetTicksPerSecond()
- numberhasWhitelist()
- booleansetHasWhitelist(boolean)
- undefinedgetOnlineMode()
- booleangetMotd()
- textshutdown()
- undefinedshutdown(text)
- undefined. The argument is the message that players will receive once disconnectedgetPlayerIdleTimeout()
- numbersetPlayerIdleTimeout(number)
- undefinedgetBroadcastChannel()
- message_channelsend(text)
- undefinedsend(text,string)
- undefined. The second argument is the chat type (ACTION_BAR
,SYSTEM
orCHAT
)
getBoundAddress()
- string
getGame()
getServer()
- server. SeeSponge.getServer()
getGameDirectory()
- stringgetSavesDirectory()
- stringgetPluginManager()
- plugin_manager. SeeSponge.getPluginManager()
getPluginManager()
- plugin_managerisLoaded()
- booleangetPlugins()
- array of plugin_containergetPlugin(string)
- plugin_container. The argument is the plugin idgetId()
- stringgetName()
- stringgetVersion()
- stringgetDescription()
- stringgetUrl()
- stringgetAuthors()
- array of stringgetSource()
- string. Returns the source code url.
getPlatform()
- platformgetApi
- plugin_container. Returns the plugin container of SpongeAPIgetImplementation
- plugin_container. Returns the plugin container of SpongeVanilla/SpongeForgegetMinecraft
- plugin_container. Returns the plugin container of Minecraft.getMinecraftVersion
- string
textOf(any)
- textappend(text)
- text. Appends textcolor(string)
- text. Check this page for a list of valid colors
println(any)
- undefined. Prints the argument to the consoleMath
random
- number. A random number between 0 and 1sqrt(number)
- number. The square root of the numberfloor(number)
- number. The closest whole number that is less than or equal to the numberceil(number)
- number. The closest whole number that is greater than or equal to the numberpow(number,number)
- number. The first number raised to the power of the secondabs(number)
- number. The absolute value of the numbersin(number)
- number. The trigonometric sine of the number (in radians)cos(number)
- number. The trigonometric cosine of the number (in radians)tan(number)
- number. The trigonometric tangent of the number (in radians)min(number,number)
- number. The least of the two numbersmax(number,number)
- number. The greatest of the two numbersany(array of boolean)
- boolean. Whether the array has anytrue
valuesall(array of boolean)
- boolean. Whether the array has onlytrue
valuesnoise(number)
- number. Simplex Noise (no idea what this is)noise(number,number)
- number. Simplex Noise (no idea what this is)
parseNumber(string)
- number. Converts the argument to a numberSystem
time
- number. Time in milliseconds since 01.01.1970formatDate
- string. Converts milliseconds since 01.01.1970 to a human-readable date
typeOf(any)
- stringrange(number)
- array of number. An array of numbers from 0 to the numberrange(number,number)
- array of number. An array of numbers from the first number to the secondSource
getName()
- stringsendMessage(text)
- undefinedsendMessages(text...)
- undefinedgetMessageChannel()
- message_channel. SeeSponge.getServer().getBroadcastChannel()