# Setting up Cruelty Squad mapping

*Following immediately from https://hackmd.io/@OsM6oUcXSwG3mLNvTlPMZg/rk56jogV_*

## Requirements

- Working modding copy from following the above guide
- TrenchBroom

## Configuring Qodot and TrenchBroom

1. If you want to work with levels in Godot, enable the Qodot plugin in *Project > Project Settings... > Plugins*
- If it's not there, go to *AssetLib* in the top middle of the editor, search for Qodot, download it, and install these files:

2. In Godot's file manager go to `addons/qodot/game-definitions/trenchbroom`
3. Double-click `qodot_trenchbroom_config_folder.tres` to open it in the inspector
- As of the time of writing, there should be 93 entity definitions, which you can check by expanding `qodot_fgd.tres` under *Fgd Files*. If you don't have this many, check the end of this guide on how to extract this file from the game.

4. Set *Trenchbroom Games Folder* (not *Target Folder*) to the `games` folder in wherever you have TrenchBroom (`...\wherever_trenchbroom_is\games`)
5. Hit the *Export Folder* checkbox at the top of the inspector (not the one under *Fgd Files*), it worked if there's now a Qodot folder in TrenchBroom's games folder and TrenchBroom shows Qodot as one of the available games
6. Open TrenchBroom and click *New map...*
7. Click Qodot then click *Open preferences...*
8. Set the game path to the `Maps` folder of your Cruelty Squad project
9. In your Cruelty Squad project, delete every `.png.import` file in `Maps/textures`
10. Copy the game's map textures into `Maps/textures`. If you don't have them, [download them here](https://github.com/crustyrashky/crus-modbase/releases/download/not-a-release/maps_textures.zip)

With that, you're done setting up TrenchBroom.

## Creating a map

For the sake of brevity, this guide assumes you already know a thing or two about using TrenchBroom. If you don't, [this tutorial series by dumptruck_ds](https://www.youtube.com/watch?v=gONePWocbqA&list=PLgDKRPte5Y0AZ_K_PZbWbgBAEt5xf74aE) is a good primer. As such, this section will just be some quick tips.

Please let me know on Discord if you have something you think should go here.

- Set *Map Format* to Valve, since it's the format the stock maps use

- Make sure your map has a `Player` entity somewhere in it
- Enabling too many texture collections or having too many/too complicated brushes may crash Godot when you try to build your map

- You can add your own textures by following the same format the other textures do of `folder/texture`. For example, to add custom textures for your map "My Cool Map", it would be best to put them into a folder `Maps/textures/my_cool_map`
- [Check this page](https://docs.godotengine.org/en/stable/getting_started/workflow/assets/importing_images.html) for the list of supported image formats
- Custom textures are only supported in levels exported from the CruS Mod Base

## Getting your map into the game

:::spoiler **With the CruS Mod Base**

1. Install the [CruS Mod Base](https://github.com/crustyrashky/crus-modbase)

2. Create the folder `%appdata%\Godot\app_userdata\Cruelty Squad\levels\_debug`, and put your TrenchBroom mapfile in it

3. If you have custom textures, create a new folder `textures` in `_debug` and copy your textures in, making sure they have the same folder structure
- For example, a texture at `Maps/textures/myfolder/texture1.png` in your project root should be copied to `textures/Maps/textures/myfolder/texture1.png` in your `_debug` folder

4. Start the game, and it should eventually load your map. If you make changes to your map in TrenchBroom, you can see them in-game without restarting by clicking the *Reload* button in the *Levels* tab of your portable stock market terminal, or by hitting Alt-Shift-R

## Exporting to a level

1. Take a nice picture of your map! Once you're in-game, hit tab to open the stock menu, go to the *Level* tab, and scroll down to find the *Take new image* button:


Once you've taken an image, it will be saved as a 240x240 .png to both the `_debug` folder (for your level's preview image), and the `snapshots` folder in your user data folder (for fun).

2. If you like what you see, hit the *Export* button to export your map as a level.
3. Go back to the `levels` folder and your new level should be there, named whatever your mapfile was named. By default, your level's name is set to the name of the folder it's in, but it can be manually named by creating a `name` property in `level.json`

:::

:::spoiler **Manually (not recommended)**

1. Make a new scene in Godot
- The standard is to put your custom content (besides the TrenchBroom `.map`) into its own folder in another folder called `MOD_CONTENT`, e.g. if your map is called "MyCoolMap" then put your stuff into `res://MOD_CONTENT/MyCoolMap`

2. Add a Spatial node called `Level` with a Navigation, NavigationMeshInstance and QodotMap under it arranged like so:


3. Setup the QodotMap
- Click the QodotMap node to pull up
- Set *Map File* to your map
- If you decided to keep your map somewhere in the project, note that you have to use the actual OS directory path here and not the Godot `res://` path
- Do a quick build to test
- The map will be untextured, set the QodotMap's *Base Texture Dir* to `res://Maps/textures`
- Do another build and now it'll be textured
- Do a full build to actually make the level geometry

4. Find `Navigation.gd` in the FileSystem tab and drag it onto your Navigation node so that a little script icon shows up


## Trying your map out

This part of the guide uses the actual game, and not your Godot project copy.

1. Install [CruS Mod Base](https://github.com/crustyrashky/crus-modbase) and either run the game to create a `levels` folder in your Cruelty Squad saves folder (`%appdata%\Godot\app_userdata\Cruelty Squad`) or make one there yourself
2. Make a new folder in the `levels` folder to put your level in
3. Create a `level.json` file in this folder and put the following in it, edited how you like:

    {
      "author": "Your author name",
      "version": "Your version string",
      "description": "Your in-game description",
      "objectives": ["Your in-game-objective"],
      "level_scene": "NameOfYourMapScene.tscn"
    }

Check the CruS Mod Base page for more information on what can go into this file.
4. Copy the level scene you made previously into the folder
5. Start the game and your level should now show up in the game level select

:::

## Finishing touches

### Baking a navigation mesh

If you exported your level from the modbase, you may have noticed a `LEVEL_WARNING.txt` telling you to bake a navmesh. Unfortunately, there is currently no way to do this outside the Godot editor. If this step isn't done, enemies will sit in place, unable to figure out where to go.

1. Open `mod.zip` in the CruS Mod Base folder, and extract the `MOD_CONTENT` folder to your project root
2. Copy your level to the newly extracted `MOD_CONTENT`, and open your level's .tscn file in Godot
3. In the *Scene* tab on the left, Drag your QodotMap under NavigationMeshInstance
4. Click the NavigationMeshInstance and a Bake NavMesh button will appear at the top middle of the editor
5. Click Bake NavMesh and a turquoise layer should appear over all the walkable looking areas of your level
- If the navmesh has holes or is broken up in areas where entities are, you may have to do the level geometry by itself by selecting and dragging the QodotMap worldspawn and any func_group area nodes on their own. To make the process quicker, you can filter the func_groups, scroll down and shift-click select them all like so:


6. Drag the nodes back out to where they were before

### Custom music

Copy your music (in .ogg format) to your level folder and edit the `music` property in `level.json` accordingly.

You can also add the `ambience` property in a similar way, which seems to make it so that the `ambience` track plays normally, while the `music` track plays during combat.

### Custom dialogue

Regular NPC dialogue can be added by adding more entries to the `dialogue` property in `level.json`, which is set to the array `["..."]` by default, or by creating a new JSON file and setting `dialogue` to its filename. The dialogue JSON file should also just be an array of text.

For now, special NPC dialogue must be set in the Godot editor. It's also best to manually add any NPCs you want to give special dialogue in it, by going to the `Entities/Enemies` folder and dragging them into your level.


Make sure that any NPC you've dragged into your level isn't inside the QodotMap node.

### Adding special NPC dialogue

1. Right-click the NPC's node in the *Scene* tab and turn on *Editable Children*:


2. Click the NPC's *Body* node. To the right, the *Inspector* tab should show its properties. Open the *Lines* property, and you will be able to add lines of dialogue by increasing its size.


Once you're done, copy these files back to your `levels` folder and your level is ready to distribute to other people.

### NPC behaviors and properties

There are a lot of things you can change about NPCs by hand-editing your level `.tscn` file.

1. After exporting your level and opening it in Godot, find the NPC you want to edit and click on them to get their name. Here, the name of this NPC is `entity_87_E_Security`.


2. Open your level `.tscn` file in your text editor of choice and search for the NPC's name. Under the corresponding `[node name ...` line, you can manually set the NPC's variables. In this example, I've set the NPC to be be a cursed/hell difficulty target and made it very slow.


A non-exhaustive list of variables to try:
- Boolean (`true`/`false`)
- `hell_objective` - Whether or not the NPC is a hell/cursed target
- `objective` - Whether or not the NPC is a normal target
- `random_spawn` - Whether or not the NPC is one that normally doesn't always spawn
- `poison_death` - Whether or not the NPC will explode into a cloud of poison gas on death
- `psychosis_inducer` - Whether or not the NPC will make your vision swim when looking at you
- `armored` - Whether or not the NPC is armored
- You should set `armor` as well
- Number
- `armor` - Amount of armor an NPC has
- Big skeleton mechs and golems have 500 armor
- `health` - Amount of health an NPC has
- Civilians usually have 15 health, enemies usually have 50 health
- `gib_health` - Amount of health an NPC has to reach before it explodes into gibs
- This is normally -50 health

Note that a lot of variables will likely conflict in strange ways, so some trial and error is involved. You can look through the NPCs in the official levels and the custom level "Armed Men In A Building" by ConsulCast which can be found [here](https://github.com/crustyrashky/crus-modbase/files/7230712/level.zip) for guidance and ideas, and the beginning definitions in `Scripts/EnemyHandler.gd` in the project folder for a complete list of variables you can tinker with.

## Conclusion

Now that everything is done, zip it up with a readme file so people know what they're getting into and you've finished a custom Cruelty Squad level.

Feel free to direct your comments, questions, suggestions or new levels to the #modifications channel on Discord. There isn't a real place to host custom Cruelty Squad content yet, so if your level is done and doesn't have any nasty stuff in it, I'll probably pin it and throw it onto the modbase GitHub page.

## Notes

- When sharing your level pre-export, be aware that the .tscn will contain the OS file path to your mapfile, which may include your computer's username
- If your map is failing to build, or for `_debug` folder maps, crashing the game on startup/reload, make sure you don't have too many texture collections enabled
- If your map's custom textures crash the game upon loading, you might be able to work around this by disabling their collection(s) after applying the textures and before saving
- Useful map debug shortcuts:
- Ctrl-S: Save changes
- Shift-N: Toggle noclip
- Alt-Shift-R: Reload mapfile
- If you want to rotate the player, rotate the Body node inside, not the whole thing
- The bare minimum requirements for a level are a Navigation with a NavigationMeshInstance child, a QodotMap and an instance of `Player_Test.tscn`
- If you don't have a player node, either because you didn't add one in TrenchBroom for some reason or entities didn't setup properly, you can drag a `Player_Test.tscn` into your level

- The CruS Mod Base map loader loads levels in the `user://levels` folder first, so if you are making changes to your level in `MOD_CONTENT` and don't see them, check to make sure it isn't because it's loading that instance instead
- If there are exclamation marks on parts of your map in the node editor and it has no collision try full building until the exclamation marks go away
- If you set a QodotMap node to a map that uses texture folders which differ from yours, and fix the folders to try and get the textures to show up, it isn't enough to do another full build
- You have to delete the node and make a new one or it'll remain untextured

### Extracting `qodot_fgd.tres` from the game

This assumes you already have the [CRUELTY SQUAD MODLOADER](https://github.com/crustyrashky/crus-modloader) installed.

1. Open the game's user data folder, `%appdata%\Godot\app_userdata\Cruelty Squad`
2. Make a new file called `modloader.cfg` and add the following to it:

    [util]
    dump_fgd=true

3. Run the game, and it should appear in the folder.
4. If you extracted it to replace an existing broken one, replace `addons/qodot/game-definitions/fgd/qodot_fgd.tres` in your project and configure Qodot and TrenchBroom again.