modwright 0.1.0

package/knowledge/baldursgate3/stats.spells.yaml

@@ -0,0 +1,293 @@
+game: baldursgate3
+topic: stats.spells
+title: Spell stat fields, reskinning, and spell mechanics
+facts:
+  - id: bg3.spells.using-reskin-idiom
+    claim: The correct spell reskin idiom is using "<VanillaEntry>" plus override only the deltas. This
+      inherits animations, sounds, VFX, flags — everything you don't restate.
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - spells
+      - reskin
+      - using
+      - inheritance
+    detail: Statuses support `using` too (e.g. SHILLELAGH_DRYAD using "SHILLELAGH" restates only
+      Boosts). A child status inherits StackId, flags and groups; restating Boosts REPLACES the
+      whole line — there is no append. Never author a spell without a SpellAnimation or a `using`
+      parent that has one (see bg3.crash.spell-missing-spellanimation).
+  - id: bg3.spells.inherited-tooltip-fields
+    claim: Inherited tooltip fields (via `using`) carry the PARENT's data. TooltipDamageList,
+      DescriptionParams, TooltipUpcastDescriptionParams, and VerbalIntent all inherit. If the reskin
+      changes what the spell DOES, these must be cleared or overridden or the tooltip lies.
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - spells
+      - tooltips
+      - using
+      - inheritance
+      - reskin
+    detail: 'Observed symptoms: a slot-restore spell showed "1~10 Healing"; a Psychic reskin showed
+      "Thunder" upcast. Fix: override TooltipDamageList "", set the right
+      TooltipUpcastDescriptionParams "DealDamage(1d8,<Type>)", and fix VerbalIntent.'
+  - id: bg3.spells.spellsavedc-literal-only
+    claim: "SpellSaveDC() should be treated as taking LITERAL integer arguments only: ceil() and dynamic
+      Level expressions appear in zero vanilla SpellSaveDC usages (all vanilla uses are literal
+      ints), so a dynamic form is unverified engine syntax."
+    status: inferred
+    source: ModWright research
+    tags:
+      - spells
+      - save-dc
+      - conditions
+      - literal
+    detail: To add a scaling DC bonus, distribute hidden SpellSaveDC(1) passives across levels, or swap
+      one passive per tier via PassivesRemoved/PassivesAdded. A class mod ships six such passives
+      granted via PassivesAdded at class levels 1/3/5/7/9/11 — identical numbers to
+      ceil(ClassLevel/2) and multiclass-correct. The passives (not progression Boosts) form was
+      chosen because vanilla never carries SpellSaveDC in progression Boosts.
+  - id: bg3.spells.upcast-variants-auto-linked
+    claim: 'Upcast variants are separate _N entries with using "<base>", data "RootSpellID" "<base>",
+      data "PowerLevel" "N", and a higher UseCosts "...;SpellSlotsGroup:1:1:N". They are
+      auto-linked, NOT list-added: grant only the base and the engine offers the _N children as
+      upcast options.'
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - spells
+      - upcast
+      - variants
+      - powerlevel
+      - slotcosts
+    detail: "Works for Shout summons too, not just damage spells — a class mod's diagnostic proved
+      summon upcast DOES route to the _N child, so the slot→variant mechanism itself works. Two open
+      questions hang off the _N children: whether SpellId() in an OnCast passive sees the child id
+      (bg3.spells.spellid-child-id-risk) and whether a +1-target boost stacks on a child's own
+      AmountOfTargets (bg3.spells.modifynumberoftargets-upcast-stacking)."
+  - id: bg3.spells.spellpowerlevel-reads-1-under-free-cast
+    claim: A free-cast that replaces the spell slot
+      (ModifyUseCosts(Replace,SpellSlotsGroup,0,-1,SpellSlotsGroup), the Arcane-Battery idiom) makes
+      SpellPowerLevel read 1 for EVERY cast, regardless of the upcast level the player picked. The
+      upcast level is carried by the consumed slot; remove the slot and the number that reaches an
+      OnCast passive's functors is 1.
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - spells
+      - free-cast
+      - powerlevel
+      - slot-replacement
+    detail: "What was seen: with the free-cast toggle on, a cast at a L2 slot summoned the level-2 (3d8)
+      weapon and another spell at L2 hit 2 targets — the spell EFFECTS upcast correctly — but
+      DealDamage(SELF, MaxHP*SpellPowerLevel*15/200, Force) dealt only the level-1 amount. Assume
+      the same flattening hides other per-cast level reads under a slot-free cast and verify with a
+      marker. Workaround (Option B): replace the scaling functor with N mutually-exclusive groups,
+      one per slot level, each guarded by IF(SpellId('child_A') or SpellId('child_B') or ...). That
+      workaround's premise is itself unproven — see bg3.spells.spellid-child-id-risk."
+  - id: bg3.spells.spellid-child-id-risk
+    claim: "Unproven: whether SpellId() inside an OnCast passive matches the upcast CHILD id
+      (<ModSpell>_2) or only the root (<ModSpell>). Every per-slot SpellId() enumeration used to
+      work around the flattened SpellPowerLevel depends on it."
+    status: unverified
+    source: ModWright research
+    tags:
+      - spells
+      - upcast
+      - spellid
+      - powerlevel
+      - free-cast
+      - unverified
+    detail: "Why it is in doubt: SpellPowerLevel reading 1 under a slot-free cast proves the engine
+      flattens some per-cast info, so the child id may be invisible too
+      (bg3.spells.spellpowerlevel-reads-1-under-free-cast). Acceptance test from the source: at L4+,
+      with the free-cast toggle on, 27 MaxHP, cast the spell at a L2 slot → expect 4 Force
+      self-damage, not 2. If it is still 2, SpellId() sees only the root and the enumeration fails.
+      Plan B: per-child charges written into each child spell's own SpellProperties, appended to
+      existing effects rather than clobbering them."
+  - id: bg3.spells.modifynumberoftargets-upcast-stacking
+    claim: "Unproven: whether ModifyNumberOfTargets(AdditiveBase,1,false) inside UnlockSpellVariant
+      stacks additively on an upcast child's own AmountOfTargets — i.e. whether child _2 with
+      AmountOfTargets 2 plus a subclass +1 yields 3 targets. Confirm in-engine before relying on the
+      stack."
+    status: unverified
+    source: ModWright research
+    tags:
+      - spells
+      - upcast
+      - targets
+      - unlockspellvariant
+      - subclass
+      - unverified
+    detail: "Acceptance test: cast a multi-target spell at a 2nd-level slot as a level-3 member of a
+      subclass that grants the +1 → expect 3 targets. The mod's testing notes call this
+      make-or-break and document a fallback that was not built. What IS vanilla-attested is the
+      surrounding mechanism: an ARBITRARY SpellId('X') eligibility inside UnlockSpellVariant (Undead
+      Thrall Cursed Tome,
+      UnlockSpellVariant(SpellId('Target_CursedTome_WakeTheDead'),ModifyNumberOfTargets(AdditiveFin\
+      al,1,false)), SharedDev Passive.txt). There is no compound SpellId(A) or SpellId(B) inside one
+      UnlockSpellVariant in vanilla, so enumerate the base AND every upcast _N child separately.
+      AdditiveBase,1 (not AdditiveFinal) matches Sorcerer Twinned / Split-Enchantment."
+  - id: bg3.spells.spellid-guard-check
+    claim: "A hardcoded per-slot SpellId() enumeration silently rots: re-levelling, adding or removing
+      any slot-costed spell must update it or the charge desyncs with zero runtime error. Guard it
+      with a static checker that re-derives the effective UseCosts/RitualCosts set and asserts every
+      slot-costed non-ritual spell appears at its level."
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - spells
+      - powerlevel
+      - checker
+      - automation
+    detail: "A class mod's checker script is the reference implementation; run it before every pack, and
+      have the passive carry a MAINTAINERS comment pointing at it. Inclusion rule for the
+      enumeration: effective SpellSlotsGroup:1:1:N (own UseCosts, else resolved up the `using` chain
+      into vanilla) AND no effective RitualCosts — a ritual casts free via the ritual path the
+      slot-replacement never touches (that mod's lone ritual spell). Base spells that are themselves
+      >L1 must be enumerated at their base level."
+  - id: bg3.spells.level-conditions-in-spellproperties
+    claim: "Default cast-time conditions work in SpellProperties/SpellSuccess IF():
+      IF(ClassLevelHigherOrEqualThan(N,'Class')), IF(CharacterLevelGreaterThan(N)),
+      IF(HasStatus('X',context.Source)) — all evaluate against the CASTER. This is the reliable
+      place for character-level logic."
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - spells
+      - conditions
+      - level
+      - class
+      - spellproperties
+    detail: Contrast with a passive weapon-item status Boosts IF(), where CharacterLevelGreaterThan does
+      NOT resolve the wielder and silently never fires — see
+      bg3.boosts.weapon-level-gating-fails-passive. The spell evaluates in the casting context,
+      where the caster is known.
+  - id: bg3.spells.untilrest-free-cast-pattern
+    claim: "A 1/long-rest innate spell (racial-style, no spell slot) is the AddSpells 6th arg UntilRest:
+      AddSpells(<list>,,<Ability>,,AlwaysPrepared,UntilRest). The spell then casts for free once per
+      long rest, independent of its own UseCosts. Arg slots: (list, selectorId, saveAbility,
+      cooldown, prepareType, replenishType)."
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - spells
+      - free-cast
+      - rest
+      - addspells
+    detail: "Caveat: the granted spell still keeps its own effective UseCosts for other purposes — a
+      reskin `using` a vanilla leveled spell (e.g. Target_Knock = L2 slot) inherits that
+      SpellSlotsGroup, so a slot-cost-scanning check still counts it even though it is cast free via
+      UntilRest. One open question hangs off the grant — see bg3.spells.untilrest-levelup-card."
+  - id: bg3.spells.addspells-autogrant-pattern
+    claim: AddSpells(listUUID,,,,AlwaysPrepared) in a progression Selectors auto-grants a whole spell
+      list at that level with no player pick. SelectSpells(list,pick,...) makes the player choose
+      pick from the list.
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - spells
+      - addspells
+      - selectspells
+      - progression
+    detail: Use AddSpells for "you just get these". Note that a direct AddSpells grant renders no
+      level-up card — see bg3.progressions.addspells-no-levelup-card.
+  - id: bg3.spells.untilrest-levelup-card
+    claim: "Unproven: whether dropping UntilRest from a merged AddSpells grant removes the level-up card
+      the grant otherwise renders automatically. If it does, each granted spell needs pairing with a
+      display-only Highlighted;ForceShowInCC passive to keep its Class Features card."
+    status: unverified
+    source: ModWright research
+    tags:
+      - spells
+      - addspells
+      - untilrest
+      - levelup-card
+      - progressions
+      - unverified
+    detail: "The question arises when a 1/long-rest innate spell is converted to the
+      custom-ActionResource recharge pattern, which drops UntilRest from the grant in favour of an
+      explicit UseCosts token. Acceptance test implied by the source: level a character through the
+      node that carries the merged grant and check whether the granted spell still renders a Class
+      Features card at level-up. The remedy if it does not is the display-only passive described in
+      bg3.progressions.addspells-no-levelup-card."
+  - id: bg3.spells.child-status-inherits-parent-stackid-and-is-replaced-by-it
+    claim: "A StatusData entry that `using`s a vanilla status without restating StackId shares the
+      parent's stack: applying the parent afterwards removes the child (the combat log shows \"lost
+      <child>\" immediately before \"received <parent>\"). A scaffolded or reskinned status that
+      should coexist with its parent needs its own `data \"StackId\"`."
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - statuses
+      - using
+      - stackid
+      - inheritance
+      - scaffold
+    related:
+      - bg3.spells.using-reskin-idiom
+    detail: An earlier application with duration 12.0 was already gone at its first read 27 seconds
+      later, before any BLESS was applied; that is the duration expiring out of combat, not the
+      stack. The engine's StackId semantics (same id replaces) are the vanilla rule; the observation
+      here is that `using` carries the id across.
+  - id: bg3.spells.empty-statuspropertyflags-value-is-a-vanilla-form-and-keeps-the-status-visible
+    claim: '`data "StatusPropertyFlags" ""` is a form vanilla StatusData uses (30 entries carry the
+      empty value in the Patch 8 stats, beside the 622 carrying
+      "DisableOverhead;DisableCombatlog;DisablePortraitIndicator"), the extender reads it back as an
+      empty flag set, and a status written that way shows on the portrait under its own name and
+      writes its "received Condition" line to the combat log.'
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - statuses
+      - statuspropertyflags
+      - scaffold
+      - vanilla-precedent
+    detail: The scaffold's `statusPropertyFlags` input defaults to empty and is written as this line
+      rather than omitted, on the strength of the vanilla count; the two are not known to differ in
+      effect, only the written form was observed.
+  - id: bg3.spells.statuspropertyflags-combatlog-flag-is-spelt-disablecombatlog
+    claim: 'The StatusPropertyFlags value that hides a status from the combat log is DisableCombatlog
+      (lower-case l). "DisableCombatLog" is not recognised: a status carrying
+      "DisableCombatLog;DisableOverhead;DisablePortraitIndicator" still wrote "received Condition"
+      lines to the combat log.'
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - statuses
+      - statuspropertyflags
+      - combat-log
+      - spelling
+      - scaffold
+    detail: "Whether the engine drops the whole flags string or only the unknown token was not
+      separated: the overhead text was not watched for, and by the time the portrait was read the
+      status had already been replaced by its parent, so DisableOverhead and
+      DisablePortraitIndicator are untested here."
+  - id: bg3.spells.createexplosion-projectile-needs-a-donor-with-a-rendering-effect-chain
+    claim: "A Projectile entry written from scratch (no `using`) and fired through CreateExplosion(...)
+      deals its damage silently: no effect, no sound. Basing it on Projectile_Fireball (`using
+      \"Projectile_Fireball\"` with SpellRoll/SpellSuccess/SpellFail/UseCosts blanked and
+      SpellProperties, ExplodeRadius and TargetConditions overridden) keeps Fireball's CastSound and
+      HitEffect — the recipe a class mod's explosion spell uses, the one CreateExplosion chain
+      confirmed to render. Not every projectile renders through CreateExplosion (a biped Steel
+      Watcher attempt in that mod did not)."
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - spells
+      - projectile
+      - createexplosion
+      - vfx
+      - fireball

package/knowledge/baldursgate3/stats.weapons.yaml

@@ -0,0 +1,210 @@
+game: baldursgate3
+topic: stats.weapons
+title: Custom summoned weapons, damage scaling, actions, and properties
+facts:
+  - id: bg3.weapons.summoned-custom-recipe
+    claim: "To summon a weapon with custom damage TYPE you need a custom Weapon stat + a custom
+      RootTemplate (no boost can change base damage type). The template is authored at
+      Public/<Mod>/RootTemplates/_merged.lsx and shipped as _merged.lsf; the weapon stat lives in
+      Public/<Mod>/Stats/Generated/Data/Weapon.txt. Two-way link: the template's Stats field points
+      at the weapon stat, the weapon stat's RootTemplate points at the template UUID."
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - weapons
+      - summoned
+      - custom
+      - roottemplate
+      - damage-type
+    detail: "Recipe: (1) extract a vanilla weapon's GameObject from a pak's
+      Public/<Mod>/RootTemplates/_merged.lsf (the weapon STAT tells you which mod dir), convert to
+      lsx, grep the template UUID, copy that one <node id=\"GameObjects\"> block. (2) Author your
+      template wrapped in <save><region id=\"Templates\"><node id=\"Templates\"><children>, changing
+      MapKey (new UUID), Name and Stats; REUSE the vanilla VisualTemplate, PhysicsTemplate, Icon and
+      Bounds for a placeholder look. Convert lsx→_merged.lsf and ship only the .lsf. (3) Weapon
+      stat: using \"<vanilla base>\", data \"RootTemplate\" \"<template UUID>\", override Damage
+      Type / Damage / DefaultBoosts, fresh ValueUUID. (4) Summon:
+      SummonInInventory(<templateUUID>,-1,1,true,true,true,,,STATUS_A,STATUS_B,...) — -1 duration =
+      permanent, and it accepts MULTIPLE trailing statuses (vanilla: ...,PactBlade,PACT_BLADE)."
+  - id: bg3.weapons.pact-blade-pattern
+    claim: PACT_BLADE (SharedDev Status_BOOST) is the canonical "bound weapon" status to model —
+      WeaponProperty(Magical);IntrinsicSummonerProficiency();IntrinsicSourceProficiency();ItemReturnToOwner();
+      Attribute(InventoryBound);WeaponAttackRollAbilityOverride(Charisma);CannotBeDisarmed(). Omit
+      ItemReturnToOwner() if the weapon shouldn't return when thrown.
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - weapons
+      - summoned
+      - boosts
+      - proficiency
+      - disarm
+    detail: Apply it (or a trimmed copy) as a SummonInInventory trailing status. Custom RootTemplates
+      work and don't crash if the structure is valid — the risky-sounding part is routine once you
+      copy a vanilla node.
+  - id: bg3.weapons.summoned-damage-scaling-finicky
+    claim: Scaling a summoned weapon's damage die by slot is finicky. WeaponDamageDieOverride(Nd8) does
+      NOT reliably apply; typeless WeaponDamage(Nd8) silently does NOT register either; only TYPED
+      WeaponDamage(Nd8, <Type>) applies. For a clean single-die display the reliable route is a
+      separate per-slot weapon stat + RootTemplate with the damage baked in, summoned by the
+      matching upcast child.
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - weapons
+      - summoned
+      - damage
+      - scaling
+      - upcast
+    detail: Verbose (6 slot tiers × N elements) but rock-solid and clean — a single die like 3d8 instead
+      of "2d8 + 1d8". A class mod shipped 18 per-slot weapon stats (3 elements × 6 slot tiers) plus
+      18 generated RootTemplates, with all 18 summon children repointed at their per-slot template.
+      The same diagnostic confirmed summon upcast DOES route to the _N child, so the slot→variant
+      mechanism itself works.
+  - id: bg3.weapons.charisma-attack-roll-override
+    claim: WeaponAttackRollAbilityOverride(Charisma) makes attacks use CHA to-hit. BG3 then adds that
+      same ability modifier to DAMAGE automatically (like a pact weapon) — you get CHA-to-damage
+      "for free" and must BlockAbilityModifierDamageBonus() to suppress it.
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - weapons
+      - charisma
+      - attack-roll
+      - ability-modifier
+    detail: WeaponAttackRollAbilityOverride(SpellCastingAbility) also exists (uses the class's
+      spellcasting ability), and WeaponEnchantment(N) = "+N weapon" (visible +N to hit/damage AND
+      counts as magical). A class mod suppresses CHA-to-damage on the S1–S3 slot tiers with
+      BlockAbilityModifierDamageBonus() and leaves it active S4+, because character level cannot be
+      read in weapon boosts.
+  - id: bg3.weapons.weapon-actions-from-stat-unlocks
+    claim: Weapon actions (Flourish, Piercing Strike, Pommel Strike, Whirlwind…) are added via the
+      weapon stat's BoostsOnEquipMainHand "UnlockSpell(<actionSpell>)". Default weapon actions come
+      from the weapon TYPE, not the stat, and setting BoostsOnEquipMainHand REPLACES the
+      type-default action set.
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - weapons
+      - actions
+      - unlockspell
+      - boosts
+    detail: The earlier belief that BoostsOnEquipMainHand only ADDS and that removing type defaults
+      needs Script Extender was WRONG for this case. To curate a weapon's actions, list exactly the
+      ones you want; the type defaults drop. To KEEP some standard actions, re-list them
+      (UnlockSpell(Target_PommelStrike);UnlockSpell(Rush_SpringAttack); UnlockSpell(<custom>)) —
+      which is exactly what vanilla magic weapons do. Whirlwind = Shout_MAG_WhirlwindAttack (using
+      Shout_Whirlwind, IsDefaultWeaponAction, short-rest recharge).
+  - id: bg3.weapons.reach-is-weapon-property
+    claim: Reach (Glaive/Halberd/Pike) is a "Weapon Properties" entry on the stat, NOT a boost — so
+      extended reach requires editing the weapon stat's properties, i.e. a custom weapon stat.
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - weapons
+      - reach
+      - properties
+    detail: A class mod added Reach to its weapon's Weapon Properties
+      ("Finesse;Light;Melee;Dippable;Reach"); reach was confirmed at L2 in a later test batch.
+  - id: bg3.weapons.attack-spell-override
+    claim: A custom basic-attack animation uses AttackSpellOverride(<CustomAttack>,
+      Target_MainHandAttack) in BoostsOnEquipMainHand. Author <CustomAttack> as using
+      "Target_MainHandAttack" and override its SpellAnimation (+ sounds) to the desired motion. It
+      still deals MainMeleeWeapon damage, runs ExecuteWeaponFunctors and dual-wields — a real weapon
+      attack, just re-animated.
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - weapons
+      - animations
+      - attack-override
+      - custom
+    detail: "The mechanism was learned from the Whips Expanded mod (#19277), which uses it to make
+      functional whips with no custom animations, and then re-implemented self-contained: a class
+      mod's own attack spell copies the whip SpellAnimation and ThornWhip sounds (vanilla animation
+      UUIDs, so no dependency on their spell entry). Caveat: AttackSpellOverride basic attacks run
+      the override's mechanics but fire NONE of its cast VFX/animation — only a real cast (an
+      UnlockSpell'ed action) plays those."
+  - id: bg3.weapons.custom-equipment-type
+    claim: A custom EquipmentType (Public/<Mod>/EquipmentTypes/EquipmentTypes.lsx, region
+      EquipmentTypes) defines idle/sheath handling and the fallback animation set via
+      WeaponType_OneHanded (Slashing1H, Sling1H = the throw/whip look, …) plus sheath bones
+      (Dummy_Sheath_Hip_L for hip). A weapon's RootTemplate points at it via EquipmentTypeID (the
+      type's UUID).
+    status: community
+    source: https://www.nexusmods.com/baldursgate3/mods/19277
+    tags:
+      - weapons
+      - equipment-type
+      - animation
+      - sheath
+    detail: A class mod consumed Whips Expanded's EquipmentTypeID (e9b4ae39) on all 18 of its weapon
+      templates for testing and wrote its own drop-in stub (UUID
+      30d6bb2d-327d-5270-94d1-1ff1e50d296f), but its notes record swapping to that own EquipmentType
+      as the "ONLY BEFORE-RELEASE ITEM LEFT" — so authoring and loading a mod's own EquipmentType
+      was never observed here. Referencing an external one also creates a hard load-order dependency
+      (see bg3.loadorder.external-guid-dependencies).
+  - id: bg3.weapons.no-new-base-weapon-type
+    claim: 'There is no new base weapon TYPE in BG3, but you can fake one: whips use Proficiency Group
+      "Flails;SimpleWeapons", Weapon Properties "Finesse;Reach;Melee;Dippable", a custom
+      EquipmentType for handling, and AttackSpellOverride for the lash. That is the whole "whip" —
+      an existing proficiency + a re-animated attack + a model/EquipmentType.'
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - weapons
+      - proficiency
+      - properties
+      - custom
+    detail: BG3 has no whip weapon type and no whip animations — a whip model swings on a finesse-weapon
+      animation set. A brand-new MODEL (not a reskin) is a Blender→GR2 job in BG3's own GR2 flavour,
+      a separate and much larger effort. The EquipmentType half of this recipe is the part not
+      proven here — see bg3.weapons.custom-equipment-type.
+  - id: bg3.weapons.weapon-category-gated-equipment-bonus
+    claim: IF(IsWeaponOfProficiencyGroup('Flails', GetAttackWeapon()) and
+      IsMeleeWeaponAttack()):RollBonus(Attack, 1) in an equip passive's Boosts WORKS, despite having
+      no vanilla precedent — vanilla only ever uses IsWeaponOfProficiencyGroup in spell/interrupt
+      conditions and ships zero weapon-category attack items.
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - weapons
+      - equipment
+      - proficiency-group
+      - conditions
+      - bonus
+    detail: "Group string = the Proficiency Group value; pipe-separated multi-group works in the vanilla
+      spell usages ('Clubs|Quarterstaffs'). Unattested tokens like this one are exactly the case for
+      pairing a diagnostic with the first attempt (see bg3.practice.unproven-token-verification).
+      Note a conflicting note in the same source: an earlier design note records the gloves' LOOK as
+      verified but the \"+1 mechanic still untested\"; a later distillation states the mechanic as
+      verified in-game."
+  - id: bg3.weapons.proficiency-on-the-weapon
+    claim: 'A weapon can grant its own proficiency: data "Boosts" "Proficiency(Glaives)" on the Weapon
+      stat (vanilla WPN_Glaive_Pact does exactly this), and/or an equip passive whose Boosts carry
+      "Proficiency(...)" plus a Highlighted card (vanilla MAG_OfArchery_Gloves_Passive:
+      Proficiency(Longbows);Proficiency(Shortbows)). Proficiency(<group>) takes the Proficiency
+      Group name.'
+    status: unverified
+    source: ModWright research
+    tags:
+      - weapons
+      - proficiency
+      - boosts
+      - passive
+      - equipment
+    related:
+      - id: bg3.weapons.no-new-base-weapon-type
+        detail: The group name in Proficiency(<group>) is the same Proficiency Group value that fact uses.
+    detail: The stat-side Boosts route needs no passive and no card; the passive route is what vanilla
+      uses when the proficiency should be visible in the tooltip. Either way the token is the
+      Proficiency Group (Glaives, Longbows, ...), not the weapon stat name.