Godot 3.0 Tutorial: Building a simple character creation menu screen

In this tutorial: structuring and scripting a simple RPG-style character creation screen using Godot’s built-in containers and Godot script

What we’re building

I recently added a menu to my game that lets the player create their own custom character for the game.

In the context of my game, that means:

  • naming the character
  • selecting the character’s head sprite
  • choosing the character’s class

This work managed to touch on a lot of concepts, so I thought I’d share my work here in hopes that it’ll help someone else. I’ve been working in Godot on a hobby project for about 5 months now and I think the engine is great but could use a few more tutorials and “here’s how I did it” type stuff, so here we go. 

Some of the things covered in this guide include:

  • Godot’s container system (VBoxContainer, HBoxContainer, etc)
  • Building a simple menu out of Godot nodes
  • Hooking that menu up to the rest of the game
  • Changing scenes
  • Altering aspects of a “hero” scene, such as its name and head sprite
  • Lots of Godot script examples

PS: The project I’m using for this guide already exists (in some capacity), so there are references to things that are already built prior to this guide. Hopefully this “slice” of the game’s development is still helpful to someone, even if it doesn’t start from scratch. 

Structuring the scene: Godot container types explained

The first thing I did was make a new scene and add a Node2D to serve as the parent node and a VBoxContainer as its child to hold all of the major elements of this menu. The first child of the VBoxContainer is a label.

My new scene is called createHero.tscn

Let’s talk about structuring a menu in Godot.

For a menu with many “sections” or “elements” that read top-to-bottom, use a VBoxContainer. The VBox stacks its children elements vertically (one on top of the other) which saves you from having to position each one individually and from having to worry about overlapping elements. You can also control the VBox’s width and the spacing between its child elements.

Each element in the stack can be something simple, such as a label or a button, and it will occupy as much vertical space as it is tall. Nothing will overlap it. Or, each element could be something more complex, such as an HBox (which would let you create a row of buttons, labels, or similar).

This system takes a little practice to get used to, but hopefully this diagram made of children’s blocks helps clarify the general concepts.

This stack represents a VBox with child elements. Each “row” is a container, element (such as a label or a button), or an HBox with child elements of its own.

For the sake of brevity I’ve skipped ahead to my assembled scene. This builds on the concepts already explained.

My scene now contains a VBox parent with three children: a label, an HBox, and another HBox.

For now, it’s just made out of unskinned/unstyled Godot nodes.

Some things of note:

  • There’s an open space below the “Create Hero” label that I will use to display the hero art later on
  • “container_spacer” is a generic Container node. I set its minimum width to 420 so that the other thing in the HBoxContainer2, the “Rename” button, gets pushed to the right side of the screen.
  • The hero class (Cleric, Druid, Ranger, etc.) buttons are in an HBox that manages their left-to-right spacing 

Getting to this new scene

I made a little button on the main screen of my game to access createHero.tscn.

This is just temporary so that I can access the new menu for testing.

Eventually, this “Create a character” screen will be the first thing the player sees when starting a new game, but I don’t want to clutter the new game startup flow with an unfinished (possibly broken) menu yet. 

Here’s the button on my main game scene:

I hooked up its button press signal (I just go with the default function name Godot suggests):

And the code:

If you’re following along at home, all you need is the last line, the one that begins get_tree()… as the other two lines are specific to my game.

With that button hooked up, I can now run my game and click the temporary button to get into my new menu. 

Here it is in-game. No, it’s not beautiful. but we gotta start somewhere!

Creating a script file for this menu

For this menu to actually do anything I’m going to need a script file for this menu (or this scene, to use Godot’s parlance). To create a script file for the scene I click on Node2D and go into the Inspector tab. I selected New Script and let Godot create a new script for me.

With Node2D selected, go down to Script and selected New Script.
I just take the defaults most of the time in Godot. This stuff is all fine as-is. I click “Create” and let it make the new script file for me.

Adding an instance of the Hero scene to the Create Hero menu

Usually with a character creator you want to show a preview of the character being created. For the game I’m working on, that means making an instance of the Hero scene and attaching it to the menu so the player can see their character preview.

(The Hero scene already exists in my project. I won’t cover it in this tutorial, but you can see the code that makes up a Hero scene and the hero generator by viewing these gists I made for the sake of this guide: hero.gd, baseHero.gd, heroGenerator.gd. You don’t need to look at or understand these files to follow this guide, but you may find them helpful if you are trying to build something similar.)

Here’s how hero.tscn looks in my project, structurally speaking:

Back in createHero.gd, we have to add some code in order to see the hero scene in the menu. The project already has a heroGenerator file that I use to make random heroes for the player’s guild. Here, the heroGenerator file is used to make a single hero and present it to the user in this menu. The general idea here is to generate a random hero, show it to the player, and then let the player customize it to their liking (just like how “create a new character” works in a lot of MMO type games).

Code for generating a hero, adding it to the guild roster, creating a scene instance for that hero, and adding the instance to the menu scene. View this code as a gist.

Here’s how it looks in-game:

Ta-dah: a hero character instance now exists in the menu.

Making the “Rename” popup and functionality

There are a few things we have to do to get the rename popup working:

  • Add the popup node itself (a ConfirmDialog node)
  • Give the popup a TextEdit field so the player can enter a name
  • Make the popup appear when the user taps the Rename button
  • Write the script that accepts the new hero name
  • Update the hero’s data to keep the new name
  • Add a random name generator button
  • Name validation (not part of this tutorial but for a real game you’d probably want this)

First, the popup.

Godot has some dialogs (popups) built in. The “Rename” popup is going to be a ConfirmDialog with a child LineEdit. The LineEdit is a field for the user to type in. This guide’s game is imagined as an Android/iOS game, and LineEdit conveniently brings up the keyboard on those devices.

I made this confirmation dialog into its own scene since the rename functionality will be used elsewhere in the game. (To do that, right click the ConfirmDialog in the Scene tree, click Save Branch As Tree, and save it as its own scene.)

If you don’t make a ConfirmDialog its own scene, its Ok button script can just go in your parent scene’s .gd file.

If you do make ConfirmDialog its own scene, its Ok script will be in its own file.

Either way works, I just like to make anything used in more than one place into a scene so I don’t have to maintain code in two places.

Hooking up the Rename button to open the popup

Now that we have the confirm popup scene made, let’s make it so the “Rename” button actually opens the ConfirmDialog (which I’ve named confirm_rename_dialog). Godot makes this really simple.

Select the Rename button and navigate to its pressed() signal.

Select the “Rename” button and navigate to its Node signals. Highlight pressed() and click the Connect… button in the lower right.
I’m happy with the method name Godot suggests, so I click Connect and let it create the method.
Here’s the empty method Godot created.
And here’s all the code it needs to open the dialog.

If we tried it in-game now, we would be able to open the popup and type a name but not actually save our new hero name. 

Saving the user’s input to the hero

To make the “OK” button actually do something, we have to go into the confirm_rename_dialog scene and attach a script file to the scene. I made a new script file for this ConfirmationDialog.

In the Node signals panel, the confirmed() entry is what is triggered when the user presses OK. I connected it to an empty function.

Click confirmed() and then click Connect to generate a function in the popup’s script file.

Godot makes it realy easy to grab the user’s input from the LineEdit. Just write:

var newName = $LineEdit.text

and then do something with newName. In my case, that meant updating the selected hero’s heroName to be the value of newName. 

(Note there’s no attempt at validation in this example, so the user can enter anything they want right now. For a real game, you’d probably want to keep names under a certain length and filter out numbers, special characters, symbols, emoji, and possibly dictionary words and profanities.)

But what’s this signal business? Well, the popup is a separate scene from createHero, so it has to communicate with its parent scene. Godot does that with signals.

Declare the signal (line 3) and then emit it (line 12). It’ll be caught by the code up in createHero.gd.

Back in createHero.gd I’ve had to make a few changes. There’s now a draw_hero_scene() method because I think we need to clear and redraw the hero scene from at least two places in the code, so I took it out of _ready and made it its own function.

I also attached the redrawHeroName signal to the confirm_rename_dialog instance, so that it can “listen” for the signal and call “update_hero_name” when the signal is “heard”. All update_hero_name() does is free the existing hero scene (clear it from the stage) and make a new one. This draws a new hero instance with the new name.

I’ll probably rename update_hero_name() to something more generic once I give the user the ability to modify the hero’s appearance and class.

Let’s try it out in game before moving on:

User types anything they want (seriously there’s no validation yet)
Success! And it doesn’t even flicker. I was afraid it would flicker.

Making the “hero class” buttons (radio buttons)

Next up: changing this hero’s class.

A hero can only be one of the available classes (ie: she can be a Wizard, or a Warrior, or a Cleric, but not more than one of those options). When the player picks a choice, the others are “deselected”. 

This is a lot like how “radio buttons” on the web work. Pick one choice, the others are “un-picked”. Godot actually has something for this: a button group! A button group is somewhat convoluted to set up.

First, select one of the buttons we want to add to the (not-yet-created) button group. In the inspector tab, scroll down to Group. Click where it says <null> and then choose New ButtonGroup. 

Click on New ButtonGroup to view its inspector pane. Go to Save As… to save it as a .tres.

Saving it lets us load it onto all the other buttons.

Select all of the remaining buttons and click the field next to Group. Choose Load and then choose the saved .tres file. Now all of the buttons are in the createHero_classButtonGroup.

Let’s try it in-game.

Here we have Cleric selected.
…and here we have Druid selected. (The faint blue border indicates which one is selected.)

Making these buttons mutually exclusive will help with styling later on and allows us to quickly “deselect” the user’s previous choice and highlight the new current choice. (The highlight on these default Godot buttons is a thin blue border that might be difficult to spot at first.)

Changing the hero’s class (in data)

This step is going to require some refactoring. Currently, there is no mechanism in the game to change a hero’s class. A hero is given a class and a matching gear loadout by the heroGenerator.gd file and that’s it. 

Our refactor will need to:

  • Change the hero’s class
  • Change the hero’s starting gear to match that class
  • Change the hero’s starting stats
  • Do not change the hero’s name or head (these might already be set by the player, but if we just generate a new hero they will also be re-generated)

I had to do some refactoring here…

So this next part is kind of a tangent and really specific to my project, but I wanted to include it and not just hand-wave it in case it’s valuable to someone who reads this (hello, future me, probably).

Currently, the hero’s starting gear is handed out in heroGenerator. A hero already has a “give_new_item” method that accepts a string (must match an item in the game’s static data) to create an instance of the item and assign it to the hero’s equipment object. Here, giving a character its starting gear is done with multiple calls to give_new_item on the hero class.

The old way of giving gear was done line-by-line.
Hero.gd has this method to find the item (by its name as a string) in staticData.items and stick it on the hero in the correct equipment slot.

The problem with how this is currently done is that this “gear assignment” step happens when the hero is generated for the first time, and then does not (or cannot) happen again. But if you change a brand-new character from a warrior to a wizard, you need to wipe the warrior gear and replace it with wizard gear. I could probably do this out of methods that already exist on the hero for giving and taking equipment, but I have an idea for something cleaner: a “gear loadout” system, whereby gear sets exist in staticData and are assigned to a hero in one fell swoop.

Here’s a quick look at the changes I did during this refactor. I won’t cover every last step, just a high level of how this stuff works in my game.

Added a new data sheet: In my game data Google Sheet, I made a new tab and set up some gear loadouts like so. (The fields are restricted to just items that actually exist in the Items tab of the game data workbook.)

This gets exported as a json:

And then I go over to the tool I wrote to process individual JSON files into my Godot project’s staticData.gd file. (This deserves its own tutorial, but for now you can check it out as a gist here if you like.)

Parsely (a tool I wrote for this project to turn .json data into objects in a .gd file) now handles this new loadouts.json file
And now var loadouts is an object in staticData.gd.

And now var loadouts = {…} exists in staticData.gd. Since staticData.gd is an AutoLoaded file, this means that my game’s code can retrieve a specific loadout by id like so, from anywhere in the project:

var gearSet = staticData.loadouts[“clericNew”]

Updating hero.gd Now that we have the concept of gear loadouts, it’s time to update the hero class with the ability to use them.

Now you can call hero.give_loadout(“clericNew”) and get all the gear associated with that loadout.

For now, the give_loadout() method is also going to delete any armor already on the hero, since this feature is only used during the creation of a new hero and we don’t want to keep all the gear generated by changing class. I don’t think give_loadout() will be used outside of character creation and testing purposes so for now this is fine.

Writing the change_class() method in hero.gd

Finally, I have everything needed to write change_class(). Now we can write hero.change_class(“Cleric” and that hero will become a cleric, complete with the default newbie cleric gear. 

One last thing to do before calling this refactor complete: update the heroGenerator.gd code to use loadouts instead of one-by-one gear gifting like we saw earlier in this guide.

heroGenerator.gd now uses give_gear_loadout() to assign gear sets to newbies. Remember, the gear loadouts themselves are stored in the spreadsheet data now, so there’s even some validation (in the Google Sheet) that the user picked a gear item that actually exists. Win-win all around.

Okay, NOW we can finish what we came here to do: clicking the class buttons should change the new hero’s class and change all of its starting gear to match.

Back in createHero.gd, we hook up each hero class button to a bit of code that calls change_class on the selected hero (the one we are viewing). I’m sure there’s some more efficient way to do this but for a small set of buttons this makes it pretty clear what’s going on. Remember how I thought we might change “update_hero_name()” to something more generic? Well now it’s “update_hero_preview()” because we also call it after changing the hero’s class.

Let’s try it out in game. Here our new hero is a Wizard.

And now she’s a Warrior, with the right gear and without losing the head graphic or name the user picked for her.

Phew – the refactoring detour is done. Yay! 

There’s just one thing I want to do before calling this particular piece of work (and this little guide) done, and that’s give the user the ability to change the hero’s head. 

Selecting a head sprite and saving that choice

There’s lots of head sprites in the game already. Currently, the only “race” (in the fantasy sense) you can play as is humans.

The game already has a concept of “male” and “female” head sprites. The lists of those sprite filenames are kept in two separate arrays, like so:

The heads are already in two arrays for the sake of the random hero generator, but the player gets to pick from all possible heads.

There’s no gameplay concept of gender, and separating heads into two arrays was just something I did to help the random hero generator pair the more masculine-looking (bearded, balding) heads with the more masculine names, and vice versa with the more feminine-looking heads and names.

This is important because when the player makes their own character the player gets to pick from ALL the heads, not just a subset of heads. So I’m going to have to combine them into one array for the sake of cycling through them in the create hero menu, while still keeping them as two separate arrays for the hero generator.

Originally, the head arrays were in heroGenerator.gd. That wouldn’t work going forward, though, since I now needed to access them from createHero.gd (the create hero menu scene) and by the time we’re in createHero, the generator is done doing its thing and we don’t want to go back “into” it and access some arrays in it.

I realize that sounds confusing: the goal is to make the head arrays exist on the hero so they can be accessed from both createHero and heroGenerator.

I moved the head arrays to baseHero.gd, which is where I keep all the base hero stats data (hero.gd extends baseHero.gd and inherits everything in it).

baseHero.gd now contains all the head sprite data

I had to make a minor update to heroGenerator.gd, telling it to look on the hero itself for the head sprite arrays instead of at a variable local to itself. Now that the arrays are on the hero, though, they can be grabbed by either heroGenerator or createHero.gd.

heroGenerator.gd before
heroGenerator.gd after – the humanMaleHeads and humanFemaleHeads are now on newHero

Over in createHero.gd, I added two new vars: allHumanHeads = [] and headIndex = -1.

I added code in _ready() to build a new array, allHumanHeads, out of the two separate male and female head arrays. It also figures out which index the hero’s starting head is at, so we can use that head as the starting point in the array when we press the “Previous Head” and “Next Head” buttons.

Adding the buttons

This part should look familiar – in the createHero scene I added another HBox (HBoxContainer3 in the screenshot) and centered two buttons inside it.

These buttons have to cycle through all the possible heads. Still in createHero.gd, I attached the “Prev Head” and “Next Head” buttons to two new functions:

I also added some logic to handle the “wrap around” effect that should occur if the user clicks “prev” or “next” enough to reach the end of the head array.

Finally, in hero.gd I added a very short method called change_head. All it does is take the string of the new head sprite (such as “female_head_01.png” and update headSprite on that hero.

Pass in a string representing the filename of the new head sprite and this method updates the hero instance to use that new head sprite.

End result: changeable heads!

This menu could be prettier, but styling it is a topic in and of itself and this guide is already huge.

Final steps: testing the results of the character creator

The very last step is to hook up the “Create hero!” button at the bottom of the menu. Technically, the hero was already created. All we did was modify that already-created hero’s class, head, and name. This button just has to take the player to the main scene. 

I hooked up the Create hero! button to this script in createHero.gd…

I customized a hero… (she was originally a warrior with a different name and head)

And confirmed she is now part of my guild. Here’s “Tidbit Littlebit” with the group:

There she is!

Checking in the Guild Management screen…

And checking her hero page (to ensure she has the correct stats):

Looks good!

I wanted to make a guide showing some of the work I’ve done in Godot, mostly just to help support what I think is a great game engine for indies and hobbyists. If you found this helpful, let me know in the comments!