BauSystem2.0/SCRIPT.md

# SteamWar.de - Script System

---
<!-- TOC -->
* [SteamWar.de - Script System](#steamwarde---script-system)
  * [Einleitung](#einleitung)
* [Basis-Apis](#basis-apis)
* [SteamWar.de-Api](#steamwarde-api)
    * [global](#global)
    * [player](#player)
    * [region](#region)
      * [tnt](#tnt)
      * [trace](#trace)
  * [server](#server)
      * [tps](#tps)
* [SteamWar.de-Global-Api](#steamwarde-global-api)
  * [Hotkeys](#hotkeys)
  * [Event Type](#event-type)
    * [BlockEvent](#blockevent)
    * [InteractEvent](#interactevent)
    * [Position](#position)
* [Beispiele](#beispiele)
  * [Hello, World!](#hello-world)
      * [Code](#code)
      * [Ausgabe](#ausgabe)
  * [BauGUI on FF](#baugui-on-ff)
      * [Code](#code-1)
  * [SL Command](#sl-command)
      * [Code](#code-2)
  * [Paste Hotkey](#paste-hotkey)
      * [Code](#code-3)
<!-- TOC -->


## Einleitung
Das Script System auf SteamWar.de basiert auf [Lua](https://www.lua.org/docs.html). Der Code wird einfach in ein Minecraft Buch geschrieben und kann mit einem Links-Klick ausgeführt werden.

# Basis-Apis
Es werden folgende Standard-Apis zur Verfügung gestellt:
- [`math`](https://www.lua.org/manual/5.4/manual.html#6.7)
- [`string`](https://www.lua.org/manual/5.4/manual.html#6.4)
- [`table`](https://www.lua.org/manual/5.4/manual.html#6.6)
- `bit32`

# SteamWar.de-Api
In den Scripten gibt es dazu noch folgende globale Variablen:
- [`player`](#player)
- [`region`](#region)
- [`server`](#server)

### global
Die `global`-Api stellt Funktionen zur Verfügung, QOL sind.
Es gibt folgende Funktionen:

| Name      | Signature                        | Beschreibung                                                                                       |
|-----------|----------------------------------|----------------------------------------------------------------------------------------------------|
| `print`   | print(String...)                 | @see message(String...)                                                                            |
| `input`   | input(String, Function\<String>) | Fragt den User nach einer Eingabe mit der Nachricht und called die zugehörige Funktion nach dieser |
| `timeout` | timeout(Number, Function\<Void>) | Wartet die angegebene Anzahl an Ticks und führt danach die zugehörige Funktion aus                 |
| `pos`     | pos(Number, Number, Number)      | Erstellt aus drei Zahlen eine Position-Table, sind unter den Namen `x`, `y` und `z` abgespeichert  |
| `exec`    | exec(String...)                  | Führt den angegebenen Befehl als Spieler aus                                                       |

### player
Die `player`-Api stellt Funktionen zur Verfügung, die den Spieler betreffen.
Es gibt folgende Funktionen:

| Name          | Signature                      | Beschreibung                                                |
|---------------|--------------------------------|-------------------------------------------------------------|
| `name`        | name(): String                 | Gibt den `displayName` des Spielers zurück                  |
| `message`     | message(String...)             | Sendet den Text in den Chat des Spielers                    |
| `actionbar`   | actionbar(String...)           | Sendet den Text in die ActionBar des Spielers               |
| `x`           | x(Number), x(): Number         | Setzt oder gibt die X-Koordinate des Spielers               |
| `y`           | y(Number), y(): Number         | Setzt oder gibt die Y-Koordinate des Spielers               |
| `z`           | z(Number), z(): Number         | Setzt oder gibt die Z-Koordinate des Spielers               |
| `yaw`         | yaw(Number), yaw(): Number     | Setzt oder gibt den Yaw des Spielers                        |
| `pitch`       | pitch(Number), pitch(): Number | Setzt oder gibt den Pitch des Spielers                      |
| `sneaking`    | sneaking(): Boolean            | Wahr, wenn der Spieler am Sneaken ist                       |
| `sprinting`   | sprinting(): Boolean           | Wahr, wenn der Spieler am Sprinten ist                      |
| `slot`        | slot(Number), slot(): Number   | Setzt oder gibt den Slot des gehaltenden Items des Spielers |
| `item`        | item(): String                 | Gibt den Item Type der Main-Hand zurück                     |
| `offHandItem` | offHandItem(): String          | Gibt den Item Type der Off-Hand zurück                      |


### region
Die `region`-Api stellt Funktion zur Verfügung, die die Region des Spielers betreffen.
Es gibt folgende Funktionen: 

| Name      | Signature          | Beschreibung                                                                                               |
|-----------|--------------------|------------------------------------------------------------------------------------------------------------|
| `name`    | name(): String     | Gibt den Namen der Region zurück                                                                           | 
| `type`    | type(): String     | Gibt den Namen des Typen der Region zurück                                                                 |
| `fire`    | fire(): Boolean    | Gibt den Fire-Mode der Region zurück                                                                       |
| `freeze`  | freeze(): Boolean  | Gibt den Freeze-Mode der Region zurück                                                                     |
| `protect` | protect(): Boolean | Gibt den Protect-Mode der Region zurück                                                                    |
| `loader`  | pvp(): String      | Gibt den Status des Loaders des Spielers zurück, die werte sind: `OFF`, `SETUP`, `RUNNING`, `PAUSE`, `END` |


Es gibt folgende Variablen:

| Name    | Beschreibung    |
|---------|-----------------|
| `tnt`   | [tnt](#tnt)     |
| `trace` | [trace](#trace) |

#### tnt
Die `tnt`-Api stellt Funktionen zur Verfügung, die den TNT-Modus in der Region des Spielers betreffen.
Es gibt folgende Funktionen:

| Name      | Signature          | Beschreibung                                                                        |
|-----------|--------------------|-------------------------------------------------------------------------------------|
| `mode`    | mode(): String     | Gibt den Aktuellen TNT-Modus zurück, die werte sind: `ALLOW`, `DENY` oder `ONLY_TB` |
| `enabled` | enabled(): Boolean | Gibt zurück, ob der TNT-Modus in der Region des Spielers aktiviert ist oder nicht   |
| `onlyTb`  | onlyTb(): Boolean  | Gibt zurück, ob der TNT-Modus auf Only-Tb ist                                       |


#### trace
Die `trace`-Api stellt Funktionen zur Verfügung, die den Status des Tracers der Region betreffen.
Es gibt folgende Funktionen:

| Name     | Signature         | Beschreibung                                                                   |
|----------|-------------------|--------------------------------------------------------------------------------|
| `active` | active(): Boolean | Gibt zurück, ob der Tracer in der Region des Spielers aktiviert ist oder nicht |
| `auto`   | auto(): Boolean   | Gibt zurück, ob der Tracer in der Region ein Auto-Tracer ist.                  |
| `status` | status(): String  | Gibt den Status des Tracers zurück                                             |
| `time`   | time(): String    | Gibt die Zeit des Tracers zurück                                               |

## server
Die `server`-Api stellt Funktionen zur Verfügung, die den Server betreffen.
Es gibt folgende Funktionen:

| Name         | Signature               | Beschreibung                                       |
|--------------|-------------------------|----------------------------------------------------|
| `time`       | time(): String          | Gibt die aktuelle Zeit im format `HH:mm:ss` zurück |
| `ticks`      | ticks(): Number         | Gibt die Ticks seit start des Server zurück        |
| `getBlockAt` | getBlockAt(Pos): String | Gibt das Material an der Position zurück           |
| `setBlockAt` | setBlockAt(Pos, String) | Setzt das Material an der angegebenen Stelle       |

Es gibt folgende Variablen:

| Name  | Beschreibung |
|-------|--------------|
| `tps` | [tps](#tps)  |

#### tps
Die `tps`-Api stellt Funktionen zur Verfügung, die die TPS des Servers betreffen.
Es gibt folgende Funktionen:

| Name         | Signature            | Beschreibung                                                      |
|--------------|----------------------|-------------------------------------------------------------------|
| `current`    | current(): Number    | Gibt die aktuelle TPS zurück                                      |
| `oneSecond`  | oneSecond(): Number  | Gibt die durchschnittliche TPS über die letzte Sekunde zurück     |
| `tenSecond`  | tenSecond(): Number  | Gibt die durchschnittliche TPS über die letzte 10 Sekunden zurück |
| `oneMinute`  | oneMinute(): Number  | Gibt die durchschnittliche TPS über die letzte Minute zurück      |
| `fiveMinute` | fiveMinute(): Number | Gibt die durchschnittliche TPS über die letzte 5 Minuten zurück   |
| `tenMinute`  | tenMinute(): Number  | Gibt die durchschnittliche TPS über die letzte 10 Minuten zurück  |
| `limit`      | limit(): Number      | Gibt den TPS-Limit zurück                                         |

# SteamWar.de-Global-Api
Mit `/script` kann man Script-Bücher global abspeichern. Diese haben dann zugrif auf die `global`-Api.
Die `global`-Api stellt Funktionen zur Verfügung um auf Events, Commands und Hotkeys mit einem Script zu reagieren.

Es gibt folgende Funktionen:

| Name      | Signature                         | Beschreibung                                                                |
|-----------|-----------------------------------|-----------------------------------------------------------------------------|
| `event`   | event(EventType, Function(Any))   | Registriere einen Event Handler                                             |
| `command` | command(String, Function(Args))   | Registriere einen Command                                                   |
| `hotkey`  | hotkey(String, Function(Boolean)) | Registriere einen Hotkey, the function gets a boolean if the key is pressed |

Es gibt folgende Variablen:

| Name     | Beschreibung                     |
|----------|----------------------------------|
| `events` | Siehe: [Event Type](#event-type) |

## Hotkeys

Hotkeys werden im folgenden Format angegeben: `MODIFIER+KEY`. Es gibt folgende Modifier:
- `ctrl`
- `shift`
- `alt`
- `meta`

Es können auch mehrere Modifier angegeben werden, z.B. `ctrl+shift+alt+c`. Die Reihenfolge der Modifier und des Keys ist egal.

## Event Type
Einige Events sind auch cancelbar, dazu muss die Funktion `setCanceled()` aufgerufen werden.
Es gibt folgende Event-Typen:

| Name                | Wenn                                                | Parameter                       | Cancelbar |
|---------------------|-----------------------------------------------------|---------------------------------|-----------|
| `FF`                | Beim Doppelten Drücken der Swap-Hands taste         | NIL                             | false     |
| `PlaceBlock`        | Beim Platzieren von Blöcken                         | [BlockEvent](#blockevent)       | true      |
| `BreakBlock`        | Beim Zerstören von Blöcken                          | [BlockEvent](#blockevent)       | true      |
| `RightClick`        | Beim Rechts klicken                                 | [InteractEvent](#interactevent) | true      |
| `LeftClick`         | Beim Links Klicken                                  | [InteractEvent](#interactevent) | true      |
| `TNTSpawn`          | Wenn ein TNT in der aktuellen Region spawnt         | NIL                             | false     |
| `TNTExplode`        | Wenn ein TNT in der aktuellen Region explodiert     | [Position](#position)           | true      |
| `TNTExplodeInBuild` | Wenn ein TNT in der aktuellen Bau Region explodiert | [Position](#position)           | true      |
| `SelfJoin`          | Wenn man selbst den Server betritt                  | NIL                             | false     |
| `SelfLeave`         | Wenn man den Server verlässt                        | NIL                             | false     |
| `DropItem`          | Wenn man ein item Droppt                            | (type: Material)                | true      |
| `EntityDeath`       | Wenn ein Entity Stirbt                              | (type: Entity Type)             | false     |

### BlockEvent
Das übergebene Objekt an den Handler hat folgende Variablen:

| Name   | Beschreibung                |
|--------|-----------------------------|
| `x`    | Die X-Koordinate des Blocks |
| `y`    | Die Y-Koordinate des Blocks |
| `z`    | Die Z-Koordinate des Blocks |
| `type` | Das Material des Blocks     |

### InteractEvent
Das übergebene Objekt an den Handler hat folgende Variablen:

| Name       | Beschreibung                                                                                                                  |
|------------|-------------------------------------------------------------------------------------------------------------------------------|
| `action`   | Die Action die ausgeführt wurde, Mögliche Werte: `RIGHT_CLICK_BLOCK`, `RIGHT_CLICK_AIR`, `LEFT_CLICK_BLOCK`, `LEFT_CLICK_AIR` |
| `hand`     | Die Hand die zum ausführen genutzt wird, Mögliche Werte: `HAND`, `OFF_HAND`                                                   |
| `block`    | Der Typ des Items mit dem geklickt wurde                                                                                      |
| `hasBlock` | Wahr, wenn auf einen Block geklickt wurde                                                                                     |

Wenn `hasBlock` wahr ist, gibt es folgende Variablen:

| Name        | Beschreibung                            |
|-------------|-----------------------------------------|
| `blockX`    | Die X-Koordinate des Blocks             |
| `blockY`    | Die Y-Koordinate des Blocks             |
| `blockZ`    | Die Z-Koordinate des Blocks             |
| `blockFace` | Die Seite des Blocks die geklickt wurde |


### Position
Die Position ist ein Objekt mit folgenden Variablen:

| Name | Beschreibung     |
|------|------------------|
| `x`  | Die X-Koordinate |
| `y`  | Die Y-Koordinate |
| `z`  | Die Z-Koordinate |


# Beispiele

## Hello, World!
Ein einfaches Hello, World!-Script.

#### Code
```lua
print("Hello, World!")
```

#### Ausgabe
```
Hello, World!
```

## BauGUI on FF
Das default Script für das Öffnen des BauGUIs

#### Code
```lua
function handler(event) 
  exec("gui")
end

event(events.FF, handler)
```

## SL Command
Ein einfacher Command Redefiner.

#### Code
```lua
function handler(args)
  exec("stoplag")
end

command("sl", handler)
```

## Paste Hotkey
Ein Hotkey zum pasten des Clipboard-Inhalts.

#### Code
```lua
function handler(pressed)
  if pressed then
    exec("/paste -o")
  end
end

hotkey("ctrl+v", handler)
```