screensaver-development

name	screensaver-development
description	| Use when this capability is needed.

LCDPossible Screensaver Development Guide

This skill provides patterns for implementing animated screensaver panels.

Quick Start

All screensavers go in src/Plugins/LCDPossible.Plugins.Screensavers/Panels/.

using LCDPossible.Sdk;
using SixLabors.ImageSharp;
using SixLabors.ImageSharp.Drawing;
using SixLabors.ImageSharp.Drawing.Processing;
using SixLabors.ImageSharp.PixelFormats;
using SixLabors.ImageSharp.Processing;

namespace LCDPossible.Plugins.Screensavers.Panels;

public sealed class MyScreensaverPanel : BaseLivePanel
{
    private DateTime _lastUpdate = DateTime.UtcNow;

    public override string PanelId => "my-screensaver";
    public override string DisplayName => "My Screensaver";
    public override bool IsAnimated => true;  // IMPORTANT: Must be true

    public override Task InitializeAsync(CancellationToken ct = default)
    {
        return Task.CompletedTask;
    }

    public override Task<Image<Rgba32>> RenderFrameAsync(
        int width, int height, CancellationToken ct = default)
    {
        // Calculate delta time for smooth animation
        var now = DateTime.UtcNow;
        var deltaTime = (float)(now - _lastUpdate).TotalSeconds;
        _lastUpdate = now;

        var image = new Image<Rgba32>(width, height, new Rgba32(0, 0, 0));

        image.Mutate(ctx =>
        {
            // Your drawing code here
        });

        return Task.FromResult(image);
    }
}

Registration (3 places)

1. ScreensaversPlugin.cs - PanelTypes Dictionary

["my-screensaver"] = new PanelTypeInfo
{
    TypeId = "my-screensaver",
    DisplayName = "My Screensaver",
    Description = "Description here",
    Category = "Screensaver",
    IsLive = true
}

2. ScreensaversPlugin.cs - ScreensaverTypes Array

private static readonly string[] ScreensaverTypes =
[
    "starfield", "matrix-rain", /* ... */, "my-screensaver"
];

3. ScreensaversPlugin.cs - CreateScreensaverPanel Switch

"my-screensaver" or "myscreensaver" => new MyScreensaverPanel(),

4. plugin.json (Full Metadata Required)

{
  "typeId": "my-screensaver",
  "displayName": "My Screensaver",
  "description": "Brief one-line description for list-panels output",
  "category": "Screensaver",
  "isLive": true,
  "isAnimated": true,
  "helpText": "Detailed description of the screensaver effect.\n\nFeatures:\n- Feature 1\n- Feature 2\n- Feature 3\n\nInspired by [reference if applicable].",
  "examples": [
    {
      "command": "lcdpossible show my-screensaver",
      "description": "Display the screensaver effect"
    }
  ]
}

Required Metadata Fields for Screensavers

Field	Value	Notes
typeId	lowercase-with-hyphens	Unique panel identifier
displayName	Title Case	Shown in help
description	Brief text	Shown in list-panels output
category	"Screensaver"	Always use this for screensavers
isLive	true	Screensavers update continuously
isAnimated	true	Screensavers manage their own timing
helpText	Multi-line	Detailed help for help-panel command
examples	Array	At least one usage example

For Parameterized Screensavers

If your screensaver accepts arguments (like falling-blocks:2 for 2 players):

{
  "typeId": "my-screensaver",
  "prefixPattern": "my-screensaver:",
  "parameters": [
    {
      "name": "mode",
      "description": "Screensaver mode or configuration",
      "required": false,
      "defaultValue": "default",
      "exampleValues": ["option1", "option2"]
    }
  ],
  "examples": [
    {
      "command": "lcdpossible show my-screensaver:option1",
      "description": "Run with option1 mode"
    }
  ]
}

Animation Patterns

Delta-Time Movement

For objects that move at consistent speed regardless of frame rate:

private float _x, _y;
private float _velocityX = 100f;  // pixels per second
private float _velocityY = 80f;
private DateTime _lastUpdate = DateTime.UtcNow;

public override Task<Image<Rgba32>> RenderFrameAsync(...)
{
    var now = DateTime.UtcNow;
    var deltaTime = (float)(now - _lastUpdate).TotalSeconds;
    _lastUpdate = now;

    // Movement is frame-rate independent
    _x += _velocityX * deltaTime;
    _y += _velocityY * deltaTime;
}

Time-Based Effects

For cyclical animations (pulsing, rotating, oscillating):

private DateTime _startTime = DateTime.UtcNow;

public override Task<Image<Rgba32>> RenderFrameAsync(...)
{
    var time = (float)(DateTime.UtcNow - _startTime).TotalSeconds;

    // Oscillation (0 to 1 to 0)
    var pulse = (MathF.Sin(time * 2f) + 1f) / 2f;

    // Rotation (radians)
    var rotation = time * MathF.PI;  // Half rotation per second

    // Color cycling
    var hue = (time * 0.1f) % 1f;
}

Cyclic Animation (Looping)

var cycleTime = time % 20f;  // 20-second loop

if (cycleTime < 5f)
{
    // Phase 1: 0-5 seconds
}
else if (cycleTime < 10f)
{
    // Phase 2: 5-10 seconds
}
// etc.

Drawing Techniques

Essential Imports

using SixLabors.ImageSharp;
using SixLabors.ImageSharp.Drawing;           // EllipsePolygon, PathBuilder
using SixLabors.ImageSharp.Drawing.Processing; // Fill, DrawLine
using SixLabors.ImageSharp.PixelFormats;      // Rgba32
using SixLabors.ImageSharp.Processing;        // Mutate, ProcessPixelRows

Basic Shapes

// Circle/Ellipse
ctx.Fill(color, new EllipsePolygon(centerX, centerY, radius));
ctx.Fill(color, new EllipsePolygon(centerX, centerY, radiusX, radiusY));

// Rectangle
ctx.Fill(color, new RectangleF(x, y, width, height));

// Line
ctx.DrawLine(color, thickness, new PointF(x1, y1), new PointF(x2, y2));

// Multiple connected lines
ctx.DrawLine(color, thickness,
    new PointF(x1, y1),
    new PointF(x2, y2),
    new PointF(x3, y3));

Complex Shapes with PathBuilder

CRITICAL: Always start with MoveTo(), not LineTo()!

var path = new PathBuilder();
path.MoveTo(new PointF(x1, y1));   // First point - MUST use MoveTo
path.LineTo(new PointF(x2, y2));   // Subsequent points
path.LineTo(new PointF(x3, y3));
path.CloseFigure();                // Connect back to start
ctx.Fill(color, path.Build());

Composite Sprites (Ghost Example)

For complex sprites, combine simple shapes:

// Ghost body = dome + rectangle + wavy bottom
ctx.Fill(bodyColor, new EllipsePolygon(x, y - size * 0.3f, size, size * 0.7f));  // Dome
ctx.Fill(bodyColor, new RectangleF(x - size, y - size * 0.3f, size * 2, size * 0.8f));  // Body

// Wavy bottom bumps
for (var i = 0; i < 4; i++)
{
    var bx = x - size + (i + 0.5f) * size * 0.5f;
    ctx.Fill(bodyColor, new EllipsePolygon(bx, y + size * 0.5f, size * 0.25f));
}

// Eyes on top
ctx.Fill(white, new EllipsePolygon(x - 4, y - size * 0.2f, 4, 5));
ctx.Fill(white, new EllipsePolygon(x + 4, y - size * 0.2f, 4, 5));

Pac-Man Mouth (Animated Wedge)

var mouthAngle = (MathF.Sin(time * 15f) + 1f) / 2f * 45f;  // 0-45 degrees
var mouthRad = mouthAngle * MathF.PI / 180f;
var baseAngle = facingLeft ? MathF.PI : 0f;

var path = new PathBuilder();
path.MoveTo(new PointF(x, y));  // Center point

var startAngle = baseAngle + mouthRad;
var endAngle = baseAngle - mouthRad + MathF.PI * 2f;

for (var a = startAngle; a < endAngle; a += 0.1f)
{
    path.LineTo(new PointF(
        x + MathF.Cos(a) * radius,
        y + MathF.Sin(a) * radius));
}
path.CloseFigure();
ctx.Fill(yellow, path.Build());

Per-Pixel Effects

For plasma, fire, noise, and other demoscene effects:

image.ProcessPixelRows(accessor =>
{
    for (var py = 0; py < height; py++)
    {
        var row = accessor.GetRowSpan(py);
        for (var px = 0; px < width; px++)
        {
            // Calculate color for this pixel
            var r = (byte)(/* calculation */);
            var g = (byte)(/* calculation */);
            var b = (byte)(/* calculation */);

            row[px] = new Rgba32(r, g, b);
        }
    }
});

Performance Optimization: Render at Lower Resolution

private const int ScaleFactor = 4;  // Render at 1/4 resolution

public override Task<Image<Rgba32>> RenderFrameAsync(int width, int height, ...)
{
    var scaledWidth = width / ScaleFactor;
    var scaledHeight = height / ScaleFactor;

    // Calculate at scaled resolution
    var buffer = new float[scaledWidth * scaledHeight];
    for (var sy = 0; sy < scaledHeight; sy++)
    {
        for (var sx = 0; sx < scaledWidth; sx++)
        {
            buffer[sy * scaledWidth + sx] = /* calculate */;
        }
    }

    // Upscale when rendering
    image.ProcessPixelRows(accessor =>
    {
        for (var py = 0; py < height; py++)
        {
            var sy = Math.Min(py / ScaleFactor, scaledHeight - 1);
            var row = accessor.GetRowSpan(py);

            for (var px = 0; px < width; px++)
            {
                var sx = Math.Min(px / ScaleFactor, scaledWidth - 1);
                var value = buffer[sy * scaledWidth + sx];
                row[px] = ValueToColor(value);
            }
        }
    });
}

Common Effect Patterns

Plasma Effect

var value = 0f;
value += MathF.Sin((x * 8f + time * 0.5f) * MathF.PI * 2f);
value += MathF.Sin((y * 7f + time * 0.4f) * MathF.PI * 2f);
value += MathF.Sin(((x + y) * 6f + time * 0.7f) * MathF.PI * 2f);

// Circular waves from moving center
var dx = x - (0.5f + MathF.Sin(time * 0.7f) * 0.3f);
var dy = y - (0.5f + MathF.Cos(time * 0.5f) * 0.3f);
var dist = MathF.Sqrt(dx * dx + dy * dy);
value += MathF.Sin((dist * 15f - time) * MathF.PI * 2f);

value = (value / 4f + 1f) / 2f;  // Normalize to 0-1

Fire Effect

// Use a buffer smaller than output, propagate heat upward
private byte[] _fireBuffer;

// Each frame: Add heat at bottom, propagate up with cooling
for (var x = 0; x < bufferWidth; x++)
{
    _fireBuffer[(bufferHeight - 1) * bufferWidth + x] =
        (byte)_random.Next(200, 256);
}

for (var y = 0; y < bufferHeight - 1; y++)
{
    for (var x = 0; x < bufferWidth; x++)
    {
        var sum = _fireBuffer[(y + 1) * bufferWidth + Math.Max(0, x - 1)]
                + _fireBuffer[(y + 1) * bufferWidth + x]
                + _fireBuffer[(y + 1) * bufferWidth + Math.Min(bufferWidth - 1, x + 1)]
                + _fireBuffer[Math.Min(bufferHeight - 1, y + 2) * bufferWidth + x];
        _fireBuffer[y * bufferWidth + x] = (byte)Math.Max(0, sum / 4 - 2);
    }
}

Starfield

private struct Star { public float X, Y, Z; }
private Star[] _stars;

// Update: Move stars toward viewer (decrease Z)
for (var i = 0; i < _stars.Length; i++)
{
    _stars[i].Z -= speed * deltaTime;
    if (_stars[i].Z <= 0)
    {
        _stars[i] = new Star
        {
            X = _random.NextSingle() * 2 - 1,
            Y = _random.NextSingle() * 2 - 1,
            Z = 1f
        };
    }
}

// Draw: Project 3D to 2D
foreach (var star in _stars)
{
    var screenX = centerX + star.X / star.Z * centerX;
    var screenY = centerY + star.Y / star.Z * centerY;
    var brightness = (byte)(255 * (1f - star.Z));
    var size = 3f * (1f - star.Z);

    ctx.Fill(new Rgba32(brightness, brightness, brightness),
        new EllipsePolygon(screenX, screenY, size));
}

Game Simulation Patterns

Entity Management

private readonly List<Enemy> _enemies = new();
private readonly List<Bullet> _bullets = new();

private void Update(float deltaTime)
{
    // Update backwards for safe removal
    for (var i = _enemies.Count - 1; i >= 0; i--)
    {
        var enemy = _enemies[i];
        enemy.X += enemy.Vx * deltaTime;

        if (enemy.X < 0 || enemy.X > _width)
        {
            _enemies.RemoveAt(i);
            continue;
        }

        _enemies[i] = enemy;
    }
}

Collision Detection

// Circle collision
var dx = obj1.X - obj2.X;
var dy = obj1.Y - obj2.Y;
var distance = MathF.Sqrt(dx * dx + dy * dy);
var colliding = distance < (obj1.Radius + obj2.Radius);

// Rectangle collision
var colliding = rect1.X < rect2.X + rect2.Width &&
                rect1.X + rect1.Width > rect2.X &&
                rect1.Y < rect2.Y + rect2.Height &&
                rect1.Y + rect1.Height > rect2.Y;

Screen Wrapping

_x = (_x + _width) % _width;
_y = (_y + _height) % _height;

Bouncing

if (_x < radius || _x > _width - radius) _vx = -_vx;
if (_y < radius || _y > _height - radius) _vy = -_vy;

_x = Math.Clamp(_x, radius, _width - radius);
_y = Math.Clamp(_y, radius, _height - radius);

Color Techniques

HSV to RGB

private static Rgba32 HsvToRgb(float h, float s, float v)
{
    var hi = (int)(h * 6) % 6;
    var f = h * 6 - (int)(h * 6);
    var p = v * (1 - s);
    var q = v * (1 - f * s);
    var t = v * (1 - (1 - f) * s);

    return hi switch
    {
        0 => new Rgba32((byte)(v * 255), (byte)(t * 255), (byte)(p * 255)),
        1 => new Rgba32((byte)(q * 255), (byte)(v * 255), (byte)(p * 255)),
        2 => new Rgba32((byte)(p * 255), (byte)(v * 255), (byte)(t * 255)),
        3 => new Rgba32((byte)(p * 255), (byte)(q * 255), (byte)(v * )),
         =>  Rgba32(()(t * ), ()(p * ), ()(v * )),
        _ =>  Rgba32(()(v * ), ()(p * ), ()(q * ))
    };
}

Fire Palette

private static Rgba32 GetFireColor(byte heat)
{
    return heat switch
    {
        < 64 => new Rgba32(heat * 4, 0, 0),           // Black to red
        < 128 => new Rgba32(255, (heat - 64) * 4, 0), // Red to yellow
        _ => new Rgba32(255, 255, (heat - 128) * 2)   // Yellow to white
    };
}

Color Cycling

var phase = value * MathF.PI * 2f + time * 0.5f;
var r = (MathF.Sin(phase) + 1f) / 2f;
var g = (MathF.Sin(phase + MathF.PI * 2f / 3f) + 1f) / 2f;
var b = (MathF.Sin(phase + MathF.PI * 4f / 3f) + 1f) / 2f;

Existing Screensavers Reference

Panel	Type	Key Techniques
starfield	3D effect	Z-depth projection, star structs
matrix-rain	Character animation	Column drops, character grid
bouncing-logo	Simple physics	Velocity, wall bouncing
mystify	Polygon animation	Trail history, connected vertices
plasma	Per-pixel	Multiple sine waves, moving centers
fire	Cellular automata	Heat buffer, upward propagation
game-of-life	Cellular automata	Neighbor counting, state buffer
bubbles	Particle system	List of bubbles, collision
rain	Particle system	Raindrops + splashes
spiral	Per-pixel	Polar coordinates, rotation
clock	Vector graphics	Angle calculation, line drawing
noise	Per-pixel	Random values, scan lines
warp-tunnel	Per-pixel	Distance from center, rings
pipes	3D simulation	Segment list, direction changes
asteroids	Game simulation	Ship AI, bullets, collision
pacman	Game simulation	Maze, ghost AI, pathfinding
mspacman-cutscene	Animation	Phased timeline, sprite drawing
missile-command	Game simulation	Trajectories, explosions, AI defense

---

Converted and distributed by TomeVault — claim your Tome and manage your conversions.