# 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)
```luau
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
```luau
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
| Group | Names (what each reuses) |
|---|---|
| woods | `hinokiPlank`, `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` |
| plaster | `whitePlaster` (shikkui), `earthenPlaster` (tsuchikabe), `namakoWall` (diagonal tile + raised plaster joints over the shikkui maps), `plasterStained` |
| roofs | `kawaraTile`, `kawaraTileDark` (ibushi silver), `kawaraRidge`, `thatch` (Brick and Mortar roofThatch maps), `cypressBark` (hiwadabuki), `copperPatina` |
| interior & cloth | `tatami`, `tatamiEdge`, `shojiPaper`, `fusumaPaper`, `lanternPaper`, `lanternPaperRed`, `norenIndigo`, `norenPersimmon`, `norenWhite`, `norenRed`, `norenGreen`, `norenBrown`, `strawRope`, `strawBale`, `strawMat` |
| stone | `dryStone` (ishigaki), `cutStone`, `granite`, `riverPebbles`, `rakedGravel` |
| ground & water | `packedEarth`, `packedEarthWet`, `mud` (Terra Firma wetMud), `paddyWater` (with rice shoots), `paddyMud`, `riverWater`, `moatWater`, `mossGround` (Terra Firma moss), `grassMeadow` (Terra Firma longGrass), `riceStalk` |
| metal & trim | `bronzePatina`, `blackIron`, `goldLeaf` |
| foliage cards | `bambooLeaf`, `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`).