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

Last updated on February 5, 2026

Overview​

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

A custom service module allows developers to leverage the AccelByte Unity 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 Unity SDK.

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

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

    b. Extract: Unzip to a working directory (e.g., ~/Downloads/accelbyte-unity-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 package 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 Unity SDK installed in your Unity project.

    tip

    If you haven't integrated the AccelByte Unity SDK yet, follow the Unity SDK setup guide first. The generated custom service plugin depends on the base AccelByte Unity 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 Unity SDK Plugin for Extend Service Extension​

  1. Place the OpenAPI 2.0 JSON file for your custom service in the my-unity-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-unity-project/
    |__ Assets/
    |__ Library/
    |__ Packages/
    |__ ProjectSettings/
    |__ 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-unity-sdk-template-pack.zip
    cd accelbyte-unity-sdk-template-pack/
    make all \
       CODEGEN_IMAGE_VERSION=0.0.28 \
       PROJECT_PATH=/path/to/my-unity-project \
       SPEC_PATH=/path/to/my-unity-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 Unity project root (where Assets folder 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 AccelByte Unity SDK package.
      • plugin (recommended): Generates as a standalone package named com.AccelByte.SDK.Custom in your project's parent directory.
    • 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 (.cs files) is written to PROJECT_PATH/../com.AccelByte.SDK.Custom/ (for PACKAGE_TYPE=plugin).
    5. The package structure includes:
      • Runtime/Api/ - API client classes
      • Runtime/Models/ - Data models
      • package.json - Unity package manifest
      • Runtime/AccelByte.Sdk.Custom.asmdef - Assembly definition
    caution

    Before running the make command:

    • Close Unity Editor before generating code to avoid file lock issues and assembly reload problems.
    • If regenerating code, consider backing up any manual modifications to the generated package.
    • When modifying or replacing the OpenAPI 2.0 JSON file, remove any leftover generated files to avoid compilation errors.
    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. Verify the generated package files.

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

    ls -la /path/to/com.AccelByte.SDK.Custom/

    Expected output (for PACKAGE_TYPE=plugin):

    com.AccelByte.SDK.Custom/
    |__ package.json
    |__ Runtime/
        |__ AccelByte.Sdk.Custom.asmdef
        |__ Api/
        |   |__ Guild.cs
        |__ Models/
            |__ GuildModels.cs
    tip

    Key files to check:

    • package.json: Unity package manifest with name, version, and dependencies
    • AccelByte.Sdk.Custom.asmdef: Assembly definition referencing the base AccelByte SDK
    • Api/<ServiceName>.cs: API client classes (e.g., Guild.cs for guild.json)
    • Models/<ServiceName>Models.cs: Data models for request/response structures

  4. Add com.accelbyte.unitysdk.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"
      }
    }
    info

    Unity will automatically reload the package when you reopen the Unity Editor or modify manifest.json. You can verify the package is loaded by checking the Package Manager window (Window > Package Manager > In Project).

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.

    note

    The proper and simpler way to call the Custom SDK function will be available in release 2026.2.

    For the legacy version, it is required to create an extension class to access the generated custom SDK functionalities. The following snippet is the extension class example

    /// <summary>
    /// Extension class to add ServerGuild service to ServerApiClient
    /// </summary>
    public static class ServerApiClientCustomExtensions
    {
       /// <summary>
       /// Prepare the temporary variable to return the actual custom SDK class
       /// </summary>
       private static ServerGuild serverGuildService;

       /// <summary>
       /// Get or create the ServerGuildService instance
       /// </summary>
       public static ServerGuild GetServerGuild(this ServerApiClient apiClient)
       {
          if (serverGuildService == null)
          {
                // Get dependencies from the ServerApiClient
                var httpClient = new AccelByteHttpClient();
                var clientConfig = AccelByteSDK.GetServerConfig();
                var coroutineRunner = new CoroutineRunner();

                // Create the API and wrapper
                var guildApi = new ServerGuildApi(httpClient, clientConfig, apiClient.session);
                serverGuildService = new ServerGuild(guildApi, apiClient.session, coroutineRunner);
          }

          return serverGuildService;
       }
    }

    Then you can call it as follows

    // Get the Guild service using extension method
    var serverGuildService = AccelByteSDK.GetServerRegistry().GetApi().GetServerGuild();

    // Call the Generated API
    serverGuildService.ServiceCreateOrUpdateGuildProgress();

    // Call the API using the generated wrapper
    string guildId = "any-guild-id";
    Result<AccelByteGuildServiceGetGuildProgressResponse> result = null;
    serverGuildService.ServiceGetGuildProgress(guildId, callback =>
    {
       if (callback.IsError)
       {
          UnityEngine.Debug.LogWarning($"Failed to get Guild progress [{callback.Error.Code}] {callback.Error.Message}");
       }
       else
       {
          // Do something with the callback result
          result = callback;
       }
    });
    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 Unity.

Additional Resources​

Understanding the Code Generation Process​

The Extend Codegen CLI uses a template-based approach powered by Jinja2 to generate Unity 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 Unity package with API classes, models, and Unity package system integration

Template Structure​

The template pack generates code from these main templates:

  • Client-operations.j2 → Client API classes
  • Client-wrapper.j2 → Client API wrapper classes
  • GameServer-operations.j2 → Server API classes
  • operations-models.j2 → Model classes for request/response structures
  • package.j2 → Unity package manifest (package.json)

File Naming Convention​

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

OpenAPI FileGenerated API ClassGenerated ModelsGenerated Wrapper
guild.jsonGuild.csGuildModels.csGuildWrapper.cs
tournament.jsonTournament.csTournamentModels.csTournamentWrapper.cs
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 Unity​

Symptom: Compilation errors in Unity Console after adding the generated package.

Common causes and solutions:

  1. Missing AccelByte SDK dependency:

    • Error: The type or namespace name 'AccelByte' could not be found
    • Solution: Ensure AccelByte Unity SDK is installed and listed in Packages/manifest.json before the custom package

  2. Duplicate symbols or conflicting basePath:

    • Error: Type 'SomeModel' already exists or similar
    • 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. Package not loaded:

    • Error: Package doesn't appear in Unity Package Manager
    • Solution: Check package.json is valid JSON and the path in Packages/manifest.json is correct

  5. Assembly definition errors:

    • Error: Assembly 'AccelByte.Sdk.Custom' has a reference to 'AccelByte.Sdk' which is not defined
    • Solution: Verify the base AccelByte SDK assembly definition is present and the custom package's .asmdef references it correctly

  6. 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 Unity 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 packages separately and use different package 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
    • Implement custom behavior in your game code, not in the package
    • Use partial classes if the generated code supports them
  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

Unity Editor doesn't recognize the new package​

Symptom: Package doesn't appear in Package Manager or code doesn't compile after adding to manifest.json.

Solution:

  1. Close and reopen Unity Editor to force package reload
  2. Check Unity Console for package loading errors
  3. Verify the package path in manifest.json is correct (relative to Packages folder)
  4. Ensure package.json has valid JSON syntax and required fields (name, version, displayName)
  5. Try removing and re-adding the package in manifest.json

Leftover files cause compilation errors​

Symptom: Errors about duplicate types or missing references after modifying OpenAPI spec.

Solution:

  1. Delete the entire com.AccelByte.SDK.Custom folder before regenerating
  2. Remove the package from Packages/manifest.json temporarily
  3. Regenerate the code with the updated OpenAPI spec
  4. Re-add the package to Packages/manifest.json
  5. Restart Unity Editor

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
  • Unity version and AccelByte SDK version
Last updated on
On this page