Fossil Hunter

A fossil-preparation game for iPad, PC and Meta Quest 3S. Buy or collect fossil-bearing rock, work the matrix off with brushes, scrapers, air abrasion and acid, then display or sell the specimen. Later: expeditions to deposits by period, multi-specimen blocks where exposing one fossil can sacrifice another, and museum curation. Real techniques where possible; gameplay wins over realism.

Design references

• docs/preparation-survey.md: real preparation techniques, how each succeeds and fails, its damage modes and speed, rock/fossil compatibility, a material property sheet, and proposed simulation rules.

Web beta: rock + fossil + tools (web/)

A playable build for iPad, PC and Meta Quest (WebXR) from one URL. No build step: plain ES modules with three.js from a CDN.

cd web
./serve.py              # desktop: http://localhost:8000
./serve.py --https      # iPad / Quest on the LAN: https://<this-ip>:8443, accept the cert warning

WebXR needs HTTPS except on localhost, which is why --https makes a self-signed certificate. Add ?level=phacops&seed=12 to jump straight into a level.

Levels: the contrast ladder.

1. Pyrite in black shale: huge hardness contrast, clean release, gold on black.
2. Wheeler Elrathia: small hardness contrast, clean release.
3. Cincinnatian Isotelus: the matrix is harder than the shell, so abrasives cut the fossil first.
4. Moroccan Phacops: the same hardness and mineral; patchy release.
5. Spiny odontopleurid: spines snap once the rock supporting them is gone.
6. Grey on grey: welded matrix and low colour contrast.

Tools.

• Hammer and chisel (wedge, bolster or point heads). Press to set the chisel, drag to lean it, hold to wind up, and release to strike. Real brittle fracture (web/src/fracture.js): a crack takes the cheapest path the blow can pay for. Bedding planes, joints, earlier damage and a clean fossil parting are all weak. Edge flakes come away, blows into the middle of a face crush, and a side blow along a weak shale bedding plane splits the layer off. Where the crack meets the fossil it follows the shell if it parts cleanly and cuts through where it's welded. Pieces fall as debris.
• Large and fine air scribes: vector aim with a through-rock line of action. A low angle pops thin matrix; a steep blow marks the shell.
• Air abrader with bicarbonate, dolomite or Al₂O₃: cuts only what is softer than the powder.

Discovery and planning.

• Field guide: candidate trilobites from the deposit, one of them real.
• Mind model: your guess at the fossil's shape. Fit it to a species, then pull or push its outline. The scribes and abrader won't cut inside it.
• Notebook: steel-needle, acid and loupe tests, your identification, and a prep plan derived from it.

Scoring. Fossil integrity % (shown live) times exposure gives the value. Materials are told apart by lustre as well as colour. There is a movable raking light and a wet-surface spray.

Design notes: docs/design-v2.md and docs/fracture-research.md. Rules and numbers follow docs/preparation-survey.md §8.

Controls.

• iPad:
  • Left thumb on the circle sets air pressure (→) and flow or stroke rate (↑). It stays where you release it.
  • One finger on the rock uses the tool. Two fingers turn, pinch zooms, twist rolls.
  • Apple Pencil pressure throttles the air.
• PC: left mouse uses the tool, right-drag turns, wheel zooms. Keys 1–4 select tools, Q/W/E select abrasives, arrows move the pad.
• Quest:
  • Left grip holds and turns the sample; left stick magnifies.
  • Right trigger (analog) is pressure or hammer force; right grip (analog) is flow or stroke rate.
  • A cycles tools, B cycles abrasives.
  • Haptics differ on rock and on shell.
  • Left X toggles the wrist panel; left Y finishes.

Code (web/src/).

• trilobite.js: seeded SDF, ported from the prototype, plus spine part IDs.
• specimen.js: block, strata and parting map; the spine-support lists and grading targets.
• volume.js: density fields and ray marching.
• mesher.js: chunked surface nets with gradient normals.
• tools.js: tool physics and grading.
• view.js: three.js scene.
• input.js: touch, mouse and pad input.
• xr.js: Quest controls.
• audio.js: synthesised tool sounds.
• game.js and ui.js: game loop and interface.

Tests (web/test/).

• node test/sim.test.js: builds and meshes every level, and checks the mesh is closed and outward-facing. Add --reveal --ply DIR to export meshes for Blender.
• node test/selectivity.js: one second of each tool on rock and on shell, per level. This is the contrast ladder in numbers.
• node test/pacing.js LEVEL TOOL [MEDIA]: a methodical bot. It reports exposure, damage and value against simulated play time.
• node test/balance.js: a careless bot.
• node test/fracture.test.js LEVEL: chisel scenarios. A centre blow crushes, an edge blow flakes, and a side blow along the bedding splits.
• node test/smoke.mjs, node test/xr-smoke.mjs and node test/career.mjs: browser checks with the server (career: storeroom, pack up, resume)
• node test/loose.test.js: loose rock falls away; sliced jobs give identical results
• node test/frames.mjs: frame times through a big chisel split on the GPU (performance probe)
• node test/bake.test.js: a prepared specimen baked to a light display mesh
• node test/museum.mjs: finish two specimens, display them, walk the museum (screenshots in ../build/museum)
• node test/economy.test.js: what displays and the gift shop bring in per day running. The XR test emulates a Quest 3 with Meta's IWER and drives the controllers.
• Setup: npm i, then npx playwright install chromium.

This is the beginning of the README. Read the rest at the original. Read the full README ↗