# Pixcen Exporter Scripts

This directory contains JavaScript exporter scripts for Pixcen. Exporters allow users to create custom export functionality using JavaScript.

## How Exporters Work

Exporters are JavaScript files that register themselves with Pixcen using the `pixcen.registerExporter()` function. When a user selects an exporter format in the save dialog, Pixcen executes the corresponding JavaScript script to perform the export.

## Exporter Structure

Every exporter script must:

1. Register itself using `pixcen.registerExporter(metadata)`
2. Define an `export` function that handles the export process
3. Declare which formats and modes it supports

### Basic Template

```javascript
pixcen.registerExporter({
    // Basic metadata
    name: "My Exporter",
    description: "Description of what this exporter does",
    category: "Category",
    version: "1.0.0",
    author: "Your Name",

    // Format support
    formats: ["format_name"],
    extensions: ["ext"],

    // Mode compatibility
    modes: {
        hires: true,        // Supports hires modes
        multicolor: true,   // Supports multicolor modes
        animation: true,    // Supports animations
        single: true        // Supports single images
    },

    // Optional parameters
    params: {
        parameterName: {
            type: "number|color|boolean|selection|string",
            label: "Display Name",
            default: defaultValue,
            min: 0,          // For numbers
            max: 100         // For numbers
        }
    },

    // Main export function
    export: function(config, filePath) {
        // config contains parameter values
        // filePath is the output file path

        // Get canvas data
        const pixels = pixcen.canvas.getPixels();
        const isAnimated = pixcen.canvas.isAnimated();

        // Perform export...

        pixcen.ui.log("Export completed!");
    }
});
```

## Available APIs

Exporters have access to the full Pixcen script API:

### Canvas APIs
- `pixcen.canvas.getWidth()` - Get canvas width
- `pixcen.canvas.getHeight()` - Get canvas height
- `pixcen.canvas.getMode()` - Get current graphics mode
- `pixcen.canvas.getPixels()` - Get all pixels as 2D array
- `pixcen.canvas.getFramePixels(index)` - Get specific animation frame
- `pixcen.canvas.isAnimated()` - Check if canvas is animated

### Animation APIs
- `pixcen.animation.getFrameCount()` - Get number of frames
- `pixcen.animation.getCurrentFrame()` - Get current frame index
- `pixcen.animation.setCurrentFrame(index)` - Set current frame

### UI APIs
- `pixcen.ui.log(message)` - Log message to output
- `pixcen.ui.showProgress(message, percent)` - Show progress dialog
- `pixcen.ui.updateProgress(message, percent)` - Update progress
- `pixcen.ui.hideProgress()` - Hide progress dialog
- `pixcen.ui.showMessage(message, title)` - Show message box

### Progress Reporting
Exporters automatically get access to progress reporting through the progress callback system. Use `pixcen.ui.showProgress()` and `pixcen.ui.updateProgress()` to provide user feedback during long operations.

## Included Exporters

### PNG Exporter (`png_exporter.js`)
- Exports canvas as PNG with configurable options
- Supports scaling, transparency, and dithering
- Handles both single images and animations

### C64 Raw Data Exporter (`c64_raw_exporter.js`)
- Exports canvas as raw C64-compatible data
- Supports multiple output formats (bitmap, full data, compressed)
- Includes proper C64 graphics mode handling

### Animated GIF Exporter (`animated_gif_exporter.js`)
- Creates animated GIF files from canvas animations
- Configurable frame timing and optimization
- Color reduction and dithering options

## Installing Exporters

1. Place `.js` files in this directory
2. Restart Pixcen or use Scripts → Reload Exporters
3. Exporters will automatically appear in the save dialog

## Debugging

- Check the debug output window for script loading errors
- Use `pixcen.ui.log()` to output debug information
- Test exporters with small canvases first

## Security Considerations

- Exporters run in a sandboxed JavaScript environment
- File access is restricted to the specified export path
- Network access is blocked
- System calls are not available

## Creating New Exporters

1. Copy an existing exporter as a template
2. Modify the metadata and export logic
3. Test with different canvas modes and sizes
4. Add proper error handling and user feedback
5. Include documentation for any special parameters

For more examples, see the included exporter scripts and the Pixcen scripting documentation.
