An API stands for Application Programming Interface. All game frameworks and game engines have API’s.
An API is what we as programmers use when we want to outsource functionality. You can think of an API as a
restaurant menu.
API format
Depending on the game engine or game framework, an API may differ however they are similar in the way they
are presented to you.
It’s usually setup in the following way:
Class Name
Description of the class
Class properties (variables)
Description of each individual property
Class methods (functions)
Description of each individual method
The Godot API
Godot is a little special when it comes to its API.
With other programming languages you would have to import a class before using it.
However, with Godot GDScript, you don’t need to import a class. All classes are in a sense globally scoped.
With Godot, API classes are wither globally scoped or need to be instantiated onto a variable.
To get immediate access to a classes API properties and methods, all you need to do is use the extends keyword.
extendsNode2D# Now we have access to the Node2D Class API
One thing to note is that if you do not use the extends keyword, your gdscript file will end up extending
from the Resource class by default.
# extends Resource# Now we have access to the Resource Class API
Lastly, I just want to end by saying that Godot Game Engine is an open source project. What this means
is that the game engine makes money either through donations, grants, or volunteers that help fix issues
with the game engine. Due to this, you may find that the API is not updated frequently and/or doesn’t explain something
in much detail. Regardless, I find that the Godot Game Engine does a really good job of laying out the details
of every class provided to you.
Transcript
Hello and welcome to another episode in the Godot basics tutorial series. In this episode we will be taking a general and brief look at API. So what exactly is an API. Well, An API stands for application programming interface.
As a matter of fact all frameworks and game engines have API as it's what we use when we want to outsource certain functionality. Remember game engines help us make games by providing us with features that make our jobs easier.
Now one way I like to think about API is is thinking of a menu at a restaurant. In a restaurant. You have a menu and you can order fish, chicken, pork etc. perhaps even a dessert section. Now when you look at the section you have to read each individual item for example, The dessert section could have a ice cream. It could have cake, donuts you wouldn't know until you first checked the section and then you read each item line by line and as a matter of fact different restaurants have different menus. And that's exactly the analogy I like to use when thinking about API's. Different game engines give you different features and functionalities that give you different menu options and it's up to you to pick whatever they provide.
Sometimes certain game engines aren't feature rich or they're more feature rich in one section versus another. And this menu and programming we call the API documentation. Moving on no matter the game engine, APIs give us tools that are desirable when making a game for example receiving player input. This is a pretty standard feature that all game engines provide. Now how exactly the game engine wants you to implement that is certainly a case by case situation. However no matter what they all handle for example receiving player input along with other functionalities.
Now again I want to reiterate game engine solve the bigger problems we face when making games. And so because of that all game engines have similar API's. So if you know how to make games in one engine you most likely know how to make a game in other engines where at least you know what to search for the other game engines API.
Now the core of an API is that it expects an input and you expect an output. Now whether you have to put an input or whether you receive an output is dependent on the API you are calling but it will tell you in the API documentation. We're gonna take a look at that later.
Now a game engine API has a very basic format no matter what game engine you choose it can easily be dissected such as the following. First you have a class name, then you have descriptions that describe what the class does and how to use it. Sometimes they provide coding examples sometimes they don't. Now obviously classes have properties variables. On top of that you have descriptions for your properties that explain for example what the data type is. And lastly you have methods.
Most of the time you'll be accessing an API as methods. Now the methods have descriptions and these descriptions basically tell you whether that method is expecting an input or if the input is optional and it will tell you if you should expect an output. Basically if you should expect a value to be returned back to you and in the description if the API is good it will tell you what the data type it is expecting of you in the parameters and it will tell you the data type that you should be expecting as a returned value.
We're gonna go ahead and take a better look at this through the Godot API documentation. But before we do that. Let's take a look at how to consume an API. Now this is really dependent on what game engine you're using. Most cases
You will have to import your API classes. However because we are using Godot, Godot handles API's a little differently. For example sometimes our API's are globally accessible through our code. Sometimes we can get that functionality with the extends keyword.
However let's take a look at an example through unity.
So this is a unity API pseudocode.
Basically because we're using C# we are expected to import our classes in a sense.
So as you can see here first we have to import the unity engine before we can do anything with Unity engine or before we can do anything with the unity API we need to import the unity engine. And then on top of that we have to import certain things we have to import the events and we have to import system collections.
And this gives us the ability to consume our classes and our class functions inside a unity C# file. However Godot does something a little different now Godot does something different.
If you're using GDScript so keep that in mind. This only applies to GDScript. If you're using C# you have to do something similar to what you are doing with the unity API in terms of importing what you need.
So in GDScript by default without you even having to do anything. We are in fact using the Godot engine. This is done for you you never have to do this as a matter of fact in GDScript you don't even have an option to for example import The Godot engine it just gives that to you. On top of that when we extend a class a class provided to us by Godot and its API section. Not only do we get access to all the API. For example in this case Node2D but we get all of Node2D inherited classes functions and so in a sense when we import one thing through the extends keyword we can get a lot of things through the inheritance chain.
Now another cool thing about Godot GDScript is by default, Even if you don't use the extended keyword you will be given the reference class as your base class. So that's another cool thing about GDScript we don't even have to use the extended keyword by default rather by omitting the extends keyword. Godot will automatically give us the reference class.
So not only do we have access to all of the APIs of the reference class we have all of the APIs of its inherited classes.
And on top of that in GDScript we can get access to a class API by instancing it. For example if we want the random number generator class we can instance it and through our variable, Now we have access to all of the methods and properties of the random number generator class that we can use in our GDScript file. Now before we look at an example I want to go over something with you. You probably may already know this but Godot is open source and free. This means that the community helps improve not only the code of Godot but the documentation that Godot provides in its website.
So that means that the API sometimes is not up to date. Sometimes it's wrong and sometimes it doesn't explain properly how to use certain classes.
And this isn't the fault of Godot, keep in mind it's free unlike unity that has the resources it has a budget that it can allocate to improving its own API.
As a matter of fact it is too Unity's benefit that they improve and update their documentation API because that's how they get to keep customers. So again Godot API is sometimes not up to date. Sometimes it's wrong and sometimes it doesn't explain itself properly. However we're gonna go through some examples so I can help you understand and break down certain things that Godot has in its documentation API.
So let's go ahead and take a look at that.
OK so I'm here in the Godot engine API documentation and first as you can see here you can see Godot API and we call this a documentation page you can see here docs Godot API and we have our class name in this case it's called random number generator so we are going to look at random number generator first and take a look at this in our documentation we get to see what we're inheriting. So number generator inherits from reference and reference inherits from Object. So just by looking at this one line of code we can see that not only will we have access to the API functions of random number generator we will also have API or rather we will have access to the functionalities that are provided to us by the reference class and the functionalities provided by the object class
And it even gives us a short summary of this class. And this class is generating pseudo random numbers. And here we have a description. You can go ahead and read this on your own time but basically it's telling us that it's Randomly generating numbers using a certain algorithm. It even lets you click on that. You see on top of that we have An example through code. But check this update the code is telling us to one instance the random number generator class into a variable. And 2. It's telling us to use the randomize function.
And so you may be asking yourself why is it asking us to use the randomized function. So we're gonna take a look at that later but first let's See what the Godot documentation API gives us.
So on top of that you can see we have a property and we have a seed. We're gonna discuss this later on top of that.
We have methods and you can see we can see the name of the methods we can see what we have to input inside our methods and we can see what values are returned to us. In this case rand_f range gives us back a float value and the randomize function which accepts no input does not give you an output. It's void and void means it doesn't return a value back. It just does something. So on top of this we have property descriptions and this is important because in Godot you do not have direct access to properties you have to use the setter and getter method.
If you don't know what a setter and getter method is please check my episode on setters and getters in the GDScript fundamental tutorial series. But a quick summary in order to get our value to get our property we have to use the getter method in this case. We have to call that get seed function and to set a seed or rather to change the value of our seed property.
We have to use the setter method set seed function and it's expecting an input. It's expecting a parameter. And on top of that it gives us notes the seed used by a random number generator.
That's pretty cool right now moving on.
We have methods and it comes with descriptions so check this out. We have a rand_f function. It's expecting no input. It's expecting nothing in the parameters. However. It's letting you know that you should expect an output. You should Expect a returned value. And in this case the values float. It even gives us a small description of what we should be expecting in this case it's telling us we should expect A random float between zero point zero and one point zero. And this is pretty cool. However let's go back to the top. Remember the example of the random number
Generator class it told us we need to randomize.
So you may be asking yourself why do we have to randomize. So if we go to the randomize section we can see it gives us a small description and it's telling us it sets up a time base seed to generator. Now let's look at our property the seed property. And it's letting us know that by default our seed value is a constant value as an every time we create a new number generator class we always get this value. Now we're going to discuss randomization in computers in a later episode. But basically if you know how random works with computers you know that if we're given a value the same value all the time we're not really creating random numbers we're getting a sequence of numbers that are gonna be exactly the same every time we use one of the random functions and it even tells us here in the notes
The RNG does not have an avalanche effect it will
Output similar random streams.
Given these similar seeds and so this is bad if you really want random it's bad to have a default value set for you all the time because again you're not really randomizing.
So for example this integer when you call one of the random functions it may give you the same number. For example if we call rand_f range we may get back the number seven all the time. For example if we call this Rand_f value and we get back a float we may possibly get the same value all the time. And that's something we don't want in a random generator. So when we call the randomized function it lets us know that we create a new seed based on the time.
So for example may 31 2020 11:00 p.m. 30 minutes 27 seconds 30 milliseconds we use that number, that date time and we randomize our seed on top of it.
Notice how the API doesn'tt tell us how they do it because when we consume an API we don't care how the game engine does this for example we don't care how it randomizes. It's nice to know that it is time base but still we don't really care.
All we care is that one it randomizes and two it does not expect a parameter and we should not expect back a value. That's all we care. And as a matter of fact APIs are going to explain in small detail because it doesn't care enough to tell us how it does something just that it needs to expect something from you in the parameter and whether or not you should expect something back from it.
Now moving on let's look at the Timer class. Now notice how we have the named timer and we inherit from the node and the node inherits from objects. So we get the API functionality of node an object on top of timer and it gives us a quick description a countdown timer now look at the description it's very small. Tells us it counts down at a specified interval and emits a signal when it reaches zero. Now if you are new and you look at this you see that it comes with properties, comes with signals, enumeration.
It comes with property descriptions. Comes with function descriptions. And it's almost like a random number generator. So you may think to yourself. Well maybe. Even though it has no code it may look something like this.
Or we call the class and then we call its method and that's a good first step. However you'll notice quickly that when you do that your timer class doesn't work and
that's the sort of problem I wanted to point out to you with the Godot engine API documentation. Sometimes even though it's absolutely correct and the properties and the methods doesn't really tell us how to use it you would have to learn that and as a matter of fact I teach you about signals in the GDScript fundamental tutorial series and one thing I taught with signals is that in order to use a signal you have to be in a permanent node you have to be A script inside a node that's Inside a scene.
And so unless you knew how signals work you would most likely be confused on how to use the timer class. And so this is a tip if you see signals that means the class not only has to be an instance object it has to be an instance object that is added into your scene. If you see signals in the Godot API, It most likely means That you need to add this class Into the scene. We're going to take a look at the
Timer class In another
Episode. However there is one more API I want to show you now. This is the last API and it's the OS, short for operating system it even tells you hearing the short description. And it lets us know it inherits from Object. And if you know how objects work they stay in memory.
Unless you manually free them now it comes with a description.
We can skip that and it comes with properties. Now before we move on I want to summarize the problem we faced with the timer and that was it didn't really properly explain to us that we needed to add this Timer class Onto the scene
And we're gonna find a similar problem when reading the operating system class. So it comes with properties we can skip that and it comes with methods. Now if you try to do. What we did in the random number generator. You would be correct in thinking you should do this. However when you actually do this, You're not going to get the expected behavior. And that's because when you're using GDScript, The Operating System Class is actually a global Class. It's an accessible global class.
When you're node or rather when your script is attached to an object inside a scene we will look at this in detail at a later episode. However through the documentation we would have no clue. And basically the Operating System class is a singleton. However the Godot docs doesn't let us know this. And so as a beginner you most likely would try something such as our random number generator and this is the problem that I wanted to point out. And it's not really a problem. It's not a huge problem. Through trial and error
You will figure this out for yourself but you can see that the Godot API documentation isn't good at explaining certain things. For example you would actually have to look at a different part of the Godot API documentation to find out that the OS class is globally accessible and can be used by any script file that's attached to the Node. But no matter what, It still behaves the same it's just we don't have to make a class instance we can just call this directly OS dot notation and either the getter and setter functions of our properties or we can call the methods directly.
And so this is where I think that some beginners have problems is that they don't know how to read the Godot API documentation and that's OK because remember GDscrip. Is an abstracted language and it is a domain specific language so you just have to wrap your head around that fact that GDScript is a special type of language and you will get this through experience and exposure. The more you use something the more you will understand how it works. As a matter of fact you should be playing around with it and that's what I recommend you do.
For example if you want to use the OS API class just create a scene, create one node object attach a script to it and just play around with the properties just see what the behaviour of your game looks like when you for example change the integer value of the currency. See what the behaviour is when you change the value of the exit code. See the behaviour when you call these centre window and that's how you grow as a programmer. And one more thing I want to point out is that different API is explained differently.
Some API documentations are good some API documentations are bad it's not our fault however as programmers we have access to API and that's a good thing because in reality no matter how experienced you are it's impossible to memorize everything. For example I don't Memorize every API that Godot has or unity has since I also program in unity server. I know what to find. I know where to find it. For example if I need to do something with window I'll look at the OS class API and Godot and I'll read the properties and I'll read the methods and I'll see if I can solve my problem.
3 function or property.
So let's look at a problem you may face for example you're about to finish your game and you realize you want your game in full screen.
Well how exactly would you do that. You haven't memorized all the methods of the API. You haven't memorized, As a matter of fact you can't memorize everything. But you do know where to go. What API class you should look at when you want to manipulate windows and that would be the operating system class. So you go to the operating system class and you look at the properties and you look at the methods and you try to find for yourself. Does it provide me a way to solve my problem a full screen and yes provides you two different ways. We'll look at that later. However the easiest way would be through the property or rather one of the properties the OS class provides you.
As you can see here we have a window full screen and by nature its value is set to false by default. So we just go ahead and we get the setter method and we set window for screen and we pass a Boolean value because it's expecting a boolean and we set that to true and wallah. Now we have a full screen window for our game. So again as a beginner this may be too much and don't worry we will go over the ones I think will help you on your game programming journey. However if you are comfortable with programming feel free to look at the Godot API.
Because, As a matter of fact Godot provides about 500 Different API classes so most likely if you have a problem when making a game, Most likely Godot has an API class that can help you solve that problem. Again five hundred API classes, can't memorize them. So it's always a good thing to look. Well that's all I have for you in this episode.
Thank you so much for joining me.
If you have any questions please feel free to leave them in the comments section down below. I look forward to seeing you in the next episode. Have an amazing day.
