2D Structs

Page Map

Header	Link
Purpose	Purpose
Use Cases	Use Cases
Struct Table	Struct Table
`Vector2`	`Vector2`
`UVector2`	`UVector2`
`IVector2`	`IVector2`
`Transform2D`	`Transform2D`
`DrawShape2D`	`DrawShape2D`

Purpose

These are the small value types every 2D API speaks: positions, sizes, grid coordinates, transforms, and draw shapes. You build them, do vector math on them, and pass them to node transform, physics, input, and drawing calls. They are plain Copy values, so moving and combining them is cheap.

Use Cases

Move and place 2D nodes: Vector2 positions and velocities feeding set_local_pos_2d! / get_global_pos_2d!, and full Transform2D values.
Address a tile grid or chunk with whole-number coordinates: UVector2 for unsigned cells, IVector2 when cells can be negative.
Rotate and scale sprites or UI: Transform2D's rotation and scale.
Aim and click from the pointer: Vector2 screen coordinates from mouse_position!.
Draw debug and gameplay overlays: DrawShape2D submitted through ctx.res.Draw2D().

Decision Guide

Use float vectors for positions, directions, and smooth motion; use integer vectors for cell identity. Use a transform when position, rotation, and scale must move as one value. Do not keep a node transform duplicated in script state unless it is a separate target or saved gameplay value; read the node when the node owns the current transform.

Struct Table

Type	Fields / Shape	Return/use type	Use when
`Vector2`	`x: f32`, `y: f32`	value type	2D position, size, velocity, direction, mouse coords, UI coords.
`UVector2`	`x: u32`, `y: u32`	value type	tile coords, grid coords, pixel counts, unsigned dimensions.
`IVector2`	`x: i32`, `y: i32`	value type	signed tile/chunk coords, grid offsets, negative cell positions.
`Transform2D`	`position: Vector2`, `scale: Vector2`, `rotation: f32`	value type	local/global 2D node transforms.
`DrawShape2D`	enum draw shape	enum value	immediate 2D debug/gameplay drawing through `ctx.res.Draw2D()`.

`Vector2`

Signature:

pub struct Vector2 {
    pub x: f32,
    pub y: f32,
}

Use when an API needs 2D coordinates, movement, direction, size, or pointer position.

Common methods:

Signature	Returns	Use when
`pub const fn Vector2::new(x: f32, y: f32) -> Self`	`Vector2`	Build a typed 2D value.
`pub const fn to_array(self) -> [f32; 2]`	`[f32; 2]`	Pass to array-based APIs or serialize compact coords.
`pub const fn to_tuple(self) -> (f32, f32)`	`(f32, f32)`	Destructure into normal Rust tuple flow.
`pub fn length(&self) -> f32` / `pub fn length_squared(&self) -> f32`	`f32`	Measure magnitude; squared avoids sqrt for comparisons.
`pub fn normalized(&self) -> Self`	`Vector2`	Get safe unit direction.
`pub fn distance_to(self, other: Self) -> f32`	`f32`	Measure distance between two points.
`pub fn direction_to(self, other: Self) -> Self`	`Vector2`	Get direction from one point to another.
`pub fn angle_to(self, other: Self) -> f32`	`f32`	Get signed angle in radians.
`pub fn dot(self, rhs: Self) -> f32` / `pub fn cross(self, rhs: Self) -> f32`	`f32`	Projection/alignment or signed 2D area/turn checks.
`pub fn min(self, rhs: Self) -> Self` / `pub fn max(self, rhs: Self) -> Self`	`Vector2`	Pick per-axis lower/upper values.
`pub fn clamp(self, min: Self, max: Self) -> Self`	`Vector2`	Keep coords inside a per-axis range.
`pub fn negated(self) -> Self`	`Vector2`	Get negated copy.
`pub fn negate(&mut self) -> &mut Self`	`&mut Vector2`	Mutate to negated value.
`pub fn lerped(self, to: Self, t: f32) -> Self`	`Vector2`	Get interpolated copy.
`pub fn lerp(&mut self, to: Self, t: f32) -> &mut Self`	`&mut Vector2`	Mutate toward target in place.
`pub fn slerped(self, to: Self, t: f32) -> Self`	`Vector2`	Get spherical interpolation copy.
`pub fn slerp(&mut self, to: Self, t: f32) -> &mut Self`	`&mut Vector2`	Mutate by spherical interpolation in place.

Example:

lifecycle!({
    fn on_update(&self, ctx: &mut ScriptContext<'_, API>) {
        let dt = delta_time!(ctx.run);
        let velocity = Vector2::new(120.0, 0.0);

        if let Some(pos) = get_local_pos_2d!(ctx.run, ctx.id) {
            set_local_pos_2d!(ctx.run, ctx.id, pos + velocity * dt);
        }
    }
});

`UVector2`

Signature:

pub struct UVector2 {
    pub x: u32,
    pub y: u32,
}

Use when a value must be non-negative and integer-sized, such as tile positions or texture/grid extents.

Common methods and conversions:

Signature	Returns	Use when
`pub const fn UVector2::new(x: u32, y: u32) -> Self`	`UVector2`	Build unsigned 2D coords.
`pub const fn to_array(self) -> [u32; 2]`	`[u32; 2]`	Pass grid coords to array-based APIs.
`pub const fn to_tuple(self) -> (u32, u32)`	`(u32, u32)`	Destructure into normal Rust tuple flow.
`pub fn as_vector2(self) -> Vector2`	`Vector2`	Feed integer coords to float APIs.
`pub fn dot(self, rhs: Self) -> u64`	`u64`	Compare unsigned grid direction/alignment.
`pub fn length_squared(self) -> u64`	`u64`	Compare unsigned magnitude without sqrt.
`pub fn min(self, rhs: Self) -> Self` / `pub fn max(self, rhs: Self) -> Self`	`UVector2`	Pick per-axis lower/upper unsigned values.
`pub fn clamp(self, min: Self, max: Self) -> Self`	`UVector2`	Keep tile coords inside a per-axis range.
`pub fn negated(self) -> Self`	`UVector2`	Get wrapping-negated copy.
`pub fn negate(&mut self) -> &mut Self`	`&mut Self`	Mutate to wrapping-negated value.
`pub fn stepped(self, to: Self, step: u32) -> Self`	`UVector2`	Get copy moved toward target by fixed step.
`pub fn step(&mut self, to: Self, step: u32) -> &mut Self`	`&mut Self`	Mutate unsigned coords toward target.
`pub fn Vector2::as_uvector2_floor(self) -> UVector2`	`UVector2`	Convert world/pixel coords to lower grid cell.
`pub fn Vector2::as_uvector2_round(self) -> UVector2`	`UVector2`	Convert with nearest-cell rounding.
`pub fn Vector2::as_uvector2_ceil(self) -> UVector2`	`UVector2`	Convert to upper grid cell.
`pub fn Vector2::as_uvector2_saturating(self) -> UVector2`	`UVector2`	Clamp negative/non-finite input to zero.
`pub fn UVector2::as_ivector2_saturating(self) -> IVector2`	`IVector2`	Convert unsigned coords to signed coords.

Example:

let tile = UVector2::new(12, 8);
let tile_center = tile.as_vector2() + Vector2::new(0.5, 0.5);
let next_tile = tile.stepped(UVector2::new(20, 8), 2);
let packed = next_tile.to_array();
let travel_score = tile.dot(next_tile);

`IVector2`

Signature:

pub struct IVector2 {
    pub x: i32,
    pub y: i32,
}

Use when integer coords may go below zero, such as chunk coords around world origin, grid deltas, signed tile offsets, or editor cell positions.

Common methods and conversions:

Signature	Returns	Use when
`pub const fn IVector2::new(x: i32, y: i32) -> Self`	`IVector2`	Build signed 2D coords.
`pub const ZERO: IVector2` / `pub const ONE: IVector2` / `pub const NEG_ONE`	`IVector2`	Common signed constants.
`pub const fn to_array(self) -> [i32; 2]`	`[i32; 2]`	Pass signed coords to array-based APIs.
`pub const fn to_tuple(self) -> (i32, i32)`	`(i32, i32)`	Destructure into normal Rust tuple flow.
`pub fn as_vector2(self) -> Vector2`	`Vector2`	Feed signed grid coords to float APIs.
`pub fn as_uvector2_saturating(self) -> UVector2`	`UVector2`	Clamp negative coords to zero for sizes.
`pub fn dot(self, rhs: Self) -> i64`	`i64`	Compare signed grid direction/alignment.
`pub fn length_squared(self) -> i64`	`i64`	Compare signed magnitude without sqrt.
`pub fn min(self, rhs: Self) -> Self` / `pub fn max(self, rhs: Self) -> Self`	`IVector2`	Pick per-axis lower/upper signed values.
`pub fn clamp(self, min: Self, max: Self) -> Self`	`IVector2`	Keep signed coords inside a per-axis range.
`pub fn negated(self) -> Self`	`IVector2`	Get negated copy.
`pub fn negate(&mut self) -> &mut Self`	`&mut Self`	Mutate to negated value.
`pub fn abs(self) -> Self`	`IVector2`	Get per-axis absolute values.
`pub fn signum(self) -> Self`	`IVector2`	Get per-axis sign (-1, 0, or 1).
`pub fn stepped(self, to: Self, step: u32) -> Self`	`IVector2`	Get copy moved toward target by fixed step.
`pub fn step(&mut self, to: Self, step: u32) -> &mut Self`	`&mut Self`	Mutate signed coords toward target.
`pub fn Vector2::as_ivector2_floor(self) -> IVector2`	`IVector2`	Convert world/pixel coords to lower grid cell.
`pub fn Vector2::as_ivector2_round(self) -> IVector2`	`IVector2`	Convert with nearest-cell rounding.
`pub fn Vector2::as_ivector2_ceil(self) -> IVector2`	`IVector2`	Convert to upper grid cell.
`pub fn Vector2::as_ivector2_saturating(self) -> IVector2`	`IVector2`	Clamp non-finite/out-of-range input.

Example:

let chunk = IVector2::new(-2, 4);
let neighbor = chunk + IVector2::new(1, 0);
let world_cell = neighbor.as_vector2();
let atlas_cell = neighbor.as_uvector2_saturating();
let packed = chunk.to_tuple();
let travel_score = chunk.dot(neighbor);

`Transform2D`

Signature:

pub struct Transform2D {
    pub position: Vector2,
    pub scale: Vector2,
    pub rotation: f32,
}

Use when an API needs full 2D node transform state instead of separate position/rotation/scale calls.

Common APIs:

Signature	Returns	Use when
`pub const IDENTITY: Transform2D`	`Transform2D`	Reset transform.
`pub const fn Transform2D::new(pos: Vector2, rot: f32, scale: Vector2) -> Self`	`Transform2D`	Build full transform.
`pub fn to_mat3(&self) -> Mat3`	`Mat3`	Convert to matrix for render/math transforms.
`pub fn from_mat3(mat: Mat3) -> Self`	`Transform2D`	Extract transform from matrix.
`pub fn lerped(self, to: Self, t: f32) -> Self`	`Transform2D`	Blend full transform over shortest rot path.
`pub fn lerp(&mut self, to: Self, t: f32) -> &mut Self`	`&mut Self`	Blend full transform in place.

Example:

lifecycle!({
    fn on_init(&self, ctx: &mut ScriptContext<'_, API>) {
        let transform = Transform2D::new(
            Vector2::new(64.0, 32.0),
            0.0,
            Vector2::ONE,
        );

        set_local_transform_2d!(ctx.run, ctx.id, transform);
    }
});

`DrawShape2D`

Use when building immediate 2D draw commands for debug overlays, editor-style helpers, or simple runtime shapes.

Most scripts use the helper methods/macros instead of constructing every enum variant directly.

Shape constructors:

Signature	Returns	Use when
`pub const fn DrawShape2D::circle(radius: f32, color: Color) -> Self`	`DrawShape2D`	Draw filled circle.
`pub const fn ring(radius: f32, color: Color, thickness: f32) -> Self`	`DrawShape2D`	Draw circle outline.
`pub const fn rect(size: Vector2, color: Color) -> Self`	`DrawShape2D`	Draw filled rectangle.
`pub const fn rect_stroke(size: Vector2, color: Color, thickness: f32) -> Self`	`DrawShape2D`	Draw rectangle outline.
`pub const fn line(end: Vector2, color: Color, thickness: f32) -> Self`	`DrawShape2D`	Draw segment from local origin to `end`.
`pub fn polyline(points: impl Into<Arc<[Vector2]>>, color: Color, thickness: f32) -> Self`	`DrawShape2D`	Draw connected open points.
`pub fn polygon(points: impl Into<Arc<[Vector2]>>, color: Color, thickness: f32) -> Self`	`DrawShape2D`	Draw connected closed points.
`pub fn path(points: impl Into<Arc<[Vector2]>>, color: Color, thickness: f32) -> Self`	`DrawShape2D`	Draw path data.
`pub const fn sprite(texture: TextureID, size: Vector2, tint: Color) -> Self`	`DrawShape2D`	Draw full texture.
`pub const fn atlas_sprite(texture: TextureID, size: Vector2, tint: Color, texture_region: [f32; 4]) -> Self`	`DrawShape2D`	Draw texture region.

Example:

lifecycle!({
    fn on_update(&self, ctx: &mut ScriptContext<'_, API>) {
        ctx.res.Draw2D().circle(
            Vector2::new(0.0, 0.0),
            16.0,
            [1.0, 0.2, 0.2, 1.0],
        );
    }
});

Navigation Menu

Uh oh!

Uh oh!

2D Structs

Page Map

Purpose

Use Cases

Decision Guide

Struct Table

`Vector2`

`UVector2`

`IVector2`

`Transform2D`

`DrawShape2D`

Uh oh!

Uh oh!

FilesExpand file tree

2d.md

Latest commit

History

2d.md

File metadata and controls

2D Structs

Page Map

Purpose

Use Cases

Decision Guide

Struct Table

Vector2

UVector2

IVector2

Transform2D

DrawShape2D

`Vector2`

`UVector2`

`IVector2`

`Transform2D`

`DrawShape2D`