A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
feat(render): editor-view studio preview lighting and preview exposure
yhhb60521df42fa
diff --git a/fixtures/scenes/studio-preview-hdr.esscene b/fixtures/scenes/studio-preview-hdr.esscenenew file mode 100644index 000000000..aa3536a1b--- /dev/null+++ b/fixtures/scenes/studio-preview-hdr.esscene@@ -0,0 +1,144 @@+{+ "version": 4,+ "name": "StudioPreviewHdr",+ "entities": [+ {+ "id": 0,+ "name": "Camera",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 0,+ "y": 0,+ "z": 300+ }+ }+ },+ {+ "type": "Camera",+ "data": {+ "projectionType": 1,+ "orthoSize": 150,+ "isActive": true,+ "priority": 0+ }+ }+ ]+ },+ {+ "id": 1,+ "name": "Cube",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": -75,+ "y": 0,+ "z": 0+ },+ "rotation": {+ "x": 0,+ "y": -0.3826834324,+ "z": 0,+ "w": 0.9238795325+ }+ }+ },+ {+ "type": "MeshRenderer",+ "data": {+ "mesh": "builtin:cube",+ "color": {+ "r": 1,+ "g": 1,+ "b": 1,+ "a": 1+ },+ "lit": true,+ "opaque": true,+ "cullBackfaces": true,+ "enabled": true+ }+ }+ ]+ },+ {+ "id": 2,+ "name": "Sphere",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 75,+ "y": 0,+ "z": 0+ }+ }+ },+ {+ "type": "MeshRenderer",+ "data": {+ "mesh": "builtin:sphere",+ "color": {+ "r": 1,+ "g": 1,+ "b": 1,+ "a": 1+ },+ "lit": true,+ "opaque": true,+ "cullBackfaces": true,+ "enabled": true+ }+ }+ ]+ },+ {+ "id": 4,+ "name": "Sky",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 0,+ "y": 0,+ "z": 0+ }+ }+ },+ {+ "type": "Light",+ "data": {+ "type": 2,+ "color": {+ "r": 1,+ "g": 1,+ "b": 1,+ "a": 1+ },+ "intensity": 1,+ "environment": "/scenes/studio.esenv",+ "drawEnvironment": true+ }+ }+ ]+ }+ ]+}diff --git a/fixtures/scenes/studio-preview-nolight.esscene b/fixtures/scenes/studio-preview-nolight.esscenenew file mode 100644index 000000000..669fe206f--- /dev/null+++ b/fixtures/scenes/studio-preview-nolight.esscene@@ -0,0 +1,110 @@+{+ "version": 4,+ "name": "StudioPreviewNoLight",+ "entities": [+ {+ "id": 0,+ "name": "Camera",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 0,+ "y": 0,+ "z": 300+ }+ }+ },+ {+ "type": "Camera",+ "data": {+ "projectionType": 1,+ "orthoSize": 150,+ "isActive": true,+ "priority": 0+ }+ }+ ]+ },+ {+ "id": 1,+ "name": "Cube",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": -75,+ "y": 0,+ "z": 0+ },+ "rotation": {+ "x": 0,+ "y": -0.3826834324,+ "z": 0,+ "w": 0.9238795325+ }+ }+ },+ {+ "type": "MeshRenderer",+ "data": {+ "mesh": "builtin:cube",+ "color": {+ "r": 1,+ "g": 1,+ "b": 1,+ "a": 1+ },+ "lit": true,+ "opaque": true,+ "cullBackfaces": true,+ "enabled": true+ }+ }+ ]+ },+ {+ "id": 2,+ "name": "Sphere",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 75,+ "y": 0,+ "z": 0+ }+ }+ },+ {+ "type": "MeshRenderer",+ "data": {+ "mesh": "builtin:sphere",+ "color": {+ "r": 1,+ "g": 1,+ "b": 1,+ "a": 1+ },+ "lit": true,+ "opaque": true,+ "cullBackfaces": true,+ "enabled": true+ }+ }+ ]+ }+ ]+}diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 2f0872bd1..3973c19a1 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -1,7 +1,7 @@# API surface — esengine/index<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 115 public · 109 beta · 1581 experimental · 3 deprecated+Symbols: 115 public · 109 beta · 1599 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -304,6 +304,11 @@ Start = 1Stretch = 4```+## AmbientSkip — type @experimental+```+'hidden' | 'disabled' | 'no-intensity'+```+## Ambiguity — interface @experimental```a: string@@ -2700,6 +2705,11 @@ EditorGridDataEditorViewData```+## DEFAULT_EDITOR_VIEW_LIGHTING — const @experimental+```+EditorViewLightingData+```+## DEFAULT_FACING_COSINE — const @experimental```0.2@@ -3348,6 +3358,11 @@ tabIndex: number | undefinedworld: World```+## EDITOR_EXPOSURE_RANGE — const @experimental+```+{ readonly min: -6; readonly max: 6; }+```+## EDITOR_UI_ANCHOR — const @experimental```{ readonly x: 0; readonly y: 0; }@@ -3418,6 +3433,11 @@ majorEvery: numberspacing: number```+## EditorLightingMode — type @experimental+```+'scene' | 'studio'+```+## EditorView — const @experimental```ResourceDef<EditorViewData>@@ -3445,6 +3465,22 @@ yaw: numberz: number```+## EditorViewLighting — const @experimental+```+ResourceDef<EditorViewLightingData>+```++## EditorViewLightingData — interface @experimental+```+exposure: number+fillIntensity: number+keyIntensity: number+mode: EditorLightingMode+rotation: number+showSky: boolean+skyIntensity: number+```+## EditorWorkPlane — interface @experimental```normal: WorldAxis@@ -3589,6 +3625,14 @@ pickable: ((entity: Entity) => boolean) | undefinedySortLayers: number | undefined```+## EnvironmentLightEntity — interface @experimental+```+components: readonly { type: string; data: Record<string, unknown>; }[]+id: number+name: string+visible: boolean | undefined+```+## EventBinding — const @experimental```ComponentDef<EventBindingData>@@ -7375,6 +7419,18 @@ setJSON: <T>(key: string, value: T) => void(typeof ScaleMode)[keyof typeof ScaleMode]```+## SceneAmbientLight — interface @experimental+```+drawEnvironment: boolean+entityId: number+environment: string | null+environmentMissing: boolean+intensity: number+name: string+rotation: number+skipped: AmbientSkip | null+```+## SceneAssetRefs — interface @experimental```byType: Map<string, Set<string>>@@ -7428,6 +7484,11 @@ trackAssets: (byType: ReadonlyMap<string, ReadonlySet<string>>) => voidunbindPostProcess: (camera: Entity) => void```+## SceneDark — type @experimental+```+'no-lights' | 'no-enabled-light'+```+## SceneData — interface @experimental```entities: SceneEntityData[]@@ -7921,6 +7982,11 @@ vertices: Uint8Array<ArrayBufferLike>| { kind: 'sh'; irradiance: readonly number[]; yaw: number; tint: readonly [number, number, number] }```+## SkyUnavailable — type @experimental+```+'no-ambient' | 'no-environment' | 'missing' | 'off' | 'unusable'+```+## SliceBorder — interface @experimental```bottom: number@@ -8531,6 +8597,14 @@ ComponentDef<StreamedWorldData>cellSize: number```+## StudioPreviewReport — interface @experimental+```+environment: SceneAmbientLight | null+sceneDark: SceneDark | null+sceneLights: number+skyUnavailable: SkyUnavailable | null+```+## SubEmitterTrigger — enum @beta```Birth = 1@@ -10826,6 +10900,11 @@ MotionDriver<AnimatorBlend2DMotion>(at: readonly [number, number, number], bvh: Bvh, lookup: HitLookup, atlas: Float32Array, atlasSize: number, width: number, height: number, sky: SkyRadiance): CapturedPanorama```+## carriesEnvironment — function @experimental+```+(light: SceneAmbientLight): boolean+```+## catalogFromManifest — function @experimental```(manifest: AddressableManifest): Catalog | undefined@@ -11366,6 +11445,16 @@ DragPlugin(view: EditorViewData): boolean```+## editorViewLightingArgs — function @experimental+```+(data: EditorViewLightingData, viewActive: boolean): { mode: number; rotation: number; key: number; fill: number; sky: number; showSky: boolean; exposure: number; }+```++## editorViewLightingIsOverriding — function @experimental+```+(data: EditorViewLightingData): boolean+```+## editorViewStandoff — function @experimental```(view: EditorViewData): number@@ -12766,6 +12855,11 @@ PrefabsPlugin(): CppResourceManager```+## resetEditorViewLighting — function @experimental+```+(data: EditorViewLightingData): EditorViewLightingData+```+## resetWorldTo — function @experimental```(world: World, sceneData: SceneData): Map<number, Entity>@@ -12856,6 +12950,16 @@ SafeAreaPlugin{ readonly clamp: (x: number, min: number, max: number) => number; readonly clamp01: (x: number) => number; readonly lerp: (a: number, b: number, t: number) => number; readonly inverseLerp: (a: number, b: number, value: number) => number; readonly remap: (value: number, inMin: number, inMax: number, outMin: number, outMax: number) => number; readonly deg2rad: (deg: number) => number; readonly rad2deg: (rad: number) => number; readonly approximately: (a: number, b: number, epsilon?: number) => boolean; readonly smoothstep: (edge0: number, edge1: number, x: number) => number; readonly mod: (x: number, n: number) => number; readonly sign: (x: number) => number; }```+## sceneAmbientLights — function @experimental+```+(entities: readonly EnvironmentLightEntity[], exists: (ref: string) => boolean): SceneAmbientLight[]+```++## sceneEnvironment — function @experimental+```+(lights: readonly SceneAmbientLight[]): { effective: SceneAmbientLight | null; shadowed: SceneAmbientLight[]; }+```+## sceneManagerPlugin — const @experimental```Plugin@@ -13241,6 +13345,11 @@ StatsPlugin(world: World, entity: Entity): void```+## studioPreviewReport — function @experimental+```+(entities: readonly EnvironmentLightEntity[], exists: (ref: string) => boolean): StudioPreviewReport+```+## summarizeCapture — function @experimental```(capture: ProfileCapture): CaptureSummarydiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 6db8ed849..059e3ba88 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -1,7 +1,7 @@# API surface — esengine/index.native<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 115 public · 114 beta · 1600 experimental · 3 deprecated+Symbols: 115 public · 114 beta · 1618 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -304,6 +304,11 @@ Start = 1Stretch = 4```+## AmbientSkip — type @experimental+```+'hidden' | 'disabled' | 'no-intensity'+```+## Ambiguity — interface @experimental```a: string@@ -2708,6 +2713,11 @@ EditorGridDataEditorViewData```+## DEFAULT_EDITOR_VIEW_LIGHTING — const @experimental+```+EditorViewLightingData+```+## DEFAULT_FACING_COSINE — const @experimental```0.2@@ -3356,6 +3366,11 @@ tabIndex: number | undefinedworld: World```+## EDITOR_EXPOSURE_RANGE — const @experimental+```+{ readonly min: -6; readonly max: 6; }+```+## EDITOR_UI_ANCHOR — const @experimental```{ readonly x: 0; readonly y: 0; }@@ -3426,6 +3441,11 @@ majorEvery: numberspacing: number```+## EditorLightingMode — type @experimental+```+'scene' | 'studio'+```+## EditorView — const @experimental```ResourceDef<EditorViewData>@@ -3453,6 +3473,22 @@ yaw: numberz: number```+## EditorViewLighting — const @experimental+```+ResourceDef<EditorViewLightingData>+```++## EditorViewLightingData — interface @experimental+```+exposure: number+fillIntensity: number+keyIntensity: number+mode: EditorLightingMode+rotation: number+showSky: boolean+skyIntensity: number+```+## EditorWorkPlane — interface @experimental```normal: WorldAxis@@ -3597,6 +3633,14 @@ pickable: ((entity: Entity) => boolean) | undefinedySortLayers: number | undefined```+## EnvironmentLightEntity — interface @experimental+```+components: readonly { type: string; data: Record<string, unknown>; }[]+id: number+name: string+visible: boolean | undefined+```+## EventBinding — const @experimental```ComponentDef<EventBindingData>@@ -7588,6 +7632,18 @@ setJSON: <T>(key: string, value: T) => void(typeof ScaleMode)[keyof typeof ScaleMode]```+## SceneAmbientLight — interface @experimental+```+drawEnvironment: boolean+entityId: number+environment: string | null+environmentMissing: boolean+intensity: number+name: string+rotation: number+skipped: AmbientSkip | null+```+## SceneAssetRefs — interface @experimental```byType: Map<string, Set<string>>@@ -7641,6 +7697,11 @@ trackAssets: (byType: ReadonlyMap<string, ReadonlySet<string>>) => voidunbindPostProcess: (camera: Entity) => void```+## SceneDark — type @experimental+```+'no-lights' | 'no-enabled-light'+```+## SceneData — interface @experimental```entities: SceneEntityData[]@@ -8134,6 +8195,11 @@ vertices: Uint8Array<ArrayBufferLike>| { kind: 'sh'; irradiance: readonly number[]; yaw: number; tint: readonly [number, number, number] }```+## SkyUnavailable — type @experimental+```+'no-ambient' | 'no-environment' | 'missing' | 'off' | 'unusable'+```+## SliceBorder — interface @experimental```bottom: number@@ -8744,6 +8810,14 @@ ComponentDef<StreamedWorldData>cellSize: number```+## StudioPreviewReport — interface @experimental+```+environment: SceneAmbientLight | null+sceneDark: SceneDark | null+sceneLights: number+skyUnavailable: SkyUnavailable | null+```+## SubEmitterTrigger — enum @beta```Birth = 1@@ -11054,6 +11128,11 @@ MotionDriver<AnimatorBlend2DMotion>(at: readonly [number, number, number], bvh: Bvh, lookup: HitLookup, atlas: Float32Array, atlasSize: number, width: number, height: number, sky: SkyRadiance): CapturedPanorama```+## carriesEnvironment — function @experimental+```+(light: SceneAmbientLight): boolean+```+## catalogFromManifest — function @experimental```(manifest: AddressableManifest): Catalog | undefined@@ -11619,6 +11698,16 @@ DragPlugin(view: EditorViewData): boolean```+## editorViewLightingArgs — function @experimental+```+(data: EditorViewLightingData, viewActive: boolean): { mode: number; rotation: number; key: number; fill: number; sky: number; showSky: boolean; exposure: number; }+```++## editorViewLightingIsOverriding — function @experimental+```+(data: EditorViewLightingData): boolean+```+## editorViewStandoff — function @experimental```(view: EditorViewData): number@@ -13029,6 +13118,11 @@ PrefabsPlugin(): CppResourceManager```+## resetEditorViewLighting — function @experimental+```+(data: EditorViewLightingData): EditorViewLightingData+```+## resetWorldTo — function @experimental```(world: World, sceneData: SceneData): Map<number, Entity>@@ -13119,6 +13213,16 @@ SafeAreaPlugin{ readonly clamp: (x: number, min: number, max: number) => number; readonly clamp01: (x: number) => number; readonly lerp: (a: number, b: number, t: number) => number; readonly inverseLerp: (a: number, b: number, value: number) => number; readonly remap: (value: number, inMin: number, inMax: number, outMin: number, outMax: number) => number; readonly deg2rad: (deg: number) => number; readonly rad2deg: (rad: number) => number; readonly approximately: (a: number, b: number, epsilon?: number) => boolean; readonly smoothstep: (edge0: number, edge1: number, x: number) => number; readonly mod: (x: number, n: number) => number; readonly sign: (x: number) => number; }```+## sceneAmbientLights — function @experimental+```+(entities: readonly EnvironmentLightEntity[], exists: (ref: string) => boolean): SceneAmbientLight[]+```++## sceneEnvironment — function @experimental+```+(lights: readonly SceneAmbientLight[]): { effective: SceneAmbientLight | null; shadowed: SceneAmbientLight[]; }+```+## sceneManagerPlugin — const @experimental```Plugin@@ -13504,6 +13608,11 @@ StatsPlugin(world: World, entity: Entity): void```+## studioPreviewReport — function @experimental+```+(entities: readonly EnvironmentLightEntity[], exists: (ref: string) => boolean): StudioPreviewReport+```+## summarizeCapture — function @experimental```(capture: ProfileCapture): CaptureSummarydiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 073c8c3d6..18f893185 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -1,7 +1,7 @@# API surface — esengine/index.node<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 115 public · 111 beta · 1580 experimental · 3 deprecated+Symbols: 115 public · 111 beta · 1598 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -299,6 +299,11 @@ Start = 1Stretch = 4```+## AmbientSkip — type @experimental+```+'hidden' | 'disabled' | 'no-intensity'+```+## Ambiguity — interface @experimental```a: string@@ -2695,6 +2700,11 @@ EditorGridDataEditorViewData```+## DEFAULT_EDITOR_VIEW_LIGHTING — const @experimental+```+EditorViewLightingData+```+## DEFAULT_FACING_COSINE — const @experimental```0.2@@ -3343,6 +3353,11 @@ tabIndex: number | undefinedworld: World```+## EDITOR_EXPOSURE_RANGE — const @experimental+```+{ readonly min: -6; readonly max: 6; }+```+## EDITOR_UI_ANCHOR — const @experimental```{ readonly x: 0; readonly y: 0; }@@ -3413,6 +3428,11 @@ majorEvery: numberspacing: number```+## EditorLightingMode — type @experimental+```+'scene' | 'studio'+```+## EditorView — const @experimental```ResourceDef<EditorViewData>@@ -3440,6 +3460,22 @@ yaw: numberz: number```+## EditorViewLighting — const @experimental+```+ResourceDef<EditorViewLightingData>+```++## EditorViewLightingData — interface @experimental+```+exposure: number+fillIntensity: number+keyIntensity: number+mode: EditorLightingMode+rotation: number+showSky: boolean+skyIntensity: number+```+## EditorWorkPlane — interface @experimental```normal: WorldAxis@@ -3584,6 +3620,14 @@ pickable: ((entity: Entity) => boolean) | undefinedySortLayers: number | undefined```+## EnvironmentLightEntity — interface @experimental+```+components: readonly { type: string; data: Record<string, unknown>; }[]+id: number+name: string+visible: boolean | undefined+```+## EventBinding — const @experimental```ComponentDef<EventBindingData>@@ -7370,6 +7414,18 @@ setJSON: <T>(key: string, value: T) => void(typeof ScaleMode)[keyof typeof ScaleMode]```+## SceneAmbientLight — interface @experimental+```+drawEnvironment: boolean+entityId: number+environment: string | null+environmentMissing: boolean+intensity: number+name: string+rotation: number+skipped: AmbientSkip | null+```+## SceneAssetRefs — interface @experimental```byType: Map<string, Set<string>>@@ -7423,6 +7479,11 @@ trackAssets: (byType: ReadonlyMap<string, ReadonlySet<string>>) => voidunbindPostProcess: (camera: Entity) => void```+## SceneDark — type @experimental+```+'no-lights' | 'no-enabled-light'+```+## SceneData — interface @experimental```entities: SceneEntityData[]@@ -7916,6 +7977,11 @@ vertices: Uint8Array<ArrayBufferLike>| { kind: 'sh'; irradiance: readonly number[]; yaw: number; tint: readonly [number, number, number] }```+## SkyUnavailable — type @experimental+```+'no-ambient' | 'no-environment' | 'missing' | 'off' | 'unusable'+```+## SliceBorder — interface @experimental```bottom: number@@ -8526,6 +8592,14 @@ ComponentDef<StreamedWorldData>cellSize: number```+## StudioPreviewReport — interface @experimental+```+environment: SceneAmbientLight | null+sceneDark: SceneDark | null+sceneLights: number+skyUnavailable: SkyUnavailable | null+```+## SubEmitterTrigger — enum @beta```Birth = 1@@ -10821,6 +10895,11 @@ MotionDriver<AnimatorBlend2DMotion>(at: readonly [number, number, number], bvh: Bvh, lookup: HitLookup, atlas: Float32Array, atlasSize: number, width: number, height: number, sky: SkyRadiance): CapturedPanorama```+## carriesEnvironment — function @experimental+```+(light: SceneAmbientLight): boolean+```+## catalogFromManifest — function @experimental```(manifest: AddressableManifest): Catalog | undefined@@ -11361,6 +11440,16 @@ DragPlugin(view: EditorViewData): boolean```+## editorViewLightingArgs — function @experimental+```+(data: EditorViewLightingData, viewActive: boolean): { mode: number; rotation: number; key: number; fill: number; sky: number; showSky: boolean; exposure: number; }+```++## editorViewLightingIsOverriding — function @experimental+```+(data: EditorViewLightingData): boolean+```+## editorViewStandoff — function @experimental```(view: EditorViewData): number@@ -12771,6 +12860,11 @@ PrefabsPlugin(): CppResourceManager```+## resetEditorViewLighting — function @experimental+```+(data: EditorViewLightingData): EditorViewLightingData+```+## resetWorldTo — function @experimental```(world: World, sceneData: SceneData): Map<number, Entity>@@ -12861,6 +12955,16 @@ SafeAreaPlugin{ readonly clamp: (x: number, min: number, max: number) => number; readonly clamp01: (x: number) => number; readonly lerp: (a: number, b: number, t: number) => number; readonly inverseLerp: (a: number, b: number, value: number) => number; readonly remap: (value: number, inMin: number, inMax: number, outMin: number, outMax: number) => number; readonly deg2rad: (deg: number) => number; readonly rad2deg: (rad: number) => number; readonly approximately: (a: number, b: number, epsilon?: number) => boolean; readonly smoothstep: (edge0: number, edge1: number, x: number) => number; readonly mod: (x: number, n: number) => number; readonly sign: (x: number) => number; }```+## sceneAmbientLights — function @experimental+```+(entities: readonly EnvironmentLightEntity[], exists: (ref: string) => boolean): SceneAmbientLight[]+```++## sceneEnvironment — function @experimental+```+(lights: readonly SceneAmbientLight[]): { effective: SceneAmbientLight | null; shadowed: SceneAmbientLight[]; }+```+## sceneManagerPlugin — const @experimental```Plugin@@ -13246,6 +13350,11 @@ StatsPlugin(world: World, entity: Entity): void```+## studioPreviewReport — function @experimental+```+(entities: readonly EnvironmentLightEntity[], exists: (ref: string) => boolean): StudioPreviewReport+```+## summarizeCapture — function @experimental```(capture: ProfileCapture): CaptureSummarydiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 7d4a0b808..20af3f57b 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -1,7 +1,7 @@# API surface — esengine/minigame<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 115 public · 109 beta · 1602 experimental · 3 deprecated+Symbols: 115 public · 109 beta · 1620 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -299,6 +299,11 @@ Start = 1Stretch = 4```+## AmbientSkip — type @experimental+```+'hidden' | 'disabled' | 'no-intensity'+```+## Ambiguity — interface @experimental```a: string@@ -2695,6 +2700,11 @@ EditorGridDataEditorViewData```+## DEFAULT_EDITOR_VIEW_LIGHTING — const @experimental+```+EditorViewLightingData+```+## DEFAULT_FACING_COSINE — const @experimental```0.2@@ -3343,6 +3353,11 @@ tabIndex: number | undefinedworld: World```+## EDITOR_EXPOSURE_RANGE — const @experimental+```+{ readonly min: -6; readonly max: 6; }+```+## EDITOR_UI_ANCHOR — const @experimental```{ readonly x: 0; readonly y: 0; }@@ -3413,6 +3428,11 @@ majorEvery: numberspacing: number```+## EditorLightingMode — type @experimental+```+'scene' | 'studio'+```+## EditorView — const @experimental```ResourceDef<EditorViewData>@@ -3440,6 +3460,22 @@ yaw: numberz: number```+## EditorViewLighting — const @experimental+```+ResourceDef<EditorViewLightingData>+```++## EditorViewLightingData — interface @experimental+```+exposure: number+fillIntensity: number+keyIntensity: number+mode: EditorLightingMode+rotation: number+showSky: boolean+skyIntensity: number+```+## EditorWorkPlane — interface @experimental```normal: WorldAxis@@ -3584,6 +3620,14 @@ pickable: ((entity: Entity) => boolean) | undefinedySortLayers: number | undefined```+## EnvironmentLightEntity — interface @experimental+```+components: readonly { type: string; data: Record<string, unknown>; }[]+id: number+name: string+visible: boolean | undefined+```+## EventBinding — const @experimental```ComponentDef<EventBindingData>@@ -7663,6 +7707,18 @@ setJSON: <T>(key: string, value: T) => void(typeof ScaleMode)[keyof typeof ScaleMode]```+## SceneAmbientLight — interface @experimental+```+drawEnvironment: boolean+entityId: number+environment: string | null+environmentMissing: boolean+intensity: number+name: string+rotation: number+skipped: AmbientSkip | null+```+## SceneAssetRefs — interface @experimental```byType: Map<string, Set<string>>@@ -7716,6 +7772,11 @@ trackAssets: (byType: ReadonlyMap<string, ReadonlySet<string>>) => voidunbindPostProcess: (camera: Entity) => void```+## SceneDark — type @experimental+```+'no-lights' | 'no-enabled-light'+```+## SceneData — interface @experimental```entities: SceneEntityData[]@@ -8209,6 +8270,11 @@ vertices: Uint8Array<ArrayBufferLike>| { kind: 'sh'; irradiance: readonly number[]; yaw: number; tint: readonly [number, number, number] }```+## SkyUnavailable — type @experimental+```+'no-ambient' | 'no-environment' | 'missing' | 'off' | 'unusable'+```+## SliceBorder — interface @experimental```bottom: number@@ -8819,6 +8885,14 @@ ComponentDef<StreamedWorldData>cellSize: number```+## StudioPreviewReport — interface @experimental+```+environment: SceneAmbientLight | null+sceneDark: SceneDark | null+sceneLights: number+skyUnavailable: SkyUnavailable | null+```+## SubEmitterTrigger — enum @beta```Birth = 1@@ -11120,6 +11194,11 @@ MotionDriver<AnimatorBlend2DMotion>(at: readonly [number, number, number], bvh: Bvh, lookup: HitLookup, atlas: Float32Array, atlasSize: number, width: number, height: number, sky: SkyRadiance): CapturedPanorama```+## carriesEnvironment — function @experimental+```+(light: SceneAmbientLight): boolean+```+## catalogFromManifest — function @experimental```(manifest: AddressableManifest): Catalog | undefined@@ -11665,6 +11744,16 @@ DragPlugin(view: EditorViewData): boolean```+## editorViewLightingArgs — function @experimental+```+(data: EditorViewLightingData, viewActive: boolean): { mode: number; rotation: number; key: number; fill: number; sky: number; showSky: boolean; exposure: number; }+```++## editorViewLightingIsOverriding — function @experimental+```+(data: EditorViewLightingData): boolean+```+## editorViewStandoff — function @experimental```(view: EditorViewData): number@@ -13075,6 +13164,11 @@ PrefabsPlugin(): CppResourceManager```+## resetEditorViewLighting — function @experimental+```+(data: EditorViewLightingData): EditorViewLightingData+```+## resetWorldTo — function @experimental```(world: World, sceneData: SceneData): Map<number, Entity>@@ -13165,6 +13259,16 @@ SafeAreaPlugin{ readonly clamp: (x: number, min: number, max: number) => number; readonly clamp01: (x: number) => number; readonly lerp: (a: number, b: number, t: number) => number; readonly inverseLerp: (a: number, b: number, value: number) => number; readonly remap: (value: number, inMin: number, inMax: number, outMin: number, outMax: number) => number; readonly deg2rad: (deg: number) => number; readonly rad2deg: (rad: number) => number; readonly approximately: (a: number, b: number, epsilon?: number) => boolean; readonly smoothstep: (edge0: number, edge1: number, x: number) => number; readonly mod: (x: number, n: number) => number; readonly sign: (x: number) => number; }```+## sceneAmbientLights — function @experimental+```+(entities: readonly EnvironmentLightEntity[], exists: (ref: string) => boolean): SceneAmbientLight[]+```++## sceneEnvironment — function @experimental+```+(lights: readonly SceneAmbientLight[]): { effective: SceneAmbientLight | null; shadowed: SceneAmbientLight[]; }+```+## sceneManagerPlugin — const @experimental```Plugin@@ -13550,6 +13654,11 @@ StatsPlugin(world: World, entity: Entity): void```+## studioPreviewReport — function @experimental+```+(entities: readonly EnvironmentLightEntity[], exists: (ref: string) => boolean): StudioPreviewReport+```+## summarizeCapture — function @experimental```(capture: ProfileCapture): CaptureSummarydiff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.mdindex d06e82f9f..c0c3af074 100644--- a/sdk/etc/wasm.api.md+++ b/sdk/etc/wasm.api.md@@ -398,6 +398,7 @@ postprocess_setScreenUniformFloat: (passName: string, uniform: string, value: nupostprocess_setScreenUniformVec4: (passName: string, uniform: string, x: number, y: number, z: number, w: number) => voidpostprocess_setUniformFloat: (passName: string, uniform: string, value: number) => voidpostprocess_setUniformVec4: (passName: string, uniform: string, x: number, y: number, z: number, w: number) => void+postprocess_setViewExposure: ((ev: number) => void) | undefinedpostprocess_shutdown: () => voidprobe_volume_create: ((resX: number, resY: number, resZ: number, shPtr: number) => number) | undefinedprobe_volume_release: ((volumeHandle: number) => void) | undefined@@ -489,6 +490,7 @@ renderer_setShadowDistance: ((distance: number) => void) | undefinedrenderer_setStage: (stage: number) => voidrenderer_setTextureParams: (textureId: number, minFilter: number, magFilter: number, wrapS: number, wrapT: number) => voidrenderer_setViewId: ((view: number) => void) | undefined+renderer_setViewLighting: ((mode: number, rotationDegrees: number, keyIntensity: number, fillIntensity: number, skyIntensity: number, showSky: boolean) => void) | undefinedrenderer_setViewport: (x: number, y: number, w: number, h: number) => voidrenderer_setYSortLayers: ((mask: number) => void) | undefinedrenderer_shadowStatus: ((entity: number, outPtr: number) => number) | undefineddiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex d90773976..bc5ce6e57 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -1,7 +1,7 @@# API surface — esengine/wechat<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 115 public · 109 beta · 1593 experimental · 3 deprecated+Symbols: 115 public · 109 beta · 1611 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -299,6 +299,11 @@ Start = 1Stretch = 4```+## AmbientSkip — type @experimental+```+'hidden' | 'disabled' | 'no-intensity'+```+## Ambiguity — interface @experimental```a: string@@ -2695,6 +2700,11 @@ EditorGridDataEditorViewData```+## DEFAULT_EDITOR_VIEW_LIGHTING — const @experimental+```+EditorViewLightingData+```+## DEFAULT_FACING_COSINE — const @experimental```0.2@@ -3343,6 +3353,11 @@ tabIndex: number | undefinedworld: World```+## EDITOR_EXPOSURE_RANGE — const @experimental+```+{ readonly min: -6; readonly max: 6; }+```+## EDITOR_UI_ANCHOR — const @experimental```{ readonly x: 0; readonly y: 0; }@@ -3413,6 +3428,11 @@ majorEvery: numberspacing: number```+## EditorLightingMode — type @experimental+```+'scene' | 'studio'+```+## EditorView — const @experimental```ResourceDef<EditorViewData>@@ -3440,6 +3460,22 @@ yaw: numberz: number```+## EditorViewLighting — const @experimental+```+ResourceDef<EditorViewLightingData>+```++## EditorViewLightingData — interface @experimental+```+exposure: number+fillIntensity: number+keyIntensity: number+mode: EditorLightingMode+rotation: number+showSky: boolean+skyIntensity: number+```+## EditorWorkPlane — interface @experimental```normal: WorldAxis@@ -3584,6 +3620,14 @@ pickable: ((entity: Entity) => boolean) | undefinedySortLayers: number | undefined```+## EnvironmentLightEntity — interface @experimental+```+components: readonly { type: string; data: Record<string, unknown>; }[]+id: number+name: string+visible: boolean | undefined+```+## EventBinding — const @experimental```ComponentDef<EventBindingData>@@ -7377,6 +7421,18 @@ setJSON: <T>(key: string, value: T) => void(typeof ScaleMode)[keyof typeof ScaleMode]```+## SceneAmbientLight — interface @experimental+```+drawEnvironment: boolean+entityId: number+environment: string | null+environmentMissing: boolean+intensity: number+name: string+rotation: number+skipped: AmbientSkip | null+```+## SceneAssetRefs — interface @experimental```byType: Map<string, Set<string>>@@ -7430,6 +7486,11 @@ trackAssets: (byType: ReadonlyMap<string, ReadonlySet<string>>) => voidunbindPostProcess: (camera: Entity) => void```+## SceneDark — type @experimental+```+'no-lights' | 'no-enabled-light'+```+## SceneData — interface @experimental```entities: SceneEntityData[]@@ -7923,6 +7984,11 @@ vertices: Uint8Array<ArrayBufferLike>| { kind: 'sh'; irradiance: readonly number[]; yaw: number; tint: readonly [number, number, number] }```+## SkyUnavailable — type @experimental+```+'no-ambient' | 'no-environment' | 'missing' | 'off' | 'unusable'+```+## SliceBorder — interface @experimental```bottom: number@@ -8533,6 +8599,14 @@ ComponentDef<StreamedWorldData>cellSize: number```+## StudioPreviewReport — interface @experimental+```+environment: SceneAmbientLight | null+sceneDark: SceneDark | null+sceneLights: number+skyUnavailable: SkyUnavailable | null+```+## SubEmitterTrigger — enum @beta```Birth = 1@@ -10852,6 +10926,11 @@ MotionDriver<AnimatorBlend2DMotion>(at: readonly [number, number, number], bvh: Bvh, lookup: HitLookup, atlas: Float32Array, atlasSize: number, width: number, height: number, sky: SkyRadiance): CapturedPanorama```+## carriesEnvironment — function @experimental+```+(light: SceneAmbientLight): boolean+```+## catalogFromManifest — function @experimental```(manifest: AddressableManifest): Catalog | undefined@@ -11392,6 +11471,16 @@ DragPlugin(view: EditorViewData): boolean```+## editorViewLightingArgs — function @experimental+```+(data: EditorViewLightingData, viewActive: boolean): { mode: number; rotation: number; key: number; fill: number; sky: number; showSky: boolean; exposure: number; }+```++## editorViewLightingIsOverriding — function @experimental+```+(data: EditorViewLightingData): boolean+```+## editorViewStandoff — function @experimental```(view: EditorViewData): number@@ -12802,6 +12891,11 @@ PrefabsPlugin(): CppResourceManager```+## resetEditorViewLighting — function @experimental+```+(data: EditorViewLightingData): EditorViewLightingData+```+## resetWorldTo — function @experimental```(world: World, sceneData: SceneData): Map<number, Entity>@@ -12892,6 +12986,16 @@ SafeAreaPlugin{ readonly clamp: (x: number, min: number, max: number) => number; readonly clamp01: (x: number) => number; readonly lerp: (a: number, b: number, t: number) => number; readonly inverseLerp: (a: number, b: number, value: number) => number; readonly remap: (value: number, inMin: number, inMax: number, outMin: number, outMax: number) => number; readonly deg2rad: (deg: number) => number; readonly rad2deg: (rad: number) => number; readonly approximately: (a: number, b: number, epsilon?: number) => boolean; readonly smoothstep: (edge0: number, edge1: number, x: number) => number; readonly mod: (x: number, n: number) => number; readonly sign: (x: number) => number; }```+## sceneAmbientLights — function @experimental+```+(entities: readonly EnvironmentLightEntity[], exists: (ref: string) => boolean): SceneAmbientLight[]+```++## sceneEnvironment — function @experimental+```+(lights: readonly SceneAmbientLight[]): { effective: SceneAmbientLight | null; shadowed: SceneAmbientLight[]; }+```+## sceneManagerPlugin — const @experimental```Plugin@@ -13277,6 +13381,11 @@ StatsPlugin(world: World, entity: Entity): void```+## studioPreviewReport — function @experimental+```+(entities: readonly EnvironmentLightEntity[], exists: (ref: string) => boolean): StudioPreviewReport+```+## summarizeCapture — function @experimental```(capture: ProfileCapture): CaptureSummarydiff --git a/sdk/src/camera/CameraPlugin.ts b/sdk/src/camera/CameraPlugin.tsindex ed016af34..631b82c95 100644--- a/sdk/src/camera/CameraPlugin.ts+++ b/sdk/src/camera/CameraPlugin.ts@@ -22,6 +22,7 @@ import { ScreenOverlay } from '../ui/core/screen-overlay';import { ProjectionType, SceneOwner, ClearFlags } from '../ecs/component';import { canvasRootEntities } from '../ui/core/canvas-roots';import { uiLayoutRect, computeEffectiveOrthoSize, EDITOR_VIEW_ENTITY, type CanvasScale } from './uiLayoutRect';+import { EditorViewLighting, DEFAULT_EDITOR_VIEW_LIGHTING, pushEditorViewLighting } from './EditorViewLighting';import { EditorView, DEFAULT_EDITOR_VIEW, editorViewStandoff, editorViewClipFar, editorViewClipNear, type EditorViewData } from './EditorView';import { ScreenScaling, DEFAULT_SCREEN_SCALING, SCREEN_FIT_OFF } from './ScreenScaling';import { planPresent, viewportPixels, RenderResolution } from './presentPlan';@@ -782,6 +783,9 @@ export function cameraPlugin(// The editor view is inactive by default — shipped games never touch// it; the editor activates it in edit mode (see desktop EngineHost).app.insertResource(EditorView, { ...DEFAULT_EDITOR_VIEW });+ // Its lighting is the view's too: untouched, the scene renders by its own.+ app.insertResource(EditorViewLighting, { ...DEFAULT_EDITOR_VIEW_LIGHTING });+ let lastViewLighting = '';// The camera director: by default it just tracks the active camera;// games call setViewTarget(app, entity, {time, curve}) to blend, or// shakeCamera(app, {...}) to shake. Fresh state (own arrays) per App.@@ -845,6 +849,12 @@ export function cameraPlugin(// Transforms resolve BEFORE any camera is read — a view is built// from Transform.worldPosition, and a pass behind the read hands// back the previous frame's placement. beginFrame clears the memo.+ // The editor view's lighting reaches the engine only while that view is+ // the one drawing; play mode and shipped games push the neutral state.+ lastViewLighting = pushEditorViewLighting(+ module, app.getResource(EditorViewLighting),+ app.hasResource(EditorView) && app.getResource(EditorView).active,+ lastViewLighting);pipeline.beginFrame(elapsed);app.measureFrameScope('render.updateTransforms', () =>Renderer.updateTransforms({ _cpp: cppRegistry }));diff --git a/sdk/src/camera/EditorViewLighting.ts b/sdk/src/camera/EditorViewLighting.tsnew file mode 100644index 000000000..d0c84f1f8--- /dev/null+++ b/sdk/src/camera/EditorViewLighting.ts@@ -0,0 +1,159 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file EditorViewLighting.ts+ * @brief The editor viewport's own lighting and exposure — view state, like EditorView.+ *+ * @details "Scene lighting" shows the scene by the lights it carries. "Studio preview"+ * replaces them, for the eye only, with a neutral sky, a key and a fill, so a+ * model the scene left dark can be read while it is authored. The exposure is+ * a second, independent control: a stop count applied where the frame is+ * written out, the same exp2(EV) the post-process exposure uses.+ *+ * None of it is a scene entity, none of it is serialized, and it reaches the+ * engine only while the editor view is active — a packaged build never inserts+ * the view, never calls the engine setters, and so renders by the scene's own+ * settings. Play mode deactivates the view and with it every override here.+ */+import { defineResource } from '../ecs/resource';+import type { ESEngineModule } from '../wasm';+import { COMPONENT_META } from '../lightmap/metaAccess';+import { LightType } from '../wasm/wasm.generated';+import {+ sceneAmbientLights, sceneEnvironment, carriesEnvironment,+ type EnvironmentLightEntity, type SceneAmbientLight,+} from '../lightmap/environmentLight';++export type EditorLightingMode = 'scene' | 'studio';++export interface EditorViewLightingData {+ mode: EditorLightingMode;+ /** Degrees about +Y that the key and the fill turn together. */+ rotation: number;+ keyIntensity: number;+ fillIntensity: number;+ /** Scales the neutral sky. Never the scene's Ambient: that light is not consulted. */+ skyIntensity: number;+ /** Draw the scene's environment as the background while studio-lit. */+ showSky: boolean;+ /** Preview exposure in stops, independent of the mode. 0 is exact identity. */+ exposure: number;+}++export const DEFAULT_EDITOR_VIEW_LIGHTING: EditorViewLightingData = {+ mode: 'scene', rotation: 0, keyIntensity: 0.8, fillIntensity: 0.3,+ skyIntensity: 1, showSky: false, exposure: 0,+};++export const EDITOR_EXPOSURE_RANGE = { min: -6, max: 6 } as const;++export const EditorViewLighting = defineResource<EditorViewLightingData>(+ { ...DEFAULT_EDITOR_VIEW_LIGHTING }, 'EditorViewLighting');++/** True when the view differs from the game's own settings in any way. */+export function editorViewLightingIsOverriding(data: EditorViewLightingData): boolean {+ return data.mode === 'studio' || data.exposure !== 0;+}++/** The game's own settings: studio off and exposure at zero. The rig's tuning is kept. */+export function resetEditorViewLighting(data: EditorViewLightingData): EditorViewLightingData {+ return { ...data, mode: 'scene', exposure: 0 };+}++/** The numbers the engine setters take, so the push and its tests share one reading. */+export function editorViewLightingArgs(data: EditorViewLightingData, viewActive: boolean): {+ mode: number; rotation: number; key: number; fill: number; sky: number; showSky: boolean; exposure: number;+} {+ // An inactive view (play mode, a packaged build) carries no override at all.+ if (!viewActive) return { mode: 0, rotation: 0, key: 0, fill: 0, sky: 1, showSky: false, exposure: 0 };+ const finite = (v: number, fallback: number) => (Number.isFinite(v) ? v : fallback);+ return {+ mode: data.mode === 'studio' ? 1 : 0,+ rotation: finite(data.rotation, 0),+ key: Math.max(0, finite(data.keyIntensity, 0)),+ fill: Math.max(0, finite(data.fillIntensity, 0)),+ sky: Math.max(0, finite(data.skyIntensity, 1)),+ showSky: data.showSky,+ exposure: Math.min(EDITOR_EXPOSURE_RANGE.max, Math.max(EDITOR_EXPOSURE_RANGE.min, finite(data.exposure, 0))),+ };+}++/**+ * Pushes the view's lighting to the engine, once per change. Returns the key it last+ * pushed, so a caller skips the crossing while nothing moved.+ */+export function pushEditorViewLighting(+ module: ESEngineModule | null,+ data: EditorViewLightingData,+ viewActive: boolean,+ lastKey: string,+): string {+ const a = editorViewLightingArgs(data, viewActive);+ const key = `${a.mode}|${a.rotation}|${a.key}|${a.fill}|${a.sky}|${a.showSky}|${a.exposure}`;+ // A module that does not carry the setters (an older core) is simply not+ // overridden; the key still advances so it is not asked every frame.+ if (key === lastKey || !module) return lastKey;+ module.renderer_setViewLighting?.(a.mode, a.rotation, a.key, a.fill, a.sky, a.showSky);+ module.postprocess_setViewExposure?.(a.exposure);+ return key;+}++export type SkyUnavailable = 'no-ambient' | 'no-environment' | 'missing' | 'off' | 'unusable';+export type SceneDark = 'no-lights' | 'no-enabled-light';++/** What a scene gives the studio preview to say about itself. */+export interface StudioPreviewReport {+ /** Non-Ambient lights that are visible, enabled and have intensity. */+ sceneLights: number;+ /** The environment the scene's own frame would use, or null. */+ environment: SceneAmbientLight | null;+ /** Why there is no environment to show as a sky, or null when there is one. */+ skyUnavailable: SkyUnavailable | null;+ /** Why the scene alone would read dark, or null when it has light. */+ sceneDark: SceneDark | null;+}++/**+ * The actual reasons, read from the scene document: nothing here guesses at what the+ * engine did. The Lighting panel uses it to say why a toggle is disabled or why the+ * scene looks dark without the studio.+ */+export function studioPreviewReport(+ entities: readonly EnvironmentLightEntity[],+ exists: (ref: string) => boolean,+): StudioPreviewReport {+ const meta = COMPONENT_META['Light'];+ const defaults = {+ ...(meta?.defaults as Record<string, unknown> | undefined),+ ...(meta?.editorDefaults as Record<string, unknown> | undefined),+ };+ let lit = 0;+ let anyLight = 0;+ for (const entity of entities) {+ for (const c of entity.components) {+ if (c.type !== 'Light') continue;+ anyLight++;+ const type = (c.data.type ?? defaults.type ?? 0) as number;+ if (type === LightType.Ambient) continue;+ const enabled = (c.data.enabled ?? defaults.enabled ?? true) !== false;+ const intensity = (c.data.intensity ?? defaults.intensity ?? 1) as number;+ if (entity.visible !== false && enabled && intensity > 0) lit++;+ }+ }+ const ambient = sceneAmbientLights(entities, exists);+ const { effective } = sceneEnvironment(ambient);+ const named = ambient.filter((l) => l.environment !== null);++ let skyUnavailable: SkyUnavailable | null = null;+ if (!effective) {+ if (ambient.length === 0) skyUnavailable = 'no-ambient';+ else if (named.length === 0) skyUnavailable = 'no-environment';+ else if (named.every((l) => l.environmentMissing)) skyUnavailable = 'missing';+ else if (named.some((l) => l.skipped !== null && !carriesEnvironment(l))) skyUnavailable = 'off';+ else skyUnavailable = 'unusable';+ }++ let sceneDark: SceneDark | null = null;+ if (lit === 0 && !effective) sceneDark = anyLight === 0 ? 'no-lights' : 'no-enabled-light';+ return { sceneLights: lit, environment: effective, skyUnavailable, sceneDark };+}diff --git a/sdk/src/core-render.ts b/sdk/src/core-render.tsindex b85769f2b..804de1435 100644--- a/sdk/src/core-render.ts+++ b/sdk/src/core-render.ts@@ -46,6 +46,8 @@ export { CameraCommit, onCameraCommitChanged, cameraCommitChanged,type CameraCommitData, type CameraCommitListener } from './camera/CameraCommit';export { EditorView, DEFAULT_EDITOR_VIEW, editorViewHalfHeight, editorViewHalfExtent, editorViewWorldPerPixel, setEditorViewHalfHeight, editorViewIsOrbited, editorViewAxes, editorViewAxisAngles, editorViewBasis, editorViewEye, editorViewStandoff, editorViewClipFar, editorViewClipNear, editorViewWorkPlane, editorViewGridPlane, screenWorkAxes, worldAxisVector, moveEditorViewFocus, editorViewBoxExtent } from './camera/EditorView';export type { EditorViewData, ScreenAxis, EditorViewBasis, EditorWorkPlane, WorldAxis } from './camera/EditorView';+export { EditorViewLighting, DEFAULT_EDITOR_VIEW_LIGHTING, EDITOR_EXPOSURE_RANGE, editorViewLightingIsOverriding, resetEditorViewLighting, editorViewLightingArgs, studioPreviewReport } from './camera/EditorViewLighting';+export type { EditorViewLightingData, EditorLightingMode, StudioPreviewReport, SkyUnavailable, SceneDark } from './camera/EditorViewLighting';export { ScreenScaling, DEFAULT_SCREEN_SCALING, SCREEN_FIT_OFF } from './camera/ScreenScaling';export type { ScreenScalingData } from './camera/ScreenScaling';export { EditorGrid, DEFAULT_EDITOR_GRID } from './camera/EditorGrid';diff --git a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts b/sdk/src/ecs/bridge/nativeEngineApi.generated.tsindex 1683a0dc7..578580b63 100644--- a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts+++ b/sdk/src/ecs/bridge/nativeEngineApi.generated.ts@@ -119,6 +119,7 @@ export interface NativeEngineApi {postprocess_setScreenUniformVec4?(passName: string, uniform: string, x: number, y: number, z: number, w: number): void;postprocess_setUniformFloat?(passName: string, uniform: string, value: number): void;postprocess_setUniformVec4?(passName: string, uniform: string, x: number, y: number, z: number, w: number): void;+ postprocess_setViewExposure?(ev: number): void;postprocess_shutdown?(): void;probe_volume_create?(resX: number, resY: number, resZ: number, shPtr: number): number;probe_volume_release?(volumeHandle: number): void;@@ -202,6 +203,7 @@ export interface NativeEngineApi {renderer_setStage?(stage: number): void;renderer_setTextureParams?(textureId: number, minFilter: number, magFilter: number, wrapS: number, wrapT: number): void;renderer_setViewId?(view: number): void;+ renderer_setViewLighting?(mode: number, rotationDegrees: number, keyIntensity: number, fillIntensity: number, skyIntensity: number, showSky: boolean): void;renderer_setViewport?(x: number, y: number, w: number, h: number): void;renderer_setYSortLayers?(mask: number): void;renderer_shadowStatus?(entity: number, outPtr: number): number;@@ -417,6 +419,7 @@ export function createNativeEngineApi(bind('postprocess_setScreenUniformVec4', 'es_postprocess_setScreenUniformVec4', false);bind('postprocess_setUniformFloat', 'es_postprocess_setUniformFloat', false);bind('postprocess_setUniformVec4', 'es_postprocess_setUniformVec4', false);+ bind('postprocess_setViewExposure', 'es_postprocess_setViewExposure', false);bind('postprocess_shutdown', 'es_postprocess_shutdown', false);bind('probe_volume_create', 'es_probe_volume_create', false);bind('probe_volume_release', 'es_probe_volume_release', false);@@ -500,6 +503,7 @@ export function createNativeEngineApi(bind('renderer_setStage', 'es_renderer_setStage', false);bind('renderer_setTextureParams', 'es_renderer_setTextureParams', false);bind('renderer_setViewId', 'es_renderer_setViewId', false);+ bind('renderer_setViewLighting', 'es_renderer_setViewLighting', false);bind('renderer_setViewport', 'es_renderer_setViewport', false);bind('renderer_setYSortLayers', 'es_renderer_setYSortLayers', false);bind('renderer_shadowStatus', 'es_renderer_shadowStatus', false);diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.tsindex 3006fb050..7fb258ff7 100644--- a/sdk/src/wasm.ts+++ b/sdk/src/wasm.ts@@ -539,6 +539,7 @@ export interface ESEngineModule {/** The curve the chain applies on the way out: 0 = none, 1 = ACES filmic.* Absent on an engine built before the output transform existed. */postprocess_setOutputTransform?(transform: number): void;+ postprocess_setViewExposure?(ev: number): void;postprocess_clearPasses(): void;postprocess_setOutputViewport(x: number, y: number, w: number, h: number): void;/** Say a present is needed when the rects cannot: see PostProcessPipeline. */@@ -666,6 +667,7 @@ export interface ESEngineModule {renderer_setQualityBudgets?(atlasSize: number, cellSize: number,cascades: number, particleLimit: number): void;renderer_setShadowDistance?(distance: number): void;+ renderer_setViewLighting?(mode: number, rotationDegrees: number, keyIntensity: number, fillIntensity: number, skyIntensity: number, showSky: boolean): void;renderer_setCullingMask?(mask: number): void;renderer_setViewId?(view: number): void;renderer_lodInspect?(view: number, entity: number, outPtr: number): number;diff --git a/sdk/tests/editor-view-lighting.test.ts b/sdk/tests/editor-view-lighting.test.tsnew file mode 100644index 000000000..1ab595d38--- /dev/null+++ b/sdk/tests/editor-view-lighting.test.ts@@ -0,0 +1,91 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * The editor view's lighting is VIEW state: it reaches the engine only while the editor eye+ * is the one drawing, it never carries a value the engine cannot take, and the scene's+ * own reasons for being dark are read from the document, not guessed.+ */+import { describe, it, expect } from 'vitest';+import {+ DEFAULT_EDITOR_VIEW_LIGHTING, EDITOR_EXPOSURE_RANGE, editorViewLightingArgs,+ editorViewLightingIsOverriding, resetEditorViewLighting, studioPreviewReport,+} from '../src/camera/EditorViewLighting';+import { pushEditorViewLighting } from '../src/camera/EditorViewLighting';+import type { EnvironmentLightEntity } from '../src/lightmap';++const studio = { ...DEFAULT_EDITOR_VIEW_LIGHTING, mode: 'studio' as const, exposure: 1.5, rotation: 30 };++describe('what reaches the engine', () => {+ it('is the neutral state whenever the editor eye is not drawing', () => {+ expect(editorViewLightingArgs(studio, false)).toEqual({+ mode: 0, rotation: 0, key: 0, fill: 0, sky: 1, showSky: false, exposure: 0,+ });+ });++ it('is the studio rig while it is, with every number made safe', () => {+ const a = editorViewLightingArgs({ ...studio, keyIntensity: -3, fillIntensity: Number.NaN, exposure: 40 }, true);+ expect(a.mode).toBe(1);+ expect(a.rotation).toBe(30);+ expect(a.key).toBe(0);+ expect(a.fill).toBe(0);+ expect(a.exposure).toBe(EDITOR_EXPOSURE_RANGE.max);+ });++ it('crosses into the engine once per change, and leaves the old core alone', () => {+ const calls: unknown[][] = [];+ const module = {+ renderer_setViewLighting: (...a: unknown[]) => calls.push(['light', ...a]),+ postprocess_setViewExposure: (...a: unknown[]) => calls.push(['ev', ...a]),+ } as never;+ let key = '';+ key = pushEditorViewLighting(module, studio, true, key);+ key = pushEditorViewLighting(module, studio, true, key);+ expect(calls).toHaveLength(2);+ // Play mode deactivates the eye: the very next frame is the game's own.+ key = pushEditorViewLighting(module, studio, false, key);+ expect(calls.slice(2)).toEqual([['light', 0, 0, 0, 0, 1, false], ['ev', 0]]);+ expect(() => pushEditorViewLighting({} as never, studio, true, '')).not.toThrow();+ });+});++describe('returning to the game', () => {+ it('is studio off and exposure zero, and nothing else', () => {+ expect(editorViewLightingIsOverriding(DEFAULT_EDITOR_VIEW_LIGHTING)).toBe(false);+ expect(editorViewLightingIsOverriding(studio)).toBe(true);+ expect(editorViewLightingIsOverriding({ ...DEFAULT_EDITOR_VIEW_LIGHTING, exposure: -1 })).toBe(true);+ expect(resetEditorViewLighting(studio)).toEqual({ ...studio, mode: 'scene', exposure: 0 });+ });+});++let next = 1;+const light = (data: Record<string, unknown>, visible?: boolean): EnvironmentLightEntity =>+ ({ id: next++, name: `L${next}`, ...(visible === undefined ? {} : { visible }), components: [{ type: 'Light', data }] });+const all = (): boolean => true;++describe('why the scene is dark, from the document', () => {+ it('says a scene with no lights has none', () => {+ const r = studioPreviewReport([], all);+ expect(r.sceneDark).toBe('no-lights');+ expect(r.skyUnavailable).toBe('no-ambient');+ });++ it('is not dark when a light shines, and says so only about what is missing', () => {+ const r = studioPreviewReport([light({ type: 1 })], all);+ expect(r.sceneLights).toBe(1);+ expect(r.sceneDark).toBeNull();+ expect(r.skyUnavailable).toBe('no-ambient');+ });++ it('names a disabled light as no light', () => {+ expect(studioPreviewReport([light({ type: 1, enabled: false })], all).sceneDark).toBe('no-enabled-light');+ });++ it('tells apart an Ambient that names nothing, one that names a missing file, and a usable one', () => {+ expect(studioPreviewReport([light({ type: 2 })], all).skyUnavailable).toBe('no-environment');+ expect(studioPreviewReport([light({ type: 2, environment: 'a.esenv' })], () => false).skyUnavailable).toBe('missing');+ const ok = studioPreviewReport([light({ type: 2, environment: 'a.esenv' })], all);+ expect(ok.skyUnavailable).toBeNull();+ expect(ok.environment).not.toBeNull();+ expect(ok.sceneDark).toBeNull();+ });+});diff --git a/src/esengine/bindings/PostProcessBindings.cpp b/src/esengine/bindings/PostProcessBindings.cppindex c0be6e594..b5952a264 100644--- a/src/esengine/bindings/PostProcessBindings.cpp+++ b/src/esengine/bindings/PostProcessBindings.cpp@@ -172,6 +172,10 @@ void postprocess_setOutputTransform(u32 transform) {: OutputTransform::None);}+void postprocess_setViewExposure(f32 ev) {+ if (g_postProcessPipeline) g_postProcessPipeline->setViewExposure(ev);+}+void postprocess_clearPasses() {if (g_postProcessPipeline) {g_postProcessPipeline->clearPasses();diff --git a/src/esengine/bindings/PostProcessBindings.hpp b/src/esengine/bindings/PostProcessBindings.hppindex da2b2db76..658e24528 100644--- a/src/esengine/bindings/PostProcessBindings.hpp+++ b/src/esengine/bindings/PostProcessBindings.hpp@@ -52,6 +52,8 @@ bool postprocess_isInitialized();void postprocess_setBypass(bool bypass);/** The curve the chain applies on the way out: 0 = none, 1 = ACES filmic. */void postprocess_setOutputTransform(u32 transform);+/** The editor view's exposure in stops (EV); 0 is exact identity. View state, never saved. */+void postprocess_setViewExposure(f32 ev);void postprocess_clearPasses();void postprocess_setOutputViewport(u32 x, u32 y, u32 w, u32 h);/** Say the frame needs a present even when the two rects look alike; seediff --git a/src/esengine/bindings/RendererBindings.cpp b/src/esengine/bindings/RendererBindings.cppindex b584ea88d..ec304be16 100644--- a/src/esengine/bindings/RendererBindings.cpp+++ b/src/esengine/bindings/RendererBindings.cpp@@ -1,6 +1,7 @@// SPDX-License-Identifier: Apache-2.0// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+#include <cmath>#include "RendererBindings.hpp"#include "TestProbeBindings.hpp"@@ -1039,6 +1040,19 @@ void renderer_setDepthLayers(u32 mask) {if (auto* frame = g_renderFrame) frame->setDepthLayers(mask);}+void renderer_setViewLighting(u32 mode, f32 rotationDegrees, f32 keyIntensity, f32 fillIntensity,+ f32 skyIntensity, bool showSky) {+ if (!g_renderFrame) return;+ RenderFrame::ViewLighting lighting;+ lighting.studio = mode == 1;+ lighting.rotation = std::isfinite(rotationDegrees) ? rotationDegrees : 0.0f;+ lighting.keyIntensity = std::isfinite(keyIntensity) ? std::max(keyIntensity, 0.0f) : 0.0f;+ lighting.fillIntensity = std::isfinite(fillIntensity) ? std::max(fillIntensity, 0.0f) : 0.0f;+ lighting.skyIntensity = std::isfinite(skyIntensity) ? std::max(skyIntensity, 0.0f) : 0.0f;+ lighting.showSky = showSky;+ g_renderFrame->setViewLighting(lighting);+}+void renderer_setShadowDistance(f32 distance) {if (g_renderFrame) g_renderFrame->setShadowDistance(distance);}diff --git a/src/esengine/bindings/RendererBindings.hpp b/src/esengine/bindings/RendererBindings.hppindex 03451e0e5..3789ac0d6 100644--- a/src/esengine/bindings/RendererBindings.hpp+++ b/src/esengine/bindings/RendererBindings.hpp@@ -26,6 +26,13 @@ void renderer_init(u32 width, u32 height);void renderer_resize(u32 width, u32 height);void renderer_setQualityBudgets(u32 atlasSize, u32 cellSize, u32 cascades, u32 particleLimit);void renderer_setShadowDistance(f32 distance);+/**+ * The editor view's lighting. mode 0 = the scene's own lights (the default, and the+ * only one a packaged build ever has); 1 = studio: a neutral sky, a key and a fill, in+ * their place. View state — nothing here is saved with a scene.+ */+void renderer_setViewLighting(u32 mode, f32 rotationDegrees, f32 keyIntensity, f32 fillIntensity,+ f32 skyIntensity, bool showSky);void renderer_beginFrame(f32 elapsedSec);void renderer_begin(uintptr_t matrixPtr, u32 targetHandle, i32 clearFlags,f32 r, f32 g, f32 b, f32 a,diff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cppindex 63b3fff1c..9f60f63d0 100644--- a/src/esengine/bindings/WebSDKEntry.cpp+++ b/src/esengine/bindings/WebSDKEntry.cpp@@ -611,6 +611,7 @@ EMSCRIPTEN_BINDINGS(esengine_renderer) {emscripten::function("postprocess_isInitialized", &esengine::postprocess_isInitialized);emscripten::function("postprocess_setBypass", &esengine::postprocess_setBypass);emscripten::function("postprocess_setOutputTransform", &esengine::postprocess_setOutputTransform);+ emscripten::function("postprocess_setViewExposure", &esengine::postprocess_setViewExposure);emscripten::function("postprocess_clearPasses", &esengine::postprocess_clearPasses);emscripten::function("postprocess_setOutputViewport", &esengine::postprocess_setOutputViewport);emscripten::function("postprocess_setPresentRequired", &esengine::postprocess_setPresentRequired);@@ -766,6 +767,7 @@ EMSCRIPTEN_BINDINGS(esengine_renderer) {emscripten::function("renderer_setDepthLayers", &esengine::renderer_setDepthLayers);emscripten::function("renderer_setQualityBudgets", &esengine::renderer_setQualityBudgets);emscripten::function("renderer_setShadowDistance", &esengine::renderer_setShadowDistance);+ emscripten::function("renderer_setViewLighting", &esengine::renderer_setViewLighting);emscripten::function("renderer_setCullingMask", &esengine::renderer_setCullingMask);emscripten::function("renderer_setViewId", &esengine::renderer_setViewId);emscripten::function("renderer_lodInspect", &esengine::renderer_lodInspect);diff --git a/src/esengine/data/shaders/blit.esshader b/src/esengine/data/shaders/blit.esshaderindex a26355d87..96244e3b7 100644--- a/src/esengine/data/shaders/blit.esshader+++ b/src/esengine/data/shaders/blit.esshader@@ -11,6 +11,9 @@ out vec4 fragColor;void main() {vec4 c = texture(u_texture, v_texCoord);+ // The editor view's exposure (u_time.z, stops): zero outside the editor, where+ // exp2(0) = 1 leaves every pixel as it was. Before the curve, like any exposure.+ c = vec4(c.rgb * exp2(u_time.z), c.a);#ifdef ES_TONEMAP// The output transform: scene radiance can exceed 1.0 on an HDR target,// and this is the one place a chain maps it down. Before the OETF, which@@ -30,6 +33,7 @@ void main() {#pragma fragment wgsl@fragment fn fs_main(v : VSOut) -> @location(0) vec4f {var c = textureSampleLevel(t0, s0, v.v_texCoord, 0.0);+ c = vec4f(c.rgb * exp2(tc.u_time.z), c.a);#ifdef ES_TONEMAPc = vec4f(acesFilmic(c.rgb), c.a);#endifdiff --git a/src/esengine/renderer/frame/FrameConstants.hpp b/src/esengine/renderer/frame/FrameConstants.hppindex e515fb26b..75990e347 100644--- a/src/esengine/renderer/frame/FrameConstants.hpp+++ b/src/esengine/renderer/frame/FrameConstants.hpp@@ -85,7 +85,7 @@ inline constexpr const char* FRAME_CONSTANTS_BLOCK = "FrameConstants";/*** @brief CPU mirror of the injected TimeConstants block (std140).- * @details u_time = (elapsed s, delta s, 0, 0); u_viewport = (w, h, 1/w, 1/h) of the+ * @details u_time = (elapsed s, delta s, view exposure EV, 0); u_viewport = (w, h, 1/w, 1/h) of the* canvas in pixels. Engine-owned: ShaderParser injects the block into every* assembled stage — shaders never declare it.*/diff --git a/src/esengine/renderer/frame/PostProcessPipeline.cpp b/src/esengine/renderer/frame/PostProcessPipeline.cppindex 701dc976e..2a37b89cd 100644--- a/src/esengine/renderer/frame/PostProcessPipeline.cpp+++ b/src/esengine/renderer/frame/PostProcessPipeline.cpp@@ -21,6 +21,7 @@#include "../../resource/ShaderParser.hpp"#include "../../core/Log.hpp"#include <algorithm>+#include <cmath>#include <cstring>#include "../rhi/GfxEnums.hpp"@@ -85,6 +86,11 @@ resource::ShaderHandle PostProcessPipeline::compileBlit(const std::vector<std::sresourceManager_.preferredShaderLanguage());}+void PostProcessPipeline::setViewExposure(f32 ev) {+ view_exposure_ = std::isfinite(ev) ? std::clamp(ev, -10.0f, 10.0f) : 0.0f;+ context_.setViewExposure(view_exposure_);+}+/*** The blit the current output transform needs. Compiled on first use rather* than at init: a project that never asks for a curve never pays for one.diff --git a/src/esengine/renderer/frame/PostProcessPipeline.hpp b/src/esengine/renderer/frame/PostProcessPipeline.hppindex 3ddae63af..311e38d37 100644--- a/src/esengine/renderer/frame/PostProcessPipeline.hpp+++ b/src/esengine/renderer/frame/PostProcessPipeline.hpp@@ -220,6 +220,7 @@ public:// to drawing straight at the surface rather than to a black frame.return initialized_ && ((!bypass_ && !passes_.empty()) || linear_output_|| output_transform_ != OutputTransform::None+ || view_exposure_ != 0.0f|| presentScales() || present_required_);}@@ -306,6 +307,9 @@ public:* than a pass of its own.*/void setOutputTransform(OutputTransform transform) { output_transform_ = transform; }+ /// The editor view's exposure in stops, applied by the blit. Engages the blit when+ /// non-zero, since only the blit carries it; the value rides the frame's time block.+ void setViewExposure(f32 ev);OutputTransform outputTransform() const { return output_transform_; }/**@@ -436,6 +440,7 @@ private:u32 scene_samples_ = 1;void applySampleRequest();OutputTransform output_transform_ = OutputTransform::None;+ f32 view_exposure_ = 0.0f;/// The graph resource the scene is drawn into, live between begin() and end().rg::ResourceId sceneResource_ = rg::kNoResource;TextureHandle sceneTexture_ = TextureHandle::Invalid;diff --git a/src/esengine/renderer/frame/RenderContext.cpp b/src/esengine/renderer/frame/RenderContext.cppindex 1737ec2bd..c18d66d7b 100644--- a/src/esengine/renderer/frame/RenderContext.cpp+++ b/src/esengine/renderer/frame/RenderContext.cpp@@ -207,7 +207,7 @@ void RenderContext::setFrameTime(f32 elapsedSec, u32 viewportW, u32 viewportH) {const f32 w = static_cast<f32>(viewportW);const f32 h = static_cast<f32>(viewportH);TimeConstants time{- glm::vec4(elapsedSec, dt, 0.0f, 0.0f),+ glm::vec4(elapsedSec, dt, viewExposure_, 0.0f),glm::vec4(w, h, w > 0.0f ? 1.0f / w : 0.0f, h > 0.0f ? 1.0f / h : 0.0f),};device_.updateBuffer(timeUbo_, 0, &time, sizeof(TimeConstants));diff --git a/src/esengine/renderer/frame/RenderContext.hpp b/src/esengine/renderer/frame/RenderContext.hppindex c748e3f35..8db40e8d1 100644--- a/src/esengine/renderer/frame/RenderContext.hpp+++ b/src/esengine/renderer/frame/RenderContext.hpp@@ -174,6 +174,14 @@ public:/** @brief Uploads the frame clock + canvas size into the injected TimeConstants UBO. */void setFrameTime(f32 elapsedSec, u32 viewportW, u32 viewportH);+ /**+ * @brief The editor view's exposure, in stops, carried to the output blit in+ * u_time.z. VIEW state: zero (the default, and every packaged build) is+ * exp2(0) = 1, an exact no-op.+ */+ void setViewExposure(f32 ev) { viewExposure_ = ev; }+ f32 viewExposure() const { return viewExposure_; }+/*** @brief The engine-side material registry (handle -> resolved render state).* @details Written by the SDK material binding (defineMaterial) and read by the render@@ -241,6 +249,7 @@ public:private:f32 lastElapsed_ = 0.0f;+ f32 viewExposure_ = 0.0f;MaterialStore materials_;LightStore lights_;ProbeStore probes_;diff --git a/src/esengine/renderer/frame/RenderFrame.cpp b/src/esengine/renderer/frame/RenderFrame.cppindex e83dc9186..a1f4237d4 100644--- a/src/esengine/renderer/frame/RenderFrame.cpp+++ b/src/esengine/renderer/frame/RenderFrame.cpp@@ -1236,6 +1236,12 @@ void RenderFrame::collectLights(ecs::Registry& registry) {environment_texture_id_ = 0;sky_texture_id_ = 0;draw_sky_ = false;+ scene_sky_available_ = false;++ if (view_lighting_.studio) {+ collectStudioLights(registry);+ return;+ }// The frame's environment is decided before any light is: a directional light// following its sun needs it, and whether one does decides which irradiance@@ -1417,6 +1423,82 @@ void RenderFrame::collectLights(ecs::Registry& registry) {collectShape2D(registry);}+/// The studio rig. A sky that is light from above and less from below, so a surface+/// reads by its facing even before a light touches it; the radiance is a + b*y, whose+/// cosine-convolved nine coefficients (already over pi, like an imported environment's)+/// are a/Y00 for the constant term and (2/3)*b/Y1 for the y one.+static void neutralSkyIrradiance(std::array<glm::vec3, 9>& sh) {+ constexpr f32 a = 0.45f;+ constexpr f32 b = 0.15f;+ sh.fill(glm::vec3(0.0f));+ sh[0] = glm::vec3(a / 0.282095f);+ sh[1] = glm::vec3((2.0f / 3.0f) * b / 0.488603f);+}++void RenderFrame::collectStudioLights(ecs::Registry& registry) {+ LightStore& lights = context_.lights();+ const ViewLighting& view = view_lighting_;++ // The scene's own environment, found by the same rule the scene frame uses, only+ // to be LOOKED AT: it never lights anything here.+ auto lightView = registry.activeView<ecs::Light>();+ for (auto entity : lightView) {+ const auto& light = lightView.get(entity);+ if (!light.enabled || light.intensity <= 0.0f) continue;+ if (static_cast<ecs::LightType>(light.type) != ecs::LightType::Ambient) continue;+ if (!light.environment.isValid()) continue;+ const Environment* environment = resource_manager_.getEnvironment(light.environment);+ if (!environment) continue;+ u32 textureId = 0;+ if (environment->hasSpecular()) {+ if (Texture* atlas = resource_manager_.getTexture(environment->specular)) {+ textureId = atlas->getId();+ }+ }+ u32 panorama = 0;+ if (environment->sky.isValid()) {+ if (Texture* sky = resource_manager_.getTexture(environment->sky)) panorama = sky->getId();+ }+ scene_sky_available_ = textureId != 0 || panorama != 0;+ if (view.showSky && scene_sky_available_) {+ environment_texture_id_ = textureId;+ sky_texture_id_ = panorama;+ draw_sky_ = true;+ }+ break;+ }++ std::array<glm::vec3, 9> sh;+ neutralSkyIrradiance(sh);+ // params.x = 0: no specular atlas, so the sky is a diffuse term only.+ lights.setEnvironment(sh.data(), glm::vec4(0.0f, 1.0f, 0.0f, 0.0f),+ glm::vec3(std::max(view.skyIntensity, 0.0f)), 0.0f);++ auto rig = [&](f32 azimuthDeg, f32 elevationDeg, f32 intensity) {+ if (intensity <= 0.0f) return;+ const f32 az = glm::radians(azimuthDeg + view.rotation);+ const f32 el = glm::radians(elevationDeg);+ // Toward the light; a directional light's aim is the way it travels.+ const glm::vec3 toLight(std::sin(az) * std::cos(el), std::sin(el), std::cos(az) * std::cos(el));+ const glm::vec3 aim = -toLight;+ GpuLight gpu;+ gpu.color = glm::vec4(1.0f, 1.0f, 1.0f, intensity);+ gpu.posDir = glm::vec4(aim.x, aim.y, 1.0f, aim.z);+ lights.addLight(gpu);+ ++light_cap_.accepted;+ };+ light_cap_.limit = MAX_LIGHTS;+ // Key from the upper left of a viewer standing on +z; the fill low on the far side.+ rig(-35.0f, 40.0f, view.keyIntensity);+ rig(145.0f, 15.0f, view.fillIntensity);+ light_cap_.requested = light_cap_.accepted;++ // Last, as in the scene path: the masks are a question about the array just filled,+ // and with none of the scene's lights in it they come back empty rather than stale.+ collectShadow2D(registry);+ collectShape2D(registry);+}+bool RenderFrame::collectEnvironment(const ecs::Light& light, const glm::vec3& scale,bool withoutSun) {if (!light.environment.isValid()) return false;diff --git a/src/esengine/renderer/frame/RenderFrame.hpp b/src/esengine/renderer/frame/RenderFrame.hppindex 5b33b2dff..77e2b0cec 100644--- a/src/esengine/renderer/frame/RenderFrame.hpp+++ b/src/esengine/renderer/frame/RenderFrame.hpp@@ -335,6 +335,33 @@ public:*/const LightCapReport& lightCap() const { return light_cap_; }+ /**+ * @brief The editor view's own lighting, in place of the scene's.+ *+ * @details VIEW state, not scene state: nothing here is a component, nothing is+ * saved, and a host that never calls the setter (every packaged build)+ * lights the scene by its own lights exactly as before. In studio mode+ * the frame ignores the scene's lights and lights with a neutral sky,+ * a key and a fill, so a model the scene left dark can be read. The+ * scene's environment may still be drawn as the BACKGROUND (`showSky`):+ * seeing the sky and being lit by it are separate questions.+ */+ struct ViewLighting {+ bool studio = false;+ /// Degrees about +Y that the key and fill turn together.+ f32 rotation = 0.0f;+ f32 keyIntensity = 0.8f;+ f32 fillIntensity = 0.3f;+ /// Scales the neutral sky's light; the scene's own Ambient is not consulted.+ f32 skyIntensity = 1.0f;+ /// Draw the scene's environment as the background while studio-lit.+ bool showSky = false;+ };+ void setViewLighting(const ViewLighting& lighting) { view_lighting_ = lighting; }+ const ViewLighting& viewLighting() const { return view_lighting_; }+ /// Whether the frame found a scene environment it could draw as the background.+ bool sceneSkyAvailable() const { return scene_sky_available_; }+/*** @brief Switch the frame to linear-light rendering (project colorSpace).* @details Sets the global ES_LINEAR shader input, linearizes CPU-side@@ -604,6 +631,8 @@ private:/// (point/directional into the light array, ambient summed). Run each frame in collectAll;/// flush() uploads + binds the result so Lit material shaders read it.void collectLights(ecs::Registry& registry);+ /// collectLights' studio branch: the view's neutral light in place of the scene's.+ void collectStudioLights(ecs::Registry& registry);/** @brief Gathers the frame's LightProbeVolume components into the ProbeStore. */void collectProbes(ecs::Registry& registry);@@ -882,6 +911,8 @@ private:f32 shadow_distance_ = 0.0f;ShadowPlanReport shadow_plan_;LightCapReport light_cap_;+ ViewLighting view_lighting_;+ bool scene_sky_available_ = false;/// The map's colour texture, handed to every mesh that receives it. 0 = none this frame.u32 shadow_texture_id_ = 0;/// The frame environment's reflection atlas, on the same terms. 0 = none this frame.diff --git a/src/esengine/renderer/rhi/ShaderEmbeds.generated.hpp b/src/esengine/renderer/rhi/ShaderEmbeds.generated.hppindex e8b228226..b381bd9d9 100644--- a/src/esengine/renderer/rhi/ShaderEmbeds.generated.hpp+++ b/src/esengine/renderer/rhi/ShaderEmbeds.generated.hpp@@ -251,6 +251,9 @@ out vec4 fragColor;void main() {vec4 c = texture(u_texture, v_texCoord);+++ c = vec4(c.rgb * exp2(u_time.z), c.a);#ifdef ES_TONEMAP@@ -270,6 +273,7 @@ void main() {#pragma fragment wgsl@fragment fn fs_main(v : VSOut) -> @location(0) vec4f {var c = textureSampleLevel(t0, s0, v.v_texCoord, 0.0);+ c = vec4f(c.rgb * exp2(tc.u_time.z), c.a);#ifdef ES_TONEMAPc = vec4f(acesFilmic(c.rgb), c.a);#endifdiff --git a/src/esengine/resource/ShaderParser.cpp b/src/esengine/resource/ShaderParser.cppindex 164bbd45a..982b5bbd6 100644--- a/src/esengine/resource/ShaderParser.cpp+++ b/src/esengine/resource/ShaderParser.cpp@@ -1793,7 +1793,7 @@ ShaderParser::AssembledStage ShaderParser::assembleStageEx(const ParsedShader& pheaderLines += countNewlines(kFrameHeader);// Engine-owned frame block, injected into every stage (identical in both, so the- // program links). u_time = (elapsed s, delta s, 0, 0); u_viewport = canvas+ // program links). u_time = (elapsed s, delta s, view exposure EV, 0); u_viewport = canvas// (w, h, 1/w, 1/h) in pixels; binding 3 (Shader::compile).static const char* kTimeHeader ="layout(std140) uniform TimeConstants { highp vec4 u_time; highp vec4 u_viewport; };\n";diff --git a/tools/check-render-scenes.mjs b/tools/check-render-scenes.mjsindex eaa6442a7..b854734b4 100644--- a/tools/check-render-scenes.mjs+++ b/tools/check-render-scenes.mjs@@ -44,7 +44,7 @@ for (const s of SCENES) {const asserts = s.env.ESTELLA_VERIFY_EXPECT || s.env.ESTELLA_VERIFY_COUNT|| s.env.ESTELLA_VERIFY_DEVICE_LOSS === 'roundtrip'|| s.env.ESTELLA_VERIFY_SEAM- || s.env.ESTELLA_VERIFY_GRID || s.env.ESTELLA_VERIFY_PREVIEW+ || s.env.ESTELLA_VERIFY_GRID || s.env.ESTELLA_VERIFY_STUDIO || s.env.ESTELLA_VERIFY_PREVIEW|| s.env.ESTELLA_VERIFY_MESH_PREVIEW || s.env.ESTELLA_VERIFY_DEPTH_LAYERS|| s.env.ESTELLA_VERIFY_COUNTERS || s.env.ESTELLA_VERIFY_COUNTERS_MAX || s.env.ESTELLA_VERIFY_FRAME_DEBUG || s.env.ESTELLA_VERIFY_EDGE || s.env.ESTELLA_VERIFY_CUTOUT_EDGE || s.env.ESTELLA_VERIFY_MINIFIED || s.env.ESTELLA_VERIFY_TWINS|| s.env.ESTELLA_VERIFY_DRAW_CALLS || s.env.ESTELLA_VERIFY_NINE_SLICEdiff --git a/tools/render-host/host.ts b/tools/render-host/host.tsindex 4b799341c..b8c115666 100644--- a/tools/render-host/host.ts+++ b/tools/render-host/host.ts@@ -22,7 +22,7 @@ import {getComponent, DeviceStatus, getDeviceStatus, getDeviceLostReport, recoverDevice,getContextLossGuardInfo, decodeImagePixels, captureFramePixels, captureFrame, replayDraw, BatchBreak,RenderTexture, Camera, Sprite,- EditorView, EditorGrid, installEditorGrid, editorViewHalfHeight, setEditorViewHalfHeight,+ EditorViewLighting, EditorView, EditorGrid, installEditorGrid, editorViewHalfHeight, setEditorViewHalfHeight,ProfileRecorder, AnimatorController, Timeline, onDeviceRestored, Schedule, defineSystem,textureImportSettingsFrom,} from 'esengine';@@ -672,6 +672,18 @@ const api = {setEditorViewHalfHeight(view, seen);},+ /** The editor view's own lighting and exposure — view state, never part of the+ * scene. Pass nothing to return to the game's own settings. The eye the frame+ * is drawn through has to be the editor's, so this wakes it if it is asleep. */+ setViewLighting(spec?: Record<string, unknown>): void {+ if (!app) throw new Error('set_view_lighting before boot');+ const view = app.getResource(EditorView);+ if (!view.active) { seedEditorViewFromScene(); view.active = true; }+ const lighting = app.getResource(EditorViewLighting);+ if (!spec) { lighting.mode = 'scene'; lighting.exposure = 0; return; }+ Object.assign(lighting, spec);+ },+/** The reference grid. Enabling seeds and activates the eye it draws through,* because this host boots with that eye inactive. */setGrid(enabled: boolean, spacing?: number): void {diff --git a/tools/render-host/run.mjs b/tools/render-host/run.mjsindex bbdcf2856..515c43daf 100644--- a/tools/render-host/run.mjs+++ b/tools/render-host/run.mjs@@ -30,6 +30,7 @@* ESTELLA_VERIFY_ANIMATOR drive an animator to a point in time (JSON)* ESTELLA_VERIFY_PICK hit-test a viewport point, asserting the entity (JSON)* ESTELLA_VERIFY_ORBIT turn the editor eye before capture ("yaw,pitch" degrees)+ * ESTELLA_VERIFY_STUDIO the editor view's studio lighting and exposure (JSON: see the block)* ESTELLA_VERIFY_COUNTERS engine counters the drawn frame must report (JSON)* ESTELLA_VERIFY_COUNTERS_MAX counters the frame must stay UNDER — a budget (JSON)* ESTELLA_VERIFY_FRAME_DEBUG capture the frame and replay it (the frame debugger)@@ -215,14 +216,17 @@ function finish(result, server) {// A frame of one colour reads as a bare clear. Where one colour IS the answer, a// count of that colour is what proves something drew it.const uniformByDesign = Boolean(process.env.ESTELLA_VERIFY_UNIFORM) && result.count?.ok === true;- const renderedOk = (result.capture?.rendered ?? false) || uniformByDesign;+ // The studio gate's own last frame is the scene's, which for the scene with no light is+ // black on purpose; what proves a frame was drawn there is the studio frame it measured.+ const studioDrew = result.studio?.ok === true && (result.studio.S?.litShare ?? 0) > 0;+ const renderedOk = (result.capture?.rendered ?? false) || uniformByDesign || studioDrew;// A scene that could not load an asset it names draws a frame nobody declared, so// its pixels answer a different question — say which asset instead.const assetsOk = (result.missingAssets?.length ?? 0) === 0;const ok = result.ok && renderedOk && assetsOk && (result.expect?.ok ?? true) && (result.twins?.ok ?? true) && (result.count?.ok ?? true) &&(result.seam?.ok ?? true) && (result.nineSlice?.ok ?? true) &&(result.resize?.ok ?? true) && (result.preview?.ok ?? true) &&- (result.meshPreview?.ok ?? true) && (result.grid?.ok ?? true) &&+ (result.meshPreview?.ok ?? true) && (result.grid?.ok ?? true) && (result.studio?.ok ?? true) &&(result.draws?.ok ?? true) && (result.counters?.ok ?? true) && (result.frameDebug?.ok ?? true) && (result.edge?.ok ?? true) && (result.cutoutEdge?.ok ?? true) && (result.minified?.ok ?? true) &&(result.roundtrip?.ok ?? true) && deviceLossOk && meshOk && pickOk;const why = assetsOk ? '' : `: could not load ${result.missingAssets.join(', ')}`;@@ -1052,7 +1056,82 @@ app.whenReady().then(async () => {`);if (respaced != null) grid = { ...grid, respacedPixels: respaced, ok: grid.ok && respaced > 300 };}- finish({ ok: true, entityCount, missingAssets, drawCalls, draws, counters, frameDebug, edge, cutoutEdge, minified, profile, capture, expect, twins, nineSlice, count, seam, resize, preview, meshPreview, grid, deviceLoss, roundtrip, meshResident, meshAsset, meshMaterial, meshPrefab, setField, animator, pick, cameraTarget }, server);+ // ESTELLA_VERIFY_STUDIO = { studio?: {...lighting}, dark?, exposure?, scene? }: the editor+ // view's own lighting, the one thing that is NOT the scene. Four frames through the+ // same eye — scene A, studio S, scene A' (switched back), and A under exposure — and+ // the claims are about their relations:+ // dark: false -> S differs from A and the scene was already lit (the studio replaces it);+ // dark: true -> A is unreadable (almost no lit pixels) and S is readable: a lit share and+ // a spread of tones, because a flat blob is not a model;+ // A' == A byte for byte, whatever the studio did in between;+ // exposure: EV -> mean display luma of A under EV scales by 2^EV (gamma frame), and+ // resetting returns A exactly.+ let studio = null;+ if (process.env.ESTELLA_VERIFY_STUDIO) {+ const spec = JSON.parse(process.env.ESTELLA_VERIFY_STUDIO);+ const api = (call) => exec(`(async () => { const api = window.__estellaHeadless.api; ${call}; await api.step(2, 1 / 60); })()`);+ const stats = (name) => readFrame(`+ window.__studio = window.__studio || {};+ window.__studio[${JSON.stringify(name)}] = px.slice();+ const lum = (i) => 0.2126 * px[i] + 0.7152 * px[i + 1] + 0.0722 * px[i + 2];+ const dec = (c) => { c /= 255; return c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4); };+ const l = []; let lit = 0, sum = 0, lin = 0;+ for (let i = 0; i < px.length; i += 4) { const v = lum(i); l.push(v); sum += v; if (v > 30) lit++; lin += 0.2126 * dec(px[i]) + 0.7152 * dec(px[i + 1]) + 0.0722 * dec(px[i + 2]); }+ const n = l.length;+ // The spread of tones among the pixels that carry any: a model reads by its shading.+ const on = l.filter((v) => v > 30).sort((a, b) => a - b);+ const spread = on.length ? on[Math.floor(on.length * 0.95)] - on[Math.floor(on.length * 0.05)] : 0;+ return { litShare: lit / n, mean: sum / n, meanLinear: lin / n, spread };+ `);+ const diff = (a, b) => readFrame(`+ const A = window.__studio[${JSON.stringify(a)}], B = window.__studio[${JSON.stringify(b)}];+ let max = 0, differing = 0;+ for (let i = 0; i < A.length; i++) { const d = Math.abs(A[i] - B[i]); if (d > max) max = d; if (d > 0) differing++; }+ return { max, differing };+ `);+ await api('api.setViewLighting()');+ const A = await stats('A');+ let S = null, back = null, dStudio = null;+ if (spec.studio) {+ await api(`api.setViewLighting(${JSON.stringify({ mode: 'studio', ...spec.studio })})`);+ S = await stats('S');+ dStudio = await diff('A', 'S');+ await api('api.setViewLighting()');+ await stats('A2');+ back = await diff('A', 'A2');+ }+ // Seeing the sky and being lit by it are separate: showSky draws the scene's environment+ // behind the studio-lit model ('adds'), and a scene with none has nothing to draw ('noop').+ let sky = null;+ if (spec.sky) {+ await api(`api.setViewLighting(${JSON.stringify({ mode: 'studio', ...spec.studio, showSky: true })})`);+ await stats('SS');+ const d = await diff('S', 'SS');+ await api('api.setViewLighting()');+ await stats('A4');+ const reset = await diff('A', 'A4');+ sky = { differing: d.differing, resetMax: reset.max,+ ok: reset.max === 0 && (spec.sky === 'adds' ? d.differing > 2000 : d.differing === 0) };+ }+ let exp = null;+ if (spec.exposure !== undefined) {+ await api(`api.setViewLighting(${JSON.stringify({ mode: 'scene', exposure: spec.exposure })})`);+ const E = await stats('E');+ await api('api.setViewLighting()');+ await stats('A3');+ const reset = await diff('A', 'A3');+ const want = Math.pow(2, spec.exposure);+ // In a linear frame the exposure is a scale of radiance, so it is measured there.+ const ratio = spec.linear ? E.meanLinear / A.meanLinear : E.mean / A.mean;+ exp = { ev: spec.exposure, ratio, want, resetMax: reset.max,+ ok: Math.abs(ratio - want) <= (spec.tol ?? 0.08) * want && reset.max === 0 };+ }+ const darkOk = spec.dark === undefined ? true+ : spec.dark ? (A.litShare < 0.02 && S && S.litShare > 0.08 && S.spread > 40)+ : (S && dStudio.differing > 200);+ studio = { A, S, dStudio, back, sky, exp, ok: Boolean(darkOk) && (!spec.studio || back.max === 0) && (!sky || sky.ok) && (!exp || exp.ok) };+ }+ finish({ ok: true, studio, entityCount, missingAssets, drawCalls, draws, counters, frameDebug, edge, cutoutEdge, minified, profile, capture, expect, twins, nineSlice, count, seam, resize, preview, meshPreview, grid, deviceLoss, roundtrip, meshResident, meshAsset, meshMaterial, meshPrefab, setField, animator, pick, cameraTarget }, server);} catch (e) {finish({ ok: false, error: String((e && e.stack) || e) }, server);}diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjsindex e1293c90c..2ab8e1800 100644--- a/tools/renderScenes.mjs+++ b/tools/renderScenes.mjs@@ -83,6 +83,14 @@ export const SCENES = [// horizon is. A plane turned to meet the eye lights the frame evenly and passes// the coverage check, so "grazing" is what tells the two apart.{ id: "editor-grid-grazing", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mesh-instanced.esscene", ESTELLA_VERIFY_GRID: "64", ESTELLA_VERIFY_GRID_EXPECT: "grazing", ESTELLA_VERIFY_PERSPECTIVE: "1", ESTELLA_VERIFY_ORBIT: "0,4", ESTELLA_VERIFY_STEPS: "3" } },+ // The editor view's studio preview: a view-only light and exposure. The scene with NO light is dark+ // and the studio makes the model readable; a scene lit by its own light or an environment is+ // replaced by it; and in every case switching back is the scene's own frame to the byte.+ { id: "studio-preview-nolight", tier: "pr", webgpu: true, env: {"ESTELLA_VERIFY_SCENE": "/scenes/studio-preview-nolight.esscene", "ESTELLA_VERIFY_W": "256", "ESTELLA_VERIFY_H": "256", "ESTELLA_VERIFY_STEPS": "3", "ESTELLA_VERIFY_STUDIO": "{\"studio\":{},\"dark\":true,\"sky\":\"noop\"}"} },+ { id: "studio-preview-sun", tier: "pr", webgpu: true, env: {"ESTELLA_VERIFY_SCENE": "/scenes/mesh-builtin.esscene", "ESTELLA_VERIFY_W": "256", "ESTELLA_VERIFY_H": "256", "ESTELLA_VERIFY_STEPS": "3", "ESTELLA_VERIFY_STUDIO": "{\"studio\":{},\"dark\":false}"} },+ { id: "studio-preview-hdr", tier: "pr", webgpu: true, env: {"ESTELLA_VERIFY_SCENE": "/scenes/studio-preview-hdr.esscene", "ESTELLA_VERIFY_W": "256", "ESTELLA_VERIFY_H": "256", "ESTELLA_VERIFY_STEPS": "3", "ESTELLA_VERIFY_PERSPECTIVE": "1", "ESTELLA_VERIFY_ORBIT": "0,0", "ESTELLA_VERIFY_STUDIO": "{\"studio\":{},\"dark\":false,\"sky\":\"adds\"}"} },+ { id: "studio-exposure", tier: "pr", webgpu: true, env: {"ESTELLA_VERIFY_SCENE": "/scenes/mesh-builtin.esscene", "ESTELLA_VERIFY_W": "256", "ESTELLA_VERIFY_H": "256", "ESTELLA_VERIFY_STEPS": "3", "ESTELLA_VERIFY_STUDIO": "{\"exposure\":-1}"} },+ { id: "studio-exposure-linear", tier: "pr", webgpu: true, env: {"ESTELLA_VERIFY_COLORSPACE": "linear", "ESTELLA_VERIFY_SCENE": "/scenes/mesh-builtin.esscene", "ESTELLA_VERIFY_W": "256", "ESTELLA_VERIFY_H": "256", "ESTELLA_VERIFY_STEPS": "3", "ESTELLA_VERIFY_STUDIO": "{\"exposure\":-1,\"linear\":true}"} },{ id: "frame-debugger-2d", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/sprite-rendering.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/sprite-rendering.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_FRAME_DEBUG: "1" } },{ id: "frame-debugger-3d", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/ssao.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "4", ESTELLA_VERIFY_FRAME_DEBUG: "1" } },{ id: "frame-debugger-split", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/camera-split.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/camera-split.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_FRAME_DEBUG: "1" } },