Quests schrijven

Een quest is één .quest.yaml-bestand. Dat bestand is de bron van waarheid: de Studio compileert het tot assets en het Quest-tabblad is er een weergave van, dus met de hand bewerken en in de constructor bewerken zijn altijd gelijkwaardig. Deze pagina loopt door het formaat heen; de volledige referentie per veld (bewust zo geschreven dat hij ook als AI-prompt dienstdoet) is beschikbaar als download.

Waar de bestanden staan

Zet quests in <Project>/Content/Quests/; ze verschijnen automatisch in de bibliotheek van de Studio. Noem ze <Name>.quest.yaml, één quest per bestand.

Minimaal skelet

quest: Region.MyQuest          # unique id/slug (required)
name: "My Quest"
giver: Bran                    # speaker key of the NPC who gives it
source_culture: en
steps:                         # required, at least 1
  - id: MyQuest_Offer
    scene:
      speakers: [Bran, Player]
      lines:
        - { by: Bran,   id: greet, text: "Hello.", emotion: neutral }
        - { by: Player, id: hi,    text: "Hi." }
      choices:
        - { id: accept, text: "I'll help.", goto: MyQuest_Do }
      on_end: { quest: accept }
  - id: MyQuest_Do
    end: completed

De gouden regels

1. Stabiele id’s in kleine letters op elke regel, keuze en elk doel. De lokalisatie en de gegenereerde stem- en gezichtsassets zijn op die id’s gesleuteld; content invoegen mag bestaande id’s nooit hernummeren.
2. Gebruik alleen gedocumenteerde velden, emoties, shots, voorwaardesoorten en effectwerkwoorden. De validator vangt alles op wat buiten het contract valt, met bij elke bevinding een sprong naar de bron.
3. Elke GameplayTag-waarde moet geregistreerd zijn in je project (native in C++ of in DefaultGameplayTags.ini). Een niet-geregistreerde tag faalt stilzwijgend, en dat is oorzaak nummer 1 van “mijn doel telt nooit mee”. Zie Doelen en voortgang.

Stappen

Een stap is één knoop van de quest: een dialoogscène, een bij te houden doel of een eindmarkering.

Veld	Functie
id	Verplicht, stabiel. Krijgt automatisch de namespace <ShortQuest>_<id>.
scene	Een dialoogscène (regels + keuzes)
objective	Een bij te houden doel: kill / collect / reach / talk / deliver
next	Standaardovergang naar de volgende stap (wanneer de scène geen keuzes heeft)
end	Eindmarkering: completed, declined of failed
require	Toegangsvoorwaarde, bijvoorbeeld om de inleverstap pas vrij te geven als het doel af is

Scènes: regels en keuzes

scene:
  speakers: [Bran, Mira, Player]   # every speaker key present in this scene
  lines:
    - { by: Bran,   id: greet, text: "Come here.", emotion: worried, shot: cu }
    - { by: Mira,   id: warn,  text: "Don't trust him.", to: Player }
    - { by: Player, id: what,  text: "What's wrong?" }
  choices:
    - { id: help,   text: "I'll help.",      goto: MyQuest_Accept }
    - { id: refuse, text: "Not my problem.", goto: MyQuest_Refuse }
  on_end: { quest: accept }

Een scène ondersteunt een willekeurig aantal sprekers: zet elke key in speakers en stel bij elke regel by in. Tijdens runtime bindt elke key aan een actor die al in het level staat; is die er niet, dan wordt er een gespawnd volgens de speaker map die de Cast-fase heeft weggeschreven, en naast de questgever neergezet. Gespawnde personages worden automatisch verwijderd zodra de dialoog eindigt.

Handige velden op een regel:

• to: benoemt tot wie de regel gericht is; stuurt de over-the-shoulder framing en de hoofddraai aan in scènes met 3 of meer sprekers.
• emotion: is een van neutral, happy, sad, angry, afraid, surprised (plus aliassen zoals worried → afraid). Stuurt de additieve gezichtsstemming en de toon van de voice-over aan.
• shot: neemt auto (standaard; de compiler kadreert de scène), wide, ots, cu, reaction, of de id van een eigen cameramark (zie Staging en camera’s).
• echo_of: markeert een regel die de tekst van een keuze herhaalt; geef de id van die keuze op, zodat ze één lokalisatiesleutel delen.

Keuzes kunnen GameplayTags afdwingen en uitdelen: require: maakt een keuze alleen beschikbaar als de speler de tag(s) bezit, grant: kent tags toe zodra de keuze gemaakt wordt.

Dynamische tekst

Tekst ondersteunt de placeholders {PlayerName} en eigen {Token}-placeholders, die op het moment van tonen op een lokalisatieveilige manier worden ingevuld. Zie Runtime-integratie voor het instellen van tokenwaarden vanuit je game.

Schrijven met een AI-assistent

De snelste weg is de kant-en-klare GPT Questwright Quest Builder: die kent het formaat al, dus je hoeft alleen je premisse te beschrijven (“een vuurtorenwachter vraagt de speler zijn vermiste broer te zoeken”) en je krijgt een complete .quest.yaml terug.

Liever een andere assistent? De volledige formaatreferentie is bewust zelfstandig leesbaar: plak het referentiebestand samen met je premisse in ChatGPT of Claude en vraag om een .quest.yaml.

Hoe dan ook: zet het resultaat in Content/Quests/; de validator vangt alles wat buiten het contract valt op, nog voordat het ooit een build bereikt.