added a docs article on creating custom maps

docs/articles/cheats.md

@@ -19,13 +19,16 @@ You can open up the game's cheat menu by pressing the `F1` key. Here is a list o
 - `Forget [name without spaces]` deletes any active relationships between the named partner and the current person.
 - `FreeLots` makes creating and importing households onto lots free.
 - `BigScreenshot` takes a full-size screenshot of the entire map, which might take a few seconds to save, during which the game will be stalled.
-- `LifeGoal [goal] [stage]` sets the current person's life goal to the goal and stage number. 
+- `LifeGoal [goal] [stage]` sets the current person's life goal to the goal and stage number.
   - `LifeGoal Advance` advances the current person's current life goal by one stage.
 - `Time [time]` sets the game's current time to the given number of hours. The current day will remain the same.
 - `Day [weekday name]` sets the game's current weekday to the given day by advancing time until the day is reached. Weekday names have to start with an uppercase letter.
+- `ShowDebugActions` will enable a set of debug actions you can always select in-game, including teleporting to a certain location, adding people to your household, and more.
+- `AgeUp` will cause the selected person to age up if possible.
+- `RemoveRandos` will remove any randomly generated people from the map and regenerate them.
 
 ## Modding and debug cheats
-- `EditWorld` allows you to place things outside of lots and adds the ability to add new lots to the world. Lots can be added using the Lots tool, and removed by clicking on them using the Remove tool.
+- `EditWorld` allows you to place things outside of lots and adds the ability to add new lots to the world. You can find out more about editing the world in the [custom maps tutorial](custom_maps.md).
 - `Held [object name or null]` sets the current person's held object. You can find a list of all object names [in the API docs](xref:TinyLife.Objects.FurnitureType).
 - `EditCurrentActionSpot` turns on action spot edit mode, which allows you to easily edit the properties of the selected person's current action spot.
   - The person's animation stops, but they are drawn on all surrounding objects of the same type instead, which makes it easier to ensure that the offset looks correct in multiple rotations and positions.

docs/articles/custom_maps.md

@@ -0,0 +1,39 @@
+Tiny Life features the ability to create custom maps that you can share with the community. This includes setting down custom lots, households, and environment decorations. Creating custom maps in this way is a lot more involved than creating custom households or lots, so this tutorial explains everything you need to know.
+
+# Getting Started
+To get started, simply create a new save file that'll serve as the basis for your new map. If you want to create a completely custom map, you'll have to delete everything that is on the default map you chose.
+
+There's a set of required [cheats](cheats.md) that you have to enable to be able to create custom maps. You can open the cheat menu with the `F1` key.
+- `EditWorld` allows you to place build mode items outside the current lot.
+- `ShowNonBuyable` allows you to access hidden build mode items, like decorative power poles, road tiles, and more.
+
+Now, you'll be able to edit the map to your heart's content. Note that you can only delete lots if they don't currently have a household occupying them, so you'll have to export or delete existing households first.
+
+# Caveats
+There's a few engine details that you'll have to pay attention to when creating custom maps. Currently, these aren't enforced in the game, so ignoring them might lead to unexpected results.
+- Roads have to be made of the hidden road tiles, and they have to be 5 tiles across to be registered as driveable area. Lane markings are optional.
+- Every map needs to have at least one road that exits the map's border, otherwise people will not be able to go out of town, which might lead to crashes during gameplay.
+- Lots should not intersect each other.
+- Newly placed lots should have a name assigned to them prior to exporting, as otherwise they will be marked as incomplete, causing them to behave unexpectedly.
+- Some build mode features behave unexpectedly outside of lots and especially close to the borders of the map, so take care when placing walls and roofs there.
+
+# Useful Cheats
+There's a few cheats not listed in the [cheats article](cheats.md) that are useful exclusively for editing custom maps.
+- `ResizeMap [width in sections] [height in sections]` allows you to change the size of the map. A section's width and height is 8 tiles. Note that, if you input a smaller width and height than the map's current size, anything beyond the borders will be deleted.
+- `MoveMap [x section amount] [y section amount]` moves the map and all of its contents by a given amount of sections. This is useful if you want to add content beyond the top or left borders of the map where resizing doesn't add any additional space.
+
+# Exporting Your Map
+To export your custom map, simply execute the `ExportCustomMap` cheat. This will reset some of the map's properties to default values, which includes normalization the skill level progress and relationships of everyone on the map. You can find your exported map in the [game directory's](game_dir.md) `Custom Maps` folder.
+
+Before sharing your map with the community, there are two additional files that are required to make the map work in-game:
+- A `txt` file with the same name as your map file that contains the description of your map which will be displayed when creating a new save file in the game.
+- A `png` file that contains a screenshot of a prominent part of your map (or any other image) which will aos be displayed when creating a new save file. The game expects this file to have 4:1 aspect ratio, with the default maps' size being 512x128 pixels.
+
+Optionally, you can put the three files into a `zip` archive to share with the community. The archive can then be put into the game's `Custom Maps` folder as-is, and the map will be available to select in-game.
+
+# Editing or Updating Your Map
+If you want to update your map, either by adding additional content to it, or by fixing issues that you noticed, like incomplete roads or misplaced decorations, you can simply create a new save file and select your map's export.
+
+When you're done editing the map using the normal procedure described above, you can export it again. The map's `StaticVersion` will automatically be increased, which means anyone who installs the updated version of your map and loads a save file will see the save file be updated to the new version of your map automatically.
+
+Note that, for this process to work, the map's `json` file has to have the exact same name as before, so you shouldn't include a version number in your map's name.

docs/articles/game_dir.md

@@ -1,6 +1,6 @@
 # Tiny Life's Data Folder
 Tiny Life's data folder contains several useful folders and files:
-- `Custom Lots`, `Custom Households` and `Mods` are the folders that you can put [custom content](getting.md) into.
+- `Custom Lots`, `Custom Households`, `Custom Maps`, and `Mods` are the folders that you can put [custom content](getting.md), including [custom maps](custom_maps.md), into.
 - `Logs` is the folder where the game's log files are stored. When you experience an issue like a crash, the information about it is stored in the most recently modified log file. If you restart the game, a new log file is created, so the one that contains the information about the issue becomes the second most recently modified file, and so on.
 - `Saves` is the folder where your save files are located. If you want to share a save file with a friend, or back it up manually, you can do so from there.
 - `Screenshots` is the folder where the game's screenshots (captured using `F12` by default) are stored.
@@ -14,13 +14,13 @@ You can open the data folder easily from within the game by going to the options
 ## From your computer
 ### Windows
 On Windows, you can simply open a file explorer window and paste the following text into its location field:
-``` 
+```
 %LocalAppData%\Tiny Life
 ```
 This should automatically cause the explorer to navigate to the appropriate folder.
 
 ### Linux
-On Linux, you have to navigate to your home directory (also known as `~`) first. This is usually `/home/username`. From there, you can navigate to `.local/share/Tiny Life`. 
+On Linux, you have to navigate to your home directory (also known as `~`) first. This is usually `/home/username`. From there, you can navigate to `.local/share/Tiny Life`.
 
 Since `.local` is usually a hidden folder, you might have to configure your file explorer to display hidden files as well.
 
@@ -30,11 +30,11 @@ cd ~/.local/share/Tiny Life
 ```
 
 ### Mac
-On Mac, you have to navigate to your home directory (also known as `~`) first. This is usually `Macintosh HD/Users/username`. From there, you can navigate to `.local/share/Tiny Life`. 
+On Mac, you have to navigate to your home directory (also known as `~`) first. This is usually `Macintosh HD/Users/username`. From there, you can navigate to `.local/share/Tiny Life`.
 
 Since `.local` is usually a hidden folder, you might have to configure your finder to display hidden files by pressing `Cmd + Shift + .` together.
 
 You can also use a command line to navigate to the folder directly using the following command:
 ```
 cd ~/.local/share/Tiny Life
-```
+```

docs/articles/getting.md

@@ -3,8 +3,9 @@ You can get custom lots, households and mods from [the community](https://itch.i
 
 Installing a mod or other custom content is pretty simple:
 - Find the `Tiny Life` folder by following [this simple guide](game_dir.md)
-- Find the `Mods` (or `Custom Lots` or `Custom Households`) folder in there
+- Find the `Mods` (or `Custom Lots`, `Custom Households` or `Custom Maps`) folder in there
   - For mods, if you received it as a `zip`, just put it straight into the `Mods` folder. If it's any other kind of archive, you need to extract it first, and then you can put the mod's `dll` as well as its `Content` folder into the `Mods` folder.
   - For custom lots and households, simply put the `json` file(s) you received into the respective folder.
+  - For custom maps, simply put the `zip` archive you received (or the three map files as described in [the custom maps article](custom_maps.md)) into the `Custom Maps` folder.
 
 Done! Now just start the game and the added content should automatically load. If there are any errors, they'll be logged in the most recent file in the `Tiny Life/Logs` folder.

docs/articles/toc.yml

@@ -6,9 +6,11 @@
       href: mod_basics.md
     - name: Creating Textures
       href: creating_textures.md
+    - name: Creating Custom Maps
+      href: custom_maps.md
 - name: Contributing Localizations
   href: localization.md
 - name: Tiny Life's Data Folder
   href: game_dir.md
 - name: Testing Cheats
-  href: cheats.md
+  href: cheats.md