How to create simple WebAssembly 2D game using Go
Hello, and welcome to my small tutorial of “How to begin your adventure with WebAssembly using Go”.
We will use marvelous library Ebiten created by hajimehoshi as game engine, Parcel as local dev server and build tool for production.
Finally, we will write multi-stage build Dockerfile and deploy it using Gitlab CI.
I must say, this tutorial is not about game logic — we will focus only on wrapping all things together. Our target result is a “W-A-S-D” controlled character with movement animation.
I will store all code at my GitHub, so you can easily navigate through using git tags, while reading this article. You can clone it with
git clone git@github.com:michaelknyazev/golang-wasm-parcel.git
So, let’s begin our adventure.
Boilerplate
First of all, we will create a simple boilerplate. Here is what we are going to do:
- Organize project structure
- Console Log “Hello World” with WASM using Go into browser console
- Create main.js and connect our wasm file using wasm_exec.js from Go
- Create index.html and see our result in browser
Project structure
To keep things simple, let’s create two directories: public directory for html/js and compiled wasm file, and src directory for our Go code.
Also, let’s init our go module and install Ebiten.
go mod init github.com/michaelknyazev/golang-wasm-parcel go get github.com/hajimehoshi/ebiten/v2
Hello World
Let’s create our main.go inside src sirectory, and write some code.
Now, let’s build it to WASM. It is actually very simple, all you need to do is provide GOOS and GOARCH environment variables for go compiler with proper values:
GOOS=js GOARCH=wasm go build -o public/game.wasm src/main.go
Cool! Now we have our WASM file ready to go! Let’s finish with HTML/JS part quickly, so we can see our “Hello world” in console.
HTML/JS
To make all things work, we need 3 files:
- wasm_exec.js, which is provided by Go team
- main.js, to wrap all things together
- and index.html
Let’s copy wasm_exec.js from local Go installation folder to our public folder (yes, its already on your computer, just copy it)
cp $(go env GOROOT)/misc/wasm/wasm_exec.js public
Great! Now, let’s create main.js and connect wasm file using wasm_exec.js
Let me explain a bit what is happening here.
First of all, to keep things clean, we imported wasm_exec.js directly to our main.js file to have single entry point for our bundler.
And because we are using Parcel as bundler, we imported wasm directly to our main.js as asset, with “url:” prefix.
After that, we wrote all necessary code to fetch and run our wasm file. Actually, you can just copy the “simple” version of it from official Go example.
Hello World in console
That’s it! All is left is index.html file and we are ready to enjoy our hello world in console.
Let’s run index.html with parcel:
parcel public/index.html
Now we can go to http://localhost:1234, open browser console and see our “Hello World” message.
Hooray! We arrived to our first git tag. You can check out all necessary code at this point using
git checkout boilerplate
First Steps
Now, let’s try to actually render something with Ebiten.
First of all, let’s define our Game struct to keep game state in it. We will add an integer count property, just for educational purposes — it will be removed in future.
Also, Ebiten requires our game to have several methods to work with:
- Layout — for defining our available “game space” (screen size)
- Update — for updating our game state and keep all game logic
- Draw — to render game based on our game state.
Let’s start with Layout.
According to documentation, layout accepts a native outside screen size and returns the game’s logical screen size.
Next, let’s write a mock update function, just to see all things working correctly.
As you can see, its just updates our count property on every call. In the Draw method we will output its value to console, just to demonstrate how the Update and the Draw methods are working together.
Back in days, you didn’t actually need two methods to make things work — It was enough to do all stuff in the Update method. But as the result, your code become messy and basically unreadable. It’s always a nice way to separate application logic from render.
Now, to the Draw method.
Here, we want our game to fill the screen with #f0f0f0 color and log into the console the count property from a game state for every frame it draws.
Finally, let’s start our game in main func, and review our main.go file.
Cool! Now we can re-build our main.go to wasm the same way, as we built it before, and see result in browser!
GOOS=js GOARCH=wasm go build -o public/game.wasm src/main.go parcel public/index.html
We can see a canvas filled with #f0f0f0 color and if you will open the browser console, you will be able to see the count property logged in it.
We arrived to our second git tag. You can checkout same way as last time to see all necessary code.
git checkout first_steps
Drawing character
Time for a cool stuff! Well, almost cool stuff, we will do controls and animation in the next section :)
At this point we will
- Create a character sprite using Universal LPC Spritesheet Character Generator
- Load it into our go code and render it on the screen
- Create Makefile to make our life a little easier
So, what are you waiting for? Go to Universal LPC Spritesheet Character Generator and generate your Gandalf! After picking all the hair colors and T-shirts, download your character sprite and save it to public/assets folder. Now, our project must look like this:
Now, let’s load our character sprite and render it. First of all, let’s remove the count property from a Game struct and let’s add actual properties that we will be using: The character Stance X and Y positions. Also, let’s define a var, where we will store our image, and let’s add two more constants, which will describe our frame dimensions (i think it’s actually not 65px but 64px — sometimes you will see glitches while moving from stance to stance. You will see what i am talking about in a moment :P).
stanceX and stanceY combined with frameWidth/Height will help us to navigate through character stances available in the sprite. After all, all we need is to pick right 65x65 rectangle around target stance, so, if you need the stance displayed in a 3rd column at a 6th row just make the stanceX variable equal to 3 and the stanceY variable equal to 6, thats all!
Next, let’s load image in the main func:
We will use a tool called ebitenutil from Ebiten package to load png image, and, as you can see we also modified starting properties for our Game struct — stanceX and stanceY now both equals 0.
Last step, before we will see our character in browser, we need to modify our Update and Draw methods.
Just clean up Update method from our test property increment, calculate stance coordinates, cut the right rectangle from our character sprite and draw it on screen. Now, you can build our main.go file (same way as usual) and see result in browser:
GOOS=js GOARCH=wasm go build -o public/game.wasm src/main.go
But if our go build command stay same as it was before, parcel now have an additional argument:
parcel ./public/index.html ./public/assets/*
This way we can tell parcel that there is additional files in public/assets folder that we want to serve as static assets.
Hold on for a moment. I don’t know about you, but i got pretty tired pressing the Up Arrow button in the terminal looking for the right build command.
Let’s use make to make our life easier and get rid of endless typing in terminal. All we need is to create a Makefile with 3 simple commands:
- clean — to clean up our build cache
- compile — for compiling our Go code to wasm
- dev — to run clean + compile and start local dev server using parcel
That’s all! Now instead of endless typing you can just run make dev and immediately see result in browser.
Things starting to look interesting and another milestone was reached. You can use git tag, as usual, and we moving to moving character section!
git checkout draw_character
Moving character
Alright, time to do some interesting stuff! Let’s try to move our character.
For accomplishing that, we need to do 3 things in our Update func:
- Listen for key press
- Change character coordinates
- Change character stance
But before that, we need to add to our Game struct positionX and positionY coordinates, and create a speed constant to control our character speed:
Now, let’s start with key press listening. We will use inpututil from Ebiten for that:
Yeah, code is pretty ugly here, i know we can do it, like, more declarative way, but for now — we are concentrating on making things to work.
After that, we can write our first handle for key press:
Basically, what we doing here is:
- Adding speed value to our main axis position (posY for Up/Down, posX for Left/Right)
- Checking if we already have correct stance row and column, and if we have, just set correct column to make “move animation”
- Choosing proper row for stances
- Blocking character to go off the screen. For that, we checking if character main axis position lower then 0, then setting it equal to 0, or greater then screenHeight (for Down) or screenWidth (for Right) setting it equal to screenHeight/screenWidth
2nd point in the list sounds a bit complex, isn’t it? Let me try to visualize what we trying to do:
See? We moving our virtual 65x65 frame over stances, to make animation.
Now, repeat it for every key we listen, and here is our Update func:
Alright! Time to render all that stuff in Draw func, and we are ready to control our character!
To render our character image at coordinates we need, we used a DrawImageOptions type. With method Translate, we can modify coordinates of our image on screen.
Piece of cake, isn’t it? Now, all is left is run make dev to rebuild all the stuff, and we can see the result in browser:
WebAssembly 2D game: Final Result
As usual, you can use git tag to checkout all the code at this point.
git checkout advanced_movement
Basically, that’s all for coding, now to DevOPS section, where we will find out how to bundle all things together with parcel.
Docker stuff and deploy
Actually, this part is really simple. All we need, is a Dockerfile with a 3 steps in it (build, bundle, nginx) and a pretty much standard .gitlab-ci.yml for image build and deploy to Gitlab Docker Registry.
Let’s start with Dockerfile:
As i told you before, we are creating 3 stages here:
- Stage to build our WASM file
- Stage to bundle all our project files
- Stage to serve all that stuff with simple nginx image
Also, we can actually modify the 5th line of our Dockerfile, and use make compile instead of full build command, just to make things look clearer.
We can test our Dockerfile with writing a couple of commands in our Makefile: for building image and for serving it locally:
Now, you can type make serve and head to http://localhost:3000 in your browser. Using dev-tools you can notice, that all files are bundled and compiled to production-ready state :)
We reached the final git tag at this point, so, as always, you can see all the code we need typing
git checkout docker_stuff
Gitlab CI
This part is super-optional, i just love the Gitlab CI for its simplicity, so i will use it to deploy our app :)
Let’s quickly write a simple .gitlab-ci.yml file to build and push our Docker container to GitLab Container Registry:
After that, create a repo in Gitlab, and push all of the code to the main branch. At CI/CD -> Pipelines page you will be able to see the status of build process.
When the Pipeline is complete, on your webserver, you can just pull image right from gitlab registry and start container like that:
docker login registry.gitlab.com
docker pull registry.gitlab.com/<your_name>/<your_project_name>
docker run -d -p 3000:80 registry.gitlab.com/<your_name>/<your_project_name>Or we can use docker-compose for that:
Now, we can just docker-compose up --build -d , and the project will be available at http://<your_server_ip>:3000.
Well, that’s all! If you red the whole article, i give you my thanks :) That was THE first article of mine and i hope you will find it helpful, or, at least, interesting to read :)
I will continue posting articles about Go development, and the next article i am already working on is about migrating from Node-Express-Mongoose tech stack to Go-Gin-Mongo.
P.S. I think I must give you my apologies for bad English grammar in some places inside this article, but i promise that i will edit it sometimes, to make it more readable for you.
