modwright 0.1.0

package/knowledge/cyberpunk2077/entities.appearance.yaml

@@ -0,0 +1,166 @@
+game: cyberpunk2077
+topic: entities.appearance
+title: Entity and appearance files structure, resolution, and inheritance
+facts:
+  - id: cp2077.entities.entity-appearance-chain
+    claim: An entity file (.ent) references an appearance file (.app) via the appearance field; the
+      appearance file defines the submesh layout and material assignments for a given entity
+      appearance, while the entity file contains the interaction chunk and properties.
+    status: inferred
+    source: ModWright research
+    tags:
+      - entity
+      - appearance
+      - file-structure
+      - separation
+    detail: cache_case.ent points at cache_case.app through appearanceResource.DepotPath, with
+      appearanceName/name/defaultAppearance all "default". The loot properties (lootTables,
+      contentAssignment, lootQuality, displayName) are set on the .ent's entity data, not in the
+      .app.
+  - id: cp2077.entities.appearance-submesh-references
+    claim: An appearance file (.app) contains appearances with submesh element references, each pointing
+      to a mesh file path via a slotName; changing which mesh loads for a slot is done in the .app
+      file, not the mesh file.
+    status: inferred
+    source: ModWright research
+    tags:
+      - appearance
+      - mesh
+      - submesh
+      - slot
+      - component
+    detail: "The unit is a named component, not a \"slotName\": cache_case.app's default appearance
+      holds entPhysicalMeshComponent entries named lid, box and handle, each with mesh.DepotPath and
+      meshAppearance. The build script repoints lid -> mod\\<mod>\\meshes\\cache_case_top.mesh and
+      box -> mod\\<mod>\\meshes\\cache_case_bottom.mesh and clones box into a handle component
+      pointing at the vanilla q000__gun_suitcase_handle.mesh."
+  - id: cp2077.entities.appearance-material-assignments
+    claim: Appearance files can assign materials to submeshes either by external reference
+      (preloadExternalMaterials) or by local instance (preloadLocalMaterialInstances); external
+      materials must be loaded from a donor mesh, while locals are editable per appearance.
+    status: verified
+    source: ModWright field verification
+    tags:
+      - appearance
+      - material
+      - external
+      - local
+      - assignment
+      - cooked
+    detail: "The trap the lesson records is the field name: a cooked mesh ignores externalMaterials and
+      reads preloadExternalMaterials. Editable local instances live in
+      preloadLocalMaterialInstances. Learned while editing the case and weapon meshes. This is a
+      CR2W/WolvenKit-side observation, so the in-game verified_on/verified_by that were on it have
+      been removed."
+  - id: cp2077.entities.entity-appearance-factory-resolution
+    claim: Weapon appearance resolution uses weapon record appearance-resource-name field + archivexl
+      factory csv to locate the .app file; the factory maps appearance name strings to absolute mesh
+      file paths, not through the entity system.
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - appearance
+      - factory
+      - resolution
+      - weapon
+      - tweakdb
+    detail: "The field is spelled appearanceResourceName. factory_parts.csv has columns name,path,shared
+      and two rows: <mod>_body -> mod\\<mod>\\<mod>_body.app and <Mod>_Weapon ->
+      mod\\<mod>\\<mod>_weapon.app. It maps to .app resources, not to mesh paths; the .app then
+      names the meshes."
+  - id: cp2077.entities.world-node-position-coordinates
+    claim: World entity node positions are specified as X, Y, Z coordinates in the sector json nodedata;
+      positions are in absolute world units and can be adjusted in build scripts before
+      reserializing.
+    status: inferred
+    source: ModWright research
+    tags:
+      - sector
+      - node
+      - position
+      - coordinate
+      - world
+    detail: "Three different positions appear in the sources and must not be conflated: (-838.7, 324.8,
+      7.9) was the hand-authored guess in the abandoned build; the entSpawner export gave the user's
+      in-game placement (-835.758, 328.628, 7.884), which the sector-building script adopted; and
+      the shipped mod sits at the old Malorian factory site on the City Center NE waterfront, which
+      the mod's README \"Features\" gives as approximately (-836, 329). Its notes add \"Moving the
+      case now = edit X/Y/Z in the sector build script -> rebuild -> repack\"."
+  - id: cp2077.entities.world-node-rotation-quaternion
+    claim: World entity node rotation is specified as a quaternion (k, r, x, y, z values) in the sector
+      json nodedata; the quaternion represents the full 3D rotation and can be adjusted if mesh
+      orientation needs changes.
+    status: inferred
+    source: ModWright research
+    tags:
+      - sector
+      - node
+      - rotation
+      - quaternion
+      - orientation
+    detail: The components are named i, j, k, r (not x, y, z, w). The entSpawner export's placement was
+      i 0, j 0, k 0.75298953056335, r 0.6580325961113. The mod's polish list mentions rotating via
+      the Orientation quaternion in the sector build script "if it clips the wall", so the shipped
+      orientation may differ from the export's.
+  - id: cp2077.entities.case-open-is-entity-state
+    claim: The Malorian cache case rendering open in game means the entity is in an open state, so the
+      fix belongs in the entity's animation or state (the animator).
+    status: contradicted
+    source: ModWright research
+    tags:
+      - animator
+      - case
+      - pose
+      - state
+      - retracted
+      - debugging
+    detail: Several rounds of debugging chased an entity-state bug that did not exist. The meshes ship
+      authored open, exterior-up. Superseded by cp2077.process.case-pose-vs-state-lesson.
+  - id: cp2077.entities.animator-removed-case-closed
+    claim: A gameTransformAnimatorComponent that was originally authored for an entity can be removed
+      from the entity file to disable its animation; removing TransformAnimator from a case entity
+      keeps it permanently closed.
+    status: contradicted
+    source: ModWright research
+    tags:
+      - animator
+      - entity
+      - animation
+      - removal
+      - retracted
+    detail: Removing the animator was the interim architecture while the lid was mis-posed; the shipped
+      v1.0.0 case animates open again, so the removal did not survive. Superseded by
+      cp2077.entities.transform-animator-open-anim.
+  - id: cp2077.entities.transform-animator-open-anim
+    claim: A gameTransformAnimatorComponent can define an animation name (e.g., "open") that drives
+      position/rotation transforms; the animator component contains the animation name and execution
+      parameters.
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - animator
+      - animation
+      - transform
+      - open
+    supersedes: cp2077.entities.animator-removed-case-closed
+    detail: The animation is named "Open" (capital O in the source). Getting it right needed the pivot
+      at the lid's measured back-bottom edge, sunk about 1cm into the rim so the closed pose shows
+      no gap.
+  - id: cp2077.entities.streaming-box-field
+    claim: Sector node nodedata includes a streamingBox field that defines the bounding box for
+      streaming distance calculations; correct streamingBox values ensure entities load/unload at
+      appropriate distances.
+    status: inferred
+    source: ModWright research
+    tags:
+      - streaming
+      - box
+      - distance
+      - nodedata
+      - descriptor
+    detail: 'streamingBox sits on the streamingblock DESCRIPTOR, not on nodeData: the sector-building
+      script sets desc["streamingBox"] to a Box built from BOX_MIN/BOX_MAX, a 300m cube centred on
+      the placement. The per-node nodeData entry has its own Bounds plus MaxStreamingDistance. The
+      values came from the entSpawner export.'

package/knowledge/cyberpunk2077/equipmentex.slots.yaml

@@ -0,0 +1,151 @@
+game: cyberpunk2077
+topic: equipmentex.slots
+title: Equipment-EX outfit slot system
+facts:
+  - id: cp2077.equipment-ex.slots.version-floors
+    claim: Equipment-EX's stated requirements are Cyberpunk 2077 2.2, ArchiveXL 1.18.0+, TweakXL
+      1.10.4+, Codeware 1.13.0+ and redscript 0.5.25+.
+    status: community
+    source: cp2077-equipment-ex README.md, section "Getting Started > Requirements"
+    tags:
+      - equipment-ex
+      - version-floor
+      - archivexl
+      - tweakxl
+      - codeware
+      - redscript
+    detail: Re-verified against the README on the master branch (there is no main branch) on 2026-09-07.
+      The framework floors are on their own numbering and stay in the claim; "Cyberpunk 2077 2.2" is
+      the game's marketing version, and is what this Equipment-EX release targets rather than a
+      version this fact was observed on, so it is not a `verified_on`.
+  - id: cp2077.equipment-ex.slots.placementslots-append-syntax
+    claim: "\"Any item can support one base slot and one outfit slot at the same time.\" The outfit slot
+      is added to `placementSlots` after the base slot with TweakXL's `!append`, e.g.
+      `placementSlots: - !append OutfitSlots.NecklaceShort` on an item whose `$base` is
+      `Items.GenericHeadClothing`; the README shows this as equivalent to spelling out `-
+      AttachmentSlots.Head` and `- OutfitSlots.NecklaceShort`."
+    status: community
+    source: cp2077-equipment-ex README.md, section "Documentation > Compatible items"
+    tags:
+      - equipment-ex
+      - placementslots
+      - append
+      - syntax
+      - tweakxl
+  - id: cp2077.equipment-ex.slots.outfit-slot-is-additive-not-required
+    claim: "\"If user doesn't have Equipment-EX installed, the item will still work with the base slot\"
+      — appending an OutfitSlots entry is therefore safe to ship unconditionally rather than as a
+      hard dependency."
+    status: community
+    source: cp2077-equipment-ex README.md, section "Documentation > Compatible items"
+    tags:
+      - equipment-ex
+      - placementslots
+      - compatibility
+      - optional-dependency
+    detail: The README states the fallback behaviour but not that the extra entry is "inert"; that word
+      was trimmed on 2026-09-07.
+  - id: cp2077.equipment-ex.slots.torso-layer-names
+    claim: Torso outfit slots, in the README's table order, are `OutfitSlots.TorsoUnder` (Bras, Tight
+      Long-sleeves), `TorsoInner` (Tops, T-Shirts, Tight Shirts, Tight Dresses), `TorsoMiddle`
+      (Waistcoats, Blazers, Loose Shirts, Loose Dresses), `TorsoOuter` (Jackets, Coats) and
+      `TorsoAux` (Vests, Harnesses, Puffers).
+    status: community
+    source: cp2077-equipment-ex README.md, section "Documentation > Outfit slots"
+    tags:
+      - equipment-ex
+      - outfitslots
+      - torso
+      - naming
+      - slot-table
+    detail: 'Corrected 2026-09-07: the README describes `TorsoAux` only by purpose; the previous claim
+      that it "stacks independently of the four" is not stated there.'
+  - id: cp2077.equipment-ex.slots.legs-and-body-layer-names
+    claim: "Leg outfit slots are `OutfitSlots.LegsInner` (Tights, Leggings), `LegsMiddle` (Tight Pants,
+      Tight Shorts) and `LegsOuter` (Loose Pants, Loose Shorts, Skirts). A parallel whole-body stack
+      exists: `OutfitSlots.BodyUnder` (Netrunning Suits), `BodyInner` (no purpose listed),
+      `BodyMiddle` (Jumpsuits, Tracksuits), `BodyOuter` (no purpose listed)."
+    status: community
+    source: cp2077-equipment-ex README.md, section "Documentation > Outfit slots"
+    tags:
+      - equipment-ex
+      - outfitslots
+      - legs
+      - body
+      - naming
+      - slot-table
+  - id: cp2077.equipment-ex.slots.paired-left-right-naming
+    claim: "Symmetric body parts get explicit Left/Right slot pairs: `OutfitSlots.EarLeft`/`EarRight`,
+      `EyeLeft`/`EyeRight`, `ShoulderLeft`/`ShoulderRight`, `ElbowLeft`/`ElbowRight`,
+      `WristLeft`/`WristRight`, `HandLeft`/`HandRight`, `FingersLeft`/`FingersRight`,
+      `FingernailsLeft`/`FingernailsRight`, `ThighLeft`/`ThighRight`, `KneeLeft`/`KneeRight`,
+      `AnkleLeft`/`AnkleRight`, `ToesLeft`/`ToesRight`, `ToenailsLeft`/`ToenailsRight`,
+      `HandPropLeft`/`HandPropRight` (props for photo mode). Eyes and hands ALSO have a shared slot
+      alongside the pair — `OutfitSlots.Eyes` and `OutfitSlots.Hands`."
+    status: community
+    source: cp2077-equipment-ex README.md, section "Documentation > Outfit slots"
+    tags:
+      - equipment-ex
+      - outfitslots
+      - naming
+      - left-right
+      - slot-table
+    detail: "Corrected 2026-09-07: the previous claim said symmetric parts are split \"rather than one
+      shared slot\", which the README's own `OutfitSlots.Eyes` and `OutfitSlots.Hands` rows
+      contradict."
+  - id: cp2077.equipment-ex.slots.auto-conversion-table
+    claim: "An item that specifies no outfit slot is auto-assigned one from its base record:
+      `Items.GenericHeadClothing` -> `OutfitSlots.Head`, `Items.Glasses` -> `OutfitSlots.Glasses`,
+      `Items.Visor` -> `OutfitSlots.Glasses`, `Items.GenericFaceClothing` -> `OutfitSlots.Mask`,
+      `Items.GenericInnerChestClothing` -> `OutfitSlots.TorsoInner`,
+      `Items.GenericOuterChestClothing` -> `OutfitSlots.TorsoOuter`, `Items.GenericLegClothing` ->
+      `OutfitSlots.LegsMiddle`, `Items.Skirt` -> `OutfitSlots.LegsOuter`,
+      `Items.GenericFootClothing` -> `OutfitSlots.Feet`, `Items.Outfit` ->
+      `OutfitSlots.BodyMiddle`."
+    status: community
+    source: cp2077-equipment-ex README.md, section "Documentation > Auto conversions"
+    tags:
+      - equipment-ex
+      - outfitslots
+      - auto-conversion
+      - default
+      - slot-table
+  - id: cp2077.equipment-ex.slots.new-slot-proposal-rules
+    claim: "Equipment-EX's recommendations for proposing a new slot: \"The purpose of the slot must be
+      clear and distinguishable from other slots\"; \"The slot must represent an area or layer for
+      only one item equipped at a time\"; \"The slot must be named after a body part if possible, or
+      equipment category otherwise\"."
+    status: community
+    source: cp2077-equipment-ex README.md, section "Documentation > Outfit slots" (closing list)
+    tags:
+      - equipment-ex
+      - outfitslots
+      - naming-rule
+      - contribution
+  - id: cp2077.equipment-ex.slots.outfit-mode-overlays-not-reequips
+    claim: Clicking an item in the Wardrobe UI "will activate outfit mode, which applies the visuals of
+      the selected items to your character over equipped gear" — the overlay is visual and sits on
+      top of what is actually equipped. It is turned off by selecting "No outfit" or unequipping the
+      outfit from the Inventory menu.
+    status: community
+    source: cp2077-equipment-ex README.md, section "Getting Started > How to use"
+    tags:
+      - equipment-ex
+      - outfit-mode
+      - wardrobe
+      - visual-only
+    detail: The Wardrobe is reached "through the new 'Wardrobe' button in the Inventory menu or from
+      wardrobe call in V's apartments"; photo mode exposes outfit switching in the pose section. The
+      README says the overlay applies visuals; it does not comment on stats, so that wording was
+      trimmed on 2026-09-07.
+  - id: cp2077.equipment-ex.slots.translation-template-path
+    claim: Localization contributions start from the template `support/localization/lang.json.json` in
+      the repo; the instruction is to "translate all `femaleVariant` values" and keep the
+      translation as close to the English version as possible.
+    status: community
+    source: cp2077-equipment-ex README.md, section "Translations"
+    tags:
+      - equipment-ex
+      - localization
+      - translation
+      - file-path

package/knowledge/cyberpunk2077/fx.effects.yaml

@@ -0,0 +1,246 @@
+game: cyberpunk2077
+topic: fx.effects
+title: Particle effects, effect descriptors, and melee swing trails
+facts:
+  - id: cp2077.fx.effects.placement-info-named-tag-required
+    claim: On a custom melee weapon's .app, an entEffectDesc only places its particles correctly when it
+      uses worldCompiledEffectInfo placementInfos + placementTags naming an actual bone tag (e.g.
+      "base", the weapon's base bone); untagged placement (placementTagIndex 255, i.e. the weapon
+      root) resolves to nothing on this app even though the identical untagged pattern works on the
+      katana's own, much richer app.
+    status: verified
+    source: ModWright field verification
+    tags:
+      - fx
+      - effect-desc
+      - placement
+      - tag
+      - silent-failure
+    detail: "Three earlier no-ops (documented in the mod's build scripts) had already proven neither
+      compiledEffectInfo componentIndexMask nor the effect's own trackGroup componentName places
+      particles here. The chainsword's vanilla blood_dripping desc revealed the real mechanism:
+      placementInfos + placementTags + relativePositions in worldCompiledEffectInfo, selected per
+      event via placementIndexMask, offset relative to the named tag. A first version of the trail
+      script copied the katana's trail desc verbatim (placementTagIndex 255, flags 9) and rendered
+      nothing; v2 mirrored the app's OWN working idle_thermal desc (placementTags [\"base\"],
+      placementTagIndex 0, flags 3) and worked. Rule recorded for this app: copy the placement shape
+      of idle_thermal, never a donor weapon's own desc."
+  - id: cp2077.fx.effects.relative-rotation-placement-quaternion
+    claim: Each placementInfo in compiledEffectInfo carries a relativeRotationIndex pointing into a
+      separate relativeRotations[] array of quaternions; this is the per-placement rotation knob for
+      an effect desc, and it is exploited on a custom weapon's idle_thermal desc to flip the far
+      horn's placement 180 degrees about local Z.
+    status: inferred
+    source: ModWright research
+    tags:
+      - fx
+      - effect-desc
+      - placement
+      - rotation
+      - quaternion
+    detail: compiledEffectInfo.placementInfos[].relativeRotationIndex ->
+      compiledEffectInfo.relativeRotations[] (Quaternion). idle_thermal's far horn placement carries
+      (0,0,1,0), a 180 degree spin about local Z, to flip its drift inward. The knob is real and in
+      active use — see cp2077.fx.effects.world-space-vectors-ignore-placement-rotation for why it
+      cannot fix every orientation problem.
+  - id: cp2077.fx.effects.world-space-vectors-ignore-placement-rotation
+    claim: A particle emitter's velocity/acceleration initializers set with worldSpace = 1 are evaluated
+      in world space; rotating the effect desc's placement quaternion (relativeRotationIndex) cannot
+      redirect them, because the placement rotation only affects local-space vectors.
+    status: inferred
+    source: ModWright research
+    tags:
+      - fx
+      - particle
+      - world-space
+      - rotation
+      - orientation
+    detail: "w_mantisblades_idle_thermal.effect's \"smoke\" event
+      (w_mantisblades_idle_thermal_sparks.particle) sets BOTH CParticleInitializerVelocity (+Z,
+      0.25..0.5) and CParticleModificatorAcceleration (direction +Z) with worldSpace = 1 on both
+      modules, so the particles rise straight up in world space no matter how the placement is
+      rotated. Correct for vertical mantis arm blades, visibly wrong for a crescent held horizontal.
+      The companion haze event has no velocity initializer, only a world-space acceleration, so it
+      is a pure distortion field and reads fine from any angle. CLOSED 2026-09-03: the user verified
+      in game that the smoke reads fine once 1b's placement fix landed, so this was never actually
+      re-fixed via option A (local-spacing a cloned particle) or option B (masking the sparks event
+      off) — recorded because it explains the mechanism, not because a fix shipped."
+  - id: cp2077.fx.effects.per-event-placement-index-mask
+    claim: A single entEffectDesc can place its several particle events at different placementInfos
+      independently, by giving each event its own placementIndexMask bit rather than sharing one
+      mask across all events.
+    status: inferred
+    source: ModWright research
+    tags:
+      - fx
+      - effect-desc
+      - placement-mask
+      - event
+    detail: "Vanilla's reflected_bullet_sparks desc proves the mechanism works. A custom weapon's own
+      idle_thermal desc does NOT use it: both its haze and sparks events currently run
+      placementIndexMask 3 (both placements), which is why the far-horn placement fix also moved the
+      haze (see cp2077.fx.effects.relative-rotation-placement-quaternion's parent finding) — an
+      available lever the mod does not currently pull."
+  - id: cp2077.fx.effects.heat-haze-hypothesis-shader-pass
+    claim: The thermal blade's heat haze is most likely a pass of the multilayer_blackbody_inject.mt
+      shader itself (it samples fx_perlin_noise_01_d / fx_perlin_noise_3d_01_d across 4 passes), so
+      using that shader on the glow material should produce the haze for free with no separate
+      effect needed.
+    status: contradicted
+    source: ModWright research
+    tags:
+      - fx
+      - heat-haze
+      - shader
+      - hypothesis
+      - retracted
+    detail: "This was the working hypothesis before the haze mechanism was pinned down. It turned out to
+      be wrong: the haze is a particle effect, not a shader pass. Superseded by
+      cp2077.fx.effects.heat-haze-is-a-particle-effect."
+  - id: cp2077.fx.effects.heat-haze-is-a-particle-effect
+    claim: "The thermal weapon heat haze is a PARTICLE effect, not a shader pass: an
+      effectTrackItemParticles track inside a dedicated idle-thermal .effect file, spawning a
+      distortion particle with a refraction shader and a circular-noise distortion texture."
+    status: inferred
+    source: ModWright research
+    tags:
+      - fx
+      - heat-haze
+      - particle
+      - pinned
+    supersedes: cp2077.fx.effects.heat-haze-hypothesis-shader-pass
+    detail: "For the mantis it is the \"Heat_Haze\" particle track inside
+      base\\fx\\weapons\\cyberware\\mantisblades\\idle\\w_mantisblades_idle_thermal .effect, emitter
+      shader base\\fx\\shaders\\simple_refraction.mt + fx_circular_distortion_03_noise_n.xbm, params
+      Refraction/RefractionStrength. The katana has its own separate haze:
+      base\\fx\\weapons\\melee\\katanas\\idles\\w_katana_idle_thermal.effect, spawning
+      w_katana_idle_thermal.particle with the same distortion texture. A custom weapon mod's shipped
+      idle_thermal desc points at the vanilla mantis effect verbatim (see
+      cp2077.fx.effects.placement-info-named-tag-required), not the katana one — two independent
+      vanilla implementations of the same visual idea exist in the game."
+  - id: cp2077.fx.effects.katana-and-mantis-have-separate-heat-haze-effects
+    claim: The katana and mantis-blades families each ship their own, separate idle-thermal haze effect
+      file and particle asset; they are not the same resource reused across weapon types.
+    status: inferred
+    source: ModWright research
+    tags:
+      - fx
+      - heat-haze
+      - katana
+      - mantis
+      - resource
+    detail: "Mantis: w_mantisblades_idle_thermal.effect / w_mantisblades_idle_thermal_sparks.particle.
+      Katana: w_katana_idle_thermal.effect / w_katana_idle_thermal.particle. Both were explored as
+      heat-haze donors for a custom weapon; the shipped weapon grafts the mantis one, per
+      cp2077.fx.effects.heat-haze-is-a-particle-effect."
+  - id: cp2077.fx.effects.effect-desc-handle-wrapped-lists
+    claim: In a custom weapon's .app, entEffectDesc entries are stored HANDLE-WRAPPED ({HandleId, Data})
+      in three separate lists (two compiledData chunks plus the source components[] array), not as
+      bare objects; a script that only checks `i["$type"] == "entEffectDesc"` will find nothing.
+    status: inferred
+    source: ModWright research
+    tags:
+      - fx
+      - effect-desc
+      - handle
+      - json
+      - wolvenkit
+    detail: Appending new descs also perturbs handle order, and WolvenKit's `convert deserialize` FAILS
+      unless every HandleId runs in document-encounter order (the same class of gotcha recorded for
+      sector json — see cp2077.sectors.sector-json-file-uniqueness — but here it is ordering, not
+      uniqueness, that breaks). The fix reuses a `renumber_handles` helper originally written for a
+      finisher routing script; deserialize plus a binary round-trip both pass after renumbering.
+  - id: cp2077.fx.effects.swing-trail-triggered-per-attack-record-timing
+    claim: The melee swing trail (weapon.StartCurrentMeleeTrailEffect / StopCurrentMeleeTrailEffect) is
+      driven purely by per-attack-record timing fields — trailStartDelay and trailStopDelay compared
+      against elapsed state time in meleeTransitions.script — not by animation data; a weapon
+      inherits this triggering for free from its base attack records regardless of whether it
+      declares a trail effect at all.
+    status: inferred
+    source: ModWright research
+    tags:
+      - fx
+      - swing-trail
+      - attack-record
+      - timing
+    detail: A machete-derived weapon's attack records inherit trailStartDelay 0.1 / trailStopDelay 0.4
+      from MacheteComboAttackAbstract / MacheteFinalAttackAbstract, so the engine had been asking
+      for the trail on every swing since the weapon's first build — it simply resolved to nothing
+      because the weapon's .app declared no trail_* effect descriptor at all. The katana's own app
+      declares eight (trail_physical/_npc, trail_thermal/_npc, trail_chemical/_npc,
+      trail_electric/_npc).
+  - id: cp2077.fx.effects.trail-name-assumed-from-thermal-flag
+    claim: Because a custom weapon record (Items.<ModWeapon>) sets BaseStats.DealsThermalDamage and the
+      weapon's own idle_thermal desc visibly renders (which StartIdleMeleeEffect only requests for
+      Thermal-type weapons), the resolved melee damage type must be Thermal, so the swing trail
+      should be requested by the name "trail_thermal".
+    status: contradicted
+    source: ModWright research
+    tags:
+      - fx
+      - swing-trail
+      - damage-type
+      - hypothesis
+      - retracted
+    detail: This chain of reasoning is wrong at the last step and cost three relaunch cycles. Superseded
+      by cp2077.fx.effects.trail-name-resolved-from-damage-comparison.
+  - id: cp2077.fx.effects.trail-name-resolved-from-damage-comparison
+    claim: GetCurrentDamageType() (the value weapon.script actually uses to pick the trail effect name)
+      is resolved by comparing damage STAT VALUES, not by reading the DealsThermalDamage flag; on
+      that weapon it resolves to Physical even though DealsThermalDamage is set, because that flag
+      only gates whether burn status applies, not which damage type the trail system sees.
+    status: verified
+    source: ModWright field verification
+    tags:
+      - fx
+      - swing-trail
+      - damage-type
+      - probe
+    supersedes: cp2077.fx.effects.trail-name-assumed-from-thermal-flag
+    detail: A logging probe (a debug redscript, <Mod>_TrailProbe.reds, deleted before ship) showed 49/49
+      requests for "trail_physical", not "trail_thermal". The fix was to pair `trail_physical ->
+      w_katana_swing_trail.effect` (the working one) and `trail_thermal ->
+      w_katana_thermal_swing_trail.effect` separately, instead of pointing both names at the thermal
+      visual. Confirmed in game on lights 2/3/4 after the pairing fix; the final gating chosen is ON
+      for light 3 and light 4 only (light 1 too subtle, heavies too slow to show the ribbon).
+  - id: cp2077.fx.effects.swing-trail-anchor-glow-arc-midpoint
+    claim: For a crescent-shaped blade, the correct swing-trail placement anchor is the midpoint of the
+      glow arc — the glow-mesh vertex farthest from the chord between the two horn tips — with the
+      perpendicular axis zeroed to center it in the blade's thickness; this is the crescent analogue
+      of the katana's straight-blade anchor point.
+    status: inferred
+    source: ModWright research
+    tags:
+      - fx
+      - swing-trail
+      - placement
+      - measurement
+      - crescent
+    detail: "Measured position (0, 0.2119, 0.2152) — the raw glow vertex is (-0.0112, 0.2119, 0.2152)
+      with X zeroed to centre it in the blade's ~22 mm thickness — 0.286 m of bulge from the chord.
+      Inferred, not verified: the anchor is an offline measurement. The trail carrying it was
+      separately confirmed rendering in game on lights 2/3/4
+      (cp2077.fx.effects.trail-name-resolved-from-damage-comparison), but the ribbon's TILT against
+      the blade plane has never been judged in game. The katana anchors at (0, -0.01, 0.5), out
+      along its straight blade; rotation is left identity (the katana's own trail carries a ~3
+      degree trim quaternion, noted as the knob to use if the ribbon ever reads tilted against the
+      blade plane in game)."
+  - id: cp2077.fx.effects.analytic-camera-projection-for-offline-placement-check
+    claim: Effect-placement offsets can be checked offline without a working render by projecting
+      measured 3D marker positions through the FPP camera analytically (Blender's
+      world_to_camera_view), reading off normalized screen-space x/y; this works even when the
+      render pipeline itself is broken for that scene.
+    status: inferred
+    source: ModWright research
+    tags:
+      - fx
+      - placement
+      - measurement
+      - camera-projection
+      - methodology
+    detail: 'Used to localize the smoke-placement bug precisely: PLACE0 (left) measured 0.0201 right of
+      its glow tip in normalized screen x, PLACE1 (right) measured -0.0508 (fine). The marker render
+      itself came out blank grey (a known silent-grey issue in this preview pipeline, referenced
+      elsewhere as "renders default to FPP camera"); the projection did not depend on the render
+      succeeding, so the fix (pulling PLACE0 1 cm toward the glow centroid, offset dropping to
+      +0.0023) was computed and shipped without needing that render fixed.'