# Plymouth Scripting Reference

Quick reference for Plymouth theme scripting. Based on Charlie Brej's Plymouth Theme Guide.

## Refresh Rate

The `refresh_callback` function is called **50 times per second** (50 FPS) unless the system is busy.

```javascript
progress = 0;
fun refresh_callback() {
    progress++;
    // Called 50x/second - use progress to control animation timing
}
Plymouth.SetRefreshFunction(refresh_callback);
```

## Animation Timing

To control animation speed, divide progress by a factor:

| Divisor | Frame Rate | 100-frame animation duration |
|---------|------------|------------------------------|
| 1       | 50 FPS     | 2 seconds                    |
| 2       | 25 FPS     | 4 seconds                    |
| 3       | ~17 FPS    | 6 seconds                    |
| 5       | 10 FPS     | 10 seconds                   |

```javascript
// Advance 1 frame per refresh (fastest)
sprite.SetImage(images[progress % frame_count]);

// Advance 1 frame every N refreshes (slower)
sprite.SetImage(images[Math.Int(progress / N) % frame_count]);
```

## Core Objects

### Image
```javascript
img = Image("file.png");              // Load PNG image
img.GetWidth();                       // Get dimensions
img.GetHeight();
img.Scale(width, height);             // Returns new scaled image
img.Rotate(radians);                  // Returns new rotated image
Image.Text("text", r, g, b);          // Create text image (RGB 0-1)
```

### Sprite
```javascript
sprite = Sprite();                    // Empty sprite
sprite = Sprite(image);               // Sprite with image
sprite.SetImage(image);               // Change image
sprite.SetPosition(x, y, z);          // Set position (z = layer)
sprite.SetX(x); sprite.SetY(y); sprite.SetZ(z);
sprite.SetOpacity(0.0 - 1.0);         // 0 = invisible, 1 = solid
```

### Window
```javascript
Window.GetWidth();                    // Screen width
Window.GetHeight();                   // Screen height
Window.GetX();                        // Window X offset
Window.GetY();                        // Window Y offset
```

### Math
```javascript
Math.Int(n);                          // Floor to integer
Math.Sin(radians);
Math.Cos(radians);
```

## Callbacks

```javascript
Plymouth.SetRefreshFunction(callback);           // Called 50x/second
Plymouth.SetDisplayPasswordFunction(callback);   // LUKS password prompt
Plymouth.SetDisplayQuestionFunction(callback);   // Question prompt
Plymouth.SetDisplayNormalFunction(callback);     // Return to normal
Plymouth.SetMessageFunction(callback);           // System messages
```

## Z-Index Guidelines

- Background: -10000
- Default: 0
- Password dialog: 10000 (don't exceed)

## Resources

- [Plymouth Theme Guide Part 1](http://brej.org/blog/?p=158) - Setup and viewing
- [Plymouth Theme Guide Part 2](http://brej.org/blog/?p=174) - Sprites and images
- [Plymouth Theme Guide Part 3](http://brej.org/blog/?p=197) - Animation
- [Plymouth Theme Guide Part 4](http://brej.org/blog/?p=238) - Advanced topics