MonstrJS

Generate unique pixel art monsters from any text. Each input produces a deterministic, adorable creature with customizable features.

Features

• Deterministic Generation: Same text always produces the same monster
• 8 Monster Types: Blob, Bunny, Kitty, Birdie, Puppy, Bear, Dino, and Alien
• Cute Pixel Art Style: Rounded shapes, big expressive eyes, friendly expressions
• 16 Color Palettes: Bright, friendly colors designed for appealing monsters
• CLI & Library: Use from command line or integrate into your Node.js projects
• PNG Export: Save monsters as scalable PNG images
• Symmetry Options: Generate symmetric or asymmetric monsters

Installation

npm install monstrjs

Or install globally for CLI usage:

npm install -g monstrjs

CLI Usage

Basic Usage

Generate and display a monster in the terminal:

monstrjs "your-text-here"

Save as PNG

monstrjs "vcgtz" --png vcgtz.png

Options

| Option | Description | |--------|-------------| | --png <file> | Save monster as PNG image | | --scale <number> | PNG scale factor (default: 4) | | --asymmetric | Generate asymmetric monster | | --no-display | Don't display in terminal | | --export <file> | Export as .monstr format | | --import <file> | Import from .monstr file | | --compare | Show side-by-side comparison |

Examples

# Generate with custom scale
monstrjs "hello world" --png hello-world.png --scale 8

# Asymmetric monster
monstrjs "unique" --png unique.png --asymmetric

# Generate without terminal output
monstrjs "avatar" --png avatar.png --no-display

# Export monster data
monstrjs "save-me" --export monster.monstr

# Import and display
monstrjs --import monster.monstr

Library Usage

Basic Usage

import { Monster } from 'monstrjs';

// Create a monster from text
const monster = Monster.create('your-text-here');

// Display in terminal
monster.print();

// Save as PNG
await monster.toPng('monster.png', 4); // scale = 4

Advanced Usage

import { Monster } from 'monstrjs';

// Create from specific seed
const monster = Monster.fromSeed(12345);

// Create with options
const asymmetricMonster = Monster.create('text', { symmetric: false });

// Export/Import
const data = monster.export();
await monster.exportToFile('monster.monstr');

const imported = await Monster.importFromFile('monster.monstr');

// Compare two monsters
Monster.compare('text1', 'text2');

Direct Generator Access

import { generateMonster } from 'monstrjs';

const result = generateMonster('your-text', {
  seed: 12345,        // optional: override seed
  symmetric: true,    // optional: enable symmetry (default: true)
});

console.log(result.grid);    // 64x64 pixel grid
console.log(result.seed);    // generation seed
console.log(result.palette); // color palette used

Monster Types

MonstrJS generates 8 different creature types based on the input seed:

| Type | Description | |------|-------------| | Blob | Round squishy body, big eyes, tiny arms | | Bunny | Upright body, long ears, fluffy tail | | Kitty | Cat-like with pointy ears, whiskers | | Birdie | Small wings, beak, feathery tuft | | Puppy | Floppy ears, wagging tail, spots | | Bear | Round ears, chubby body, paws | | Dino | Small spikes on back, stubby tail | | Alien | Antenna, big eyes, unique patterns |

How It Works

1. Text Hashing: Input text is hashed to create a deterministic seed
2. Type Selection: Monster type is selected based on seed
3. Feature Selection: Eyes, mouth, ears, tail, and accessories are chosen
4. Sprite Composition: Parts are layered onto a 64x64 pixel grid
5. Color Application: A color palette is applied to the sprite
6. Symmetry: Optional vertical symmetry is applied

Configuration

Grid Size

Monsters are generated on a 64x64 pixel grid.

Color Palettes

16 built-in palettes including:

• Coral Pink, Sunny Orange, Sky Blue
• Mint Green, Lavender, Bubblegum Pink
• Lemon Yellow, Seafoam, Peach
• And more...

Development

# Clone the repository
git clone [email protected]:vcgtz/monstrjs.git
cd monstrjs

# Install dependencies
npm install

# Build
npm run build

# Run in development mode
npm run dev

License

MIT License - see LICENSE for details.

Author

Vicente Gutierrez (@vcgtz)