High Level Peripherals

模组

· 作者 Arthurus36

这是模组 Tom's Peripherals 的一个分支,包含少量新增内容和修复。

0 本站下载 0 关注 更新于 4 个月前

需要前置:CC: Tweaked

最新 1.4.3 · 1.21.1 · NeoForge

一键开服(送7天)

高级外设

一款 CC:Tweaked 监视器外设,真正能跟上你构建需求的存在。

这是 Tom's Peripherals 的一个分支版本,经过重构,使其更加实用、稳定且完整——支持更大的屏幕、真实的 GPU 渲染着色器、完整的鼠标/触控输入,以及一个不会与你作对的更简洁 API。

✨ 特性

?️ 巨大且清晰的监视器

构建高达 32x32 方块(管理员可调整至 64x64)的阵列,每个方块的分辨率最高可达 4096x4096。使用完整的 2D API 进行绘制——填充形状、渐变、自定义字体的文本、图像加载、双缓冲——所有操作均在服务器端运行,并自动同步到每个客户端。

⚡ 真正的 GPU 着色器,而非 Lua 数学运算

只需编写一次小型类 GLSL 着色器,它就会在每位观看者自己的显卡上实时渲染,以他们各自的帧率运行,完全与服务器刻脱钩。不再用逐像素的 Lua 光线步进来拖慢游戏——着色器引擎以零 Lua 参与的方式处理这些计算。内置一流的光线追踪基元(球体/平面/立方体相交),让你无需从零开始手写光线数学。

gpu.compileShader([[
  color = vec3(uv.x, uv.y, sin(time));
]])

仅此而已——它已经在渲染了。

?️ 完整的鼠标输入

直接在监视器屏幕面上点击、右键单击、拖拽和滚动,像素级精确的坐标直接传递给你的脚本。尊重玩家配置的任何控制设置——没有硬编码的按键假设。非常适合构建真正的交互式 UI,而不仅仅是静态显示。

? 3D 立即模式渲染

采用 OpenGL-1 风格的 API(glBegin/glVertex/glTranslate/glRotate/光照),用于在监视器上构建真正的 3D 场景,而无需编写着色器——非常适合模型、图表或简单游戏。

? 亮度控制

以尼特为单位缩放监视器的输出亮度,从昏暗的环境显示到刺眼的明亮——适用于绘制的像素和实时着色器。

? 充足的构建空间

慷慨的默认显存预算(每块屏幕约 2 GiB),共享于帧缓冲区、图像和着色器纹理之间,并提供服务器可配置的限额以支持更大的构建。

为什么选择这个分支?

Tom's Peripherals 提供了监视器和 GPU 外设,但很快遇到了真正的瓶颈——低分辨率限制、无着色器渲染、无鼠标输入,以及一些长期存在的多区块/同步错误。High Level Peripherals 保留了你已经熟悉的 peripheral.find("tm_monitor") API,并将所有这些瓶颈一一突破——让你的构建不再受限于外设,而是受限于你的想象力。

入门指南

local gpu = peripheral.find("tm_monitor")
gpu.fill(0x000000)
gpu.drawText(10, 10, "Hello, HLPS!", 0xFFFFFF)

完整 API 参考见下文。

文档

tm_monitor Lua API 参考

监视器外设的完整参考:2D 绘制、文本、图像、3D 立即模式 API、鼠标/滚动输入以及着色器引擎。

1. 限制

限制项 值
网格大小 默认最多 32x32 个方块(maxScreenSize,1-64)。超出限制 → 每次调用都会抛出异常。
gpu.setSize(n) 64–4096 像素/轴,默认 1024。
gpu.setGpuResolution(w, h) 64–4096 像素/轴,或 (0,0) 表示自动。
显存预算 默认约 2 GiB(maxVRAMSize),共享于帧缓冲区/图像/缓冲区/纹理之间。

2. 颜色格式

打包的 0xRRGGBB 整数,或 (r,g,b[,a]) 各分量 0-255。

  • Alpha 0 或 255 → 不透明。
  • Alpha 1..254 → 源覆盖混合:out = (src*a + dst*(255-a)) / 255。
  • getPixel/getpx 返回 0xRRGGBB(已去除 alpha)。

3. 尺寸调整

调用 效果
gpu.setSize(n) 单方块分辨率,单一轴。总画布为 (blocksWide*n) x (blocksTall*n)。
gpu.getSize() → width, height, cols, rows, blockSize。
gpu.getResolution() → width, height。
gpu.refreshSize() 强制重新扫描阵列的网格布局。
gpu.debugTiling() → string 转储当前服务器端的平铺状态,用于诊断看起来错误的阵列。

如果在 Lua 中进行逐像素绘制,请保持 setSize 较低(64-256)——对于任何程序化内容,请改用着色器引擎(第 8 节)。

4. 基本 2D 绘制

所有坐标均为 1-based(从 1 开始)。

调用 备注
gpu.fill([color]) 填充整个画布。默认为黑色。
gpu.clear([color]) fill 的别名。
gpu.setPixel(x, y, color) 越界写入将被忽略。
gpu.getPixel(x, y) → int,越界时为 0。
gpu.filledRectangle(x, y, w, h, [color]) 越界时抛出异常。
gpu.rectangle(x, y, w, h, [color]) 仅轮廓。
gpu.line(x1, y1, x2, y2, [color]) Bresenham 算法。
gpu.lineS(x1, y1, x2, y2, [color]) 替代算法。
gpu.circle(cx, cy, r, [color]) 轮廓。
gpu.fillCircle(cx, cy, r, [color]) 填充。
gpu.triangle(x1,y1, x2,y2, x3,y3, [color]) 轮廓。
gpu.fillTriangle(x1,y1, x2,y2, x3,y3, [color]) 填充。
gpu.gradientRectangle(x, y, w, h, c1, c2, [vertical]) 两种颜色之间的线性插值。
gpu.copy(srcX, srcY, w, h, dstX, dstY) 重叠安全。上限为 64M 像素。
gpu.scroll(dx, dy, [fillColor]) 移动画布;暴露区域被填充。相同上限。
gpu.drawBuffer(x, y, w, scale, ...pixels) 行优先像素作为可变参数数字,而非表格。

5. 双缓冲

gpu.setDoubleBuffered(true)
-- ... 绘制调用 ...
gpu.flush()   -- 呈现 + 同步

gpu.sync() 直接将帧缓冲区推送(内部节流)——通常在双缓冲/着色器流程之外不需要。

6. 文本

调用 备注
gpu.drawText(x, y, text, [fg=-1], [bg=-1], [size=1], [pad=1]) -1 表示跳过该图层。
gpu.drawTextSmart(x, y, text, [fg], [bg], [forceUnicode=false], [size=1], [pad=1]) 自动选择 ASCII/unicode 字体(ASCII 以 2 倍大小绘制)。
gpu.getTextLength(text, [size=1], [pad=1]) → 像素宽度。
gpu.getFont() → name, editable。
gpu.setFont(name) 如果字体不存在则无操作。
gpu.drawChar(x, y, charIndex, [fg], [bg], [size=1]) 绘制单个字形,索引从 1 开始。
gpu.addNewChar(char, width, ...16 numbers) → int。字体必须可编辑。
gpu.delChar(char) / gpu.freeChars() / gpu.clearChars() 字形管理。
gpu.setFontDefaultCharID(id) / gpu.getFontDefaultCharID() 备用字形。

7. 图像与缓冲区

调用 返回值
gpu.newImage(w, h) 空白 LuaImage。
gpu.imageFromBuffer(w, ...pixels) 从原始像素数据创建 LuaImage。
gpu.decodeImage(bufferRef) / gpu.decodeImage(...bytes) 解码 PNG 等格式。
gpu.newBuffer([initialCapacity=32]) 可增长的 LuaByteBuffer。
gpu.drawImage(x, y, image) 绘制图像,裁剪至画布范围内。

所有图像都会预先占用 VRAM(w*h*4 字节),若超出预算则抛出错误。

8. 着色器引擎

编写一个小型类 GLSL 程序一次;它将在真实 GPU 上逐像素运行,不涉及 Lua。

gpu.compileShader([[
  float sdSphere(vec3 p, float r) { return length(p) - r; }
  uniform float speed;
  color = vec3(uv.x, uv.y, sin(time * speed));
]])
gpu.setUniform("speed", 2.0)

没有 main 函数 — 函数定义之后的代码自上而下执行;color 即为像素输出。gpu.clearShader() 返回到正常的 2D 绘制模式。

  • gpu.isGpuMode() → 当着色器处于活动状态时返回 true。
  • gpu.setUniform(name, value) / gpu.setUniform3(name, x, y, z) — 实时更新,无需重新编译。
  • gpu.setGpuResolution(w, h) — 着色器渲染的分辨率(独立于 setSize)。匹配你的数组 cols:rows 的比例,或者不调用它。

活动的着色器与启动它的计算机没有持续的关联 — 除非最后连接的计算机断开连接,或者你调用 gpu.clearShader(),否则着色器不会停止。

texture() 尚未实现 GPU 加速 — 采样纹理的着色器可以正常编译,但不会自动渲染。需自行驱动:

gpu.compileShader(src)
gpu.uploadTexture(0, w, h, pixels)
while true do
  gpu.runShader(os.clock())
  gpu.sync()
  sleep(0)
end

着色器语言

  • 两种类型:float, vec3。
  • 预定义变量:color(写入此变量)、uv(.x/.y 范围 0..1,.y=0 在顶部)、res, time。
  • uniform <float|vec3> name;
  • 函数:<float|vec3> name(params) { ...; return expr; }。不支持递归。必须出现在任何其他顶层语句之前,包括 uniform 声明。
  • 控制流:if/else、for (init; cond; update) {}、break;、return expr;。
  • 运算符:+ - * /、一元 - !、比较运算符、&& ||、.x .y .z 组件访问。 vec3 * float 有效;float * vec3 无效。
  • 内置函数:vec3(f,f,f)、sin cos tan sqrt abs floor fract exp pow mod min max step clamp mix smoothstep length dot cross normalize reflect、texture(slot, u, v)。
  • 光线追踪内置函数(返回最近的正碰撞距离,未命中则返回 -1.0): intersectSphere(ro, rd, center, radius)、intersectPlane(ro, rd, planeY)、 intersectBox(ro, rd, center, halfSize)。

9. 内存

调用 返回值
gpu.getUsedMemory() 当前使用的字节数。
gpu.getMaxMemory() 此外围设备的 VRAM 预算。

10. 鼠标与滚轮输入

仅在注视屏幕表面且没有 GUI 打开时触发。潜行(Sneaking)无效。键盘输入不在这里捕获 — 那是单独的键盘外围设备。

事件 参数 触发条件
tm_monitor_touch side, x, y, soft 绑定到“使用”(默认右键)的任意按钮。soft 始终为 false。
tm_monitor_mouse side, x, y, button, action 鼠标按键按下/释放。
tm_monitor_scroll side, x, y, dir dir 为 1(向上)或 -1(向下)。
tm_monitor_drag side, x, y, button 在该刻内按住时光标移动。每个客户端刻仅触发一次。

x, y 是跨整个阵列的屏幕绝对坐标(从 1 开始)。

while true do
  local ev, side, x, y, button, action = os.pullEvent("tm_monitor_mouse")
  gpu.setPixel(x, y, 0xFF0000)
  gpu.sync()
end

11. 3D 立即模式 API

gpu3d = gpu.createWindow3D(...)
gpu3d.glFrustum(70, 0.1, 100)
gpu3d.glLoadIdentity()
gpu3d.glTranslate(0, 0, -5)
gpu3d.glDirLight(0, -1, 0)
gpu3d.glBegin(4)   -- 三角形
gpu3d.glColor(0xFF0000)
gpu3d.glVertex(-1, -1, 0)
gpu3d.glVertex( 1, -1, 0)
gpu3d.glVertex( 0,  1, 0)
gpu3d.glEnd()
gpu3d.render()
gpu3d.sync()
调用 备注
glFrustum(fov, near, far) 透视投影。
glDirLight(x, y, z) 方向光。
glLoadIdentity() / glPushMatrix() / glPopMatrix() 模型矩阵堆栈。
glTranslate / glScale / glRotate(angleDeg, x,y,z)
glBegin([mode=4]) / glEnd() 开始/结束图元。
glVertex(x,y,z) 附加带有当前颜色/UV 的顶点。
glTexCoord(u,v) 下一个顶点的 UV。
glColor(color) 打包整数或 (r,g,b[,a])。
glEnable(3553) / glDisable(3553) 仅支持 GL_TEXTURE_2D。
glGenTextures() / glDeleteTextures / glBindTexture / glTexImage 纹理管理。
getConstants() GL 常量名称→值表。
render() 自上次 clear() 以来进行剔除、光照、裁剪、投影、排序和位块传输。
clear() 清除画布 + 三角形 + 重置矩阵/深度缓冲区。

12. 性能

所有绘图均在服务器端的 Java 中进行,无论是单人游戏、局域网还是专用服务器都是如此。将像素推送到客户端是唯一的实际客户端开销,通过批量内存复制完成。

逐像素的 Lua 绘图(光线行进、等离子效果等)会使客户端不堪重负 — 请改用着色器引擎,它在 GPU 上运行,每个像素零 Lua 开销。

13. 亮度(尼特)

gpu.setBrightness(200)   -- 正常亮度的 2 倍
print(gpu.getBrightness())

nits / 100 用于缩放最终的像素输出 —— 默认值为 100(即 1.0 倍)。该设置同时适用于 CPU 绘图和 GPU 着色器。若计算结果超过 255,则会截断而非回绕。取值范围可在服务器配置中调整(minBrightnessNits/maxBrightnessNits,默认为 10–400)。

你是这个资源的作者?登录后可认领此资源。

评论 0

0.0
暂无评分
5 星
0
4 星
0
3 星
0
2 星
0
1 星
0
我的评分

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源