Getting Started with the Realm SDK for Unity

hi i'm nick raboy from mongodb in this tutorial we're going to see how to get started with the realm sdk for unity so we're going to be seeing some game development in this particular tutorial now i want to be upfront about something the realm sdk for unity as of right now which is march 2021 it is currently an alpha release so you have to expect that by the time that it reaches production stable release things might have changed slightly between now and then but it's all good because it'll give you a lot of the ideas when it comes to core concepts when it comes to persisting your data in realm in a game development project specifically with unity so up on my screen you'll notice that i do have unity open what we're going to do is we're going to be creating a new project for this particular example we're going to be creating a 2d project and we're going to save it right to our desktop it might take a few minutes to create the foundation for our project right now so our base project was created for our 2d game up in the top left you'll notice that my unity version is 2020.2.6 f1 so make sure that you're using a version of unity that's similar to that version so that way the experience will be very similar between my tutorial and what you see on your own development machine with our unity project created the next step is we actually have to get the realm sdk so if we open up our web browser we can navigate to the realm.net sdk github page so while it's in alpha we will have to download that sdk manually when it becomes stable we'll be able to include the sdk through the unity asset manager but for now we have to download it manually so what we'll want to do is we'll want to go to the releases section on github and we'll want to view those releases we're going to take the most recent realm unity bundle release so as of right now which is in march 2021 we have 10.1.1 as the release that we want to download now i've already downloaded it it's on my desktop what i'm going to do is i'm going to go back into unity i'm going to click on window and i'm going to open up the package manager up in the left hand corner of the package manager we're going to click that plus icon and we're going to say add package from tarball the next step is to add the realm unity sdk bundle that we had previously downloaded it may take a moment or two to include the realm sdk in our unity project now it's important to note that it's adding a reference to the sdk to our project so if we were to move the sdk from our desktop we would have to re-add it to unity however like i mentioned when the realm sdk for unity becomes a stable release and is part of the unity asset store we won't have to worry about it so we have added the realm sdk for unity to our project before we actually start developing our game let's focus on defining a data model that will represent our data stored in realm so within assets let's go ahead and create a new directory that directory we're going to call it scripts and within that scripts directory let's go ahead and create a new script so a new c-sharp script and we're going to call it data model or game model go ahead and open up that game model file in whatever editor you feel the most comfortable with so this is a pretty basic default unity script that we can apply to any game object we're going to make some modifications because the sole purpose of this particular script is to represent a class for our realm object so let's go ahead and remove the includes here and say we're going to say using realms because we now have the realm sdk as part of our project and instead of extending mono behavior we're going to extend realm object that means that we can now remove the start and update methods that are part of mono behavior so in this particular class file we're going to be defining the fields that are going to be part of our realm object we're also going to be defining the constructor methods for actually adding data to those fields when we initialize a new object so for this particular game we're going to be working with different colored squares the objective of this game is to click on a colored square and it'll increase the score for that particular color it's a very simplistic game not at all fun but it does serve the purpose of introducing us to the realm experience so we're going to have three different colors red green and white let's go ahead and create three different integer variables to represent those scores so i'm going to say public int and i'm going to say red score now each score is going to have a get and a set so what we need now is a primary key for our realm object this primary key is a unique identifier to represent any particular object within our realm data store so let's go ahead and add a new primary key value what we're going to say is we're going to say public and we're going to say this is going to be a string and for this example we're going to call it a gamertag so typically when you're playing a game the game information is unique to a particular player so for example you might have one computer game and you might have four different people within your household playing that game and you don't want all four people to be playing the same game and overriding each person's score information or similar instead we're going to make it unique to the particular player now we're not going to have multiplayers in this particular game so if we really wanted to we could just say something like game one and hard code that value across the board but we're going to use our imagination here and continue with the idea that this is a gamer tag and like with the scores we're also going to have a get and a set to identify this gamer tag as a primary key what we need to do is we need to inside of square brackets say primary key so just like that we have the data model for our realm object however we're not done yet though we need a way to be able to initialize all of this data when we want to create a new object in our realm database so what we're going to need to do is we're going to need to create a default constructor so we're going to say public game model and for this particular constructor we're going to leave it blank instead we're going to create an overloaded constructor where we can actually set each value in our object so we're going to say public game model and we're going to say string gamertag we're going to say integer red score and we're going to do the same thing for the rest of the scores now to finish it off what we're going to say is we're going to say something like this dot gamertag equals gamertag and we're going to reproduce this for each of the other values and just like that we're done with our realm data model however we still need to create scripts that are responsible for using this realm data model and then we're going to have to create other scripts to interact with the script that does the the reading and the writing but we're going to get to that so let's go back into our unity editor instead of writing more code to actually work with our realm data store what we're going to do is we're going to add a few game objects to our game and start working with the visual component of things and then we're going to ease our way back into actually working with our data so let's go ahead and start by creating a new sprite what we're going to say is we're going to say 2d object sprites and we're going to say square now for this particular square we're going to call it red square we're going to be creating a different colored square to kind of represent what we have in our realm data model although the naming convention doesn't need to match what we put inside of our game model script let's go and create our other game objects we have three different square sprite game objects and as of right now by default they are all white squares so if i were to move them around we would see three different white squares let's start by changing the color of each of these squares so i'm going to click on the red square and then i'm going to go into the inspector for this particular game object and i'm going to choose color and i'm going to pick a red color next up i'm going to click the green square and i'm going to do the same thing but this time around i'm going to make it a green color and then finally for white i'm going to leave it alone because white is the default color for this particular square sprite now that we have each of our sprites which we'll eventually be clicking on let's go ahead and create a game object to represent the game controller so this is going to oversee everything that happens in the game and it's also going to be responsible for when we want to interact with our realm i'm going to create an empty game object and i'm going to call it game controller this game controller will not have a visual component to it it's going to be responsible for just orchestrating what happens in our game now the final game object that we want to do is we want to create text so that way when we actually click on each of these squares or reload our game we want to be able to display the score information so let's go ahead and right click in our unity panel and we're going to say ui and we're going to say text and what that's going to do is it's going to create a canvas for us it's going to have a child item called text and it's going to add an event system we're going to rename text to score and we're going to change how the canvas is actually rendered on the screen so by default it's set to screen space for the render mode we're going to change it to camera and we're going to drag our main camera game object into the render camera area so you'll notice down at the bottom corner of our viewport that we have very small text that says new text let's go ahead and fix that let's go ahead and change it to be white text so that way it's a little more visible than that color of gray so we can enter a hexadecimal value let's go ahead and change the size of that text let's go ahead and say maybe 30 and you'll notice that it has disappeared that's because the size of our text has exceeded the area of the surrounding text box and we can change that by going into the rectangle tool inside of unity and dragging to expand the viewable text area let's go ahead and move where our text shows up so let's go ahead and change it to the move tool and let's drag it to maybe the top portion of the screen so we have new text which is eventually going to be score information so let's go ahead and change it to score so let's go ahead and say that we have a red score let's set that as zero let's go ahead and say that we have a green score which we're going to set at zero and let's go and say we have a white score which we're also going to set as zero and it's all right that our box is larger than the actual area so as of right now we have all of the necessary game objects on our screen let's go ahead and work with actually interacting with our realm data in the game so to do that let's create another script in our scripts directory let's go to say create c-sharp script and we're going to name this game controller so this game controller script will eventually be set on our game controller game object so i'm going to open it up in visual studio code let's go ahead and start by adding the using realms just like what we saw in the game model now we need to actually get an instance of our realm database before we do that we have to declare a private variable as well as the data model that we're going to be using for our realm so let's start by saying private realm and we're going to say underscore realm and we're going to say private game model underscore game model now we could technically add this to the start method but since there's no visual component to our realm we're going to do it in the on enable life cycle event rather than start so this is going to happen before the start event so we're going to say void on enable and we're going to say underscore realm equals realm.getinstance so now we have an instance to our realm database now before we try to query it we need to go ahead and set up a destructor so that way when we end our game it it properly disposes of the realm database but without clearing it so we're going to create a new method we're going to say void on disable and this is an actual method that's available as part of unity's lifecycle events and we're going to say underscore realm dot dispose now it's very important that you dispose of your realm when the application ends otherwise you're going to get some strange results so we actually get the instance and we dispose of it when we're done so let's start querying our realm let's go ahead and say game model equals underscore realm dot find we're going to be finding a game model and we need to provide it a string value that represents our primary key in this case let's go ahead and assume that it's going to be enroboy or nikraboy which is me now we don't know if that data exists in realm we're doing a find it may not necessarily exist and at least for now it doesn't exist we have a clean slate when it comes to our game so we're going to say if game model equals null so it does not exist no data was found for that particular primary key so if that's the case we need to create it so we're going to say realm dot write and inside of a write block what we can do is we can say game model equals realm dot add and we can say new game model we're going to provide it our primary key so which is our gamer tag so i'm going to say enter boy we're going to say 0 for the red score 0 for the green score and 0 for the white score now as of right now we either obtain our object from realm or we create our new object into realm at which case by the end of it we still have an object to work with so regardless by the end of this on enable we will have something from our realm to work with so let's go ahead and start working with it let's go ahead and figure out well how are we going to increase our scores or how are we going to query for our scores now the great thing about realm is it's an object database so we can work with our data in realm as if we were working with a standard object in c sharp so let's go ahead and create a new method this method we're going to use it and we're going to call it set button score and the whole purpose of this method is when the user clicks on the colored square we want to be able to increase the score inside of our game controller and we're going to connect it all together after so let's go ahead and say public void set button score now this is a method that we're making up this is not part of unity we're going to be providing it a color and we're going to be providing it a value to increment by we're going to do a switch statement so we're not going to necessarily know which square was clicked because we're going to be adding the same kind of logic the click logic to all squares and we're going to provide the actual name of that square to this script so let's create a switch so we're going to say switch we're going to provide the color so whatever was passed to the set button score method and we're going to add several case statements so we're going to say case red square if the red square was clicked what we want to do is we want to open up a realm right block so that way we can safely change the game model so we're going to say realm right and we're going to say game model dot red score plus plus so this is the same thing that we did when we initialized our realm so we got the instance and we potentially initialized this variable so we created a realm dot write let's go ahead and do the same thing for each of our different color squares now if for some reason one of the colors was not found because we've created some kind of uh inconsistency within our game let's go ahead and have a default so we're going to say default now instead of actually incrementing any kind of score what we're going to do is we're just going to print a log to the log so we're going to say debug.log and we're going to say color not found and then we're going to break so assuming that this set button score was called we're going to be providing a color and an increment value now you'll notice that in our code here we're not actually using the increment value and say we did plus plus but let's go ahead and say that we wanted to do plus equals increment instead so we're going to increment by whatever was passed into us so provided that the color was red square we're going to use the right block and we're going to increment the red score likewise we're going to do the same thing for green and white and if it doesn't exist we're going to print an error to the logs now let's go ahead and say that we want to actually obtain the score from realm so whether that be constantly or when the application starts now we're not going to do that in the start block we could but the start is only on the first frame instead we're just going to get the score on every frame that the game is open so what we can do is we can actually remove this start method since we're not going to be using it and inside of the update we can actually link our score ui text element to our game controller but we haven't done that yet so let's go ahead and scroll up what we're going to do now is we're actually going to create a public variable so that way we can link our score game object to our actual game controller so i'm going to say public i'm going to say text and i'm going to say score text now before we can actually use the text component we do have to import it into this script and to do that we can say using unity engine dot ui so if we scroll back down to our update method now we can actually make use of it so we can say score text dot text equals and we're going to do a long string and we're going to separate new lines with the with the new line character so i'm going to say red so red is going to be game model dot red score we're going to say plus we're going to say new line character so slash n we're going to say plus we're going to say green we're going to say plus game model dot green score and we're going to do the same thing until we've gotten everything that we need so this is a long string but when it comes to rendering our text on the screen it's going to be multi-line because of the new line character so we're going to be printing out the red score the green score and the white score now when it comes to reading from our realm we don't have to include it at any kind of block we only have to use the right block when we make changes to our realm object if we only need to read we can access it like any other object in c sharp so it's going to save it and go back into our unity editor this is where we actually want to start attaching scripts to our game objects so we know that our game controller script is going to be attached to our game controller object so let's go ahead and click on our game controller object and drag the game controller script into the add component you'll notice that i have a score text field for that game controller script that's our public variable that we added for text so we can take our score game object for text and we can drag it into that particular field so now we have a way to interact with our realm data however we aren't actually interacting yet because when we click on each one of these squares we're not actually calling that setbuttonscore method yet so we need to do that now so to do that we're going to want to create another script so inside of our scripts we're going to say create and we're going to say c sharp script and this time around i'm just going to call it button so this represents our colored squares i'm going to open up that button script and for this we're not going to be using the start or the update we're not going to be doing anything that has to do with altering the way that things are rendered for the particular button instead what we care about is we want to get mouse down events on the square itself so let's go ahead and remove that so to get mouse down events on the squares we actually need to add a box collider to each one of the squares so that way we can get a collision between the mouse and the square itself so let's go back into our unity editor let's go ahead and click on each of the squares starting with the red square and we're going to say add component and we're going to say box collider and we're going to do the same thing for each so now that we have a box collider on each one of our squares that'll give us access to a particular method within unity so what it'll give us access to is it'll give us access to the void on mouse down method so when the mouse is clicked what we want to do is we want to call that set button score method now the way to do that is we need to obtain reference to the game controller so we want to call the game controller from within our button script which is attached to any given button to do that let's create a public variable similar like what we did with the text component inside of our game controller script so we're going to say public we're going to say game controller and we're going to say game now using that inside of the on mouse down i can now say game dot set button score and we know that it expects a string for the color as well as a value to increment by so to get the color what we're going to do is we're going to get the actual game object name so if we go back into our unity editor you'll notice that each one of our game objects is named the same values that we hard coded in the game controller so remember our switch statement we have a case statement for red square green square and white square so we're going to extract the names for these squares and use them dynamically so let's go back into our visual studio code what we're going to say is we're going to say game object dot name so game object refers to the actual game object that this script is attached to so when we attach it to the three different game objects it'll have three different names and we're going to increment by one so let's go ahead and save it let's go back into our unity editor and we want to attach the button to each one of our squares starting with the red square so i'm going to drag button over to the add component area and it says game we have a game field because that's a public variable within our script we're going to drag game controller into that field and we're going to do the same thing for each one of our squares and what i can do is i can save it now so let's go ahead and try to run the application and see what we end up with so you'll notice that we have three squares but our text has now disappeared it probably disappeared because of how we chose to position it so let's go ahead and stop our game let's go ahead and click on score and let's go ahead and change the pivot information for this text so if i click on the bullseye looking thing inside of our inspector for score let's go ahead and change the pivot point to be the top left now when i do that now if i were to move the text over it's going to position itself relative to this top left corner so let's go ahead and hit play again so you'll notice that this time around our text is visible on the screen because we've changed how it's positioned within the scene itself so everything's zero by default because this should in theory be a fresh game instance so let's go ahead and click on that green square you'll notice that the green has now increased now remember every time i click on one of these squares it's storing it inside of our realm object and it's reading it from the realm object to actually display it on the screen so i'll click white i'll click red and maybe i'll i'll increase the score a few times on green now let's go ahead and stop it now what i'm going to do next it zeroed it out because i'm not currently playing the game it's not loading from our realm within the preview mode so i'm going to click play and hopefully it should still reflect what we saw the previous time we ran the game so i'm going to hit play and as you can see it still says four one and one so it persisted our data between when we closed the game and when we reopened it again now again in this particular example it was rather basic we only dealt with increasing scores but you have to imagine other scenarios so for example maybe you're playing a game like pokemon well you might be storing information such as the pokemon that are in your party the level that they're at the items that you purchase from the pokemon center all kinds of various information when it comes to the overall game for your player and there are other use cases well beyond the things that i've mentioned here but this is just a getting started guide when it comes to using the realm sdk for unity which as of right now is alpha if you wanted to get more help in regarding using the realm sdk so i showed you where to download it on github for the temporary but if you go to the.net sdk quickstart for realm it actually uses the same sdk as what you would find for the net sdk so they both use the same so if you went to the quick start it gives you instructions on how to create realm objects and how to use those realm objects and they're not they're not too different from what i demonstrated in this particular tutorial so i encourage you to have a look play around with it and start making some really epic games if you run into trouble go ahead and stop by the mongodb community forums and post your question there regarding the realm sdk for unity and either myself or somebody else will come and pick up your question

Channel: MongoDB

Views: 5,580

Keywords: mongodb, database, developer, coding, code, software engineer, stem, engineering, dbaas, data, serverless, nosql, realm, unity, game development, object oriented database

Id: df2qo8G2ZfU

Length: 28min 43sec (1723 seconds)

Published: Fri Mar 19 2021