This keyword has two uses: as the header of a state, it's used to declare a state other than default; as a regular statement, it's used to switch to a state.

As a declaration, the syntax for a whole state is:

state <state_name>
{
   <event_declaration>

   <event_declaration>

   ...
}

where <state_name> is the identifier that will be used in switch statements. As an exception, when declaring state default we don't add the keyword state in front of it. Additionally, the default state must always appear before any other state declaration.

For the <event_declaration> syntax see Events. States can't be empty; there must be at least one event declaration inside of each state. There can be as many event declarations as necessary, but there can't be two declarations of the same event inside the same state.

The syntax as a statement is:

state <state_name>;

where <state_name> can be default or the name of any existing state.

When a state switch statement is found, a return statement is automatically inserted at that point in the code, and when the currently executed event finalizes, the state switch happens. This triggers two events: first, the state_exit event for this state; then, the state_entry event for the state changed to.

State statements aren't designed to be used within user-defined functions, only within events. It's possible to use state statements in user functions, but with caveats; see hacks below.

Script execution always starts in the default state; other states aren't executed unless they are switched to.

TODO: Talk about interaction of touch_start and switching states.

TODO: Talk about the event queue flush.

Here's an example of a simple drawer that moves along the local X axis, implemented using states:

State-example.lsl

// State declaration of the default state (mandatory, always first)
default
{
    touch_end(integer n)
    {
        // State switch statement that switches to the 'open' state
        state open;
    }
}

// State declaration of an additional state we've called 'open'
state open
{
    state_entry()
    {
        llSetPos(llGetLocalPos() - <0.3, 0, 0>);
    }

    touch_end(integer n)
    {
        // State switch statement that switches to the default state
        state default;
    }

    state_exit()
    {
        llSetPos(llGetLocalPos() + <0.3, 0, 0>);
    }
}

The default state just waits for a click release to switch to the open state. When entering the open state, the drawer moves 0.3 metres along x, then waits for a click release. When that happens, it switches to the default state. The state switch statement triggers the state_exit event, which moves the drawer back to its original position before actually switching.

TODO