Platform Newcomer's Brief Guide

Requirements

Before starting to use Gaijin Application Platform (GAP), please make sure that:

• You have an active account at https://login.gaijin.net

  If you don’t have any account, please create one.

  If you have already been playing one of Gaijin’s games, your gaming account should suffice, however, for security considerations, it would be better if you used a separate account for development purposes.

  Note:

  If your email service supports subaddressing, we recommend using that mechanism for creating multiple accounts linked to the same email address.

  Let’s say you already have a gaming account with the registered email address [email protected]. You can create additional accounts according to the pattern jsmith+***@test.com with any sequence of symbols in place of the asterisks that is allowed for email addresses. In this case, a separate, fully independent account will be created, but all correspondence will go to the address [email protected].

  This way you can create both accounts for development and administration as well as accounts for test profiles. For instance, [email protected], [email protected], [email protected] and so on.

• TOTP two-factor authentication has been enabled for your account.

  Go to security settings https://login.gaijin.net/ru/profile/settings/security and make sure that two-factor authentication has been enabled and configured.

  

Getting a Developer License

To get a Developer License Activation Code contact with Gaijin directly.

You can activate your License here: https://store.gaijin.net/activate.php

Attention!

Before activating Gaijin Developer License, make sure you have been authorized in the store with the account you will use for creating and managing your projects.

New Project Registration

• Go to https://central-admin.gaijin.net

• Press the Add project button

• Enter the project name (Latin letters, numbers, and spaces are allowed)

  A project identifier will be generated automatically, based on the project name. All symbols will be made lowercase and spaces will be replaced with the underscore. Thus, for the project named Mind Games the mind_games identifier will be generated

• Press the Create button

Done. The project has been created and you are its owner and administrator.

Project Owners and Administrators

A project can have any number of administrators, one of them being its owner. Administrators have full permissions within the project except for being unable to remove the project owner.

There are two ways to add a new administrator:

• Knowing their numerical user identifier (user_id), add them using the “Add administrator” button
• Generate an invitation and send the link to your colleague. After they accept the invitation, their data will need to be confirmed.

On the screenshot above, you can see the project owner John Smith and his assigned administrator Alice Fox. Further above, in the “Invite” section, you can see an invitation link and a request from Bob Kinley waiting for the administrators’ approval.

Advice.

Many users use nicknames in their accounts. Use the possibility of changing a user’s Display Name so as not to get confused about who is who.

Service accounts

A service account is a special kind of account that can be used by a external applications or services to manage resources within the project.

You can't use service accounts to log in to the system in the usual way. However, you can assign roles and permissions for these accounts, just as you do for regular accounts.

A list of service accounts can be found in the "Service accounts" section of the main menu. Press the Create service account button to create a new one.

When you create a new service account, you can specify a display name, comment, and its lifetime (e.g for one year). As a result of creating a service account, you will be issued a token that will allow you to make API requests on behalf of the account.

WARNING!

For your protection, you should never share your token with anyone. If you have lost your token or it has been compromised, you can generate a new token for the account.

Applications

As soon as a project is created, it consists of one application of the same name.

Application - a logical entity, allowing for breaking a project into separate subsystems, each of whom can have its own permissions, its roles, and its own administrators. It is usually enough for a small project to have just one application. Additional applications within a project can be created at any time. Each application is fully independent and in no way affects the other applications.

In which cases will it be convenient to have several applications? If a project consists of several subsystems that are quite independent. For example, a game itself, which may require moderators, community managers or players with the permission to temporarily mute other players. A marketplace may stand alone, having a completely different range of permissions and roles. It will require permissions to manage transactions, refund, modify players’ inventory and so on.

Application roles and permissions

Open the Users section. There is a single user at the moment - it’s you as the project owner. You don’t have any roles or permissions assigned. It’s because no permissions schema has been defined in the application so far.

To make it clearer, let’s create a sample schema. In future, you can build upon it or you can create your own application schema from scratch. Let’s return to the main page of the project and go to the Roles and permissions section. There’s also nothing here at the moment. Let’s import the ready-made import schema.

• Press the Import button

• Put the schema into the form.

  SCHEMA

  {
    "roles": {
      "moderator": {
        "name": "moderator",
        "description": "",
        "protected": true,
        "permissions": [
          {
            "name": "user.kick",
            "value": true
          },
          {
            "name": "user.mute",
            "value": true
          }
        ]
      },
      "lead support": {
        "name": "lead support",
        "description": "",
        "protected": true,
        "permissions": [
          {
            "name": "inventory.edit",
            "value": true
          },
          {
            "name": "inventory.view",
            "value": true
          },
          {
            "name": "user.ban",
            "value": true
          }
        ]
      },
      "god": {
        "name": "god",
        "description": "",
        "protected": true,
        "permissions": [
          {
            "name": "inventory.edit",
            "value": true
          },
          {
            "name": "inventory.view",
            "value": true
          },
          {
            "name": "user.ban",
            "value": true
          },
          {
            "name": "user.kick",
            "value": true
          },
          {
            "name": "user.mute",
            "value": true
          }
        ]
      }
    },
    "permissions": {
      "user.kick": {
        "name": "user.kick",
        "value": false,
        "description": "Can kick user from game session",
        "protected": true
      },
      "user.mute": {
        "name": "user.mute",
        "value": false,
        "description": "Can mute a  user permanantly or for limited time",
        "protected": true
      },
      "user.ban": {
        "name": "user.ban",
        "value": false,
        "description": "Can ban a user from the game login",
        "protected": true
      },
      "inventory.edit": {
        "name": "inventory.edit",
        "value": false,
        "description": "Can edit a player inventory content",
        "protected": true
      },
      "inventory.view": {
        "name": "inventory.view",
        "value": false,
        "description": "Can view a player inventory",
        "protected": true
      }
    }
  }

• Press the Import button

  The application schema should display in the form of a table.

  

• Save changes (number 18 means that we have made 18 different edits to the application scheme)

You could create all permissions and roles manually, one by one, but it is much faster to import a ready-made schema.

The first column shows the list of permissions. In order to take any non-standard action in the game, the user should have the appropriate permission. Try to assign such names to permissions that will reflect the meaning of the permission assigned.

Header rows list roles. They serve to logically unite permissions according to particular tasks. There can be dozens of separate permissions within a single application. Assigning separate permissions to each user is complicated, confusing, and time-consuming. Moreover, if later you decide that all moderators should have the possibility to ban players, as soon as you add the user.ban permission to the moderator role, all users assuming the moderator rule will automatically get the user.ban permission.

Every user may assume several roles at the same time. So, there is no sense in creating a large number of complicated roles that differ literally in a couple of features. It is better to create several roles complementary to each other and assign a necessary role combination to a particular user.

NOTE!

Permissions do not function on their own. An application can request permissions assigned to a particular user and retrieve a list of actual permissions. The rest is on the part of the application itself.

User Management

Now you can return to the Users section and see that our only user may be assigned all three roles. Let’s make them, for instance, a moderator and a lead support.

There is also a possibility of adding other users or inviting them to manage the application in the same way it was done in the case of project administrator list management.

API Access Tokens

To make authorized requests to GAP API in the name of the application, you need to generate an API Access token. It can be done at any time in the Tokens section.

You can have a maximum of two active tokens at the same time. Two tokens are necessary in case you need to reissue a token, for example, because the current one was compromised. In this case you can issue a new token, replace the current token with the new one and then remove the previous token, thus making it invalid.

WARNING!

When generated, the new token should be saved. Once created, it cannot be restored. Only a new one can be issued.

It is not advisable to generate an access token until you really need it.

Services

Gaijin Application Platform offers a range of services allowing the applications in development to use services such as content delivery, matchmaking, leaderboards, inventory, bug reporting, forums and so on.

When necessary, these services are connected to your project. Being that any project needs the content delivery service, the YupMaster GDN service is automatically connected to a new project.

YupMaster GDN (Gaijin Delivery Network)

This service allows for preparing builds to be uploaded to the content delivery system, marking required versions and making versions available to players.

Only the one who has been assigned the appropriate permissions can perform these operations. Unlike with your own application, you cannot independently define the list of permissions and roles for managing an external service. Instead, each service has a predefined set of roles that can be assigned to users. In particular, the YupMaster service offers two roles: uploader and publisher.

Apart from that, the user adding system operates just like with the other project components.

We add the users who will prepare and deploy builds and assign necessary roles to them.

This may be useful

Please note. When assigning a role, you can assign it for a time. That is to arrange for the extended permissions given to a user to be automatically revoked on the expiry of the indicated time.

Uploading a Project to Gaijin Distribution Network (GDN)

Preparation

To work with the GDN servers, you need the following programs:

• yupgen.exe - preparing a build for upload to GDN
• yupload.exe - uploading a build to GDN
• gaijin_updater64.exe - downloading a version from GDN to a local computer

Download tools from the releases page: GaijinApplicationPlatform/releases

Now assume that all utilities are available on paths, although they may be located at any place and they may be called up by the full name of the file.

Let’s say that your build is in the .\builds\release catalog, counting from the current catalog

Generating a YUP file

Invoke the following command:

yupgen.exe -path .\builds\release -proj mind_games -ver 0.0.0.1

As a result, in the current catalog, there should appear a file of the form a2e61e8a631c353b59091a6b17ef64f7f358b70d.yup

That file contains the description of your build together with the project name, version, a list of all files, and a hash of their content. Being that YUP contains hashes of all the files from the .\builds\release catalog, you must not change the content of that catalog after the build.

Uploading a build

yupload.exe a2e61e8a631c353b59091a6b17ef64f7f358b70d.yup -check 0 -src .\builds\release -deploy -tracker http://yuptracker.gaijinent.com:27022/announce -dev https://gdn.gaijin.net/yuitem

This command will request a login and a password of the user on whose behalf the operation will be performed, then it will register the build in GDN and perform the build upload, making sure that all the data has been uploaded successfully and can be available for download.

Managing builds

Build are managed through the administrative panel at https://gdn.gaijin.net/yuitem/admin/

Downloading a build

Let us suppose that you want to download the build currently marked with the nightly tag to the last_nightly_build catalog

mkdir last_nightly_build
gaijin_updater64.exe -p mind_game -t nightly -f last_nightly_build --yupmaster gdn.gaijin.net --clear --verbose --norun --noupdate