Log inGet started
World

Tsukikage Castle Town: A Sengoku Town of Rooftops, Temples and Rice Terraces, with a Town Builder

README.md

sengokuMaterials

Surfaces for a late-16th-century (Azuchi-Momoyama) Japanese castle town: 60 materials (54 real-scale surfaces and 6 leaf cards), each in four looks: realistic (default), weathered (sun-bleached grey wood, stained plaster, mossy tiles), festival (realistic with brighter cloths and stronger lantern glow) and toon (flat cel bands, toonBlocks' toon light). Every surface also turns wet in the rain.

Version 1.0.0.

Put a surface on something (empty world)

local SM = require("sengokuMaterials.SengokuMaterials")

local floor = entity.spawn("tatamiRoom")
floor.component.add("Model", { model = "cube", material = SM.get("tatami") })
floor.localScale = { 3.64, 0.06, 3.64 }          -- four mats; textures are placed at real size, no UVs needed

local wall = entity.spawn("wall")
wall.component.add("Model", { model = "cube", material = SM.get("whitePlaster", { look = "weathered" }) })
wall.localPosition = { 0, 1.4, 1.9 }
wall.localScale = { 3.64, 2.8, 0.15 }

Materials place their maps by where each point stands on its object, in metres (masonryMaterials' projection), so a 1 m cube, a 10 m wall and a baked prop mesh all show planks, tiles and mats at real size: a kawara course ~0.22 m with 0.3 m columns, tatami 0.91 x 1.82 m with its dark cloth edge, shoji panes 0.3 x 0.25 m.

API

SM.get(name, { look = "realistic" }) -> material identity (string)  -- never errors; unknown name -> visible fallback + one warning
SM.ref(name, { look })               -> material AssetRef (pinned literal)
SM.names() -> { string }
SM.footstep(name) -> "wood" | "tatami" | "stone" | "earth" | "paddyWater" | "gravel" | "grass"
SM.info(name) -> { name, category, footstep, tileMetres, description, reuses?, texturesFrom? }
SM.setGlow(amount)   -- 0..1: lantern papers glow fully, shoji / fusuma ~15 % (light behind screens); every instance, every look
SM.rain() -> number  -- the rain every material currently shows
SM.LOOKS, SM.FALLBACK, SM.isFinal(name, look)

Every answer comes from SengokuMaterialsTable, a literal index (no computed asset.resolve at run time), so components that use it can be published.

Rain

The engine's surface weather (@builtin::systems.weather.weather, driven by worldClockKit's director, a Weather component or weather.set) darkens and adds a wet sheen to everything on screen. sengokuMaterials adds what a post pass cannot: SengokuRain keeps each material's rain property equal to the weather's wetness (one system task per peer, four checks a second, writes only on change), and the shader then

  • soaks porous surfaces darker (earth, thatch, plaster more than lacquer, metal or stone),
  • lowers roughness on everything,
  • fills puddles in the low parts of flat, up-facing ground (packedEarth, packedEarthWet, cutStone, rakedGravel, riverPebbles, mud, paddyMud) and drops expanding rain rings on them,
  • rings the water (paddyWater, riverWater, moatWater). packedEarthWet, paddyMud and mud stay damp whatever the weather. Measured in the gallery: packed earth's median brightness 197 dry → 64 at wetness 0.9.

Surfaces

GroupNames (what each reuses)
woodshinokiPlank, sugiBoard, darkTimber, blackLacquerBoard (shitami-itabari), charredBoard (Heartwood charredWood maps), latticeSlat (koshi slats over sugi), greyWeatheredBoard (Heartwood weatheredPlanks maps), vermilionLacquer (shu lacquer over sugi grain), bambooCulm (Heartwood bamboo maps), bambooSplit, woodShingle
plasterwhitePlaster (shikkui), earthenPlaster (tsuchikabe), namakoWall (diagonal tile + raised plaster joints over the shikkui maps), plasterStained
roofskawaraTile, kawaraTileDark (ibushi silver), kawaraRidge, thatch (Brick and Mortar roofThatch maps), cypressBark (hiwadabuki), copperPatina
interior & clothtatami, tatamiEdge, shojiPaper, fusumaPaper, lanternPaper, lanternPaperRed, norenIndigo, norenPersimmon, norenWhite, norenRed, norenGreen, norenBrown, strawRope, strawBale, strawMat
stonedryStone (ishigaki), cutStone, granite, riverPebbles, rakedGravel
ground & waterpackedEarth, packedEarthWet, mud (Terra Firma wetMud), paddyWater (with rice shoots), paddyMud, riverWater, moatWater, mossGround (Terra Firma moss), grassMeadow (Terra Firma longGrass), riceStalk
metal & trimbronzePatina, blackIron, goldLeaf
foliage cardsbambooLeaf, pineNeedles, mapleLeaf, mapleLeafAutumn, cherryBlossom, reedBlade: alpha-cut, on the mesh's own UVs (0..1 over the card), vertex alpha = sway weight (0 stem, 1 tip), sway with the engine wind, sunlight glows through from behind

Realistic mud, mossGround and grassMeadow answer Terra Firma's own materials; their other looks are this package's, on the same maps. Every other answer is a material this package ships, on one of three shaders:

  • sengokuSurface: engine-lit PBR; maps + analytic patterns (tatami edge, shoji kumiko grid, namako joints, koshi slats, lantern ribs, fusuma gold flecks) + weathering (bleach, grime, moss) + rain.
  • sengokuToon: the same maps and patterns read as flat stepped colour, lit with toonBlocks' cel bands; pairs with toonBlocks' ink outline.
  • sengokuFoliage: alpha-cut leaf cards: wind sway by vertex alpha, back-lit translucency, rain gloss, weathered (dusty) and toon (stepped) looks.
  • sengokuWater: near-mirror shallow water, bed showing through, drifting ripples, rain rings, optional rice shoots.

Gallery and tests

  • sengokuMaterials.SurfaceGallery (scene) / SurfaceGallery (component): every surface in every look on a floor slab, wall and cube, labelled; rain and glow fields to check the wet and night responses.
  • tests/sengokuMaterials.testSuite (9 tests): every name x look resolves to a real material, footsteps, rain reaches every material and follows the weather, night glow, library registration, literal index.

Texture memory

90 textures, all UASTC with mips: 11 hero sets at 1024 px (albedo + normal 1024, mask 512), 17 sets at 512 px and 6 leaf cards at 512 px, about 56 MiB of GPU texture if every surface is on screen. The toon, weathered and festival looks reuse the same maps (no extra memory). Surfaces drawn on Heartwood, Brick and Mortar and Terra Firma maps use those packages' textures.

Rebuilding

Tool code, run from an execute call: SengokuBaker.bake(name, SengokuRecipes.BAKE[name]) re-bakes one set from its generated source picture (kept in local/sengokuSources, not synced; prompts are SengokuRecipes.PROMPT_LEAD + the surface description), SengokuBuild.buildAll() rewrites the material files, the literal index and the collection.

Known limits

  • Heartwood's (woodsMaterials) own materials still render invisible when Heartwood is installed as a library, so charredBoard, greyWeatheredBoard and bambooCulm only borrow its textures, not its materials. Fixing this needs an upstream Heartwood release re-pinned to materialLibraryKit 1.4.x; until then woodsMaterials also cannot be installed here as a package of its own.

Depends on

Versions are the ones this package's package.yaml names, which are the releases installed in this world.

  • materialLibraryKit 1.4.3 (Swatchbook): the surfaces are registered in its material library as the sengoku collection (sengoku.materialCollection/collection.yaml, written by SengokuBuild.writeCollection); the test suite checks Materials.list({ collection = "sengoku" }) and Materials.problems().
  • groundMaterials 1.0.8 (Terra Firma): its GroundBaker is the field toolkit SengokuBaker bakes every texture with (field, fbm, blur, cavity, makePeriodic, packNormal, seamRatio and others). mud, mossGround and grassMeadow draw on its wetMud, moss and longGrass textures (SengokuRecipes), and its materials of the same names are the reuse entries in SengokuCatalog.
  • masonryMaterials 2.0.0 (Brick and Mortar): every sengoku shader (sengokuSurface, sengokuToon, sengokuWater) includes its masonryProjection shader module to place maps at real scale on any object. thatch draws on its roofThatch textures, and several of its materials (plaster, stucco, roofClayPantiles, roofSlate and others) serve as temporary stand-ins while a sengoku material loads.
  • toonBlocks 1.4.5 (Style Cookbook): sengokuToon includes its toonLight shader module for the cel bands of the toon look.
  • @heartwood library, woodsMaterials 1.0.2 (Heartwood): charredBoard, greyWeatheredBoard and bambooCulm draw on its charredWood, weatheredPlanks and bamboo textures (albedo, normal, roughness and metal) on this package's own shader. Its materials are not used, because they render invisible when Heartwood is installed as a library (see NOTES.md).