# World art guide: making an iamar world look like iamar

For an AI agent building a world package (docs/WORLD_FORMAT.md: `scene.json`,
`assets/*.glb`, `textures/*`, optional `scripts/*.wasm`) that should sit
comfortably next to the iamar city. Every number here is taken from the city's
own code or from the package rules; the file is named after each one so you
can check it. Where the city does something a package cannot, this guide says
so and gives the nearest thing a package can do.

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](world_art_guide/kings_way.jpg)

---

## 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.

![A 5 m lane in the Mages' quarter](world_art_guide/mages_lantern_lane.jpg)

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](world_art_guide/roofs_overview.jpg)

### 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](world_art_guide/warriors_frames_close.jpg)

### 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)](world_art_guide/market_cross_day.jpg)
![At night: warm lit windows (each quarter its own glow colour, mp_look.gd:118-119), a silver moon, the street still readable](world_art_guide/market_cross_night.jpg)

### 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](world_art_guide/cathedral_market.jpg)

---

## 2. Raising the art quality, step by step

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

1. **Scale.** Put a 1.8 m person and a 2.2 m door in every view you check.
   Wrong scale undoes everything after it.
2. **Silhouette.** Roofs a third to a half of each building; overhangs,
   jetties, gables and chimneys break every roofline; no long same-height
   flat front.
3. **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.
4. **Closure and culling.** Close every visible edge, delete every face nobody
   can see, offset every overlay by 2 cm or more.
5. **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.
6. **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.
7. **Dressing.** Signs, window boxes, barrels, carts, banners, plants; vary
   them, never in rows.
8. **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](world_art_guide/herbalists_roofs_close.jpg)

---

*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).*