Model or dataset
xr843/insect-world avatar
xr843/insect-world

insect-world generates every insect in code, and tells you its own text is unverified

Interactive 3D insect field guide: 63 species across 14 orders, every body procedurally generated in the browser with TypeScript + Three.js — no model or texture files in the repo. Eight species step through a full life cycle; the hoverers beat their wings.

809 stars76 forksTypeScriptMIT

At a glance

What is it?
A 3D field guide for 63 species across 14 orders, where each body is procedural TypeScript geometry rather than a scanned asset, and where the life-cycle wing expansion is the only continuous morph. The same page warns that all of its species text was written by a model and checked by nobody, and the build downloads photographs before it type-checks.
Who is it for?
Treat insect-world as a rendering project first and a field guide second. The geometry work is the reason to read the source: one builder module, one file per species, one file per life-cycle stage, and a stated triangle budget of thirteen to thirty-six thousand per body, with the species tables showing which order dominates and why readers objected to it.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 29 days ago.
What is it written in?
Mainly TypeScript, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • xr843/insect-world809 ★ · +58
Star history
Repository2026-09-212026-11-15
xr843/insect-world751809

58 Stars in the last 55 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The page says its own species text was never checked

A warning sits above the fold and it is the first thing to read:

> About the descriptive text: the overviews, key data, life history and trivia for all 63 insects were written by AI and have not been checked line by line against entomological literature or by a professional. Read it as something pleasant that happens to teach you a body plan, not as a source you can cite. Open an issue when you find a mistake.

That changes what the site is. The geometry can be checked against morphology, because insect bodies are regular, and a wrong leg count or a missing wing pair is visible on screen. A wrong life-cycle fact or a wrong date is not, and it would be indistinguishable from a correct one. The species count is stated precisely, 63 across 14 orders, with the breakdown given: Coleoptera 28, Diptera 5, Lepidoptera 5, Hymenoptera 5, Hemiptera 4, Orthoptera 4, four orders with 2 each for dragonflies, mantises, lacewings and cockroaches, and four orders with one species each. The 28 beetles are close to half the guide, which readers complained about, and the response was a later round that added the housefly, the pale mosquito and the German cockroach. The README is written in Simplified Chinese, with an English version in `README.en.md`.

The manifest says 0.1.0, the release says v0.2.0

The package manifest declares `"version": "0.1.0"` and `"private": true`, while the only published release is v0.2.0, titled with a four-character Chinese phrase about the insects starting to move. Nobody bumped the manifest. The consequence is that there is no single place to ask what version is running: the tag, the manifest and the site itself can disagree, and a checkout of master reports 0.1.0 while carrying whatever the v0.2.0 work added. The repository description disagrees with the page on a second point. It says eight species step through a full life cycle, while the page counts eighteen species and 48 stage models, and the two lifecycle tables between them name eighteen: a rhinoceros beetle whose pupa already has the horn bud, a monarch, an oak silkworm moth whose cocoon is cut open lengthwise to show the brown pupa inside, a honey bee that never leaves the hexagonal comb, a firefly whose egg, larva and pupa all glow, a dung beetle whose eggs and larvae sit in brood balls, a seven-spotted ladybird whose naked pupa still carries the shed larval skin at its rear, an ant whose silk cocoon has a window cut in the side wall, a longhorn beetle whose pupa coils its long antennae around the body, a stag beetle whose male pupa already has its mandibles formed, a tiger beetle larva that plugs its burrow with a metallic head shield, and a swallowtail whose girdled pupa hangs by a silk band. The incomplete-metamorphosis table adds six more, a cicada, a damselfly, a mantis, a migratory locust, the German cockroach and a stick insect.

The build downloads photographs before it type-checks

The claim on the repository page is that every insect is generated in real time by code and that no model file exists in the repository. That is true of the geometry and not of the images, because the script order in the manifest pulls files in from outside before anything is compiled:

json
"prebuild": "node scripts/download-photos.mjs",
"build": "tsc --noEmit && vite build",
"postbuild": "node scripts/make-species-pages.mjs",

There is a whole photo pipeline around it: `photos` runs `node scripts/fetch-photos.mjs`, `photos:check` runs the same script with `--check`, `photos:notice` and `photos:notice:check` do the same for `scripts/photo-notice-cli.mjs`, and `NOTICE-photos.md` sits at the repository root as the attribution file. So the images are downloaded at build time and their licences are tracked separately, which is a different claim from zero assets. The size budget for the code side is documented in the same spirit. One species runs 13,000 to 36,000 triangles, from 13,308 for the pale mosquito to 35,732 for the oak silkworm moth, built in 30 to 90 milliseconds, except the first one at 230 to 730 milliseconds because the procedural surface textures are shared across the library and generated once. The first screen ships about 424 KB of JavaScript gzipped, a vendor chunk of 340 KB dominated by three and a main chunk of 84 KB, with the 103 KB desktop post-processing pipeline as a lazy chunk that phones never download.

deploy runs the tests, the build, and wrangler with a dirty tree flag

One script does the release, and it is worth reading in full because each part is a gate:

code
"deploy": "npm test && npm run build && npx wrangler pages deploy dist --project-name=insect-world --branch=master --commit-dirty=true",
"postdeploy": "node scripts/indexnow-submit.mjs && node scripts/inbox.mjs summary",

Tests run before the build, the build type-checks with `tsc --noEmit` before Vite runs, and the upload targets the master branch as the production branch with `--commit-dirty=true`, which allows the deployment even when the working tree has uncommitted changes. After the upload, a script submits URLs to search engines and another prints a summary of the feedback inbox. Feedback itself is stored in a Cloudflare D1 database, and the schema and seed are applied by running `wrangler d1 execute insect-world --remote --file=db/schema.sql` against the remote database. The test command is `vitest run`, and the page claims more than four thousand tests in it. The browser regression suite is separate, `test:browser` runs `node scripts/audit-smoke.mjs` against the built output for mobile layout, species switching and storage failure, and it needs a browser installed first with `npx playwright install chromium`. The README also names three helper scripts that are deliberately not in the dependency list: `bash scripts/make-og.sh` for the share card, which needs ImageMagick, `node scripts/shots.mjs` for retaking the README screenshots, and `node scripts/perf-firstframe.mjs` for first-frame timing.

The root path is a Function that 302s on Accept-Language

Visitors to `/` are redirected to `/en/` unless they ask for Chinese, and that decision is made by a Pages Function at `functions/index.ts` in the repository root rather than in the build output. The function looks at `Accept-Language`, leaves crawlers alone, and honours an existing language choice cookie. Its response carries `Vary: Accept-Language, Cookie, User-Agent` and `Cache-Control: private, no-store`, so no shared cache can hand a Chinese page to an English reader. The reason this works without a special flag is documented by quoting the tool rather than by assertion: the README points at wrangler 4.x, where `deploy2()` sets `functionsDirectory = customFunctionsDirectory || path.join(process.cwd(), "functions")`, so the functions directory is taken from the working directory at the moment the command runs and not from the directory argument, which here is `dist`. Since `npm run deploy` runs in the repository root, the function is discovered and bundled automatically. The same chain can be checked locally with `npx wrangler pages dev dist` and a `curl` of the root path with different `Accept-Language` and `Cookie` headers. Static assets are handled separately: `public/_headers` caches hashed filenames as immutable for a year and revalidates HTML on every request, so a new release shows up immediately.

Wing beats are compressed, and the real frequencies stay in the table

Eight species hover in place and beat their wings: dragonfly, damselfly, honey bee, bumblebee, hoverfly, lacewing, hawkmoth and crane fly. In dragonflies the fore and hind wings beat in antiphase, which is the reason they can hover and the quickest way to recognise one in motion. The page is explicit about what it does to the numbers. A honey bee really beats at 230 Hz and a hoverfly at 200 Hz, while a 60 frames per second screen has a Nyquist limit of 30 Hz, so driving the animation at the true rate does not look fast, it looks like aliasing, with the wings seeming to beat slowly backwards. The rates are therefore compressed logarithmically to 4 to 12 Hz, which keeps the relative order between species, and the real values stay in the data table in the code with the compression function written next to them. Standing insects also make small posture adjustments of about 1.7 degrees, with the six legs phase-offset by where they attach. There is no walking gait, and the reason is given rather than hidden: the display is a turntable with the insect centred, so the legs step while the body does not move, which reads as a treadmill. Hovering has no such problem, because staying in place is what hovering actually is.

Only the wing expansion is a continuous morph

The lifecycle card swaps the specimen for an egg, then a larva, then a pupa, in steps, and there is a stated reason for the discontinuity. Turning a caterpillar into a butterfly is not a continuous morphing operation: the text names tissue breakdown and adult disc development as the biology, and says a smooth morph would look right and be wrong. One transition is continuous, the eclosion at the top of the page where a monarch's crumpled wing bundle opens to full size and lifts from hanging to rest, because that one is genuinely continuous: the wing starts as a small mass of soft tissue, is pushed open by haemolymph, and then hardens. The curve is given as `1-(1-u)³`, fast first and slow later, on the grounds that haemolymph pressure is highest at the start. The animation is not hand-tuned frame by frame: `scripts/make-emerge-gif.mjs` opens the lifecycle on the live site, steps to the pupa and then one step further, and captures the frames the browser compositor produced. The four-panel lifecycle comparison image is generated the same way, by `scripts/make-lifecycle-strip.mjs`, from the same code as the site, which is why the size difference between a cluster of eggs and a long grub is a property of the models rather than of the layout.

The first version copied a reference site, and the public release replaced it

The page is candid about where its design came from. The reference site it compares itself with serves each organ as a roughly 3.2 MB GLB asset such as `/models/heart.glb`, bought or scanned, and insects have no equivalent assets to buy, which is the reason for generating geometry instead. What was taken from that site is the information architecture, and the page says it does not hide that: a three-column workbench of list, stage and detail panel, coloured annotation points on the model, an expanding card at the bottom, five entries in the top bar, and the idea of the cutaway and the comparison view. The implementation is all its own, and the rule it set for itself is that every control has a real response, with a table of controls and what each one does. The colours are the part with a history. Version one measured and copied the reference site, down to the cream paper background, the coral accent, Cormorant Garamond, and the width and corner radius of the explanation popup. When the repository was made public, every borrowed value was replaced with two themes of its own, a dark museum night built on an exhibition black and a brass accent, and a light specimen bench built on a pale archive backing with a bronze accent and four label inks for brick red, indigo, moss green and ochre, with the typography changed to Playfair Display and Noto Serif SC.

Editorial conclusion

Treat insect-world as a rendering project first and a field guide second. The geometry work is the reason to read the source: one builder module, one file per species, one file per life-cycle stage, and a stated triangle budget of thirteen to thirty-six thousand per body, with the species tables showing which order dominates and why readers objected to it. The text is the weak half, and the project says so itself, so a quoted life history or a datum copied out of it should be checked against literature before anyone relies on it. Three things to check first: the version, since the manifest still says 0.1.0 while the only release tag is v0.2.0; the asset story, since the claim of no model files covers three-dimensional geometry only and the build downloads photographs before it runs; and the wing-beat representation, since the displayed rates are a logarithmic compression of real values that live in the code rather than on screen. Anyone wanting a citable entomology reference should look elsewhere. The repository README is written in Simplified Chinese with an English version beside it, and the last commit is dated October 1, 2026.

Frequently asked questions

How many insects does insect-world cover?

63 species across 14 orders. Coleoptera has 28, Diptera, Lepidoptera and Hymenoptera 5 each, Hemiptera and Orthoptera 4 each, four orders have 2 each, and four orders have a single species.

Are the insect descriptions in insect-world verified?

The README carries a warning that the overviews, key data, life history and trivia for all 63 species were written by AI and have not been checked line by line against entomological literature or by a professional, and asks readers to treat the site as something pleasant rather than a source they can cite.

Does insect-world use 3D model files?

Not for the insects, since every species body is generated by TypeScript in the browser. Photographs are a separate matter: the build runs `node scripts/download-photos.mjs` before type-checking, and the photo fetch and photo notice scripts each have a `--check` mode with `NOTICE-photos.md` at the root.

How much JavaScript does insect-world ship?

About 424 KB gzipped for the first screen, as a vendor chunk of 340 KB dominated by three plus a main chunk of 84 KB. The desktop post-processing pipeline is a further 103 KB lazy chunk that phones do not download, and species code is split so a species is fetched when it is selected.

How does insect-world show insects beating their wings?

Real rates would alias on a 60 frames per second screen, so they are logarithmically compressed to 4 to 12 Hz, which preserves the relative order between species. The real frequencies, including 230 Hz for a honey bee and 200 Hz for a hoverfly, stay in the data table in the code next to the compression function.

Official sources

  1. License: MIT
  2. Project website
  3. README
  4. Releases
  5. xr843/insect-world on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/xr843-insect-world.svg)](https://hysenlabs.com/projects/xr843-insect-world)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/xr843-insect-world.svg)](https://hysenlabs.com/projects/xr843-insect-world)

Was this useful?