Ductane v1.4.0
Contents

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)

The clock answers these questions about any time:

MethodReturns
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.

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.