【Three.js】第十章 Debug UI 调试界面

10.Debug UI 调试界面

介绍

每个创意项目的一个重要方面是使调试变得容易并调整您的代码。开发人员（您）和从事该项目的其他参与者（如设计师甚至客户）必须能够更改尽可能多的参数。
你必须考虑到这一点，以便他们找到完美的颜色、速度、数量等，以获得最佳体验。您甚至可能会得到看起来很棒的意想不到的结果。
首先，我们需要一个调试 UI。
虽然您可以使用 HTML / CSS / JS 创建自己的调试 UI，但已经有多个现成的库：

• 数据.GUI
• 控制面板
• 控制套件
• 乌尔
• 调整面板
• 归化
• 欧伊

所有这些都可以实现我们想要的UI界面，但我们将使用最流行的一个，即dat.GUI。你也可以尝试其他的。

Dat.GUI漏洞

Dat.GUI 已经很长时间没有更新了，如果我们将库添加到我们的项目中，可能会出现一些漏洞警告。
幸运的是，有一个名为lil-gui 的替代库可以用作“dat.gui 的直接替代品”。这意味着我们可以像使用 dat.gui 一样使用它。
本课程大部分是使用 dat.gui 编写和录制的，文本、屏幕截图和视频将参考 dat.gui，但您应该安装和使用 lil-gui（这就是我们将在下面做的）。
下一课的入门文件将使用 lil-gui。

例子

你可以在我的作品集中找到一个很好的调试 UI 示例。#debug此 UI 仅在您添加到 URL时显示。
https://bruno-simon.com/#debug

您可以调整重力、颜色、速度、元素位置等。
虽然我花了很多时间来创建所有这些调整，但如果没有它，游戏就会显得不那么平衡。

设置

在启动器中，我们有我们的多维数据集，但依赖项不包括 Dat.GUI。我们将添加它并进行一些调整。

如何实现Dat.GUI

要将 Dat.GUI 添加到我们的项目中，我们可以使用 Node.js 提供的依赖管理器，称为 NPM（就像我们在上一课中为 GSAP 所做的一样）。
在您的终端中（当服务器未运行或在同一文件夹上使用另一个终端窗口时）运行npm install --save lil-gui
如前所述，我们正在安装 lil-gui 而不是 dat.gui，但在本课程的其余部分我们将把它称为 dat.gui。
Dat.GUI 现在在文件夹中可用/node_modules/，我们可以将其导入我们的script.js. 不要忘记重新启动服务器：

import './style.css'
import * as THREE from 'three'
import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js'
import gsap from 'gsap'
import * as dat from 'lil-gui'

// ...

您现在可以实例化 Dat.GUI：

/**
 * Debug
 */
const gui = new dat.GUI()

这将导致屏幕右上角出现一个空白面板。
您可以向该面板添加不同类型的元素：

• Range — 对于具有最小值和最大值的数字
• 颜色— 用于各种格式的颜色
• 文本——用于简单文本
• 复选框——用于布尔值（true或false）
• 选择— 从值列表中进行选择
• 按钮——触发功能
• 文件夹——如果你有太多元素，用来组织你的面板

让我们看看其中的一些。

添加元素

要将元素添加到面板，您必须使用gui.add(...). 第一个参数是一个对象，第二个参数是您要调整的对象的属性。您需要在创建相关对象后对其进行设置：

gui.add(mesh.position, 'y')

面板中应出现一个范围。尝试改变它并观察立方体相应地移动。
要指定最小值、最大值和精度，您可以在参数中设置它们：

gui.add(mesh.position, 'y', - 3, 3, 0.01)

或者您可以使用方法min(...)，max(...)并在方法step(...)之后直接链接add(...)：

gui.add(mesh.position, 'y').min(- 3).max(3).step(0.01)

如果你不喜欢在一行中链接太多方法，你可以简单地添加换行符：

gui
    .add(mesh.position, 'y')
    .min(- 3)
    .max(3)
    .step(0.01)

要更改标签，请使用以下方法name(...)：

gui
    .add(mesh.position, 'y')
    .min(- 3)
    .max(3)
    .step(0.01)
    .name('elevation')

Dat.GUI 将自动检测您想要调整的属性类型并使用相应的元素。一个很好的例子是Object3D 的visible属性。这是一个布尔值，将隐藏对象：false

gui.add(mesh, 'visible')

如您所见，因为该visible属性是一个布尔值,所以Dat.GUI 推导选择了一个复选框。
我们可以对材料的属性wireframe做同样的事情：

gui.add(material, 'wireframe')

颜色

处理颜色有点困难。
首先，我们需要使用addColor(...)instead of add(...)。这是因为 Dat.GUI 无法仅根据属性的类型来判断您是想调整文本、数字还是颜色。
其次，您必须创建一个在其属性中包含颜色的中间对象，并在您的材质中使用该属性。这是因为 Three.js 材料没有像#ff0000.
实际上，因为我们使用的是lil-gui而不是Dat.GUI，所以我们可以直接在素材上使用addColor(...)。但由于我们将要看到的技术可以用于其他情况，所以我们也实现一遍。
在该部分之后的代码开头创建一个变量parameter：

const parameters = {
    color: 0xff0000
}

然后，在实例化您的gui变量后，添加以下调整：

gui.addColor(parameters, 'color')

您应该在面板中看到一个颜色选择器。问题是改变这种颜色不会影响材质。它确实改变了变量parameter的属性color，但我们还没有在我们的材料中使用该变量。
为了解决这个问题，我们需要 Dat.GUI 在值发生变化时提醒我们。我们可以通过链式调用material.color.set(...).onChange(...)该方法使用更新材质颜色来做到这一点。这种方法非常有用，因为您可以使用多种格式，例如'#ff0000', '#f00',0xff0000甚至'red':

const parameters = {
    color: 0xff0000
}

// ...

gui
    .addColor(parameters, 'color')
    .onChange(() =>
    {
        material.color.set(parameters.color)
    })

目前，0xff0000颜色在两个地方指定：在parameters对象中和在material.
虽然这没什么大不了的，但如果我们想改变颜色，我们必须在这两个地方进行。
让我们简单地通过使用 parameters.color材质中的属性来解决这个问题：

const material = new THREE.MeshBasicMaterial({ color: parameters.color })

功能

要触发一个函数，比如颜色值，我们必须将该函数添加到一个对象中。我们可以使用parameters之前创建的对象添加一个 spin属性，该属性包含使立方体动画化的函数：

const parameters = {
    color: 0xff0000,
    spin: () =>
    {
        gsap.to(mesh.rotation, { duration: 1, y: mesh.rotation.y + Math.PI * 2 })
    }
}

再一次，我们可以gui在实例化后将调整添加到我们的：

gui.add(parameters, 'spin')

您应该会看到一个spin按钮，单击它会导致您的立方体进行 360 度旋转。

如何以及何时使用它

我们将在下一个练习的特定时刻使用我们的调试面板。但您可以随意添加任意数量的调整。这是练习和开始构建一些有创意的东西的绝佳方式。
我建议您在开发过程时就进行微调。如果您考虑在项目结束时添加DebugUI去微调，可能你就不会去调整这个项目了（作者应该想说开发微调这种态度更好，开发完了耦合太高了你就懒得调了）。