Unreal export/import tesztmanual

Ezt a checklistet használd, amikor YarnDraft Unreal exportot validálsz ilyen változtatások után:

• src/lib/export/runtimeGraph.ts
• src/lib/export/unrealNativeExport.ts
• src-tauri/src/unreal_export.rs
• src-tauri/templates/unreal
• entity mezők, változók, flow node szemantika vagy audio kezelés

A cél két dolgot bizonyítani:

1. Az exportált Unreal plugin lefordul.
2. Az exportált story.json és az importált Entity Data Assetek ugyanúgy viselkednek, mint a YarnDraft canvas/runtime modell.

Tesztkörnyezet

Eldobható Unreal projektet használj. Ne egy valódi játékprojektben tesztelj először.

Ajánlott alap:

• Unreal Engine 5.7, vagy az a verzió, amit támogatni akarsz.
• Visual Studio telepítve Game development with C++ workload-dal.
• Tiszta UE tesztprojekt, például YarnDraftExportTest.
• Olyan YarnDraft projekt, ami lefedi az alábbi checklistet.

Legyenek kéznél ezek az útvonalak:

<YarnDraft project>.yarndraft/
<Export parent>/<ProjectName>_Unreal/
<UE test project>/<UE test project>.uproject

YarnDraft tesztprojekt lefedettség

Export előtt legyen a YarnDraft projektben legalább:

Terület	Mit tartalmazzon
Dialogue	Egy sor szöveggel, speaker entityvel és voice audióval
Choice	Két címkézett kimenő választás
Choice requirement	Egy condition által zárolt hidden/disabled választás
Choice effect	Egy choice edge, ami változót/taskot/clue-t módosít
Condition	Egy stored variable condition és egy inventory-linked variable condition
Instruction	Stored variable állítás, task state állítás, clue reveal
Task	Egy Task card legalább egy nested flow-val
Clue	Egy Clue card, ami discovered állapotba kerül
Inventory	Item entity give/take
Puzzle	Solved/failed/locked kimenetek
Timer	Normál út és timeout út
Trigger	Event name és legalább egy key/value paraméter
Audio	Egy Audio card sfx vagy bgm típussal
Entity fields	string, integer, boolean, enum, rich text, gameplay tags, entity references
Assets	Legalább egy .wav, .mp3 vagy .ogg, amit dialogue/audio használ

Entity reference teszthez használj például spawnLocations mezőt egy Item template-en, ami Location entitykre mutat.

Export YarnDraftból

1. Nyisd meg a YarnDraft projektet.
2. Használd az Export to game engine funkciót.
3. Válaszd az Unreal Engine targetet.
4. Válassz egy üres export parent mappát.
5. Ellenőrizd, hogy létrejött:

<ProjectName>_Unreal/
├── Plugins/YarnDraft/
├── Content/YarnDraft/story.json
├── Content/YarnDraft/assets/
└── Config/Tags/YarnDraftTags.ini

Elvárt:

• Plugins/YarnDraft/YarnDraft.uplugin létezik.
• Plugins/YarnDraft/YarnDraftPluginSnapshot.json létezik.
• Content/YarnDraft/story.json létezik.
• A hivatkozott dialogue/audio fájlok bekerültek a Content/YarnDraft/assets/ alá.
• A Config/Tags/YarnDraftTags.ini tartalmaz minden gameplay taget, amit entity mezők használnak.

Telepítés Unrealbe

1. Zárd be az Unreal Editort.
2. Másold az exportált Plugins/YarnDraft/ mappát a UE projekt gyökerébe:

<UE test project>/Plugins/YarnDraft/

3. Másold az exportált Content/YarnDraft/ mappát ide:

<UE test project>/Content/YarnDraft/

4. Első telepítéskor másold az exportált Config/Tags/YarnDraftTags.ini fájlt ide:

<UE test project>/Config/Tags/YarnDraftTags.ini

5. Ha a projekt eddig Blueprint-only volt, először nyisd meg az .uproject fájlt. Unreal várhatóan felajánlja a hiányzó plugin modulok rebuildjét; fogadd el.
6. Ha Unreal azt írja, hogy nincs source code, és nem tud project files-t generálni, akkor az Editorban hozz létre egy üres C++ class-t: Tools → New C++ Class → válassz például None / Actor alapot → Create. Ez létrehozza a projekt Source/ mappáját.
7. Zárd be az Editort.
8. Ezután Windowson jobb klikk a .uproject fájlon, majd Generate Visual Studio project files.

Fordítási ellenőrzés

Buildeld a projektet Development Editor konfigurációval.

Elvárt:

• YarnDraftRuntime lefordul.
• YarnDraftEditor lefordul.
• Az UnrealHeaderTool elfogad minden Blueprint delegate-et és structot.
• Nincs hiba ezekre: FYarnDraftAudioCue, FYarnDraftTriggerParams, FYarnDraftChoice, UYarnDraftStoryPlayer.

Opcionális command-line check Windowson:

& "<UE install>\Engine\Build\BatchFiles\Build.bat" UnrealEditor Win64 Development -Project="<UE test project>\<UE test project>.uproject" -WaitMutex

Ha ez elbukik, mentsd el a teljes compiler outputot. Általában az első UnrealHeaderTool hiba a leghasznosabb.

Editor megnyitás ellenőrzés

1. Nyisd meg a UE projektet.
2. Menj ide: Edit → Plugins.
3. Keress rá: YarnDraft.

Elvárt:

• A plugin látszik és enabled.
• Sikeres fordítás után az editor rebuild prompt nélkül nyílik meg.

Entity import ellenőrzés

1. Nyisd meg: Tools → Import YarnDraft Entity Data Assets.
2. Erősítsd meg a sikeres import dialogot.
3. Ellenőrizd a generált asseteket itt:

/Game/YarnDraft/Entities/<TemplateName>/DA_<EntityLabel>

Elvárt minden Data Assetnél:

• EntityId, TemplateId, TemplateName, DisplayName ki van töltve.
• Fields tartalmazza a scalar mezőket: string, number, boolean, enum, rich text.
• A rich text értékek Unreal Rich Text markup stringként maradnak meg.
• ReferenceAssets tartalmazza az entity reference list mezők közvetlen asset referenciáit, például spawnLocations.
• GameplayTags tartalmazza a YarnDraftTags.ini alapján regisztrált tageket.
• PortraitAssetId, PortraitPath, Color ki van töltve, ha YarnDraftban volt értékük.

Ezt is ellenőrizd:

/Game/YarnDraft/RichText/DT_YarnDraftRichTextStyles

Elvárt:

• A Data Table létezik.
• A Row struct FRichTextStyleRow.
• Vannak ilyen sorok: Default, Important, Red, Blue, Small, Medium, Large, Bold, Italic.

Blueprint runtime smoke test

1. Kapcsold be a Show Plugin Content opciót a Content Browserben.
2. Nyisd meg a YarnDraft Content mappát.
3. Húzd be a BP_YarnDraftPlayer Blueprintet egy üres levelbe.
4. Nyomj Playt.

Elvárt:

• A story a Content/YarnDraft/story.json fájlból indul.
• A kezdő log vagy az első line handler lefut.
• Ha csak annyit látsz, hogy a runtime elindult, az még nem bizonyítja az input/choice útvonalat.

A plugin template-ben ezek vannak:

• BP_YarnDraftPlayer - gyors smoke-test actor.
• BPC_YarnDraft - actor component, ha saját player/UI Blueprintből akarod vezérelni.
• WBP_YarnDraftDialogue - egyszerű dialogue textbox + choice button UI.
• WBP_YarnDraftChoiceButton - a default choice gomb widget.

Ha az Enter nem léptet:

1. Nyisd meg a BP_YarnDraftPlayer Blueprintet.
2. Ellenőrizd, hogy kap-e inputot az actor. Ha nem, állítsd be az Auto Receive Input értéket Player 0-ra, vagy hívj Enable Input-ot BeginPlay után.
3. Ellenőrizd, hogy az input event tényleg Advance()-t hív-e.
4. Ha choices jelennek meg, az Enter önmagában nem elég; ilyenkor explicit Choose(index) hívás kell.

UI-s teszthez használhatod a plugin WBP_YarnDraftDialogue widgetjét, vagy készíthetsz saját egyszerű Widget Blueprintet:

1. TextBlock a dialogue line-nak.
2. VerticalBox a choice gomboknak.
3. OnLine → állítsd a TextBlock szövegét.
4. OnChoices → töröld a régi gombokat, majd hozz létre egy Button-t minden choice-hoz.
5. Button click → hívd a Choose(Index)-et.
6. Ha nincs choice, kattintás vagy billentyű → Advance().

Ez jobb runtime teszt, mint a template BP Print Stringje.

Korábbi node smoke tesztek

Ezeket egy YarnDraft Dialogue komponenssel ellátott teszt actoron érdemes futtatni. A komponensen állítsd be:

• Story File Name: YarnDraft/story.json
• Start Flow Name: a tesztelendő flow neve, például Second Flow
• Dialogue Widget Class: WBP_YarnDraftDialogue

Validált alapviselkedések:

Node / feature	Teszt	Elvárt eredmény
Dialogue	Több Dialogue node egymás után	A widget sorban megjeleníti a line-okat, majd a story végén eltűnik
Choice	Két vagy több kimenő választás	A widget gombokat mutat; gombnyomás után a megfelelő ág fut
Inventory	Give item a flow elején, majd itemhez kötött condition/puzzle	A későbbi branch/puzzle már látja az itemet
Puzzle	Required item/clue nélkül, majd meglévő requirementtel és item darabszámmal	Hiányzó vagy kevés requirementnél locked/failed ág, meglévő requirementnél solved ág
Task	Task node állapotváltással	A OnYarnDraftTaskChanged / task status UI megkapja a labelt és state-et
Clue	Clue node után clue-linked condition	A Clue collected állapotba kerül, a condition ezt követi
Game Event	open_door + doorId paraméter	On Game Event Blueprint event megkapja az event nevet és paramétert

Jegyzetek:

• Puzzle item requirement darabszámot is ellenőriz; üres/régi értéknél a runtime 1 darabbal számol.
• Task/Clue állapotok debug UI-ban hasznosak, de éles játékban saját quest/journal UI-ba érdemes kötni őket.
• A YarnDraft canvas node-koordinátáinak változása nem releváns runtime adat, Live Sync ne küldjön erre külön UE toastot.

Game Event Blueprint teszt

Game Event node validálásához használj egy egyszerű flow-t:

Dialogue → Game Event → Dialogue

A Game Event például:

• Event Name: open_door
• parameter: doorId = test_door_01

Actor Blueprintben:

1. Add hozzá a YarnDraft Dialogue komponenst az actorhoz.
2. BeginPlay-ből kösd be: YarnDraftDialogue → Bind Event to On Game Event.
3. A bind Event pinjén hozz létre matching custom eventet, például HandleGameEvent.
4. HandleGameEvent.Event → Print String.
5. HandleGameEvent.Params → Break Yarn Draft Trigger Params → Values → Find, key: doorId → Print String.

Elvárt Output Log:

open_door
test_door_01

Ha csak a dialogue szövegek jelennek meg, de az event nem:

• ellenőrizd, hogy a Live Sync vagy statikus export után a friss story.json tényleg bekerült-e az Unreal projekt Content/YarnDraft/ mappájába;
• ellenőrizd, hogy a Bind Event to On Game Event lefut-e BeginPlay-ből, például egy Print String "game event bound" node-dal;
• UE képernyőn a Print String sorrendje fordítva is látszódhat, az Output Log megbízhatóbb.

Régi WBP teszt UI javítása

Ha egy korábbi tesztből megmaradt WBP_YarnDraftDialogue / WBP_YarnDraftChoiceButton párost használsz, és ilyesmit látsz:

Widget Blueprint could not be loaded because it derives from an invalid class.
Could not find a function named "ChooseOption" in "WBP_YarnDraftChoiceButton".

akkor nem a story.json import romlott el, hanem a régi widget Blueprint már nem illeszkedik a mostani plugin/API állapothoz.

Javítás:

1. Nyisd meg vagy hozd újra létre a WBP_YarnDraftDialogue widgetet UserWidget parenttel.
2. Legyen benne egy referencia arra az objektumra/actorra, amelyik a UYarnDraftStoryPlayer-t birtokolja.
3. Hozz létre rajta egy ChooseOption(Index: Integer) függvényt vagy custom eventet.
4. A ChooseOption belül hívja a runtime aktuális API-ját: Choose(Index).
5. A WBP_YarnDraftChoiceButton kapjon:
   • Owner Dialogue változót WBP_YarnDraftDialogue reference típussal,
   • Choice Index integer változót.
6. A button OnClicked eseménye hívja: Owner Dialogue → ChooseOption(Choice Index).
7. Ha a node-ok pirosak maradnak, jobb klikk a node-on → Refresh Node, vagy töröld és húzd be újra a függvényhívást.

Ha a WBP_YarnDraftDialogue invalid parent miatt nem nyitható meg, gyorsabb új widgetet létrehozni ugyanazzal a névvel/feladattal, mint a régi assetet javítgatni.

Runtime viselkedés checklist

Play módban validáld ezeket:

Viselkedés	Elvárt eredmény
Dialogue voice	Az OnLine nem üres voice pathot kap voice-os dialogue esetén
Choice voice	Voice-os choice választásakor lefut az OnChoiceVoice
Audio card	Az Audio card OnAudioCue eventet küld AudioType, AssetId, AssetPath, Volume, FadeSeconds értékekkel
Trigger card	Az OnTrigger lefut event name-mel és params értékekkel
Hidden choice requirement	Sikertelen hidden requirement nem kerül bele az OnChoices listába
Disabled choice requirement	Sikertelen disabled requirement bEnabled = false értékkel jelenik meg; a Choose() nem csinál semmit
Choice effect	A választás módosítja a cél változót/taskot/clue-t a következő node előtt
Stored variable condition	A true/false branch a stored variable értékét követi
Inventory-linked condition	Az Inventory give/take után a branch az item count szerint változik
Task-linked condition	A branch az aktuális task state-et követi
Clue-linked condition	A branch a discovered/not discovered clue állapotot követi
Nested flow	Flow/dialogue/task child flow belép, majd visszatér a parent útra
Output pin	A konkrét output pin a hozzá tartozó parent transitionre tér vissza
Puzzle	A solved/failed/locked outcome-ok choice-ként jelennek meg
Timer	seconds alapú delay után továbbmegy; timed choice lejáratkor a timeout ágra fut
Finished story	A graph vége OnFinished eventet küld

Conditionöknél, ha lehet, mindkét oldalt teszteld: egyszer state változás előtt, egyszer utána.

Re-export update ellenőrzés

Az első sikeres install után:

1. Csak story contentet módosíts YarnDraftban.
2. Exportálj újra.
3. Statikus re-exportnál csak ezeket másold:

Content/YarnDraft/story.json
Content/YarnDraft/assets/
Config/Tags/YarnDraftTags.ini

4. Ne cseréld le a Plugins/YarnDraft mappát.
5. Indítsd újra a Play módot vagy nyisd újra az editort.

Elvárt:

• Nem kell C++ rebuild.
• Az új story content töltődik be.
• Az entity importer az új story.json alapján frissíti a Data Asseteket.

Ha a YarnDraft plugin template változott, akkor a Plugins/YarnDraft mappát is cserélni kell, majd regenerate project files és rebuild.

Live Sync ellenőrzés

Ezt csak akkor teszteld, ha a statikus export/import út már működik.

1. Indítsd el az Unreal Live Syncet YarnDraftból.
2. Unrealben használd a YarnDraft toolbar actiont a Live Sync csatlakozáshoz.
3. Módosíts egy line-t vagy entityt YarnDraftban.
4. Pushold vagy várd meg a live sync update-et.

Elvárt:

• Unreal kiírja/frissíti a Content/YarnDraft/story.json fájlt.
• Unreal kiírja/frissíti a Config/Tags/YarnDraftTags.ini fájlt.
• Az entity import lefut az update után.
• A következő Play run már az új story-t használja.
• Ha új gameplay tag jelent meg, indítsd újra az Unreal Editort, mert a Gameplay Tags manager csak restart után tölti be az új ini tartalmat.

Mentendő bizonyítékok

Release validációhoz mentsd el:

• YarnDraft verzió / commit.
• Unreal Engine verzió.
• UE test project path.
• Export folder path.
• Build result vagy Build.bat output.
• Screenshot az enabled YarnDraft pluginról.
• Screenshot az importált Data Assetekről.
• Screenshot/log az OnAudioCue, OnTrigger és legalább egy choice működéséről.
• Bármilyen warning az entity importertől.

Gyakori hibák

Tünet	Valószínű ok	Javítás
Unreal minden megnyitáskor rebuildet kér	Előző build elbukott vagy stale binary maradt	Töröld a Binaries/ és Intermediate/ mappákat, regenerate files, rebuild
This project does not have any source code project file generáláskor	Blueprint-only projektben még nincs Source/ mappa	Nyisd meg az Editort, hozz létre egy üres C++ class-t, zárd be, utána generate project files
Hiányzik a YarnDraft plugin	Rossz helyre lett másolva a plugin folder	Ennek kell léteznie: <UE project>/Plugins/YarnDraft/YarnDraft.uplugin
Gameplay tag invalid / not registered	A tag ini még nincs betöltve az aktuális editor sessionben	Live Sync/import után indítsd újra Unrealt; statikus installnál ellenőrizd, hogy létezik <UE project>/Config/Tags/YarnDraftTags.ini
Entity reference hiányzik	Új story.json másolása után nem futott entity import	Futtasd: Tools → Import YarnDraft Entity Data Assets
Régi YD_ assetek jelennek meg	Régi plugin copy fut	Cseréld a Plugins/YarnDraft mappát, regenerate, rebuild
Üres audio path	Az audio asset nincs hivatkozva vagy nem lett kimásolva	Ellenőrizd: Content/YarnDraft/assets/ és story.json asset id-k
OnAudioCue nem elérhető Blueprintben	Régi plugin binary/template	Cseréld a plugint, regenerate project files, rebuild