Facade Mods Guide

1. A mod in one minute

A mod is a zip file with one facades.json and three pictures for each facade. Nothing else in it is used and nothing in it is ever run.

The game's own facades

Textures by najjar320 — Pixel Facades – 100 Building Textures.

2. The three pictures of a facade

Each facade is cut into three horizontal parts. All three have the same width (w) and the same scale: every floor is exactly floorRows pixels high.

_top.png 109 px

_floors.png 177 px

_ground.png 98 px

roof edge 50 px

last floor 59

floor 59

floor 59

floor 59

ground 98

w = 192 px

Brownstone, drawn at 1.1×. Red: where the three files are cut. Blue: the floors inside them. Right: the three files the game reads. The whole picture (facade_brownstone.png, 192×384) is only a preview.

3. facades.json

One file for the whole mod. Sizes are in pixels of your pictures; the game turns them into metres from the floor height.

{
  "$schema": "https://www.thecitynauts.com/mods/facades.schema.json",
  "title": "Old Town",          // optional - the name shown in the game
  "map": "roadmap",            // optional - "roadmap" (default) or "satellite"
  "roofs": "flat",             // optional - "flat" (default) or "photo" (satellite only)
  "roofColor": "#3b3e44",      // optional - flat roof colour (satellite only)
  "floorMetres": 3.1,          // optional - how high one floor is drawn (default 3.1)
  "facades": [
    { "name": "brownstone", "w": 192, "top": 109, "floors": 177, "ground": 98,
      "floorRows": 59, "floorsInPart": 3 },
    { "name": "limestone", "w": 182, "top": 82, "floors": 174, "ground": 72,
      "floorRows": 58, "floorsInPart": 3 }
  ]
}

The comments above are only for this guide: JSON itself does not allow comments, so leave them out of your file. Fields the game does not know (like the note and metres in the game's own file) are ignored, so you can keep notes in them.

The mod

Each facade

4. How the game builds a wall

The game takes the real buildings of the map (their outline and height) and lays your pictures on every outside wall, 6 cm in front of it. Up the wall, from the bottom:

1. the ground floor (_ground),
2. as many floors as fit, taken from _floors from its top down and repeated for tall buildings,
3. the last floor and the roof edge (_top).

The number of floors is the one that fits the building's height best; the whole stack is then stretched or squeezed a little to the exact height. Nothing is cut in the middle of a floor.

The same Brownstone on buildings of different heights, drawn exactly as the game does (here 8 m wide walls):

Brownstone: 19.0 px per metre (59 px = 3.1 m); ground floor 5.15 m, roof edge 2.63 m, each floor 3.1 m. The percentage is how much the stack is stretched (+) or squeezed (−) to the building's height.

5. Across a wall: tiling

Along a wall the pictures are laid side by side at their own size (w pixels = w / floorRows × floorMetres metres; about 10 m for the game's facades). They are not stretched to fit a wall, with one exception:

• When the wall is within 12 % of a whole number of pictures, the pictures are fitted to it exactly.
• Otherwise there are whole pictures in the middle and the same cut piece at both ends, so the wall looks centred.
• A wall narrower than one picture shows the middle of the picture.
• Straight runs of a building's outline (edges that turn less than about 10°) are tiled as one wall, so a gently curved street front stays continuous.

Limestone on 14 m high walls. 2.08 pictures: fitted: 2 whole tiles, squeezed 3.8 %; 2.5 pictures: 2 whole tiles, the same cut piece at both ends; 0.62 pictures: narrower than a tile: the middle of one.

Sizes of the game's facades

With floorMetres 3.1. Keep your facades roughly 8 to 12 m wide and at the same pixel density as each other, so neighbouring buildings look alike in detail.

6. Light and shade

The game shades the facades itself, so draw your pictures evenly lit, without a strong shadow of their own. Each wall is darkened by the way it faces: the sun stands in the south, a little to the west.

On top of that every wall is a little darker towards the ground: 70 % at its foot, full brightness at its top (the dark band at the bottom of each sample). Pictures are drawn with sharp pixels up close and smoothly far away, so pixel art stays crisp.

8. Packing the zip

• Picture names: facade_<name>_top, _floors, _ground, with .png, .jpg / .jpeg or .webp. Upper or lower case does not matter.
• Other files (a preview, a readme, your source files) may be in the zip; they are ignored. Hidden files and macOS __MACOSX folders are skipped.
• PNG is best for pixel art: no blur, transparency kept. Transparent pixels show the building's grey wall behind them.

Limits

10. Sharing a mod

Mod Link downloads the zip straight from the browser, so the site it is on must allow other sites to download its files (it sends the CORS header Access-Control-Allow-Origin). Many do not.

Licence and credit

Only share textures you made or may share. If your mod is based on someone's texture pack, follow its licence and credit its author in your mod's page or readme, as this guide does for najjar320's Pixel Facades.

11. When a mod is refused

The game says exactly what is wrong; nothing of a refused mod is used and the mod you had stays.

12. Checklist, tips and credits

Before you share

• All three pictures of a facade have the same width, written as w.
• top = roof edge + floorRows; floors = floorsInPart × floorRows.
• Left and right edges join; the floors picture's top and bottom join.
• Edges of the pictures look fine when cut (no half windows at the edges).
• Even lighting, no baked-in shadows.
• The zip loads with User Mod without a message; look at low, middle and tall buildings, and at the north (darkest) side.
• Credit the textures' author if they are not yours.

Tips

• Start from demo-mod.zip: change one facade, zip, load, look.
• More facades = more variety on a street; 5–10 is a good number.
• Keep the floor height in pixels the same for all your facades (e.g. 59 or 64), so they share one scale.
• Shop fronts, doors and steps belong in _ground; balconies and window rows in _floors; cornices, parapets and roof lines in _top.

Credits

The example facades — Brownstone, Limestone, Art Deco, Mediterranean and Shop Terrace — shown throughout this guide and used by the game are from
Pixel Facades – 100 Building Textures by najjar320
https://najjar320.itch.io/pixel-facades-100-building-textures

The Citynauts · Facade Mods Guide · for the map menu's Textured, Fully Textured, Realistic, User Mod and Mod Link... modes. Also as a PDF.