modwright 0.1.0

package/knowledge/cyberpunk2077/red4ext.plugins.yaml

@@ -0,0 +1,124 @@
+game: cyberpunk2077
+topic: red4ext.plugins
+title: RED4ext plugin loading contract — exported functions, install paths, logging
+facts:
+  - id: cp2077.red4ext.plugins.two-project-split
+    claim: "RED4ext is split into two separate projects: `RED4ext` itself (the loader, responsible only
+      for managing plugins) and `RED4ext.SDK` (the reversed types/helpers used to extend the engine,
+      usable independently); a new plugin should depend only on `RED4ext.SDK`, not on the `RED4ext`
+      loader project."
+    status: community
+    source: WopsS/RED4ext@c52c8d8 README.md:16-21, section "About this library"
+    tags:
+      - red4ext
+      - sdk
+      - loader
+      - project-structure
+  - id: cp2077.red4ext.plugins.three-required-exports
+    claim: "A RED4ext plugin DLL must export three `RED4EXT_C_EXPORT` functions: `Supports() ->
+      uint32_t` (the plugin's supported API version, e.g. `RED4EXT_API_VERSION_LATEST`),
+      `Query(RED4ext::PluginInfo*)` (fills in name, author, `version`, `runtime` and `sdk` fields)
+      and `Main(RED4ext::PluginHandle, RED4ext::EMainReason, const RED4ext::Sdk*)` (the entry point,
+      called for both Load and Unload reasons)."
+    status: community
+    source: CDPR-Modding-Documentation/Red4Ext-Wiki/mod-developers/creating-a-plugin.md, section
+      "Exported functions" and the worked "Example"
+    tags:
+      - red4ext
+      - plugin
+      - exports
+      - supports
+      - query
+      - main
+  - id: cp2077.red4ext.plugins.runtime-field-pins-game-version
+    claim: "`PluginInfo::runtime`, set inside a plugin's `Query` function, controls which game version
+      the plugin will load against: an explicit value like `1.21` means RED4ext loads the plugin
+      only when the running game's version is exactly `1.21`; setting it to `RED4EXT_RUNTIME_LATEST`
+      (the recommended default) targets whatever the latest game version the installed SDK defines
+      is; `RED4EXT_RUNTIME_INDEPENDENT` opts out of the version check entirely when the plugin only
+      uses RED4ext as a loader."
+    status: community
+    source: CDPR-Modding-Documentation/Red4Ext-Wiki/mod-developers/creating-a-plugin.md, warning hint
+      under "Query"
+    tags:
+      - red4ext
+      - plugin
+      - runtime
+      - version-gate
+      - plugininfo
+    detail: 'A plugin whose `runtime` is pinned to an old exact version stops being loaded after a game
+      update unless it is rebuilt with a new pin or switched to `RED4EXT_RUNTIME_LATEST`. Checked
+      against the source (2026-09-08): the page says only "it would not be loaded" — whether that is
+      reported to the user (red4ext.log line, dialog, nothing at all) is not stated there, so do not
+      promise a silent failure either way.'
+  - id: cp2077.red4ext.plugins.main-return-false-triggers-immediate-unload
+    claim: If a plugin's `Main` entry point returns `false` in response to a `Load` reason, RED4ext
+      immediately sends it an `Unload` notification and unloads the plugin; however, if the
+      `Load`-handling code throws an exception instead of returning `false`, the plugin does NOT
+      receive the `Unload` notification.
+    status: community
+    source: CDPR-Modding-Documentation/Red4Ext-Wiki/mod-developers/creating-a-plugin.md, section "Main >
+      Remarks"
+    tags:
+      - red4ext
+      - plugin
+      - main
+      - unload
+      - exception
+      - failure-mode
+  - id: cp2077.red4ext.plugins.main-called-before-memory-allocators-ready
+    claim: A plugin's `Main` function is called before RED4ext's memory allocators are initialized; a
+      plugin that needs to touch the game's RTTI system (e.g. call functions) from startup must
+      instead register a custom game state and defer that work to when the RTTI system is ready,
+      rather than doing it directly in `Main`.
+    status: community
+    source: CDPR-Modding-Documentation/Red4Ext-Wiki/mod-developers/creating-a-plugin.md, warning under
+      "Main"
+    tags:
+      - red4ext
+      - plugin
+      - main
+      - initialization-order
+      - rtti
+    detail: "RELATED: this is the reason custom-game-states.md exists — its
+      `OnEnter`/`OnUpdate`/`OnExit` state callbacks are the documented way to hook a later point in
+      the game's life cycle than `Main` provides."
+  - id: cp2077.red4ext.plugins.install-paths-and-logs
+    claim: RED4ext itself installs by extracting into the game's root directory and logs to
+      `<game_directory>/red4ext/logs/red4ext.log`; a plugin installs into
+      `<game_directory>/red4ext/plugins` (or a named sub-directory there) and its load status is
+      checked in `<game_directory>/red4ext/logs/game.log`.
+    status: community
+    source: CDPR-Modding-Documentation/Red4Ext-Wiki/getting-started/installing-red4ext.md and
+      getting-started/installing-a-plugin.md
+    tags:
+      - red4ext
+      - install-path
+      - log-file
+      - plugins-directory
+  - id: cp2077.red4ext.plugins.per-plugin-log-file-created-lazily
+    claim: RED4ext's SDK gives every plugin its own logger (`aSdk->logger`, with `Trace`/`TraceF`
+      methods shown in the docs); the log file named after the plugin is only created in
+      `<game_directory>/red4ext/logs` the first time that plugin actually logs a message, not at
+      load time unconditionally.
+    status: community
+    source: CDPR-Modding-Documentation/Red4Ext-Wiki/mod-developers/logging.md
+    tags:
+      - red4ext
+      - logging
+      - plugin
+      - lazy-file-creation
+  - id: cp2077.red4ext.plugins.abi-is-fastcall-x86-64
+    claim: A RED4ext plugin must be built for the x86-64 architecture with the `__fastcall` calling
+      convention; the SDK provides `RED4EXT_C_EXPORT` (expands to `extern "C"
+      __declspec(dllexport)`) and `RED4EXT_CALL` (expands to `__fastcall`) helper macros to export
+      functions with the correct linkage and convention.
+    status: community
+    source: CDPR-Modding-Documentation/Red4Ext-Wiki/mod-developers/creating-a-plugin.md, opening
+      paragraph and "Exported functions" intro
+    tags:
+      - red4ext
+      - plugin
+      - abi
+      - fastcall
+      - x86-64

package/knowledge/cyberpunk2077/redhottools.hotreload.yaml

@@ -0,0 +1,245 @@
+game: cyberpunk2077
+topic: redhottools.hotreload
+title: Red Hot Tools hot-reload scope, integrations and version floors
+facts:
+  - id: cp2077.redhottools.hotreload.version-floors
+    claim: Red Hot Tools' README lists its compatibility as Cyberpunk 2077 2.21, ArchiveXL 1.21.0+,
+      Cyber Engine Tweaks 1.35.0+ and redscript 0.5.25+, and its installation step 1 requires
+      RED4ext 1.27.0+ before extracting `RedHotTools-x.x.x.zip` into the Cyberpunk 2077 directory.
+    status: community
+    source: cp2077-red-hot-tools README.md, sections "Getting Started > Compatibility" (game, ArchiveXL,
+      CET, redscript) and "Getting Started > Installation" (RED4ext)
+    tags:
+      - redhottools
+      - version-floor
+      - archivexl
+      - cet
+      - redscript
+      - red4ext
+    detail: 'Source corrected 2026-09-07: RED4ext is under Installation, not Compatibility. Re-verified
+      against the master branch (there is no main branch). Framework versions stay in the claim;
+      "Cyberpunk 2077 2.21" is the game version this release targets, not an observation date, so
+      there is no `verified_on`.'
+  - id: cp2077.redhottools.hotreload.core-feature-scope
+    claim: "Red Hot Tools' stated features are: \"Inspect game entities and world nodes\"; \"Inspect ink
+      layers and widgets (user interface)\"; \"Hot reload archives, scripts and tweaks\"; \"Prevent
+      game from starting if scripts compilation fails\"."
+    status: community
+    source: cp2077-red-hot-tools README.md, opening feature list
+    tags:
+      - redhottools
+      - feature
+      - hot-reload
+      - compile-guard
+  - id: cp2077.redhottools.hotreload.wolvenkit-pack-and-reload-button
+    claim: '"WolvenKit: Pack & reload archives from the editor with a press of a button" — packing and
+      the hot-reload trigger are one action.'
+    status: community
+    source: cp2077-red-hot-tools README.md, the integration list under "For greater convenience it
+      integrates with other tools"
+    tags:
+      - redhottools
+      - wolvenkit
+      - hot-reload
+      - archive
+    detail: TENSION with two other verified facts in this knowledge base, which are not changed by this.
+      cp2077.loadorder.rht-watches-hot-directory-only records that the live depot mount watches
+      `archive\pc\hot` ONLY, so a one-button reload presupposes the archive landing there;
+      cp2077.process.assetbuild.rht-hot-folder-banned-for-whole-mesh-archives records that
+      whole-archive hot ingest of an archive containing a mounted weapon mesh explodes geometry and
+      must be deployed cold. The README states neither caveat, so a scaffold should not offer
+      pack-and-reload for a mesh-carrying archive on the strength of this fact alone.
+  - id: cp2077.redhottools.hotreload.vscode-extension-reload-commands
+    claim: "\"With extension installed, when editing scripts or tweaks files in VS Code, you'll get new
+      editor commands in the menu to hot reload the scripts or tweaks. As any other command they can
+      also be bound to hotkeys.\" The extension is installed by dragging `red-hot-vscode-x.x.x.vsix`
+      onto the VS Code extension bar."
+    status: community
+    source: cp2077-red-hot-tools README.md, section "Visual Studio Code" and "Getting Started >
+      Installation" (optional step 4)
+    tags:
+      - redhottools
+      - vscode
+      - hot-reload
+      - hotkey
+    detail: 'Corrected 2026-09-07: the README says "extension bar", not "extensions bar".'
+  - id: cp2077.redhottools.hotreload.cet-menu-integration
+    claim: '"Cyber Engine Tweaks: Reload assets using in-game menu and inspect world nodes and entities"
+      — available with the optional CET UI, installed by extracting `RedHotTools-x.x.x-Overlay.zip`
+      into the Cyberpunk 2077 directory.'
+    status: community
+    source: cp2077-red-hot-tools README.md, the integration list under "For greater convenience it
+      integrates with other tools" and "Getting Started > Installation" (optional step 3)
+    tags:
+      - redhottools
+      - cet
+      - in-game-menu
+      - inspect
+  - id: cp2077.redhottools.hotreload.optional-artifacts-are-separate-zips
+    claim: 'Three separate artifacts ship: `RedHotTools-x.x.x.zip` (the base plugin, installation step
+      2), `RedHotTools-x.x.x-Overlay.zip` (the CET UI) and `red-hot-vscode-x.x.x.vsix` (the VS Code
+      extension). The README marks the latter two steps "_(Optional)_".'
+    status: community
+    source: cp2077-red-hot-tools README.md, section "Getting Started > Installation"
+    tags:
+      - redhottools
+      - installation
+      - optional-dependency
+  - id: cp2077.redhottools.hotreload.struct-fields-not-reinitialized
+    claim: 'Documented limitation: "Struct fields are not reinitialized (if you change the fields of a
+      struct and an instance of that struct exists during hot reload, this can lead to issues)."'
+    status: community
+    source: cp2077-red-hot-tools README.md, section "Limitations"
+    tags:
+      - redhottools
+      - struct
+      - hot-reload
+      - limitation
+  - id: cp2077.redhottools.hotreload.new-scriptable-system-handler-needs-session-reload
+    claim: "Documented limitation: \"Handlers for scriptable systems requests aren't registered on
+      scripts load, if you add a new handler you have to reload the game session.\""
+    status: community
+    source: cp2077-red-hot-tools README.md, section "Limitations"
+    tags:
+      - redhottools
+      - scriptablesystem
+      - handler
+      - hot-reload
+      - limitation
+    detail: "Corrected 2026-09-07: the previous claim inverted the README's mechanism, stating that
+      handlers \"are registered only at scripts-load time\" where the README says they are NOT
+      registered on scripts load. The practical consequence — a new handler needs a full session
+      reload, not just a script reload — is the same either way, but the stated mechanism was
+      wrong."
+  - id: cp2077.redhottools.hotreload.hot-folder-moves-into-mods
+    claim: "Placing an `.archive` inside `archive/pc/hot` (not `archive/pc/mod/hot` as the CDPR docs
+      page says) is not a permanent location: RHT's ArchiveWatcher moves a new file into
+      `archive/pc/mod` (an existing archive of the same name is replaced in place, in
+      `archive/pc/mod` or `mods/*/archives`), unloads and reloads the game archives, resets the
+      resource cache and reloads archive extensions; the `hot` folder appearing empty right after a
+      drop is expected, not a failure."
+    status: verified
+    verified_on: "2.31"
+    source: CDPR-Modding-Documentation/Cyberpunk-Modding-Docs
+      for-mod-creators-theory/modding-tools/redhottools/rht-hot-reload.md, sections "The theory" and
+      "But the folder is always empty!"
+    tags:
+      - redhottools
+      - hot-reload
+      - hot-folder
+      - archive
+    detail: 'RELATED: sharpens cp2077.redhottools.hotreload.wolvenkit-pack-and-reload-button and
+      cp2077.loadorder.rht-watches-hot-directory-only — "watches" means RHT actively relocates the
+      file out of `hot`, it does not reload the archive in place.'
+  - id: cp2077.redhottools.hotreload.already-spawned-instances-unaffected
+    claim: Hot Reload invalidates the game's cached resources and will apply changes to newly-spawned
+      content, but anything already spawned in the world keeps using what it loaded originally; the
+      page's documented ways to force an already-spawned instance to pick up a change are (in
+      decreasing reliability) loading a save, spawning and equipping a new copy of the item via CET,
+      despawning/respawning the entity, respawning the UI widget, or unequipping and re-equipping
+      the item.
+    status: community
+    source: CDPR-Modding-Documentation/Cyberpunk-Modding-Docs
+      for-mod-creators-theory/modding-tools/redhottools/rht-hot-reload.md, section "But my changes
+      don't show up!"
+    tags:
+      - redhottools
+      - hot-reload
+      - limitation
+      - cache-invalidation
+  - id: cp2077.redhottools.hotreload.archive-reload-is-automatic-xl-reload-is-manual
+    claim: RHT's overlay window ("Hot Reload", Archives tab) has one manual button, "Reload extensions",
+      which re-runs ArchiveXL's extension discovery over `archive/pc/mod` and `mods/*/archives` and
+      nothing else; `.archive` files are reloaded automatically by the hot-folder watcher, and that
+      automatic path already ends with an extension reload of its own, so the button is only needed
+      after editing an `.xl` without dropping an archive. The button gives no feedback in the
+      window; ArchiveXL.log ("Discovering archive extensions..." then one "Loading ..." line per
+      .xl) is where it shows.
+    status: verified
+    verified_on: "2.31"
+    source: CDPR-Modding-Documentation/Cyberpunk-Modding-Docs
+      for-mod-creators-theory/modding-tools/redhottools/rht-hot-reload.md, section "The CET overlay
+      > Archives"
+    tags:
+      - redhottools
+      - hot-reload
+      - cet-overlay
+      - .xl
+      - archive
+    detail: "Direct quote: \"Pushing the button will not reload `.archive` files.\" The page adds that
+      RHT does that automatically by watching the `hot` folder. RELATED: this is the asymmetry that
+      cp2077.archivexl.manifest-registers-at-init describes from ArchiveXL's side (archives need a
+      restart to register, `.xl` entries do not) — RHT's hot-reload path narrows but does not
+      eliminate that asymmetry, since it still needs a manual button press for `.xl` changes
+      specifically."
+  - id: cp2077.redhottools.hotreload.triggers-are-sentinel-files
+    claim: "Red Hot Tools' three hot-reload triggers are file drops, not console or overlay actions:
+      creating an empty `red4ext/plugins/RedHotTools/.hot-scripts` makes the ScriptWatcher delete it
+      and run `ScriptLoader::ReloadScripts()`; writing anything to
+      `red4ext/plugins/RedHotTools/.hot-tweaks` makes the TweakWatcher delete it and call
+      `TweakXL.Reload()` on the next main-loop tick; and copying an `.archive` (with any `.xl`) into
+      `archive/pc/hot` makes the ArchiveWatcher ingest it. ModWright can therefore drive all three
+      through its own file-writing transport (deploy --reload apply)."
+    status: inferred
+    source: psiberx/cp2077-red-hot-tools src/App/Environment.hpp (the sentinel paths) and
+      src/App/Scripts/ScriptWatcher.cpp, src/App/Tweaks/TweakWatcher.cpp,
+      src/App/Archives/ArchiveWatcher.cpp (the watchers), read 2026-09-13; the support/vscode
+      extension issues the same triggers
+    tags:
+      - redhottools
+      - hot-reload
+      - sentinel
+      - hot-scripts
+      - hot-tweaks
+      - hot-folder
+      - deploy
+    detail: 'Status: the mechanism is VERIFIED from RHT source; its EFFECT in the engine splits by
+      trigger, per an in-game test (2026-09-13, RHT 1.3.0.33690, on a live game): the
+      `archive/pc/hot` half is VERIFIED WORKING (RHT moved the archive out and logged "Archives
+      reload completed" after the trigger — see the archives read-back and
+      hot-folder-moves-into-mods); the `.hot-tweaks` half is VERIFIED INEFFECTIVE — the sentinel is
+      deleted/consumed but no TweakXL.Reload follows (see hot-tweaks-consumed-without-reload-1.3.0);
+      `.hot-scripts` is still untested. So "ModWright can drive all three" holds only for archives;
+      tweaks must go through TweakXL.Reload() via cp2077.lua.eval. RELATED:
+      cp2077.redhottools.hotreload.hot-folder-moves-into-mods (the archive half) and
+      cp2077.process.assetbuild.rht-hot-folder-banned-for-whole-mesh-archives.'
+  - id: cp2077.redhottools.hotreload.hot-tweaks-consumed-without-reload-1.3.0
+    claim: "In Red Hot Tools 1.3.0.33690, dropping `red4ext/plugins/RedHotTools/.hot-tweaks` is consumed
+      (RHT deletes the file) but does NOT drive a TweakXL reload: after an edited `r6/tweaks` file
+      was deployed and `.hot-tweaks` written and deleted, TweakXL.log showed no import after the
+      launch-time one and the changed flat was unchanged in TweakDB. A direct `TweakXL.Reload()`
+      (via cp2077.lua.eval) on the same session then DID apply the change. So the working tweak
+      hot-reload path is `TweakXL.Reload()` through the bridge, not the `.hot-tweaks` sentinel."
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - redhottools
+      - hot-tweaks
+      - tweakxl
+      - hot-reload
+      - negative-result
+    detail: The `archive/pc/hot` watcher works in the same build and session, so this is specific to the
+      `.hot-tweaks` path, not a dead RHT. deploy --reload apply should reload tweaks via
+      TweakXL.Reload() through the bridge rather than (or in addition to) the sentinel; the sentinel
+      is kept only because it is harmless and may work in other RHT builds.
+  - id: cp2077.redhottools.hotreload.presence-not-version-floor
+    claim: "Whether the hot-reload path is available is decided by presence, not a version floor: the
+      `RedHotTools.dll` is installed AND the current `RedHotTools*.log` carries this launch's
+      `[ArchiveWatcher] Watching` line. `scc.exe` carries no redscript version (gap 12), so a floor
+      check on redscript cannot be evaluated and would refuse a working install; the README's
+      framework floors stay an advisory only."
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - redhottools
+      - presence-detection
+      - version-floor
+      - archivewatcher
+      - deploy
+    detail: "Supersedes the reliance on cp2077.redhottools.hotreload.version-floors as a gate: those
+      framework versions are reported for information, but ModWright's reload classifier
+      (src/core/deploy/reload.ts detectRedHotTools) now gates the RHT-dependent rows on the DLL +
+      the watcher line instead. RHT 1.3.0 is installed and current while the README floors read
+      2.21, so a floor check would have refused it."

package/knowledge/cyberpunk2077/redscript.compile-log.yaml

@@ -0,0 +1,76 @@
+game: cyberpunk2077
+topic: redscript.compile-log
+title: redscript's startup log line, log/script/cache file locations
+facts:
+  - id: cp2077.redscript.compile-log.startup-log-line-format
+    claim: On every compile, `scc` (the redscript compiler) logs `"Running REDscript {version}"` via
+      `log::info!`, where `{version}` is `env!("CARGO_PKG_VERSION")` — the compiling crate's own
+      Cargo package version, not the game's version.
+    status: verified
+    source: jac3km4/redscript@3ca666c crates/scc/core/src/lib.rs:34 (`log::info!("Running REDscript {}",
+      env!("CARGO_PKG_VERSION"));`, inside `pub fn compile`)
+    tags:
+      - redscript
+      - compile-log
+      - version
+      - startup
+    detail: "At the snapshot under refs/, the workspace `Cargo.toml` pins `version =
+      \"1.0.0-preview.22\"` (Cargo.toml:21), so a log parser matching this exact source tree would
+      see \"Running REDscript 1.0.0-preview.22\" — but the log line itself always reflects whatever
+      version the installed `scc` binary was built from, not a fixed string. Offline check
+      2026-09-09: the installed build does NOT write this line. `engine/tools/scc.exe` and
+      `scc_lib.dll` (both dated 2025-08-28, no PE FileVersion resource) produce a
+      `r6/logs/redscript_rCURRENT.log` whose first line is `[INFO - Wed, 9 Sep 2026 07:52:43 -0700]
+      Compiling files in <game>\\r6\\scripts:` followed by one `.reds` path per line, and no line
+      containing \"REDscript\" appears anywhere in the 509-line log; the dated copies from
+      2026-09-08 have the same shape. So the claim holds for the cited source tree
+      (1.0.0-preview.22) but not for every shipped `scc`; the 2025-08-28 build predates or omits the
+      banner. Consequence for ModWright: `check_compat`'s banner fallback
+      (src/surfaces/cyberpunk2077/compat.ts) cannot read a version on this install and reports
+      redscript undetermined, so every framework floor on redscript is a warning rather than a
+      check."
+  - id: cp2077.redscript.compile-log.log-file-location
+    claim: On Windows, a successful redscript setup is confirmed by log output appearing in `Cyberpunk
+      2077/r6/logs/redscript_rCURRENT.log`.
+    status: community
+    source: jac3km4/redscript@3ca666c README.md:15, section "Windows"
+    tags:
+      - redscript
+      - log-file
+      - windows
+  - id: cp2077.redscript.compile-log.default-scripts-dir-is-r6-scripts
+    claim: "`scc`'s default script source directory, relative to the game's root directory, is
+      `r6/scripts` (`R6_DIR` = \"r6\", `SCRIPTS_DIR` = \"scripts\"); additional script paths can be
+      layered on top of this default via `SccSettings`, but the default is always included."
+    status: verified
+    source: jac3km4/redscript@3ca666c crates/scc/core/src/settings.rs:11-13 (the `R6_DIR`/`SCRIPTS_DIR`
+      constants) and :59-66 (`default_scripts_dir_path` joins `root_dir/r6/scripts`, and
+      `script_paths()` always yields it first before any `additional_script_paths`)
+    tags:
+      - redscript
+      - r6-scripts
+      - layout
+      - compiler
+  - id: cp2077.redscript.compile-log.compiled-cache-bundle-path
+    claim: "`scc` writes its compiled script bundle by default to `r6/cache/final.redscripts` (relative
+      to the game root), with a backup of the previous bundle kept alongside as
+      `final.redscripts.bk`; a custom output cache file path can override this default."
+    status: verified
+    source: jac3km4/redscript@3ca666c crates/scc/core/src/settings.rs:8-9
+      (`BUNDLE_FILE`/`BACKUP_BUNDLE_FILE` constants), :55-57 (`default_cache_file_path` joining
+      `root_dir/r6/cache/final.redscripts`) and :80-85 (`default_backup_cache_file_path` joining
+      `root_dir/r6/cache/final.redscripts.bk`)
+    tags:
+      - redscript
+      - cache
+      - final.redscripts
+      - layout
+  - id: cp2077.redscript.compile-log.user-hints-dir
+    claim: "`scc` reads user-authored compiler hints from `r6/config/redsUserHints` under the game root."
+    status: verified
+    source: jac3km4/redscript@3ca666c crates/scc/core/src/settings.rs:15 (`USER_HINTS_DIR` =
+      "redsUserHints") and :48-53 (`user_hints_dir()` joins `root_dir/r6/config/redsUserHints`)
+    tags:
+      - redscript
+      - user-hints
+      - layout

package/knowledge/cyberpunk2077/redscript.modules.yaml

@@ -0,0 +1,118 @@
+game: cyberpunk2077
+topic: redscript.modules
+title: redscript's module declaration, import forms and item qualifiers, from the parser grammar
+facts:
+  - id: cp2077.redscript.modules.module-declaration-is-optional-dotted-path
+    claim: A `.reds` file's `module` declaration is optional and, when present, takes a dotted path of
+      one or more identifiers (e.g. `module Test.Module`); the parser accepts a file with no
+      `module` line at all (the module path is `Option`-typed in the grammar) — module scoping is
+      not mandatory for every script file.
+    status: verified
+    source: 'jac3km4/redscript@3ca666c crates/syntax/parser/src/parser.rs:123-140 (the `module` parser:
+      `just(Token::Ident("module"))` followed by a dot-separated identifier path with
+      `.at_least(1)`, wrapped in `.or_not()`)'
+    tags:
+      - redscript
+      - module
+      - parser
+      - grammar
+    detail: Confirmed against the formatter's own test fixture
+      crates/syntax/formatter/tests/data/module.reds, whose first non-blank line is `module
+      Test.Module` followed by an `import Dummy.*` line and then item declarations — matching the
+      grammar's module-then-imports-then-items shape.
+  - id: cp2077.redscript.modules.three-import-forms
+    claim: "redscript's import grammar accepts three forms of a dotted path after `import`: `import
+      A.B.C` (exact import of a single path), `import A.B.*` (wildcard import of everything under a
+      path) and `import A.B.{X, Y}` (a selector list of specific names under a path); the AST
+      records these as `Import::Exact`, `Import::All` and `Import::Select` respectively."
+    status: verified
+    source: jac3km4/redscript@3ca666c crates/syntax/parser/src/parser/item.rs:196-211 (the `import`
+      parser building `Import::Select(path, idents)` at :207, `Import::All(path)` at :208 or
+      `Import::Exact(path)` at :209 depending on whether an import selector follows the path)
+    tags:
+      - redscript
+      - import
+      - module
+      - parser
+      - grammar
+  - id: cp2077.redscript.modules.item-qualifier-keywords
+    claim: "redscript's item-qualifier keywords, i.e. the modifiers a class/function/field declaration
+      can carry before its body, are: `abstract`, `cb` (marks a callback), `const`, `exec`, `final`,
+      `importonly`, `native`, `persistent`, `quest` and `static` — each is parsed into a distinct
+      `ItemQualifiers` bit flag."
+    status: verified
+    source: jac3km4/redscript@3ca666c crates/syntax/parser/src/parser/item.rs:240-249, function
+      `item_qualifier` (the `select!` match listing all ten keyword-to-flag pairs)
+    tags:
+      - redscript
+      - qualifier
+      - keyword
+      - grammar
+  - id: cp2077.redscript.modules.exec-qualifier-sets-is-exec-flag
+    claim: The `exec` qualifier on a global function is threaded through the compiler as a boolean
+      `is_exec` flag on the function's resolved metadata
+      (`.with_is_exec(qs.take_flag(ast::ItemQualifiers::EXEC))`); the parser and frontend resolution
+      stage both handle `exec` as a distinct qualifier from `static`/`native`/etc., but neither of
+      those two source locations documents what `is_exec` changes about how the function can be
+      invoked (e.g. from the game's console) — that runtime behavior is not covered by this source.
+    status: verified
+    source: jac3km4/redscript@3ca666c crates/syntax/parser/src/parser/item.rs:243 (`Token::Ident("exec")
+      => ItemQualifiers::EXEC`); crates/compiler/frontend/src/stages/resolution.rs:816
+      (`.with_is_exec(qs.take_flag(ast::ItemQualifiers::EXEC))`, building `FreeFunctionFlags`)
+    tags:
+      - redscript
+      - exec
+      - qualifier
+      - gap
+    detail: "Left deliberately narrow per the transcription-lesson rule: the compiler plumbing for
+      `exec` is confirmed, but its actual observable effect (console-exposure, if any) is not
+      asserted here because neither cited file states it."
+  - id: cp2077.redscript.modules.duplicate-global-func-crashes-the-script-load
+    claim: "Two module-less global functions with the same name and the same parameter types but
+      different parameter names and return types (`Mod_Possess(target: ref<GameObject>) -> Bool` in
+      one file, `Mod_Possess(body: ref<GameObject>) -> String` in another) compile: redscript
+      reports \"Output successfully saved\" and RED4ext registers the blob. The 2.31 engine then
+      crashes at launch, right after \"Scripts blob path was updated\", with an access violation
+      reading 0x28 at exe+0x5C61A4. The crashing routine (fn_5C60F8) copies one function definition
+      onto another. It looks up each parameter by name in the other definition's parameter array
+      (fn_5C5B88) and reads the result's +0x28 unchecked; the missing name was \"body\" (hash
+      CD4DE79BC6C93295 in rdx)."
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - redscript
+      - global
+      - module-less
+      - duplicate
+      - crash
+      - script-load
+    detail: The hash was matched by FNV-1a 64 against every identifier in the deployed r6/scripts tree;
+      "body" was the only match. A validator rule (cp2077.history.redscript-duplicate-global-func)
+      reports the shape before a launch.
+  - id: cp2077.redscript.modules.module-name-with-a-space-does-not-compile
+    claim: "A module declaration must be a dotted identifier path: `module FTR Settings` fails the whole
+      script compile with a syntax error at the space, and the game starts with no mod scripts
+      active."
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - redscript
+      - module
+      - syntax
+      - scaffold
+    related:
+      - cp2077.redscript.modules.module-declaration-is-optional-dotted-path
+  - id: cp2077.redscript.modules.scriptable-system-registered-under-module-qualified-name
+    claim: A ScriptableSystem declared inside `module M` is registered in the scriptable systems
+      container under its module-qualified name `M.<Class>`; looking it up by the bare class name
+      finds nothing.
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - redscript
+      - module
+      - scriptablesystem
+      - cet