MPP - Day and Night Sky Cycle V2.4 - Documentation

A complete day and night cycle for your Sansar scene, ready to use: a sun that follows the real path of the sun for the place and the date you choose, a sky dome with stars, a cloud layer, a desk of buttons for your visitors, and a scheduler that talks in the nearby chat and can switch your lamps on at sunset.

New in V2.4: the scene clock can show legal time (time zone, summer time, longitude), and sunrise and sunset are within about 3 minutes of the official times. The set is delivered for Paris; to use another place, you only change a few settings (section 2).

Contents

1. What you get
2. Quick start (5 minutes)
3. The Commands Desk
4. How time works
5. Control settings
6. Sun settings
7. Sky, Stars and Clouds settings
8. Visitor commands
9. Scheduled events - Actions A and Actions B
10. Announcements
11. Welcome message
12. Adding the script to your own objects
13. Recipes
14. Troubleshooting
15. Limits

• Appendix A - 40 cities
• Appendix B - 20 dates
• Appendix C - Related MPP items

1. What you get

In Build mode, your inventory holds the item - MPP - Day and Night Sky Cycle - V 2.4. It is one parent object that groups four objects, all already scripted and set up:

The five DayNight scripts are the same script, MPP - Day Night V2.4.0, used as three modules:

• Control (on MPP Sun): the settings of the whole scene. It sends them to the Sun, and receives the visitor commands.
• Sun (on MPP Sun): moves the light along the sun path and changes its color and intensity through the day.
• Sky (three times: Sky and Stars on MPP Sky, Clouds on MPP Clouds): each one follows the Sun, fades and tints the materials of its object and, when its rotation is On, turns the object with the sun.

To see the settings of a script: in the Scene Objects list, expand - MPP - Day and Night Sky Cycle - V 2.4 to show its four objects, select one and open Properties. Each script appears as a block titled with its name in capitals, for example MPP - DAY NIGHT - CONTROL. Under the title, the first drop-down shows the script (MPP - Day Night V2.4.0) and the second one its module (MPPDayNightControl, MPPDayNightSun or MPPDayNightSky). On MPP Clouds the script sits on the part Sphere 02. The nine buttons are the objects inside MPP - Commands Desk, named after their button (for example MPP button - City).

All the modules talk on one private channel, General/Group = DayNight. Keep it identical everywhere.

2. Quick start (5 minutes)

2.1 Place the set

1. Open your scene in Build mode.
2. In your inventory, find - MPP - Day and Night Sky Cycle - V 2.4 and drag it into the scene.
3. Move it near the centre of your scene: the sky dome and the clouds surround it.
4. Do not rotate MPP Sun, MPP Sky or MPP Clouds on their own: the sun and the sky are set to turn together from their current orientation. You may move the whole set, and turn the whole set around the vertical axis (for example to choose where the sun is at noon), but never tilt it.
5. Save and build the scene, then visit it. The sun already runs: Paris, July 21, a 4-hour day, opening at 4:30 AM at the first light of dawn.

2.2 Choose your place on the globe

Select MPP Sun, open Properties, and go to the block MPP - DAY NIGHT - CONTROL, group Geo:

Appendix A gives these values for 40 cities. Example, Tokyo: latitude 35.68, longitude 139.65, UTC Offset 9, Clock Mode 1, Place Name Tokyo in Japan.

Do not forget Geo/Place Name: the welcome message quotes it.

The desk's City button only knows Stockholm, Paris, Los Angeles and Sydney: once a visitor clicks it, your own place comes back only when the scene restarts. Delete that button (it is the object MPP button - City inside the desk) if you want to keep your place.

2.3 Choose the day of the year

Same block, Geo/Day Of Year (1-365). Delivered: 202 (July 21). The day sets the height of the sun and the length of the day.

Appendix B gives the day number of 20 well-known dates (Christmas = 359, Halloween = 304...). The date does not advance by itself: the scene always replays the day you chose.

The desk's Season button switches between days 172 and 355 only: once a visitor clicks it, your own day comes back only when the scene restarts. Delete that button (MPP button - Season) if you want to keep your day.

2.4 Choose the length of a day and the opening hour

Same block, group Cycle:

Examples: 1 h 0 min = a whole day in one real hour; 0 h 16 min = a fast day for a demo; 24 h 0 min = the in-world day runs at real speed.

If you change the day length, also change Buttons/Normal (minutes) (same block, group Buttons) to the same length in minutes, for example 60 for a 1-hour day. The desk's Cycle speed button switches between Buttons/Fast and Buttons/Normal: otherwise its "normal" position brings back the 4-hour day.

4:30 AM is the first light of dawn in Paris in July. After changing the place or the day, check the opening hour: for example 9 opens the scene in the morning almost everywhere.

2.5 Save, build and visit

Type /daynight help in the nearby chat to see the visitor commands, or click the ? button of the desk. That is all you need: the rest of this guide explains every option.

3. The Commands Desk

A sloped desk titled Commands Desk with 9 buttons. The large button on the left is Help. The top row holds the four "setting" buttons (from left to right: Cycle speed, Season, Time of day, City); the bottom row holds the four "moment" buttons (Sunrise, Noon, Sunset, Midnight). Any visitor can click them.

Good to know:

• Sweeps. A time button does not jump: the sun, the sky and the light sweep to the requested moment in 8 seconds (Transition/Duration (s) on the Control). Time always moves forward, so asking for sunrise in the evening goes through the night.
• One command every 4 seconds. The Control accepts one visitor command every 4 seconds, for everybody, buttons and chat together (Chat/Cooldown (s)). A click during that time is refused, and the visitor receives a private "[DayNight] please wait". Each button also has its own short cooldown (0.8 s, shared by all visitors): when the same button is clicked again too fast, by you or by someone else, it answers privately "Please wait 1 second before using this button again." and the click is ignored. A multi-state button (Time of day, Cycle speed, Season, City) moves to its next state even when its click is refused: its color no longer matches the scene, and its next click sends the state after that one. Wait a few seconds, then click on until the scene shows what you want (Cycle speed and Season: two more clicks).
• Season and City move the clock. These buttons keep the solar time: the sun stays at the same point of its daily course, only higher or lower for the new date or place. With a legal clock the hour shown jumps, usually by about 1 hour.
• Colors at start. When the scene starts, Time of day shows the sunrise color, Season the summer color, City the Stockholm color, and Cycle speed the green (normal) color. The first click of Time of day, Season or City sends the first command of its list.
• Adjust or remove it. You can move, resize, copy or delete the desk: it has no link with the other objects, it only sends script events. Without it, the chat commands still work.
• Keep the sun to yourself. Turn Owner Only On on each button (script MPP - ActionButton): only you, the scene owner, can then use them; add your friends' handles to its Access List to let them in too. Visitors who are not allowed receive a private "You are not allowed to use this button." (Denied Text), and Hide From Denied On even hides the buttons from them. Turn Chat/Owner Only On in the Control as well, for the chat commands. Other ways: delete the desk, or turn Buttons/Enable Off in the Control (the buttons then still click and change color, but do nothing).
• Add a button. Any object with the MPP Action Button Script (V1.7.0, Appendix C) works with Send as Command = On and one of the command texts of section 8, for example daynight_summer.

Button settings (script MPP - ActionButton V1.7.0)

Shared by the 9 buttons: Collision Mode Off (click), Cooldown Seconds 0.8, Global Cooldown On, Cooldown Notice On (text "Please wait {time} before using this button again."), Owner Only Off, Access List empty, List Is Blacklist Off, Denied Text "You are not allowed to use this button.", Hide From Denied Off, Send as Command On, Private Text Off, Remote Control Off (Remote Prefix mpp_actionbutton, unused), Click Sound MPP - Computer Beep at volume 100, Visual On, Tint Material Name empty (every tintable material of the button), Return Fade Seconds 0.8, Emissive On, Debug Off.

The one-command buttons flash their tint with an emissive of 0.2, then fade back; the multi-state buttons keep the tint of their current state, with an emissive of 4.

4. How time works

• The in-world day runs from 0 h to 24 h on the scene clock (see below). Its real duration is Cycle/Day Length (delivered: 4 real hours).
• The clock is anchored on real time: a 4-hour day lasts 4 hours, with no drift, whatever the server load.
• Sunrise and sunset are computed from Geo/Latitude and Geo/Day Of Year. Near the poles the sun may never set (polar day) or never rise (polar night).
• The day is cut in four periods: Morning, Day, Evening, Night. With Timeline/Auto From Geo On they follow the computed sunrise and sunset. Each period has its own light color and intensity on the Sun, and its own tint on the sky, the stars and the clouds.

Solar time and legal time

The sun itself always moves in solar time: at 12:00 solar time it stands at its highest. Real clocks show legal time, which differs by the time zone, summer time, the longitude inside the time zone and the equation of time (the sun runs up to 16 minutes early or late during the year). In Paris, the sun culminates between 12:34 PM (early November) and 1:57 PM (late July), legal time.

Geo/Clock Mode chooses the clock that visitors read and type: 0 = solar time, 1 = legal time without summer time, 2 = legal time with European summer time (delivered), 3 = North American, 4 = southern hemisphere (Australia). With a legal clock, set Geo/Longitude and Geo/UTC Offset (winter offset from UTC: Paris 1, London 0, New York -5). The City button sets all three (a Control in Clock Mode 0 keeps solar time). Appendix A gives the values of 40 cities.

Hours you type (time 18, 18:30 in the Events lists, Cycle/Start Time) are on the scene clock. Keywords follow the sun: sunrise, sunset, noon (sun at its highest) and midnight (sun at its lowest). The four manual period starts of the timeline are solar hours, because they describe the light.

Sunrise and sunset follow the published convention (upper edge of the sun on the horizon, with atmospheric refraction). Accuracy: about 3 minutes compared with official ephemerides, with a few exceptions near the polar circles and around the summer time switches (section 15).

Example - the delivered set (Paris, July 21). The scene clock is 1 h 57 min ahead of the sun. Sunrise reads 6:10 AM and sunset 9:44 PM, like the real ones; the sun is at its highest at 1:57 PM, so the Noon button answers time set to noon (1:57 PM); /daynight time 12 puts the sun 1 h 57 min before its highest point. The scene opens at 4:30 AM, when the Morning period begins: the first light of dawn, 1 h 40 min before sunrise.

5. Control settings

Object MPP Sun, block MPP - DAY NIGHT - CONTROL (module MPPDayNightControl). The "Delivered" column gives the values of the set.

Cycle

Geo

Timeline

Chat, Buttons, Transition

Events, General, Debug

6. Sun settings

Object MPP Sun, block MPP - DAY NIGHT - SUN (module MPPDayNightSun).

Intensities go from 0 to 100. The evening colors of the whole set (light, sky, clouds) are a stylized magenta sunset.

7. Sky, Stars and Clouds settings

Three modules share the same settings (module MPPDayNightSky):

• Sky: object MPP Sky, block MPP - DAY NIGHT - SKY. It drives the sky layers of the dome (materials Sky and FX).
• Stars: object MPP Sky, block MPP - DAY NIGHT - STARS. It drives the star layer of the same dome (material Stars). Its Emissive is 0 by day and 3.2 at night (Blend/Emissive Day / Night), so the stars shine at night and vanish by day.
• Clouds: object MPP Clouds, block MPP - DAY NIGHT - CLOUDS. It drives every scriptable material of the object, so both cloud spheres. The clouds do not rotate but darken at night and take the colors of the day.

8. Visitor commands

Chat

Type these in the nearby chat. Every command but help goes through the shared cooldown (4 seconds).

With a legal clock (Clock Mode 1-4), date, the season and the city commands keep the solar time (the sun changes height, not its place in the day) but make the clock jump, usually by about 1 hour.

A command changes the scene for everybody until the scene restarts (or until the Control or the Sun script restarts): then the settings of the Control apply again.

Button commands

The desk sends these texts as script events (MPP ActionButton, Send as Command = On):

daynight_midnight daynight_sunrise daynight_noon daynight_sunset daynight_fast daynight_normal daynight_summer daynight_winter daynight_help daynight_stockholm daynight_paris daynight_losangeles daynight_sydney

daynight_fast and daynight_normal apply Buttons/Fast and Buttons/Normal; daynight_summer and daynight_winter jump to days 172 and 355.

9. Scheduled events - Actions A and Actions B

The Control can send script events to any other script of the scene at chosen in-world times. Two lists, the same syntax, two different behaviors.

Delivered: Actions A holds sunset | mpp_lamp_all_on and sunrise | mpp_lamp_all_off. No lamp comes with the set: these two lines are a ready-made example for lamps driven by the MPP Light Switch Script (V1.5.1, sold on the Sansar Store, see Appendix C; V1.4.2 works too), which is compatible as is. Put that script on your lamps with External Events On and they switch on at sunset and off at sunrise by themselves (example 1). Without such lamps these two lines do nothing; delete them if you like. Actions B is empty.

Line syntax

when | event_name
when | event_one, event_two

Everything before the first | is the time, everything after is one event name or several separated by commas. Event names are sent exactly as typed (case and punctuation kept). Each list holds up to 20 lines.

The when part

A = states, B = moments

Why it matters: start the scene at 10 PM with lamps in list A and they are lit within 5 seconds, although sunset happened before the scene existed. A bell at 18:00 in list A would ring at every scene start; in list B it rings only when 6 PM really passes.

The Control's own commands (daynight_noon, daynight_summer...) are refused in list A, because a replayed time command would loop. Put them in list B.

Example 1 - street lamps (MPP Light Switch Script V1.5.1 or V1.4.2)

LightSwitch settings: External Events = On, External Event Prefix = mpp_lamp. (V1.4.0 and V1.4.1 also answer the _all_ names below; on V1.4.0 the switch is called Enable External Script Events.) Since V1.5 the lamp's Cooldown Seconds also applies to these events: when the scheduler replays the last 24 hours (scene start, Season or City change), each lamp goes straight to the right state, without blinking.

Actions A (states)
  sunset  | mpp_lamp_all_on
  sunrise | mpp_lamp_all_off

_all_ reaches every LightSwitch whatever its Group. To drive one group only, write the group name in lowercase, with underscores for spaces. For lamps whose Group is Street:

  sunset  | mpp_lamp_street_on
  sunrise | mpp_lamp_street_off

Use night and morning instead of sunset and sunrise to switch at the end of dusk and at the first light of dawn.

Example 1b - the same with MPP LightSwitch V1.3

V1.3 listens to another name pattern: <Event Prefix>:<group in lowercase>:<action>. With Event Prefix = mpp_lamp and Group = Lamp:

Actions A (states)
  sunset  | mpp_lamp:lamp:on
  sunrise | mpp_lamp:lamp:off

With an empty Group the names are mpp_lamp:on and mpp_lamp:off.

Example 2 - shop window lit before the street lamps

Actions A (states)
  sunset-0:30 | mpp_lamp_shop_on
  23:00       | mpp_lamp_shop_off
  sunset      | mpp_lamp_street_on
  sunrise     | mpp_lamp_street_off

Example 3 - one line, several receivers

  sunset  | mpp_lamp_all_on, campfire_on, fountain_off
  sunrise | mpp_lamp_all_off, campfire_off, fountain_on

Example 4 - moments

Actions B (moments)
  sunrise  | rooster_crow
  12:00    | church_bell
  hourly   | clock_chime
  midnight | daynight_summer

The last line uses a DayNight command as a moment: each time the sun really passes its lowest point (midnight), the season jumps to summer. Like a click, it goes through the 4-second cooldown: it is skipped silently if a visitor command was accepted just before, and a visitor who clicks right after gets "please wait".

Which scripts can receive these events?

Any script that subscribes to a script event by name. One thing to know: a scheduled event is sent by the scene, not by a visitor, so it carries no avatar.

For scripters. The payload is compatible with the MPP ActionButton interface and adds the hour of the scene clock:

public interface IScheduledEvent
{
    string ActivatorAvatarUuid { get; }   // always empty for a scheduled event
    float InWorldHour { get; }            // 0..24, the hour of the entry on the scene clock
}

SubscribeToScriptEvent("campfire_on", (ScriptEventData e) =>
{
    // e.Data is null when another script posts the same name without a payload
    var data = (e.Data != null) ? e.Data.AsInterface<IScheduledEvent>() : null;
    LightTheFire();
});

10. Announcements

Lines of the Events/Announcements list are said in the nearby chat, to everybody.

when | message

Same when syntax as the actions. Delivered:

  hourly  | It is {time}.
  morning | Have a good day!
  night   | Have a restful night.

With a 4-hour day, hourly speaks every 10 real minutes: delete that line for a quieter scene. To silence all the announcements, empty the list (or turn Events/Enable Off, which also stops the actions and the welcome message).

The message may contain variables:

More examples

Events/Announcements
  sunrise     | Good morning! The sun rises at {sunrise}.
  sunset-1    | One hour of daylight left: sunset is at {sunset}.
  12:00       | Noon in {place}. Lunch time!
  noon        | The sun is at its highest: it is {time}.

Good to know:

• Announcements are never replayed and are skipped during a sweep: clicking Noon does not flood the chat with hourly messages.
• On very short days, an hourly line that comes less than 4 seconds after the previous announcement is skipped, not delayed. Other lines (sunrise, 12:00...) are said even then, up to 3 in the same half second.
• In polar day, sunset, evening and night lines stay silent; in polar night, sunrise, morning and day lines do. This holds for the actions too, and for morning, day, evening and night only while Timeline/Auto From Geo is On (manual period starts keep firing).
• With a legal clock, a date or city change moves the clock: around that change, an hourly or fixed-hour line may be said twice or skipped once.

11. Welcome message

Events/Welcome Delay (s) is counted from the visitor's arrival, not from the scene start, so the message is not lost while the scene is still loading. 10 seconds suits most scenes; raise it for heavy scenes.

Delivered text:

Welcome! Here it is {date}. Our position on the globe: {location}. A full day lasts {daylength} in this world.

which gives:

Welcome! Here it is July 21. Our position on the globe: Paris in France (latitude 48.9 N). A full day lasts 4 hours in this world.

Another example:

Welcome to the harbour! Local time is {time}, sunset at {sunset}. The lamps switch on by themselves at nightfall.

In the welcome message {time} is the current time on the scene clock.

12. Adding the script to your own objects

The script MPP - Day Night V2.4.0 comes with the set, in your inventory. You can add it to your own objects, for example a second cloud layer, your own sky dome, or a sun of your own: in Build mode, drag the script from your inventory onto the object, choose its module in the second drop-down of the new script block (MPPDayNightSky, MPPDayNightSun or MPPDayNightControl), then enter its values. A new module starts with the built-in defaults of the script (last point below), not with the values of the set.

• A layer that follows the sun (clouds, dome, stars, fog...): add the script to the object and choose the module MPPDayNightSky. Keep General/Group = DayNight. For a layer that rotates, place the object at its midnight orientation and tick Movable from Script; for a still layer, set Rotation/Enable Off. Fill Materials/Names if the object has materials you do not want to drive; the materials must be scriptable.
• One Sun and one Control per scene. They are already on MPP Sun. To use another light as the sun, add the Sun and Control modules to it, enter their values again, then delete the two scripts of MPP Sun. The light must point straight up from under the ground at midnight (with the standard pose, a rotation of <90,0,0>), and the object needs Movable from Script.
• If an object has both a RigidBody and Movable from Script, keep the RigidBody Motion Type = Keyframed: a Static rigid body blocks the rotation.
• A module added from your inventory starts with the built-in defaults of the script, which differ from the delivered set on a few points: copper evening light (255,99,41) and sky tint (255,140,107); sky fading Absorption 0.20 / 0.95 and Emissive 0.18 / 0.02; Materials/Log Names On; and, on a new Control, day 80, Start Time 0, an empty Place Name, empty event lists, Chat/Cooldown 1 and Welcome Mode 1.

13. Recipes

A - Your city, today's season. In the Control: the values of your city from Appendix A, the day of the year from Appendix B, and your city's name in Geo/Place Name. That is the quick start of section 2.

B - Village with automatic lighting. Keep the delivered Actions A (sunset | mpp_lamp_all_on, sunrise | mpp_lamp_all_off) and put the MPP Light Switch Script (V1.5.1, Appendix C) on your lamps with External Events = On. Choose day 172 for long summer days.

C - Always-winter Nordic scene. In the Control: latitude 59.33, longitude 18.07, UTC offset 1, Clock Mode 2, day 355, place name Stockholm in Sweden. The sun rises late, stays low and sets early; lamps in list A follow these short days by themselves. For a polar night, use Tromso (Appendix A) and day 355.

D - Fixed hours whatever the season. Timeline/Auto From Geo = Off, then Manual starts 6, 8, 18, 20. morning, day, evening and night now mean 6:00, 8:00, 18:00 and 20:00 solar time all year; set Geo/Clock Mode = 0 if you want the clock to read these very hours.

E - Showroom demo. Keep the desk; set Buttons/Fast (minutes) to your liking and keep Chat/Cooldown = 4, so that a group of visitors cannot fight over the sun.

F - Solar clock. Geo/Clock Mode = 0: 12:00 is always the sun at its highest, noon reads 12:00 PM and every hour you type or read is on solar time.

G - Quick test of your schedule. Set the day length to 16 minutes, turn Debug/Verbose Logging On in the Control, visit, and open the script console: every sent event shows with its time on the scene clock, as events: 21:44 state #1 -> mpp_lamp_all_on.

H - A quiet scene. Delete the hourly announcement, set Events/Welcome Mode = 0, and turn Chat/Feedback Off.

14. Troubleshooting

15. Limits

• Each list holds 20 lines (Sansar limit). One line may carry several events, and hourly counts as one line.
• Scheduled events carry no avatar: receivers that require one ignore them (see section 9).
• A moment placed exactly on the target of a time preset does not fire when that time is reached by a sweep.
• A DayNight command in Actions B (example 4) shares the 4-second visitor cooldown: if a visitor used a command just before, it is skipped without a message, and a visitor who clicks right after it gets "please wait".
• One DayNight set per scene: two Controls would both answer the same buttons and chat commands.
• The calendar has 365 days and no year: summer time starts and ends on fixed days (Europe: March 28 to October 28; North America: March 11 to November 4; Australia: October 4 to April 4). Near a switch, the clock can be one hour off for up to 3 days.
• Sunrise and sunset are within about 3 minutes of official ephemerides: the calendar has no year, refraction is the standard value, and relief and altitude are ignored.
• Near the polar circles, in the days around the start and end of polar day or polar night, the sun grazes the horizon and sunrise and sunset can be up to about 15 minutes off.
• The date does not advance by itself: the scene replays the same day until the Control or a visitor changes it.

Appendix A - 40 cities

Type these values in the Control, Geo group, and the city name in Geo/Place Name if you like. Geo/Use Geographic Model must be On.

Checked for the year 2027 against the official times (NOAA algorithm, real time zone rules): sunrise and sunset within 2 minutes, except on up to 3 days around each summer time switch (6 days a year at most), and for Tromso (see below).

• Vancouver: British Columbia keeps summer time all year from November 2026, hence UTC -7 without summer time (Clock Mode 1).
• Tromso: polar night from November 28 to January 14 (days 332 to 14), midnight sun from May 18 to July 25 (days 138 to 206). Near these dates sunrise and sunset can be up to about 15 minutes off.
• Southern hemisphere (Lima, Rio, Buenos Aires, Nairobi, Johannesburg, Cape Town, Sydney, Melbourne): the seasons are reversed, day 172 is their shortest day.
• Stockholm, Paris, Los Angeles and Sydney are also the four cities of the City button and of the chat commands (sections 3 and 8).

Appendix B - 20 dates

Type the day number in Geo/Day Of Year. The calendar has 365 days and no year.

Easter, Chinese New Year and Thanksgiving move every year: the table gives their 2026 date. For another year, count the day number from January 1 (January 31 = 31, February 28 = 59, March 31 = 90, April 30 = 120, May 31 = 151, June 30 = 181, July 31 = 212, August 31 = 243, September 30 = 273, October 31 = 304, November 30 = 334).

Appendix C - Related MPP items

Other MPP creations on the Sansar Store that work with this set:

MPP - My Pretty Pixels. Day and Night Sky Cycle V2.4 (script MPP - Day Night V2.4.0).