How to use library functions in MNScript [Hydro's Series Part #3]

Hydro

Civil Gamers Expert
Dec 19, 2020
217
126
71
Hello everyone! Welcome to part 3 of this tutorial series that I'm making. In this chapter, we'll be looking at library functions, what they are and how to use them.

As always, this tutorial series will assume that you are somewhat familiar with Maxnet, and that you have followed along with all previous instalments. Let's begin!

Part 1). What is a library function?

In MNScript, the way that you can interact with the game world through code is provided in the form of libraries. Libraries are composed of functions, classes and events. In this tutorial, we'll be focusing on functions; specifically regarding what they actually are, how you can use them in your own MNScript code why you'll need to use them.

You can think of a library function as a machine in a factory:

  • Each machine has certain inputs that it requires in order to properly perform its job
  • Each machine will perform a specific task using the materials that you give it
  • You don't need to understand every last detail about a machine to operate it; you can use them without really understanding how they work internally
  • Different machines do different things, but all the machines in a single factory are for a single purpose (all of the machines in a Coca-Cola factory will be there to help manufacture new drinks)

Each of the points listed above regarding machines can be applied to library functions in MNScript; and below is a brief image showing the Util.ToNumber library function. In this image, the library function is the black box in the centre, the input is the arrow pointing into the box and the output is the arrow pointing away from the box. In this example, you can see that we give the function the string "312.25" and that it outputs the number 312.25. Please note that the input is surrounded by speech marks and that the output isn't; this is intentional and it's because the input is a string (text) value, whereas the output is a number value that we can treat like an actual number and perform calculations on.

88af6143f0bd5a3d9ade7f4779f9c1d2.png

931dadabf986faf0a3b5e21e98295487.png



Part 2). Why do we need library functions then?

Good question! Library functions enable you to work with things which you haven't created in your script; you use libraries to control turrets, set the text on a TextScreen, read/write text on a terminal's console, create Graphical User Interfaces (GUIs) and so much more. All of the scripts that you'll write will ingest data through a library, and will output data through a library; they are the only mechanism in MNScript that allows you to interact with the game world as well as all MNScript-compatible devices.

Take the following design brief as an example:

"Your client, VBank, has contacted you and has asked you to develop an application for them. They need an application that will allow their staff to easily calculate compound interest so that their bank tellers can provide a more streamlined service. You should design an application that will allow the user to enter three numbers: their starting bank balance, yearly interest rate as well as the number of years that interest needs to be calculated for. This application must allow bank tellers to enter the numbers, and therefore hard-coding values into a program is not an option."

Let's look at this specification, and break down what our program needs to do.

  1. We should prompt the bank teller to enter the starting bank balance
  2. We should then read the starting bank balance into the application
  3. We should then ask the bank teller to enter the account's interest rate, and then read it into the application
  4. To retrieve the last of the data that we need to work with, we should prompt the teller to enter the number of years that we should calculate compound interest for
  5. Apply the formula (starting_balance * (interest_rate ^ years)) to calculate the resulting bank balance (^ = to the power of)
  6. We should inform the bank teller of the final bank balance

In order to complete this task, we'll need to use two libraries:

  • Console - The console library will be used to write prompts out to the user, and to read the text that the user enters
  • Util - The util library will be needed so that we can convert string inputs into numbers so that we can perform maths on the numbers entered



Part 3). How can I use library functions in my own programs?

Let's first implement the solution to the design brief above. Below is the code that you would need to implement the solution.
Code:
// Let the program know that we will need the Console and Util libraries
using Console;
using Util;

// Get the starting bank balance
Console.WriteLine("Please enter the starting bank balance");
string startingBalanceInput = Console.ReadLine();

// Get the account's interest rate
Console.WriteLine("Please enter the account's interest rate");
string interestRateInput = Console.ReadLine();

// Get the number of years
Console.WriteLine("Please enter the number of years to calculate interest over");
string yearsInput = Console.ReadLine();


// Convert the strings provided into numbers that we can use

number startingBalance = Util.ToNumber(startingBalanceInput);
number interestRate = Util.ToNumber(interestRateInput);
number years = Util.ToNumber(yearsInput);

// Calculate the final balance
number finalBalance = startingBalance * ((1 + interestRate) ^ years);

// Tell the user what the final balance is
Console.WriteLine("The final account balance is: "..finalBalance);

36358bda380efd0a3330d474a4dc23b2.png

Please read the code in the spoiler above, once you've read it the key concepts below will make loads more sense.

Importing libraries

Libraries can be imported into an application with the using keyword. This keyword tells the MNScript compiler that you want to use the library specified, and that it should be imported before the program is run. Please refer to the first few lines of the code snippet above, in those lines of code we include the Console as well as the Util libraries. This means that we can then write code that leverages each of them. Please note that you can see all of MNScript's documentation by typing mnscript_documentation into the console. Inside of this menu is a list of all of the libraries that you can use, as well as all of the functions, classes and events which they contain. For the meanwhile, please just stick with the Libraries header in the top-left corner of the menu as that's all we've covered so far in this tutorial series.


Invoking Library functions

Once you have imported a library you want to use, you can "call" the function by typing the following <libraryName>.<functionName>(<input data>);. This may seem very confusing at first, but please refer to the examples below and it should be much clearer
Library NameFunction NameExampleExplanation
ConsoleReadLinestring myText = Console.ReadLine();Reads a line of text entered by the user in the Maxnet terminal, and saves it in the variable myText[/b]
ConsoleWriteLineConsole.WriteLine("Hello World!");Writes the string "Hello World!" to the console
UtilToNumbernumber five = Util.ToNumber("5");Converts the string "5" into a number, and assigns it to the variable called five
EncodingBase64Encodestring encoded = Encoding.Base64Encode("I'm going to turn into base64");Encodes the string provided into base64 (this could be useful for automating hacks)
SystemShutdownSystem.Shutdown();Shuts down the terminal that the code is running on. (Note: You need to use Application.RequestAdminPrivilege(); before you can do this.
PeripheralStartAllVCMinersPeripheral.StartAllVCMiners();Starts all of the VCMiners that are connected to the terminal
[td]
[td]

The table above should be useful as a point of reference when learning how to use libraries. Remember to use the using statement at the top of your file to include the libraries that you want to work with. If you get stuck, reference the example posted above and it should help you get off your feet.


As always, if you have any questions, you're more than welcome to post them below. Alternatively, you can ask your questions in the MNScript channel on our Discord server.