Lua mirror

Open Markdown

Viewpoint.Addons is a mirror for reading. A Lua mod can read two things: the view state, and the settings that an addon shares. Viewpoint changes nothing through these functions.

To call the Java functions of your own addon from Lua, use exports. See Lua exports. The exports of an addon are in Viewpoint.Addons["<id>"]. The functions on this page are in Viewpoint.Addons itself.

The functions

Function	Gives
`Viewpoint.Addons.viewState()`	A table with the fields below. `nil` the first time, and after a pause of two seconds without a call.
`Viewpoint.Addons.terrainHeight(x, y)`	The ground height at the point, or `nil`. `nil` also for a number that is not finite.
`Viewpoint.Addons.setting(addonId, name)`	The current value of one setting of one addon: a boolean, a number or a string. `nil` if the addon is off, the setting does not exist, or the addon did not share it (see below).

Viewpoint builds the view state only while it is asked for. Call viewState() each frame to keep it. The first call, or the first call after a pause of two seconds, answers nil, and the next frame has the table.

An addon shares a setting with <name>.lua=true in its settings.properties. Every other setting answers nil. Any mod can read a shared setting, so share only what you want every mod to see.

The table of the view state:

local v = Viewpoint.Addons.viewState()

if v and v.on then
    print(v.mode)               -- "FIRST_PERSON" or "THIRD_PERSON"
    print(v.eye.x, v.eye.y, v.eye.z, v.eye.yaw, v.eye.pitch)
    print(v.fov)
    print(v.crosshair.x, v.crosshair.y, v.crosshair.z)         -- the ray's origin
    print(v.crosshair.dx, v.crosshair.dy, v.crosshair.dz)      -- its direction
    print(v.versions.game, v.versions.viewpoint, v.versions.api)
    print(v.freeCamera, v.cursorCaptured)
    print(v.sceneOrigin.x, v.sceneOrigin.y, v.sceneOrigin.z)
    if v.crosshairHit then print(v.crosshairHit.x, v.crosshairHit.y, v.crosshairHit.z) end -- nil if it meets nothing
    if v.cursorHit then print(v.cursorHit.x, v.cursorHit.y, v.cursorHit.z) end             -- under the free cursor
end

The fields and units are the same as in ViewState. The coordinates are the game’s world coordinates.

Rules

Call the functions on the main thread. The game’s Lua runs there.
There are no callbacks. Ask each frame, or when your own trigger occurs.
You do not need an addon. The Lua of all mods can call these functions.
setting gives the value that the player has set now. This includes a value that has an effect only at the next enable.
The table that you get is a copy. If you change it, nothing changes in Viewpoint.
Viewpoint.Addons is one table that every mod shares, and it also holds the exports of the addons by their ids. Lua lets a mod write to it. A mod that does can change what a different mod reads from it. Viewpoint does not protect the table.