Build mods with a self-hosted Jenkins setup
中文 | English
Use Jenkins to schedule a local build manifest on your own Windows build machine. The official mod repository uses GitHub Actions Build modpack.
1. Install the service and complete setup
- Install a Java version supported by your Jenkins LTS, then run its Windows MSI. Choose the installation directory. Use a local or domain account with Log on as a service permission, then select the Java home and port. Jenkins Windows installation
- Check that Jenkins is running in Windows Services. Use Restart there after changing the service configuration. Open the selected local port in a browser. The default is
http://localhost:8080. - On Unlock Jenkins, read the
initialAdminPasswordfile from the shown location and enter it. Choose Install suggested plugins or Select plugins to install. Create the first administrator and open Jenkins. The Pipeline below calls Unity directly. Install other plugins as needed.
2. Prepare the build machine and manifest
- Install Git, Git LFS, the SDK's Unity version, and the target platform modules. Verify that the Jenkins service account can read the project and run Unity. Put the full path to the matching
Unity.exein the worker'sUNITY_EXEenvironment variable. - Commit the ModPackageBuildPiplineData asset and
CI/ModBuild.jsonin the Unity project. Follow the manifest example and keepStandaloneWindows64as its platform andBuild/Ship/Windowsas its destination. Begin with an empty output directory. - Add
Assets/Editor/CiModBuild.csto the Unity project with this-executeMethodentry point. The caller passes the manifest path.
using System;
using System.IO;
using ShanghaiWindy.Editor;
public static class CiModBuild
{
public static void Run()
{
var args = Environment.GetCommandLineArgs();
var index = Array.IndexOf(args, "-modManifest");
if (index < 0 || index + 1 >= args.Length)
{
throw new ArgumentException("Supply -modManifest followed by the JSON path.");
}
Utility_BuildPipline.BuildPiplineManifest(Path.GetFullPath(args[index + 1]));
}
}
3. Create a Pipeline and check the build
- Save the script below as
CI/Build-Mod.ps1in the Unity project.Win64is Unity 2022.3's command-line switch value. The manifest still usesStandaloneWindows64. Unity Editor command-line arguments
$ErrorActionPreference = 'Stop'
$project = (Resolve-Path .).Path
$manifest = Join-Path $project 'CI/ModBuild.json'
$output = Join-Path $project 'Build/Ship/Windows'
$log = Join-Path $project 'Build/UnityBuild.log'
New-Item -ItemType Directory -Path $output -Force | Out-Null
if (Get-ChildItem -LiteralPath $output -Filter '*.modpack' -File) {
throw "Use a clean output directory before building: $output"
}
$arguments = @(
'-batchmode', '-quit', '-projectPath', ('"' + $project + '"'),
'-buildTarget', 'Win64', '-executeMethod', 'CiModBuild.Run',
'-modManifest', ('"' + $manifest + '"'), '-logFile', ('"' + $log + '"')
)
$build = Start-Process -FilePath $env:UNITY_EXE -ArgumentList $arguments -Wait -PassThru -WindowStyle Hidden
if ($build.ExitCode -ne 0) { throw "Unity exited with $($build.ExitCode). See $log" }
if (-not (Get-ChildItem -LiteralPath $output -Filter '*.modpack' -File)) {
throw "No .modpack in $output. Check the manifest's target platform and directory."
}
- Create a Jenkins Pipeline and select Pipeline script from SCM. Save the following
Jenkinsfileat the repository root. Replacewindows-unitywith the label on your Windows agent. The Checkout stage resets this job's dedicated build workspace before cloning so each build has a fresh output directory. If the Unity project is in a subdirectory, wrap the PowerShell build step indir('path/to/project')and prefix the archive patterns with that path. Jenkinsfile guide · PowerShell step
pipeline {
agent { label 'windows-unity' }
options { skipDefaultCheckout() }
stages {
stage('Checkout') {
steps {
deleteDir()
checkout scm
bat 'git lfs pull'
}
}
stage('Build mods') {
steps {
powershell '& ./CI/Build-Mod.ps1'
archiveArtifacts artifacts: 'Build/Ship/Windows/*.modpack'
}
}
}
post {
always {
archiveArtifacts artifacts: 'Build/UnityBuild.log', allowEmptyArchive: true
}
}
}
- Choose Build Now with a teaching mod. Open
Build/UnityBuild.logfrom the artifacts and check the target, the names built, and the destination. Before distributing a successful build, create the matching.modpack.jsonusing the manifest guide and keep it alongside the archive. Check each archive's GUID, version, and target.