Install SDK

TypeScript

Quick Start

1. Install the Balancy SDK package:

   npm i --save @balancy/core@latest
   npm i --save @balancy/cli@latest
   

2. Simple example to initialize the SDK:

   import {
       AppConfig,
       Balancy,
       Environment,
       Platform,
   } from '@balancy/core';
   
   (async () => {
       // TODO: Replace with your game ID and public key
       const config = AppConfig.create({
           apiGameId: "6f5d4614-36c0-11ef-9145-066676c39f77",
           publicKey: "MzA5MGY0NWUwNGE5MTk5ZDU4MDAzNT",
           environment: Environment.Development,
       });
   
       config.platform = Platform.AndroidGooglePlay;
       config.deviceId = "TestDevice";
       config.customId = "Custom456";
       config.appVersion = "1.0.0";
       config.engineVersion = "TypeScript_1.0";
   
       Balancy.Callbacks.initExamplesWithLogs();
   
       await Balancy.Main.init(config);
   })();
   

3. Clone a complete working example from our public GitHub project: Balancy TypeScript Example.

File Manager

The Balancy SDK includes a file manager system to help you manage configurations and assets. It caches the downloaded data, so it can be reused next session. To make the file manager work, you have to implement the following interface:

export interface JSFileHelper {
  createSubDirectoryInCacheCallback(fileName: string): void;
  saveFileInCacheCallback(fileName: string, data: string): void;
  saveFileInCacheBinaryCallback(fileName: string, data: string): void;
  saveFileInResourcesCallback(fileName: string, data: string): void;
  cleanUpResourcesFolderCallback(): void;
  cleanGeneratedCodeFolderCallback(): void;
  saveGeneratedCodeCallback(fileName: string, data: string): void;
  loadFileFromCacheCallback(fileName: string): string;
  loadFileFromResourcesCallback(fileName: string): string;
  deleteCachedFolderCallback(path: string): void;
  deleteCachedFileCallback(path: string): void;
  getFilesInCachedFolderCallback(path: string): string[];
  applyTempFolderCallback(tempFolder: string): void;
}

We've prepared several implementations for different platforms:

• NodeJS - it uses the file system to save/load files.
• TypeScript Browser - it uses the local storage to save/load files.

Feel free to download any of the files and use them in your project or write your own implementation. Below is the code you should use to initialize the file helper. Make sure to do that before calling Balancy.Main.init:

await Balancy.Main.initializeFileHelper(new FileHelperClassBrowser({
        cachePath: '.balancy'
    }));

cachePath is the path where the files will be saved. There is an additional parameter resourcesPath that could be used, in case you are planning to use the files saved in resources. You can download the configs to resources using the npm command.

Additional Methods

You can use several npm commands to configure the Balancy SDK. These commands are part of the @balancy/cli package. To access them, add the balancy script to your package.json file:

{
  "name": "balancy-demo",
  "version": "1.0.0",
  "main": "index.tsx",
  "scripts": {
    "start": "react-scripts start",
    "build": "react-scripts build",
    "balancy": "balancy"
  }
}

Adding "balancy": "balancy" allows you to run Balancy commands directly from the terminal.

Authentication

Authenticate the Balancy SDK using this command:

npm run balancy -- config-login -e <email> -p <password> -c .balancy

Use your email and password from the Balancy Dashboard. This command creates a .balancy folder containing a user.info file, which securely stores your email and token. It is recommended to add this folder to .gitignore to prevent sharing tokens. After authentication, you can run Balancy commands without logging in again by specifying the -c .balancy parameter.

Get Game List (Optional)

npm run balancy -- config-list-games -c .balancy

Lists all games associated with your account. Use this command to retrieve the game ID.

Select Game

npm run balancy -- config-select-game -c .balancy -g 6f5d4614-36c0-11ef-9145-066676c39f77

Select the game you want to work with by specifying its game ID. The selected game is saved in the user.info file, which you can edit manually if needed.

List Branches

npm run balancy -- config-list-branches -c .balancy

Lists all branches in the selected game. Use this command to retrieve branch IDs.

Select Branch

npm run balancy -- config-select-branch -c .balancy -b 0

Select a branch by specifying its ID. The selected branch is saved in the user.info file, which you can edit manually if needed.

Generate Code

npm run balancy -- config-generate -c .balancy -p src/auto-generated-code

Generates code for the selected branch and saves it to the specified path. For example, the code is saved to the src/auto-generated-code folder in this command. Once generated, you can import the code into your project:

import 'auto-generated-code/index';

Download Configs

npm run balancy -- config-download -c .balancy -p src/resources

Downloads configurations and assets for the selected branch. Specify the path where the files should be saved. For example, the configs are saved to the src/resources folder in this command. This allows your app to include essential configs for offline use or as a fallback.

---

Cocos Creator

Quick Start

Follow the TypeScript setup instructions first. You can continue using npm commands to manage the Balancy SDK, or install an additional package for enhanced integration:

npm i --save @balancy/cocos-creator@latest

Once installed, a new menu item appears in the Cocos Creator editor. You can find it in the top menu under Balancy. Use this menu to run all Balancy commands.

---

Unity

To be added...