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

Last updated on January 27, 2026

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 module allows developers to leverage the AccelByte Unreal SDK to interact with custom service APIs. This includes services created with the Extend Service Extension, as well as any other custom service that provides an OpenAPI 2.0 specification.

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. Extend Codegen CLI template pack ZIP for AccelByte Unreal SDK.

   The template pack contains a Makefile and Jinja2 templates that drive the code generation process.

   a. Download: Get the latest accelbyte-unreal-sdk-template-pack.zip from GitHub Releases.

   b. Extract: Unzip to a working directory (e.g., ~/Downloads/accelbyte-unreal-sdk-template-pack/).

   c. Contents: The template pack includes:

   • Makefile - Build automation script that orchestrates code generation
   • config.yaml - Configuration for Jinja2 template rendering
   • templates/ - Jinja2 templates for generating C++ code
   • res/ - Base plugin structure and resources
   • version.txt - Template pack version (e.g., 0.0.28)
   tip

   The Makefile automatically pulls the Docker image when you run the make command, so you don't need to manually download or install the Extend Codegen CLI.

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

   info

   The make command in the template pack uses Docker to run the Extend Codegen CLI. The Docker image (accelbyte/extend-codegen-cli) is automatically pulled if not already cached locally.

3. AccelByte Unreal SDK installed in your Unreal project.

   tip

   If you haven't integrated the AccelByte Unreal SDK yet, follow the Unreal SDK setup guide first. The generated custom service plugin depends on the base AccelByte Unreal SDK.

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

   info

   If your custom service uses the Extend Service Extension, an OpenAPI 2.0 JSON file is automatically generated when the app is deployed in AccelByte Gaming Services (AGS). To access it, open the AGS Admin Portal, navigate to your app's App Details page, click Open API Documentation, and find the JSON file link at the top of the Swagger UI page.

   Alternatively, if you need to get the OpenAPI 2.0 JSON file before deploying your app in AGS, see here.

   tip

   Validating your OpenAPI 2.0 JSON file: Before proceeding, validate your OpenAPI spec using tools like Swagger Editor. Invalid specs will cause codegen errors.

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.

   caution

   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=0.0.28 \
      PROJECT_PATH=/path/to/my-unreal-project \
      SPEC_PATH=/path/to/my-unreal-project/spec \
      PACKAGE_TYPE=plugin \
      ADMIN_API_PATH=/admin/

   info

   Make command parameters:

   • CODEGEN_IMAGE_VERSION: Docker image version from Docker Hub. Use the latest version listed (e.g., 0.0.28). Check version.txt in the template pack for the recommended version.
   • PROJECT_PATH: Absolute path to your Unreal project root (where .uproject file is located). Must match the path from step 1.
   • SPEC_PATH: Absolute path to the spec folder containing your OpenAPI 2.0 JSON files. Must match the path from step 1.
   • PACKAGE_TYPE: Choose one of two options:
     • module: Generates as a module within the existing AccelByteUe4Sdk plugin (requires modifying AccelByteUe4Sdk.uplugin).
     • plugin (recommended): Generates as a standalone plugin named AccelByteUe4SdkCustomization in your project's Plugins folder.
   • ADMIN_API_PATH (optional): Separates admin/server endpoints from client endpoints:
     • If specified (e.g., /admin/), ServerAPI includes endpoints with this path prefix, ClientAPI includes all others.
     • If not specified, both ServerAPI and ClientAPI include all available endpoints.
   tip

   What happens during code generation:

   1. Docker pulls the accelbyte/extend-codegen-cli:<version> image (if not already cached).
   2. The CLI reads your OpenAPI 2.0 JSON files from SPEC_PATH.
   3. Jinja2 templates from the template pack are processed with your OpenAPI spec data.
   4. Generated C++ code (.h and .cpp files) is written to PROJECT_PATH/Plugins/AccelByteUe4SdkCustomization/ (for PACKAGE_TYPE=plugin).
   5. The plugin structure includes:
      • Source/AccelByteUe4SdkCustomization/Public/Api/ - API client classes
      • Source/AccelByteUe4SdkCustomization/Public/Models/ - Data models
      • Source/AccelByteUe4SdkCustomization/AccelByteUe4SdkCustomization.Build.cs - Build configuration
      • AccelByteUe4SdkCustomization.uplugin - Plugin descriptor
   caution

   Before running the make command:

   • Ensure the Plugins folder exists in your Unreal project. If it doesn't exist, create it manually: mkdir -p /path/to/my-unreal-project/Plugins
   • Close Unreal Editor before generating code to avoid file lock issues.
   • If regenerating code, consider backing up any manual modifications to the generated plugin.
   tip

   [OPTIONAL] Manually pulling the Docker image: While the make command automatically pulls the Docker image, you can pre-download it to verify connectivity or cache it:

   docker pull accelbyte/extend-codegen-cli:0.0.28

   To check the version and verify the image:

   docker run --rm accelbyte/extend-codegen-cli:0.0.28 info

   Expected output:

   version: 0.0.28
   hash: 6b93fa76ad531938c02b1be7e0ab0958fad8c72d
   glibc: 2.31
   sub-packages:
     accelbyte-codegen-ext-openapi2-legacy:
       version: 0.0.28
       description: AccelByte Code Generator [Open API 2.0 - Legacy]

   To see available commands:

   docker run --rm accelbyte/extend-codegen-cli:0.0.28 --help

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

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

4. Verify the generated plugin files.

   After running the make command, verify that the plugin was generated successfully:

   ls -la /path/to/my-unreal-project/Plugins/AccelByteUe4SdkCustomization/

   Expected output (for PACKAGE_TYPE=plugin):

   AccelByteUe4SdkCustomization/
   |__ AccelByteUe4SdkCustomization.uplugin
   |__ Resources/
   |   |__ Icon128.png
   |__ Source/
       |__ AccelByteUe4SdkCustomization/
           |__ AccelByteUe4SdkCustomization.Build.cs
           |__ Private/
           |   |__ AccelByteUe4SdkCustomizationModule.cpp
           |__ Public/
               |__ Api/
               |   |__ AccelByteGuildApi.h
               |   |__ AccelByteGuildApi.cpp
               |__ Models/
                   |__ AccelByteGuildModels.h

   tip

   Key files to check:

   • AccelByteUe4SdkCustomization.uplugin: Plugin descriptor with metadata and module definitions
   • AccelByte<ServiceName>Api.h/cpp: API client classes (e.g., AccelByteGuildApi.h for guild.json)
   • AccelByte<ServiceName>Models.h: Data models for request/response structures
   • AccelByteUe4SdkCustomization.Build.cs: Build configuration with dependencies

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

   tip

   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.

Additional Resources

• Extend Codegen CLI GitHub Repository - Source code, documentation, and issue tracker
• Extend Codegen CLI Docker Hub - Available Docker image versions
• Jinja2 Documentation - Official Jinja2 template engine documentation
• OpenAPI 2.0 Specification - OpenAPI 2.0 (Swagger) specification reference

Understanding the Code Generation Process

The Extend Codegen CLI uses a template-based approach powered by Jinja2 to generate Unreal SDK code:

1. Input: OpenAPI 2.0 JSON file(s) describing your custom service API
2. Processing: The CLI parses the spec using OA2LegacyProcessor to extract endpoints, models, and parameters
3. Template Rendering: Jinja2 templates in templates/sdk_customization/ are populated with parsed data
4. Output: Complete Unreal Engine plugin with API classes, models, and build system integration

Template Structure

The template pack generates code from these main templates:

• Client-operations-decl.j2 / Client-operations-def.j2 → Client API headers and implementations
• GameServer-operations-decl.j2 / GameServer-operations-def.j2 → Server API headers and implementations
• operations-models.j2 → Model classes for request/response structures
• Client-settings-decl.j2 / Client-settings-def.j2 → Configuration classes

File Naming Convention

Generated files use the OpenAPI JSON filename (converted to PascalCase):

OpenAPI File	Generated API Header	Generated API Implementation	Generated Models
guild.json	AccelByteGuildApi.h	AccelByteGuildApi.cpp	AccelByteGuildModels.h
tournament.json	AccelByteTournamentApi.h	AccelByteTournamentApi.cpp	AccelByteTournamentModels.h

tip

For a deep dive into Jinja2 templates, custom filters, and advanced debugging techniques, see Extend Codegen CLI - Templates and Debugging.

Troubleshooting

Code generation fails with "Docker not found"

Symptom: make: docker: Command not found or similar error.

Solution:

1. Verify Docker is installed: docker --version
2. Ensure Docker daemon is running: docker ps
3. Check user permissions: docker run hello-world
4. If permission denied, add user to docker group: sudo usermod -aG docker $USER and log out/in

Code generation fails with "Invalid OpenAPI specification"

Symptom: Codegen CLI reports validation errors or fails to parse the OpenAPI JSON file.

Solution:

1. Validate your OpenAPI 2.0 spec using Swagger Editor
2. Ensure the spec version is OpenAPI 2.0 (not 3.0+)
3. Check for:
   • Missing required fields (swagger, info, paths)
   • Invalid JSON syntax (trailing commas, unquoted keys)
   • Undefined schema references ($ref pointing to non-existent definitions)
4. If using Extend Service Extension, ensure the app is deployed and the OpenAPI spec is generated correctly

Generated code doesn't compile in Unreal

Symptom: Build errors in Unreal Editor after adding the generated plugin.

Common causes and solutions:

1. Missing AccelByte SDK dependency:

   • Error: Cannot open include file: 'Core/AccelByteRegistry.h'
   • Solution: Ensure AccelByte Unreal SDK is installed and added to your project's dependencies

2. Duplicate symbols or conflicting basePath:

   • Error: Multiple definitions of... or linking errors
   • Solution: Ensure each OpenAPI JSON file has a unique basePath value

3. Invalid C++ identifiers:

   • Error: Syntax errors in generated code
   • Solution: Use lowercase alphabets (a-z) for OpenAPI JSON filenames. Avoid special characters, numbers, or uppercase letters.

4. Plugin not loaded:

   • Error: Plugin 'AccelByteUe4SdkCustomization' failed to load
   • Solution: Check AccelByteUe4SdkCustomization.uplugin is valid JSON and the plugin is enabled in your .uproject file

5. Outdated template pack:

   • Error: Generated code uses deprecated SDK APIs
   • Solution: Download the latest template pack from GitHub Releases

API calls return 404 or fail at runtime

Symptom: Generated API functions compile but fail when called from your game code.

Solution:

1. Verify the custom service is deployed and accessible
2. Check the ServerUrl configuration in your Unreal project settings
3. Ensure the basePath in the OpenAPI spec matches the deployed service's base path
4. Enable SDK logging to inspect the actual HTTP requests being made

Multiple OpenAPI specs cause conflicts

Symptom: Compilation errors when using multiple custom services.

Solution:

1. Ensure each OpenAPI JSON file has a unique basePath value (e.g., /guild, /tournament, /leaderboard)
2. Use unique filenames for each service (e.g., guild.json, tournament.json)
3. Verify no duplicate endpoint paths across different specs
4. If conflicts persist, generate plugins separately and use different plugin names

Regenerating code overwrites manual changes

Symptom: Custom modifications to generated code are lost when regenerating.

Solution:

1. Don't modify generated code directly. Instead:
   • Create wrapper classes that extend or compose the generated API classes
   • Use Unreal's blueprint system to add custom logic
   • Implement custom behavior in your game code, not in the plugin
2. If you must modify generated code, maintain a separate patch file or version control branch
3. Consider contributing improvements to the template pack if the generated code is insufficient

Docker image pull fails or is slow

Symptom: make command hangs or fails during Docker image download.

Solution:

1. Check internet connectivity: ping hub.docker.com
2. Verify Docker Hub is accessible: docker pull hello-world
3. If behind a corporate proxy, configure Docker proxy settings
4. Use a specific image version instead of latest to avoid re-downloading
5. Pre-pull the image manually: docker pull accelbyte/extend-codegen-cli:0.0.28

Need to debug the code generation process

Symptom: Generated code is incorrect or missing expected functionality.

Steps to debug:

1. Inspect the OpenAPI spec: Ensure endpoints, models, and parameters are defined correctly
2. Check the Jinja2 templates: Located in the template pack, these define how code is generated
3. Review the Makefile: Shows the exact docker run command and parameters passed to the CLI
4. Run with verbose logging: Add VERBOSE=1 to the make command to see detailed output
5. Use --inspect verbose to explore the template environment: This powerful debugging tool reveals all available Jinja2 filters, functions, globals, and tests. See the Templates and Debugging guide for detailed usage.
6. Compare with working examples: Check the template pack's example specs and generated output

tip

For additional support, refer to the Extend Codegen CLI GitHub repository or contact AccelByte support with:

• Your OpenAPI 2.0 JSON file
• The exact make command used
• Full error output from the code generation process
• Unreal Engine version and AccelByte SDK version