modwright 0.1.0

package/knowledge/baldursgate3/toolchain.divine.yaml

@@ -0,0 +1,179 @@
+game: baldursgate3
+topic: toolchain.divine
+title: Divine.exe toolchain and core operations
+facts:
+  - id: bg3.toolchain.divine-core-tool
+    claim: divine.exe (LSLib, in Packed/Tools/) is the core modding tool for BG3. It packs/unpacks .pak
+      files, converts .lsf↔.lsx, lists packages, extracts single files, and handles GR2 resources.
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - toolchain
+      - divine
+      - lsx
+      - lsf
+    detail: "Core commands: list-package, extract-package, create-package, convert-resource,
+      extract-single-file. The official Toolkit is incompatible with Script Extender, so the
+      hand-authored + divine pipeline is the SE-compatible path."
+  - id: bg3.toolchain.divine-requires-absolute-paths
+    claim: divine.exe convert-resource requires ABSOLUTE Windows paths (C:\...) for both source and
+      destination. Relative or MSYS-style paths cause "[FATAL] Cannot proceed without absolute
+      path".
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - divine
+      - convert-resource
+      - paths
+      - windows-only
+    detail: 'Command: divine.exe -g bg3 -a convert-resource -i lsx -o lsf -s <ABS_SRC> -d <ABS_DST>. A
+      separate failure mode: a malformed path makes divine write nothing and still exit 0 — silent
+      no-op, no stderr. Build Windows paths with cygpath -m and forward slashes; in bash "$D\$var"
+      collapses to a literal $var with the backslash eaten. See bg3.audio.divine-silent-failure.'
+  - id: bg3.toolchain.divine-staging-required
+    claim: "divine.exe create-package requires staging first: copy only Mods/ + Public/ (+ Generated/
+      for custom models) into a clean temp directory, never point it at a repo root."
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - divine
+      - create-package
+      - pak
+      - staging
+    detail: "create-package at a repo root will pack docs, PNGs, source files, and other junk.
+      Generated/ is required if the mod has custom GR2 models — omitting it ships a pak whose
+      VisualBank dangles and the model is missing (a regression seen in a class mod). PowerShell
+      pattern: Copy-Item -Recurse into $stage, then divine -g bg3 -a create-package -s $stage -d
+      output.pak."
+  - id: bg3.toolchain.pak-deployment
+    claim: Deploy the finished pak to %LOCALAPPDATA%\Larian Studios\Baldur's Gate 3\Mods\<Mod>.pak. The
+      game must be fully closed first — paks lock while BG3 runs ("Device or resource busy").
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - pak
+      - deployment
+      - game-lock
+    detail: "Reliable pattern: build to a scratch path, then a background watcher polls tasklist | grep
+      bg3_dx11.exe and copies the pak once the process exits. The player has to restart to load a
+      new pak anyway."
+  - id: bg3.toolchain.extract-single-file
+    claim: Extract one file from a game pak using divine.exe -g bg3 -a extract-single-file -s <game>.pak
+      -f "Public/.../file.lsf" -d <out.lsf>. List available paths first with list-package (grep the
+      output).
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - divine
+      - extract-single-file
+      - pak
+    detail: "The weapon STAT tells you which mod dir a RootTemplate lives in — e.g. Shadow Blade's
+      WPN_ShadowBlade is in GustavDev, so its template is Gustav.pak:
+      Public/GustavDev/RootTemplates/_merged.lsf. Convert lsf→lsx to read/edit."
+  - id: bg3.toolchain.loca-compilation
+    claim: Localization .xml must be compiled to binary .loca; the .loca is required at runtime and is
+      what ships in the pak. Compile with divine.exe -g bg3 -a convert-loca -s <src>.xml -d
+      <out>.loca. Multitool 0.10.6 does NOT do this step for you, and Vortex's stripped divine.exe
+      cannot — use LSLib's full divine.exe.
+    status: verified
+    source: ModWright field verification
+    tags:
+      - localization
+      - loca
+      - divine
+      - xml
+    detail: "Recorded as a hard-won lesson from an earlier mod's build loop. The same convert-loca
+      action reads the other way for vanilla text: Localization/English.pak → english.loca → divine
+      -a convert-loca → a 34 MB grep-able XML."
+  - id: bg3.toolchain.divine-dot-directory-empty-package
+    claim: divine.exe create-package silently produces an empty 48-byte package (exit 0, "[INFO] Package
+      created successfully.") when any directory anywhere in the -s source path has a dot-prefixed
+      name, whether -s itself is the dot directory or is nested inside one.
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - divine
+      - create-package
+      - paths
+      - silent-failure
+    detail: 'Repro: identical content packed from a deep path with no dot segment gives a 5.3 MB pak;
+      from ".x/" or from ".x/inner/" it gives 48 bytes. Stage BG3 packages under a path with no
+      dot-prefixed segments (ModWright: build.staging, e.g. "build/stage") and treat a pak smaller
+      than its largest input as failed.'
+  - id: bg3.toolchain.divine-game-flag-required-no-default
+    claim: divine.exe's -g/--game argument is required (Optional = false, DefaultValue = null in the CLI
+      argument definition) — there is no implicit game and omitting -g fails argument parsing rather
+      than falling back to a default target.
+    status: verified
+    source: "Norbyte/lslib@6f5f698 Divine/CLI/CommandLineArguments.cs:25-32 (the -g/--game
+      EnumeratedValueArgument: DefaultValue = null, Optional = false)"
+    tags:
+      - divine
+      - cli
+      - game-flag
+      - required
+    detail: "Checked against the source (2026-09-08): `verified_on` removed — read from LSLib's source,
+      which names no game version."
+  - id: bg3.toolchain.divine-game-flag-cli-allowed-values-excludes-unset
+    claim: The -g/--game argument's own AllowedValues list is exactly "dos;dosee;dos2;dos2de;bg3" — five
+      values. LSLib's internal GetGameByString switch statement also recognizes a sixth string,
+      "unset" (mapping to Game.Unset), but "unset" is absent from the CLI argument's AllowedValues,
+      so divine.exe itself rejects -g unset before that switch statement is ever reached; "unset" is
+      only reachable by code that calls into LSLib directly, not through the divine.exe CLI.
+    status: verified
+    source: Norbyte/lslib@6f5f698 Divine/CLI/CommandLineArguments.cs:28 (AllowedValues); :226-257
+      (GetGameByString switch, including the "unset" case at :250-253 unreachable from the CLI's own
+      allow-list)
+    tags:
+      - divine
+      - cli
+      - game-flag
+      - unset
+      - unreachable-code
+  - id: bg3.toolchain.lslib.gr2-max-four-influences
+    claim: divine -a convert-model dae->gr2 fails with "GR2 only supports at most 4 vertex influences".
+      Blender's vertex_group_smooth can add a fifth influence AFTER vertex_group_limit_total(4) has
+      run, so cap the influences again as the last step before the COLLADA export.
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - divine
+      - gr2
+      - collada
+      - blender
+      - vertex-groups
+      - skinning
+      - export
+    detail: "Order that works: weight transfer, vertex_group_limit_total(4), vertex_group_smooth, then
+      vertex_group_limit_total(4) again immediately before export. The GR2 writer rejects the file
+      rather than truncating influences, so the failure is loud, unlike most of the worn-mesh
+      pipeline."
+  - id: bg3.toolchain.lslib.dae-mesh-order-is-gr2-mesh-index
+    claim: divine numbers the GR2's meshes in <library_geometries> order of the source COLLADA, and a
+      VisualBank ObjectID is "<GR2>.<meshname>.<index>". Blender's COLLADA exporter does not order
+      geometries by name (it put a second mesh first), so when the index matters, reorder the
+      <geometry> and matching <controller> blocks in the .dae before converting.
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - divine
+      - gr2
+      - collada
+      - blender
+      - mesh-order
+      - objectid
+      - visualbank
+    related:
+      - id: bg3.items.visualbank.gr2-mesh-name-must-match-objectid
+        detail: That fact fixes the middle segment of the ObjectID; this one fixes the trailing index.
+      - id: bg3.items.visualbank.objectid-mesh-order-vs-lod
+    detail: Check offline with divine -g bg3 -a convert-model gr2->dae and read the geometry order back;
+      no ModWright validator reads GR2 binaries, so this stays on the mesh-export checklist.

package/knowledge/baldursgate3/toolchain.lslib-formats.yaml

@@ -0,0 +1,242 @@
+game: baldursgate3
+topic: toolchain.lslib-formats
+title: LSLib resource format internals (LSF/LSX/PAK versions, Divine CLI action set, .loca binary layout)
+facts:
+  - id: bg3.toolchain.lslib-formats.divine-full-action-enumeration
+    claim: "divine.exe's --action argument accepts exactly these values: create-package, list-package,
+      extract-single-file, extract-package, extract-packages, convert-model, convert-models,
+      convert-resource, convert-resources, convert-loca, build-vt — any other value is rejected by
+      the argument parser's AllowedValues list."
+    status: verified
+    source: Norbyte/lslib@6f5f698 Divine/CLI/CommandLineArguments.cs:85 (the Action argument's
+      AllowedValues)
+    tags:
+      - divine
+      - cli
+      - actions
+      - lslib
+    detail: "Checked against the source (2026-09-08): `verified_on` removed. The claim was read out of
+      LSLib's source, which names no game version; recording it against a BG3 build number would
+      have implied an in-engine observation that did not happen. The same applies to every other
+      source-read fact in this file."
+    related:
+      - id: bg3.toolchain.divine-core-tool
+        detail: Sharpens the existing "list-package, extract-package, create-package, convert-resource,
+          extract-single-file" summary with the complete, exact action-name enumeration read from
+          the argument parser's own allow-list, including convert-loca and the plural batch forms.
+  - id: bg3.toolchain.lslib-formats.batch-actions-need-explicit-formats
+    claim: The three batch actions are extract-packages, convert-models and convert-resources. For
+      convert-models/convert-resources a missing --input-format is a fatal argument error with the
+      message "Cannot perform batch action without --input-format and --output-format arguments";
+      --output-format is also read for those two (but not for extract-packages).
+    status: verified
+    verified_on: LSLib divine build dated 2026-01-24 (no --version flag), 2026-09-09
+    source: Norbyte/lslib@6f5f698 Divine/CLI/CommandLineActions.cs:41-45 (batchActions list), :72-90
+      (validation)
+    tags:
+      - divine
+      - cli
+      - batch
+      - convert-resources
+    detail: 'Checked against the source (2026-09-08): an earlier wording generalised the error path. The
+      guard at :74-79 only logs that fatal message when the action is NOT extract-packages;
+      `GetResourceFormatByString(args.InputFormat)` is then called unconditionally at :81, so
+      `extract-packages` with no --input-format instead throws "Unknown resource format" from
+      CommandLineArguments.cs. Both mean --input-format is required in practice; only one of them
+      produces the quoted message. Machine run 2026-09-09: `divine -g bg3 -a extract-packages -s
+      <dir> -d <dir>` with no --input-format printed `Unhandled exception. System.ArgumentException:
+      Unknown resource format: ""` with a stack through
+      `CommandLineArguments.GetResourceFormatByString` and `CommandLineActions.SetUpAndValidate`,
+      exit code 127 — the extract-packages branch exactly as the review predicted. (`--input-format
+      pak` is rejected the same way, `Unknown resource format: "pak"`: the accepted values are
+      resource formats, not package formats.)'
+  - id: bg3.toolchain.lslib-formats.resource-format-enum-values
+    claim: divine.exe's --input-format/--output-format values are exactly lsb, lsf, lsj, lsx (case names
+      as matched by the CLI argument parser's switch statement).
+    status: contradicted
+    source: Norbyte/lslib@6f5f698 Divine/CLI/CommandLineArguments.cs:62-75, :262-290
+    tags:
+      - divine
+      - cli
+      - resource-format
+      - lsx
+      - lsf
+      - lsj
+      - lsb
+    detail: "Checked against the source (2026-09-08): citation does not support the claim: the cited
+      switch (`GetResourceFormatByString`, :262-290) is only the resource-format helper; the
+      --input-format and --output-format arguments themselves declare AllowedValues =
+      \"dae;glb;gltf;gr2;lsv;pak;lsj;lsx;lsb;lsf\" (:65 and :75), ten values, so the CLI accepts six
+      more than this fact says. Superseded by
+      bg3.toolchain.lslib-formats.format-flags-accept-ten-values; kept per the format's rule that a
+      wrong belief stays recorded."
+  - id: bg3.toolchain.lslib-formats.format-flags-accept-ten-values
+    claim: divine.exe's -i/--input-format and -o/--output-format arguments each accept ten values — dae,
+      glb, gltf, gr2, lsv, pak, lsj, lsx, lsb, lsf — covering model formats (dae/glb/gltf/gr2),
+      package formats (lsv/pak) and resource formats (lsj/lsx/lsb/lsf). Only the four resource
+      formats are convertible by `GetResourceFormatByString`, which is what the batch/convert
+      actions call; any of the other six passed there throws "Unknown resource format".
+    status: verified
+    supersedes: bg3.toolchain.lslib-formats.resource-format-enum-values
+    source: Norbyte/lslib@6f5f698 Divine/CLI/CommandLineArguments.cs:62-75 (both AllowedValues),
+      :262-290 (GetResourceFormatByString)
+    tags:
+      - divine
+      - cli
+      - resource-format
+      - input-format
+      - output-format
+  - id: bg3.toolchain.lslib-formats.package-compression-enum-values
+    claim: divine.exe create-package's compression argument — spelled `-c` / `--compression-method` on
+      the CLI, not `--compression` — accepts exactly zlibfast, zlib, lz4, lz4hc, or none; any other
+      string is rejected up front by the CLI argument parser and no package is written.
+    status: verified
+    verified_on: LSLib divine build dated 2026-01-24 (no --version flag), 2026-09-09
+    source: Norbyte/lslib@6f5f698 Divine/CLI/CommandLineArguments.cs:90-97 (the --compression argument's
+      AllowedValues = "zlib;zlibfast;lz4;lz4hc;none")
+    tags:
+      - divine
+      - cli
+      - compression
+      - create-package
+    detail: "Checked against the source (2026-09-08): citation corrected. The originally cited lines are
+      `GetCompressionOptions`'s switch, which does NOT reject an unknown string — its `case
+      \"none\": default:` arm silently maps anything unrecognised to CompressionMethod.None. The
+      rejection the claim describes happens earlier, at the argument declaration's AllowedValues
+      list, which is now what this fact cites. Machine run 2026-09-09: the flag is `-c,
+      --compression-method` (`divine --help`); `--compression bogus` fails as `[FATAL] Unknown
+      argument found: compression.` before the value is even looked at, and `-c bogus` fails as
+      `[FATAL] Value bogus is not allowed for argument c(compression-method)`, exit 1, with no
+      output file. `-c none` (946 bytes for a two-file tree), `-c lz4`, `-c lz4hc`, `-c zlib` and
+      `-c zlibfast` each wrote a package. An earlier wording's `--compression` spelling was the
+      review's shorthand, not the CLI's; corrected in the claim."
+  - id: bg3.toolchain.lslib-formats.bg3-uses-lsx-v4-and-lsf-verbg3patch3
+    claim: For Game.BaldursGate3, LSLib's own per-game version tables select LSXVersion.V4 (the LSX
+      schema variant that "Replaces type IDs with type names") and LSFVersion.VerBG3Patch3 (0x07) —
+      both distinct from the D:OS 2 values (LSXVersion.V3 = 3; LSFVersion.VerExtendedNodes = 0x03)
+      that Divine would pick for -g dos2 or -g dos2de instead of -g bg3.
+    status: verified
+    source: Norbyte/lslib@6f5f698 LSLib/LS/Enums/Game.cs:33-44 (LSFVersion switch) and :46-62
+      (LSXVersion switch); LSLib/LS/Enums/LSFVersion.cs:51-62 (LSXVersion V3/V4 with the "Replaces
+      type IDs with type names" comment), :18-38 (VerExtendedNodes 0x03 through VerBG3Patch3 0x07)
+    tags:
+      - divine
+      - lsx
+      - lsf
+      - version
+      - bg3
+      - lslib
+    detail: LSFVersion.VerBG3Patch3 is described in the enum's own doc comment as "BG3 Patch 3 version
+      with unknown additions" — LSLib's own author does not know what changed in that revision, only
+      that BG3's current release build needs it. MaxReadVersion and MaxWriteVersion are also both
+      0x07 in this LSLib checkout, so this is the newest LSF revision the tool can produce.
+  - id: bg3.toolchain.lslib-formats.bg3-release-pak-is-packageversion-v18
+    claim: "Divine's -g bg3 selects PackageVersion.V18 (\"BG3 Release\") for create-package, distinct
+      from the BG3 Early Access versions the same enum also names: V15 (\"BG3 EA\") and V16 (\"BG3
+      EA Patch4\")."
+    status: verified
+    source: Norbyte/lslib@6f5f698 LSLib/LS/Enums/PackageVersion.cs:5-12 (enum comments);
+      LSLib/LS/Enums/Game.cs:28 (PAKVersion switch, BaldursGate3 -> V18)
+    tags:
+      - divine
+      - pak
+      - packageversion
+      - bg3
+    detail: "Inference, not in the source: a pak built with an EA-era divine.exe or against the wrong -g
+      value would therefore carry a different package-version header. The enum and the switch are
+      all the cited source shows."
+  - id: bg3.toolchain.lslib-formats.pak-max-size-4gb-at-v16-plus
+    claim: LSLib's own MaxPackageSize table caps a package at 0x40000000 (1 GiB) for PackageVersion V15
+      and below, but 0x100000000 (4 GiB) for V16 and above — since BG3's release paks are V18 (see
+      bg3.toolchain.lslib-formats.bg3-release-pak-is-packageversion-v18), a single BG3 pak's
+      practical ceiling in this tool is 4 GiB, not 1 GiB.
+    status: verified
+    source: Norbyte/lslib@6f5f698 LSLib/LS/Enums/PackageVersion.cs:9-11,20-30 (MaxPackageSize)
+    tags:
+      - divine
+      - pak
+      - packageversion
+      - size-limit
+      - packaging
+    detail: "Merged 2026-09-08 from the duplicate bg3.paks.practical-size-ceiling-is-4gib-not-1gib
+      (deleted), which restated this for the packaging topic: relevant when deciding whether a large
+      asset set (many high-res textures, several custom meshes) needs splitting across multiple
+      paks, and what ceiling ModWright's own pak-size validation should use for BG3."
+  - id: bg3.toolchain.lslib-formats.package-crc-only-v10-through-v16
+    claim: LSLib's HasCrc predicate is true only for PackageVersion V10 through V16 inclusive — BG3's
+      release package version (V18) is outside that range, so a BG3 release pak carries no per-file
+      CRC the way a D:OS 2 or BG3 EA pak would.
+    status: verified
+    source: Norbyte/lslib@6f5f698 LSLib/LS/Enums/PackageVersion.cs:9-11 (V18 = BG3 Release), :15-18
+      (HasCrc)
+    tags:
+      - divine
+      - pak
+      - crc
+      - packageversion
+      - integrity
+      - packaging
+    detail: "Merged 2026-09-08 from the duplicate bg3.paks.release-pak-carries-no-per-file-crc
+      (deleted). Its extra consequence is this project's own conclusion, not something the enum
+      states: a corruption check on a BG3 release pak cannot rely on a per-file checksum stored in
+      the package and must compare against an external manifest (e.g. ModWright's build manifest) or
+      re-read the pak's listing."
+  - id: bg3.toolchain.lslib-formats.loca-binary-layout
+    claim: The compiled .loca binary format is a 12-byte header (Signature uint32 'LOCA' = 0x41434f4c,
+      NumEntries uint32, TextsOffset uint32) followed by one fixed-size entry record per handle (a
+      64-byte Key buffer, then a uint16 Version, then a uint32 Length), with the actual text bytes
+      stored afterward starting at TextsOffset. LSLib's reader throws "Incorrect signature in
+      localization file" if the magic doesn't match.
+    status: verified
+    source: Norbyte/lslib@6f5f698 LSLib/LS/Localization.cs:5-13 (LocaHeader), :16-42 (LocaEntry), :75-80
+      (signature check)
+    tags:
+      - localization
+      - loca
+      - binary-format
+      - lslib
+    related:
+      - id: bg3.loca.xml-location-and-format
+        detail: Adds the binary layout underneath the already-verified .xml-to-.loca compile step; explains
+          why the 64-byte Key field below matters.
+  - id: bg3.toolchain.lslib-formats.loca-key-64-byte-buffer
+    claim: A .loca entry's Key field is a fixed 64-byte buffer (KeyString reads it back up to the first
+      NUL and writes it by copying the UTF-8 bytes into a freshly zeroed 64-byte array); the setter
+      performs no length check, so a handle whose UTF-8 encoding exceeds 64 bytes makes convert-loca
+      throw and leaves a truncated .loca behind. A handle of exactly 64 bytes round-trips intact.
+    status: verified
+    verified_on: LSLib divine build dated 2026-01-24 (no --version flag), 2026-09-09
+    source: Norbyte/lslib@6f5f698 LSLib/LS/Localization.cs:16-42 (LocaEntry.Key, KeyString getter/setter)
+    tags:
+      - localization
+      - loca
+      - handle
+      - buffer-limit
+    detail: "Inferred from the struct layout ([MarshalAs ... SizeConst = 64]) and the setter's
+      unconditional `Array.Copy(bytes, Key, bytes.Length)`. Checked against the source (2026-09-08):
+      an earlier wording said such a handle \"will be silently truncated or corrupted\". Nothing in
+      the source supports \"silently\" — an over-long copy into a 64-byte destination is the case
+      .NET's Array.Copy raises on, so a throw is at least as likely as truncation. Machine run
+      2026-09-09 settled it: `divine -g bg3 -a convert-loca` on an XML whose contentuid is 65 ASCII
+      characters prints `[FATAL] Failed to convert localization file: Destination array was not long
+      enough. Check the destination index, length, and the array's lower bounds. (Parameter
+      'destinationArray')`, exit code 102, and leaves a 12-byte .loca (header only) at the
+      destination — a throw, not silent truncation, but the partial output file is still written. 63
+      and 64 characters both convert (90-byte .loca) and read back with the full handle, so the
+      boundary is \"more than 64 bytes\", not \"reaches 64\". A standard BG3 handle (\"h\" +
+      UUID-with-g-separators, 33 characters) is far under the limit; the risk is only a
+      hand-authored non-standard handle name."
+  - id: bg3.toolchain.lslib-formats.build-vt-uses-source-not-destination
+    claim: For divine.exe's build-vt action, the --source argument is read as the virtual-texture config
+      path and a separate --vt-root argument supplies the VT root path; unlike every other action,
+      build-vt does not read a --destination argument at all (DestinationPath is only assigned when
+      the action is not list-package or build-vt).
+    status: verified
+    source: Norbyte/lslib@6f5f698 Divine/CLI/CommandLineActions.cs:100-104 (build-vt reads args.Source
+      and args.VTRoot), :131-135 (SourcePath always; DestinationPath only when the action is neither
+      list-package nor build-vt)
+    tags:
+      - divine
+      - cli
+      - build-vt
+      - virtual-texture

package/knowledge/baldursgate3/toolkit.levels.yaml

@@ -0,0 +1,177 @@
+game: baldursgate3
+topic: toolkit.levels
+title: Level creation in the Toolkit — GUI-only scope boundary
+facts:
+  - id: bg3.toolkit.levels.screen-archery-scope-not-gameplay-levels
+    claim: 'The most complete community-tested level-creation tutorial is explicitly scoped to virtual
+      photography: "It is written for virtual photography / screen archery in mind, and it will not
+      cover things you need to know to create actual gameplay levels."'
+    status: community
+    source: wiki.bg3.community/en/Tutorials/Toolkit/Creating-a-new-level §Creating a New Level (opening
+      scope note)
+    tags:
+      - toolkit
+      - level
+      - scope-boundary
+      - gui-only
+    detail: ModWright's own reading of that gap — that new level geometry is Toolkit-GUI-only with no
+      text/LSX-first path documented the way there is for stats or dialogue, so levels are
+      validate-only rather than authorable — comes from ModWright research (its "Level (Toolkit)"
+      coverage row), not a claim the tutorial makes.
+  - id: bg3.toolkit.levels.roottemplate-required-before-placement
+    claim: An object cannot be dragged directly from the Resource Manager onto a level — it must first
+      exist as a RootTemplate (either an existing one, or a new one built for it) before it can be
+      placed; Resource Manager resources and RootTemplates are related but distinct, and only
+      RootTemplates ("Objects" in the level-building sense) are placeable.
+    status: community
+    source: wiki.bg3.community/en/Tutorials/Toolkit/Creating-a-new-level
+    tags:
+      - toolkit
+      - level
+      - roottemplate
+      - gui-only
+  - id: bg3.toolkit.levels.local-template-vs-root-template
+    claim: Once a RootTemplate is placed in a level it becomes a "local template" — an override that can
+      carry per-instance changes (a unique face, armor, or stats) while still inheriting from the
+      shared root; editing the root modifies every local instance that inherits from it and hasn't
+      overridden that field itself.
+    status: community
+    source: docs.baldursgate3.game/index.php?title=Editor:_Navigation §Editing Templates
+    tags:
+      - toolkit
+      - level
+      - roottemplate
+      - local-template
+  - id: bg3.toolkit.levels.override-in-active-mod-required-before-edit
+    claim: 'A vanilla resource must be right-clicked and set to "Override in the Active Mod..." before
+      it becomes editable and is assigned to your mod; when asked "Do you want to keep the same
+      package structure?", select "Yes". Resource properties are then edited through their own
+      resource editors, not the Sidebar: "Properties of resources are not editable through the
+      Sidebar, but through special resource editors."'
+    status: community
+    source: docs.baldursgate3.game/index.php?title=Editor:_Navigation §Resources
+    tags:
+      - toolkit
+      - level
+      - override
+      - gui-only
+  - id: bg3.toolkit.levels.uuid-preferred-over-name-for-lookup
+    claim: Finding objects by UUID (copied via right-click "Copy Value to Clipboard" on a Sidebar
+      property) is preferred over searching by name in the Toolkit's Root Template Manager /
+      Resource Manager, since many unrelated objects can share the same display name while UUIDs are
+      always unique.
+    status: community
+    source: docs.baldursgate3.game/index.php?title=Editor:_Navigation §Editing Templates ("It's usually
+      better to find objects by UUID rather than by name, since many objects can share the same name
+      but their UUIDs will always be different")
+    tags:
+      - toolkit
+      - level
+      - uuid
+      - workflow
+  - id: bg3.toolkit.levels.distant-vs-local-light-probes
+    claim: "A LightProbe is one of two kinds: a Distant probe captures far-away sun/sky lighting and
+      applies to everything within the same LightingResources (a level needs at least one Distant
+      probe); a Local probe only captures nearby lights/objects within its own defined area, any
+      number of which can be placed (including nested inside another probe's area), with the
+      smallest probe's lighting always taking priority where areas overlap."
+    status: community
+    source: wiki.bg3.community/en/Tutorials/Toolkit/Creating-a-new-level
+    tags:
+      - toolkit
+      - level
+      - lightprobe
+      - lighting
+  - id: bg3.toolkit.levels.lightprobe-render-requires-save-and-toggle
+    claim: "A LightProbe's baked HDRI lighting only updates after selecting the LightProbe and toggling
+      \"Infinite Capture\" or \"Enabled\" off and back on (\"I haven't figure out a better
+      consistent way\"), and the rendered HDRI maps are only written when the level itself is saved:
+      \"Whenever you make changes with a probe, you need to save your level in order for the
+      LightProbe to save the rendered HDRI maps\"."
+    status: community
+    source: wiki.bg3.community/en/Tutorials/Toolkit/Creating-a-new-level
+    tags:
+      - toolkit
+      - level
+      - lightprobe
+      - save
+      - gui-only
+  - id: bg3.toolkit.levels.every-lightprobe-renders-per-lightingresource
+    claim: Every LightProbe in a level renders its HDRI capture once per LightingResource referenced by
+      the level's LightingTrigger, so a level with many probes and many LightingResources takes
+      proportionally longer to render — the guide recommends focusing on 1-4 LightingResources while
+      iterating, and only adding additional ones for the final render pass.
+    status: community
+    source: wiki.bg3.community/en/Tutorials/Toolkit/Creating-a-new-level
+    tags:
+      - toolkit
+      - level
+      - lightprobe
+      - performance
+  - id: bg3.toolkit.levels.game-mode-photo-mode-combination-hangs-editor
+    claim: Switching between Game Mode and Editor Mode while Photo Mode is enabled makes the game window
+      unresponsive and forces a level reload; the in-game Main Menu button or loading a savegame
+      while in Game Mode inside the Toolkit similarly forces a force-quit-and-restart of the
+      Toolkit.
+    status: community
+    source: "docs.baldursgate3.game/index.php?title=Editor:_Navigation §Testing While Playing in the
+      Editor (\"Doing so causes the game window to become unresponsive and you'll have to reload the
+      level\"; using the in-game Main Menu button or loading a savegame: \"you'll end up having to
+      force-quit and restart the Toolkit\")"
+    tags:
+      - toolkit
+      - level
+      - game-mode
+      - photo-mode
+      - crash
+      - gui-only
+  - id: bg3.toolkit.levels.editor-camera-escapes-void-spawn
+    claim: A level offset from the world origin can spawn the player character in the void in Game Mode;
+      the documented recovery is switching to the Editor Camera (usable while in Game Mode), flying
+      to the level visually or via known coordinates, then pressing Ctrl+T over walkable terrain to
+      teleport the player character there.
+    status: community
+    source: docs.baldursgate3.game/index.php?title=Editor:_Navigation §Testing While Playing in the
+      Editor ("Remember how the level was offset a bit from the world origin? Well, now we've
+      spawned in the middle of the void and cannot move." — then fly with WASD and "When you've
+      found a bit of good, walkable terrain, hover your cursor over it and press Ctrl+T")
+    tags:
+      - toolkit
+      - level
+      - game-mode
+      - teleport
+      - workflow
+  - id: bg3.toolkit.levels.large-levels-slow-to-load-prefer-smaller
+    claim: Some levels contain many smaller sub-areas nested inside them (e.g. WLD_Main_A bundles the
+      Crashsite, Emerald Grove, Goblin Camp, Underdark, and more) and take proportionally longer to
+      load; loading a smaller, specifically-scoped level (e.g. WLD_Crashsite_D) instead saves
+      loading time while testing.
+    status: community
+    source: docs.baldursgate3.game/index.php?title=Editor:_Navigation §Loading a Level
+    tags:
+      - toolkit
+      - level
+      - load-time
+      - workflow
+  - id: bg3.toolkit.levels.terrain-console-teleport-command
+    claim: The console command TeleportPartiesToLevelWithMovie("YourLevelName","","") is the quickest
+      way to jump directly to a specific level for testing, where YourLevelName is the level's own
+      name, not the Toolkit project's name.
+    status: community
+    source: wiki.bg3.community/en/Tutorials/Toolkit/Creating-a-new-level
+    tags:
+      - toolkit
+      - level
+      - console-command
+      - workflow
+  - id: bg3.toolkit.levels.removing-terrain-material-removes-all-painted-instances
+    claim: '"Removing a material from the terrain panel will remove all instances of that painted
+      material from the terrain" — the removal is retroactive over everything already painted, not
+      just a change to what you can paint next.'
+    status: community
+    source: wiki.bg3.community/en/Tutorials/Toolkit/Creating-a-new-level
+    tags:
+      - toolkit
+      - level
+      - terrain
+      - gotcha