The diorama village kit

The diorama village kit is a pixel village a game copies into its own source: the painted ground and its block set, houses, a windmill, a farm, a well, a market stall, lamps, furniture, fences, bridges, beds, rocks, trees and fires. Each object is a map object, so a map file places it by kind and the map builder’s inspector edits its fields. Every wall, roof, window and prop is a pixel texture painted at 16 texels a metre from one palette, as Luminati’s village is; the lamps’ iron and glass are plain colours. Each object is built from a few numbers, so every creator’s village differs.

Add the kit

Run spawnite add kit diorama-village, or ask your agent to, which calls the MCP’s add_kit. The files land under src/kits/diorama-village/. Import the kit once from src/game.ts with import "./kits/diorama-village";, before any map loads, so the room and every page know its block set and its objects. A scene that places them mounts <Particles effects={particleEffects} /> from the kit, with any effects of its own added, since its chimneys, fires, trees and areas play the kit’s particle presets.

A map file then names the kit’s block set and places its objects by kind:

{
    "blockSet": "village",
    "props": {
        "inn": {
            "kind": "house",
            "position": [1.5, -7.5],
            "fields": { "stories": 2, "roof": "roof-tiles", "lantern": true }
        },
        "well": { "kind": "well", "position": [3.5, -0.5] },
        "stall": { "kind": "market-stall", "position": [-3, -1] },
        "lamp": { "kind": "lamppost", "position": [-3.5, -2.5] }
    }
}

The objects

house: a gabled house of one or two storeys on a stone plinth, with windows that glow at dusk, a door, a chimney, a lantern by the door and a hanging sign. Its wall, upperWall and roof pick a painted texture; roofPitchRadians left null lets the seed pick a slope from 38 to 45 degrees. doorOffset moves the door along the front; the lantern takes the side with more wall, and the sign the other, turned 45 degrees away from the door.
windmill: an octagonal tower of stone under plaster or timber, upperWall, with a conical thatch cap, a door and windows that glow at dusk. Four lattice sails on a hub turn clockwise with the weather’s wind, one turn in about 11.4 s in clear weather, from a start the seed picks; turning false holds them. Left null, height is 6 to 6.6 m by the seed.
haystack: a round, layered mound of straw 0.7 to 1 m across on a pole, with a loose skirt; count stands up to four together.
hen-yard: a fenced rectangle for hens, the kit’s fence round it with a 1.1 m gap in its front unless gate is false. measureHenYardPen reads its pen, the ground inside the posts, and its gate from its fields and size, so a game’s hens walk inside it.
well: a ring of fieldstone with water inside, under a little roof on two posts.
market-stall: a counter under an awning striped in stripeColor and cream, with crates of goods on it.
lamppost: an iron post whose lantern lights at dusk, hanging from an arm or set on its top, its light from the point light pool. An arm’s lantern swings a little on its hook unless swing is false, as a house’s door lantern does.
crate: one crate, or a pile of up to six with a barrel at one end; count is every crate in the pile. The seed lays the pile out and sets each upper crate down a little askew.
barrel: an iron-hooped barrel, standing or lying along its front.
bench: a plank seat on two stone feet, with or without a back.
fence: a line of pointed posts joined by one rail or two; each post stands on the ground under it, and two runs meeting at a corner draw one post.
bridge: an arched plank bridge along a line. Left deckHeight null, its deck runs from bank to bank a tenth of a metre clear of any water; its planks are thin, so a path can pass under it.
signpost and notice-board: a post of arrow boards, and a board of notices under a little roof. Neither holds text: a game that lets a player read them adds the field with its reading.
flower-box: a planter of flowers on legs, or hung on a wall at its mountHeight. A house hangs its own under some windows unless flowerBoxes is false.
flower-bed and garden-bed: raised beds over a rectangle, of flower clumps or of crop rows along their own x, edged with planks, stones or nothing; each lies level at the highest ground under it. A character steps onto one from that ground; across a terrace’s edge, its lower side stands the drop plus its border high, past the 0.6 m a character steps.
rock: a mossy boulder size metres across, with a leaning stone and pebbles beside a large one.
tree: an oak, a birch or a pine, its crown of leaf cards swaying in the wind and its trunk bending under it, its shadow with it; an oak or a birch takes leaves green, autumn or blossom, and autumn leaves lie under it. An autumn crown sheds leaves in its colour and a blossom sheds petals, unless shedding says otherwise; a pine sheds none.
wall-torch and campfire: a flame that turns to the camera, a glow round it and a light from the pool, burning day and night, with embers rising; lightColor colours both, and lit puts them out. A wall torch’s dayShare turns its light down by day. A campfire’s smoke, off unless set, rises over it.
god-rays: shafts of sunlight standing in a rectangle, the god rays a look draws, with dust motes drifting in them by day unless motes is false.
particle-area: the air over a rectangle, height metres deep: fireflies by night, dust-motes by day, or falling-leaves or falling-petals at any hour. Its count over each square metre stays the same at any size, and density multiplies it. A scene’s own JSX places the same air with <AreaParticles size effect />.
waterfall: a pixel water sheet from a river’s end down to the pool or the ground ahead, width metres across, 2 unless you set it, with the asset library’s mist and splash at its foot. Stand its point at the foot of the lip’s cliff, its front facing downstream; it refuses a place with no water behind its lip, a lip on two reaches, or a drop under 0.25 m. A scene that places one mounts the kit’s waterfallEffects beside its particleEffects in its one Particles, or the mist and splash play nothing.

A house’s chimney smokes unless smoke is false: warm in the day’s light and a moonlit blue-grey by night, because the particle library lights no billboard. The fireflies, the motes, the leaves and the petals follow the world’s weather: a rain puts the fireflies out and thins the dust.

The set’s farmland block lays ploughed rows with their crop painted in, and grows nothing. The meadow’s flowers stand in drifts of red, yellow, white and blue, with clearings where none grow.

Place the kit’s tree where a player walks among a village’s trees; the scatter’s treeRound and treeTall fill a forest’s floor, where many draw as one. The set’s forestFloor block lays dark grass under them, with short muted tufts and shrubs.

Stand the world past the map

OuterScenery, mounted under the scene’s Landscape, stands a hilly ground and a border forest past a block map’s edges, so the camera at the edge never meets the cut:

The ground: it reaches 170 m out, rising behind the map into hills and a ridge 18 to 52 m high, 55 to 120 m out, and 4 to 18 m along the sides. It cools with distance and on slopes.
The forest: its trees are the kit’s own tree, merged by side, cast no shadow, and thin from 24 to 34 m out.
Its settings:
- ridge names the side the hills rise behind, MapSide.North for the diorama camera.
- forest takes a frontGap kept clear on the camera’s side, or false for none.
- trees stands trees of your own, such as tall oaks in the foreground.
Where it draws: on a page alone, nothing on an interior level, and again when an edit moves the map’s edge.

A point object’s front faces +z at a yaw of 0, toward the diorama camera, and a line’s runs along its own +x. These reach their footing and colliders down to the lowest ground under them: a house and its door step, a well, a stall, a bench, a signpost, a notice board, a standing flower box, a bed, a fence and a bridge. Each stands on what a player sees across a terrace’s edge. A crate, a barrel, a rock, a tree and a campfire stand at the height of the ground under their position. A wall torch and a hung flower box stand their mountHeight over the ground 0.6 m in front of the wall instead, the wall behind their position. None of them scales: each sizes by its fields, so its texels stay square. A rock and a tree turn by their seed, not their yaw.

The kit also paints its people and animals as sprite sheets in code. defineCharacterSheet in painters/characters.ts takes a preset, a seed and any parts you name, and defineCritterSheet in painters/critters.ts paints a cat, a dog, a hen or a bird. The characters shade from five-tone ramps of their own, characterPalette, and each person’s idle plays at a seeded 0.5 to 0.62 of 2.5 frames a second.

Its townsfolk

The townsfolk plugin in townsfolk.tsx sets the village’s people and hens about their day, built on the engine’s routines alone. Add it to your game’s plugins, and give each <Npc> one of these routines and the component that holds its numbers:

A wanderer: wanderRoutines with <Villager home={at} wander={1.5} />. It pauses 2.5 to 6.5 s, then walks to the best of six walkable picks from 0.4 m to its wander metres from home: the one farthest from where it stands. It turns to a player who comes within 2.4 m while it stands, and stops while a player stands within 1 m ahead on its walk.
A post: postRoutines with <Villager home={at} />. It turns a quarter, a half and a quarter round, 2.5 to 5 s apart, and faces a player within 2.2 m for as long as the player stays. Pushed more than 0.15 m off its post, it walks back.
A hen: henRoutines with <Hen yard={yard} />. It pecks for 0.6 to 2 s, walks 0.4 to 1.4 m inside its yard, and pauses 1.2 to 4 s. A player or a chaser within 1.7 m sends it running straight at 3.4 m/s for 0.5 to 0.8 s: away from the threat, or turned the least that gives it the whole run inside its yard, or else its longest run there. A hen with no run of 0.4 m left stands.
A hen chaser: henChaserRoutines with <HenChaser yard={yard} />: a person who runs after a hen of its yard every 1.5 to 4 s, as Luminati’s Nim does, and after another once that hen is gone.

A HenYard is a ring, { center, radius }, or a pen, { center, min, max }, with min and max in metres from center. A villager’s routine also holds for 1.2 to 2.5 s after a conversation ends. The game’s Townsfolk, in src/scenes/Townsfolk.tsx, places them from data: a wander, a speed and a yard on each placement, and a person with none keeps a post.

Change it

The kit is your source. A house’s wall texture is a member of WallTexture in objects/house.tsx with its painter beside it in wallTextures, so a new member that has no painter is a type error. A painter is a definePixelTexture in painters/, shading from the ramps in palette.ts. A lamp’s intensity, range and flicker are written in the view that mounts it, LamppostView or HouseView, and a fire’s in wallTorchLight and campfireLight. Each area effect’s preset, hours and weather factor are a row of particleAreaEffects in objects/particleArea.tsx, and each leaf colour’s shedding is a row of treeShedding in objects/tree.tsx. A new member of ParticleAreaEffect or LeafColor that has no row is a type error.

The values and Luminati’s

Value	The kit	Luminati
A house’s plinth	0.5 m	0.5 m
Storeys	3 m, then 2 m jettied out 0.25 m	the same
Roof pitch	38 to 45 degrees from the seed, or set	38 to 45 degrees
Eaves and roof	0.35 m over the walls, 0.22 m thick	the same
Windows’ glow	1.6 by night	1.6
A lamppost’s light	30 over 12 m, flicker 0.2, priority 2	12 over 9 m
A door lantern	15 over 9 m, flicker 0.25, priority 3, 0.15 by day	6 over 7 m, 0.15 by day
A house’s sign	0.95 by 0.52 m on a 1.05 m arm, 45 degrees	the same
A meadow cell	3 tufts, or 5 in a patch, 3 in 7 tall	5, 45% tall past 0.58
Flowers	zones about 5 m across, one colour each	zones from palettes
A windmill	6 to 6.6 m, 4 sails 3.7 by 0.95 m	the same
Its sails’ turn	0.55 rad/s times 0.6 + 0.4 of the weather’s wind	the same
A trunk’s bend	from 0.28 of its height, 0.25 a pine’s, power 1.35	the same
A hanging lantern	±0.04 to 0.07 rad over 3 to 4 s, seeded	the same
A haystack	0.7 to 1 m across, up to 4 together	the same
A hen yard	8 by 2.8 m in Larkmoor, any size placed	about 14 by 2.8 m
The outer forest	about 400 trees past Emberfall	436
A wall torch	7 over 7 m, flicker 0.45, priority 1	the same
A campfire	14 over 10 m, flicker 0.5, priority 0	the same
A bridge’s deck	bank to bank, so no step at either end	at the higher bank
A tree’s crown	17 to 21 cards on an oak, 12 to 16 on a birch	24 to 30, 16 to 20
Texels a metre	16	16
Fireflies	about 21 over 100 m², 0.14 to 0.19 m, at 2.4	36, 0.2 to 0.3 m
Dust motes	about 30 over 100 m², 0.05 to 0.1 m, at 2.4	90, 0.06 to 0.12 m
Embers	21 a second, rising 1.5 m a second	34, rising 1.5
Smoke	4.4 puffs a second at alpha 0.32, unlit	22, lit, alpha 0.5
Falling petals	about 40 over 100 m²	40
A person’s idle	0.5 to 0.62 of 2.5 frames a second, by the seed	the same, seeded
A wanderer’s walk	0.4 m to its radius, 2.5 to 6.5 s apart	the same
A villager’s look	2.4 m standing, 2.2 m at a post	the same
A post’s turns	a quarter, a half, a quarter, 2.5 to 5 s apart	a new facing, 2.5 to 5 s
After a talk	1.2 to 2.5 s before the routine goes on	the same
A hen’s walk	0.4 to 1.4 m after 0.6 to 2 s, then 1.2 to 4 s	the same
A hen’s flight	within 1.7 m, 3.4 m/s for 0.5 to 0.8 s	the same

Its frame cost

The kit’s frame cost is not profiled yet.