The Basics

How to write an NScript Command

Introduction

This page will give you the basics of how you should write an NScript script.

Information about your script

Every NScript must start with the following 3 lines in this order:

command = yourCommandHere
summary = This is an example NScript start
remarks = yourCommandHere

Command tells the interpreter what should be said in the Discord chat to run your command. For example, if your listen character is set to = and your command is called hello, it would be ran with =hello.

Summary is where you can put a summary of what your command does.

Remarks is for any arguments you may have. For example, if your command expects a number and the command was called random, remarks could be random <number>.

Creating variables

Creating variables is easy in NScript. You first need to initialise one, you can do so by using the var command like:

var text
var number
var array

You don't need to give them a data type (like string, integer, list) as NScript will determine this automatically.

Useful notes on creating variables:

• You cannot put spaces in variable names.
• You must initialise them before using them, after that, do not initialise them again.

Setting variables statically

Setting variables is easy in NScript. You can use any variable which has already been initialised. If it hasn't been initialised, you will be warned in the output.

text = "This is some text that we've set!"
number = 20
array = ["First item", "Second item"]

Make sure that for variables where you want to set text, like the text variable above, you need to put quotes around your text.

Useful notes on static variables:

• You can change a static variable dynamically later on in the script.
• These will be set as your script says on every script run.

Setting variables from arguments (dynamically)

You can also set variables dynamically based upon arguments or previous processing that has been run. For example:

var length
length = array.length()
number = random(0,length)
text = array(number)

In the example above, we have set up a new variable called length, and on the following line, set it to the number of items in the array variable array, which will return 2. We then set number to a randomly generated number between 0 and the length of the array variable stored in length, which is 2. Finally, we set the text variable to the item at the position of the randomly generated number. This could be either 1 or 2.

Useful notes on dynamic variables:

• You can use the same variable multiple times without re-creating it. This includes switching data types.
• Dynamic variables are forgotten between command runs, so you cannot reference something from a previous script run, even if it is the same script.

Outputting text & variables

There are currently 3 supported methods of output, these are say, embedsay and dm.

dm text
embedsay text
say text

The dm command works by checking the inputs from the user. If they provided a mention, by @'ing a user in their message which ran the command, it will DM that user the output of the variable, text.

The embedsay command outputs the contents of the variable, text, in to a neat embed, which will contain the name of your bot.

The say command simply outputs the contents of the variable, text.

You can output both statically & dynamically (aka you can just put say "Hello World!" to output Hello World! every time it is ran).

Want to output many things in a single line? Use an array. For example

embedsay ["I have a funny joke: ",myjokevar," I hope it made you laugh!"]

If myjokevar above was What do you call a fish wearing a bowtie? Sofishticated., it would output I have a funny joke: What do you call a fish wearing a bowtie? Sofishticated. I hope it made you laugh! all on a single line.

Useful notes on outputting:

• Do not use multiple say, embedsay or dm in your script if possible. If you try to use these too rapidly, you will run in to Discord rate limiting. Instead, use an array to output things on to the same line.
• Using these can be a good way to debug issues in your script.

Conditional checking

NScript also supports checking using conditional statements (known as if statements). Currently, these cannot be nested, and do not support multiple checks, so you can only check a single thing at a time.

Here is a simple example of how a conditional might work

if {text = "Hello World"}
	say "This world is nice!"
endif

This conditional if statement would check the contents of the text variable. If it equals Hello World, it would run the say command. Otherwise, it will go to the endif and continue running from there.

Useful notes on conditionals:

• The tab / spacing before the say command in the example given, or any of your other commands, does not matter.
• Make sure your check is completely wrapped in the curly brackets {}
• Make sure you specify an endif point, otherwise NScript will consider the entirety of your script to be within the if statement.