Added part of docs

docs/pl/reference/SOUND.md

@@ -0,0 +1,150 @@
+# SOUND
+
+Krótki efekt dźwiękowy wczytywany z pliku `.WAV`. Obsługuje sterowanie odtwarzaniem oraz zmianę próbkowania, co pozwala dynamicznie zmieniać wysokość i prędkość odtwarzanego dźwięku.
+
+## Pola
+
+### FILENAME
+
+```
+STRING FILENAME
+```
+
+Nazwa pliku `.WAV` z dźwiękiem. Jeżeli ścieżka nie zaczyna się od `$`, silnik dokleja prefiks `$WAVS\`. Pole odczytywane podczas inicjalizacji zmiennej; może być również ustawione w trakcie działania metodą [`LOAD`](#load).
+
+### PRELOAD
+
+```
+BOOL PRELOAD
+```
+
+Określa, czy dane dźwięku mają być załadowane od razu przy inicjalizacji, czy dopiero przed pierwszym odtworzeniem.
+
+## Metody
+
+### ISPLAYING
+
+```
+BOOL ISPLAYING()
+```
+
+Sprawdza, czy dźwięk jest aktualnie odtwarzany.
+
+**Zwraca**: [`BOOL`](BOOL.md) — `TRUE`, jeżeli dźwięk jest odtwarzany.
+
+**Przykłady**
+
+```
+SNDATGOAL^ISPLAYING();
+SNDREX0^ISPLAYING();
+```
+
+### LOAD
+
+```
+void LOAD(STRING path)
+```
+
+Wczytuje plik dźwiękowy do zmiennej, zastępując dotychczas załadowany dźwięk. Bieżące odtwarzanie zostaje zatrzymane. Jeżeli ścieżka nie zaczyna się od `$`, dodawany jest prefiks `$WAVS\`.
+
+**Parametry**
+
+- `path` — ścieżka pliku `.WAV` w VFS gry.
+
+**Przykłady**
+
+```
+SNDATGOAL^LOAD(VARSTEMP0);
+SNDWAV^LOAD("$WAVS\NAR_I000.WAV");
+SNDANSWER^LOAD(ARRSEQ^GET(0));
+```
+
+### PAUSE
+
+```
+void PAUSE()
+```
+
+Pauzuje odtwarzanie dźwięku.
+
+**Przykłady**
+
+```
+SND_SHIP_GAZ2^PAUSE();
+```
+
+### PLAY
+
+```
+void PLAY()
+```
+
+Rozpoczyna odtwarzanie dźwięku. Po starcie emitowany jest sygnał [`ONSTARTED`](#onstarted); po zakończeniu odtwarzania — [`ONFINISHED`](#onfinished). Jeżeli dźwięk już gra, jest najpierw zatrzymywany i odtwarzany od początku.
+
+**Przykłady**
+
+```
+SNDTAKE^PLAY();
+SNDATGOAL^PLAY();
+```
+
+### RESUME
+
+```
+void RESUME()
+```
+
+Wznawia odtwarzanie zatrzymane wcześniej przez [`PAUSE`](#pause).
+
+**Przykłady**
+
+```
+SND_SHIP_GAZ2^RESUME();
+```
+
+### SETFREQ
+
+```
+void SETFREQ(INTEGER sampleRate)
+```
+
+Ustawia bieżące próbkowanie odtwarzanego dźwięku (w hercach). Wartość różna od próbkowania oryginalnego pliku zmienia wysokość i prędkość odtwarzania proporcjonalnie do stosunku obu wartości. Próbkowanie pliku oryginalnego silnik traktuje domyślnie jako `22050` Hz.
+
+**Parametry**
+
+- `sampleRate` — docelowe próbkowanie w Hz.
+
+**Przykłady**
+
+```
+SNDENGINE0^SETFREQ(10025);
+```
+
+### STOP
+
+```
+void STOP([BOOL emitSignal])
+```
+
+Zatrzymuje odtwarzanie dźwięku.
+
+**Parametry**
+
+- `emitSignal` — (opcjonalnie) jeżeli `FALSE`, sygnał [`ONFINISHED`](#onfinished) nie zostanie wyemitowany. Domyślnie sygnał jest emitowany.
+
+**Przykłady**
+
+```
+SNDATGOAL^STOP(FALSE);
+SNDIDLEREX^STOP();
+```
+
+## Sygnały
+
+### ONSTARTED
+
+Wywoływany po rozpoczęciu odtwarzania dźwięku przez metodę [`PLAY`](#play).
+
+### ONFINISHED
+
+Wywoływany po zakończeniu odtwarzania (naturalnym lub przez metodę [`STOP`](#stop) bez argumentu `FALSE`).