Hi Guys!

I'm writing this guide because when I first got Planetoid Pioneers I was so excited to start coding, but had absolutely no idea how to code in Lua. Even though I had learned different languages before, I had no idea what was going on in the code. Well after hundreds of questions and constantly reading different guides, I'd like to compile that information in a guide for Beginners to Lua.

Even if you already have a good understanding of Lua, this guide will be tailored to things you'll see specifically in Planetoid Pioneers so it's worth a read!

First thing to understand is code runs from top to bottom. Your code will run line by line, going into for loops, changing variables, and ultimately arriving at the end of the script.

When you first open up a script you will see 2 empty "blocks". It will look like this:



It will be in either of these two blocks that you'll write ALL of your code. As labelled in the example, your Code will either run once at the start when the item is spawned in or every single tick after the item is spawned.

A "tick" will happen about every 4milliseconds (Physics engine runs at 210Hz). This means that your code will run many times a second.

The most basic part of lua is Variables. Variables are what hold your information throughout the code. It's the way you have an ammo count in a weapon or how much force to put on an object. Variables have 2 parts: A Name, and a Value.


The naming of your variable is very important. You want to make names that have meaning as well as have the right type.

Meaning

While you are certainly able to type " a = 1 " and know that "a" stands for ammo, it's much more important for you to label it correctly.

A lot of what you'll be dealing with in code is Movable Objects, which we will call MO in our variables.

Some examples:
ammo =
HoverHeight =
GolfBallName =
GolfBallMO =

Doing this will help you quickly call up variables and not get confused when halfway through your code when you find "if a == 5 then"

Type

Here is where things might get a little confusing, but while coding it'll make more sense. The "Type" of a variable will define where in the code the variable can be seen from, otherwise known as scope. It can have one of 3 types:

Local
Self
Global

Here is a quick cheat sheet of what they all mean and how to call them:

A useful visual guide of the scope can be seen here:














Note: nil is the response when the code doesn't know what the value is.



The Value of a variable is where they really shine. The value can be as simple as a number or it can be as complicated as the exact position and orientation of a block. When you give a Variable a value, that variable now becomes that value and can be called up instead. Regardless of what you intend to do to the variable, they will always start off the same with a type, name, and value:


Variables only need to be DECLARED once, but need a starting value. eg.

Variables are very easily called up, and changed. The following are some common things you can do with variables:



This concludes the Variables section. You should have an understanding at this point the Type of variable (local, self. , global), good Naming Structure(not using a or x or i for everything), and know that you can manipulate the value of variables.

Operators and Comparators are very basic even though they may sound a little confusing.




Operators are simple an "Operation" such as addition, subtraction, or multiplication.

In lua code you have the following Operators:

*Note some Operators have no been included for simplicity.

Some code examples:


Keep in mind that when we do operations like "ammo = ammo + 5" the first time we call up ammo (ammo = ) we are saying "This should equal", and the second time we say ammo( = ammo + 5) we are saying "The last known value of ammo" or "However many bullets I have left".


*Better known as Relational Operators, but I like thinking of it comparing.

Comparators means to "Compare" two variables. It's very useful for checking if a certain number has been met or if something is set to true or false.

Comparators will take the first item, and check to see if it equals the second item. If they do it, it returns "true", but if they don't equal then it will return "false".

The most common place you'll find comparators are if statements which we'll cover more in the next section.

The following is a table of usable comparators:


Some code examples:


At the end of this section you should have an understanding of the different type of ways you can change variables, as well as the ways you can check/compare variables.

If statements are VERY easy and incredibly useful. If statements will contain a block of code that will only run when certain requirements have been met. "if" statements will run through the block of code until it reaches the end, at which point it will continue with the next line of code.

Example:

In this example we are using a comparator(double ==, not single =) to check if the power has reached 100, at which point the weapon is ready to fire.


Once your code asks the question "Is power equal to 100" it has two boolean (boolean means either true or false) options. If true, it will run the code til it reaches an "end". If false, then it will ignore all of the code and go straight to the "end" of the if statement.

Visualization:



Keep in mind that Variables have a value to them. Should they already have a true/false value then you don't need to use a comparator. These are sometimes referred to as "flags".

Example:


This specific example you will see at the START of a lot of Update(running every tick) scripts. The item will become "activated" (self.activated = true) when the pioneer picks up the object, and become "deactivated" (self.activated = false) when the pioneer drops it. This makes it so that code you have running inside the if statement WILL NOT RUN until the pioneer picks up the item.

Functions are pieces of pre-written code that you can call up to do various tasks. It's extremely important to have a knowledge of how Functions are called, and what they do. You can find a list of all the pre-made functions by pressing F1 and clicking "Scripting" on the top bar. This will bring up what we call the LuaManDocs (can also be found in your PP folder under Docs > LuaManDocs.html).

In the first section of the docs you'll find all of the different Objects that a function can be called on.

Some examples are:

PS - Particle System
MO - Movable Object
Assembly - The whole collection of MO's in your blueprint.
Scene - The whole scene and parts within it. Example: Camera
Joint - A joint connecting 2 MOs such as a knee or a wheel.


So we know which Object we want to use a function for, but how to we use it?

To use a function you will use a colon " : ". The structure will look like this:

Object:Function

Examples:


Now that we know how you call up a function, we'll discuss how/why you use a function.



Parameters is the information that we give to the functions.


When using anything starting with "Get" we are using the function to "return" something back to use. This will be information that we can store and read, or further use functions to manipulate.