nixos/frame12/framework-plymouth-theme/SCRIPTING.md

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.

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

// 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

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

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

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

Math

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

Callbacks

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 - Setup and viewing
• Plymouth Theme Guide Part 2 - Sprites and images
• Plymouth Theme Guide Part 3 - Animation
• Plymouth Theme Guide Part 4 - Advanced topics