210 lines
6.1 KiB
Markdown
210 lines
6.1 KiB
Markdown
# UTF-8 Display Library for ComputerCraft
|
||
|
||
> 一个支持中文与 UTF-8 字符的高性能像素字体显示库，适用于 **ComputerCraft**（包括 CC:Tweaked）环境。
|
||
|
||
---
|
||
|
||
## 📦 安装
|
||
|
||
### 方法一：本地加载（推荐）
|
||
#### 下载到本地
|
||
```shell
|
||
wget https://git.liulikeji.cn/xingluo/ComputerCraft-Utf8/raw/branch/main/utf8display/utf8display.lua utf8display.lua
|
||
```
|
||
#### 在 Lua 脚本中使用
|
||
```lua
|
||
local utf8display = require("utf8display")
|
||
```
|
||
|
||
### 方法二：远程加载（无需存储）
|
||
|
||
```lua
|
||
local utf8display = load(http.get("https://git.liulikeji.cn/xingluo/ComputerCraft-Utf8/raw/branch/main/utf8display/utf8display.lua").readAll())()
|
||
```
|
||
|
||
---
|
||
|
||
## ⚙️ 配置
|
||
|
||
默认配置如下：
|
||
|
||
```lua
|
||
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, -- 是否缓存已加载字体（提升性能）
|
||
}
|
||
```
|
||
|
||
### 修改配置
|
||
|
||
```lua
|
||
-- 示例：使用本地字体
|
||
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}`
|
||
|
||
---
|
||
|
||
## 🎨 颜色控制
|
||
|
||
### 统一颜色（数字）
|
||
|
||
```lua
|
||
utf8display.write("Hello 世界！", colors.red, colors.black)
|
||
```
|
||
|
||
### 逐字颜色（字符串）
|
||
|
||
```lua
|
||
utf8display.blit("ABC", "123", "000")
|
||
```
|
||
|
||
> 💡 颜色字符串长度不足时，后续字符使用默认色
|
||
|
||
---
|
||
|
||
## 📝 使用示例
|
||
|
||
### 基础用法
|
||
|
||
```lua
|
||
local utf8display = require("utf8display")
|
||
|
||
-- 自动初始化字体（首次调用 write/print 时触发）
|
||
utf8display.write("你好，ComputerCraft！")
|
||
|
||
utf8display.print("这是一段\n包含换行的\n中文文本。")
|
||
```
|
||
|
||
### 彩色输出
|
||
|
||
```lua
|
||
-- 统一颜色
|
||
utf8display.write("警告！", colors.orange, colors.black)
|
||
|
||
-- 逐字变色（彩虹效果）
|
||
utf8display.blit("RAINBOW", "1234567", "0000000")
|
||
```
|
||
|
||
### 使用本地字体
|
||
|
||
```lua
|
||
utf8display.setConfig("fontPath", "/my_fonts/chinese_font.lua")
|
||
utf8display.write("使用本地字体！")
|
||
```
|
||
|
||
### 手动加载字体
|
||
|
||
```lua
|
||
local success, error_msg = utf8display.loadFont()
|
||
if success then
|
||
print("字体加载成功！")
|
||
else
|
||
print("字体加载失败：" .. error_msg)
|
||
end
|
||
```
|
||
|
||
### 自动换行功能
|
||
|
||
```lua
|
||
-- 使用strToBimg的宽度参数进行自动换行
|
||
local bimg = utf8display.strToBimg("这是一段很长的文本，需要自动换行显示", colors.white, colors.black, 20)
|
||
-- 文本将在第20个cc字符位置自动换行
|
||
|
||
-- 或者在print中自动换行
|
||
utf8display.print("这是一段很长的文本，会自动换行显示", colors.white, colors.black)
|
||
```
|
||
|
||
---
|
||
|
||
## 🔙 返回值说明
|
||
|
||
所有显示函数均返回以下结构：
|
||
|
||
```lua
|
||
{
|
||
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以供自动换行时可能的切断单词使用 |