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

Last updated on June 23, 2025

Overview

This article provides a step-by-step guide on how to generate a custom service plugin for the AccelByte Unreal SDK using the Extend Codegen CLI template pack.

A custom service plugin allows developers to leverage the AccelByte Unreal SDK to interact with custom service APIs, such as those created with the Extend Service Extension.

The Extend Codegen CLI template pack consists of a Makefile and some Jinja template files. To generate the necessary code, simply invoke a single make command. This command triggers the Extend Codegen CLI to process the Jinja template files alongside an OpenAPI 2.0 JSON file, which outlines the custom service APIs, to generate the corresponding 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. AccelByte Unreal SDK.

3. Extend Codegen CLI template pack zip for AccelByte Unreal SDK.

4. A valid OpenAPI 2.0 JSON file for your custom service.

   ヒント

   In an Extend Service Extension project, you can generate an OpenAPI 2.0 JSON file without running or deploying the service: First, ensure that the base_path property in the service.proto file matches the actual base path when the service is deployed and update it if needed. Then, run make proto in the project folder, and the file will be saved at gateway/apidocs/service.swagger.json.

Generate Unreal SDK Plugin for Extend Service Extension

1. Place the OpenAPI 2.0 JSON file for your custom service in the my-unreal-project/spec folder. In this example, the file is named guild.json. Next, copy the guild.json file into the following three folders: Client, GameServer, and 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 Extend Codegen CLI 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 generating code.

   注意

   When working with multiple OpenAPI 2.0 JSON files, identical basePath values across files may cause issues in the generated code: We recommend ensuring that each OpenAPI 2.0 JSON file has a unique basePath value that matches the actual base path when the service is deployed.

2. Unzip the downloaded Extend Codegen CLI template pack, navigate to the extracted folder, and run the make command to generate the code.

   unzip accelbyte-unreal-sdk-template-pack.zip

   cd accelbyte-unreal-sdk-template-pack/

   make all \
      CODEGEN_IMAGE_VERSION=x.x.x-alpha \
      PROJECT_PATH=/path/to/my-unreal-project \
      SPEC_PATH=/path/to/my-unreal-project/spec \
      PACKAGE_TYPE=plugin \
      ADMIN_API_PATH=/admin/

   important

   • The CODEGEN_IMAGE_VERSION can be found here. For new projects, it is recommended to use the latest available version.
   • The PROJECT_PATH and SPEC_PATH come from step 1.
   • The PACKAGE_TYPE has two options:
     • module: Generates as a module within the AccelByteUe4Sdk plugin.
     • plugin: Generates as a standalone plugin named AccelByteUe4SdkCustomization.
   • If ADMIN_API_PATH is specified, the ServerAPI will include any endpoints with the specified path, while the ClientAPI will include all other endpoints. If ADMIN_API_PATH is not specified, both ServerAPI and ClientAPI will include all available endpoints.
   • If the Plugins folder does not exist in your Unreal project, you will need to create it manually.

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

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

4. [OPTIONAL] If PACKAGE_TYPE is set to module, you need to 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 = AccelByteOnlineSubsystemPtr->GetApiClient();
   // ApiClient->GetApiPtr<AccelByte::Api::<ApiName>>()->SomeFunction(...);

   ヒント

   If you need to override the ServerUrl of your custom service and/or the basePath, refer to the guide for Enabling environment switching for Unreal.