Lesson 13: Build pipeline and platform checks

The first time you build for a platform should not be the first time you discover missing references, wrong main scenes, or a scripting backend mismatch. This lesson turns “it builds on my machine” into a repeatable release pipeline: lock your build settings, run smoke tests per target, and output an artifact you can trust for submission.

Lesson Objective

By the end of this lesson you will:

Make clear Player Settings decisions for your target platforms (including scripting backend)
Produce a build that matches your expectations using versioning discipline
Run lightweight smoke tests that catch the biggest release-breaking issues early
Generate a simple build-readiness checklist your team can reuse

Why this matters now

Lesson 12 gave you structured playtesting and bug triage. Lesson 13 is the bridge from “game feels right” to “build is reliable.” This is where platform differences (IL2CPP behavior, scene packing, asset stripping, and runtime platform constraints) can quietly invalidate weeks of work.

Step-by-step workflow

Step 1: Lock build targets and decide IL2CPP vs Mono

Start by listing every platform you plan to ship (even if only one is immediate). Then decide the scripting backend for each:

Use IL2CPP when you need closer-to-release behavior, better platform compatibility, or stricter runtime expectations
Use Mono when you need faster iteration and your platform is known to behave reliably during the vertical slice stage

Pro tip: If you switch scripting backends late, expect surprises. Decide early and keep settings stable through your submission cycle.

Step 2: Verify Player Settings before you build

Open Edit → Project Settings and validate these categories for every target:

Main Scene / Scene order
- Ensure your “bootstrap” scene is correct so the build starts where you expect.
Application identifiers
- Bundle identifiers, package names, and product naming rules.
Versioning
- Keep a version string that matches your release plan and submission notes.
Graphics defaults
- Confirm your rendering pipeline assumptions match what you tested.

Write down any changes you make so you can reproduce them on the next build.

Step 3: Create a per-target smoke test checklist

Smoke tests are not playtests. They are fast “does the game boot and do the critical flows survive” checks.

Run the same checklist per target:

Boot the game and reach your main menu
Start a fresh play session (no save file expected)
Trigger the core loop once (move, interact, complete one objective beat)
Save and load to confirm persistence is present in the build
Quit and relaunch to verify there is no persistent state corruption

Keep this checklist short enough that you can run it every build candidate.

Step 4: Build artifacts with a consistent pipeline

Use a stable build naming convention so you can tell builds apart without guessing:

Include date and lesson phase (e.g., 2026-03-25_L13_build)
Include platform in the filename
Keep a “latest” copy for the current checklist run

Then verify your output:

Build output exists and is the correct type for the platform
File size is within an expected band (a sudden size jump can indicate packaging mistakes)

Step 5: Run smoke tests and record results

Before you move into store submission work, record:

Which checklist steps passed/failed
Any error messages (including stack traces)
Which platform-specific setting likely caused the issue (if known)

If smoke tests fail, do not “just submit.” Fix the build settings or content packing issues and rebuild.

Mini challenge

Choose two targets (for example Windows and one additional platform you plan to support). Then:

Produce two builds using the same version string
Run the smoke checklist on both
Write a 1-page build readiness note with:
- What passed
- What failed
- One likely cause per failure
- One next action you will take before Lesson 14

Troubleshooting

“Build runs but starts on the wrong scene”

Most common causes:

Main Scene / startup scene is not set for the target
Scene order in build settings changed accidentally
You are using an old build configuration you forgot to update

“Works in Editor but breaks in build”

Typical reasons:

Missing references that the Editor hides during play
Asset stripping differences depending on build settings
Timing differences when initialization code runs earlier or later

Fix strategy:

Narrow it down to the smallest failing flow
Rebuild after each change and re-run the smoke checklist

“IL2CPP build fails during compilation”

Things to check:

Any platform-specific scripting defines or conditional compilation
Third-party native plugins compatibility
Any unsafe reflection or unsupported runtime patterns

Common mistakes to avoid

Changing build settings and gameplay content at the same time
Treating smoke tests as optional
Building on only one machine and then assuming the artifact is identical
Not tracking version strings, which makes triage impossible later

Pro tips

Keep build settings changes in a short “release diff” you can review before the next lesson
Run smoke tests after any major content merge, not just once at the end
If you have CI, automate at least the build command and artifact upload

Recap

You now have a pipeline mindset: lock build targets and settings, run consistent per-platform smoke tests, and output a build artifact you can trust for submission. This prevents late stage build surprises and makes the store prep work in Lesson 14 much smoother.

Next lesson teaser

Lesson 14 is where you turn the build into a launch package: store page assets and a checklist for what must be ready before you hit publish.

FAQ

Should I run smoke tests in Editor or Build?
Always run the critical “boot and core loop” checks in the actual build for each target. Editor-only tests can miss platform packing and runtime differences.

Does IL2CPP always fix runtime issues?
IL2CPP changes runtime behavior and compatibility. It can prevent certain problems, but it can also introduce new constraints. Use it intentionally and keep settings stable.

How long should smoke tests take?
Target 10 to 20 minutes per build candidate per platform. If it takes longer, the checklist is probably drifting into playtest territory.

What should I do if my smoke test fails on one platform only?
Treat it as a platform settings issue first (scene packing, identifiers, backend settings). Record steps and error messages, then fix and rebuild.