Use Extend Codegen CLI to generate Unity SDK Plugin for Extend Service Extension

Last updated on May 15, 2024
info

Extend is in Open Beta for AGS Premium Clients! This means that the Extend add-on is available for you to try in your development environment. You can submit your feedback via our Extend Open Beta feedback form.

Overview​

This article walks you through how generate a custom service plugin for AccelByte Unity SDK using the Extend Codegen CLI template pack.

A custom service service enables you to use AccelByte Unity SDK to interact with custom service APIs, such as one created using Extend Service Extension.

An Extend Codegen CLI template pack consists of a Makefile and Jinja template files. In order to generate code, you need to invoke a single make command. The make command runs Extend Codegen CLI with Jinja template files and a given OpenAPI 2.0 JSON file that describes the custom service APIs to generate code.

Prerequisites​

  1. Windows 11 WSL2 or Linux Ubuntu 22.04 with the following tools installed.

    a. Bash

    bash --version

    GNU bash, version 5.1.16(1)-release (x86_64-pc-linux-gnu)
    ...

    b. Make

    • To install from Ubuntu repository, run: sudo apt update && sudo apt install make.

      make --version

      GNU Make 4.3
      ...

    c. Docker (Docker Engine v23.0+)

    • To install from Ubuntu repository, run: sudo apt update && sudo apt install docker.io.

    • Add your user to docker group: `sudo usermod -aG docker $USER.

    • Log out and log back in so that the changes take effect.

      docker version

      ...
      Server: Docker Desktop
       Engine:
        Version:          24.0.5
      ...

  2. The latest version of the template pack zip for Unity.

  3. A valid OpenAPI 2.0 JSON file of your custom service.

    • For example, you can see the service.swagger.json, which is generated automatically when created using the Extend Service Extension.

      info

      You can generate Open API 2.0 from the Extend Service Extension sample app without running or deploying the app itself. Run make proto inside your Extend Service Extension sample app, then get the gateway/apidocs/service.swagger.json spec file.

  4. The AccelByte Unity SDK.

Generate Unity SDK Plugin for Extend Service Extension​

  1. Get a valid OpenAPI 2.0 JSON file of your custom service and place it under my-unity-project/spec folder. In this example, it is guild.json. After that, copy the guild.json file into three more folders: Client, GameServer, Models.

    /path/to/my-unity-project/
    ├── Assets/
    ├── Library/
    ├── Packages/
    ├── ProjectSettings/
    └── spec/
       ├── Client/
       │   └── guild.json <
       ├── GameServer/
       │   └── guild.json <
       ├── Models/
       │   └── guild.json <
       └── guild.json
    important

    The template pack uses the OpenAPI 2.0 JSON file name as an identifier for your service. You can rename the file according to your preferences, but we recommend using all lowercase alphabets (a-z) to avoid issues when generating code.

  2. Unzip the contents of the template pack zip file you downloaded. Then, from the unzipped contents, note the location of the Makefile.

  3. In a terminal, go to the location of the Makefile and execute the following command:

    make all \
       CODEGEN_IMAGE_VERSION=<codegen-cli-version> \
       PROJECT_PATH=/path/to/my-unity-project \
       SPEC_PATH=/path/to/my-unity-project/spec
    note
    • Get the AccelByte codegen-cli-version from the Docker Hub. For new projects, we recommend to start with the latest available version.
    • The PROJECT_PATH and SPEC_PATH comes from step 1.

    The output will be similar to the following:

    * copied ./res/com.AccelByte.SDK.Custom into com.AccelByte.SDK.Custom
    * copied spec/Client into com.AccelByte.SDK.Custom/spec/Client
    * copied spec/GameServer into com.AccelByte.SDK.Custom/spec/GameServer
    * copied spec/Models into com.AccelByte.SDK.Custom/spec/Models
    * generated package.json: '{package_name: com.AccelByte.SDK.Custom, package_version: 0.1.0, unity_version: 2020.2}'
    * generated package-lock.json
    * generated version.json
    * generated guild Client API
    * generated guild Client Wrapper
    * generated guild GameServer API
    * generated guild GameServer Wrapper
    * generated guild Models
    { "services": [ { "file_stem": "guild", "path": "guild" } ] }
    { "services": [ { "file_stem": "guild", "path": "guild" } ] }
    * generated Client Config
    * generated GameServer Config
    important

    Ensure to remove any leftover files when modifying or replacing the OpenAPI 2.0 JSON file as they might cause compilation errors to show up.

  4. Add com.accelbyte.sdk.custom as a dependency in Packages/manifest.json.

    {
      "dependencies": {
        "com.accelbyte.unitysdk": "file:../com.AccelByte.SDK",
        ...
        "com.accelbyte.unitysdk.custom": "file:../com.AccelByte.SDK.Custom"
      }
    }

Integrate Extend Service Extension API into your Unity project​

  1. Include API from the AccelByte SDK plugin.

    using AccelByte.Api;
    using AccelByte.Core;
    using AccelByte.Models;

  2. Call the API function.

    ApiClient apiClient = MultiRegistry.GetApiClient();
    // apiClient.GetApi<<ApiName>, <ApiName>Api>().SomeFunction(...);
    note

    In case you need to override the ServerUrl of your custom service and/or the basePath (e.g., /guild), refer to the guide for Enabling environment switching for Unity.

Last updated on

On this page