Path2D
Линии, многоугольники и кривые в 2D-сцене — дорога на карте, след, отладочная линия, участок с
границей, скруглённая панель: Node2D, который рисуется в батче спрайтов и
сортируется как любой узел. Это не браузерный Path2D: рисовать в картинку — это
Canvas; коллайдер — это Shape2D (у пути нет ни
пикинга, ни своего коллайдера).
- нарисовать линию или ломаную в 2D-сцене: дорогу, отладочную линию, лазер
- нарисовать залитый многоугольник, прямоугольник, круг или эллипс
- нарисовать скруглённый прямоугольник: панель или форму кнопки в мире
- нарисовать гладкую кривую: кривые Безье и дуги
- сохранить толщину линии на экране при любом масштабе
- вырезать дырку в залитой фигуре
- дать линии кайму, скруглить её стыки и концы
- сохранить кривые гладкими вблизи
Платформы: везде, где работает Scene2D; headless-тесты строят геометрию
(points), но ничего не рисуют.
Обзор
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
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 })Опции, которые принимает любой путь:
{
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
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 держит их раздельно); обводка залитого пути —
это его граница, и она рисуется поверх заливок соседей.
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()Круги, эллипсы, дуги и скруглённые прямоугольники: статические методы фигур
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 (тогда
концы соединяет хорда, а заливка — сегмент круга).
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
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.
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()путь — это один контур. Второй 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.
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, применяется каждый кадр при любом зуме.
Изменение пути во время игры: живые свойства
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 узла, а не её точки. Линию, которая
действительно меняется, вроде линии прицела, переписывай из системы:
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
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
// 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); трансформ и порядок отрисовки — это пропы узла. См.
файлы сцен.
Подводные камни
// ✗ имена из 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)