Skip to content

Commit 094e7bc

Browse files
WieszczY85WieszczY85
committed
docs: add Alpha-02 flag implementation status
1 parent c4ce7dc commit 094e7bc

1 file changed

Lines changed: 260 additions & 0 deletions

File tree

‎docs/alpha-02-flagi-status.md‎

Lines changed: 260 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,260 @@
1+
# PlotsX — Alpha-02: status dodatkowych flag i zabezpieczeń
2+
3+
> Stan repozytorium zweryfikowany na gałęzi `main`, commit `c4ce7dc246f0a3693b6504e269ba17a74289ef79`.
4+
>
5+
> Dokument opisuje nie tylko obecność wpisu w `PlotFlagRegistry`, ale również faktyczną obsługę zdarzeń w `PlotProtectionListener`, obecność w GUI i zgodność z pierwotnym założeniem Alpha-02.
6+
7+
## Legenda
8+
9+
- ✅ — zaimplementowane i faktycznie obsługiwane,
10+
- 🟡 — funkcjonalność istnieje, ale pod inną nazwą, wspólną flagą lub nie obejmuje jeszcze całego planowanego zakresu,
11+
- ❌ — brak implementacji,
12+
- ➖ — pomysł świadomie zastąpiony innym rozwiązaniem / osobna flaga nie jest obecnie potrzebna.
13+
14+
---
15+
16+
# Zbiór pomysłów: Alpha-02
17+
18+
## Dodatkowe flagi i zabezpieczenia
19+
20+
### Zabezpieczenie przed kradzieżą zwierząt
21+
22+
- ✅ ~~Flaga `animal-leash` — blokująca przywiązywanie zwierząt do liny~~
23+
- Nie istnieje jako osobna flaga.
24+
- Funkcjonalność została połączona we wspólną flagę `animal-interact`.
25+
- Obsługiwane są `PlayerLeashEntityEvent` oraz `PlayerUnleashEntityEvent`.
26+
27+
- ✅ ~~Flaga `animal-ride` — blokująca wsiadanie na zwierzęta (konie, muły, osły)~~
28+
- Nie istnieje jako osobna flaga.
29+
- Obsługiwana przez `animal-interact`.
30+
- Wykorzystywany jest `EntityMountEvent`.
31+
32+
- ✅ ~~Flaga `animal-breed` — blokująca rozmnażanie zwierząt~~
33+
- Nie istnieje jako osobna flaga.
34+
- Obsługiwana przez `animal-interact`.
35+
- Wykorzystywany jest `EntityBreedEvent`.
36+
37+
- 🟡 **Jedna flaga `passive`, która to wszystko blokuje automatycznie.**
38+
- Konsolidacja została wykonana, ale nie pod nazwą `passive`.
39+
- Obecna flaga `animal-interact` kontroluje interakcje ze zwierzętami, m.in. smycz, rozmnażanie, wsiadanie i część pozostałych interakcji.
40+
- Obecna flaga `passives` ma inne znaczenie: blokuje zadawanie obrażeń pasywnym zwierzętom.
41+
- Taki podział jest czytelniejszy i warto go zachować:
42+
- `passives` — ochrona zwierząt przed obrażeniami,
43+
- `animal-interact` — ochrona przed interakcjami/kradzieżą/użyciem zwierząt.
44+
45+
### Zabezpieczenie przed kradzieżą przedmiotów
46+
47+
- ✅ ~~Flaga `item-pickup` — blokująca podnoszenie przedmiotów z ziemi~~
48+
- Jest już pełnoprawną flagą.
49+
- Obsługiwana przez `EntityPickupItemEvent`.
50+
- Dotyczy graczy podnoszących przedmioty znajdujące się na terenie działki.
51+
52+
- ✅ ~~Flaga `item-drop` — blokująca wyrzucanie przedmiotów na działce~~
53+
- Jest już pełnoprawną flagą.
54+
- Obsługiwana przez `PlayerDropItemEvent`.
55+
56+
### Zabezpieczenie przed niszczeniem roślin
57+
58+
- ✅ **Flaga `crop-trample` — blokująca niszczenie upraw przez skakanie.**
59+
- Zaimplementowana.
60+
- Obsługiwana przez `PlayerInteractEvent`.
61+
- Sprawdzane jest `Action.PHYSICAL` na `Material.FARMLAND`.
62+
- Spełnia wymaganie oznaczone wcześniej jako konieczne jeszcze dla Alpha-01.
63+
64+
- ➖ ~~Flaga `sapling-trample` — blokująca niszczenie sadzonek~~
65+
- Osobna flaga nie została dodana.
66+
- Zgodnie z założeniem ten przypadek pozostaje pod ochroną budowania/niszczenia bloków, czyli `build`.
67+
68+
### Zabezpieczenie przed używaniem przedmiotów
69+
70+
- ➖ ~~Flaga `item-use` — blokująca używanie przedmiotów (np. łuki, miecze, narzędzia)~~
71+
- Nie istnieje jedna ogólna flaga `item-use`.
72+
- Zakres został rozdzielony na bardziej precyzyjne zabezpieczenia, m.in.:
73+
- `projectiles`,
74+
- `use-potions`,
75+
- `special-weapons`,
76+
- `fishing`,
77+
- `elytra`.
78+
- Obecny podział daje większą kontrolę właścicielowi działki.
79+
80+
- ✅ **Flaga `fishing` — blokująca łowienie ryb.**
81+
- Zaimplementowana.
82+
- Obsługiwana przez `PlayerFishEvent`.
83+
- Sprawdzane są lokalizacje gracza, haczyka oraz złowionego obiektu.
84+
85+
### Zabezpieczenie przed interakcją z blokami
86+
87+
- ✅ **Flaga `bed-use` — blokująca używanie łóżek.**
88+
- Zaimplementowana.
89+
- Obejmuje wszystkie materiały, których nazwa kończy się na `_BED`.
90+
- Spełnia wymaganie oznaczone wcześniej jako konieczne jeszcze dla Alpha-01.
91+
92+
- ✅ **Flaga `crafting` — blokująca używanie stołów rzemieślniczych jako osobna flaga poza `utility`.**
93+
- Zaimplementowana.
94+
- Obejmuje `CRAFTING_TABLE` oraz `CRAFTER`.
95+
- Jest oddzielona od ogólnej flagi `utility`.
96+
- Automatycznie pojawia się w GUI flag.
97+
98+
- ✅ **Flaga `enchanting` — blokująca używanie stołów do zaklęć jako osobna flaga poza `utility`.**
99+
- Zaimplementowana.
100+
- Obejmuje `ENCHANTING_TABLE`.
101+
- Jest oddzielona od `utility`.
102+
- Automatycznie pojawia się w GUI flag.
103+
104+
### Zabezpieczenie przed efektami pogodowymi
105+
106+
- 🟡 **Flaga `weather-damage` — blokująca obrażenia od piorunów.**
107+
- Funkcjonalność istnieje pod wspólną flagą `weather`.
108+
- Obsługiwane są:
109+
- `LightningStrikeEvent`,
110+
- `EntityDamageEvent` z `DamageCause.LIGHTNING`.
111+
- Osobna flaga `weather-damage` nie jest obecnie potrzebna, jeśli akceptujemy wspólną kontrolę przez `weather`.
112+
113+
- ❌ **Flaga `weather-effects` — blokująca efekty pogodowe (deszcz, burza).**
114+
- Brak implementacji.
115+
- Obecne `weather` chroni przed piorunami, ale nie tworzy lokalnej pogody dla gracza na działce.
116+
- Do realizacji wymagane byłoby sterowanie pogodą per-player albo inne rozwiązanie symulujące lokalne warunki pogodowe.
117+
118+
### Zabezpieczenie przed używaniem komend
119+
120+
- ✅ **Flaga `command-use` — blokująca używanie komend na działce.**
121+
- Zaimplementowana przez `PlayerCommandPreprocessEvent`.
122+
- `/home` i `/sethome` mają osobną kontrolę przez `allow-home`.
123+
- Bezpieczne wyjątki dla komend PlotsX:
124+
- `/plotsx`,
125+
- `/ptx`,
126+
- `/plot`,
127+
- `/claim`,
128+
- `/unclaim`.
129+
130+
### Zabezpieczenie przed używaniem przedmiotów specjalnych
131+
132+
- ✅ **Flaga `elytra-use` — blokująca używanie elytry.**
133+
- Funkcjonalność istnieje pod nazwą `elytra`.
134+
- Blokowane jest rozpoczęcie szybowania przez `EntityToggleGlideEvent`.
135+
136+
- 🟡 **Flaga `trident-use` — blokująca używanie trójzębu.**
137+
- Funkcjonalność została połączona z `special-weapons`.
138+
- Obsługiwane jest:
139+
- rzucanie trójzębem przez `ProjectileLaunchEvent`,
140+
- zadawanie obrażeń trójzębem.
141+
- Do sprawdzenia / uzupełnienia pozostaje obsługa Riptide (`PlayerRiptideEvent`), aby nie można było ominąć ochrony poprzez użycie trójzębu do przemieszczania się.
142+
143+
- ✅ **Flaga `mace-use` — blokująca używanie buzdyganu.**
144+
- Funkcjonalność istnieje pod wspólną flagą `special-weapons`.
145+
- Blokowane są obrażenia zadawane przez `MACE`.
146+
147+
### Zabezpieczenie przed używaniem bloków specjalnych
148+
149+
- 🟡 **Flaga `conduit-use` — blokująca używanie przewodników.**
150+
- Funkcjonalność istnieje jako `conduit-effects`.
151+
- Blokowane jest nakładanie efektu przewodnika przez `EntityPotionEffectEvent.Cause.CONDUIT`.
152+
- To rozwiązanie odpowiada faktycznemu mechanizmowi działania conduitów lepiej niż blokowanie zwykłej interakcji kliknięciem.
153+
154+
- ✅ **Flaga `respawn-anchor-use` — blokująca używanie kotwic odrodzenia.**
155+
- Funkcjonalność istnieje pod nazwą `respawn-anchor`.
156+
- Obsługiwana podczas interakcji z `Material.RESPAWN_ANCHOR`.
157+
158+
### Zabezpieczenie przed używaniem przedmiotów dekoracyjnych
159+
160+
- 🟡 **Flaga `frame-use` — blokująca używanie ramek na przedmioty.**
161+
- Funkcjonalność jest częściowo objęta wspólną flagą `decorations`.
162+
- Chronione jest m.in.:
163+
- umieszczanie obiektów wiszących,
164+
- niszczenie obiektów wiszących,
165+
- usuwanie przez gracza lub pocisk.
166+
- Potencjalna luka: brak dedykowanej obsługi interakcji z już istniejącym `ItemFrame` / `GlowItemFrame` podczas obracania lub podmiany przedmiotu.
167+
- **Do uzupełnienia.**
168+
169+
- ✅ **Flaga `armor-stand-use` — blokująca używanie stojaków na zbroję.**
170+
- Funkcjonalność istnieje pod wspólną flagą `decorations`.
171+
- Obsługiwane jest:
172+
- `PlayerArmorStandManipulateEvent`,
173+
- niszczenie ArmorStanda przez gracza lub pocisk.
174+
175+
---
176+
177+
# GUI flag
178+
179+
`FlagsGUI` nie posiada ręcznie utrzymywanej listy flag.
180+
181+
GUI iteruje po `PlotFlagRegistry.allFlags`, dlatego każda poprawnie zarejestrowana flaga automatycznie pojawia się w panelu. Dotyczy to między innymi:
182+
183+
- `crop-trample`,
184+
- `animal-interact`,
185+
- `item-pickup`,
186+
- `item-drop`,
187+
- `fishing`,
188+
- `command-use`,
189+
- `elytra`,
190+
- `special-weapons`,
191+
- `weather`,
192+
- `bed-use`,
193+
- `crafting`,
194+
- `enchanting`,
195+
- `respawn-anchor`,
196+
- `conduit-effects`,
197+
- `decorations`.
198+
199+
Dla nowych flag nie trzeba ręcznie dodawać osobnych slotów, o ile zostaną poprawnie dodane do `PlotFlagRegistry` wraz z nazwą, opisem i materiałem.
200+
201+
---
202+
203+
# Najważniejsze braki do domknięcia Alpha-02
204+
205+
## 1. `weather-effects`
206+
207+
Status: ❌ brak.
208+
209+
Do zaprojektowania pozostaje sposób blokowania lub ukrywania deszczu/burzy dla gracza znajdującego się na działce. Należy pamiętać, że standardowa pogoda świata nie jest ograniczona do regionu działki, więc najprawdopodobniej potrzebne będzie rozwiązanie per-player.
210+
211+
## 2. Pełna ochrona ItemFrame / GlowItemFrame
212+
213+
Status: 🟡 częściowo.
214+
215+
`decorations` chroni obecnie umieszczanie i niszczenie dekoracji, ale trzeba upewnić się, że blokowane są również:
216+
217+
- wkładanie przedmiotu do ramki,
218+
- wyjmowanie przedmiotu,
219+
- podmiana przedmiotu,
220+
- obracanie przedmiotu,
221+
- analogiczne operacje dla `GlowItemFrame`.
222+
223+
## 3. Trident + Riptide
224+
225+
Status: 🟡 do weryfikacji / uzupełnienia.
226+
227+
`special-weapons` blokuje rzucanie trójzębem oraz obrażenia, ale warto dodać kontrolę `PlayerRiptideEvent`, aby użytkownik nie mógł wykorzystać trójzębu do poruszania się na działce mimo blokady.
228+
229+
---
230+
231+
# Podsumowanie
232+
233+
Alpha-02 jest już w zdecydowanej większości zaimplementowana.
234+
235+
Najważniejsza zmiana względem pierwotnej listy polega na scaleniu części bardzo szczegółowych flag w bardziej ogólne grupy:
236+
237+
| Pierwotny pomysł | Aktualna flaga |
238+
| --- | --- |
239+
| `animal-leash` | `animal-interact` |
240+
| `animal-ride` | `animal-interact` |
241+
| `animal-breed` | `animal-interact` |
242+
| ochrona zwierząt przed obrażeniami | `passives` |
243+
| `elytra-use` | `elytra` |
244+
| `trident-use` | `special-weapons` |
245+
| `mace-use` | `special-weapons` |
246+
| `weather-damage` | `weather` |
247+
| `conduit-use` | `conduit-effects` |
248+
| `respawn-anchor-use` | `respawn-anchor` |
249+
| `frame-use` | `decorations` |
250+
| `armor-stand-use` | `decorations` |
251+
252+
Aktualna architektura jest bardziej zwarta i pozwala uniknąć nadmiernego rozdrobnienia GUI flag.
253+
254+
Do pełnego zamknięcia tej listy pozostają przede wszystkim:
255+
256+
1. `weather-effects`,
257+
2. pełna ochrona interakcji z `ItemFrame` / `GlowItemFrame`,
258+
3. obsługa Riptide dla `special-weapons`.
259+
260+
Po zaimplementowaniu tych elementów Alpha-02 można uznać za funkcjonalnie domkniętą w zakresie tej checklisty.

0 commit comments

Comments
 (0)