@yourname/laya-image-config-loader

A smart image configuration loader for LayaAir with code-drawn graphics fallback

Features

✨ Code-First Approach: Prioritize code-drawn graphics (gradients, rounded corners) over image assets 🎨 GraphicsDrawer: Built-in graphics drawing utilities for common UI elements 📦 Smart Fallback: Automatically uses code-drawn graphics or color blocks when images are missing 🔄 Hot Reload: Support for runtime image updates 💾 Embedded Config: Works without external JSON files 🎯 TypeScript: Full type safety and intellisense support 🚀 Zero Dependencies: Only requires LayaAir as peer dependency

Installation

npm install @yourname/laya-image-config-loader

Quick Start

1. Basic Usage

import { ImageLoader } from '@yourname/laya-image-config-loader';

// Initialize
const imageLoader = ImageLoader.getInstance();
await imageLoader.init();

// Load image with automatic fallback
const button = new Laya.Sprite();
await imageLoader.loadImage("ui_button_primary", button);
Laya.stage.addChild(button);

2. With Code-Drawn Graphics

import { GraphicsDrawer } from '@yourname/laya-image-config-loader';

// Draw a gradient button directly
const button = new Laya.Sprite();
GraphicsDrawer.draw(button, 200, 60, {
    type: "gradientRoundRect",
    colorStart: "#5DA5F5",
    colorEnd: "#4A90E2",
    gradientDirection: "vertical",
    radius: 8,
    borderColor: "#3A7BC8",
    borderWidth: 2
});

3. With Configuration

Create imageConfig.json:

{
  "images": {
    "ui_button_primary": {
      "path": "assets/images/ui/button_primary.png",
      "width": 200,
      "height": 60,
      "fallbackColor": "#4A90E2",
      "aiPrompt": "A modern primary button...",
      "useCodeDraw": true,
      "drawStyle": {
        "type": "gradientRoundRect",
        "colorStart": "#5DA5F5",
        "colorEnd": "#4A90E2",
        "gradientDirection": "vertical",
        "radius": 8
      }
    }
  }
}

API Reference

ImageLoader

Methods

• getInstance(): Get singleton instance
• init(configPath?): Initialize loader
• loadImage(key, target): Load image to target sprite
• preloadImage(key): Preload single image
• preloadImages(keys): Preload multiple images
• refreshImage(key, target?): Refresh image after update
• getAIPrompt(key): Get AI generation prompt
• getConfig(key): Get image configuration
• getAllKeys(): Get all image keys
• isImageMissing(key): Check if image is missing
• getMissingImageKeys(): Get all missing image keys

GraphicsDrawer

Draw Types

• solid: Solid color rectangle
• gradient: Gradient rectangle (horizontal/vertical)
• roundRect: Rounded rectangle
• gradientRoundRect: Gradient rounded rectangle
• circle: Circle

Preset Styles

GraphicsDrawer.presetPrimaryButton();
GraphicsDrawer.presetSecondaryButton();
GraphicsDrawer.presetPanel();
GraphicsDrawer.presetCoinIcon();
GraphicsDrawer.presetGemIcon();

ImageConfigManager

Methods

• getInstance(): Get singleton instance
• loadConfig(path): Load configuration from JSON
• getImageConfig(key): Get specific image config
• getAllKeys(): Get all configured keys
• setImageConfig(key, config): Set config at runtime

Configuration Schema

IImageConfig

interface IImageConfig {
  path: string;              // Image file path
  width: number;             // Image width
  height: number;            // Image height
  fallbackColor: string;     // Fallback color (hex)
  aiPrompt: string;          // AI generation prompt
  useCodeDraw?: boolean;     // Prioritize code drawing
  drawStyle?: IDrawStyle;    // Code drawing style
}

IDrawStyle

interface IDrawStyle {
  type: "solid" | "gradient" | "roundRect" | "circle" | "gradientRoundRect";
  color?: string;
  colorStart?: string;
  colorEnd?: string;
  gradientDirection?: "horizontal" | "vertical";
  radius?: number;
  borderColor?: string;
  borderWidth?: number;
}

Use Cases

✅ Recommended for Code Drawing

• Solid color buttons
• Gradient buttons
• Rounded panels
• Simple icons (circles, squares)
• UI backgrounds
• Progress bar backgrounds
• Dividers

❌ Not Recommended for Code Drawing

• Complex character sprites
• Textured images
• Irregular shapes
• Complex alpha channel images
• Animation frames

Workflow

1. Development: Use code-drawn graphics for rapid prototyping
2. Testing: Test layout with color blocks/graphics
3. AI Generation: Generate complex images using AI prompts
4. Integration: Place generated images at configured paths
5. Hot Reload: Call refreshImage() to switch to real images

Advanced Usage

Custom Configuration

import { ImageConfigManager } from '@yourname/laya-image-config-loader';

const configManager = ImageConfigManager.getInstance();

// Add config at runtime
configManager.setImageConfig("custom_button", {
  path: "assets/custom.png",
  width: 150,
  height: 50,
  fallbackColor: "#FF0000",
  aiPrompt: "Custom button design...",
  useCodeDraw: true,
  drawStyle: {
    type: "roundRect",
    color: "#FF6B6B",
    radius: 10
  }
});

Preloading

// Preload all images
const allKeys = imageLoader.getAllKeys();
await imageLoader.preloadImages(allKeys);

// Check for missing images
const missing = imageLoader.getMissingImageKeys();
if (missing.length > 0) {
  console.log("Missing images:", missing);
  missing.forEach(key => {
    const prompt = imageLoader.getAIPrompt(key);
    console.log(`Generate ${key}: ${prompt}`);
  });
}

Examples

Check the examples/ directory for complete examples:

• Basic usage
• Custom configurations
• Code-drawn UI kit
• Image generation workflow

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for details.

License

MIT © [Your Name]

Support

• 🐛 Report Issues
• 💬 Discussions
• 📧 Email: [email protected]

Related

• LayaAir Engine
• LayaAir Documentation

Made with ❤️ for the LayaAir community