Mesh

Рисуемый 3D-узел, построенный из геометрии: примитивные формы (Mesh.box(), Mesh.sphere(), …) и Mesh.from() для своей Geometry. Это Node (трансформ, иерархия, события, аспекты). GLB-модель — это Model.load; одна и та же геометрия сотни раз — это InstancedMesh.

  • добавить в 3D-сцену куб, шар, цилиндр, капсулу или плоскость
  • сделать плоский пол или плоскость земли
  • показать свою процедурную форму как меш
  • поменять цвет или материал меша
  • дёшево нарисовать сотни одинаковых объектов (деревья, монеты, ящики)
  • нарисовать маркер или гизмо поверх всего
  • включить или выключить тени меша

Платформы: Mesh — на любом хосте; InstancedMesh — на iOS, Android, десктопе, в веб-плеере и приложении-вьюере le.codes; не в вебе (Web Lite) и не в headless-тестах, где он один раз предупреждает и ничего не рисует.

Обзор

TypeScript
const scene = new Scene()

const ground = Mesh.plane({
  material: Material.lit({ color: '#556655' }),
  normal: [0, 1, 0],                    // лицом вверх
  scale: 20,
  receiveShadows: true,
})
const crate = Mesh.box({
  material: Material.lit({ color: '#b5854b' }),
  size: [1, 1, 1],
  position: [0, 0.5, 0],
  castShadows: true,
})
scene.add(Light.sun(), ground, crate)
scene.open()

Куб, шар, цилиндр, капсула или плоскость: Mesh.box, Mesh.sphere, …

Куб (box), шар (sphere), цилиндр, капсула или плоскость добавляются в 3D-сцену одним вызовом. Все фабрики делят одни базовые опции и возвращают готовый Mesh:

TypeScript
type MeshOptions = {
  material?: Material          // по умолчанию Material.unlit()
  position?: Vec3Like
  eulerAngles?: Vec3Like       // градусы
  scale?: Vec3Like | number    // число = равномерно
  name?: string
  castShadows?: boolean        // по умолчанию true
  receiveShadows?: boolean     // по умолчанию true
  renderPriority?: number      // 0 … 7, по умолчанию 4 — см. «Маркер поверх всего»
}

Mesh.box(options?: MeshOptions & {
  size?: Vec3Like | number     // полные длины рёбер в мировых единицах; по умолчанию 1 (единичный куб)
})
Mesh.sphere(options?: MeshOptions & {
  radius?: number              // по умолчанию 0.5 (единичный диаметр)
  widthSegments?: number       // по умолчанию 32
  heightSegments?: number      // по умолчанию 32
})
Mesh.cylinder(options?: MeshOptions & {
  radius?: number              // по умолчанию 0.5; высота фиксирована на 1 (Y: -0.5..0.5)
  radiusTop?: number           // по умолчанию = radius (конус: поставь 0)
  radiusBottom?: number        // по умолчанию = radius
  edges?: number               // по умолчанию 32
  smooth?: boolean             // по умолчанию true — гладкие боковые нормали; false = гранёные
})
Mesh.capsule(options?: MeshOptions & {
  radius?: number              // по умолчанию 0.5
  length?: number              // между центрами двух полусфер; по умолчанию 1 (0 = сфера) — полная высота length + 2·radius
  widthSegments?: number       // вокруг оси; по умолчанию 32
  capSegments?: number         // колец на полусферу; по умолчанию 8
})
Mesh.plane(options?: MeshOptions & {
  normal?: Vec3Like            // куда смотрит квад 1×1; по умолчанию [0, 0, 1] (к камере)
})
  • Дефолты единичного размера и с центром в начале координат: box 1×1×1, sphere диаметром 1, cylinder высотой 1 / диаметром 1, capsule вдоль Y (2 м высотой при дефолтах), plane 1×1. Размер задаётся через size (box), radius / length или scale — у плоскости нет опции размера, только scale.
  • box.size запекается в буферы геометрии; scale — трансформ узла. Рисуются они одинаково, а запечённый size — это то, что измеряет авто-бокс Shape; годится любой вариант, потому что авто-бокс тоже умножает на мировой масштаб.

Плоский пол или плоскость земли: Mesh.plane({ normal })

Плоскость — это квад 1×1, по умолчанию стоящий вертикально лицом к +Z. Для пола направь его нормаль вверх и отмасштабируй — Mesh.plane({ normal: [0, 1, 0], scale: 20 }), как в обзоре.

Меш из своей геометрии: Mesh.from, setGeometry

TypeScript
new Mesh(geometry?: Geometry, material?: Material)
Mesh.from(geometry: Geometry, options?: MeshOptions): Mesh
mesh.setGeometry(geometry: Geometry): this      // перестроить буферы на месте
mesh.geometry                                   // Geometry | undefined — буферы, из которых построен этот меш

Geometry хранит сырые буферы (vertices, normals, indices, uv и необязательный uv1 — UV-набор для лайтмапы, без перекрытий; билдеры box и cylinder его заполняют, а uv плоскости уже им является, см. лайтмапы). Построй её из билдеров примитивов (Geometry.box(size), .sphere(opts), .cylinder(opts), .capsule(opts), .plane(opts) — те же опции, что у фабрик выше) и измени форму или собери из своих Float32Array — см. Geometry:

TypeScript
const geo = Geometry.cylinder({ radiusTop: 0, edges: 6 })   // шестигранный конус
  .scale(1, 3, 1)                                           // меняет буфер вершин
  .translate(0, 1.5, 0)                                     // сдвинуть пивот к основанию
const spike = Mesh.from(geo, { material: Material.lit(), position: [2, 0, 0] })

Буферы заливаются, когда меш строится: правка Geometry после этого ничего не меняет, пока mesh.setGeometry(geo) их не перестроит, — узел, его трансформ, материал и флаги рендера остаются. geometry.kind = 'triangles' | 'edges' | 'vertices' переключает режим отрисовки (линии / точки, см. Geometry); задай его до построения. Геттер geometry — то, что авто-бокс Shape измеряет для формы коллизии (см. физику).

Цвет или материал меша: mesh.material

TypeScript
mesh.material                                  // слот 0 — get/set, у Mesh никогда не null
mesh.material.color = '#e33'                   // перекрасить его текущий материал (только запись)
mesh.setMaterial(material, index = 0): this    // чейнится, любой слот
mesh.getMaterial(index = 0): Material | null   // null, если слот пуст
TypeScript
const scene = new Scene()
const ball = Mesh.sphere({ material: Material.lit({ color: '#3a7' }), position: [0, 1, 0] })
scene.add(Light.sun(), ball)
scene.open()

ball.material.color = '#e33'                                  // перекрасить текущий материал
ball.material = Material.lit({ color: '#888', metallic: 1 })  // или дать другой

У примитивов один слот материала. Не передав материал фабрике, получишь дефолтный Material.unlit() (плоский, без освещения, без отклика на свет). Материал, общий для нескольких мешей, перекрашивает их все. Встроенные материалы и их опции: Material.

Сотни копий: InstancedMesh

Одна и та же геометрия сотни или тысячи раз (трава, ящики, монеты, обломки, толпа одинаковых пропсов): один InstancedMesh с трансформом на каждый инстанс вместо отдельного Mesh на каждую копию. Инстансинг аппаратный — движок применяет матрицу каждого инстанса, работает любой обычный материал, и стоит это один draw call на 64 инстанса (8 на WebGL), причём каждый такой чанк отсекается по фрустуму по своим границам. Не в вебе (Web Lite) и не в headless-тестах (см. строку о платформах выше).

TypeScript
const scene = new Scene()
scene.add(Light.sun())
scene.open()

const crates = new InstancedMesh(Geometry.box(0.8), 500, {
  material: Material.lit({ color: '#b5854b', roughness: 0.8 }),
  castShadows: true,
})
for (let i = 0; i < 500; i++) {
  crates.setAt(i, { position: [ (i % 25) * 1.2, 0.4, Math.floor(i / 25) * -1.2 ], rotation: Quat.fromEuler(0, i * 37, 0) })
}
crates.commit()            // одна заливка всего, что задано с прошлого commit
scene.add(crates)

class Bob extends Aspect<'bob', InstancedMesh> {
  private t = 0
  update(dt: number) {     // правь, потом commit раз за кадр
    this.t += dt
    this.node.setAt(3, { position: [ 3.6, 1 + Math.sin(this.t), 0 ] }).commit()
  }
}
crates.aspect(Bob)
TypeScript
new InstancedMesh(geometry: Geometry, count: number, options?: MeshOptions)   // count фиксирован (≥ 1)
crates.count                                                // ёмкость (только чтение)
crates.setAt(i, { position?, rotation?, eulerAngles?, scale? })   // локально к узлу; опущенное = единичное
crates.setMatrixAt(i, mat4)                                 // по столбцам, локально
crates.setMatrices(float32, offset = 0)                     // пачкой, по 16 float на каждый, начиная с инстанса `offset`
crates.hideAt(i)                                            // нулевая матрица — для него ничего не рисуется
crates.matrixAt(i)                                          // → Mat4 (копия того, что хранится)
crates.commit(): this                                       // залить грязный диапазон
crates.dirty                                                // есть что-то незакоммиченное?
crates.material = Material.lit()                            // get/set, по умолчанию Material.unlit()
crates.setShadows(cast: boolean, receive = cast): this      // для всех инстансов сразу

Каждый инстанс скрыт (нулевая матрица), пока ты его не расставишь. rotation — кватернион и побеждает eulerAngles; setAt / setMatrixAt / hideAt бросают RangeError за пределами 0 … count-1. Правки буферизуются на стороне JS; в движок ничего не попадает до commit(). Собственный трансформ узла применяется поверх каждого инстанса — двигай InstancedMesh, чтобы сдвинуть всё поле. Из геометрии используются только треугольники, нормали и uv (не kind, uv1 и не colors).

Note

eulerAngles в setAt сейчас переводится в радианы дважды — [0, 90, 0] поворачивает инстанс на ~1.6°, а не на 90°. Передавай вместо него rotation: Quat.fromEuler(x, y, z) (в градусах).

Для обломков, которые сами летят, отскакивают и исчезают, бери меш-частицы (Particles({ mesh }), см. частицы) — они симулируются; InstancedMesh — для того, что расставляешь ты.

Тени и отсечение: castShadows, receiveShadows, culling

TypeScript
mesh.castShadows = true      // только запись; по умолчанию true
mesh.receiveShadows = true   // только запись; по умолчанию true
mesh.culling = false         // только запись; отключить отсечение по фрустуму (рисовать всегда)

Это также опции фабрик (Mesh.box({ castShadows: false })); InstancedMesh задаёт оба флага теней через setShadows(cast, receive).

Note

это только сеттеры — прочитать значение нельзя. Задавай при создании (опции фабрики) или храни свой флаг.

Маркер поверх всего: renderPriority

TypeScript
mesh.renderPriority = 7      // только запись; грубый порядок отрисовки 0 (первым) … 7 (последним), по умолчанию 4

renderPriority — приоритет отрисовки в 3D-движке: внутри одного приоритета непрозрачное сортируется спереди назад, а смешиваемое — сзади вперёд; приоритеты рисуются по порядку. Он нужен для оверлея — гизмо, маркера — с материалом depthTest: false (см. Material): в приоритете 7 его не перекроет ничто нарисованное позже. Это также опция фабрик (Mesh.box({ renderPriority: 7 })). На хосте он необязателен: старый хост один раз предупредит и оставит дефолт.

TypeScript
const scene = new Scene()
scene.add(Light.sun(), Mesh.box({ material: Material.lit(), position: [0, 0.5, 0] }))
scene.open()

const marker = Mesh.sphere({
  material: Material.unlit({ color: '#ff0', depthTest: false }),  // игнорировать то, что впереди
  radius: 0.15,
  position: [0, 0.5, 0],     // внутри куба, но всё равно виден
  renderPriority: 7,         // рисуется последним: ничто его не перекроет
  castShadows: false,
})
scene.add(marker)

Подводные камни

TypeScript
// ✗ ждать, что плоскость по умолчанию ляжет плашмя
Mesh.plane({ scale: 10 })                      // стоит вертикально, лицом к +Z
// ✓ для пола направь нормаль вверх
Mesh.plane({ scale: 10, normal: [0, 1, 0] })

// ✗ изменение СОХРАНЁННОЙ копии трансформа (семантика значений — см. соглашения)
const p = crate.position; p.y = 2
// ✓ (crate.position.y = 2, записанное напрямую, компилируется в это)
crate.y = 2

Смотрите также

  • Node — трансформ, иерархия, события (унаследованы)
  • Geometry — буферы, билдеры, файлы геометрии
  • Material — встроенные материалы и свои шейдеры
  • Model — GLB-импорты (другой вид рисуемого узла)
  • Физика и формы — авто-боксы Shape из mesh.geometry
  • Соглашения — единицы, градусы, семантика значений