modwright 0.1.0

package/knowledge/cyberpunk2077/tweakdb.melee.yaml

@@ -0,0 +1,352 @@
+game: cyberpunk2077
+topic: tweakdb.melee
+title: Melee attack records, combo mechanics, and per-hit modifiers
+facts:
+  - id: cp2077.tweakdb.melee.attack-lookup-by-state-plus-counter
+    claim: "The engine resolves which attack record to play by concatenating the state name with the
+      current combo counter — GetAttack(StringToName( stateName + IntToString(attackNumber))) — and
+      a missing record is not an error: the lookup simply returns null and the caller's enter
+      condition fails silently."
+    status: verified
+    source: ModWright field verification
+    tags:
+      - tweakdb
+      - melee
+      - attack-record
+      - lookup
+      - silent-failure
+    detail: This is the root mechanism behind the endless-flow bug/feature (see
+      cp2077.tweakdb.melee.missing-final-record-loops-combo-forever) and behind why authoring
+      <ModAttacks>.FinalAttack4 (named MeleeFinalAttack3, since AttacksNumber 4 puts the finisher at
+      counter 3) was required to get a real finisher instead of an infinite loop.
+  - id: cp2077.tweakdb.melee.dormant-fourth-combo-hit-in-all-vanilla-melee
+    claim: "Every vanilla held melee weapon ships with BaseStats.AttacksNumber = 3, so the authored 4th
+      combo-hit records (MeleeComboAttack3 across machete/chainsword/katana movesets — including the
+      machete/chainsword center thrust and the katana's 4th diagonal) exist in the game's data but
+      are dormant: no vanilla weapon's stat allows the state machine to ever reach them. Cyberware
+      weapons (strong arms 5, mantis blades 9) use higher AttacksNumber values, proving the state
+      machine natively supports longer chains."
+    status: inferred
+    source: ModWright research
+    tags:
+      - tweakdb
+      - melee
+      - attacksnumber
+      - dormant-content
+      - combo
+    detail: "A risk the note flags explicitly: authored records existing does not guarantee the
+      corresponding animation clip exists in a given weapon's anim set (later testing found only the
+      katana moveset had a real 4th-slash animation; the rest fell back to a bare left-hand punch —
+      animation content itself is out of scope for this file)."
+  - id: cp2077.tweakdb.melee.missing-final-record-loops-combo-forever
+    claim: If BaseStats.AttacksNumber is set to N and a combo record exists at index N-1 but no final
+      (finisher) record exists at that same index, the finisher's enter condition can never succeed,
+      the combo transition wins by default every time, and IncrementAttackNumber wraps the counter
+      back to 0 once it reaches N — producing an unbreakable light-attack loop with no finisher,
+      stopped only by stamina.
+    status: verified
+    source: ModWright field verification
+    tags:
+      - tweakdb
+      - melee
+      - attacksnumber
+      - combo
+      - infinite-loop
+    detail: Discovered by accident (AttacksNumber 4 on a machete-based weapon with only 3 final records
+      authored), then deliberately fixed for the shipped build by authoring
+      <ModAttacks>.FinalAttack4 so the finisher can enter at counter 3. The unpatched behavior is
+      kept as a documented, unshipped design option for a future no-finisher continuous-combo
+      variant.
+  - id: cp2077.tweakdb.melee.vanilla-infinite-combo-flag-pair
+    claim: "Vanilla has a distinct, runtime-toggleable mechanism for an unending combo, independent of
+      record-shape gaps: CheckIfInfiniteCombo requires BOTH BaseStats.CanWeaponInfinitlyCombo (on
+      the weapon record) and BaseStats.CanMeleeInfinitelyCombo (on the player) to be set; when both
+      are true, CheckIfFinalAttack returns false unconditionally (no finisher, ever) and
+      IncrementAttackNumber wraps the counter to 1 instead of 0."
+    status: inferred
+    source: ModWright research
+    tags:
+      - tweakdb
+      - melee
+      - infinite-combo
+      - status-effect
+      - community
+    detail: 'Wrapping to 1 rather than 0 means combo index 0 plays only once at the very start of a
+      chain (the loop afterward is 1->2->3->1->...), a thinner loop than the accidental record-shape
+      variant, which cycles all four indices (0->1->2->3->0). This is read from vanilla tweak files
+      and scripts, not independently tested — recorded as the documented foundation for a future
+      toggleable "flow state" ability, not as an observed result. (Reclassified from community to
+      inferred: the source is vanilla game data read directly, not a community claim.)'
+  - id: cp2077.tweakdb.melee.attack-records-live-in-per-family-packages
+    claim: Weapon attack records are NOT defined under a generic Attacks.* package; each weapon family
+      has its own package (MacheteAttacks.*, KatanaAttacks.*, ChainswordAttacks.*,
+      TwoHandHammerAttacks.*). Only the truly generic base classes (Slash, QuickMelee, ...) live
+      under Attacks.*. Get the correct record IDs from the base weapon's own `attacks` list in its
+      vanilla tweak file, verbatim.
+    status: inferred
+    source: ModWright research
+    tags:
+      - tweakdb
+      - melee
+      - attack-record
+      - package
+      - naming
+    detail: Cost several launch cycles to learn. Confirms the general TweakDB ground-truth rule
+      (cp2077.process.tweakdb-ground-truth) with a melee-specific gotcha not covered by that fact.
+  - id: cp2077.tweakdb.melee.tweakxl-log-required-after-yaml-changes
+    claim: TweakXL yaml errors (missing record, ambiguous definition) are completely silent in game and
+      only visible in red4ext\plugins\TweakXL\TweakXL-<timestamp>.log; always check that log after
+      any yaml change before concluding a change "did nothing."
+    status: verified
+    source: ModWright field verification
+    tags:
+      - tweakdb
+      - tweakxl
+      - log
+      - debugging
+      - archivexl
+    detail: "Named instance: \"the morning timing yaml's Attacks.* entries never applied\" and the log
+      was the only place that said why. Distinct from the unrelated CET-mod-status log check already
+      recorded as cp2077.packaging.cet-log-checks. Merged from an equivalent fact in the ArchiveXL
+      topic, which extends the same rule to the ArchiveXL side: after any .xl manifest edit, the
+      corresponding ArchiveXL log is the only confirmation that a resource patch, animations entry,
+      factory, localization or streaming block actually registered. The two named TweakXL failure
+      modes are \"record doesn't exist\" (an entirely unapplied edit) and \"Ambiguous definition\"
+      (see cp2077.tweakdb.melee.dotted-path-mod-of-same-file-record-fails)."
+  - id: cp2077.tweakdb.melee.dotted-path-mod-of-same-file-record-fails
+    claim: 'Modifying a record via a dotted path (e.g. Items.<ModWeapon>.attacks: appends) inside the
+      SAME yaml file that first defines that record fails with an "Ambiguous definition" error,
+      caused by declaration ordering; the fix is to put the modification in a second file that sorts
+      alphabetically after the first.'
+    status: inferred
+    source: ModWright research
+    tags:
+      - tweakdb
+      - tweakxl
+      - yaml
+      - ordering
+      - silent-failure
+    detail: 'Recorded pattern: a second, later-sorting file (a "<mod>_patch.yaml") for such appends. `-
+      !append` per-item is confirmed to work fine both inside record definitions and in dotted
+      modifications of existing records.'
+  - id: cp2077.tweakdb.melee.iconic-quality-pattern-confirmed-across-mods
+    claim: "The iconic-scaling pattern of quality: Quality.Random plus
+      Items.CraftableIconicQualityRandomisation appended to statModifierGroups (with
+      Quality.IconicItem appended to statModifiers) is confirmed working identically on a second,
+      independently-built iconic weapon, not just the mod it was first documented on."
+    status: verified
+    source: ModWright field verification
+    tags:
+      - tweakdb
+      - quality
+      - iconic
+      - confirmed
+      - cross-mod
+    detail: "Confirms cp2077.tweakdb.quality-stat-iconic-progression and
+      cp2077.tweakdb.craftable-iconic-quality-randomisation (both originally documented from a
+      ranged weapon mod): the melee mod's weapon record already carried the full iconic scaffold
+      (Quality.Random, IconicWeapon/CraftableIconic tags, Items.Iconic_Melee_Blueprint,
+      Items.Craftable_Iconic_Weapon) with no base-record change needed, unlike the ranged mod, which
+      had to author a custom blueprint for its heavily kitbashed sniper receiver — so the pattern
+      generalizes across weapon type (melee vs. ranged) without modification."
+  - id: cp2077.tweakdb.melee.candropweapon-defaults-off-not-immunity
+    claim: gamedataStatType.CanDropWeapon defaults to 0/false on most NPCs — it is an opt-in vanilla
+      ability flag, not a boss-immunity flag. Gating a custom disarm mechanic on this stat alone
+      will silently do nothing on ordinary NPCs; gate the mechanic on NPCPuppet.IsBoss() instead to
+      exempt bosses specifically.
+    status: verified
+    source: ModWright field verification
+    tags:
+      - tweakdb
+      - melee
+      - disarm
+      - stat
+      - gate
+    detail: "Observed vanilla behaviors once disarm worked: the dropped weapon is a damaged-quality
+      lootable, and NPCs re-equip a backup weapon (kept deliberately as counterplay rather than
+      patched out). A Stagger status effect was added on proc for readability."
+  - id: cp2077.tweakdb.melee.thermal-damage-flag-required-for-burn-application
+    claim: BaseStats.BurningApplicationRate is multiplied by the BaseStats.DealsThermalDamage flag in
+      base_melee's stat calculation (the flag is 0 on machetes by default); a plain additive
+      BurningApplicationRate modifier on a machete-family weapon will never show any burn chance
+      unless DealsThermalDamage is also explicitly set to 1.
+    status: verified
+    source: ModWright field verification
+    tags:
+      - tweakdb
+      - melee
+      - burning
+      - thermal
+      - stat-modifier
+      - silent-failure
+    detail: 'Fix shipped as two appended ConstantStatModifiers: DealsThermalDamage Additive 1, then
+      BurningApplicationRate Multiplier 0.75 (a token quality curve, since per-item proc damage
+      cannot itself be reduced). Ships alongside a parallel BleedingApplicationRate Multiplier 0.5,
+      described as "modest real baselines" the redscript disarm/burn logic stacks larger
+      attack-specific bonuses on top of (+25% light burn, +15% heavy bleed at Legendary).'
+  - id: cp2077.tweakdb.melee.tag-check-required-for-tiered-base-clones
+    claim: "Tiered spawn-preset records built as `$base: Items.<ModWeapon>` clones
+      (Items.<ModWeapon>_T2..T5) get their OWN distinct TweakDBIDs; redscript that gates a behavior
+      on exact TweakDBID equality to the base item silently skips every tiered clone. Use HasTag()
+      on a custom identity tag appended to the base record instead, which all clones inherit."
+    status: verified
+    source: ModWright field verification
+    tags:
+      - tweakdb
+      - melee
+      - tag
+      - tweakdbid
+      - base-clone
+      - silent-failure
+    detail: Both the disarm hook (HitReactionComponent.EvaluateHit) and the bullet deflect hook
+      (DamageSystem.ProcessBulletBlockAndDeflect) check
+      weapon.GetItemData().HasTag(n"<ModWeaponTag>") rather than comparing TweakDBIDs, specifically
+      because of this. The tag is appended once, on Items.<ModWeapon>, and inherited by every $base
+      clone.
+  - id: cp2077.tweakdb.melee.enableadjustingplayerpositiontotarget-lunge-flag
+    claim: enableAdjustingPlayerPositionToTarget on an attack record is the perk-free mechanism (read in
+      meleeTransitions.script:2345) that makes a vanilla blade's STRONG attack close distance to a
+      target; it requires a hostile within roughly 4 m and 10 degrees of the crosshair and does
+      nothing when swung at empty air (vanilla behavior, not a bug). Any light-chain or finisher
+      record can set it to gain the same lunge, since the code path (MeleeFinalAttackEvents.OnEnter
+      -> super.OnEnter, or the combo equivalent) is not exclusive to strong attacks.
+    status: verified
+    source: ModWright field verification
+    tags:
+      - tweakdb
+      - melee
+      - lunge
+      - target-snap
+      - attack-record
+    detail: "Distinct from BaseStats.CanMeleeLeap / the meleeLeap PSM state (which this mechanism is NOT
+      — that state is unreachable from a light chain, demanding a charged-hold release instead).
+      Enabled and tested on the light finisher (<ModAttacks>.FinalAttack4), then deliberately
+      DISABLED there by the author's call: by swing 4 of the light chain the player is already
+      standing on the target, so the gated ~4 m snap rarely fires and adds nothing — not a defect in
+      the mechanism, a mismatch with where the chain puts the player. Re-enabling is one
+      commented-out line. It was then MOVED to the chain OPENER instead: <ModAttacks>.ComboAttack1
+      (counter 0) sets enableAdjustingPlayerPositionToTarget: true, where the ~4 m closing gate
+      actually helps. A companion field, useAdjustmentInsteadOfImpulse (a target-free fixed-metres
+      variant), is explicitly left UNVERIFIED in the yaml — no vanilla record exercises it, and the
+      comment says not to add it without observing it first."
+  - id: cp2077.tweakdb.melee.vanilla-camera-impulse-inert-during-melee-attack
+    claim: Vanilla's generic camera-space movement impulse mechanism does not apply while the player is
+      in a melee-attack state, confirmed by in-game logging; a target-free forward-motion effect
+      during a melee attack cannot rely on that vanilla route and needs a custom implementation
+      instead.
+    status: verified
+    source: ModWright field verification
+    tags:
+      - tweakdb
+      - melee
+      - impulse
+      - lunge
+      - silent-failure
+    detail: "This is why the mod's lunge script exists at all: it reads the cameraSpaceImpulse field
+      itself and hands the state machine an adjustTransform call (the same underlying mechanism as
+      enableAdjustingPlayerPositionToTarget's target-snap), rather than relying on vanilla's own
+      impulse application."
+  - id: cp2077.tweakdb.melee.retiming-preserves-hit-frame-position
+    claim: When re-timing an attack record's startupDuration/activeDuration/ recoverDuration to speed up
+      or slow down a hand-keyed clip, scale ALL the state-time fields (including attackEffectDelay
+      and the attackWindow open/close bounds) by the same factor, so the hit frame and input-buffer
+      windows keep their original frame positions relative to the clip instead of drifting.
+    status: inferred
+    source: ModWright research
+    tags:
+      - tweakdb
+      - melee
+      - timing
+      - attack-record
+      - retiming
+    detail: "Worked example: StrongAttack1's 49-frame clip has phase markers at f~0/f12/f19 (30 fps);
+      durations 0.400/0.233/0.967 scaled by 0.9 keep the hit locked to clip frame 24 while the whole
+      swing plays 10% faster. Reverting is documented as deleting the three durations to restore the
+      pre-scale values (0.8/0.9/1.3/1.65)."
+  - id: cp2077.tweakdb.melee.trailstartdelay-999-disables-swing-trail-per-record
+    claim: Setting an attack record's trailStartDelay to a value larger than the clip's total length
+      (e.g. 999.0) disables the melee swing trail for that specific record without touching any
+      other record or any effect descriptor, because the trail only starts once elapsed state time
+      passes trailStartDelay.
+    status: verified
+    source: ModWright field verification
+    tags:
+      - tweakdb
+      - melee
+      - swing-trail
+      - attack-record
+      - per-record-toggle
+    detail: "Shipped gating (the author's verdict: trail ON only for light 3 and light 4): ComboAttack1,
+      ComboAttack2, StrongAttack1 and StrongAttack2 are pushed to trailStartDelay 999.0 by this
+      mechanism, while ComboAttack3 and FinalAttack4 are left at the inherited working 0.1 delay and
+      show the trail. See cp2077.fx.effects.trail-name-resolved-from-damage-comparison for why the
+      trail needed a separate effect-pairing fix before any of this per-record gating became visible
+      at all."
+  - id: cp2077.tweakdb.melee.deflect-tuning-stamina-and-ricochet
+    claim: "A weapon-specific bullet-deflect rework can independently tune: (a) the per-bullet stamina
+      cost while blocking bullets (vanilla divides StaminaCostToBlock by 2; this weapon divides by
+      4), (b) a quality-scaled chance to ricochet a blocked-but-not-deflected bullet back WITHOUT
+      the Reflexes_Right_Perk_2_1 perk (vanilla requires the perk for any ricochet at all), and (c)
+      a flat damage multiplier on ricocheted damage WITH the perk. All three are implemented as a
+      @wrapMethod(DamageSystem) ProcessBulletBlockAndDeflect override gated on the blocking item's
+      tag."
+    status: inferred
+    source: ModWright research
+    tags:
+      - tweakdb
+      - melee
+      - deflect
+      - bullet
+      - stamina
+      - ricochet
+    detail: "Shipped values: stamina divisor 4.0 (vanilla 2.0); ricochet chance without the perk scales
+      by weapon quality: Legendary/Iconic 0.45, Epic 0.25, Rare 0.10, below-Rare 0.05 (the spec was
+      \"10% at rare, 45% at legendary\"; Epic interpolated). With the perk, ricochet damage is
+      multiplied 1.5x on top of the existing parry bump. The block prerequisite itself (a blade +
+      Reflexes_Right_Milestone_2 level 2) is explicitly kept, not part of this change — see
+      cp2077.tweakdb.melee.tag-check-required-for-tiered-base-clones for the identity-tag gating
+      mechanism this hook reuses. Inferred, not verified: the values are read out of the shipped
+      redscript; the source records no in-game observation of the ricochet rates themselves. The
+      gate in code is blockingItem.GetItemData().HasTag(n\"<ModWeaponTag>\"), despite the header
+      comment's looser \"gated on the blocking item being Items.<ModWeapon>\"."
+  - id: cp2077.tweakdb.melee.finisher-tag-backward-scan-selects-effect
+    claim: finisher.script scans a weapon's tags array BACKWARD and uses the first tag that resolves to
+      a 'playFinisher' game effect; appending a new finisher-identity tag to a weapon's tags list is
+      enough to make it win over an inherited finisher tag (e.g. OneHandBladeFinisher), with no
+      !remove of the inherited tag required.
+    status: inferred
+    source: ModWright research
+    tags:
+      - tweakdb
+      - melee
+      - finisher
+      - tag
+      - scan-order
+    detail: Cited from finisher.script:224-231 in the source mod's own comment. The specific finisher
+      motions this routes to (the mod's own finisher tag and its back variant) are
+      animation-workspot content outside this file's scope; only the generic tag-scan selection
+      mechanism is recorded here.
+  - id: cp2077.tweakdb.melee.iconic-melee-mod-element-is-items-iconicmeleeweaponmodelement
+    claim: The vanilla blueprint element that grants a melee weapon its iconic-mod attachment slot is
+      Items.IconicMeleeWeaponModElement (type ItemBlueprintElement, slot
+      AttachmentSlots.IconicMeleeWeaponMod1), declared in blueprint_elements.tweak beside
+      Items.IconicRangedWeaponModElement (slot AttachmentSlots.IconicWeaponModLegendary), and used
+      by the vanilla melee iconics' own blueprints (Preset_Baseball_Bat_Denny, Preset_Baton_Murphy,
+      Preset_Butchers_Knife_Iconic, Preset_Cane_Fingers and others, each through an inline
+      rootElement child with that slot).
+    status: verified
+    verified_on: "2.31"
+    source: installed Cyberpunk 2077 2.31 tools/redmod/tweaks (blueprint_elements.tweak,
+      melee/presets/*.tweak), via the ModWright vanilla index
+    tags:
+      - tweakdb
+      - melee
+      - iconic
+      - blueprint
+      - attachment-slot
+      - scaffold
+    detail: "Settles the name the new-item-chain scaffold's iconicModElementName input needed for a
+      melee base (its header called it UNCONFIRMED). Not yet seen in game: whether a mod-authored
+      blueprint carrying this element gives a scaffolded melee item a functional iconic slot is the
+      same open question as for the ranged element. One melee mod's iconic instead points blueprint:
+      at the vanilla Items.Iconic_Melee_Blueprint and never clones a blueprint."

package/knowledge/cyberpunk2077/tweakdb.weapons.yaml

@@ -0,0 +1,325 @@
+game: cyberpunk2077
+topic: tweakdb.weapons
+title: Weapon records, damage calibration, and iconic modifiers
+facts:
+  - id: cp2077.tweakdb.slot-part-list-preset-paints-weapon
+    claim: A weapon's visuals can be painted by giving it part records in slotPartListPreset whose
+      appearances carry the custom mesh.
+    status: contradicted
+    source: ModWright research
+    tags:
+      - appearance
+      - visual
+      - slot-part-list-preset
+      - body-part
+      - retracted
+    detail: "This was the mod's v1 belief, and the stale header comment of its tweak yaml still records
+      it (\"Visuals : G-58 Dian part records via slotPartListPreset\"). A complete part chain
+      (Items.<ModWeapon>BodyPart, based on Items.w_smg__kang_tao_dian__rcv1, with
+      appearanceResourceName: <mod>_body resolved through factory_parts.csv to
+      mod\\<modname>\\<mod>_body.app) was authored into slotPartListPreset and had no visual effect
+      at all. It still ships in the yaml, inert. Merged here from a former entities-focused fact,
+      which claimed the same mechanism plus an unsourced \"invisible weapon\" symptom. Superseded by
+      cp2077.tweakdb.weapon-visuals-via-appearanceresourcename."
+  - id: cp2077.tweakdb.weapon-visuals-via-appearanceresourcename
+    claim: Weapon visuals are painted by the weapon-level .app file resolved via the weapon record's
+      appearanceResourceName + the ArchiveXL factory csv, not by slotPartListPreset part
+      appearances.
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - appearance
+      - visual
+      - factory
+      - appearance-resource-name
+      - slot-part-list-preset
+    supersedes: cp2077.tweakdb.slot-part-list-preset-paints-weapon
+    detail: "Items.Preset_<ModWeapon> sets appearanceResourceName: <ModWeapon>_Weapon, which
+      mod\\<modname>\\factory_parts.csv maps to mod\\<modname>\\<mod>_weapon.app. The part chain in
+      slotPartListPreset did nothing until that weapon-level .app existed."
+  - id: cp2077.tweakdb.iconic-blueprint-required-for-mod-slot
+    claim: The IconicWeaponModLegendary attachment slot only exists if the weapon blueprint is an iconic
+      blueprint; on a non-iconic blueprint the slot is absent and the iconic modifier (which carries
+      all the special stats) is silently dropped.
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - blueprint
+      - iconic
+      - attachment-slot
+      - silent-failure
+    detail: The v1 weapon shipped with every iconic stat missing and no error. <ModWeapon>Blueprint is
+      based on Items.Base_Smart_Precision_Sniper_Rifle_NoMuzzle_Blueprint and adds
+      Items.IconicRangedWeaponModElement to rootElement.childElements — that child element is what
+      supplies the iconic mod slot the modifier lives in.
+  - id: cp2077.tweakdb.damage-per-hit-empirical-calibration
+    claim: DamagePerHit must be calibrated empirically by reading the in-game damage panel at each tier;
+      the panel value derives from a DPS/DamagePerHit interplay that no formula in the sources
+      predicts.
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - damage
+      - damage-per-hit
+      - calibration
+      - balance
+      - in-game
+    detail: "Readings on the Ashura base, with modifierType AdditiveMultiplier on
+      BaseStats.DamagePerHit: -0.25 -> 278 at T5; -0.104 -> 333 (the mod's notes: \"calibrated so
+      Tier 5 shows 333 dmg\"). The yaml comment records the arithmetic behind the second value:
+      unpenalized Tier-5 base 371 (443/1.194), 371 x 0.896 = 332. The shipped main file uses -0.104;
+      a balanced variant file uses -0.5, where \"the full burst (2 rounds) totals one vanilla Ashura
+      shot (371): each round lands ~186\"."
+  - id: cp2077.tweakdb.twin-lock-stat-modifiers
+    claim: "Twin smart-lock (both hip and ADS) requires two separate stat modifiers:
+      BaseStats.SmartGunAdsMaxLockedTargets +1 and BaseStats.SmartGunHipMaxLockedTargets +1
+      (modifierType Additive), both on the iconic modifier."
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - smart-weapon
+      - lock
+      - stat-modifier
+      - dual-target
+    detail: The yaml comment records the Ashura stock value as 1 for each (hip and ADS single-target);
+      +1 additive on each yields 2 simultaneous locks. The stock value is an authoring comment, not
+      a measurement.
+  - id: cp2077.tweakdb.burst-fire-true-two-rounds
+    claim: A true 2-round burst (both rounds real, each consuming ammo and able to strike a different
+      lock) is produced by BaseStats.NumShotsInBurst +2 and BaseStats.CycleTime_Burst +0.06
+      (Additive) on the iconic modifier, with TriggerMode.Burst as the weapon's primaryTriggerMode.
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - burst
+      - fire-mode
+      - ammo
+      - cycle-time
+    detail: "Shipped behaviour per the mod's notes: \"fires 2, consumes 2, mag = 2 (twin chambers)\".
+      The +0.06 CycleTime_Burst is the near-simultaneous gap between the paired rounds."
+  - id: cp2077.tweakdb.magazine-capacity-twin-chamber
+    claim: A twin-chamber weapon that empties on one trigger pull needs BaseStats.MagazineCapacity +1
+      (Additive) over the vanilla Ashura base of 1, giving capacity 2.
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - magazine
+      - capacity
+      - twin
+      - chamber
+      - reload
+    detail: The yaml comment records the vanilla Ashura MagazineCapacity as 1 ("loads a single round per
+      reload"); this gun chambers a pair, so one pull empties the magazine and forces a reload.
+  - id: cp2077.tweakdb.headshot-multiplier-stat
+    claim: BaseStats.HeadshotDamageMultiplier takes an Additive stat modifier; a ranged weapon mod ships
+      value 2.5.
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - headshot
+      - damage-multiplier
+      - stat
+    detail: "The sources describe the same +2.5 additive two ways: the yaml comment and README call it a
+      \"250% headshot bonus\", the mod's design notes call it \"+400% headshot (+2.5 additive)\". No
+      source states how the engine folds the additive into the final headshot multiplier, so do not
+      quote a total multiplier."
+  - id: cp2077.tweakdb.projectile-velocity-stat
+    claim: BaseStats.SmartGunPlayerProjectileVelocity is the smart-weapon projectile speed stat; the
+      Ashura base is 80 and an Additive +20 takes it to 100.
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - projectile
+      - velocity
+      - stat
+      - smart-weapon
+    detail: The shipped modifier (+20 Additive) is part of the weapon confirmed in game; the base value
+      80 and the resulting 100 come from the yaml authoring comment, not from a reading. The units
+      are not documented in the sources.
+  - id: cp2077.tweakdb.smart-targeting-reticle-size
+    claim: BaseStats.SmartGunTargetingRectangleSizeIncrease is expressed in percent as an Additive
+      modifier; a ranged weapon mod ships value 25 for a +25% smart reticle.
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - smart-weapon
+      - ui
+      - targeting
+      - reticle
+    detail: That the stat is in percent is the yaml comment's statement; only the shipped value (25) and
+      the described effect (+25%) are recorded elsewhere.
+  - id: cp2077.tweakdb.weapon-noise-silencer-stat
+    claim: BaseStats.WeaponNoise Additive -10 is the vanilla SilencerBase value and is what an integral
+      suppressor applies on the weapon.
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - weapon-noise
+      - suppressor
+      - silencer
+      - stealth
+    detail: Applied on the iconic modifier alongside RicochetCount x0. The sources state the value and
+      its vanilla origin, not the detection-range curve it feeds.
+  - id: cp2077.tweakdb.ricochet-count-multiplier-zero
+    claim: BaseStats.RicochetCount with modifierType Multiplier and value 0 removes ricochets; a weapon
+      mod applies it as part of the integral-suppressor stat block.
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - ricochet
+      - suppressor
+      - stat
+    detail: Copied from the vanilla SilencerBase stat set, which pairs WeaponNoise -10 with
+      RicochetCount x0.
+  - id: cp2077.tweakdb.can-silent-kill-on-weapon-record
+    claim: BaseStats.CanSilentKill +1 must sit in the weapon record's own statModifiers, not on the
+      iconic-mod part record, because StealthRunner's detection patch (bug_fixes.reds) falls back to
+      scanning the record's statModifiers.
+    status: inferred
+    source: ModWright research
+    tags:
+      - stealth
+      - silent-kill
+      - stat
+      - iconic-modifier
+      - interoperability
+    detail: A weapon mod places it on Items.Preset_<ModWeapon>, not <ModWeapon>IconicWeaponMod, which
+      the yaml comment says is how Wind (Silent Ashura) stays reliably silent. The placement ships
+      in the working weapon, but no source records testing the part-record placement and observing a
+      failure, so the causal claim is reasoning, not observation.
+  - id: cp2077.tweakdb.quality-stat-iconic-progression
+    claim: "quality: Quality.Random on an iconic weapon is what makes it scale with player level like
+      other iconics; the actual tier is fixed when the item is crafted."
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - quality
+      - iconic
+      - progression
+      - scaling
+    detail: Paired with the tiered craftables Items.$(tier)_<ModWeapon> and their recipes, this is the
+      pattern that gives the level-banded spec drop shipped in the mod's v1.0.0.
+  - id: cp2077.tweakdb.craftable-iconic-quality-randomisation
+    claim: Items.CraftableIconicQualityRandomisation is appended to statModifierGroups on a craftable
+      iconic weapon; a weapon mod ships it alongside quality Quality.Random.
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - crafting
+      - quality
+      - stat-modifier-group
+      - iconic
+    detail: "Appended as `statModifierGroups: [!append Items.CraftableIconicQualityRandomisation]`, with
+      `statModifiers: [!append Quality.IconicItem]` on the same record. The sources state the
+      pairing, not the internal roll mechanics."
+  - id: cp2077.tweakdb.tier-badge-quality-stat-times-two
+    claim: The in-game item tier badge comes from the Quality STAT x 2 (EffectiveTier).
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - quality
+      - tier
+      - badge
+      - visual
+      - stat
+    detail: Read off the in-game item panel while working on tiered weapons. The lesson's other half —
+      that the `quality:` field only seeds loot rolls — is
+      cp2077.tweakdb.quality-field-loot-roll-seed.
+  - id: cp2077.tweakdb.quality-field-loot-roll-seed
+    claim: The `quality:` field on a weapon record only seeds loot rolls; it does not set the displayed
+      tier.
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - quality
+      - loot
+      - recipe
+      - tier
+    detail: "In a weapon mod, crafted tiers come from the tiered craftable records
+      Items.$(tier)_<ModWeapon> (quality: Quality.$(tier)) that the tiered recipes produce, not from
+      Items.Preset_<ModWeapon>'s own Quality.Random."
+  - id: cp2077.tweakdb.weapons.spawned-weapon-itemid-carries-a-seed-so-bare-tdbid-reads-miss-it
+    claim: "A weapon added with Game.AddToInventory(recordId, 1) is present in the inventory, but
+      Game.GetTransactionSystem():GetItemQuantity(player, ItemID.FromTDBID(TweakDBID.new(recordId)))
+      returns 0 and HasItem(...) returns false for it, in the same tick and seconds later: a bare
+      TweakDB id does not identify a spawned weapon instance, whose ItemID carries a per-instance
+      seed. Counting spawned weapons needs an inventory walk, not a TDBID query."
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - tweakdb
+      - weapons
+      - itemid
+      - inventory
+      - cet
+      - eval
+      - read-back
+    detail: The "seed" explanation is the standard one for weapon ItemIDs and is inferred here; the
+      observation is only that the TDBID-based reads miss the spawned item. A CET-side count that
+      walks the inventory was not tried.
+  - id: cp2077.tweakdb.weapons.blueprint-root-restated-with-only-the-iconic-element-yields-no-slots
+    claim: "A project blueprint that $base's a vanilla weapon blueprint and restates rootElement with
+      childElements holding only Items.IconicRangedWeaponModElement (no slot, none of the base
+      root's children) gives the item no attachment slots at all in the weapon modding screen: the
+      base's mod slots are gone and no iconic slot appears either. The restatement replaces the
+      inherited root rather than adding to it."
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - tweakdb
+      - weapons
+      - blueprint
+      - iconic
+      - attachment-slot
+      - scaffold
+    detail: "Answered on 2026-09-12 (the next fact): with the base's slot and children restated beside
+      the iconic element the base's slots come back, and an iconic slot with no part in it is not
+      listed at all. The vanilla index names a root's inline children <root>_inline0/1/2 while the
+      engine flattens them to <blueprint>_inline1/2/3, so a restatement cannot copy the index's
+      inline names verbatim; the blueprint-root lookup renders inline elements as nested mappings
+      instead."
+  - id: cp2077.tweakdb.weapons.restated-root-with-base-children-keeps-base-slots-and-empty-iconic-slot-is-unlisted
+    claim: "A project blueprint that $base's a vanilla weapon blueprint and restates rootElement with
+      the base root's own slot and every child (named elements by name, inline ones as nested
+      slot/childElements mappings) plus Items.IconicRangedWeaponModElement first keeps the base's
+      attachment slots: at the same tier the clone's tooltip lists exactly the slots the vanilla
+      base's tooltip lists (equipped, the clone's panel lists that same single slot; the vanilla was
+      not equipped). Which mod slots appear is gated by tier, not by the blueprint (a Tier 1 vanilla
+      JKE-X2 Kenshin lists only \"Empty Scope Slot\" while a Tier 5 one lists the scope and two mod
+      slots), and the iconic slot the IconicRangedWeaponModElement opens
+      (AttachmentSlots.IconicWeaponModLegendary) is not listed while nothing is attached in it."
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    related:
+      - cp2077.tweakdb.weapons.blueprint-root-restated-with-only-the-iconic-element-yields-no-slots
+      - cp2077.tweakdb.iconic-blueprint-required-for-mod-slot
+    tags:
+      - tweakdb
+      - weapons
+      - blueprint
+      - iconic
+      - attachment-slot
+      - tier
+      - scaffold
+    detail: Showing the iconic slot populated therefore needs an iconic modifier part authored on the
+      element (a <ModWeapon>IconicWeaponMod in its slotPartListPreset), which stays the scaffold's
+      manual step. The Tier 5 control comes from an earlier launch (2026-09-11), the Tier 1 pair
+      from this one (2026-09-12); no tier in between was observed.