modwright 0.1.0

package/scaffolds/cyberpunk2077/new-localization.yaml

@@ -0,0 +1,130 @@
+# new-localization (Cyberpunk 2077) — a quickhack's records name `LocKey#`s
+# that something has to define. Adds ONE
+# on-screen localization entry — the `en-us.json.json` CR2W source, the
+# `.archive.xl` manifest's `localization.onscreens.en-us` pointer, and the
+# `convert deserialize` build step — the loca half `new-item-chain` emits inline
+# for an item, lifted out so any sequence can name it. Runs once per LocKey: the
+# skeleton (both files), the manifest pointer and the build step are idempotent
+# (write-text `ifExists: skip`; patch-project's own dedupe), and only the entry
+# append (`entries.-`) adds per run, so N runs give one source with N entries.
+# The manifest is JSON — a YAML append would break it — so the entry goes in
+# through `insert-xl-entry`, not `insert-block`.
+#
+# The record that references the text uses `LocKey#${secondaryKey}` (the handle
+# is `LocKey#` + this entry's secondaryKey); `text` is the femaleVariant the
+# player sees. Paths follow the item chain's own convention (WolvenKit.CLI names
+# a `convert deserialize` output by stripping exactly one trailing `.json`, so
+# the source must be `en-us.json.json` to compile to the `en-us.json` the
+# manifest points at — observed in game, 2026-09).
+id: cyberpunk2077.new-localization
+game: cyberpunk2077
+title: New Cyberpunk 2077 on-screen localization entry
+summary: Add one en-us on-screen localization entry (source, manifest pointer and deserialize step), so a LocKey# a record references resolves to real text.
+modTypes: [gameplay-tweak, quickhack, weapon, item, loot, garment]
+needs: {}
+inputs:
+  - type: string
+    name: modSlug
+    prompt: "Lowercase depot folder name, used in the mod\\\\<slug>\\\\... paths, e.g. mymod."
+    pattern: "^[a-z][a-z0-9_]*$"
+  - type: path
+    name: xlFile
+    prompt: "The .archive.xl manifest (created with a localization skeleton if missing; an existing one — e.g. an entity patch's — gains the localization.onscreens.en-us pointer). Registered as a project source and an archive deploy target."
+    mustExist: false
+  - type: path
+    name: enUsSourceDir
+    prompt: "Directory the localization JSON source is written to, typically sources/<slug>. Its filename is fixed to en-us.json.json (WolvenKit.CLI strips one trailing .json, so only that name compiles to en-us.json)."
+    mustExist: false
+  - type: path
+    name: entCompiledDir
+    prompt: "Directory the compiled en-us.json lands in, typically archive-staging/<Mod>/mod/<slug> — passed to convert deserialize -o (a directory, not a file)."
+    mustExist: false
+  - type: string
+    name: secondaryKey
+    prompt: "The LocKey secondaryKey, e.g. MyMod-Name. The referencing record uses LocKey#<this>."
+  - type: string
+    name: text
+    prompt: "The player-facing text this LocKey resolves to (the femaleVariant)."
+ids: []
+emits:
+  - op: write-text
+    path: "${input.xlFile}"
+    ifExists: skip
+    body: |
+      {
+        "localization": { "onscreens": {} }
+      }
+  - op: insert-xl-entry
+    path: "${input.xlFile}"
+    pointer: localization.onscreens.en-us
+    value: "mod\\${input.modSlug}\\en-us.json"
+  - op: write-text
+    path: "${input.enUsSourceDir}/en-us.json.json"
+    ifExists: skip
+    body: |
+      {
+        "Header": {
+          "WolvenKitVersion": "8.20.0",
+          "WKitJsonVersion": "0.0.9",
+          "GameVersion": 2310,
+          "DataType": "CR2W",
+          "ArchiveFileName": "mod\\${input.modSlug}\\en-us.json"
+        },
+        "Data": {
+          "Version": 195,
+          "BuildVersion": 0,
+          "RootChunk": {
+            "$type": "JsonResource",
+            "cookingPlatform": "PLATFORM_PC",
+            "root": {
+              "HandleId": "0",
+              "Data": { "$type": "localizationPersistenceOnScreenEntries", "entries": [] }
+            }
+          },
+          "EmbeddedFiles": []
+        }
+      }
+  - op: insert-xl-entry
+    path: "${input.enUsSourceDir}/en-us.json.json"
+    pointer: Data.RootChunk.root.Data.entries.-
+    value:
+      $type: localizationPersistenceOnScreenEntry
+      femaleVariant: "${input.text}"
+      maleVariant: ""
+      primaryKey: "0"
+      secondaryKey: "${input.secondaryKey}"
+  - op: patch-project
+    add:
+      outDir: "archive-staging"
+      sources:
+        - id: "xl-${input.modSlug}"
+          path: "${input.xlFile}"
+          kind: xl
+      steps:
+        - step: exec
+          id: "deserialize-${input.modSlug}-enus"
+          command: wolvenkit-cli
+          args: ["convert", "deserialize", "${input.enUsSourceDir}/en-us.json.json", "-o", "${input.entCompiledDir}"]
+          expectOutputs: ["${input.entCompiledDir}/en-us.json"]
+          before: stage
+      deployTargets:
+        - rootId: archive
+          from: "${input.xlFile}"
+          locked: false
+          backup: true
+templates: []
+satisfies:
+  - cp2077.garments.xl-entries-resolve
+  - cp2077.history.xl-manifest-lint
+  - cp2077.history.clean-pack-json-sweep
+  - cp2077.vehicles.cr2w-unique-ids
+  - cp2077.vehicles.cr2w-resource-path-shape
+manual:
+  - title: Confirm the text renders
+    steps:
+      - "Build and deploy, then load a save with the mod active and confirm the string that reads LocKey#${input.secondaryKey} in the record now shows \"${input.text}\" rather than the raw key."
+    expected: "The record referencing LocKey#${input.secondaryKey} renders \"${input.text}\" in game."
+claim:
+  idSuffix: "loca.${input.secondaryKey}"
+  claim: "LocKey#${input.secondaryKey} resolves to \"${input.text}\" through the mod's en-us on-screen entries."
+evidence: ["ModWright research"]

package/scaffolds/cyberpunk2077/new-mod-settings.yaml

@@ -0,0 +1,133 @@
+# new-mod-settings (Cyberpunk 2077) — writes (or appends to) a redscript
+# settings class with `@runtimeProperty("ModSettings.*", ...)` annotation
+# blocks — the convention `cp2077.history.modsettings-annotation-keys` checks
+# (see that validator's own header comment).
+id: cyberpunk2077.new-mod-settings
+game: cyberpunk2077
+title: New Cyberpunk 2077 mod setting (native settings UI)
+summary: Append a @runtimeProperty-annotated field to a redscript settings class, so a value shows up in the native in-game settings menu.
+modTypes: [gameplay-tweak]
+needs: {}
+inputs:
+  - type: path
+    name: file
+    prompt: "Destination .reds file under a project source of kind \"scripts\" (created if it does not yet exist)."
+    mustExist: false
+  - type: string
+    name: className
+    prompt: "Settings class name, e.g. MyModSettings."
+    pattern: "^[A-Za-z][A-Za-z0-9_]*$"
+  - type: string
+    name: settingName
+    prompt: "Field name, e.g. glowIntensity."
+    pattern: "^[a-z][A-Za-z0-9_]*$"
+  - type: enum
+    name: settingType
+    prompt: "redscript type of the setting."
+    values: [Bool, Int32, Float, String]
+  - type: string
+    name: category
+    prompt: "Settings menu category/section."
+  - type: string
+    name: displayName
+    prompt: "Player-facing label."
+  - type: string
+    name: defaultValue
+    prompt: "Default value literal (e.g. true, 0, 0.5, \"text\")."
+ids: []
+emits:
+  # A field appended INSIDE the settings class, before its closing brace
+  # (anchor before-last-line, anchorPattern "^}"): the first run creates the
+  # class shell through createIfMissing and drops the field in; a second run
+  # finds the same "}" and adds its field to the SAME class. An earlier
+  # shape wrote one self-contained class per run, so a
+  # second setting on a sequence's fixed className redeclared the class.
+  # `indent: 4` nests the field body (kept a readable block scalar) inside the
+  # class.
+  #
+  # Observed in game (2026-09-11): the `@runtimeProperty` block
+  # sits on the property, not the class, and the property is the `settingName`
+  # input (the first shape annotated the class and named every field `value`).
+  # Mod Settings binds annotations to properties (knowledge
+  # `cp2077.ui.modsettings.unannotated-property-is-invisible`, the wiki's
+  # "Binding properties"), and registering the class as a singleton by
+  # extending `ScriptableSystem` is how to do that without Codeware (which
+  # `ScriptableService` would need). This is the documented shape.
+  #
+  # The class shell also registers itself as a Mod Settings listener. Without
+  # that the control renders and persists, but the property keeps its default:
+  # "Binding annotations to your class' properties isn't enough, as you also
+  # must register a listener to the class in order to have Mod Settings update
+  # the properties during run-time" (the wiki's "Listeners"; knowledge
+  # `cp2077.ui.modsettings.listener-callbacks-require-cb-keyword`,
+  # `…lifecycle-differs-by-base-class`: a ScriptableSystem listens from
+  # OnAttach and stops in OnDetach). The registration is compiled only when
+  # Mod Settings is installed (its redscript module is `ModSettingsModule`),
+  # so the mod still compiles without it and the setting keeps its default.
+  - op: insert-block
+    path: "${input.file}"
+    anchor: before-last-line
+    anchorPattern: "^}"
+    indent: 4
+    createIfMissing: |
+      module ${project.moduleName}
+
+      public class ${input.className} extends ScriptableSystem {
+          public func OnAttach() -> Void {
+              this.ListenToModSettings();
+          }
+
+          public func OnDetach() -> Void {
+              this.UnlistenToModSettings();
+          }
+
+          @if(ModuleExists("ModSettingsModule"))
+          private func ListenToModSettings() -> Void {
+              ModSettings.RegisterListenerToClass(this);
+          }
+
+          @if(!ModuleExists("ModSettingsModule"))
+          private func ListenToModSettings() -> Void {}
+
+          @if(ModuleExists("ModSettingsModule"))
+          private func UnlistenToModSettings() -> Void {
+              ModSettings.UnregisterListenerToClass(this);
+          }
+
+          @if(!ModuleExists("ModSettingsModule"))
+          private func UnlistenToModSettings() -> Void {}
+
+          public static func GetInstance(game: GameInstance) -> ref<${input.className}> {
+              return GameInstance.GetScriptableSystemsContainer(game).Get(NameOf<${input.className}>()) as ${input.className};
+          }
+      }
+    body: |
+      @runtimeProperty("ModSettings.mod", "${project.name}")
+      @runtimeProperty("ModSettings.category", "${input.category}")
+      @runtimeProperty("ModSettings.displayName", "${input.displayName}")
+      public let ${input.settingName}: ${input.settingType} = ${input.defaultValue};
+templates: []
+satisfies:
+  - cp2077.history.modsettings-annotation-keys
+  - cp2077.history.dev-scripts-never-ship
+manual:
+  - title: Confirm the control renders
+    steps:
+      - "Load the game with the mod active and open the main menu's MOD SETTINGS entry (the page Mod Settings adds beside Settings, not Settings → Mods)."
+      - "Find \"${input.displayName}\" under \"${input.category}\" and confirm it renders as a ${input.settingType} control with default ${input.defaultValue}."
+    expected: "The control renders in the Mod Settings page and persists its value across a restart — the one step that is always confirmed by a person."
+claim:
+  idSuffix: menu-control
+  claim: "${input.settingName} on ${input.className} renders as a ${input.settingType} control named \"${input.displayName}\" in the Mod Settings page."
+testRows:
+  - gate: MS-1
+    title: "RED4ext/CET log shows the plugin loaded with no error"
+    expected: "The game log shows ${input.className} loaded with no redscript compile or runtime error."
+    manual: true
+    probeKinds: []
+  - gate: MS-2
+    title: "Control renders in the Mod Settings page"
+    expected: "A human confirms the control renders and its value persists — never automated."
+    manual: true
+    probeKinds: []
+evidence: ["ModWright research"]