modwright 0.1.0

package/knowledge/cyberpunk2077/ui.inkatlas.yaml

@@ -0,0 +1,81 @@
+game: cyberpunk2077
+topic: ui.inkatlas
+title: .inkatlas icon-sheet format — slot coordinates, resolution slots and yaml wiring
+facts:
+  - id: cp2077.ui.inkatlas.slices-by-percentage-not-pixels
+    claim: An `.inkatlas` file slices its backing texture into sprite slots using fractional coordinates
+      (a float between 0 and 1) rather than pixel coordinates; the origin (0,0) is the sheet's
+      top-left corner and (1,1) is its bottom-right corner, so a slot's bounds are
+      resolution-independent of the actual texture's pixel dimensions.
+    status: community
+    source: CDPR-Modding-Documentation/Cyberpunk-Modding-Docs
+      for-mod-creators-theory/files-and-what-they-do/file-formats/game-icons-the-inkatlas-file.md,
+      section "Summary"
+    tags:
+      - inkatlas
+      - coordinates
+      - texture
+      - icon
+  - id: cp2077.ui.inkatlas.slot-is-inktextureatlasmapper
+    claim: Each sprite slot in an `.inkatlas` is represented by an `inkTextureAtlasMapper` entry
+      carrying four coordinates (the fractional top-left and bottom-right bounds described in
+      cp2077.ui.inkatlas.slices-by-percentage-not-pixels); a two-sprite column example gives
+      (x0,y0)-(x1,y0.5) for the upper sprite and (x0,y0.5)-(x1,y1) for the lower one.
+    status: community
+    source: CDPR-Modding-Documentation/Cyberpunk-Modding-Docs
+      for-mod-creators-theory/files-and-what-they-do/file-formats/game-icons-the-inkatlas-file.md,
+      section "Summary"
+    tags:
+      - inkatlas
+      - inktextureatlasmapper
+      - slot
+      - schema
+  - id: cp2077.ui.inkatlas.three-texture-slots-only-slot-0-needed-for-modding
+    claim: Every `.inkatlas` has three `inkTextureSlot` entries supporting different backing-texture
+      resolutions; for modding purposes it is sufficient to populate `inkTextureSlot` 0 (the first
+      slot in the list) — the other two are additional-resolution variants a modder does not need to
+      fill in.
+    status: community
+    source: CDPR-Modding-Documentation/Cyberpunk-Modding-Docs
+      for-mod-creators-theory/files-and-what-they-do/file-formats/game-icons-the-inkatlas-file.md,
+      section "inkTextureSlots"
+    tags:
+      - inkatlas
+      - inktextureslot
+      - resolution
+      - modding
+    detail: As of WolvenKit 8.11.1, WolvenKit's "Part Mapping" tab (which shows which image region maps
+      to which slot name) only appears/refreshes after reopening the file once an `.xbm` texture is
+      hooked up to the atlas.
+  - id: cp2077.ui.inkatlas.atlaspartname-must-match-mapper-entry
+    claim: "A `UIIcon` yaml record targets a specific sprite inside an `.inkatlas` via two fields:
+      `atlasResourcePath` (the `.inkatlas` file's depot path) and `atlasPartName` (the name of an
+      entry in that atlas's `inkTextureAtlasMapper`); if `atlasPartName` does not match any part
+      name in the atlas, the game displays an empty icon rather than erroring."
+    status: community
+    source: 'CDPR-Modding-Documentation/Cyberpunk-Modding-Docs
+      for-mod-creators-theory/files-and-what-they-do/file-formats/game-icons-the-inkatlas-file.md,
+      section "Inkatlas: Slot names"'
+    tags:
+      - inkatlas
+      - uiicon
+      - atlaspartname
+      - atlasresourcepath
+      - silent-failure
+    detail: A validator can catch this class of mistake by cross-checking every `UIIcon` record's
+      `atlasPartName` against the named `.inkatlas` resource's actual part-mapping entries, since
+      the failure mode (blank icon, no log error) is otherwise invisible until observed in-game.
+  - id: cp2077.ui.inkatlas.slot-names-are-freely-renameable
+    claim: The part names inside an `.inkatlas`'s `inkTextureAtlasMapper` (referenced by
+      `atlasPartName`) can be freely renamed by a modder in WolvenKit; they are arbitrary labels the
+      mod author controls, not fixed engine-reserved names — some project templates ship with
+      several slot names already wired up by convention, but nothing enforces those specific names.
+    status: community
+    source: 'CDPR-Modding-Documentation/Cyberpunk-Modding-Docs
+      for-mod-creators-theory/files-and-what-they-do/file-formats/game-icons-the-inkatlas-file.md,
+      caption under "Inkatlas: Slot names" ("You can change field names at your leisure.")'
+    tags:
+      - inkatlas
+      - atlaspartname
+      - naming
+      - convention

package/knowledge/cyberpunk2077/ui.modsettings.yaml

@@ -0,0 +1,204 @@
+game: cyberpunk2077
+topic: ui.modsettings
+title: Mod Settings annotation schema and the Native Interactions Framework
+facts:
+  - id: cp2077.ui.modsettings.class-must-extend-system-or-service
+    claim: A Mod Settings class holds the mod's settings as properties. Registering it as a singleton is
+      recommended, and the way to do that is to extend `ScriptableSystem`; with Codeware installed
+      you can extend `ScriptableService` instead. "`ScriptableSystem`s are bounded to game sessions,
+      they're only available when in a game session. `ScriptableService`s are independent of game
+      sessions as they are created when the game starts, so they're always available." The page
+      recommends `ScriptableService` for settings.
+    status: community
+    source: wiki.redmodding.org "Mod Settings", section "Define a class" (including the "Different Types
+      of Singletons" box)
+    tags:
+      - modsettings
+      - scriptablesystem
+      - scriptableservice
+      - class-structure
+    detail: 'Corrected 2026-09-07 on three counts: the singleton is recommended, not required;
+      `ScriptableService` requires Codeware; and the difference is session-scope/availability, not
+      "settings persisted between sessions" as previously recorded (Mod Settings persists values in
+      its own configuration file either way — see
+      cp2077.ui.modsettings.programmatic-change-needs-acceptchanges). The source URL was also
+      changed: the cited /scripting-cyberpunk/mod-settings/introduction 404s, and the live page is
+      /scripting-cyberpunk/scripting/settings/mod-settings. The page title is "Mod Settings"; there
+      is no page called "Mod Settings Framework Extraction".'
+  - id: cp2077.ui.modsettings.unannotated-property-is-invisible
+    claim: "Mod Settings binds a property to the UI through `@runtimeProperty(key: String, value:
+      String)` annotations, of which `ModSettings.mod` is the mod's unique name and \"You must reuse
+      the same value on other properties.\" A property with no annotations is simply not exposed —
+      the reference class's `secret: String` field is left unannotated with the comment \"We don't
+      want to expose this.\""
+    status: community
+    source: wiki.redmodding.org "Mod Settings", sections "Define a class" (example class) and "Binding
+      properties > Base Annotations"
+    tags:
+      - modsettings
+      - runtimeproperty
+      - required-field
+    detail: 'Whatever value the property is assigned is treated as its default, and any annotation
+      taking a string value can instead take a localization key. Corrected 2026-09-07: "with no
+      error raised" was trimmed as unsourced, and the section names fixed (the page has no
+      "Annotation System" or "Notable Gotchas" headings).'
+  - id: cp2077.ui.modsettings.universal-annotation-keys
+    claim: "Annotations supported on all property types: `ModSettings.mod` (unique mod name),
+      `ModSettings.displayName` (label), `ModSettings.description` (hover hint),
+      `ModSettings.category` (groups properties under a named separator),
+      `ModSettings.category.order` (a Number giving the category's placement) and
+      `ModSettings.dependency`."
+    status: community
+    source: wiki.redmodding.org "Mod Settings", section "Binding properties > Base Annotations"
+    tags:
+      - modsettings
+      - runtimeproperty
+      - annotation
+      - syntax
+  - id: cp2077.ui.modsettings.type-specific-annotation-keys
+    claim: "Type-specific annotations: `ModSettings.min`, `ModSettings.max` and `ModSettings.step`
+      (minimum, maximum and increment for the slider) are supported on `Int32` and `Float`
+      properties, typed to match the property; `ModSettings.displayValues.EnumValue` sets the UI
+      label for one value of an `Enum` property, which otherwise displays the enum's own value
+      names."
+    status: community
+    source: wiki.redmodding.org "Mod Settings", section "Binding properties > Specific Annotations"
+    tags:
+      - modsettings
+      - runtimeproperty
+      - annotation
+      - enum
+      - numeric
+  - id: cp2077.ui.modsettings.type-to-widget-mapping
+    claim: "Supported property types and how each is shown: `Bool` -> \"A toggle-able on/off switch\";
+      `Int32` -> \"A slider with `Int32` values for the user to choose from\"; `Float` -> \"A slider
+      with `Float` values\"; `Enum` -> \"A selector to choose from the specified enum's values\";
+      `EInputKey` -> \"A button where the user can input any key (supports both keyboard and
+      controller)\"."
+    status: community
+    source: wiki.redmodding.org "Mod Settings", section "Binding properties > Supported Types"
+    tags:
+      - modsettings
+      - widget
+      - property-type
+    detail: 'Corrected 2026-09-07: "There is no annotation to pick a different widget for a given type"
+      was trimmed — the page lists the mapping but does not state that it cannot be overridden.'
+  - id: cp2077.ui.modsettings.dependency-annotation-hides-property
+    claim: '`@runtimeProperty("ModSettings.dependency", "String")` shows the annotated property "only if
+      another Boolean setting is enabled"; the String "must be the name of the Boolean setting
+      property".'
+    status: community
+    source: wiki.redmodding.org "Mod Settings", section "Binding properties > Base Annotations"
+    tags:
+      - modsettings
+      - dependency
+      - conditional-display
+    detail: 'Corrected 2026-09-07: "in the same group" was trimmed as unsourced, and the section name
+      fixed (this is a base annotation, not a gotcha).'
+  - id: cp2077.ui.modsettings.listener-callbacks-require-cb-keyword
+    claim: 'Listeners are registered with `ModSettings.RegisterListenerToClass(target:
+      ref<IScriptable>)` and/or `ModSettings.RegisterListenerToModifications(target)` (with matching
+      `Unregister...` calls). The target must define `OnModVariableChangeRequested(groupPath: CName,
+      varName: CName)`, `OnModVariableChangeAccepted(groupPath: CName, varName: CName)` and/or
+      `OnModSettingsChange()`: "You must exactly name the callback methods as you see it, you must
+      also not forget to use the keyword `cb` either. Both conditions are required for the method to
+      be called by Mod Settings."'
+    status: community
+    source: wiki.redmodding.org "Mod Settings", sections "Listeners > Listening to Changes" and
+      "Listeners > Listening to Modifications" (including the info hints)
+    tags:
+      - modsettings
+      - listener
+      - callback
+      - cb-keyword
+      - silent-failure
+    detail: "`groupPath` is `/mods/[ModName]/[ModClass]` and `varName` is the variable name. Registering
+      a listener is not optional: \"Binding annotations to your class' properties isn't enough\".
+      Changes reach the class when the player presses `Accept`."
+  - id: cp2077.ui.modsettings.lifecycle-differs-by-base-class
+    claim: Where `Listen`/`Unlisten` go depends on the base class. A `ScriptableSystem` calls
+      `this.Listen()` from `OnAttach()` and `this.Unlisten()` from `OnDetach()`. A
+      `ScriptableService` calls `this.Listen()` from BOTH `OnLoad()` and `OnReload()` and
+      `this.Unlisten()` only from `OnUninitialize()` — and the page's warning is explicit that
+      RedHotTools users "must call `Listen` in the `Reload` method of your `ScriptableService`. You
+      don't need to `Unlisten` in such case."
+    status: community
+    source: wiki.redmodding.org "Mod Settings", section "Listeners > Registering Listeners" (including
+      the "If you are using `ScriptableService`" box and the RedHotTools warning hint)
+    tags:
+      - modsettings
+      - scriptableservice
+      - scriptablesystem
+      - redhottools
+      - lifecycle
+  - id: cp2077.ui.modsettings.programmatic-change-needs-acceptchanges
+    claim: "Changing a setting from code rather than the Mod Settings menu takes three steps: `let
+      configs = ModSettings.GetVars(n\"MyMod\", n\"\");` (`n\"\"` meaning no explicit category),
+      locate the `ConfigVar` by `config.GetName()` and cast it (e.g. to `ModConfigVarBool`) to call
+      `SetValue`, then call `ModSettings.AcceptChanges()` to \"save new value in configuration
+      file\". Without that last call, \"changes made to a setting won't be saved by Mod Settings in
+      its configuration file\"."
+    status: community
+    source: wiki.redmodding.org "Mod Settings", section "Save changes dynamically"
+    tags:
+      - modsettings
+      - acceptchanges
+      - configvar
+      - persistence
+    detail: Section name corrected 2026-09-07 (the heading is "Save changes dynamically", not "Dynamic
+      Saving").
+  - id: cp2077.ui.modsettings.values-persist-in-the-plugin-user-ini-keyed-by-mod-and-class
+    claim: 'Mod Settings persists a changed value in red4ext/plugins/mod_settings/user.ini, under a
+      section named "[<ModSettings.mod>.<class name>]" with one "<property> = <value>" line per
+      changed property, and reads it back at the next launch. The section outlives the mod: removing
+      the .reds leaves the section in place.'
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - modsettings
+      - persistence
+      - user-ini
+      - red4ext
+      - scaffold
+    related:
+      - cp2077.ui.modsettings.unannotated-property-is-invisible
+    detail: Whether an unchanged default is written is not known (only the changed value was seen). A
+      stale section is harmless as far as observed; cleaning it is a hand edit of the plugin's file,
+      which ModWright does not touch.
+  - id: cp2077.ui.modsettings.scriptablesystem-listener-updates-properties-on-accept
+    claim: A ScriptableSystem settings class that calls ModSettings.RegisterListenerToClass(this) from
+      OnAttach has its annotated properties updated in the live instance when the player presses
+      Accept in MOD SETTINGS, with none of the listener callbacks (OnModVariableChangeRequested,
+      OnModVariableChangeAccepted, OnModSettingsChange) defined and no reload.
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - modsettings
+      - listener
+      - scriptablesystem
+      - scaffold
+      - live-update
+    related:
+      - cp2077.ui.modsettings.listener-callbacks-require-cb-keyword
+      - cp2077.ui.modsettings.lifecycle-differs-by-base-class
+    detail: "The callbacks are for reacting to a change; the property update itself needed only the
+      registration. Not tested here: the same class without the registration (the wiki says the
+      properties then keep their defaults)."
+  - id: cp2077.ui.modsettings.module-guard-compiles-with-and-without-mod-settings
+    claim: Mod Settings' redscript module is ModSettingsModule (the first line of
+      red4ext/plugins/mod_settings/module.reds), so a settings class that puts its
+      ModSettings.RegisterListenerToClass / UnregisterListenerToClass calls behind
+      @if(ModuleExists("ModSettingsModule")), with empty @if(!ModuleExists("ModSettingsModule"))
+      twins, compiles whether Mod Settings is installed or not.
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - modsettings
+      - redscript
+      - conditional-compilation
+      - optional-dependency
+    detail: "Compile evidence only: the game was not launched with Mod Settings removed, since other
+      installed mods may need it."