LeCodesdocs

Sprite

Текстурированный 2D-узел — рабочая лошадка 2D-сцены. Расширяет Node2D, поэтому имеет полный трансформ, иерархию, события и поверхность аспектов. Анимация спрайт-листа не встроена: прикрепи аспект SpriteAnimation.

Обзор

TypeScript
const tex = await Texture2D.load(asset('./hero.png'))

const hero = new Sprite({ texture: tex, anchor: [0.5, 1], layer: 1 })
  .aspect(SpriteAnimation, { size: [32, 48], fps: 10, clips: { idle: [0], walk: [1, 2, 3, 4] } })
hero.position = [120, 64]
hero.anim.play('walk')
scene.add(hero)

Создание

TypeScript
new Sprite(options?: {
  texture?: Texture2D | Canvas   // Canvas запекается в текстуру при присвоении
  anchor?: Vec2Like              // пивот: [0,0] верх-лево … [1,1] низ-право; по умолчанию [0.5, 0.5]
  size?: Vec2Like                // мировой размер; по умолчанию = пиксельные размеры текстуры
  frame?: [u0, v0, u1, v1]       // нормализованный UV-подпрямоугольник
  color?: ColorInput             // тинт, умножается с текстурой
  opacity?: number               // 0..1
  layer?: number                 // слой отрисовки (см. слои Scene2D)
  position?: Vec2Like
})
Note

пространство якоря — Y вниз, хотя мир Y вверх: [0.5, 1] — низ-центр спрайта («ноги»). Используй его для всего на Y-сортируемом слое, чтобы глубина сортировалась по ногам.

Текстура и размер

TypeScript
sprite.texture = tex             // Texture2D или Canvas (запекается при присвоении)
sprite.size = [w, h]             // мировые единицы; сбрасывает нативный дефолт при смене текстуры
  • Размер по умолчанию — пиксельные размеры текстуры — 1 тексель = 1 мировая единица = 1 логический px при зуме 1.
  • Спрайт на основе Canvas по умолчанию берёт логический размер канваса, поэтому pixelRatio канваса влияет только на чёткость, никогда на экранный размер. См. Canvas.

Кадры (атласы / спрайт-листы)

TypeScript
sprite.frame = [u0, v0, u1, v1]        // нормализованный UV-подпрямоугольник
sprite.setFramePx(x, y, w, h): this    // подпрямоугольник в пикселях текстуры — чейнится

setFramePx — то, что стоит использовать с атласом: координаты совпадают с тем, что показывает графический редактор. Смена кадра не меняет size — задай size один раз равным пиксельным размерам кадра, если хочешь вывод без масштабирования.

Для покадровой анимации не гоняй frame сам — прикрепи SpriteAnimation и определи клипы.

Внешний вид

TypeScript
sprite.color = '#ff8800'    // тинт (умножается); по умолчанию белый = без тинта
sprite.opacity = 0.5        // 0..1
sprite.flipX = true         // отразить по горизонтали (лицом влево/вправо без отрицательного масштаба)
sprite.flipY = true

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

TypeScript
// ✗ ждать, что scale повлияет на физику — экстенты Shape2D это сырые мировые единицы, без масштаба
sprite.scale = 2   // рисует 2×, но его физический бокс остаётся объявленного размера

// ✗ покадровая смена текстуры для анимации
setLoop(() => sprite.setFramePx(...))   // работает, но плохо переизобретает SpriteAnimation

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

  • Node2D — трансформ, иерархия, события (унаследованы).
  • SpriteAnimation — клипы, fps, события play/loop.
  • Texture2D — загрузка изображений.
  • Scene2D — слои, Y-сортировка, добавление узлов.
← НазадCamera2DДальше →SpriteAnimation