Randoloot/documentation.txt

SYSTEM PRZEDMIOTÓW I LOOTU

Przedmioty: Weapon, Shield, Hull, Generator, Extension. Baza typów znajduje się
w resources/items, generator w scripts/items/item_generator.gd.
Poziom przedmiotu = GameState.system_level (1–1000; aktualny poziom układu).
Cecha główna modułów i regeneracja generatora: baza * (1 + 0.05 * (L - 1)) * losowe 0.8–1.2.
Definicje bazowe pozostają wspólne i nie są zmieniane; wylosowane wartości zapisuje
ItemInstance. Każdy drop ma 1–5 różnych addonów z bazy zasobów affix_database.tres.
Liczba addonów zwykłego dropu: 1=50%, 2=25%, 3=14%, 4=8%, 5=3%.
Elite dostaje jeden addon więcej (maks. 5), Boss co najmniej 4.
Rzadkość wg liczby addonów: zwykły, niepospolity, rzadki, epicki, legendarny.
Zakresy addonów interpolują liniowo między poziomem 1 a 1000 wg concept_game.txt.
Cap dotyczy pojedynczego addonu; bonusy zamontowanych przedmiotów sumują się.

Po zniszczeniu wroga: Normal 65%, Elite 90%, Boss 100% szansy na jeden przedmiot.
Typ wroga ustawia loot_tier; generator układu dobiera skład zależnie od poziomu.
Drop pozostaje na mapie, przyciąga się z 150 px i zbiera do wolnego slotu z 48 px.
Pełna ładownia: drop czeka i pokazuje komunikat. Zniszczony gracz nie zbiera lootu.
Niezebrany loot znika przy restarcie poziomu. Zebrane przedmioty zachowują wszystkie
wylosowane wartości, addony, poziomy i rozmieszczenie po śmierci gracza.

Addony działają wyłącznie w zamontowanej broni/modułach. Procenty kadłuba, tarcz
i prędkości mnożą bazę powiększoną o bonusy płaskie. Bonus obrażeń działa na obie
bronie (także laser i rakiety). Regeneracja dodaje punkty na sekundę.
EXP i kredyty mają obliczone mnożniki statku i zwiększają nagrody kapitana
za zniszczonego wroga. Bonusy działają wyłącznie po zamontowaniu przedmiotu.

UI: kolor przedmiotu wskazuje rzadkość. Najechanie na slot pokazuje pełne parametry,
poziom, rzadkość, addony i parametry broni. Przenoszenie nadal odbywa się drag/drop.
Małe × w zajętym slocie magazynu usuwa przedmiot natychmiast, bez przesuwania
pozostałych slotów. Przedmioty zamontowane nie mają przycisku usuwania.

EDYCJA BAZY CECH (ADDONÓW)

Katalog bazy: resources/items/affix_database.tres.
Definicje poszczególnych cech: resources/items/affixes/*.tres.
Klasa pól i reguł: scripts/items/item_affix_definition.gd.
Losowanie ważone i kontrola zgodności: scripts/items/item_affix_database.gd.

W Godocie wybierz plik cechy .tres w FileSystem i edytuj go w Inspectorze:
- affix_id: unikalny identyfikator cechy.
- display_name, description, unit: nazwa, opis, jednostka.
- stat_key: identyfikator efektu obsługiwanego przez statek/bronie.
- enabled: włącza lub wyłącza przyszłe losowanie cechy.
- selection_weight: względna waga losowania (2 = dwa razy większa waga niż 1).
  Waga 0 wyłącza losowanie; procent szansy zależy od pozostałej dozwolonej puli.
- category_mask: zaznacz dozwolone Weapon, Shield, Hull, Generator, Extension.
  Obecnie zaznaczone są wszystkie kategorie, zgodnie z wcześniejszą pulą ogólną.
- allowed_item_ids: pusta lista dopuszcza wszystkie itemy dozwolonych kategorii;
  wpisana lista dopuszcza tylko podane item_id z bazowych resources/items/*.tres.
- excluded_item_ids: zawsze wyklucza wskazane itemy.
- minimum_level / maximum_level: poziomy, na których cecha może się pojawić.
- minimum/maximum_value_level_1 i level_1000: zakresy dla poziomów krańcowych;
  między nimi generator interpoluje liniowo. Dla stałej wartości ustaw wszystkie
  cztery pola identycznie.
- exclusive_group: puste = bez ograniczenia. Cechy o tej samej niepustej grupie
  nie mogą pojawić się razem na jednym przedmiocie.
- incompatible_affix_ids: lista cech wykluczonych na tym samym przedmiocie.
  Wystarczy wpisać wykluczenie po jednej stronie. Ta sama cecha nie powtarza się.

Aby dodać cechę: utwórz zasób ItemAffixDefinition, zapisz w affixes i dodaj do
tablicy affixes w affix_database.tres. Sama obecność pliku w katalogu nie dodaje
go do losowania. Aktualne dziesięć cech ma wagę 1 i nie ma wzajemnych wykluczeń.
Nowy stat_key wymaga również implementacji efektu w kodzie; baza opisuje reguły
losowania i prezentację, nie tworzy automatycznie nowych mechanik statku.
Tooltip pobiera nazwę i jednostkę z definicji cechy. Wylosowana wartość pozostaje
w ItemStatModifier; zmiana zakresów w bazie nie przelicza zdobytych przedmiotów.
Przy zbyt małej puli zgodnych cech generator kończy losowanie wcześniej, bez
duplikatów i bez pętli nieskończonej. Rzadkość wynika z faktycznej liczby addonów.
Pusta dozwolona pula daje przedmiot bez addonów o rzadkości zwykłej.

ZAKRES OBRAŻEŃ BRONI

Każda nowa broń ma zapisane w ItemInstance damage_min / damage_max. Generator
losuje dolną granicę oraz szerokość zakresu. Obie granice skaluje przez
(1 + 0.05 * (L - 1)) i zaokrągla do całkowitych punktów obrażeń.
Wartości dla poziomu 1 edytuje się w zasobach poszczególnych broni .tres:
damage_lower_roll_min/max = zakres losowania dolnej granicy;
damage_spread_roll_min/max = zakres losowania szerokości (górna = dolna + szerokość).
Laser: dolna 1–4, szerokość 2–4 (możliwe m.in. 1–5 i 4–6).
Plazma: dolna 10–14, szerokość 2–4.
Działko maszynowe: dolna 2–4, szerokość 1–2.
Rakiety: dolna 45–58, szerokość 5–12.

Każdy wystrzelony pocisk i każdy trafiający impuls lasera losują obrażenia
równomiernie z zakresu swojej broni, włącznie z obiema granicami.
Po losowaniu naliczany jest mnożnik damage_percent z całego wyposażenia.
Jedna rakieta ma jeden wynik losowania, wspólny dla trafienia i jej eksplozji.
Tooltip i etykieta slotu pokazują bazowy zakres broni; bonus procentowy statku
jest naliczany w walce. Zakres dropu zachowuje się po restarcie poziomu.
Bronie startowe mają zakres z wartości środkowych ustawień w definicji.
Starszy item z primary_value_override i bez zakresu zachowuje stałe obrażenia.

UKŁADY I PRZECHODZENIE POZIOMÓW

Generator: scripts/levels/system_generator.gd. Balans: scripts/levels/level_balance.gd.
Nowa gra zaczyna się na poziomie 1. Poziom widoczny jest wyłącznie w debug HUD.
Każdy układ ma gwiazdę w (0,0) i 1–5 planet w odległości ok. 960–1480 px.
Tekstury są losowane z assets/stars/s1–s8 i assets/planets/p1–p18.
Dokładnie jedna planeta ma chronioną rasę, oznaczoną podpisem i kolorową obwódką.
Znacznik na HUD wskazuje kierunek do tej planety, kiedy jest poza obszarem widoku.
Numer układu, liczba planet, cel, odległość i kierunek są podane w oknie debug.
Stare dekoracyjne planety, boja nawigacyjna i cel testowy zniknęły z poziomu gry.

Gracz zaczyna w (180,200), obok centralnej gwiazdy. Przy generowaniu wrogowie nie
pojawiają się w promieniu 1200 px od gwiazdy ani bliżej niż 940 px od gracza.
Jest to bezpieczny obszar startowy; aktywowany podczas walki wróg może tam dolecieć.
Wrogowie powstają w skupiskach 2–5 przy planetach, z zachowaniem granic mapy,
odległości od planet i minimum 110 px między jednostkami. Boss ma dwie elitarne
jednostki w swoim skupisku. Końcowe skupisko może być mniejsze.
Liczba wrogów interpoluje między punktami koncepcji:
1=5, 10=10, 50=18, 100=23, 250=29, 500=34, 1000=40.
Poziomy 1–10: wyłącznie zwykli. Udziały Elite/Boss interpolują od 50:15%/0%,
100:25%/5%, 500:45%/10% do 1000:55%/15%. Wyniki są zaokrąglane; od 100
jest co najmniej jeden Boss, a liczba Elite gwarantuje dwie obstawy na Bossa.
Kadłub i obrażenia wrogów skalują się jak loot: 1 + 0.05 * (L - 1).
Elite: x2 kadłub, x1.3 obrażenia; Boss: x6 kadłub, x1.7 obrażenia i Mega_boss.png.
Prędkość: 62 * (1 + 0.0005 * (L - 1)); cooldown: max(0.55, 1.5/(1+0.001*(L-1))).

Po pokonaniu wszystkich wrogów chroniona planeta otwiera usługi. Przy podlocie
na odległość radius_planety + 180 px menu pojawia się automatycznie. Na razie
zawiera miejsce na usługi, przycisk następnego układu i powrotu do statku.
Podczas wizyty statek stoi, nie strzela i nie przyjmuje obrażeń. Zamknięcie menu
nie otwiera go ponownie, dopóki gracz nie opuści zasięgu i nie podleci ponownie.
Następny układ: poziom +1, nowy seed, nowe planety i wrogowie, zachowany ekwipunek,
poziomy itemów, addony i konfiguracja. Kadłub, tarcze i energia są uzupełnione.
Nowe dropy korzystają z nowego poziomu; wcześniej zdobyte nie zmieniają statystyk.
Po śmierci poziom i seed pozostają te same: układ odtwarza planety i pełny skład
wrogów. Niezebrany loot znika; zebrane itemy pozostają. Maksymalny poziom to 1000;
na nim menu usług działa, ale przycisk następnego poziomu jest zablokowany.

KAPITAN, XP, KREDYTY I NAUKA

Stan kapitana: GameState.captain (CaptainProgress), zachowany przy śmierci
i zmianie układu. Nowa gra zeruje postać: poziom 1, XP 0, kredyty 0, punkty nauki 0,
wszystkie umiejętności 0. Balans: scripts/captain/captain_balance.gd.
Awans wymaga 100 + 50 * (poziom_kapitana - 1) XP. Nadwyżka przechodzi dalej,
jedna nagroda może dać kilka awansów. Każdy awans daje 1 punkt nauki.
Plus w panelu kapitana kupuje 1 poziom wybranej umiejętności za 1 punkt nauki.
Umiejętności mają limit 100; nie da się wydać punktów, których postać nie ma.

Nagroda za wroga (XP / kredyty): Normal 20/15, Elite 50/40, Boss 150/120.
Nagrody mnożą się przez 1 + 0.05 * (poziom_układu - 1) oraz odpowiedni mnożnik
EXP/kredytów wyposażenia i są zaokrąglane do całkowitych punktów.
Wróg wypłaca nagrodę dokładnie raz przy zniszczeniu, niezależnie od dropu itemu.
XP i kredyty są przyznawane bez konieczności podlatywania do wraku.

Każdy poziom umiejętności:
- Pilotaż: +1 punkt procentowy szansy na unik. Unik anuluje 100% danego trafienia,
  nie zabiera tarcz ani kadłuba i pokazuje napis UNIK.
- Strzelec: +1% obrażeń. Mnożnik kapitana mnoży się z mnożnikiem wyposażenia.
- Mechanik: -1% otrzymywanych obrażeń, po próbie uniku, przed tarczami i kadłubem.
- Celne oko: +1 punkt procentowy szansy na krytyk.
Pilotaż 100 = 100% uniku, Mechanik 100 = 100% redukcji. Obrażenia nigdy nie leczą.

TRAFIENIA KRYTYCZNE

Bazowa szansa: 0%. Szansa = Celne oko + suma critical_chance_percent z wyposażenia,
ograniczona do 100%. Bazowe obrażenia krytyczne: x2. Mnożnik krytyka wynosi
2 * (1 + suma critical_damage_percent / 100), więc addon +20% daje x2.4.
Losowanie odbywa się raz dla pocisku lub trafiającego impulsu lasera. Rakieta
ma ten sam wynik obrażeń i krytyka dla całej eksplozji; ten sam cel nie dostaje
obrażeń dwa razy. Trafienie krytyczne pokazuje wyróżniony napis KRYT!.
Dwa nowe zasoby w resources/items/affixes, edytowalne jak pozostałe:
critical_chance_percent: 1–2% na poziomie 1, 10–20% na poziomie 1000.
critical_damage_percent: 5–10% na poziomie 1, 50–100% na poziomie 1000.
Obecnie dozwolone na wszystkich kategoriach; można zmienić maskę w Inspectorze.

INTERFEJS

Kompaktowy panel kapitana znajduje się nad wyposażeniem statku po prawej stronie:
poziom postaci, XP i pasek postępu, kredyty, punkty nauki, cztery umiejętności
z plusami, łączna szansa i mnożnik krytyka. Numer układu nadal jest tylko w debug.
Panel statku ma mniejszy schemat i sloty. Magazyn ma 5 kolumn i 4 wiersze,
przyciski kasowania, drag/drop i pełne podpowiedzi statystyk zachowują działanie.

AKTYWNE ROZSZERZENIA I CZĘŚCI

Nowa kategoria ItemDefinition.Category.ACTIVE_EXTENSION (5), odrębna od starszych
pasywnych rozszerzeń (4). Aktywne rozszerzenie zajmuje jeden z sześciu slotów modułów.
Numer slotu przypisuje klawisz 1–6; przeniesienie modułu zmienia przypisanie.
Na dole ekranu pojawia się przycisk z nazwą i klawiszem. Nieaktywny przycisk ma
w podpowiedzi przyczynę (energia, pełne tarcze/kadłub, brak części). Można też kliknąć.
Dopalacz, Ładowanie tarcz i Drony naprawcze są w startowym magazynie i puli łupów.
Dodatkowe statystyki losują się jak na pozostałych modułach; siła aktywnej umiejętności
jest ustalona przez jej zasób i nie skaluje się automatycznie z poziomem itemu.

Dopalacz: wymaga pełnej energii i zużywa całą aktualną maksymalną energię.
Rozpędza w kierunku przodu statku do 300% maksymalnej prędkości (+200%) w 0.3 s.
Nadmiar prędkości potem maleje ze zwykłym space_drag. Hamulec nadal działa.
Nie można ponownie odpalić podczas trwania dopalacza.
Ładowanie tarcz: wymaga pełnej energii, zużywa ją i dodaje 100 pkt tarcz do maksimum.
Drony naprawcze: bez kosztu energii, natychmiast naprawiają maksymalnie możliwy kadłub,
wydając 1 część za 1 pkt. Części mogą mieć ułamkową wartość, ponieważ kadłub także ją ma.
Pełne tarcze/kadłub lub brak zasobów blokują użycie bez wydawania kosztu.
Umiejętności są zablokowane podczas dokowania i po zniszczeniu statku.

Kliknięcie × przy przedmiocie w magazynie rozkłada go na 10 części. Pusty slot
nie daje części. Licznik jest w panelu kapitana i nagłówku magazynu. Części są
w CaptainProgress i pozostają przy restarcie oraz zmianie układu; nowa gra je zeruje.

DODAWANIE NASTĘPNEJ UMIEJĘTNOŚCI

1. Utwórz skrypt extends ActiveAbility w scripts/abilities. Zaimplementuj
   unavailable_reason(ship): String (pusty tekst oznacza gotowość) oraz activate(ship).
   Eksportowane parametry służą do regulowania działania w Inspectorze.
   Zasób opisuje działanie; stan czasowy efektu trzymaj na statku, nie na współdzielonym zasobie.
2. Skopiuj np. resources/items/shield_charge.tres. W sub_resource Ability ustaw skrypt,
   display_name, description i jego parametry. W ItemDefinition ustaw unikalne item_id,
   nazwę, category = 5 i active_ability wskazujące ten zasób.
3. Dopisz preload nowego .tres do DEFINITIONS w scripts/items/item_generator.gd,
   aby losował się z wrogów. Opcjonalnie dodaj ścieżkę do starter_items
   w scripts/items/ship_inventory.gd, aby od razu był dostępny w nowej grze.
4. Załóż go w dowolnym slocie modułu. Pasek, klawisz i blokady zasobów działają
   automatycznie — nie trzeba dopisywać wyjątków w HUD ani obsłudze klawiatury.

Maska addonów ma teraz sześć kategorii. 63 oznacza wszystkie, 32 tylko aktywne rozszerzenia.
Test integracyjny: tests/abilities/active_abilities_test.tscn.

MIKSER DŹWIĘKÓW BRONI

Układ: res://default_bus_layout.tres (ustawiony jako domyślny w projekcie).
Panel Audio Godota: Plasma, MachineGun, Laser, Missile — każda szyna ma osobny
suwak głośności i własny AudioEffectEQ10. Kliknij efekt, aby edytować pasma equalizera
w Inspectorze. Domyślnie pasma są neutralne (0 dB), szyny mają -6 dB i wysyłają do Master.
WeaponAudio.BUS_NAMES przypisuje rodzaj broni do szyny. Głośność gracza na odtwarzaczu
wynosi 0 dB, plazma wrogów -4 dB względem szyny. Zmiana szyny Plasma obejmuje oba źródła.
Muzyka i inne dźwięki nie przechodzą przez szyny broni.