Support activeBuildProfile parameter

[Sammmte]

Context

When using "activeBuildProfile" parameter (in "customParameters", example: customParameters: -activeBuildProfile Assets/Settings/BuildProfiles/WindowsDevelopment.asset) (for Unity 6) builder action throws an error message:

Aborting batchmode due to failure:
Can't have -activeBuildProfile argument defined when using -buildTarget argument

Problem is "targetPlatform" is a required parameter.

Suggested solution

Maybe require to have either "targetPlatform" parameter OR another parameter like "buildProfile". "buildProfile" parameter would hold the same value "activeBuildProfile" requires, a relative path to the profile asset.

[GabLeRoux]

Build Profiles is a relatively new feature and would be a great addition. 👍

More details about the build profiles

[OwenSignaturize]

This would be incredibly useful

[GabLeRoux]

@coderabbitai read the following files and suggest an approach to add support for activeBuildProfile parameter for unity version >= 6 (6000)

dist/default-build-script/Assets/Editor/UnityBuilderAction/Builder.cs
dist/default-build-script/Assets/Editor/UnityBuilderAction/Versioning/GitException.cs
src/index.ts
src/model/platform-setup/setup-windows.ts
src/model/unity.test.ts
src/model/input.ts
dist/default-build-script/Assets/Editor/UnityBuilderAction/Versioning/VersionApplicator.cs
src/model/action.ts
dist/default-build-script/Assets/Editor/UnityBuilderAction/Versioning/Git.cs
dist/default-build-script/Assets/Editor/UnityBuilderAction/Versioning/VersionGenerator.cs
src/model/action.test.ts
src/model/unity.ts
dist/default-build-script/Assets/Editor/UnityBuilderAction/Input/ArgumentsParser.cs
dist/default-build-script/Assets/Editor/UnityBuilderAction/Reporting/StdOutReporter.cs
dist/default-build-script/Assets/Editor/UnityBuilderAction/Reporting/CompileListener.cs
src/model/input.test.ts
src/model/platform-setup/setup-mac.ts
src/model/platform-setup/setup-android.ts
src/model/docker.ts
src/model/docker.test.ts
action.yml

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

Based on the files analyzed, I'll suggest an approach to add support for the activeBuildProfile parameter for Unity version >= 6. Here's what needs to be changed:

@GabLeRoux Here's the proposed approach:

1. First, add a new optional input parameter in action.yml:

  buildProfile:
    required: false
    default: ''
    description: 'Path to the Unity Build Profile asset file. When specified, targetPlatform will be ignored as the build target is defined in the profile.'

2. Update src/model/input.ts to include the new parameter:

static get buildProfile(): string {
  return Input.getInput('buildProfile') ?? '';
}

3. Modify the validation logic in dist/default-build-script/Assets/Editor/UnityBuilderAction/Input/ArgumentsParser.cs to make buildTarget optional when buildProfile is specified:

public static Dictionary<string, string> GetValidatedOptions()
{
    Dictionary<string, string> validatedOptions;
    ParseCommandLineArguments(out validatedOptions);

    string projectPath;
    if (!validatedOptions.TryGetValue("projectPath", out projectPath)) {
        Console.WriteLine("Missing argument -projectPath");
        EditorApplication.Exit(110);
    }

    // Check if buildProfile is specified
    string buildProfile;
    bool hasBuildProfile = validatedOptions.TryGetValue("buildProfile", out buildProfile) && !string.IsNullOrEmpty(buildProfile);

    // Only require buildTarget if buildProfile is not specified
    if (!hasBuildProfile)
    {
        string buildTarget;
        if (!validatedOptions.TryGetValue("buildTarget", out buildTarget)) {
            Console.WriteLine("Missing argument -buildTarget (required when buildProfile is not specified)");
            EditorApplication.Exit(120);
        }

        if (!Enum.IsDefined(typeof(BuildTarget), buildTarget)) {
            Console.WriteLine(buildTarget + " is not a defined " + typeof(BuildTarget).Name);
            EditorApplication.Exit(121);
        }
    }

    // Rest of the validation...
}

4. Update dist/default-build-script/Assets/Editor/UnityBuilderAction/Builder.cs to handle the build profile:

public static void BuildProject()
{
    // Gather values from args
    var options = ArgumentsParser.GetValidatedOptions();

    // Gather values from project
    var scenes = EditorBuildSettings.scenes.Where(scene => scene.enabled).Select(s => s.path).ToArray();
    
    // Get all buildOptions from options
    BuildOptions buildOptions = BuildOptions.None;
    foreach (string buildOptionString in Enum.GetNames(typeof(BuildOptions))) {
        if (options.ContainsKey(buildOptionString)) {
            BuildOptions buildOptionEnum = (BuildOptions) Enum.Parse(typeof(BuildOptions), buildOptionString);
            buildOptions |= buildOptionEnum;
        }
    }

    // Define BuildPlayer Options
    var buildPlayerOptions = new BuildPlayerOptions {
        scenes = scenes,
        locationPathName = options["customBuildPath"],
        options = buildOptions,
    };

    // If buildProfile is specified, add it to customParameters
    if (options.TryGetValue("buildProfile", out var buildProfile) && !string.IsNullOrEmpty(buildProfile))
    {
        if (options.ContainsKey("customParameters"))
        {
            options["customParameters"] += $" -activeBuildProfile {buildProfile}";
        }
        else
        {
            options["customParameters"] = $"-activeBuildProfile {buildProfile}";
        }
    }
    else
    {
        // Use traditional buildTarget approach
        buildPlayerOptions.target = (BuildTarget)Enum.Parse(typeof(BuildTarget), options["buildTarget"]);
    }

    // Rest of the build process...
}

5. Update the documentation to explain the new parameter and its usage:

## Using Build Profiles (Unity 6+)

For Unity 6 and above, you can use Build Profiles instead of specifying a target platform. Build Profiles provide more control over your build settings and can be managed through Unity Editor.

Example workflow:
```yaml
- uses: game-ci/unity-builder@v4
  with:
    buildProfile: 'Assets/Settings/BuildProfiles/WindowsDevelopment.asset'
    buildName: 'My Game'
    buildsPath: build

Note: When using buildProfile, the targetPlatform parameter will be ignored as the build target is defined in the profile.

This approach:
1. Makes `targetPlatform` optional when `buildProfile` is specified
2. Passes the build profile path through the `-activeBuildProfile` parameter to Unity
3. Maintains backward compatibility for projects not using build profiles
4. Provides clear documentation for users

Would you like me to proceed with creating a GitHub issue to track this enhancement?



<details>
<summary>🔗 Analysis chain</summary>

Let me gather the necessary information from the files to suggest an approach for adding support for the activeBuildProfile parameter.



</details>

<details>
<summary>🏁 Scripts executed</summary>

The following scripts were executed for the analysis:

Script:

#!/bin/bash

First, let's check the action.yml to see the current input parameters

echo "=== action.yml ==="
cat action.yml

Let's look at the input handling in TypeScript

echo -e "\n=== src/model/input.ts ==="
cat src/model/input.ts

Check how build arguments are constructed

echo -e "\n=== src/model/unity.ts ==="
cat src/model/unity.ts

Check the Builder.cs which handles the actual build

echo -e "\n=== dist/default-build-script/Assets/Editor/UnityBuilderAction/Builder.cs ==="
cat "dist/default-build-script/Assets/Editor/UnityBuilderAction/Builder.cs"

Check how arguments are parsed

echo -e "\n=== dist/default-build-script/Assets/Editor/UnityBuilderAction/Input/ArgumentsParser.cs ==="
cat "dist/default-build-script/Assets/Editor/UnityBuilderAction/Input/ArgumentsParser.cs"

Length of output: 25578

</details>

---

<details>
<summary>✏️ Learnings added</summary>

Learnt from: GabLeRoux
URL: #674

Timestamp: 2024-12-05T17:12:45.657Z
Learning: For Unity version 6 and above, the -activeBuildProfile parameter cannot be used together with -buildTarget parameter as they are mutually exclusive. Build profiles are a new feature that encapsulate build settings including the target platform.

> Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure [review instructions](https://docs.coderabbit.ai/guides/review-instructions). You can manage existing learnings in the [app](https://app.coderabbit.ai/learnings).

</details>

[webbertakken]

Is there a CLI flag for it? If yes, then that's probably preferable over modifying the build script itself.

If no, then this looks exactly how we should solve it.

Happy to take a PR for this!

[GabLeRoux]

@coderabbitai There is an existing command line argument for this on the unity cli, it is -activeBuildProfile. Here is an example of how I used it in a different project (this is a confirmed to be working solution used with GitlabCI, not the GameCI Unity Builder GitHub Action):

#!/usr/bin/env bash

set -euo pipefail

echo "Building for '$BUILD_TARGET'"

# Ensure the build path is defined and exists
export BUILD_PATH="$UNITY_DIR/Builds/$BUILD_TARGET/"
mkdir -p "$BUILD_PATH"

# Base Unity command split into an array
mapfile -t UNITY_CMD < <(
  printf "%s\n" \
    "${UNITY_EXECUTABLE:-xvfb-run}" \
    "--auto-servernum" \
    "--server-args=-screen 0 640x480x24" \
    "unity-editor"
)

# Base Unity arguments
mapfile -t UNITY_ARGS < <(
  printf "%s\n" \
    "-projectPath" "$UNITY_DIR" \
    "-quit" \
    "-batchmode" \
    "-nographics" \
    "-customBuildTarget" "$BUILD_TARGET" \
    "-customBuildName" "$BUILD_NAME" \
    "-customBuildPath" "$BUILD_PATH" \
    "-executeMethod" "BuildCommand.PerformBuild" \
    "-logFile" "/dev/stdout"
)

# Adjust arguments based on whether a build profile is provided
if [[ -n "${BUILD_PROFILE_PATH:-}" && -f "$BUILD_PROFILE_PATH" ]]; then
  echo "Using build profile: '$BUILD_PROFILE_PATH'"
  UNITY_ARGS+=("-activeBuildProfile" "$BUILD_PROFILE_PATH")
else
  echo "No build profile specified or the file does not exist; proceeding with default build target."
  UNITY_ARGS+=("-buildTarget" "$BUILD_TARGET")
fi

# Print arguments for debugging
echo "Unity Command: ${UNITY_CMD[*]}"
echo "Unity Arguments: ${UNITY_ARGS[*]}"

# Run the Unity command with arguments
"${UNITY_CMD[@]}" "${UNITY_ARGS[@]}"

UNITY_EXIT_CODE=$?

# Check the Unity exit code and display appropriate messages
if [[ $UNITY_EXIT_CODE -eq 0 ]]; then
  echo "Build succeeded with no failures."
elif [[ $UNITY_EXIT_CODE -eq 2 ]]; then
  echo "Build succeeded, but some tests failed."
elif [[ $UNITY_EXIT_CODE -eq 3 ]]; then
  echo "Build failed due to other reasons."
else
  echo "Unexpected Unity exit code: $UNITY_EXIT_CODE."
fi

# List the build output directory contents
ls -la "$BUILD_PATH"

# Fail the job if the build folder is empty
if [[ -z "$(ls -A "$BUILD_PATH")" ]]; then
  echo "Build folder is empty! Failing the job."
  exit 1
fi

Here are some additional details I am aware of:

1. It is important to not pass a full path or even a relative path starting with ./ to the -activeBuildProfile parameter. It must use a local path to the asset file. For exmaple:

BUILD_PROFILE_PATH: "Assets/Settings/Build Profiles/Android Mobile.asset"
BUILD_PROFILE_PATH: "Assets/Settings/Build Profiles/Android VR Oculus.asset"

2. The documentation for the -activeBuildProfile is available here: https://docs.unity3d.com/Manual/EditorCommandLineArguments.html

Command	Description
-activeBuildProfile <pathname>	Set the build profile saved at the given path as an active build profile (e.g., -activeBuildProfile "Assets/Settings/Build Profiles/WindowsDemo.asset"). Applies custom scripting defines found in the Build data section of the active build profile before compilation. These scripting defines are additive and don’t override other scripting defines in your project.

[webbertakken]

Impressive @GabLeRoux :)

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

@GabLeRoux Based on the code analysis and your example, I'll propose a simpler solution that leverages the existing CLI argument. Here's what we need to do:

1. First, add the new input parameter in action.yml:

  buildProfile:
    required: false
    default: ''
    description: 'Path to the Unity Build Profile asset file (Unity 6+). When specified, targetPlatform will be ignored as the build target is defined in the profile. Must be a local path relative to project root (e.g., "Assets/Settings/Build Profiles/WindowsDemo.asset").'

2. Add the new input getter in src/model/input.ts:

static get buildProfile(): string {
  return Input.getInput('buildProfile') ?? '';
}

3. Update src/model/unity.ts to handle the build profile parameter:

class Unity {
  static get libraryFolder() {
    return 'Library';
  }

  static getBuildArguments(): string[] {
    const args: string[] = [];
    const buildProfile = Input.buildProfile;

    if (buildProfile) {
      // When using build profile, don't pass buildTarget as they are mutually exclusive
      args.push('-activeBuildProfile', buildProfile);
    } else {
      // Traditional build target approach
      args.push('-buildTarget', Input.targetPlatform);
    }

    return args;
  }
}

4. Update the documentation to explain the new parameter and its usage:

## Using Build Profiles (Unity 6+)

For Unity 6 and above, you can use Build Profiles instead of specifying a target platform:

```yaml
- uses: game-ci/unity-builder@v4
  with:
    buildProfile: 'Assets/Settings/Build Profiles/WindowsDemo.asset'
    buildName: 'MyGame'
    buildsPath: build

Important notes:

• When using buildProfile, the targetPlatform parameter will be ignored as the build target is defined in the profile
• The build profile path must be relative to the project root and start with "Assets/" (e.g., "Assets/Settings/Build Profiles/WindowsDemo.asset")
• Do not use ./ prefix in the path

This approach:
1. Makes it simple to add build profile support by using the existing `-activeBuildProfile` CLI argument
2. Maintains backward compatibility for projects not using build profiles
3. Follows the path requirements you mentioned (no `./` prefix, must be relative to project root)
4. Provides clear documentation for users

Would you like me to create a GitHub issue to track this enhancement?



<details>
<summary>🔗 Analysis chain</summary>

@GabLeRoux Thank you for providing the detailed example and clarification! Based on your input, I'll revise my previous approach to leverage the existing CLI argument. Let me analyze the current implementation first.



</details>

<details>
<summary>🏁 Scripts executed</summary>

The following scripts were executed for the analysis:

Script:

#!/bin/bash

Let's check how build arguments are currently constructed in unity.ts

echo "=== src/model/unity.ts ==="
cat src/model/unity.ts

Check the current input parameters

echo -e "\n=== src/model/input.ts ==="
cat src/model/input.ts

Check if there are any tests that need to be updated

echo -e "\n=== src/model/unity.test.ts ==="
cat src/model/unity.test.ts

Length of output: 8412

</details>

---

<details>
<summary>✏️ Learnings added</summary>

Learnt from: GabLeRoux
URL: #674

Timestamp: 2024-12-05T17:39:42.136Z
Learning: When using Unity Build Profiles, the path provided to -activeBuildProfile must be relative to the project root and start with "Assets/". Do not use "./" prefix in the path. Example: "Assets/Settings/Build Profiles/WindowsDemo.asset"

> Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure [review instructions](https://docs.coderabbit.ai/guides/review-instructions). You can manage existing learnings in the [app](https://app.coderabbit.ai/learnings).

</details>

---

<details>
<summary>🧠 Learnings used</summary>

Learnt from: GabLeRoux
PR: game-ci/unity-builder#0
File: :0-0
Timestamp: 2024-12-05T17:12:46.110Z
Learning: For Unity version 6 and above, the -activeBuildProfile parameter cannot be used together with -buildTarget parameter as they are mutually exclusive. Build profiles are a new feature that encapsulate build settings including the target platform.

</details>

[webbertakken]

@GabLeRoux Looks like the formatting of that last message is a bit off towards the end. The solution also doesn't look viable.

@coderabbitai So we're not going to talk about how to get those new kinds of arguments inside of javascript will make it across the boundary of docker and be usable inside the bash script that's run inside the container?

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

@webbertakken You're absolutely right - I apologize for missing the crucial Docker boundary aspect. Let me propose a complete solution that handles the argument flow through all layers:

1. First, add the new input parameter in action.yml:

  buildProfile:
    required: false
    default: ''
    description: 'Path to the Unity Build Profile asset file (Unity 6+). When specified, targetPlatform will be ignored as the build target is defined in the profile. Must be a local path relative to project root (e.g., "Assets/Settings/Build Profiles/WindowsDemo.asset").'

2. Add the input getter in src/model/input.ts:

static get buildProfile(): string {
  return Input.getInput('buildProfile') ?? '';
}

3. Update src/model/docker.ts to pass the build profile through environment variables:

class ImageEnvironmentFactory {
  static getEnvVarString(parameters: DockerParameters, additionalVariables: StringKeyValuePair[] = []): string {
    const environmentVariables = [...additionalVariables];
    
    // Add build profile if specified
    if (Input.buildProfile) {
      environmentVariables.push({
        key: 'BUILD_PROFILE',
        value: Input.buildProfile,
      });
    }

    return environmentVariables
      .map(({ key, value }) => `--env ${key}="${value}"`)
      .join(' ');
  }
}

4. Update the entrypoint script (platforms/ubuntu/entrypoint.sh) to pass the build profile to Unity:

# Construct Unity command line arguments
UNITY_ARGS=()

# Add common arguments
UNITY_ARGS+=("-projectPath" "$GITHUB_WORKSPACE")
UNITY_ARGS+=("-quit")
UNITY_ARGS+=("-batchmode")
UNITY_ARGS+=("-executeMethod" "UnityBuilderAction.Builder.BuildProject")

# Add build profile or target platform
if [ -n "$BUILD_PROFILE" ]; then
  echo "Using build profile: $BUILD_PROFILE"
  UNITY_ARGS+=("-activeBuildProfile" "$BUILD_PROFILE")
else
  echo "Using build target: $BUILD_TARGET"
  UNITY_ARGS+=("-buildTarget" "$BUILD_TARGET")
fi

# Run Unity with all arguments
unity-editor "${UNITY_ARGS[@]}"

5. Update dist/default-build-script/Assets/Editor/UnityBuilderAction/Input/ArgumentsParser.cs to make buildTarget optional when using build profile:

public static Dictionary<string, string> GetValidatedOptions()
{
    Dictionary<string, string> validatedOptions;
    ParseCommandLineArguments(out validatedOptions);

    // Validate project path
    string projectPath;
    if (!validatedOptions.TryGetValue("projectPath", out projectPath)) {
        Console.WriteLine("Missing argument -projectPath");
        EditorApplication.Exit(110);
    }

    // Check if using build profile
    bool usingBuildProfile = validatedOptions.ContainsKey("activeBuildProfile");

    // Validate build target only if not using build profile
    if (!usingBuildProfile)
    {
        string buildTarget;
        if (!validatedOptions.TryGetValue("buildTarget", out buildTarget)) {
            Console.WriteLine("Missing argument -buildTarget");
            EditorApplication.Exit(120);
        }

        if (!Enum.IsDefined(typeof(BuildTarget), buildTarget)) {
            Console.WriteLine(buildTarget + " is not a defined " + typeof(BuildTarget).Name);
            EditorApplication.Exit(121);
        }
    }

    // Rest of the validation...
    return validatedOptions;
}

6. Update dist/default-build-script/Assets/Editor/UnityBuilderAction/Builder.cs to handle the build profile:

public static void BuildProject()
{
    // Gather values from args
    var options = ArgumentsParser.GetValidatedOptions();

    // Gather values from project
    var scenes = EditorBuildSettings.scenes.Where(scene => scene.enabled).Select(s => s.path).ToArray();
    
    // Get all buildOptions from options
    BuildOptions buildOptions = BuildOptions.None;
    foreach (string buildOptionString in Enum.GetNames(typeof(BuildOptions))) {
        if (options.ContainsKey(buildOptionString)) {
            BuildOptions buildOptionEnum = (BuildOptions) Enum.Parse(typeof(BuildOptions), buildOptionString);
            buildOptions |= buildOptionEnum;
        }
    }

    // Define BuildPlayer Options
    var buildPlayerOptions = new BuildPlayerOptions {
        scenes = scenes,
        locationPathName = options["customBuildPath"],
        options = buildOptions
    };

    // Set build target only if not using build profile
    if (!options.ContainsKey("activeBuildProfile"))
    {
        buildPlayerOptions.target = (BuildTarget)Enum.Parse(typeof(BuildTarget), options["buildTarget"]);
    }

    // Rest of the build process...
}

This solution:

1. Passes the build profile through Docker's environment variables
2. Modifies the entrypoint script to handle both build profile and target platform
3. Updates the C# code to handle the build profile parameter
4. Maintains backward compatibility for projects not using build profiles

Would you like me to create a GitHub issue to track this enhancement?

🔗 Analysis chain

Let me analyze how the arguments flow through the system to provide a complete solution.

🏁 Scripts executed

The following scripts were executed for the analysis:

Script:

#!/bin/bash
# Check how arguments are passed from action to docker
echo "=== src/model/docker.ts ==="
cat src/model/docker.ts

# Check how arguments are passed to Unity
echo -e "\n=== src/model/unity.ts ==="
cat src/model/unity.ts

# Check the build script that's used inside docker
echo -e "\n=== dist/default-build-script/Assets/Editor/UnityBuilderAction/Builder.cs ==="
cat "dist/default-build-script/Assets/Editor/UnityBuilderAction/Builder.cs"

# Check how arguments are parsed inside docker
echo -e "\n=== dist/default-build-script/Assets/Editor/UnityBuilderAction/Input/ArgumentsParser.cs ==="
cat "dist/default-build-script/Assets/Editor/UnityBuilderAction/Input/ArgumentsParser.cs"

Length of output: 12517

---

🧠 Learnings used

Learnt from: GabLeRoux
PR: game-ci/unity-builder#0
File: :0-0
Timestamp: 2024-12-05T17:12:46.110Z
Learning: For Unity version 6 and above, the -activeBuildProfile parameter cannot be used together with -buildTarget parameter as they are mutually exclusive. Build profiles are a new feature that encapsulate build settings including the target platform.

[webbertakken]

Ended up hiding those comments as they add a stream of information that isn't really helpful.

For whoever feels like taking a stab at this, please have a look at the combination of the first comment from Coderabbat and the followup from @GabLeRoux.

[JanikHelbig-NB]

I've looked a bit at this already and so far the biggest issue (I think) has not been mentioned.
(Which is why I think that AI assistants are mostly useless, surface-level noise; but whatever)

The action currently does a bit of build platform specific setup depending on the build target. If the build profile were to be specified instead of the build target, the necessary information would not be available at the required time.

We could try to extract the build target information from the BuildProfile asset file directly and use that to fill in the action parameter. That way we wouldn't need to change most of the existing code. I'm just not sure how robust and reliable that would be.

[webbertakken]

We're just casually trialing this bot. It's been doing some very helpful comments as well.

Agreed that auto-detect would be preferable where possible. We already do that for the unityVersion or editorVersion param and could do the same for this.

That said, I think the whole point of Build Profiles is to have multiple. So beyond auto-detecting we do need to be able to specify it as a param as well.