pxui-compiler

v1.0.1

Published

a month ago

Compile .pxui pixel art files to CSS. Build-time compiler with CLI and programmatic API.

0High
0Medium
0Low

thexpo

pixel-art css compiler cli pxui sprite retro 8-bit pixel game web-component

PXUI - Pixel Art to CSS Compiler

Create pixel art sprites using simple JSON files, then render them as pure CSS. No images, no canvas, just CSS!

⚡ Quick Start (5 Minutes)

Step 1: Install

npm install pxui-compiler

Step 2: Create Your First Sprite

Create a file called heart.pxui:

{
  "pxuiVersion": "1.0",
  "meta": {
    "name": "heart"
  },
  "grid": {
    "width": 8,
    "height": 8,
    "pixelSize": 16
  },
  "palette": {
    ".": "transparent",
    "R": "#ff0000",
    "P": "#ff6b6b"
  },
  "pixels": [
    ".RR..RR.",
    "RRRRRRRR",
    "RRRPRRRR",
    "RRRRRRRR",
    ".RRRRRR.",
    "..RRRR..",
    "...RR...",
    "........"
  ]
}

How it works:

palette maps characters to colors (. = transparent, R = red, P = pink)
pixels is your sprite - each character is one pixel!
pixelSize controls how big each pixel renders (16px here)

Step 3: Compile It

pxui compile heart.pxui -o heart.css

Step 4: Use in HTML

<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="heart.css">
</head>
<body>
  <div class="pxui-heart"></div>
</body>
</html>

That's it! Your pixel art heart renders as pure CSS. 🎉

🌐 Browser Method (Even Easier!)

Don't want to compile? Use the runtime loader with <pxui-sprite> tags:

<!DOCTYPE html>
<html>
<head>
  <title>PXUI Demo</title>
</head>
<body>
  <!-- Include the loader (only 3KB) -->
  <script src="node_modules/pxui-compiler/src/loader.js"></script>
  
  <!-- Use sprites directly! -->
  <pxui-sprite src="heart.pxui"></pxui-sprite>
  
  <!-- Scale it up 2x -->
  <pxui-sprite src="heart.pxui" scale="2"></pxui-sprite>
  
  <!-- Scale it up 4x -->
  <pxui-sprite src="star.pxui" scale="4"></pxui-sprite>
</body>
</html>

The loader:

Fetches .pxui files automatically
Compiles them in the browser
Injects CSS for you
Caches results for performance

📁 Complete Working Example

1. Project Structure

my-project/
├── sprites/
│   ├── heart.pxui
│   └── star.pxui
├── index.html
└── package.json

2. star.pxui

{
  "pxuiVersion": "1.0",
  "meta": { "name": "star" },
  "grid": { "width": 9, "height": 9, "pixelSize": 12 },
  "palette": {
    ".": "transparent",
    "Y": "#ffd700",
    "O": "#ff8c00"
  },
  "pixels": [
    "....Y....",
    "....Y....",
    "...YYY...",
    "YYYYYYYYY",
    ".YYYYYYY.",
    "..YYOYY..",
    "..YYYYY..",
    ".YY...YY.",
    ".Y.....Y."
  ]
}

3. index.html

<!DOCTYPE html>
<html>
<head>
  <title>My Pixel Art</title>
  <style>
    body {
      background: #1a1a2e;
      display: flex;
      gap: 2rem;
      padding: 2rem;
    }
  </style>
</head>
<body>
  <pxui-sprite src="sprites/heart.pxui" scale="2"></pxui-sprite>
  <pxui-sprite src="sprites/star.pxui" scale="2"></pxui-sprite>
  
  <script src="node_modules/pxui-compiler/src/loader.js"></script>
</body>
</html>

🛠 CLI Commands

# Compile single file
pxui compile heart.pxui -o heart.css

# Compile entire folder
pxui build ./sprites ./dist

# Validate a file (check for errors)
pxui validate heart.pxui

# Compile with minified CSS
pxui compile heart.pxui -o heart.css --minify

# Use box-shadow mode (single element, smallest HTML)
pxui compile heart.pxui -o heart.css --mode shadow

💻 Programmatic API

const { loadPXUI, loadPXUIDir, compileToCSS } = require('pxui-compiler');

// Load and compile a single file
const { html, css } = loadPXUI('./sprites/heart.pxui');
console.log(css);  // The generated CSS

// Load all sprites from a folder
const { sprites, combinedCSS } = loadPXUIDir('./sprites');
console.log(sprites.heart.html);  // Access by filename
console.log(sprites.star.css);

// Quick compile from JSON string
const css = compileToCSS(jsonString, { minify: true });

🎨 .pxui File Format

{
  "pxuiVersion": "1.0",
  "meta": {
    "name": "sprite-name",
    "author": "Your Name",
    "description": "What this sprite is"
  },
  "grid": {
    "width": 8,
    "height": 8,
    "pixelSize": 16
  },
  "palette": {
    ".": "transparent",
    "A": "#ff0000",
    "B": "#00ff00",
    "C": "#0000ff"
  },
  "pixels": [
    "AABBCCAA",
    "AABBCCAA",
    "........"
  ]
}

| Field | Required | Description | |-------|----------|-------------| | pxuiVersion | Yes | Always "1.0" | | grid.width | Yes | Number of columns | | grid.height | Yes | Number of rows | | grid.pixelSize | Yes | Size of each pixel in CSS pixels | | palette | Yes | Map of characters to colors | | pixels | Yes | Array of strings (your pixel art!) | | meta | No | Optional name, author, description |

🔧 Render Modes

| Mode | Command | Best For | |------------------|----------------|---------------------------------------------------| | grid (default) | --mode grid | Static sprites, most compatible | | flex | --mode flex | Row-based layouts | | shadow | --mode shadow| Smallest HTML (single <div>) |

License

MIT