States let you run what the user types through your own parser. Lua states let you do this in lua.

To make a lua state, put some code in a lua.state property on an object and then call lua_pushstate(player,your_object) to put them into your state.

When the user types a command, your state will get called with pl being the player, and txt being what they typed.

If you wish to use a different prompt so the user knows they're not in the normal mud, set the prompt property on your object.

By default, a user can type ** to leave your state and return to his previous one. If you need to override that, set the integer property ignorestars to 1. You must then provide a way for users to leave your state, or they will be stuck in there forever. To make a user leave your state and return to the one he was in previously, do lua_popstate(pl)

States work in a stack. Every time you use lua_pushstate you add a new state to the stack. lua_popstate leaves the inner most stack and returns the user to the previous one. If you have more than one state and you want to move users between them, but still only need a single pop to return them to their normal state, you can use lua_setstate(pl, new_object) to replace their current state with your new one. This only works to move from one lua state to another lua state. You can't replace a built-in C state with a lua one.

You can store data in a state. Use lua_setstatestr(pl,property,value) from inside your state to store some data. You can retrieve this data later in future calls to your state with lua_getstatestr(property). This data storage is per invocation - each user in the state at once will have their own distinct sets of data. The data is kept for the new state when you use lua_setstate().

For an example lua state, look at template_locker_2.