Log inGet started
Package

alpineKit.package

This package holds more than this page lists. See all of its files in its world.

README.md

alpineKit

A whole walkable alpine mountain for your world, in one component. Pine and spruce forest at the bottom that thins into stunted trees and alpine meadow, then cliffs and scree, then snow above a snow line; a cold blue lake in a basin with an inflow stream; snowy ranges on the horizon; and a signposted hiking trail from a forest trailhead past a cabin, along the lake, over a footbridge, up to a lookout and across the scree by cairns to a summit cross. It comes with dawn, midday, dusk and night lighting, snowfall, a colour grade, valley haze, wind, forest, lake and night ambience that follow the time and where you stand, and footsteps that sound like needles, meadow, scree, rock, snow, gravel, wood or water. Size, snow line, density and seed are each one setting, and every player builds exactly the same mountain from the same seed.

Drop a mountain into your world

Paste this into an empty world (the editor's run box, or inside content() of a scene's build.luau):

entity.spawn("Mountain").component.add("alpineKit.Mountain", {
    size = 640, snowLine = 0, density = "normal", seed = 7,
    mountainType = "lakeValley", forestMix = "spruceForest", season = "summer", look = "real",
})
entity.spawnSynced("WorldClock").component.add("WorldClock", { dayLengthMinutes = 30, startHour = 10.5, skyMode = "engine" })
entity.spawn("AlpineAtmosphere").component.add("alpineKit.AlpineAtmosphere", {})
entity.spawn("Sky").component.add("ProceduralSky", { exposure = 1.6, turbidity = 2.4, syncSunToLight = false })

The first build of a new setting shapes, erodes and paints the ground on the engine's terrain system (half a minute to a minute in the editor) and saves it into your world under alpineMountains/, with its plan (trail, lake, bands) beside it. After that every machine loads those saved files, so build it in the editor before you publish. A machine places the forest only once the saved ground answers its own heights (it waits for it, and tries again if it is not there within a minute), so a slow load never puts the trees on flat ground. Press play: a player who lands below the ground is set on top of it. To start players at the trailhead, see the guide How to make mountains for my game.

What you set

SettingValuesWhat it does
size192-1536 (m)the side of the square mountain
snowLinemetres above the valley floor, 0 = the type's ownwhere the snow starts
densitysparse, light, normal, dense, lushhow thick the forest, shrubs, rocks and flowers grow
seedany whole numbereach seed is a different mountain, the same seed always the same one
mountainTypelakeValley, craggyRidge, glacierPeak, roundedFell, forestedValleythe shape
forestMixspruceForest, pineLarch, mixedMontane, stonePineLarchwhich conifers grow
seasonsummer, autumn, winter, springautumn turns larches gold, winter snows everything
lookreal, painted, toonrealistic or stylised surfaces and props
lake, trail, backdroptrue/falsethe lake and stream, the route and its props, the far ranges
cabinStylelogHut, stoneHut, aFramethe cabin by the lake
quality0.3-1draw distance (nothing moves or stops colliding)

What is inside

  • Mountain (component) and MountainBuilder (module): build, update and tear down a mountain; MountainBuilder.build(opts) from code.
  • MountainShape, MountainTypes, Layout, Surfaces, Backdrop: the ground cook, the five mountain recipes, the trail planner and height bands, the painted surfaces (with ochre and rust strata across the faces), the far ranges that carry on from the mountain's own edge into forested foothills.
  • The trail planner searches by grade and by heading: the path climbs at a hiking grade, turns at most 30 degrees per 4 m (a hairpin is a wide arc), pays for every hairpin so the legs run long and stand well apart, never doubles back at a stop, and lines up with the footbridge. Layout.TURN_COST and Layout.MAX_TURN tune it. Where the very top is a spire no hiking path can reach, the route ends on the highest walkable ground near it (a fore-summit) and the summit cross stands there; the bed is only held above the lake's water along the lake itself; and the lookout is a level landing beside the trail, so a sharp turn there is on flat ground.
  • AlpineRules, ForestMixes, MountainSite: the scatter rules by height and steepness, the forest mixes, the questions you can ask the ground (height, slope, surface, footstep surface, distance to the trail and the lake).
  • Pois: the trailhead board, signposts with walking times, waymarks, cabin, bench, footbridge, lookout, cairns and summit cross, each standing clear of the trail bed.
  • TrailWalker (component): walks a player's body up the trail by itself and reports stalls, drops below the ground and strays from the path. Use it to check a new mountain end to end, alone or with several players at once. It drives only a body this machine owns: on the other players' machines the walker that rides along on your body stays silent, so each player's walk steers only their own character.
  • AlpineAtmosphere (component), Atmos, Ambience, Footsteps: lighting and sky presets on worldClockKit's shared clock, the ambience presets on soundstage, and the mountain's footstep surfaces.
  • Guides: How to make mountains for my game and Snowy mountain level with a lake. Tests: tests/alpineKit.testSuite.

It installs alpineProps (the conifers, shrubs, flowers, rocks and cabin), alpineMaterials (the alpine surfaces) and forestKit (which brings forestProps, the material collections, worldClockKit and soundstage).

Time of day, weather and sound

local Atmos = require("alpineKit.Atmos")
Atmos.setTime("dawn")                  -- dawn | midday | dusk | night, for every player
Atmos.setWeather("snow")               -- clear | cloudy | snow | blizzard

Every player, the same mountain

The ground is one saved terrain file and one plan file; the props are placed from the plan by a pure function of the seed, so two players see the same trees in the same places and bump into the same trunks and boulders. mountain.stats.fingerprint is a short hash of every placement: equal fingerprints on two machines mean equal mountains. Time and weather are worldClockKit's shared clock; footsteps are soundstage's, heard from every walker. alpineKit adds two ground sounds of its own (pine needles and scree, recorded for the kit) and answers only for the mountain's own colliders: the ground, the lake, trunks, stones and the trail's props. Every other floor, even one standing on the mountain, is left to soundstage and to other kits (forestKit's forest ground, a floor named "Cabin Floor Planks"), so they sound exactly as they do without alpineKit and their own checks keep passing beside it.

Known limits

  • The first cook of a new setting needs a GPU that can run compute, and is meant to happen in the editor.
  • Steep rock faces show stretched texture (#23596): the engine's terrain paints its layers from straight above and has no side projection, so a 60-degree face stretches its texture about twice over. The trail itself never crosses such ground.
  • In a web browser the saved ground never draws, so the mountain does not build there (#23597). Build and play it in the desktop editor.
  • The stream is carved into the ground; it has no flowing water surface yet. The lake is drawn by the kit (LakeSurface), not by the terrain's own water sheet, which could stand above the trail in cuttings by the shore.
  • In snow and blizzard the kit draws its own sky: an overcast cloud deck that fades in with the snowfall and darkens toward night (Atmos.OVERCAST sets its colour and density). Falling flakes show in motion only, not in a still capture. Snowfall does not whiten a summer mountain: snow lies on the ground and the branches with season = "winter".
  • There are no clouds yet. The engine's cloud layer can be switched on with Atmos.configure({ clouds = true }), but it currently draws its own dark slate sky behind the clouds, so it is off by default. The fiery clouded dusk sky of the reference is the gap that leaves.
  • On a peak whose top is a spire, the summit cross stands on the highest walkable ground below it (on the showcase, 120 m under the 380 m top), not on the very tip.
  • The default walking character sometimes draws a second, cone-shaped body at the player (#23010).
  • Frame time is set by how many pixels the graphics card fills (alpha-cut needle cards, the painted ground, shadows), not by scripts, which take about 2 ms a frame. Measured in the editor's play mode with two players walking, on an integrated Intel GPU running a development build of the engine: about 70 ms a frame in a 1280 x 720 window and about 360 ms in a 3200 x 1756 one.
  • Installing pulls in forestKit with its kits (about 19,500 files in all), which takes about a minute (#21420).

1.0.15 (first sent as 1.0.14, changed on review in PR #3)

  • keepClear on the Mountain component: extra circles { x, z, r } in world metres that the forest, shrubs and rocks keep empty, beside the trail's own points of interest. A course, a camp or buildings a scene stands on the mountain get no tree growing through them (and no trunk collider inside them). Changing it rebuilds the props like any other setting (the saved ground is not re-made). A tree only keeps its trunk out of a circle, and its crown can reach about half its width inside: make r the space you need plus a crown (5 to 6 m for the big spruces). Entries that are not tables with finite numbers and r above 0 are left out. Example: keepClear = { { x = -32, z = -94, r = 7 } }.