Build a mod

WebGL

Draw your own shapes in the 3D world, or over the finished frame, with the browser's WebGL 2 API.

Advertisement

ctx is great for flat things on the screen. When you want to draw in the world itself, like a beam over a waypoint or a box around a block, use gl. It is the browser's WebGL 2 API with the same function and constant names (gl.createBuffer, gl.TRIANGLES and so on), so any WebGL 2 tutorial works here too.

This is the most advanced part of modding. If you have never used WebGL or OpenGL, read a WebGL 2 tutorial first and come back. And if all you need is a label that follows a spot in the world, skip ahead to the easy way.

Where you can draw

GL calls only work inside two events. Anywhere else, they throw an error.

  • render_world runs right after the world is drawn, before your hand. The game's main framebuffer is bound with the world's depth buffer, so your shapes can hide behind blocks.
  • render_overlay runs after all the 2D drawing, on the same framebuffer. Use it for things that sit on top of everything.

Zeus saves the game's GL state before your first call and puts it back afterwards, so you can change any state you like without breaking the game.

gl only exists in the browser. gl.available() tells you whether you have it.

The view

Both events give you a view table.

In render_world:

FieldWhat it is
view.projectionthe projection matrix, 16 numbers in column-major order
view.viewthe camera's view matrix, in the same format
view.x, view.y, view.zthe camera's position in the world
view.width, view.heightthe size of the framebuffer in real pixels
view.partialTickhow far the game is between two ticks, from 0 to 1
view.depthFuncthe depth test to use against the world
view.reversedZtrue when this game version uses a reversed depth buffer

In render_overlay:

FieldWhat it is
view.orthoa matrix that maps GUI pixels to clip space
view.width, view.heightthe size of the framebuffer in real pixels
view.guiWidth, view.guiHeight, view.guiScalethe GUI size and scale

Positions you draw in render_world are relative to the camera. To put something at world position x, y, z, subtract the camera: x - view.x, y - view.y, z - view.z.

Some game versions use a reversed depth buffer, where near is 1 and far is 0. Call gl.depthFunc(view.depthFunc) and your depth test works on every version.

A triangle in the world

local prog, vbo, loc

local function setup()
  prog = gl.program([[#version 300 es
    in vec3 pos;
    uniform mat4 mvp;
    void main() { gl_Position = mvp * vec4(pos, 1.0); }]], [[#version 300 es
    precision mediump float;
    out vec4 color;
    void main() { color = vec4(1.0, 0.3, 0.3, 0.6); }]])
  vbo = gl.createBuffer()
  loc = gl.getUniformLocation(prog, "mvp")
end

on("render_world", function(view)
  if not prog then setup() end

  local x, y, z = -view.x, 70 - view.y, -view.z

  gl.bindBuffer(gl.ARRAY_BUFFER, vbo)
  gl.bufferData(gl.ARRAY_BUFFER, gl.f32{ x, y, z, x + 1, y, z, x, y + 1, z }, gl.DYNAMIC_DRAW)
  gl.useProgram(prog)
  gl.uniformMatrix4fv(loc, false, matrix.multiply(view.projection, view.view))
  gl.enableVertexAttribArray(0)
  gl.vertexAttribPointer(0, 3, gl.FLOAT, false, 0, 0)
  gl.enable(gl.BLEND)
  gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA)
  gl.drawArrays(gl.TRIANGLES, 0, 3)
end)

It builds the shader and buffer the first time it runs, then draws a see-through red triangle at height 70 above the world's center (x = 0, z = 0) every frame.

Helpers Zeus adds

HelperWhat it does
gl.program(vs, fs)compiles and links a shader program, with readable errors when something is wrong
gl.f32, gl.i8, gl.u8, gl.i16, gl.u16, gl.i32, gl.u32make typed arrays from a table, or empty ones from a length. You can also pass a plain table where float data is expected
gl.gameTexture("color"), gl.gameTexture("depth")the game's main color and depth textures, to read in your shaders
gl.mainFramebuffer()binds the game's main target again after you drew into your own framebuffer
gl.size()the width and height of the target you are drawing to

GL objects are plain numbers (handles). Everything your mod creates is deleted for you when it unloads, so you do not have to clean up.

Matrices

The matrix library builds the 4x4 matrices you need, as column-major tables of 16 numbers.

FunctionWhat it gives you
matrix.identity()the identity matrix
matrix.multiply(a, b)a times b
matrix.translate(m, x, y, z)m moved by x, y, z
matrix.scale(m, x, y, z)m scaled. y and z are the same as x if you leave them out
matrix.rotate(m, deg, x, y, z)m rotated by deg degrees around the axis x, y, z
matrix.perspective(fov, aspect, near, far)a perspective projection
matrix.ortho(left, right, bottom, top, near, far)an orthographic projection
matrix.transform(m, x, y, z, w)the point x, y, z, w multiplied by m, as four numbers

The easy way to mark a spot

camera.project(x, y, z) turns a world position into a position on the screen, in GUI pixels. It gives you back x, y and a depth, or nil when the spot is behind you. For a label over a waypoint, that is all you need, and it works without any WebGL.

hud.add(function(ctx)
  local sx, sy = camera.project(0.5, 80, 0.5)
  if sx then
    ctx:centeredText("Spawn", sx, sy, "yellow")
  end
end)

The position is not kept on the screen for you, so a spot far to the side can come back with an x past the edge.