1# Region Settings
2
3The **region_settings** define the attributes for map generation that apply to an entire region.
4The general settings define the default overmap terrain and ground cover. Additional sections are
5as follows:
6
7|             Section             |                              Description                              |
8| ------------------------------- | --------------------------------------------------------------------- |
9| `region_terrain_and_furniture`  | Defines the resolution of regional terrain/furniture to actual types. |
10| `field_coverage`                | Defines the flora that cover the `field` overmap terrain.             |
11| `overmap_lake_settings`         | Defines parameters for generating lakes in the region.                |
12| `overmap_forest_settings`       | Defines parameters for generating forests and swamps in the region.   |
13| `forest_mapgen_settings`        | Defines flora (and "stuff") that cover the `forest` terrain types.    |
14| `forest_trail_settings`         | Defines the overmap and local structure of forest trails.             |
15| `city`                          | Defines the structural compositions of cities.                        |
16| `map_extras`                    | Defines the map extra groups referenced by overmap terrains.          |
17| `weather`                       | Defines the base weather attributes for the region.                   |
18| `overmap_feature_flag_settings` | Defines operations on overmap features based on their flags.          |
19
20Note that for the default region, all attributes and sections are required.
21
22### Fields
23
24|       Identifier        |                            Description                             |
25| ----------------------- | ------------------------------------------------------------------ |
26| `type`                  | Type identifier. Must be "region_settings".                        |
27| `id`                    | Unique identifier for this region.                                  |
28| `default_oter`          | Default overmap terrain for this region.                           |
29| `default_groundcover`   | List of terrain types and weights applied as default ground cover. |
30
31
32### Example
33```json
34{
35	"type": "region_settings",
36	"id": "default",
37	"default_oter": "field",
38	"default_groundcover": [
39		["t_grass", 4],
40		["t_dirt", 1]
41	]
42}
43```
44
45## Region Terrain / Furniture
46
47The **region_terrain_and_furniture** section defines the resolution of regional terrain/furniture
48to their actual terrain and furniture types for the region, with a weighted list for
49terrain/furniture entry that defines the relative weight of a given entry when mapgen resolves the
50regional entry to an actual entry.
51
52### Fields
53
54| Identifier  |                            Description                             |
55| ----------- | ------------------------------------------------------------------ |
56| `terrain`   | List of regional terrain and their corresponding weighted lists.   |
57| `furniture` | List of regional furniture and their corresponding weighted lists. |
58
59### Example
60```json
61{
62	"region_terrain_and_furniture": {
63		"terrain": {
64			"t_region_groundcover": {
65				"t_grass": 4,
66				"t_grass_long": 2,
67				"t_dirt": 1
68			}
69		},
70		"furniture": {
71			"f_region_flower": {
72				"f_black_eyed_susan": 1,
73				"f_lily": 1,
74				"f_flower_tulip": 1,
75				"f_flower_spurge": 1,
76				"f_chamomile": 1,
77				"f_dandelion": 1,
78				"f_datura": 1,
79				"f_dahlia": 1,
80				"f_bluebell": 1
81			}
82		}
83	}
84}
85```
86
87
88## Field Coverage
89
90The **field_coverage** section defines the furniture and terrain that make up the flora that
91cover the `field` overmap terrain.
92
93### Fields
94
95|         Identifier         |                                 Description                                  |
96| -------------------------- | ---------------------------------------------------------------------------- |
97| `percent_coverage`         | % of tiles in the overmap terrain that have a plant.                         |
98| `default_ter`              | Default terrain feature for plants.                                          |
99| `other`                    | List of features with % chance when `default_ter` isn't used.                |
100| `boost_chance`             | % of field overmap terrains with boosted plant growth.                       |
101| `boosted_percent_coverage` | % of tiles in the boosted that have a plant.                                 |
102| `boosted_other`            | List of features in the boosted with % chance when `default_ter` isn't used. |
103| `boosted_other_percent`    | % of `boosted_percent_coverage` that will be covered by `boosted_other`.     |
104
105### Example
106```json
107{
108	"field_coverage": {
109		"percent_coverage": 0.9333,
110		"default_ter": "t_shrub",
111		"other": {
112			"t_shrub_blueberry": 0.4166,
113			"t_shrub_strawberry": 0.4166,
114			"f_mutpoppy": 8.3333
115		},
116		"boost_chance": 0.833,
117		"boosted_percent_coverage": 2.5,
118		"boosted_other": {
119			"t_shrub_blueberry": 40.0,
120			"f_dandelion": 6.6
121		},
122		"boosted_other_percent": 50.0
123	}
124}
125```
126
127## Overmap Lake Settings
128
129The **overmap_lake_settings** section defines the attributes used in generating lakes on the
130overmap. The actual placement of these features is determined globally across all overmaps so that
131the edges of the features align, and these parameters are mostly about how those global features
132are interpreted.
133
134### Fields
135
136|                 Identifier                 |                                 Description                                 |
137| ------------------------------------------ | --------------------------------------------------------------------------- |
138| `noise_threshold_lake`                     | [0, 1], x > value spawns a `lake_surface` or `lake_shore`.                  |
139| `lake_size_min`                            | Minimum size of the lake in overmap terrains for it to actually spawn.      |
140| `lake_depth`                               | Depth of lakes, expressed in Z-levels (e.g. -1 to -10).                     |
141| `shore_extendable_overmap_terrain`         | List of overmap terrains that can be extended to the shore if adjacent.     |
142| `shore_extendable_overmap_terrain_aliases` | Overmap terrains to treat as different overmap terrain for extending shore. |
143
144### Example
145
146```json
147{
148	"overmap_lake_settings": {
149		"noise_threshold_lake": 0.25,
150		"lake_size_min": 20,
151		"lake_depth": -5,
152		"shore_extendable_overmap_terrain": ["forest_thick", "forest_water", "field"],
153		"shore_extendable_overmap_terrain_aliases": [
154			{ "om_terrain": "forest", "om_terrain_match_type": "TYPE", "alias": "forest_thick" }
155		]
156	}
157}
158```
159
160## Overmap Forest Settings
161
162The **overmap_forest_settings** section defines the attributes used in generating forest and swamps
163on the overmap. The actual placement of these features is determined globally across all overmaps
164so that the edges of the features align, and these parameters are mostly about how those global
165features are interpreted.
166
167### Fields
168
169|               Identifier               |                              Description                               |
170| -------------------------------------- | ---------------------------------------------------------------------- |
171| `noise_threshold_forest`               | [0, 1], x > value spawns `forest`.                                     |
172| `noise_threshold_forest_thick`         | [0, 1], x > value spawns `forest_thick`.                               |
173| `noise_threshold_swamp_adjacent_water` | [0, 1], x > value spawns `forest_water` if forest near a waterbody.    |
174| `noise_threshold_swamp_isolated`       | [0, 1], x > value spawns `forest_water` if forest isolated from water. |
175| `river_floodplain_buffer_distance_min` | Minimum buffer distance in overmap terrains for river floodplains.     |
176| `river_floodplain_buffer_distance_max` | Maximum buffer distance in overmap terrains for river floodplains.     |
177
178### Example
179
180```json
181{
182	"overmap_forest_settings": {
183		"noise_threshold_forest": 0.25,
184		"noise_threshold_forest_thick": 0.3,
185		"noise_threshold_swamp_adjacent_water": 0.3,
186		"noise_threshold_swamp_isolated": 0.6,
187		"river_floodplain_buffer_distance_min": 3,
188		"river_floodplain_buffer_distance_max": 15
189	}
190}
191```
192
193## Forest Map Generation Settings
194
195The **forest_mapgen_settings** section defines the attributes used in generating forest (`forest`,
196`forest_thick`, `forest_water`) terrains, including their items, groundcover, terrain and
197furniture.
198
199### General Structure
200
201At the top level, the `forest_mapgen_settings` is a collection of named configurations where each
202entry has the name of the overmap terrain that it applies to, e.g. `forest`, `forest_thick`,
203`forest_water`. It is possible to define settings for overmap terrains that are not rendered by
204the forest mapgen, but will be used when blending forest terrains with other terrain types.
205
206```json
207{
208	"forest_mapgen_settings": {
209		"forest": {},
210		"forest_thick": {},
211		"forest_water": {}
212	}
213}
214```
215
216Each terrain then has an independent set of configuration values that control the mapgen.
217
218### Fields
219
220|          Identifier           |                                 Description                                  |
221| ----------------------------- | ---------------------------------------------------------------------------- |
222| `sparseness_adjacency_factor` | Value relative to neighbors controls how sparse the overmap terrain will be. |
223| `item_group`                  | Item group used to place items randomly within the overmap terrain.          |
224| `item_group_chance`           | % chance, between 1 and 100, that an item will be placed.                    |
225| `item_spawn_iterations`       | Number of times that the item spawning will be called.                       |
226| `clear_groundcover`           | Clear all previously defined `groundcover` for this overmap terrain.         |
227| `groundcover`                 | Weighted list of terrains used for base groundcover.                         |
228| `clear_components`            | Clear all previously defined `components` for this overmap terrain.          |
229| `components`                  | Collection of components that make up the terrains and furniture placed.     |
230| `clear_terrain_furniture`     | Clear all previously defined `terrain_furniture` for this overmap terrain.   |
231| `terrain_furniture`           | Collection of furniture conditionally placed based on terrain.               |
232
233### Example
234
235```json
236{
237	"forest": {
238		"sparseness_adjacency_factor": 3,
239		"item_group": "forest",
240		"item_group_chance": 60,
241		"item_spawn_iterations": 1,
242		"clear_groundcover": false,
243		"groundcover": {
244			"t_grass": 3,
245			"t_dirt": 1
246		},
247		"clear_components": false,
248		"components": {},
249		"clear_terrain_furniture": false,
250		"terrain_furniture": {}
251	}
252}
253```
254
255### Components
256
257The components are a collection of named objects with a sequence, chance, and set of types that,
258during mapgen, are rolled in sequence to pick a feature to be placed at a given location. The names
259for the components are only relevant for the purposes of overriding them in region overlays.
260
261### Fields
262
263|  Identifier   |                             Description                              |
264| ------------- | -------------------------------------------------------------------- |
265| `sequence`    | Sequence in which components are processed.                          |
266| `chance`      | One in X chance that something from this component will be placed.   |
267| `clear_types` | Clear all previously defined `types` for this component.             |
268| `types`       | Weighted list of terrains and furniture that make up this component. |
269
270### Example
271
272```json
273{
274	"trees": {
275		"sequence": 0,
276		"chance": 12,
277		"clear_types": false,
278		"types": {
279			"t_tree_young": 128,
280			"t_tree": 32,
281			"t_tree_birch": 32,
282			"t_tree_pine": 32,
283			"t_tree_maple": 32,
284			"t_tree_willow": 32,
285			"t_tree_hickory": 32,
286			"t_tree_blackjack": 8,
287			"t_tree_coffee": 8,
288			"t_tree_apple": 2,
289			"t_tree_apricot": 2,
290			"t_tree_cherry": 2,
291			"t_tree_peach": 2,
292			"t_tree_pear": 2,
293			"t_tree_plum": 2,
294			"t_tree_deadpine": 1,
295			"t_tree_hickory_dead": 1,
296			"t_tree_dead": 1
297		}
298	},
299	"shrubs_and_flowers": {
300		"sequence": 1,
301		"chance": 10,
302		"clear_types": false,
303		"types": {
304			"t_underbrush": 8,
305			"t_shrub_blueberry": 1,
306			"t_shrub_strawberry": 1,
307			"t_shrub": 1,
308			"f_chamomile": 1,
309			"f_dandelion": 1,
310			"f_datura": 1,
311			"f_dahlia": 1,
312			"f_bluebell": 1,
313			"f_mutpoppy": 1
314		}
315	}
316}
317```
318
319### Terrain Furniture
320
321The terrain furniture are a collection of terrain ids with a chance of having furniture
322picked from a weighted list for that given terrain and placed on it during mapgen after
323the normal mapgen has completed. This is used, for example, to place cattails on fresh
324water in swamps. Cattails could be simply placed in the `components` section and placed
325during the normal forest mapgen, but that would not guarantee their placement on fresh
326water only, while this does.
327
328### Fields
329
330|    Identifier     |                            Description                             |
331| ----------------- | ------------------------------------------------------------------ |
332| `chance`          | One in X chance that furniture from this component will be placed. |
333| `clear_furniture` | Clear all previously defined `furniture` for this terrain.         |
334| `furniture`       | Weighted list of furniture that will be placed on this terrain.    |
335
336### Example
337
338```json
339{
340	"t_water_sh" : {
341		"chance": 2,
342		"clear_furniture": false,
343		"furniture": {
344			"f_cattails": 1
345		}
346	}
347}
348```
349
350## Forest Trail Settings
351
352The **forest_trail_settings** section defines the attributes used in generating trails in the
353forests, including their likelihood of spawning, their connectivity, their chance for spawning
354trailheads, and some general tuning of the actual trail width/position in mapgen.
355
356### Fields
357
358|         Identifier         |                                         Description                                         |
359| -------------------------- | ------------------------------------------------------------------------------------------- |
360| `chance`                   | One in X chance a contiguous forest will have a trail system.                               |
361| `border_point_chance`      | One in X chance that the N/S/E/W-most point of the forest will be part of the trail system. |
362| `minimum_forest_size`      | Minimum contiguous forest size before a trail system can be spawned.                        |
363| `random_point_min`         | Minimum # of random points from contiguous forest used to form trail system.                |
364| `random_point_max`         | Maximum # of random points from contiguous forest used to form trail system.                |
365| `random_point_size_scalar` | Forest size is divided by this and added to the minimum number of random points.            |
366| `trailhead_chance`         | One in X chance a trailhead will spawn at end of trail near field.                          |
367| `trailhead_road_distance`  | Maximum distance trailhead can be from a road and still be created.                         |
368| `trail_center_variance`    | Center of the trail in mapgen is offset in X and Y by a random amount between +/- variance  |
369| `trail_width_offset_min`   | Trail width in mapgen is offset by `rng(trail_width_offset_min, trail_width_offset_max)`.   |
370| `trail_width_offset_max`   | Trail width is mapgen offset by `rng(trail_width_offset_min, trail_width_offset_max)`.      |
371| `clear_trail_terrain`      | Clear all previously defined `trail_terrain`.                                               |
372| `trail_terrain`            | Weighted list of terrain that will used for the trail.                                      |
373| `trailheads`               | Weighted list of overmap specials / city buildings that will be placed as trailheads.       |
374
375### Example
376
377```json
378{
379	"forest_trail_settings": {
380		"chance": 2,
381		"border_point_chance": 2,
382		"minimum_forest_size": 100,
383		"random_point_min": 4,
384		"random_point_max": 50,
385		"random_point_size_scalar": 100,
386		"trailhead_chance": 1,
387		"trailhead_road_distance": 6,
388		"trail_center_variance": 3,
389		"trail_width_offset_min": 1,
390		"trail_width_offset_max": 3,
391		"clear_trail_terrain": false,
392		"trail_terrain": {
393			"t_dirt": 1
394		},
395		"trailheads": {
396			"trailhead_basic": 50
397		}
398	}
399}
400```
401
402## City
403
404The **city** section defines the possible overmap terrains and specials that may be used as
405buildings in a city, their weighted chances of placement, and some attributes that control the
406relative placements of various classes of buildings.
407
408### Fields
409
410|       Identifier        |                            Description                             |
411| ----------------------- | ------------------------------------------------------------------ |
412| `type`                  | City type identifier--currently unused.                            |
413| `shop_radius`           | Radial frequency of shop placement. Smaller number = more shops.   |
414| `park_radius`           | Radial frequency of park placement. Smaller number = more parks.   |
415| `houses`                | Weighted list of overmap terrains and specials used for houses.    |
416| `parks`                 | Weighted list of overmap terrains and specials used for parks.     |
417| `shops`                 | Weighted list of overmap terrains and specials used for shops.     |
418
419### Placing shops, parks, and houses
420
421When picking a building to place in a given location, the game considers the city size, the
422location's distance from the city center, and finally the `shop_radius` and `park_radius` values for
423the region. It then tries to place a shop, then a park, and finally a house, where the chance to
424place the shop or park are based on the formula `rng( 0, 99 ) > X_radius * distance from city center
425/ city size`.
426
427### Example
428```json
429{
430	"city": {
431		"type": "town",
432		"shop_radius": 80,
433		"park_radius": 90,
434		"houses": {
435			"house_two_story_basement": 1,
436			"house": 1000,
437			"house_base": 333,
438			"emptyresidentiallot": 20
439		},
440		"parks": {
441			"park": 4,
442			"pool": 1
443		},
444		"shops": {
445			"s_gas": 5,
446			"s_pharm": 3,
447			"s_grocery": 15
448		}
449	}
450}
451```
452
453## Map Extras
454
455The **map_extras** section defines the named collections of map extras--special mapgen events
456applied on top of the defined mapgen--that may be referenced by the `extras` property of an overmap
457terrain. This includes both the chance of an extra occurring as well as the weighted list of extras.
458
459### Fields
460
461| Identifier |                           Description                            |
462| ---------- | ---------------------------------------------------------------- |
463| `chance`   | One in X chance that the overmap terrain will spawn a map extra. |
464| `extras`   | Weighted list of map extras that can spawn.                      |
465
466### Example
467
468```json
469{
470	"map_extras": {
471		"field": {
472			"chance": 90,
473			"extras": {
474				"mx_helicopter": 40,
475				"mx_portal_in": 1
476			}
477		}
478	}
479}
480```
481
482## Weather
483
484The **weather** section defines the base weather attributes used for the region.
485
486### Fields
487
488|     Identifier                 |                              Description                              |
489| ------------------------------ | --------------------------------------------------------------------- |
490| `base_temperature`             | Base temperature for the region in degrees Celsius.                   |
491| `base_humidity`                | Base humidity for the region in relative humidity %                   |
492| `base_pressure`                | Base pressure for the region in millibars.                            |
493| `base_wind`                    | Base wind for the region in mph units. Roughly the yearly average.    |
494| `base_wind_distrib_peaks`      | How high the wind peaks can go. Higher values produce windier days.   |
495| `base_wind_season_variation`   | How the wind varies with season. Lower values produce more variation  |
496| `weather_types`				 | Ids of the weather types allowed in this region. When choosing weather they will be iterated over in the order they are listed and the last valid entry will be the weather. |
497
498### Example
499
500```json
501{
502	"weather": {
503		"base_temperature": 6.5,
504		"base_humidity": 66.0,
505		"base_pressure": 1015.0,
506		"base_acid": 0.0,
507		"base_wind": 5.7,
508		"base_wind_distrib_peaks": 30,
509		"base_wind_season_variation": 64,
510		"base_acid": 0.0,
511		"weather_types": [
512			"clear",
513			"sunny",
514			"cloudy",
515			"light_drizzle",
516			"drizzle",
517			"rain",
518			"thunder",
519			"lightning",
520			"flurries",
521			"snowing",
522			"snowstorm"
523      	]
524    	},
525	}
526}
527```
528
529## Overmap Feature Flag Settings
530
531The **overmap_feature_flag_settings** section defines operations that operate on the flags assigned to overmap features.
532This is currently used to provide a mechanism for whitelisting and blacklisting locations on a per-region basis.
533
534### Fields
535
536|    Identifier     |                                        Description                                         |
537| ----------------- | ------------------------------------------------------------------------------------------ |
538| `clear_blacklist` | Clear all previously defined `blacklist`.                                                  |
539| `blacklist`       | List of flags. Any location with a matching flag will be excluded from overmap generation. |
540| `clear_whitelist` | Clear all previously defined `whitelist`.                                                  |
541| `whitelist`       | List of flags. Only locations with a matching flag will be included in overmap generation. |
542
543### Example
544
545```json
546{
547	"overmap_feature_flag_settings": {
548		"clear_blacklist": false,
549		"blacklist": [ "FUNGAL" ],
550		"clear_whitelist": false,
551		"whitelist": []
552	}
553}
554```
555
556# Region Overlay
557
558A **region_overlay** allows the specification of `region_settings` values which will be applied to
559specified regions, merging with or overwriting the existing values. It is only necessary to specify
560those values which should be changed.
561
562### Fields
563
564| Identifier |                                         Description                                         |
565| ---------- | ------------------------------------------------------------------------------------------- |
566| `type`     | Type identifier. Must be "region_overlay".                                                  |
567| `id`       | Unique identifier for this region overlay.                                                   |
568| `regions`  | A list of regions to which this overlay should be applied. "all" will apply to all regions. |
569
570All additional fields and sections are as defined for a `region_overlay`.
571
572### Example
573```json
574[{
575	"type": "region_overlay",
576	"id": "example_overlay",
577	"regions": ["all"],
578	"city": {
579		"parks": {
580			"examplepark": 1
581		}
582	}
583}]
584```
585