MAGE tutorial —01. First steps with MAGE

Source: https://www.wizcorp.jp/

Welcome to the First steps with MAGE series tutorial! This tutorial series will guide you through the long way to learn MAGE. There will be several tutorials, each one helping you to build a new brick for your project.

Let’s start! In this first tutorial, we will learn how to setup a basic MAGE server. At the end of this tutorial, you will be able to store players data making a manual call to your MAGE server using curl.

For this tutorial and all the following ones we assume you have NODE_ENV environment variable set to development. If not, run in your terminal:

export NODE_ENV=development

Project creation

To create a new MAGE project, you will need to use npx and enter the following command:

npx mage create my-gameserver --typescript

npx will install mage like npm, but will also run a script which will generate a basic MAGE project using a template.

Note that we pass typescript flag. MAGE has 2 templates : one to generate a JavaScript project, and another one for a TypeScript project. This tutorial and the upcoming ones will only cover the TypeScript template.

project generator prompt

MAGE npx script will also prompt information to update the project’s package.json.

Project structure

When generated, the project structure is the following:

• config: server config files, one file per environment. Environment files will overwrite config/default.yaml file.
• lib/archivist/index.ts: Archivist topics configuration
• lib/modules: user modules, most of your code will be there
• lib/index.ts: MAGE server configuration
• tsconfig.json: config file for TypeScript compiler.

The first thing you will need to setup when creating a MAGE project is your database backend, or vault.

Vault setup

A vault is a database backend abstraction used by Archivist to store data. We will configure a new one for our players.

config/default.yaml

In config/default.yaml, we added a new vault named playerVault which is a file vault. We specified that the data will be stored in the directory playerVaultData.

One modification we also made is to add playerVault in readOrder and writeOrder. This is needed to be able to do read and write operations onplayerVault.

To see all the different vault types and for more information on the configuration, please refer to the user documentation.

The last step is to initialize the vault by running:

npm run archivist:create

This command will create the directory playerVaultData for playerVault.

Depending on your vault type and configuration, it could create a directory, database, bucket, etc…

Now we have defined our storage backend, we need to configure our player datatype.

Topic setup

A topic is a datatype which defines the vault(s) used for storage and how the data is accessed (ie. index, permission).

archivist/index.ts

In archivist/index.ts, we create a simple topic for our player data. We have configured our topic to use the vault playerVault, and to be accessed with the index playerId.

Module setup

We will now create our PlayerModule module. First, create the directory path players/usercommands in lib/modules.

Then, we will create a PlayerModule class in lib/modules/players/index.ts:

‘lib/modules/players/index.ts

The PlayerModule class will contain all the methods related to the player. We define a create method that will create a player with a given username. For now, we hardcode the playerId to 1.

Now, let’s create our create user command in lib/modules/players/usercommands/create.ts.

lib/modules/players/usercommands/create.ts

The create command is created by exporting a class which contains an async function named execute taking a state as first parameter, and as many parameters as we need (here, username).

The execute function is pretty simple: we just call our PlayerModule.create method.

We also need to specify an acl, which will be explained in another tutorial.

Testing the create user command

Now we have setup everything, we can start the server by running this command:

npm run develop

Then, open another terminal and make a manual request to the server using curl.

curl -X POST http://127.0.0.1:8080/game/players.create \
--data-binary @- << EOF
[]
{"username": "test"}
EOF

The request url is constituted as follow:

• http://127.0.0.1:8080: server endpoint
• game: application name (default to game)
• players: module name
• create: command name

The request takes a raw binary data in which an array containing headers data, and a payload of your data.

You should have a response like this:

[[null,{"username":"test"}]]

As MAGE is developed to receive a batch of user commands, it returns an array of responses. Each response contains an array where:

• The first element is the error message (if there is one), represented by a string
• The second element is the response data (here, {“username”:”test”})

Conclusion

Well done! You have created your first MAGE project. There is a lot more to cover to become a MAGE expert. In the upcoming tutorials, we will be covering:

• Mage data validation
• Client creation using the JavaScript SDK
• User authentication
• Distributed modules development
• And others !

In the next tutorial, we will see how to debug our server using mage-console.