alpineMaterials.package
- .metadata17 B
- AlpineBaker.module
- AlpineBuild.module
- AlpineCollections.module
- AlpineMaterials.module
- AlpineMaterialsTable.module
- AlpineRecipes.module
- README.md14.3 KB
- alpine.materialCollection
- docs
- materials
- package.yaml2.4 KB
- shaders
- tests
- textures
This package holds more than this page lists. See all of its files in its world.
README.md
alpineMaterials
The surfaces of a walkable alpine mountain, at real scale: forest floor, scree, meadow, granite, wind-rippled snow, trail and wet lake shingle for the ground; granite with snow lying on its tops for boulders and outcrops; conifer needle cards, grass, flower and shrub atlases for the plants; conifer barks; log-cabin walls, shingles, slate, a snow-covered roof and wrought iron for the huts; and a still glacial lake. Every surface answers in three looks (real, painted, toon) and four seasons from one call, and never answers nil.
The package ships 27 materials no installed collection has and borrows 8 more by their collection names (fresh snow, forest floor and cliff rock under those names, plus snow on branches, Scots pine bark, deadwood, rough timber and dry-stone wall) from Terra Firma (groundMaterials), Heartwood (woodsMaterials) and Bedrock (stoneMaterials), so nothing is duplicated. It draws with forestMaterials' foliage, solid and stylised shaders, Terra Firma's groundSurface, animatedMaterials' animWater, and one shader of its own, alpineSnowCap (snow by world normal).
local AM = require("alpineMaterials.AlpineMaterials")
-- a material for a Model or an instanced draw
part.material = AM.get("scree") -- summer, real
part.material = AM.get("needlesLarch", { season = "autumn" }) -- golden larch
part.material = AM.get("logWall", { look = "toon" }) -- stylised cabin wall
part.material = AM.get("snowDustedRock") -- boulder with snow on its top
part.material = AM.get("snowRoof", { season = "winter" }) -- the cabin roof in winter
part.material = AM.get("freshSnow") -- Terra Firma's fresh snow, by its own name
if AM.leafless("needlesLarch", season) then --[[ draw no needles ]] end
-- TerrainStream layers: { albedo, normal, mask, tint, tiling, color }
local layers = {}
for _, name in AM.TERRAIN do layers[name] = AM.terrainLayer(name) end -- or AM.terrainLayer(name, "toon")
layers.shore = AM.terrainLayer("lakeShingle")
-- atlas cells: card UVs (0..1) map to u' = (col + u) / cols, v' = (row + v) / rows, row 0 = top
local gentian = AM.ATLAS.alpineFlowers.cells.gentian -- { 0, 0 } in a 3 x 3 sheet
Surfaces
AM.surfaces() lists all 35 names below and every one resolves to the material it names, in every look and season (the tests check both this table and AM.surfaces()). AM.group(surface) answers terrain, rock, needles, snow, bark, flora, building or water; AM.tileSize(surface) gives the metres per repeat of a shipped tile; AM.source(surface, opts) says where an answer came from (own:, runtime:, installed:).
| Surface | What it is | Shipped or borrowed |
|---|---|---|
needleLitter | conifer forest floor: rust needles (a few cm), cones, twigs, moss and lichen on dark humus | shipped terrain tile, 1 m repeat |
scree | loose angular grey granite and rust-ochre gneiss, stones 5-30 cm in grey and ochre grit | shipped terrain tile, 2.4 m |
alpineMeadow | short dense alpine turf with gentians, buttercups and white star flowers | shipped terrain tile, 1.8 m |
lichenGranite | grey speckled granite bedrock with green, yellow and orange map lichen | shipped terrain tile, 2.5 m |
windSnow | wind-rippled snow, faint blue in the troughs; the ripples keep their heading | shipped terrain tile, 3 m |
alpineTrail | worn path of packed grey-brown grit and small stones | shipped terrain tile, 2.4 m |
lakeShingle | wet lake shore: water-rounded grey and grey-brown pebbles 2-12 cm in damp grit, darker and glossier than scree (roughness ~0.25 on the pebble tops) | shipped terrain tile, 1.5 m |
snowDustedRock | lichen granite with fine powder snow on its up-facing parts: full on flat tops, none on steep faces | shipped rock material on alpineSnowCap, rock 2.5 m, snow 1.5 m |
needlesSpruce needlesFir needlesPine needlesStonePine needlesMugo | conifer spray cards, alpha cut, sway by vertex alpha | shipped foliage cards, 1024 px |
needlesLarch | soft larch tufts: fresh green spring, green summer, gold autumn, bare winter | shipped card + 3 seasonal albedos |
alpineGrass | grass and sedge tussock: spring, summer, straw autumn, bleached winter | shipped card + 3 seasons, 512 px |
alpineFlowers | 3×3 atlas: gentian, edelweiss, arnica / alpenrose, saxifrage, cottonGrass / campanula, globeflower, alpineAster | shipped atlas, 1536 px |
alpineShrubs | 2×2 atlas: alpenrose, juniper / dwarfWillow, greenAlder (bottom row yellows in autumn) | shipped atlas + autumn and winter |
barkSpruce barkFir barkLarch barkStonePine | conifer barks | shipped solid tiles, 0.5-0.7 m |
logWall | weathered horizontal round logs with chinking, 5 logs per repeat | shipped solid tile, 1.6 m |
woodShingles | split larch shakes in overlapping rows | shipped solid tile, 1 m |
slateRoof | overlapping hand-split dark slates | shipped solid tile, 1.2 m |
snowRoof | snow lying on every row of larch shingles, the dark lower edge of each row still showing | shipped solid tile, 1 m (rows along U) |
ironWrought | dark forged iron; rust spots are non-metal | shipped solid tile, 0.3 m (512 px) |
mountainLake | still glacial lake: pale turquoise shallows deepening to dark teal, the rock-flour turquoise of a glacial lake in the deep water, slow ripples, fresnel sky | shipped material on animWater (no textures) |
freshSnow | fresh snow ground (toon: toonSnow) | borrowed: Terra Firma groundMaterials.materials.freshSnow |
forestFloor | broadleaf/mixed forest floor (toon: toonDirt) | borrowed: Terra Firma groundMaterials.materials.forestFloor |
cliffRock | cliff rock faces (toon: toonRock) | borrowed: Bedrock stoneMaterials.materials.cliffRock |
snowLoad | opaque snow on branches and roofs | borrowed: Terra Firma freshSnow (toon: toonSnow) |
barkPine | Scots pine bark | borrowed: Heartwood woodsMaterials.materials.pineBark |
deadwoodSilver | sun-bleached silver deadwood | borrowed: Heartwood woodsMaterials.materials.driftwood |
roughTimber | rough weathered timber | borrowed: Heartwood woodsMaterials.materials.weatheredPlanks |
stoneWall | dry-stone wall | borrowed: Bedrock stoneMaterials.materials.dryStoneWall |
Borrowed surfaces answer the collection's own material in the real look, the collection's toon material in the toon look, and a forestStylised build from the collection's albedo and normal in the painted look.
Every collection material by name. Beyond the surfaces above, AM.get answers any material of Terra Firma, Bedrock and Heartwood by its own name, the same three ways: AM.get("packedSnow"), "ice", "gravel", "moss", "granite", "riverPebbles", "cliffRockTriplanar", "pineBark", "pineBoard", "basalt" and the rest. Plain words work too: slate (cleft slate), pineBoards, pebbles, triplanarCliffRock, needles (needleLitter), stillWater or water (mountainLake), snow, rock, meadow, trail, shingle (AM.ALIASES lists them). AM.source(name) says where an answer came from; only a name nothing knows answers the granite fallback.
Terrain layers
The seven terrain tiles (AM.TERRAIN: needleLitter, scree, alpineMeadow, lichenGranite, windSnow, alpineTrail, lakeShingle) use Terra Firma's groundSurface, which places texture by object-space metres, so mesh UVs don't matter and one repeat covers the tile size above, hex-tiled so no repeat shows. Paint them straight onto rocks and ground meshes with AM.get.
For a TerrainStream (or forestKit's Ground), AM.terrainLayer(name, look?) returns { albedo, normal, mask, tint, tiling, color }: texture identities, the colour multiplier the material uses, metres per repeat, and a flat mean colour for renderers that draw a layer without maps. It answers for the seven tiles and for the borrowed Terra Firma ground freshSnow and forestFloor. The mask follows the engine's terrain layout (R metallic, G occlusion, B height, A smoothness); lakeShingle's high smoothness is what makes it read wet. The toon look gives the collections' flat toon ground, albedo only.
snowDustedRock and cliffRock are rock materials, not terrain layers: a terrain already chooses rock and snow by slope itself (paint lichenGranite on steep ground and windSnow or freshSnow on flat ground). Put snowDustedRock on boulder and outcrop meshes.
Each tile was checked on a 6 × 6 m plane and a boulder at 1.7 m eye height and from 10 m against design/references/alpine/ground.png. The tint and tiling in AlpineMaterials.RECIPES hold its mean albedo to real ground (forest floor ~0.1, meadow ~0.1, wet shingle ~0.085, scree and trail ~0.2, granite ~0.22, fresh snow ~0.8).
Snow by slope: alpineSnowCap
snowDustedRock draws with the package's own shader alpineSnowCap (no installed collection or engine shader blends by world normal; the engine's pbr_layered blends by a mask texture only). Both layers are projected from three sides in the object's own space in metres, so a boulder needs no UVs, and the snow follows the world normal, so it stays on top whichever way the boulder is turned: full cover on flat tops, thinning over the shoulders, none on faces steeper than about 60°. The rock's height map fills hollows first and a slow noise breaks the snow line. snow_amount (0 bare … 1 snow far down the slopes, default 0.6), snow_soft, height_bias, breakup and breakup_scale are material properties; the painted and toon looks flatten and posterise the same maps (flatten, posterise) and harden the snow line.
Channel views
Colour, albedo, roughness and normal of every shipped material, on a sphere (cards on an upright plane), one sheet per group:
- terrain tiles: needleLitter, scree, alpineMeadow, lichenGranite, windSnow, alpineTrail
- foliage cards and atlases: the six needle cards, alpineGrass, alpineFlowers, alpineShrubs
- solids and water: the four barks, logWall, woodShingles, slateRoof, ironWrought, mountainLake (animWater lights itself, so its albedo and roughness views read empty)
- new surfaces: snowDustedRock, lakeShingle, snowRoof
Texture memory
70.1 MB of GPU texture memory (UASTC, mips included; AlpineBuild.textureMemory() measures it). That is the terrain tiles at 1024 px albedo and normal plus a 512 px mask, solids at 1024 px plus a 512 px ORM (iron at 512 px), needle cards at 1024 px with 512 px normals, alpine grass at 512 px, flowers at 1536 px and shrubs at 1024 px. lakeShingle, snowRoof and snowDustedRock's snow layer add 3 MB each; snowDustedRock reuses lichenGranite's maps for its rock. The collection records each material's share as textureKB.
Looks and seasons
- Real, summer is the material asset in
materials/for every shipped surface. - Seasons recolour cards: larch, alpine grass and shrubs have their own seasonal albedos on
forestFoliage, with translucency tinted by season. Ground, rock, bark and building surfaces don't change by season: for winter, usesnowDustedRockfor boulders,snowRooffor roofs, andwindSnoworfreshSnowfor ground. - Painted and toon tiles and cards are built on forestMaterials'
forestStylisedfrom the same textures. Toon terrain uses Terra Firma's and Bedrock's toon ground, painted meadow useshandPaintedGrass, snowDustedRock usesalpineSnowCapflattened and posterised, and the lake usesanimWater's toon bands in glacial colours. - Leafless:
needlesLarchis bare in winter andalpineFlowersin autumn and winter (AM.leafless). Nothing else is ever bare.
Runtime looks are built once per machine and cached in module state, so a module reload never releases a handle a Model still holds.
Known limits
- The terrain normal, height and AO maps are derived from albedo luminance, not scanned: stones and needles have depth, but no true parallax or silhouette. Put rock and plant meshes on top for relief.
lichenGranite(and so the rock ofsnowDustedRock) is a fine-grained surface without large joints or fractures. Cliff faces and slabs read best when the mesh carries the big forms.snowDustedRockreads cover from the mesh's normals: a very low-poly boulder gets a faceted snow line. The snow adds no thickness to the silhouette.snowRoofis a texture of snow on shingles; it does not drift off the roof edge or hang over it. Model a snow lip on the mesh if the eaves need one.- Cards are single sprays on a full frame. Build branches from several cards; one card isn't a tree.
- The lake is a surface shader, not a volume: depth colour comes from the material's
depthandabsorb_distanceand doesn't see the real lake bed.
Making and changing it
The source pictures were generated with image_gen (prompts in AlpineRecipes.PROMPTS) and baked by AlpineBaker. Tiles are made seamless (minimum-error cuts) and de-lit, height is read from luminance, and normal plus AO or mask are derived. Cards were generated on a magenta or cyan screen and keyed into alpha. To regenerate, put the source pictures in <world source>/local/alpineSources/ and run require("alpineMaterials.AlpineRecipes").bakeAll() inside a task (snowDustedRock_snow is the snow layer of snowDustedRock). To change tiling, tint or roughness, edit AlpineMaterials.RECIPES and run require("alpineMaterials.AlpineBuild").all(), which rewrites the materials, the collection and the resolve table. Tests are in tests/alpineMaterials.testSuite.
Dependencies: forestMaterials (shaders), groundMaterials, woodsMaterials, stoneMaterials, animatedMaterials and materialLibraryKit (the materialCollection type), all addressed by package name. Every asset is resolved through the generated literal table AlpineMaterialsTable, and no code names an absolute path, so the package works wherever it is installed, including under another world's deps/.