Docs / World
The world's clock
WorldClock runs a world's time of day, its season and its moon from one time your game gives it. If every player's game passes the same time, every player sees the same hour, the same season and the same phase of the moon, with no state to send between them. The clock also drives foliage through the year, using FallColors. This page also covers Sway, which moves foliage and cloth in the wind.
One shared time
The clock is a function of a time, in seconds. It keeps no state of its own. Pass Weather.realTime() (seconds since 1970, UTC) and players share the hour without a server. A game that has a server passes the server's time instead, so a player who changes their Mac's clock changes nothing. Weather schedules run on the same clock, so when that clock is shared the sky, the weather and the season all agree.
// your game, each frame let clock = world.sky.clock ?? WorldClock() let now = serverTime ?? Weather.realTime() let sky = clock.sky(world.sky.daySky, at: now) // the hour, latitude, year and moon from the clock let lighting = sky.lighting
sky(_:at:) takes a DaySky and sets its hour, latitude, yearPosition, moonAge and nightNumber from the clock. See the sky by the hour.
WorldClock
public init(runsDay: Bool = true, dayLength: Double = 3600, nightSpeed: Double = 2, calendar: Calendar = .days(perSeason: 7), latitude: Float = 45, foliage: FallColors = FallColors(), moonCycle: Double? = nil)
runsDay: whether the day runs. When it's off,timeOfDay(at:held:)returnsheld, andsky(_:at:)keeps the sky's own hour.dayLength: how long a game day lasts, in real seconds, from a minute up to a real day (WorldClock.dayLengths). The default is an hour.nightSpeed: how many times faster night passes than day, from 1 to 8. Day runs from six to eighteen and night covers the rest, each at its own pace. Midnight falls at the clock's zero.calendar: where the season comes from..days(perSeason:)is a game's own year, with each season lasting that many game days (1–365) and the middle of winter at the clock's zero..held(_:)always keeps one season..realDateuses the real date.latitude: degrees, north positive, from −89 to 89. It sets the sun's path, and it sets the hemisphere: south of the equator, winter falls in July, andsouthernis true.moonCycle: how many game days the moon takes from new to new on a game calendar. Withnil, the moon stays in step with the year, at about 12.4 cycles a year as the real one has. With seven-day seasons, that's a full cycle every two or three game days. The real-date calendar always has the real moon.
The clock answers these questions about any time:
| Method | Returns |
|---|---|
timeOfDay(at:held:) | the hour, 0…24 |
gameDays(at:) | game days since the clock's zero |
yearPosition(at:) | 0…4 on the northern calendar, as DaySky.yearPosition reads it |
season(at:) | the WeatherSchedule.Season where the world is |
moonAge(at:) | 0 new … 0.5 full |
nightNumber(at:) | a count that steps up each game noon, so a night keeps its number past midnight |
foliagePhase(at:) | where foliage is in its year (see below) |
WorldClock is Codable. A file can say anything, so reading one brings every value back into its range.
Seasons in the weather
A weather schedule can have seasons, each with its own chances. seasons(_:) puts them on the clock's calendar and hemisphere, so the weather's winter is the sky's winter:
// your game
weather.schedule?.seasons = clock.seasons(WeatherSchedule.Seasons.standardChances)
WeatherSchedule.Seasons.standardChances gives winter snow and fog, spring rain, summer clear skies and storms, and autumn rain and fog. Each season's chances and warmth belong to its middle, and every day in between mixes the two seasons on either side, so nothing jumps on a date. See weather.
Fall colors
FallColors, the clock's foliage, turns a wood through the year. Through autumn each tree turns at its own pace to its own color, and grass goes to straw. Late in autumn the leaves thin until broadleaf trees stand bare, and fallen leaves gather beneath them. In spring the trees green again. It tints the leaves a pack already has, so no autumn textures are needed.
palette:.mixed(yellow, orange and red),.golden,.fiery, or.customwith three linear colors incustom.extent: how far the turning goes, from 0 (leaves stay green) to 1 (full color).bareInWinter: off, broadleaf trees keep their leaves through winter, gone brown.
FallColors.phase(yearPosition:southern:) runs from 0 at midsummer through 1 (the middle of autumn) and 2 (winter) to 3 (spring). foliagePhase(at:) gives you the phase directly. Each tree's two numbers, how early it turns and which color it takes, come from FallColors.seed(x:z:), an integer hash of where it stands. Every player sees the same wood on the same day. From the phase and a tree's timing, turn(phase:timing:), leaves(phase:timing:), brown(phase:timing:) and straw(phase:timing:) say how far along it is. litter(phase:) says how thick fallen leaves lie, and leafFall(phase:) gives a falling-leaf particle effect its rate and whether it wears its autumn look. FallColors.changesAnything(phase:) is false through high summer, so a renderer can leave foliage alone then.
Which props take part is Foliage: .turns (a broadleaf tree or bush), .evergreen, .grass or .unchanged. Foliage.guess(name:) reads a prop's name: SM_Env_Tree_Pine_01 and PineTree01 are both evergreen. A dead tree, stump or log is unchanged. A world editor corrects a wrong guess per prop, and a world file carries the answer in foliage. On a prop, only the leaves change, never the bark.
In your shaders, DuctaneWeather.h has the same sums, term for term. In the vertex stage, once per copy, duSeasonOf computes a tree's turned color and how many leaves it has left. duShed drops whole cards of a submesh that is all leaves, by giving their corners duFallenPosition, so a thinning tree draws less, not more. In the fragment stage, duThroughTheYear colors a leaf, and returns false where a leaf sharing a submesh with bark has fallen. The foliage vector these take is built per copy: x is what the prop does (0 unchanged, 1 turns, 2 grass), y is the phase, z is 1 when trees go bare in winter, and w is the extent. Pass fall: (colors: clock.foliage, phase: clock.foliagePhase(at: now)) to WeatherSurface so the shaders get the palette and the litter. See weather.
Moving in the wind
Sway is how a prop moves in the wind. .tree bends from the root, more toward the top, with its leaves fluttering. .plant (grass, reeds, ferns, a bush) bends harder all over, in waves across a field. .cloth (a flag, a banner, a tarp) ripples and billows. .still doesn't move. Sway.guess(name:) reads a prop's name, the same way Foliage does, and a world file carries the answer in sway.
Weather.foliageWind(at:) is the wind for that moment. x and z give the way it blows, y gives how hard (0 for still air, about 0.15 for a breeze, 1 for a gale, times the world's Weather.sway of 0…2), and w gives seconds wrapped to an hour. Move vertices with duSwayed(world, root, scale, sway, wind, leafCard) in your vertex stage, where sway is the prop's (x: 1 tree, 2 plant, 3 cloth, 0 still; y: its height; z: half its width, in meters in its own space). Call it in your shadow vertex function too, or the shadows stand still while the trees thrash. Every wave turns a whole number of times an hour, so nothing twitches when the clock wraps.
Related: the sky by the hour, weather, instancing.