csata formátum dokumentáció

doc/CsataFormatum.md

@@ -0,0 +1,444 @@
+# Csata objektum
+
+## Szerkezet
+
+```python
+{
+    "enemies": [...],
+    "party_members": [...],
+    "enemy_turn_func": ...,
+    "mus_id": "...",
+    "init_ai_data": {...},
+    "menus": [...],
+    "spells": [...],
+    "inventory": [...]
+}
+```
+
+---
+
+## enemies
+
+Az ellenséges egységek listája.
+
+### Típus
+
+```python
+list[Combatant]
+```
+
+### Példa
+
+```python
+"enemies": [
+    Combatant("Six-Seven kid", 120, 30, 80, 20, 0, 50, False, False),
+    Combatant("Ice Sprite", 60, 15, 150, 10, 0, 200, False, True),
+]
+```
+
+Minden elem egy `Combatant` objektum.
+
+---
+
+## party_members
+
+A játékos által irányított karakterek listája.
+
+### Típus
+
+```python
+list[Combatant]
+```
+
+### Példa
+
+```python
+"party_members": [
+    Combatant("Locke", 80, 45, 130, 15, 10, 10, False, False),
+    Combatant("Terra", 100, 35, 100, 30, 30, 30, False, False),
+]
+```
+
+A lista sorrendje határozza meg:
+
+- a karakter pozícióját a csatában,
+- a menük hozzárendelését,
+- a varázslatok hozzárendelését.
+
+---
+
+## enemy_turn_func
+
+Az ellenséges köröket kezelő függvény.
+
+### Típus
+
+```python
+callable
+```
+
+### Példa
+
+```python
+"enemy_turn_func": enemy_turn_test
+```
+
+A függvényt a rendszer az ellenfelek körének feldolgozására használja.
+
+---
+
+## mus_id
+
+A csata alatt lejátszandó zene azonosítója.
+
+### Típus
+
+```python
+str
+```
+
+### Példa
+
+```python
+"mus_id": "mus_fnafsux"
+```
+
+---
+
+## init_ai_data
+
+Az MI számára átadott inicializáló adatok.
+
+### Típus
+
+```python
+dict
+```
+
+---
+
+### moves
+
+Az MI által használható képességek gyűjteménye.
+
+#### Típus
+
+```python
+dict[str, tuple]
+```
+
+#### Formátum
+
+```python
+"azonosító": (
+    név,
+    függvény,
+    célpont_szükséges
+)
+```
+
+#### Paraméterek
+
+- `név` (`str`)  
+  A képesség megjelenő neve.
+
+- `függvény` (`callable`)  
+  A végrehajtandó függvény.
+
+- `célpont_szükséges`
+  - `True` → ellenséges célpont szükséges
+  - `False` → szövetséges célpont szükséges
+  - `None` → nincs célpont
+
+#### Példa
+
+```python
+"attack": (
+    "Physical attack",
+    move_attack,
+    True
+)
+```
+
+---
+
+### Teljes példa
+
+```python
+"moves": {
+    "attack": ("Physical attack", move_attack, True),
+    "fire": ("Fira", move_fire, True),
+    "ice": ("Blizzara", move_ice, True),
+    "cure": ("Cure", move_cure, False),
+    "defend": ("Defend", move_defend, None)
+}
+```
+
+---
+
+## menus
+
+Karakterenként meghatározza a harci főmenüt.
+
+### Típus
+
+```python
+list[list]
+```
+
+A külső lista a karaktereket reprezentálja.
+
+A sorrendnek meg kell egyeznie a `party_members` listával.
+
+---
+
+### Egy karakter menüje
+
+```python
+[
+    ["Attack", "phys_att"],
+    ["Magic", "magic"],
+    ["Item", "items"]
+]
+```
+
+---
+
+### Menüpont formátuma
+
+```python
+[
+    megjelenő_szöveg,
+    parancs
+]
+```
+
+#### Paraméterek
+
+- `megjelenő_szöveg` (`str`)
+- `parancs` (`str`)
+
+---
+
+### Speciális parancsok
+
+#### Fizikai támadás
+
+```python
+["Attack", "phys_att"]
+```
+
+#### Mágia
+
+```python
+["Magic", "magic"]
+```
+
+#### Tárgyak
+
+```python
+["Item", "items"]
+```
+
+#### Nem választható hely
+
+```python
+["", "unselectable"]
+```
+
+Ez egy üres, nem kiválasztható menüpont.
+
+---
+
+## spells
+
+Karakterenként meghatározza az elérhető varázslatokat.
+
+### Típus
+
+```python
+list[list]
+```
+
+A lista sorrendje megegyezik a `party_members` sorrendjével.
+
+---
+
+### Varázslat formátuma
+
+```python
+[
+    név,
+    mp_költség,
+    (
+        név,
+        függvény,
+        célpont_szükséges
+    )
+]
+```
+
+#### Paraméterek
+
+- `név` (`str`)  
+  A varázslat megjelenő neve.
+
+- `mp_költség` (`int`)  
+  A varázslat MP költsége.
+
+- `akció` (`tuple`)  
+  A végrehajtandó harci művelet.
+
+---
+
+### Példa
+
+```python
+[
+    "Fira",
+    15,
+    ("Fira", move_fire, True)
+]
+```
+
+---
+
+### Teljes példa
+
+```python
+"spells": [
+    [],
+    [
+        ["Fira", 0, ("Fira", move_fire, True)],
+        ["Blizzara", 0, ("Blizzara", move_ice, True)]
+    ],
+    [
+        ["Fira", 0, ("Fira", move_fire, True)],
+        ["Blizzara", 0, ("Blizzara", move_ice, True)]
+    ],
+    []
+]
+```
+
+Ebben az esetben:
+
+- Locke nem rendelkezik varázslatokkal,
+- Terra használhatja a **Fira** és **Blizzara** varázslatokat,
+- Celes használhatja a **Fira** és **Blizzara** varázslatokat,
+- Cyan nem rendelkezik varázslatokkal.
+
+---
+
+## inventory
+
+A csatában használható tárgyak listája.
+
+### Típus
+
+```python
+list
+```
+
+---
+
+### Tárgy formátuma
+
+```python
+[
+    név,
+    mennyiség,
+    (
+        név,
+        függvény,
+        célpont_szükséges
+    )
+]
+```
+
+#### Paraméterek
+
+- `név` (`str`)  
+  A tárgy megjelenő neve.
+
+- `mennyiség` (`int`)  
+  A rendelkezésre álló darabszám.
+
+- `akció` (`tuple`)  
+  A tárgy használatakor meghívandó művelet.
+
+---
+
+### Példa
+
+```python
+[
+    "Phoenix Down",
+    67,
+    (
+        "Phoenix Down",
+        move_phoenix,
+        False
+    )
+]
+```
+
+---
+
+### Teljes példa
+
+```python
+"inventory": [
+    [
+        "Phoenix Down",
+        67,
+        (
+            "Phoenix Down",
+            move_phoenix,
+            False
+        )
+    ]
+]
+```
+
+---
+
+## Indexkapcsolatok
+
+A következő listák indexei összetartoznak:
+
+```python
+party_members[i]
+menus[i]
+spells[i]
+```
+
+Példa:
+
+```python
+party_members[1]  # Terra
+menus[1]          # Terra menüje
+spells[1]         # Terra varázslatai
+```
+
+Ez biztosítja, hogy minden karakter saját menüvel és saját varázslistával rendelkezzen.
+
+---
+
+## Összefoglaló
+
+```python
+{
+    "enemies": list[Combatant],
+    "party_members": list[Combatant],
+    "enemy_turn_func": callable,
+    "mus_id": str,
+    "init_ai_data": {
+        "moves": dict[str, tuple]
+    },
+    "menus": list[list],
+    "spells": list[list],
+    "inventory": list
+}
+```
+
+Egy csata teljes egészében leírható egyetlen szótárral, amely tartalmazza az összes résztvevőt, a harci lehetőségeket, az MI által használható képességeket, valamint a játékos számára elérhető menüket, varázslatokat és tárgyakat.