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

Last updated on April 6, 2026

Overview​

This guide shows the shortest path to generate a Unity package for a custom service by using the Extend Codegen CLI.

Use this flow when you already have:

tip

If your service is an Extend Service Extension app, you can get its OpenAPI 2.0 JSON from the AGS Admin Portal on the app's Open API Documentation page.

If you need the OpenAPI file before deployment, see Generate Service Extension OpenAPI without deploying.

Before You Start​

Prepare these items first:

  1. A Unity project with the AccelByte Unity SDK already installed.
  2. A Linux environment or Windows 11 WSL2 with bash, make, and Docker available.
  3. A valid OpenAPI 2.0 JSON file for your custom service.
  4. The accelbyte-unity-sdk-template-pack.zip file.
tip

You can get its OpenAPI 2.0 JSON from the AGS Admin Portal on the app's Open API Documentation page. If you need the OpenAPI file before deployment, see Generate Service Extension OpenAPI without deploying.

Validate the OpenAPI file with Swagger Editor before running code generation. Invalid specs are the most common reason generation fails.

Quick Start​

1. Pull the Extend Codegen CLI Docker image​

docker pull accelbyte/extend-codegen-cli:0.0.29

2. Download and extract the Unity template pack​

wget https://github.com/AccelByte/extend-codegen-cli/releases/download/v0.0.29/accelbyte-unity-sdk-template-pack.zip
unzip accelbyte-unity-sdk-template-pack.zip

3. Open the extracted folder​

cd accelbyte-unity-sdk-template-pack/

4. Prepare the spec folder​

Create a spec folder in your Unity project, then place the same OpenAPI file in the root and in these three subfolders:

  • spec/Client
  • spec/GameServer
  • spec/Models

Example:

/path/to/my-unity-project/
|__ Assets/
|__ Packages/
|__ ProjectSettings/
|__ spec/
   |__ Client/
   |   |__ guild.json
   |__ GameServer/
   |   |__ guild.json
   |__ Models/
   |   |__ guild.json
   |__ guild.json
important

Use a simple lowercase filename such as guild.json. The template pack uses that filename as the service identifier when generating code.

caution

If you generate multiple services, make sure each OpenAPI file uses a unique basePath. Duplicate basePath values can create naming and runtime conflicts.

5. Run code generation​

Run:

make all \
  CODEGEN_IMAGE_VERSION=0.0.29 \
  PROJECT_PATH=/path/to/my-unity-project \
  SPEC_PATH=/path/to/my-unity-project/spec \
  PACKAGE_TYPE=plugin \
  ADMIN_API_PATH=/admin/

Parameter summary:

  • CODEGEN_IMAGE_VERSION: version of accelbyte/extend-codegen-cli to use
  • PROJECT_PATH: Unity project root
  • SPEC_PATH: path to the spec folder
  • PACKAGE_TYPE=plugin: generate a standalone Unity package
  • ADMIN_API_PATH: optional split between client and server endpoints

6. Confirm the package was generated​

For PACKAGE_TYPE=plugin, the generated package is created beside your Unity project:

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

7. Add the package to Unity​

Add the generated package to Packages/manifest.json:

{
  "dependencies": {
    "com.accelbyte.unitysdk": "file:../com.AccelByte.SDK",
    "com.accelbyte.unitysdk.custom": "file:../com.AccelByte.SDK.Custom"
  }
}

Reopen Unity, or let Unity reload the package after manifest.json changes.

Use the Generated API​

Import the SDK namespaces:

using AccelByte.Api;
using AccelByte.Core;
using AccelByte.Models;

Call the generated service through the SDK registry:

Guild guild = AccelByteSDK.GetClientRegistry().GetApi().GetApi<Guild, GuildApi>();
guild.GetGuildProgress("testGuildId", (Result<AccelByteGuildGetGuildProgressResponse> result) =>
{
});
note

A simpler custom SDK access pattern is planned for release 2026.2.

tip

If you need to override the custom service ServerUrl or basePath, see Enabling environment switching for Unity.

Need More Detail?​

Use these references when you need more than the quick start:

Troubleshooting​

make fails before generation starts​

Check these first:

  • Docker is installed and running.
  • Your user can run Docker commands.
  • The OpenAPI file is valid OpenAPI 2.0.

Unity cannot load the generated package​

Check these items:

  • Packages/manifest.json points to the correct relative path.
  • package.json exists inside com.AccelByte.SDK.Custom.
  • The base AccelByte Unity SDK package is already installed.

Generated code conflicts with another custom service​

Check these items:

  • Each OpenAPI file uses a unique filename.
  • Each OpenAPI file uses a unique basePath.

Regenerating removes manual edits​

Treat generated files as build output. Keep custom logic in your own project code instead of editing the generated package directly.

Last updated on
On this page