modwright 0.1.1 → 0.1.3

package/dist/surfaces/stardewvalley/writes.js

@@ -0,0 +1,136 @@
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { hasTokens, parseContentJson, patchesOf, pick, splitLexically } from "./contentpatcher.js";
+const MAX_INCLUDE_DEPTH = 5;
+const obj = (v) => v && typeof v === "object" && !Array.isArray(v) ? v : undefined;
+function push(ctx, write) {
+    const full = { ...write, file: ctx.file };
+    if (ctx.unit)
+        full.unit = ctx.unit;
+    ctx.writes.push(full);
+}
+function patchWrites(cfg, ctx) {
+    const includes = [];
+    for (const patch of patchesOf(cfg).patches) {
+        const when = obj(pick(patch.raw, "When")?.value);
+        const condition = when && Object.keys(when).length > 0 ? JSON.stringify(when) : undefined;
+        const action = patch.action?.trim().toLowerCase();
+        if (action === "include") {
+            for (const from of splitLexically(patch.fromFile ?? "")) {
+                includes.push(condition ? { fromFile: from, condition } : { fromFile: from });
+            }
+            continue;
+        }
+        const targets = splitLexically(patch.target ?? "");
+        for (const target of targets) {
+            const certainty = (...parts) => condition || hasTokens(target) || parts.some((p) => hasTokens(p)) ? "conditional" : "definite";
+            const base = (extra = {}) => (condition ? { condition, ...extra } : extra);
+            if (action === "load") {
+                const w = { key: target, keyKind: "asset", op: "load", certainty: certainty(), ...base() };
+                if (patch.fromFile)
+                    w.value = patch.fromFile;
+                push(ctx, w);
+            }
+            else if (action === "editdata") {
+                const tf = pick(patch.raw, "TargetField")?.value;
+                const prefix = Array.isArray(tf) && tf.length > 0 ? `${target}#${tf.map(String).join(".")}` : undefined;
+                const entryKey = (k) => (prefix ? `${prefix}.${k}` : `${target}#${k}`);
+                let parts = 0;
+                const entries = obj(pick(patch.raw, "Entries")?.value);
+                for (const [k, v] of Object.entries(entries ?? {})) {
+                    push(ctx, { key: entryKey(k), keyKind: "asset-entry", op: v === null ? "remove" : "set", value: v, certainty: certainty(k), ...base() });
+                    parts++;
+                }
+                const fields = obj(pick(patch.raw, "Fields")?.value);
+                for (const [k, fieldMap] of Object.entries(fields ?? {})) {
+                    for (const [f, v] of Object.entries(obj(fieldMap) ?? {})) {
+                        push(ctx, { key: `${entryKey(k)}.${f}`, keyKind: "asset-field", op: v === null ? "remove" : "set", value: v, certainty: certainty(k, f), ...base() });
+                        parts++;
+                    }
+                }
+                const textOps = pick(patch.raw, "TextOperations")?.value;
+                for (const op of Array.isArray(textOps) ? textOps : []) {
+                    const o = obj(op);
+                    const opTarget = o ? pick(o, "Target")?.value : undefined;
+                    if (!Array.isArray(opTarget) || opTarget.length < 2)
+                        continue;
+                    const [kind, ...rest] = opTarget.map(String);
+                    const operation = String((o && pick(o, "Operation")?.value) ?? "").toLowerCase();
+                    const writeOp = operation === "removedelimited" ? "remove" : operation === "replacedelimited" ? "set" : "append";
+                    const key = kind.toLowerCase() === "fields" ? `${entryKey(rest[0])}.${rest.slice(1).join(".")}` : entryKey(rest.join("."));
+                    push(ctx, { key, keyKind: kind.toLowerCase() === "fields" ? "asset-field" : "asset-entry", op: writeOp, value: o && pick(o, "Value")?.value, certainty: certainty(...rest), ...base() });
+                    parts++;
+                }
+                const moves = pick(patch.raw, "MoveEntries")?.value;
+                for (const move of Array.isArray(moves) ? moves : []) {
+                    const id = obj(move) && pick(obj(move), "ID")?.value;
+                    if (typeof id !== "string")
+                        continue;
+                    push(ctx, { key: entryKey(id), keyKind: "asset-entry", op: "edit", value: move, certainty: certainty(id), ...base() });
+                    parts++;
+                }
+                if (parts === 0)
+                    push(ctx, { key: target, keyKind: "asset", op: "edit", certainty: certainty(), ...base() });
+            }
+            else if (action === "editimage" || action === "editmap") {
+                const w = { key: target, keyKind: "asset", op: "edit", certainty: certainty(), ...base() };
+                const toArea = pick(patch.raw, "ToArea")?.value;
+                if (toArea !== undefined)
+                    w.value = { ToArea: toArea };
+                push(ctx, w);
+            }
+        }
+    }
+    return includes;
+}
+async function readPack(packDir, file, unit, extraction, depth) {
+    let cfg;
+    try {
+        cfg = parseContentJson(await fs.readFile(file, "utf8"));
+    }
+    catch (error) {
+        extraction.errors.push({ file, error: error.message });
+        return;
+    }
+    const ctx = { file, unit, writes: [] };
+    const includes = patchWrites(cfg, ctx);
+    extraction.writes.push(...ctx.writes);
+    for (const include of includes) {
+        if (hasTokens(include.fromFile)) {
+            extraction.errors.push({ file, error: `Include of "${include.fromFile}" uses tokens; not followed.` });
+            continue;
+        }
+        if (depth >= MAX_INCLUDE_DEPTH) {
+            extraction.errors.push({ file, error: `Include of "${include.fromFile}" is nested more than ${MAX_INCLUDE_DEPTH} deep; not followed.` });
+            continue;
+        }
+        const target = path.resolve(packDir, include.fromFile);
+        if (!target.startsWith(path.resolve(packDir) + path.sep)) {
+            extraction.errors.push({ file, error: `Include of "${include.fromFile}" points outside the pack; not followed.` });
+            continue;
+        }
+        const before = extraction.writes.length;
+        await readPack(packDir, target, unit, extraction, depth + 1);
+        if (include.condition) {
+            for (const w of extraction.writes.slice(before)) {
+                w.certainty = "conditional";
+                w.condition = w.condition ? `${include.condition} and ${w.condition}` : include.condition;
+            }
+        }
+    }
+}
+export async function extractStardewWrites(mod, root) {
+    if (root.id !== "mods")
+        return undefined;
+    const packs = mod.files.filter((f) => f.toLowerCase() === "content.json" || f.toLowerCase().endsWith("/content.json"));
+    if (packs.length === 0)
+        return undefined;
+    const extraction = { writes: [], errors: [] };
+    for (const rel of packs) {
+        const packRel = path.posix.dirname(rel);
+        const packDir = path.join(mod.path, packRel);
+        const unit = packRel === "." ? undefined : packRel;
+        await readPack(packDir, path.join(mod.path, rel), unit, extraction, 0);
+    }
+    return extraction;
+}

package/knowledge/baldursgate3/dialogue.osiris-goals.yaml

@@ -384,3 +384,32 @@ facts:
       Whether the journal .lsx under Mods/<Mod>/Story/Journals loads as loose .lsx was not separated
       from the missing compile; the RootTemplates rule (loose .lsx not loaded, .lsf needed) suggests
       it does not.
+  - id: bg3.dialogue.osiris-goals.prefix-convention-is-a-compiler-warning-in-lslib
+    claim: In LSLib's Osiris story compiler a database whose name does not start with "DB", a PROC whose
+      name does not start with "PROC" or a query whose name does not start with "QRY" produces a
+      warning (W26 DbNamingStyle, W23 RuleNamingStyle), never an error, and W23 is switched off by
+      default; the story still compiles.
+    status: inferred
+    source: Norbyte/lslib@6f5f698 LSLib/LS/Story/Compiler/Compiler.cs VerifyIRRule ("Name of PROC ...
+      should start with the prefix PROC", "Name of Query ... should start with the prefix QRY"),
+      VerifyDatabases ("Name of database ... should start with the prefix DB");
+      CompilationContext.cs DiagnosticCode RuleNamingStyle = "W23", DbNamingStyle = "W26",
+      CompilationLog() WarningSwitches[RuleNamingStyle] = false
+    tags:
+      - osiris
+      - naming
+      - db-prefix
+      - proc-prefix
+      - qry-prefix
+      - compiler
+      - warning
+    detail: "This is the community compiler's behaviour, not Larian's in-engine one: there the prefix is
+      a style check. Nothing read in that source supports the claim, attributed to a Nexus article,
+      that a missing prefix silently disables the whole story component; until the game's own
+      compiler is shown to behave differently, the bg3.story.osiris-naming-convention validator rule
+      stays informational. The checks compare the first 2-4 characters case-insensitively
+      (\"PROC\"/\"QRY\"/\"DB\"), and the PROC and QRY checks skip names no longer than the prefix,
+      so \"Proc_X\" and \"dbFoo\" pass them."
+    related:
+      - id: bg3.dialogue.osiris-goals.qry-proc-color-coding
+        detail: Agrees on the convention itself; adds what the compiler does when it is broken.

package/knowledge/baldursgate3/osiris.tags.yaml

@@ -0,0 +1,78 @@
+game: baldursgate3
+topic: osiris.tags
+title: "Osiris entity tags: SetTag/IsTagged/ClearTag and the tag events, from Larian's modding wiki
+  and the generated stubs"
+facts:
+  - id: bg3.osiris.tags.settag-istagged-cleartag-signatures
+    claim: Osiris tags an entity with the call SetTag((GUIDSTRING)_Target, (TAG)_Tag), tests it with the
+      query IsTagged([in](GUIDSTRING)_Target, [in](TAG)_Tag, [out](INTEGER)_Bool), and removes it
+      with the call ClearTag((GUIDSTRING)_Source, (TAG)_Tag). In the Script Extender's Osi table
+      these are Osi.SetTag(target, tag), Osi.IsTagged(target, tag) -> integer, and
+      Osi.ClearTag(target, tag).
+    status: verified
+    source: wiki pages SetTag ("call SetTag((GUIDSTRING)_Target, (TAG)_Tag)"), IsTagged ("query
+      IsTagged([in](GUIDSTRING)_Target, [in](TAG)_Tag, [out](INTEGER)_Bool)"), ClearTag
+      ("ClearTag((GUIDSTRING)_Source, (TAG)_Tag)"); LaughingLeader/BG3ModdingTools@ab343b6
+      generated/ Osi.lua:4273-4275 (SetTag), :1840-1843 (IsTagged, @return integer bool), :2570-2572
+      (ClearTag).
+    tags:
+      - osiris
+      - tag
+      - settag
+      - istagged
+      - cleartag
+      - signature
+    detail: "Verified as declared signatures only; what the calls do at runtime was not observed. The
+      wiki's own examples: SetTag(_ParentA, (TAG)_SHADOW_CURSE_IMMUNE) inside a PROC;
+      IsTagged(_Player, (TAG)_DARK_URGE, 1) as an AND condition in a QRY (the trailing 1 binds the
+      out-param to \"true\"). A TAG is a UUID-keyed resource, referenced in story scripts by a named
+      constant; the wiki examples use (TAG)_NAME constants, which the story compiler resolves."
+  - id: bg3.osiris.tags.cleartag-only-clears-osiris-set-tags
+    claim: ClearTag removes only tags that Osiris itself set. Tags placed via the editor sidebar on a
+      root template or on an object instance cannot be cleared this way (a polymorph status replaces
+      them with the target template's, but plain Transform calls leave them), and tags set from
+      Anubis or from dialogs can only be cleared from those same systems (dialog tags via
+      ClearDialogTag).
+    status: community
+    source: wiki page ClearTag, "Further Information" section (last edited 2024-12-16); ClearDialogTag
+      is Osi.ClearDialogTag(target, tag) at LaughingLeader/BG3ModdingTools@ab343b6
+      generated/Osi.lua:2522-2524.
+    tags:
+      - osiris
+      - tag
+      - cleartag
+      - gotcha
+      - roottemplate
+      - dialog
+    related:
+      - bg3.osiris.tags.settag-istagged-cleartag-signatures
+    detail: "Practical consequence for a probe or test row: IsTagged answers for every tag source, so a
+      tag that \"will not clear\" is usually one that was never Osiris-owned — check the root
+      template's sidebar tags before treating a failed ClearTag as a scripting bug."
+  - id: bg3.osiris.tags.tag-events-and-inventory-tag-queries
+    claim: "Osiris declares tag-related events — CharacterTagEvent(character, tag, event),
+      TagCleared(target, tag), TagEvent(tag, event), TagSet(target, tag) — and inventory queries
+      that take their tags as a string rather than a TAG: GetByTagInInventory(tags, inventoryHolder)
+      -> GUIDSTRING, GetItemByTagInInventory(tags, inventoryHolder) -> ITEM, and
+      TaggedItemsGetCountInMagicPockets(tags, source) -> integer. HasAppearanceVisualTag(character,
+      tag) -> integer tests visual tags separately."
+    status: verified
+    source: LaughingLeader/BG3ModdingTools@ab343b6 generated/Osi.Events.lua:237
+      CharacterTagEvent(character, tag, event); Osi.Events.lua:1197 TagCleared(target, tag);
+      Osi.Events.lua:1201 TagEvent(tag, event); Osi.Events.lua:1205 TagSet(target, tag);
+      generated/Osi.lua:796-799 (GetByTagInInventory), :1006-1009 (GetItemByTagInInventory),
+      :2136-2139 (TaggedItemsGetCountInMagicPockets), :1347-1350 (HasAppearanceVisualTag).
+    tags:
+      - osiris
+      - tag
+      - event
+      - inventory
+      - tag-expression
+    related:
+      - bg3.osiris.tags.settag-istagged-cleartag-signatures
+    detail: Verified as declared signatures only; when the events fire and what the queries return at
+      runtime was not observed. The wiki's search-result snippets describe the string argument as a
+      tag expression, but its grammar (how several tags combine) is not established by anything read
+      here; test it before relying on more than a single tag name. Recorded so a future BG3 probe
+      kind for "is the scaffolded entity tagged" has its call shapes on file; none is registered yet
+      (bg3.entity.* probes go through the Script Extender's Ext.Entity, not Osiris tags).

package/knowledge/cyberpunk2077/cet.rtti-binding.yaml

@@ -0,0 +1,227 @@
+game: cyberpunk2077
+topic: cet.rtti-binding
+title: "How Cyber Engine Tweaks binds the game's RTTI to Lua: globals, the Game table, member calls,
+  out-params, structs, arrays"
+facts:
+  - id: cp2077.cet.rtti-global-functions-reachable-bare-and-via-game-table
+    claim: "CET exposes every non-member, non-exec RTTI global function to Lua under three names: the
+      bare short name as a sandbox global (`TSF_NPC()`), `Game.TSF_NPC()` (short-name lookup, with
+      an overload dispatcher when several arities exist), and `Game[\"TSF_NPC;\"]()` (exact RTTI
+      full name). So the TSF_*/TSQ_* target-search constructors listed in the RTTI dump's
+      globals.json are callable from a CET console or mod without any wrapper."
+    status: inferred
+    source: 'src/reverse/RTTIMapper.cpp:186-213 (RegisterDirectGlobals walks apRtti->funcs and sets
+      aLuaGlobal[shortName] = RTTIHelper::Get().ResolveFunction(shortName) for every function whose
+      full name has no "::" and whose short name has no ";", skipping flags.isExec; the target table
+      is the sandbox globals, RTTIMapper.cpp:34, which is the fallback environment of every mod and
+      of the console, src/scripting/Sandbox.cpp:6-11, Scripting.cpp:644);
+      src/scripting/Scripting.cpp:487 (globals["Game"] = this) and :675-686 (Scripting::Index ->
+      RTTIHelper::ResolveFunction); src/reverse/RTTIHelper.cpp:316-343 (branch on ";" in the name:
+      full-name GetFunction vs short-name FindFunctions, RTTIHelper.cpp:238-259, with
+      MakeInvokableOverload at :444).'
+    tags:
+      - cet
+      - lua
+      - rtti
+      - globals
+      - game-table
+      - tsf
+      - binding
+    related:
+      - cp2077.entities.gameobject-getentitiesaroundobject-filter-constructors-exist
+    detail: 'One residual the source cannot settle: the bare-global registration is skipped when the
+      game marks a function isExec. Nothing in CET says whether TSF_* carry that flag, so the bare
+      form is very likely but not proven; the two Game[...] forms do not depend on it. A single
+      console line settles all three at once: print(type(TSF_NPC), type(Game.TSF_NPC),
+      type(Game["TSF_NPC;"])).'
+  - id: cp2077.cet.game-table-resolves-globals-then-scriptgameinstance-statics-and-throws-on-miss
+    claim: "`Game.Foo` resolves first against RTTI global functions and then against
+      ScriptGameInstance's static functions, including script-added ones (a redscript
+      `@addMethod(GameInstance)` registers a global named \"ScriptGameInstance::Foo;...\" which CET
+      indexes per class), with the GameInstance parameter supplied automatically. A name that
+      resolves nowhere raises a Lua error rather than returning nil, and a successful resolution is
+      memoized on the Game table."
+    status: inferred
+    source: src/reverse/RTTIHelper.cpp:56 (m_pGameInstanceType = GetClass("ScriptGameInstance"));
+      :316-343 (globals first, then FindFunctions(m_pGameInstanceType, hash, false)); :59-80
+      (ParseGlobalStatics indexes every "Class::Func" global into m_extendedFunctions) and :283-294
+      (the static branch searches that map alongside staticFuncs); :598 (GameInstance and out params
+      excluded from the arity check) and :657-671 (GameInstance auto-supplied, erroring "can't be
+      used yet because game instance is not ready" before the engine is up);
+      src/scripting/Scripting.cpp:686 ("Function Foo is not a GameInstance member and is not a
+      global.") with s_cThrowLuaErrors = true at RTTIHelper.cpp:17; Scripting.cpp:677-702
+      (memoization into m_properties on success only).
+    tags:
+      - cet
+      - lua
+      - game-table
+      - scriptgameinstance
+      - codeware
+      - addmethod
+      - error-handling
+    related:
+      - cp2077.rtti.scriptgameinstance-getxxx-system-getters
+      - cp2077.entities.gettaggedids-is-a-dynamic-entity-registry-not-a-node-lookup
+    detail: "This is why Game.GetDynamicEntitySystem() (Codeware's @addMethod addition, attested in a
+      shipped CET mod's script) and Game.GetGameTagSystem() (a native ScriptGameInstance static) go
+      through the same door. Probe-design consequence: a bare-global existence check (type(TSF_NPC))
+      is nil on a miss, but Game.Missing() throws — every handler in probes.lua that touches Game.*
+      must stay pcall-wrapped, which they are. The \"how redscript names an @addMethod(GameInstance)
+      function\" half is one reading step beyond CET's code (CET only shows it handles Class::Func
+      globals); the attested Game.GetDynamicEntitySystem() call is the evidence that the step holds
+      in practice."
+  - id: cp2077.cet.member-calls-via-colon-and-out-params-as-extra-returns
+    claim: "An RTTI object reaches Lua as a StrongReference/WeakReference/ClassReference userdata whose
+      __index resolves properties first, then member functions, so `obj:Method(args)` is the
+      supported call form. Out-parameters are never taken from Lua: CET allocates them and appends
+      their values after the return value, in declaration order, so a function declared `Bool
+      F(CName tag, out array<ref<entEntity>> entities)` is called `local ok, entities = obj:F(tag)`.
+      A static function can also be called through an instance."
+    status: inferred
+    source: "src/scripting/Scripting.cpp:186-200 (usertype __index -> ClassType::Index);
+      src/reverse/Type.cpp:229-256 (Index_Impl: properties, then ResolveFunction(class, name,
+      hasHandle), cached on the object; :238 a same-named property wins over a method);
+      src/reverse/RTTIHelper.cpp:514-566 (ResolveHandle pops the colon-call self as the RED context,
+      type-checked against the function's class at :551-553); :673-681 (out params get zeroed
+      placeholders) and :742-757 (results = return value, then every isOut param); :598 (out params
+      excluded from arity); :386-395 (instance call falls back to static scope)."
+    tags:
+      - cet
+      - lua
+      - rtti
+      - member-call
+      - out-params
+      - binding
+    related:
+      - cp2077.entities.native-gametagsystem-finds-entities-by-tag
+    detail: "Direct consequence for the native tag lookup: gameGameTagSystem::GetAllMatchingEntities
+      returns two Lua values, `ok, entities`, not the array alone. GetAnyMatchingEntity has no out
+      param and returns the handle directly."
+  - id: cp2077.cet.native-struct-values-are-classreference-copies-that-round-trip
+    claim: A non-handle RTTI class/struct value returned to Lua (for example the gameTargetSearchFilter
+      a TSF_* constructor returns) becomes a ClassReference userdata holding its own copy of the
+      struct, and passing that userdata back as a struct-typed parameter hands the copy's pointer
+      through unchanged. Building such a struct from a Lua table is disabled in CET, so the
+      constructor functions are the only way to obtain one.
+    status: inferred
+    source: "src/reverse/Converter.h:192-247 (ClassConverter: ToLua wraps in ClassReference(type,
+      value); ToRED takes aObject.as<ClassReference*>()->GetHandle(), else nullptr; the Lua-table
+      path is commented out at :213-227; Is() at :238-247 matches any Class type);
+      src/reverse/ClassReference.cpp:9-11 (constructor allocates and Assigns a copy)."
+    tags:
+      - cet
+      - lua
+      - rtti
+      - struct
+      - classreference
+      - tsf
+      - binding
+    related:
+      - cp2077.entities.gameobject-getentitiesaroundobject-filter-constructors-exist
+    detail: "This removes the \"guessing a native struct layout\" worry recorded earlier for
+      GetEntitiesAroundObject(range, searchFilter): the filter is obtained from TSF_NPC()/
+      TSF_All(mask)/... and passed straight back. Caveat from the same code: ToRED does not check
+      that the ClassReference's type matches the parameter type, so passing the wrong struct is not
+      caught by CET. The struct has no listed properties in the RTTI dump, so indexing it from Lua
+      yields nothing."
+  - id: cp2077.cet.float-params-from-numbers-and-array-returns-as-tables-with-nil-holes
+    claim: A Float parameter accepts a plain Lua number (20 and 20.0 alike). An array return value
+      becomes a fresh 1-based Lua table; elements that are handles become StrongReference userdata,
+      but a null handle inside the array becomes nil, so `#t` and ipairs can stop early — count with
+      a pairs loop when the array may contain empty slots.
+    status: inferred
+    source: src/reverse/LuaRED.h:56-71 (arithmetic types converted from sol::type::number, cdata via
+      tostring/tonumber); src/scripting/Scripting.cpp:767-782 (array -> sol::table, result[i+1] =
+      ToLua(el)); :748-757 (a null handle returns sol::nil).
+    tags:
+      - cet
+      - lua
+      - rtti
+      - float
+      - array
+      - nil-hole
+      - binding
+    related:
+      - cp2077.entities.gameobject-getnpcsaroundobject-exists-in-rtti
+    detail: "probes.lua's existing handlers use ipairs over GetTaggedIDs results (EntityID values, not
+      handles, so no holes there). The nearby handler iterates handle arrays and should count with
+      pairs rather than #; the nil-hole consequence is one reading step from the nil return, hence
+      inferred like the rest."
+  - id: cp2077.cet.enum-params-accept-number-string-or-enum-but-undeclared-values-become-zero
+    claim: "An RTTI enum parameter accepts a Lua number, a member-name string, or an Enum userdata
+      (Enum.new(typeName, nameOrValue)), and every RTTI enum is also reachable as a global table
+      (TSFMV.Obj_Device). But a number or name that is not a declared member is replaced by 0
+      silently: only Enum.new with a misspelled TYPE name raises a Lua error. So an ORed combination
+      of members the game did not itself declare (e.g. 31 for every Obj_* bit of
+      gametargetingSystemSearchFilterMaskValue) reaches the engine as 0."
+    status: inferred
+    source: 'src/reverse/Converter.h:67-111 (EnumConverter::ToRED: Enum userdata with type check; nil ->
+      0; sol::type::number -> Enum(type, uint32); string -> Enum(type, name));
+      src/reverse/Enum.cpp:42-52 (SetValueSafe assigns only when the value matches a declared entry;
+      m_value defaults to 0 at Enum.h:35) and :105-120 (SetValueByName, same for names);
+      src/reverse/RTTIHelper.cpp:711-714 (the "parameter N must be X" error only fires on a null
+      result, which these paths never produce); src/scripting/Scripting.cpp:219-221 (Enum.new
+      constructors) and :223-234 (EnumInt); src/reverse/RTTIMapper.cpp:164-171 and :215-219
+      (EnumStatic globals and the TSFMV alias); src/reverse/EnumStatic.cpp:15-33 (any member name
+      indexes, typos included). Dump: enums.json lists exactly 20 declared TSFMV values, 31 not
+      among them.'
+    tags:
+      - cet
+      - lua
+      - rtti
+      - enum
+      - tsfmv
+      - silent-failure
+      - binding
+    related:
+      - cp2077.entities.gameobject-getentitiesaroundobject-filter-constructors-exist
+    detail: "Probe-design consequence: never pass a computed mask. Build filters from declared members
+      one at a time — TSF_Any(Enum.new(\"gametargetingSystemSearchFilterMaskValue\",
+      \"Obj_Device\")) — and combine with TSF_Or/TSF_And (2 to 4 filters; the dump marks tsf3/tsf4
+      optional and CET honours optional params, RTTIHelper.cpp:784-788). Use the Enum.new form so a
+      wrong type name is a loud error. Which member a sector-placed prop matches (Obj_Device,
+      Obj_Other, or none if it has no targeting component) is exactly what a live run must observe;
+      print(EnumInt(Enum.new(\"gametargetingSystemSearchFilterMaskValue\", 31))) printing 0 confirms
+      the silent-zero path live in one line. Native and script-defined globals register and resolve
+      by the same code (RTTIMapper.cpp:188-210; RTTIHelper.cpp:316); CET reads no native/script
+      flag. Which is which, per NativeDB's decoder (next fact): TSF_All/Any/Not/ And/Or (plain full
+      names) are native statics; TSF_NPC/TSF_EnemyNPC/TSF_Quickhackable (mangled \"Name;\" full
+      names) are script-side wrappers — an earlier draft of this fact had that backwards."
+  - id: cp2077.cet.nativedb-lua-generator-and-flag-layout-corroborate-the-binding
+    claim: "NativeDB, the community viewer built on the same RTTI dump, independently encodes the same
+      calling conventions: its \"Copy call\" generator for Lua · CET renders a global function as
+      Game.Name(...), a static member as Class.Name(...) with GameInstance aliased to Game, an
+      instance member as obj:Name(...), and types a CName parameter as `string | CName`. Its flag
+      decoder reads the dump's per-function flag word as bits isPrivate, isProtected, isNative,
+      isStatic, isFinal, isThreadSafe, isEvent, isConst, isQuest, isTimer — no exec bit — so the
+      dump cannot say whether a function is exec-only."
+    status: inferred
+    source: "rayshader/cp2077-nativedb at b5d29af: src/shared/formatters/lua.formatter.ts
+      (formatStaticCall -> `Game.${func.name}`, formatMemberStaticCall -> `${Class}.${name}` with
+      formatAlias mapping GameInstance to Game, formatMemberCall -> `${self}:${name}`,
+      LuaPrimitiveDef.CName = 'string | CName'); src/shared/red-ast/red-function.ast.ts:85-105
+      (fromJson decodes json.d) and :145-156 (enum RedFunctionFlags). Decoded flag words from
+      classes.json/globals.json: TSF_All/Any/Not/And/Or = 12 (isNative, isStatic);
+      TSF_NPC/EnemyNPC/Quickhackable = 40 (isStatic, isThreadSafe — script-defined);
+      ScriptGameInstance::GetGameTagSystem and GetTargetingSystem = 12 (native static);
+      gameGameTagSystem::GetAnyMatchingEntity/GetAllMatchingEntities and
+      gametargetingTargetingSystem::GetLookAtObject = 4 (native instance);
+      gameObject::GetNPCsAroundObject = 48 (isFinal, isThreadSafe — script-defined);
+      entEntity::GetCurrentAppearanceName = 132 (native, const)."
+    tags:
+      - cet
+      - lua
+      - rtti
+      - nativedb
+      - flags
+      - corroboration
+    related:
+      - cp2077.cet.rtti-global-functions-reachable-bare-and-via-game-table
+      - cp2077.cet.game-table-resolves-globals-then-scriptgameinstance-statics-and-throws-on-miss
+    detail: "Two consequences. First, the `string | CName` typing is a second, independent source for
+      passing plain Lua strings where a CName is expected, which probes.lua already relies on
+      (GetTaggedIDs(<tag>) with a plain string is attested live). Second, the exec question stays
+      open but is now bounded: CET skips bare-global registration only for functions the engine
+      flags isExec, that flag is not in the dump's word at all, and exec functions are console cheat
+      commands by design, so a TSF_* constructor carrying it would be surprising. The Game.TSF_X
+      form is unaffected either way and is what NativeDB itself generates."

package/knowledge/cyberpunk2077/cet.sandbox.yaml

@@ -217,3 +217,25 @@ facts:
       - hook
       - debugging
       - bridge
+  - id: cp2077.cet.sandbox.exec-func-vs-addmethod-reachability
+    claim: "From a CET mod's Lua environment, a module-less redscript `public static exec func Foo(gi:
+      GameInstance, ...)` is not reachable as `Game.Foo(...)`: the call returns with no Lua error,
+      but the function body never runs. An `@addMethod(<Class>)` instance method is reachable the
+      way a vanilla method is: `@addMethod(PlayerPuppet) public func Foo() -> String` is called as
+      `Game.GetPlayer():Foo()`, and its return value comes back to Lua. To read a value back from
+      redscript, add a method to a live game class and return the value; do not rely on an exec func
+      writing a log."
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - cet
+      - redscript
+      - addmethod
+      - exec-func
+      - bridge
+      - reachability
+      - lua-eval
+    detail: "This covers calls from a mod's Lua environment (where a bridge evaluates code). The CET
+      console, where a person types `Game.Foo()`, was not retested and may still reach exec funcs.
+      RELATED: cp2077.redhottools.hotreload.reloadscripts-recompiles-cleanly-storm-crash-1.3.0."

package/knowledge/cyberpunk2077/codeware.overview.yaml

@@ -6,7 +6,10 @@ facts:
     claim: "Codeware's own documentation groups its API surface under nine headings: Lifecycle, World,
       Entities, Player, User Interface, Resources, Localization, Reflection and Utilities."
     status: community
-    source: psiberx/cp2077-codeware/README.md, section "Documentation" (list)
+    source: 'psiberx/cp2077-codeware/README.md, section "Documentation" (list). Checked against commit
+      3a43182 (2026-08-28): README.md still lists exactly these nine headings in this order; this is
+      a documentation table of contents with no corresponding code to confirm or contradict it
+      against.'
     tags:
       - codeware
       - overview
@@ -22,8 +25,12 @@ facts:
       or a specific resource inside any mounted archive is present — the documented uses are
       verifying that the mod's own archive is actually enabled, and detecting whether another mod
       (and therefore a resource it ships) is installed."
-    status: community
-    source: psiberx/cp2077-codeware/wiki/Home.md, section "Resources > Checking resource existence"
+    status: inferred
+    source: 'psiberx/cp2077-codeware/wiki/Home.md, section "Resources > Checking resource existence";
+      confirmed against commit 3a43182 in scripts/Depot/ResourceDepot.reds: `public native func
+      ArchiveExists(name: String) -> Bool` and `public native func ResourceExists(path: ResRef) ->
+      Bool` on `public native class ResourceDepot`, reached via `@addMethod(GameInstance) public
+      static native func GetResourceDepot() -> ref<ResourceDepot>` in the same file.'
     tags:
       - codeware
       - resourcedepot
@@ -36,8 +43,14 @@ facts:
       caller registers a callback (`token.RegisterCallback(this, n"OnResourceReady")`) and only
       accesses `token.GetResource()` inside that callback — resource loading through this API is
       asynchronous, not a direct return value.
-    status: community
-    source: psiberx/cp2077-codeware/wiki/Home.md, section "Resources > Reading resources"
+    status: inferred
+    source: 'psiberx/cp2077-codeware/wiki/Home.md, section "Resources > Reading resources"; confirmed
+      against commit 3a43182 in scripts/Depot/ResourceDepot.reds: `public native func
+      LoadResource(path: ResRef) -> ref<ResourceToken>`, and scripts/Depot/ResourceToken.reds:
+      `public native class ResourceToken` declares `GetResource() -> ref<CResource>`,
+      `RegisterCallback(target: ref<IScriptable>, function: CName)`, plus
+      `IsFinished`/`IsLoaded`/`IsFailed` — there is no synchronous accessor, only the
+      callback-registration path the wiki describes.'
     tags:
       - codeware
       - resourcedepot
@@ -49,8 +62,14 @@ facts:
       assigning a resource depot path to it with the `*=` operator (the wiki's example is
       `weapon.effect *= r"base\gameplay\game_effects\strongmelee.es";`); `*=` is the only
       initialization form the page shows.
-    status: community
-    source: psiberx/cp2077-codeware/wiki/Home.md, section "Resources > Resource references"
+    status: inferred
+    source: "psiberx/cp2077-codeware/wiki/Home.md, section \"Resources > Resource references\";
+      confirmed against commit 3a43182 in scripts/Base/Addons/WeaponObject.reds:
+      `@addField(WeaponObject) public native let effect: ResourceRef; // rRef<gameEffectSet>` — the
+      exact field the wiki's `weapon.effect *= r\"...\"` example assigns to. The `ResourceRef` type
+      itself is Codeware's own wrapper, registered as `RTTI_DEFINE_CLASS(App::ResourceWrapper,
+      \"ResourceRef\", {...})` in src/App/Depot/ResourceReference.hpp, whose `LoadPath` method
+      resolves and starts loading the assigned path — the backing for `*=`'s effect."
     tags:
       - codeware
       - resourceref
@@ -65,26 +84,48 @@ facts:
       `DefineTexts()`/`DefineSubtitles()` using `Text`/`TextM`/`TextF` (and
       `Subtitle`/`SubtitleM`/`SubtitleF`) calls, with gendered variants set either as two separate
       calls or one three-argument `Text(key, female, male)` call."
-    status: community
-    source: psiberx/cp2077-codeware/wiki/Home.md, sections "Localization > Localization providers" and
-      "Localization > Localization packages"
+    status: inferred
+    source: 'psiberx/cp2077-codeware/wiki/Home.md, sections "Localization > Localization providers" and
+      "Localization > Localization packages"; confirmed against commit 3a43182 in
+      scripts/Localization/Module/ModLocalizationProvider.reds (`public abstract class
+      ModLocalizationProvider extends ScriptableSystem` with `GetPackage(language: CName) ->
+      ref<ModLocalizationPackage>` and `GetFallback() -> CName`) and
+      scripts/Localization/Module/ModLocalizationPackage.reds (`public abstract class
+      ModLocalizationPackage` with `DefineTexts`/ `DefineSubtitles` and the
+      `Text`/`TextF`/`TextM`/`Subtitle`/ `SubtitleF`/`SubtitleM` overloads, including the two-arg
+      and three-arg `Text(key, valueF, valueM)` form).'
     tags:
       - codeware
       - localization
       - modlocalizationprovider
       - modlocalizationpackage
-    detail: Texts registered this way are also pushed into the native localization system, so they
+    detail: "Texts registered this way are also pushed into the native localization system, so they
       remain reachable via `GetLocalizedTextByKey`/`GetLocalizedText` and from TweakDB records — not
-      only from the mod's own redscript.
+      only from the mod's own redscript. Confirmed for interface texts specifically:
+      src/App/Localization/LocalizationService.cpp hooks the native `LoadTexts` raw function and, in
+      `OnLoadTexts`, walks every non-abstract `ModLocalizationProvider` subclass via RTTI, calls its
+      `GetOnScreenEntries`, and merges the results into the native
+      `localizationPersistenceOnScreenEntries` list by primary/secondary key. Subtitle texts
+      (`EntryType.Subtitle`) are not part of that native merge — they stay served through
+      `LocalizationSystem.GetSubtitle` at runtime instead."
   - id: cp2077.codeware.overview.reflection-get-class-and-call
     claim: "Codeware's `Reflection` API lets a mod resolve a class by name
       (`Reflection.GetClass(n\"...\")` or `Reflection.GetTypeOf(instance)`), enumerate its
       properties/functions, and read/write/call them dynamically: `prop.GetValue(instance)`,
       `getter.Call(instance)`, `setter.Call(instance, [args])`, with a `status`-returning overload
       of `Call` available to detect argument-count/signature mismatches instead of throwing."
-    status: community
-    source: psiberx/cp2077-codeware/wiki/Home.md, sections "Reflection > Inspecting types and values"
-      and "Reflection > Custom callbacks"
+    status: inferred
+    source: 'psiberx/cp2077-codeware/wiki/Home.md, sections "Reflection > Inspecting types and values"
+      and "Reflection > Custom callbacks"; confirmed against commit 3a43182 in
+      scripts/Reflection/Reflection.reds (`public native struct Reflection` with `GetClass(name:
+      CName) -> ref<ReflectionClass>` and `GetTypeOf(value: Variant) -> ref<ReflectionType>`),
+      scripts/Reflection/ReflectionProp.reds (`GetValue(owner: Variant) -> Variant` /
+      `SetValue(owner: Variant, value: Variant)`), and scripts/Reflection/ReflectionFunc.reds
+      (`public native class ReflectionMemberFunc extends ReflectionFunc { public native func
+      Call(self: ref<IScriptable>, opt args: array<Variant>, opt status: script_ref<Bool>) ->
+      Variant }`, mirrored on `ReflectionStaticFunc`). Note: the "status-returning overload" is a
+      single `Call` with an optional `script_ref<Bool>` out-parameter, not a second,
+      separately-named overload.'
     tags:
       - codeware
       - reflection
@@ -102,7 +143,13 @@ facts:
       Reflection to check whether a particular class, property or function exists at runtime before
       touching it, rather than assuming it does.
     status: community
-    source: psiberx/cp2077-codeware/wiki/Home.md, section "Reflection > Mods and patches compatibility"
+    source: "psiberx/cp2077-codeware/wiki/Home.md, section \"Reflection > Mods and patches
+      compatibility\". Checked against commit 3a43182: this is guidance prose (\"In cases where you
+      can't use conditional compilation with `ModuleExists()`, you can use reflection...\") with no
+      corresponding API of its own — `ModuleExists()` is redscript's own conditional-compilation
+      builtin, not something Codeware's source defines, and the Reflection API it recommends is
+      confirmed separately by cp2077.codeware.overview.reflection-get-class-and-call. Left community
+      rather than inferred since no code confirms or contradicts this specific piece of advice."
     tags:
       - codeware
       - moduleexists