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

Last updated on December 18, 2024

Overview

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

A custom service service enables developers to use AccelByte Unreal 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 Unreal.

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 Unreal SDK.

Generate Unreal SDK Plugin for Extend Service Extension

1. Get a valid OpenAPI 2.0 JSON file of your custom service and place it under my-unreal-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-unreal-project/
   ├── ...
   ├── MyAwesomeGame.uproject
   ├── Config
   ├── Content
   ├── Plugins
   ├── Source
   └── 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-unreal-project \
      SPEC_PATH=/path/to/my-unreal-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.
   important

   If the Plugins folder does not exist in your Unreal project, you'll have to create it manually.

   Output

   * copied ./res/AccelByteUe4SdkCustomization into Source/AccelByteUe4SdkCustomization
   * copied spec/Client into Source/AccelByteUe4SdkCustomization/spec/Client
   * copied spec/GameServer into Source/AccelByteUe4SdkCustomization/spec/GameServer
   * copied spec/Models into Source/AccelByteUe4SdkCustomization/spec/Models
   * generated guild Client API Source
   * generated guild Client API Header
   * generated guild GameServer API Source
   * generated guild GameServer API Header
   * generated guild Models
   { "services": [ { "file_stem": "guild", "path": "guild" } ] }
   { "services": [ { "file_stem": "guild", "path": "guild" } ] }
   * generated Client Config Source
   * generated Client Config Header
   * generated GameServer Config Source
   * generated GameServer Config Header

4. Add AccelByteUe4SdkCustomization into PublicDependencyModuleNames of your project .Build.cs file.

   PublicDependencyModuleNames.AddRange(new string[] { …, "AccelByteUe4SdkCustomization" });

5. Add the AccelByteUe4SdkCustomization module in the AccelByteUe4Sdk.uplugin file.

   {
      "Name": "AccelByteUe4SdkCustomization",
      "Type": "Runtime",
      "LoadingPhase": "PreDefault"
   }

Integrate Extend Service Extension API into your Unreal project

1. Include the API from the AccelByteUe4SdkCustomization plugin.

   // #include "Api/AccelByte<ApiName>Api.h"
   #include "Api/AccelByteGuildApi.h"

2. Call the API function.

   FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();
   // ApiClient->GetApiPtr<AccelByte::Api::<ApiName>>()->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 Unreal.