World art guide: making an iamar world look like iamar

Read docs/WORLD_FORMAT.md, docs/WORLD_TIERS.md and kit/AGENT_KIT.md first: they are the rules. This guide is about the look. It never asks for a scene field that does not exist ("do not invent scene fields", kit/AGENT_KIT.md:197).

The King's Way at eye height: timber-framed plaster houses on stone ground storeys, a corner tower, a fountain, a fingerpost and bunting

1. The iamar look, in numbers

1.1 The idea in one paragraph

A painted, warm, lived-in medieval town: hand-painted surfaces that are "warm saturated but not neon" (docs/MASTERPLAN_CITY_BUILD.md:247-249), detail from paint rather than from geometry (docs/MASTERPLAN_ART_TECHNIQUES.md:22-25), nothing thin or flat (CITY_BUILD.md:240), and every visible thing closed: no gap, crack or open underside, while nothing a player can never see has a polygon at all (ART_TECHNIQUES.md:29-30). Colours are weathered toward lime plaster and old oak, because raw colours "read as fresh paint" (scripts/world/masterplan/mp_buildings.gd:618-620).

1.2 Palette

Base looks the whole city draws from (scripts/world/mats.gd:11-24):

Material	Colour
stone	`#a39c90` (dark `#7f786e`, castle `#b8b0a0`)
plaster	`#ece1c6` (warm `#ecd3a4`)
timber	`#5c3b22` (lighter wood `#936238`)
roof slate	`#4d6d93` (red tile `#a9463a`)
window glass	`#2f4660`

Each quarter has its own palette (tools/city_map/geometry/city-masterplan.json:116096-116128), with roofs replaced in the art pass (mp_style.gd:46-53):

Quarter	Roof	Wall	Timber	Trim	Ground-storey stone
central / civic	`#3e5d8c` slate	`#efe3c8`	`#4d3626`	`#2f4f6f`	`#c9bfac`
Mages'	`#35539a` blue-glazed	`#e3dccd`	`#5a4a6e`	`#c9a548` gold	`#d8d2c6` pale limestone
Warriors'	`#4b5160` dark slate	`#c9b79c`	`#4a3526`	`#8c2f25`	`#8c857b` rough granite
Herbalists'	`#7a5a32` thatch / mossy shingle	`#e8dfc2`	`#5c4a2a`	`#5f7f45`	`#cdb07a` honey stone

(mp_style.gd:34-43 for the stone.) Most houses have that stone ground storey: civic 80%, Warriors' 90%, Mages' 85%, Herbalists' 55% (mp_style.gd:45). Trims are pale dressed stone #cfc4ae..#d8cdb5, beams oak #5c3b22, straps iron #4d5157 (scripts/world/masterplan/mp_materials.gd:40-44).

Weathering, so nothing looks freshly painted (mp_buildings.gd:622-628): walls at 0.5 x saturation and 0.96 x value, timber 0.8 / 0.95, trim 0.5 / 0.72, roofs 0.85 / 0.97, each house jittered a little in hue, saturation and value, and no two neighbours sharing a tint (mp_buildings.gd:660-680). Do the same in your textures: one base colour per material, then small per-object shifts.

1.3 Materials and textures

The city paints 13 seamless layers plus an 8-strip trim sheet at 256 px per metre, warm-balanced (1.06, 1, 0.88) because the first pass was "too cold and bleached" (mp_materials.gd:6-14; ART_TECHNIQUES.md:170-191). In a package:

Textures are PNG or JPEG only, power-of-two sizes, JPEG for colour and PNG where you need alpha, alpha MASK for foliage (WORLD_FORMAT.md:52-54, 515-518).
The browser caps a texture at 4096 px and all textures at 1 GiB counted as width x height x 4 (scripts/worlds/world_format.gd:16-24); a "sensible small world" keeps textures at 1024-2048 (WORLD_FORMAT.md:638-647). For the iamar look, 256 px/m on near surfaces is the city's density; a 2048 tiling texture covers 8 m.
Paint the age in: darker, damper bases at the ground and under eaves, moss on north and stone faces, lighter wear along edges.
No black and no pink (missing-texture) surfaces: that is a review check (WORLD_FORMAT.md:820-822; AGENT_KIT.md:150-155). Even "black" iron in the city is #4d5157.

1.4 Shapes, scale and street sizes

Scale is checked in review: a person is 1.8 m, a door about 2.1-2.2 m (WORLD_FORMAT.md:820-822). The city's own numbers:

Thing	Size	Source
Door leaf height	2.28 m (grand doors: inn ~3 m, halls 4-5, library 6-7, cathedral ~8)	mp_buildings.gd:11; ART_TECHNIQUES.md:124-128
Wall thickness	0.18 m	mp_buildings.gd:12
Storey	3.2 m (ground storey up to 1.32 x, top down to 0.84 x)	mp_buildings.gd:691, 707
Roof	1/3 to 1/2 of the building's height; pitches 0.72-1.36 rise per run	CITY_BUILD.md:239-240; mp_buildings.gd:708
Windows	0.62-1.15 m wide, 0.36-0.5 of the storey tall, bays 1.9-3.1 m apart	mp_buildings.gd:882-886
Eave overhang	0.18-0.66 m	mp_style.gd:29-32; mp_buildings.gd:895
Jetty (upper storey over the street)	0.32-0.55 m	mp_buildings.gd:716, 892
Oriel (bay window)	1.6-2.4 m wide, 0.45-0.6 m deep	mp_buildings.gd:1053-1091
Corner tower	radius 1.0-1.35 m, 12 sides	mp_style.gd:640-650
Window box	at most 1.0 x 0.25 x 0.18 m	ART_TECHNIQUES.md:152-155
Rooms	shops and homes ~5-6 m across, halls 10 m+	ART_TECHNIQUES.md:158

Streets (the plan's paths[].width_m): lanes 5 m (the commonest), alleys 3 m, main streets 10 m, the King's Way 14 m, gate bridges 11-19 m.

What makes a street front read at eye height, learned the hard way on the city (tests/masterplan_city/mesh_review.md, B7): in a 5 m lane the eave line is seen edge-on, so what reads is what stands out of the wall or above the eave: jetties, oriels, a gable or a dormer on every house front, corner towers, signs and window boxes. Eave height steps of under ~0.6 m are invisible from the street (mp_buildings.gd:714). Vary the houses: no two neighbours share a window rhythm, timber pattern, roof pitch or tint (tests/masterplan_city/mp_buildings_closure_test.gd:110-142).

The roofscape: every roof closed, ridges capped, chimneys and dormers

1.5 Mesh budgets, closure and culling

	City	A package
A house	~1-3k triangles (median 2,198 over 121 houses)	same is a good target
A landmark	5-15k
A creature / mount	3-8k / 6-12k
The visible frame	"well under 1M primitives, shadows included"	low tier: under 150k triangles and 150 draw calls in the busiest view, 30 fps on a Radeon HD 5750-class card

Sources: ART_TECHNIQUES.md:26-28; oakhaven-city-models models.json; kit/AGENT_KIT.md:233-243; docs/WORLD_TIERS.md:8-36. Browser hard limits: 3,000,000 triangles, 5,000 objects, 64 lights (world_format.gd:16-24).

Cull per face. Export only faces a player can see (oakhaven-city-models README:21). The city drops ~66-70k hidden faces of ~735k (ART_TECHNIQUES.md:70-79): undersides of things on the ground, faces against a wall, the backs of facades.
Close what is seen. No open edges, gaps or cracks on anything visible; openings (doors, gates) stay open with a frame (ART_TECHNIQUES.md:29-33).
No z-fighting. Two surfaces facing the same way must not share a plane: the city's audit flags anything within 2 cm (tests/masterplan_city/zfight_audit.gd:20-27). Offset by 1-2 cm or more along the normal, never by depth bias alone; glass 2.5 cm off its wall, panes 3 cm proud; a 5 mm gap still flickers (ART_TECHNIQUES.md:596-607). A window frame whose face lies 5 mm behind its glass is the classic mistake.
LOD: the browser builds an LOD chain for every model by itself (1.0 / 0.5 / 0.2 at a 4 px threshold); you supply no LOD meshes (kit/recipes/TECHNIQUES.md:14-31). Give big far objects an "impostor": <metres> (80-150 m suggested, default 120; TECHNIQUES.md:33-49) and small clutter a visible_range (WORLD_FORMAT.md:283). The city fades small meshes at 40-260 m by size and props at 110 m (mp_lod.gd:32-35; mp_budget.gd:51).

Close-up in the Warriors' quarter: timber framing over a dressed-stone ground storey, an arched door, painted window frames

1.6 Light: what the city bakes, and what a package can do

The city bakes light in Blender Cycles (256 samples) into a lightmap on UV2: sky light (AO-like) and sun visibility, with a fixed sun 22 deg up (scripts/world/masterplan/mp_bake.gd:3-27; tools/bake_light.py:31-39, 79). Lamps at night add a warm pool on the ground, about twice the lamp's height across, toward 2700 K (mp_lamp_fx.gd:58; shaders/masterplan_look/lamp_pool.gdshader).

A package has no lightmap field. What it can do:

Bake in Blender into vertex colours or a texture on UV2, and export the baked meshes with an Emission or Background material so the glTF carries KHR_materials_unlit, which the browser honours. Bake only things that never move (kit/AGENT_KIT.md:334-369; kit/recipes/TECHNIQUES.md:169-187, "bake_sky_sun": texel 0.1 m, at most 4096). The city's own texel is 0.1 m (scripts/world/bake.gd:27-28).
Or stay live-lit with one sun: scene.environment.sun (colour, energy, direction, shadows), ambient, sky, fog, exposure, time_of_day (WORLD_FORMAT.md:164-206). The browser renders one sun shadow pass over 50 m with a linear tonemap (scripts/worlds/world_builder.gd:274-314); the shadows tier switch can turn it off.
Point and spot lights: only the nearest 6 lamps get a real light (TECHNIQUES.md:149-165), shadows default off. Fake the rest with emissive windows and lantern glass.
Not available to a package: weather (accepted and ignored, WORLD_FORMAT.md:207-209), a moving day (day_length_minutes is in the schema but nothing reads it yet), and script control of light, time or weather (no such call in docs/WORLD_API.md).

1.7 Atmosphere

The city's default "golden" look (scripts/world/masterplan/mp_look.gd:39-48): sky #3f78d0 to horizon #f8e6cc, sun #ffc274, ambient #b4aaa6, a cool fog #ccd8ea at density 0.0013 that thins with height (x1 at 8 m, x0.15 at 60 m), filmic tone mapping, a light vignette (0.28). Night (lines 75-84): sky #0b1434, a silver moon #c4d2f4 at 0.6, slate ambient #66708e, fog #1c2646. Each quarter tints its fog and lamps: Mages' violet #8a78e8 / #9c8cff, Warriors' ember #d08050 / #ff9a48, Herbalists' meadow #e6e2a2 / #ffd28c (lines 92-100).

A warning from the city: a warm, peachy fog (#eccfa8, heavy sun scatter) tinted the whole valley yellow from the air; the fix was the cool #ccd8ea with less scatter (docs/MASTERPLAN_TODO.md, B15). Keep the warmth in the sun and the surfaces, and the fog cool and light.

In a package, set these through scene.environment (sky, sun, ambient, fog, exposure, time_of_day) rather than per-object effects (TECHNIQUES.md:262-274). The browser applies a linear tonemap, so you will want slightly less sun energy and a touch more ambient than the city's filmic values.

The same street by day (10:00) and at night (21:30)

At night: warm lit windows (each quarter its own glow colour, mp_look.gd:118-119), a silver moon, the street still readable

1.8 Ground and flora

Paving: setts 15-21 cm (0.17 x 0.12 m typical), larger flags in the squares (courses ~0.52 m, lengths ~0.92 m), with 2.6 cm joints (shaders/mp_ground_paving.gdshaderinc:45-130). Paint wear and ruts down the middle of a street, damp along the walls.
Grass and flowers are alpha cards, faded out with distance: tufts 0.9 x 0.7 m to 26-40 m, flowers 0.8 x 0.75 to 34-52 m, reeds 1.3 x 1.9 to 60-90 m (mp_flora.gd:18-25), sampled about every 1.1 m.
Beds and gardens: each bed its own plants, never uniform rows of one plant (the city's herb and kitchen gardens: mp_herb_garden.gd, mp_crop_beds.gd). Plant spacing 0.2-0.95 m by crop.
Trees switch to impostor cards at 45-75 m (scripts/world/forest_impostors.gd:23-25).

The cathedral market: stalls with striped awnings, trees, flagstone paving with joints and wear

2. Raising the art quality, step by step

Work in this order; each step is worth more than the next.

Scale. Put a 1.8 m person and a 2.2 m door in every view you check. Wrong scale undoes everything after it.
Silhouette. Roofs a third to a half of each building; overhangs, jetties, gables and chimneys break every roofline; no long same-height flat front.
Palette and paint. One weathered base colour per material from 1.2, a small shift per object, texture density near 256 px/m on what the player walks past. No pure black, no fresh-paint colours.
Closure and culling. Close every visible edge, delete every face nobody can see, offset every overlay by 2 cm or more.
Light. Bake sky and sun light into the static meshes (1.6), or tune one live sun with a soft ambient; lit windows and lantern glass at night.
Atmosphere. A cool, light fog that hides the far edge of the world, a sky that matches the sun, the time of day you want.
Dressing. Signs, window boxes, barrels, carts, banners, plants; vary them, never in rows.
Budget. Measure the busiest view against the low-tier targets in 1.5; add impostors and visible_range before cutting detail near the player.

Self-check list (run it on your own screenshots)

Take eye-height (1.7 m) screenshots in the busiest street, the widest square and one alley, by day and at night, and one from above. Then check:

A person-sized reference fits doors and stairs (door ~2.1-2.3 m).
No black or pink surface anywhere; nothing looks freshly painted.
Every roof has an overhang and every roofline is broken somewhere.
No two neighbouring buildings share colour, window rhythm and roof pitch.
From the street, something projects from or rises above every house front.
No flicker when you walk past walls, windows, signs and the ground (z-fighting).
No gaps, holes or open undersides from any reachable view, including from above.
Nothing floats above or sinks into the ground.
Flora and beds are mixed, not uniform rows.
The fog is cool and light; the sky is not tinted yellow from above.
Night: windows and lanterns glow warm; the scene is readable, not black.
Low tier: the busiest view is under 150k triangles and 150 draw calls and holds 30 fps (kit/AGENT_KIT.md:233-243), and it still looks "pleasant, not just functional" (WORLD_TIERS.md:161-162).

Close-up of the Herbalists' roofs: painted shingle, ridge caps, street gables

Images: rendered from the iamar city (main, 2026-10-10) at 1280x720 on emma, without its baked lighting (tests/masterplan_city/mp_materials_shots.gd). Written by Z-EMMA for the iamar.ai world-creator docs (board #2540).

Rendered from docs/WORLD_ART_GUIDE.md in endsley/iamar (1a54596596, 2026-10-10). Regenerate with python3 site/sync_docs.py — never edit this page by hand.