diff --git a/utf8display/README.md b/utf8display/README.md index 2dcada0..ee91aca 100644 --- a/utf8display/README.md +++ b/utf8display/README.md @@ -1,109 +1,109 @@ -```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, -- 是否缓存已加载的字体 - autoScroll = true -- print 函数是否自动滚动 -} -``` - -### 修改配置 -```lua -utf8display.setConfig("fontUrl", "your_font_url_here") -``` - -## 主要函数 - -### `utf8display.initFont()` -主动初始化字体,预先加载字体资源。 - -### `utf8display.write(str)` -- 不自动换行的字符串输出 -- 遇到换行符 `\n` 会替换为空格 -- 如果内容超出屏幕范围,光标回到起始位置 -- 返回: `{success, info}` - -### `utf8display.print(str)` -- 自动换行的字符串输出 -- 遵循传统 print 行为,自动换行并滚动 -- 遇到换行符 `\n` 会正常换行 -- 光标始终在输出内容的下一行开头 -- 返回: `{success, info}` - -### `utf8display.blit(str, textColorStr, backgroundColorStr)` -- 带颜色的字符串输出 -- 遇到换行符 `\n` 会替换为空格 -- `textColorStr` 和 `backgroundColorStr` 为颜色字符串 -- 如果内容超出屏幕范围,光标回到起始位置 -- 返回: `{success, info}` - -### `utf8display.getFontInfo()` -获取当前字体信息,包括高度、是否已加载等。 - -### `utf8display.isInitialized()` -检查字体是否已初始化。 - -## 使用示例 - -### 基本用法 -#### 本地加载 -```lua -local utf8display = require("utf8display") - --- 写入文本(不自动换行) -utf8display.write("Hello 世界!") - --- 写入文本(自动换行) -utf8display.print("Hello 世界!") - --- 带颜色输出 -utf8display.blit("Hello 世界!", "ffffffff", "00000000") -``` -#### 或网络加载 -```lua - -``` -### 预加载字体 -```lua -local utf8display = require("utf8display") - --- 主动初始化字体 -utf8display.initFont() -``` - -### 修改配置 -```lua -local utf8display = require("utf8display") - --- 设置本地字体路径 -utf8display.setConfig("fontPath", "/path/to/local/font.lua") -``` - -## 返回值说明 - -所有显示函数都返回一个包含以下信息的表: -- `success`: 操作是否成功 -- `textColor`: 文本颜色(write/print) -- `backgroundColor`: 背景颜色(write/print) -- `startX`, `startY`: 起始光标位置 -- `endX`, `endY`: 结束光标位置 -- `charCount`: 显示的字符数 -- `fontHeight`: 字体高度 -- `overflowX`: 水平方向是否溢出(write/blit) -- `overflowY`: 垂直方向是否溢出(write/blit) - -## 注意事项 - -1. 字体文件包含预定义的字符映射,支持中文字符 -2. write 和 blit 函数中的换行符 `\n` 会被替换为空格 -3. print 函数会正常处理换行符并自动换行 -4. 当内容超出屏幕范围时,write 和 blit 会将光标移回起始位置 -5. 支持在屏幕边界处正常显示字符,超出部分不会渲染 -6. 字体高度固定,所有字符都按此高度计算行间距 - -## 如何制作Font -- 字体文件返回一个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以供自动换行时可能的切断单词使用 +```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, -- 是否缓存已加载的字体 + autoScroll = true -- print 函数是否自动滚动 +} +``` + +### 修改配置 +```lua +utf8display.setConfig("fontUrl", "your_font_url_here") +``` + +## 主要函数 + +### `utf8display.initFont()` +主动初始化字体,预先加载字体资源。 + +### `utf8display.write(str)` +- 不自动换行的字符串输出 +- 遇到换行符 `\n` 会替换为空格 +- 如果内容超出屏幕范围,光标回到起始位置 +- 返回: `{success, info}` + +### `utf8display.print(str)` +- 自动换行的字符串输出 +- 遵循传统 print 行为,自动换行并滚动 +- 遇到换行符 `\n` 会正常换行 +- 光标始终在输出内容的下一行开头 +- 返回: `{success, info}` + +### `utf8display.blit(str, textColorStr, backgroundColorStr)` +- 带颜色的字符串输出 +- 遇到换行符 `\n` 会替换为空格 +- `textColorStr` 和 `backgroundColorStr` 为颜色字符串 +- 如果内容超出屏幕范围,光标回到起始位置 +- 返回: `{success, info}` + +### `utf8display.getFontInfo()` +获取当前字体信息,包括高度、是否已加载等。 + +### `utf8display.isInitialized()` +检查字体是否已初始化。 + +## 使用示例 + +### 基本用法 +#### 本地加载 +```lua +local utf8display = require("utf8display") + +-- 写入文本(不自动换行) +utf8display.write("Hello 世界!") + +-- 写入文本(自动换行) +utf8display.print("Hello 世界!") + +-- 带颜色输出 +utf8display.blit("Hello 世界!", "ffffffff", "00000000") +``` +#### 或网络加载 +```lua +local utf8display = load(http.get("https://git.liulikeji.cn/xingluo/ComputerCraft-Utf8/raw/branch/main/utf8display/utf8display.lua").readAll())() +``` +### 预加载字体 +```lua +local utf8display = require("utf8display") + +-- 主动初始化字体 +utf8display.initFont() +``` + +### 修改配置 +```lua +local utf8display = require("utf8display") + +-- 设置本地字体路径 +utf8display.setConfig("fontPath", "/path/to/local/font.lua") +``` + +## 返回值说明 + +所有显示函数都返回一个包含以下信息的表: +- `success`: 操作是否成功 +- `textColor`: 文本颜色(write/print) +- `backgroundColor`: 背景颜色(write/print) +- `startX`, `startY`: 起始光标位置 +- `endX`, `endY`: 结束光标位置 +- `charCount`: 显示的字符数 +- `fontHeight`: 字体高度 +- `overflowX`: 水平方向是否溢出(write/blit) +- `overflowY`: 垂直方向是否溢出(write/blit) + +## 注意事项 + +1. 字体文件包含预定义的字符映射,支持中文字符 +2. write 和 blit 函数中的换行符 `\n` 会被替换为空格 +3. print 函数会正常处理换行符并自动换行 +4. 当内容超出屏幕范围时,write 和 blit 会将光标移回起始位置 +5. 支持在屏幕边界处正常显示字符,超出部分不会渲染 +6. 字体高度固定,所有字符都按此高度计算行间距 + +## 如何制作Font +- 字体文件返回一个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以供自动换行时可能的切断单词使用