Open Peripheral Addons: Terminal Glasses в OpenComputers

[Xytabich 257]

OpenPeripheral предоставляет мощный функционал по созданию собственных интерфейсов в виде очков дополненной реальности "Terminal Glasses". К сожалению, полного списка функционала и всех нюансов по работе с этими очками не найти. Присутствуют некоторые отрывки, небольшие видео с результатами работы и прочие поделки. Но! Спустя пару бессонных ночей, декомпилированного кода и трёх литров чая, удалось описать полный функционал этих очков.

 

Основные возможности очков и периферии:

• Отображение геометрических объектов различной сложности и цветовой гаммы.
• Отображение текста.
• Отображение жидкостей и предметов.
• Взаимодействие с мышью/клавиатурой.
• Чтение сообщений чата.
• Специальные команды чата, не отображающиеся в нем.
• Возможность индивидуальной работы с каждым пользователем терминала.
• Установка очков в любой шлем.

 

Возможности данных очков я опишу по разделам, в лучших традициях вики 

Для начала, определю некоторые понятия.

Система терминальных очков состоит из трёх предметов: терминала, очков, беспроводной клавиатуры.

Терминал является центром всей системы, через него происходит общение между компьютером и очками. Также он хранит все данные интерфейса и пользователей.

На очки выводится вся графическая информация, а сами очки передают сообщения или команды чата на терминал.

Беспроводная клавиатура позволяет дополнить всю систему, своей возможностью контроля элементов при помощи клавиатуры и мыши.

 

Как выводить информацию на очки:

local com = require("component")
local opb = com.openperipheral_bridge

-- Построение интерфейса происходит во внутреннем буффере терминала (он же мост).
local text = opb.addText(10, 10, "", 0xffef7f) -- Создаем компонент "Текст".
-- Его нужно создать только один раз, в остальное время можно обращаться по ссылке и изменять любой параметр.

local counter = 0
while true do -- В качестве примера будет выводится счетчик секунд.
  text.setText(tostring(counter)) -- Обновляем текста компонента.
  
  opb.sync() -- Для отображения графики на экране, необходимо отправить буффер на очки.
  
  os.sleep(1) -- Ждем секунду и прибавляем счетчик.
  counter = counter+1
end

 

API

Перед тем как перейти к API, нужно знать:

Color:number -- Число в формате TrueColor RGB (по умолчанию 0xffffff).
Opacity:number -- Прозрачность, число от 0.0 до 1.0 (по умолчанию 1).
Знак '?' -- Опциональный параметр/функция.

 

События

Скрытый текст

Все события имеют несколько одинаковых параметров, остальные описываются индивидуально:

componentAddress:string, userName:string, userUUID:string

 

Сами события:

glasses_key_down(keyCode:number, char:string, isRepeat:boolean)
-- Событие нажатия или удержания(isRepeat = true) кнопки клавиатуры.

glasses_key_up(keyCode:number)
-- Событие отпускания кнопки клавиатуры.

glasses_mouse_scroll(value:number)
-- Событие поворота колесика мыши.

glasses_mouse_down(button:number)
-- Событие нажатия кнопки мыши.

glasses_mouse_up(button:number)
-- Событие отпускания кнопки мыши.

glasses_component_mouse_wheel(id:number, private:boolean, x:number, y:number, value:number) 
-- Событие поворота колесика мыши над интерактивным элементом.
-- Параметр id является идентификатором объекта, над которым сработало событие.
-- Позиции x,y относительно позиции объекта.
-- Поле private устанавливается если элемент находится в интерфейсе отдельного пользователя.

glasses_component_mouse_down(id:number, private:boolean, x:number, y:number, button:number)
-- Событие нажатия кнопки мыши над интерактивным элементом.
-- Параметр id является идентификатором объекта, над которым сработало событие.
-- Позиции x,y относительно позиции объекта.

glasses_component_mouse_up(id:number, private:boolean, x:number, y:number, button:number)
-- Событие отпускания кнопки мыши над интерактивным элементом.
-- Параметр id является идентификатором объекта, над которым сработало событие.
-- Позиции x,y относительно позиции объекта.

glasses_mouse_drag(deltaX:number, deltaY:number)
-- Событие перетаскивания мышью (движение с зажатой клавишей мыши).

glasses_attach
-- Событие экипировки очков.

glasses_detach
-- Событие снятия очков.

glasses_capture
-- Событие входа в режим захвата.

glasses_release
-- Событие выхода из режима захвата.

glasses_chat_message(msg:string)
-- Пользователь отправил сообщение в чат.

glasses_chat_command(command:string)
-- Пользователь отправил команду.
-- Командой является сообщение в чат, начинающееся с символов '$$'

 

Строковые константы

VerticalAlignment:[TOP, MIDDLE, BOTTOM]
HorizontalAlignment:[LEFT, MIDDLE, RIGHT]
GuiElement:[OVERLAY, PORTAL, HOTBAR, CROSSHAIRS, BOSS_HEALTH, HEALTH, ARMOR, FOOD, MOUNT_HEALTH, AIR, EXPERIENCE, JUMP_BAR, OBJECTIVES]

 

Структуры данных

SimpleBox, ColoredPoint, Coord, User

Скрытый текст

Структура таблиц, возвращаемых или задаваемых функциям.

SimpleBox -- Содержит информацию о положении и размере области.
  top:number
  left:number
  width:number
  height:number

ColoredPoint -- Содержит информацию о вершине: её положение и цвет.
  x:number
  y:number
  rgb:Color?
  opacity:Opacity?

Coord -- Содержит информацию о координатах объекта.
  x:number
  y:number

User: -- Содержит информацию о пользователе терминала.
  name:string -- Имя игрока.
  uuid:string -- Уникальный идентификатор игрока в терминале.

 

 

Абстрактные объекты

Drawable, BoundedShape, Box

Скрытый текст

Здесь я описал базовый функционал некоторых типов объектов, наследники которых реализуют этот функционал.

Drawable -- Базовый интерфейс всех отображаемых объектов
  getId():number
    -- Получить идентификатор объекта в терминале.
  delete()
    -- Удалить объект из терминала.
  getType():string
    -- Получить тип объекта.
  get/setVisible():boolean
    -- Получить или установить видимость объекта.
  get/setClickable():boolean
    -- Получить или установить интерактивность объекта.
  get/setRotation():number
    -- Получить или установить текущий поворот объекта (в градусах).
  get/setUserdata():object
    -- Получить или установить кастомные данные. Могут быть любого типа,
    -- используются для хранения данных/ссылок и т.п. (при необходимости).
  get/setZ():number
    -- Получить или установить положение объекта по оси 'Z'.
    -- Принимаются значения от -32768 до 32767 (short), но отображаться будут только в пределах [-999, 1000].
    -- Чем больше значение - тем "ближе" объект.
  setScreenAnchor(horizontal:HorizontalAlignment, vertical:VerticalAlignment)
    -- Установить начальную точку отсчета.
    -- Т.е. позицию {x:0,y:0} относительно экрана.
  setObjectAnchor(horizontal:HorizontalAlignment, vertical:VerticalAlignment)
    -- Установить конечную точку отсчета.
    -- Т.е. сдвигает координаты {x:0,y:0} объекта на ширину и/или высоту объекта.
    -- Также является осью поворота объекта.
  setAlignment(horizontal:HorizontalAlignment, vertical:VerticalAlignment)
    -- Устанавливает начальную и конечную точку отсчета одновременно.

BoundedShape:Drawable -- Базовый объект для объектов с произвольным набором вершин(точек).
  getBoundingBox():SimpleBox
    -- Возвращает экранную позицию и размер объекта.

Box:Drawable -- Базовый объект для прямоугольников.
  get/setX():number
  get/setY():number
  get/setWidth():number
  get/setHeight():number

 

 

Графические объекты

Скрытый текст

Имеют расширенные возможности по представлению изображения на экране.

Point:Drawable -- Точка на экране.
  get/setCoord():Coord
    -- Экранные координаты точки.
  get/setSize():number
    -- Размер точки (по умолчанию 1).
  get/setColor():Color
  get/setOpacity():Opacity

SolidLine:BoundedShape -- Закрашенная линия.
  get/setWidth():number
    -- Ширина линии (по умолчанию 1).
  get/setP1():Coord
    -- Первая точка линии.
  get/setP2():Coord
    -- Вторая точка линии.
  get/setColor():Color
  get/setOpacity():Opacity

GradientLine:BoundedShape -- Линия с градиентным переходом.
  get/setWidth():number
    -- Ширина линии (по умолчанию 1).
  get/setP1():ColoredPoint
    -- Первая точка линии.
  get/setP2():ColoredPoint
    -- Вторая точка линии.

SolidLineStrip:BoundedShape -- Закрашенная произвольная линия.
  get/setWidth():number
    -- Ширина линии (по умолчанию 1).
  get/setPoints():Coord[]
    -- Получить или установить вершины линии.
  ?getPoints(index:number):Coord
    -- Получить вершину по индексу.
  ?setPoints(point:Coord, index:number)
    -- Установить вершину по индексу.
  get/setColor():Color
  get/setOpacity():Opacity

GradientLineStrip:BoundedShape -- Произвольная линия с градиентным переходом.
  get/setWidth():number
    -- Ширина линии (по умолчанию 1).
  get/setPoints():ColoredPoint[]
    -- Получить или установить вершины линии.
  ?getPoints(index:number):ColoredPoint
    -- Получить вершину по индексу.
  ?setPoints(point:ColoredPoint, index:number)
    -- Установить вершину по индексу.

SolidBox:Box -- Закрашенный прямоугольник.
  get/setColor():Color
  get/setOpacity():Opacity

GradientBox:Box -- Прямоугольник с градиентным переходом.
  get/setColor1():Color
  get/setOpacity1():Opacity
  get/setColor2():Color
  get/setOpacity2():Opacity
  get/setGradient():number
    -- Направление градиента, 1 - снизу/вверх, остальные значения - справа/налево.

SolidTriangle:BoundedShape -- Закрашенный треугольник.
  get/setP1():Coord
  get/setP2():Coord
  get/setP3():Coord
  get/setColor():Color
  get/setOpacity():Opacity

GradientTriangle:BoundedShape -- Треугольник с градиентным переходом.
  get/setP1():ColoredPoint
  get/setP2():ColoredPoint
  get/setP3():ColoredPoint

SolidQuad:BoundedShape -- Закрашенный четырёхугольник.
  get/setP1():Coord
  get/setP2():Coord
  get/setP3():Coord
  get/setP4():Coord
  get/setColor():Color
  get/setOpacity():Opacity

GradientQuad:BoundedShape -- Четырёхугольник с градиентным переходом.
  get/setP1():ColoredPoint
  get/setP2():ColoredPoint
  get/setP3():ColoredPoint
  get/setP4():ColoredPoint

SolidPolygon:BoundedShape -- Закрашенная произвольная фигура.
  get/setPoints():Coord[]
    -- Получить или установить вершины фигуры.
  ?getPoints(index:number):Coord
    -- Получить вершину по индексу.
  ?setPoints(point:Coord, index:number)
    -- Установить вершину по индексу.
  get/setColor():Color
  get/setOpacity():Opacity

GradientPolygon:BoundedShape -- Произвольная фигура с градиентным переходом.
  get/setPoints():ColoredPoint[]
    -- Получить или установить вершины фигуры.
  ?getPoints(index:number):ColoredPoint
    -- Получить вершину по индексу.
  ?setPoints(point:ColoredPoint, index:number)
    -- Установить вершину по индексу.

ItemIcon:Drawable -- Иконка предмета с размерами 16х16
  get/setX():number
  get/setY():number
  get/setScale():number
    -- Размер иконки (по умолчанию 1).
  get/setItemId():string
    -- Полный id предмета.
  get/setMeta():number
    -- Метаданные объекта (поворот и т.п.).
  get/setDamageBar():number
    -- Полоска прочности объекта.
    -- 0.0 - полоса отсутствует, 1.0 - полоса пустая (закончилась прочность).
  get/setLabel():string
    -- Текст с информацией о количестве.
    -- Тем не менее, может принимать и отображать любой текст.

LiquidIcon:Box -- Прямоугольник с текустурой жидкости.
  get/setFluid():string
    -- Имя жидкости (не id блока).
  get/setAlpha():Opacity

Text:Drawable -- Текстовое поле.
  get/setX():number
  get/setY():number
  get/setText():string
    -- Отображаемый текст.
  get/setScale():number
    -- Размер текста (по умолчанию 1).
  get/setColor():Color
  get/setAlpha():Opacity

 

Управление графическими объектами
DrawableFactory, DrawableContainer

Скрытый текст

DrawableFactory -- Фабрика отображаемых объектов. Созданный объект автоматически добавляется в контейнер.
  addPoint(coord:Coord, color:Color?, opacity:Opacity?):Point
    -- Создать объект Point - точку.
  addLine(p1:Coord, p2:Coord, color:Color?, opacity:Opacity?):SolidLine
    -- Создать объект SolidLine - цветную линию.
  addGradientLine(p1:ColoredPoint, p2:ColoredPoint):GradientLine
    -- Создать объект GradientLine - линию с градиентным переходом.
  addLineList(color:Color?, opacity:Opacity?, point1:Coord, point2...):SolidLineStrip
    -- Создать объект SolidLineStrip - произвольную цветную линию.
  addGradientLineList(point1:ColoredPoint, point2...):GradientLineStrip
    -- Создать объект GradientLineStrip - произвольную линию с градиентным переходом.
  addBox(x:number, y:number, width:number, height:number, color:Color?, opacity:Opacity?):SolidBox
    -- Создать объект SolidBox - цветной прямоугольник.
  addGradientBox(x:number, y:number, width:number, height:number, color:Color?, opacity:Opacity?,
        color2:Color?, opacity2:Opacity?, gradient:number):GradientBox
    -- Создать объект GradientBox - прямоугольник с градиентным переходом.
    -- Параметр gradient определяет направление градиента, 1 - вертикальный, 2 - горизонтальный.
    -- Если gradient установлен в 0, color2 и opacity2 игнорируются - получается цветной прямоугольник.
  addTriangle(p1:Coord, p2:Coord, p3:Coord, color:Color?, opacity:Opacity?):SolidTriangle
    -- Создать объект SolidTriangle - цветной треугольник.
  addGradientTriangle(p1:ColoredPoint, p2:ColoredPoint, p3:ColoredPoint):GradientTriangle
    -- Создать объект GradientTriangle - треугольник с градиентным переходом.
  addQuad(p1:Coord, p2:Coord, p3:Coord, p4:Coord, color:Color?, opacity:Opacity?):SolidQuad
    -- Создать объект SolidQuad - цветной четырёхугольник.
  addGradientQuad(p1:ColoredPoint, p2:ColoredPoint, p3:ColoredPoint, p4:ColoredPoint):GradientQuad
    -- Создать объект GradientQuad - четырёхугольник с градиентным переходом.
  addPolygon(color:Color?, opacity:Opacity?, point1:Coord, point2...):SolidPolygon
    -- Создать объект SolidPolygon - произвольную цветную фигуру.
  addGradientPolygon(point1:ColoredPoint, point2...):GradientPolygon
    -- Создать объект GradientPolygon - произвольную фигуру с градиентным переходом.
  addIcon(x:number, y:number, id:string, meta:number?):ItemIcon
    -- Создать объект ItemIcon - иконку предмета с размерами 16*16.
  addFluid/addLiquid(x:number, y:number, width:number, height:number, liquid:string):LiquidIcon
    -- Создать объект LiquidIcon - прямоугольник с текстурой жидкости.
  addText(x:number, y:number, text:string, color:Color?):Text
    -- Создать объект Text - цветной текст.

DrawableContainer -- Хранит отображаемые объекты.
  getById/getObjectById(id:number):Drawable
    -- Получить объект по идентификатору.
  getAllIds():number[]
    -- Получить идентификаторы хранящихся объектов.
  getAllObjects():{id:number, obj:Drawable}
    -- Получить таблицу хранящихся объектов.
  clear()
    -- Удалить все объекты.

 

 

Управление терминалом

Скрытый текст

Объекты обеспечивающие взаимодействие с терминалом и пользователями.

UserSurface:DrawableContainer, DrawableFactory -- Контролирует интерфейс отдельно взятого пользователя.

CaptureControl -- Предоставляет управление "режимом захвата" во время использования "Беспроводной клавиатуры".
  stopCapturing()
  -- Остановить захват.
  setBackground(color:Color, alpha:Opacity?)
  -- Установить цвет и прозрачность фона.
  setKeyRepeat(repeat:boolean)
    -- Включить/отключить периодический повтор события "glasses_key_down" (по умолчанию false).
  setDragParameters(distance:number, delay:number)
    -- Установить минимальную дистанцию для возникновения события "glasses_mouse_drag"
    -- и минимальное время между срабатываниями (в тиках).
    -- По умолчанию distance=5, delay=10, эти значения также являются минимальными.
  toggleGuiElements({element:GuiElement, value:boolean})
    -- Установить видмость стандартных графических элементов.

TerminalGlassesBridge:DrawableContainer, DrawableFactory -- Управляет интерфейсами и хранит данные пользователей.
  getGuid():string
    -- Получить уникальный идентификатор терминала.
  sync()
    -- Отправить графические данные на очки всех пользователей.
  getUsers():User[]
    -- Получить всех пользователей терминала.
  getSurfaceByName(username:string):UserSurface
    -- Получить холст по имени игрока.
  getSurfaceByUUID(uuid:string):UserSurface
    -- Получить холст по уникальному идентификатору игрока.
  getCaptureControl(uuid:string):CaptureControl
    -- Получить контроллер режима захвата.

 

Вот такая шпаргалка по очкам, надеюсь пригодится 

Изменено 24 января, 2021 пользователем Xytabich

[Alex 4 683]

10 часов назад, Xytabich сказал:

Вот такая шпаргалка по очкам, надеюсь пригодится 

гайд четкий. Отличный контент для сайта.

[Oleshe 35]

@Xytabich 

У меня есть предъява, нету параметра setDragParameters.

Как и параметра setKeyRepeat.

Почему?

Изменено 25 июня, 2022 пользователем Oleshe

[Xytabich Автор темы 257]

@Oleshe неизвестно, без примера кода это лишь абстрактные ошибки

Изменено 25 июня, 2022 пользователем Xytabich

[Oleshe 35]

1 час назад, Xytabich сказал:

@Oleshe неизвестно, без примера кода это лишь абстрактные ошибки

вот

[Xytabich Автор темы 257]

@Oleshe компонент "openperipheral_bridge" возвращает объект типа TerminalGlassesBridge, у него нет подобных методов. Для использования setDragParameters и подобных методов, необходим объект CaptureControl, который доступен только в режиме захвата (насколько я помню). Т.е. необходимо сначала удостовериться что пользователь надел очки, для этого можно использовать события glasses_capture и glasses_release. После этого можно получить CaptureControl при помощи openperipheral_bridge.getCaptureControl(uuid), используя uuid пользователя который находится в режиме захвата (т.е. ткнул пкм с клавиатурой в руках).
Примерный код:

local bridge = component.openperipheral_bridge

event.listen("glasses_capture", function()
  local uuid = bridge.getUsers()[1].uuid -- можно использовать только если один пользователь использует терминал
  local capture = bridge.getCaptureControl(uuid)
  capture.setDragParameters(5, 10)
end)

 

В данной статье используются принципы объектно-ориентированного программирования, для сокращения объема кода и разделения функционала по своим разделам. По этому необходимо обращать внимание в каком объекте реализован необходимый функционал, а также возвращаемые функциями значения. Например:

TerminalGlassesBridge:DrawableContainer, DrawableFactory
  -- при использовании объекта TerminalGlassesBridge можно так же использовать функционал из объектов DrawableContainer и DrawableFactory
  -- TerminalGlassesBridge также реализует собственный функционал:
  getCaptureControl(uuid:string):CaptureControl
    -- принимает на вход параметр с именем uuid, имеющий тип string
    -- возвращает объект типа CaptureControl

 

Изменено 26 июня, 2022 пользователем Xytabich