Растительность

Трава, кусты и деревья, которые качаются на ветру, отклоняются от всего, что сквозь них проходит, и исчезают с расстоянием: модель, загруженная с foliage: true, получает шейдер растительности, а копии одного ассета делят один материал, так что тысячи растений рисуются дёшево. Это вариант семейства lightmap; землю, на которой они растут, даёт террейн.

  • качать траву и деревья на ветру
  • пригибать траву, когда сквозь неё идёт игрок
  • растворять траву вдали
  • менять скорость и направление ветра или устроить бурю
  • дать каждой копии растения чуть иной оттенок
  • удешевить отрисовку карточек листвы и травы

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

Обзор

TypeScript
// level.scene.ts — трава загружается как растительность; env.foliage — ветер уровня
import { Hero } from './hero'

export default defineScene({
  env: {
    foliage: { wind: { direction: [1, 0.3], speed: 6, gust: 0.4 }, touch: 0.6, variation: 0.35 },
  },
  nodes: {
    grass: { model: asset('./assets/grass.glb'), foliage: { fade: [30, 40] } },
    player: { mesh: { kind: 'capsule' }, position: [0, 1, 0], aspects: [use(Hero)] },
  },
})

// hero.ts — капсула раздвигает траву
export class Hero extends Aspect<'hero', Node> {
  onAttach(): void {
    Foliage.bend(this.node, 0.6)
  }
}

Загрузить модель как растительность — foliage: true

TypeScript
Model.load(src, { foliage: true }): Promise<Model>     // код
{ model: asset('./grass.glb'), foliage: true }          // узел файла сцены
{ model: asset('./grass.glb'), foliage: { fade: [30, 40] } }   // + затухание по расстоянию (ниже)

Модели растительности не нужны ни lightmap: true, ни свой прямоугольник в атласе: её запечённый свет — это свет земли под каждым пикселем (запечённый террейн), а без запекания её освещают фоновый свет неба сцены и солнце. Клоны наследуют вариант шейдера. lecodes assets scene сам помечает тип объекта из Unity как foliage: true, когда один из его материалов лежит в папке растительности или назван соответственно (Materials/Trees/…, M_Grass_01), — но никогда по режиму альфы; --foliage <re> задаёт такие типы явно.

Вариант выбирается для ассета целиком: каждый материал alpha-MASK (карточки) получает маскированный двойник, непрозрачные (стволы) — непрозрачный, и качаются оба.

TypeScript
// в коде: трава как растительность, которая исчезает дальше 40 м, и буря по требованию
const scene = new Scene()
scene.add(Light.sun())
const main = async () => {
  const grass = await Model.load(asset('./assets/grass.glb'), { foliage: true })
  Foliage.fade(grass, 30, 40)       // каждая копия grass.glb редеет с 30 м и пропадает дальше 40 м
  scene.add(grass)
  scene.open()
}
main()
const startStorm = () => Foliage.wind({ speed: 20, turbulence: 1, gust: 0.8 })

Всё, что задаёт Foliage, — состояние всего уровня, которое держит движок: ветер и опции вида действуют на каждую модель растительности, нынешнюю и будущую; изгибатели каждый кадр читаются по их текущим трансформам; затухание принадлежит ассету, так что его делят все копии этой модели.

Host-gated

хост, в чьей среде выполнения нет материала foliage, загружает модель через вариант lightmap, если она заодно статика лайтмапа (lightmap: true, статичный узел запечённой сцены), иначе — стандартным шейдером; хост без моста foliageSet* игнорирует любой вызов Foliage. У десктопного хоста есть и то и другое.

Растения качаются на ветру, освещение листвы — Foliage.configure / Foliage.wind

TypeScript
Foliage.configure(options: {
  wind?: FoliageWind | false   // ниже; false = штиль
  touch?: number        // м, на которые верхушка небольшого растения отклоняется от изгибателя в его центре; по умолчанию 0.6, 0 = нет
  variation?: number    // 0..1 разброс оттенка между копиями; по умолчанию 0.35
  sunWrap?: number      // 0..1 «обёрнутое» солнечное освещение (тонкие листья пропускают свет); по умолчанию 0.5
  shiver?: number       // × shiver drag каждого материала (собственное дрожание листьев); по умолчанию 1, 0 = нет
  translucency?: number // 0..1 солнце сквозь тонкий лист, освещённый сзади (крона в контровом свете светится); по умолчанию 0.35
  leafShadow?: number   // 0..1 какую долю тени от источника света принимает карточка листа (кора — всю); по умолчанию 0.6
  skyAo?: number        // 0..1 насколько запечённая повершинная видимость неба затемняет фоновый свет; по умолчанию 0.7
  canopy?: number       // 0..1 нормаль для освещения карточки: её собственная плоскость (0) … оболочка кроны (1); по умолчанию 0.7
  normalMap?: number    // сила карты нормалей карточек; по умолчанию 0.5
  edgeFade?: number     // карточка, видимая с ребра, растворяется на этой доле |N·V|; по умолчанию 0.15, 0 = нет
  coverage?: number     // alpha × (1 + coverage × mip level): далёкая крона не редеет; по умолчанию 0.25
}): void
Foliage.wind(wind: FoliageWind | false): void   // только ветер, вживую

type FoliageWind = {
  direction?: [x, z]    // по земле, движок нормализует; по умолчанию [1, 0.3]
  speed?: number        // м/с — постоянный наклон растений и скорость дрейфа поля; по умолчанию 8.3, 0 = неподвижно
  turbulence?: number   // 0..2 случайная доля скорости; по умолчанию 0.4
  gust?: number         // 0..1 сила порывов; по умолчанию 0.35
  gustSpeed?: number    // м/с, с которой движется узор порывов; по умолчанию 5.6
}

Ветер — это поле, а не синусоида: бегущее шумовое поле, которое читается у корня каждого растения, наклоняет растение целиком вокруг корня — угол растёт с расстоянием от корня, так что крона ели уходит дальше, чем травинка, — а более мелкое поле, читаемое в каждой вершине, шевелит листья (дрожь, shiver). Фиксированного периода нет: turbulence отклоняет растение от среднего ветра, а порывы идут по медленному третьему полю и бегут по уровню со скоростью gustSpeed. То, что у каждого растения своё, берётся из модели: drag, жёсткость, постоянный наклон и shiver drag его материалов лежат в extras материалов GLB (lecodes.wind, их пишет lecodes assets scene из Unity-материала), иначе — значение по умолчанию по размеру растения.

Каждое переданное поле заменяет текущее значение; остальные остаются. Блок env.foliage файла сцены проходит через configure до загрузки моделей. Всё это работает вживую — Foliage.wind({ speed: 20 }) из консоли устроит пробную бурю.

Note

вариант читает COLOR_0 GLB растительности как ДАННЫЕ, а не как оттенок: (видимость неба, впадины коры, 1, вес ветра). lecodes assets scene запекает его при импорте на каждом типе растительности (видимость неба из каждой вершины — внутренность кроны и ствол под ней получают меньше фонового света; вес ветра — тот, что задан в паке: пак деревьев запекает ствол 0 / хвою ~0.4, — иначе квадрат высоты над основанием растения). Дрожь взвешивается этим весом ветра; модель без цветов вершин не получает затенения и берёт вес по высоте: кончики двигаются, основание — никогда.

Note

покачивание идёт по реальному времени движка, поэтому не останавливается, когда игровые часы на паузе: меню паузы поверх качающегося леса — так задумано.

Трава, которая пригибается, когда сквозь неё идёт игрок — Foliage.bend

TypeScript
Foliage.bend(node: Node, radius = 0.7): () => void   // возвращает функцию снятия регистрации
Foliage.unbend(node: Node): void

Изгибатель — узел, чья текущая мировая позиция раздвигает растительность: капсула героя, враг, катящийся валун. Растение отклоняется целиком — у основания стоит на месте, у верхушки отклоняется полностью, — когда изгибатель подходит ближе radius к его пятну на земле. Движок измеряет каждый ассет при загрузке: растения ниже ~2 м отклоняются полностью, к ~5 м реакция сходит на нет, так что трава и кусты расступаются вокруг тебя, а дерево не скручивается, когда задеваешь его ствол.

Движок также следит за скоростью каждого изгибателя (сглаженной за ~0.2 с) и вблизи центра растения наклоняет его по направлению движения, а не прямо от изгибателя: куст, сквозь который ты бежишь, пригибается вперёд и выпрямляется позади тебя, а не перекидывается, когда ты проходишь его середину. Изгибатель, который неподвижно стоит внутри растения, оставляет его почти прямым.

Зарегистрировать можно сколько угодно узлов; каждый кадр действуют 8 ближайших к камере. Уничтоженный узел выбывает сам.

Трава, исчезающая вдали — Foliage.fade

TypeScript
Foliage.fade(model: Model, start: number, end: number): void   // метры от камеры; end 0 = нет

Между start и end карточки редеют (альфа тексель за текселем опускается ниже порога маски), а дальше end копия целиком уходит из кадра — LOD-проход убирает её из сцены, и на отрисовку она не тратится. Это для травяного покрова при свободной камере: трава и клевер на [30, 40], деревьям не нужно. Диапазон принадлежит ассету: его делят все копии этой модели, нынешние и будущие; в файле сцены foliage: { fade: [start, end] } на одном узле задаёт его для всех. Камере, которая никогда не видит дальше диапазона (игра с видом сверху), он ничего не даёт — копии вне экрана и так отсекаются.

Свой оттенок у каждой копии растения — variation

Разброс оттенка (variation) берётся в шейдере из хэша позиции каждой копии, а не из параметра на копию: копии одного ассета по-прежнему делят один экземпляр материала, и именно это позволяет движку дёшево рисовать их тысячами. Убавь его у растения, текстура которого уже содержит разброс цвета.

Дешёвые карточки листвы и травы — lecodes assets doctor --trim-cards

Карточка растительности — это в основном прозрачные тексели, которые маскированный шейдер отбрасывает уже после расчёта, и на уровне из тысяч карточек на этот впустую закрашенный fill и уходит кадр. --trim-cards [--trim-margin N] обрезает каждый alpha-MASK-квад до прямоугольника его непрозрачных текселей (+ N текселей, по умолчанию 2) и выбрасывает пустые квады — на вид ничего не меняется. Он читает базовый цвет из PNG/JPEG, так что запускай его вместе с --ktx2, а не после (lecodes assets scene так и делает, на каждом типе).

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

  • Модель с foliage: true, чьи материалы в логе хоста значатся как стандартные ([glb] material … -> ubershader), получила стандартный шейдер: либо этот вариант не принимает материал (правила какие материалы и меши принимает запекание — строка [lightmap] … называет, чего не хватает), либо у хоста нет этого варианта. Ошибки в файле сцены тут нет.
  • Foliage.bend на модели героя, а не на капсуле его контроллера, следует за визуальным корнем, который может отставать от капсулы или опережать её; регистрируй узел, который двигает физика.

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

  • lightmap.md — семейство, к которому относится этот вариант: запечённые тени, световой объём, варианты
  • terrain.md — земля, чей запечённый свет берут растения
  • model.md — опции Model.load, клоны, LOD
  • scene-files.md — foliage на узле, env.foliage