Adding Creatures to the Vivarium

The catalogue grows when creatures arrive. This document tells you how to bring one in.

What counts as a creature

A creature in the Vivarium is:

• A parametric formula producing a body when sampled densely.
• Computable in GLSL — a vertex shader is the entire kernel.
• Controlled by 3 to 9 parameters with meaningful, named axes (not just numbered knobs).
• Rendered as points, not meshes — typically 10,000 to 100,000 points blended additively.
• Capable of animation through a time uniform inside the formula, not as an interpolation between snapshots.

What does not count:

• A 3D model loaded from disk. The Vivarium is about formulas, not geometries.
• A noise field. The creature must be parametric — meaningful axes, not random variation.
• A creature that requires more than one HTML file. Each creature is self-contained.

The template

Copy any existing creature in creatures/ and rename it. The structure is:

1. <style> block — editorial styling, color palette specific to the creature.
2. Header — title, byline, volume number.
3. Side panel — parameter sliders and presets.
4. Marginalia — a few sentences placing the creature in the catalogue.
5. Readout — point count, render backend.
6. Action buttons — Play/Pause, Mutate, Reset.
7. <script type="module"> — Three.js setup, geometry, shaders, uniforms, controls.

Everything except the shaders is mechanical. The shaders are where you actually do work.

Writing the formula

1. Choose the family. Aquatic, terrestrial, aerial, subterranean, microbial, planar, hypothetical. A new family is fine — invent one.

2. Pick the parameters. Each parameter should change a real morphological property — a length, a count, a curvature, a phase. Three to nine. Fewer than three is impoverished; more than nine is unreadable.

3. Derive the position function. This is the hard part. Given a point index i ∈ [0, N) and the parameters, produce a position (x, y, z). The trick is usually to partition the indices into regions (body, limb, surface, particle) and write a separate sub-formula for each region.

4. Add time. Time is a uniform uTime. It should appear inside the formula, not outside it. If time only multiplies a rotation matrix, the creature is rotating — not breathing. Embed t where it can modulate frequency, amplitude, or phase.

5. Project to NDC. Map your world-space position to normalized device coordinates. Most creatures use orthographic projection. Apply aspect ratio correction.

6. Vary point size and color. Pass varyings to the fragment shader: depth along the body, stress under load, distance from rim, age of a particle. Use these in the fragment shader to vary color and alpha.

The presets

Each creature exposes 5 to 6 preset buttons. The convention:

• 4 to 5 buttons name real regions of the morphospace. These should correspond to actual creatures of the family (Moon, Lion's Mane, Box for jellyfish; Cheetah, Bear, Dachshund for quadrupeds; Albatross, Falcon, Swift for wings).
• 1 button is always Empty Quadrant. This is a deliberately implausible corner of the parameter space — physically possible but biologically absent, or just bizarre. The point is to make the unoccupied regions visible.

The color palette

Each creature has a primary accent color. Existing palettes:

• Fireeel: ember red #d94f3a / amber #f0a868
• Jellyfish: cyan #3ea4d9 / aqua #68d0f0
• Quadruped: umber #c89060 / warm sand #e6b884
• Wing: violet #b8a8f0 / pale lilac #d8cffa

Pick a new color for your creature. Match the editorial tone — muted, atmospheric, never saturated.

The marginalia

A short essay in the bottom-left corner of each creature, written in the same voice as the others:

• One italic sentence stating the geometric trick (e.g., "The bell is a superellipse of revolution; tentacles, catenaries modulated by a traveling wave.")
• One sentence placing the creature among its catalogue siblings (e.g., "Where the fireeel writhes, the jellyfish pulses.")
• One sentence on the physics or constraint (e.g., "The constraint is sharper than the fireeel's: water is heavy.")

Three sentences. No more.

Submitting

1. Fork the repo.
2. Add your creature at creatures/your-creature.html.
3. Add the creature to the catalogue in index.html.
4. Document the formula in docs/formulas.md using the existing template — annotated math, parameter list, "why this works" paragraph.
5. Bump the volume or issue number if you think your creature opens a new volume.
6. Open a pull request.

No aesthetic gatekeeping. The formula must produce something; that is the bar. Strange creatures are welcome. Failed creatures are welcome. Creatures whose Empty Quadrants are the more interesting parts are especially welcome.

On formulas already taken

The four creatures in this volume use specific mathematical structures: trigonometric writhe (fireeel), superellipsoid-plus-catenary (jellyfish), SLIP gait on a parametric spine (quadruped), planform-plus-vortex (wing). Don't feel obligated to use one of these. The most interesting contributions will introduce structures that aren't here yet — Fourier descriptors, harmonic surfaces, branching grammars, reaction-diffusion patterns, knot theory, anything that maps a small parameter vector to a body.

The catalogue is a collection of different mathematical worlds, each rendered through the same window.

Build a creature. Add it to the Vivarium.