Use Extend Codegen CLI to generate Unreal 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 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.

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

      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 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
    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.
    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(...);
    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 Unreal.

Last updated on

On this page