modwright 0.1.0

package/knowledge/cyberpunk2077/toolchain.wolvenkit.yaml

@@ -0,0 +1,163 @@
+game: cyberpunk2077
+topic: toolchain.wolvenkit
+title: wolvenkit cli and mesh import workflow
+facts:
+  - id: cp2077.toolchain.glb-import-ignores-transforms
+    claim: wolvenkit glb import ignores node transforms from the source file;
+      transform_apply(location=True) in blender before export is mandatory to embed transforms in
+      vertex positions.
+    status: verified
+    source: ModWright field verification
+    tags:
+      - mesh
+      - import
+      - glb
+      - blender
+      - transform
+    detail: The export scripts call bpy.ops.object.transform_apply(location=True, rotation=True,
+      scale=True) on every object before joining, and clear armature parents with
+      CLEAR_KEEP_TRANSFORM first so the world transform survives. Without this the imported
+      submeshes land in the wrong place relative to the donor mesh. This is importer behaviour, not
+      an in-game observation.
+  - id: cp2077.toolchain.glb-contains-junk-icosphere
+    claim: Every glb that wolvenkit exports contains a junk 2-meter icosphere that must be deleted in
+      blender before the geometry is exported back and imported by the cli.
+    status: verified
+    source: ModWright field verification
+    tags:
+      - mesh
+      - glb
+      - blender
+      - cleanup
+    detail: "Corrected from the earlier wording, which blamed Blender's exporter: the icosphere arrives
+      in the GLBs WolvenKit exports of the vanilla donor meshes, and both the kitbash and export
+      scripts delete every object whose name contains \"Icosphere\" before doing anything else."
+  - id: cp2077.toolchain.cli-import-flag
+    claim: wolvenkit cli import command uses the `-k` flag to preserve local material edits when
+      importing a glb over an existing donor mesh.
+    status: inferred
+    source: ModWright research
+    tags:
+      - cli
+      - import
+      - materials
+      - flag
+    detail: "Only the flag itself is sourced: -k is the short form of --keep, and both spellings appear
+      in a mod's build scripts. What --keep actually preserves is nowhere stated; the \"preserves
+      the donor's material bindings\" reading is an inference from the copy-donor-then-import
+      pipeline."
+  - id: cp2077.toolchain.cli-convert-serialize
+    claim: wolvenkit cli convert serialize command transforms a cr2w binary mesh file to json format,
+      allowing programmatic field edits before deserializing back to binary.
+    status: verified
+    source: ModWright field verification
+    tags:
+      - cli
+      - convert
+      - serialize
+      - cr2w
+      - json
+    detail: Every scripted asset in a mod's pipeline is authored this way. The json carries a Header
+      (WolvenKitVersion 8.20.0, GameVersion 2310, DataType CR2W) plus Data.RootChunk. This is CLI
+      behaviour, not an in-game observation.
+  - id: cp2077.toolchain.cli-convert-deserialize
+    claim: wolvenkit cli convert deserialize command transforms json back to cr2w binary format after
+      programmatic edits, validating structure before writing.
+    status: verified
+    source: ModWright field verification
+    tags:
+      - cli
+      - convert
+      - deserialize
+      - cr2w
+      - json
+    detail: "Deserialize is the validation gate for hand-edited json — it rejected the ent-derived loot
+      chunk and it is where duplicate BufferIds surface. Its errors can be useless, though: see
+      cp2077.toolchain.redpackage-reader-rejects-unidentified-field."
+  - id: cp2077.toolchain.redpackage-reader-rejects-unidentified-field
+    claim: The RedPackage json reader can reject an instanceData chunk over a field it does not accept,
+      and bisecting the chunk does not necessarily identify which field; the working answer was to
+      adapt a chunk from a known-good sector instead.
+    status: unverified
+    source: ModWright research
+    tags:
+      - cr2w
+      - redpackage
+      - json
+      - deserialize
+      - silent-failure
+      - open-question
+    detail: Open question, deliberately recorded as unresolved. The reference chunk came from a working
+      modded ShardCaseContainer node in AldecaldosHighStakes, saved as a reference container sector
+      json; the mod's build scripts both build the chunk by deep-copying that node's instanceData
+      and overwriting $type, lootTables, lootQuality and containerType, then popping itemTDBID and
+      shardMesh.
+  - id: cp2077.toolchain.cli-extract-vs-uncook
+    claim: wolvenkit cli extract command is used for .app and .ent files (resources); uncook is used for
+      other binary formats. Never uncook .app or .ent files.
+    status: verified
+    source: ModWright field verification
+    tags:
+      - cli
+      - extract
+      - uncook
+      - app
+      - ent
+      - resource
+    detail: The lesson states the rule only; the explanation offered in the earlier version of this fact
+      ("extract preserves cr2w structure, uncook is for general binaries") is not in any source.
+  - id: cp2077.toolchain.mlsetupbuilder-hexkeys
+    claim: WolvenKit's GUI shows only hex lookup keys for mlsetup files, so mlsetup editing is done in
+      MLSetupBuilder or by exporting json with cli serialize, editing, and deserializing back.
+    status: verified
+    source: ModWright field verification
+    tags:
+      - mlsetup
+      - wolvenkit
+      - editor
+      - hex
+      - json
+    detail: Corrected from the earlier wording, which attributed the hex-key limitation to
+      MLSetupBuilder. MLSetupBuilder is a separate tool; it is WolvenKit's GUI that is unusable for
+      this. A tuned mlsetup can be kept as an exported json (an edited .mlsetup.json) and
+      deserialized back when needed.
+  - id: cp2077.toolchain.cr2w-enums-are-strings
+    claim: cr2w json enums are represented as quoted STRING values (e.g. "Always"), not numbers; bare
+      enum names in json are invalid.
+    status: verified
+    source: ModWright field verification
+    tags:
+      - cr2w
+      - json
+      - enum
+      - format
+    detail: "Examples from a mod's own CR2W json: category \"Exterior\", lootQuality \"Legendary\",
+      containerType \"ClothingContainer\", Flags \"Soft\", cookingPlatform \"PLATFORM_PC\". The
+      earlier version of this fact illustrated it with TweakXL yaml (TriggerMode.Burst), which is a
+      different format entirely and not evidence for this claim."
+  - id: cp2077.toolchain.resource-path-shape
+    claim: cr2w resourcepath fields require the exact path shape (e.g., backslashes, no leading slash)
+      and case; wrong paths produce a silent failure at resource resolution time, not at import.
+    status: unverified
+    source: ModWright research
+    tags:
+      - cr2w
+      - resourcepath
+      - path
+      - format
+    detail: "Shipping examples: mod\\<modname>\\meshes\\cache_case_top.mesh,
+      mod\\<modname>\\cache_case.ent,
+      base\\gameplay\\loot\\containers\\common_suitcases\\common_suitcase_small.ent. The failure
+      mode in the claim is untested reasoning."
+  - id: cp2077.toolchain.gameversion-header
+    claim: cr2w json files must include a GameVersion header identifying the engine version the file was
+      created for; missing or incorrect version produces an import error.
+    status: unverified
+    source: ModWright research
+    tags:
+      - cr2w
+      - gameversion
+      - header
+      - format
+    detail: Every CR2W json in the reference mod carries GameVersion 2310, i.e. game 2.31; the CLI
+      writes it on serialize/extract. The "produces an import error" half of the claim is untested.

package/knowledge/cyberpunk2077/tweakdb.loot-recipes.yaml

@@ -0,0 +1,184 @@
+game: cyberpunk2077
+topic: tweakdb.loot-recipes
+title: Loot tables, iconic recipes, and tier-based crafting
+facts:
+  - id: cp2077.loot.iconic-recipe-structure
+    claim: "Iconic weapon recipes follow a canonical structure: a base iconic recipe
+      (Items.Recipe_PresetName) that defines the item, plus five tier-specific variants
+      (Items.Recipe_Common/Uncommon/Rare/Epic/Legendary_Name) each with hideOnItemsAdded set to the
+      tier-specific item to gate visibility."
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - recipe
+      - iconic
+      - tier
+      - gating
+      - visibility
+    detail: "Items.Recipe_Preset_<ModWeapon> ($base Items.IconicRecipe) is the base recipe; the five
+      variants are generated with $instances as Items.Recipe_$(tier)_<ModWeapon>, each with
+      craftingResult.item Items.$(tier)_<ModWeapon> and hideOnItemsAdded:
+      [Items.$(tier)_<ModWeapon>]. The cache grants exactly one spec."
+  - id: cp2077.loot.loot-table-drop-chance-structure
+    claim: "A loot table that must drop exactly one recipe (no randomness between tiers) uses
+      lootGenerationType: dropChance, minItemsToLoot: 1, maxItemsToLoot: 1, with each tier entry
+      carrying dropChance: 1 and gated by playerPrereqID."
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - loot-table
+      - drop-chance
+      - prerequisite
+      - tier
+    detail: LootTables.<ModCacheLoot> is a gamedataLootTable_Record with five gamedataLootItem_Record
+      entries, each dropChance 1, dropCountMin/Max 1, an itemID and a playerPrereqID. Field names
+      corrected — the yaml spells them itemID and playerPrereqID.
+  - id: cp2077.loot.player-prereq-tier-gating
+    claim: Vanilla iconic weapon recipe loot uses playerPrereqID conditions (e.g.,
+      LootPrereqs.CraftedIconicWeaponRecipePrereq_Common through _Legendary) that gate each tier to
+      a specific player level band; a weapon mod can reuse these exact record names for
+      compatibility.
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - loot
+      - prerequisite
+      - player-level
+      - gating
+    detail: The yaml comment names the vanilla pattern it copies,
+      ma_wbr_jpn_20_Igla_Sovereign_recipe_loot_table, and records the bands as <9 / 9-16 / 17-24 /
+      25-32 / 33+. Those band numbers are the comment's, not something read out of the vanilla
+      record here; what was confirmed in game is that the case drops the one recipe matching player
+      level.
+  - id: cp2077.loot.loot-quality-vs-loot-table
+    claim: A lootable entity's lootQuality field (e.g., Legendary) controls the visual tier badge shown
+      to the player; the lootTables field determines what items actually drop. Both must be present
+      and in sync for visual correctness.
+    status: inferred
+    source: ModWright research
+    tags:
+      - loot
+      - loot-quality
+      - loot-tables
+      - visual
+    detail: Field names corrected to lootQuality / lootTables. What the sources show is that the
+      shipping case sets both (lootTables [LootTables.<ModCacheLoot>], lootQuality Legendary). That
+      lootQuality drives the tier badge, and that a mismatch yields "a gold container with no
+      items", is reasoning — no source records either.
+  - id: cp2077.loot.debug-recipe-list-registration
+    claim: Iconic recipe variants must be appended to Debug.RecipeIconicFirearms.items list to appear in
+      developer menus and testing tools; absence makes them invisible to debug-time spawning.
+    status: inferred
+    source: ModWright research
+    tags:
+      - debug
+      - recipe
+      - list
+      - visibility
+    detail: The append ships, but nothing in the sources records testing what happens without it, or
+      which tools read that list. "Must" is the author's inference.
+  - id: cp2077.loot.loot-container-animated-by-transform-chunk
+    claim: A lootable world container entity requires a LootContainerObjectAnimatedByTransform chunk
+      with fields lootTables, lootQuality, and displayName to be interactable; this chunk structure
+      is mandatory and entity-level, not appearance-level.
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - chunk
+      - loot
+      - container
+      - entity
+      - interactive
+    detail: "The case .ent is a clone of common_suitcase_small.ent, which is a
+      LootContainerObjectAnimatedByTransform; the same chunk type is set on the sector node's
+      instanceData. Fields written by the build scripts: lootTables, contentAssignment, lootQuality,
+      displayName on the .ent, and $type, lootTables, lootQuality, containerType on the sector chunk
+      (with itemTDBID and shardMesh popped from the donor). A hand-edited chunk was rejected by the
+      RedPackage json reader over a field that \"was never identified\", so it was adapted from the
+      AldecaldosHighStakes reference instead — see
+      cp2077.toolchain.redpackage-reader-rejects-unidentified-field."
+  - id: cp2077.loot.loot-displays-via-loc-key
+    claim: Lootable entity displayName field takes a LocKey# reference (e.g., LocKey#<Mod>-Cache-Name)
+      which must be defined in the archivexl onscreens localization file; undefined keys produce no
+      label in-game.
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - loot
+      - localization
+      - display-name
+      - lockey
+    detail: "Spelling corrected to LocKey#. The value is written as {\"unk1\": \"0\", \"value\":
+      \"LocKey#<Mod>-Cache-Name\"} on the entity. Note the sector node's own chunk does not have to
+      repeat it: the build script sets lootTables, lootQuality and containerType only, leaving the
+      transplanted chunk's displayName empty, and the case still shows its name in game."
+  - id: cp2077.loot.dynamic-containers-dont-interact
+    claim: Dynamically spawned loot containers (via cet or redscript spawn) do not produce interact
+      prompts or accept looting; only sector-placed entities created at load time are interactable
+      with loot.
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - loot
+      - dynamic
+      - spawn
+      - interactable
+      - sector
+    detail: Dynamic spawns in early builds left two overlapping cases, neither lootable, which a CET
+      cleanup mod then had to erase. The redscript half of the claim is an extrapolation — only CET
+      spawns were tried.
+  - id: cp2077.loot.cet-proximity-auto-grant
+    claim: Where a real lootable container cannot be made to work, a CET mod that spawns a visible case
+      and grants the item on player proximity is an acceptable substitute.
+    status: contradicted
+    source: ModWright research
+    tags:
+      - loot
+      - cet
+      - auto-grant
+      - fallback
+      - rejected
+      - retracted
+    detail: "The mechanism was built and is described as previously proven working, so this is a product
+      decision rather than a technical failure — but it was reverted, and the shipped CET mod is
+      cleanup-only. Record it so the fallback is not quietly re-built: the author wanted real loot.
+      Superseded by cp2077.loot.streaming-sector-required-for-loot."
+  - id: cp2077.loot.streaming-sector-required-for-loot
+    claim: Lootable world objects must be placed via archivexl streaming sectors (registered in .xl
+      manifest), not dynamic spawns; streaming ensures the entity loads with proper loot wiring.
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - loot
+      - streaming
+      - sector
+      - archivexl
+      - interactable
+    supersedes: cp2077.loot.cet-proximity-auto-grant
+    detail: "Shipped paths, from the mod's .archive.xl: streaming block malorian\\all.streamingblock ->
+      malorian\\sectors\\malorian.streamingsector -> mod\\<modname>\\cache_case.ent. An earlier
+      hand-authored build used a streamingsector and streamingblock under mod\\<modname>\\ instead;
+      that build was abandoned."
+  - id: cp2077.loot.loot-requires-mesh-collision
+    claim: Loot interact prompts require mesh collision data; a custom mesh used in a lootable entity
+      must include a meshMeshParamPhysics chunk with box colliders set to both Simple and Complex
+      filter types.
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - loot
+      - collision
+      - physics
+      - mesh
+      - interact-prompt
+    detail: Applies to custom case meshes (a top and a bottom half), which arrive with no physics. Same
+      lesson as cp2077.mesh.phys-chunk-colliders, kept here because it is what a reader chasing a
+      missing loot prompt will search for.