feat: require an options asset; add Initialize(configure) by bobbyg603 · Pull Request #260 · BugSplat-Git/bugsplat-unity

bobbyg603 · 2026-10-30T17:10:11Z

Summary

The build reads the selected BugSplatOptions asset for everything it does: it adds the native crash reporting files, turns off Unity's own iOS crash reporter, and uploads symbols. Options that existed only in code left the build guessing. This PR makes the asset always required and gives code a clean way to change values at runtime.

A release build requires an asset. BUGSPLAT_MANUAL_INITIALIZE is removed, because with an asset required it did exactly what unchecking Initialize Automatically does. BUGSPLAT_DISABLED stays as the per-build-target off switch.
BugSplat.Initialize(Action<BugSplatOptions> configure = null):
- With no arguments, it initializes from the selected asset, so a consent flow doesn't need a reference to it.
- With configure, it initializes from a copy of the asset with your changes applied, for example Initialize(o => o.Database = db). The asset itself isn't changed.
- The per-platform native switches can be turned off this way but not on, because the build already read them from the asset.
- With no asset selected, it warns and returns null.
- Initialize(BugSplatOptions) is unchanged.
Simpler preload handling. OnEnable keeps the first options it sees, which is always the preloaded asset, and ignores the rest. The "more than one preloaded" warning is removed: the build already refuses a second preloaded asset, so the warning couldn't fire.
Post-build: unchanged from main.
Docs: automation.md §3 is rewritten as "Initialize from code"; api.md, the README and the CHANGELOG are updated.

Verification (Unity 6000.5, Windows)

EditMode: 18/18 pass.
PlayMode: 157/157 pass, including new tests for Initialize(), Initialize(configure) and the no-asset case.
Release build with no asset: fails with BuildFailedException: BugSplat: no BugSplatOptions asset is selected… To ship without BugSplat, define BUGSPLAT_DISABLED.
Release build with an asset: succeeds, and the player initializes from the preloaded asset before the first scene.

🤖 Generated with Claude Code

https://claude.ai/code/session_0153YxLptnAqnBKq5T1hyrtC

… selected The post-build step returned as soon as it found no selected asset, so a project that builds its options in code - the documented BUGSPLAT_MANUAL_INITIALIZE path - shipped a Windows player with no BugSplatMonitor.exe, Reporter, WER handler or theme, and its native crashes went unreported. Only symbol upload needs the asset (for the database); the file copies run with default options now, unless BUGSPLAT_DISABLED is defined for the target. The log says what was skipped, as information under BUGSPLAT_MANUAL_INITIALIZE and as a warning otherwise. A player that preloaded an asset and also created options in code warned that "more than one BugSplatOptions was loaded before the first scene": OnEnable counted every instance, including ones made long after startup. Counting now stops at BeforeSceneLoad, after preloaded assets have loaded. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0153YxLptnAqnBKq5T1hyrtC

Copilot

🟡 Changes recommended

Unresolved issues can leave iOS builds without an active crash reporter and cause duplicate-options warnings that depend on Unity callback ordering.

2 open issues

What changed in this PR

This PR supports code-only BugSplat initialization by running native build setup even when no options asset is selected, while keeping symbol upload dependent on an asset.

Changes:

Runs post-build processing with default options and symbol uploads disabled when no asset is selected.
Limits duplicate-options tracking to startup to exclude options created later in code.
Documents the no-asset build behavior and records the fixes in the changelog.

File	Description
`Runtime/Client/BugSplatOptions.cs`	Adds a startup cutoff for duplicate-options tracking.
`Editor/PostBuild.cs`	Adds no-asset post-processing with symbol uploads disabled.
`Editor/BugSplatOptionsPreloader.cs`	Exposes target-specific disabled and manual-initialization checks.
`Documentation~/automation.md`	Clarifies native file inclusion and symbol-upload requirements.
`CHANGELOG.md`	Records native build setup and duplicate-warning fixes.

_{Review effort: Balanced}

bobbyg603 · 2026-10-30T20:29:41Z

+				defaults.UploadDebugSymbolsForMac = false;
+				defaults.UploadDebugSymbolsForIos = false;
+				defaults.UploadDebugSymbolsForAndroid = false;
+				PostProcess(target, pathToBuiltProject, defaults);


Fixed in 32fcd60: with no asset selected, the defaults now set UseNativeCrashReportingForIos = false, so Unity's own crash reporter is left on. The build log says so on iOS, and the CHANGELOG and automation.md mention it. The Xcode setup (linker flags, dSYM format, line-number mappings) still runs, because it's needed whenever the player does initialize BugSplat.

Reverted in 0915a42, so this one is declined. Native crash reporting is on by default on every platform, and options created in code default to UseNativeCrashReportingForIos = true as well. A no-asset build that left Unity's reporter on would leave it competing with BugSplat's in the common case. A project that wants Unity's reporter on iOS can select an asset with Use Native Crash Reporting For Ios unchecked.

bobbyg603 · 2026-10-30T20:29:42Z

 			}
 		}
+
+		[RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.BeforeSceneLoad)]


Fixed in 32fcd60: the cutoff moved to BeforeSplashScreen. I checked it in a 6000.5 Windows player. The preloaded asset is in memory from SubsystemRegistration onward, and with options created in a BeforeSceneLoad callback the player no longer warns and still initializes from the preloaded asset.

Update in b8d515b: the cutoff and the duplicate-preload warning are both removed. A release build now always carries the selected asset, the build refuses a second BugSplatOptions in Preloaded Assets, and the asset is in memory from SubsystemRegistration on. So the first options enabled is always the asset, and OnEnable keeps it and ignores any created later, with nothing to warn about.

… close the preload window earlier With no asset selected the defaults turned native iOS reporting on, so the build disabled Unity's own crash reporter on a choice nobody made. The no-asset path now leaves it on and says so. The preload cutoff moves from BeforeSceneLoad to BeforeSplashScreen. Unity does not order callbacks within a phase, so options a project created in its own BeforeSceneLoad callback could be counted as preloaded and warn. A 6000.5 player shows the preloaded asset in memory from SubsystemRegistration on, and with options created in a BeforeSceneLoad callback it no longer warns and still initializes from the preloaded asset. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0153YxLptnAqnBKq5T1hyrtC

Native crash reporting is on by default on every platform, and options created in code default to it too, so a build with no asset selected should still turn off Unity's own iOS crash reporter rather than leave it competing with BugSplat's. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0153YxLptnAqnBKq5T1hyrtC

…) for runtime changes The build reads the selected asset for everything it does - the native crash reporting files, turning off Unity's iOS crash reporter, symbol upload - so options that exist only in code left it guessing, and the previous commits here had it instrument a player it could not upload symbols for. An asset is now always required: BUGSPLAT_MANUAL_INITIALIZE only changes who calls Initialize, and a release build without an asset fails with or without it. The no-asset post-build path is back to skipping, which now only a development build reaches. Code still decides when BugSplat starts and can change values at runtime. BugSplat.Initialize() uses the selected asset, so a consent flow needs no reference to it. BugSplat.Initialize(o => ...) initializes from a copy of the asset with the changes applied, for a database or version chosen at runtime. The per-platform native switches can be turned off there but not on, since the build read them from the asset. The preload cutoff fix stays: options created in code next to a preloaded asset still happen, through Initialize(BugSplatOptions). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0153YxLptnAqnBKq5T1hyrtC

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0153YxLptnAqnBKq5T1hyrtC

…ing, and the extra overload BUGSPLAT_MANUAL_INITIALIZE now requires an asset, which leaves it doing exactly what unchecking Initialize Automatically does. BUGSPLAT_DISABLED stays as the per-build-target switch. The build refuses a second preloaded BugSplatOptions and a release build always carries the selected one, which is in memory from SubsystemRegistration on, so the first options enabled is the asset. OnEnable keeps the first and ignores the rest; the warning and the BeforeSplashScreen cutoff guarded against cases that can't happen. Initialize() and Initialize(configure) become one method with an optional parameter. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0153YxLptnAqnBKq5T1hyrtC

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0153YxLptnAqnBKq5T1hyrtC

Copilot AI balanced review requested due to automatic review settings October 30, 2026 17:10

Copilot started reviewing on behalf of bobbyg603 October 30, 2026 17:10

View session

Copilot AI reviewed Oct 30, 2026

View reviewed changes

bobbyg603 and others added 3 commits October 30, 2026 16:29

bobbyg603 changed the title ~~fix: add native crash reporting files to builds with no options asset selected~~ feat: require an options asset; add Initialize() and Initialize(configure) Oct 30, 2026

bobbyg603 and others added 2 commits October 30, 2026 16:47

chore: trim comments

62a71d8

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0153YxLptnAqnBKq5T1hyrtC

bobbyg603 changed the title ~~feat: require an options asset; add Initialize() and Initialize(configure)~~ feat: require an options asset; add Initialize(configure) Oct 30, 2026

docs: drop a leftover reference to handing over initialization

fcb2e29

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0153YxLptnAqnBKq5T1hyrtC

This was referenced Oct 30, 2026

feat: native Xbox crash reporting through the BugSplat Xbox add-on #262

Open

Consoles: crash reporting for Unity PS5, Xbox, and Switch 2 builds #261

Open

daveplunkett approved these changes Oct 30, 2026

View reviewed changes

bobbyg603 merged commit 47b5de9 into main Oct 31, 2026
14 checks passed

bobbyg603 deleted the fix/postbuild-without-asset branch October 31, 2026 10:06

Navigation Menu

Repository navigation

feat: require an options asset; add Initialize(configure) - #260

feat: require an options asset; add Initialize(configure)#260
bobbyg603 merged 7 commits into
mainfrom
fix/postbuild-without-asset

bobbyg603 commented Oct 30, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

bobbyg603 Oct 30, 2026

Uh oh!

bobbyg603 Oct 30, 2026

Uh oh!

bobbyg603 Oct 30, 2026

Uh oh!

bobbyg603 Oct 30, 2026

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

bobbyg603 commented Oct 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Verification (Unity 6000.5, Windows)

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

bobbyg603 Oct 30, 2026

Choose a reason for hiding this comment

Uh oh!

bobbyg603 Oct 30, 2026

Choose a reason for hiding this comment

Uh oh!

bobbyg603 Oct 30, 2026

Choose a reason for hiding this comment

Uh oh!

bobbyg603 Oct 30, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

bobbyg603 commented Oct 30, 2026 •

edited

Loading