Node2D

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

Обзор

TypeScript

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

const cart = new Node2D()
cart.add(wheelA, wheelB)        // дети двигаются вместе с тележкой
cart.x += 40

Трансформ

Локальный относительно родителя, Y вверх; 1 единица = 1 логический px при зуме камеры 1. См. Соглашения.

TypeScript

node.x, node.y                     // сеттеры одной оси
node.position = [120, 64]          // Vec2Like; геттер возвращает свежий Vec2
node.rotation = 45                 // градусы, CCW
node.scale = 2                     // число (равномерно) или Vec2Like — только масштаб отрисовки
node.layer = 1                     // слой отрисовки (int); более высокие слои рисуются поверх
node.z = 5                         // внутрислойная глубина на не-Y-сортируемых слоях (больше = поверх)
node.visible = false

Note

Геттеры position и scale возвращают свежие копии — node.position.x = 3 это тихий no-op. Используй node.x = 3 или поменяй локальную переменную и присвой обратно. См. семантику значений в математике.

Note

scale влияет только на отрисовку — физические формы его никогда не читают. Увеличенный спрайт сохраняет объявленный тобой коллайдер. См. 2D-физику.

Иерархия

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, чтобы сохранить локальные значения и прыгнуть в систему нового родителя. Сам себя и потомков в родители не пускает (без циклов).

TypeScript

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

Трансформы под управлением физики

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

События

TypeScript

node.addEventListener(channel, callback)
node.removeEventListener(channel, callback)

Канал	Срабатывает, когда	Аргумент колбэка
`click`	отпускание над физической формой этого узла	`ClickEvent`
`touchstart`	нажатие на его форму — `ev.track()` для перетаскиваний	`TouchStartEvent`
`enter` / `exit`	контакт физики / перекрытие сенсора начались / закончились	другой `Node2D`
`loopReached`	зацикленный клип `SpriteAnimation` обернулся	имя клипа (строка)
`completed`	незацикленный клип завершился	имя клипа (строка)

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

Уничтожение

TypeScript

node.destroy(): void

Освобождает нативную сущность и отсоединяет от родителя. Дети переподвешиваются к корню, сохраняя мировые трансформы — они не уничтожаются вместе с родителем. Использование уничтоженного узла после — неопределённое поведение.

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

TypeScript

// ✗ изменение копии трансформа
node.position.x = 3
// ✓ сеттер одной оси или присвоение целого значения
node.x = 3

// ✗ борьба с шагом физики на динамическом теле
setLoop(() => { node.y += 2 })
// ✓ управляй телом вместо этого
node.physics.velocity = [0, 120]

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

Scene2D — добавление узлов, слои, Y-сортировка.
Sprite — текстурированный узел.
2D-физика — Shape2D, тела, триггеры, enter/exit.
События указателя и жесты — click, touchstart, перетаскивания.
Соглашения — единицы, семантика значений, жизненный цикл.