modwright 0.1.0

package/knowledge/baldursgate3/dialogue.osiris-goals.yaml

@@ -0,0 +1,386 @@
+game: baldursgate3
+topic: dialogue.osiris-goals
+title: Osiris goal structure (INIT/KB/EXIT), goal hierarchy, and build errors
+facts:
+  - id: bg3.dialogue.osiris-goals.init-kb-exit-sections
+    claim: 'Every Osiris goal script has three sections: INIT "will run only once when the goal
+      activates" (used for setup such as establishing characters); KB "is where the bulk of the
+      script goes" and is assessed while the goal is active; EXIT "contains logic that will only
+      execute when GoalCompleted is called", and "Once the EXIT section runs, the logic from your KB
+      section will no longer be evaluated by the game."'
+    status: community
+    source: docs.baldursgate3.game/index.php?title=Osiris:_Using_the_Story_Editor §Sections
+    tags:
+      - osiris
+      - goal
+      - init
+      - kb
+      - exit
+      - structure
+  - id: bg3.dialogue.osiris-goals.exit-clears-databases
+    claim: A goal's EXIT section is the conventional place to tidy up databases the goal no longer
+      needs, most commonly via SysClear("NameOfDatabaseGoesHere", Number) calls, since KB stops
+      being evaluated once EXIT runs.
+    status: community
+    source: docs.baldursgate3.game/index.php?title=Osiris:_Using_the_Story_Editor §Sections
+    tags:
+      - osiris
+      - goal
+      - exit
+      - sysclear
+      - databases
+  - id: bg3.dialogue.osiris-goals.goals-execute-top-to-bottom
+    claim: Goals — and Osiris in general — execute in the order they are listed in the Story Editor's
+      goal hierarchy, top to bottom, at the same nesting level.
+    status: community
+    source: docs.baldursgate3.game/index.php?title=Osiris:_Using_the_Story_Editor §Example ("goals are
+      executed from top to bottom")
+    tags:
+      - osiris
+      - goal
+      - execution-order
+      - goal-hierarchy
+  - id: bg3.dialogue.osiris-goals.parent-goal-must-complete-before-children-activate
+    claim: A parent goal executes first in full, and its child (sub-)goals only activate once the parent
+      fires a GoalCompleted event — a child goal placed under a parent that never completes will
+      never run.
+    status: community
+    source: docs.baldursgate3.game/index.php?title=Osiris:_Using_the_Story_Editor §Example ("parent
+      goals execute first, and will only activate their children once that parent goal is complete")
+    tags:
+      - osiris
+      - goal
+      - goal-hierarchy
+      - goalcompleted
+      - silent-failure
+  - id: bg3.dialogue.osiris-goals.act-region-situation-naming-convention
+    claim: New goal scripts conventionally follow an "Act_Region_Situation" naming pattern (e.g.
+      "Act3b_LOW_Applesnatcher" for a Lower City situation in Act 3b), and should be placed as a
+      sub-goal of the goal that represents the level/act being targeted, so the new goal doesn't
+      activate before that content is loaded.
+    status: community
+    source: docs.baldursgate3.game/index.php?title=Osiris:_Using_the_Story_Editor §Example
+    tags:
+      - osiris
+      - goal
+      - naming-convention
+      - act-region-situation
+  - id: bg3.dialogue.osiris-goals.modwrapper-gustav-scope
+    claim: ModWrapper_Gustav contains all quest logic that appears in the journal; systemics (e.g.
+      crime), achievements, spells, savegame patching, and tutorials all live in goals outside of
+      ModWrapper_Gustav.
+    status: community
+    source: docs.baldursgate3.game/index.php?title=Osiris:_Using_the_Story_Editor §Example
+    tags:
+      - osiris
+      - goal
+      - modwrapper-gustav
+      - scope
+  - id: bg3.dialogue.osiris-goals.must-save-before-renaming-new-goal
+    claim: A newly created goal script item must be saved in the Story Editor before it can be renamed;
+      if you rename it again right after creation without saving in between, the new name may not
+      stick, and closing and reopening the Story Editor may be needed to recover.
+    status: community
+    source: docs.baldursgate3.game/index.php?title=Osiris:_Using_the_Story_Editor §Example ("you must
+      first save after creating new script items before you can rename them")
+    tags:
+      - osiris
+      - goal
+      - save
+      - rename
+      - toolkit-gotcha
+  - id: bg3.dialogue.osiris-goals.generate-definitions-build-reload-workflow
+    claim: "Three reload paths, in decreasing cost: \"Generate Definitions, Build and Reload\" (Ctrl+F7)
+      builds and reloads story \"along with making it easier to find any new objects you have
+      created\"; \"Reload Level and Story\" (Ctrl+F8, in the main Editor) also reloads the level's
+      objects, which is what you need when characters have been defeated or items destroyed;
+      \"Reload Story\" (F8) alone \"save[s] some time\" when you made no script changes and don't
+      need the level reloaded."
+    status: community
+    source: "docs.baldursgate3.game/index.php?title=Osiris:_Using_the_Story_Editor §Generate
+      Definitions, Build and Reload; §Option 1: Reload Level and Story; §Option 2: Reload Story"
+    tags:
+      - osiris
+      - story-editor
+      - build
+      - reload
+      - workflow
+  - id: bg3.dialogue.osiris-goals.errors-panel-reports-every-goal-file
+    claim: The Story Editor's Errors panel at the bottom reports build errors and warnings from every
+      goal file in the project, not only the one currently open — a build failure elsewhere can
+      appear while editing an unrelated goal.
+    status: community
+    source: docs.baldursgate3.game/index.php?title=Osiris:_Using_the_Story_Editor §Sections
+    tags:
+      - osiris
+      - story-editor
+      - errors
+      - debugging
+  - id: bg3.dialogue.osiris-goals.db-checked-but-never-defined-error
+    claim: '"Database checked but never defined" "occurs if you have left a reference to a DB somewhere
+      in the KB section of your script, but you never defined the DB within the INIT section of the
+      script, nor as part of a THEN block. Either remove the check or define the DB to fix the
+      error."'
+    status: community
+    source: docs.baldursgate3.game/index.php?title=Osiris:_Using_the_Story_Editor §Common Build Errors
+      and Warnings > Database checked but never defined
+    tags:
+      - osiris
+      - build-error
+      - database
+      - kb
+  - id: bg3.dialogue.osiris-goals.type-mismatch-requires-explicit-recast
+    claim: A "Conflict with function definition" build error "means the Story Editor has been told a
+      single variable has multiple types"; the fix is to recast "by adding the expected type in ()s
+      before the variable name" at one of its uses — the page's worked example changes the
+      DB_Players check to DB_Players((CHARACTER)_Player) — and you should "avoid recasting the type
+      of a variable multiple times in the same code block".
+    status: community
+    source: docs.baldursgate3.game/index.php?title=Osiris:_Using_the_Story_Editor §Common Build Errors
+      and Warnings > Conflict with function definition
+    tags:
+      - osiris
+      - build-error
+      - type-mismatch
+      - recast
+  - id: bg3.dialogue.osiris-goals.qry-proc-color-coding
+    claim: '"A properly spelled query will have a brick red name, and procs will have a bright green
+      one" — so a QRY_/PROC_ name still rendering in the default colour is the tell for a misspelled
+      name, which is what the "Could not find any complete/correct definition of Osiris User
+      Query/Procedure" error usually means.'
+    status: community
+    source: docs.baldursgate3.game/index.php?title=Osiris:_Using_the_Story_Editor §Common Build Errors
+      and Warnings > Could not find any complete/correct definition of Osiris User Query/Procedure
+    tags:
+      - osiris
+      - story-editor
+      - qry
+      - proc
+      - debugging
+  - id: bg3.dialogue.osiris-goals.osi-div-source-file
+    claim: "Compiled Osiris goal scripts ship as story.div.osi, one per module:
+      Gustav/Mods/Gustav/Story/, Gustav/Mods/GustavDev/Story/ and Gustav/Mods/Honour/Story/. Extract
+      with LSLib's \"Story (OSI) tools\" section: put the file in \"Story/savegame file path\",
+      press Load, set \"Goal output path\", press Extract."
+    status: community
+    source: wiki.bg3.community/en/Information/Osiris/unpacking-osiris
+    tags:
+      - osiris
+      - story-div-osi
+      - lslib
+      - extraction
+  - id: bg3.dialogue.osiris-goals.rule-structure-if-and-then
+    claim: 'Every Osiris rule has exactly two parts: an IF section of one or more conditions, each on
+      its own line and separated by the line AND, evaluated whenever the rule is triggered; and a
+      THEN section of one or more actions, each on its own line and ending with ";", executed only
+      once every condition in the IF section evaluates true.'
+    status: community
+    source: 'bg3-community/Tutorials/Osiris/Understanding-Osiris-Rules.md §The Structure of an Osiris
+      Rule (lines 33-48: "This part begins with IF"; "Each condition is separated by the line AND";
+      "This part begins with THEN"; "Each action ends with ;")'
+    tags:
+      - osiris
+      - rule
+      - structure
+      - if-then
+  - id: bg3.dialogue.osiris-goals.fact-database-definitions
+    claim: A "fact" is a set of one or more values; a "database" is a container for zero or more unique
+      facts, analogous to a table of rows (facts) and columns (values) — a fact can be "defined"
+      (added) or removed from a database at any time, and a database rejects a second definition of
+      a fact it already holds.
+    status: community
+    source: 'bg3-community/Tutorials/Osiris/Understanding-Osiris-Rules.md §Basic Definitions (lines
+      21-25: "Fact: A set of one or more values."; "Database: A container for zero or more unique
+      facts.")'
+    tags:
+      - osiris
+      - database
+      - fact
+      - definitions
+  - id: bg3.dialogue.osiris-goals.database-action-not-then-redefines-nothing
+    claim: Using a database as a THEN action defines (adds) the fact unless it is already defined, in
+      which case "the action won't do anything" — facts in a database must be unique, so the same
+      fact cannot be added a second time. Database actions must be used with a literal or an
+      already-assigned variable.
+    status: community
+    source: bg3-community/Tutorials/Osiris/Understanding-Osiris-Actions.md:15,19, §Databases ("Using a
+      database as an action will add a fact to the database unless the fact is already defined, in
+      which case the action won't do anything.")
+    tags:
+      - osiris
+      - database
+      - action
+      - idempotent
+    detail: 'Checked against the source (2026-09-08): an earlier wording also said such a rule "does not
+      re-trigger database conditions that already fired for it the first time". The page does not
+      say that anywhere; it only describes the add being a no-op. Dropped rather than promoted.'
+  - id: bg3.dialogue.osiris-goals.not-prefix-removes-database-fact
+    claim: Prefixing a database action with NOT removes that fact from the database if it is currently
+      defined (and is a no-op if it is not), which also re-triggers "inverted" database conditions
+      and allows the fact to be re-defined and trigger normal database conditions again afterward.
+    status: community
+    source: bg3-community/Tutorials/Osiris/Understanding-Osiris-Actions.md:17,41, §Databases ("We can
+      also invert database actions by adding `NOT` to the beginning of the line, which will remove a
+      fact from the database if it is already defined."; the worked example at :41 adds that this
+      triggers inverted database conditions and lets the fact be re-defined and trigger normal ones
+      again)
+    tags:
+      - osiris
+      - database
+      - not
+      - action
+  - id: bg3.dialogue.osiris-goals.condition-order-controls-evaluation-cost
+    claim: Combining two undeclared-variable database conditions on the SAME database before any
+      filtering condition makes the rule evaluate once per pair of facts (size(DB) squared,
+      described as "very inefficient"); reordering so a filtering condition (an equality check
+      against a known value) comes immediately after the first database condition collapses most of
+      those evaluations before the second database condition ever creates new versions of the rule,
+      avoiding the exponential blow-up.
+    status: community
+    source: 'bg3-community/Tutorials/Osiris/Considering-Performance.md §Number of Evaluations (worked
+      DB_Players example: "the number of times this rule has to be evaluated is the size of
+      DB_Players multiplied by itself. This is very inefficient." / the reordered version: "the
+      number of evaluations no longer grows exponentially")'
+    tags:
+      - osiris
+      - performance
+      - condition-order
+      - database
+    detail: "Practical rule of thumb for authoring: put the most selective filter condition as early as
+      possible after each undeclared-variable database condition, rather than grouping all database
+      conditions together before any filters."
+  - id: bg3.dialogue.osiris-goals.overloaded-procedure-with-default-parameter
+    claim: 'A procedure can be declared with two different parameter counts (an overload) to emulate a
+      default parameter value: PROC_MyProc() calling PROC_MyProc("This is the default message")
+      inside its own body makes calling the zero-argument form behave identically to calling the
+      one-argument form with that literal, while a caller can still supply a different string
+      explicitly via the one-argument form.'
+    status: community
+    source: bg3-community/Tutorials/Osiris/Understanding-Osiris-Actions.md:191-201, §Procedures ("If you
+      define the procedure more than once with different numbers of parameters, they will behave
+      like completely different procedures. We can use this to make our own default values"; worked
+      PROC_MyProc example with and without a (STRING)_Message parameter)
+    tags:
+      - osiris
+      - procedure
+      - overload
+      - default-parameter
+  - id: bg3.dialogue.osiris-goals.variables-start-with-underscore-convention
+    claim: The Osiris naming convention for variables is to always start with an underscore ("_"),
+      distinguishing a variable (e.g. _Player, _Character) from a literal, function name, or
+      database name in the same line of code.
+    status: community
+    source: 'bg3-community/Tutorials/Osiris/Understanding-Osiris-Conditions.md:102 ("The naming
+      convention for variables in Osiris is to always start with an underscore: _")'
+    tags:
+      - osiris
+      - naming-convention
+      - variables
+  - id: bg3.dialogue.osiris-goals.query-return-database-naming-convention
+    claim: The recommended naming convention for a database that only exists to capture a custom query's
+      return value is DB_QRYRTN_QueryName — e.g. a query QRY_CustomGetHitpoints would store its
+      result in DB_QRYRTN_CustomGetHitpoints.
+    status: community
+    source: 'bg3-community/Tutorials/Osiris/Understanding-Osiris-Conditions.md:645 ("A good naming
+      convention for query-return databases is: DB_QRYRTN_QueryName")'
+    tags:
+      - osiris
+      - naming-convention
+      - query
+      - database
+  - id: bg3.dialogue.osiris-goals.qry-onlyonce-fire-once-utility
+    claim: QRY_OnlyOnce is a built-in query that takes a string in-parameter and evaluates true only the
+      first time it is ever called with that particular string, even across multiple
+      concurrently-evaluating versions of the same rule — the documented pattern for making a
+      multiply-triggered rule fire exactly once per distinct key.
+    status: community
+    source: bg3-community/Tutorials/Osiris/Understanding-Osiris-Conditions.md:689 ("there is a query
+      `QRY_OnlyOnce` that takes a string as an in-parameter and only evaluates to true the first
+      time it is called with that particular string."; the next sentence adds that it evaluates true
+      for only one of several concurrently-evaluating versions of a rule)
+    tags:
+      - osiris
+      - qry-onlyonce
+      - deduplication
+      - utility-query
+  - id: bg3.dialogue.osiris-goals.calls-require-constant-or-assigned-variable
+    claim: Every in-parameter to an Osiris Call must be given either a constant/literal value or an
+      already- assigned variable — a Call cannot be given an undeclared (unassigned) variable the
+      way a database condition can, since a Call has no mechanism to enumerate possible values for
+      it.
+    status: community
+    source: bg3-community/Tutorials/Osiris/Understanding-Osiris-Actions.md §Calls ("Every call has one
+      or more in-parameters that must be given a constant value or an assigned variable so that it
+      knows exactly what we want it to do")
+    tags:
+      - osiris
+      - call
+      - variable
+      - constraint
+  - id: bg3.dialogue.osiris-goals.hardcoded-guid-literal-is-most-efficient-condition-form
+    claim: "When a rule only cares about specific, known characters, writing their GUIDs directly as
+      literals inside the database condition (e.g. DB_Players(S_Player_Wyll_c774d764-...)) instead
+      of an undeclared variable plus a separate equality filter is the most efficient form: the rule
+      then has exactly one version and only triggers for evaluation when one of the literal facts
+      itself is added or removed — strictly better than the \"declared variable filtered right after
+      its database condition\" pattern this topic's other performance fact recommends when the
+      target isn't a fixed, known value."
+    status: community
+    source: bg3-community/Tutorials/Osiris/Considering-Performance.md §Number of Evaluations (final
+      worked example and "This is incredibly efficient in both regards")
+    tags:
+      - osiris
+      - performance
+      - database
+      - literal
+      - condition-order
+    related:
+      - id: bg3.dialogue.osiris-goals.condition-order-controls-evaluation-cost
+        detail: "Names the even-more-efficient special case of that fact's general reordering advice: when
+          the values being matched are fixed and known ahead of time, skip the
+          undeclared-variable-plus-filter pattern entirely and hard-code the literal into the
+          database condition itself."
+  - id: bg3.dialogue.osiris-goals.player-membership-databases-are-distinct
+    claim: DB_Players (all registered player character UUIDs), DB_Avatars (registered player Avatar
+      character UUIDs), and DB_PartyMembers (currently registered party member UUIDs) are three
+      separately maintained, single-parameter (Character UUID) databases with distinct descriptions
+      in the db reference, listed as separate rows under Character Management.
+    status: community
+    source: bg3-community/Information/Osiris/db-reference/character-dbs.md:25-30, §Character Management
+      (DB_Players, DB_Avatars, DB_PartyMembers rows, each "1|Character UUID")
+    tags:
+      - osiris
+      - database
+      - db-players
+      - db-avatars
+      - db-partymembers
+      - gotcha
+    detail: "Inference, not in the source: because they are separately maintained, picking the wrong one
+      for a rule's intent (\"everyone in the current party\" vs. \"every player character that
+      exists\") will include or exclude characters the author did not mean to. The reference table
+      states the three descriptions only; it does not compare them or warn about the mix-up."
+  - id: bg3.dialogue.osiris-goals.raw-goal-txt-in-a-pak-is-inert-without-a-story-compile
+    claim: "A goal shipped only as Mods/<Mod>/Story/RawFiles/Goals/<Goal>.txt inside a pak does not
+      exist at runtime: its INIT database is nil (Osi.DB_<name> is nil, indexing it raises \"attempt
+      to index a nil value\"), and Osi.QuestUpdate for the journal entry it names returns without
+      error and shows nothing in the journal. The goal has to be compiled into the module's story
+      (the toolkit's Generate Definitions / Build) before the pak carries anything the engine runs."
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - osiris
+      - goals
+      - story-compile
+      - pak
+      - quest-stub
+      - journal
+      - scaffold
+    related:
+      - bg3.dialogue.osiris-goals.generate-definitions-build-reload-workflow
+      - bg3.dialogue.osiris-goals.osi-div-source-file
+    detail: The loca handles the scaffold wrote (journal title and entry text) resolved through
+      Ext.Loca.GetTranslatedString in the same session, so the loca half of the scaffold loads.
+      Whether the journal .lsx under Mods/<Mod>/Story/Journals loads as loose .lsx was not separated
+      from the missing compile; the RootTemplates rule (loose .lsx not loaded, .lsf needed) suggests
+      it does not.

package/knowledge/baldursgate3/dialogue.yaml

@@ -0,0 +1,122 @@
+game: baldursgate3
+topic: dialogue
+title: Vanilla dialogue editing, pipeline correction, and dialog override delivery
+facts:
+  - id: bg3.dialogue.binary-source-not-editor
+    claim: "Never patch the shipped editor .lsj under Mods/<ns>/Story/Dialogs/ — it carries an extra
+      top-level editorData REGION and an older save version (4.5.0.500 vs the binary's 4.6.0.1), and
+      Divine bakes both into the converted .lsf. Correct source: extract the vanilla
+      DialogsBinary/*.lsf, convert lsf→lsj (drops editor junk, right version), patch THAT, convert
+      back lsj→lsf."
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - dialogue
+      - editing
+      - editor
+      - binary
+      - pipeline
+    detail: The editor .lsj is still the best READING copy (it has logicalname labels the binary lacks),
+      but it is not the correct patching source. Round-trips cleanly; a patched file lands at
+      ~vanilla size (a bloated output means editor junk came along).
+  - id: bg3.dialogue.node-structure
+    claim: "Dialog node graph: save.regions.dialog.nodes[0].node[]. Constructors include TagGreeting
+      (entry, per checkflags), TagQuestion (player option), TagAnswer, ActiveRoll (an option with
+      dice: RollType/Ability/Skill/DifficultyClassID guid), RollResult (Success bool → children),
+      Jump (jumptarget + jumptargetpoint: 2 = target's children), Alias."
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - dialogue
+      - node-graph
+      - structure
+    detail: Add an option = clone a donor node in the SAME dialog (keeps field shapes valid), give it a
+      new UUID, and splice it into the parent's children[0].child list at the position you want it
+      shown.
+  - id: bg3.dialogue.class-gate-tag-rules
+    claim: Gate an option by class with either TaggedText RuleGroup tag rules (what vanilla [WIZARD]
+      options use; auto-renders the tag DisplayName prefix) or a checkflags flaggroup type="Tag"
+      {UUID=<tag guid>, value=true, paramval=<speaker index>} (no auto-prefix, so custom "[Hack]
+      ..." text works). The player's speaker index varies per dialog — read speakerlist.
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - dialogue
+      - gating
+      - class
+      - tags
+    detail: "Verified by hand end-to-end in game: a custom [Hack] option passes the class gate (pod
+      console; Withers crypt dialog)."
+  - id: bg3.dialogue.override-cannot-ship-in-pak
+    claim: "Earlier rule (v1.5.3.1): dialog overrides CANNOT ship inside a registered mod pak — any
+      Mods/<vanilla-module>/Story/DialogsBinary/*.lsf in the pak was said to CTD at LoadModule, even
+      a byte-exact copy of vanilla, so overrides had to be deployed as loose files under the game's
+      Data/Mods/<ns>/Story/DialogsBinary/."
+    status: contradicted
+    source: ModWright research
+    tags:
+      - dialogue
+      - pak
+      - override
+      - delivery
+    detail: Kept so the mistake is not remade. The rule stood for a full release cycle and shaped
+      dialogue strategy (it is why the namespaced DialogBank workaround was built). Superseded by
+      bg3.dialogue.override-packing-rule-was-wrong. Loose files under
+      Data/Mods/<ns>/Story/DialogsBinary/ do still load — that half of the rule is correct and is
+      the fast dev-iteration route.
+  - id: bg3.dialogue.override-packing-rule-was-wrong
+    claim: Dialog overrides CAN be packed. A pak containing all 22 binary-derived
+      Mods/<vanilla-module>/Story/DialogsBinary overrides launched with NO crash (verified by hand),
+      and the [Hack] options fire from the pak.
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    supersedes: bg3.dialogue.override-cannot-ship-in-pak
+    source: ModWright field verification
+    tags:
+      - dialogue
+      - pak
+      - override
+      - misattribution
+    detail: The original CTD was "almost certainly" the editor-vs-binary save-version bug (editor .lsj
+      4.5.0.500 baked into the .lsf vs the binary's 4.6.0.1) — the same root cause that broke the
+      loose files before the pipeline switched to binary-derived sources; it was misattributed to
+      "packing dialogs." The release pak now folds DialogOverrides/{Gustav,GustavDev} into its Mods/
+      tree. The loose-file route still works for fast dev iteration but is no longer required for
+      distribution.
+  - id: bg3.dialogue.dialogbank-namespaced-pattern
+    claim: "Community non-override layout (Various Dialogue Fixes / wiki.bg3.community Dialogue Files
+      Tutorial): ship each edited .lsf at Mods/<mod>/Story/DialogsBinary/<same rel path> and add a
+      DialogBank at Public/<mod>/Content/Assets/Dialogs/[PAK]_<BankName>/_merged.lsf whose Resource
+      nodes are byte-for-byte copies of the vanilla entries (same resource ID, Name, flags,
+      SpeakerSlotsWithLines) with only SourceFile re-pointed to Mods/<mod>/Story/Dialogs/<rel>.lsj.
+      The game resolves the DialogsBinary .lsf through that .lsj path (no .lsj needs to ship)."
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - dialogue
+      - dialogbank
+      - namespaced
+      - toolkit
+    detail: "A class mod shipped 22 such Resource nodes in its own [PAK]_ dialogue bank. Needed because
+      the Toolkit packs only the project's own Mods/<proj> + Public/<proj> folders, so
+      path-overrides into Gustav(Dev) never reach the mod.io pak. Load-order aware; shows in the
+      in-game mod manager. Verified by hand: the options fire from the namespaced test pak;
+      extract+diff confirmed all 22 lsf byte-identical plus the bank."
+  - id: bg3.dialogue.flags-guid-definitions
+    claim: Dialogs reference flags by GUID; definitions are one-per-file Public/Gustav/Flags/<guid>.lsf
+      (convert to .lsx, read Name). The Osiris FLAG identifier is Name_GUID.
+      Osi.SetFlag("Name_GUID", char) WORKS (actions are fine); Osi.GetFlag is broken like the other
+      queries (returned 0 for a provably-set flag).
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - dialogue
+      - flags
+      - guid
+      - osiris
+    detail: Use SetFlag to arm flags from dialogue; do not rely on GetFlag for queries in this SE build.

package/knowledge/baldursgate3/feats.classes.yaml

@@ -0,0 +1,164 @@
+game: baldursgate3
+topic: feats.classes
+title: Basic class creation, and the feats-as-passives pattern
+facts:
+  - id: bg3.feats.classes.classdescription-required-attributes
+    claim: A ClassDescription node's practical minimum attribute set is BaseHp, CharacterCreationPose (a
+      guid, commonly reused from a vanilla class), Description and DisplayName (TranslatedString
+      handles), HpPerLevel, LearningStrategy, Name (FixedString), PrimaryAbility (uint8),
+      ProgressionTableUUID, SoundClassType (FixedString, can reuse a vanilla class's),
+      SpellCastingAbility (uint8), and UUID.
+    status: community
+    source: wiki.bg3.community/en/Tutorials/Classes/Basic-Class-Creation §ClassDescription.lsx
+    tags:
+      - class
+      - classdescription
+      - required-fields
+  - id: bg3.feats.classes.hpperlevel-adds-one
+    claim: 'The engine adds 1 to the HpPerLevel value: "Please be aware that it takes what value you put
+      here and adds 1 to it. So the 4 I put here plus the basehp i put as 6 will give me 11, not
+      10." Author HpPerLevel one lower than the per-level gain you want.'
+    status: community
+    source: wiki.bg3.community/en/Tutorials/Classes/Basic-Class-Creation §ClassDescription.lsx
+    tags:
+      - class
+      - classdescription
+      - hpperlevel
+      - gotcha
+  - id: bg3.feats.classes.primaryability-numeric-mapping
+    claim: ClassDescription's PrimaryAbility (and SpellCastingAbility) attribute is a uint8 ability
+      index, given on the page as "1 = dex, 2 = str, 3 = con, 4 = int, 5 = wis, 6 = chr" — note
+      Dexterity is 1 and Strength is 2, not the usual STR-first order.
+    status: community
+    source: wiki.bg3.community/en/Tutorials/Classes/Basic-Class-Creation §ClassDescription.lsx
+    tags:
+      - class
+      - classdescription
+      - primaryability
+      - enum
+  - id: bg3.feats.classes.subclass-is-classdescription-with-parentguid
+    claim: A subclass is defined as its own ClassDescription node whose ParentGuid equals the base class
+      ClassDescription's UUID, and which needs its own newly-generated ProgressionTableUUID distinct
+      from the base class's and from every other subclass's.
+    status: community
+    source: wiki.bg3.community/en/Tutorials/Classes/Basic-Class-Creation §Subclasses
+    tags:
+      - class
+      - subclass
+      - parentguid
+      - progressiontableuuid
+  - id: bg3.feats.classes.subclass-listed-under-parent-progression
+    claim: A subclass becomes choosable at a given level by adding a SubClasses/SubClass child node
+      (Object = the subclass's ClassDescription UUID) to the base class's Progression node for that
+      level, and the subclass's own Progression node(s) must set ProgressionType to 1 (versus 0 for
+      the base class).
+    status: community
+    source: wiki.bg3.community/en/Tutorials/Classes/Basic-Class-Creation §Subclasses
+    tags:
+      - class
+      - subclass
+      - progression
+      - progressiontype
+  - id: bg3.feats.classes.actionresourcedefinition-required-fields
+    claim: A custom class resource is defined in ActionResourceDefinitions.lsx with Description and
+      DisplayName (TranslatedString handles), MaxLevel (uint32), Name (FixedString — the worked
+      example uses "SpeedForce", the same string that then appears in the
+      ActionResource(SpeedForce,2,0) boost), ReplenishType (FixedString, "ShortRest" in the
+      example), IsSpellResource (bool), ShowOnActionResourcePanel (bool), and its own UUID (guid).
+    status: community
+    source: wiki.bg3.community/en/Tutorials/Classes/Basic-Class-Creation §Action Resources
+    tags:
+      - class
+      - actionresourcedefinition
+      - required-fields
+  - id: bg3.feats.classes.actionresource-granted-via-boosts
+    claim: "A custom ActionResourceDefinition only takes effect once granted through a Progression's
+      Boosts string, e.g. ActionResource(SpeedForce,2,0): \"We have made a new action resource but
+      right now it just floating around.\""
+    status: community
+    source: wiki.bg3.community/en/Tutorials/Classes/Basic-Class-Creation §Action Resources
+    tags:
+      - class
+      - actionresourcedefinition
+      - boosts
+      - silent-failure
+  - id: bg3.feats.classes.tags-live-in-children-node
+    claim: A ClassDescription (or subclass) links to its Tags entry through a children/Tags node
+      carrying an Object guid attribute — not through an attribute on ClassDescription itself; the
+      tag's own .lsx file "should be a new unique uuid" as its filename, and that filename UUID is
+      what other files reference.
+    status: community
+    source: wiki.bg3.community/en/Tutorials/Classes/Basic-Class-Creation §Tags > Make tag file, §Use
+      Tag; filename-vs-internal-UUID rule from the Community Library wiki, Building-a-Race-Mod
+      §Anatomy of a Tag
+    tags:
+      - class
+      - tags
+      - structure
+    detail: The Basic-Class-Creation page shows the structure and the uuid-named tag file but does not
+      spell out which of the tag's two UUIDs to reference; that is stated explicitly on the
+      Community Library race page — see
+      bg3.races.progression.tag-filename-differs-from-internal-uuid.
+  - id: bg3.feats.classes.passivesadded-vs-selectpassives-selector
+    claim: "Passives can reach a class two ways with different semantics: PassivesAdded on the
+      Progression node unconditionally grants a fixed, named passive at that level; a
+      SelectPassives(...) inside Selectors lets the player choose among a PassiveList's options. Use
+      PassivesAdded for something the class always gets, SelectPassives only when the player must
+      pick."
+    status: community
+    source: wiki.bg3.community/en/Tutorials/Classes/Basic-Class-Creation §Selectors ("SelectPassives()
+      takes 3 parameters...the UUID of the list of passives, the amount of options you can select"),
+      §Boosts and PassivesAdded/Removed (Progressions.lsx) > PassivesAdded/Removed
+    tags:
+      - class
+      - passivesadded
+      - selectors
+      - selectpassives
+  - id: bg3.feats.classes.boosts-vs-passivesadded-distinction
+    claim: 'Boosts and PassivesAdded on a Progression node are different attributes, not two spellings
+      of the same thing: Boosts holds inline boost-function strings ("things our class should get,
+      like maybe certain weapon proficiencies, different actions resources...debuffs, buffs, ability
+      changes"), while PassivesAdded holds names that "refer to passives found in Passive.txt".'
+    status: community
+    source: wiki.bg3.community/en/Tutorials/Classes/Basic-Class-Creation §Boosts and
+      PassivesAdded/Removed (Progressions.lsx) > Boosts, > PassivesAdded/Removed
+    tags:
+      - class
+      - boosts
+      - passivesadded
+      - progressions
+    detail: 'Both are semicolon-separated lists (Community Library wiki, Building-a-Race-Mod §Racial
+      Progressions: "PassivesAdded: A semicolon-separated list of passive IDs").'
+  - id: bg3.feats.classes.level1-progression-required-for-cc
+    claim: A class requires at minimum a Level 1 Progression node with its TableUUID matching the
+      ClassDescription's ProgressionTableUUID; without one the class cannot progress past the
+      character-creation screen ("your class does require a level 1 progression to make it past the
+      character creation page").
+    status: community
+    source: wiki.bg3.community/en/Tutorials/Classes/Basic-Class-Creation §Progressions.lsx
+    tags:
+      - class
+      - progressions
+      - level1
+      - character-creation
+  - id: bg3.feats.classes.feats-follow-passive-boost-pattern
+    claim: "A Feat is the same injection target as a Progression: the Compatibility Framework's config
+      and API take FileType \"Feat\" or \"Progression\" interchangeably for both Strings (Type
+      Boosts, PassivesAdded, PassivesRemoved, Requirements) and Selectors, so a feat is authored as
+      the PassivesAdded/Boosts pattern applied to a Feats entry rather than to a Progression node."
+    status: community
+    source: BG3-Compatibility-Framework wiki, _Boosts-and-Passives.md §API ("FileType = either
+      Progression or Feat, defaults to Progression if not included") and _Selector-API.md (Feats
+      config entries); pattern side from
+      wiki.bg3.community/en/Tutorials/Classes/Basic-Class-Creation §Boosts and PassivesAdded/Removed
+      (Progressions.lsx)
+    tags:
+      - feat
+      - passive
+      - boost
+      - source-gap
+    detail: "Recorded because no feat-specific tutorial exists to cite: feats are not independently
+      documented on wiki.bg3.community as of this writing, a real gap rather than an artifact of
+      search limitations. This fact says plainly that feats are the passive/boost pattern applied to
+      Feats.lsx — an analogy backed by the framework's own FileType enum, not by a feat
+      walkthrough."