エクステンド Codegen CLI を使用してエクステンドサービス拡張用に Unity SDK プラグインを生成する

Last updated on October 23, 2024

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 docker-buildx docker-compose-v2.

   • 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.

     備考

     You can generate Open API 2.0 from the Extend Service Extension app template without running or deploying the app itself. Run make proto inside your Extend Service Extension app template, 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
   注記

   • 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(...);
   注記

   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.