DEV Community: Othmane ETTAIB

Pricing an economy off its difficulty model

Othmane ETTAIB — Sat, 19 Sep 2026 18:12:32 +0000

Originally published on indiecore.net.

Part 8 of 10 on building a word-block puzzle engine. Part 7: testing a level pack you did not write.

The first economy paid 20 coins for finishing a level. Every level. It survived about a week of
my own play before it was obviously broken, and the reason is a number from part 3.

A level's decision load — the total count of real choices the board forces across a full
solve — runs from 7.5 on the easiest tier to 96.7 on the hardest. A 13× spread. A flat rate
pays the same for a two-minute board and a twenty-minute one, which teaches the player to grind
the easy end of whatever is unlocked and never touch the interesting boards.

Reward follows the thinking, not the rating

The payout is tied to decision load rather than the 0–10 difficulty rating, and that distinction
is deliberate. The rating is a percentile — a comparison against other boards. The decision load
is an absolute count of work done. Coins should pay for work.

economy.js

// A coin economy priced off the difficulty model, as data and pure functions.
//
// Nothing in here touches React, the store, or storage. That is not tidiness —
// it is what lets the balance SIMULATOR import the same module. A simulator
// that re-implements the economy tells you about a game you are not shipping,
// and it diverges on the first tuning pass, silently, because nothing connects
// them.
//
// WHERE THE NUMBERS COME FROM
//
// A level's difficulty is its DECISION LOAD: walk the board the way the
// difficulty model does — fill the topmost-leftmost empty cell, count how many
// pieces in hand could go there — and sum (choices - 1) over every step.
//
// It runs 7.5 on the easiest tier to 96.7 on the hardest. A 13x spread, which
// is why nothing here is a flat rate. The first version paid 20 coins for
// finishing a level, every level, and taught players to grind the easy end.

/** Board size bands. Pieces per board runs 4..30, median 15. */
export const BANDS = ['S', 'M', 'L'];
export const bandFor = (pieceCount) => (pieceCount <= 9 ? 'S' : pieceCount <= 17 ? 'M' : 'L');

// ---------------------------------------------------------------------------
// Earning
// ---------------------------------------------------------------------------

/**
 * What a first clear pays.
 *
 * Tied to the decision load rather than the 0-10 rating, and the distinction is
 * deliberate: the rating is a percentile — a comparison against other levels —
 * while the decision load is an absolute count of work done. Coins pay for work.
 *
 * Yields 8 coins on an Easy board, 35 on an Expert one. The floor exists so a
 * tiny 3x3 still feels like it paid something; the slope is what makes a hard
 * board worth choosing.
 */
export const CLEAR_BASE = 6;
export const CLEAR_PER_DECISION = 0.30;

export const clearReward = (decisionLoad) =>
  Math.round(CLEAR_BASE + CLEAR_PER_DECISION * decisionLoad);

/**
 * Star bonuses, paid as a DELTA against the highest tier ever banked for that
 * level. Replaying a 3-star level pays nothing; dragging a 1-star up to 3 pays
 * the difference once and never again.
 *
 * Without the delta, replaying your easiest completed level is the optimal way
 * to earn — a broken economy and a boring game.
 *
 * These are deliberately small. Simulation put star bonuses at 45% of ALL
 * income — the single largest faucet, larger than clears, ads or the daily
 * chest — while three stars is earned on about two thirds of levels. A generous
 * bonus here is a tax-free salary rather than a reward for excellence.
 *
 * The top delta is also the ceiling on what any single purchase can unlock, so
 * it sets the price floor: if a hint costs less than this, the optimal strategy
 * is to buy hints until three stars is guaranteed, forever, and the economy
 * becomes a vending machine.
 */
export const STAR_BONUS = { 0: 0, 1: 0, 2: 6, 3: 18 };

export const starDelta = (stars, tierAlreadyPaid) =>
  Math.max(0, (STAR_BONUS[stars] ?? 0) - (STAR_BONUS[tierAlreadyPaid] ?? 0));

/**
 * Rewarded-video multiplier on a first clear. Never offered on a replay.
 *
 * A multiplier rather than a flat coin amount, so the ad reward inherits the
 * difficulty scaling for free: doubling a 35-coin Expert clear is worth
 * watching, doubling an 8-coin Easy one is not, and the player self-selects.
 * A flat "watch for 25 coins" inverts that — farm the easiest level, watch,
 * repeat.
 */
export const DOUBLER = 2;
export const PEAK_DOUBLER = 3;

/**
 * Daily login chest: a 7-day cycle that grows a little each time it completes,
 * then STOPS.
 *
 * The escalation is capped because the version this replaced multiplied without
 * limit — by the eighth cycle its day-7 chest paid 225 coins, more than three
 * level clears, for opening the app. Retention rewards should be worth showing
 * up for and never worth more than playing.
 */
export const DAILY_CHEST = [20, 22, 25, 28, 32, 40, 70];
export const CHEST_GROWTH = 0.2;
export const CHEST_MAX_CYCLES = 2;

export const dailyChest = (totalDaysClaimed = 0) => {
  const cycle = Math.min(CHEST_MAX_CYCLES, Math.floor(totalDaysClaimed / DAILY_CHEST.length));
  const day = totalDaysClaimed % DAILY_CHEST.length;
  return Math.round(DAILY_CHEST[day] * (1 + CHEST_GROWTH * cycle));
};

// ---------------------------------------------------------------------------
// The invariants the simulator asserts (--test), rather than numbers it prints
// ---------------------------------------------------------------------------
//
//   - no sequence of legitimate actions produces unbounded coins
//   - every purchasable item is reachable within a bounded number of levels
//     from zero
//   - replaying a completed level never nets positive
//   - the difficulty walk these prices are computed from still matches the
//     metrics shipped on every board
//
// The last one is the join to the rest of the system. Prices derive from the
// same walk that rates the levels and drives the power-ups. If that walk drifts,
// the game keeps running and every price silently becomes wrong.

Eight coins on an Easy board, 35 on an Expert one. The floor exists so a tiny 3×3 still feels
like it paid something; the slope is what makes a hard board worth choosing.

The module knows nothing about the game

Everything the game charges, pays or caps is in one file, and nothing in that file touches React,
the store, or storage. It is data and pure functions.

That is not tidiness. It is what lets the simulator import the same module. A balance
simulator that re-implements the economy is a simulator that tells you about a game you are not
shipping — and it will diverge on the first tuning pass, silently, because nothing connects them.

Sharing the module means a number tuned in one place cannot drift from the other, and the balance
the simulator reports is the balance that ships.

What the simulation actually found

I would not have found either of these by playing.

Star bonuses were 45% of all income. The single largest faucet in the game — larger than
level completion, larger than ads, larger than the daily chest. And three stars is earned on
about two thirds of levels, which makes a generous star bonus a tax-free salary rather than a
reward for excellence.

They came down hard, and STAR_BONUS above pays them as a delta against the highest tier
ever banked for that level. Replaying a 3-star level pays nothing. Dragging a 1-star up to 3 pays the difference, once, ever.
Without the delta, replaying your easiest completed level is the optimal way to earn, which is
both a broken economy and a boring game.

The daily chest escalated without limit. It grows a little each time the seven-day cycle
completes, which is a nice feeling for the first fortnight. Left unbounded, by the eighth cycle
the day-7 chest paid 225 coins — more than three level clears — for opening the app.
CHEST_MAX_CYCLES is the whole fix. Retention rewards should be worth showing up for and never worth more
than playing.

The price floor is set by the largest single payout

A subtle constraint I got wrong first. The most any single purchase can unlock is bounded by the
biggest reward it can lead to — here, the top star delta. If a hint costs less than that, the
optimal strategy is to buy hints until three stars is guaranteed, on every level, forever. The
economy becomes a vending machine.

So the top star delta sets a floor under every price, and the floor is written down next to the
constant that produces it. The relationship between two numbers in different sections of a file
is exactly the thing that gets broken by someone reasonably tuning one of them.

Ads pay a multiplier, not a currency

Rewarded video doubles a first clear and never appears on a replay.

Tying the ad reward to the level rather than to a fixed coin amount means it inherits the
difficulty scaling for free — doubling a 35-coin Expert clear is worth watching, doubling an
8-coin Easy one is not, and the player self-selects. A flat "watch for 25 coins" would have
inverted that: farm the easiest level, watch the ad, repeat.

There is no interstitial between levels. That was a product decision rather than an economic one
and I do not have data to defend it; what I can say is that it removed an entire class of tuning
problem, because there was no longer a knob whose optimum is "as often as players tolerate".

Invariants, not just numbers

The simulator has a --test mode that asserts properties rather than printing a report:

No sequence of legitimate actions produces unbounded coins.
Every purchasable item is reachable within a bounded number of levels from zero.
Replaying a completed level never nets positive.
The difficulty walk the prices are computed from still matches the metrics shipped on every board (part 7).

The last one is the join between this post and the rest of the series. Prices are derived from
the same walk that rates the levels and drives the power-ups. If that walk drifts, the game keeps
running and every price silently becomes wrong. A test that says so is worth more than a
spreadsheet.

What I still do not know

Whether any of it is right. Every number here is defended against a simulation, and a simulation
is a model of a player I invented.

The honest position is that this is a starting balance whose main property is being internally
consistent and cheap to change — one file, no game code, a simulator that shares it. When real
telemetry arrives, most of these constants will move. The structure is built so that moving them
is a one-line change with a test run behind it, rather than an archaeology expedition through the
UI code.

Next: part 9, cutting a Capacitor Android build in half — where the download actually goes, and the consumer ProGuard rule that cost 9,304 classes.

Originally published at Pricing an economy off its difficulty model.

The code is on GitHub: The economy module the simulator shares

The opening layout is part of the puzzle

Othmane ETTAIB — Fri, 18 Sep 2026 18:38:24 +0000

Originally published on indiecore.net.

Part 5 of 10 on building a word-block puzzle engine. Part 4: difficulty rates, progression places.

A level opens with an empty grid and a scatter of loose blocks around it. I assumed this was
presentation — put the pieces somewhere sensible, get on with the game.

It is not presentation. It decides how big the grid is drawn, and it can give away the answer.
Both of those took a rewrite to learn.

The objective is grid size, not fit

The camera frames the board and the loose blocks together, so the zoom is:

scale = min(availW / spanW, availH / spanH)

where the span is the bounding box of the board and every block, in cells. The board is then
drawn at cols × scale.

Every wasted cell of span comes straight off the size of the grid the player is reading letters
from. On a phone that is the difference between comfortable and squinting.

So this is not "does the arrangement fit on screen". It is a packing problem whose objective is
how large can the grid be drawn, and a loose arrangement that fits perfectly well can cost 20%
of the board.

The measure I report is kept: the drawn board size as a fraction of what it would be drawn at
with no loose blocks at all. Raw scale is not comparable between a 3×3 and a 17×10; kept is.

The rule that makes it hard

Here is the trap, and it is a good one.

A cut board is tiled exactly by its own blocks. So the tightest possible way to pack those blocks
is to rebuild the tiling — and a packer whose objective is the smallest bounding box will
find that on its own, because it is genuinely optimal.

It is also the one arrangement the game cannot use. The blocks come out already assembled and
the level is reduced to sliding a finished slab onto the grid.

The near-misses are just as bad and much easier to ship by accident: two neighbouring blocks
sitting at the offset their solved positions have. The player sees af and fo already
interlocked and has been handed a piece of the answer for free.

The rule that catches all of it turned out to be one line of algebra. A block's implied board
origin is:

origin = seat − home

Two blocks that share an origin are sitting in their solved relationship. So: no two blocks
that are neighbours in the solution may share an origin.

Blocks that are not neighbours are left alone deliberately — at their home offset they do not
touch, so there is nothing there for a player to read. Being stricter costs span for no gain.

That rule is enforced at every seat inside the solver, again in the runtime fallback that deals
a layout when a board has none stored, and a third time as a check in the test harness. Three
places, because it is the constraint whose violation is invisible in a screenshot and obvious the
moment a player notices it.

Clearance, and the corner exception

A loose block touching the board reads as one already placed. So there is a clearance gap —
AIR = 0.28 cells — between the board and anything loose.

But only on the axes that matter, not diagonally. A block sitting off one of the board's corners
overlaps it on neither axis and touches it at a single point, which no player reads as placed.

Forbidding those four corner cells is expensive out of all proportion: it costs a whole column of
margin on every side, and with it any arrangement that wraps the board on all four sides is often
impossible at a size worth having. The tightest arrangements are built by tucking a block
diagonally past a corner, which is precisely what the naive rule bans.

Cells, not pixels — and the half-row bug

Positions are stored as (row, col) in cells, relative to the board origin. Not pixels. That
is what makes an arrangement solved once offline reusable on any screen, any cell size, any zoom.

Fractional offsets are allowed and useful, which is where it gets subtle.

Packing happens in whole cells, then each block is slid back toward the board to close most of
the ring of air that packing needed. So a block can end up off the lattice on an axis where it
stands clear of the board — that offset is the closed gap, and it is what buys the span back.

But on an axis where it shares the board's extent it has to stay whole. A block in a side strip
sitting half a row out has its letters out of line with the rows it is about to join, and it
looks broken. The solver enforces that while sliding, and the harness checks it independently.

Blocks on all four sides

Wherever an arrangement exists that puts something above, below, left and right of the board,
that is what ships.

This is a rule rather than a preference, and it costs real span. An arrangement that stacks
everything below the board is almost always tighter. It also looks like a bug in the camera — the
board floats at the top of the screen with a heap underneath, and the player's first read is that
something failed to load.

Symmetry buys more than it costs even when the arithmetic says otherwise. That is not a
statement I can defend with a number, which is why it is written down as a rule with the reason
attached, instead of being a constant somebody later "optimises".

What "good" means, measurably

The harness reports four things per board, and the pipeline refuses to ship a pack that fails
any of them:

kept — drawn board size as a share of the unobstructed maximum
fill density — blockCells / (spanW × spanH − boardCells)
cells per side — above / below / left / right, balanced, with the two side strips equal
overlapping cell pairs — must be zero

Bounding boxes may and should overlap; interlocking silhouettes is the whole point. Only filled
cells may not.

Why solve it offline

Layout solving is the slow step of the pack pipeline by a wide margin — it is a packing search
per board, with constraints, over 392 boards. Done at runtime it would be a visible pause on
every level open, on the slowest device you support, for an answer that is identical every time.

So the arrangement is computed once, stored in the board file, and read at level load. The
runtime keeps a fallback dealer for boards that have no stored layout, and that fallback enforces
the same scramble rule — because the day someone ships a pack without running the layout step,
the failure should be a slightly loose arrangement, not a level that opens pre-solved.

The general lesson

I would not have guessed that where the pieces sit was a design surface at all. It looked like
the last 2% of polish, and it turned out to contain a real optimisation problem, a
solution-leaking bug class, and a constraint that had to be re-implemented three times to be
trustworthy.

The tell, in hindsight: it was the only part of the level that the level data did not describe. Everything
the board is was in the file; where it starts was being decided by whatever code happened to
run first. Anything in that category is worth a second look.

Next: part 6, shipping a 4 MB level pack — what all this data costs in the download, and how to stop paying for the parts nobody reads.

Originally published at The opening layout is part of the puzzle.

opacity 0 does not hide anything

Othmane ETTAIB — Fri, 18 Sep 2026 18:38:23 +0000

Originally published on indiecore.net.

Lighthouse has a list of accessibility items it will not judge for you. Interactive controls
are keyboard focusable. The page has a logical tab order. Offscreen content is hidden from
assistive technology. No score, no pass, no fail — a list of things a machine cannot decide.

I had been treating that list as decoration. Then I actually worked it, one item at a time,
by driving the running page rather than reading my own markup, and three of the eleven turned
out to be real.

All three were the same component.

Invisible is not gone

My screenshot lightbox is built by JavaScript on page load and hidden until someone clicks a
thumbnail. Hidden like this:

.lb { position: fixed; inset: 0; display: flex;
      opacity: 0; pointer-events: none; transition: opacity .3s }
.lb.open { opacity: 1; pointer-events: auto }

That is a normal way to write a fade. opacity: 0 makes it invisible. pointer-events: none
makes it unclickable. Between them they cover mouse users completely.

They do nothing at all for the keyboard. The element still has layout, still sits in the
accessibility tree, and its three buttons are still tabbable. I counted them in the console:

lbButtonsTabbable: [ 'Previous screenshot', 'Next screenshot', 'Close' ]
totalTabbable: 52

On every game page, a keyboard user tabbing through the footer would land on three controls
that were not on the screen. Press Enter on one and a dialog they cannot see starts
responding.

visibility: hidden fixes it, because visibility is inherited by hit-testing, focus and
assistive technology in a way opacity is not. Tab stops went from 52 to 49.

Then I broke the thing that was working

Here is the part I did not see coming. Opening the dialog does this:

lb.classList.add('open');
document.body.style.overflow = 'hidden';
lb.querySelector('.lb-close').focus();

That worked before my change. After it, focus stayed on the thumbnail and the dialog opened
behind the user — the exact failure the managed focus item on that list describes, newly
introduced by fixing a different item on the same list.

focus() on an element that is visibility: hidden does nothing. It does not throw. It does
not warn. It returns, and document.activeElement is whatever it was before.

And at the moment .focus() runs, the element still is hidden, because I had put visibility
in the transition:

transition: opacity .3s, visibility .3s;

With a duration on it, the computed value does not flip until the transition starts on the
next frame. The class is applied, the style says .open, and getComputedStyle still reports
hidden for one more tick. I confirmed that by reading it twice — immediately after the
click, and 600 ms later:

same tick:   { hasOpenClass: true, visibility: 'hidden',  opacity: '0' }
after 600ms: { hasOpenClass: true, visibility: 'visible', opacity: '1' }

I tried forcing a reflow with void lb.offsetWidth first. That did not help, which is the
clue that it was never a style-flush problem. The fix is to take visibility out of the timed
part and delay it only on the way out:

.lb      { visibility: hidden;  transition: opacity .3s, visibility 0s .3s }
.lb.open { visibility: visible; transition: opacity .3s, visibility 0s 0s }

Zero duration, no delay when opening, so it flips in the same tick and focus() lands.
Delayed by the length of the fade when closing, so the dialog does not vanish mid-animation.

Testing it by pressing the keys

I could not have found either bug by reading the code, because both times the code says the
right thing. The class gets added. .focus() gets called.

So I drove it over the DevTools protocol instead — real Tab and Escape key events
dispatched at the page, printing document.activeElement after each one:

before open, focus: BUTTON[Enlarge screenshot 1 of 5].shot
after open,  focus: BUTTON[Close].lb-close
tabbing forward:    lb-prev → lb-next → lb-close → lb-prev → lb-next → lb-close
shift+tab:          lb-next
after Escape:       BUTTON[Enlarge screenshot 1 of 5].shot

That is the whole contract for a modal, visible as output. Focus enters, cycles without
escaping, and returns to whatever opened it. The first run of that same script printed
BUTTON[Enlarge screenshot 1 of 5] on the second line, which is how I knew.

The dialog also needed to say what it was. It had no role, so a screen reader announced
three buttons with no indication that anything had opened:

lb.setAttribute('role', 'dialog');
lb.setAttribute('aria-modal', 'true');
lb.setAttribute('aria-label', 'Screenshot viewer');

aria-modal tells assistive technology to ignore the rest of the page. It does not stop Tab
from walking out into it, so the trap is still yours to write.

The one I would look at first on your site

Any element you hide with opacity and reveal with a class. Carousels, drawers, tooltips,
cookie banners, off-canvas menus. If it contains a link or a button, tab through your page
with your eyes on the screen and see where focus goes when it disappears.

Mine had been shipping like that for months, on six pages, and every automated audit I ran
gave the site 100 for accessibility the entire time.

Originally published at opacity 0 does not hide anything.

The code is on GitHub: The lightbox, dependency-free

AdMob Unity test IDs, and two error codes

Othmane ETTAIB — Thu, 17 Sep 2026 19:16:09 +0000

Originally published on indiecore.net.

The AdMob Unity test IDs are the same three strings everywhere, so there is not much to say
about copying them. What is worth writing down is what happens when the ID is slightly
wrong, because the SDK reports the two common mistakes with completely different errors and
only one of them looks like a mistake.

This is the same lab as the previous post: Unity
6000.4.0f1, Google Mobile Ads 11.5.0, play-services-ads:25.4.0, on a Pixel 9 Pro emulator
running Android 16.

The three that work

const string Banner       = "ca-app-pub-3940256099942544/6300978111";
const string Interstitial = "ca-app-pub-3940256099942544/1033173712";
const string Rewarded     = "ca-app-pub-3940256099942544/5224354917";

All three loaded on a real device in one run:

LAB_AD interstitial LOADED
LAB_AD banner-test LOADED
LAB_AD rewarded LOADED

The app ID that goes with them is ca-app-pub-3940256099942544~3347511713. Note the
separator: an app ID uses ~, an ad unit ID uses /. The prefix is identical, which
is what makes the next section possible.

You can confirm you are actually in test mode without an AdMob account open. The SDK says so
in logcat:

I/Ads: This request is sent from a test device.

If that line is absent and ads are still loading, the requests are live, and clicking one is
the fastest way to get an account limited.

Two ways to get the ID wrong

I loaded two more banners in the same run. One used a well-formed unit that does not exist,
the other used the app ID where the unit belongs — the copy-paste slip the shared prefix
invites.

const string Bogus     = "ca-app-pub-3940256099942544/0000000000";
const string Malformed = "ca-app-pub-3940256099942544~3347511713";  // app ID, wrong place

The results, verbatim:

LAB_AD banner-malformed FAILED code=1 domain=com.google.android.gms.ads
  msg=Error building request URL: Cannot determine request type. Is your ad unit id correct?

LAB_AD banner-bogus FAILED code=3 domain=com.google.android.gms.ads
  msg=Publisher data not found. <https://support.google.com/admob/answer/9905175#9>

Two different codes, and the difference matters more than it looks.

Code 1 is honest. The SDK could not even build a request, and the message asks you the
right question. You will fix this one in a minute.

Code 3 is the trap. Code 3 is ERROR_CODE_NO_FILL — the same code you get on a healthy
integration when the network genuinely has no ad to serve. A new app with a correct setup
sees plenty of it, so the reasonable reading of a code 3 is "no inventory yet, check back
later". Here it was produced by an ad unit ID that does not exist, and the only thing telling
the two apart is the message text.

So read the message, not the code. Publisher data not found means the unit is wrong or does
not belong to your account. A real no-fill does not say that.

The first launch that never fired

Before any of that, the run nearly produced nothing at all. On a freshly booted emulator I
installed the build, launched it, and waited four and a half minutes. The process was alive,
the activity was topResumedActivity, Play services had logged
Initialized AdMob in container 26.26.34, and my MobileAds.Initialize callback had not
fired once.

adb shell am force-stop com.indiecore.admoblab
adb shell am start -n com.indiecore.admoblab/com.unity3d.player.UnityPlayerGameActivity

Every callback landed within a minute of the second launch. Same APK, same emulator, one
force-stop between them.

I have no mechanism to offer for that and I am not going to invent one — I did not
instrument the SDK's internals, so anything I said about why would be a guess dressed as a
finding. What I can say is the practical part: on a cold device or a fresh emulator, a first
launch that produces no ad callbacks is not yet evidence of anything. Force-stop it, launch
it again, and judge the second run. I had written most of a bug report before I tried the
obvious thing.

What I did not test

Real ad unit IDs from a live account. Everything above uses Google's sample units, so none of
it says anything about fill rates, eCPM, mediation behaviour or what a policy-limited account
does. Those need a real AdMob account and real traffic, and a post claiming to have measured
them from an emulator would be worth nothing.

Takeaway

Keep the test IDs in a constant, not inline at the call site, so switching to real ones is one
edit and one diff to review. Check for This request is sent from a test device. in logcat
before you tap anything. And when a load fails, read the message rather than the code —
code=3 alone will send you off investigating an inventory problem you do not have.

Originally published at AdMob Unity test IDs, and two error codes.

Unity 6 Android build errors that exit 0

Othmane ETTAIB — Thu, 17 Sep 2026 19:16:08 +0000

Originally published on indiecore.net.

A unity 6 android build error is easy to deal with when Unity says the words. What cost me
an evening was the opposite: four builds that reported success, returned exit code 0, and had
not done the thing I asked. On a laptop you notice, eventually. In CI, exit code 0 is the
whole signal, and a green pipeline shipped an APK that crashed on launch.

These all came out of one week on Unity 6000.4.0f1, building Android from -batchmode on
macOS. Three of the four are Unity behaving as designed.

The build that succeeded with one error

I was building a project with the Google Mobile Ads plugin and had deliberately left its App
ID blank, expecting the plugin's own check to stop me. The build report:

result=Succeeded  seconds=151.1  errors=1  warnings=0
[Preprocess Player] Exception: BuildMethodException: [GoogleMobileAds]
  Android Google Mobile Ads app ID is empty.

Succeeded, and errors=1, at the same time. Exit code 0, APK on disk, and that APK died on
launch because the manifest was missing the value the pre-processor never got to write.

The mechanism is in Unity's own stack trace:

UnityEditor.Build.BuildPipelineInterfaces:InvokeCallbackInterfacesPair (…)
  (at Editor/Mono/BuildPipeline/BuildPipelineInterfaces.cs:492)
UnityEngine.Debug:LogException(Exception)
  (at Editor/Mono/BuildPipeline/BuildPipelineInterfaces.cs:505)

Unity catches whatever an IPreprocessBuildWithReport throws, logs it, and carries on to the
next callback. So no plugin can stop your build by throwing, however firmly its
documentation says otherwise. The exception becomes a line in a log nobody reads, and the
build continues without whatever that pre-processor was supposed to do.

I wrote that one up separately, with the crash trace and the manifest dumps, in
the AdMob post.

The import that imported nothing

Importing a .unitypackage from an editor method looks like this, and does nothing:

AssetDatabase.ImportPackage(pkg, false);
AssetDatabase.Refresh();
Debug.Log("done");     // prints

It printed done. It exited 0. Assets/ was untouched — no error, no warning, no partial
import. ImportPackage schedules work on the editor's main loop, and -quit tears the editor
down before that loop runs again.

The command-line argument is synchronous and does work:

Unity -batchmode -quit -projectPath "$P" -importPackage thing.unitypackage

Anything asynchronous is suspect under -quit. If a call returns void and its work shows up
in the Project window a moment later when you do it by hand, it will probably no-op in
batchmode.

The setting that was quietly overruled

PlayerSettings.Android.minSdkVersion = AndroidSdkVersions.AndroidApiLevel23;

Unity logged this as an error and then ignored me:

Minimum supported Android API level is 25 (Android 7.1 Nougat).
Please use AndroidApiLevel25 or higher.

The shipped APK reported minSdkVersion:'25'. The build still exited 0. A Debug.LogError
during a build is not a build failure — it does not increment the report's error count and it
does not change the exit code. Worth knowing before you trust a grep for error in a Unity
log, because you will match hundreds of them that mean nothing.

The plugin in that project logged Verified Minimum API Level is >= 23. two lines later,
against its own constant. Both were satisfied. Neither was right.

The one that failed properly

For contrast, here is Unity refusing:

LAB_RESULT result=Unknown errors=1
LAB_MSG [Build player] Error: Cannot build untitled scene.

Exit code 1, no APK. This is what a real failure looks like — result is not Succeeded, and
the process returns non-zero. I had passed scenes = new string[0] and never saved a scene,
so there was nothing to build. Save one first:

var scene = EditorSceneManager.NewScene(NewSceneSetup.DefaultGameObjects, NewSceneMode.Single);
EditorSceneManager.SaveScene(scene, "Assets/Scenes/Main.unity");

The useful part is the contrast. Unity can fail your build and return non-zero. It just does
not do it for any of the three cases above.

What to check instead of the exit code

The build report already knows. Read both fields, not one:

var r = BuildPipeline.BuildPlayer(opts);
var s = r.summary;
if (s.result != BuildResult.Succeeded || s.totalErrors > 0)
{
    foreach (var step in r.steps)
        foreach (var m in step.messages)
            if (m.type == LogType.Error || m.type == LogType.Exception)
                Debug.Log($"[{step.name}] {m.type}: {m.content}");
    EditorApplication.Exit(1);
}

totalErrors > 0 is the line that catches the swallowed pre-processor exception, and printing
report.steps is what tells you which step produced it — the console alone will not, because
by then it is thousands of lines of Gradle output.

Then check the artifact rather than the log, because a build that lies in its report will also
lie in its log. For an Android build that is one command, using the aapt2 already in your
Android SDK:

aapt2 dump xmltree app.apk --file AndroidManifest.xml | grep -c "YOUR_REQUIRED_META_DATA"
aapt2 dump badging app.apk | grep -E "minSdkVersion|targetSdkVersion"

That is what caught the missing App ID for me, after the report and the exit code had both
said everything was fine. If a value has to be in the manifest for the app to start, assert on
it in CI. It costs a second and it is the only check that reads what your players will run.

Takeaway

When a unity build not working search sends you looking for the error message, consider that
there may not be one. Unity's exit code covers a narrower set of failures than most people
assume: it catches a build it refused to start, and not much else. A pre-processor that threw,
a setting that was overruled, and an asynchronous call that never ran all look identical to a
passing pipeline.

Read summary.totalErrors, print report.steps, and inspect the file you built.

Originally published at Unity 6 Android build errors that exit 0.

Unity IL2CPP vs Mono on Android, measured

Othmane ETTAIB — Fri, 11 Sep 2026 18:44:26 +0000

Originally published on indiecore.net.

The advice you find on unity il2cpp vs mono is mostly repeated from 2019: IL2CPP is faster at
runtime, slower to build, and makes a bigger APK. I built the same project both ways on Unity
6000.4.0f1 to see which parts still hold. One of them is backwards, and the interesting result
is not a number at all.

The project is deliberately small — one scene, one MonoBehaviour doing two million
iterations of Math.Sqrt(i) / i so there is some managed work to compile. Android, release,
built from -batchmode on an M3 Max.

The numbers

	Mono2x	IL2CPP
Build, as reported by `BuildReport`	108.9 s	230.4 s
APK	27,301,649 bytes	14,323,788 bytes
ABI produced	`armeabi-v7a`	`arm64-v8a`
`.dll` files inside the APK	101	1

IL2CPP produced an APK 12,977,861 bytes smaller — 47.5% less — and took 2.1× as long to
build. The build-time half of the folklore is right. The size half is backwards, at least at
this project size and on this Unity version.

The native libraries say where it goes:

Mono, armeabi-v7a                 IL2CPP, arm64-v8a
  libunity.so        20,768,248     libunity.so       13,926,400
  libmonobdwgc-2.0.so 6,013,288     libil2cpp.so       9,651,328
  libmono-native.so   1,169,684     libc++_shared.so   1,292,904
  libMonoPosixHelper.so 350,080     + global-metadata.dat 1,555,108

Mono ships a 6 MB runtime to interpret your code, and a much larger libunity.so. IL2CPP
ships your code compiled into libil2cpp.so instead. In a bigger game libil2cpp.so grows
with your codebase while Mono's runtime stays fixed, so the gap narrows — do not read 47% as a
constant.

The .dll count is the line I would put in front of anyone who has not thought about it. A
Mono APK carries 101 real .NET assemblies, including yours. Renaming the file to .zip and
opening Assembly-CSharp.dll in any decompiler gives back readable C#. The IL2CPP build has
one. That is not obfuscation and IL2CPP is not a security feature, but the difference between
"unzip it" and "reverse a native binary" is real.

Mono cannot target ARM64

This is where I was wrong, and where checking mattered.

I assumed Unity would refuse to set ARM64 with the Mono backend. It does not:

PlayerSettings.SetScriptingBackend(NamedBuildTarget.Android, ScriptingImplementation.Mono2x);
PlayerSettings.Android.targetArchitectures = AndroidArchitecture.ARM64;
// reads back as: ARM64

No warning, no complaint. The setting sticks. The build is where it fails, and the message
is wrong about why:

LAB_CFG    backend=Mono2x arch=ARM64
LAB_RESULT result=Failed errors=1
[Prepare For Build] Exception: UnityException: Target architecture not specified

The architecture was specified. It is ARM64, and it is printed on the line above. Exit code 1,
no APK. If you search that string you will find people adding architectures to a project that
already had one.

Then the case that actually costs somebody a release. Select both ARMv7 and ARM64, which
is what you do when you want a universal build:

LAB_CFG    backend=Mono2x arch=ARMv7, ARM64
LAB_RESULT result=Succeeded errors=0

Exit code 0. No errors. No warnings. I grepped the entire build log for arm64, 64-bit and
architecture and found nothing. The APK it produced contains:

lib/armeabi-v7a/

That is all. It is byte-for-byte the same size as the ARMv7-only build, 27,301,649 bytes. You
asked for two architectures, you got one, and the build told you it succeeded. Google Play
requires a 64-bit version of every native library, so this is a green build that gets rejected
at upload with nothing in the Unity log to explain it.

The comparison I could not make

I could not measure which backend is faster at runtime, and the reason is the practical
answer to unity android il2cpp or mono in 2026.

$ adb shell getprop ro.product.cpu.abilist
arm64-v8a

$ adb install -r mono.apk
Failure [INSTALL_FAILED_NO_MATCHING_ABIS: Failed to extract native libraries, res=-113]

The test device — an Android 16, API 36 emulator image — has no 32-bit support at all. The
Mono build cannot be installed on it. Since Mono cannot produce arm64, there is no
configuration in which a Mono build runs on that device, and every arm64-only Android device
in the field is in the same position.

So I have no unity android mono vs il2cpp speed figure to give you. I also will not give you
the IL2CPP numbers I did collect: across four cold launches the same APK measured 570, 1561,
2020 and 2514 ms to first frame, and the managed loop took between 10 and 24 ms. A 4.4× spread
is emulator noise, and quoting the fastest one would be a made-up result. Startup timing needs
real hardware and many more runs than I did.

What this changes

For an Android game, unity il2cpp android is not a performance decision any more. It is the
only backend that produces a binary current devices will install and Google Play will accept.
Mono's remaining use is the editor and fast local iteration, where the shorter build genuinely
helps.

Two things to take away if you touch these settings. Set the architecture after the
backend and log what it reads back, because Unity will accept a combination it cannot build.
And check the ABIs in the artifact rather than the project settings:

unzip -l app.apk | grep -oE "lib/[a-z0-9-]+/" | sort -u

One line, and it catches the silent 32-bit-only build before Google Play does.

Originally published at Unity IL2CPP vs Mono on Android, measured.

What AdMob Unity mediation adapter status means

Othmane ETTAIB — Fri, 11 Sep 2026 18:44:24 +0000

Originally published on indiecore.net.

A while back I initialised the Google Mobile Ads SDK in a Unity project with no mediation set
up at all, and the callback handed me this:

adapter com.google.android.gms.ads.MobileAds = Ready
adapter com.google.ads.mediation.vungle.VungleMediationAdapter = NotReady
adapter com.google.ads.mediation.applovin.AppLovinMediationAdapter = NotReady
adapter com.google.ads.mediation.adcolony.AdColonyMediationAdapter = NotReady

Three adapters I had never installed, all reporting NotReady. That looks like a broken
mediation setup, and people rewrite their configuration over it. So I installed one properly
and compared.

This continues the lab from the AdMob SDK post: Unity
6000.4.0f1, a Pixel 9 Pro emulator on Android 16. The adapter is Liftoff Monetize 5.7.7 —
Vungle, renamed — which is one of the three in that list.

It is worth saying what this post is not. If you came from admob unity integration,
admob unity tutorial, admob unity guide or how to integrate admob in unity, the
walkthrough for getting the SDK into a project and building an APK is
that post, not this one, and admob unity github will
take you to the plugin source. This one picks up afterwards, at the line in your log naming
ad networks you have never heard of.

Read the description, not the state

AdapterStatus has an InitializationState and a Description. Everyone logs the state. The
description is the field that carries the information. With the Liftoff adapter genuinely
installed:

adapters=4
com.google.android.gms.ads.MobileAds                       = Ready    ()
com.google.ads.mediation.vungle.VungleMediationAdapter     = NotReady (Timeout.)
com.google.ads.mediation.applovin.AppLovinMediationAdapter = NotReady (Failed to create Adapter.)
com.google.ads.mediation.adcolony.AdColonyMediationAdapter = NotReady (Failed to create Adapter.)

All three still say NotReady. But the one I installed says Timeout. and the two I did
not say Failed to create Adapter.

That is the distinction:

Failed to create Adapter. — the adapter class is not in your build. The SDK knows the name, tried to instantiate it, and there was nothing there. Nothing is wrong. This is what every uninstalled adapter looks like.
Timeout. — the adapter is present and ran, and did not finish initialising. Now you have something to fix.

So the log that started this was never evidence of a problem. play-services-ads enumerates
adapters it has heard of, and reports on the ones that are absent in exactly the same NotReady
state as the ones that are broken. Log the description or the state alone will mislead you:

foreach (var kv in status.getAdapterStatusMap())
    Debug.Log($"{kv.Key} = {kv.Value.InitializationState} ({kv.Value.Description})");

Mine timed out for a reason logcat was happy to explain:

W/VungleMediationAdapter: Multiple 'appid' entries found:
  [fake-vungle-app-id, 54d153ece5b12c181f0000b4].
  Using 'fake-vungle-app-id' to initialize the Vungle SDK.

I have no Liftoff account, so AdMob served a placeholder app id and the adapter dutifully tried
to initialise the Vungle SDK with the string fake-vungle-app-id. Which is honest of it.

Two errors on the way in

Installing the adapter is where the time actually goes. Both failures below are exact.

The scoped registry was too narrow. The adapters live on OpenUPM, and the obvious scope is
the one matching the package name:

"scopes": ["com.google.ads.mobile"]

An error occurred while resolving packages:
  com.google.external-dependency-manager (dependency):
  Package [com.google.external-dependency-manager@1.2.186] cannot be found

Exit code 1 in 22 seconds, never reaching the build. The adapter depends on the plugin, and
the plugin depends on the External Dependency Manager, which is a different scope. Add it:

"scopes": ["com.google.ads.mobile", "com.google.external-dependency-manager"]

Then the two install methods collided. My project already had the plugin installed from
GoogleMobileAds-v11.5.0.unitypackage, under Assets/. The adapter pulls
com.google.ads.mobile@11.0.0 from UPM, under Packages/. Same files, two homes:

result=Failed  errors=238
GUID [c0080e86890c24abba53b3f4d2daf6db] for asset
  'Packages/com.google.ads.mobile/GoogleMobileAds/Editor/AndroidBuildPreProcessor.cs'
  conflicts with: …
Found plugins with same names,
  Packages/com.google.ads.mobile/Plugins/Android/googlemobileads-unity.aar and
  Assets/Plugins/Android/googlemobileads-unity.aar.
  Delete the one of the duplicate plugins.

238 errors. Pick one install method. I deleted the Assets/ copy and let UPM own it, keeping
Assets/GoogleMobileAds/Resources/GoogleMobileAdsSettings.asset, which holds the App ID and is
not part of the package.

The downgrade nobody mentions

Watch what the resolver wrote into mainTemplate.gradle afterwards:

implementation 'com.google.ads.mediation:vungle:7.7.4.0'
implementation 'com.google.android.gms:play-services-ads:25.0.0'

25.0.0. Before the switch, the .unitypackage at 11.5.0 was resolving
play-services-ads:25.4.0. Taking the OpenUPM route moved me back four minor versions of the
ads SDK, because the adapter pins com.google.ads.mobile@11.0.0 and that is what 11.0.0 asks
for. Nothing warns. If you are on a recent .unitypackage and add a mediation adapter from
OpenUPM, check the resolved version afterwards.

What it costs

I nearly published a wrong number here. Comparing the mediation build against my earlier APK
suggested the adapter cost about 11 MB, which would be alarming — but those two builds also
differed in build type and plugin version. With a proper control, same UPM plugin, same
development build, only the adapter changing:

	APK bytes
Plugin only	30,188,822
Plugin + Liftoff Monetize	30,962,294

773,472 bytes, 0.74 MiB, +2.6%. One adapter is cheap. The point generalises: if two builds
differ in more than one thing, the difference between them is not a measurement.

What I did not test

A mediation adapter with real credentials, actually filling. That needs a Liftoff account and
a configured waterfall in the AdMob console, so I cannot tell you anything about fill, latency
or revenue. Everything above is about getting the adapter into the build and reading what the
SDK says about it.

Takeaway

Log Description alongside InitializationState, because on its own the state cannot
distinguish an adapter you never installed from one that is failing. Failed to create Adapter. on a network you do not use is the correct, healthy output, and it is not worth a
single minute of debugging.

Originally published at What AdMob Unity mediation adapter status means.

The AdMob Unity SDK check that stops nothing

Othmane ETTAIB — Thu, 10 Sep 2026 18:41:22 +0000

Originally published on indiecore.net.

I imported the AdMob Unity SDK into an empty Unity 6000.4.0f1 project, built a release APK,
and then left the one field the plugin says it cannot build without empty — to see what the
error looked like.

There was no error. There was a 19,627,503-byte APK that installs, launches, and dies before
Unity draws a single frame.

Everything below came off this laptop: an M3 Max on macOS 26.5.1, Unity 6000.4.0f1 Personal
with the Android module, and GoogleMobileAds-v11.5.0.unitypackage, published four days
before I ran this.

However you phrased the search that brought you here — admob unity integration,
admob unity tutorial, admob unity guide, how to integrate admob in unity, or
admob unity github when you wanted the source instead of somebody's screenshots — the steps
are further down, under Getting it to work. The reason they are not at
the top is that the interesting part of this run was the failure the plugin promises to give
you and does not.

What version 11.5.0 actually pulls in

Before building anything, it is worth reading what the package declares, because the numbers
people quote in forum threads are usually two years old. GoogleMobileAdsDependencies.xml, on
Android:

<androidPackage spec="com.google.android.gms:play-services-ads:25.4.0">
<androidPackage spec="androidx.constraintlayout:constraintlayout:2.1.4">
<androidPackage spec="androidx.lifecycle:lifecycle-process:2.6.2">
<androidPackage spec="androidx.fragment:fragment:1.7.1">

And GoogleUmpDependencies.xml adds com.google.android.ump:user-messaging-platform:4.0.0.
The bundled External Dependency Manager is 1.2.188. There is a second, newer ads library the
plugin knows about and does not use by default —
com.google.android.libraries.ads.mobile.sdk:ads-mobile-sdk:1.4.0, which the source calls
NextGen and which raises the minimum API level from 23 to 24.

Importing the package headless is the first thing that bit me. This does nothing at all:

AssetDatabase.ImportPackage(pkg, false);   // returns immediately, imports nothing

It logged my "done" line, exited 0, and left Assets/ exactly as it was. ImportPackage is
asynchronous and -quit tears the editor down before it runs. The command-line argument is
synchronous and works:

Unity -batchmode -quit -projectPath "$P" \
      -importPackage GoogleMobileAds-v11.5.0.unitypackage

The check that stops nothing

AndroidBuildPreProcessor.cs opens with a class comment listing what it does. Second item:

Throw an exception if the Android Google Mobile Ads app ID is not set.

No such check exists in that class. It lives in a different file, ManifestProcessor.cs:

string appId = instance.GoogleMobileAdsAndroidAppId.Trim();
if (appId.Length == 0) {
  StopBuildWithMessage(
    "Android Google Mobile Ads app ID is empty. Please enter a valid app ID to run ads properly.");
}

The two classes have different callbackOrder values — -1 for the Gradle pre-processor,
0 for the manifest one. So the ordering is: resolve every Android dependency, download
play-services-ads, write the Gradle templates, and then look at the text box.

I expected that to waste two minutes and fail. Here is what the build report said instead:

LAB_RESULT result=Succeeded seconds=151.1 totalSize=135445990 errors=1 warnings=0
LAB_MSG [Preprocess Player] Exception: BuildMethodException: [GoogleMobileAds]
  Android Google Mobile Ads app ID is empty. Please enter a valid app ID to run ads properly.

result=Succeeded with errors=1. The process exited 0. The APK was on disk.

The reason is in Unity's own stack trace, and it is not the plugin's fault:

UnityEditor.Build.BuildPipelineInterfaces:InvokeCallbackInterfacesPair (…)
  (at Editor/Mono/BuildPipeline/BuildPipelineInterfaces.cs:492)
UnityEngine.Debug:LogException(Exception)
  (at Editor/Mono/BuildPipeline/BuildPipelineInterfaces.cs:505)

Line 505 logs the exception. Line 492 keeps going. Unity catches whatever an
IPreprocessBuildWithReport throws, writes it to the console, and continues the build. A
plugin cannot stop your build by throwing, however loudly it says it will.

What ended up in the APK

The plugin never got to write the App ID, so I checked what the artifact actually contained
with aapt2 — the tool in your Android SDK, reading the built file, not the project.

aapt2 dump xmltree noappid.apk --file AndroidManifest.xml \
  | grep -c "com.google.android.gms.ads.APPLICATION_ID"
0

Zero. But everything else the SDK merges was there:

com.google.android.gms.ads.MobileAdsInitProvider
com.google.android.gms.ads.AdActivity
com.google.android.gms.ads.AdService
com.google.android.gms.ads.OutOfContextTestingActivity
com.google.android.gms.ads.flag.OPTIMIZE_INITIALIZATION
com.google.android.gms.ads.flag.OPTIMIZE_AD_LOADING

Two dex files, 8,385,264 and 7,960,200 bytes, carrying 1,002 references to
com/google/android/gms/ads between them. So the APK ships an ad SDK that boots itself
through a ContentProvider, and no App ID for it to boot with.

What that does on a real device

I installed it on a Pixel 9 Pro emulator, Android 16, API 36, Play Store system image.

E/AndroidRuntime: FATAL EXCEPTION: main
Process: com.indiecore.admoblab, PID: 3041
java.lang.RuntimeException: Unable to get provider
  com.google.android.gms.ads.MobileAdsInitProvider:
  java.lang.IllegalStateException:

******************************************************************************
* Missing application ID. AdMob publishers should follow the instructions    *
* here: https://goo.gle/admob-android-update-manifest.                       *
* to add a valid App ID inside the AndroidManifest.                          *
******************************************************************************

  at android.app.ActivityThread.installProvider(ActivityThread.java:8647)
  at android.app.ActivityThread.installContentProviders(ActivityThread.java:8157)
  at android.app.ActivityThread.handleBindApplication(ActivityThread.java:7814)
Caused by: java.lang.IllegalStateException:
  at com.google.android.gms.ads.internal.client.zzev.attachInfo(
     com.google.android.gms:play-services-ads-api@@25.4.0:21)

It dies in handleBindApplication. That is a ContentProvider installed before
Application.onCreate, which is before Unity exists — so nothing of yours runs, no splash
screen appears, and no Unity log line is written. If you have ever seen a Unity game that
force-closes instantly on launch with nothing in the player log, this shape of failure is
worth checking first.

Note the version in the trace: play-services-ads-api@@25.4.0, matching the dependency file
exactly. The resolver did its whole job. Only the text box was missing.

Getting it to work

The fix is the App ID, and Google publishes a sample one so you never have to put a real unit
in a test build:

const string TestAppId  = "ca-app-pub-3940256099942544~3347511713";
const string TestBanner = "ca-app-pub-3940256099942544/6300978111";

GoogleMobileAdsSettings.LoadInstance() is internal, so from your own editor code the way
in is the asset:

var settings = AssetDatabase.LoadAssetAtPath<ScriptableObject>(
    "Assets/GoogleMobileAds/Resources/GoogleMobileAdsSettings.asset");
var so = new SerializedObject(settings);
so.FindProperty("adMobAndroidAppId").stringValue = TestAppId;
so.ApplyModifiedPropertiesWithoutUndo();
AssetDatabase.SaveAssets();

That build came out clean — errors=0, and aapt2 now shows
APPLICATION_ID = ca-app-pub-3940256099942544~3347511713 in the manifest. It launched, and a
banner loaded:

One more thing had to be fixed on the way, and it is quiet enough to miss:

Assembly 'Assets/GoogleMobileAds/GoogleMobileAds.Unity.dll' will not be loaded due to errors:
Unable to resolve reference 'UnityEngine.UI'.

My project had com.unity.modules.ui but not com.unity.ugui, so the assembly providing
UnityEngine.UI did not exist. The plugin's Unity-side DLLs need it. That is a warning, the
build succeeds without them, and you find out later. Adding "com.unity.ugui": "2.0.0" to
Packages/manifest.json cleared it. A project made from a Hub template already has it; mine
was made with -createProject, which does not add it.

What adding the SDK costs

Same project, same settings, one variable:

Build	APK bytes	Gradle-stage time
No AdMob	14,316,448	143.9 s
AdMob, valid App ID	19,640,015	—

That is +5,323,567 bytes, or 5.08 MiB — a 37% increase on an otherwise empty game. For a
small puzzle game that is a real number, and it arrives before you have shown a single ad.

Two toolchain facts worth writing down, because both contradict what the machine looks like
from the outside. Unity used its own bundled JDK, Temurin 17.0.9, not the OpenJDK 25.0.2 that
java -version reports here; and its own copy of the Android SDK under PlaybackEngines, not
~/Library/Android/sdk. Gradle 8.13, Android Gradle Plugin 8.10.0.

Two smaller things

I set PlayerSettings.Android.minSdkVersion = AndroidApiLevel23, which is what AdMob's
documentation asks for. Unity logged an error and overruled me:

Minimum supported Android API level is 25 (Android 7.1 Nougat).
Please use AndroidApiLevel25 or higher.

Two lines later, AdMob's pre-processor logged Verified Minimum API Level is >= 23. It still
carries const int StandardMinimumAPILevel = 23; and is checking against a floor Unity 6 has
already moved. Nothing breaks, but AdMob's documented minimum of 23 is not reachable here;
the shipped APK reports minSdkVersion:'25'.

The second thing is the one I would have searched admob unity mediation over, and it
surprised me. With no mediation adapters installed at all, the initialization callback listed
three:

adapter com.google.android.gms.ads.MobileAds = Ready
adapter com.google.ads.mediation.vungle.VungleMediationAdapter = NotReady
adapter com.google.ads.mediation.applovin.AppLovinMediationAdapter = NotReady
adapter com.google.ads.mediation.adcolony.AdColonyMediationAdapter = NotReady

play-services-ads 25.4.0 enumerates adapters it knows about and reports on ones that are
absent. Three NotReady lines in your log are not evidence that a mediation setup is broken.

The null result I nearly published

For a while I had a good story: the banner code ran on one build and produced no log output on
another, and I could have written that up as a stripping bug.

It was not one. I checked the scene first — the built level0 was 1,820 bytes without my
component and 2,160 with it, so the object shipped. Then the binary: AdLoader and my log
strings were both present in global-metadata.dat in every APK, so IL2CPP had stripped
nothing. Then I reinstalled the identical APK on a freshly booted emulator, and it logged
normally.

Same binary, different result, so the variable was the device. On a cold emulator, AdMob's
first initialization is slow:

t+0s    calling MobileAds.Initialize
t+45s   initialize callback fired
t+85s   banner LOADED

I had been sampling logcat for 25 seconds. The null result was impatience, and the honest
version of this article says so rather than shipping a plausible cause I never tested.

Takeaway

Read the guard rather than trusting it. A build check written as a thrown exception in an
IPreprocessBuildWithReport cannot stop a Unity build, so treat those messages as warnings no
matter how they are phrased. Then check the artifact: aapt2 dump xmltree your.apk --file AndroidManifest.xml takes a second and tells you what you actually built, which is the only
thing your players will run.

Originally published at The AdMob Unity SDK check that stops nothing.

AdMob limited ad serving on the wrong app

Othmane ETTAIB — Thu, 10 Sep 2026 18:40:48 +0000

Originally published on indiecore.net.

Logo Quiz: Guess Brand is Android-only and has been on Play
for a few versions. At some point I created a second AdMob app for it. I no longer remember
why — probably to start clean after fumbling something in the first one.

The result was AdMob limited ad serving on the game that was actually live — ads coming
from an app AdMob would not verify, next to a verified app with nothing in it, and no way to
swap them from the Play Console.

What "limited" actually means here

AdMob will happily give you an app ID and ad unit IDs before it knows the app exists in a
store. Until you link that AdMob app to its store listing, it stays unverified, and unverified
apps get limited ad serving — low fill, low eCPM, no programmatic demand. The ads are not
off. They are just worth very little, which is harder to notice than an outage.

It is worth being precise about which limit this is, because the phrase is overloaded. Search
for admob limited ads and most of what comes back is the Policy centre kind: a violation, a
suspension, a temporary ad serving limit placed on your AdMob account while somebody reviews it.
That was not my problem, and nothing below will lift one. Mine was the boring administrative
kind — an app nobody had ever linked to a store listing — and the fix has nothing to do with
policy.

The rule nobody states until you hit it

A Play Store listing links to exactly one AdMob app.

That single sentence is the whole problem. My second AdMob app had claimed the Logo Quiz
listing and been verified. My first AdMob app — the one whose IDs were compiled into the APK
people had actually installed — could not be linked, because the listing it needed was already
spoken for. AdMob does not offer to move the link. The console simply does not show the
listing as available any more.

So there were two apps, and each was missing exactly what the other had:

	App A (in the build)	App B (linked)
Ad units	banner, interstitial, rewarded	none
Store listing	cannot link — taken	linked and verified
Ad serving	limited	nothing to serve

How to remove the AdMob app ad serving limit

For the verification kind, there are two ways, and the cheap one is not the obvious one.

Delete App B. It had no ad units, so there was nothing in it to lose. Deleting or
unlinking it frees the listing, and App A — already shipping, already wired up — can then be
linked and verified. No code change. No new release. The version already on people's phones
starts serving properly once verification goes through.

Or move to App B. Create the three ad units there, swap four IDs in the project, build,
upload, and wait for players to update.

I recommended the first one. We went with the second — the three ad units in App B got created
while we were still deciding, and at that point shipping a release we were going to ship anyway
felt easier than unpicking it.

I still think deleting the empty app is the better default. It is the option with no tail:
nothing to roll out, nothing to wait for, no window where half your installs are on old IDs.

What the swap actually cost

Four IDs, and I would have got it wrong if I had only changed the obvious ones.

The app ID lived in two places, not one. There is the react-native-google-mobile-ads
block in app.json, which is the one you find first:

"react-native-google-mobile-ads": {
  "android_app_id": "ca-app-pub-3940256099942544~3347511713"
}

And there is the same ID again in AndroidManifest.xml, carrying a tools:replace so that it
wins the manifest merge:

<meta-data
  android:name="com.google.android.gms.ads.APPLICATION_ID"
  android:value="ca-app-pub-3940256099942544~3347511713"
  tools:replace="android:value" />

The ID in both blocks is Google's published sample app ID rather than mine, which is redacted.
The shape is the part worth copying.

Change only app.json and the build still succeeds — with the old app ID baked into the APK,
because the manifest entry is the one that ends up in the package. That is a silent wrong
answer, which is the kind I care about most.

So I stopped trusting the source and checked the artifact instead. The app ID is readable
straight out of the bundle:

unzip -p app-release.aab base/manifest/AndroidManifest.xml | strings | grep -o "ca-app-pub-[0-9]*~[0-9]*"

One line, and it answers the only question that matters: what did I actually ship.

The other cost is the one that keeps arriving. Because the fix travels inside a release, it
spends a versionCode — the swap went out as 1.0.10. Then a second pass at the same build,
later the same night, needed an upload of its own, and 10 was gone. Play rejects a re-used
number, so that became 1.0.11.

Nothing about that is hard. It is just a cost that only exists because I chose the option that
needs a release. Deleting the empty AdMob app would have spent no version numbers at all,
because it changes nothing in the build.

One thing that did not cost anything: the publisher ID was the same for both apps, so
app-ads.txt never had to change. If you end up moving between two different AdMob accounts,
that file does need updating, and it is a separate way to end up with poor fill.

You cannot check this on an emulator

I installed the release build on an emulator to confirm the banner still loaded, and it did —
labelled Test Ad.

That is not a bug and not a configuration mistake. AdMob treats emulators as test devices
unconditionally, so a "Test Ad" is the correct and only outcome there. It proves the SDK
initialised and the ad unit was requested. It proves nothing whatsoever about whether the
limit has lifted.

The actual verification is in the AdMob console: the app has to stop showing a prompt to link
a store listing. If it still shows one, shipping the release changed nothing about the
admob limited ad serving state, and you have spent a release finding that out.

What I would do differently

Create the AdMob app once, and link it to the Play listing before wiring a single ID into the
build. The linking step is free at that point and expensive later, because later means the
listing is claimed by whichever app you created first — including the one you have decided to
abandon.

And if a second app already exists, look at which of the two is empty before deciding which
one to keep. The instinct is to keep the app you have already integrated. The cheaper move is
usually to delete the one with nothing in it and let the app you already shipped inherit the
listing it should have had.

Originally published at AdMob limited ad serving on the wrong app.

Gradle build failed is not the error

Othmane ETTAIB — Thu, 10 Sep 2026 18:40:46 +0000

Originally published on indiecore.net.

I made a throwaway Unity 6000.4.0f1 project on a Mac, built a release APK from it, and then
broke it four different ways to see what the console would say. The APK took 155 seconds in
the Gradle stage and came out at 27 MB. Every failure below is from a log on this laptop, not
from a thread I read.

The reason for doing it that way: the message everybody searches for says nothing about the
project that produced it, and I wanted to know exactly where the part that does say something
had gone.

The error you searched for

However you phrased it — unity gradle build failed, unity error gradle build failed,
unity commandinvokationfailure gradle build failed, unity android build failed gradle,
unity 6 gradle build failed, unity 2022 gradle build failed,
unity firebase gradle build failed — you got here from the same eleven words in the console:

CommandInvokationFailure: Gradle build failed. 
/Applications/Unity/Hub/Editor/6000.4.0f1/PlaybackEngines/AndroidPlayer/OpenJDK/bin/java -classpath "/Applications/Unity/Hub/Editor/6000.4.0f1/PlaybackEngines/AndroidPlayer/Tools/gradle/lib/gradle-launcher-8.13.jar" org.gradle.launcher.GradleMain "-Dorg.gradle.jvmargs=-Xmx4096m" "assembleRelease" 

Environment Variables:
XPC_FLAGS = 0x0
CLAUDE_CODE_ENTRYPOINT = claude-vscode
ANDROID_NDK_ROOT = /Applications/Unity/.../AndroidPlayer/NDK
LANG = C.UTF-8

Sixty-seven of those variables in my log, and I counted them because I kept scrolling through
them looking for the reason. There isn't one in there. Unity started a Java process, the
process exited 1, and this block is Unity reporting which process it started. It would look
identical if the failure were a missing semicolon or a full disk.

Which is why the answers on the first page of results are all different from each other, and
why none of them worked for you. They are answers to different questions that produce the same
sentence.

Where the cause actually is

Here is the shape of the whole log for one failing build of an otherwise empty project — 1,572
lines, from a project with one scene and no gameplay in it:

Line	What is there
171	`CommandInvokationFailure: Unable to list connected devices` — unrelated, no phone plugged in
174	environment variables, first dump
921	`FAILURE: Build failed with an exception.`
923	*` What went wrong:` — the cause**
926–1336	410 lines listing every duplicate class
1140	`BUILD FAILED in 6s`
1158	`CommandInvokationFailure: Gradle build failed.`
1161	environment variables, second dump, 67 of them
1231	the whole thing again, quoted inside the exception

The line that tells you what to fix comes 235 lines before the line that tells you
something failed. Everyone scrolls down from the error. The answer is up.

Two other things that log shows. There is a CommandInvokationFailure at line 171 that has
nothing to do with the build — it is ADB failing to list devices, with its own full
environment dump, and in a headless build it is always there. And the real Gradle output is
printed twice: once as it happens, once again quoted inside the exception body at line 1231,
which is why the log looks twice as bad as the problem is.

So stop reading the console and grep the log:

grep -A6 '^\* What went wrong:' ~/Library/Logs/Unity/Editor.log

That worked on every failure I produced. The Editor log is at
~/Library/Logs/Unity/Editor.log on macOS, %LOCALAPPDATA%\Unity\Editor\Editor.log on
Windows, ~/.config/unity3d/Editor.log on Linux.

Unity also saves the Gradle run on its own, which is cleaner to read and easier to link to a
colleague:

Library/Bee/Android/Prj/<Mono2x|IL2CPP>/Gradle/launcher/build/outputs/logs/unity-assembleRelease-build.log

Four builds I broke on purpose

One jar, twice

I copied unity-classes.jar out of the generated Gradle project into
Assets/Plugins/Android/ under a second name, which is structurally what happens when two
plugins each vendor the same library.

* What went wrong:
Execution failed for task ':launcher:checkReleaseDuplicateClasses'.
> A failure occurred while executing com.android.build.gradle.internal.tasks.CheckDuplicatesRunnable
   > Duplicate class com.unity3d.player.UnityPlayer found in modules unity-classes-copy.jar
     -> jetified-unity-classes-copy (unity-classes-copy.jar) and unity-classes.jar -> ...

410 lines of that, one per class. The task name is the useful part:
checkReleaseDuplicateClasses means two artifacts on the classpath contain the same class,
and the two module names on the first line are the two to reconcile. In a real project the
pair is usually AdMob and In-App Purchase pulling different versions of Play Billing or
play-services-basement through the External Dependency Manager, and the first thing to try
is Assets → External Dependency Manager → Android Resolver → Delete Resolved Libraries,
then a force resolve.

A repository in the wrong file

This one is specific to Unity 2022.2 and later, and it is worth knowing because the
instructions shipped with a lot of ad and analytics SDKs are older than the change.

I added a JitPack-only dependency to Assets/Plugins/Android/mainTemplate.gradle and, in the
same file, the repository it lives in:

dependencies {
    implementation fileTree(dir: 'libs', include: ['*.jar'])
**DEPS**    implementation 'com.github.PhilJay:MPAndroidChart:v3.1.0'
}

repositories {
    maven { url 'https://jitpack.io' }
}

* What went wrong:
Execution failed for task ':launcher:checkReleaseDuplicateClasses'.
> Could not resolve all files for configuration ':launcher:releaseRuntimeClasspath'.
   > Could not find com.github.PhilJay:MPAndroidChart:v3.1.0.
     Searched in the following locations:
       - https://dl.google.com/dl/android/maven2/com/github/PhilJay/...
       - https://repo.maven.apache.org/maven2/com/github/PhilJay/...

JitPack is not in that list. The repository block was read, parsed, and ignored, because
Unity's generated settings.gradle sets:

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)

Under PREFER_SETTINGS, Gradle discards repositories declared anywhere else. No warning
appears — the only symptom is a search list that quietly lacks the one place the artifact
exists.

The fix is the same declaration, moved. Copy settingsTemplate.gradle next to
mainTemplate.gradle and put the repository in its dependencyResolutionManagement block:

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)
    repositories {
        **ARTIFACTORYREPOSITORY**
        maven { url 'https://jitpack.io' }
        google()
        mavenCentral()

Same dependency, same project, next build succeeded. If a plugin's README tells you to edit
mainTemplate.gradle and the artifact still cannot be found, the README predates this.

A mainTemplate.gradle from an older Unity

I dropped in the template Unity 2019 and 2020 generated — the one with
minSdkVersion **MINSDKVERSION**, lintOptions and aaptOptions — which is exactly what a
project carries when it has been upgraded and the file was committed years ago.

Gradle never ran. Unity 6 stopped at the prerequisites step:

Assets/Plugins/Android/mainTemplate.gradle file is missing the CMake arguments required
for GameActivity and Framepacing to work. To fix this, add "**DEFAULT_CONFIG_SETUP**"
inside the defaultConfig block. If not fixed, your build can fail.

UnityException: Error
mainTemplate.gradle file is using the old androidResources noCompress property definition
which does not include types defined by unityStreamingAssets constant.

That is a genuine improvement, and it changes the advice. The Unity 6 token names differ from
the old ones — **MINSDK** rather than **MINSDKVERSION**, compileSdk rather than
compileSdkVersion, lint rather than lintOptions — so if you have a custom template, the
reliable move after an editor upgrade is to copy the current one out of

<editor>/PlaybackEngines/AndroidPlayer/Tools/GradleTemplates/mainTemplate.gradle

and reapply your handful of edits to it, rather than patching the old file forward.

The one that refused to break

I tried to reproduce the most-cited conflict of the past two years — the app declaring a
lower minimum SDK than a library it depends on — by setting the project to API 22 and adding
com.google.android.gms:play-services-ads:24.3.0, which needs 23. The build failed, but not
where I expected:

Assets/Editor/BuildAndroid.cs(26,48): error CS0619: 'AndroidSdkVersions.AndroidApiLevel22'
is obsolete: 'Minimum supported Android API level is 25 (Android 7.1 Nougat).
Please use AndroidApiLevel25 or higher.'

Unity 6000.4 will not compile a script that names API 22. The floor is 25, above every
current Play Services minimum, so the classic
uses-sdk:minSdkVersion 22 cannot be smaller than version 23 declared in library is no longer
reachable from a modern editor — it is still the top answer on threads dated July 2025, and
still the right answer if you are on 2021 or 2022 LTS. With the floor left alone, that same
AdMob dependency resolved and built with no changes at all.

A second one that would not break: putting <uses-sdk android:minSdkVersion="34" /> in the
manifest of an .androidlib under Assets/Plugins/Android/. Unity regenerates that module's
build.gradle with the player's minimum, so the manifest declaration is overridden and the
build succeeds. Library minimums bite when they arrive as an AAR from a repository, not when
they are sitting in your own project.

Two pieces of stale advice

Both come from a time when Unity used your machine's tooling. It does not.

The prerequisites step prints what it is actually going to use, and mine looked like this:

 JDK: '/Applications/Unity/Hub/Editor/6000.4.0f1/PlaybackEngines/AndroidPlayer/OpenJDK'
 Android SDK: '/Applications/Unity/Hub/Editor/6000.4.0f1/PlaybackEngines/AndroidPlayer/SDK'
 Android NDK: '/Applications/Unity/Hub/Editor/6000.4.0f1/PlaybackEngines/AndroidPlayer/NDK'
 Gradle: '.../AndroidPlayer/Tools/gradle' (Gradle Version: '8.13' Android Plugin Version: '8.10.0')

Installing a JDK will not help. Unity ran its own bundled OpenJDK 17.0.9. The system Java
on this laptop is 25 and was never invoked. Pointing Unity at your Android SDK will not
help either — ANDROID_HOME was set to ~/Library/Android/sdk in the environment dump
Unity printed, and Unity used its own SDK anyway. Both answers were correct in 2019. They now
send people to change something that has no effect, then conclude their install is corrupt.

What is actually breaking builds this year

The failures I could not stage on an empty project, from reports with dates on them:

Gradle running out of heap, which surfaces as something else entirely. One November 2025 report on Unity 6000.0.58f2 shows it as Execution failed for task ':launcher:signReleaseBundle' and java.lang.IllegalArgumentException: Self-suppression not permitted, fixed by raising Maximum JVM Heap Size from 4096 to 8192 in Preferences → External Tools. If your unity android build error mentions bundling or signing and the project is large, try this before anything else.
16 KB page alignment. From 31 May 2026 Play stops accepting updates whose native libraries are 4 KB-aligned. NDK r27 and later emit aligned segments by default; the fix is an editor and NDK upgrade, not a Gradle setting.
Non-ASCII characters or spaces in the project path, still, still on Windows.
Two plugins, one library. The duplicate-class case above, arriving through the External Dependency Manager rather than by hand.

The takeaway

CommandInvokationFailure: Gradle build failed. is a category, in the way that "the car won't
start" is a category. Reading the console top to bottom is how you end up believing it is
about environment variables, and reinstalling the editor over a two-line Gradle problem.

Grep for * What went wrong:. Whatever it says next — a task name, a class name, a coordinate
that could not be found — that is the thing to search, and it has an answer.

Originally published at Gradle build failed is not the error.

One engine, many games

Othmane ETTAIB — Fri, 04 Sep 2026 01:56:41 +0000

Originally published on indiecore.net.

Part 1 of 10 on building a word-block puzzle engine. Series index at the bottom.

The second game was a copy of the first. That is not a confession, it is what everybody does,
and for about six weeks it is the correct decision — you do not know which parts are the game
and which parts are that game until you have built a second one.

The bill arrives later. I fixed a rounding bug in the star calculation, shipped it, and then
found the same bug sitting untouched in the sibling title, because the sibling was a folder
copy from before the fix existed. The fix took four minutes. Finding out the other game had it
took three weeks, because nothing told me.

What a copy actually costs

The honest number is not "duplicate code". It is the number of places a decision lives.

At the point I stopped, one game's src/ held 70 files: screens, the board renderer, the
store, hooks, the economy, the difficulty tiers, the sound layer, the ad wiring. The other
game held 70 files that were 90% the same, drifting apart one hotfix at a time.

Every one of those pairs is a place where two games can disagree. Not in theory — in practice,
what diverged first was exactly the stuff nobody looks at twice:

The interstitial cooldown, changed in one game after a review complaint.
The daily-chest table, retuned in one game and not the other.
A catalog.json fetch that got an error handler in one game after a crash report.

None of those are interesting enough to remember to port. All of them are the kind of thing
that turns two products into two codebases.

The split I landed on

There is a package that is the game, and an app directory per published title that is
nothing but identity.

packages/word-engine/     the game itself — 92 files
apps/<title>/src/          3 files

Three files. That is the whole shell:

src/main.jsx     mount the engine, hand it the content source
src/brand.js     turn brand.json into what the engine reads
brand.json       this build, as data

Everything else in an app directory is not code: an icon source, a board pack under public/,
a generated android/, a capacitor.config.json. The parts a designer or a store listing
would change, and none of the parts a bug lives in.

brand.json is data, deliberately

The temptation is to make the brand a module — a JS file exporting a config object, so you can
compute things in it. I did that first and had to undo it.

The problem is who needs to read it. The Vite config needs the board-pack directory so it can
shrink the pack on the way into dist/. The release script needs the app name and the store
identity. A provisioning check needs the leaderboard ids. None of those run inside the app's
module graph, and none of them should have to resolve src/ — or a JSX transform, or an alias
— to find out what folder the boards are in.

So the declaration is plain JSON:

{
  "id": "…",
  "defaultLanguage": "en-US",
  "content": {
    "stagesDir": "/stages-blocks-en",
    "dictionaryUrl": "/words-blocks-en.txt",
    "stageCount": 392
  }
}

and src/brand.js is two lines that hand it to the engine's defineBrand(). Interpretation
lives in the engine, where every sibling gets the same interpretation. The rule I kept
tripping over and eventually wrote down: if a value is worth setting per game it belongs in
brand.json; if it needs interpreting, that belongs in the engine.

The alias, and why it is not a setter

The engine has to reach the brand from ninety-odd files. The obvious approach is an
initialiser — setBrand(brand) at the top of main.jsx, before rendering.

That does not work, and the failure is quiet. Several engine modules read the brand as they
load: the string catalogues bake the game's name into seventeen languages at import time. A
setter runs after the imports it needs to precede, so those modules capture whatever the
default was and the game ships with the placeholder name in nine of its seventeen locales.

The fix is to make it a resolution concern rather than a runtime one. The shared Vite config
points an alias at the app's own file:

resolve: {
  alias: { '@brand': resolve(appDir, 'src/brand.js') },
}

Engine modules import brand from '@brand' and get this game's identity at module-evaluation
time, because that is what an alias is for. No ordering to get wrong.

The build has to be shared too, or it isn't shared

This is the part I underestimated. You can move all the game code into a package and still end
up with a fleet, because the build stays per-app. The first game that needs a Vite plugin
adds it to its own vite.config.js, the next game copies that file, and now there are as many
build configs as there are titles — which is the thing you just spent a month removing.

An app's Vite config is now one line:

export default defineGameConfig(import.meta.url)

import.meta.url rather than a path, because that is the single thing an app knows about
itself that the shared config cannot work out. Vite may load a config from a temp file
somewhere else on disk, which makes both process.cwd() and the shared module's own
import.meta.url unreliable — I found this the way everyone does, with an ENOENT naming a
path under node_modules/.vite-temp/.

The same argument applies to the native project, the release script and the pack tooling.
Those are parts 9 and 10.

What this does not fix

Two things, and they are worth saying because the pitch for "one engine" usually skips them.

The engine has to actually be general, and generality is a cost you pay per feature. A
change that would have been ten minutes inside one game is now a change to a shared package,
which means asking whether the sibling wants it, and often adding a brand field so it can say
no. That is the correct amount of friction and it is still friction.

Divergence pressure does not go away, it moves. When a store listing needs one game to
behave differently, the pressure lands on brand.json — and a declaration file with forty
fields in it is a copy of the old problem, wearing JSON. I do not have a clean rule for this
yet. The one heuristic that has held: if a field would only ever have two values and one of
them is "the way it already works", it is a bug in the engine, not a brand field.

The check that keeps a shell a shell

None of the above survives contact with a deadline unless something enforces it. The engine
ships a test suite that a shell runs against itself, and one of its assertions is simply that
the shell contains nothing but identity — no components, no store, no game logic.

import { describeGameShell } from '@gamefactory/word-engine/testing'

describeGameShell(import.meta.url)

That is the entire test file in each app. The suites live in the engine, because a copy of the
suite in each app is a copy that drifts, and the sibling whose copy is stale is exactly the one
that ships the broken pack. Part 7 is about what else it checks.

Was it worth it

The measurable part: adding the second title on the engine took a brand file, a board pack, an
icon and a native project. No source files. The next one will be the same, and that is the
whole return — not code reuse, which nobody can feel, but the fact that a bug fixed once is
fixed everywhere without anyone remembering to go and look.

The unmeasurable part is that I now think about "what is this game" and "what is a game" as
two different questions, and the answer to the second one is a package with a version number.

The series

Originally published at One engine, many games.

Lighthouse's image budget is w h 6

Othmane ETTAIB — Fri, 04 Sep 2026 01:56:39 +0000

Originally published on indiecore.net.

Lighthouse told me my home page was carrying 345 KiB of unnecessary image bytes, on a page
already scoring 99. The panel is called Improve image delivery and it gives you a list of
files, a savings figure, and one of two sentences under each:

Increasing the image compression factor could improve this image's download size.
This image file is larger than it needs to be (400×710) for its displayed dimensions (254×452). Use responsive images to reduce the image download size.

Those look like the same complaint. They are not, they behave differently, and only one of
them can ever reach zero on a site that serves retina screens.

Reading the constant out of the report

The HTML panel rounds everything. The JSON does not, and it gives you both the file size and
the bytes it considers wasted, which means the target it has in mind is just subtraction.

A 256×256 icon on my site:

totalBytes:   18804
wastedBytes:   7881   ("increasing the image compression factor…")

So Lighthouse wanted 10,923 bytes. The image has 65,536 pixels. 65536 ÷ 10923 = 6.0000.

One more, a 400×712 screenshot:

totalBytes:   55558
wastedBytes:   8091
target:       47467      →  284800 px ÷ 47467 = 6.0000

The compression target is one sixth of a byte per pixel, or 1.333 bits per pixel. Under that
line, no complaint. Over it, a complaint — unless the saving comes to less than 4 KiB, which
is the reporting floor and explains the files that are technically over and stay quiet
anyway.

That is a number you can build against. My encoder now computes w × h ÷ 6 for every
derivative and re-encodes only the ones that overshoot.

Treat it as a ceiling, never a target

The obvious move once you have a target is to encode everything to it. That would have
roughly doubled several of my files.

Most images were already far under. One 400px-wide screenshot was 21 KB against a 47 KB
ceiling, because it is a simple picture that compresses well. Encoding it to the budget
would have added 26 KB of nothing.

if (cap && fs.statSync(dst).size > cap)
  execFileSync('cwebp', ['-size', String(cap), '-m', '6', '-sharp_yuv', '-pass', '8', …]);

Only files above the line get touched. The rest keep whatever quality they landed on.

The second complaint is geometry, and it does not negotiate

The other sentence has its own arithmetic, and it is not about compression at all:

waste = bytes × (1 − displayedPixels ÷ intrinsicPixels)

I checked that against all eight flagged files on my home page. It reproduces every figure
Lighthouse reported to within 7 bytes.

That tells you exactly when it reaches zero: when the file has the same number of pixels as
the CSS box it lands in. A 254px slot wants a 254px-wide file. That is a 1× image, and on the
phone Lighthouse is emulating — deviceScaleFactor: 1.75 — a 254px file in a 254px slot is
visibly soft.

So the audit compares intrinsic pixels against CSS pixels while simulating a screen that has
1.75 device pixels per CSS pixel. Satisfying it completely means shipping images that look
worse on the device it is pretending to be.

What I actually did

Compression: hold everything under w × h ÷ 6, using cwebp's method 6 with -sharp_yuv,
which reaches the same fidelity in fewer bytes than the default method. Every quality value
was picked by measuring PSNR against what the old encoder produced, so nothing could come out
worse than what it replaced.

Icons are exempt. Their art is lettering and gradients, where WebP shows its seams first.
Holding one to the ceiling cost 2.8 to 3.8 dB and read as blotchy type at 3× magnification,
to save about 1.4 KB. I looked at them side by side before deciding. The same ceiling on a
photographic screenshot cost 0.15 dB and I could not tell the two apart at 250%.

Resolution: I stopped the candidate ladder at 320px for a 254px slot. That is 1.26×, above 1×
and below what the audit calls waste. Rendered at the size it actually appears, it is
indistinguishable from the 400px file it replaced. I compared those too, at the real display
size rather than at full resolution, where a difference exists that no visitor ever sees.

The result on the home page: image waste 345 KiB → 0, the insight passing with nothing
flagged, page total 520 KiB → 353 KiB. On a game page it went 482 KiB → 40 KiB, and the 40
that remain are the geometry complaint on two files I have decided to keep sharp.

Why bother reverse-engineering it

I could have twiddled the quality number until the warning went away. I have done that
before. What you get is a setting that satisfies today's audit and no idea which direction is
correct, so the next person to touch it — including you, in four months — starts over.

Knowing it is w × h ÷ 6 turns a warning into a build rule. The other formula told me
something more useful: one of these two complaints was a bug in my markup, and the other is a
disagreement about how sharp images should be. Only one of those was worth fixing.

Originally published at Lighthouse's image budget is w × h ÷ 6.

The code is on GitHub: The pipeline and the markup, ready to adapt