Shape2D — C# API

Общая геометрия 2D-коллизий, прямые запросы и контактные пары.

class Shape2DReckfellSharpНаследует Resource

Shape2D — базовый ресурс геометрии. Создавайте конкретную форму: круг, прямоугольник, капсулу или полигон. Ресурс не является телом и не добавляет себя в физический мир. Для обычного коллайдера назначьте его Shape у CollisionShape2D, который является непосредственным дочерним Entity нужного CollisionObject2D.

Прямые Collide-методы работают с двумя переданными ресурсами. Они не ищут объекты в EntityTree, не применяют слои и маски тел и не выполняют физическую реакцию. У каждой формы своё преобразование из локальных координат в одно общее пространство. Если передаёте мировые преобразования, контактные точки будут мировыми; повторно применять к ним GlobalTransform не нужно.

Выбор метода:

Collide: нужен только ответ о пересечении при двух заданных положениях.
CollideAndGetContacts: нужны точки двух поверхностей без движения.
CollideWithMotion и CollideWithMotionAndGetContacts: запрос с векторами смещения, с ограничениями ниже.

Контактный массив содержит пары [A0,B0,A1,B1,…]: точку первой формы и точку второй формы. Это не массив нормалей и не список Collider. Предел текущей реализации — 16 пар, то есть 32 Vector2. Полный проверенный пример разбирает пары и использует отдельные ресурсы кругов:

C#
using System;
using Reckfell;

public static class ShapeContacts2D
{
    // Both transforms map local shape coordinates into the same query space.
    public static (Vector2 A, Vector2 B)[] Query(
        Shape2D a, Transform2D transformA, Shape2D b, Transform2D transformB)
    {
        ArgumentNullException.ThrowIfNull(a);
        ArgumentNullException.ThrowIfNull(b);
        Vector2[] raw = a.CollideAndGetContacts(transformA, b, transformB);
        var pairs = new (Vector2 A, Vector2 B)[raw.Length / 2];
        for (int i = 0; i < pairs.Length; i++)
            pairs[i] = (raw[2 * i], raw[2 * i + 1]);
        return pairs;
    }

    public static (Vector2 A, Vector2 B)[] Example()
    {
        using var a = new CircleShape2D { Radius = 10 };
        using var b = new CircleShape2D { Radius = 10 };
        return Query(a, new Transform2D(0, new Vector2(100, 50)),
                     b, new Transform2D(0, new Vector2(115, 50)));
    }
}

В Example круги радиуса 10 стоят в (100,50) и (115,50). Проверка вернула одну пару: A=(110,50), B=(105,50). При разнесении форм массив пуст. GetRect() при этом остаётся локальным: запрос не перемещает ресурс или Entity.

Важное ограничение движения: для обычных выпуклых форм SAT-путь сравнивает протянутые области, а не вычисляет точное время встречи по двум синхронным траекториям. У WorldBoundaryShape2D и SeparationRayShape2D отдельные алгоритмы; не переносите описание SAT на все типы форм. В проверке круги радиуса 2 начинали в (100,50) и (120,50), оба получали смещение (30,0), и CollideWithMotion вернул true. Расстояние между кругами при таком совместном движении остаётся 20: true здесь не доказывает реальный удар. Не используйте результат как время удара, безопасную долю движения или замену перемещению физического тела. Motion — смещение, не скорость; delta автоматически не умножается.

CustomSolverBias обычно оставляйте 0: используется коэффициент пространства. Setter не испускает Changed. Draw добавляет команды в уже существующий CanvasItem; не создаёт коллайдер. RID формы принадлежит ресурсу: не освобождайте его отдельно через PhysicsServer2D. Общий ресурс остаётся общим для всех пользователей.

Проверены статические и протянутые пересечения, порядок и координаты контактных пар, пример, bias и локальные границы в установленном Windows runtime. Draw проверен только как принятие команды в headless. Лимит 16 пар подтверждён исходниками, но не нагрузочным тестом. Динамика тел, другие backend, изображение и производительность не проверялись.

Объявления сверены с C# SDK 1.0.0. Раскройте имя, чтобы увидеть сигнатуры и описание.

Свойства1

CustomSolverBiasСвойство

# CustomSolverBias

C#
public float CustomSolverBias { get; set; }

Пользовательский коэффициент коррекции проникновения в решателе контактов, изначально 0. В текущем 2D backend 0 использует коэффициент пространства; если обе формы задают ненулевой коэффициент, используется среднее, если одна — её значение. Это не margin, не радиус и не фильтр пересечений. Inspector предлагает диапазон 0…1; setter не ограничивает значение этим диапазоном и не испускает Changed. Обычно оставляйте 0; влияние на динамику тел этим прогоном не проверялось.

Методы8

Collidebool

# Collide

C#
public bool Collide(Transform2D localXform, Shape2D withShape, Transform2D shapeXform);

Проверяет пересечение этой формы и withShape при двух заданных Transform2D, без смещения. Обе трансформации должны переводить локальные координаты форм в одно пространство запроса. Не ищет тела в мире, не учитывает слои/маски CollisionObject2D и не двигает Entity. Нужен существующий ненулевой ресурс второй формы.

Параметры
Имя	Тип	По умолчанию
`localXform`	`Transform2D`	—
`withShape`	`Shape2D`	—
`shapeXform`	`Transform2D`	—

localXform

Преобразование локальных координат этой формы в общее пространство запроса. Для мирового запроса учитывайте мировую трансформацию пользователя формы, включая её локальное смещение.

withShape

Второй существующий ненулевой ресурс Shape2D с настроенной геометрией. Не CollisionObject2D и не RID тела.

shapeXform

Преобразование локальных координат withShape в то же пространство, что localXform. Не относительная трансформация второй формы к первой.

Возвращает bool

true при пересечении двух форм в заданных трансформациях; иначе false. Не сообщает тело или контактную нормаль.

CollideAndGetContactsVector2[]

# CollideAndGetContacts

C#
public Vector2[] CollideAndGetContacts(Transform2D localXform, Shape2D withShape, Transform2D shapeXform);

Возвращает плоский массив контактных пар для двух форм без движения: [A0,B0,A1,B1,…]. A относится к этой форме, B — к withShape; обе точки уже находятся в общем пространстве заданных трансформаций. При отсутствии пересечения массив пуст. Лимит текущей реализации — 16 пар (32 Vector2), а не 16 элементов. Это не список тел, нормалей или всех возможных контактов мира.

Параметры
Имя	Тип	По умолчанию
`localXform`	`Transform2D`	—
`withShape`	`Shape2D`	—
`shapeXform`	`Transform2D`	—

localXform

withShape

Второй существующий ненулевой ресурс Shape2D с настроенной геометрией. Не CollisionObject2D и не RID тела.

shapeXform

Возвращает Vector2[]

До 16 пар точек [A0,B0,A1,B1,…] в пространстве запроса, либо пустой массив. Число пар равно Length/2.

CollideWithMotionbool

# CollideWithMotion

C#
public bool CollideWithMotion(Transform2D localXform, Vector2 localMotion, Shape2D withShape, Transform2D shapeXform, Vector2 shapeMotion);

Проверяет пересечение с учётом заданных векторов смещения обеих форм. Смещения заданы в общем пространстве запроса и не являются скоростью: delta не применяется автоматически. Для обычных выпуклых форм в SAT-пути сравниваются протянутые геометрические области; true не доказывает столкновение в один момент времени. WorldBoundaryShape2D и SeparationRayShape2D используют отдельные алгоритмы. Не возвращает безопасную долю движения, время удара, поворот во время движения или реакцию тел.

Параметры
Имя	Тип	По умолчанию
`localXform`	`Transform2D`	—
`localMotion`	`Vector2`	—
`withShape`	`Shape2D`	—
`shapeXform`	`Transform2D`	—
`shapeMotion`	`Vector2`	—

localXform

localMotion

Вектор смещения этой формы в общем пространстве запроса. Если исходно известна скорость, самостоятельно вычислите смещение для нужного интервала. Vector2.Zero отключает её протягивание.

withShape

Второй существующий ненулевой ресурс Shape2D с настроенной геометрией. Не CollisionObject2D и не RID тела.

shapeXform

shapeMotion

Вектор смещения withShape в общем пространстве запроса; для неподвижной второй формы передайте Vector2.Zero. Два смещения не превращают метод в расчёт синхронного времени удара.

Возвращает bool

Результат запроса со смещениями; алгоритм зависит от типов форм. true не является доказательством одновременного столкновения движущихся тел и не содержит доли движения.

CollideWithMotionAndGetContactsVector2[]

# CollideWithMotionAndGetContacts

C#
public Vector2[] CollideWithMotionAndGetContacts(Transform2D localXform, Vector2 localMotion, Shape2D withShape, Transform2D shapeXform, Vector2 shapeMotion);

Возвращает контактные пары запроса со смещением в формате [A0,B0,A1,B1,…], максимум 16 пар. Пустой массив означает отсутствие возвращённых контактов. Координаты относятся к общему пространству запроса; это контакты запроса со смещением, не гарантированная первая точка удара на синхронных траекториях. Ограничения CollideWithMotion сохраняются; массив не содержит времени удара, Collider или безопасной доли движения.

Параметры
Имя	Тип	По умолчанию
`localXform`	`Transform2D`	—
`localMotion`	`Vector2`	—
`withShape`	`Shape2D`	—
`shapeXform`	`Transform2D`	—
`shapeMotion`	`Vector2`	—

localXform

localMotion

withShape

Второй существующий ненулевой ресурс Shape2D с настроенной геометрией. Не CollisionObject2D и не RID тела.

shapeXform

shapeMotion

Возвращает Vector2[]

До 16 пар точек запроса со смещением в пространстве запроса, либо пустой массив; без времени удара и безопасной доли движения.

Drawvoid

# Draw

C#
public void Draw(Rid canvasItem, Color color);

Добавляет команды изображения конкретной формы в существующий CanvasItem по его RID с указанным цветом. Не создаёт CanvasItem, физическое тело или материал. Используйте это для диагностической 2D-отрисовки; повторные вызовы добавляют команды, очистка принадлежит владельцу CanvasItem. Проверено принятие команды в headless, но не вид, сглаживание или качество изображения.

Параметры
Имя	Тип	По умолчанию
`canvasItem`	`Rid`	—
`color`	`Color`	—

canvasItem

Действующий RID CanvasItem. Владение и очистка команд остаются у вызывающего кода; не передавайте RID формы или тела.

color

Цвет диагностической формы, включая альфа-компоненту. Не влияет на физическую геометрию.

GetCustomSolverBiasfloat

# GetCustomSolverBias

C#
public float GetCustomSolverBias();

Возвращает сохранённый пользовательский коэффициент этой формы; 0 означает использование общего коэффициента пространства, а не отключение коррекции. Не возвращает итоговое среднее для пары тел.

Возвращает float

Сохранённый коэффициент этой формы, изначально 0; не итоговый коэффициент пары.

GetRectRect2

# GetRect

C#
public Rect2 GetRect();

Возвращает локальный Rect2, определяемый конкретной формой; положение/поворот Entity и переданные ранее трансформации запросов в него не входят. Для круга, прямоугольника и капсулы это геометрические границы. Не используйте метод как точный тест столкновения: контур может быть пустым внутри, SeparationRayShape2D добавляет поля отладочного изображения, а конечный прямоугольник WorldBoundaryShape2D не ограничивает бесконечную физическую границу.

Возвращает Rect2

Прямоугольник в локальных координатах конкретной формы; не мировые границы и не точный результат пересечения.

SetCustomSolverBiasvoid

# SetCustomSolverBias

C#
public void SetCustomSolverBias(float bias);

Параметры
Имя	Тип	По умолчанию
`bias`	`float`	—

bias

Пользовательский коэффициент решателя; обычно 0 для настройки пространства. Диапазон Inspector 0…1 не применяется как clamp в setter.