OpenComputers/Robot API

Этот программный интерфейс доступен только тогда, когда исполняющий компьютер является роботом.

## Общие функции

`robot.level(): number`


Получает текущий уровень робота. Дробная часть обозначает текущий прогресс до следующего уровня. Например, если это число `1.5`

, робот имеет уровень 1, и на 50% достиг второго уровня.

**Внимание**: начиная с версии **1.3** функция устарела. Используйте `component.experience.level()`

, поскольку робот получает очки опыта, только при наличии апгрейда на опыт.

`robot.name(): string`


Получает название робота.



## Работа с блоками

`robot.detect(): boolean, string`


Проверяет, есть ли что-нибудь перед роботом. Возвращает `true`

если что-то может препятствовать движению робота, `false`

в противном случае. Второе возвращаемое значение определяет что именно находится перед роботом. Это может быть `entity`

, `solid`

, `replaceable`

, `liquid`

или `air`

. Первые два могут блокировать робота, остальные — нет. В случае `entity`

это может быть как животным или мобом, так и игроком или вагонеткой.

*Примечание*: для того чтобы получить более подробную информацию (ID, метаданные) о блоке, вы можете использовать функцию `analyze()`

геосканера.

`robot.detectUp(): boolean, string`


Аналогично `robot.detect()`

, только проверяет блок над роботом.

`robot.detectDown(): boolean, string`


Аналогично `robot.detect()`

, только проверяет блок под роботом.



`robot.swing([side: number]): boolean[, string]`


Производит "левый щелчок мыши" роботом, используя при этом экипированный инструмент. Результат зависит от инструмента и того, какой блок располагается перед роботом. Возвращает `true`

и дескриптор, если был обработан какой-то блок, либо `false`

и возможную причину в случае неудачи.

Параметр `side`

определяет сторону подвергаемую обработке. Если параметр опущен, робот перебирает все возможные стороны. Это позволяет контролировать направление "щелчка мыши" если необходимо.

Возвращаемая строка может быть одной из следующих:

`entity`

— если робот атаковал живое существо


`block`

— если робот сломал блок


`fire`

— если робот потушил огонь


`air`

— если перед роботом ничего не было


`robot.swingUp([side: number]): boolean[, string]`


Аналогично `robot.swing()`

, но работает с блоком над роботом.

`robot.swingDown([side: number]): boolean[, string]`


Аналогично `robot.swing()`

, но работает с блоком под роботом.



`robot.use([side: number[, sneaky: boolean[, duration: number]]]): boolean[, string]`


Делает "правый щелчок мыши" роботом, используя экипированный инструмент. Результат зависит от инструмента и блока перед роботом.
Возвращает `true`

в случае успеха, либо `false`

в случае неудачи.

Параметр `side`

определяет сторону, куда направлено действие. Если параметр опущен, робот попробует воздействовать на все стороны. Это позволяет точнее контролировать действие, если необходимо. К примеру — сторону в которую полетит стрела, если использовать лук.

Параметр `sneaky`

определяет "присел" ли робот (для игрока — клавиша `⇧ Shift`), совершая действие. Это необходимо, к примеру, если робот пытается разместить блок на устройстве, которое по "правому щелчку" открывает свой интерфейс.

Параметр `duration`

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

Возвращаемое значение может быть:

`block_activated`

— если блок перед роботом был активирован (например — рычаг)


`item_placed`

— если выбранный предмет был использован перед роботом (например — поставлен блок, или использована костная мука на растении)


`item_used`

— если экипированный инструмент был использован непосредственно (например — робот выстрелил из лука)


`air`

— если ничего нельзя использовать в выбранном направлении, или экипированный инструмент нельзя использовать сам по себе


`robot.useUp([side: number[, sneaky: boolean[, duration: number]]]): boolean[, string]`


Аналогично `robot.use()`

, но работает с блоком над роботом.

`robot.useDown([side: number[, sneaky: boolean[, duration: number]]]): boolean[, string]`


Аналогично `robot.use()`

, но работает с блоком под роботом.



## Работа с инвентарем

`robot.durability(): number or nil, string`


Если робот имеет инструмент, функция возвращает состояние этого инструмента. Возможные значение: 0 - сломан, 1 - цел.

Если робот не имеет инструмента, или инструмент не может быть сломан, функция возвратит `nil`

и соответствующую строку: `no tool equipped`

или `tool cannot be damaged`

.

`robot.inventorySize(): number`


Возвращает внутренний размер инвентаря.

`robot.select([slot: number]): number`


Делает активным слот инвентаря с заданным индексом. Индекс — число в интервале от 1 до N, где N — число слотов (зависит от количества апгрейдов на инвентарь). Нумерация начинается в левом верхнем углу, и идет слева направо и сверху вниз. Таким образом левый верхний слот имеет номер 1, верхний правый — 4, левый нижний — 13, правый нижний — 16. Создает ошибку, если введен неверный индекс. Возвращаемое значение — номер выбранного слота. Функция может использоваться без аргументов, для получения номера активного слота.

`robot.count([slot: number]): number`


Возвращает количество предметов в заданном слоте. Если номер слота не задан, возвращает количество предметов в активном слоте.

`robot.space([slot: number]): number`


Возвращает количество предметов которое может еще поместиться в заданный слот. Это число зависит от типа предметов, которые уже находятся в слоте. (К примеру, ведра складываются в стеки только по 16. Если в слоте уже есть два ведра, функция вернет число 14.) Если слот не задан, функция работает с активным слотом.

`robot.compareTo(slot: number): boolean`


Сравнивает предметы в заданном и активном слотах. Если предметы одинаковы (количество предметов в слотах не имеет значение) — возвращает `true`

. Иначе — `false`

.

`robot.transferTo(slot: number[, count: number]): boolean`


Перемещает предметы из активного слота в заданный. Если определен параметр `count`

, функция перемещает заданное количество предметов. Возвращает `true`

, если был перемещен хотя бы один предмет, и `false`

— если ни одного.

Обратите внимание, что если целевой слот не пуст, а число предметов для перемещения не задано, больше или равно числу предметов в активном слоте, результатом будет обмен слотов содержимым.



`robot.compare(): boolean`


Сравнивает предмет в заданном слоте и блок перед роботом. Если блок эквивалентен предмету в слоте — возвращает `true`

. Иначе — `false`

.

`robot.compareUp(): boolean`


Аналогично `robot.compare()`

, но сравнивает с блоком над роботом.

`robot.compareDown(): boolean`


Аналогично `robot.compare()`

, но сравнивает с блоком под роботом.



`robot.drop([count: number]): boolean`


Выбрасывает предмет из активного слота. `count`

может определять число предметов. Если перед роботом находится блок с инвентарем, например сундук, робот попытается положить предметы в него. Если инвентаря перед роботом нет, предметы будут просто выброшены наружу. Возвращает `true`

, если один или больше предмет был выброшен. Иначе — `false`

. Если инвентарь (сундук) полон, функция вернет `false`

и предметы выброшены не будут.

Также функция работает для вагонеток с сундуками и вагонеток с воронками.

`robot.dropUp([count: number]): boolean`


Аналогично `robot.drop()`

, но работает с блоком над роботом.

`robot.dropDown([count: number]): boolean`


Аналогично `robot.drop()`

, но работает с блоком под роботом.



`robot.place([side: number[, sneaky: boolean]]): boolean`


Помещает блок из активного слота перед роботом. Возвращает `true`

в случае успеха, иначе — `false`

. Параметр `side`

определяет сторону на которую будет помещен блок. Если параметр опущен, робот попробует все поверхности. Это позволяет точнее ставить блоки, которые имеют ориентацию. (Например — факел. Значение `5`

или `sides.left`

позволит разместить факел на стене слева.) Параметр `sneaky`

определяет "присел" (для игрока — клавиша `⇧ Shift`) ли робот когда ставил блок. Это необходимо для некоторых модов.

**Важно**: по умолчанию, робот не может ставить блок в воздухе без опоры (как и игрок). В пространстве перед роботом должна быть хотя бы одна "стенка". Если вы хотите, чтобы роботы могли ставить блоки в воздухе (как черепашки из ComputerCraft) установите роботу апгрейд-"ангел".

`robot.placeUp([side: number[, sneaky: boolean]]): boolean`


Аналогично `robot.place()`

, но работает с блоком над роботом.

`robot.placeDown([side: number[, sneaky: boolean]]): boolean`


Аналогично `robot.place()`

, но работает с блоком под роботом.



`robot.suck([count: number]): boolean`


Захватывает максимум один стек предметов в активный слот, или первый свободный слот после активного. Возвращает `true`

если захватил один или больше предметов, иначе — `false`

. Если перед роботом находится блок с инвентарем (например — сундук), робот попытается забрать предметы из него. Параметр `count`

определяет, сколько именно предметов будет захвачено. Функция также работает с вагонетками с инвентарем.

Если перед роботом нет инвентаря, он попытается подобрать предмет "с земли". В этом случае параметр `count`

будет проигнорирован.

`robot.suckUp([count: number]): boolean`


Аналогично `robot.suck()`

, но работает с блоком над роботом.

`robot.suckDown([count: number]): boolean`


Аналогично `robot.suck()`

, но работает с блоком под роботом.



## Работа с внутренними цистернами

`robot.tankCount():number`


Возвращает число внутренних цистерн робота.

`robot.selectTank(tank)`


Выбирает одну из цистерн активной.

`robot.tankLevel([tank:number]):number`


Возвращает уровень жидкости в заданной (а если параметр не указан — в активной) цистерне.

`robot.tankSpace([tank:number]):number`


Возвращает объем свободного пространства в заданной (а если параметр не указан — в активной) цистерне.

`robot.compareFluidTo(tank:number):boolean`


Сравнивает жидкости в активной и указанной параметром цистернах.

`robot.transferFluidTo(tank:number[, count:number]):boolean`


Перемещает указанное количество жидкости из активной цистерны в заданную. Если количество не указано — перемещает 1000 mB (1 ведро).

`robot.compareFluid():boolean`


Сравнивает жидкость в активной цистерне с жидкостью перед роботом (или в хранилище перед роботом).

`robot.compareFluidUp():boolean`


Аналогично `compareFluid()`

, но сравнивает с жидкостью над роботом.

`robot.compareFluidDown():boolean`


Аналогично `compareFluid()`

, но сравнивает с жидкостью под роботом.

`robot.drain([count:number]):boolean`


Закачивает жидкость из блока перед роботом в активную внутреннюю цистерну. Если объем не указан, закачивает 1000 mB (1 ведро).

`robot.drainUp([count:number]):boolean`


Аналогично `drain()`

, но закачивает жидкость над роботом.

`robot.drainDown([count:number]):boolean`


Аналогично `drain()`

, но закачивает жидкость под роботом.

`robot.fill([count:number]):boolean`


Выкачивает жидкость из активного внутреннего хранилища в блок перед роботом. Если объем не указан, выкачивает 1000 mB (1 ведро).

`robot.fillUp([count:number]):boolean`


Аналогично `fill()`

, но выкачивает жидкость в пространство над роботом.

`robot.fillDown([count:number]):boolean`


Аналогично `fill()`

, но выливает жидкость в пространство под роботом.



## Движение робота

`robot.forward(): boolean[, string]`


Робот делает попытку двигаться вперед на один блок. Возвращает `true`

в случае успеха. Иначе — `nil`

и возможную причину — в противном случае. Причина — одна из строк функции `robot.detect()`

.

`robot.back(): boolean[, string]`


Аналогично `robot.forward()`

, но двигает робота на один блок назад.

`robot.up(): boolean[, string]`


Аналогично `robot.forward()`

, но двигает робота на один блок вверх.

`robot.down(): boolean[, string]`


Аналогично `robot.forward()`

, но двигает робота на один блок вниз.

`robot.turnLeft()`


Поворачивает робота на 90° влево.

`robot.turnRight()`


Поворачивает робота на 90° вправо.

`robot.turnAround()`


Поворачивает робота на 180°.