Dokumentacja Zbuduj pokaz świateł

Dokumentacja API środowisk

Wszystko, co pakiet środowiska może zadeklarować, otrzymać i zaimportować. To jest wersja 1 API środowisk.

To jest dokumentacja dla osób piszących środowisko pokazu świateł. Tworzenie środowiska prowadzi krok po kroku, a Jak działa pokaz świateł wyjaśnia, skąd biorą się dane.

W obrębie jednej wersji API rzeczy są tylko dodawane. Pakiet napisany dla wersji 1 działa w każdym Rainy, który obsługuje wersję 1.

Pakiet

Pakiet to plik .zip:

my-show.zip
  rainy-environment.json    the manifest
  index.js                  the entry module
  style.css                 optional
  preview.jpg               the picture people choose it by
  …                         your own modules, libraries, shaders, images, fonts

Manifest znajduje się w katalogu głównym pliku zip albo w jednym folderze najwyższego poziomu, czyli tak, jak wygląda pobrane repozytorium.

Ograniczenie
Rozmiar	20 MB po spakowaniu, 60 MB po rozpakowaniu, 500 plików.
Typy plików	`js` `mjs` `json` `css` `wasm`; obrazy `png` `jpg` `jpeg` `webp` `avif` `gif` `svg`; czcionki `woff2` `woff` `ttf` `otf`; shadery i tekst `glsl` `vert` `frag` `wgsl` `txt` `md`; dane `bin` `ktx2` `hdr`; multimedia `mp3` `ogg` `mp4` `webm`.
Pomijane	Ukryte pliki, `node_modules` oraz to, co dodają programy pakujące (`__MACOSX`, `.DS_Store`).
Odrzucane	Ścieżki bezwzględne, `..`, dowiązania, inne typy plików i wszystko, co przekracza ograniczenia.

Manifest

rainy-environment.json:

Pole
`manifest`	wymagane	Wersja formatu tego pliku: `1`.
`api`	wymagane	Wersja API środowisk, dla której napisano kod: `1`. Rainy odrzuca pakiet napisany dla wersji, której nie obsługuje.
`id`	wymagane	Od 2 do 32 znaków: małe litery, cyfry i łączniki, zaczynając od litery. Zainstalowanie pakietu o id już zainstalowanego zastępuje go. `classic` jest zajęte.
`name`	wymagane	Wyświetlane w Ustawieniach i w pokazie. Do 60 znaków.
`version`	wymagane	W postaci `1.2.3`.
`entry`	wymagane	Moduł do wczytania: plik `.js` lub `.mjs` z pakietu.
`description`		Jeden wiersz dla okna wyboru. Do 300 znaków.
`author`, `license`		Wyświetlane w Ustawieniach.
`homepage`		Adres `http` lub `https`.
`styles`		Do 8 arkuszy stylów, wczytywanych, gdy środowisko jest na scenie, i usuwanych, gdy z niej schodzi. Zobacz Stylowanie odtwarzacza.
`preview`	zalecane	Obrazek w Ustawieniach: obraz 16:9; 960 × 540 w zupełności wystarczy. Bez niego środowisko dostaje pustą planszę.
`layout`		`stage` (domyślnie) lub `immersive`. Zobacz Układy.
`requires`		Dowolne z `webgl`, `webgl2`, `webgpu`. Na urządzeniu bez któregoś z nich środowiska nie da się wybrać.
`i18n`		`name` i `description` dla kodu języka: `{ "es": { "description": "…" } }`.

Klasa środowiska

Domyślnym eksportem modułu wejściowego jest klasa. Rainy tworzy jedną instancję, gdy środowisko wchodzi na scenę. Wymagane są tylko cztery pierwsze metody.

Metoda	Kiedy
`mount(ctx)`	Raz, aby wszystko zbudować. Może zwrócić obietnicę.
`update(S)`	W każdej klatce, najpierw: odczytaj pokaz, uruchom efekty, przesuń tekst.
`render(S)`	W każdej klatce, potem: rysuj.
`unmount()`	Raz, aby zwolnić to, czego strona nie zwolni za Ciebie: konteksty WebGL, workery, timery.
`resize(cssW, cssH, { tier, lowPower, scale })`	W każdej klatce, przed `update`. Wyjdź od razu, gdy nic się nie zmieniło. Rysuj w rozmiarze `cssW × scale` na `cssH × scale`. `tier` to 0 (pełna jakość), 1 lub 2 (najlżejsza).
`setScore(score)`	Dotarła partytura utworu albo zniknęła (`null`).
`setTrack(track)`	`{ id, title, artist, cover }` utworu na scenie albo `null`. `cover` to adres obrazu albo `null`.
`onTrackChange()`	Zaczął się inny utwór.
`leave()`	Scenę przejmuje inne środowisko. Twoja warstwa już zanika.
`dropLyrics()`	Zdejmij teraz tekst ze sceny.

Gdy środowisko zawiedzie

Rainy zdejmuje środowisko ze sceny, usuwa wszystko, co dodało, i kontynuuje w Klasycznym, gdy:

update lub render zgłaszają wyjątek przez trzy klatki z rzędu,
dowolna inna metoda zgłasza wyjątek,
wczytanie i montowanie trwają dłużej niż dziesięć sekund albo
środowisko wywołuje ctx.fail(error).

Na tym urządzeniu pozostaje wyłączone do odświeżenia strony albo aktualizacji pakietu. Błąd jest zapisywany w konsoli przeglądarki.

`ctx`

To, co otrzymuje mount.


`ctx.root`	Twoja własna warstwa nad sceną: pusty element, który ją wypełnia. Tu trafiają płótna i DOM. Rainy płynnie pokazuje ją po `mount`, wygasza, gdy schodzisz ze sceny, i usuwa. Ignoruje wskaźnik, chyba że ustawisz `pointer-events` na czymś w jej wnętrzu.
`ctx.lyrics`	Oś czasu tekstu, przekazywana też w każdej klatce jako `S.lyrics`.
`ctx.asset(path)`	Adres pliku z Twojego pakietu. Względne importy i `url()` w arkuszach stylów też działają jak zwykle.
`ctx.ui.safeArea()`	`{ top, right, bottom, left }`, każde od 0 do 1: jaką część danej strony sceny zasłania teraz odtwarzacz.
`ctx.ui.addButton({ icon, title, onClick, pressed })`	Własny przycisk na pasku pokazu. `icon` to znaczniki SVG, 14 pikseli. Zwraca `{ el, setPressed(on), remove() }`.
`ctx.ui.toast(message)`	Krótkie powiadomienie.
`ctx.ui.fontFamily`	Czcionka interfejsu, do tekstu, który rysujesz samodzielnie.
`ctx.locale`	Język interfejsu: `en`, `ca`, `es` lub `pl`.
`ctx.id`, `ctx.manifest`	Twoje id i Twój manifest.
`ctx.api`	Wersja API tego Rainy.
`ctx.fail(error)`	Nie możesz kontynuować. Rainy wraca do Klasycznego.

`@rainy/lightshow`

Jedyny moduł Rainy, który importuje pakiet.

Eksport
`API_VERSION`	`1`.
`TAU`, `clamp(v, a, b)`, `lerp(a, b, t)`, `smooth(t)`	Matematyka. `smooth` to smoothstep od 0 do 1.
`hsl(h, s, l)`, `mixHue(a, b, t)`, `mixRgb(a, b, t)`, `toWhite(c, t)`	Kolor. Kolor to `[r, g, b]`, każda składowa od 0 do 255.
`rgba(c, alpha)`	Kolor jako ciąg znaków CSS.
`paletteFor({ accentHue, key, mode, label, genre, swap })`	Paleta sekcji, tak jak wylicza ją dyrygent. Przydaje się, gdy potrzebujesz kolorów sekcji, zanim zabrzmi.
`stepEase(beat)`, `altBeat(beat)`	Ruch zsynchronizowany z uderzeniem: wartość, która w każdym uderzeniu przesuwa się o krok z krótkim poślizgiem, oraz wartość, która kołysze się z boku na bok w co drugim uderzeniu.
`hash(n)`	Powtarzalna liczba pseudolosowa od 0 do 1.
`floorIndex(sortedArray, t)`	Indeks ostatniego elementu, który jest nie większy niż `t`, albo -1. Do tablic czasów w partyturze.
`LEAD`, `HOLD_MAX`, `REST_AFTER`, `HELD`	Czasy tekstu wspólne dla wszystkich środowisk, w sekundach.
`pickTransition(F, lineIndex, last)`	Które z sześciu przejść dostaje wers tekstu: `slam`, `fall`, `flicker`, `sweep`, `collapse` lub `lift`. Podąża za muzyką i nigdy nie powtarza się dwa razy z rzędu.
`MIN_FLASH_GAP`, `PHRASE_BARS`	Ograniczenia dyrygenta: sekundy między pełnymi błyskami oraz liczba taktów we frazie.

`S`: pokaz

Przekazywane do update i render w każdej klatce.


`S.F`	Klatka muzyczna. Zobacz niżej.
`S.t`	Czas utworu w sekundach, wygładzony i przesunięty o przesunięcie synchronizacji użytkownika.
`S.now`, `S.dt`	Zegar rzeczywisty i czas klatki, w sekundach. Do rzeczy, które nie są muzyką.
`S.running`	Utwór jest odtwarzany. Jednorazowe efekty uruchamiaj tylko wtedy.
`S.I`	Intensywność, od 0,3 do 1.
`S.pulse`	`{ k, s, h }`: obwiednie stopy, werbla i hi-hatu, od 0 do 1.
`S.phrase`	Która to ośmiotaktowa fraza sekcji, licząc od 0.
`S.palette`	`{ a, b, c, w, deep }`: kolor główny, drugi, trzeci, zabarwiona biel i tło.
`S.accentHue`	Odcień koloru akcentu użytkownika, od 0 do 360.
`S.dim`	Główny ściemniacz, od 0 do 1. Pomnóż przez niego swoje światło.
`S.flash(amount, color)`	Poproś o błysk, od 0 do 1. Ograniczone do trzech pełnych błysków na sekundę i złagodzone przy opcji Ogranicz błyski.
`S.blind(amount)`	Poproś o oślepiacz: wolniejszą falę bieli.
`S.burst(amount)`	Poproś o zryw: wzmocnienie, które wybrzmiewa przez około pół sekundy.
`S.flashAmt`, `S.flashColor`	Co narysować z błysków w tej klatce.
`S.blinderAmt`, `S.burstAmt`	Co narysować z oślepiacza i zrywu.
`S.prefs`	Ustawienia użytkownika: `reduceFlashing`, `disableLasers`, `showBgBlur`, `lowPower` (wartości logiczne) oraz `intensity` (`auto`, `chill`, `balanced` lub `hype`).
`S.lyrics`, `S.lyricsOn`	Oś czasu tekstu oraz to, czy tekst jest teraz na scenie.
`S.songId`	Id utworu na scenie.

`F`: muzyka

S.F, klatka muzyczna.

Z partyturą F.scripted ma wartość true i wszystko jest dokładne. Gdy utwór jest jeszcze analizowany, Rainy szacuje te same pola na podstawie dźwięku: nie ma patrzenia w przyszłość (nextIn i dropIn mają wartość Infinity), a section jest przypuszczeniem.


`F.t`	Czas utworu w sekundach.
`F.bands`	`{ sub, bass, mid, high, air, rms, harm }`, każde od 0 do 1: energia pasm, głośność i tonalność dźwięku.
`F.hits`	`{ k, s, h }`: siła stopy, werbla lub hi-hatu, które zabrzmiały w tej klatce; w przeciwnym razie 0.
`F.beat`, `F.bar`	Numery uderzenia i taktu, z ułamkami.
`F.beatPhase`, `F.barPhase`	Pozycja w uderzeniu i w takcie, od 0 do 1.
`F.beatInBar`	Od 0 do 3.
`F.period`	Sekundy na uderzenie.
`F.newBeat`, `F.newBar`	W tej klatce zaczęło się uderzenie lub takt.
`F.section`	`{ idx, label, t0, t1, key, mode, energy, density }`. `label` to `intro`, `verse`, `build`, `chorus`, `drop`, `breakdown` lub `outro`.
`F.sectionProgress`, `F.sectionBar`	Od 0 do 1 w obrębie sekcji oraz liczba taktów od jej początku.
`F.nextSection`, `F.nextIn`	Następna sekcja i liczba sekund do niej.
`F.dropIn`	Liczba sekund do następnego dropu.
`F.buildProgress`	Od 0 do 1 w obrębie narastania.
`F.stopDepth`, `F.stopIn`	Jak głęboko utwór jest w ciszy, od 0 do 1, oraz liczba sekund do następnej.
`F.events`	Co wydarzyło się w tej klatce: `{ type, t }`, gdzie `type` to `drop`, `impact`, `stop` lub `riser`.
`F.profile`	`{ genre, intensity }`. `genre` to `edm`, `pop`, `rock`, `hiphop`, `latin`, `chill` lub `orchestral`.
`F.tempoConf`	Pewność analizatora co do tempa, od 0 do 1.
`F.jumped`	Użytkownik przewinął utwór albo zmienił się utwór. Zmień stan od razu, bez płynnego przejścia.
`F.running`	Utwór jest odtwarzany.

Partytura

To, co otrzymuje setScore: cały utwór naraz.


`score.duration`	Sekundy.
`score.tempo`, `score.period`	Uderzenia na minutę oraz sekundy na uderzenie.
`score.beats`, `score.downbeats`	Czasy w sekundach, posortowane.
`score.onsets.k`, `.s`, `.h`	Stopy, werble i hi-haty: `{ t, s }`, dwie tablice tej samej długości z czasem i siłą.
`score.env`, `score.fps`	`score.env[band]` zawiera jeden bajt na klatkę, od 0 do 255, dla każdego pasma z `F.bands`, przy `score.fps` klatkach na sekundę.
`score.envAt(band, t)`	Wartość pasma w danej chwili, od 0 do 1.
`score.sections`, `score.sectionAt(t)`	Sekcje, jak `F.section`.
`score.events`, `score.nextEvent(type, t, horizon)`	Zdarzenia, jak `F.events`, oraz następne zdarzenie danego typu w ciągu `horizon` sekund.
`score.beatAt(t)`, `score.barAt(t)`	Numery uderzenia i taktu w danej chwili.
`score.stopDepth(t)`	Jak głęboko utwór jest w ciszy w danej chwili.
`score.profile`	Jak `F.profile`.

Tekst

S.lyrics, oś czasu tekstu. Warto ją czytać, gdy S.lyricsOn ma wartość prawda.


`lyrics.ready`	Utwór ma zsynchronizowany tekst.
`lyrics.lines`	`{ t0, t1, on, end, blank, words }`. Wers wchodzi na scenę w `on`, a jego ostatnie słowo kończy się w `end`. `blank` oznacza wers instrumentalny.
`words`	`{ text, s, e }`: słowo oraz jego początek i koniec.
`lyrics.adlibs`	Chórki, oddzielone od wersów: `{ s, e, k, words }`. `k` to kolejny numer, przydatny do naprzemiennego rozmieszczania po bokach.
`lyrics.aligned`	Czasy słów są dokładne. W przeciwnym razie są szacowane na podstawie długości wersu.
`lyrics.lineIndex(t)`	Wers na scenie w danej chwili albo -1.
`lyrics.resting(t, index)`	Nikt nie śpiewa teraz tego wersu.
`lyrics.breakAt(t, index)`	`{ a, b }`, gdy trwa przerwa instrumentalna; w przeciwnym razie `null`.
`lyrics.version`	Zmienia się za każdym razem, gdy wersy są zastępowane: nowy utwór albo nadejście dokładnych czasów.

Układy

layout w manifeście określa, jak odtwarzacz jest ułożony wokół Twojej warstwy.


`stage`	Odtwarzacz bez zmian, z okładką, elementami sterującymi i kolejką. Pokaz działa za nimi.
`immersive`	Pokaz jest całym obrazem. Kolejka się chowa, a przycisk na pasku przywraca ją nad pokazem, utwór i jego elementy sterujące stają się małą kartą na dole, a wszystko przygasa, gdy wskaźnik pozostaje w bezruchu.

Stylowanie odtwarzacza

Środowisko zmienia wygląd odtwarzacza pełnoekranowego arkuszami stylów wymienionymi w styles. Rainy wczytuje je, gdy środowisko wchodzi na scenę, i usuwa, gdy z niej schodzi.

Gdy Twoje środowisko jest na scenie, odtwarzacz ma klasę ls-env-<id>. Zaczynaj od niej każdą regułę:

#fullscreen-player.ls-env-my-show .fs-progress-fill {
    background-color: rgb(var(--ls-a));
}

Klasy stanu

Na #fullscreen-player:

Klasa
`lightshow-on`	Pokaz trwa.
`ls-env-<id>`	To środowisko jest na scenie.
`ls-immersive`	Układ jest immersyjny.
`ls-idle`	Tylko w układzie immersyjnym: wskaźnik jest w bezruchu, a odtwarzacz jest przygaszony.
`ls-queue-peek`	Tylko w układzie immersyjnym: użytkownik otworzył kolejkę nad pokazem.
`ls-lowpower`	Tryb niskiej wydajności jest włączony. Zrezygnuj z filtrów i cieni.
`mode-modern`, `mode-standard`	Tryb pełnoekranowy wybrany przez użytkownika. Nowoczesny ma własne elementy sterujące. Standardowy zostawia na dole pasek odtwarzacza aplikacji, więc `.fs-player-controls` i przycisk głośności są ukryte.
`layout-swapped`	Okładka jest po lewej, a kolejka po prawej, czyli domyślnie. Bez tej klasy są odwrotnie.

Części

Selektor
`.fs-backdrop`	Rozmyta okładka albumu za wszystkim.
`.ls-env-root`	Twoja warstwa.
`.fs-brand`	Znak Rainy, u góry po lewej.
`#fs-volume-btn`, `#fs-lightshow-btn`, `#fs-close-btn`	Przyciski u góry.
`.ls-hud`, `.ls-hud-btn`	Pasek pokazu, z tempem i gatunkiem, oraz jego przyciski, łącznie z Twoimi.
`.fs-content`	Kontener, który mieści utwór i kolejkę.
`.fs-current-info`	Utwór: okładka, tytuł, wykonawca i elementy sterujące. W układzie immersyjnym jest to karta.
`.fs-artwork-container`	Okładka albumu.
`.fs-title`, `.fs-artist`	Tytuł i wykonawca utworu.
`.fs-player-controls`	Pasek postępu i przyciski.
`.fs-progress-container`, `.fs-progress-bar`, `.fs-progress-fill`, `.fs-time`	Pasek postępu, jego wypełniona część i oba czasy.
`.fs-buttons`, `.fs-control-btn`, `.fs-control-btn.play-pause`	Przyciski odtwarzania.
`.fs-queue-container`	Panel z kolejką i tekstem.

Wszystko, czego nie ma w tej tabeli, jest wewnętrzne i może się zmienić bez uprzedzenia.

Zmienne

Zmienna
`--ls-a`, `--ls-b`, `--ls-c`	Kolor główny, drugi i trzeci sekcji, która właśnie gra, każdy jako `r g b`. Te same kolory co w `S.palette`.
`--ls-w`	Zabarwiona biel, jako `r g b`.
`--ls-deep`	Ciemny kolor tła, jako `r g b`.
`--accent-primary`	Kolor akcentu użytkownika.
`--text-primary`, `--text-secondary`, `--text-tertiary`	Kolory tekstu Rainy.
`--bg-primary`, `--bg-secondary`, `--bg-tertiary`, `--bg-elevated`	Kolory powierzchni Rainy.
`--border-subtle`	Kolor obramowania Rainy.
`--radius-sm`, `--radius-md`, `--radius-lg`, `--radius-full`	Promienie narożników.
`--spacing-xs`, `--spacing-sm`, `--spacing-md`, `--spacing-lg`, `--spacing-xl`	Stopnie odstępów.
`--font-family`	Czcionka interfejsu.

Zmiennej palety używaj jako rgb(var(--ls-a)) albo, z przezroczystością, rgb(var(--ls-a) / 0.5). Zmienne palety istnieją, gdy pokaz trwa, i płynnie przechodzą od kolorów jednej sekcji do kolorów następnej.

Ograniczenia

Ogranicz się do odtwarzacza pełnoekranowego. Twoje reguły nie powinny pasować do niczego poza #fullscreen-player.ls-env-<id>.
Nie ukrywaj ani nie zasłaniaj #fs-close-btn ani #fs-lightshow-btn i zadbaj, żeby elementy sterujące odtwarzaniem dało się obsługiwać.
CSS dostaje paletę, a nie rytm. Wszystko, co porusza się z muzyką, rysuj w swojej warstwie.

Narzędzia


`RAINY_DEV=1 RAINY_ENVIRONMENTS_DEV=<folder>`	Serwuje niespakowane pakiety z folderu, bez pamięci podręcznej. Każdy jest widoczny jako środowisko z etykietą Wersja robocza i zastępuje zainstalowany pakiet o tym samym id.
`python scripts/pack_environment.py <folder> [-o <wyjście>]`	Sprawdza folder tak, jak serwer sprawdza przesłany plik, i zapisuje `<id>-<version>.zip`, domyślnie w `dist`. Te same pliki zawsze dają ten sam plik zip.
`node --import ./tests/js/sdk-hook.mjs --test <pliki>`	Uruchamia własne testy pakietu w Node, z `@rainy/lightshow` rozwiązywanym tak jak w przeglądarce.