Journal: DB Helpers

From Baldur's Gate 3 Modding

This page outlines the DB helpers to use when working with the journal in script. If you're unfamiliar with the journal, we recommend having a look at the tutorials, how-tos, and reference pages linked on the main Journal page.

Party Shared Quest State

These DBs are set automatically and can be checked.

DB_QuestIsAccepted

DB_QuestIsAccepted(_QuestID)

  • Quest was started at any moment, but keep in mind it might be opened or closed by now.

DB_QuestIsOpened

DB_QuestIsOpened(_QuestID)

  • Quest was accepted/opened and is not closed yet.

DB_QuestIsClosed

DB_QuestIsClosed(_QuestID)

  • Quest ended, it's still accepted, but not open anymore.

NOTE: Subquests are also added to the above DBs.

Declarative Databases

These DBs can be defined to set quest steps automatically when conditions are met.

Reacting to Flags Being Set

DB_QuestDef_State

DB_QuestDef_State(_Flag, _Quest, _Update)

  • When _Flag is set, unlock _Update in _Quest.
  • If _Flag is global, _Update is unlocked for everyone.
    • Otherwise, it is unlocked for the character on whom the update is set.

DB_QuestDef_State_ConditionalFlag

DB_QuestDef_State_ConditionalFlag(_Flag, _Quest, _Entry, _ConditionalGlobalFlagState, _ConditionalGlobalFlag)

  • Similar to DB_QuestDef_State, but you can define a global flag to check.
  • Typically, you define it twice with 0 and 1 in _FlagState and a different _Entry accordingly.

Linking Quest Entries

DB_QuestDef_ChainedState (3 params)

DB_QuestDef_ChainedState(_Quest, _Step, _NewStep):

  • When _Step in _Quest is unlocked, so is _NewStep.

DB_QuestDef_ChainedState (4 params)

DB_QuestDef_ChainedState(_Quest, _Step, _NewQuest, _NewStep):

  • When _Step in _Quest is unlocked, so is _NewStep in _NewQuest.

Entries Conditional to Other Entries

DB_QuestDef_ConditionalState (5 params)

DB_QuestDef_ConditionalState(_Quest, _UnlockedStep, _NewStep, _ConditionalStep, _ConditionalBool)

  • _NewQuest & _ConditionalQuest = _Quest

DB_QuestDef_ConditionalState (6 params)

DB_QuestDef_ConditionalState(_Quest, _UnlockedStep, _NewQuest, _NewStep, _ConditionalStep, _ConditionalBool)

  • _ConditionalQuest = _Quest

DB_QuestDef_ConditionalState (7 params)

DB_QuestDef_ConditionalState(_Quest, _UnlockedStep, _NewQuest, _NewStep, _ConditionalQuest, _ConditionalStep, _ConditionalBool)

How the DB_QuestDef_ConditionalState DBs Work
  • Similar to DB_QuestDef_ChainedState, but they can be defined multiple times.
  • When _Step in _Quest is unlocked, so is _NewStep IF all the conditions are met.
    • For example, you can define DB_QuestDef_ConditionalState twice to execute this logic: Give entry WyllGaveQuest_AfterZev when receiving DEN_LearntGoblinLeaderWyll after receiving ZevGaveQuest, unless we already have WyllGaveQuest_BeforeZev.

Dead & Defeated

DB_QuestDef_DefeatedState

DB_QuestDef_DefeatedState(_Quest, _Update, _NPC);

  • Set as soon as the NPC is defeated, without requiring a line of sight.

DB_QuestDef_PermaDefeatedState

DB_QuestDef_PermaDefeatedState(_Quest, _Update, _NPC);

  • Set as soon as the NPC is permanently defeated (covers more than just killing), without requiring a line of sight.

DB_QuestDef_SawDeadState

DB_QuestDef_SawDeadState(_Quest, _Update, _NPC);

  • When the players see the dead NPC, unlock _Update in _Quest.
  • NOTE: Is it really necessary to see the corpse in your quest?
  • Alternatively, you could use DB_QuestDef_State with either DB_DefeatedEvent, DB_KilledEvent or DB_SeenDeadNPCGlobalFlag, depending on your needs.

DB_QuestDef_SawDefeatedState

DB_QuestDef_SawDefeatedState(_Quest, _Update, _NPC);

  • When the players see the defeated NPC, unlock _Update in _Quest.
  • Read the note and alternatives about DB_QuestDef_SawDeadState above.

Books

DB_QuestDef_BookReadState

DB_QuestDef_BookReadState((STRING)_Quest, (STRING)_Update, (ITEM)_Book);

  • Update given on GameBookInterfaceClosed.

Leaving/Entering a Region

DB_QuestDef_LevelLoaded

DB_QuestDef_LevelLoaded((STRING)_Quest, (STRING)_Update, (STRING)_Level);

  • On PROC_LevelLoadedOnce, the update is given to all players.
  • Typical use: For closing entries, when a quest must close when the player progresses to the next region and they can't go back.

DB_QuestDef_LevelUnloading

DB_QuestDef_LevelUnloading((STRING)_Quest, (STRING)_Update, (STRING)_Level);

  • On PROC_LevelUnloading, the update is given to all players.
  • Typical use: For closing entries, when a quest must close when the player progresses to the next region and they can't go back.

Companions

DB_QuestDef_State_CompanionLeft

DB_QuestDef_State_CompanionLeft((TAG)_CompanionTag, (STRING)_Quest, (STRING)_Reason)

  • _CompanionTag refers to the REALLY_ORIGIN tag a companion has.
  • _Quest refers to the companion's quest in the journal.
  • _Reason is a quest step defined in the journal; it explains the reason for the companion leaving.
How DB_QuestDef_State_CompanionLeft Works

PROC_Origins_CompanionLeavePermanently((CHARACTER)_Companion, (STRING)_Reason) will update the journal with the _Reason step when called.

Custom _Reason steps can be added to the DB and defined in the journal. The following _Reason steps are generic and should be defined in any companion's journal:

  • CompanionLowRelation
  • CompanionMurdered
  • CompanionHostile
  • PROC_Origins_CompanionLeavePermanently() is called using a generic _Reason step when a DB_OriginMayLeaveDialog() dialogue concludes.
    • By default it uses the CompanionLowRelation _Reason.
    • If GLO_Companion_Murder is set, then the CompanionMurder _Reason is set.
    • if GLO_Companion_Combat is set, then the CompanionHostile _Reason is set.

Adding Exceptions to Declarative Database Rules

Sometimes you want to add a very specific custom rule to one of the defined declarative databases. For this you can use:

QRY_QuestDef_BlockQuestUpdate((CHARACTER)_Player, (STRING)_Quest, (STRING)_Update)

  • _Player refers to the player on whom the QuestUpdate will be assigned.
  • _Quest refers to the name of the quest that is about to be updated.
  • _Update refers to the name of the update that is about to be updated.

Every declarative database rule will also check if this QRY returns false before calling the QuestUpdate. This allows for a last-minute catch in case you need to add exceptions to certain rules.

Retrieved from "https://docs.baldursgate3.game/index.php?title=Journal:_DB_Helpers&oldid=3683"