ComputerCraft-Utf8/utf8display

UTF-8 Display Library for ComputerCraft

一个支持中文与 UTF-8 字符的高性能像素字体显示库，适用于 ComputerCraft（包括 CC:Tweaked）环境。

---

📦 安装

方法一：本地加载（推荐）

下载到本地

wget https://git.liulikeji.cn/xingluo/ComputerCraft-Utf8/raw/branch/main/utf8display/utf8display.lua utf8display.lua

在 Lua 脚本中使用

local utf8display = require("utf8display")

方法二：远程加载（无需存储）

local utf8display = load(http.get("https://git.liulikeji.cn/xingluo/ComputerCraft-Utf8/raw/branch/main/utf8display/utf8display.lua").readAll())()

---

⚙️ 配置

默认配置如下：

utf8display.config = {
    fontUrl = "https://git.liulikeji.cn/xingluo/ComputerCraft-Utf8/raw/branch/main/fonts/fusion-pixel-8px-proportional-zh_hans.lua",
    fontPath = nil,     -- 本地字体路径（若设置则优先使用）
    cacheFont = true,   -- 是否缓存已加载字体（提升性能）
}

修改配置

-- 示例：使用本地字体
utf8display.setConfig("fontPath", "/fonts/my_font.lua")

-- 示例：更换远程字体
utf8display.setConfig("fontUrl", "https://example.com/my_font.lua")

✅ 支持的配置项：fontUrl、fontPath、cacheFont

---

🧰 主要函数

utf8display.write(str, [textColor, backgroundColor])

• 用途：不自动换行地输出文本（适合标题、状态栏等）
• 行为：
  • 换行符 \n 会被替换为空格
  • 若内容超出屏幕，光标回退至起始位置
  • 支持统一颜色或逐字颜色（见下文"颜色控制"）
• 返回值：{success, info}

utf8display.print(str, [textColor, backgroundColor])

• 用途：自动换行输出文本（类似传统 print）
• 行为：
  • 正常处理 \n 换行
  • 根据终端宽度自动换行
  • 光标最终位于输出内容下一行开头
• 返回值：{success, info}

utf8display.blit(str, textColorStr, backgroundColorStr)

• 用途：高级颜色控制输出（逐字符指定颜色）
• 参数：
  • textColorStr：前景色字符串（如 "123456"，每个字符对应一个 blit 颜色码）
  • backgroundColorStr：背景色字符串（同上）
• 注意：\n 同样被替换为空格
• 返回值：{success, info}

utf8display.strToBimg(str, textColor, backgroundColor, [width])

• 参数说明：
  • str：要转换的字符串
  • textColor：前景色，可以是：
    • colors.xxx（如 colors.red）
    • blit颜色字符串（如 "fff"）
  • backgroundColor：背景色，可以是：
    • colors.xxx（如 colors.black）
    • blit颜色字符串（如 "000"）
  • [width]：行宽限制（可选），如果输入数字则根据此大小进行自动换行
• 用途：将字符串转换为 bimg 格式（用于自定义渲染）
• 返回值：符合 term.blit() 格式的多帧图像结构（当前仅单帧）

utf8display.loadFont()

• 用途：手动加载字体资源
• 行为：根据配置加载远程或本地字体
• 返回值：{success, error_message}

---

🎨 颜色控制

统一颜色（数字）

utf8display.write("Hello 世界！", colors.red, colors.black)

逐字颜色（字符串）

utf8display.blit("ABC", "123", "000")

💡 颜色字符串长度不足时，后续字符使用默认色

---

📝 使用示例

基础用法

local utf8display = require("utf8display")

-- 自动初始化字体（首次调用 write/print 时触发）
utf8display.write("你好，ComputerCraft！")

utf8display.print("这是一段\n包含换行的\n中文文本。")

彩色输出

-- 统一颜色
utf8display.write("警告！", colors.orange, colors.black)

-- 逐字变色（彩虹效果）
utf8display.blit("RAINBOW", "1234567", "0000000")

使用本地字体

utf8display.setConfig("fontPath", "/my_fonts/chinese_font.lua")
utf8display.write("使用本地字体！")

手动加载字体

local success, error_msg = utf8display.loadFont()
if success then
    print("字体加载成功！")
else
    print("字体加载失败：" .. error_msg)
end

自动换行功能

-- 使用strToBimg的宽度参数进行自动换行
local bimg = utf8display.strToBimg("这是一段很长的文本，需要自动换行显示", colors.white, colors.black, 20)
-- 文本将在第20个cc字符位置自动换行

-- 或者在print中自动换行
utf8display.print("这是一段很长的文本，会自动换行显示", colors.white, colors.black)

---

🔙 返回值说明

所有显示函数均返回以下结构：

{
    success = true,
    startX = 1,         -- 起始光标 X
    startY = 1,         -- 起始光标 Y
    endX = 10,          -- 结束光标 X
    endY = 2,           -- 结束光标 Y
    charCount = 5,      -- 显示的字符数（UTF-8 计数）
    fontHeight = 8,     -- 字体高度（行高）
    overflowX = false,  -- 水平溢出（write/blit）
    overflowY = false,  -- 垂直溢出（write/blit）
    lineCount = 3       -- 行数（仅 print）
}

---

⚠️ 注意事项

1. 换行行为：
   • write / blit：\n → 空格
   • print：\n → 实际换行 + 自动折行
2. 性能：
   • 首次使用会自动加载字体（网络或本地）
   • 启用 cacheFont = true 可避免重复加载
3. 渲染机制：
   • 使用 term.blit() 高效绘制

---

🛠 如何制作自定义字体

• 字体文件返回一个table，键值为utf8编码，值为和对应字体的bitmap。
• bitmap为一个包含等长string的table，string中的char属于computer craft定义的2*3像素点阵（如需使用右下角像素，将char的码值减128表示反转backgroundColor 和 textColor）
• 单个字体文件中可以有不同尺寸的bitmap，且需要有'H'(ascII:72)的bitmap表示该文件中最大bitmap高度
• 会以FontFamily出现的最大bitmap高度为基准，最终输出下对齐的文本
• FontFamily中需要'-'(ascII:45)的bitmap以供自动换行时可能的切断单词使用