Skip to content

Rendering

Jump to bottom
Homak edited this page Nov 1, 2026 · 3 revisions

Rendering Utilities

This page covers the rendering utilities provided by Citrine, including custom world-space geometry and texture rendering.

Quad Renderer

QuadRenderer provides methods for rendering 2D textured quads (planes) in the world.

All methods are found in:

org.carpentry.citrine.api.render

Scheduling Quads

The primary method for scheduling a quad is scheduleClient().

QuadRenderer.scheduleClient(
    pos,
    width,
    height,
    rotation,
    scale,
    texture,
    duration,
    fade,
    fadeStart,
    scaleUp,
    scaleStart,
    scaleFactor,
    alpha,
    tileTexture
);
Parameter Description
pos World-space position of the quad.
width Width of the quad.
height Height of the quad.
rotation Rotation around the X, Y, and Z axes (in degrees).
scale Initial scale multiplier.
texture Texture identifier.
duration How long the quad remains rendered, in ticks.
fade Whether the quad should fade over time.
fadeStart Tick at which fading begins.
scaleUp Whether the quad scales up over time.
scaleStart Tick at which scaling begins.
scaleFactor How much the quad scales up to if scaleUp is true.
alpha Initial opacity, from 0.0 to 1.0.
tileTexture If the texture should tile or stretch to fit the quad dimensions.

Rotation and Spinning

Quads can be configured to continuously rotate around a specified axis.

Use the method accepting SpinAxis and rotMult:

QuadRenderer.scheduleClient(
    pos, width, height, rotation, scale, texture,
    duration, fade, fadeStart, scaleUp, scaleStart,
    scaleFactor, alpha,
    QuadRenderer.SpinAxis.Y, 2.0f,
    tileTexture
);

Available rotation axes:

  • SpinAxis.X
  • SpinAxis.Y
  • SpinAxis.Z

rotMult determines the number of degrees rotated per tick.

A value of 0 disables continuous rotation.

Frame-Based Rendering

By default, scheduled quads use tick-based lifetimes. Citrine also provides frame-based alternatives.

scheduleClientFrames()

Schedules a quad for a specified number of rendered frames rather than ticks.

QuadRenderer.scheduleClientFrames(
    pos, width, height, rotation, scale, texture,
    durationFrames, fade, fadeStartFrame,
    scaleUp, scaleStartFrame, scaleFactor,
    alpha, tileTexture
);

scheduleClient240Hz()

Schedules a quad timed using 240 time units per second instead of ticks.

QuadRenderer.scheduleClient240Hz(
    pos, width, height, rotation, scale, texture,
    duration, fade, fadeStart,
    scaleUp, scaleStart, scaleFactor,
    alpha, tileTexture
);

Sending Quads From The Server

Quads can also be scheduled from the server using scheduleCommon().

QuadRenderer.scheduleCommon(
    serverWorld,
    pos, width, height, rotation, scale, texture,
    duration, fade, fadeStart,
    scaleUp, scaleStart, scaleFactor,
    alpha, tileTexture
);

The renderer sends the quad's parameters to players in the specified ServerWorld, where the effect is scheduled on their clients.

Same as client, these support rotation:

QuadRenderer.scheduleCommon(
    serverWorld,
    pos, width, height, rotation, scale, texture,
    duration, fade, fadeStart,
    scaleUp, scaleStart, scaleFactor,
    alpha, QuadRenderer.SpinAxis.Y, 2.0f,
    tileTexture
);

Immediate Rendering

renderImmediate() renders a quad directly in the current frame.

QuadRenderer.renderImmediate(
    matrices,
    cameraPosition,
    pos,
    width,
    height,
    rotation,
    scale,
    texture,
    alpha,
    tileTexture
);

Managing Scheduled Quads

The system provides methods for clearing scheduled effects:

Method Description
clearAllQuads() Removes all scheduled tick-based and frame-based quads.
clearFrameQuads() Removes only frame-based quads.
getRenderableQuads(Vec3d camPos, float partialTicks) Retrieves scheduled quads as renderable objects.

Example: Spinning, Fading Quad

QuadRenderer.scheduleClient(
    player.getPos().add(0, 1, 0),
    2.0f,
    2.0f,
    new Vec3d(0, 0, 0),
    1.0f,
    new Identifier("mymod", "textures/effect.png"),
    40,
    true,
    20,
    true,
    0,
    3.0f,
    1.0f,
    QuadRenderer.SpinAxis.Y,
    5.0f,
    false
);

This creates a quad above the player that:

  • Remains visible for 40 ticks.
  • Begins fading after 20 ticks.
  • Scales up to three times its original size.
  • Rotates around the Y axis.
  • Uses the specified texture without tiling.

Cube Renderer

CubeRenderer provides similar methods for rendering textured 3D cubes in the world.

TextureFaceData

TextureFaceData stores the textures used by each face of a cube.

Create a TextureFaceData instance by supplying an identifier for each face:

CubeRenderer.TextureFaceData textures =
    new CubeRenderer.TextureFaceData(
        new Identifier("example", "textures/cube/front.png"),
        new Identifier("example", "textures/cube/back.png"),
        new Identifier("example", "textures/cube/top.png"),
        new Identifier("example", "textures/cube/bottom.png"),
        new Identifier("example", "textures/cube/right.png"),
        new Identifier("example", "textures/cube/left.png")
    );

If all six faces should use the same texture, use fromSingleTexture() instead:

CubeRenderer.TextureFaceData textures =
    CubeRenderer.TextureFaceData.fromSingleTexture(
        new Identifier("example", "textures/cube.png")
    );

Individual textures can be retrieved using get(int faceIndex) or getter methods:

  • getFront()
  • getBack()
  • getTop()
  • getBottom()
  • getRight()
  • getLeft()

Scheduling cubes

scheduleClient()

Schedules a cube for rendering on the client.

CubeRenderer.scheduleClient(
    pos,
    width, height, depth,
    rotation,
    scale,
    textures,
    duration,
    fade,
    fadeStart,
    scaleUp,
    scaleStart,
    scaleFactor,
    alpha,
    tileTexture
);
Parameter Description
pos World-space position of the quad.
width Width of the cube.
height Height of the cube.
depth Depth of the cube.
rotation Rotation around the X, Y, and Z axes (in degrees).
scale Initial scale multiplier.
textures TextureFaceData containing the six face textures.
duration How long the quad remains rendered, in ticks.
fade Whether the quad should fade over time.
fadeStart Tick at which fading begins.
scaleUp Whether the quad scales up over time.
scaleStart Tick at which scaling begins.
scaleFactor How much the quad scales up to if scaleUp is true.
alpha Initial opacity, from 0.0 to 1.0.
tileTexture If the texture should tile or stretch to fit the cube dimensions.

scheduleCommon()

Schedules a cube for rendering on the clients of every player in a given world, has the same parameters as scheduleClient.

CubeRenderer.scheduleCommon(
    world,
    pos,
    width, height, depth,
    rotation,
    scale,
    textures,
    duration,
    fade,
    fadeStart,
    scaleUp,
    scaleStart,
    scaleFactor,
    alpha,
    tileTexture
);

Animations

Same as the quad impl.

Example

A cube effect with separate face textures, rotation, and a fade animation:

CubeRenderer.TextureFaceData textures =
    CubeRenderer.TextureFaceData.fromSingleTexture(
        new Identifier("example", "textures/effects/cube.png")
    );

CubeRenderer.scheduleClient(
    player.getPos(),
    1.0f, 1.0f, 1.0f,
    new Vec3d(0, 45, 0),
    1.0f,
    textures,
    40,
    true,
    20,
    false,
    0,
    1.0f,
    1.0f,
    false
);

This schedules a one-block-sized cube at the player's position. It rotates by 45 degrees around the Y axis, remains visible for 40 ticks, and fades during the final 20 ticks.

Clone this wiki locally