> For the complete documentation index, see [llms.txt](https://halekio.gitbook.io/state-controller-block/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://halekio.gitbook.io/state-controller-block/1_main_screen.md).
# Main Screen Configuration
***
***
The Main Screen is where you define how the State Controller Block (SCB) behaves.
It allows you to:
* Select the target block (by face and distance)
* Set timers for states
* Enable or disable states
* Duplicate and reorder state sequences
* Set an "off" state
* Access the Conditions configuration screen
***
## 1. Face Selection
At the top of the screen, colored squares buttons represent the six faces of the SCB.
The currently selected face is highlighted with a thick white border.\
When the selected face targets a block that has available states, these will appear in the mid section.
## 2. Target Selection
The Distance field below each face color represents the distance from that colored face (in number of blocks) where the target is located.
* Distance `0` means no target in that direction
* Distance `1` means the block immediately adjacent to the SCB in that face's direction.
* Distance `5` means the 5th block in the direction pointed to be that face color.
Distance value must be between `0` and `9`.\
Once a target is determined for the selected face, the mid section of the configuration screen will display all available states for that target block.
⚠️ **Important:** You must press "Apply" after changing the distance for the targetting to take effect.
***
## 3. State List
The mid section displays all available states for the targeted block for the selected SCB face.\
Each row represents one possible state.
### 3.1 Block Name
This is the name of the targeted block.\
It will appear even it that block does not have any available states.
### 3.2 List of Available States
These are the different states that the target block can be set to.
### 3.3 Timer Input
Here you set the amount of time you wish the target block to stay in the given state.\
By default, the SCB will swith to the next state with a timer set once a state's timer expires.\
The sequence will be from top to bottom and by default it will loop infinitely.\
The states for which no timers was set (value `0`) will be skipped.
⚠️ **Important:** You must press "Apply" after changing the timers before swithing face.\
ℹ️ The default looping behavior can be overriden with custom looping and condition. (See [Conditions](https://github.com/Halekio/TimerBlock/blob/main/docs/Conditions_Screen.md))
### 3.4 Time Unit Selectors
Here you can select the unit of time used in the Timer Inputs.\
Are we timing in Seconds (default) or Minutes ?\
Either way the Timer Inputs allows for decimal values.\
Ex: `0.001` Secs means 1 Millisecond\
Ex: `0.25` Mins means 15 Seconds
⚠️ Although you can enter very small Timer values, performance might be impacted if you set 1000s of SCB to check/set states every tick.\
ℹ️ It is recommanded to use `0.1` (3 ticks) Secs for most 'fast response times' and `0.01` Secs when response time is 'critical' (every tick).
### 3.5 "Off" Marker
Marks the state as the state to apply why the looping stops.\
The looping can stop in multiple ways:
* Number of iterations is completed (\*)
* The conditions return False (\*)
* The SCB's state if changed to "Off"
(\*) See [Conditions](https://github.com/Halekio/TimerBlock/blob/main/docs/Conditions_Screen.md)
ℹ️ If **NO** State is Marked "Off", the Target block will freeze on the last active state and continue from there when looping resumes.\
ℹ️ If the Target block is set to its Marked "Off" State when looping stops, it will restart from the top when it resumes.
### 3.6 Re-Order Buttons
These button help you order the States' sequence for the desired effect.\
Pressing the button will move the corresponding line Up by one, effectively switching place with the line above it.
### 3.7 "DUP" Buttons
These buttons enable you to "Duplicate" a State in the list. This can be useful for:
* Having the same state multiple times in the looping sequence with different Timers
* Ex: Morse Code S.O.S from a Lantern
* Marking an "Off" State that you also want to be part of the looping sequence
* Ex: Lantern flashing ON and OFF while a monster is close by, but needs finish in the OFF State when the danger is gone
⚠️ Currently the maximum number of Lines in the State List is set to `16`.
### 3.8 Active Marker
Unchecking this marker will turn OFF the Looping Sequence for this Target Block. ℹ️ It is useful for debugging behaviors when multiple SCB interact together.
***
## 4. Timing (Minutes / Seconds)
Each state has a timing configuration.
You define how long the controller remains in that state before moving to the next active state.
Timing supports:
* Minutes
* Seconds
If a state is active and has a duration of `0`, it will be skipped unless explicitly configured otherwise.
***
## 5. Off Toggle
The **Off** option determines what happens when the controller is not in that state.
If enabled, the controller ensures that state is actively disabled when not selected.
This is useful for blocks that require explicit reset behavior.
***
## 6. Active Checkbox
Only states marked as **Active** will be included in the cycle.
If unchecked:
* The state will not run
* It will be skipped during iteration
You can quickly test variations by toggling states on or off.
***
## 7. DUP Button
The **DUP** button duplicates the current state entry.
Useful for:
* Creating multi-stage sequences
* Repeating a state with different timing
* Building patterns
Duplicated entries can then be modified independently.
***
## 8. Reordering States
The arrow buttons allow you to move states up or down.
Order matters.
The controller cycles through states in top-to-bottom order.
Example cycle:
1. State A (5s)
2. State B (10s)
3. State C (2s)
Then repeats.
***
## 9. Conditions Button
The **Conditions…** button opens the Conditions Screen.
Conditions restrict when the state cycle is allowed to execute.
If conditions are not satisfied:
* The cycle pauses
* No state changes are applied
Conditions are optional.
***
## 10. Apply / Cancel
* **Apply** saves changes.
* **Cancel** discards modifications.
Changes are not active until applied.
***
Continue to **Conditions Screen** to configure environmental or player-based triggers.
---
# 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, and the optional `goal` query parameter:
```
GET https://halekio.gitbook.io/state-controller-block/1_main_screen.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
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.