# Script Types

### Script Type Hierarchy

<details>

<summary><strong>LoopingScript</strong> - Simple</summary>

**Extends**: `SuspendableScript`\
**Base Class**: `BwuScript`\
**Complexity**: Simple

**What it offers**:

* Basic loop-based execution
* Optional `onInit()` method for initialization
* Direct `onTick()` implementation
* Full Kotlin coroutine support (`awaitTicks()`, `awaitUntil()`, `awaitIdle()`)
* No state management
* Minimal interface - cleanest API

**When to use**:

* Simple scripts without state management
* Straightforward logic that doesn't need complex state transitions
* When you prefer direct control over execution flow

</details>

<details>

<summary><strong>StateScript</strong> - Medium</summary>

**Extends**: `BaseStateScript<State>` → `SuspendableScript`\
**Base Class**: `BwuScript`\
**Complexity**: Medium

**What it offers**:

* Automatic state machine functionality
* Enum-based state management (no class instantiation required)
* State iteration with `StateIterator`
* Skip conditions for conditional state skipping
* Runtime skip condition updates
* Simple state switching with enum values
* Full Kotlin coroutine support

**When to use**:

* Complex scripts with multiple states
* When you want automatic state machine functionality
* Simple enum-based state management without class instantiation

</details>

<details>

<summary><strong>PermissiveScript</strong> - Advanced</summary>

**Extends**: `BaseStateScript<State>` → `SuspendableScript`\
**Base Class**: `BwuScript`\
**Complexity**: Advanced

**What it offers**:

* Manual state management with class instantiation
* Enum-based state instances using `PermissiveStateEnum`
* State iteration with `StateIterator`
* Skip conditions for conditional state skipping
* Runtime skip condition updates
* Explicit class instantiation from enum's `classz` property
* Backend permissive package integration
* Full Kotlin coroutine support

**When to use**:

* Scripts that need explicit class instantiation
* Manual control over state lifecycle
* Integration with backend permissive package
* When you need custom state classes extending `PermissiveDSL`

</details>

***

### Common Features

All script types provide:

* **Coroutine Support**: `awaitTicks()`, `awaitUntil()`, `awaitIdle()`
* **Debug Mode**: Constructor parameter for verbose logging
* **Error Handling**: Built-in error handling and logging
* **Initialization**: Various initialization methods (`onInit()`, `init()`)
* **Status Updates**: Built-in status reporting

***

### StateScript vs PermissiveScript: Common Access

Both `StateScript` and `PermissiveScript` extend `BaseStateScript` and share the following common functionality:

#### State Iterator Methods

```kotlin
// Get the current state iterator
protected fun getStateIterator(): StateIterator<State>?

// Move to the next state using the iterator
protected fun nextState(): State?

// Reset the state iterator to the first state
protected fun resetStateIterator()

// Set the current state using the iterator
protected fun setState(state: State)
```

#### Skip Conditions

```kotlin
// Override to set initial skip conditions
protected open fun getSkipConditions(): Map<State, () -> Boolean> = emptyMap()

// Update skip conditions at runtime
protected fun updateSkipConditions(newSkipConditions: Map<State, () -> Boolean>)
```

#### State Management

```kotlin
// Get all available states
protected val actualStates: List<State>

// Create the state iterator
protected fun createStateIterator(): StateIterator<State>
```

#### Initialization

```kotlin
// Abstract method to initialize states - implemented by subclasses
protected abstract fun initializeStates()
```

***

### Key Differences

| Feature                 | LoopingScript       | StateScript       | PermissiveScript           |
| ----------------------- | ------------------- | ----------------- | -------------------------- |
| **State Management**    | None                | Enum values only  | Enum + class instantiation |
| **Base Class**          | `SuspendableScript` | `BaseStateScript` | `BaseStateScript`          |
| **State Interface**     | N/A                 | `StateEnum`       | `PermissiveStateEnum`      |
| **Class Instantiation** | N/A                 | No                | Yes (`classz` property)    |
| **Complexity**          | Simple              | Medium            | Advanced                   |
| **Use Case**            | Basic scripts       | State machines    | Manual state control       |

***

### Constructor Patterns

```kotlin
// LoopingScript
class MyScript : LoopingScript()

// StateScript
class MyScript : StateScript<MyState>(debug = true)

// PermissiveScript  
class MyScript : PermissiveScript<MyState>(debug = true)
```

***

### Quick Decision Guide

**Choose LoopingScript when**:

* You have simple, linear logic
* No state management needed
* Want the cleanest possible API

**Choose StateScript when**:

* You need state management but not class instantiation
* Want automatic state machine functionality
* Working with simple enum-based states

**Choose PermissiveScript when**:

* You need explicit class instantiation
* Want manual control over state lifecycle
* Integrating with backend permissive package
* Need custom state classes extending `PermissiveDSL`


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://kxapi.gitbook.io/kxapi/scripting/script-types.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.