运行配置

Author ：Charley

运行配置栏目用于集中管理项目启动与运行过程中常用的基础配置项，包括屏幕适配设置、默认字体与字号、2D 灯光全局参数、3D 全局配置以及调试相关选项等。

1、分辨率相关设置

与分辨率相关的设置会直接影响项目运行的预览效果，屏幕适配的方式、画布背景色等。

可设置属性如图1-1所示：

（图1-1）

1.1 画面宽高适配

影响产品画面宽高表现的核心有三个设置：设计宽高（designWidth、designHeight）与缩放模式（scaleMode）。

设计宽高决定了 IDE 中 2D 场景编辑区的默认尺寸，开发者通常在这一尺寸下构建与排列 UI。

场景运行时，引擎会依据设计宽高和当前的缩放模式，计算适合目标设备的最终显示大小。

实际运行环境中，设备屏幕比例千差万别，几乎不可能所有设备都与设计宽高一致。为解决这一差异，引擎通过不同的缩放模式进行适配，例如将画面按比例缩放至全屏，以满足项目在各类设备上的显示需求。

屏幕适配的完整机制不仅涉及缩放模式，也包含画布、舞台尺寸与适配算法等内容。开发者可在另一篇文档《屏幕适配》里查看更详细的介绍。

1.2 基于画布的对齐模式

画布的对齐模式包括 垂直对齐（alignV）与水平对齐（alignH）。当舞台尺寸未铺满画布（即舞台分辨率小于画布分辨率）时，对齐模式用于控制舞台在画布中的显示位置。

垂直对齐模式（alignV）用于指定舞台在画布垂直方向上的对齐方式，支持以下取值： top（顶部对齐）、middle（垂直居中）、bottom（底部对齐），分别表示舞台位于画布的顶部、中部或底部。

水平对齐模式（alignH）用于指定舞台在画布水平方向上的对齐方式，支持以下取值： left（左对齐）、center（水平居中）、right（右对齐），分别表示舞台位于画布的左侧、中部或右侧。

有的缩放模式，舞台会被强制缩放以完全填充画布，此时舞台尺寸与画布一致，对齐模式不会产生可见效果。因此，IDE 仅在缩放模式可能导致舞台与画布尺寸不一致的情况下，才会显示画布对齐相关选项。

注意：画布对齐与场景内的相对布局不同，如果是希望在场景内居于某个位置的对齐，请在文档搜索栏，搜索“相对布局”关键字，查看相关文档。

1.3 横竖屏适配

有的时候，我们需要根据屏幕的比例强制横竖屏设置，在IDE中可以通过设置屏幕模式（screenMode）来设置。

横竖屏有三种适配模式，如图1-2所示。

（图1-2）

无变化：无

选择无时，无论设备屏幕如何旋转，游戏的水平方向都不会产生跟随屏幕旋转的变化。效果如动图1-3所示。

(动图1-3)

可以看到，无变化时，当屏幕发生旋转后，基于竖屏设计的界面在横屏下就会变的不适合，同理，基于横屏设计的界面在竖屏下，也会变的不适合。

当然，如果我们合理运用相对布局的功能，也许也可以兼顾横竖屏的体验。效果如动图1-4所示。

(动图1-4)

但为了达到最佳的效果，最好的方案，还是竖屏始终与设备竖屏的方向保持一致，横屏与设备横屏的方向保持一致。

始终横屏：水平

当我们设计的宽高就是横屏产品时，水平无疑是最佳的体验。无论屏幕方向如何旋转，设计上的水平方向都会与屏幕最短的边始终保持垂直，所以用户设备竖屏时看到横屏画面，自然就会把设备横过来，从而吻合了产品的设计。效果如动图1-5所示。

(动图1-5)

始终竖屏：垂直

当我们设计的宽高就是竖屏产品时，垂直无疑是最佳的体验。无论屏幕方向如何旋转，游戏的水平方向都会与屏幕较长的边始终保持垂直。所以用户哪怕是把设备横屏了，仍然看到的是竖屏画面，自然就会把设备恢复竖屏，从而吻合了产品的设计。效果如动图1-6所示。

(动图1-6)

[!Tip]

需要注意的是，浏览器中运行的时候，引擎的自动横屏和自动竖屏，只能对画布进行旋转，如果用户的手机锁屏了，虽然画面自动旋转过来了，但是浏览器没有旋转过来，会导致输入法依然按浏览器的方向弹出，此时，可能会导致输入法与浏览器的显示呈90度。

在小游戏平台中运行，由于小游戏底层有横屏还是竖屏的配置，不会出现这个问题。

1.4 画布背景色设置

画布背景色用于为画布设置背景颜色，同时也作为 IDE 中 2D 场景编辑界面的背景色。

需要注意的是，在实际运行中，若场景中启用了 3D 天空盒，或 3D 相机本身设置了背景色，在全屏适配模式下这些内容会覆盖画布，因此画布背景色通常不会被看到。只有在画面存在未被内容填满、能够 “露出” 画布的区域时，画布背景色才会显示出来，如图 1-7 所示：

（图1-7）

2、引擎通用的初始化设置

2D选项卡下，主要是2D与通用的全局配置。如图2-1所示：

（图2-1）

2.1 每秒帧数 FPS

在游戏开发中，FPS（Frames Per Second）表示每秒帧数，即单位时间内画面更新的次数，是衡量运行流畅度的重要性能指标。FPS 越高，画面更新越频繁，视觉体验越流畅，同时输入响应延迟也通常越低；反之，FPS 较低时会出现画面卡顿、不连贯的现象（通常称为“掉帧”），严重影响游戏体验。

在大多数场景下，60 FPS 已能提供较为流畅的体验。随着高刷新率屏幕的普及，越来越多的移动设备和 VR 设备支持 90Hz、120Hz 甚至更高的刷新率，对更高帧率的需求也随之增加。

在实际项目中，为了在不同设备上保持一致的运行节奏，或在流畅度与性能消耗之间取得平衡（FPS 越高，CPU 与 GPU 的消耗通常也越大），可以通过 IDE 中的 “每秒帧数（FPS）” 进行统一配置。

例如，默认值为 60 时，表示引擎的逻辑帧率上限为 60；若设置为 90，则表示逻辑更新的目标上限为 90。该设置用于控制引擎主循环的更新节奏，而非强制改变设备本身的显示刷新率。

如果开发者不希望固定逻辑帧率上限，可以将 Config.fixedFrames 设置为 false，关闭固定帧模式，使逻辑更新尽可能跟随平台的 requestAnimationFrame 调用频率执行。

// - 当为 true 时：渲染和逻辑更新被限制在由 Config.FPS 定义的帧率内。确保在不同设备上应用程序运行速度一致。
// - 当为 false 时：在每次 requestAnimationFrame 回调时进行更新。可能导致在不同设备上应用程序运行速度不同。
Laya.Config.fixedFrames = false;

2.2 画布抗锯齿 isAntialias

画布抗锯齿 isAntialias 是一项全局配置属性，用于控制 WebGL 画布是否启用抗锯齿。该属性通过设置 WebGL 上下文的 antialias 开关生效，主要作用于 2D WebGL 渲染，用于减少图形边缘的锯齿现象，提升整体视觉效果，默认值为 true。

在引擎初始化过程中，Config.isAntialias 会被传递到底层 WebGL 配置，并在创建 WebGL 上下文时作为参数交由浏览器处理。一旦 WebGL 上下文创建完成，该设置将无法再动态修改，如果通过代码控制开关，需要在引擎初始化之前进行配置。

// 在引擎初始化前执行自定义逻辑(此方法在Laya.init前调用)
Laya.addBeforeInitCallback(() => {
    // 不启用抗锯齿
    Laya.Config.isAntialias = false;
    console.log("before init");
});

开启抗锯齿可以改善曲线线条及非矩形图形的显示质量，但会带来一定的 GPU 性能开销。在性能敏感或对画质要求不高的场景中，可以将其设置为 false。需要注意的是，该属性仅影响 2D WebGL 渲染，3D 场景的抗锯齿需通过相机（Camera）上的 FXAA 或 MSAA 等方式单独配置。

2.3 视网膜画布模式 useRetinalCanvas

视网膜画布模式useRetinalCanvas 是一项全局配置属性，用于启用视网膜（高 DPI）画布模式，以提升高分辨率屏幕上的显示清晰度与渲染精度。该属性默认值为 false。当设置为 true 时，引擎会根据设备像素比（DPR）创建更高分辨率的画布，在相同的物理显示尺寸下使用更多像素进行渲染，从而获得更锐利的视觉效果。

在多数适配（缩放）模式下，引擎会将舞台内容缩放以铺满屏幕，使用较小的画布进行绘制可以有效降低性能消耗。因此，对于不追求极致画面精度的项目，通常优先选择性能更优的缩放方案。但在需要保持高分辨率显示的场景中，尤其是涉及小字号文本或精细图形时，单纯依赖缩放放大可能会导致画面模糊，此时可启用视网膜模式以提升显示质量。

启用视网膜画布模式后，无论哪种适配（缩放）模式，画布均采用屏幕物理分辨率尺寸，在不改变布局与逻辑尺寸的前提下，提高整体渲染精度与画面清晰度。

视网膜模式适用于对显示精度要求较高的场景，例如需要精确像素拾取、对文本清晰度要求较高，或追求高质量视觉表现的应用。

需要注意的是，开启 useRetinalCanvas 会显著增加 GPU 计算量与显存占用，因为更大的画布意味着需要处理更多像素数据。在性能或内存资源受限的场景中，应谨慎启用该模式，仅在确实需要高分辨率显示效果时使用。

2.4 画布透明 isAlpha

画布透明isAlpha 是一项全局配置属性，用于控制画布是否支持透明度渲染。该属性默认值为 false，表示创建不透明的画布背景；当设置为 true 时，引擎将启用画布的 Alpha 通道支持，使画布背景可呈现完全透明或半透明的渲染效果。

在渲染实现层面，isAlpha 会影响底层图形上下文的创建方式：在 WebGL 渲染模式下，该属性会作为 alpha 参数传递给底层上下文；在 WebGPU 渲染模式下，则会将 Alpha 模式设置为 premultiplied，以确保透明度混合计算的正确性。

当启用画布透明，并将背景颜色同时设置为透明时，画布内容将不再遮挡运行平台的背景（例如浏览器页面的底色），从而可以直接透过画布看到其下方内容，如图 2-2 所示。

（图2-2）

透明画布为渲染表现提供了更大的灵活性，尤其适用于需要将 LayaAir 渲染内容与其他 HTML 元素进行叠加显示的场景。例如，将 3D 粒子效果叠加在网页 UI 之上、在 HTML 页面中嵌入 3D 场景，或在可视化与 AR 等应用中实现特殊的透明叠加效果。这种方式可以打破传统画布的视觉边界，构建更丰富的层次与交互体验。

需要注意的是，启用透明画布会增加 GPU 的混合计算开销，并且在部分移动设备或低性能环境下可能存在兼容性与性能压力。因此，在启用 isAlpha 时，应结合具体使用场景与性能预算进行评估，在视觉效果与整体性能之间取得合理平衡。

2.5 开启UBO模式 enableUniformBufferObject

开启UBO模式enableUniformBufferObject 用于控制是否启用 Uniform Buffer Object（UBO） 功能，默认值为 true。UBO 是现代图形渲染管线中的一项重要优化技术，主要依赖 WebGL 2.0 提供的统一缓冲区机制，用于高效管理和传输着色器中的 uniform 数据。

启用该功能后，引擎不再以传统方式逐个设置 uniform 变量，而是将多个相关的 uniform 数据集中存储在统一缓冲区中，并一次性绑定到着色器。这种方式可以显著减少 gl.uniform* 等 API 调用次数，降低 CPU 与 GPU 之间的通信开销，从而提升整体渲染性能，尤其在包含大量材质或频繁状态切换的场景中效果更为明显。

在实现层面，引擎会在渲染设备初始化阶段检测当前硬件与运行环境是否支持 UBO 特性，并据此启用或禁用内部的 UBO 相关逻辑。在 WebGL 渲染流程中，引擎会创建专门的 Uniform Buffer 管理器，用于统一分配、维护和复用材质相关的 uniform 内存块，实现高效的批量上传与绑定。

需要注意的是，使用 UBO 可能会带来一定的额外显存占用，因此在显存资源紧张或对内存占用较为敏感的场景中，可根据实际情况选择是否启用。对于不支持 WebGL 2.0 的设备或原生平台，引擎会自动禁用该功能，以保证兼容性。

此外，引擎还提供了更细粒度的控制方式，例如通过 matUseUBO 属性对材质级别的 UBO 使用进行管理，使开发者能够根据具体需求与硬件性能进行针对性的优化配置。这种分层设计在充分利用现代 GPU 性能的同时，也兼顾了对低端设备和不同平台的适配需求。

2.6 材质使用UBO matUseUBO

材质使用UBOmatUseUBO 是用于控制材质是否启用 Uniform Buffer Object（UBO）的配置属性，默认值为 true，属于一项面向 3D 材质渲染的性能优化机制。启用该功能后，引擎会为材质相关数据创建专用的 Uniform Buffer，将原本分散设置的材质 uniform 变量（如颜色参数、纹理属性、光照相关数据等）统一打包为连续的内存块，并一次性上传至 GPU。相比逐个设置 uniform 的传统方式，这种批量传输方式可以显著减少材质全局变量的绑定次数，降低 CPU 与 GPU 之间的数据交互开销，同时提升内存访问效率和整体渲染性能。

在具体实现层面，matUseUBO 的作用贯穿多个关键环节。首先，在 GLSL 着色器代码生成阶段，该配置会影响材质 uniform 的声明方式，将原本独立声明的 uniform 变量转换为 Uniform Block 结构；其次，在实际渲染执行过程中，引擎会根据该配置决定是否为材质创建对应的子 Uniform Buffer，并通过统一的上传流程将材质数据同步到 GPU。此外，为了兼容 2D 渲染的特殊需求，引擎在创建着色器实例时会对该配置进行临时调整，确保 2D 材质仍然采用传统的 uniform 设置方式，而 3D 材质则能够充分利用 UBO 带来的性能优势。

这种设计体现了引擎针对不同渲染场景所采取的精细化优化策略。通过将材质级 UBO 控制与全局 UBO 开关进行分离，开发者可以更灵活地调节材质数据的传输与管理方式，而不会影响其他 Uniform Buffer 的使用。同时，引擎在初始化和运行过程中会进行硬件能力检测，在不支持 UBO 的设备上自动进行功能降级，从而保证渲染流程的稳定性与兼容性。这种分层且可控的设计，在充分发挥现代 GPU 性能潜力的同时，也兼顾了对低端设备和跨平台环境的支持。

2.7 2D网格内存预分配 webGL2D_MeshAllocMaxMem

2D网格内存预分配webGL2D_MeshAllocMaxMem 是优化 2D WebGL 渲染性能的配置属性，用于控制 2D 顶点缓冲区（VB）是否采用最大容量的预分配策略。该属性默认值为 true。启用后，引擎在创建 2D 顶点缓冲区时会一次性分配可容纳约 64K 个顶点的内存空间，而不是根据实际顶点数量进行动态扩容。通过提前分配较大的连续缓冲区，可以有效减少运行过程中因缓冲区扩容而产生的内存重新分配和数据拷贝操作，从而提升 2D 渲染的整体性能和稳定性。

在实现层面，该配置直接影响 2D 渲染系统的内存管理策略。当设置为 true 时，顶点缓冲区具备更高的顶点承载能力，能够连续处理大量 2D 几何数据，避免频繁的缓冲区调整开销；当设置为 false 时，引擎将采用更保守的按需分配方式，仅分配当前渲染所需的缓冲区大小，从而节省显存（可减少约 64K 顶点对应的显存占用），但在复杂或高度动态的 2D 场景中，可能会引入额外的性能消耗。

该优化策略适用于包含大量 2D 图形元素的场景，例如复杂 UI 界面、2D 粒子系统或动态生成的图形内容。它通过适当增加内存占用来换取更高的渲染效率，体现了引擎在内存使用与性能表现之间的权衡。在显存或内存资源受限的设备上，开发者可以选择关闭该配置，以节省内存空间，但需接受在部分场景下可能出现的性能下降。

2.8 默认字体与字号

文本的默认字体为 Arial，默认字号为 12。如果创建文本时未指定字体或字号，系统将自动使用引擎全局配置中的默认值。

开发者也可以在 IDE 中修改此处设置，如图2-3所示。改变引擎全局默认字体和字号，从而影响新建文本的默认显示效果。

（图2-3）

3、2D灯光全局配置

3.1 环境光颜色 ambientColor

环境光颜色ambientColor 是 2D 灯光系统中的基础环境光颜色配置，用于定义场景整体的基础照明强度与色调。环境光没有方向性，也不会产生阴影，其默认值为半透明的灰色 new Color(0.2, 0.2, 0.2, 0)，如图3-1所示。用于提供一种均匀、柔和的基础照明效果，避免画面在缺乏光源时完全变暗。

（图3-1）

在渲染实现上，ambientColor 会被传递到 2D 渲染管线的片段着色器中，作为基础光照分量参与最终像素颜色的计算。

当场景中没有其他灯光时，环境光将直接与材质颜色相乘，形成最基本的亮度；

存在方向光或其他灯光的情况下，它则作为底层光照与其他光照效果叠加，提升整体明暗层次和色彩稳定性。

环境光的颜色会直接影响整个场景的色调氛围，例如偏冷的环境光可营造夜晚或阴影感，偏暖的环境光则更适合日照或室内场景。这种设计模拟了现实世界中来自各个方向的散射光，即使在阴影区域也能保持一定的可见度。通过调整 ambientColor 的 RGB 分量，开发者可以灵活控制场景的基础亮度与整体氛围，从微弱的月光效果到明亮的室内环境都能够自然表现。

3.3 环境光遮罩 ambientLayerMask

环境光遮罩ambientLayerMask 是 LayaAir 2D 灯光系统中用于控制环境光作用范围的配置参数，采用位掩码（bitmask）方式，通过 32 位整数的每一位来标识对应渲染层是否受到环境光影响。

其默认值为 -1（二进制下所有位为 1），表示环境光会默认作用于场景中的所有 2D 渲染层。

在渲染过程中，引擎会通过位运算 ambientLayerMask & (1 << layer) 判断指定层级是否启用环境光：结果为真时，将环境光颜色参与该层的光照计算；否则，该层将忽略环境光，相当于使用透明环境光颜色。

在 IDE 中，开发者可以在“项目设置 → 预设值 → 2D 渲染层名字定义”中为各层设置可读名称，并通过环境光遮罩ambientLayerMask 进行配置，如图3-2所示，从而精确控制哪些 2D 网格渲染器所在的图层会受到环境光影响，实现更灵活的光照分层管理。

（图3-2）

3.4 光影图多重采样数 multiSamples

光影图多重采样数multiSamples 是 LayaAir 2D 灯光系统中用于控制光影图渲染质量的关键配置参数，它通过多重采样（Multi-Sampling Anti-Aliasing）技术来改善阴影边缘的视觉效果。

该参数的默认值设为 4，表示光影图在渲染时会进行 4 倍的多重采样，这意味着每个像素点会被采样 4 次，然后取平均值来计算最终颜色，从而有效减少阴影边缘的锯齿效应（jagged shadow edges）。开发者也可以将其设置为 1 来禁用多重采样，这样可以获得更好的性能表现，但阴影边缘可能会显得较为粗糙。

当 multiSamples 值发生变化时，系统会重建整个光影渲染纹理（RenderTexture），这是因为多重采样数量直接影响了渲染目标的创建参数。值得注意的是，该配置仅适用于 2D 灯光系统的光影图渲染，不影响场景中其他 2D 元素的抗锯齿处理，后者通常通过独立的画布设置或材质属性来控制。

在实际使用中，开发者需要在视觉质量和性能之间做出权衡：较高的多重采样值（如 4）能够提供更平滑的阴影边缘，但会消耗更多的 GPU 资源和内存；而较低的值（如 1）则能提升渲染性能，但可能在阴影过渡区域产生明显的锯齿。

4、3D相关参数说明：

4.1 开启动态合批 enableDynamicBatch

开启动态合批 enableDynamicBatch 用于控制动态批处理（Dynamic Batch）功能的开关。该配置默认为 true，表示默认启用动态批处理功能。

动态批处理是一种利用 GPU 实例化渲染（Instanced Rendering）技术的优化机制，它能够将多个具有相同几何形状和材质但变换不同的渲染元素合并为一次绘制调用，从而显著减少 Draw Call 数量并提升渲染性能。当该配置启用时，引擎会在渲染过程中自动检测符合条件的渲染元素，并将它们分组批处理。

要使动态批处理生效，需要同时满足多个条件：首先是 enableDynamicBatch 配置必须为 true，其次是渲染引擎必须支持实例化渲染能力，再者是渲染元素本身需要支持动态批处理（canDynamicBatch 属性为 true），最后是对应的着色器必须启用实例化（enableInstancing 为 true）。只有当所有条件都满足时，系统才会将符合条件的渲染元素进行实例合并。

开发者可以禁用此功能，这种情况通常出现在调试阶段需要精确控制渲染顺序，或者在某些特殊渲染需求下需要避免批处理带来的副作用。在生产环境中，建议保持默认开启状态以获得最佳性能表现，特别是对于包含大量相似对象的场景，如粒子系统、植被渲染或重复的建筑元素等。

4.2 默认物理内存 defaultPhysicsMemory

默认物理内存 defaultPhysicsMemory 用于控制 物理引擎初始化时分配的内存大小。该配置以 MB 为单位，默认值为 16MB，用于为物理引擎预先分配堆内存以存储物理世界中的碰撞体、刚体、关节等物理对象的计算数据。

在代码实现中，系统通过 Math.max(16, Config3D.defaultPhysicsMemory) * 16 的计算方式来确定最终的内存分配量，其中确保最小内存不低于 16MB，然后将 MB 单位转换为物理引擎内部使用的页单位（通常每页 64KB）。这种设计确保了物理引擎在初始化时就预留足够的连续内存空间，避免运行时频繁的内存分配和释放操作。

开发者可以通过调整 defaultPhysicsMemory 值来适应不同的物理场景复杂度：对于简单的物理场景可以适当降低该值以节省内存，而对于包含大量碰撞体和复杂物理交互的场景则应该提高该值以确保物理模拟的稳定性和性能。如果设置过小可能导致物理引擎内存不足而出现异常或性能下降，如果设置过大则会增加应用的内存占用。

该配置仅在物理引擎初始化阶段生效，一旦物理世界创建完成就无法动态修改，因此建议在应用启动时根据预期的物理场景复杂度合理设置该参数，并在不同设备上进行性能测试以找到最佳平衡点。

4.3 分辨率倍数 pixelRatio

分辨率倍数 pixelRatio 用于设置 3D 渲染目标的分辨率倍数。该配置通过一个浮点数乘数来影响整个 3D 渲染管线的分辨率计算，默认值为 1.0，表示使用基础分辨率进行渲染。

在代码实现中，pixelRatio 主要影响相机的 clientWidth 和 clientHeight 属性计算，其中如果启用了自定义分辨率（Config3D.customResolution），则实际渲染分辨率为 Config3D.resoluWidth/_resoluHeight 乘以 pixelRatio；如果使用自动分辨率，则为 RenderContext3D.clientWidth/clientHeight 乘以 pixelRatio。这种设计允许开发者通过调整单个参数来统一控制所有 3D 渲染目标的分辨率。

pixelRatio 的应用贯穿于多个关键的 3D 渲染环节：在视口坐标转换函数中用于确保屏幕坐标到世界坐标的正确映射，在射线计算函数中用于精确的鼠标拾取和碰撞检测，在 3D UI 交互处理中用于正确的视口范围判断，以及在世界坐标到视口坐标的转换过程中用于保持坐标系的一致性。

开发者可以通过设置 Config3D.pixelRatio = 2.0 来获得 2 倍分辨率的 3D 渲染效果，这在高分辨率显示设备上可以提供更清晰的视觉质量，但也会相应增加 GPU 的渲染负载；反之，设置较小的值如 0.5 可以降低渲染分辨率以提升性能，适用于对画质要求不高的场景。建议在不同的目标设备上测试不同的 pixelRatio 值，以找到性能和画质的最佳平衡点。

需要注意的是，该设置只会影响 3D 分辨率，不会影响2D UI的分辨率。

4.4 开启多光源 enableMultiLight

开启多光源enableMultiLight 用于决定是否启用现代化的多光源集群渲染技术。该配置默认为 true，表示默认启用多光源系统，但会根据硬件能力进行最终确定。

当 enableMultiLight 启用时，系统会初始化完整的多光源渲染管线：创建 Cluster 实例来管理光照集群，将视锥体空间划分为多个小的三维网格区域；生成专门的光照纹理缓冲区来存储多达 Config3D.maxLightCount 个光源的数据；并使用先进的集群算法将光源按照空间位置分配到相应的视锥体区域中。这种设计允许场景中同时存在大量的光源（点光源、聚光灯、方向光），每个像素能够受到多个光源的照亮影响。

当 enableMultiLight 关闭时，系统会切换到传统的单光源渲染模式：添加 LEGACYSINGLELIGHTING 着色器定义，将光源计算限制为最多1个；使用固定的 uniform 变量传递单个光源的属性数据；并调用 legacyLightingValueInit() 初始化传统的单光源着色器参数。这种模式虽然性能更好，但只能渲染单个主要光源的效果。

使用单光源模式，在开发阶段调试光照效果或针对低端设备优化性能时非常有用；在生产环境中，对于需要复杂光照效果的场景如室内设计、多角色战斗等，应该保持默认的多光源模式以获得更好的视觉表现力。需要注意的是，多光源模式对显卡的纹理缓冲能力和计算性能有较高要求，在不支持浮点纹理的设备上会自动降级到单光源模式。

4.5 最大光源数量 maxLightCount

最大光源数量maxLightCount 用于控制场景中可以同时激活的最大光源数量。该配置默认为 32，表示在默认情况下，场景中最多只能有 32 个光源同时参与渲染计算。

在代码实现中，maxLightCount 首先会受到系统上限的限制，如果设置超过 2048 会被自动调整为 2048，并发出警告提示。其次，该值还会与光照集群配置（lightClusterCount）进行协同计算，确保每个集群区域能够合理分配光源资源，避免远距离集群区域忽略过多光源的情况。

当场景中的光源数量超过 maxLightCount 时，多余的光源会被放入备用队列（alternateLights）中，这些光源不会参与实际的渲染计算，但仍然保存在场景中以便后续管理。系统会在控制台输出警告信息，提醒开发者当前的光源数量已超过限制。

maxLightCount 的值会被用于多个关键环节：在多光源渲染系统的初始化阶段，它决定了光照纹理缓冲区的大小（width × maxLightCount）；在 GLSL 代码生成时，它被定义为 MAX_LIGHT_COUNT 宏，控制着色器中光源遍历循环的上限；同时在运行时的光源管理中，它作为添加新光源的判断阈值。

开发者可以根据项目需求调整 maxLightCount 的值：对于简单的场景，可以适当降低该值以节省内存和计算开销；对于复杂的室内场景或需要大量动态光源的游戏，可以适当提高该值以获得更好的光照效果。但需要注意的是，过高的 maxLightCount 会显著增加 GPU 的计算负担和内存占用，特别是在移动设备上可能导致性能问题。建议在不同目标平台上进行性能测试，找到视觉效果和运行性能的最佳平衡点。

4.6 光照集群数量 lightClusterCount

光照集群数量 lightClusterCount 用于定义光照集群（Light Clustering）技术的三维空间划分。该配置是一个 Vector3 类型的值，默认设置为 (12, 12, 12)，分别代表 X、Y、Z 三个轴向的聚类数量。

在光照集群系统中，相机视锥体空间被划分为一个三维网格：X 和 Y 轴将视口均匀划分为多个矩形区域，而 Z 轴则使用对数分布来划分深度范围，因为近处的物体需要更精细的光照计算，而远处物体对光照变化不那么敏感。这种划分方式确保了光照计算的效率和质量平衡。

lightClusterCount 的三个分量在系统中发挥着不同的作用：X 和 Y 值决定了屏幕空间的集群分辨率，影响每个像素点需要查询的光照数据量；Z 值不仅控制深度方向的集群数量，还直接影响每个集群区域能够容纳的最大区域光源数量，计算公式为 Math.floor(2048 / lightClusterCount.z - 1) * 4。

这些集群参数会被用于多个关键环节：在初始化阶段创建 Cluster 实例和相应的纹理缓冲区；在运行时根据相机参数动态计算集群平面位置；在 GLSL 代码生成时定义 CLUSTER_X_COUNT、CLUSTER_Y_COUNT 和 CLUSTER_Z_COUNT 宏常量，供着色器使用；在光源分配时决定每个集群区域能够处理的最大光源数量。

开发者可以根据项目需求调整 lightClusterCount 的值：对于需要精细光照控制的场景，可以适当增加 X 和 Y 值以获得更好的光照精度；对于大型室外场景，可以增加 Z 值以更好地处理不同距离的光源分布。但需要注意的是，每个分量的最大值被限制为 128，过高的集群数量会显著增加内存占用和计算开销。建议在不同设备上进行性能测试，平衡视觉质量和运行效率。

4.7 最大变形目标数量 maxMorphTargetCount

最大变形目标数量 maxMorphTargetCount 是 LayaAir 3D 引擎中变形目标（Morph Target）系统的数量限制配置，用于控制每个网格渲染器最多可以同时激活的变形目标数量。该配置默认为 32，表示在默认情况下，每个网格最多只能同时应用 32 个变形目标的混合效果。

变形目标是一种 3D 动画技术，通过预定义的顶点变形数据来实现平滑的网格变形效果，常用于面部动画、肌肉模拟、表情变化等需要精细控制的动画场景。每个变形目标包含一套完整的顶点位置、法线、切线等变形数据，多个变形目标可以通过权重混合来创建复杂的变形效果。

maxMorphTargetCount 的值在系统中发挥着多个关键作用：在网格渲染器初始化时，它决定了变形目标激活数据缓冲区的大小（maxMorphTargetCount × 4 个浮点数）；在 GLSL 代码生成时，它被定义为 MORPH_MAX_COUNT 宏常量，控制着色器中变形目标数组的声明大小；在运行时激活变形目标时，它作为上限来限制同时激活的目标数量，超过限制的目标会被忽略。

在着色器层面，maxMorphTargetCount 定义了 u_MorphActiveTargets 数组的大小，这个数组存储着每个激活变形目标的索引和权重信息。渲染时，顶点着色器会遍历所有激活的变形目标，根据权重对原始顶点数据进行线性插值计算，实现平滑的变形过渡效果。

开发者可以根据项目需求调整 maxMorphTargetCount 的值：对于需要精细面部动画的角色系统，可以适当提高该值以支持更多表情和肌肉变形；对于简单的网格变形需求，可以降低该值以节省内存和计算开销。但需要注意的是，过高的变形目标数量会显著增加 GPU 的顶点处理负担，特别是在移动设备上可能影响渲染性能。建议在目标平台上进行性能测试，平衡动画质量和运行效率。

5、杂项

在杂项里，主要是调试相关的功能项，如图5-1所示：

（图5-1）

5.1 显示统计信息

在 IDE 中，显示统计信息的作用是实时监控项目的运行状态和性能指标，包括帧率、渲染批次、顶点和三角形数量、内存使用情况以及渲染模式信息等，从而帮助开发者分析性能瓶颈、优化资源管理和调试渲染效果，提高项目运行效率和视觉体验。

勾选显示统计信息之后，如图5-2所示。

（图5-2）

如想了解更详细的统计信息面板上的参数，以及自定义统计信息，请查阅文档《性能统计与优化》。

5.2 显示 VConsole（移动端调试工具）

在移动端调试，通常需要联到电脑端的浏览器上。

如果开发者不需要断点，只是一些常用的日志打印、加载等查看等，可以开启显示VConsole，在移动端的浏览器查看时，会出现如图 5-3 所示的调试工具面板。

（图5-3）

注意：只支持移动端浏览器上开启VConsole

5.3 弹窗显示全局错误

如果捕获全局错误window.onerror，勾选弹窗显示全局错误可以弹窗抛出详细错误堆栈。例如，可以自定义一个全局错误，代码如下：

//自定义一个全局错误
let err = new Error("自定义的Error");
Laya.Browser.window.onerror(err.message, "", "", "", err);

运行时，就会弹窗抛出异常，效果如图5-4所示。

（图5-4）