Crumple

Crumple

Crumpled paper you can open.

A dependency-free WebGL2 library: a crumpled note flies to the center of the screen and unfolds into a readable sheet, creases, ink and all.

Paper types

Ten kinds of paper, one for each type. Click any of them.

Shapes

The same typed sheet, folded or crumpled seven ways.

States

Fourteen states: wear, stains, fire and marks, plus the secrets.

Move the light over the hidden ink to read it (mouse on a desktop). Burn after reading is gone for good once you close it.

Burn forms

Four ways to burn: from a corner, along an edge, a hole from the center, or a few embers.

Playground

Build a paper, then crumple, unfold, flip at any moment, tear it, or burn it four ways. The JSON box shows exactly what you are using.

Paper settings

Config (JSON)

Install and usage

Pick the way you load it. All of them need Crumple.config.assets pointing at the assets folder.

Script tag (CDN)

Set the assets folder before the first paper is built. The CDN serves the textures and the demo photos.

HTML
<script src="https://cdn.jsdelivr.net/gh/devAndreotti/crumple@1.0.0/dist/crumple.min.js"></script>
<script>
  Crumple.config.assets = 'https://cdn.jsdelivr.net/gh/devAndreotti/crumple@1.0.0/assets/';
</script>

npm (ES modules)

Install from GitHub, then import what you need. Scene attaches to buttons, Stage draws into your own canvas.

shell
npm i @devandreotti/crumple
JavaScript
import { Scene, config } from '@devandreotti/crumple';

// serve the package's assets/ folder and point config.assets at it
config.assets = '/assets/';
Scene.init({ motion: 'auto' });
CommonJS
const { Stage } = require('@devandreotti/crumple');

Minimal HTML

HTML
<button id="note">Open the note</button>

<script src="https://cdn.jsdelivr.net/gh/devAndreotti/crumple@1.0.0/dist/crumple.min.js"></script>
<script>
  Crumple.Scene.init();
  Crumple.Scene.attach(document.getElementById('note'), {
    id: 'welcome',
    type: 'typed',
    text: '# Hello\n\nThis note was folded for you.'
  });
</script>

Stage example

HTML
<canvas id="sheet" style="width: 100%; height: 480px"></canvas>
<button id="flip">Flip</button>

<script src="https://cdn.jsdelivr.net/gh/devAndreotti/crumple@1.0.0/dist/crumple.min.js"></script>
<script>
  (async () => {
    const stage = Crumple.Stage(document.getElementById('sheet'));
    if (!stage) return; // no WebGL2
    await stage.set({ type: 'notebook', seed: 12, text: '# A note on a canvas\n\nNo flight, just a sheet.' }, { progress: 0 });
    stage.uncrumple();
    document.getElementById('flip').onclick = () => stage.flip();
  })();
</script>

Events

Events bubble from the trigger, so one listener on document catches all of them.

JavaScript
document.addEventListener('crumple:open', (e) => {
  console.log('opened', e.detail.id);
});

document.addEventListener('crumple:burn', (e) => {
  console.log('burned', e.detail.id);
});

API reference

Compact reference. The full typings are in crumple.d.ts.

Paper config

Config object passed to attach, Stage.set, or normalize.

NameDescription
idUnique id, used for storage keys and events. Defaults to the type.
typeOne of the ten paper types.
shapeClosed shape. Envelopes always use their own shape.
statesArray of states: torn, burnt, coffee, water, prints, aged, scribbled.
textFront text, with the markup described below.
backBack text, shown when the paper is flipped.
seedInteger. The same seed always gives the same crumple.
open'auto' unfolds by itself; 'drag' waits for the reader to drag or pinch it open.
hiddenInkIndented writing, visible only under grazing light (the flashlight).
burnAfterReadingOn close the paper burns for good. Remembered per browser in localStorage.
imagePhoto URL for the polaroid type (same origin or CORS-enabled).
addressAddress written on the envelope.
letterType of the letter inside an envelope.
burnWhere the fire starts: 'corner' (default), 'edge', 'center' or 'spots'. Used by burnt, burnAfterReading and Stage.burn().
stampThe word of the rubber stamp state, in capitals. Default 'RECEIVED'.

Scene (triggers)

Papers that sit on the page as buttons and fly to the center when clicked.

NameDescription
Scene.init(options)Call once. Options: labels, remember, motion (auto, full or reduce), flashlight (default true), maxBuilt (papers kept on the GPU, default 3).
Scene.detach(el or id)Undoes attach for one trigger, or for the paper with that id.
Scene.destroy()Removes the overlay, listeners, observers and the WebGL context. attach() or init() starts it again.
Scene.attach(el, config, opts)Turns a button into a crumpled-paper trigger. Options: snapshot and snapshotOpened (still images).
Scene.open(entry)Opens an attached entry programmatically. Resolves when the paper is built.
Scene.close()Closes the open paper (the same as Escape or a click outside).
Scene.flip() / tear()Flips the open paper, or tears its stub.
Scene.reset()Forgets which papers were opened (with remember on).
entries · isOpen · reducedMotionentries (list), isOpen (boolean), reducedMotion (boolean).

Minimal example

JS
Crumple.config.assets = 'assets/';
Crumple.Scene.init({ motion: 'auto' });
// any button becomes a paper: click to open, drag to crumple
// 'note' is any 

Stage (inline canvas)

A paper rendered in place in your own canvas, with no flight.

NameDescription
Stage(canvas, opts)Crumple.Stage(canvas, { fit, flashlight, drag, motion }). fit is the share of the canvas height the open sheet takes (default 0.8). motion is 'auto', 'reduce' or 'full'. Returns null without WebGL2.
set(config, { progress })Builds a paper from a config and shows it. Resolves with the paper (or null if a newer call replaced it).
crumple · uncrumple · togglecrumple(), uncrumple(), toggle(), flip() (at any moment), tear(), restoreStub(), restore().
burn()Burns the paper from its burn form, on any paper. Returns a Promise that resolves once the burn has started.
destroy()Frees the paper, listeners and the WebGL context. Every method is a no-op afterwards.
setProgress(v)setProgress(0..1): 0 is closed, 1 is fully open.
png() · snapshot()png() returns a data URL of the current frame. snapshot(opened, format, size) returns a still image.

Sound

Paper noises, synthesized with Web Audio. Off by default.

NameDescription
Sound.set(bool)Turns sounds on or off. Stored in localStorage.
Sound.enabledCurrent state (read-only).
Sound.useSamples(urls)Optional recordings, used instead of the synthesized sounds when they load.
Sound.play(name)Plays one of: crumple, uncrumple, flip, tear, seal, fire, grain.

Events

CustomEvents dispatched from the trigger button. Each carries detail.id.

NameDescription
crumple:openOpened. detail: { id, openings, fallback }.
crumple:closeClosed. detail: { id }.
crumple:flipFlipped. detail: { id, back }.
crumple:tearStub torn. detail: { id }.
crumple:burnBurned after reading. detail: { id }.

Text markup

Plain text with three small extras.

NameDescription
# titleA line that starts with "# " is a heading.
~~word~~{fix}A struck-out word with a handwritten correction.
[[text]]A redaction bar that fades a little more on every opening.

Modules and renderer

ES modules and CommonJS. Importing the package in Node or on a server is safe: nothing touches window until you call it.

NameDescription
import · requireimport { Scene, Stage, config } from '@devandreotti/crumple', or const { Stage } = require('@devandreotti/crumple').
Renderer(canvas)A lower-level renderer on your own canvas (build, snapshot, release). destroy() frees its GL resources; release the papers first.

Crumple.config

NameDescription
assetsBase URL of the assets folder (textures and demo photos).
storagePrefixPrefix for localStorage keys (sound, opening counts, burnt papers).
googleFontsLoad the paper fonts from Google Fonts on demand (set false if the page already ships them).