Katton

简体中文

English

简体中文

English
On this page

HUD 与世界渲染 ​

WARNING

HUD 与世界渲染回调只在 Fabric/NeoForge 客户端运行。

HUD 渲染器在屏幕空间绘制。世界渲染器在客户端世界中每帧绘制。两类 API 都使用稳定字符串 id；再次注册相同 id 会替换旧回调，客户端重载时也会清理脚本拥有的渲染回调。

详细 API 见 KattonClientRenderApi。

HUD 渲染器 ​

在 @ClientScriptEntrypoint 中使用 registerHudRenderer。回调会收到 HudRenderContext，可以传给 drawHudText、fillHudRect、drawHudTexture 等辅助函数。

kotlin
import top.katton.api.*

@ClientScriptEntrypoint(ClientPhase.JOINED)
fun hudRenderTestMain() {

    registerHudRenderer("katton:test:hud", HudRenderLayer.FOREGROUND, 20) { ctx ->
        fillHudRect(ctx, 6, 6, 258, 64, 0xAA000000.toInt())
        fillHudRect(ctx, 8, 8, 256, 62, 0x66002244)

        drawHudText(ctx, "Katton HUD Render Test", 14, 14, 0xFFE8F1FF.toInt(), true)
        drawHudText(ctx, "FPS: ${clientFps()}", 14, 28, 0xFF9BD5FF.toInt(), false)
        drawHudText(ctx, "Screen: ${clientScreenName() ?: "In-World"}", 14, 40, 0xFFB5FFC5.toInt(), false)

        val p = clientPos()
        if (p != null) {
            drawHudText(ctx, "Pos: %.2f, %.2f, %.2f".format(p.x, p.y, p.z), 14, 52, 0xFFFFD38A.toInt(), false)
        }
    }
    clientTell("[Katton] HUD render test script loaded", overlay = false)
}
在 HUD 中渲染文本示例

世界渲染器 ​

使用 registerWorldRenderer 绘制与相机相关的世界空间内容。当前常用辅助函数包括 drawLine3D，适合调试线、指引线和简单空间提示。

kotlin
import top.katton.api.*

@ClientScriptEntrypoint(ClientPhase.JOINED)
fun worldRenderTestMain() {
    registerWorldRenderer("katton:test:world", WorldRenderLayer.NORMAL, 0) { ctx ->
        val pos = clientPos() ?: return@registerWorldRenderer

        val x = pos.x
        val y = pos.y + 1.6
        val z = pos.z

        // X axis — red
        drawLine3D(
            ctx,
            x - 1.0, y, z,
            x + 1.0, y, z,
            argbColor = 0xFFFF5050.toInt(),
            lineWidth = 2.0f
        )

        // Y axis — green
        drawLine3D(
            ctx,
            x, y - 1.0, z,
            x, y + 1.0, z,
            argbColor = 0xFF50FF9E.toInt(),
            lineWidth = 2.0f
        )

        // Z axis — blue
        drawLine3D(
            ctx,
            x, y, z - 1.0,
            x, y, z + 1.0,
            argbColor = 0xFF5BB4FF.toInt(),
            lineWidth = 2.0f
        )
    }

    clientTell("[Katton] World render test script loaded", overlay = false)

}
3D 图形渲染示例

客户端 UI 消息 ​

标题、覆盖层、Action Bar、Toast 和客户端音效不需要逐帧渲染器，直接使用客户端 UI 辅助函数即可。

kotlin
import net.minecraft.client.gui.components.toasts.SystemToast
import top.katton.api.*

@ClientScriptEntrypoint(ClientPhase.JOINED)
fun clientUiSmokeTestMain(){
    runOnClient {
        clientTell("[Katton] Starting client UI test")
        clientTitleTimes(fadeInTicks = 8, stayTicks = 30, fadeOutTicks = 10)
        clientTitle("Katton Client API")
        clientSubtitle("UI smoke test")

        clientOverlay("Overlay message from script", tinted = true)
        clientActionBar("Action bar notification")
        clientNowPlaying("Current music track hint")
        clientAddSystemToast(SystemToast.SystemToastId.NARRATOR_TOGGLE, "Toast fallback test", "If no specific toast path is found, this message will be displayed.")

        playClientSound("minecraft:entity.experience_orb.pickup", volume = 0.8f, pitch = 1.0f)

        // Clear overlay after a short delay (triggered via script execution)
        clearClientOverlay()
    }
}
消息与通知展示

清理 ​

需要在下一次重载前停止某个渲染器时，可以调用 unregisterHudRenderer(id) 或 unregisterWorldRenderer(id)。建议每个功能使用独立 id，避免不同脚本意外互相替换。