@fps-games/editor 0.1.5-beta.5 → 0.1.7-beta.1

package/node_modules/@fps-games/editor-playable-sdk/dist/inspector/document-sections.js

@@ -1,6 +1,7 @@
 import { createIdentityEditorTransform, decomposeEditorTransformMatrix, isEditorTransformMatrixSnapshot, } from '@fps-games/editor-core';
 import { getEditorSceneAuthoringSourceRef, } from '../authoring/index.js';
 import { findEditorSceneModelRenderer, findEditorSceneTransform, readEditorSceneNodeKind, } from '../document/index.js';
+import { EDITOR_SHADOW_LEGACY_AUTHORING_ENABLED, EDITOR_SHADOW_OBJECT_ADVANCED_PARAMS_ENABLED, EDITOR_SHADOW_STATIC_AUTHORING_ENABLED, readEditorShadowSettingsWithLegacy, resolveEditorShadowPlan, } from '../shadow-system/index.js';
 import { normalizeEditorSceneRenderingProfile, } from '../rendering-profile/index.js';
 import { collectEditorSceneSubtreeIdList, } from '../session/hierarchy.js';
 import { isEditorSceneRootGameObject, } from '../session/identity.js';
@@ -433,7 +434,21 @@ export function createEditorSceneShadowInspectorSection(input) {
         return null;
     const language = readEditorSceneShadowInspectorLanguage(input.gameObject);
     const text = getEditorSceneShadowInspectorText(language);
-    const mode = readEditorSceneInspectorShadowMode(input.gameObject.shadowMode);
+    const authoredShadowSettings = readEditorShadowSettingsWithLegacy({
+        shadow: input.gameObject.shadow,
+        shadowMode: input.gameObject.shadowMode,
+    }).shadow;
+    const shadowSettings = authoredShadowSettings ?? {};
+    const profile = normalizeEditorSceneRenderingProfile(input.renderingProfile);
+    const fallbackMode = readEditorSceneShadowFallbackModeFromRenderingProfile(profile);
+    const documentGameObject = findEditorSceneGameObject(input.document, input.gameObject.id);
+    const detachedInspectorGameObject = documentGameObject !== input.gameObject;
+    const resolvedPlan = resolveEditorShadowPlan({
+        document: input.document,
+        casterId: input.gameObject.id,
+        fallbackMode,
+        ...(detachedInspectorGameObject && authoredShadowSettings ? { settings: { instance: authoredShadowSettings } } : {}),
+    });
     const properties = [
         createEditorSceneEditableInspectorProperty(input, {
             document: input.document,
@@ -448,33 +463,150 @@ export function createEditorSceneShadowInspectorSection(input) {
             controlOptions: { variant: 'segmented' },
             tooltip: text.tooltips.language,
         }),
+        ...createEditorSceneShadowResolvedInspectorProperties(resolvedPlan, text, 1),
         createEditorSceneEditableInspectorProperty(input, {
             document: input.document,
-            path: 'shadowMode',
-            label: text.mode,
+            path: 'shadow.cast',
+            label: text.cast,
             valueType: 'enum',
             control: 'enum',
-            value: mode,
+            value: readEditorSceneCompactShadowCastValue(shadowSettings.cast, resolvedPlan.mode),
             commitMode: 'immediate',
-            order: 1,
-            options: createEditorSceneShadowModeOptions(text),
-            tooltip: text.tooltips.mode,
+            order: 10,
+            options: createEditorSceneShadowCastOptions(text),
+            tooltip: text.tooltips.cast,
         }),
+        createEditorSceneEditableInspectorProperty(input, {
+            document: input.document,
+            path: 'shadow.receive',
+            label: text.receive,
+            valueType: 'enum',
+            control: 'enum',
+            value: readEditorSceneCompactShadowReceiveValue(shadowSettings.receive),
+            commitMode: 'immediate',
+            order: 11,
+            options: createEditorSceneShadowReceiveOptions(text),
+            tooltip: text.tooltips.receive,
+        }),
+        createEditorSceneEditableInspectorProperty(input, {
+            document: input.document,
+            path: 'shadow.mode',
+            label: text.policy,
+            valueType: 'enum',
+            control: 'enum',
+            value: readEditorSceneCompactShadowPolicyValue(shadowSettings.mode, resolvedPlan.mode),
+            commitMode: 'immediate',
+            order: 12,
+            options: createEditorSceneShadowPolicyOptions(text),
+            tooltip: text.tooltips.policy,
+        }),
+        createEditorSceneEditableInspectorProperty(input, {
+            document: input.document,
+            path: 'shadow.quality',
+            label: text.quality,
+            valueType: 'enum',
+            control: 'enum',
+            value: readEditorSceneCompactShadowQualityValue(shadowSettings.quality, resolvedPlan.quality),
+            commitMode: 'immediate',
+            order: 13,
+            options: createEditorSceneShadowQualityOptions(text),
+            tooltip: text.tooltips.quality,
+        }),
+        ...(EDITOR_SHADOW_OBJECT_ADVANCED_PARAMS_ENABLED
+            ? createEditorSceneShadowParamInspectorProperties(input, shadowSettings, text, 30)
+            : []),
+        ...(EDITOR_SHADOW_LEGACY_AUTHORING_ENABLED ? [createEditorSceneEditableInspectorProperty(input, {
+                document: input.document,
+                path: 'shadowMode',
+                label: text.legacyMode,
+                valueType: 'enum',
+                control: 'enum',
+                value: readEditorSceneInspectorShadowMode(input.gameObject.shadowMode),
+                commitMode: 'immediate',
+                order: 80,
+                options: createEditorSceneShadowModeOptions(text),
+                tooltip: text.tooltips.legacyMode,
+            })] : []),
     ];
-    if (mode === 'static') {
-        properties.push(createEditorSceneStaticShadowBakeActionProperty(text, 2));
+    if (EDITOR_SHADOW_STATIC_AUTHORING_ENABLED && resolvedPlan.mode === 'static') {
+        properties.push(createEditorSceneStaticShadowBakeActionProperty(text, 90));
     }
     return {
         id: 'shadow',
         title: text.title,
         order: 34,
         placement: 'body',
-        summary: text.summaryMode(mode),
+        summary: text.summaryPolicy(resolvedPlan.mode),
         persistence: 'document',
         collapsedByDefault: false,
         properties,
     };
 }
+function readEditorSceneCompactShadowCastValue(value, resolvedMode) {
+    if (value === 'enabled')
+        return 'enabled';
+    if (value === 'none')
+        return 'none';
+    return resolvedMode === 'none' ? 'none' : 'enabled';
+}
+function readEditorSceneCompactShadowReceiveValue(value) {
+    return value === 'enabled' ? 'enabled' : 'none';
+}
+function readEditorSceneCompactShadowPolicyValue(authoredMode, resolvedMode) {
+    if (authoredMode === 'none' || authoredMode === 'dynamic' || authoredMode === 'blob' || authoredMode === 'projected') {
+        return authoredMode;
+    }
+    if (resolvedMode === 'none' || resolvedMode === 'dynamic' || resolvedMode === 'blob' || resolvedMode === 'projected') {
+        return resolvedMode;
+    }
+    return 'none';
+}
+function readEditorSceneCompactShadowQualityValue(authoredQuality, resolvedQuality) {
+    if (authoredQuality === 'low' || authoredQuality === 'medium' || authoredQuality === 'high') {
+        return authoredQuality;
+    }
+    if (resolvedQuality === 'low' || resolvedQuality === 'medium' || resolvedQuality === 'high') {
+        return resolvedQuality;
+    }
+    return 'high';
+}
+function createEditorSceneShadowResolvedInspectorProperties(plan, text, startOrder) {
+    const diagnostics = plan.diagnostics
+        .map(diagnostic => `${diagnostic.severity}:${diagnostic.code} - ${diagnostic.message}`)
+        .join('\n');
+    const properties = [];
+    if (EDITOR_SHADOW_STATIC_AUTHORING_ENABLED && plan.mode === 'static') {
+        properties.push(createEditorSceneReadonlyInspectorProperty({
+            path: 'shadow.static.bakeState',
+            label: text.staticBakeState,
+            value: plan.stale ? text.staticBakeStale : text.staticBakeAuthored,
+            order: startOrder + 5,
+            source: 'Derived',
+            tooltip: text.tooltips.staticBakeState,
+            effect: 'derived',
+        }));
+    }
+    if (diagnostics) {
+        properties.push(createEditorSceneReadonlyInspectorProperty({
+            path: 'shadow.resolved.diagnostics',
+            label: text.resolvedDiagnostics,
+            value: diagnostics,
+            order: startOrder + 6,
+            source: 'Derived',
+            tooltip: text.tooltips.resolvedDiagnostics,
+            effect: plan.diagnostics.some(diagnostic => diagnostic.severity === 'error')
+                ? 'unsupported'
+                : 'derived',
+        }));
+    }
+    return properties.filter((property) => !!property);
+}
+function readEditorSceneShadowFallbackModeFromRenderingProfile(profile) {
+    const defaultMode = profile.shadows.defaultMode;
+    if (defaultMode === 'planar')
+        return 'projected';
+    return defaultMode;
+}
 export function createEditorSceneStaticShadowBakeActionProperty(text, order) {
     return {
         path: EDITOR_SCENE_STATIC_SHADOW_BAKE_ACTION_PATH,
@@ -497,6 +629,33 @@ export function createEditorSceneStaticShadowBakeActionProperty(text, order) {
         tags: ['Rendering'],
     };
 }
+function createEditorSceneShadowParamInspectorProperties(input, shadow, text, startOrder) {
+    return [
+        createEditorSceneShadowNumberInspectorProperty(input, 'shadow.params.opacity', text.opacity, shadow.params?.opacity ?? null, startOrder + 0, 0.05, text.tooltips.opacity),
+        createEditorSceneShadowNumberInspectorProperty(input, 'shadow.params.softness', text.softness, shadow.params?.softness ?? null, startOrder + 1, 0.05, text.tooltips.softness),
+        createEditorSceneShadowNumberInspectorProperty(input, 'shadow.params.bias', text.bias, shadow.params?.bias ?? null, startOrder + 2, 0.0001, text.tooltips.bias),
+        createEditorSceneShadowNumberInspectorProperty(input, 'shadow.params.normalBias', text.normalBias, shadow.params?.normalBias ?? null, startOrder + 3, 0.0001, text.tooltips.normalBias),
+        createEditorSceneShadowNumberInspectorProperty(input, 'shadow.params.maxDistance', text.maxDistance, shadow.params?.maxDistance ?? null, startOrder + 4, 1, text.tooltips.maxDistance),
+        createEditorSceneShadowNumberInspectorProperty(input, 'shadow.params.resolution', text.resolution, shadow.params?.resolution ?? null, startOrder + 5, 64, text.tooltips.resolution),
+        createEditorSceneShadowNumberInspectorProperty(input, 'shadow.params.cascadeCount', text.cascadeCount, shadow.params?.cascadeCount ?? null, startOrder + 6, 1, text.tooltips.cascadeCount),
+        createEditorSceneShadowNumberInspectorProperty(input, 'shadow.params.bakeSamples', text.bakeSamples, shadow.params?.bakeSamples ?? null, startOrder + 7, 1, text.tooltips.bakeSamples),
+        createEditorSceneShadowNumberInspectorProperty(input, 'shadow.params.blurKernel', text.blurKernel, shadow.params?.blurKernel ?? null, startOrder + 8, 1, text.tooltips.blurKernel),
+    ];
+}
+function createEditorSceneShadowNumberInspectorProperty(input, path, label, value, order, step, tooltip) {
+    return createEditorSceneEditableInspectorProperty(input, {
+        document: input.document,
+        path,
+        label,
+        valueType: 'number',
+        control: 'number',
+        value,
+        commitMode: 'live',
+        order,
+        step,
+        tooltip,
+    });
+}
 export function createEditorSceneRenderingInspectorSection(input) {
     if (!canEditEditorSceneObjectRendering(input))
         return null;
@@ -704,13 +863,7 @@ function readEditorSceneRenderingAlphaIndex(gameObject) {
     const renderingAlphaIndex = gameObject.rendering?.alphaIndex;
     if (typeof renderingAlphaIndex === 'number' && Number.isFinite(renderingAlphaIndex))
         return renderingAlphaIndex;
-    const groundDecal = gameObject.groundDecal;
-    const legacyAlphaIndex = groundDecal && typeof groundDecal === 'object' && !Array.isArray(groundDecal)
-        ? groundDecal.alphaIndex
-        : undefined;
-    return typeof legacyAlphaIndex === 'number' && Number.isFinite(legacyAlphaIndex)
-        ? legacyAlphaIndex
-        : undefined;
+    return undefined;
 }
 function createEditorSceneRenderingInspectorSummary(groupSlot, alphaIndex) {
     return alphaIndex == null
@@ -754,10 +907,53 @@ export function createEditorSceneShadowModeOptions(text) {
         { label: text.modeProjectDefault, value: 'default' },
         { label: text.modeNone, value: 'none' },
         { label: text.modeBlob, value: 'blob' },
-        { label: text.modeStatic, value: 'static' },
+        ...(EDITOR_SHADOW_STATIC_AUTHORING_ENABLED
+            ? [{ label: text.modeStatic, value: 'static' }]
+            : []),
         { label: text.modePlanar, value: 'planar' },
     ];
 }
+export function createEditorSceneShadowCastOptions(text) {
+    return [
+        { label: text.castNone, value: 'none' },
+        { label: text.castEnabled, value: 'enabled' },
+    ];
+}
+export function createEditorSceneShadowReceiveOptions(text) {
+    return [
+        { label: text.receiveNone, value: 'none' },
+        { label: text.receiveEnabled, value: 'enabled' },
+    ];
+}
+export function createEditorSceneShadowPolicyOptions(text) {
+    return [
+        { label: text.policyNone, value: 'none' },
+        { label: text.policyDynamic, value: 'dynamic' },
+        { label: text.policyBlob, value: 'blob' },
+        { label: text.policyProjected, value: 'projected' },
+    ];
+}
+export function createEditorSceneShadowQualityOptions(text) {
+    return [
+        { label: text.qualityLow, value: 'low' },
+        { label: text.qualityMedium, value: 'medium' },
+        { label: text.qualityHigh, value: 'high' },
+    ];
+}
+export function createEditorSceneShadowLightOptions(text) {
+    return [
+        { label: text.inherit, value: 'inherit' },
+        { label: text.lightSceneMain, value: 'scene-main' },
+        { label: text.lightNearest, value: 'nearest' },
+        { label: text.lightExplicit, value: 'explicit' },
+    ];
+}
+export function readEditorSceneInspectorShadowSettings(gameObject) {
+    return readEditorShadowSettingsWithLegacy({
+        shadow: gameObject.shadow,
+        shadowMode: gameObject.shadowMode,
+    }).shadow ?? {};
+}
 function readEditorSceneInspectorTransformVector(transform, vectorName) {
     if (vectorName === 'scale')
         return transform.scale ?? { x: 1, y: 1, z: 1 };
@@ -795,8 +991,58 @@ const EDITOR_SCENE_SHADOW_INSPECTOR_TEXT = {
     zh: {
         title: '阴影',
         language: '语言',
-        mode: '阴影模式',
+        cast: '投射阴影',
+        receive: '接收阴影',
+        policy: '阴影模式',
+        quality: '质量预设',
+        light: '阴影光源',
+        lightId: '显式光源 ID',
+        opacity: '透明度',
+        softness: '柔和度',
+        bias: 'Bias',
+        normalBias: 'Normal Bias',
+        maxDistance: '最大距离',
+        resolution: '分辨率',
+        cascadeCount: '级联数量',
+        bakeSamples: '烘焙采样',
+        blurKernel: '模糊核',
+        legacyMode: 'Legacy shadowMode',
         bakeAction: '更新烘焙结果',
+        resolvedSource: '生效来源',
+        resolvedPolicy: '生效策略',
+        resolvedQuality: '生效质量',
+        resolvedReceivers: '接收面',
+        resolvedLight: '光源',
+        resolvedDiagnostics: '诊断',
+        staticBakeState: '静态烘焙状态',
+        staticBakeAuthored: '已标记静态；请在修改后更新烘焙',
+        staticBakeStale: '烘焙已过期',
+        sourceShadowSettings: '当前对象 shadow.*',
+        sourceLegacyMode: '当前对象 legacy shadowMode',
+        sourcePrefabDefaults: 'Prefab defaults',
+        sourceAssetDefaults: 'Source asset defaults',
+        sourceInherited: '继承 / 项目默认',
+        none: '无',
+        inherit: '继承',
+        castNone: '关闭',
+        castEnabled: '开启',
+        castAuto: '自动',
+        receiveNone: '关闭',
+        receiveEnabled: '开启',
+        receiveAuto: '自动',
+        policyNone: '无阴影',
+        policyDynamic: '动态 Shadow Map',
+        policyStatic: '静态烘焙',
+        policyBlob: 'Blob 阴影',
+        policyProjected: 'Projected 阴影',
+        policyAuto: '自动',
+        qualityLow: '高性能',
+        qualityMedium: '平衡',
+        qualityHigh: '高质量',
+        qualityUltra: '超高质量',
+        lightSceneMain: '场景主光源',
+        lightNearest: '最近光源',
+        lightExplicit: '指定光源',
         modeProjectDefault: '项目默认',
         modeNone: '无阴影',
         modeBlob: 'Blob 阴影',
@@ -815,17 +1061,106 @@ const EDITOR_SCENE_SHADOW_INSPECTOR_TEXT = {
                 return '主平面阴影';
             return '项目默认';
         },
+        summaryPolicy: (mode, mixed) => {
+            if (mixed)
+                return '多种策略';
+            if (mode === 'none')
+                return '无阴影';
+            if (mode === 'dynamic')
+                return '动态 Shadow Map';
+            if (mode === 'static')
+                return '静态烘焙';
+            if (mode === 'blob')
+                return 'Blob 阴影';
+            if (mode === 'projected')
+                return 'Projected 阴影';
+            if (mode === 'auto')
+                return '自动';
+            return '继承';
+        },
         tooltips: {
             language: '切换阴影 Inspector 的显示语言。该字段只影响编辑器，不会导出到运行时。',
-            mode: '选择当前物体使用的阴影策略：项目默认跟随 Rendering 面板；无阴影禁用投射；Blob 适合可移动物体；静态烘焙阴影只参与编辑器烘焙并由 artifact 显示；主平面阴影跟随直射光动态投影。',
+            cast: '控制该对象是否投射阴影。关闭时该对象不会产生阴影。',
+            receive: '控制该对象是否接收阴影。通常地面或平台开启，角色和道具按需要开启。',
+            policy: '选择当前对象使用的阴影模式：无阴影、动态 Shadow Map、Blob 阴影或 Projected 阴影。',
+            quality: '选择阴影预设：高性能、平衡或高质量。具体项目级参数在右侧 Rendering / Shadows 面板中配置。',
+            light: '选择阴影使用的光源策略。显式光源需要填写光源 ID。',
+            lightId: '当阴影光源为指定光源时使用。为空表示稍后由 resolver 诊断。',
+            opacity: '覆盖阴影透明度，范围 0 到 1；为空则使用质量预设。',
+            softness: '覆盖阴影柔和度；为空则使用质量预设。',
+            bias: '覆盖 Shadow Map bias；为空则使用质量预设。',
+            normalBias: '覆盖 Shadow Map normal bias；为空则使用质量预设。',
+            maxDistance: '覆盖阴影最大作用距离；为空则使用质量预设。',
+            resolution: '覆盖阴影贴图或烘焙分辨率；为空则使用质量预设。',
+            cascadeCount: '覆盖动态阴影级联数量；为空则使用质量预设。',
+            bakeSamples: '覆盖静态烘焙采样数；为空则使用质量预设。',
+            blurKernel: '覆盖静态或 projected 阴影的模糊核大小；为空则使用质量预设。',
+            legacyMode: '兼容旧 runtime 的 shadowMode 字段。新系统优先使用上方 Caster / Receiver / Policy / Quality / Params。',
             bakeAction: '重新烘焙当前场景中所有标记为静态烘焙阴影的物体，并刷新编辑器预览和运行时 artifact。',
+            resolvedSource: '只读摘要：当前对象阴影配置主要来自对象自身、legacy 字段、Prefab/Instance 链或项目默认。',
+            resolvedPolicy: '只读摘要：resolver 将当前 Caster / Receiver / Light / Quality 设置解析成的实际后端。',
+            resolvedQuality: '只读摘要：resolver 使用的实际质量预设。',
+            resolvedReceivers: '只读摘要：resolver 找到的阴影接收面对象 id。',
+            resolvedLight: '只读摘要：resolver 找到的阴影光源 id。',
+            resolvedDiagnostics: '只读摘要：resolver 返回的 warning/error，可用于解释为什么阴影没有显示。',
+            staticBakeState: '静态阴影只随 owner 显隐同步；transform、light 或 source 改动后需要更新烘焙。',
         },
     },
     en: {
         title: 'Shadow',
         language: 'Language',
-        mode: 'Shadow Mode',
+        cast: 'Cast Shadow',
+        receive: 'Receive Shadow',
+        policy: 'Shadow Mode',
+        quality: 'Quality Preset',
+        light: 'Shadow Light',
+        lightId: 'Explicit Light ID',
+        opacity: 'Opacity',
+        softness: 'Softness',
+        bias: 'Bias',
+        normalBias: 'Normal Bias',
+        maxDistance: 'Max Distance',
+        resolution: 'Resolution',
+        cascadeCount: 'Cascade Count',
+        bakeSamples: 'Bake Samples',
+        blurKernel: 'Blur Kernel',
+        legacyMode: 'Legacy shadowMode',
         bakeAction: 'Update Bake',
+        resolvedSource: 'Effective Source',
+        resolvedPolicy: 'Effective Policy',
+        resolvedQuality: 'Effective Quality',
+        resolvedReceivers: 'Receivers',
+        resolvedLight: 'Light',
+        resolvedDiagnostics: 'Diagnostics',
+        staticBakeState: 'Static Bake State',
+        staticBakeAuthored: 'Authored static; update bake after changes',
+        staticBakeStale: 'Bake is stale',
+        sourceShadowSettings: 'This object shadow.*',
+        sourceLegacyMode: 'This object legacy shadowMode',
+        sourcePrefabDefaults: 'Prefab defaults',
+        sourceAssetDefaults: 'Source asset defaults',
+        sourceInherited: 'Inherited / project default',
+        none: 'None',
+        inherit: 'Inherit',
+        castNone: 'Off',
+        castEnabled: 'On',
+        castAuto: 'Auto',
+        receiveNone: 'Off',
+        receiveEnabled: 'On',
+        receiveAuto: 'Auto',
+        policyNone: 'No Shadow',
+        policyDynamic: 'Dynamic Shadow Map',
+        policyStatic: 'Static Baked',
+        policyBlob: 'Blob Shadow',
+        policyProjected: 'Projected Shadow',
+        policyAuto: 'Auto',
+        qualityLow: 'High Performance',
+        qualityMedium: 'Balanced',
+        qualityHigh: 'High Quality',
+        qualityUltra: 'Ultra',
+        lightSceneMain: 'Scene Main Light',
+        lightNearest: 'Nearest Light',
+        lightExplicit: 'Explicit Light',
         modeProjectDefault: 'Project Default',
         modeNone: 'No Shadow',
         modeBlob: 'Blob Shadow',
@@ -844,10 +1179,49 @@ const EDITOR_SCENE_SHADOW_INSPECTOR_TEXT = {
                 return 'Planar Shadow';
             return 'Project Default';
         },
+        summaryPolicy: (mode, mixed) => {
+            if (mixed)
+                return 'Mixed policies';
+            if (mode === 'none')
+                return 'No Shadow';
+            if (mode === 'dynamic')
+                return 'Dynamic Shadow Map';
+            if (mode === 'static')
+                return 'Static Baked';
+            if (mode === 'blob')
+                return 'Blob Shadow';
+            if (mode === 'projected')
+                return 'Projected Shadow';
+            if (mode === 'auto')
+                return 'Auto';
+            return 'Inherit';
+        },
         tooltips: {
             language: 'Switches the display language for this Shadow inspector. This editor-only field is not exported to runtime.',
-            mode: 'Choose the shadow strategy for this object: Project Default follows the Rendering panel; No Shadow disables casting; Blob is lightweight for moving objects; Static Baked Shadow only participates in editor baking and displays from artifacts; Planar follows the directional light dynamically.',
+            cast: 'Controls whether this object casts shadows. Off prevents it from producing a shadow.',
+            receive: 'Controls whether this object receives shadows. Ground and platforms usually turn this on; characters and props can opt in when needed.',
+            policy: 'Chooses this object shadow mode: No Shadow, Dynamic Shadow Map, Blob Shadow, or Projected Shadow.',
+            quality: 'Chooses a shadow preset: High Performance, Balanced, or High Quality. Project-level parameters live in the Rendering / Shadows panel.',
+            light: 'Chooses the light selection policy for shadows. Explicit light requires a light id.',
+            lightId: 'Used when Shadow Light is Explicit Light. Empty values will be diagnosed by the resolver later.',
+            opacity: 'Overrides shadow opacity from 0 to 1. Empty uses the quality preset.',
+            softness: 'Overrides softness. Empty uses the quality preset.',
+            bias: 'Overrides shadow-map bias. Empty uses the quality preset.',
+            normalBias: 'Overrides shadow-map normal bias. Empty uses the quality preset.',
+            maxDistance: 'Overrides max shadow distance. Empty uses the quality preset.',
+            resolution: 'Overrides map or bake resolution. Empty uses the quality preset.',
+            cascadeCount: 'Overrides dynamic shadow cascade count. Empty uses the quality preset.',
+            bakeSamples: 'Overrides static bake sample count. Empty uses the quality preset.',
+            blurKernel: 'Overrides static or projected blur kernel. Empty uses the quality preset.',
+            legacyMode: 'Compatibility field for legacy runtime shadowMode. The new system prefers Caster / Receiver / Policy / Quality / Params above.',
             bakeAction: 'Rebake every object authored as Static Baked Shadow in the current scene, then refresh the editor preview and runtime artifact.',
+            resolvedSource: 'Readonly summary of whether this object is mainly using object shadow.*, legacy shadowMode, prefab/instance inheritance, or project defaults.',
+            resolvedPolicy: 'Readonly summary of the concrete backend resolved from Caster / Receiver / Light / Quality settings.',
+            resolvedQuality: 'Readonly summary of the quality preset used by the resolver.',
+            resolvedReceivers: 'Readonly summary of receiver object ids selected by the resolver.',
+            resolvedLight: 'Readonly summary of the light id selected by the resolver.',
+            resolvedDiagnostics: 'Readonly resolver warnings/errors explaining why a shadow may not appear.',
+            staticBakeState: 'Static shadows follow owner visibility; transform, light, or source changes require a rebake.',
         },
     },
 };