Welcome to the first tutorial in our series of launching an HTML5 game in the ARK Desktop Wallet! This series is aimed at developers of all skill levels. The goal of this series is to be able to convert an HTML5 game to work as a fully functioning plugin within the ARK Desktop Wallet. The first set of tutorials will explain how to interact with the blockchain in a standalone HTML5 environment before finally jumping over into the ARK Desktop Wallet.
At a glance, this tutorial series will be broken down into the following parts:
- Part One: How to import an ARK wallet address into your application
- Part Two: Creating the Backend for your Plugin
- Part Three: Making your game work with a betting system
- Part Four: Implementing Game Logic into your Plugin
- Part Five: Determining how Prizes Work
- Part Six: Launching your game as a wallet plugin
One thing to keep in mind before we start, these tutorials are aimed at launching an HTML5 game within the ARK Desktop Wallet. These tutorials are not aimed at teaching developers how to build games. However, once your game is built, we would love to support it within the ARK Desktop Wallet. So let’s dive in and get started with importing a wallet address into your game!
Importing A Wallet Address Into Your Game
In this first part of this series, we will look at how to import a wallet address by making sure it is valid so players don’t accidentally make a mistake by entering the wrong address and losing out on a potential prize. This will lay the groundwork for the next installments where we will write our game logic in our very own Core plugin.
We will be using the free plan of the Construct 3 engine — a point and click game development environment — to create our simple HTML5 game, so head over there and start a new project.
Unfortunately, at the time of writing, the ARK JavaScript SDK is not fully compatible with HTML5 games out of the box, so we will use an alternative called bs58check to validate addresses. The steps to build our alternative are outlined below, but if you prefer to skip that, you can use a pre-bundled version which we’ll discuss in a second. If you’d like to build it yourself, make sure you’ve installed NodeJS and npm, then execute:
npm install -g browserify uglify-jsnpm install bs58checkbrowserify — standalone bs58check -r bs58check | uglifyjs > bs58check.min.js
Next, we’ll import our bs58check.min.js file into our Construct 3 project so the game can use it. This is really simple — just right click Scriptsin the top-right pane, choose Import Scripts and drag and drop our bs58check.min.js file into the window. Click Import and you’re done!
What Makes An ARK Wallet Address Valid?
Now we need to take a step back from the practical activities and focus on the theoretical side. What makes an address valid, and how can we separate an ARK Public Network address from an address on the ARK Development Network or another bridgechain?
Each address must be exactly 34 characters long and, in the case of the ARK Public Network, each address starts with an A; conversely, addresses on the ARK Development Network start with a D and bridgechains can use their own character. This first character is related to the network version — remember this, we’ll be coming back to it in a second. The characters used in an address are known as base58, which is a group of 58 alphanumeric characters that are easily distinguished to minimize the risk of confusion, for example, 0 (zero) and O (uppercase o) look similar, so they are excluded; also, I (uppercase i) and l (lowercase L) are omitted from the character set for the same reason. Lastly, the address includes a checksum to make sure the rest of the address has been entered correctly with no typos.
So, remember how the first character of an ARK Public Network address is A and the ARK Development Network is D? That is derived from something called the network version, and each blockchain can have a different network version, which determines the first character of all the wallet addresses on that network. In case you’re curious — and you’ll need this later — the network version for the ARK Public Network is 23, and the network version for the ARK Development Network is 30.
Now you know that an address is valid if — and only if — it is exactly 34 characters long, starts with the correct character for the blockchain’s network version, only contains characters in the base58 group and has a valid checksum. Now to put this into our game!
Adding An ARK Wallet Address To Your Game
Let’s begin by adding some objects to our layout. In our example we are going to add a text input box for a user to enter their address, a button to validate the entered address and a text display to tell us if the address is valid. Double click Layout 1 in the top-right pane, then right-click the blank canvas and chooseInsert new object. Double click Text input and drop it on the layout where you want it to appear. Repeat this to add Buttonand Textobjects too. Feel free to customize the style of the objects however you like, and if you’re feeling creative, add some sprites and a background image to spice up your layout.
Let’s start by creating a variable to hold the network version. Right-click our event sheet and choose Add global variable. Call it networkVersion with an initial value of 23.
We will create a function to validate the address. Right-click anywhere in the event sheet and choose Add function. Call it validateAddress and set the return type to Number. Hit OK, then right-click our new function and Add parameter. Call it address which is a String. Now right click Add action for our function and choose Add script. Now we can finally write some JavaScript!
if (localVars.address.length === 34) {try {const networkVersion = bs58check.decode(localVars.address).readUInt8(0);if (networkVersion === runtime.globalVars.networkVersion) {runtime.setReturnValue(1);}} catch (error) {// the address is invalid}}
Let’s break this down. By default, the function will return zero. If the address is 34 characters, it will execute bs58check.decode which will throw an error and exit the function if the address contains invalid characters or the checksum fails. Otherwise, we check that the network version matches the ARK Public Network. If so, we return a value of 1. In simple terms, if the address passes our checks, the function returns 1, otherwise, it returns 0.
Now we’ll put our function to work! We want it to run whenever our button is clicked. Click *Add**…* next to our On clicked event andAdd sub-event. Scroll down to Systemand Compare two values. Essentially, what we want to do is check if our function returns a 1 or not. So, our first value should be Functions.validateAddress(TextInput.Text) and our second value should be 1.
Almost done! We just have to tell it what to do if the function passes and if it fails. Click Add action for our comparison, double click our Text object and choose Set text. Enter “Address is valid!” and choose OK. Now for the failure case: Click *Add**…* next to our new Set text action and choose Add Else. Click Add action for our Else case, double click our Textobject and choose Set text. Enter “Address is invalid” and choose OK.
We can now test our creation by clicking the triangle in the menu bar. Try entering a valid ARK Public Network address and click the button, then try an invalid one. Go back into the source code and change the networkVersion variable from 23 to 30 and try again with a Devnet address. All being well, you should now be able to tell if an address is valid on the ARK Public Network or the ARK Development Network!
Next Steps
That’s it for part 1 of this tutorial series. In our next session, we’ll explore Construct a little more and learn how to connect to a peer to obtain its network version and use that rather than hardcoding the value so our game can be compatible with all bridgechains, and we’ll start our Core plugin for the main game logic.
If you become stuck at any point make sure to consult our documents on the Learn ARK hub. In addition, our team and developers are active on Slack so do not hesitate to reach out to us!
