🌾 Needle in a Haystack
A small 3D game about the world's least efficient search problem. You are a
farmhand in a barn full of hay. A needle is buried in one of the piles. Walk
over, dig it out one shovel-load at a time, sift it on the conveyor, and keep going
until the needle turns up — then move to a bigger barn.
Built with three.js (vendored, MIT). No build step, no
network calls, no dependencies to install.
▶ Play it: https://needleinahaystack.politecarrot.com
How to play
| Desktop | Touch |
|---|
| Move | W A S D / arrow keys | left stick |
| Dig / sift | hold Space or E | hold the action button |
| Look around | drag the scene | drag the scene |
| Pause | Esc | ⏸ button |
- Walk to a hay pile and hold to dig until your shovel is full.
- Carry the load to the conveyor sifter in the corner and tip it into the
hopper. The belt carries it to the crate, and sifted hay pays coins.
- The needle is buried at a hidden depth in one pile. Dig that pile down far
enough and you will see it lying in what is left, glinting — walk over
and grab it. Digging the wrong pile is never wasted; it still pays.
- Spend coins on shovels and gear between barns. Bigger shovels unlock as you
clear barns, so the farm opens up gradually rather than all at once.
What's in it
- A barn you walk around — procedural low-poly barn interior and exterior,
lanterns, dust in the light shafts, a farmhand with a hand-animated walk,
dig and dump cycle, and a conveyor sifter running in the corner.
- A field you can walk all the way round. The barn stands in a fenced
field and the fence is the edge of the world — post-and-rail on all four
sides with a shut five-bar gate out front where the track carries on. Two
cows, two sheep, a pig and three chickens are spread around it, grazing and
trotting out of your way when you get close. Each keeps to its own strip of
the field, so none of them ever has to work out how to walk round a building.
- Something behind the barn. Every barn has a crate round the back where
nobody digs. Most of them hold coins. Three hold something that is not for
sale at any price — the Scarecrow Head behind barn 4, the Lantern
Spade behind barn 8, and the Diamond Excavator behind barn 12. You have
to go and look.
- A walk-in cutscene for every barn: the doors swing open, the camera
follows you inside, and the barn number lands on screen. Skippable.
- Spatial search, not tapping. Each barn has labelled piles (A, B, C…) and
exactly one holds the needle, at its own depth and its own spot inside the
pile. The pile card shows how far down you have dug the pile you're standing
at. The needle is a real object: uncover it and it lies there in the hay
until you pick it up — your hired hands can dig it out for you, but only you
can take it.
- Needle Sense — a detector that reads how far off the nearest metal is
from where you stand, and never names the pile. One reading narrows it to a
ring around you; walk somewhere else, take another, and the rings cross.
Levels buy precision — warm/hot/burning, then metres to the nearest five,
then metres — not the answer.
- Odds and ends in the hay. Horseshoes, a rusty key, a tin can, an old
boot, a pocket watch, a wedding ring — buried at their own depths, worth
coins, and dug out the same way the needle is. The metal ones are what the
detector actually hears, so a promising reading can turn out to be a
horseshoe; digging the scrap out is how you clear the noise.
- 8 shovels and 4 pieces of gear: work boots, sifting screen, the detector,
and farmhands — hired hands who actually walk the barn, each picking a pile,
digging a load, carrying it to the conveyor and heading back for more.
- My Farmer — a wardrobe you spend barn coins in, with a turntable preview:
56 outfits shelved under Colours, Flags (26 of them, named for the countries
they belong to), Camo (woodland through digital, tiger stripe and one very
loud pink) and Other (check, hi-vis, cow print, pinstripe, disco); 21 hats
(caps, cowboy, sombrero, tricorn, wizard, hard hat, a bunny head, a pumpkin
head, a traffic cone, a crown, and the Polite Carrot mascot worn as a full
head); 15 facial expressions from Big Grin through Eyepatch and Monocle to a
Full Beard; and 15 shovel skins (gold, trident, frying pan, umbrella, bone
spade, candy cane, neon, diamond). The preview turns by itself and can be
dragged round by hand.
Three pieces are not for sale at any price — Rosette Claret, the Tin Can Hat
and the Heirloom Spade are earned by retiring and by filling the Barn Shelf.
Cosmetic only — every dig stat still comes from the shop. Patterns are drawn procedurally at
runtime, so there are still no image assets in the repo.
Ads
There is no ad network in the repository. js/ads.js owns when an ad is
allowed and hands the showing to a provider you plug in with
NIAH.ads.use({ interstitial, rewarded }); with nothing plugged in every call
resolves immediately and the game plays exactly as it does without it. A
provider that fails, or one that never comes back, is treated as "no ad" — an
interstitial can never strand a player between barns, and a reward is only ever
paid when the provider says it was watched to the end.
One interstitial, on the way out of the win card — not on the needle. The
finale and the win card are the payoff; an ad on top of them lands badly. By
the time "On to the next barn" is tapped the player has had both, and the ad
covers the walk into the next one. Three conditions all have to pass:
| |
|---|
firstBarn: 4 | nothing at all until barn 4 is cleared |
minBarns: 3 | barns cleared since the last one |
minGapMs: 180000 | and three minutes since the last one |
sessionGraceMs: 90000 | and ninety seconds into this session |
firstBarn only ever protects a brand-new player; someone returning at barn 30
has long passed it and would otherwise catch an ad on their first barn back,
which is the worst possible moment. The session grace covers that. A session is
one page load.
A barn takes about a minute, so a time gate on its own would land one every
couple of levels — the barn counter is what stops that on a fast run. The
counters ride along in the save, so closing the tab is not a way to dodge the
gap. The Daily Barn is excluded outright: it is timed and competitive.
Three rewarded doubles, each beside a button that already does the job for
free — the crew's night's work on the menu, the needle bounty on the win card,
and the crate behind the barn. The three exclusive finds are never doubled and
never behind an ad; the whole point of them is that they cannot be had any
other way.
Append ?adstub=1 to the URL to install a fake provider and see the placements
work before choosing an SDK. It is only ever installed from that parameter.
If you also set frequency capping in the ad network's dashboard you will be
capping in two places and get noticeably fewer ads than either implies. Keep
the cadence here, where it can see barns as well as the clock.
Privacy & Data
Two choices, both off until the player turns them on, in the same shape as the
other Polite Carrot titles: Send usage data and Personalised ads.
The usage-data question is asked once, on a Before you start card, before
anything is collected. Both live afterwards in Privacy & Data, reachable
from the foot of the main menu and from the pause card. The choice is saved,
handed to NIAH.ads.setConsent() — which passes it to the network adapter's
consent() whenever it changes, including to an adapter plugged in later — and
published as window.__consentState = { analytics, ads }, which is what the
label's other games read.
This is the game's own surface for the choice. It is not by itself the
consent signalling an ad network requires: whichever SDK you use still has to
be given the decision through its own privacy API, and in the UK and EU a
certified CMP may be required on top. The adapter is where those meet.
Balance
Each barn has more piles and bigger piles than the last (×1.5 hay), and pays
×1.85 per hay. Shovels are gated behind barn levels as well as price, so
clearing barns — not grinding one — is what opens the next tier.
That curve outruns its own sinks: by barn 10 a single barn pays about 6.4M
coins while everything buyable in the game costs about 9.8M put together, and
barn 13 pays 137M. Retiring is the sink. It puts the whole shop back in
front of you, and rosettes pay out in the two things a fresh run is actually
short of — dig rate and early shovels — rather than in coins alone, which the
barn gates would have swallowed.
Running it
Open index.html in a browser, or serve the folder:
npx serve . # or: python3 -m http.server
Progress is saved in localStorage under niah.save.v2; Erase save on the
main menu clears it. Older saves are migrated forward on load, so an existing
game keeps its coins, barn and wardrobe.
The service worker only registers over http(s), so opening index.html
straight off disk still works. When you change any file in the shell, bump
CACHE in sw.js so returning players fetch it.
Hosting on GitHub Pages
The site is the repository root on main — static files, relative paths, so it
serves from a project subpath. .nojekyll stops Pages running it through Jekyll.
Settings → Pages → Build and deployment → Source: Deploy from a branch, then
pick main and / (root).
CNAME points the site at needleinahaystack.politecarrot.com; GitHub reads
it on every deploy, so it has to stay at the repository root. On a custom
domain the game is served from /, which suits the relative paths and gives
the service worker the whole origin as its scope.
Layout
| Path | What it does |
|---|
index.html | Canvas plus every UI overlay (menu, HUD, shop, cutscene, modals) |
css/style.css | Barn-themed UI, responsive down to small phones |
js/world.js | Renderer, barn geometry, hay piles, sifter, particles |
js/player.js | Farmhand mesh, walk/dig animation, movement, camera rig |
js/game.js | State, economy, barn flow, digging, input, save/load |
js/ui.js | Screens, HUD, shop and wardrobe rendering |
js/cosmetics.js | Outfits, hats, faces, shovel skins and their procedural textures |
js/wardrobe.js | The My Farmer preview scene and its auto-framing |
js/helpers.js | Hired farmhands: their round trip, steering and animation |
js/animals.js | The yard livestock: how they are built and how they wander |
js/audio.js | WebAudio sound effects |
js/haptics.js | Vibration patterns, and the feature test that hides them on iOS |
js/ads.js | When an ad is allowed, and the provider seam — no network in it |
sw.js | Service worker: precaches the shell so the game runs offline |
manifest.webmanifest | Web app manifest — name, colours, icons, display mode |
assets/ | Polite Carrot logo and wordmark, plus the app icon in SVG and PNG |
CNAME | The custom domain GitHub Pages serves the game from |
vendor/three.min.js | three.js r160 (MIT, see vendor/three.LICENSE) |
The original 2D tap version lives in this repo's git history, before the 3D rework.
