Unity3dBuilder Plugin

Skip to end of metadata
Go to start of metadata

Plugin Information

Plugin ID unity3d-plugin Changes In Latest Release
Since Latest Release
Latest Release
Latest Release Date
Required Core
Dependencies
0.6
Mar 24, 2014
1.436
Source Code
Issue Tracking
Maintainer(s)
GitHub
Open Issues
Jerome Lacoste (id: lacostej)
Usage Installations 2013-Apr 194
2013-May 202
2013-Jun 222
2013-Jul 240
2013-Aug 260
2013-Sep 269
2013-Oct 334
2013-Nov 360
2013-Dec 365
2014-Jan 383
2014-Feb 406
2014-Mar 469
A problem, An idea ?
Please use our tasks and issues tracker to report bugs, improvements or new feature.

Also if you want to propose some code change using a Github pull request, please open also a Jira issue. It is easier for developers to track them.

Unity3d is a powerful 3d game creation editor and engine that runs on Mac and Windows.

This plugin adds the ability to call the Unity3d Editor from the command line to automate build and packaging of Unity3d applications.

Background

Automating Unity3d builds from the command line is possible. There are a few problems though:

  • the unity runner writes its output to a separate log file, instead of the output
  • tool and file locations are platform specific
  • only one project can be built at a time per machine

Features

This plugin aims to make it easier to run Unity3d builds easily in Jenkins, by adding the following features:

  • log file redirection
  • distributed builds

The plugin was tested with versions ranging from unity3d 3.4.2 to 4.3.3. Tested on distributed and single server environments

Documentation

Installation guide

As Unity3d is multi-platform, you may need to install the proper third party OS & tools (Android SDK, XCode, etc) depending on the type of build targets you intend to exercise.

Install the latest version of the plugin from the update center and configure a freestyle job (see Usage Guide). If necessary restrict the job to the node(s) that will perform the build(s).

On the node(s) you are going to build Unity projects, add at least one unity3d installation (Manage Jenkins -> Configure System) and configure the location of the Unity3d installation. This location is by default /Applications/Unity/Unity.app on Mac OS X and C:\Program Files (x86)\Unity on Windows. The plugin will automatically suffix the installation path with the proper executable location.

Usage guide
Prerequisites

The plugin assumes you've created a special Editor class with at least one method responsible for your build.

Here's an example extracted from one of our projects:

Assets/Editor/MyEditorScript.cs
class MyEditorScript {
        static string[] SCENES = FindEnabledEditorScenes();

        static string APP_NAME = "YourProject";
        static string TARGET_DIR = "target";

        [MenuItem ("Custom/CI/Build Mac OS X")]
        static void PerformMacOSXBuild ()
        {
                 string target_dir = APP_NAME + ".app";
                 GenericBuild(SCENES, TARGET_DIR + "/" + target_dir, BuildTarget.StandaloneOSXIntel,BuildOptions.None);
        }

	private static string[] FindEnabledEditorScenes() {
		List<string> EditorScenes = new List<string>();
		foreach(EditorBuildSettingsScene scene in EditorBuildSettings.scenes) {
			if (!scene.enabled) continue;
			EditorScenes.Add(scene.path);
		}
		return EditorScenes.ToArray();
	}

        static void GenericBuild(string[] scenes, string target_dir, BuildTarget build_target, BuildOptions build_options)
        {
                EditorUserBuildSettings.SwitchActiveBuildTarget(build_target);
                string res = BuildPipeline.BuildPlayer(scenes,target_dir,build_target,build_options);
                if (res.Length > 0) {
                        throw new Exception("BuildPlayer failure: " + res);
                }
        }
}
User/OS setup

On Mac OS X, the user running needs to be logged in otherwise the Unity3d editor might fail to acquire the graphical resources. FIXME add a log.

Build queue

The Unity Editor can only perform one build at a time. If you have multiple job, you may want to prevent more than one Unity jobs to be running at the single time. One simple way to achieve this is to have a single Executor on your build server node. This has of course drawbacks if you intend to run other types of jobs on the same node that are not affected by the same limitation.

Setting up a build step

Add the Unity3d build step to a free-style project, select the unity3d installation and set your command line arguments (e.g. -quit -batchmode -executeMethod MyEditorScript.PerformMacOSXBuild). If you do not specify -projectPath (case-sensitive), the plugin will use the current workspace. You may want to add an extra step to clean the project before you build to make sure the build starts in a clean state.

If you want to build for iOS, you will have to add extra build steps to trigger xcode build. This step isn't covered here.

Unity3d Builder configuration parameters
Parameter Since version Description
command line 0.1 The full command line, the builder adding the -projectPath (case-sensitive) if it isn't specified
Tips
Using Unity3d with large set of jobs
  • use multiple executors. Ensure that you do not run multiple concurrent build from the same job
  • use the global argLine (from 0.6) to configure default configuration in one place
  • specify the -logFile argument to be relative to each project. You don't want all concurrent projects to use the same standard editor.log file
  • combine it with a plugin like EnvInject to differentiate between jobs
  • automate the install of unity
Automatically installing unity3d (MacOSX)

To automatically install unity3d from jenkins (even beta versions)

  1. Install this script somewhere on your machines. E.g. /Users/Shared/Jenkins/Home/bin/
  2. run sudo visudo and add a line like
    jenkins ALL=(ALL) NOPASSWD: /Users/Shared/Jenkins/Home/bin/install_unity3d.sh
  3. Create a parametrized job that takes a String parameter
    name: UNITY3D_URL
    default value: e.g. http://netstorage.unity3d.com/unity/unity-4.2.1.dmg
    description: The URL of the DMG package to install
  4. Add a shell builder to your job:
    shell build step
    cd 
    echo "Installing $UNITY3D_URL"
    curl -C - -O -L $UNITY3D_URL
    file=`echo $UNITY3D_URL | sed -e 's/.*\/\([^\/]*\)/\1/' `
    echo $file
    sudo /Users/Shared/Jenkins/Home/bin/install_unity3d.sh $file
    
Friendly plugins
  • The EnvInject Plugin can help you parametrize your command line for maintaining large amount of projects in a similar manner
  • The Log Parser Plugin can help you to quickly set some parsing rules for your Unity3d builds. Here's a tentative set of rules that we use in one project:
    start /^Initialize mono/
    start /^- starting compile/
    start /^Mono dependencies included in the build/
    start /^Textures/
    info /^Complete size/
    warning /warning CS/
    error /error CS/
    start /^-----CompilerOutput:-stdout/
    info /^Compilation succeeded/
    error /^Compilation failed/
    start /^Used Assets, sorted by uncompressed size/
    info /^\*\*/
    info /^Exiting batchmode successfully now/
    start /^=== BUILD NATIVE TARGET/
    start /^Packaging IPA/
    start /^Archiving artifacts/
    start /Uploading to testflight/
    
Known issues
Troubleshooting failures

If the plugin fails to run the command you want it to run here are some steps you can perform to help identifying the issue:

  • check the editor.log and/or the job console for any errors.
  • if you are trying to run an -executeMethod argument, expose the editor method in the Unity3d menus ( [MenuItem (".../...")] ) and run it. Bonus if you are able to run it on the machine it is supposed to run. If the command doesn't run here, then the problem isn't in the plugin
  • run your build command from a Jenkins "Run in a Windows batch command" build step. If the job fails, then check the arguments (the plugins may have fiddled with the arguments incorrectly).
  • run your build command from a CMD on the machine you intend to. If that works, and the run from jenkins doesn't, compare the environments (user, permissions, access to graphics devices, etc)
Related information

Changelog

Version 0.7 (DEV IN PROGRESS)
Version 0.6 (24.03.2014)
  • reduce risks of truncating console
  • fix command line documentation issue
  • properly handle editor.log piping when using the -logFile argument
  • global argLine
Version 0.5 (27.09.2003)
  • fix command line setting been overwritten at execution time
Version 0.4 (16.09.2013)
  • support build and environment variables injection into the command line
Version 0.3 (06.06.202)
  • Validity of Unity3D project folder was not correctly checked when projectPath parameter was used.
Version 0.2 (30.01.2012)
  • JENKINS-12590
Version 0.1 (24.01.2012)
  • live redirection of the Editor.log file into the console
  • supports distributed builds
  • automatically adds the -projectPath command line

Labels

Edit
plugin-builder plugin-builder Delete
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.