# HEX..END

Sanny Builder поддерживает запись произвольных значений в выходной файл без какой-либо обработки и проверки.

{% hint style="warning" %}
Используйте эту возможность только в том случае, если вы знаете, что делаете. Любые ошибки могут повредить файл и его невозможно будет прочитать в игре или в скриптовом редакторе.
{% endhint %}

## Синтаксис <a href="#syntax" id="syntax"></a>

`hex`\
`<последовательность байтов>`\
`end`

`последовательность байтов` - одна или несколько пар цифр в [шестнадцатиричном формате](https://docs.sannybuilder.com/ru/data-types#hex-numbers). Каждая пара представляет собой один байт, который будет записан в файл. Все пробелы игнорируются. Если число символов в последовательности нечетное, к последнему значению слева дописывается `0`:

```pascal
hex
    04 00 02 0800 04 1
end
```

Эта последовательность является бинарным представлением команды `0004: $2 = 1`. Игра сможет прочитать его и установит значение переменной `$2` в `1`.

В конструкции `HEX..END` также можно использовать [строковые литералы](https://docs.sannybuilder.com/ru/data-types#strokovye-literaly), [метки](https://docs.sannybuilder.com/ru/data-types#metki), [глобальные переменные](https://docs.sannybuilder.com/ru/variables#globalnye-peremennye), [имена моделей](https://docs.sannybuilder.com/ru/data-types#imena-modelei). Они компилируются без предшествующего байта, указывающего на тип данных.

```pascal
:get_offset
hex
    04 00 02 $PLAYER_CHAR 01 @get_offset
end
```

Это эквивалентно команде  `0004: $PLAYER_CHAR = @get_offset`

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

```pascal
hex
    "This is a string"
end
```

## Экранированные последовательности <a href="#escape-sequences" id="escape-sequences"></a>

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

| Имя                          | Последовательность | Вывод в файл |
| ---------------------------- | ------------------ | ------------ |
| пустой символ                | \0                 | 00           |
| возврат на один шаг          | \b                 | 08           |
| табуляция                    | \t                 | 09           |
| перевод каретки              | \n                 | 0A           |
| возврат каретки              | \r                 | 0D           |
| запись произвольного байта   | \x`nn`             | `nn`         |
| запись произвольного символа | \\`символ`         | `символ`     |

```
hex
    "\0\b\t\n\r\xDD"
end
```

В файл будет записана последовательность байтов `00 08 09 0A 0D DD`.

{% hint style="info" %}
В настоящее время несколько подряд идущих пробелов в строке конвертируются в один пробел. Например, строка `"This    is  a     string"` будет сконвертирована в `"This is a string"`. Используйте символ `\` чтобы добавить дополнительные пробелы в строку: `"This \ \ \ is \ a \ \ \ \ string"`.
{% endhint %}

## Ввод больших чисел <a href="#entering-large-numbers" id="entering-large-numbers"></a>

Для удобства записи больших чисел поставьте в начале знак `&`. Число после знака `&` может быть как положительным, так и отрицательным, в десятичном или шестнадцатиричном форматах.

```pascal
hex
    &1000 &-0xA33500 
end
```

В файл будет записана последовательность байтов `E8 03 00 CB 5C FF`.

## Повторение байтов <a href="#byte-repetition" id="byte-repetition"></a>

В случае, если один байт повторяется много раз, например, для создания пустого буфера, заполненного нулями, кол-во повторений можно задать, добавив `(n)` после байта, где `n` - это целое положительное число:

```pascal
hex
 00(10
end
```

Это будет эквивалентно:

```pascal
hex
  00 00 00 00 00 00 00 00 00 00
end
```

Повторения байтов можно использовать несколько раз в одном блоке, так же можно задать кол-во при помощи константы:

```pascal
const n = 25

hex
00(n) 01(3) 02(4)
end
```

## Добавление бинарных файлов <a href="#including-binary-files" id="including-binary-files"></a>

`hex..end` позволяет использовать директиву `{$INCLUDE}` для вставки содержимого бинарного файла в тело скрипта. Используется следующий синтаксис:

```
hex 
 {$INCLUDE <path>}
end
```

Путь к файлу определяется по правилам [директивы](https://docs.sannybuilder.com/ru/directives#usdinclude) `{$INCLUDE}`.