File /obj/handlers/weather.c

Basic Operation
---------------
The weather is based on weather 'pattern's. The pattern lasts for several hours and is calculated from the 'seasonal' norm and the 'variance'. The 'current' weather will tend towards the pattern weather.

The pattern depends on the climate. The climates are taken from the Koppen Climate Classification system. The possible climates are:
tropical
- rainforest 'Af' eg. amazon, congo, malaysia
- monsoon 'Am'
- savanna 'Aw' eg. caribbean, tropical africa, central america
desert
- arid 'Bw'
- semi-arid 'Bs'
mediterranean (aka Moist Subtropical Mid-Latitude Climates)
- humid subtropical 'Cfa' eg. Souteast US (florida)
- mediterranean 'Cs' eg. california, south africa, western/central australia
- marine 'Cfb' eg. US west coast, nw europe
continental
- dry winters 'Dw'
- dry summers 'Ds'
- wet 'Df'
polar
- tundra 'Et'
- frozen 'Ef'
highland 'H'

The default for a room is mediterranean marine (Cfb).

The actual temparture in a room will depend on the current weather for that climate, local modifiers (climate property), diurnal variations and variance.

Thus update_patttern() is called once every hour (CYCLE_SPEED) and update_weather() is called every 5 minutes (UPDATE_SPEED).

Decisions
---------
Calculation of the general weather has been moved into update_weather. Rather than doing it on a room by room basis everytime someone looks! Instead, local climate controls will be added verbatim to the current global weather. This will improve efficiency massively, but will reduce the overall weather variations.

Principles
----------
Rain/sleet/snow depends on cloud density and temperature.
If it's windy and lots of cloud density we might get a thunder storm. Cloud cover should lower temperature as should wind.

Usage
-----
To alter the weather in a given room the easiest approach is to set the climate. Individual room or area variations can be done by adding a climate property.
The property should contain three integers, temperature, cloud cover and wind speed. These modify the default values for the room.

For example:
add_property("climate", ({10, -50, 0});
This will increase the temperature by 10C, reduce the cloud cover by 50% and make no change to the wind speed.

To completely alter the weather in a room you need to define the function room_weather() as follows:
int *room_weather(int temp, int cloud, int wind, int rain);
Your room_weather function will be called with the values the room would ordinarily receive and should return the new temperature, cloud cover, wind speed and rain type values that you desire.

If you need to make your room react to changes in the weather you can use the weather_notify() system to be told when the weather changes.
This should only be done for a small number of rooms or the lag will be excessive Also note that after a notification has been done, you will need to register if you want another one.

Changed Jun 3 1996 by Grampa to include weather notifications for rooms.

Includes

Method index

• check_umbrella(object)
• cloud_string(object)
  A string giving a nice description of the cloud types.
• day_number()
  Find out which day of the Disc (common) year it is.
• minute_number()
  Find out which minute of the day (0 - 1439) it is.
• query_cloud(object)
  Find out the cloud cover of a given room
• query_darkness(object)
  return percentage of light should be dependant on the base amount of light, day or night time and cloud cover.
• query_moon_phase()
  Find out which phase of the moon we're currently in.
• query_moon_state()
  Query the state of the moon.
• query_moon_string(object)
  Get the appropriate moon string.
• query_raining(object)
  Find out if its raining in a given room.
• query_season()
  Return which of the 4 seasons we are in.
• query_snowing(object)
  Find out if its snowing in a given room.
• query_star_string(object)
  Returns a string describing the current visible stars.
• query_stars(object)
  Return the number of currently visible stars as a percentage.
• query_sunrise(int)
  Find out when sunrise will be on a given day of the year.
• query_sunset(int)
  Find out when sunset will be on a given day of the year.
• query_temperature(object)
  Find out the temperature of a given room
• query_tod()
  Return a string for the period of the day
• query_visibility(object)
  return percentage of visibility.
• query_windsp(object)
  Find out the wind speed in a given room
• rain_string(object)
  Creates a string showing how heavily it is raining.
• sleet_string(object)
  Creates a string showing how heavily it is sleeting.
• snow_string(object)
  Creates a string showing how heavily it is snowing.
• temp_string(int)
  Return a temperature string equating to the temperature passed
• weather_notify(object, int)
  Add a room to the list of rooms to notify about weather.
• weather_string(object, string)
  Creates the weather string which is put into room descs.

Public Functions

check_umbrella

int check_umbrella(object ob)

cloud_string

string cloud_string(object env)

A string giving a nice description of the cloud types.

Parameters:
env - the environment to find the clouds for

Returns:
the current clouds

day_number

int day_number()

Find out which day of the Disc (common) year it is.

Returns:
the day of the year.

minute_number

int minute_number()

Find out which minute of the day (0 - 1439) it is.

Returns:
the minute.

query_cloud

int query_cloud(object env)

Find out the cloud cover of a given room

Parameters:
env - the room

Returns:
an open ended percentage. Greater than 100 means heavier cover.

query_darkness

int query_darkness(object env)

return percentage of light should be dependant on the base amount of light, day or night time and cloud cover.

Parameters:
the - room

Returns:
a percentage

query_moon_phase

string query_moon_phase()

Find out which phase of the moon we're currently in.

Returns:
a string for the phase of the moon.

query_moon_state

int query_moon_state()

Query the state of the moon.

Returns:
an integer indicating the state of the moon. 0 - no moon, 1 - crescent, 2 - quarter, 3 - half, 4 - three quarter, 5 - gibbous, 6 - full.

query_moon_string

string query_moon_string(object env)

Get the appropriate moon string. This is almost completely from the old system. I don't understand the moon.

Parameters:
env - the room to check

Returns:
the moon string.

query_raining

int query_raining(object env)

Find out if its raining in a given room.

Parameters:
env - the room

Returns:
1 or 0 for true or false.

query_season

string query_season()

Return which of the 4 seasons we are in.

Returns:
spring, summer, autumn or winter.

query_snowing

int query_snowing(object env)

Find out if its snowing in a given room.

Parameters:
env - the room

Returns:
1 or 0 for true or false.

query_star_string

string query_star_string(object env)

Returns a string describing the current visible stars.

Returns:
a string for the visible stars.

query_stars

int query_stars(object env)

Return the number of currently visible stars as a percentage.

Returns:
A number 0-100, 0 being no stars.

query_sunrise

int query_sunrise(int doy)

Find out when sunrise will be on a given day of the year.

Parameters:
doy - Day of the Discworld common year.

Returns:
sunrise time (in seconds past midnite).

See also:
minute_number() and day_number()

query_sunset

int query_sunset(int doy)

Find out when sunset will be on a given day of the year.

Parameters:
doy - Day of the Discworld common year.

Returns:
sunset time (in seconds past midnite).

query_temperature

int query_temperature(object env)

Find out the temperature of a given room

Parameters:
env - the room

Returns:
a temperature in Celcius

query_tod

string query_tod()

Return a string for the period of the day

Returns:
night, morning, midday, afternoon or evening.

query_visibility

int query_visibility(object env)

return percentage of visibility. It should also depend on things like rain/snow etc, anything which will effect visibility.

Parameters:
the - room

Returns:
a percentage

query_windsp

int query_windsp(object env)

Find out the wind speed in a given room

Parameters:
env - the room

Returns:
the wind speed in miles per hour.

rain_string

string rain_string(object env)

Creates a string showing how heavily it is raining.

Parameters:
env - the room room to check in

Returns:
the rain string

sleet_string

string sleet_string(object env)

Creates a string showing how heavily it is sleeting.

Parameters:
env - the room room to check in

Returns:
the sleet string

snow_string

string snow_string(object env)

Creates a string showing how heavily it is snowing.

Parameters:
env - the room room to check in

Returns:
the snow string

temp_string

string temp_string(int temp)

Return a temperature string equating to the temperature passed

Parameters:
int - The temperature in Celcius

Returns:
string a temperature string.

weather_notify

int weather_notify(object which_room,
                   int notifications)

Add a room to the list of rooms to notify about weather. Notifications are an ORed (|) combination of the #defines in /include/climate.h IE: To inform about temperature and rain changes, call weather_notify( room, (NOTIFY_TEMPERATURE | NOTIFY_RAIN) );

Parameters:
which_room - the room to be notified
notifications - a bitmap of notifications

Returns:
success or failure (1 or 0)

weather_string

varargs string weather_string(object env,
                              string obscured)

Creates the weather string which is put into room descs.