Hearthvale: Walkable Fantasy Town Kit
- ..
- .metadata107 B
- Gallery.component
- README.md11.7 KB
- Town.component
- TownGallery.scene
- api.module
- buildings.module
- example-build-a-medieval-market-village-in-ten-minutes.guide
- gallery.module
- geo.module
- how-to-build-a-fantasy-town-players-can-walk-around.guide
- layouts.module
- manifest.module
- package.yaml643 B
- props
- props.module
- reference
- screenshots
- styles.module
- textures
- townKitTests.testSuite
README.md
Hearthvale: a walkable medieval anime fantasy town kit (townKit)
Drop a whole walkable fantasy town into any world with one call or one component. Hearthvale builds a medieval anime isekai town: a walled castle town with a castle gate, a fountain plaza, an adventurers' guild hall you can walk into (reception desk, quest board, tables, fireplace, chandeliers), an inn and tavern you can walk into (bar, barrels, tables, fireplace), market stalls, shops with striped awnings and hanging signs, half-timbered houses in three sizes, thatched cottages, a chapel, towers and town walls, cobbled roads with kerbs, narrow back alleys with crates and barrels, street lamps, benches, trees, a well and carts. Everything has colliders, and the interiors that matter have walkable floors and ramps at their doorsteps, so a third-person player walks the whole town without getting stuck.
It comes in five art styles switched by one setting, with one shared API: anime (clean two-tone cel light, lavender shadows, bright saturated anime background textures and a thin ink line), painted (soft hand-painted textures and soft light bands), toon (flat palette colours, three hard bands, ink outlines), realistic (generated PBR textures with normal and roughness maps) and lowpoly (flat matte colours, props re-cut into faceted geometry). Three town plans ship: castleTown, riverVillage and hamlet. The game asks the town for named anchors (guild desk, quest board, shop counters, inn bar, castle gate, alley spots, the roads out to the dungeons, the player spawn) and gets activity spots in townsfolkKit's format for crowds.
Version 1.0.2.


Install
Search ZeroMind for "Hearthvale" or "fantasy town kit" and install the townKit package, or run zero zeromind installAsset <townKit package guid>. The install brings its one dependency, toonMaterials (Ink and Gouache, whose toonSurface shader draws the anime, painted and toon styles and whose ToonInk draws the ink line), which brings materialLibraryKit. Nothing else is needed. The kit finds its own textures and meshes by package-relative names, so it works wherever it is installed (including under another world's deps/).
Quick start
As a component (the simplest way, in a scene's build.luau):
local town = entity.spawn("Hearthvale")
town.component.add("townKit.Town", { style = "anime", layout = "castleTown", seed = 1 })
From code (a scene entrypoint, a component's awake, or the console):
local Town = require("townKit.api")
local t = Town.place({ style = "anime", layout = "castleTown", seed = 1 })
local desk = Town.anchor("guildDesk") -- { name, position = vector, yaw, forward = vector }
local spawn = Town.anchor("playerSpawn")
Town.building("guildHall", { at = vector.create(80, 0, 0), yaw = math.pi, style = "anime" })
Town.prop("fountain", { at = { 0, 0, 0 } })
Open the gallery of every building in every style: zero scene load townKit.TownGallery.
The townKit.Town component
| field | default | what it does |
|---|---|---|
style | anime | anime, painted, toon, realistic, lowpoly |
layout | castleTown | castleTown, riverVillage, hamlet |
seed | 1 | house variants, clutter, tree placement; same seed, same town |
collide | true | colliders on buildings, walls, props, ground, interior floors and doorway ramps |
lights | true | point lights in the guild hall and inn (fireplaces, chandeliers), every other street lamp, gate torches |
:rebuild() rebuilds from the current fields. The town is placed at the entity's transform.
API (require("townKit.api"))
| call | answers |
|---|---|
Town.place(opts) | a town: { root, style, layout, seed, anchors = {names}, spots, bounds, ms }. opts: style, layout, seed, at (vector or {x,y,z}), yaw, parent, collide, lights, townsfolk (townsfolkKit's api module, to register the spots), name |
Town.building(kind, opts) | { root, kind, footprint = {w, d} }. opts: at, yaw, style, seed, parent, collide, lights, id (anchor alias), shop, goods, roof, length |
Town.prop(kind, opts) | the prop entity. opts: at, yaw, style, parent, collide, scale |
Town.anchor(name) | { name, position, yaw, forward } or nil |
Town.anchors(prefix?) | every anchor (optionally by name prefix) |
Town.spots() | activity spots { kind, position, yaw, tag } (townsfolkKit spot kinds) |
Town.registerTownsfolkSpots(TF) | hands every spot to townsfolkKit: pass require("townsfolkKit.api"); answers how many were added |
Town.clear() / Town.forget() | remove everything placed / forget anchors and spots only |
Town.stats() | buildings, props, entities, colliders, lights, triangles, build ms |
Town.material(style, slot) | the material a slot wears in a style, to dress your own geometry to match |
Town.STYLES, Town.LAYOUTS, Town.BUILDINGS, Town.PROPS | the id lists |
A building's front (its main door) faces -Z at yaw = 0; yaw turns it about +Y. 1 unit = 1 m, ground at y = 0.
Buildings (Town.BUILDINGS): houseSmall, houseMedium, houseLarge, cottage, shop (shop = "smith" | "potion" | "general" | "bakery" | "tailor"), marketStall (goods = "fruit" | "bread" | "cloth" | "potions" | "pots"), guildHall, inn, chapel, tower, wall (length), castleGate.
Props (Town.PROPS): fountain, well, questBoard, lamp, barrel, crates, cart, bench, tree.
Anchors
Every anchor a layout registers (duplicates are numbered: shopCounter, shopCounter2, ...; a building placed with id also answers name:id, such as guildDesk:guild):
| anchor | where |
|---|---|
playerSpawn | where a player should start (castleTown: foot of the market street, facing the plaza) |
guildDesk, guildDeskFront | behind the reception desk (receptionist) and in front of it (player), on the raised floor |
questBoard, questBoardOutside | the board inside the guild hall, and the one outside on the plaza |
guildEntrance, guildInterior, guildTable1..4, guildFireplace | guild hall points |
innBar, innBarFront, innEntrance, innInterior, innTable1..3, innFireplace | inn points |
shopCounter*, shopKeeper* | in front of and behind every shop counter |
marketStall*, market | in front of every market stall, the market square |
castleGate, castleGateInside, castleRoad | outside and inside the castle gate (castleTown) |
townGate | the main entrance of the town |
plaza, fountain, well, chapelDoor, bridge, riverbank | squares and landmarks |
alley1..n | the middle of each back alley |
dungeonRoadNorth, dungeonRoadEast, dungeonRoadSouth, dungeonRoadWest | out on the roads leaving town |
Activity spots
Spot kinds are townsfolkKit's (stall, shop, bench, teahouse, queue, well, watch, chat, perform, play, pray, fish, beg), each with a tag (market, guild, inn, guildDesk, gate, alley, ...). Call Town.registerTownsfolkSpots(require("townsfolkKit.api")) after the town is built (or pass that module as townsfolk to Town.place) to hand them to townsfolkKit; townKit itself does not depend on townsfolkKit, or read Town.spots() for your own NPCs.
Styles and materials
Every building is written into material slots (plaster, plasterWarm, plasterBlue, timber, wood, planks, stone, stoneDark, roofTile, roofTeal, roofSlate, thatch, cobble, flagstone, ground, glass, glassDay, metal, gold, clothRed, clothBlue, clothGreen, clothCream, foliage, flowers, water, dark, paper, candle). A style is one material per slot, made once and shared. Textures shipped: anime and painted surface sets (generated with image_gen), a realistic PBR set (pbr_gen) and the generated prop meshes (mesh_gen) with their albedo, normal and roughness maps. The kit does not change your scene's lighting or post effects; for the full anime look pair it with a warm sun and a bright ambient (see the main scene of the Hearthvale world) or a Style Cookbook look.
Multiplayer
Everything is built as local, temporary entities from deterministic rules (a seeded number stream, no math.random), so every peer that runs the same call or carries the same component fields builds the same town, and nothing is written into the scene file or replicated per frame. The Town component's fields are synced, so a style switch made on one peer rebuilds the town on all of them.
Interiors
The guild hall and the inn are finished inside in every style: warm wood wainscoting with stiles, a chair rail and skirting boards, plaster walls above, plank floors, hanging banners (red and blue guild banners either side of the crest, green and red pennants in the inn), candle sconces on the walls with warm point lights, chandeliers, and a stronger fireplace with logs and a hearth rug. Before (1.0.1) and after (1.0.2), anime style:


Buildings.innerFinish(b, length, height, thickness, openings, opts) puts the same finish on the inside of any wall you build with a townKit.geo builder.
Performance
Identical houses share their meshes (six variants per house kind), every slot shares one material per style, and every prop kind shares one mesh and material, so the renderer instances them. Measured on the castleTown layout (anime): about 76 buildings, 100 props, 1,070 entities, 190 colliders, 103k triangles of unique geometry, built in about 2 s at load, and the frame held at 60 fps with the engine CPU at about 6.8 ms (dev build, 1920x1080). lowpoly halves the building triangles.
What is in the package
api.module (the API), Town.component, layouts.module, buildings.module, geo.module (the builder), styles.module, props.module, manifest.module (literal asset references), gallery.module, Gallery.component, TownGallery.scene, textures/ (anime, painted, realistic), props/ (generated meshes and maps), two guides: how-to-build-a-fantasy-town-players-can-walk-around and example-build-a-medieval-market-village-in-ten-minutes.
Tests
zero tests run townKitTests: 5 tests. Every layout (castleTown, riverVillage, hamlet) builds in every style (anime, painted, toon, realistic, lowpoly); the anchors games rely on exist (guildDesk, guildDeskFront, innBarFront, castleGate, questBoardOutside, dungeonRoadEast, dungeonRoadNorth, dungeonRoadWest, market); every activity spot registers with townsfolkKit through registerTownsfolkSpots; layouts are deterministic by seed (same seed, same anchors and spots; another seed, another town); and the guild hall and inn interiors carry their warm sconce and fireplace lights in full and lowpoly builds.
History
- 1.0.2: warm guild hall and inn interiors in every style (wood wainscoting, plaster walls, banners, candle sconces with warm lights, a stronger fireplace); the
townKitTestssuite. - 1.0.1: walkable interiors (floor and ramp colliders), performance and anchors.
- 1.0.0: first release.
Tested
Zero engine @builtin 28ef193 (November 2026), desktop. Walked in third person with the default humanoid player: up the guild hall ramp onto its floor and through the hall, along the streets, alleys and bridge. toonMaterials 1.0.11.