Draw3D

com.jsmacrosce.jsmacros.client.api.classes.render.Draw3D

Since1.0.6

A collection of 3D elements rendered as a world overlay.

Elements use world-space block coordinates and are rendered relative to the camera.

Elements render only while this overlay is registered with register() and visible; unregister() stops rendering without removing them, while clear() removes its elements.

Duplicate entries are allowed. Elements are sorted in place before rendering, so typed getters return matching entries in the current sorted order, not insertion order.

// a world overlay with a box and a line in it, registered so it shows
const draw = Hud.createDraw3D();  
draw.addBox(0, 64, 0, 1, 65, 1, Color.rgb(0xFF, 0x00, 0x00), Color.argb(0x88, 0, 0, 0), true);  
draw.addLine(0, 64, 0, 8, 72, 0, Color.rgb(0x00, 0xFF, 0x00));  
draw.register();  

// what went in, in the order it will be drawn
Chat.log(`${draw.getBoxes().size()} boxes, ${draw.getLines().size()} lines`);  

// stop rendering this overlay without removing its elements
draw.unregister();

Constructors

new Draw3D

new Draw3D()#

Fields

visible

visible: booleanSince2.0.0#

Whether this overlay is rendered while registered. Changing visibility does not unregister it or alter its elements; defaults to true. Use setVisible(boolean) to change it.

Methods

addBox

addBox(Box box): BoxSince1.8.4#

Adds an existing box to this overlay. The same box can be added more than once.

Parameters:

box: the cube to add

Returns: the box that was added

addBox(double x1, double y1, double z1, double x2, double y2, double z2, int color, int fillColor, boolean fill): BoxSince1.0.6#

Parameters:

x1: the x coordinate of the first corner
y1: the y coordinate of the first corner
z1: the z coordinate of the first corner
x2: the x coordinate of the second corner
y2: the y coordinate of the second corner
z2: the z coordinate of the second corner
color: the colour of the outline, with or without an alpha of its own
fillColor: the colour of the inside
fill: whether to draw the inside as well as the outline

Returns: the added box

addBox(double x1, double y1, double z1, double x2, double y2, double z2, int color, int fillColor, boolean fill, boolean cull): Box

Since1.3.1#

Adds a box between two corners, optionally depth-tested against world geometry.

Parameters:

x1: the x coordinate of the first corner
y1: the y coordinate of the first corner
z1: the z coordinate of the first corner
x2: the x coordinate of the second corner
y2: the y coordinate of the second corner
z2: the z coordinate of the second corner
color: the colour of the outline, with or without an alpha of its own
fillColor: the colour of the inside
fill: whether to draw the inside as well as the outline
cull: whether to depth-test the box against world geometry; false draws over it

Returns: the added box

addBox(double x1, double y1, double z1, double x2, double y2, double z2, int color, int alpha, int fillColor, int fillAlpha, boolean fill): Box

Since1.1.8#

Parameters:

x1: the x coordinate of the first corner
y1: the y coordinate of the first corner
z1: the z coordinate of the first corner
x2: the x coordinate of the second corner
y2: the y coordinate of the second corner
z2: the z coordinate of the second corner
color: the colour of the outline
alpha: the alpha of the outline, from 0 to 255
fillColor: the colour of the inside
fillAlpha: the alpha of the inside, from 0 to 255
fill: whether to draw the inside as well as the outline

Returns: the added box

addBox(double x1, double y1, double z1, double x2, double y2, double z2, int color, int alpha, int fillColor, int fillAlpha, boolean fill, boolean cull): Box

Since1.3.1#

Adds a box between opposite corners with separate outline and fill alpha values. The alpha arguments determine opacity; cull enables depth testing so terrain can occlude the box. Without this argument, depth testing is disabled.

Parameters:

x1: the x coordinate of the first corner
y1: the y coordinate of the first corner
z1: the z coordinate of the first corner
x2: the x coordinate of the second corner
y2: the y coordinate of the second corner
z2: the z coordinate of the second corner
color: the colour of the outline
alpha: the alpha of the outline, from 0 to 255
fillColor: the colour of the inside
fillAlpha: the alpha of the inside, from 0 to 255
fill: whether to draw the inside as well as the outline
cull: whether the box is depth tested, so terrain draws over it

Returns: the added box

addDraw2D

addDraw2D(double x, double y, double z): SurfaceSince1.6.5#

Adds a 1-by-1 panel with no rotation, 200 minimum subdivisions, and no back face rendering or depth culling.

Parameters:

x: the x coordinate of the panel corner
y: the y coordinate of the panel corner
z: the z coordinate of the panel corner

Returns: the Surface you added.

addDraw2D(double x, double y, double z, double width, double height): SurfaceSince1.6.5#

Adds a panel of the given size with no rotation, 200 minimum subdivisions, and no back face rendering or depth culling.

Parameters:

x: the x coordinate of the panel's corner
y: the y coordinate of the panel's corner
z: the z coordinate of the panel's corner
width: the width of the panel, in blocks
height: the height of the panel, in blocks

Returns: the Surface you added.

addDraw2D(double x, double y, double z, double xRot, double yRot, double zRot): SurfaceSince1.6.5#

Adds a 1-by-1 panel with the given rotation, 200 minimum subdivisions, and no back face rendering or depth culling.

Parameters:

x: the x coordinate of the panel's corner
y: the y coordinate of the panel's corner
z: the z coordinate of the panel's corner
xRot: the rotation about the x axis, in degrees
yRot: the rotation about the y axis, in degrees
zRot: the rotation about the z axis, in degrees

Returns: the Surface you added.

addDraw2D(double x, double y, double z, double xRot, double yRot, double zRot, double width, double height): SurfaceSince1.6.5#

Adds a panel with the given position, rotation, and size, using 200 minimum subdivisions with back-face rendering and depth culling disabled.

Parameters:

x: the x coordinate of the panel's corner
y: the y coordinate of the panel's corner
z: the z coordinate of the panel's corner
xRot: the rotation about the x axis, in degrees
yRot: the rotation about the y axis, in degrees
zRot: the rotation about the z axis, in degrees
width: the width of the panel, in blocks
height: the height of the panel, in blocks

Returns: the Surface you added.

addDraw2D(double x, double y, double z, double xRot, double yRot, double zRot, double width, double height, int minSubdivisions): Surface

Since1.6.5#

Adds a panel with the requested minimum subdivision count, clamped to at least 1; back-face rendering and depth culling are disabled.

Parameters:

x: the x coordinate of the panel's corner
y: the y coordinate of the panel's corner
z: the z coordinate of the panel's corner
xRot: the rotation about the x axis, in degrees
yRot: the rotation about the y axis, in degrees
zRot: the rotation about the z axis, in degrees
width: the width of the panel, in blocks
height: the height of the panel, in blocks
minSubdivisions: the minimum number of subdivisions along the shorter side

Returns: the Surface you added.

addDraw2D(double x, double y, double z, double xRot, double yRot, double zRot, double width, double height, int minSubdivisions, boolean renderBack): Surface

Since1.6.5#

Adds a panel with optional back-face rendering. The subdivision count is clamped to at least 1, and depth culling is disabled.

Parameters:

x: the x coordinate of the panel's corner
y: the y coordinate of the panel's corner
z: the z coordinate of the panel's corner
xRot: the rotation about the x axis, in degrees
yRot: the rotation about the y axis, in degrees
zRot: the rotation about the z axis, in degrees
width: the width of the panel, in blocks
height: the height of the panel, in blocks
minSubdivisions: the minimum number of subdivisions along the shorter side
renderBack: whether the back of the panel is drawn as well as its front

Returns: the Surface you added.

addDraw2D(double x, double y, double z, double xRot, double yRot, double zRot, double width, double height, int minSubdivisions, boolean renderBack, boolean cull): Surface

Since1.6.5#

Adds a panel with the specified geometry and rendering options. The subdivision count is clamped to at least 1.

Parameters:

x: the x coordinate of the panel corner
y: the y coordinate of the panel corner
z: the z coordinate of the panel corner
xRot: the rotation about the x axis, in degrees
yRot: the rotation about the y axis, in degrees
zRot: the rotation about the z axis, in degrees
width: the width of the panel, in blocks
height: the height of the panel, in blocks
minSubdivisions: the minimum number of subdivisions along the shorter side
renderBack: whether the back of the panel is drawn as well as its front
cull: whether to depth-test the panel against world geometry; false draws over it

Returns: the Surface you added.

addEntityTraceLine

addEntityTraceLine(EntityHelper<?> entity, int color): EntityTraceLineSince1.9.0#

Adds a camera-to-entity line. The target follows the entity's interpolated position plus a 0.5-block vertical offset, recalculated each frame. The line draws over terrain by default and is removed from the overlay after the entity is gone.

Parameters:

entity: the entity to point at
color: the colour of the line

Returns: the EntityTraceLine you added.

addEntityTraceLine(EntityHelper<?> entity, int color, int alpha): EntityTraceLineSince1.9.0#

Adds a line from the crosshair to an entity, with an explicit alpha. It uses the default 0.5-block vertical offset and is drawn over the world.

Parameters:

entity: the entity to point at
color: the colour of the line
alpha: the alpha of the line, from 0 to 255

Returns: the EntityTraceLine you added.

addEntityTraceLine(EntityHelper<?> entity, int color, int alpha, double yOffset): EntityTraceLineSince1.9.0#

Adds a line from the crosshair to an entity at a chosen vertical offset above its feet. The offset is in blocks and follows the entity each frame; the line is drawn over the world.

const player = Player.getPlayer();
if (player !== null) {
  const draw = Hud.createDraw3D();
  // aim at the player's eyes rather than their feet
  draw.addEntityTraceLine(player, Color.rgb(0xFF, 0x00, 0x00), 255, player.getEyeHeight());
  draw.register();
}

Parameters:

entity: the entity to point at
color: the colour of the line
alpha: the alpha of the line, from 0 to 255
yOffset: how far above the entity's feet to aim, in blocks

Returns: the EntityTraceLine you added.

addEntityTraceLine(EntityHelper<?> entity, int color, int alpha, double yOffset, boolean alwaysOnTop): EntityTraceLineSince1.9.0#

Adds a line from the crosshair to an entity at a chosen vertical offset above its feet. The offset is in blocks and follows the entity each frame. Set alwaysOnTop to true to draw it over the world; false allows terrain to hide it.

Parameters:

entity: the entity to point at
color: the colour of the line
alpha: the alpha of the line, from 0 to 255
yOffset: how far above the entity's feet to aim, in blocks
alwaysOnTop: whether to draw over the world instead of allowing terrain to hide the line

Returns: the added line

addLine

addLine(Line3D line): Line3DSince1.8.4#

Adds an existing straight 3D line to this overlay. The same line can be added more than once.

Parameters:

line: the line to add

Returns: the line that was added

addLine(double x1, double y1, double z1, double x2, double y2, double z2, int color): Line3DSince1.0.6#

Adds a line between two world-space endpoints. A zero alpha byte is treated as opaque when the RGB value is nonzero; transparent black remains transparent.

Parameters:

x1: the x coordinate of the start
y1: the y coordinate of the start
z1: the z coordinate of the start
x2: the x coordinate of the end
y2: the y coordinate of the end
z2: the z coordinate of the end
color: the line color, with or without an alpha byte

Returns: the Line3D you added.

addLine(double x1, double y1, double z1, double x2, double y2, double z2, int color, boolean cull): Line3DSince1.3.1#

Adds a line between two world-space endpoints, optionally depth-tested against world geometry. With cull false, it draws over the world.

Parameters:

x1: the x coordinate of the start
y1: the y coordinate of the start
z1: the z coordinate of the start
x2: the x coordinate of the end
y2: the y coordinate of the end
z2: the z coordinate of the end
color: the colour of the line, with or without an alpha of its own
cull: whether to depth-test the line against world geometry

Returns: the Line3D you added.

addLine(double x1, double y1, double z1, double x2, double y2, double z2, int color, int alpha): Line3DSince1.1.8#

Adds a line between two world-space endpoints with an explicit alpha from 0 to 255. The alpha is used as given, so zero makes the line transparent.

Parameters:

x1: the x coordinate of the start
y1: the y coordinate of the start
z1: the z coordinate of the start
x2: the x coordinate of the end
y2: the y coordinate of the end
z2: the z coordinate of the end
color: the colour of the line
alpha: the alpha of the line, from 0 to 255

Returns: the Line3D you added.

addLine(double x1, double y1, double z1, double x2, double y2, double z2, int color, int alpha, boolean cull): Line3DSince1.3.1#

Adds a line between two world-space endpoints with an explicit alpha, optionally depth-tested against world geometry.

Parameters:

x1: the x coordinate of the start
y1: the y coordinate of the start
z1: the z coordinate of the start
x2: the x coordinate of the end
y2: the y coordinate of the end
z2: the z coordinate of the end
color: the colour of the line
alpha: the alpha of the line, from 0 to 255
cull: whether to depth-test the line against world geometry

Returns: the Line3D you added.

addPoint

addPoint(Pos3D point, double radius, int color): BoxSince1.4.0#

Adds a filled cube centered at point, with side length twice the radius.

Parameters:

point: the center point
radius: 1/2 of the side length of the cube
color: point color

Returns: the added box

See:

Box

addPoint(double x, double y, double z, double radius, int color): BoxSince1.4.0#

Adds a filled cube centered at the given coordinates, with side length twice the radius. Its outline and fill use the same color.

Parameters:

x: x value of the center point
y: y value of the center point
z: z value of the center point
radius: 1/2 of the side length of the cube
color: point color

Returns: the added box

See:

Box

addPoint(double x, double y, double z, double radius, int color, int alpha, boolean cull): BoxSince1.4.0#

Adds a filled cube centered at the given coordinates, with side length twice the radius. The supplied alpha applies to both its outline and fill; cull controls whether terrain can hide it.

Parameters:

x: x value of the center point
y: y value of the center point
z: z value of the center point
radius: 1/2 of the side length of the cube
color: point color
alpha: alpha of the point, used for both the outline and the inside
cull: whether to cull the point or not

Returns: the added box

See:

Box

addSurface

addSurface(Surface surface): SurfaceSince1.8.4#

Adds an existing surface to this overlay. The same surface can be added more than once.

Parameters:

surface: the surface to add

Returns: the surface that was added

addTraceLine

addTraceLine(TraceLine line): TraceLineSince1.9.0#

Adds an existing trace line to this overlay. The same line can be added more than once.

Parameters:

line: the trace line to add

Returns: the trace line that was added

addTraceLine(double x, double y, double z, int color): TraceLineSince1.9.0#

Adds a line from the camera toward a fixed world-space target. Its camera endpoint is updated each frame; it draws over terrain by default. Use traceLineBuilder() to configure depth testing or alpha.

Parameters:

x: the x coordinate of the target
y: the y coordinate of the target
z: the z coordinate of the target
color: the colour of the line

Returns: the TraceLine you added.

addTraceLine(double x, double y, double z, int color, int alpha): TraceLineSince1.9.0#

Adds a camera-to-target line with an explicit alpha from 0 to 255. Unlike the single-color form, alpha zero remains transparent. It draws over terrain by default.

Parameters:

x: the x coordinate of the target
y: the y coordinate of the target
z: the z coordinate of the target
color: the colour of the line
alpha: the alpha of the line, from 0 to 255

Returns: the TraceLine you added.

addTraceLine(Pos3D pos, int color): TraceLineSince1.9.0#

Adds a camera-to-target line using the position's coordinates at call time. Later changes to pos do not move the target; the line draws over terrain by default.

Parameters:

pos: the position of the target
color: the colour of the line

Returns: the TraceLine you added.

addTraceLine(Pos3D pos, int color, int alpha): TraceLineSince1.9.0#

Adds a camera-to-target line using the position's coordinates at call time, with an explicit alpha from 0 to 255. Alpha zero is transparent; the line draws over terrain by default.

Parameters:

pos: the position of the target
color: the colour of the line
alpha: the alpha of the line, from 0 to 255

Returns: the TraceLine you added.

boxBuilder

boxBuilder(): Box.BuilderSince1.8.4#

Creates a box builder whose corners default to the origin and whose color is white; set both corners and the color before building. Boxes are unfilled and drawn over the world by default. For a one-block box, use boxBuilder(int, int, int).

const draw = Hud.createDraw3D();
draw.boxBuilder().pos(0, 64, 0, 3, 67, 2).color(Color.rgb(0xFF, 0x00, 0x00)).buildAndAdd();
draw.register();

Returns: a new Box.Builder instance.

boxBuilder(BlockPosHelper pos): Box.BuilderSince1.8.4#

Creates a box builder with its corners set to the block's position and the opposite corner one block farther along each axis.

const player = Player.getPlayer();
if (player !== null) {
  const draw = Hud.createDraw3D();
  draw.boxBuilder(player.getBlockPos()).color(Color.rgb(0xFF, 0x00, 0x00)).buildAndAdd();
  draw.register();
}

Parameters:

pos: the block position of the box

Returns: a new Box.Builder instance.

boxBuilder(int x, int y, int z): Box.BuilderSince1.8.4#

Creates a box builder spanning the block at (x, y, z).

const draw = Hud.createDraw3D();
// a wireframe around a single block
draw.boxBuilder(0, 64, 0).color(Color.rgb(0xFF, 0x00, 0x00)).buildAndAdd();
draw.register();

Parameters:

x: the x coordinate of the box
y: the y coordinate of the box
z: the z coordinate of the box

Returns: a new Box.Builder instance.

clear

clear(): voidSince1.8.4#

Removes all elements from this overlay without unregistering it; other overlays and references to the removed elements are unaffected.

entityTraceLineBuilder

entityTraceLineBuilder(): EntityTraceLine.BuilderSince1.9.0#

Creates a builder for a white, fully opaque, always-on-top line that follows an entity, with a 0.5-block vertical offset. No entity is set by default; a line built without one is removed on its first frame.

const player = Player.getPlayer();
if (player !== null) {
  const draw = Hud.createDraw3D();
  draw.entityTraceLineBuilder().entity(player).color(Color.rgb(0xFF, 0x00, 0x00)).buildAndAdd();
  draw.register();
}

Returns: a new EntityTraceLine.Builder instance.

getBoxes

getBoxes(): List<Box>Since1.0.6#

Returns a new list of this overlay's boxes in their current element order.

Returns: the cubes in this overlay

getDraw2Ds

getDraw2Ds(): List<Surface>Since1.6.5#

Returns a new list of this overlay's world-space surfaces. The legacy method name refers to surfaces, not screen overlays.

Returns: the surfaces in this overlay

getElements

getElements(): List<RenderElement3D<?>>Since2.0.0#

Returns an immutable snapshot of every element in this overlay, in its current order. The snapshot is separate from the overlay; later changes to the overlay do not change it.

Returns: an immutable snapshot of this overlay's elements

getEntityTraceLines

getEntityTraceLines(): List<EntityTraceLine>Since1.9.0#

Returns a new list of trace lines targeting entities.

Returns: the entity trace lines in this overlay

getLines

getLines(): List<Line3D>Since1.0.6#

Returns a new list of fixed-endpoint lines, excluding camera trace lines.

Returns: the straight lines in this overlay

getTraceLines

getTraceLines(): List<TraceLine>Since1.9.0#

Returns a new list of fixed-target camera trace lines.

Returns: the trace lines in this overlay

isVisible

isVisible(): booleanSince2.0.0#

Returns whether this overlay will render while registered. This does not indicate whether it is currently registered.

Returns: true if this overlay is visible; false otherwise

lineBuilder

lineBuilder(): Line3D.BuilderSince1.8.4#

Creates a line builder with both endpoints at the origin, white, and drawn over the world. Set distinct endpoints for a visible line.

const draw = Hud.createDraw3D();
draw.lineBuilder().pos(0, 64, 0, 8, 72, 0).color(Color.rgb(0x00, 0xFF, 0x00)).buildAndAdd();
draw.register();

Returns: a new Line3D.Builder instance.

reAddElement

reAddElement(T extends RenderElement3D<?> element): T extends RenderElement3D<?>Since1.8.4#

Adds an existing render element to this overlay and returns it. Elements built with build() are not added automatically; adding the same instance more than once creates duplicate list entries and draws it more than once.

Parameters:

element: the element to put back

Type Parameters:

T: the type of element to add

Returns: the element that was added

register

register(): Draw3DSince1.6.5#

Registers this overlay for rendering. Adding elements alone does not make them render; registration adds this instance to the renderer's set. Re-registering an already registered instance has no additional effect.

const draw = Hud.createDraw3D();
draw.addBox(0, 64, 0, 1, 65, 1, Color.rgb(0xFF, 0x00, 0x00), Color.argb(0, 0, 0, 0), false);
// nothing has been drawn until this
draw.register();

Returns: self for chaining

removeBox

removeBox(Box b): Draw3DSince1.0.6#

Parameters:

b: the cube to take off this overlay

Returns: this overlay

removeDraw2D

removeDraw2D(Surface surface): Draw3DSince1.6.5#

Removes a panel from this overlay. The surface object and its elements are not modified.

Parameters:

surface: the surface to take off this overlay

Returns: self for chaining

removeElement

removeElement(RenderElement3D<?> element): Draw3DSince2.0.0#

Removes an element from this overlay without modifying the element itself. If it is absent, this has no effect.

Parameters:

element: the element to take off

Returns: self for chaining

removeLine

removeLine(Line3D l): Draw3DSince1.0.6#

Removes one matching straight line entry from this overlay, if present.

Parameters:

l: the straight line to remove

Returns: self for chaining

removeTraceLine

removeTraceLine(TraceLine traceLine): Draw3DSince1.9.0#

Removes the trace line from this overlay if present.

Parameters:

traceLine: the line to remove

Returns: self for chaining

setVisible

setVisible(boolean visible): Draw3DSince2.0.0#

Sets whether this overlay is rendered while registered. Changing visibility does not unregister the overlay or alter its elements.

Parameters:

visible: whether this overlay should be rendered

Returns: self for chaining

surfaceBuilder

surfaceBuilder(): Surface.BuilderSince1.8.4#

Creates a surface builder with a 10 × 10-block size, centered rotation, a rendered back, no depth culling, and full-bright lighting. Its default subdivision count is 1, so set the size and subdivisions for the desired panel dimensions and element resolution.

const draw = Hud.createDraw3D();
const surface = draw.surfaceBuilder()
   .pos(0.5, 64, 0.5)
   .size(1, 1)
   .minSubdivisions(200)
   .buildAndAdd();
surface.addText("hello", 10, 10, Color.rgb(0xFF, 0xFF, 0xFF), true);
draw.register();

Returns: a new Surface.Builder instance.

traceLineBuilder

traceLineBuilder(): TraceLine.BuilderSince1.9.0#

Creates a trace-line builder targeting the origin, white and fully opaque, drawn over the world. Its start point is calculated from the camera each frame.

const draw = Hud.createDraw3D();
draw.traceLineBuilder().pos(0, 64, 0).color(Color.rgb(0xFF, 0x00, 0x00)).buildAndAdd();
draw.register();

Returns: a new TraceLine.Builder instance.

unregister

unregister(): Draw3DSince1.6.5#

Unregisters this overlay without removing its elements. It can be registered again later; other overlays are unaffected.

const draw = Hud.createDraw3D();
draw.addBox(0, 64, 0, 1, 65, 1, Color.rgb(0xFF, 0x00, 0x00), Color.argb(0, 0, 0, 0), false);
draw.register();
draw.unregister();
// the box is still on the overlay, just not being drawn
Chat.log(`${draw.getBoxes().size()} boxes, none of them visible`);

Returns: self for chaining

Draw3D ​

Constructors ​

new Draw3D ​

Fields ​

visible ​

Methods ​

addBox ​

addDraw2D ​

addEntityTraceLine ​

addLine ​

addPoint ​

addSurface ​

addTraceLine ​

boxBuilder ​

clear ​

entityTraceLineBuilder ​

getBoxes ​

getDraw2Ds ​

getElements ​

getEntityTraceLines ​

getLines ​

getTraceLines ​

isVisible ​

lineBuilder ​

reAddElement ​

register ​

removeBox ​

removeDraw2D ​

removeElement ​

removeLine ​

removeTraceLine ​

setVisible ​

surfaceBuilder ​

traceLineBuilder ​

unregister ​

Draw3D

Constructors

new Draw3D

Fields

visible

Methods

addBox

addDraw2D

addEntityTraceLine

addLine

addPoint

addSurface

addTraceLine

boxBuilder

clear

entityTraceLineBuilder

getBoxes

getDraw2Ds

getElements

getEntityTraceLines

getLines

getTraceLines

isVisible

lineBuilder

reAddElement

register

removeBox

removeDraw2D

removeElement

removeLine

removeTraceLine

setVisible

surfaceBuilder

traceLineBuilder

unregister