Map and venues

Every building on the map has a venue tag: cafe, gym, bar, hospital, home… Tags are the shared vocabulary of the whole game: actions and scenes list them in WHERE, rooms are built per tag, look profiles are chosen by tag. They are defined in Map/amenities.json.

#amenities.json

json{
  "miles_per_hour": 3.1,
  "amenities": {
    "bar": {
      "group": "food",
      "icon": "bar",
      "open": 12,
      "close": 4,
      "name": "Bar",
      "category": "retail",
      "roll": 1,
      "ensure": true
    }
  }
}

How a building gets its tag: its OSM amenity=* or shop=* value if that is a known tag, else its building=* value through osm_buildings, else a weighted roll within its bucket.

The base game has two landmarks: the town hall (townhall, OSM's own tag; ul_CityHall's mayor and ul_Politics' registration happen there) and Broken Human Studio (broken_human_studio, the studio that makes the game: a dark tower with a red roof).

json"broken_human_studio": {
  "group": "work", "icon": "broken_human_studio", "open": 9, "close": 22,
  "category": "work", "roll": 0, "ensure": true,
  "landmark": { "wall": "#3A3842", "roof": "#E8344A", "floors": 16 }
}

#Changing and adding venues

The file merges field by field across mods: ship only what you change.

json{
  "amenities": {
    "bakery": { "open": 5, "close": 13 },
    "ynl_speakeasy": {
      "group": "food", "icon": "ynl_speakeasy", "name": "Speakeasy",
      "open": 21, "close": 3, "category": "retail", "roll": 0.2, "ensure": true
    }
  }
}

A new tag needs, to be worth visiting: an icon (Map/Icons/Locations/ynl_speakeasy.png), a room recipe, and some actions with the tag in WHERE. If its strangers should be someone in particular (a back alley is not a bakery), a crowd profile.

#The base vocabulary

The base game defines about 180 tags. Some you will use often:

The full list is the keys of ul_Base/Map/amenities.json. Special WHERE values that are not venues: all, none, interaction, quest.

#Map icons

Map/Icons/<Group>/<name>.png, looked up across mods (a later mod replacing the same path). Groups used by the base game: Locations (venue markers), Stats (player panel chips), Moods, History, Quest, Stock, UI, Markers, MapControls, Weather, Districts, Preferences. Mod UI pages use any group you like (MENU.icon, see Mod UI).

Use white glyphs on a transparent background: the HUD tints them.

#City styles

Map/city_styles.json defines the colours of the city's buildings, roads and street lamps look. The player picks a style in the map settings; default is used until they do. A later mod replaces a style with the same name.

json{
  "default": "model_white",
  "styles": {
    "ynl_neon": {
      "use_osm_colours": false,
      "walls": ["#1B1030", "#241540", "#2E1A52"],
      "roofs": ["#3A2170", "#4B2A8C"],
      "lamps": { "spacing": 2400, "lit_streets": 0.8, "radius": 1200, "color": "#FF4FD8", "intensity": 0.2 },
      "roads": { "street": "#2A2A33", "major": "#23232B", "highway": "#1C1C22" }
    }
  }
}

| look | Optional. The map's composed atmosphere, see below |

Buildings are always plain colour. Base styles: underlives (the default), night_blue, pastel, slate_teal, warm_sand, model_white, sunset. Test one with -CityStyle=<name>, and an hour with -LookHour=<0-23>.

#The look block

Without look the map is lit by the plain day cycle and the weather. With it, the style decides what the map looks like at every hour: fixed exposure, a clear view up to a horizon fade, lit windows at night.

json"look": {
  "shadows": true,
  "skyline": { "share": 0.12, "min_span": 2200, "min_floors": 16, "max_floors": 48 },
  "windows": { "share": 0.2, "lit": 0.7, "min_height": 1100, "color": "#FFD49A", "intensity": 12 },
  "ground_color": "#DCD8D1",
  "water_color": "#7FAAD8",
  "park_color": "#355C3B",
  "day":   { "exposure": 1.5, "fog_color": "#B9BEC9", "fog_density": 0.02, "fog_start": 130000 },
  "night": { "exposure": -1.0, "fog_color": "#0E0D14", "moon": 4.0, "fill": 0.8, "road_glow": 0.45 }
}

#Traffic: vehicles.json

Cars drive the streets around wherever the camera looks, keep to their lane, queue behind slower cars and turn at junctions. They are decoration: nothing in the game reads where a car is. Map/vehicles.json lists the models and sets the traffic; the models are loose .glb (or .fbx) files in your mod's Map/ folder, loaded at runtime like furniture.

json{
  "traffic": { "cars_per_km": 28, "max_cars": 450, "speed_street": 850, "speed_major": 1150, "speed_highway": 1800, "hide_above": 70000, "shadows": true },
  "vehicles": [
    { "id": "ynl_bus", "file": "Vehicles/ynl_bus.glb", "length": 1200, "yaw": 0, "weight": 1, "paint": "#E86147", "roles": ["traffic", "bus"] },
    { "id": "police", "weight": 0 }
  ],
  "paints": [ { "color": "#F4F4F2", "weight": 18 }, { "color": "#17181C", "weight": 20 }, { "color": "#6E1820", "weight": 9 } ],
  "left_hand_cities": ["Dublin"]
}

traffic merges field by field across mods, so ship only what you change. Footpaths and service roads (OSM "other") carry no traffic. Keep models light (a few thousand triangles): hundreds are on screen at once. The base fleet is Kenney's Car Kit (CC0).

#Who lives in the homes: housing.json

Every home on the map has occupants. A home gets them the first time anything looks at it (the player walks in, a scene calls Places:residence), and keeps them in the save from then on. The people are ordinary known NPCs whose home is that building, so they are in it when their day sends them home, and nowhere else.

Map/housing.json (in ul_Base; a mod overrides a field or adds a household kind by shipping its own):

Inside a home that is not the player's, the location is residential, not home: the legacy vocabulary already kept the two apart, so WHERE = { "home" } means the player's own home. Actions marked PRIVATE = true (see Actions) are offered there only when the player is welcome. No passers-by are generated in a home: the people in it are the ones who live there, and whoever came with the player.