Level 1: The Journey Begins

Our import_floors.gd script is a script we will re-use and build on as we move forwards. If you want to be a developer, here’s where you start. If you need to, you can come back and review this section later. It is very common as a developer to refer back to documentation or Google answers to syntax. As your experience as a developer grows, you may know what you want to do, but not remember or know how to do it in whatever language you’re working in. This is why we are providing extensive links for further reading. Don’t feel you have to follow every link before moving on. They will be here when you’re ready for it.

@tool # Needed so it runs in editor.

This line starts with what’s known as an annotation. Annotations are keywords that when they precede a line, block of code, or a whole script, they tell Godot something special. They are in a way, very special, built-in functions. Anything that starts with the at (@) symbol is an annotation. Our annotation says that our script is a special tool script that is meant to be run while we are in the editor. It is used to create plugins, test code without playing the game, (or in our case) to run an import script. The default color for an annotation in the GDScript editor is orange.

The line ends with a comment. Comments are there for human beings. The computer ignores them, unless it is compiling documentation, and then there are rules about which comments it pays attention to and which it ignores. Anything that starts with the pound sign (#) (also called the number sign) is a comment. The default color for comments is grey.

Comments should be used when you want to remember why you did something. If you don’t know if you should comment something, do it. The comment on this line was left just for you so you know the annotation is needed for it to run in the editor (and not a run-time when the game is being played.) Normally, we wouldn’t leave a comment on this line, as it’s self-evident what that annotation does. As you get more experience in coding, you’ll learn comments aren’t usually necessary inside blocks of code. We will use them to help explain things sometimes.

extends EditorScenePostImport

This line starts with the extends keyword. This keyword is in red and it tells the editor what properties this script should inherit. (Inheritance is an Object-Oriented Programming (OOP) concept. We will talk about OOP in more detail in the next step.) Inheriting code means we can leverage what other people have written and don’t have to re-write everything from scratch.

The second part is an object type, also known as a built-in class. It is of type EditorScenePostImport. Object types are always in green. This one is specifically used for import scripts.

func _post_import(scene):

This line declares a function. A function always starts with the keyword “func”. It then has a name, an argument list, and a return value. The first line always ends in a colon ( : ). Our function is called _post_import and it is actually a name that is defined in the EditorScenePostImport class. It is known as a virtual function, and is named so that Godot knows what function to use, but it is left for us to define it.

The fact that our function name starts with an underscore ( _ ) is important. In GDScript underscore is an access modifier, and it means that a function or variable is private. This means that any method outside of this one cannot see this method. In GDScript, we default to everything being public. This results in less errors while learning to program.

Our function takes one argument, which we are calling “scene”. We could call it anything we want, we are declaring a variable here. You will notice we are not declaring a return type anywhere. This is because GDScript allows us to leave that information blank, and it will return whatever we ask it to.

You can think of the arguments to a function as its input, and the return value as its output. In this function, we are taking a scene as input (in this case the model we are importing), modifying it, and then returning that scene modified scene.

iterate(scene)

This is a function call. We use the name of a function and then pass it any arguments it needs. The iterate function actually hasn’t been defined yet. It’s the next thing we will define. Godot knows to search the whole file for function names, even if we haven’t told it about the function yet when we call it. In this case, we are passing it the scene variable, which is the same one from the previous line. We are passing it from one function to the next.

return scene

This line starts with a reserved word, “return”. Reserved words are pink in GDScript. A reserved word cannot be used as a variable name, a function name, or anything else. It is reserved by the language to mean one thing and one thing only. Return means we are done with this function, and we are returning control back to whatever function called us. If there is a value after the word “return”, we are returning that value, along with control. In this case, we are returning our scene, that we just modified by calling iterate(), to the importer.

func iterate(node):

We are declaring our iterate function here. Our scene is being passed in and we are renaming it to the variable “node”. We haven’t changed what’s underneath. Interestingly, every scene is a node, so this will works out fine for us. But using the name “scene” or “node” doesn’t mean it is either of those things. We could pass it “Hello world” and the function would take that variable, and then fail when it tried to perform an operation on it later. We will talk more about how you tell a variable what type it has to be in a later lesson.

if node != null:

This is an “if statement”. It is a conditional statement. We are comparing our “node” variable to something. “!=” is our condition. We are saying here that we are looking for our variable “node” to be not equal to the next thing. That next thing is the keyword null. Null is a special programming language term that means “nothing”. This statement is a way to say, “If this node is a real object and not nothing…” The colon ( : ) indicates that comes next is what we should do if this condition is true.

if node is MeshInstance3D:

We are checking to see if this node is a MeshInstance3D node. Our scene, which we have passed, is not, so this is going to be skipped. However, if it was…

node.create_trimesh_collision()

This just calls another function on the node to create a collision mesh. This is the only line in this entire file that changes anything about our imported scene. This is a built-in function that creates a collision mesh of a type called “trimesh”. It programmatically measures our object, and exactly matches it with a CollisionShape3D. We will be talking a lot more about collisions in the future. For now, just know that it will keep other objects from falling through the floor.

This script is just so that we don’t have to worry about characters, monsters, items, decorations, or anything else from falling through the floor. That’s it. But since it doesn’t get called on the scene itself, read about the next line to see how this works.

for child in node.get_children():

This is a “for loop”, another type of conditional statement. It takes a group of things, and iterates (goes one-by-one) over each one and does the code following on each object in the collection. In this case we are iterating over every child node in our scene. The word “child” in this line is a declaration of the variable child that will be used to hold each node - it does not need to be named “child” for this “for loop” to work.

iterate(child)

This is the magic of the recursive function. A recursive function is one that simply calls itself inside itself, typically on its children. In this case, the children nodes in our scene. Each of them will be evaluated to see if it is a MeshInstance3D and if it is, collision data will be added. Either way, it will also see if any of those nodes have child nodes, and if so, it will call itself again on them - until we’ve hot the bottom of the tree. This recursion will become much more important when we start importing more complex models, like character models.

The iterate() function has no return statement. GDScript is a tab-based language, like python. What that means is it knows where it is in a function by how many tabs were used. When we reach the end of a function in GDScript, if there’s nothing else, there is an implicit return of control. This function doesn’t return anything, because it modifies the object directly that it was given as input. This ability to modify a variable or object that is passed is called passing by reference.