# The Moon Is a Pearl — `moon-pearl@1.0.0`

A moon over a midnight sea; the camera withdraws to show the sea sits inside a giant oyster and the moon is its pearl. Iridescent nacre, ray-traced reflections. Loops.

A full moon hangs over a dark sea, with its rippling reflection below. The camera withdraws and light unfurls across mother-of-pearl: the sea is held inside a monumental oyster, hinged and opened to about 76 degrees, and the moon is the pearl resting in it, reflected in the black water. The layered shell halves, the iridescent nacre with its growth rings, the contact shadows and the ray-traced pearl reflection are all computed in the shader, and every animated part completes whole cycles, so the 12 seconds loop exactly. The film has no settings.

- Kind: background; status: published; digest sha256:33f4ebf6db0f59d07250b25e916ba967e5671643905f1e909c30278d5efe0864
- Role: Shader film (three.js): Surreal nacre sculpture, a finished 12-second portrait film with no settings.
- Implementation: three; entry `src/moon-pearl.js`
- Files: https://aipixelwizard.com/registry/moon-pearl/1.0.0/<path> (`LICENSE`, `asset.json`, `demo.js`, `index.html`, `src/moon-pearl.js`)
- Manifest JSON: https://aipixelwizard.com/api/v1/visuals/moon-pearl/versions/1.0.0
- Runnable demo: https://aipixelwizard.com/registry/moon-pearl/1.0.0/index.html (open over http; it imports sibling packages by relative path)
- Dependencies (exact): `three@0.185.1` (source) — Renderer and a full-screen shader material.; `apw-runtime@1.0.0` (demo) — Demo harness.

## Exports
- `createMoonPearl() => { scene, camera, setSize(width, height), update(time), dispose() }` — The film as one full-screen shader; render its scene with its camera straight to the canvas.

## Composition
- Inputs: The time in seconds, 0 to 12. The film has no other settings.
- Outputs: An opaque full-frame picture, already in display colours: render it straight to the canvas.
- Coordinates: Composed for a 4:5 portrait frame and measured by the frame height: in a wider frame the picture stays centred at full height and its background fills the sides; in a narrower one, such as 9:16, the sides are cropped.
- Lighting: Moonlit: a bright pearl reflected in rippling water, iridescent nacre and contact shadows.
- Timing: Moon and sea first; the camera withdraws and light unfurls across the shell to show the oyster; the view then returns to the moon.
- Works with: —
- The rear shell half is genuinely opened about 76 degrees on a shared hinge.
- It is one of the heavier films: about 30 ms a frame on an integrated GPU.
- Every pixel is a function of the time alone, so frames can be rendered in any order.

## Output and loop
- 1080×1350, 30 fps, 12 s, procedural
- Seamless loop: yes — Every part of the film is a function of the time modulo its length, and every motion completes whole cycles, so the last frame meets the first.
- Verified 2026-10-10 in Chrome 154.0.8037.97 headless on Linux 7.0.0-38-generic (x64), Node 22.14.0 (WebGL 2 via SwiftShader (software)); deterministic: yes; loop check: Frame 0 vs end state (progress 1): mean |Δ| 0.0000, max |Δ| 0 of 255.

## Use it
New project: Create a WebGLRenderer on a canvas (no antialiasing), call createMoonPearl() once and film.setSize(width, height); then for each frame call film.update(timeInSeconds) and renderer.render(film.scene, film.camera).

Existing project: Copy src/moon-pearl.js, which needs only three. Render film.scene with film.camera into your own canvas or render target; the output is opaque and already in display colours, so use no tone mapping or colour conversion.

Reuse ideas:
- Reveal clip: the pull-back from moon to oyster is a ready-made "it was something else" moment.
- Seamless loop: it returns to the moon at the end, so it repeats for any length.
- Calm night background: hold the first seconds as a still moon over the sea.

## Limitations
- The film is finished: it has no settings. To change colours or timing, edit the shader.
- It is composed for a 4:5 portrait frame.
- Its length is fixed at 12 seconds; repeat the loop to fill a longer clip.

## License
MIT. Copyright (c) 2026 AI Pixel Wizard. Released under the MIT License. See LICENSE in this folder.

Provenance: From the owner's collection Twenty Impossible Worlds: the original GLSL ES 3.00 shader of the film “The Moon Is a Pearl”, created with ChatGPT / Codex and used as published, wrapped for AI Pixel Wizard as a three.js full-screen shader in October 2026. The collection's synthesised soundtrack is not part of this ingredient.