Generic Ambient Noise Room (#176)

     Settable properties:
     
     .amb_delay - this is the delay between random announcements, in seconds.
                  The default is 5 minutes, or 300 seconds.
     .amb_noise - this is the list of random messages you wish to display.
     .active    - set to 1 (default) when runs. Set to 0 to turn off ambient noise
                  behavior entirely.
     
     All you need to do is @notedit the .amb_noise property and enter in all possible 
messages you want announced. The order doesn't matter.
     
     Then, whenever a player enters, the announcements will start and appear every .amb_delay 
seconds. If the .amb_noise property is empty, nothing will happen and the room will 
act like a normal blank room would.
     Note - the first noise message appears 30 seconds after the first player enters.
     ----
     Commands:
     
     @restart
     
     The owner of the room can call this verb to restart the ambient noise tasks. Mostly 
in the case when .active was set to 0 for a while, then set back to 1 while there 
are people still in the room.

occupied = 0;
for thing in (this.contents)
    if (is_player(thing) && $object_utils:connected(thing))
        occupied = occupied + 1;
    endif
endfor
return occupied;
.

if (caller != this)
    return E_PERM;
endif
while (((amb = this:get_amb()) && this.occupied) && this.active)
    this:announce_all(amb);
    suspend(this.amb_delay);
endwhile
.

if (caller != this)
    return E_PERM;
endif
if (this.amb_noise && this.active)
    if ((occupied = this:occupied()) > 1)
        this.occupied = 1;
    elseif ((occupied == 1) && (!this.occupied))
        this:start_amb();
    elseif (!occupied)
        this.occupied = 0;
    endif
endif
.

if (caller != this)
    return E_PERM;
endif
if (occupied = this:occupied())
    this.occupied = 1;
else
    this:stop_amb();
endif
.

pass(@args);
this:check_amb();
.

pass(@args);
this:end_amb();
.

"Usage: @restart";
"";
"The owner of the room can call this verb to restart the ambient noise tasks. Mostly 
in the case when .active was set to 0 for a while, then set back to 1 while there 
are people still in the room.";
if (!$perm_utils:controls(player, this))
    player:tell(E_PERM);
    return;
endif
if ($code_utils:task_valid(this.amb_task))
    player:tell(this.name, " is already running ambient noise.");
    return;
elseif (!this.active)
    player:tell("Please set .active to 1 before @restarting ", this.name, ". (You 
can use: @set here.active to 1)");
    return;
endif
this:start_amb();
player:tell(this.name, " has been restarted with ambient noise.");
.

"Starts the ambient noise task. Children can program verbs on the rooms that start 
and stop the noise as they wish. Be careful of multiple noise tasks though.";
if (caller != this)
    return E_PERM;
endif
fork ambience (this.initial_amb_delay)
    if (this:occupied())
        this.occupied = 1;
        this:ambience();
    else
        this.amb_task = 0;
    endif
endfork
this:set_amb_task(ambience);
.

"Ends the Ambient noise. Children can write verbs on their descendants which turn 
it off at will.";
if (caller != this)
    return E_PERM;
endif
if ($code_utils:task_valid(this.amb_task))
    kill_task(this.amb_task);
endif
this.amb_task = 0;
this.occupied = 0;
.

"Just returns a random noise. Children can override in case they want to send different 
noise under different conditions.";
if (caller != this)
    return E_PERM;
endif
return this.amb_noise[random(length(this.amb_noise))];
.

"Let's whoever controls this, or this, to set the .amb_task directly so that children 
can deal with the tasks and the property.";
if ((caller != this) && (!$perm_utils:controls(caller_perms(), this)))
    return E_PERM;
elseif ((typeof(t = args[1]) == NUM) && $code_utils:task_valid(t))
    this.amb_task = t;
else
    return E_INVARG;
endif
.