isometric-core/io.github.jayteealao.isometric/IsometricEngine

IsometricEngine

class IsometricEngine @JvmOverloads constructor(angle: Double = PI / 6, scale: Double = 70.0, colorDifference: Double = 0.2, lightColor: IsoColor = IsoColor.WHITE) : SceneProjector

Core isometric rendering engine. Platform-agnostic — outputs PreparedScene that can be rendered by any platform.

This class is a thin facade that delegates to focused collaborators:

SceneGraph — mutable scene state accumulation
IsometricProjection — 3D-to-2D projection, lighting, culling
DepthSorter — intersection-based depth sorting with broad-phase acceleration
HitTester — hit testing with point-in-polygon and touch radius

Coordinate System

The engine uses a standard isometric projection with configurable angle (default 30°) and scale (default 70 pixels per unit).

            z (up)
            |
            |
           / \
          /   \
         y     x
    (left-down) (right-down)

x-axis: points right-and-down on screen
y-axis: points left-and-down on screen
z-axis: points straight up on screen

Projection formulas

The 3D-to-2D projection is:

screenX = originX + x * scale * cos(angle) + y * scale * cos(PI - angle)
screenY = originY - x * scale * sin(angle) - y * scale * sin(PI - angle) - z * scale

Depth sorting

Faces are sorted back-to-front using Point.depth: x + y - 2 * z. Higher depth values are farther from the viewer and drawn first.

Constructors

IsometricEngine

@JvmOverloads

constructor(angle: Double = PI / 6, scale: Double = 70.0, colorDifference: Double = 0.2, lightColor: IsoColor = IsoColor.WHITE)

Types

Companion

object Companion

Properties

angle

var angle: Double

The isometric projection angle in radians. Changing this at runtime recomputes the internal projection matrix.

projectionVersion

@Volatile

open override var projectionVersion: Long

Monotonically increasing version counter, incremented whenever mutable engine parameters (angle, scale) change. Signals caches that projected output may be stale. Volatile to ensure visibility when read by the renderer on a different thread (e.g. Canvas draw vs main-thread mutation).

scale

var scale: Double

The isometric scale factor (pixels per world unit). Changing this at runtime recomputes the internal projection matrix.

Functions

add

open override fun add(shape: Shape, color: IsoColor)

Adds all faces of a Shape to the scene with the given color.

open override fun add(path: Path, color: IsoColor, originalShape: Shape?, id: String?, ownerNodeId: String?)

Adds a single Path (polygon face) to the scene.

clear

open override fun clear()

Removes all items from the scene graph.

findItemAt

open override fun findItemAt(preparedScene: PreparedScene, x: Double, y: Double, order: HitOrder, touchRadius: Double): RenderCommand?

Finds the RenderCommand at the given screen coordinates in the prepared scene.

projectScene

open override fun projectScene(width: Int, height: Int, renderOptions: RenderOptions, lightDirection: Vector): PreparedScene

Projects the 3D scene to 2D screen space for the given viewport size.

screenToTile

fun IsometricEngine.screenToTile(screenX: Double, screenY: Double, viewportWidth: Int, viewportHeight: Int, tileSize: Double = 1.0, elevation: Double = 0.0, originOffset: Point = Point.ORIGIN): TileCoordinate

Returns the TileCoordinate of the tile at the given screen position on the specified z-plane.

screenToWorld

fun screenToWorld(screenPoint: Point2D, viewportWidth: Int, viewportHeight: Int, z: Double = 0.0): Point

Unproject a 2D screen point back to 3D world coordinates on a given plane.

worldToScreen

fun worldToScreen(point: Point, viewportWidth: Int, viewportHeight: Int): Point2D

Project a 3D world point to 2D screen coordinates.