start_con_handler( descriptor, func, ... )

Creates a coroutine of the given function and sets it as the con state handler to the target descriptor. Any additional arguments to start_con_handler are passed to func when it is called.
The con state handler handles all player input from the given descriptor. Entered commands are accessed within the handler function through coroutine.yield().

The general logic is thus:
start_con_handler creates a coroutine of func
func coroutine is set as descriptor's con state handler
func coroutine is resumed, passing any additional start_con_handler arguments as arguments to func
if coroutine.yield() is called inside the handler, then the coroutine will suspend until the player enters a command, at which time the handler function resumes, with the return value of coroutine.yield() being the command that was entered.
If/when the handler function returns, descriptor's con state handler is cleared and con state is set back to "playing". The player can now enter normal game commands again.


Example 1: confirming an action (example uses luai for convenience)
<code>
luai
lua>
</code>
<code lua>
do

local function confirm_handler( ch )
    sendtochar(ch, "Are you sure you want to declare yourself a butthead? [Y/n]\n\r")
    
    while true do
        local cmd=coroutine.yield()
        
        if cmd=="Y" then
            ch:mdo("gossip I AM BUTTHEAD")
            return
        elseif cmd=="n" then
            sendtochar(ch, "Fine, don't then.\n\r")
            return
        else
            sendtochar(ch, "Invalid! Please input {GY{x or {rn{x.\n\r")
        end
    end
end

start_con_handler( mob.descriptor, confirm_handler, mob )

end
</code>
<code>
Are you sure you want to declare yourself a butthead? [Y/n]
Y
You gossip 'I AM BUTTHEAD'
lua>
</code>

See also [[lua:scripting:examples:constates]]