// Research & architecture

REDnode

REDnode is a Node-based API for scripting Cyberpunk 2077, built on the same injection points that RED4ext, Cyber Engine Tweaks and redscript already use. Asynchronous mods run in a normal Node process. A small sandboxed tier runs inside the game for the few cases that must change a value mid-call.

Recommended: hybrid B + small A Tier 2: Node (out of process) Tier 1: sandboxed in-process Single-player modding

01Goal and scope

In scope

Let modders write game logic in TypeScript and JavaScript with npm packages.
Expose game state, events and commands through a typed API generated from the game's own reflection data.
Coexist with CET, RED4ext plugins, redscript and REDmod.
Survive game patches without per-patch rewrites of mods.

Out of scope for v1

Multiplayer or anything that touches online services.
Full in-process Node with fs, require and a live event loop.
Replacing redscript for engine-level changes.
Mods that need to run arbitrary game calls from inside a hook.

02Existing landscape

Checked against the install on this machine. Two independent injection points are already in use, so a new framework can attach to either.

Component	How it attaches	Seen on this install
Ultimate ASI Loader	Proxy `version.dll` that loads every `.asi` in `bin/x64/plugins/`.	v6.0.0. Loads `cyber_engine_tweaks.asi`.
RED4ext	Proxy `winmm.dll` loads `red4ext/RED4ext.dll`, which loads `red4ext/plugins//.dll`.	v1.30.0. Plugins: ArchiveXL, Codeware, RedData, mod_settings, input_loader.
Cyber Engine Tweaks	In-process Lua runtime with reflection access to game types and an ImGui overlay.	Closest precedent for an embedded scripting runtime.
redscript	Compiles `.reds` files into the game's script bytecode at launch. Not a runtime embed.	Many mods under `r6/scripts/`.
REDmod	Official CDPR deploy tool for archives, tweaks, scripts and audio. No injection.	`redMod.exe` present, `mods/` empty.

What this teaches

The game exposes a reflection (RTTI) system. That is what makes a dynamic scripting layer possible, and CET relies on it.
Codeware is a native RED4ext plugin that exposes extra functions to redscript. A native bridge exposing a scripting surface is the established pattern.
RedData and mod_settings ship a native DLL together with .reds files. Mod authors already expect that packaging shape.

03Options considered

Plan	Approach	Strengths	Weaknesses
A	Embed Node in a RED4ext plugin or `.asi`.	Closest to CET. JS runs inside hooks as plain function calls.	30 to 80 MB runtime. Event loop and threads inside a DX12 game process. Hard to keep stable.
B	Thin native RED4ext plugin plus a separate Node process over IPC.	Crash isolation. Normal npm tooling. Easy hot reload. Small native surface to maintain.	No synchronous access from hooks. Round-trip latency on every call.
C	Embed QuickJS only.	About 1 MB. Fast start. Easy to sandbox.	Not Node. No npm ecosystem.

The tradeoff in Plan B

A hook runs inside the game's own function call, on the game thread, and the game waits for it to return. If the logic lives in another process, the hook must block on a round trip. That costs roughly 50 to 200 µs when healthy and much more when Node is busy. A 60 fps frame has about 16 ms, and hooks such as damage or per-frame ticks can fire thousands of times a frame. If the Node process crashes or hangs, the game thread blocks until a timeout.

Pattern	Plan B
Notify: "the player took damage"	Works. The hook enqueues an event and returns.
Query: "what is the player's health?"	Works. Node awaits the answer.
Command: "set health to 100"	Works. Queued and applied on the game thread next tick.
Intercept: change a value before the call continues	Does not work well. Needs a synchronous answer while the game waits.

04Recommended design: two tiers

Keep Plan B as the main path. Add a small in-process tier for interceptors only. A mod can ship either tier or both.

Game process

Game threadhooks, RTTI, script calls

Tier 1: interceptor runnersandboxed JS, sync, time-limited

Native plugin (RED4ext)RTTI bridge, event queue, command queue

Node process

Tier 2: async modsfull Node, npm, await

Framework SDKtyped proxies, events, queries

Dev toolinghot reload, logs, type generation

NATIVE PLUGIN ⇄ NODE · named pipe or local socket · events out, queries and commands in · interceptor parameters pushed ahead of time

Tier 1 · sync interceptors

Runs inside the hook on the game thread.
Can change arguments or return values, or cancel a call.
No await, no I/O, no require.
Hard time budget, for example 100 µs.

Tier 2 · async Node mods

Observe events, query state, send commands.
Full Node and npm.
Never blocks the game.
Can push parameters to Tier 1 interceptors.

What runs Tier 1

Engine	Size	Notes
Full Node / V8	30 to 80 MB	Brings back every problem of Plan A. Not recommended for interceptors.
Bare V8 isolate	10 to 30 MB	Same JS dialect as Node. Fast. No Node APIs. Heavier to ship.
QuickJS	about 1 MB	Recommended. Small, easy to sandbox and to time-limit. TypeScript is compiled ahead of time. Slower than V8, which is fine for tiny functions.

Tier 1 shares TypeScript types with Tier 2 but is not Node. The documentation must say so plainly.

Cheaper than either: declarative rules

For the simplest cases, such as "multiply incoming damage by X", offer a no-code rule that the native plugin applies directly in the hook. It needs no JS engine and no IPC, and it covers a large share of real mods.

05API sketch

Tier 1 · interceptor (sync, sandboxed)

export default defineInterceptor({
  target: "PlayerPuppet.OnDamageReceived",
  run(ctx) {
    ctx.args.damage *= ctx.params.multiplier;   // pushed from Tier 2
  }
});

Tier 2 · async mod (full Node)

import { game } from "rednode";

game.on("PlayerPuppet.OnDamageReceived", async (e) => {
  await db.log(e);                          // fine, the game is not waiting
  game.player.setHealth(100);              // queued, runs next tick
});

const hp = await game.player.getHealth();    // async query
interceptor("damage-scale").set("multiplier", 0.5);

Native plugin responsibilities

Enumerate RTTI classes, functions and properties for type generation.
Call functions and get or set properties on game objects.
Hook functions through RED4ext and the Address Library so mods survive patches.
Marshal game types (CName, Vector4, handles, arrays) to and from JSON-like values.
Queue all incoming commands and run them on the game thread, because game objects are not thread-safe.
Manage object handle lifetime so Node never holds a stale reference.

06Safety rails for Tier 1

Hard requirement

A buggy interceptor must never crash or freeze the game.

Time budget

Each call is time-limited. On overrun, return to default game behavior.

Fault handling

Catch exceptions, fall back to defaults, and auto-disable an interceptor after repeated failures.

Ordering

Define priority and chaining when several mods hook the same function.

Typed writes

Validate every write to ctx.args against the real parameter types before it reaches the game.

Limited host API

Read-only accessors and shared-memory reads only. No arbitrary game calls from a hook, to avoid reentrancy bugs.

Safe reload

Swap Tier 1 code between frames. Tier 2 reloads freely.

07Risks

Risk	Impact	Mitigation
Game patch breaks hooks	Mods stop working until the plugin updates.	Use the Address Library and RED4ext hooking. Never hard-code offsets.
Conflicts with other plugins	Double hooks, crashes.	Use RED4ext's hook API. Do not add a third loader.
Thread-safety bugs	Random crashes.	All game access goes through the game-thread queue.
IPC latency or stalls	Stutter.	Async by default. Fast-path rules and shared memory for hot paths.
Tier 1 scope creep	Maintenance load.	Build it last, only for hooks modders actually need.
Modding terms	Distribution limits.	Check CD Projekt and Nexus Mods terms before publishing. Single-player only.

08Roadmap

P0RESEARCH

Map the ABI

Read the RED4ext plugin entry points and the imports and exports of an installed plugin. Inspect how cyber_engine_tweaks.asi hooks and resolves addresses.

P1PROOF

Hello-world plugin

A RED4ext plugin that logs the RTTI class count. Confirms build, load and logging on the current game version.

P2TIER 2

Pipe bridge and Node SDK

Expose one function over a named pipe and call it from Node. Then events, queries, commands and generated types.

P3RULES

Declarative rules

Native fast-path rules applied inside hooks with no IPC. Gives synchronous behavior with no engine.

P4TIER 1

QuickJS interceptors

Add the sandboxed runner, time limits, ordering and fault handling. Only after P2 and P3 show which hooks need it.

09Open questions

Full CET-style reflection access, or a smaller curated API for v1?
Which hooks must support Tier 1 interception on day one?
Implementation language for the native plugin: C++ with RED4ext.SDK, or Rust with red4ext-rs (Audioware is a Rust precedent)?
IPC transport: named pipe, local socket, or shared memory for hot data?
Packaging: should a Node mod ship inside the usual red4ext/plugins layout or its own folder?