ScreenConvert¶

Overview¶

The ScreenConvert table contains functions which will convert to and from screen positions and in-game coordinate positions.

Info

Conversions from a screen position into a CoordGrid or CoordFine without supplying a level will output at the same level as the active player character.

Examples¶

-- The screen position at the feet of the player entity
local playerScreenPos = ScreenConvert.Vector3ToScreen(Player.GetEntity().position)

-- The tile currently under the mouse cursor
-- Outputs a tile at the same level as the player character
local coordGrid = ScreenConvert.ScreenToCoordGrid(Mouse.GetPosition())
-- This outputs a tile at the specified level instead
local coordGrid = ScreenConvert.ScreenToCoordGrid(Mouse.GetPosition(), 3)

Functions¶

ScreenToCoordGrid(position)¶

function ScreenConvert.ScreenToCoordGrid(position : Vector2) -> CoordGrid?

Returns the CoordGrid under the given screen position.
Resulting coord will be on the same level as the player character.

Parameter	Type	Description
position	Vector2	The XY screen position to convert.

Returns	Description
CoordGrid?	The tile coordinate to return. Returns `nil` if the active player or game world is unavailable, or if there is no tile beneath the given screen position.

Example

if Mouse.IsAvailable() then
    local coordGrid = ScreenConvert.ScreenToCoordGrid(Mouse.GetPosition())
end

ScreenToCoordGrid(position, level)¶

function ScreenConvert.ScreenToCoordGrid(position : Vector2, level : Integer) -> CoordGrid?

Returns the CoordGrid for the specified level under the given screen position.

Parameter	Type	Description
position	Vector2	The XY screen position to convert.
level	Integer	The level to output the coordinate for. The value of `level` must be between `0` and `3`.

Returns	Description
CoordGrid?	The tile coordinate to return. Returns `nil` if the game world is unavailable, the value of `level` is invalid, or if there is no tile beneath the given screen position.

Example

if Mouse.IsAvailable() then
    local coordGrid = ScreenConvert.ScreenToCoordGrid(Mouse.GetPosition(), 3)
end

ScreenToCoordGrid(x, y)¶

function ScreenConvert.ScreenToCoordGrid(x : Integer, y : Integer) -> CoordGrid?

Returns the CoordGrid under the given screen X & Y positions.
Resulting coord will be on the same level as the player character.

Parameter	Type	Description
x	Integer	The X screen position to convert.
y	Integer	The Y screen position to convert.

Returns	Description
CoordGrid?	The tile coordinate to return. Returns `nil` if the active player or game world is unavailable, or if there is no tile beneath the given screen position.

Example

if Mouse.IsAvailable() then
    local coordGrid = ScreenConvert.ScreenToCoordGrid(Mouse.GetX(), Mouse.GetY())
end

ScreenToCoordGrid(x, y, level)¶

function ScreenConvert.ScreenToCoordGrid(x : Integer, y : Integer, level : Integer) -> CoordGrid?

Returns the CoordGrid for the specified level under the given screen X & Y positions.

Parameter	Type	Description
x	Integer	The X screen position to convert.
y	Integer	The Y screen position to convert.
level	Integer	The level to output the coordinate for. The value of `level` must be between `0` and `3`.

Returns	Description
CoordGrid?	The tile coordinate to return. Returns `nil` if the game world is unavailable, the value of `level` is invalid, or if there is no tile beneath the given screen position.

Example

if Mouse.IsAvailable() then
    local coordGrid = ScreenConvert.ScreenToCoordGrid(Mouse.GetX(), Mouse.GetY(), 3)
end

ScreenToCoordFine(position)¶

function ScreenConvert.ScreenToCoordFine(position : Vector2) -> CoordFine?

Returns the CoordFine under the given screen position.
Resulting coord will be on the same level as the player character.

Parameter	Type	Description
position	Vector2	The XY screen position to convert.

Returns	Description
CoordFine?	The tile coordinate to return. Returns `nil` if the active player or game world is unavailable, or if there is no tile beneath the given screen position.

Example

if Mouse.IsAvailable() then
    local coordFine = ScreenConvert.ScreenToCoordFine(Mouse.GetPosition())
end

ScreenToCoordFine(position, level)¶

function ScreenConvert.ScreenToCoordFine(position : Vector2, level : Integer) -> CoordFine?

Returns the CoordFine for the specified level under the given screen position.

Parameter	Type	Description
position	Vector2	The XY screen position to convert.
level	Integer	The level to output the coordinate for. The value of `level` must be between `0` and `3`.

Returns	Description
CoordFine?	The tile coordinate to return. Returns `nil` if the game world is unavailable, the value of `level` is invalid, or if there is no tile beneath the given screen position.

Example

if Mouse.IsAvailable() then
    local coordFine = ScreenConvert.ScreenToCoordFine(Mouse.GetPosition(), 3)
end

ScreenToCoordFine(x, y)¶

function ScreenConvert.ScreenToCoordFine(x : Integer, y : Integer) -> CoordFine?

Returns the CoordFine under the given screen X & Y positions.
Resulting coord will be on the same level as the player character.

Parameter	Type	Description
x	Integer	The X screen position to convert.
y	Integer	The Y screen position to convert.

Returns	Description
CoordFine?	The tile coordinate to return. Returns `nil` if the active player or game world is unavailable, or if there is no tile beneath the given screen position.

Example

if Mouse.IsAvailable() then
    local coordFine = ScreenConvert.ScreenToCoordFine(Mouse.GetX(), Mouse.GetY())
end

ScreenToCoordFine(x, y, level)¶

function ScreenConvert.ScreenToCoordFine(x : Integer, y : Integer, level : Integer) -> CoordFine?

Returns the CoordFine for the specified level under the given screen X & Y positions.

Parameter	Type	Description
x	Integer	The X screen position to convert.
y	Integer	The Y screen position to convert.
level	Integer	The level to output the coordinate for. The value of `level` must be between `0` and `3`.

Returns	Description
CoordFine?	The tile coordinate to return. Returns `nil` if the game world is unavailable, the value of `level` is invalid, or if there is no tile beneath the given screen position.

Example

if Mouse.IsAvailable() then
    local coordFine = ScreenConvert.ScreenToCoordFine(Mouse.GetX(), Mouse.GetY(), 3)
end

CoordGridToScreen¶

function ScreenConvert.CoordGridToScreen(coordGrid : CoordGrid, heightAboveGround : Integer) -> Vector2?

Returns the screen XY position, as a Vector2, of the given CoordGrid.
The position is calculated from the centre of the coordinate tile.
An optional in-game vertical offset heightAboveGround, which in Fine units, can be applied to the coordinate.

Parameter	Type	Description
coordGrid	CoordGrid	The tile coordinate to convert to a screen position. Calculations are made from the centre of the tile.
heightAboveGround	Integer	An additional vertical offset, in Fine units, to add to the tile position before converting.

Returns	Description
Vector2?	The resulting screen XY position. Returns `nil` if the game world or ground data for the given coordinate is unavailable.

Example

local screenPos = ScreenConvert.CoordGridToScreen(Player.GetEntity().coordGrid, 1024)
if screenPos ~= nil then
    -- A valid screen position above the player character's head
end

CoordFineToScreen¶

function ScreenConvert.CoordFineToScreen(coordFine : CoordFine, heightAboveGround : Integer) -> Vector2?

Returns the screen XY position, as a Vector2, of the given CoordFine.
An optional in-game vertical offset heightAboveGround, which in Fine units, can be applied to the coordinate.

Info

The vertical component of CoordFine.position.y is ignored.
Only CoordFine.position.x and CoordFine.position.z are used to calculate the ground height at CoordFine.level.
The value of heightAboveGround is then added to the ground height before converting.

If you need to convert a position with an explicit vertical component, use ScreenConvert.Vector3ToScreen.

Parameter	Type	Description
coordFine	CoordFine	The tile coordinate to convert to a screen position. The vertical position component is ignored (see above).
heightAboveGround	Integer	An additional vertical offset, in Fine units, to add to the tile position before converting.

Returns	Description
Vector2?	The resulting screen XY position. Returns `nil` if the game world or ground data for the given coordinate is unavailable.

Example

local screenPos = ScreenConvert.CoordFineToScreen(Player.GetEntity().coordGrid:ToCoordFine(true), 1024)
if screenPos ~= nil then
    -- A valid screen position above the player character's head
end

Vector3ToScreen¶

function ScreenConvert.Vector3ToScreen(vec3 : Vector3) -> Vector2?

Returns the screen XY position, as a Vector2, of the given Vector3, in Fine units.

Info

This method does not perform a ground height look-up, and so will perform better than coordinate-to-screen conversions.

Parameter	Type	Description
vec3	Vector3	The world position, in Fine units, to convert to a screen position.

Returns	Description
Vector2?	The resulting screen XY position. Returns `nil` if the game world is unavailable.

Example

local screenPos = ScreenConvert.Vector3ToScreen(Player.GetEntity().position + Vector3.new(0, 1024, 0))
if screenPos ~= nil then
    -- A valid screen position above the player character's head
end