> **Примечание.** Этот документ описывает концептуальный API событий. Актуальная реализация скриптов использует класс-ориентированный подход на базе Scope-классов.  
> Подробнее: [`docs/control-scripts-guide.md`](./control-scripts-guide.md)

---

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

### Основные положения. INIT
- Файл скрипта должен содержать как минимум одну функцию, название которой должно формироваться по следующему принципу: `script_[filename]_init`, именно эта функция и будет точкой входа скрипта. **Её основная задача - зарегистрировать всё, что нужно, подписаться на ивенты и передать управление дальше**
- Основная фукция должна принимать 2 параметра: `$server` - ссылка на само приложение сервера, `$params` - произвольный набор параметров.
- Система ожидает, что функция вернёт результат выполнения.

#### Пример
```php
	<?php
	function script_example_init($server, $params) {
		// something...

		return true; // result of executing
	}
	```

### Основные положения. INVOKE
- Скрипт может быть вызван принудительно через rest api, в таком случае будет вызвана определённая функция из файла скрипта. 
- Функция должна называться по схожему принципу `script_[filename]_invoke`
- Эта функция принимает всё те же 2 параметра: `$server` - ссылка на само приложение сервера, `$params` - произвольный набор параметров. Параметры должны быть переданы при вызове через RESP API
- Эта функция должна вернуть ассоциативный массив с минимум одним ключём `status` выполнения скрипта (`true|false`)
- Если функция хочет что-то вернуть в ответ на запрос REST API, она должна в `return` включить поле `response`

#### Пример
```php
	<?php
	function script_example_invoke($server, $params) {
		// something...

		return [
			"status" => true, // result of executing
			"response" => [
				// ...
			]
		]; 
	}
	```

### Основные положения. EVENTS
- Скрипт может работать с ивентами. Он может подписаться на ивент, или стригерить существующий ивент, или зарегистрировать свой, на который потом смогут подписаться другие скрипты.
- Регистрацию ивентов нужно проводить при инициализации скрипта.
- Подписываться на ивенты нужно при инициализации скрипта.
- Запуск обработчика ивента не произойдёт в момент вызова тригера ивента. Вместо этого нужно передать колбек функцию тригера, которая будет вызвана как только ивент станет доступным в системе, ведь на момент тригера он ещё может быть не зарегистрированным. 

#### Пример регистрации ивента

```php
	<?php
	function script_example_init($server, $params) {
		$server -> events -> add("name_of_event");
		return true; 
	}
	```

#### Пример тригера ивента

```php
	<?php
	function script_example_invoke($server, $params) {
		$server -> events -> trigger("name_of_event", $data);
		return true; 
	}
	```

#### Пример подписки обработчика события

```php
	<?php
	function script_example_init($server, $params) {
		$server -> events -> new_handler("name_of_event", function($event) {
			var_dump($event -> data);
		});
		return true; 
	}
	```