{
  "schemaVersion": 1,
  "id": "cube-wave",
  "version": "1.0.0",
  "status": "published",
  "kind": "object",
  "title": "Cube Wave",
  "summary": "A field of glossy cubes rising and sinking in rings, crossing diagonals or a spiral, coloured by height. Loops perfectly.",
  "description": "A field of cubes that rise and sink in waves. Each cube's height is a function of its position — rings spreading from the middle, crossing diagonals, a spiral arm or travelling rows — and its size and colour follow its height, so the field looks like a pulsing landscape of glossy blocks. Choose the number of cubes, the pattern (ripple, cross, spiral or rows), the colours (aurora, sunset, candy or mono), how tall the waves are, how many wave cycles pass per loop, the backdrop colour and whether the camera sways.",
  "role": "Object (3D, three.js): the classic wave-field loop, glossy and colourful, for tech, music and abstract content.",
  "collections": [
    "satisfying",
    "hypnotic-loops",
    "backgrounds"
  ],
  "tags": [
    "cube wave",
    "grid",
    "waves",
    "ripple",
    "cubes",
    "height field",
    "pulse",
    "abstract",
    "studio",
    "loop",
    "3d"
  ],
  "synonyms": [
    "wave grid",
    "cube grid",
    "ripple field",
    "voxel wave",
    "3d bar wave",
    "pulsing cubes"
  ],
  "useCases": [
    "A tech or product launch backdrop",
    "A music or club visual",
    "A hypnotic ambient loop"
  ],
  "featured": null,
  "publishedAt": "2026-10-05",
  "implementation": {
    "target": "three",
    "runtime": "browser",
    "language": "javascript",
    "module": "esm",
    "entry": "src/cube-wave.js",
    "exports": [
      {
        "name": "createCubeWave",
        "signature": "createCubeWave({ grid?, pattern?, palette?, height?, speed? }) => { group, setProgress(progress), dispose() }",
        "description": "The field of instanced cubes, about 14 across, resting on y = 0; needs an environment map."
      },
      {
        "name": "PALETTES",
        "signature": "PALETTES: { aurora, sunset, candy, mono }",
        "description": "Colour ramps from the lowest to the highest cube."
      }
    ],
    "reusable": [
      "src/cube-wave.js"
    ],
    "demo": "demo.js",
    "harness": "index.html"
  },
  "dependencies": [
    {
      "id": "three",
      "version": "0.185.1",
      "reason": "Renderer, geometry and shader materials."
    },
    {
      "id": "chrome-material",
      "version": "1.1.0",
      "scope": "demo",
      "reason": "Studio environment light, backdrop and contact shadow."
    },
    {
      "id": "apw-runtime",
      "version": "1.0.0",
      "scope": "demo",
      "reason": "Demo harness."
    }
  ],
  "params": [
    {
      "key": "grid",
      "label": "Cubes per side",
      "type": "integer",
      "min": 9,
      "max": 41,
      "step": 2,
      "default": 25
    },
    {
      "key": "pattern",
      "label": "Pattern",
      "type": "select",
      "default": "ripple",
      "options": [
        {
          "value": "ripple",
          "label": "Ripple"
        },
        {
          "value": "cross",
          "label": "Cross"
        },
        {
          "value": "spiral",
          "label": "Spiral"
        },
        {
          "value": "rows",
          "label": "Rows"
        }
      ]
    },
    {
      "key": "palette",
      "label": "Colours",
      "type": "select",
      "default": "aurora",
      "options": [
        {
          "value": "aurora",
          "label": "Aurora"
        },
        {
          "value": "sunset",
          "label": "Sunset"
        },
        {
          "value": "candy",
          "label": "Candy"
        },
        {
          "value": "mono",
          "label": "Mono"
        }
      ]
    },
    {
      "key": "height",
      "label": "Wave height",
      "type": "number",
      "min": 0.4,
      "max": 2,
      "step": 0.1,
      "default": 1
    },
    {
      "key": "speed",
      "label": "Waves per loop",
      "type": "integer",
      "min": 1,
      "max": 4,
      "step": 1,
      "default": 2
    },
    {
      "key": "background",
      "label": "Backdrop",
      "type": "color",
      "default": "#10141f"
    },
    {
      "key": "orbit",
      "label": "Camera sway",
      "type": "boolean",
      "default": true
    }
  ],
  "presets": [
    {
      "id": "default",
      "label": "Aurora ripple",
      "params": {}
    },
    {
      "id": "sunset",
      "label": "Sunset spiral",
      "params": {
        "pattern": "spiral",
        "palette": "sunset",
        "background": "#1a1020"
      }
    },
    {
      "id": "candy",
      "label": "Candy cross, fine",
      "params": {
        "pattern": "cross",
        "palette": "candy",
        "grid": 37,
        "background": "#1a1830"
      }
    },
    {
      "id": "mono",
      "label": "Mono rows, tall",
      "params": {
        "pattern": "rows",
        "palette": "mono",
        "height": 1.7,
        "background": "#0e1016"
      }
    }
  ],
  "output": {
    "width": 1080,
    "height": 1080,
    "fps": 30,
    "durationSeconds": 12,
    "posterSeconds": 3,
    "alpha": false,
    "motion": "procedural",
    "loop": {
      "seamless": true,
      "cycleSeconds": 12,
      "method": "Each wave advances a whole number of cycles per loop and the camera sway is a sine of the loop, so the last frame meets the first."
    },
    "seed": null
  },
  "composition": {
    "inputs": "Time within the loop; the cubes, pattern, colours, height, waves per loop, backdrop and camera sway.",
    "outputs": "A full frame rendered in 3D with a studio environment.",
    "coordinates": "The field is centred on the origin on y = 0, about 14 across; cubes grow from y = 0 up to about 3.7 tall.",
    "lighting": "A warm key light with a shadow map, a shadow-catching floor and the studio environment.",
    "timing": "setProgress(progress) sets every cube's height, size and colour; frames render in any order.",
    "compatibleWith": [
      "chrome-material",
      "orbit-camera",
      "kinetic-title",
      "number-reveal"
    ],
    "notes": [
      "One instanced mesh with instance colours from a four-stop ramp."
    ]
  },
  "reuse": [
    "Tech launch: Aurora ripple.",
    "Warm: Sunset spiral.",
    "Playful: Candy cross, fine."
  ],
  "integration": {
    "newProject": "Create a WebGLRenderer with a studio environment and a shadow-casting light, add createCubeWave().group and call field.setProgress(progress) each frame.",
    "existingProject": "Copy src/cube-wave.js; add the group to your scene with an environment map."
  },
  "performance": {
    "notes": "One instanced draw call of up to 1 681 cubes with a shadow map: about a millisecond a frame on an integrated Intel GPU.",
    "limits": "Software WebGL renders in about two seconds a frame."
  },
  "limitations": [
    "Heights come from a formula; to chart data replace the field function.",
    "At the finest grids neighbouring cubes nearly touch."
  ],
  "license": {
    "spdx": "MIT",
    "notice": "Copyright (c) 2026 AI Pixel Wizard. Released under the MIT License. See LICENSE in this folder.",
    "thirdParty": []
  },
  "provenance": "Adapted from the owner's threejs-sketches/geometry-math/cube-wave (MIT) and rebuilt for AI Pixel Wizard in October 2026 as an original studio object: instanced glossy cubes on a grid with four closed-form wave patterns, size and colour following height, on an exact loop.",
  "changelog": [
    {
      "version": "1.0.0",
      "date": "2026-10-05",
      "notes": "Initial release."
    }
  ]
}