STUDY.tavharc_v2 - kaktusztea/szilankrpg GitHub Wiki

STUDY: Távharc fegyverek v2 adatmodellre áttérés

Státusz: RÉSZBEN KÉSZ (2026-09-30). Az adatmodell-migráció (tipizált v2 JSON + a régi pipeline kivezetése) ÉS a per-fegyver CÉ-Idea bekötés IMPLEMENTÁLVA. Hátra: a process_fegyverek.py teljes kivezetése (l. 9. szakasz).

A CÉL: a távharc fegyveradatot a közelharci v2-vel egységes, tipizált JSON-modellre hozni, és a régi md→json visszaolvasó pipeline-t (process_fegyverek.py) kivezetni. A nyereség az adat-réteg egységesítése (kevesebb párhuzamos, hasonló logika a webappban) - NEM a kalkulációs motor összevonása (a CÉ/VÉ mechanika eleve külön a közelharctól).

Ezt a fájlt egy üres session elején beolvasva "képben vagy".

9. Elvégezve (2026-09-30) és ami hátra van

Kész (implementálva, build zöld, 496 teszt)

  • Tipizált v2 source: data/sources/fegyverek/tavfegyverek_fixed.json (28 fegyver, minden mező numerikus). Konvenciók: SP: -99 sentinel = nincs/spec sebzés; Hatótáv → hatótáv_bázis + hatótáv_erő_szorzó; sebzésjelleg enum S/V/Z/spec; név kulcs; idea_default: 0.
  • Build-gate: data/gen/fegyverek_v2.py::generate_tavfegyverek_v2 → data/tables/tavfegyverek_v2.json, a generate_tables.py regiszterben.
  • Extrák: a nem-numerikus hatások a közös extrak.yaml-ban (tényleges hatás-mezővel, szöveges a KM-döntésesekre), egységes tavharc_ prefixű id-kkel: tavharc_aquir_azonnali_halal, tavharc_fuvocso_kicsi_kabitas, tavharc_sfe_duplan, tavharc_pajzs_ve_csokkentes, tavharc_ij_erobonusz_tervezett, tavharc_hajitotor_kozeli_loves, tavharc_elf_ij_keszito, tavharc_ujratoltes_kharei, tavharc_ujratoltes_shad0ni. A fegyver_extrak.json-ban (közös runtime).
  • Webapp: TavfegyverAlap tipizált; data-loader a v2 táblát tölti; a parseInt-ek eltűntek; név-alapú lookup; tavSP() (a -99 sentinel → 0) és tavHatótáv() (a bázis/erő_szorzó-ból) helperek.
  • Régi ág archiválva: tavfegyverek.json + tavfegyver_pattern.json → archive/data_fegyverek_v1/. A data/patterns/ üres.
  • Per-fegyver CÉ-Idea (Modell 2): a példány Idea a karakter.távfegyverek[].idea-ban (szerializált, url-share tuple), idea_default-ról indul; a CÉ-be a példány_idea − idea_default delta 1:1 (spec §17). A korábbi közös UI-only useState(0) (ami MINDEN fegyver CÉ-jét egyszerre torzította - bug) kivezetve. Az Idea popup per-fegyver (index-alapú). Séma (karakter.yaml távfegyverek + idea), TavfegyverPeldany.

Hátra

  • process_fegyverek.py teljes kivezetése: most már elárvult (üres data/patterns/), de a code/lib/-nek van másik fogyasztója (generate.markdown.py) - a process_fegyverek.py + a lib szétválasztása/archiválása külön, óvatos lépés.
  • Osztó-Idea hatás (md/078, lőfegyver ±1) - opcionális, későbbi.
  • Nyitott: a CÉ-Idea jelenleg 1:1 (spec §17). Ha később tábla-alapú modell kell (mint a közelharci konstansok idea), a döntés a 5. szakasz 1. pontjában.

0. A cél és a hatókör tömören

  • A távfegyverek NEM generáltak (nincs full paraméter-generátor, mint a közelharcinál) - a CÉ/Osztó értékek egyediek, nem mátrix-vezéreltek. A távfegyver v2 = tipizált, kézzel karbantartott JSON (a közelharci fegyverek_fixed.json mintájára, távfegyver-mezőkkel).
  • A valódi nyereség: egységes adatmodell (string→tipizált, közös név-alapú lookup, séma + naming-lint build-gate), és a régi process_fegyverek.py pipeline teljes kivezetése.
  • A CÉ/VÉ kalkuláció (tavharc/helpers.ts) külön marad - a távharc mechanika (CÉ + Osztó/Cella/Szorzó) más, mint a közelharci (TÉ/VÉ/SP + harckeret), ezeket NEM vonjuk össze.
  • Az Idea (idea_default + CÉ-delta) ennek EGY komponense (l. 4. szakasz).

1. A jelenlegi (régi) távharc adat-réteg - amit lecserélünk

1.1 Pipeline (RÉGI md→json, elavult)

  • Forrás: md/068_07_hajitofegyverek.md, md/068_08_lofegyverek.md (szabálykönyv-táblák).
  • Kinyerés: data/patterns/tavfegyver_pattern.json → code/process_fegyverek.py md→JSON → data/tables/tavfegyverek.json. A webapp EZT tölti (data-loader.ts).
  • Minden érték STRING (CÉ: "5", Osztó: "5") → a webapp mindenütt parseInt-tel konvertál.
  • Mágiatáv I-IV: a process_fegyverek.py fűzi hozzá (virtuális fegyverek).
  • Ez ugyanaz a pipeline, amit a pajzs-ág kivezetésekor elavultnak ítéltünk. A pajzs már archiválva (archive/data_fegyverek_v1/); a távfegyver az UTOLSÓ fogyasztója → ha ez is v2-re kerül, a process_fegyverek.py teljesen elárvul és kivezethető.

1.2 Adatmodell (a párhuzamosság forrása)

  • TavfegyverAlap (types.ts): csupa string mező (Fegyver, CÉ, Osztó, SP, Sebesség, Sebzés módja, Forgatás módja, Erőbónusz, Átütés, Hatótáv, Kategória, Harcmodor) - a md-tábla lenyomata. Vö. a közelharci FegyverAlap: tipizált, név kulcs, módok[].
  • Lookup: a közelharc közös lookupFegyver(fegyverek, alap) utilt használ (d.név); a távharc 4-5 helyen inline data.tavfegyverek.find(d => d.Fegyver.toLowerCase() === ...) - külön, mert a kulcs Fegyver (nagybetűs), nem név.
  • Karakter-példány: karakter.yaml távfegyverek blokk CSAK alap: ""; TavfegyverPeldany CSAK { alap: string } (nincs idea/név/anyag - szemben a közelharci FegyverPeldany-nal).

1.3 A párhuzamos, hasonló logika (amit csökkentünk)

Réteg Közelharc Távharc (régi) v2 után
Adat-formátum tipizált (TÉ: 3) string (CÉ: "5") + parseInt tipizált mindkettő
Lookup lookupFegyver (közös util, név) inline .find(Fegyver...) × 4-5 közös név-alapú lookup
Betöltés fegyverek_v2.json (generált) tavfegyverek.json (md→json) tavfegyverek_v2.json (kézi, gate-elt)
Séma/gate séma + naming-lint nincs séma + naming-lint
Példány-modell alap, név, anyag, idea csak alap egységes (legalább alap + idea)

Amit NEM vonunk össze: a CÉ-kalkuláció (helpers.ts) vs a közelharci TÉ/VÉ/SP (fegyver-calc.ts) - külön mechanika, marad külön.

2. A cél-állapot (v2 adatmodell a távfegyvernél)

2.1 tavfegyverek_v2.json (tipizált, kézi)

  • Egy rekord tipizált mezőkkel: név (kulcs), CÉ: szám, Osztó: szám, SP, Sebesség, sebzéstípus, Átütés, Hatótáv, Kategória, Harcmodor, idea_default: szám, megjegyzés.
  • Forrás: a jelenlegi tavfegyverek.json tartalmának egyszeri, tipizált átemelése (string→szám).
  • Kézzel karbantartott (fixed-minta), NINCS generátor.
  • Mágiatáv I-IV: a JSON-ban explicit rekordok (a process_fegyverek.py hozzáfűzés helyett).

2.2 Build-gate

  • data/gen/-ben egy tavfegyverek_v2 lépés: a kézi JSON betöltése + séma-validáció + naming-lint + átírás a data/tables/-be (mint a sebzesjelleg_pancel_matrix / fegyver_idea_tabla egyszerű exportok). A generate_tables.py regiszterbe kötve.

2.3 Régi ág kivezetése

  • data/patterns/tavfegyver_pattern.json + a process_fegyverek.py távfegyver-ág → archive/ (mint a pajzs). Ezzel a process_fegyverek.py teljesen kivezethető (nincs több fogyasztó).

2.4 TS + webapp

  • TavfegyverAlap tipizált mezőkkel (név kulcs, számok); a parseInt-ek eltávolítása a helpers.ts-ből; közös név-alapú lookup (a lookupFegyver mintájára, vagy generikus).
  • TavfegyverPeldany + karakter.yaml távfegyverek blokk egységesítése (legalább alap + idea).

3. Spec és szabálykönyv (a CÉ-oldal, változatlan mechanika)

  • engine_spec.md §17: CÉ = -15 + Önuralom + CM + harcmodor_CÉ + távfegyver.CÉ + mesterfegyver_CÉ + Idea. A CÉ-Idea a spec szerint közvetlen (1:1) tag.
  • md/071_tavharc_ce.md: a fő CÉ-képletből az Idea hiányzik (a "Kapcsolódik" linkeli a minőség-oldalt). FESZÜLTSÉG a spec §17-tel - tisztázandó (5/4 nyitott kérdés).
  • md/078_tavharc_fegyverek.md "Távolsági fegyverek minősége": a minőség a CÉ-t javítja/rontja (átlagos Nyílpuska 5, kiváló 8, ócskavas 2) → a bázis-CÉ MAGA tükrözi a minőséget (Modell-2-szerű). Szélsőséges esetben az Osztó is módosul (lőfegyver max ±1; hajító csak lefelé) - Idea Osztó-hatás.
  • A távolsági VÉ (Osztó/Cella/Szorzó, tavharc_szorzok.json, §17.3) NEM része ennek a migrációnak (az a VÉ-oldal, külön adatforrás).

4. Idea komponens (a v2 adatmodell EGY része)

A közelharci idea_default delta-modell (Modell 2) a minta:

  • idea_default (a tavfegyverek_v2.json-ban): a standard példány kezdő-Ideája; a v2 CÉ EZT MÁR tartalmazza.
  • Példány Idea (karakter.távfegyverek[].idea): idea_default-ról indul, hangolható; a jelenlegi UI-only efemer useState(0) (TavharcScreen) kivezetése, a karakter-modellbe szerializálva.
  • CÉ-delta: példány_idea − idea_default a CÉ-hez (1:1, a spec §17 szerint - l. 5/1).
  • Referencia (közelharci, KÉSZ): ideaDelta() (harc/shared.ts), fegyver_idea_tabla.json, DEVSTATE "Fegyver Idea implementáció".

5. Nyitott kérdések

  1. CÉ-Idea modell: 1:1 közvetlen (spec §17, jelenlegi webapp) vagy tábla-alapú delta (mint a közelharci konstansok idea)? A md/078 alapján a bázis-CÉ tartalmazza a minőséget → 1:1 delta (példány − idea_default) tűnik konzisztensnek. Ha tábla-alapú kell, a konstansok idea tábla CÉ-oszloppal bővül.
  2. Osztó-hatás: a minőség módosítsa-e az Osztót is (md/078: lőfegyver ±1, hajító csak le), vagy első körben CSAK a CÉ-t? (Javaslat: első körben csak CÉ, az Osztó-hatás külön al-lépés.)
  3. Mágiatáv (mágikus) ág: az Idea 0 marad-e (a fokozat = minőség, a webapp már most 0-ra kényszeríti)?
  4. Séma bővítés hatóköre: a távfegyver-példány kapjon-e név/anyag-ot is (mint a közelharci fegyver), vagy csak idea? (A távfegyvernek van-e egyedi neve/anyaga a rendszerben?)
  5. Szabálykönyv-feszültség: a md/071 fő CÉ-képletébe kerüljön-e be az Idea (spec §17-tel összhangban)?
  6. tavfegyverek_v2.json helye: data/sources/-ban (mint a többi source) vagy egy fixed-szerű fájl? És a build-gate a meglévő data/gen/fegyverek_v2.py-hoz kerüljön, vagy külön data/gen/tavfegyverek_v2.py?

6. Migrációs lépések (javasolt sorrend)

  1. tavfegyverek_v2.json létrehozása: a jelenlegi tavfegyverek.json egyszeri tipizált átemelése (név kulcs, számok, idea_default: 0 alapból, Mágiatáv explicit rekordok).
  2. Séma + build-gate: séma a távfegyverre + data/gen/ export + naming-lint + generate_tables.py regiszter.
  3. TS + webapp: TavfegyverAlap tipizált; parseInt-ek eltávolítása; közös név-alapú lookup; a helpers.ts a tipizált adatot használja.
  4. Régi ág archiválása: tavfegyver_pattern.json + process_fegyverek.py (távfegyver-ág) → archive/. A process_fegyverek.py ezzel teljesen kivezethető (a pajzs után az utolsó fogyasztó).
  5. Idea (4. szakasz): idea_default a JSON-ban + példány-Idea a karakter-modellbe + CÉ-delta bekötés + a UI-only useState(0) kivezetése. Séma (karakter.yaml távfegyverek) + TavfegyverPeldany
    • url-share szerializálás.
  6. Verifikáció: golden a CÉ-re (default példány CÉ = jelenlegi, visszafelé kompatibilis); séma + naming-lint + linkspector; a dist/runtime nem hivatkozik többé a tavfegyverek.json-ra.

7. Fájl-pointerek (gyors belépés)

Terület Fájl
CÉ kalkuláció (marad, tipizálásra vár) web/karakter/src/components/tavharc/helpers.ts (calcCÉ, calcCÉBontás, getCÉInputs, getFortélyCÉ) - a parseInt-ek itt vannak
CÉ-Idea UI state (kivezetendő) web/karakter/src/components/tavharc/TavharcScreen.tsx (useState(0) idea + ideaPopup)
Távfegyver típus (string→tipizált) web/karakter/src/engine/types.ts (TavfegyverAlap, TavfegyverPeldany)
Karakter séma (hiányos) data/schemas/karakter.yaml → távfegyverek: blokk
Régi pipeline (kivezetendő) data/tables/tavfegyverek.json ← data/patterns/tavfegyver_pattern.json ← code/process_fegyverek.py ← md/068_07, md/068_08
Betöltés web/karakter/src/engine/data-loader.ts (tavfegyverek fetch + return)
Spec data/docs/engine_spec.md §17, §17.1b, §17.2, §17.3
Szabálykönyv md/071_tavharc_ce.md, md/078_tavharc_fegyverek.md ("Távolsági fegyverek minősége"), md/068_01_02_fegyver_idea.md
v2 minta (KÉSZ) data/sources/fegyverek/fegyverek_fixed.json (fixed-minta), data/gen/fegyverek_v2.py (generate_fegyver_idea_tabla export-minta), engine/utils.ts (lookupFegyver), harc/shared.ts (ideaDelta)
Archiválási minta archive/data_fegyverek_v1/ (pajzs kivezetés precedens)

8. Összefoglaló egy mondatban

A távfegyvereket tipizált, kézzel karbantartott v2 JSON-ra visszük (nincs generátor), egységes lookup/séma/build-gate-tel, és kivezetjük a régi process_fegyverek.py md→json pipeline-t; a nyereség az adat-réteg párhuzamosságának csökkentése (a CÉ/VÉ kalkuláció külön marad), az Idea pedig egy komponens - a 6 nyitott kérdés eldöntése után indulhat az implementáció.