Log inGet started
Package

sengokuProps.package

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

README.md

sengokuProps

Late-16th-century (Azuchi-Momoyama) Japanese castle-town props for any world: machiya townhouses, storehouses, farmhouses, castle keeps and walls, temples, walk-in tea house and castle hall, and the street props around them. Every kind has variants, three baked levels of detail, four looks and colliders that match what is drawn.

Put a machiya in an empty world

-- a ground to stand on, a sun, and a 3-ken merchant townhouse facing the street (local -Z)
local sun = entity.spawn("sun")
sun.component.add("Light", { kind = "directional", intensity = 3, directionX = -0.4, directionY = -0.7, directionZ = 0.5 })
local ground = entity.spawn("ground", { position = { 0, -0.5, 0 } })
ground.component.add("Model", { model = "@builtin::meshes.cube" })
ground.localScale = { 60, 1, 60 }
ground.component.add("BoxCollider", {})

local shop = entity.spawn("shop", { position = { 0, 0, 0 } })
shop.component.add("sengokuProps.SengokuProp", { kind = "machiyaMerchant3", look = "realistic", variant = 1 })
-- change it live: every peer rebuilds from the synced fields
shop.component.get("sengokuProps.SengokuProp").look = "weathered"

SengokuProp fields: kind, look (realistic | weathered | festival | toon), variant (1..n, wraps), seed (non-zero picks the variant for scattering), collide (default on), lit (interior lamps of the tea house and castle hall), detail (auto swaps LODs by screen size; near/mid/far pins one). The parts are local, temporary children rebuilt from the synced fields, so every peer builds the same prop and nothing is saved twice.

Buildings

Local frame for every building: footprint centre on the ground (y = 0), street front facing −Z, 1 unit = 1 m, bays on the ken grid (1.82 m).

KindWhat it isVariants
machiyaMerchant2/3/41.5-storey (zushi-2) shop, 2/3/4 ken. Ground front all dark timber: posts every ken, full-height koshi lattice (3 cm slats, 3 cm gaps) over shoji and a low dark board skirt, an open earthen doma bay with noren on a hook rail, display floor with a granite step stone inside. Tiled pent roof (hisashi) across the whole frontage, eave 2.5 m, 1.05 m deep, round end tiles, flashing ridge, exposed rafters and brackets. Low plaster upper storey with mushiko slatted windows. Main roof kirizuma or irimoya with tile courses, ridge cap, onigawara, a slight upward sweep at the eave corners.gable/irimoya, white/earthen plaster, udatsu, noren colour
machiyaArtisan2/31-storey workshop, front eave 2.35 to 2.6 m (the climb-up houses): propped shutter (age-shitomi), board door with wicket, lattice.eave height, shingle/tile roof, irimoya
machiyaWealthy3/42-storey house with udatsu firewall wings (tile-capped), namako lower walls, full upper storey with lattice and shoji, pent roof at 2.6 m, a kura at the back (info.offsetZ).namako, irimoya, open/closed front
machiyaCornerIrimoya corner house with a second shop face and pent roof on its left side (info.cornerSide = "left").1.5/2 storey, 3/4 ken
nagayaPoor row tenement: 3 to 5 board-walled units under one long roof, stones on shingle roofs.units, shingle/tile
kuraStorehouse: thick plaster on a cut-stone base, namako skirt, kannon doors with their own roof, barred windows.size, namako, stained
minkaThatched farmhouse: 0.7 m thick kayabuki irimoya/hip roof, earthen walls, engawa with a step stone.5 to 7 ken, irimoya/hip
granaryTakakura on posts with rat guards, bamboo ladder (climbable) with a flat stone at its foot.thatch/tile/shingle
waterWheelOvershot wheel on trestles with a flume; the part named wheel turns about local X through info.wheelHub.radius 1.6 to 2.6 m
teaHouseWalk-in chaya: open front with noren and reed screens, earthen doma with benches, a granite kutsunugi-ishi under every front bay (earth 0 → stone 0.22 → tatami 0.45), tatami platform with black-lacquer tables, shoji on the back and both side walls (glow at night via SM.setGlow), board ceiling.3/4 ken, irimoya/gable, tile/shingle/bark
castleHallWalk-in goten: floor 0.75 m on posts, engawa all round, front steps (0.19 m rises), tatami rooms divided by gold fusuma painted with pines, ranma transoms, coffered ceiling, dark posts, tokonoma, door gaps front, sides and between rooms.7 to 9 ken, tile/bark
keepBaseBattered, concave (ogi-no-kobai) dry-stone ishigaki: pillow stones over recessed joints, sangi-zumi long/short corner stones; info.top, info.topRect.size, rough/dressed
keepTierBase/Middle/TopStackable keep storeys (info.next / info.fits carry the sizes): skirt roofs, chidori and kara-hafu gables, black board bands on lower tiers, balcony and gold shachihoko on the top.large/medium/small
keep3/4/5Complete keeps on their stone base (info.tiers, info.top).white/black-boarded
castleWall, castleWallCornerDobei on stone with tile coping and loopholes (info.length).length, style
yaguramon, koraimon, sumiYagura, moatRevetmentGates, corner tower, moat bank (info.length).size
templeHallHondo on a stone podium: bracket sets, deep upturned eaves, veranda with railing, stone steps then wooden steps (rises ≤ 0.2 m), step canopy.size, dark/vermilion columns, bark roof
sanmon, pagoda, bellTower, hokoraTwo-storey gate, five-storey pagoda with sorin, shoro (info.bellHook), wayside shrine.size, colour

Vermilion lacquer appears only on shrines and temples; town houses use dark timber, charred cedar cladding (charredBoard) and, in the weathered look, grey sun-bleached boards.

Looks. realistic; weathered (grey boards, stained plaster patches, sagging ridges, missing round tiles); festival (realistic + a red/white kohaku curtain and chochin along every front eave; hooks are in info.festival for any look); toon (thicker members, coarser tiles, inverted-hull ink outline).

Info for town builders. Props.info(kind) (and .byVariant[v]): footprint, height, climbHints (eaves = { {y, z, x0, x1, what} }, ridge, ladder, baseTop), interior (floors with heights and zones, doors, steps, ceiling), lights, festival, plus the per-kind points above.

API

local Props = require("sengokuProps.Props")
Props.kindsOf("building")                                   -- { "machiyaMerchant2", ... }
Props.info("teaHouse").interior.floors                     -- { {y=0, surface="earth"}, {y=0.45, surface="tatami"} }
Props.parts("kura", { look = "weathered", variant = 2, lod = 0 })   -- { {mesh, material, name, offset?} }
Props.colliders("machiyaArtisan2", { variant = 1 })        -- local-space Collider list

Colliders

Each building answers a short list: boxes for walls, posts, floors, benches and steps, oriented boxes for ladders and ridges, and mesh colliders for every sloped roof, generated from the same roof plane as the tiles and lifted onto the round tiles, so the surface you stand on lies within 5 cm of what is drawn (the test suite raycasts it). Every collider carries sengokuSurface (wood, tatami, stone, earth, grass); roofs carry noNav and walkableRoof; stone bases, koshi lattice fronts, posts and ladders carry climbable. Pent roofs are mesh colliders on the tiles at 2.5 to 2.6 m, so climbKit can mantle onto them from a bale stack or a stall roof. Interiors are open: doorways have no collider, and every raised floor is reached by rises of 0.25 m or less (step stones, steps).

Budgets

Triangle budgets are limits the test suites enforce, summed over all of a kind's parts at one level of detail and taken from the worst look and variant. They are budgets, not measured counts.

CategoryKindsLOD0LOD1LOD2Enforced by
houses: building11 townhouse and town building kinds16,0008,000600sengokuBuildings
houses: farm3 farm kinds16,0008,000600sengokuBuildings
big: castle14 castle kinds70,0009,0001,200sengokuBuildings
big: temple5 temple kinds70,0009,0001,200sengokuBuildings
small props (all 58 kinds)street, light, farm, gate, fence, bridge, nature4,000 unless listed belowfewer than its LOD0no more than its LOD1smallProps

The house limit leaves room for the wealthy house's back kura; a machiya alone stays near 12k at LOD0.

Per-kind exceptions to the small-prop LOD0 budget of 4,000 (from the smallProps suite):

KindLOD0 budgetFar (LOD2) budget
archBridge9,000 (the hero crossing, one or two per town, never instanced in bulk)
bambooCluster13,000
barrelStack12,000
riceBaleStack410,000
riceBaleStack37,000
stallLarge8,000
stallStraw, oxCart, kabukimon, bambooYoung5,000
stoneWallLow3,500
barrel2,600120
toriiRyobu2,500
riceBale1,000120
chochin700120
riceClump25016
reeds, gardenRock4,00060 (reeds), 120 (gardenRock)

stallSmall, well and templeBell are listed in the suite at the default 4,000. The far budgets apply to the bulk kinds placed by the hundred, which must be very cheap at a distance. Measured counts for the main small kinds are in the small-props section.

Rebuilding

Generators: BuildingGen (roofs, walls, lattice, shoji, ridges, gables), BuildingTown, BuildingCastle, BuildingTemple. After a change, rebake with require("sengokuProps.BuildingBake").bakeKind("kura") or .bakeAll() (writes meshes/buildings/<kind>/, the manifest, BakedMaterials and the literal BakedBuildings index the runtime reads). sengokuBuildings (test suite) checks meshes, materials, budgets, collider tags, roof collider fit and the component. The PropGallery scene shows every building in every look.

Small props (street, light, farm, gate, fence, bridge, nature)

58 small kinds, each with 2 to 6 variants, three baked LODs and the four looks. Put one down like any kind:

local e = entity.spawn("stall")
e.component.add("sengokuProps.SengokuProp", { kind = "stallStraw", look = "festival", variant = 2 })
CategoryKinds
streetstallSmall, stallLarge, stallStraw (market stalls; roofs 1.85 to 2.25 m, solid walkable slab collider tagged walkableRoof + noNav, climbable posts, counter as a step), norenShort, norenLong (variant = colour 1 indigo, 2 persimmon, 3 white + crest, 4 red, 5 green, 6 brown), kanbanHanging, kanbanStanding, kanbanRoof, nobori, barrel, barrelStack, crate, basket, bucket, trough, well, ladder (climbable), handCart, oxCart
farmriceBale, riceBaleStack2/3/4 (stepped climbable box colliders, 39 cm risers), firewood, riceClump (instancing-cheap: LOD2 = 8 tris)
lightstoneLanternKasuga, stoneLanternYukimi, stoneLanternOki, chochin, chochinLong, andon, tsuriDoro, lanternString (6/10/16 m), taimatsu
gate / templetoriiMyojin (vermilion 4.6 m, granite, vermilion 7 m, Inari 2.5 m), toriiShinmei, toriiRyobu, kabukimon, slidingGate, bambooGate, templeBell (bonsho + shumoku striker)
fencefenceYotsume, fenceKenninji, fenceBoard, stoneWallLow, fenceBrush (segments tiling along local X, variants 1/2/3 = 1.8/2.7/3.6 m, info.length), fencePost (info.post names the joint post)
bridgearchBridge (12/16/20 m, smooth ramp colliders on the drawn deck), plankBridge, stoneSlabBridge, earthBridge: all span along local Z (info.span), deck meeting y = 0 at the banks
naturebambooCluster, bambooYoung, pineTree, mapleTree, cherryTree, reeds, gardenRock

Looks. weathered swaps to grey boards and tears cloth (noren, nobori, stall noren); festival adds corner chochin and red/white bunting to stalls and a shimenawa with shide to torii and the kabukimon; toon uses chunkier members (x1.3) at LOD 0 plus an inverted-hull ink part (inkHull material). Materials follow the look through PropMaterials.

Anchors. Hanging kinds (norenShort/Long, chochin, chochinLong, tsuriDoro, templeBell) have their origin at the hanging point (info.anchor = "top"); kanbanHanging at the wall mount ("wallTop"); templeBell goes at a bell tower's info.bellHook (info.strikerPivot, info.strikeHeight for animating the striker).

Lights. Every light kind gives info.lights = { { pos, color, radius } } (local; info.lightsByVariant[v] per variant); taimatsu also gives info.fire for a flame effect. Paper and ember parts use the emissive-capable lanternPaper / lanternPaperRed surfaces.

Sway. Cloth (noren, nobori, stall bunting, shide, sudare blinds) and foliage (bamboo, pine pads, leaves, rice, reeds) carry the sway weight in vertex alpha (0 at the rod/base, 1 at the hem/tips). Foliage cards sway through sengokuMaterials' foliage shader; cloth parts are baked with a sway flag (w = 1 in BakedSmall rows) and wear the swaying copies of the cloth materials that sengokuMaterials ships (SengokuSway: compliance = 1 on sengokuSurface / sengokuToon, every look), so noren and banners move in the engine wind and stall cloth bolts stay still. This package keeps no copies of its own.

Fitting to points (SmallGen).

local SG = require("sengokuProps.SmallGen")
local r = SG.lanternString({0, 4, 0}, {9, 4.4, 2}, 0.55, "festival")   -- { parts = { {mesh, material, pos, rot, scale, name} }, lights }
for _, p in r.parts do
	local piece = entity.spawn(p.name, { parent = holder, position = p.pos, rotation = p.rot, temporary = true })
	piece.localScale = p.scale
	piece.component.add("Model", { model = p.mesh, material = p.material })
end
for _, pl in SG.fenceRun("fenceKenninji", {0, 0, 0}, {12, 0, 3}) do
	-- pl = { kind, variant, pos, yaw }: spawn a SengokuProp per placement
end

Budgets (worst variant, LOD0 / LOD1 / LOD2 triangles, realistic). Kinds placed by the hundred are kept tight, and kinds that repeat a piece (bale stacks, carts with bales, lantern strings) draw it one level coarser than the lone kind does:

KindLOD0 / LOD1 / LOD2Test budget (LOD0)
riceClump (v2 = a row of six)192 / 48 / 8250, LOD2 ≤ 16
riceBale888 / 310 / 481000, LOD2 ≤ 120
riceBaleStack2/3/41.9k / 3.7k / 6.2k at LOD0, 288 to 960 at LOD1/24000 / 7000 / 10000
chochin576 / 268 / 84700, LOD2 ≤ 120
lanternString (16 m, 12 lanterns)2.6k / 1.2k / 2704000
handCart (loaded)2.7k / 1.0k / 5204000
stoneWallLow (3.6 m)2.6k / 212 / 243500
barrel2.4k / 516 / 1122600, LOD2 ≤ 120
norenLong896 / 356 / 244000
stallLarge7.5k / 2.9k / 2408000
pineTree2.7k / 766 / 2744000
bambooCluster11.8k / 2.2k / 21613000
archBridge (20 m)8.2k / 2.6k / 9289000 (the hero crossing, one or two per town)

The smallProps test suite enforces a LOD0 budget per kind (4000 where none is listed), LOD1 strictly cheaper than LOD0, LOD2 no dearer than LOD1, and the far budgets of the bulk kinds.

Count. The package holds 91 kinds: 33 buildings (see Buildings) and 58 small props, each with variants, three LODs and the four looks.

Rebuilding. Generators are SmallGen*.module (shapes from SmallShapes, prop pieces from SmallKit, specs collected by SmallSpecs). After changing one, run require("sengokuProps.SmallBake").run({ kinds = { "well" } }): it rebakes meshes/small/<kind>/ and regenerates the literal BakedSmall index that SmallCatalog registers from. The PropGallery component shows them with categories = "street,light,gate,fence,bridge,nature,farm".

Lantern light and shadows

  • A lantern's glowing paper (paper, paperRed, paperWhite parts) never casts a shadow: it is the light's own surface, so the light leaves through it.
  • An info.lights entry may say castsShadows = false, and the SengokuProp component (and lanternStair) honour it.
  • Every stone lantern casts no shadow (stoneLanternKasuga, stoneLanternYukimi and stoneLanternOki, both variants of each). Their light sits inside a stone fire box that lets it out only through a few small windows, so a shadow-casting light there lights almost nothing around the lantern: the ground and steps near it go dark. Without shadows a stone lantern lights all the way round.
  • The paper and bronze lanterns (chochin, chochinLong, andon, tsuriDoro, lanternString) and the taimatsu torch light all the way round, and their lights may cast shadows.

Changes: 1.0.5 sets castsShadows = false on all three stone lantern styles (the 1.0.4 notes said the Yukimi's was off, but that line never reached the release, so all six stone lanterns still cast). 1.0.4 stopped the paper casting shadows. 1.0.3 was published by mistake from an old branch: skip it.

Known limits

  • Look switching (realistic, weathered, festival, toon) has been verified rebuild-complete on a built town (one look fully replaces the last before it is dropped), but not yet checked the same way on the PropGallery scene itself.
  • Climb and navigation tags on colliders (climbable, noNav) are plain attributes rather than climbKit's or navKit's own component types, so a world that does not follow sengokuTownKit's pattern has to know to read them itself.

Depends on

Versions are the ones installed in this world.

  • sengokuMaterials 1.0.1: every building and small prop part wears a sengokuMaterials surface. PropMaterials and the generated BakedMaterials index pick the surface for each part and look (realistic, weathered, festival, toon), and SengokuMaterials is required for them at run time. Cloth parts (noren, nobori, bunting, shide, sudare) wear sengokuMaterials' SengokuSway materials, the wind-swaying versions of its cloth surfaces.

  • groundMaterials 1.0.8 (Terra Firma): the generated BakedMaterials index names three of its materials directly (groundMaterials.materials.wetMud, moss and longGrass) as the realistic look of mud, mossGround and grassMeadow, so it is a dependency of this package in its own right, not only through sengokuMaterials.