Node2D
Базовый узел 2D-сцены — трансформ, который ничего не рисует. Sprite (картинка),
Text2D (текст), Path2D (линии и фигуры) и
Tilemap расширяют его, поэтому всё здесь работает и на них. Голый Node2D —
группирующий родитель, маркер или точка спавна, невидимый физический / триггерный объект.
- двигать, поворачивать или масштабировать спрайт
- рисовать узел перед другими или за ними, прятать его
- сгруппировать спрайты, чтобы они двигались вместе (родитель и дети)
- переводить точку между локальным пространством узла и миром
- анимировать узел к новой позиции, повороту или масштабу
- двигать узел с физическим телом, не борясь с физикой
- реагировать на тапы, столкновения и завершение анимаций на узле
- удалить узел вместе с детьми насовсем
Платформы: iOS, Android, десктоп, веб (Web Lite), веб-плеер, приложение-вьюер le.codes;
нет в варианте движка 3d / core у приложения, собранного через lecodes app, — там
new Node2D() бросает исключение. Headless-тесты двигают узлы, но ничего не рисуют.
Обзор
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 прячет узел и всё, что под ним.
См. соглашения.
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 после уничтожения)геттеры position и scale возвращают свежие копии. Прямая запись node.position.x = 3
компилируется в node.x = 3 и работает; копия, которую ты сначала сохранил, остаётся копией
(const p = node.position; p.x = 3 — тихий no-op). См.
семантику значений в математике.
явный Shape2D (box, circle, …) игнорирует scale — увеличенный спрайт сохраняет
объявленный тобой коллайдер. Только автоформа Shape2D {} меряет size × scale, один раз, когда
строится коллайдер. См. 2D-физику.
Анимация спрайта или узла к новой позиции, повороту или масштабу: animateTo
Сдвинуть, закрутить или увеличить спрайт (или любой узел) за время: animateTo анимирует от текущих
значений, animateFrom — от заданных обратно к текущим.
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 — см.
что анимирует каждая цель.
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()анимации узлов по умолчанию идут по часам 'game', но эти часы следуют за Time.scale /
Time.paused только когда существует 3D Scene — в чисто 2D-приложении анимация узла продолжает
идти, пока игра на паузе (см. часы).
анимация пишет только отрисовываемый трансформ — до физического тела или персонажа она не
доходит. Анимированный узел с телом оставляет свой коллайдер позади; тела ставь через position.
Сгруппировать спрайты, чтобы они двигались вместе: родитель и дети, add / setParent
Положи спрайты под родительский узел — и они двигаются, поворачиваются и масштабируются вместе с ним: трансформ ребёнка задан относительно родителя.
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): thissetParent с keepWorld: true (по умолчанию) пересчитывает локальный трансформ, чтобы ничего не
сдвинулось на экране; передай false, чтобы сохранить локальные значения и встать в систему
координат нового родителя. Сам узел и его потомки в родители не годятся (циклов нет).
ребёнок идёт туда же, где его родитель: подвешенный под узел в сцене, он
входит в эту сцену и рисуется; под узел вне сцены — покидает её;
отсоединённый (setParent(null), remove), остаётся в своей сцене корнем. Скрытый родитель скрывает
и его. А parent читается как null, пока родитель — свободный корень (ещё не в сцене и не под
другим узлом).
Место ребёнка в мире: worldPosition, worldToLocal, localToWorld
position ребёнка задан относительно родителя; эти члены дают его место в мире и переводят точку
между миром и собственным пространством узла. Точка экрана (тап) идёт через камеру:
screenToWorld.
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.
направляется только ПРЯМАЯ запись. Тело или сенсор, подвешенные под движущийся узел, за ним не следуют — держи их на корневых узлах и пиши их собственный трансформ.
Тапы, столкновения и события клипов на узле: addEventListener
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
node.destroy(): voidОсвобождает нативную сущность и всё её поддерево — дети уходят вместе с родителем, как в 3D- и
UI-деревьях (чтобы сохранить ребёнка, сначала отсоедини его через setParent(null)). Сначала
отсоединяется каждый аспект в поддереве, так что тела освобождаются. Узел, который ты так и не
добавил в сцену и на который перестал ссылаться, освобождается сам. После этого node.id читается
как 0, а записи до движка больше не доходят.
Подводные камни
// ✗ изменение СОХРАНЁННОЙ копии трансформа
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]Смотрите также
- Scene2D — добавление узлов, порядок отрисовки, Y-сортировка
- Sprite — текстурированный узел
- 2D-физика —
Shape2D, тела, триггеры,enter/exit - События указателя и жесты —
click,touchstart, перетаскивания - Соглашения — единицы, семантика значений, жизненный цикл