Skip to content

Latest commit

 

History

History
220 lines (177 loc) · 10.5 KB

README.md

File metadata and controls

220 lines (177 loc) · 10.5 KB
Raw

com.virtualmaker.buildalon

Discord openupm openupm marketplace

A Build Pipeline utility package for the Unity Game Engine.

This package is designed to be use in conjunction with the Buildalon GitHub Actions.

Installing

Requires Unity 2019.4 LTS or higher.

The recommended installation method is though the unity package manager and OpenUPM.

Via Unity Package Manager and OpenUPM

  • Open your Unity project settings
  • Add the OpenUPM package registry:
    • Name: OpenUPM
    • URL: https://package.openupm.com
    • Scope(s):
      • com.virtualmaker

scoped-registries

  • Open the Unity Package Manager window
  • Change the Registry from Unity to My Registries
  • Add the Buildalon package

Via Unity Package Manager and Git url

  • Open your Unity Package Manager
  • Add package from git url: https://github.com/buildalon/com.virtualmaker.buildalon.git#upm

Documentation

Example Usage

Create Github Action Workflow

  • Create a new action workflow file:
    • .github/workflows/unity-build.yml
  • Add the following content to the file:
name: unity-build
on:
  push:
    branches:
      - 'main'
  pull_request:
    branches:
      - '*'
  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true
jobs:
  build:
    runs-on: ${{ matrix.os }}
    strategy:
      # max-parallel: 2 # Use this if you're activating pro license with matrix
      matrix:
        os: [ubuntu-latest, windows-latest, macos-15]
        unity-version: [2019.x, 2020.x, 2021.x, 2022.x, 6000.x]
        include: # for each os specify the build targets
          - os: ubuntu-latest
            build-target: StandaloneLinux64
          - os: windows-latest
            build-target: StandaloneWindows64
          - os: macos-15
            build-target: StandaloneOSX
    steps:
      - uses: actions/checkout@v4

        # Installs the Unity Editor based on your project version text file
        # sets -> env.UNITY_EDITOR_PATH
        # sets -> env.UNITY_PROJECT_PATH
      - uses: buildalon/unity-setup@v1
        with:
          unity-version: ${{ matrix.unity-version }}
          build-targets: ${{ matrix.build-target }}

        # Activates the installation with the provided credentials
      - uses: buildalon/activate-unity-license@v1
        with:
          license: 'Personal' # Choose license type to use [ Personal, Professional ]
          username: ${{ secrets.UNITY_USERNAME }}
          password: ${{ secrets.UNITY_PASSWORD }}
          # serial: ${{ secrets.UNITY_SERIAL }} # Required for pro activations

      - uses: buildalon/unity-action@v1
        name: Project Validation
        with:
          log-name: 'project-validation'
          build-target: '${{ matrix.build-target }}'
          args: '-quit -batchmode -executeMethod Buildalon.Editor.BuildPipeline.UnityPlayerBuildTools.ValidateProject -importTMProEssentialsAsset'

      - uses: buildalon/unity-action@v1
        name: '${{ matrix.build-target }}-Build'
        with:
          log-name: '${{ matrix.build-target }}-Build'
          build-target: '${{ matrix.build-target }}'
          args: '-quit -batchmode -executeMethod Buildalon.Editor.BuildPipeline.UnityPlayerBuildTools.StartCommandLineBuild -export'

      - uses: actions/upload-artifact@v4
        id: upload-artifact
        name: 'Upload ${{ matrix.build-target }} Artifacts'
        if: success() || failure()
        with:
          compression-level: 0
          retention-days: 1
          name: '${{ github.run_number }}.${{ github.run_attempt }}-${{ matrix.os }} ${{ matrix.unity-version }} ${{ matrix.build-target }}-Artifacts'
          path: |
            ${{ github.workspace }}/**/*.log
            ${{ env.UNITY_PROJECT_PATH || github.workspace }}/Builds/${{ matrix.build-target }}/**/*
            !${{ env.UNITY_PROJECT_PATH || github.workspace }}/Library/**/*
            !/**/*_BackUpThisFolder_ButDontShipItWithYourGame/**
            !/**/*_BurstDebugInformation_DoNotShip/**

Executable Methods

These methods can be executed using the -executeMethod command line argument to validate, sync, and build the Unity project.

Method Description
Buildalon.Editor.BuildPipeline.UnityPlayerBuildTools.ValidateProject Validates the Unity Project assets by forcing a symbolic link sync and creates solution files.
Buildalon.Editor.BuildPipeline.UnityPlayerBuildTools.SyncSolution Force Unity to update CSProj files and generates solution.
Buildalon.Editor.BuildPipeline.UnityPlayerBuildTools.StartCommandLineBuild Start a build using command line arguments. 
"/path/to/Unity.exe" -projectPath "/path/to/unity/project" -quit -batchmode -executeMethod Buildalon.Editor.BuildPipeline.UnityPlayerBuildTools.StartCommandLineBuild

Project Validation Command Line Arguments

Note

No longer required in Unity 6+

Argument Description
-importTMProEssentialsAsset Imports the TMPro Essential assets if they are not already in the project. 
"/path/to/Unity.exe" -projectPath "/path/to/unity/project" -quit -batchmode -executeMethod Utilities.Editor.BuildPipeline.UnityPlayerBuildTools.ValidateProject -importTMProEssentialsAsset

Additional Custom Command Line Arguments

In addition to any already defined Unity Editor command line arguments, this plugin offers some additional options:

Argument Description
-ignoreCompilerErrors Disables logging.
-autoIncrement Enables auto incrementing.
-versionName Sets the version of the application. Value must be string.
-versionCode Sets the version code of the application. Value must be an integer.
-bundleIdentifier Sets the bundle identifier of the application.
-sceneList Sets the scenes of the application, list as CSV.
-sceneListFile Sets the scenes of the application, list as JSON.
-buildOutputDirectory Sets the output directory for the build.
-acceptExternalModificationsToPlayer Sets the build options to accept external modifications to the player.
-development Sets the build options to build a development build of the player.
-colorSpace Sets the color space of the application, if the provided color space string is a valid ColorSpace enum value.
-buildConfiguration Sets the build configuration of the application. Can be: debug, master, or release.
-export Creates a native code project for the target platform.
-symlinkSources Enables the use of symbolic links for the sources.
-disableDebugging ⚠️ deprecated. Use allowDebugging. Disables the ability to attach remote debuggers to the player.
-allowDebugging Enables or disables the ability to attache a remote debugger to the player. Can be: true or false.
-dotnetApiCompatibilityLevel Sets the dotnet api compatibility level of the player. Can be: NET_2_0, NET_2_0_Subset, NET_4_6, NET_Unity_4_8, NET_Web, NET_Micro, NET_Standard, or NET_Standard_2_0.
-scriptingBackend Sets the scripting framework of the player. Can be: Mono2x, IL2CPP, or WinRTDotNET.
-autoConnectProfiler Start the player with a connection to the profiler.
-buildWithDeepProfilingSupport Enables deep profiling support in the player.

Platform specific Command Line Arguments

Android Command Line Arguments
Argument Description
-appBundle Builds an .abb for Google Play Store
-splitBinary Builds an APK per CPU architecture.
-splitApk Uses APK expansion files.
-keystorePath Path to the keystore.
-keystorePass Sets the keystore password.
-keyaliasName Name of the key to use when signing.
-keyaliasPass Sets the key alias password.
-symbols Sets the symbol creation mode. Can be: public, debugging, or disabled.
Apple Device Command Line Args

Works for any Apple Platform Target: MacOS, iOS, tvOS, and visionOS.

Argument Description
-appleTeamId The team id used for signing.
-enableAppleAutomaticSigning Enables automatic signing.
-disableAppleAutomaticSigning Disables automatic signing.
-appleProvisioningProfileId Sets the provisioning profile UUID.
-appleProvisioningProfileType Sets the provisioning profile type. Can be Automatic, Development, or Distribution.
-appleSdkVersion Sets the apple sdk version. Can be Device or Simulator.
MacOS Command Line Arguments
Argument Description
-arch Sets the build architecture. Can be: x64, arm64, or x64arm64.
Windows Universal Platform Command Line Arguments
Argument Description
-arch Sets the build architecture. Can be: x64, x86, ARM, or ARM64.
-wsaUWPBuildType Sets the output build type when building to Universal Windows Platform. Can be: XAML, D3D, or ExecutableOnly.
-wsaSetDeviceFamily Sets the device family. Can be: Desktop, Mobile, Xbox, Holographic, Team, IOT, or IoTHeadless.
-wsaUWPSDK Sets the UWP SDK Version to build for.
-wsaMinUWPSDK Sets the min UWP SDK to build for.
-wsaCertificate Sets the signing certificate. Must pass the path and password together. -wsaCertificate "path/to/cert.pfx" myP@55w0rd