Minimap Utilities

Coordinate transforms, drawing helpers, color sets, and boundary clamping for the minimap.

Overview

ui_apps_minimap_utils provides the core math (world-to-map transforms, boundary clamping) and drawing primitives (circles, lines, edge pointers) used by all minimap sub-modules.

Extension path: lua/ge/extensions/ui/apps/minimap/utils.lua

Exports (M)

State Management

Function	Signature	Description
`setMinimapState`	`(w, h, cx, cy, camPos, camRot, camRotInverse, scale, scaleInverse, td, ox, oy, mode, dpi)`	Called by main minimap each frame to sync state.

Coordinate Transforms

Function	Signature	Description
`worldToMap`	`(pos) → vec3`	Transforms a world vec3 to minimap pixel coords.
`worldToMapXYZ`	`(target, source)`	In-place transform: writes minimap coords into `target` from `source`. Zero-alloc.
`worldToMapXY`	`(x, y) → mapX, mapY`	Scalar version - returns minimap coords from world x,y.
`mapToWorld`	`(pos) → vec3`	Inverse transform: minimap coords → world position.

Boundary Helpers

Function	Signature	Description
`isInsideMinimapBounds`	`(pos, buffer?) → bool`	Tests if a minimap-space point is within bounds.
`clampToMinimapBounds`	`(pos, buffer?)`	Clamps a minimap-space point to bounds (mutates).
`setClampToBounds`	`(pos, inset?, maxDist?) → pos, wasClamped`	Ray-based clamping to circle or rect boundary.

Drawing Helpers

Function	Signature	Description
`simpleCircle`	`(worldPos, fill?, stroke?, radius?)`	Draws a filled+stroked circle at a world position.
`simpleLine`	`(pos1, pos2, fill?, stroke?)`	Draws a stroked line between two world positions.
`simpleCircleWithEdgePointer`	`(worldPos, fill?, stroke?, radius?)`	Circle if on-screen, directional edge pointer if off-screen.
`simpleLineWithEdgePointer`	`(pos1, pos2, fill?, stroke?)`	Line if on-screen, edge pointer at midpoint if off-screen.
`drawEdgePointer`	`(worldPos, fill?, stroke?, radius?, maxDist?) → bool`	Draws a directional triangle+circle at the minimap edge. Returns true if clamped.
`drawGrid`	`()`	Draws a 50m-spaced grid overlay.
`getDefaultStyleColorSet`	`()`	Returns the default style color set for minimap rendering.

Data Fields

Field	Description
`M.centerPointer`	Function that centers the map pointer/cursor.

Internals

Transform Math

The core transform applies offset, scale, and rotation in one pass:

local function worldToMapXY(x, y)
  x = (x - camPos.x) * scaleInverse
  y = (y - camPos.y) * scaleInverse
  local tX = x
  x = halfWidthWithOffset  + (tX * camFwd.x + y * camRight.x)
  y = halfHeightWithOffset - (tX * camFwd.y + y * camRight.y)
  return x, y
end

Boundary Clamping

setClampToBounds supports both modes:

Circle: Clamps to width/2 - inset radius from center
Rect: Ray-cast from center to target, intersecting against 4 rectangle edges using Cramer's rule

Color Palette

M.colors = {
  orange         = color(255,115,10,255),
  orangeMuted    = color(255*0.8,165*0.8,80,255),
  grayMuted      = color(100,100,100,255),
  roadBgTransparentBlack = color(50,50,50,255),
  navBgWhite     = color(255,255,255,255),
  navFgBlue      = color(0,102,255,255),
  gridWhite      = color(160,160,160,255),
}

Style Color Sets

Six predefined color themes (Default, Monochrome, Green, Blue, Orange, Grayscale) control road and UI element colors. Access via getStyleColorSet() and getCurrentStyleColors().

How It Works

Main minimap calls setMinimapState() each frame with camera and canvas data
All sub-modules use worldToMapXYZ / worldToMapXY for coordinate projection
Drawing helpers handle world→map transform + primitive rendering in one call
Edge pointers auto-detect off-screen positions and draw directional indicators at the boundary

Additional Exports

The following exports are available but not yet documented in detail:

M.clampToMinimapBounds
M.dpi
M.drawEdgePointer
M.drawGrid
M.getCurrentStyleColors
M.getDefaultStyleColorSet
M.getStyleColorSet
M.isInsideMinimapBounds
M.mapToWorld
M.setClampToBounds
M.setMinimapState
M.simpleCircle
M.simpleCircleWithEdgePointer
M.simpleLine
M.simpleLineWithEdgePointer
M.worldToMap
M.worldToMapXY
M.worldToMapXYZ

Overview

ui_apps_minimap_utils provides the core math (world-to-map transforms, boundary clamping) and drawing primitives (circles, lines, edge pointers) used by all minimap sub-modules.

Extension path: lua/ge/extensions/ui/apps/minimap/utils.lua

Exports (M)

State Management

Function	Signature	Description
`setMinimapState`	`(w, h, cx, cy, camPos, camRot, camRotInverse, scale, scaleInverse, td, ox, oy, mode, dpi)`	Called by main minimap each frame to sync state.

Coordinate Transforms

Function	Signature	Description
`worldToMap`	`(pos) → vec3`	Transforms a world vec3 to minimap pixel coords.
`worldToMapXYZ`	`(target, source)`	In-place transform: writes minimap coords into `target` from `source`. Zero-alloc.
`worldToMapXY`	`(x, y) → mapX, mapY`	Scalar version - returns minimap coords from world x,y.
`mapToWorld`	`(pos) → vec3`	Inverse transform: minimap coords → world position.

Boundary Helpers

Function	Signature	Description
`isInsideMinimapBounds`	`(pos, buffer?) → bool`	Tests if a minimap-space point is within bounds.
`clampToMinimapBounds`	`(pos, buffer?)`	Clamps a minimap-space point to bounds (mutates).
`setClampToBounds`	`(pos, inset?, maxDist?) → pos, wasClamped`	Ray-based clamping to circle or rect boundary.

Drawing Helpers

Function	Signature	Description
`simpleCircle`	`(worldPos, fill?, stroke?, radius?)`	Draws a filled+stroked circle at a world position.
`simpleLine`	`(pos1, pos2, fill?, stroke?)`	Draws a stroked line between two world positions.
`simpleCircleWithEdgePointer`	`(worldPos, fill?, stroke?, radius?)`	Circle if on-screen, directional edge pointer if off-screen.
`simpleLineWithEdgePointer`	`(pos1, pos2, fill?, stroke?)`	Line if on-screen, edge pointer at midpoint if off-screen.
`drawEdgePointer`	`(worldPos, fill?, stroke?, radius?, maxDist?) → bool`	Draws a directional triangle+circle at the minimap edge. Returns true if clamped.
`drawGrid`	`()`	Draws a 50m-spaced grid overlay.
`getDefaultStyleColorSet`	`()`	Returns the default style color set for minimap rendering.

Data Fields

Field	Description
`M.centerPointer`	Function that centers the map pointer/cursor.

Internals

Transform Math

The core transform applies offset, scale, and rotation in one pass:

local function worldToMapXY(x, y)
  x = (x - camPos.x) * scaleInverse
  y = (y - camPos.y) * scaleInverse
  local tX = x
  x = halfWidthWithOffset  + (tX * camFwd.x + y * camRight.x)
  y = halfHeightWithOffset - (tX * camFwd.y + y * camRight.y)
  return x, y
end

Boundary Clamping

setClampToBounds supports both modes:

Circle: Clamps to width/2 - inset radius from center
Rect: Ray-cast from center to target, intersecting against 4 rectangle edges using Cramer's rule

Color Palette

M.colors = {
  orange         = color(255,115,10,255),
  orangeMuted    = color(255*0.8,165*0.8,80,255),
  grayMuted      = color(100,100,100,255),
  roadBgTransparentBlack = color(50,50,50,255),
  navBgWhite     = color(255,255,255,255),
  navFgBlue      = color(0,102,255,255),
  gridWhite      = color(160,160,160,255),
}

Style Color Sets

Six predefined color themes (Default, Monochrome, Green, Blue, Orange, Grayscale) control road and UI element colors. Access via getStyleColorSet() and getCurrentStyleColors().

How It Works

Main minimap calls setMinimapState() each frame with camera and canvas data
All sub-modules use worldToMapXYZ / worldToMapXY for coordinate projection
Drawing helpers handle world→map transform + primitive rendering in one call
Edge pointers auto-detect off-screen positions and draw directional indicators at the boundary

Additional Exports

The following exports are available but not yet documented in detail:

M.clampToMinimapBounds
M.dpi
M.drawEdgePointer
M.drawGrid
M.getCurrentStyleColors
M.getDefaultStyleColorSet
M.getStyleColorSet
M.isInsideMinimapBounds
M.mapToWorld
M.setClampToBounds
M.setMinimapState
M.simpleCircle
M.simpleCircleWithEdgePointer
M.simpleLine
M.simpleLineWithEdgePointer
M.worldToMap
M.worldToMapXY
M.worldToMapXYZ

Minimap Utilities

Overview

Exports (M)

State Management

Coordinate Transforms

Boundary Helpers

Drawing Helpers

Data Fields

Internals

Transform Math

Boundary Clamping

Color Palette

Style Color Sets

How It Works

Additional Exports

See Also

On this page

Minimap Utilities

Overview

Exports (M)

State Management

Coordinate Transforms

Boundary Helpers

Drawing Helpers

Data Fields

Internals

Transform Math

Boundary Clamping

Color Palette

Style Color Sets

How It Works

Additional Exports

See Also

On this page