XF Studio
Source

Knowledge base

How Cyberpunk 2077 fits together, as far as we know

XF Studio runs a research lab beside the product. It studies how the game’s engine, resources and modding frameworks work, so that the Studio can read game files the way the game does. These pages share its consolidated findings with the modding community. They are generated from the knowledge base in the repository each time the site is built, so they follow its current state.

Research in progress: some of this may be wrong. These notes record what XF Studio’s research has worked out so far about how Cyberpunk 2077 and its modding frameworks behave. Most of it comes from reading source code and game resources offline; not all of it has been confirmed in the running game, and claims graded hypothesis are unproven. If you spot a mistake or know more, please open an issue or a pull request.

Evidence grades

source
Read in engine/framework/tool source or decompiled data.
resource
Observed in extracted game or mod resources.
wiki
Documented in the Modding Docs, text or image.
runtime
Observed in the running game.
hypothesis
Not yet established.

01Topics

Published pages

Each page states what it covers, which game and framework versions it describes, and how each claim was established. Draft means consolidated but with significant gaps.

  • Character-customisation file chain

    Resource formats and the character-customisation file chain (.inkcharcustomization → .app → .ent → .mesh / .morphtarget → materials)

    Draftevery category mapped 30 Sep; resolver phase 1 implementedLast updated

  • Rendering every head character-creator option

    Rendering every head character-creator option (per-option resources, templates and key parameters, skin type versus tone, complexion mods, ranked preview render plan)

    DraftLast updated

  • V's body: resources, rig and the Studio's body render

    V's body (which resources make the third-person body per body gender, the consumer groups and censorship rules that pick them, the shared skin model and tone link, the rig and idle, and how the Studio draws it, including what clothing will need from it)

    Draftresolved and drawn offline; no runtime evidenceLast updated

  • Eye rendering (V's eyes, game 2.31)

    Eye rendering (the 71 eye colours as gradient, texture and multilayer materials; the refracted iris projection, cornea and iris normals, the Eye-class light, the wetness shell, how CCXL eye mods plug in, and the preview spec)

    Draftdecoded offline; no runtime evidenceLast updated

  • Materials and shaders (REDengine 4, game 2.31)

    Materials and shaders (.mt / .remt / .mi chains, shader templates, G-buffer channels; skin, hair, eye, decals, multilayered)

    DraftLast updated

  • Glitter in game: what can sparkle on a face decal (game 2.31)

    Glitter in game (what can sparkle on a face decal: the flake-to-pixel filter chain, plate texel density, temporal antialiasing and upscalers, candidate mechanisms, the proposed glint-flake route and its preview contract)

    Drafttraced and measured offline; no runtime evidenceLast updated

  • Hair shading (hair.mt family, game 2.31)

    Hair shading (hair.mt passes, .hp profile lookup and overlay, deferred Marschner-style hair light, brow decal sqrt blend)

    DraftLast updated

  • Hair and jewellery dangle physics

    Hair and jewellery dangle physics (how a hairstyle or worn earring declares swinging joints: the dangle component, its rig and bindings, the Dyng particle simulation and its per-joint parameters and collision capsules, what drives it in game, the solver's arithmetic from the executable, what the Studio does)

    Draftresources, type definitions, wiki and the executable's arithmetic; the Studio's solver reproduces it; no runtime evidenceLast updated

  • Eyebrows

    Eyebrows (the one shared brow mesh and per-style texture sets, the double-diffuse material and its gradient, how brow colour relates to hair colour, skinning and morphs, how CCXL brow mods merge into the vanilla switcher, what a brow designer can author)

    Draftdecoded offline; no runtime evidenceLast updated

  • Face makeup: cheeks, and how face decals combine

    Face makeup (vanilla cheek blush, freckles and metallic blush; the face-decal meshes' footprints, lifts, UV layouts and texel densities; how face decals combine; worn-item, replacement and CCXL makeup mods; head-UV regions for a cheek plate)

    Draftdecoded offline; no runtime evidenceLast updated

  • Tattoos: face and body, vanilla and modded

    Tattoos (the creator's face and body tattoo rows, their lifted decal meshes, UV layouts and texel densities, tone-tinted ink, how tattoos sit with skin, makeup, scars and clothing, how they cross body-part seams, texture-framework overlays against CCXL additions, the community tattoo rows)

    Draftdecoded and measured offline; no runtime evidenceLast updated

  • Character-creator and mirror lighting (game 2.31)

    Character-creator and mirror lighting (scene, 15-light rig, render-to-texture camera, fixed exposure, LogC3 grading LUT, indirect light (none from probes, GI or bounce; the lighting-integrate variants), preview spec and capture protocol; the Studio's Character creator lighting preset and calibration helper)

    DraftLast updated

  • Mod loading and resource precedence

    Mod loading and resource precedence (MO2 VFS, archive mount groups and order, ArchiveXL .xl discovery, scopes, fixes, patches, copies/links, dynamic materials, store editions and where each records the install)

    DraftLast updated

  • Vortex: how it deploys Cyberpunk 2077 mods

    Vortex (how it stages and hard-links Cyberpunk mods into the game folder, its deployment manifest, conflict and REDmod order, where it keeps mod metadata and Nexus ids, how to detect it and which profile is active, what XF Studio attributes, and how to add a mod without touching the user's setup)

    Draftsource read; central claims observed in one Windows Sandbox run; no game evidenceLast updated

  • Facial expressions and idles

    Facial expressions and idles (the facial control vocabulary, which graph drives V's face in the creator, photo mode and gameplay, how photo mode picks an expression, the creator's idle and section clips, how mods add expressions and poses, what an expression or idle export must look like, what each control does and how FACS action units map onto them)

    Draftdecoded offline; no runtime evidenceLast updated

  • Facial animation and the blink

    Facial animation and the blink (control tracks, the facial setup and solver, how a blink closes the lids and which joints it turns, the game's blink clips and timing, which setup V uses, eye shapes' own joint binds, the Studio's solved blink)

    Draftdecoded and solved offline; no runtime evidenceLast updated

  • Lip sync: how spoken lines move the face

    Lip sync (how a spoken line's facial clip is found through per-language lip-sync maps, scene actors and line names; what the clip's tracks do, including JALI's jaw and lip strengths, the lip-sync pose outputs and the override weights; how the facial setup layers speech over an expression; how modders add voiced lines today; open tools and rules for generating lip sync from new audio)

    Draftdecoded and solved offline; no runtime evidenceLast updated

  • Save files

    Save files (the container and its node tree, which nodes hold life path, progression, inventory, facts, world state and the creator's choices, the three node encodings, the save's own type database that makes script and mod data decodable without per-mod schemas, where mods keep their data in and outside the save, and what an editor must preserve)

    Draftsource study and read-only probes of three saves; no runtime evidenceLast updated

  • Piercings and jewellery

    Piercings and jewellery (the creator's piercing rows, the four shared piece banks and their chunk masks, how pieces follow facial morphs and animation, multilayered finishes, how PRC, inventory items and CCXL add jewellery, and the rules that keep a CCXL jewellery option additive)

    Draftdecoded offline; no piercing-specific runtime evidenceLast updated

  • Worn clothing

    Worn clothing (how a save records what V wears, including wardrobe overrides, hidden slots and EquipmentEx outfits; how an item resolves from its TweakDB record through the factory, suffixes and ArchiveXL dynamic appearances to meshes; how visual tags hide other items and body parts; garment layering and support; clothing materials; what rendering clothes in XF Studio would take)

    Draftsource, resource and wiki study; render plan phases 1–4 built; no runtime evidenceLast updated

  • Tooling: WolvenKit CLI

    Tooling (the WolvenKit CLI as XF Studio runs it: releases, runtime, success rules, uncook outputs; the Blender add-on and conversion round trips are not covered yet)

    DraftWolvenKit CLI releases, runtime, success rules, uncook outputsLast updated

  • Archive and resource formats

    Archive and resource formats (the .archive container, depot hashes, Oodle compression, CR2W resources, value encodings, compiledData packages, the resolver's JSON conventions, and the native reader that reads them without WolvenKit)

    Draftdecoded and checked against WolvenKit offline; the resolver reads through it firstLast updated

  • Runtime access: RED4ext, redscript, CET and the XF bridge

    Runtime access (RED4ext plugins and natives, redscript, CET, TweakXL; log locations; the XF named-pipe bridge; what agents can drive in game)

    Draftseen in game on 26 September: the bridge's reads, photo-mode writes, creator apply, clock and kill switch; the autonomy batch and batch 2 are built and tested offline onlyLast updated

  • Photo mode and the character creator from script

    Photo mode and the character creator from script (why a quest-node photo mode is restricted, the photo-mode key, the menu's attributes, camera presets, lights on/off and spawned light rigs, hiding the cursor, opening, confirming and leaving the creator, keeping its rows in step, and what photo-mode, camera and lighting mods teach an automated test session)

    Draftsource and mod study; menu and quest-node results from one sessionLast updated

  • Player control: moving V, the camera, interactions and input

    Player control from a mod (teleporting and walking V, navmesh checks and paths, turning the camera instantly or smoothly with the game's own look-at, what third-person and free cameras do, reading the HUD's interaction and dialogue choices from their blackboard and why choosing a dialogue line needs input, crouch, weapons, consumables and menus through the game's systems, how input reaches the game and the retail build's hidden functional-test input natives)

    Draftsource, resources and installed mods; no runtime evidenceLast updated

  • Photo-mode and spawned lights (game 2.31)

    Photo-mode and spawned lights (the engine's light component and what scripts can change, photo mode's three lights, how CharLi, Appearance Menu Mod and World Builder spawn and steer lights about V, exposure in photo mode, and how an XF Studio lighting setup maps onto game lights and back)

    Draftsource and installed-mod study, mapping prototype tested offline; no runtime evidence beyond the menu attributesLast updated

  • V's body in motion: the preview puppets, their idles and the deformation rig

    V's body in motion (the creator and inventory puppets, the preview idles each screen loops on V, the deformation rig that solves the body's helper joints and how the Studio evaluates it, which feet state each idle is authored for, the nails' skin)

    Draftoffline; no runtime evidenceLast updated

  • Photo-mode poses

    Photo-mode poses (the pose and category records and lists, which entity and animation sets hold the clips, what a pose clip holds and how its compressed keys are laid out, the body graph and the deformation rig that drives the helper joints, how mods add poses and which routes photo mode can't see)

    Draftsource, resource and mod study; no runtime evidenceLast updated

  • Terminals, the in-game browser, messages and arcade cabinets

    Terminals, the in-game browser, messages and arcade cabinets (how computers build their screens, why web pages are journal entries, three additive ways to add a site, how Browser Extension and Virtual Atelier let other mods plug in sites and stores, phone messages rewritten from script, what fits inside a page, how a cabinet launches Roach Race or the shooter, what a new arcade game would need, and options for authoring such content and scripting it in TypeScript)

    Draftsource, mod and resource study; no runtime evidenceLast updated

  • Quests, story content and persistent systems from mods

    Quests, story content and persistent systems from mods (how a mod attaches quest phases with ArchiveXL, the quest node types mods use, journal contacts, messages, quests, objectives and map pins, facts as the link between script and quest graphs, scenes and world pieces, a minimal quest recipe, braindances vanilla and staged, where long-lived mod state lives, what can be generated at run time, and what can be hot-reloaded)

    Draftsix installed story mods, their serialised quest resources and framework source; no runtime evidenceLast updated

  • The game's UI system (ink): building, injecting and drawing XF UI in game

    The game's UI system, ink (widgets built from script, the game's fonts and colour tokens, animation as a UI clock, input and the cursor, the HUD's layers and entries, where and how a mod joins each standard screen, world-space ink on surfaces and floating labels, map pins and markers, 3D previews and video in UI, and whether an XF-owned overlay is feasible beside Cyber Engine Tweaks)

    Draftsource-read; the bridge's first ink demos await their sessionLast updated

  • Skin and makeup on spawned objects

    Skin and makeup on spawned objects (how a prop in the world can show a character's skin and makeup: a replica of V that carries only the character creator's controllers, as Phantom Liberty's head in a tank and the V's Faceplate mod use it, against a static head built from explicit mesh components on the player head's own rig, as the shop mannequins are; how XF Finish Showroom builds its heads and light rigs from the second)

    Draftresource and mod study, offline build; no runtime evidenceLast updated

  • The game world, streaming and location mods

    The game world and location mods (how Night City is split into streaming blocks and sectors, what a sector holds and how its nodes are placed, the kinds of world node from meshes and instances to collision, lighting, occlusion, communities and navigation, how the game streams them, how mods add sectors, hide or move vanilla nodes, patch devices and hook quests without replacing each other, how World Builder authors locations, runtime spawning, a dozen location mods as worked examples, what loading and drawing a location offline would take, and the risks when mods overlap)

    Draftsource, resource, wiki and mod study; no runtime evidenceLast updated

  • NPC reactions, crowd barks and what NPCs can notice about V

    NPC reactions and crowd barks (stimuli and reaction presets, the proximity look-at and facial reaction including the game's one appearance reaction to a naked V, how an NPC's generic voice lines are chosen through voiceset scenes and trigger names, which vanilla lines could comment on V, script-built overhead text barks, what a script can read about V's clothes, car and district, what reaction mods already do, and how a mod could add reactions)

    Draftsource, resource and mod study; no runtime evidenceLast updated

  • NPC direction: spawning, moving, speaking and choices from a mod

    NPC direction from a mod (spawning NPCs that never reach a save with Codeware's dynamic entities, choosing an existing NPC safely, the AI commands that walk, follow, turn, hold and teleport an NPC and how to track and cancel them, speech in the NPC's own voice or as subtitle, overhead and holocall-style text, dialogue choices added to the game's own widget at run time versus .scene choice nodes, facial reactions, look-at and workspot gestures, and clean-up)

    Draftsource, resource and mod study; no runtime evidenceLast updated

  • Game crashes: reading them, known triggers and how to probe

    Game crashes (where the game records a crash, fingerprinting a minidump without a debugger, known crash triggers including native-to-script calls, the crash after a crash, finding the crashing call with one probe)

    DraftLast updated

Not published yet

Topics the knowledge base covers only as pointers to existing research so far.

  • Animation, rigs and facial deformation Seed

02Corrections

Help us get it right

These notes will contain mistakes. If you know better, or can confirm something in game, please open an issue or send a pull request that edits the page’s Markdown in the knowledge folder. Links to sources, captures or tests help most.

The Cyberpunk 2077 Modding Wiki remains the community’s reference. These pages link to it rather than copy it, and add what our own reading of source code and resources found.

03Attribution

Built on community work

Much of this knowledge comes from modders, tool authors and wiki writers. Each page cites its sources inline, with links to the wiki pages, mods and repositories it learned from, and the credits acknowledge everyone whose work taught us something. If you recognise your work and it is not credited properly, please tell us.