Godot API Basics | Godot Basics Tutorial | Ep 04

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 AP eyes 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 ap eyes 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 ice cream it could have cake doughnuts you wouldn't know until you first check 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 ap is 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 in programming we call the API documentation moving on no matter the game engine api's 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 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 in api's 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 and 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 the DOE Godot handles API is a little differently for example sometimes our API is our globally accessible through our code sometimes we can get that functionality with the extends keyword however let's take a look an example through unity so this is a unity API pseudo code basically because we're using c-sharp 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-sharp file however Godot does something a little different now Godot does something different if you're using GD scripts so keep that in mind this only applies to GD script if you're using c-sharp you have to do something similar to what you are doing with the Unity API in terms of importing what you need so in GD script 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 Gd script 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 in its API section not only do we get access to all the api's for example in this case no 2d but we get all of no 2ds 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 GT script is by default even if you don't use the extends keyword you will be given the reference class as your base class so that's another cool thing about GT script we don't even have to use the extends 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 api's of the reference class we have all of the api's of its inherited classes and on top of that and GT script 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 GED script 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 photo 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 to unities benefit that they improve and update their documentation API because that's how they get to keep customers so again godot's 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 Doc's 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 and you see on top of that we have an example through code but check this up the code is telling us to one instance the random number generator class into a variable and two it's telling us to use the demise function and so you may be asking yourself why is it asking us to use the randomize 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 R and F range gives us back the from the value and the randomized 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 GT script 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 the 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 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 R and 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 to return the value and in this case the value is float maybe 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 basse c2 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 and every time we create a new number generator class we always get this value now we are 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 going to be exactly the same every time we use one of the random functions and it even tells us here in the notes the oranjee does not have an avalanche effect it will output similar random streams given the 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 random f range we may get back the number seven all the time for example if we call this R and 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 randomize function it lets us know that we create a new seed based on the time so for example May 31 2012 30 minutes 27 seconds 30 milliseconds we use that number that date time and we randomized our seat on top of that notice how the api's don't 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 api's are going to explain in small detail because it doesn't care enough to tell us how it does something just that it to expect something from you in the parameter and 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 name timer and we inherit from the node and the node inherits from objects so we get the API functionality of node and 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 0 now if you are new and you look at this you see that it comes with properties comes with signals enumerations 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 methods 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 in the properties and the methods doesn't really tell us how to use it you would have to learn that as a matter of fact I teach you about signals in the GD script 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 AP I want to show you now this is the less API and it's the OS short for operating system it even tells you here in 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 Gd script the operating system class is actually a global class it's an accessible global class when your node or 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 a 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 note 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 okay because remember Gd script is an abstracted language and it is a domain-specific language so you just have to wrap your head around that fact that GT script 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 note object attach a script to it and just play around with the properties just see what the behavior of your game looks like when you for example change the integer value of the current scene see what the behavior is when you change the value of the exit code see the behavior when you call the center window and that's how you grow as a programmer and one more thing I want to point out is that different ap is explained differently some API documentation czar good some API documentation czar bad it's not our fault however as programmers we have access to api's 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 however I know what to find I know where to find it for example if I need to do something with window I look at the OS class API in Godot and now read the properties and I'll read the methods and I'll see if I can solve my problem through a 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's 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 window full screen and by nature its value is set to foes by default so we just go ahead and we get the setter method and we set window full screen and we pass a boolean value because it's expecting a boolean and we set that to true and voila 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 good dough has an API class that can help you solve that problem again 500 API classes can't memorize them all 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 the comment section down below I look forward to seeing you in the next episode have an amazing day

Channel: Godot Tutorials

Views: 9,438

Keywords: API, Basic, Godot, GDScript, Documentation, Page, Random, Number, Generator, Timer, OS, Operating, System, Signals, Tutorial, Series, Beginner, Learn, Code, C#, Practice, Coding, Learning, Help, Example

Id: NLyJWV-QHDs

Length: 21min 19sec (1279 seconds)

Published: Fri Jun 05 2020