modwright 0.1.0

package/knowledge/cyberpunk2077/red4ext.api.yaml

@@ -0,0 +1,645 @@
+game: cyberpunk2077
+topic: red4ext.api
+title: RED4ext plugin API, address resolution, frame ticks, red-lib and Codeware hooking patterns,
+  and the puppet locomotion natives a plugin can reach
+facts:
+  - id: cp2077.red4ext.api.sdk-struct-five-services
+    claim: "The `RED4ext::v1::Sdk` a plugin receives in `Main` carries exactly five pointers: `runtime`
+      (a `SemVer*` holding the game's product version, e.g. 2.31, not its file version), `logger`,
+      `hooking`, `gameStates` and `scripts`."
+    status: verified
+    source: WopsS/RED4ext.SDK@ad72777 include/RED4ext/Api/v1/Sdk.hpp
+    tags:
+      - red4ext
+      - sdk
+      - api
+      - services
+    related:
+      - cp2077.red4ext.plugins.three-required-exports
+  - id: cp2077.red4ext.api.hooking-attach-detach-signatures
+    claim: "The loader's hooking service is two function pointers: `bool Attach(PluginHandle, void*
+      target, void* detour, void** original)` (original may be null; returns true when attached) and
+      `bool Detach(PluginHandle, void* target)` (detaches every hook at that target); the loader
+      implements them with Detours transactions."
+    status: verified
+    source: WopsS/RED4ext.SDK@ad72777 include/RED4ext/Api/v1/Hooking.hpp; WopsS/RED4ext@c52c8d8
+      src/dll/Systems/HookingSystem.cpp
+    tags:
+      - red4ext
+      - hooking
+      - detours
+      - api
+  - id: cp2077.red4ext.api.api-version-1-compat-0
+    claim: The SDK defines a single API version, `RED4EXT_API_VERSION_1` (= 1), bumped only on
+      incompatible ABI changes; `RED4EXT_API_VERSION_1_COMPAT_0` (= 0) lets a plugin report API v0
+      for older loaders because v0 and v1 are fully compatible.
+    status: verified
+    source: WopsS/RED4ext.SDK@ad72777 include/RED4ext/Api/ApiVersion.hpp
+    tags:
+      - red4ext
+      - api-version
+      - supports
+  - id: cp2077.red4ext.api.runtime-pins-are-pe-file-versions
+    claim: "`PluginInfo::runtime` is a PE file version, not a marketing version:
+      `RED4EXT_V1_RUNTIME_VERSION_2_31` is `FILEVER(3, 0, 80, 51928)`,
+      `RED4EXT_V1_RUNTIME_VERSION_2_30` is `FILEVER(3, 0, 80, 33925)`, and
+      `RED4EXT_V1_RUNTIME_VERSION_INDEPENDENT` is all four fields set to `(uint16_t)-1`."
+    status: verified
+    verified_on: "2.31"
+    source: WopsS/RED4ext.SDK@ad72777 include/RED4ext/Api/v1/Runtime.hpp
+    tags:
+      - red4ext
+      - runtime
+      - version-gate
+      - fileversion
+    related:
+      - cp2077.red4ext.plugins.runtime-field-pins-game-version
+    detail: "Matches ModWright's two-axis version convention: 2.31 on the marketing axis is 3.0.80.51928
+      on the file-version axis, and the runtime pin lives on the file-version axis. At this SDK
+      commit `RED4EXT_V1_RUNTIME_VERSION_LATEST` is `#define`d to `RED4EXT_V1_RUNTIME_VERSION_2_31`
+      (Runtime.hpp:53), so a plugin built against it and pinned to LATEST refuses any later game
+      build until rebuilt against a newer SDK."
+  - id: cp2077.red4ext.api.address-resolve-through-loader-export
+    claim: "`UniversalRelocFunc<T>(hash)` resolves an address by calling the loader's exported
+      `RED4ext_ResolveAddress(uint32_t)` (looked up with `GetProcAddress` on the RED4ext module);
+      when the loader returns 0 the SDK shows a dialog (\"Failed to find the address for the hash
+      ... This issue is likely caused by the mod using an incorrect or outdated hash.\") and
+      terminates the process."
+    status: verified
+    source: WopsS/RED4ext.SDK@ad72777 include/RED4ext/Relocation-inl.hpp; WopsS/RED4ext@c52c8d8
+      src/dll/Addresses.cpp
+    tags:
+      - red4ext
+      - address
+      - hash
+      - relocation
+      - failure-mode
+    detail: "Design consequence: resolve hashes lazily and log the hash before resolving, so an outdated
+      hash is diagnosable and does not kill the game at startup."
+  - id: cp2077.red4ext.api.loader-address-file-shape
+    claim: 'The loader fills its hash-to-address table from
+      `<game>\bin\x64\cyberpunk2077_addresses.json`: a root `Addresses` array of objects with a
+      `hash` (a number carried as a string) and an `offset` string `"<segment>:<hex>"`, where
+      segment 1, 2 and 3 are relative to the `.text`, `.rdata` and `.data` sections of the running
+      executable; a missing file is a fatal message box.'
+    status: verified
+    source: WopsS/RED4ext@c52c8d8 src/dll/Addresses.cpp
+    tags:
+      - red4ext
+      - address
+      - json
+      - bin-x64
+  - id: cp2077.red4ext.api.address-file-is-not-shipped-by-red4ext
+    claim: Nothing in the RED4ext repository generates, vendors or documents
+      `cyberpunk2077_addresses.json`; the loader reads it from the game's own `bin\x64`, so the file
+      is inferred to ship with the game itself, and whether its entries carry a symbol name beside
+      `hash` and `offset` is not established from any source read here.
+    status: inferred
+    source: grep for "addresses.json" / "cyberpunk2077_addresses" across WopsS/RED4ext@c52c8d8 (README,
+      BUILDING, CHANGELOG, src), the SDK and the wiki on 2026-09-20 matched only
+      src/dll/Addresses.cpp
+    tags:
+      - red4ext
+      - address
+      - provenance
+      - install-check
+    detail: Whether the file exists and carries symbol strings is a one-line check against a game
+      install. The loader reads only `hash` and `offset` (find_field), so extra fields would be
+      ignored, not rejected.
+  - id: cp2077.red4ext.api.address-hashes-are-not-fnv1a-of-symbols
+    claim: "The numeric address ids used with `UniversalRelocFunc` are not the FNV-1a (32-bit or
+      truncated 64-bit) hash of the symbol names the community records beside them: for the three
+      Codeware entries that carry a symbol comment, the computed FNV-1a32 of the comment differs
+      from the recorded id in every case."
+    status: verified
+    source: psiberx/cp2077-codeware@613a1cb src/Red/Addresses/Library.hpp:11,94,124
+    tags:
+      - red4ext
+      - address
+      - hash
+      - codeware
+    detail: So a new native's id comes from the address file, not from hashing its name; the SDK's own
+      Detail/AddressHashes.hpp (260 lines) names only RTTI, memory, resource, job, TweakDB and
+      render internals, none of the puppet locomotion natives.
+  - id: cp2077.red4ext.api.plugin-directory-depth-one
+    claim: The loader scans `red4ext\plugins` recursively but loads a `.dll` only at depth 0 or 1
+      (`plugins\X.dll` or `plugins\X\X.dll`); any deeper directory is skipped without recursion, and
+      a depth-1 plugin is loaded with an altered DLL search path so libraries beside it resolve. A
+      stem listed under `[plugins] ignored` in `red4ext\config.ini` is skipped.
+    status: verified
+    source: WopsS/RED4ext@c52c8d8 src/dll/Systems/PluginSystem.cpp; src/dll/Config.hpp
+    tags:
+      - red4ext
+      - plugins-directory
+      - deploy
+      - config
+    related:
+      - cp2077.red4ext.plugins.install-paths-and-logs
+  - id: cp2077.red4ext.api.deploy-into-names-the-file
+    claim: 'A ModWright deploy target whose `from` is a single file is copied to exactly `<root>/<into>`
+      (or `<root>/<basename of from>` with no `into`), so an `into` that names a folder makes the
+      folder name the installed file. On the `red4ext` root, `into: "<Mod>"` with the plugin DLL as
+      `from` installed `red4ext\plugins\<Mod>`, a 108 KB file with no extension, which the loader
+      does not load; `into: "<Mod>/<Mod>.dll"` is the working form.'
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - red4ext
+      - deploy
+      - plugins-directory
+      - into
+    related:
+      - cp2077.red4ext.api.plugin-directory-depth-one
+  - id: cp2077.red4ext.api.plugin-extension-compared-exactly
+    claim: 'The loader keeps a file under `red4ext\plugins` only when `path.extension() == L".dll"`, a
+      `std::filesystem::path` comparison of the native strings, which is case-sensitive: a plugin
+      installed as `X.DLL` is not loaded.'
+    status: inferred
+    source: WopsS/RED4ext@c52c8d8 src/dll/Systems/PluginSystem.cpp:145
+    tags:
+      - red4ext
+      - plugins-directory
+      - extension
+    related:
+      - cp2077.red4ext.api.plugin-directory-depth-one
+  - id: cp2077.red4ext.api.plugin-exports-supports-query-required
+    claim: "The loader requires a plugin DLL to export `Supports` and `Query`: a missing one logs
+      \"Could not retrieve 'Supports' function\" (or 'Query') at warn level and the plugin is not
+      loaded. `Main` is optional: without it the loader logs \"does not export a 'Main' function,
+      skipping the call\" at trace level and keeps the plugin loaded, so nothing it would register
+      in `Main` exists."
+    status: inferred
+    source: WopsS/RED4ext@c52c8d8 src/dll/Systems/PluginSystem.cpp:341-354;
+      src/dll/PluginBase.cpp:36-46, :88-128
+    tags:
+      - red4ext
+      - exports
+      - plugin-load
+      - main
+    related:
+      - cp2077.red4ext.api.plugin-exports-matched-by-exact-name
+  - id: cp2077.red4ext.api.plugin-exports-matched-by-exact-name
+    claim: The loader finds `Supports`, `Query` and `Main` with `GetProcAddress` by those literal names,
+      so each must be exported undecorated (`extern "C"`, which the SDK's `RED4EXT_C_EXPORT`
+      supplies); a C++ export carries its decorated name (MSVC `?Query@@...`, MinGW `_Z5QueryPv`)
+      and is not found.
+    status: inferred
+    source: WopsS/RED4ext@c52c8d8 src/dll/Systems/PluginSystem.cpp:341; src/dll/PluginBase.cpp:40, :93;
+      test/fixtures/cp2077/red4ext/pe/decorated.x64.dll
+    tags:
+      - red4ext
+      - exports
+      - name-decoration
+      - extern-c
+  - id: cp2077.red4ext.api.config-ini-dev-console
+    claim: "`red4ext\\config.ini` is TOML despite its extension and carries `[logging]
+      level/flush_on/max_files/max_file_size`, `[plugins] enabled/ignored` and `[dev]
+      console/wait_for_debugger`; the wiki lists `dev.console` as defaulting to true while the
+      loader source defaults `hasConsole` to false."
+    status: community
+    source: CDPR-Modding-Documentation/Red4Ext-Wiki@3635293 getting-started/configuration.md (options
+      table and example); WopsS/RED4ext@c52c8d8 src/dll/Config.hpp (DevConfig.hasConsole = false)
+    tags:
+      - red4ext
+      - config
+      - console
+      - logging
+    detail: The two sources disagree on the console default; treat the example file's `console = false`
+      as what a fresh install writes and set it explicitly for a development session.
+  - id: cp2077.red4ext.api.update-registrar-tick-groups-and-stages
+    claim: "The SDK exposes the engine's per-frame update registrar: tick groups in order FrameBegin,
+      Multiplayer_UpdateStateSnapshots, EntityUpdateState, PreBuckets, Buckets, PostBuckets,
+      CameraUpdate, PlayerAimUpdate, PostPlayerAimUpdate, MappinsUpdate,
+      BlackboardCallbacks_SecondPass, PreRenderUpdate, Multiplayer_CaptureStateSnapshots; buckets
+      Vehicle, Character, AttachedObject; bucket stages in order Entities_PreTick,
+      Entities_ServiceEvents, PrePhysicsTick, UpdateTransformPrePhysics, PhysicsFlushBufferedState,
+      PhysicsExecuteAsyncQueries, PostPhysicsSyncResults, UpdateTransformPostPhysics,
+      AnimationUpdate, PostPhysicsTick, Entities_PostTick, Entities_PostServiceEvents.
+      `UpdateRegistrar::RegisterUpdate` takes either (group, system, name, callback(FrameInfo&,
+      JobQueue&)) or (bucket mask, stage, system, name, callback(bucket, FrameInfo&, JobQueue&));
+      `FrameInfo` carries `deltaTime` and `details->timeDilation`."
+    status: verified
+    source: WopsS/RED4ext.SDK@ad72777 include/RED4ext/SystemUpdate.hpp
+    tags:
+      - red4ext
+      - tick
+      - frame
+      - update-registrar
+      - bucket
+      - stage
+    detail: The enum order is the declaration order in the header; that it is also the execution order
+      is the natural reading of the names (PrePhysics before PostPhysics) and is not separately
+      attested.
+  - id: cp2077.red4ext.api.game-system-registers-frame-tick
+    claim: A native `gameIGameSystem` inherits `IUpdatableSystem`, whose virtual
+      `OnRegisterUpdates(UpdateRegistrar*)` (vtable slot 0x108) is where a system registers its
+      per-frame callbacks; `IGameSystem` adds `OnWorldAttached`/`OnWorldDetached`, save/load,
+      pause/resume and `OnInitialize`/`OnUninitialize` slots and holds `gameInstance` at 0x40.
+      Codeware's StaticEntitySystem registers a FrameBegin tick this way.
+    status: verified
+    source: WopsS/RED4ext.SDK@ad72777 include/RED4ext/Scripting/Natives/IUpdatableSystem.hpp,
+      gameIGameSystem.hpp; psiberx/cp2077-codeware@613a1cb src/App/World/StaticEntitySystem.cpp
+    tags:
+      - red4ext
+      - game-system
+      - tick
+      - frame
+      - codeware
+  - id: cp2077.red4ext.api.game-states-add
+    claim: "`Sdk->gameStates->Add(PluginHandle, EGameStateType, GameState*)` registers
+      `OnEnter`/`OnUpdate`/`OnExit` callbacks (each `bool(*)(CGameApplication*)`) on one of four
+      engine states: BaseInitialization, Initialization, Running, Shutdown."
+    status: verified
+    source: WopsS/RED4ext.SDK@ad72777 include/RED4ext/Api/v1/GameStates.hpp; include/RED4ext/GameStates.hpp
+    tags:
+      - red4ext
+      - game-state
+      - tick
+      - api
+    related:
+      - cp2077.red4ext.plugins.main-called-before-memory-allocators-ready
+  - id: cp2077.red4ext.api.logger-levels
+    claim: The loader's logger service exposes Trace, Debug, Info, Warn, Error and Critical, each in
+      four forms (narrow, narrow printf-style `F`, wide `W`, wide printf-style `WF`), all taking the
+      plugin handle first.
+    status: verified
+    source: WopsS/RED4ext.SDK@ad72777 include/RED4ext/Api/v1/Logger.hpp
+    tags:
+      - red4ext
+      - logging
+      - api
+    related:
+      - cp2077.red4ext.plugins.per-plugin-log-file-created-lazily
+  - id: cp2077.red4ext.api.scripts-service
+    claim: "`Sdk->scripts` offers `Add(PluginHandle, const wchar_t* path)` to add a script path to the
+      compile, and `RegisterNeverRefType(const char*)` / `RegisterMixedRefType(const char*)` for
+      type-reference handling."
+    status: verified
+    source: WopsS/RED4ext.SDK@ad72777 include/RED4ext/Api/v1/Scripts.hpp
+    tags:
+      - red4ext
+      - scripts
+      - api
+    detail: The semantics of the two Register calls are not documented in the header; only the
+      signatures are attested here.
+  - id: cp2077.red4ext.api.function-registration-callbacks
+    claim: Without red-lib, a plugin registers native types and functions from `Main` by
+      `CRTTISystem::Get()->AddRegisterCallback(RegisterTypes)` and
+      `AddPostRegisterCallback(PostRegisterTypes)`; a native function has the fixed shape
+      `void(IScriptable* ctx, CStackFrame* frame, T* out, int64_t)`, reads arguments with
+      `GetParameter(frame, &arg)` in order and then `frame->code++` to skip ParamEnd, and is created
+      with `CGlobalFunction::Create` / `CClassFunction::Create` / `CClassStaticFunction::Create`
+      then `RegisterFunction`.
+    status: verified
+    source: WopsS/RED4ext.SDK@ad72777 examples/function_registration/Main.cpp;
+      examples/native_class_redscript/Main.cpp
+    tags:
+      - red4ext
+      - rtti
+      - native-function
+      - registration
+  - id: cp2077.red4ext.api.redlib-has-no-hooking-api
+    claim: psiberx's red-lib is a header-only CMake INTERFACE library whose `include/Red/` holds only
+      TypeInfo (definition macros, invocation, registrar), Engine (framework, log channel, mappings)
+      and Utils (handles, job queues, resources); it provides RTTI registration, function calling,
+      game-system auto-registration and logging, and no hooking facility.
+    status: verified
+    source: psiberx/cp2077-red-lib@6822105 CMakeLists.txt; include/Red/*; README.md
+    tags:
+      - red-lib
+      - hooking
+      - rtti
+      - scope
+    detail: "Corrects a premise that red-lib provides hooks: hooks come from the loader's Sdk->hooking
+      or a library the plugin brings, not from red-lib."
+  - id: cp2077.red4ext.api.redlib-rtti-macros
+    claim: red-lib declares native types with `RTTI_DEFINE_CLASS(Type, {...})` (with `RTTI_METHOD`,
+      `RTTI_PROPERTY`, `RTTI_GETTER`, `RTTI_PARENT`, `RTTI_ABSTRACT`, `RTTI_ALIAS`,
+      `RTTI_PERSISTENT`), `RTTI_DEFINE_GLOBALS`, `RTTI_DEFINE_ENUM`/`RTTI_DEFINE_FLAGS`, and
+      `RTTI_EXPAND_CLASS(Existing, {...})` to add methods (never properties) to an existing class; a
+      class needs `RTTI_IMPL_TYPEINFO` and `RTTI_IMPL_ALLOCATOR` members; an `IGameSystem` subclass
+      is registered in the game instance automatically and reached from script through an
+      `@addMethod(GameInstance) public static native func`; everything is registered by calling
+      `Red::TypeInfoRegistrar::RegisterDiscovered()` in `Main` on Load.
+    status: community
+    source: psiberx/cp2077-red-lib@6822105 README.md, sections "Building type info", "Game systems",
+      "Class extensions", "Registration"
+    tags:
+      - red-lib
+      - rtti
+      - macros
+      - game-system
+      - registration
+  - id: cp2077.red4ext.api.redlib-alias-binds-module-scoped-declarations
+    claim: A native class declared inside a redscript `module` binds to its C++ definition only when the
+      definition carries `RTTI_ALIAS("Module.ClassName")`; a plugin installs at
+      `red4ext\plugins\<Name>\<Name>.dll` and its native declarations as ordinary `.reds` files
+      under `r6\scripts`.
+    status: community
+    source: CDPR-Modding-Documentation/Red4Ext-Wiki@3635293
+      mod-developers/creating-a-plugin-with-redlib.md ("You only need to add an alias when declaring
+      scripts with 'module' and 'import' keywords"; the install paths in the same page)
+    tags:
+      - red-lib
+      - redscript
+      - module
+      - alias
+      - install-path
+  - id: cp2077.red4ext.api.any-toolchain-x64-fastcall
+    claim: A plugin may be built with any build system or toolchain as long as the output is x86-64 with
+      the `__fastcall` convention; WopsS publishes a CMake example (RED4ext.Example.CMake) and a
+      Visual Studio example, and only RED4ext.SDK must be on the include path.
+    status: community
+    source: CDPR-Modding-Documentation/Red4Ext-Wiki@3635293 mod-developers/creating-a-plugin.md:3-17
+    tags:
+      - red4ext
+      - toolchain
+      - cmake
+      - visual-studio
+    related:
+      - cp2077.red4ext.plugins.abi-is-fastcall-x86-64
+  - id: cp2077.red4ext.api.cmake-example-shape
+    claim: The official CMake example adds the SDK as a submodule at `deps/red4ext.sdk`, calls
+      `add_subdirectory(deps/red4ext.sdk)`, builds the plugin as a `SHARED` library linked `PRIVATE
+      RED4ext::SDK` with C++20, optionally `RED4EXT_HEADER_ONLY`, and its CI configures with `cmake
+      -A x64` and builds with `cmake --build . --config <Debug|Release>`.
+    status: verified
+    source: WopsS/RED4ext.Example.CMake@d5aa651 CMakeLists.txt; src/CMakeLists.txt;
+      .github/workflows/build.yml
+    tags:
+      - red4ext
+      - cmake
+      - build
+      - example
+    detail: The example is dated 2022-09-06 and pins nothing; the SDK's own README asks for Visual
+      Studio 2022 and CMake 3.23 or newer and exports the `RED4ext::SDK` alias from
+      cmake/RED4extConfig.cmake.in.
+  - id: cp2077.red4ext.api.sdk-build-requirements
+    claim: RED4ext.SDK is used either header-only (include the headers, C++20) or as a static library
+      (headers plus src, define `RED4EXT_STATIC_LIB`); building the SDK itself asks for Visual
+      Studio 2022 Community or newer and CMake 3.23 or newer.
+    status: verified
+    source: WopsS/RED4ext.SDK@ad72777 README.md
+    tags:
+      - red4ext
+      - sdk
+      - build
+      - requirements
+  - id: cp2077.red4ext.api.cmake-modules-repo-not-found
+    claim: A repository named `psiberx/cp2077-cmake-modules` could not be cloned on 2026-09-20 (the
+      clone failed with GitHub's credential prompt, the response a nonexistent or private repository
+      produces), while six sibling clones in the same session succeeded; the shared CMake helpers
+      the task expected there may live under another name or not exist.
+    status: unverified
+    source: ModWright research
+    tags:
+      - cmake
+      - psiberx
+      - provenance
+    detail: "Codeware itself builds with xmake (xmake.lua: minhook, spdlog, tiltedcore, hopscotch-map;
+      targets Codeware.dll), not with CMake."
+  - id: cp2077.red4ext.api.codeware-entity-setworldtransform
+    claim: "Codeware adds `SetWorldTransform(transform: WorldTransform)` to every `Entity` from
+      redscript: `RTTI_EXPAND_CLASS(Red::Entity, App::EntityEx, ...)` registers
+      `EntityEx::SetWorldTransform`, which calls the native `IPlacedComponent_SetTransform`
+      (Codeware address id 1828854026, signature `void(IPlacedComponent*, const WorldTransform&)`)
+      on the entity's root transform component; the wiki documents it as moving static entities
+      without a respawn."
+    status: verified
+    source: psiberx/cp2077-codeware@613a1cb src/App/Entity/EntityEx.hpp; src/Red/Entity.hpp;
+      src/Red/Addresses/Library.hpp; scripts/Entity/Entity.reds; wiki/Home.md
+    tags:
+      - codeware
+      - entity
+      - transform
+      - setworldtransform
+      - puppet-control
+    detail: Documented for static entities; that it also moves a live NPCPuppet (whose mover may
+      re-assert its own transform) is the first thing to measure. Codeware's version at this commit
+      is 1.20.4 (xmake.lua); the release that first shipped the method is not established here.
+  - id: cp2077.red4ext.api.codeware-raw-entity-offsets
+    claim: "Codeware's `Raw::Entity` reads an `entEntity` at fixed offsets: the `EntityID` at 0x48, the
+      appearance name at 0x50, the template path at 0x60, the components storage at 0x70, the root
+      transform component (`IPlacedComponent*`) at 0xB0, the runtime scene at 0xB8 and the status
+      byte at 0x156; its `EntityStatus` enum runs Undefined, Initializing, Detached, Attaching,
+      Attached, Detaching, Uninitializing, Uninitialized."
+    status: verified
+    verified_on: "2.31"
+    source: psiberx/cp2077-codeware@613a1cb src/Red/Entity.hpp
+    tags:
+      - codeware
+      - entity
+      - offsets
+      - layout
+    detail: The SDK's own generated ent/Entity.hpp leaves the 0x160-byte class undecoded, so these
+      offsets are Codeware's reverse engineering, pinned to its SDK submodule 6ea7425 and to the
+      game build it was released for; a game patch can move them.
+  - id: cp2077.red4ext.api.codeware-hooking-backends
+    claim: Codeware's `Core::Hook::{Attach,Before,After,Wrap,Detach}` facade drives a `HookingDriver`;
+      when loaded as a RED4ext plugin the driver is `Support::RED4extProvider`, whose
+      `HookAttach`/`HookDetach` call `m_sdk->hooking->Attach/Detach` and whose `ResolveAddress`
+      calls `RED4ext::UniversalRelocBase::Resolve`; when loaded as an ASI it uses a MinHook driver
+      instead. The facade is part of Codeware's own tree (lib/Core), not a library another plugin
+      depends on.
+    status: verified
+    source: psiberx/cp2077-codeware@613a1cb lib/Core/Facades/Hook.hpp;
+      lib/Support/RED4ext/RED4extProvider.cpp; lib/Support/MinHook/MinHookProvider.hpp; src/main.cpp
+    tags:
+      - codeware
+      - hooking
+      - minhook
+      - detours
+      - pattern
+  - id: cp2077.red4ext.api.codeware-query-runtime-independent
+    claim: Codeware's `Query` reports `RED4EXT_V1_RUNTIME_VERSION_INDEPENDENT` and
+      `RED4EXT_V1_SDK_VERSION_1_0_0_COMPAT_0_5_0`, and its `Supports` returns
+      `RED4EXT_API_VERSION_1_COMPAT_0`; it relies on runtime address resolution rather than a
+      game-version pin.
+    status: verified
+    source: psiberx/cp2077-codeware@613a1cb src/main.cpp
+    tags:
+      - codeware
+      - runtime
+      - version-gate
+      - pattern
+    related:
+      - cp2077.red4ext.api.runtime-pins-are-pe-file-versions
+  - id: cp2077.red4ext.api.movepolicies-component-is-push-pop-query
+    claim: "`movePoliciesComponent` (script alias MovePoliciesComponent, 0x5E0 bytes, undecoded) exposes
+      22 natives that only push, pop or query: AddPolicies, PopPolicies, GetTopPolicies,
+      ChangeMovementType, GetCurrentLocomotionAction, GetDestination, GetDistanceToDestination,
+      GetClosestPointToPath, IsDestinationCalculated, IsDestinationChanged, IsInIdle,
+      IsPathfindingFailed, IsTopPolicyEvaluated, IsPausedByDynamicCollision and the
+      off-mesh/incline/stairs queries; none sets a velocity. `moveLocomotionAction` is Undefined,
+      Exploration, Idle, IdleTurn, Reposition, Start, Move, Stop."
+    status: verified
+    verified_on: "2.31"
+    source: rayshader/cp2077-nativedb@b5d29af src/assets/reddump/classes.json, enums.json;
+      WopsS/RED4ext.SDK@ad72777
+      include/RED4ext/Scripting/Natives/Generated/move/PoliciesComponent.hpp
+    tags:
+      - nativedb
+      - movepolicies
+      - locomotion
+      - puppet-control
+    detail: "Observed in game: a MovePolicies push is the one script lever that moves a taken idle
+      puppet; this fact is why it cannot be made velocity-driven from script."
+  - id: cp2077.red4ext.api.movepolicies-record-layout
+    claim: "`movePolicies` (script alias MovePolicies, 0x228 bytes, fully decoded) holds
+      `destination`/`destinationTangent`/`startTangent` (Vector3 at 0x40/0x4C/0x58), `targetObject`
+      (wref at 0x88), `strafingTarget` (0x98), `desiredDistance` 0x108, `minMovementDistance` 0x10C,
+      `toleranceRadius` 0x114, `movementType` 0x140 (moveMovementType: Walk, Run, Sprint, Strafe,
+      Stand), `stopOnObstacle` 0x154, `useCollisionAvoidance` 0x156, `ignoreNavigation` 0x180,
+      `useStart` 0x181, `useStop` 0x182, `isEvaluated` 0x184; its 51 natives include
+      SetDestinationPosition, SetDestinationOrientation, SetIgnoreNavigation, SetUseStartStop,
+      SetDistancePolicy, SetMovementType, SetPositionProvider, SetStrafingTarget, SetMaxPathLength
+      and SetCollisionAvoidancePolicy."
+    status: verified
+    verified_on: "2.31"
+    source: WopsS/RED4ext.SDK@ad72777 include/RED4ext/Scripting/Natives/Generated/move/Policies.hpp;
+      rayshader/cp2077-nativedb@b5d29af src/assets/reddump/classes.json
+    tags:
+      - nativedb
+      - movepolicies
+      - layout
+      - locomotion
+  - id: cp2077.red4ext.api.mover-component-undecoded
+    claim: "A puppet's mover is `moveComponent : entIMoverComponent : entIComponent`; the SDK gives its
+      size as 0x2C0 with the struct commented out (undecoded) and `entIMoverComponent` as an
+      abstract 0x90-byte interface with no natives; `moveMoveComponentVelocityProvider.
+      CreateMoveComponentVelocityProvider(puppet)` and `gamePuppet.GetVelocity()` are the only
+      script-visible reads of it."
+    status: verified
+    verified_on: "2.31"
+    source: WopsS/RED4ext.SDK@ad72777 include/RED4ext/Scripting/Natives/Generated/move/Component.hpp,
+      ent/IMoverComponent.hpp; rayshader/cp2077-nativedb@b5d29af src/assets/reddump/classes.json
+    tags:
+      - nativedb
+      - mover
+      - locomotion
+      - undecoded
+  - id: cp2077.red4ext.api.entity-has-no-transform-setter
+    claim: "`entEntity` exposes `GetWorldPosition`, `GetWorldOrientation`, `GetWorldTransform` and
+      `FindComponentByName` and no world transform setter; `entIPlacedComponent` (0x120;
+      `parentTransform` at 0x90, `localTransform` at 0xC0) exposes `SetLocalTransform(pos, rot)`,
+      `SetLocalPosition`, `SetLocalOrientation`, `GetLocalToWorld` for components; `gameObject` adds
+      `EnableTransformUpdates(Bool)` with undocumented semantics."
+    status: verified
+    verified_on: "2.31"
+    source: rayshader/cp2077-nativedb@b5d29af src/assets/reddump/classes.json; WopsS/RED4ext.SDK@ad72777
+      include/RED4ext/Scripting/Natives/Generated/ent/IPlacedComponent.hpp
+    tags:
+      - nativedb
+      - entity
+      - transform
+      - puppet-control
+    related:
+      - cp2077.red4ext.api.codeware-entity-setworldtransform
+  - id: cp2077.red4ext.api.aihumancomponent-movement-params
+    claim: "`AIHumanComponent : AICAgent` (0x5B8; `movementParamsRecord` TweakDBID at 0x4F0) exposes
+      `GetMovementParams(moveMovementType) -> moveMovementParameters {type, maxSpeed, acceleration,
+      deceleration, rotationSpeed}`, `SetMovementParams` and `SetTDBMovementParams`; `AICAgent`
+      (alias AIComponent) exposes `SendCommand`, `CancelCommand`, `SetBehaviorArgument(CName,
+      Variant)`, `GetBehaviorArgument`, `ForceTickNextFrame`, `GetUpdateTickCount`,
+      `GetHighLevelState`, `SetAIRole`, `DisableCollider`/`EnableCollider`."
+    status: verified
+    verified_on: "2.31"
+    source: rayshader/cp2077-nativedb@b5d29af src/assets/reddump/classes.json; WopsS/RED4ext.SDK@ad72777
+      include/RED4ext/Scripting/Natives/Generated/AI/HumanComponent.hpp
+    tags:
+      - nativedb
+      - ai
+      - movement-params
+      - speed
+      - puppet-control
+  - id: cp2077.red4ext.api.animfeature-movement-fields
+    claim: "`animAnimFeature_Movement` carries `movementDirection: Vector4`, `speed`, `desiredSpeed`,
+      `stabilizedSpeed`, `acceleration`, `timeToChangeLocomotion`, `strafeYaw`, `yawSpeed` and
+      `locomotionState: Int32` with natives `SetSpeed` and `SetAcceleration`;
+      `animAnimFeature_Locomotion` carries `action`, `style`, `pathCurvature`, `inclineAngle`,
+      `groundAngle`, `animDeltaZ`, `speedProgress`, `isOnStairs`; `animAnimFeature_MoveTo` offers
+      `MoveTo(targetPosition, targetYawRotation, timeToMove)` and `MoveToWithDir`;
+      `entAnimationControllerComponent.ApplyFeature(obj, inputName, feature, delay)` is a static
+      native that applies any feature to an object's graph input by name."
+    status: verified
+    verified_on: "2.31"
+    source: rayshader/cp2077-nativedb@b5d29af src/assets/reddump/classes.json
+    tags:
+      - nativedb
+      - animation
+      - anim-feature
+      - locomotion
+      - puppet-control
+    detail: Which input name an NPC locomotion graph reads for the Movement feature is not in the RTTI;
+      it is in the `.animgraph` resource and needs a check against the game files.
+  - id: cp2077.red4ext.api.muppet-classes-are-input-driven-puppet
+    claim: "The RTTI carries a native `gameMuppet : gamePuppetBase` with components
+      `gameMuppetLocomotionComponent` (0x98, undecoded), `gameMuppetInputHandlerComponent`,
+      `gameMuppetRawInput`, `gameMuppetInputStates`, and input structs
+      `gameMuppetInputActionMoveForward {direction: Vector2, isSprinting}`,
+      `gameMuppetInputActionLook {rotation: Vector2}`, a `gameMuppetMoveState {desiredSpeed,
+      isJumping, moveStyle: gameMuppetMoveStyle (Walk, Sprint, Crouch, WalkAim, GravityOnly)}`, and
+      a replicated state with `Muppet.ReplicateInputStates( gameMuppetCompressedInputStates)`: an
+      input-driven, network-replicated player puppet from the cancelled multiplayer, with no known
+      shipped entity template."
+    status: verified
+    verified_on: "2.31"
+    source: rayshader/cp2077-nativedb@b5d29af src/assets/reddump/classes.json, enums.json;
+      WopsS/RED4ext.SDK@ad72777
+      include/RED4ext/Scripting/Natives/Generated/game/MuppetLocomotionComponent.hpp
+    tags:
+      - nativedb
+      - muppet
+      - multiplayer
+      - input
+      - puppet-control
+    detail: '"No known shipped entity template" is the absence of evidence in the RTTI and the SDK, not
+      a search of the archives; a few cheap checks would settle it.'
+  - id: cp2077.red4ext.api.navigation-clamp-natives
+    claim: "`AINavigationSystem` exposes `IsPointOnNavmesh(character, point, tolerance)`,
+      `GetNearestNavmeshPointBelow(character, origin, querySphereRadius, numberOfSpheres) ->
+      Vector4`, `FindWallInLineForCharacter(start, end, tolerance, owner)`,
+      `FindPointBelowForCharacter`, `HasPathForward(object, distance)` and
+      `CalculatePathForCharacter`; `gamePuppet` exposes `GetCurrentNavmeshPosition(out position) ->
+      navNaviPositionType` and `GetLastValidNavmeshPoint()`."
+    status: verified
+    verified_on: "2.31"
+    source: rayshader/cp2077-nativedb@b5d29af src/assets/reddump/classes.json
+    tags:
+      - nativedb
+      - navigation
+      - navmesh
+      - clamp
+      - puppet-control
+  - id: cp2077.red4ext.api.time-dilation-native-signature
+    claim: "`gameTimeDilatable` (a gameObject ancestor of every puppet) exposes
+      `SetIndividualTimeDilation(reason: CName, dilation: Float, duration: Float, easeInCurve:
+      CName, easeOutCurve: CName, ignoreGlobalDilation: Bool, useRealTime: Bool)`,
+      `UnsetIndividualTimeDilation(easeOutCurve)`, `GetTimeDilationValue`,
+      `HasIndividualTimeDilation(reason)` as natives."
+    status: verified
+    verified_on: "2.31"
+    source: rayshader/cp2077-nativedb@b5d29af src/assets/reddump/classes.json
+    tags:
+      - nativedb
+      - time-dilation
+      - freeze
+      - puppet-control
+    detail: 'Observed in game: the TimeDilationHelper wrapper of this froze a taken puppet ("freeze is
+      the smoothness fix"); a per-frame drive must lift it while moving.'
+  - id: cp2077.red4ext.api.redlib-call-helpers
+    claim: "red-lib lets native code call script-visible functions by name through the RTTI:
+      `Red::CallGlobal(name, out?, args...)`, `Red::CallStatic(className, funcName, out?, args...)`
+      and `Red::CallVirtual(IScriptable* context, funcName, out?, args...)` (with an overload taking
+      the `CClass*`), each returning a bool for success; the README's example chain is
+      GetPlayerSystem → GetLocalPlayerControlledGameObject → Revive."
+    status: verified
+    source: psiberx/cp2077-red-lib@6822105 include/Red/TypeInfo/Invocation.hpp; README.md
+    tags:
+      - red-lib
+      - invocation
+      - callvirtual
+      - rtti
+    detail: This is what lets a plugin call Codeware's registered Entity.SetWorldTransform without
+      resolving any game address itself (the no-address variant).