API_ru.md

HUD Glasses — Lua API

Тип периферии: hud_glasses.

local hud = peripheral.find("hud_glasses")
if not hud then error("HUD modem not found on the network") end

Большинство методов бинарно совместимы с CC monitor / term. Скрипт для монитора почти всегда работает на HUD без изменений.

Раздел	Методы
Запись текста	`write`, `blit`, `clear`, `clearLine`, `scroll`
Курсор	`getCursorPos`, `setCursorPos`, `getCursorBlink`, `setCursorBlink`
Размер	`getSize`, `setSize`, `setWidth`, `setHeight`, `resetSize`
Цвета пера	`getTextColour`, `setTextColour`, `getBackgroundColour`, `setBackgroundColour`, `isColour`
Палитра	`getPaletteColour`, `setPaletteColour`
Привязка / идентификация	`getId`, `getOwner`, `getOwners`, `getOwnerCount`
Поведение и ошибки	сводка
Примеры	готовые скрипты
Отличия от monitor

Запись текста

`write(text)`

Пишет text в текущей позиции курсора текущим цветом пера. После записи курсор сдвигается на #text вправо. Если курсор уехал за правый край — символы тихо отбрасываются.

Аргумент coerce'ится — 42, true, nil (→ "nil") тоже подходят.

hud.setCursorPos(1, 1)
hud.write("HP: ")
hud.write(20)

`blit(text, fgColours, bgColours)`

Пишет блок символов сразу с per-cell цветами. Все три аргумента — строки одинаковой длины (CC передаёт их как ByteBuffer, скрипт пишет обычные строки).

text — символы (1 байт на ячейку)
fgColours — hex 0..9 a..f (индекс палитры) на каждую ячейку
bgColours — то же, плюс символ - означает прозрачную ячейку фона

hud.setCursorPos(1, 3)
hud.blit("WARN",
         "eeee",     -- весь текст красный (e = colors.red)
         "----")     -- фон прозрачный

Throws Arguments must be the same length, если длины не совпадают.

`clear()`

Заливает весь буфер пробелами текущим setBackgroundColour. Если фон прозрачный (0) — экран становится пустым.

`clearLine()`

То же, но только строка, на которой курсор.

`scroll(y)`

Сдвигает все строки на y. y > 0 — содержимое уходит вверх (внизу появляются пустые строки текущим фоном пера), y < 0 — наоборот. |y| ≥ height эквивалентно clear().

hud.scroll(1)   -- прокрутить вверх на одну строку

Курсор

`getCursorPos() → x, y`

Возвращает текущую позицию курсора. 1-based: (1, 1) — левый верхний угол.

`setCursorPos(x, y)`

Перемещает курсор. Значения вне диапазона допустимы — следующая запись просто ничего не отрисует за пределами буфера.

`getCursorBlink() → blink`

Возвращает флаг «курсор мигает».

`setCursorBlink(blink)`

Устанавливает флаг. Замечание: сейчас курсор визуально не рисуется на HUD — флаг хранится только ради совместимости с библиотеками, которые его читают/пишут.

Размер

`getSize() → width, height`

Возвращает текущий размер сетки в символах (не в пикселях). HUD всегда заполняет экран — меньше клеток означает крупнее каждый символ.

`setSize(width, height)`

Меняет разрешение этого конкретного модема. Содержимое буфера при этом очищается.

width ∈ [4, 256]
height ∈ [1, 128]
иначе → LuaException.

После вызова модем «помечен» как кастомный — изменения hudWidth/hudHeight в hudglassescc-common.toml его больше не трогают. Размер хранится в NBT блока, переживает рестарт сервера, поршни и Sable sub-level.

hud.setSize(60, 20)

`setWidth(width)` / `setHeight(height)`

Удобство: меняет только одну ось, вторую оставляет как есть. Те же границы.

`resetSize()`

Снимает «кастомный» флаг и возвращает размер к текущим значениям hudWidth/hudHeight из конфига. Содержимое очищается.

Цвета пера

Аргумент colour всегда CC-bitmask: степень двойки в [1, 0x8000]. Используйте константы из CC API: colors.red, colors.lime и т.д. Любое другое число → LuaException("Expected color").

`getTextColour() → c`

Возвращает текущий цвет текста (для последующих write/clear).

Aliases: getTextColor.

`setTextColour(c)`

Устанавливает цвет текста.

Aliases: setTextColor. Throws на невалидном цвете.

`getBackgroundColour() → c`

Возвращает текущий цвет фона. 0 означает прозрачный (HUD-расширение).

Aliases: getBackgroundColor.

`setBackgroundColour(c)`

Устанавливает цвет фона. HUD-расширение: аргумент 0 делает фон прозрачным — clear() тогда оставляет экран пустым, а write не рисует подложку под символами. Любой другой c — обычный цвет CC.

Aliases: setBackgroundColor. Throws на цвете, который не 0 и не валидный CC-bitmask.

`isColour() → true`

Всегда возвращает true (HUD поддерживает все 16 цветов).

Aliases: isColor, getIsColour, getIsColor.

Палитра

У каждого модема — своя 16-цветная палитра, которую можно перенастраивать.

`getPaletteColour(c) → r, g, b`

Возвращает три числа в [0, 1] (RGB-компоненты текущей палитры для цвета c).

Aliases: getPaletteColor.

local r, g, b = hud.getPaletteColour(colors.red)

`setPaletteColour(c, ...)`

Меняет один из 16 цветов. Два варианта вызова:

-- RGB-int
hud.setPaletteColour(colors.red, 0xFF8800)

-- три float-а в [0..1]
hud.setPaletteColour(colors.red, 1.0, 0.5, 0.0)

Aliases: setPaletteColor. Throws при невалидном цвете или неверном числе аргументов.

Изменённая палитра живёт только в RAM буфера — сбрасывается к дефолтной при setSize / resetSize.

Привязка / идентификация

Привязка живёт на очках. ПКМ по модему очками в руке записывает id модема в сам предмет. Кто наденет эти очки (слот очков Curios или шлем) — тот видит HUD. Передал очки другому игроку → HUD «переезжает» вместе с ними. Один модем могут смотреть сколько угодно игроков одновременно.

`getId() → id`

Возвращает стабильный ID модема (число). Не меняется при перемещении, толчке поршнем, переезде в Sable sub-level (Create Aeronautics). Этот же ID показан в тултипе очков (Bound to modem #N).

print("This is modem #" .. hud.getId())

`getOwner() → name`

Возвращает ник первого текущего зрителя (кто сейчас носит привязанные очки) или nil, если никто не смотрит.

`getOwners() → table`

Возвращает Lua-таблицу ников текущих зрителей — игроков онлайн, которые прямо сейчас носят очки, привязанные к этому модему.

for _, name in ipairs(hud.getOwners()) do
    print(name)
end

`getOwnerCount() → n`

Сколько игроков сейчас смотрят этот модем.

Поведение и ошибки

Что бросает `LuaException`

Метод	Когда
`setTextColour` / `setBackgroundColour`	цвет не валидный CC-bitmask (для bg `0` тоже валиден)
`setPaletteColour`	цвет невалидный или странное число аргументов
`setSize` / `setWidth` / `setHeight`	вне `[4..256] × [1..128]`
`blit`	разные длины `text`/`fg`/`bg`

Что обрабатывается тихо (ничего не происходит, но без ошибки)

Ситуация	Поведение
Никто не носит привязанные очки	Запись копится в буфере. Кто наденет — сразу увидит текущее состояние.
Игрок снял очки	HUD у него пропадает. Надел снова — снова видит.
Очки переданы другому игроку	HUD «переезжает»: новый владелец видит то же самое.
Игрок вне `maxRangeBlocks`	Кадр «замораживается». Зайдёт в радиус — получит свежий.
`write("")` или `write` за пределами экрана	No-op.

Это сознательное решение: peripheral никогда не падает из-за состояния получателя. Скрипт пишет в буфер, доставка — отдельная забота сервера.

Примеры

1. Минимум: «Hello, HUD!»

local hud = peripheral.find("hud_glasses")
hud.setBackgroundColour(0)
hud.setTextColour(colors.lime)
hud.setCursorPos(1, 1)
hud.write("Hello, HUD!")

2. Часы по центру

local hud = peripheral.find("hud_glasses")
hud.setBackgroundColour(0)
hud.setTextColour(colors.white)

while true do
    local text = textutils.formatTime(os.time(), true)
    local w, h = hud.getSize()
    local x = math.floor((w - #text) / 2) + 1
    local y = math.floor(h / 2)
    hud.clear()
    hud.setCursorPos(x, y)
    hud.write(text)
    sleep(1)
end

3. Цветная полоса с `blit`

local hud = peripheral.find("hud_glasses")
local w, h = hud.getSize()
local label = " STATUS: OK "
local pad = math.floor((w - #label) / 2)

hud.setCursorPos(1, h)
hud.blit(string.rep(" ", pad) .. label .. string.rep(" ", w - pad - #label),
         string.rep("0", w),                      -- весь текст белый
         string.rep("d", w))                      -- весь фон зелёный

4. Адаптивный layout: меняем разрешение динамически

local hud = peripheral.find("hud_glasses")

local function showLarge(text)
    hud.setSize(40, 10)             -- крупно
    hud.setBackgroundColour(0)
    hud.clear()
    hud.setTextColour(colors.red)
    local w, h = hud.getSize()
    hud.setCursorPos(math.floor((w - #text) / 2) + 1, math.floor(h / 2))
    hud.write(text)
end

local function showCompact(lines)
    hud.setSize(80, 28)             -- мелко, много строк
    hud.setBackgroundColour(0)
    hud.clear()
    hud.setTextColour(colors.white)
    for i, line in ipairs(lines) do
        hud.setCursorPos(1, i)
        hud.write(line)
    end
end

showLarge("ALERT")
sleep(2)
showCompact({"Power: 80%", "Fuel:  120", "Crew:  3/4"})

5. Кто смотрит этот HUD

local hud = peripheral.find("hud_glasses")
print("Modem #" .. hud.getId() .. " is watched by:")
for _, name in ipairs(hud.getOwners()) do
    print("  " .. name)
end

Отличия от monitor

Аспект	`monitor` (CC)	`hud_glasses`
Отображение	физический блок в мире	overlay на экране игрока
Зрители	все, кто видит блок	все, кто носит привязанные очки
Прозрачный фон	нет	`setBackgroundColour(0)` или `-` в blit
Масштаб	`setTextScale(s)` (пиксели)	`setSize(w, h)` (клетки)
Размер	через `setTextScale` + множители блоков	`setSize` + дефолты из конфига
Поведение при offline	n/a (блок всегда «есть»)	копит буфер, доставит когда сможет
Доп. методы	—	`getId`, `getOwners`, `setSize`, `resetSize`

setTextScale / getTextScale не реализованы — у HUD нет понятия пиксельного шага, размер задаётся через setSize.

Справочник по кодировке символов (CC-шрифт в стиле CP437, адресуется по байту): CHARS.md.

API_ru.md

HUD Glasses — Lua API

Оглавление

Запись текста

write(text)

blit(text, fgColours, bgColours)

clear()

clearLine()

scroll(y)

Курсор

getCursorPos() → x, y

setCursorPos(x, y)

getCursorBlink() → blink

setCursorBlink(blink)

Размер

getSize() → width, height

setSize(width, height)

setWidth(width) / setHeight(height)

resetSize()

Цвета пера

getTextColour() → c

setTextColour(c)

getBackgroundColour() → c

setBackgroundColour(c)

isColour() → true

Палитра

getPaletteColour(c) → r, g, b

setPaletteColour(c, ...)

Привязка / идентификация

getId() → id

getOwner() → name

getOwners() → table

getOwnerCount() → n

Поведение и ошибки

Что бросает LuaException

Что обрабатывается тихо (ничего не происходит, но без ошибки)

Примеры

1. Минимум: «Hello, HUD!»

2. Часы по центру

3. Цветная полоса с blit

4. Адаптивный layout: меняем разрешение динамически

5. Кто смотрит этот HUD

Отличия от monitor

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

CC: HUD Glasses

Clone this wiki locally

`write(text)`

`blit(text, fgColours, bgColours)`

`clear()`

`clearLine()`

`scroll(y)`

`getCursorPos() → x, y`

`setCursorPos(x, y)`

`getCursorBlink() → blink`

`setCursorBlink(blink)`

`getSize() → width, height`

`setSize(width, height)`

`setWidth(width)` / `setHeight(height)`

`resetSize()`

`getTextColour() → c`

`setTextColour(c)`

`getBackgroundColour() → c`

`setBackgroundColour(c)`

`isColour() → true`

`getPaletteColour(c) → r, g, b`

`setPaletteColour(c, ...)`

`getId() → id`

`getOwner() → name`

`getOwners() → table`

`getOwnerCount() → n`

Что бросает `LuaException`

3. Цветная полоса с `blit`