0
# Math Utilities and Types
1

2
Mathematical functions, vector operations, geometric utilities, color types, and game-specific calculations for comprehensive game development support.
3

4
## Capabilities
5

6
### Core Math Functions
7

8
```python { .api }
9
def clamp(value: float, min_value: float, max_value: float) -> float:
10
    """Clamp value between minimum and maximum."""
11

12
def lerp(start: float, end: float, t: float) -> float:
13
    """Linear interpolation between two values."""
14

15
def lerp_2d(start: tuple[float, float], end: tuple[float, float], t: float) -> tuple[float, float]:
16
    """2D linear interpolation."""
17

18
def get_distance(x1: float, y1: float, x2: float, y2: float) -> float:
19
    """Calculate distance between two points."""
20

21
def get_angle_degrees(x1: float, y1: float, x2: float, y2: float) -> float:
22
    """Get angle in degrees between two points."""
23

24
def get_angle_radians(x1: float, y1: float, x2: float, y2: float) -> float:
25
    """Get angle in radians between two points."""
26

27
def rotate_point(x: float, y: float, cx: float, cy: float, angle: float) -> tuple[float, float]:
28
    """Rotate point around center."""
29
```
30

31
### Vector Types
32

33
```python { .api }
34
class Vec2:
35
    """2D vector class with mathematical operations."""
36
    def __init__(self, x: float = 0, y: float = 0):
37
        """Create 2D vector."""
38
    
39
    x: float
40
    y: float
41
    
42
    def __add__(self, other: 'Vec2') -> 'Vec2':
43
        """Vector addition."""
44
    
45
    def __sub__(self, other: 'Vec2') -> 'Vec2':
46
        """Vector subtraction."""
47
    
48
    def __mul__(self, scalar: float) -> 'Vec2':
49
        """Scalar multiplication."""
50
    
51
    def dot(self, other: 'Vec2') -> float:
52
        """Dot product."""
53
    
54
    def length(self) -> float:
55
        """Vector magnitude."""
56
    
57
    def normalize(self) -> 'Vec2':
58
        """Normalized vector."""
59

60
class Vec3:
61
    """3D vector class."""
62
    def __init__(self, x: float = 0, y: float = 0, z: float = 0):
63
        """Create 3D vector."""
64
    
65
    x: float
66
    y: float
67
    z: float
68
```
69

70
### Random Generation
71

72
```python { .api }
73
def rand_in_rect(rect: arcade.types.Rect) -> tuple[float, float]:
74
    """Random point within rectangle."""
75

76
def rand_in_circle(center_x: float, center_y: float, radius: float) -> tuple[float, float]:
77
    """Random point within circle."""
78

79
def rand_on_circle(center_x: float, center_y: float, radius: float) -> tuple[float, float]:
80
    """Random point on circle circumference."""
81

82
def rand_angle_360_deg() -> float:
83
    """Random angle 0-360 degrees."""
84

85
def rand_vec_magnitude(angle: float, lo_magnitude: float, hi_magnitude: float) -> tuple[float, float]:
86
    """Random vector with specified angle and magnitude range."""
87
```
88

89
### Color Types and Constants
90

91
```python { .api }
92
# Color type definitions
93
RGB = tuple[int, int, int]
94
RGBA = tuple[int, int, int, int]
95
RGBOrA = RGB | RGBA
96

97
class Color:
98
    """Color utility class with conversion methods."""
99
    def __init__(self, r: int, g: int, b: int, a: int = 255):
100
        """Create color from RGBA values."""
101
    
102
    r: int
103
    g: int
104
    b: int
105
    a: int
106
    
107
    @classmethod
108
    def from_hex_string(cls, hex_string: str) -> 'Color':
109
        """Create color from hex string (e.g., '#FF0000')."""
110
    
111
    def to_hex_string(self) -> str:
112
        """Convert to hex string."""
113
    
114
    def to_tuple(self) -> tuple[int, int, int, int]:
115
        """Convert to RGBA tuple."""
116

117
# Common colors
118
BLACK: Color = (0, 0, 0, 255)
119
WHITE: Color = (255, 255, 255, 255)
120
RED: Color = (255, 0, 0, 255)
121
GREEN: Color = (0, 255, 0, 255)
122
BLUE: Color = (0, 0, 255, 255)
123
```
124

125
### Geometry Types
126

127
```python { .api }
128
# Point types
129
Point = tuple[float, float]
130
Point2 = tuple[float, float]
131
Point3 = tuple[float, float, float]
132
PointList = list[Point]
133

134
# Rectangle classes
135
class Rect:
136
    """General rectangle class."""
137
    def __init__(self, x: float, y: float, width: float, height: float):
138
        """Create rectangle."""
139
    
140
    x: float
141
    y: float
142
    width: float
143
    height: float
144
    
145
    def contains_point(self, x: float, y: float) -> bool:
146
        """Check if point is inside rectangle."""
147
    
148
    def intersects(self, other: 'Rect') -> bool:
149
        """Check if rectangles intersect."""
150

151
class LRBT:
152
    """Rectangle defined by left, right, bottom, top."""
153
    def __init__(self, left: float, right: float, bottom: float, top: float):
154
        """Create LRBT rectangle."""
155
    
156
    left: float
157
    right: float
158
    bottom: float
159
    top: float
160

161
class LBWH:
162
    """Rectangle defined by left, bottom, width, height."""
163
    def __init__(self, left: float, bottom: float, width: float, height: float):
164
        """Create LBWH rectangle."""
165
    
166
    left: float
167
    bottom: float
168
    width: float
169
    height: float
170
```
171

172
## Usage Examples
173

174
### Vector Math
175

176
```python
177
import arcade
178
import arcade.math
179

180
# Create vectors
181
velocity = arcade.math.Vec2(5.0, 3.0)
182
position = arcade.math.Vec2(100.0, 200.0)
183

184
# Vector operations
185
new_position = position + velocity
186
distance = velocity.length()
187
direction = velocity.normalize()
188

189
# Angle calculations
190
angle = arcade.get_angle_degrees(0, 0, 100, 100)  # 45 degrees
191
rotated_point = arcade.rotate_point(10, 0, 0, 0, 90)  # (0, 10)
192

193
# Interpolation
194
start_pos = (0, 0)
195
end_pos = (100, 100)
196
half_way = arcade.lerp_2d(start_pos, end_pos, 0.5)  # (50, 50)
197
```