Path2D

Линии, многоугольники и кривые в 2D-сцене — дорога на карте, след, отладочная линия, участок с границей, скруглённая панель: Node2D, который рисуется в батче спрайтов и сортируется как любой узел. Это не браузерный Path2D: рисовать в картинку — это Canvas; коллайдер — это Shape2D (у пути нет ни пикинга, ни своего коллайдера).

  • нарисовать линию или ломаную в 2D-сцене: дорогу, отладочную линию, лазер
  • нарисовать залитый многоугольник, прямоугольник, круг или эллипс
  • нарисовать скруглённый прямоугольник: панель или форму кнопки в мире
  • нарисовать гладкую кривую: кривые Безье и дуги
  • сохранить толщину линии на экране при любом масштабе
  • вырезать дырку в залитой фигуре
  • дать линии кайму, скруглить её стыки и концы
  • сохранить кривые гладкими вблизи

Платформы: везде, где работает Scene2D; headless-тесты строят геометрию (points), но ничего не рисуют.

Обзор

TypeScript
const scene = new Scene2D({ background: "#1d2430" })

const road = Path2D.line([[-200, -60], [-40, 20], [200, 0]], { width: 3, units: "px", color: "#fc4", join: "round" })
const park = Path2D.polygon([[-80, 40], [60, 40], [60, 120], [-80, 120]], { fill: "#2a8f4a", stroke: { width: 1, units: "px", color: "#9fe0b0" } })
const sun = Path2D.circle(24, { fill: "#f8d34a", position: [150, 120] })
const card = Path2D.roundRect([160, 60], 12, { fill: "#223", stroke: 2, position: [0, -140] })
const bend = Path2D.shape(p => {
  p.moveTo(-200, -100)
  p.cubicTo(-100, 20, 100, -220, 200, -100)              // S-образный изгиб
}, { stroke: { width: 4, color: "#7dd3fc", cap: "round" } })

scene.add(road, park, sun, card, bend)
scene.open()

Точки задаются в локальной системе координат узла, Y вверх, как любая 2D-позиция: весь путь двигай через position / rotation / scale.

Линия, многоугольник, прямоугольник: line, polygon, rect

TypeScript
Path2D.line(points: Vec2Like[], stroke: Stroke2D | number, options?): Path2D   // открытая ломаная
Path2D.polygon(points: Vec2Like[], options?): Path2D     // замкнутое кольцо: дай ему заливку и / или обводку
Path2D.rect(size: Vec2Like, options?): Path2D            // прямоугольник с центром в начале координат узла

new Path2D(options: { points: Vec2Like[], closed?: boolean, ...the options below })

Опции, которые принимает любой путь:

TypeScript
{
  stroke?: Stroke2D | number     // число = { width }; не указано — без обводки
  fill?: ColorInput              // не указано — без заливки
  closed?: boolean               // обводка соединяет конец с началом; заливка замкнута всегда
  holes?: Vec2Like[][]           // кольца, вырезанные из заливки
  tolerance?: number             // только для кривых, см. ниже; по умолчанию 0.25
  antialias?: boolean            // по умолчанию true; false — для чётких пиксель-арт-линий
  position?: Vec2Like
  rotation?: number              // градусы, против часовой
  scale?: number | Vec2Like
  z?: number                     // порядок отрисовки, см. Scene2D
  renderPriority?: number        // 0..7, по умолчанию 4
  material?: Material2D          // для пути важно только смешивание
}

closed по умолчанию false для line, shape, arc и простого конструктора и true для polygon, rect, roundRect, ellipse и circle. Заливка триангулируется по внешнему кольцу и его дыркам; обводка идёт только по внешнему кольцу.

Толщина, цвет, стыки, концы и кайма линии: Stroke2D

TypeScript
type Stroke2D = {
  width: number                            // в `units`
  color?: ColorInput                       // по умолчанию белый
  units?: 'world' | 'px'                   // по умолчанию 'world'; 'px' = логические px экрана при любом зуме
  join?: 'miter' | 'round' | 'bevel'       // как стыкуются отрезки; по умолчанию 'miter'
  cap?: 'butt' | 'round' | 'square'        // концы открытого пути; по умолчанию 'butt'
  outline?: { width: number, color?: ColorInput }   // полоса с каждой стороны линии, в `units`; по умолчанию чёрная
}

units: 'px' сохраняет толщину линии на экране при любом масштабе — дороги на карте, отладочные линии; 'world' по умолчанию масштабируется вместе со всей сценой. Толщина применяется каждый кадр, поэтому смена масштаба ничего не перестраивает. Горизонтальные и вертикальные отрезки линии с толщиной в px ложатся на сетку пикселей устройства: рамка в 1 px — это один чёткий ряд пикселей.

Проходы отрисовки держат дороги и участки опрятными (порядок отрисовки): кайма (outline) рисуется под самими линиями с теми же renderPriority и z, так что две дороги с каймой на одном z сливаются на перекрёстке (другой z держит их раздельно); обводка залитого пути — это его граница, и она рисуется поверх заливок соседей.

TypeScript
const scene = new Scene2D({ background: "#e8e4da" })
const roadStyle = { width: 6, units: "px" as const, color: "#ffffff", join: "round" as const, cap: "round" as const,
  outline: { width: 1.5, color: "#9a9384" } }
const avenue = Path2D.line([[-200, 0], [200, 0]], roadStyle)
const side = Path2D.line([[0, 0], [40, 160]], roadStyle)    // тот же z: каймы сливаются на перекрёстке
scene.add(avenue, side)
scene.open()

Круги, эллипсы, дуги и скруглённые прямоугольники: статические методы фигур

TypeScript
Path2D.circle(radius: number, options?): Path2D
Path2D.ellipse(radii: [rx, ry], options?): Path2D
Path2D.roundRect(size: Vec2Like, radius: number | [topLeft, topRight, bottomRight, bottomLeft], options?): Path2D
Path2D.arc(radius: number, startAngle: number, endAngle: number, options? & { clockwise?: boolean }): Path2D

Центр каждой фигуры — в начале координат узла. roundRect принимает один радиус или по одному на угол, в том порядке, в каком углы видны на экране; слишком большие для стороны радиусы уменьшаются вместе. Углы arc — в радианах, отсчитываются на экране против часовой от +X (Y вверх), и дуга идёт против часовой, если не задан clockwise; это открытая обводка, если не задан closed (тогда концы соединяет хорда, а заливка — сегмент круга).

TypeScript
const scene = new Scene2D()
const ring = Path2D.circle(40, { stroke: { width: 6, color: "#333" } })
const progress = Path2D.arc(40, Math.PI / 2, Math.PI / 2 - 0.7 * Math.PI * 2, {   // 70 %, от верха
  clockwise: true, stroke: { width: 6, color: "#4ade80", cap: "round" },
})
progress.z = 1                                                                     // поверх дорожки
scene.add(ring, progress)
scene.open()

Кривая пером: Path2D.shape

TypeScript
Path2D.shape((p: PathBuilder2D) => void, options?): Path2D

p.moveTo(x, y)                                        // начать контур
p.lineTo(x, y)
p.quadTo(cpx, cpy, x, y)                              // квадратичная кривая Безье
p.cubicTo(c1x, c1y, c2x, c2y, x, y)                   // кубическая кривая Безье
p.arcTo(x1, y1, x2, y2, radius)                       // скруглённый угол (arcTo из Canvas2D)
p.arc(cx, cy, radius, startAngle, endAngle, clockwise = false)              // радианы
p.ellipse(cx, cy, rx, ry, rotation, startAngle, endAngle, clockwise = false)
p.roundRect(x, y, w, h, radius | [tl, tr, br, bl])    // целый замкнутый контур: только на пустом пере
p.close()                                             // соединить конец с началом; завершает путь

Словарь путей Canvas2D (каждый вызов возвращает перо), в локальной системе координат узла. Y вверх, поэтому углы на экране отсчитываются против часовой, а clockwise: true ведёт в другую сторону. arc и ellipse сначала проводят линию от текущей точки к своему началу; кривая без текущей точки начинается в своей первой контрольной точке. Фигура открыта, если в ней нет вызова close() и у пути не задан closed: true.

TypeScript
const scene = new Scene2D({ background: "#10131a" })
const tab = Path2D.shape(p => {
  p.moveTo(-60, 0)
  p.arcTo(-60, 40, 0, 40, 12)       // скруглить верхний левый угол
  p.arcTo(60, 40, 60, 0, 12)        // и верхний правый
  p.lineTo(60, 0)
  p.close()
}, { fill: "#2563eb", stroke: { width: 1, units: "px", color: "#93c5fd" } })
scene.add(tab)
scene.open()
Note

путь — это один контур. Второй moveTo после того, как что-то уже нарисовано, roundRect после других отрезков или что угодно после close() отбрасывается вместе с остатком пера — в лог пишется path <id>: … dropped (one subpath per path). Второй контур рисуй вторым Path2D; дырка задаётся через holes.

Гладкие кривые вблизи: tolerance

Движок разбивает кривую на прямые хорды один раз, когда задаётся фигура: ни одна хорда не отходит от кривой дальше, чем на tolerance локальных единиц (по умолчанию 0.25 — четверть логического px при зуме 1 и масштабе узла 1; ограничено диапазоном 0.01..100). Заново кривая не разбивается, поэтому вблизи видны её хорды: подбирай допуск под самый большой зум (и масштаб узла), при котором её будут смотреть, — 0.25 / zoom.

TypeScript
const scene = new Scene2D()
const coin = Path2D.circle(8, { fill: "#f8d34a", tolerance: 0.25 / 8 })   // гладкая до зума 8
scene.add(coin)
scene.open()
scene.camera.zoom = 8

Меньший допуск — больше точек; запись в tolerance разбивает фигуру заново. antialias — отдельная вещь: кромка шириной в один логический px, применяется каждый кадр при любом зуме.

Изменение пути во время игры: живые свойства

TypeScript
path.points: Vec2[]          // внешнее кольцо; у фигуры — кольцо, на которое движок её разбил
path.shape                   // функция пера или null у пути из точек
path.tolerance
path.closed
path.stroke                  // Stroke2D | null — null = без обводки
path.fill                    // ColorInput | null — null = без заливки
path.holes                   // Vec2[][] — запись заменяет их все
path.antialias
path.material

Запись в points, shape, closed, holes или tolerance заново тесселирует путь в нативном коде (запись в points превращает путь-фигуру в ломаную), как и включение или выключение обводки или заливки, новый join / cap или antialias; новая толщина или цвет — нет. Если фигура только двигается, анимируй position / rotation / scale узла, а не её точки. Линию, которая действительно меняется, вроде линии прицела, переписывай из системы:

TypeScript
const scene = new Scene2D()
const hero = new Sprite({ size: [16, 16], color: "#4f7cff", position: [-100, 0] })
const target = new Sprite({ size: [16, 16], color: "#f43f5e", position: [100, 60] })

class AimLine extends System<"aim", Scene2D> {
  private line!: Path2D
  onAttach() {
    this.line = Path2D.line([hero.position, target.position], { width: 2, units: "px", color: "#f43f5e" })
    this.scene.add(this.line)
  }
  update() { this.line.points = [hero.position, target.position] }   // раз в кадр
}

scene.add(hero, target)
scene.system(AimLine)
scene.open()
hero.animateTo({ y: -80, duration: 2000, loop: true, loopMode: "ping-pong" })

Дырка в залитой фигуре: holes

TypeScript
const scene = new Scene2D({ background: "#e8e4da" })
const yard = Path2D.polygon(
  [[-100, -60], [100, -60], [100, 60], [-100, 60]],
  { fill: "#86c06c", holes: [[[-30, -20], [30, -20], [30, 20], [-30, 20]]] },   // место для пруда
)
scene.add(yard)
scene.open()

Дырки — кольца точек в системе координат узла, и вырезают они только заливку: обводка идёт по внешнему кольцу, так что своя граница у дырки — это второй путь (Path2D.polygon(ring, { stroke })). Кривая дырка — тоже кольцо точек: его даёт путь, который ты не добавляешь в сцену, — Path2D.circle(20).points с центром в начале координат.

Пути в файле сцены: блок path

TypeScript
// map.scene2d.ts
export default defineScene2d({
  nodes: {
    road: { path: { points: [[0, 0], [400, 120]], stroke: { width: 3, units: "px", color: "#fc4" } } },
    lake: { path: { shape: p => { p.ellipse(0, 0, 80, 50, 0, 0, Math.PI * 2).close() }, fill: "#5aa0d8" }, position: [200, -80] },
  },
})

Блок принимает опции конструктора (points или shape, closed, stroke, fill, holes, tolerance, antialias); трансформ и порядок отрисовки — это пропы узла. См. файлы сцен.

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

TypeScript
// ✗ имена из Canvas на пере — у пера нет bezierCurveTo / quadraticCurveTo
p.bezierCurveTo(10, 40, 50, 40, 60, 0)
// ✓
p.cubicTo(10, 40, 50, 40, 60, 0)

// ✗ два контура в одном пере: второй moveTo и всё после него отбрасываются
Path2D.shape(p => { p.roundRect(-50, -20, 100, 40, 8); p.moveTo(0, -20); p.lineTo(10, -35) })
// ✓ один путь на контур (облачко реплики = его прямоугольник + хвостик, одна заливка)
const box = Path2D.roundRect([100, 40], 8, { fill: "#fff" })
const tail = Path2D.polygon([[-6, -20], [6, -20], [0, -32]], { fill: "#fff" })

// ✗ градусы: дуги принимают радианы
Path2D.arc(30, 0, 90)
// ✓
Path2D.arc(30, 0, Math.PI / 2)

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

  • Scene2D — порядок отрисовки, добавление узлов
  • Node2D — трансформ, иерархия (унаследованы)
  • Text2D — подписи рядом с линиями
  • Canvas — пути, нарисованные в картинку
  • 2D-физика — коллайдер для фигуры (Shape2D)