Mesh
Рисуемый 3D-узел, построенный из геометрии: примитивные формы (Mesh.box(), Mesh.sphere(), …)
и Mesh.from() для своей Geometry. Это Node (трансформ,
иерархия, события, аспекты). GLB-модель — это Model.load; одна и та же геометрия сотни
раз — это InstancedMesh.
- добавить в 3D-сцену куб, шар, цилиндр, капсулу или плоскость
- сделать плоский пол или плоскость земли
- показать свою процедурную форму как меш
- поменять цвет или материал меша
- дёшево нарисовать сотни одинаковых объектов (деревья, монеты, ящики)
- нарисовать маркер или гизмо поверх всего
- включить или выключить тени меша
Платформы: Mesh — на любом хосте; InstancedMesh — на iOS, Android, десктопе, в веб-плеере и
приложении-вьюере le.codes; не в вебе (Web Lite) и не в headless-тестах, где он один раз
предупреждает и ничего не рисует.
Обзор
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:
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
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:
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
mesh.material // слот 0 — get/set, у Mesh никогда не null
mesh.material.color = '#e33' // перекрасить его текущий материал (только запись)
mesh.setMaterial(material, index = 0): this // чейнится, любой слот
mesh.getMaterial(index = 0): Material | null // null, если слот пуст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-тестах (см. строку
о платформах выше).
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)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).
eulerAngles в setAt сейчас переводится в радианы дважды — [0, 90, 0] поворачивает
инстанс на ~1.6°, а не на 90°. Передавай вместо него rotation: Quat.fromEuler(x, y, z) (в градусах).
Для обломков, которые сами летят, отскакивают и исчезают, бери меш-частицы
(Particles({ mesh }), см. частицы) — они симулируются; InstancedMesh —
для того, что расставляешь ты.
Тени и отсечение: castShadows, receiveShadows, culling
mesh.castShadows = true // только запись; по умолчанию true
mesh.receiveShadows = true // только запись; по умолчанию true
mesh.culling = false // только запись; отключить отсечение по фрустуму (рисовать всегда)Это также опции фабрик (Mesh.box({ castShadows: false })); InstancedMesh задаёт оба флага теней
через setShadows(cast, receive).
это только сеттеры — прочитать значение нельзя. Задавай при создании (опции фабрики) или храни свой флаг.
Маркер поверх всего: renderPriority
mesh.renderPriority = 7 // только запись; грубый порядок отрисовки 0 (первым) … 7 (последним), по умолчанию 4renderPriority — приоритет отрисовки в 3D-движке: внутри одного приоритета непрозрачное
сортируется спереди назад, а смешиваемое — сзади вперёд; приоритеты рисуются по порядку. Он нужен для
оверлея — гизмо, маркера — с материалом depthTest: false (см. Material): в
приоритете 7 его не перекроет ничто нарисованное позже. Это также опция фабрик
(Mesh.box({ renderPriority: 7 })). На хосте он необязателен: старый хост один раз предупредит и
оставит дефолт.
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)Подводные камни
// ✗ ждать, что плоскость по умолчанию ляжет плашмя
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 - Соглашения — единицы, градусы, семантика значений