README

Lux is the ScrapyardIO LED visualization library. It ships 36 animations that drive any LEDShape (via the NeoPixel actuator) through a registry and the Visualization magic alias.

Requirements

PHP 8.4+
scrapyard-io/framework / fabricate/* 0.6.x
scrapyard-io/waveforms 0.6.x

Installation

In the ScrapyardIO monorepo skeleton, require the path package:

composer require scrapyard-io/lux:^0.6.0
php workshop package:discover

Publish the config if you want to toggle entries:

php workshop vendor:publish --provider="ScrapyardIO\Lux\LuxServiceProvider"

Quick start

use ScrapyardIO\Waveforms\Light\NeoPixel;

$neopixel = NeoPixel::circuit('w281x-strip');

// Blocking — paced at the visualization's target FPS (default 40)
Visualization::play('fire', $neopixel);

// Cooperative — for use inside a Sketch loop()
$player = Visualization::open('rainbow-cycle', $neopixel);

public function loop(): SketchLoopResult
{
    return $player->tick();
}

Interactive visualizations take additional inputs after the NeoPixel:

Visualization::play('vu-meter', $neopixel, $potentiometer);
Visualization::play('gamepad-paint', $neopixel, $gameController);

API

Method	Behavior
`Visualization::play($name, $neopixel, ...$inputs)`	Blocking paced loop with SIGINT/SIGTERM shutdown
`Visualization::open($name, $neopixel, ...$inputs)`	Returns a `VisualizationPlayer` for one-frame `tick()`
`Visualization::listVisualizations()`	`name => class-string` map
`Visualization::addVisualization($name, $class)`	Register a custom visualization
`Visualization::hasVisualization($name)`	Existence check

Create your own with Workshop:

php workshop make:visualization MyEffect

Visualizations

Default target FPS is 40 unless noted. All run on any LEDShape. Entries marked 2D take a richer path when handed an LEDGrid.

Ambient

Name	Appearance	Inputs
`solid`	Solid fill	—
`gradient`	Static palette gradient	—
`rainbow`	Full-spectrum spread	—
`rainbow-cycle`	Cycling rainbow	—
`color-waves`	Soft palette waves	—
`breathe`	Whole-strip breathe pulse	—
`plasma`	Plasma field	— (2D)

Motion

Name	Appearance	Inputs
`color-wipe`	Wipe on / wipe off	—
`theater-chase`	Every-third-pixel chase	—
`theater-chase-rainbow`	Rainbow theater chase	—
`running-lights`	Soft sine running lights	—
`comet`	Head + fading trail	—
`larson-scanner`	Cylon / Knight Rider bounce	—
`bounce`	Multiple bouncing dots	—
`meteor-rain`	Meteor streaks	—
`sinelon`	Weaving trail dot	—
`juggle`	Multi-dot weave	—

Sparkle

Name	Appearance	Inputs
`twinkle`	Random stars	—
`twinkle-fade`	Fading twinkles	—
`sparkle`	Single sparkle on base	—
`glitter`	Rainbow + white speckles	—
`confetti`	Colored fading speckles	—
`ripple`	Expanding ripple rings	—

Natural

Name	Appearance	Inputs
`fire`	Rising fire (Fire2012-style)	—
`lava`	Molten noise	—
`candle`	Warm flicker	—
`pacifica`	Layered ocean	—
`noise`	Evolving noise field	— (2D)
`rain`	Falling rain	— (2D)

Utility

Name	Appearance	Inputs
`strobe`	Hard flash	—
`police`	Red/blue flashers	—
`heartbeat`	Double-pulse throb	—
`bpm`	Musical BPM stripes	—

Interactive

Name	Appearance	Required inputs
`vu-meter`	Level bar	`Potentiometer`
`slider-track`	Thumb highlight	`Potentiometer`
`gamepad-paint`	Stick painting	`GameController` (2D)

Configuration

config/lux.php maps kebab-case names to classes with an enabled flag. Disabled entries are not registered at boot.

License

MIT. See LICENSE and ATTRIBUTION.md.

scrapyard-io / lux

Maintainers

Package info

Statistics

Security