Log inGet started
Package

arcticProps.package

Newest version

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

README.md

arcticProps

High-Arctic props for tundra and ice worlds: 32 kinds, from 5 cm saxifrage flowers to a 28 m layered ice-shelf cliff wall, every one in five looks (realistic, painted, cartoon with ink outline, low-poly, pixel). Each kind has at least three seeded shapes (the hut and the mast have two; lake cracks and flags have six), three baked levels of detail, colliders where a player needs them (box colliders on everything walkable) and a footstep surface. Materials come only from arcticMaterials. Place one prop with the ArcticProp component; arcticKit scatters them over a whole tundra; every kind is also registered with forestProps' Props, so forestKit's instanced renderer can draw them too.

Quick start

Paste into an empty world's run box:

-- an inuksuk, a research hut with its weather mast, a sled and a fuel cache
local function place(kind, x, z, fields)
	local e = entity.spawn(kind, { position = { x, 0, z } })
	local f = fields or {}
	f.kind = kind
	e.component.add("arcticProps.ArcticProp", f)
	return e
end
place("inuksuk", 0, 0)
place("researchHut", 8, -4)
place("weatherMast", 13, -6)
place("sled", 5, 2, { variant = 3 })
place("drumCluster", 12, -1, { variant = 2 })
place("lichenBoulder", -4, 3, { look = "cartoon" })

A whole tundra with these props scattered over it comes from arcticKit:

entity.spawn("Tundra").component.add("arcticKit.Tundra", { size = 512, seed = 7 })

Every kind side by side: open PropGallery.scene, or entity.spawn("gallery").component.add("arcticProps.PropGallery", {}).

From code

local AP = require("arcticProps.ArcticProps")
AP.kinds()                         -- all 32, catalog order
AP.kindsOf("ice")                  -- ice, snow, rock, structure, remains, plant (forestProps categories work too)
AP.info("researchHut")             -- { kind, category, variants, radius, height, collider, colliders, surface, walkable, lodBand, budget, byVariant }
AP.parts("serac", { look = "pixel", variant = 2, lod = 0 })   -- { { mesh, material, part, surface, spin? } }
AP.tris("shelfCliff", { look = "realistic", lod = 1 })        -- triangles drawn
  • look: "realistic" | "painted" | "cartoon" | "lowpoly" | "pixel"; nil or "auto" follows the world look (arcticMaterials.ArcticLook.get()).
  • outline = false drops the cartoon ink hull; snow = false drops the snow dusting parts.
  • info(kind).collider is one { shape = "box", size = {x,y,z}, offset = {x,y,z} } in prop space at scale 1 (the median variant); info(kind).byVariant[v].colliders lists every box of that variant (the hut has one per wall plus roof, deck and steps; the ridge has three stepped boxes up to its crest). Plants and small things have none.
  • info(kind).lodBand = { near, mid, far } metres: LOD1 from near, LOD2 from mid, gone past far.
  • Parts with spin = { pivot, rate, mode } (the mast's anemometer cups and wind vane) are baked in prop space, so an instanced renderer can draw them still; ArcticProp turns them about their pivot.

ArcticProp component

FieldMeaning
kindany kind AP.kinds() lists
variantshape 1..n (wraps); used when seed is 0
lookauto (world look, rebuilds when it changes) or one of the five
seednon-zero picks the variant and a yaw from the seed
lodauto (MeshLod swaps by screen size), or near, mid, far to pin one
collidestatic BoxColliders from the catalog, tagged forestSurface = footstep surface
outlinecartoon ink outline on or off
snowsnow dusting on rocks, ice, roofs and drum lids

Children are temporary and rebuilt from the synced fields, so every player sees the same prop and a reload rebuilds it.

Kinds

Triangle counts are read from the baked indexes (range over variants, all parts, ink excluded). Budgets for the browser at 30 fps: plants 300, rocks and small ice 2000, structures and big ice 6000, shelf cliff 8000 at LOD0; LOD1 about 30 to 40 percent, LOD2 about 10 percent.

KindCategoryforestPropsVariantsLOD0LOD1LOD2LowpolyPixelFootstepCollider
pressureRidgeiceice32282-35171204-2108221-415613-10871248-1784icewalkable
iceRubbleiceice3386-779329-55095-128219-3881082-1296icewalkable
seraciceice31879-20441078-1304102-114161-1781494-1866icesolid
iceBlockiceice31041-1197260-29936-4020-29470-670icewalkable
shelfClifficecliff35268-53161520-1552152716-7441472-1960icewalkable
crevasseLipiceice336001248288600200-418icewalkable
lakeCrackiceice6276-530240-43640-82140-27854-678icenone
snowDriftsnowsnow3192251298162148-208freshSnowwalkable
sastrugiPatchsnowsnow319225127220012-144crustnone
cornicesnowsnow3780364130208724-952freshSnowwalkable
lichenBoulderrockrock3599-635146-16032321054-1092rockwalkable
erraticrockrock3781-828125-13460-6365-691232-1402rockwalkable
frostRockPilerockrock3689-1193393-702119-208474-7901078-1626rockwalkable
rockOutcroprockrock3433-1647316-433134-186235-3391532-1908rockwalkable
inuksukstructurestructure3626-1260622-745192-228268-3481144-1414rocksolid
researchHutstructurestructure2292614584205601228-1308woodwalkable
weatherMaststructurestructure2676-1178584-806272-276287-4771124-1288metalsolid
sledstructurestructure3636-962420-61496-188144-236256-608woodsolid
fuelDrumstructurestructure3588-630180-204608076-156metalsolid
drumClusterstructurestructure32460-4452792-1524240-540320-680396-882metalsolid
markerStakestructurestructure31413692824-68woodnone
flagstructurestructure6108-70033-25821-8025-10324-648metalexpedition pole
whaleBonesremainslog3808-888424-552120-144200-248754-2344rocksolid
caribouAntlersremainslog3350-732216-46430-68156-320658-1028scrubnone
driftwoodremainslog3304-1520102-51032-16040-200108-664woodsolid
dwarfWillowplantbush327011226112240-270scrubnone
cottongrassplantgrass3200-27264-763280-104180-264scrubnone
mossHummockplantmoss312832832234-278scrubnone
purpleSaxifrageplantflower3208-288922892112-280scrubnone
arcticPoppyplantflower3108-22840-882856-104178-236scrubnone
mossCampionplantflower3228-28811218112240-274scrubnone
sedgeTuftplantgrass3108-192561248242-292scrubnone

Categories registered with forestProps: the standard rock, bush, grass, flower, moss, log, cliff, structure, plus new ice and snow.

Sizes are real: inuksuk about 1.6 to 1.8 m, research hut 4 x 3 m and 3.3 m to the stovepipe cap, drum 0.88 m tall, weather mast 4.5 or 6.5 m, pressure ridge 9 to 18 m long, shelf cliff 24 m wide and 21 to 28 m tall (its ends share one profile so sections tile side by side along a coast, face toward +Z), flowers 5 to 15 cm.

Crevasses, lake cracks and flags

crevasseLip is a crevasse you can look into: a jagged slot 15, 22 or 30 m long along the prop's +Z (variants 3, 1, 2), 1.9 to 3.2 m across, with overhanging snow cornice lips on both edges, a band of layered firn under them, blue ice walls that ledge and narrow as they drop and darken to blue-black, and a near-black floor 3.6 to 6 m down. Its ends are snow ramps (grade 0.72) so anyone who falls in walks out. A snow apron runs 6.4 m out from each wall, its outer edge buried 6 cm under the ground. The walls go below ground level, so the ground under it must be cut for the slot to open: AP.crevasse(variant) answers the cut at scale 1 (floor(u) depth and wall(u) half-width along the axis, full, apron, gap): flat at the prop's origin under the apron, and floor(u) + gap deep within wall(u) * 1.1 + full of the axis. arcticKit's tundra does this itself (TundraCrevasse). Colliders: four chord boxes per side hold the lips and walls (they never stand out into the slot) and one box per side under the apron holds the cut ground; the floor and ramps are the real ground. Placed alone on uncut ground it reads as a lipped scar in the snow.

lakeCrack is a flat crack decal for lake ice, 6 mm above the ice, about 8 to 15 m across: variants 1 to 3 are bright white-cyan fractures for clear black ice (a radial star with a spider web of rings, a long pressure crack doubled over part of its run with a refrozen grey band and feather fractures, a polygonal network), 4 to 6 the same forms in blue-grey for white ice. No colliders, no shadows (info("lakeCrack").shadow == false); its pixel look is a flat raster, not voxels.

flag stands on its own, in three forms and two colours each:

VariantFormColourHeightCollides
1expedition flag on a guyed aluminium pole, snow collarred, white band2.9 myes
3expedition flagblue, white band2.6 myes
2survey pennant on a wooden lath, flagging-tape tailorange1.75 mno
5survey pennantyellow1.55 mno
4small marker flag on a steel wirelime0.92 mno
6small marker flagred0.78 mno

The cloth is baked in a wind-blown curve flying toward the prop's local +X (static: arcticMaterials' canvas has no wind sway). Place one flying downwind:

local AP = require("arcticProps.ArcticProps")
local wind = { 0.3, -0.95 }                       -- the way the wind blows
local e = entity.spawn("flag", { position = { 4, 0, 2 }, rotation = { Transform.quatFromAxisAngle(0, 1, 0, AP.flagYaw(wind[1], wind[2])) } })
e.component.add("arcticProps.ArcticProp", { kind = "flag", variant = AP.flagVariant("pennant", "yellow") })

AP.FLAGS lists the forms and colours; AP.flagVariant(form, colour?) picks the variant.

Looks

  • realistic, painted, cartoon share the smooth meshes and differ by material (arcticMaterials' realistic, painted, cartoon). Cartoon adds an ink outline: a baked inverted hull (the surface pushed out along welded normals, wound inward) drawn with arcticMaterials' ink surface, the same technique the published toon content uses.
  • lowpoly draws its own bake: a deliberately coarse cage of each prop (fewer facets, fewer stones, low subdivision) with every triangle split off and shaded by its face normal, one flat colour per face, with arcticMaterials' flat-colour lowpoly materials.
  • pixel draws a voxel bake: all parts of a prop sampled onto one grid (about 10 to 44 cells across, coarser per LOD), each cell owned by the part with most surface in it, only faces toward open air kept and merged into rectangles of one colour, with arcticMaterials' point-sampled pixel materials. That gives the blocky read of design/references/arctic/styles_sheet.png.

Baking

Meshes are baked files (meshes/<kind>/<kind>_v<variant>_<set><lod>_<part>.mesh, sets s smooth, l lowpoly, p pixel, i ink), so every machine loads identical geometry. The generators (IceGen, StoneGen, CampGen, RemainsGen, PlantGen, on top of Shapes and alpineProps' GroundKit) and ArcticBake are authoring tools; the game only reads the Baked* indexes. To change a kind, edit its generator and run require("arcticProps.ArcticBake").run({ kinds = { "serac" } }), one kind at a time.

Tests

tests/arcticProps (tools.use("tests", "run", "arcticProps")) checks registration, every kind x look x variant x LOD resolving to baked meshes and live materials, the outline and snow switches, distinct meshes per look, triangle budgets, colliders on walkable kinds, the mast's spinning parts, and the component (rebuild on look change, seeded variants, rays landing on walkable colliders).

Known limits

  • In the browser a first sight of many new meshes can hitch while they load (#22751); a whole gallery streams in over a few seconds.
  • Destroying an entity whose ArcticProp parts carry MeshLod logs one harmless "component this proxy names was removed" error per part from the engine's MeshLod onDestroy. Changing fields to rebuild does not.
  • Plants are true to scale (5 to 40 cm), so they read only up close or in numbers; scatter them in drifts.
  • The pixel look of very flat kinds (sastrugi patch) is a near-flat slab of blocks: their relief is smaller than a cell.
  • Spinning mast parts only turn on an ArcticProp; instanced renderers draw them still.