Photo-mode and spawned lights (game 2.31)

Maturity: Draft. How lights reach V in photo mode: the engine's light component, photo mode's own three lights, how mods spawn and steer extra lights (CharLi, Appearance Menu Mod, World Builder), what exposure does to the result, and how a lighting setup authored in XF Studio maps onto game lights. Consolidated on 27 September 2026 from RED4ext.SDK's generated types, the decompiled 2.31 script bundle, the game's input configuration, the installed CharLi 2.2a, Appearance Menu Mod, Photo Mode Preferences and ENV Tuner packages in the reference MO2 instance (read only), the World Builder, Codeware and Cyber Engine Tweaks sources, and the lighting mirror's offline prototype. Little on this page has been seen in game yet: the photo-mode menu attributes (the bridge's first session dumped them) and where a photo-mode light starts (session 3, 28 September 2026). The mirror design that builds on it is research/runtime/lighting-mirror-design.md.

Grades follow the knowledge rules. [installed] is a mod package in the reference install, read only (paths are inside the mod's folder, mods/<mod name>/ under MO2). [offline] is the mirror prototype's own tests.

In brief

• Every game light is an entLightComponent with a colour, a type (point, spot, area), a unit (lumen, watt, lux, nit, EV100), an intensity, an attenuation (inverse square or linear) and radius, inner and outer cone angles, a softness exponent, a source radius and per-light shadow switches. Scripts can change only the colour, intensity, radius, cone angles, temperature, strength and on/off at run time; everything else is fixed when the component is created. source
• Photo mode has three lights of its own, each switched, typed (spot or ambient), shadowed, and set by brightness, range, cone angles and hue/saturation/luminance sliders (attributes 43–53). No menu value places a light, and how the sliders map to component values is unknown. runtime menu; mapping hypothesis
• Mods add lights by spawning entities, then steering them through the component's setters and moving them with the teleportation facility. CharLi and AMM spawn their own light templates through Cyber Engine Tweaks; World Builder spawns an empty entity through Codeware and adds a light component with every field set from data when the entity assembles. source [installed]
• Placing lights about V is solved in the mods: CharLi re-reads the photo-mode puppet's position and yaw on every update and teleports its lights to follow. [installed]
• A Studio setup can be mirrored with the same techniques: positions and aim convert exactly, colour and cones convert by the Studio's own conventions, and a light that came from the game (the creator rig) can be carried in its native lumens. Absolute brightness is the one thing that needs fitting, because photo mode's automatic exposure and the world's own light are not the Studio's. [offline] mapping; the match hypothesis

1. The light component

entLightComponent (alias LightComponent), and its game subclass gameLightComponent, carry these fields source RED4ext.SDK ad727771 include/RED4ext/Scripting/Natives/Generated/ent/LightComponent.hpp and the enums beside it:

The evaluation of spot and point lights, decoded from the clustered local-light shader, is in creator lighting §2: inverse-square saturate(1 − (d/r)⁴)² / d², linear 1 − saturate(d/r) with no 1/d² term, and a cone pow(saturate(a·cosθ + b), softness) source. How the CPU turns lumens and cone angles into the shader's constants is not known; the Studio reads lumens as candela Φ/4π hypothesis.

What scripts can change at run time source 2.31 core/components/lightComponent.script, gameLightComponent.script:

Unit, EV, attenuation, softness, source radius, type and the shadow switches have no setter. A mod that needs another value either spawns a different template (AMM keeps a _shadows twin of each light and respawns it, photo mode §5.2) or builds the component from data before it attaches (World Builder, §3) source. Whether writing those fields on a live component and toggling it takes effect is untested hypothesis.

Reading a component works from Lua: AMM reads intensity, radius, color, innerAngle, outerAngle, type and contactShadows straight off the component it finds by class name source AMM Modules/light.lua:3-27, 571-590.

2. Photo mode's own lights

• The lights are native entities: gamePhotomodeLightObject with a gamePhotomodeLightComponent, a subclass of entLightComponent with no script-visible fields of its own source SDK game/PhotomodeLightObject.hpp, game/PhotomodeLightComponent.hpp. The menu receives PhotomodeLightInitializedEvent { light: wref<Entity> } for each, and PhotomodeLightResetEvent exists source 2.31 orphans.script:53440-53443; SDK game/ui/PhotomodeLightResetEvent.hpp. No script handles the initialised event, so the controller that receives it is native.
• A light starts where the camera is when it switches on and stays there in the world runtime session 3 (28 September 2026): light 1 switched on before framing lit V only in one pass, and its reflection showed outside a window once the camera had moved. Switching it off and on after framing re-places it at the camera, unreliably in that session.
• Its entity can be reached and moved from script: the light indicator's projection for each light names the light's entity (GetProjection(index).GetEntity()), a gamePhotomodeLightObject game object, which TeleportationFacility.Teleport accepts source; XF Runtime Bridge 0.4 moves it about V's head and aims it at V (photo.light.set place), then reads its position back (held). Whether photo mode keeps a moved light there is open question 6.
• An off-screen light keeps its place. The light indicator projects the active light's position and shows an arrow at the screen edge while it is off screen source 2.31 photoModeLightIndicatorController.script:54-110. So a light stays in the world while the camera moves; where it starts is not traced. The input ResetCurrentLight (IK_R, left thumbstick) exists in the photo-mode context resource r6/config/inputContexts.xml:207, inputUserMappings.xml:2071-2074; that it puts the light back at the camera is a hypothesis.
• Lights reset each time photo mode opens runtime, so any tool sets them each time.
• Which component values the sliders produce (brightness to lumens or another unit, range to radius, hue/saturation/luminance to colour) is unknown. One read of the three components after setting each slider answers it (§7, question 1).

3. Spawning lights from a mod

• Moving a spawned light: GetTeleportationFacility():Teleport(entity, position, EulerAngles), every time the target moves [installed] CharLi cl.glow.lua:1473-1482.
• Aiming: a spot light's own +Y is its axis, the convention of the Blender add-on's sector importer (creator lighting §2) [hypothesis for spawned entities until one is placed in a session].
• Templates are the mod's own assets. A tool that spawns lights needs its own entity template (an empty entity is enough on the World Builder route); CharLi's, AMM's and World Builder's templates may not be reused (provenance follow-ups).
• Redscript without Codeware has no script-visible way to spawn an arbitrary template in 2.31 (no spawn function in the decompiled bundle) source; Codeware-dependent script can be compiled only when Codeware is present with @if(ModuleExists("Codeware")), as World Builder does source entBuilder.reds:1.

4. CharLi: a character light rig for photo mode

What and who. "CharLi – Character Lighting Suite for Photomode", Nexus mod 8176, version 2.2a in the reference install. Its script headers read "2023 by FreakaZ (+FlowerD)" and thank Beethy, Cyanide and PewPew [installed] bin/x64/plugins/cyber_engine_tweaks/mods/CharLi/init.lua:1-7. The Nexus page itself could not be checked (automated access is blocked), so the page's author field, permissions and any stated performance notes are unverified (provenance follow-ups). It is a Cyber Engine Tweaks mod (seven Lua files, 7,133 lines) plus archive/pc/mod/charli.archive (16 resources: light and prop templates under base\charli\) [installed].

What it does. It spawns groups of lights in a ring around V that follow V, in photo mode or in normal play. Its description allows up to 10 groups of 1, 2, 4, 6, 8 or 10 lights, 100 lights in all [installed] meta.ini description.

Not verified. The templates' own light settings (unit, attenuation, softness, shadows, source radius) sit in each entity's compressed component buffer. WolvenKit 9.0.1 refused to serialise these 2023-era entities (entMeshComponent.castShadows stored as a Bool where 2.x expects an enum), and WolvenKit 8.17.4 needed more memory than this study's 1 GB budget. So what CharLi's intensity numbers mean in lumens, and whether its lights cast shadows, stay open (question 4).

What it teaches. The whole mirror loop already exists in a player mod: spawn, set, follow V's photo-mode puppet by position and yaw, remove on load. What CharLi does not do is place lights from outside data: its positions come from ring parameters, not from a light list.

5. Exposure and what else changes the result

• Photo mode inherits the world's automatic exposure and offers its own compensation (attribute 10, ±2.2 raw, shown as −100 to 100; the range is the flat photo_mode.postFX.brightness_range and the step range / 100, photo mode §11.2) [installed] resource; the creator camera instead uses fixed manual exposure (creator lighting §4). Automatic exposure adapts to the frame, so the same lights look brighter on a dark surround.
• Exposure can be pinned in memory. ENV Tuner (CyanideX, per its script namespace) catches the environment resources as they load (Codeware resource callbacks on worldEnvironmentDefinition and worldEnvironmentAreaParameters), then rewrites each ExposureAreaSettings curve (minimum, maximum, compensation, adaptation speeds) to one point, and keeps the originals to restore [installed] r6/scripts/ENVTuner/ENVTuner.reds:395-445, modules/exposure.reds:84-160. Setting minimum equal to maximum should hold exposure fixed hypothesis.
• The grade is the same LUT in the creator and in photo mode, but runtime LUT mods such as LUT Switcher apply as player effects that may switch off in menus, so photo mode can be graded differently from the mirror screen (creator lighting §5) [installed].
• The world keeps lighting V: its sky, probes, GI and street lights all add to anything a tool spawns, and local lights without shadows shine through walls. The creator's box has none of that (creator lighting §10) resource.

6. Mapping a Studio setup onto game lights

The prototype is projects/xf-runtime-bridge/tools/lighting/mirror-map.ts with its tests (tools/test/lighting-mirror.test.ts, 19 passing) [offline]. The design and its reasons are in the lighting mirror design.

Open questions

1. What component values do photo mode's brightness, range and colour sliders produce, and where does each light start? (Catch the three gamePhotomodeLightObject entities and read their components and transforms; also answers photo mode open question 5.)
2. Does a light spawned through Codeware's static entity system with a component added at assembly render and shadow like a sector light with the same values?
3. Is a spot light's +Y its axis for a spawned entity, and does the engine's lumen conversion treat inverse-square and linear lights the same way (the creator calibration's open question 9)?
4. CharLi's template light settings (unit, falloff, softness, shadows): read with a WolvenKit build that accepts the 2023 format, within a memory budget.
5. Does pinning ExposureAreaSettings hold photo mode's exposure fixed, and is it restored cleanly?
6. Can the photo-mode lights themselves be moved with the teleportation facility, or does photo mode re-place them every frame? The entity route is built (bridge 0.4, photo.light.set place, which reports held). Since 0.4.1 it moves an entity only when the light indicator's projection for that index names a gamePhotomodeLightObject (checked by class name with IScriptable.IsA, since the class has no script declaration), no other light's projection names the same entity, and the indicator, when it shows a light, shows that one (PhotomodeLightIndicatorController.m_activeIndex); whether those checks hold in game is part of the preflight [offline]; the session-4 preflight answers it.

Sources

• RED4ext.SDK ad727771: ent/LightComponent.hpp, ELightUnit.hpp, ELightType.hpp, ELightShadowSoftnessMode.hpp, rend/LightAttenuation.hpp, rend/ContactShadowReciever.hpp, game/LightSettings.hpp, game/PhotomodeLight*.hpp, game/ui/PhotomodeLight*.hpp.
• Decompiled 2.31 script bundle (redscript-cli 0.5.31): core/components/lightComponent.script, gameLightComponent.script, cyberpunk/UI/fullscreen/photoMode/photoModeLightIndicatorController.script, photoModeMenuController.script, orphans.script.
• Game input configuration: r6/config/inputContexts.xml, inputUserMappings.xml (2.31).
• Installed packages, read only: CharLi 2.2a (Nexus 8176), Appearance Menu Mod (repository 5427235, same Lua as the installed 2.12.5), Photo Mode Preferences 0.1.1 (Nexus 32736), ENV Tuner 1.10 (Nexus 23079).
• Source: World Builder d9680f4d, Codeware 613a1cb8, Cyber Engine Tweaks 9a8522f.
• Who made each and what it taught us: community credits.

Related pages

Photo mode · Character-creator lighting · Runtime access · Lighting mirror design · Bridge autonomy backlog