Added documentation for various language features and in-game functions. Added example scripts
This commit is contained in:
302
docs/builtins.md
Normal file
302
docs/builtins.md
Normal file
@@ -0,0 +1,302 @@
|
||||
# Built-in Functions
|
||||
|
||||
<!--toc:start-->
|
||||
|
||||
- [Built-in Functions](#built-in-functions)
|
||||
- [System Functions](#system-functions)
|
||||
- [`yield()`](#yield)
|
||||
- [`sleep(ticks)`](#sleepticks)
|
||||
- [`hash(prefabName)`](#hashprefabname)
|
||||
- [Device I/O Functions](#device-io-functions)
|
||||
- [Reading from Devices](#reading-from-devices)
|
||||
- [Load from device](#load-from-device)
|
||||
- [Load From Device Batched](#load-from-device-batched)
|
||||
- [Load From Device Batched Named](#load-from-device-batched-named)
|
||||
- [Load Slot](#load-slot)
|
||||
- [Load Reagent](#load-reagent)
|
||||
- [Writing to Devices](#writing-to-devices)
|
||||
- [Set On Device](#set-on-device)
|
||||
- [Set On Device Batched](#set-on-device-batched)
|
||||
- [Set On Device Batched Named](#set-on-device-batched-named)
|
||||
- [Set Slot](#set-slot)
|
||||
- [Math Functions](#math-functions)
|
||||
- [Trigonometric Functions](#trigonometric-functions)
|
||||
- [Trig Example](#trig-example)
|
||||
- [Rounding Functions](#rounding-functions)
|
||||
- [Rounding Example](#rounding-example)
|
||||
- [Other Math Functions](#other-math-functions)
|
||||
- [Math Example](#math-example)
|
||||
- [See Also](#see-also)
|
||||
<!--toc:end-->
|
||||
|
||||
Slang provides built-in functions for device I/O and mathematical operations.
|
||||
These map directly to IC10 instructions.
|
||||
|
||||
## System Functions
|
||||
|
||||
### `yield()`
|
||||
|
||||
Pauses execution for exactly one game tick.
|
||||
|
||||
```rust
|
||||
yield();
|
||||
```
|
||||
|
||||
**IC10:** `yield`
|
||||
|
||||
---
|
||||
|
||||
### `sleep(ticks)`
|
||||
|
||||
Pauses execution for the specified number of ticks.
|
||||
|
||||
```rust
|
||||
sleep(10); // Sleep for 10 ticks
|
||||
```
|
||||
|
||||
**IC10:** `sleep ticks`
|
||||
|
||||
---
|
||||
|
||||
### `hash(prefabName)`
|
||||
|
||||
Computes the in-game hash for a prefab name. The hash is computed at compile
|
||||
time and no runtime code is generated.
|
||||
|
||||
```rust
|
||||
const AC_HASH = hash("StructureAirConditioner");
|
||||
```
|
||||
|
||||
**Note:** This is different from IC10's `hash` instruction, which computes the
|
||||
hash at runtime.
|
||||
|
||||
```rust
|
||||
setBatched(AC_HASH, "On", 0);
|
||||
```
|
||||
|
||||
**IC10:** `sb -2087593337 On 0` (no hash computation at runtime)
|
||||
|
||||
---
|
||||
|
||||
## Device I/O Functions
|
||||
|
||||
### Reading from Devices
|
||||
|
||||
#### Load from device
|
||||
|
||||
`load(device, property)` / `l(device, property)`
|
||||
|
||||
Loads a property value from a device:
|
||||
|
||||
```rust
|
||||
let temp = load(sensor, "Temperature");
|
||||
let temp = l(sensor, "Temperature");
|
||||
|
||||
// Preferred: use dot notation
|
||||
let temp = sensor.Temperature;
|
||||
```
|
||||
|
||||
**IC10:** `l r? d? var`
|
||||
|
||||
---
|
||||
|
||||
#### Load From Device Batched
|
||||
|
||||
`loadBatched(deviceHash, property, batchMode)` / `lb(...)`
|
||||
|
||||
Loads a property from all devices matching a hash, aggregated by batch mode:
|
||||
|
||||
```rust
|
||||
const SENSOR = hash("StructureGasSensor");
|
||||
let avgTemp = loadBatched(SENSOR, "Temperature", "Average");
|
||||
let maxTemp = lb(SENSOR, "Temperature", "Maximum");
|
||||
```
|
||||
|
||||
**Batch Modes:** `"Average"`, `"Sum"`, `"Minimum"`, `"Maximum"`
|
||||
|
||||
**IC10:** `lb r? deviceHash logicType batchMode`
|
||||
|
||||
---
|
||||
|
||||
#### Load From Device Batched Named
|
||||
|
||||
`loadBatchedNamed(deviceHash, nameHash, property, batchMode)` / `lbn(...)`
|
||||
|
||||
Loads a property from devices matching both device hash and name hash:
|
||||
|
||||
```rust
|
||||
const SENSOR_HASH = hash("StructureGasSensor");
|
||||
const SENSOR_NAME_HASH = hash("Outdoor Gas Sensor");
|
||||
let avgTemp = loadBatchedNamed(SENSOR_HASH, SENSOR_NAME_HASH, "Temperature", "Average");
|
||||
let maxTemp = lbn(SENSOR_HASH, SENSOR_NAME_HASH, "Temperature", "Maximum");
|
||||
```
|
||||
|
||||
**IC10:** `lbn r? deviceHash nameHash logicType batchMode`
|
||||
|
||||
**Note:** This function is useful when a script interfaces with a lot of
|
||||
devices, as it allows for arbitrary device access without limited to the 6 `dx` pins.
|
||||
|
||||
---
|
||||
|
||||
#### Load Slot
|
||||
|
||||
`loadSlot(device, slotIndex, property)` / `ls(...)`
|
||||
|
||||
Loads a slot property from a device:
|
||||
|
||||
```rust
|
||||
let occupied = loadSlot(sorter, 0, "Occupied");
|
||||
let occupied = ls(sorter, 0, "Occupied");
|
||||
```
|
||||
|
||||
**IC10:** `ls r? d? slotIndex logicSlotType`
|
||||
|
||||
---
|
||||
|
||||
#### Load Reagent
|
||||
|
||||
`loadReagent(device, reagentMode, reagentHash)` / `lr(...)`
|
||||
|
||||
Loads reagent information from a device:
|
||||
|
||||
```rust
|
||||
let amount = loadReagent(furnace, "Contents", reagentHash);
|
||||
let amount = lr(furnace, "Contents", reagentHash);
|
||||
```
|
||||
|
||||
**IC10:** `lr r? d? reagentMode reagentHash`
|
||||
|
||||
---
|
||||
|
||||
### Writing to Devices
|
||||
|
||||
#### Set On Device
|
||||
|
||||
`set(device, property, value)` / `s(...)`
|
||||
|
||||
Sets a property on a device:
|
||||
|
||||
```rust
|
||||
set(valve, "On", true);
|
||||
s(valve, "On", true);
|
||||
|
||||
// Preferred: use dot notation
|
||||
valve.On = true;
|
||||
```
|
||||
|
||||
**IC10:** `s d? logicType r?`
|
||||
|
||||
---
|
||||
|
||||
#### Set On Device Batched
|
||||
|
||||
`setBatched(deviceHash, property, value)` / `sb(...)`
|
||||
|
||||
Sets a property on all devices matching a hash:
|
||||
|
||||
```rust
|
||||
const LIGHT_HASH = hash("StructureWallLight");
|
||||
setBatched(LIGHT_HASH, "On", true);
|
||||
sb(LIGHT_HASH, "On", true);
|
||||
```
|
||||
|
||||
**IC10:** `sb deviceHash logicType r?`
|
||||
|
||||
**Note:** This function is useful when a script interfaces with a lot of devices,
|
||||
as it allows for arbitrary device access without limited to the 6 `dx` pins.
|
||||
|
||||
---
|
||||
|
||||
#### Set On Device Batched Named
|
||||
|
||||
`setBatchedNamed(deviceHash, nameHash, property, value)` / `sbn(...)`
|
||||
|
||||
Sets a property on devices matching both device hash and name hash:
|
||||
|
||||
```rust
|
||||
const SENSOR_HASH = hash("StructureGasSensor");
|
||||
const SENSOR_NAME_HASH = hash("Outdoor Gas Sensor");
|
||||
setBatchedNamed(SENSOR_HASH, SENSOR_NAME_HASH, "On", true);
|
||||
sbn(SENSOR_HASH, SENSOR_NAME_HASH, "On", true);
|
||||
```
|
||||
|
||||
**IC10:** `sbn deviceHash nameHash logicType r?`
|
||||
|
||||
---
|
||||
|
||||
#### Set Slot
|
||||
|
||||
`setSlot(device, slotIndex, property, value)` / `ss(...)`
|
||||
|
||||
Sets a slot property on a device:
|
||||
|
||||
```rust
|
||||
setSlot(sorter, 0, "Open", true);
|
||||
ss(sorter, 0, "Open", true);
|
||||
```
|
||||
|
||||
**IC10:** `ss d? slotIndex logicSlotType r?`
|
||||
|
||||
---
|
||||
|
||||
## Math Functions
|
||||
|
||||
All math functions accept numbers, variables, or expressions as arguments.
|
||||
|
||||
### Trigonometric Functions
|
||||
|
||||
| Function | Description | IC10 |
|
||||
| ------------- | ---------------------------- | ------- |
|
||||
| `sin(x)` | Sine of angle in radians | `sin` |
|
||||
| `cos(x)` | Cosine of angle in radians | `cos` |
|
||||
| `tan(x)` | Tangent of angle in radians | `tan` |
|
||||
| `asin(x)` | Arc sine, returns radians | `asin` |
|
||||
| `acos(x)` | Arc cosine, returns radians | `acos` |
|
||||
| `atan(x)` | Arc tangent, returns radians | `atan` |
|
||||
| `atan2(y, x)` | Two-argument arc tangent | `atan2` |
|
||||
|
||||
#### Trig Example
|
||||
|
||||
```rust
|
||||
let angle = atan2(y, x);
|
||||
let sineValue = sin(angle);
|
||||
```
|
||||
|
||||
### Rounding Functions
|
||||
|
||||
| Function | Description | IC10 |
|
||||
| ---------- | ----------------------------- | ------- |
|
||||
| `ceil(x)` | Round up to nearest integer | `ceil` |
|
||||
| `floor(x)` | Round down to nearest integer | `floor` |
|
||||
| `trunc(x)` | Remove decimal portion | `trunc` |
|
||||
| `abs(x)` | Absolute value | `abs` |
|
||||
|
||||
#### Rounding Example
|
||||
|
||||
```rust
|
||||
let rounded = floor(3.7); // 3
|
||||
let positive = abs(-5); // 5
|
||||
```
|
||||
|
||||
### Other Math Functions
|
||||
|
||||
| Function | Description | IC10 |
|
||||
| ----------- | ----------------------------- | ------ |
|
||||
| `sqrt(x)` | Square root | `sqrt` |
|
||||
| `log(x)` | Natural logarithm | `log` |
|
||||
| `max(a, b)` | Maximum of two values | `max` |
|
||||
| `min(a, b)` | Minimum of two values | `min` |
|
||||
| `rand()` | Random number between 0 and 1 | `rand` |
|
||||
|
||||
#### Math Example
|
||||
|
||||
```rust
|
||||
let root = sqrt(16); // 4
|
||||
let bigger = max(a, b);
|
||||
let randomVal = rand();
|
||||
```
|
||||
|
||||
## See Also
|
||||
|
||||
- [Language Reference](language-reference.md) — Complete syntax guide
|
||||
- [Examples](examples.md) — Real-world code samples
|
||||
Reference in New Issue
Block a user