Node2D

Базовый узел 2D-сцены — трансформ, который ничего не рисует. Sprite (картинка), Text2D (текст), Path2D (линии и фигуры) и Tilemap расширяют его, поэтому всё здесь работает и на них. Голый Node2D — группирующий родитель, маркер или точка спавна, невидимый физический / триггерный объект.

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

Платформы: iOS, Android, десктоп, веб (Web Lite), веб-плеер, приложение-вьюер le.codes; нет в варианте движка 3d / core у приложения, собранного через lecodes app, — там new Node2D() бросает исключение. Headless-тесты двигают узлы, но ничего не рисуют.

Обзор

TypeScript
async function main() {
  const scene = new Scene2D()
  const wheel = await Texture2D.load(asset('./wheel.png'))

  const door = new Node2D()
    .aspect(Shape2D, { box: [16, 32] })
    .aspect(Trigger2D)
  door.position = [320, 64]
  door.addEventListener('enter', other => console.log('entered by', other.name))

  const cart = new Node2D()
  const wheelA = new Sprite({ texture: wheel, position: [-10, 0] })
  const wheelB = new Sprite({ texture: wheel, position: [10, 0] })
  cart.add(wheelA, wheelB)                  // дети двигаются вместе с тележкой
  cart.x += 40
  scene.add(door, cart)                     // тележка приносит свои колёса: сцена рисует поддеревья
  scene.open()
}
main()

Сдвиг, поворот и масштаб узла: position, rotation, scale, порядок отрисовки

Позиция, поворот и масштаб — локальные относительно родителя, Y вверх; 1 единица = 1 логический px при зуме камеры 1. renderPriority / z задают порядок отрисовки (вместе с ySort сцены, см. что рисуется поверх), visible прячет узел и всё, что под ним. См. соглашения.

TypeScript
node.x, node.y                     // сеттеры одной оси
node.position = [120, 64]          // Vec2Like; геттер возвращает свежий Vec2
node.rotation = 45                 // градусы, против часовой
node.scale = 2                     // число (равномерно) или Vec2Like
node.renderPriority = 6            // грубый порядок отрисовки 0..7 (по умолчанию 4); больше — поверх
node.z = 5                         // порядок внутри одного renderPriority (больше — поверх); по умолчанию 0
node.visible = false               // прячет узел и всё его поддерево
node.name = 'door'                 // необязательная обычная JS-метка (файлы сцен пишут сюда ключи узлов)
node.id                            // id нативной сущности (только чтение; 0 после уничтожения)
Note

геттеры position и scale возвращают свежие копии. Прямая запись node.position.x = 3 компилируется в node.x = 3 и работает; копия, которую ты сначала сохранил, остаётся копией (const p = node.position; p.x = 3 — тихий no-op). См. семантику значений в математике.

Note

явный Shape2D (box, circle, …) игнорирует scale — увеличенный спрайт сохраняет объявленный тобой коллайдер. Только автоформа Shape2D {} меряет size × scale, один раз, когда строится коллайдер. См. 2D-физику.

Анимация спрайта или узла к новой позиции, повороту или масштабу: animateTo

Сдвинуть, закрутить или увеличить спрайт (или любой узел) за время: animateTo анимирует от текущих значений, animateFrom — от заданных обратно к текущим.

TypeScript
node.animateTo({ x?, y?, position?, rotation?, scale?, duration?, delay?, easing?, loop?, clock? }): Animation
node.animateFrom({ ...the same }): Animation    // от заданных значений к текущим

duration / delay — миллисекунды (по умолчанию 225 мс, ease-in-out); rotation — градусы; массив значений — список ключевых кадров (для position / scale — массив векторов). Возвращает хэндл Animation (pause, resume, cancel, finished, …); Sprite добавляет opacity и color — см. что анимирует каждая цель.

TypeScript
async function main() {
  const scene = new Scene2D()
  const tex = await Texture2D.load(asset('./coin.png'))
  const coin = new Sprite({ texture: tex, position: [0, -100] })
  scene.add(coin)
  scene.open()
  // поднимается к центру, делая один оборот; await .finished, чтобы связать следующий шаг
  await coin.animateTo({ y: 0, rotation: 360, duration: 600, easing: 'outBack' }).finished
  coin.animateTo({ scale: 1.5, duration: 200 })
}
main()
Note

анимации узлов по умолчанию идут по часам 'game', но эти часы следуют за Time.scale / Time.paused только когда существует 3D Scene — в чисто 2D-приложении анимация узла продолжает идти, пока игра на паузе (см. часы).

Note

анимация пишет только отрисовываемый трансформ — до физического тела или персонажа она не доходит. Анимированный узел с телом оставляет свой коллайдер позади; тела ставь через position.

Сгруппировать спрайты, чтобы они двигались вместе: родитель и дети, add / setParent

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

TypeScript
node.parent                              // Node2D | null (можно присваивать — сахар для setParent)
node.children                            // readonly Node2D[]
node.add(...children: Node2D[]): this    // прикрепить (каждый сохраняет свой мировой трансформ)
node.remove(child: Node2D): this         // отсоединить прямого ребёнка → корень, сохранив мировой трансформ
node.setParent(parent: Node2D | null, keepWorld = true): this

setParent с keepWorld: true (по умолчанию) пересчитывает локальный трансформ, чтобы ничего не сдвинулось на экране; передай false, чтобы сохранить локальные значения и встать в систему координат нового родителя. Сам узел и его потомки в родители не годятся (циклов нет).

Note

ребёнок идёт туда же, где его родитель: подвешенный под узел в сцене, он входит в эту сцену и рисуется; под узел вне сцены — покидает её; отсоединённый (setParent(null), remove), остаётся в своей сцене корнем. Скрытый родитель скрывает и его. А parent читается как null, пока родитель — свободный корень (ещё не в сцене и не под другим узлом).

Место ребёнка в мире: worldPosition, worldToLocal, localToWorld

position ребёнка задан относительно родителя; эти члены дают его место в мире и переводят точку между миром и собственным пространством узла. Точка экрана (тап) идёт через камеру: screenToWorld.

TypeScript
node.worldPosition                    // Vec2 — собирает всех предков
node.worldToLocal(p: Vec2Like): Vec2  // мировая точка → локальное пространство этого узла
node.localToWorld(p: Vec2Like): Vec2  // и обратно

Двигать узел с физическим телом

Как только у узла есть dynamic- или kinematic-тело Physics2D — или CharacterController2D, — его трансформом владеет нативный шаг. Чтение node.position / worldPosition всегда корректно: узел автоматически пересинхронизируется с нативной стороной. Не пиши node.position каждый кадр; динамическим телом управляй через velocity / applyImpulse, персонажем — через move().

Запись position или rotation направляется тому, кто владеет узлом — телу, сенсору или персонажу, — поэтому телепортирует коллайдер вместе с ним. Так ставят кинематическое тело, и это пришло на смену старым physics.moveTo / trigger.moveTo.

Note

направляется только ПРЯМАЯ запись. Тело или сенсор, подвешенные под движущийся узел, за ним не следуют — держи их на корневых узлах и пиши их собственный трансформ.

Тапы, столкновения и события клипов на узле: addEventListener

TypeScript
node.addEventListener(channel, callback)
node.removeEventListener(channel, callback)
Канал Срабатывает, когда Аргументы колбэка
click указатель отпущен над физической формой этого узла ClickEvent
touchstart указатель нажат на его форме — ev.track() для перетаскиваний TouchStartEvent
enter / exit физический контакт / перекрытие сенсора началось / закончилось другой Node2D, контакт { point, normal, speed }
loopReached зацикленный клип SpriteAnimation пошёл на новый круг имя клипа (строка)
completed незацикленный клип завершился имя клипа (строка)

click / touchstart требуют, чтобы в узел можно было попасть: Shape2D плюс Physics2D, Trigger2D или CharacterController2D. См. события указателя и жесты и пикинг в 2D-физике; аргумент контакта описан в событиях enter / exit.

Удалить узел с детьми насовсем: destroy

TypeScript
node.destroy(): void

Освобождает нативную сущность и всё её поддерево — дети уходят вместе с родителем, как в 3D- и UI-деревьях (чтобы сохранить ребёнка, сначала отсоедини его через setParent(null)). Сначала отсоединяется каждый аспект в поддереве, так что тела освобождаются. Узел, который ты так и не добавил в сцену и на который перестал ссылаться, освобождается сам. После этого node.id читается как 0, а записи до движка больше не доходят.

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

TypeScript
// ✗ изменение СОХРАНЁННОЙ копии трансформа
const p = node.position; p.x = 3
// ✓ сеттер одной оси или присвоение целого значения (node.position.x = 3 компилируется в node.x = 3)
node.x = 3

// ✗ борьба с шагом физики — трансформ динамического тела пишется каждый кадр
crate.y += 2                          // в update(dt)
// ✓ управляй телом
crate.physics.velocity = [0, 120]

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