Letter Collage API

The Letter Collage system creates stylized text with per-letter customization. Each letter becomes a separate Paper.js item that can be individually styled, animated, or positioned.

Overview

Letter Collage transforms plain text into visually stunning designs by applying different styles to each character. This is perfect for:

• Word game graphics (Wordle, Scrabble)
• Ransom note / magazine cutout effects
• Paper craft and origami aesthetics
• Gradient text designs
• Creative typography

Available Styles

Basic Usage

// Access via app.letterCollage
const collage = app.letterCollage.create('HELLO', {
  style: 'tile',
  palette: 'wordle',
  fontSize: 48
});

// Returns { group, letters, collageId }
// - group: Paper.js Group containing all letters
// - letters: Array of individual letter groups
// - collageId: Unique identifier for this collage

API Reference

create(text, options)

Create a letter collage from text.

Parameters:

Returns: { group, letters, collageId }

Style-Specific Options

Tile Style

app.letterCollage.create('WORD', {
  style: 'tile',
  palette: 'wordle',      // Color palette
  cornerRadius: 6,        // Tile corner radius
  showBorder: true,       // Show tile border
  shadowEnabled: true     // Add drop shadow
});

Magazine Style

app.letterCollage.create('RANSOM', {
  style: 'magazine',
  palette: 'magazine',
  magazinePreset: 'classic'  // 'classic', 'bold', 'vintage'
});

Paper Cut Style

app.letterCollage.create('CUT', {
  style: 'paperCut',
  paperCutPreset: 'classic'  // 'classic', 'rough', 'clean'
});

Fold Style

app.letterCollage.create('FOLD', {
  style: 'fold',
  palette: 'origami',
  foldPreset: 'simple'  // 'simple', 'complex'
});

Gradient Style

app.letterCollage.create('GRADIENT', {
  style: 'gradient',
  gradientPalette: 'sunset',
  gradientDirection: 'vertical'  // 'vertical', 'horizontal', 'diagonal', 'radial'
});

Image Style

app.letterCollage.create('IMAGE', {
  style: 'image',
  imageSource: 'https://example.com/texture.jpg'  // URL or data URL
});

Available Palettes

Tile Palettes (for tile, magazine, fold styles)

Gradient Palettes (for gradient style)

Utility Methods

getCollage(collageId)

Get a collage by its ID.

const collage = app.letterCollage.getCollage('collage_1');

updateCollage(collageId, newOptions)

Update an existing collage with new options.

app.letterCollage.updateCollage('collage_1', {
  palette: 'neon',
  fontSize: 64
});

removeCollage(collageId)

Remove a collage from the canvas.

app.letterCollage.removeCollage('collage_1');

animateCollage(collageId, animationType, options)

Apply animation to all letters with staggered timing.

app.letterCollage.animateCollage('collage_1', 'pulse', {
  staggerDelay: 0.1,     // Delay between letters
  animationSpeed: 1
});

getAvailableStyles()

Get list of available styles.

const styles = app.letterCollage.getAvailableStyles();
// ['tile', 'magazine', 'paperCut', 'fold', 'gradient', 'image']

getAvailablePalettes()

Get available palettes organized by category.

const palettes = app.letterCollage.getAvailablePalettes();

getAvailableGradients()

Get available gradient palette names.

const gradients = app.letterCollage.getAvailableGradients();
// ['rainbow', 'sunset', 'ocean', 'fire', 'cyberpunk', ...]

clearAll()

Remove all collages.

app.letterCollage.clearAll();

Examples

Wordle-Style Word

const wordle = app.letterCollage.create('HELLO', {
  style: 'tile',
  palette: 'wordle',
  fontSize: 64,
  cornerRadius: 4
});

Magazine Ransom Note

const ransom = app.letterCollage.create('RANSOM NOTE', {
  style: 'magazine',
  palette: 'magazine',
  fontSize: 48
});

Animated Gradient Text

const gradient = app.letterCollage.create('SHINE', {
  style: 'gradient',
  gradientPalette: 'gold',
  gradientDirection: 'diagonal',
  fontSize: 72
});

// Add staggered pulse animation
app.letterCollage.animateCollage(gradient.collageId, 'pulse', {
  staggerDelay: 0.15
});

Paper Craft Effect

const paperCut = app.letterCollage.create('CRAFT', {
  style: 'paperCut',
  fontSize: 56
});

Origami Fold

const origami = app.letterCollage.create('FOLD', {
  style: 'fold',
  palette: 'origami',
  fontSize: 60
});

Working with Individual Letters

Each letter in a collage is a separate Paper.js Group that can be manipulated individually:

const collage = app.letterCollage.create('WORD', { style: 'tile' });

// Access individual letters
collage.letters.forEach((letterGroup, index) => {
  console.log(`Letter ${index}: ${letterGroup.data.char}`);

  // Modify individual letter
  letterGroup.rotate(5);
  letterGroup.scale(1.1);
});

// Select the entire collage group
app.select(collage.group);

Selection and Manipulation

Letter collages are registered with the ItemRegistry and can be selected, moved, and deleted like any other canvas item:

// Create collage
const collage = app.letterCollage.create('TEXT', { style: 'tile' });

// Select the collage group
app.select(collage.group);

// Modify using standard modify API
app.modify({
  x: 500,
  y: 300,
  rotation: 15
});

// Delete
app.removeSelectedItems();

Serialization

Letter collages are automatically serialized with the scene and will be restored when loading saved scenes.