This handbook aims to give you a starting point for making mods for Quadrilateral Cowboy. Mods can be many things -- create or modify maps, characters, equipment, and almost anything else.

Quadrilateral Cowboy uses id Software's idTech4 game engine. This engine was previously used in games such as Doom 3, Quake 4, and Brink.

If you have any modding questions, please ask in the Modding discussion forum.

Ready to start? Here we go.

To start, a mod needs a folder for all of its files. Let's create this folder.

1. Enter Quadrilateral Cowboy's root folder.
   

   It will likely be something similar to:
   steam\steamapps\common\quadrilateralcowboy

2. Create a new folder for your mod. Give it a distinctive name.
   

   • Keep the folder name less than 16 characters.
     
   • Do not use spaces in the folder name.
     
   • Your setup should now look like this:
     

Great, we now have a folder for your new mod. Now we need to set up some information files for this new mod.

This file determines the name of the mod.

1. Enter your mod's folder.
   
2. In the mod's folder, create a file called: description.txt
   
3. In this file, enter the title of your mod.
   

   • This determines what appears in the main menu MODS list.
     
   • The file should consist of just one line.

Create a dummy PK4 file. This allows the game to find your mod.

1. Enter your mod's folder.
   
2. In the mod's folder, create an empty file called: pak000.pk4
   

   • I usually just create an empty text file and then rename it to pak000.pk4
     
   • Those are three zeroes.
     
   • Your setup should now look like this:
     

Time to test out your new mod.

1. Run Quadrilateral Cowboy.
   
2. In the main menu, select: Mods
   
3. Your new mod should appear in the list. Select it and click: ACTIVATE MOD

Great! The mod doesn't do anything yet -- it's basically empty at the moment -- so let's add new content to it.

To create and edit maps, Quadrilateral Cowboy uses a tool called DarkRadiant.

DarkRadiant was made for The Dark Mod, a great Doom 3 mod. The creators of DarkRadiant have graciously made their editor compatible with other games, for which I'm tremendously thankful.

We'll begin by downloading and installing DarkRadiant.

1. Download DarkRadiant at: http://darkradiant.sourceforge.net
   
2. Install DarkRadiant.
   
3. Run DarkRadiant.

On initial startup, DarkRadiant will request setup information. Use these settings:

You should now see something like this:

Your window layout might look different. To use the same window layout as pictured above:

1. In the top menu bar, select: View > Window Layout > Regular
   
2. Exit DarkRadiant
   
3. Start DarkRadiant

In this walkthrough, I'm going to refer to the windows with these names:

Let's make a map. Map architecture is made up of solid pieces of geometry, also known as brushes. A brush can be thought of as a building block - if you see a wall, or ceiling, or floor, it's probably made up of one or more brushes.

Let's create a simple wall brush.

1. On your keyboard, press the minus key until the status bar's grid size reads 256:
   
   
2. In the 2D window, press and hold LMB to draw a wall brush. It should look similar to this:
   
   
3. Press ESC to deselect the wall brush. Done!

One wall is good, but four walls is better. Let's make more walls.

1. In the 2D window, press and hold LMB to make another wall brush:
   
   
2. Press ESC to deselect the wall brush.
   
3. Repeat steps 1 and 2 until you have four wall brushes that look like this:
   

We now have four walls. Let's add a floor brush.

1. Press CTRL+TAB. This will change the 2D window's perspective. Notice the 2D window is now looking from a side view.
   
2. Press and hold LMB to draw the floor brush:
   
   
3. Press ESC to deselect the floor brush. Done!

Let's finish this room with a ceiling brush.

1. Press and hold LMB to draw the ceiling brush:
   
   
2. Press ESC to deselect the ceiling brush. Done!

Your First Room: Review

Let's review some of the things we covered in this section:

• BRUSH: a piece of architectural geometry. Create by holding down LMB.
  
• DESELECTION: deselect everything by pressing ESC.
  
• GRID: The plus and minus keys resize the grid.
  
• 2D PERSPECTIVE: Pressing CTRL+TAB will cycle the 2D window's perspective.

We now have four walls, a floor, and a ceiling. There's your first room! In the next section, we'll paint the walls with some textures.

Let's move the camera to a good spot.

1. Move the mouse cursor into the 3D window.
   
2. Press RMB to activate camera mode.
   
   • Move the mouse to rotate the camera.
     
   • Press the keyboard's arrow keys to move the camera.
3. Press RMB again to exit camera mode.

The walls look a little naked. Let's give them some textures.

1. In the 3D window, move the mouse cursor onto a wall brush.
   
2. Press SHIFT+LMB to select that wall brush:
   
   
3. Press S to open the Surface Inspector.
   
4. Click the folder icon:
   
   
5. Click blue64:
   
   
6. Click OK:
   
   
7. Click the X button to close the Surface Inspector:
   
   
8. Press ESC to deselect the wall.

Great, the map now has one textured wall brush. Let's texture the rest of the brushes.

1. Move and rotate the camera to face an untextured brush.
   
2. In the 3D window, SHIFT+LMB select an untextured brush.
   
3. In the Material Browser, click blue64:
   
   
4. Press ESC to deselect the brush.
   
5. Repeat steps 1-4 until all surfaces are textured.

Texturing Your First Room: Review

Let's review what we covered in this section.

• CAMERA: press RMB in the 3D window to toggle camera mode.
  
• BRUSH SELECTION: press SHIFT+LMB to select brushes.
  
• SURFACE INSPECTOR: press S to choose textures.

Great, everything is now textured. In the next section, we'll give the map a start point and a light source.

If something moves, affects the world in some way, or can be interacted with, it's an entity. Examples of entities include doors, breakable windows, and soda cans.

We're going to place two entities into this map:

• A player start point.
  
• A light source.

1. Press the keyboard's plus key until the grid size is 64. The current grid size can be found on the status bar:
   
   
2. In the 2D window, move the mouse cursor inside the room:
   
   
3. Press RMB.
   
4. Click Create Entity:
   
   
5. Click the + icon.
   
   
6. Find info_player_start in the list and click it.
   
7. Click Add.
   
8. Press ESC to deselect the entity. Done!

If the placement of the entity does not look right, let's adjust it.

1. SHIFT+LMB on the player start point to select it.
   
2. Hold LMB on the player start point. Drag it. Release LMB when done.
   
3. Press CTRL+TAB to look at the player start point from different perspectives.

1. Follow the steps in the above Add the Player Start section.
   
2. In step 6, click on light (instead of info_player_start).

Adding Entities to Your First Map: Review

Let's review what we covered in this section:

• PLACING ENTITIES: press RMB to add entities.
  
• ENTITY SELECTION: press SHIFT+LMB to select entities.
  
• MOVING ENTITIES: hold LMB on a selected entity.
  
• DESELECTION: press ESC to deselect entities.

Great, the room now has a player start point and a light source. In the next section, we'll test the map.

It's time to play this map.

1. Click File > Save as...
   
2. Enter the mod folder you created in the Modding: Folder Creation section.
   
3. Click the Create Folder button. Name the folder: maps
   

   The folder structure should look like:
   

4. Enter the maps folder.
   
5. In the Name field, type: coolmap
   
6. Click Save

To make testing easier, let's enable the console.

1. Run Quadrilateral Cowboy.
   
2. Click Options > Advanced Options
   
3. Click Debug Console to YES
   
4. Done!

Let's activate your mod.

1. Run Quadrilateral Cowboy.
   
2. Click on: Mods
   
3. Select your mod from the list.
   
4. Click on: ACTIVATE MOD
   
   
   Compile
   In order for the Quadrilateral Cowboy to understand the new map, we first have to compile it.
   
   1. Run Quadrilateral Cowboy.
      
   2. On the keyboard, press tilde (the key next to 1) to toggle the console.
      
   3. Type: dmap coolmap
      
   4. Done!
   
   

   Leaks

   If you receive this error message...
   
   ...then it means there's a leak in the map. Leaks must be fixed before the map can be run.
   
   What's a leak?
   
   

   • First, let's consider everything outside of rooms as a void.
     
   • Room interiors must be 100% airtight from the void.
     
     • If a room's interior has any line-of-sight into the void, then the map is considered to be leaking.
   • Entities must be placed inside rooms.
     
     • If an Entity is in the void or has line-of-sight into the void, then the map is considered to be leaking.

   
   
   Play the map
   1. Run Quadrilateral Cowboy.
      
   2. On the keyboard, press tilde (the key next to 1) to toggle the console.
      
   3. Type: map coolmap
   
   Done! Welcome to your first room.
   
   

The console grants access to various developer tools and debug information.

To enable console access:

1. In Quadrilateral Cowboy's main menu, click Options > Advanced Options
   
2. Set Debug Console to YES
   
   • On your keyboard, you may now press tilde (next to the 1 key) to open the console.
     
   • Press tilde again to close the console.

When you update any files, enter these commands to dynamically reload the asset while the game is running.

What are scripts? A script:

• handles the logic in maps, weapons, and characters.
  
• uses its own language, DoomScript.
  
• is represented by text files.
  
• are files are appended with a .script suffix.

For this introduction to scripting, we'll cover basic map scripting functionality.

Let's make a map script file.

1. Enter the folder you saved your map file in.

   It will likely be something similar to: steam\steamapps\common\quadrilateralcowboy\YOUR_MOD_NAME\maps

2. In this folder, create a text file named: coolmap.script
   

   Ensure your map file and script file share the same name. For example, if your map file name is coolmap.map, then the script file should be named coolmap.script

3. Open coolmap.script with a text editor.
   

   I use Notepad++[notepad-plus-plus.org] but any text editor will work fine.

4. Copy and paste this into your newly-created script file:
   namespace coolmap { void main() { sys.println("hello coolmap world"); } }

Great, now we have a brand-new script file. Next, let's connect this script file to the map.

Let's connect the script file to the map.

1. Return to DarkRadiant. Open coolmap.map
   
2. In the 3D window, move the mouse cursor onto a wall brush.
   
3. Press SHIFT+LMB to select that wall brush:
   
4. Press N to open the Entity Inspector:
   
5. Enter into the two fields:
   
   • call
     
   • coolmap::main
   
6. Press the enter key. The Entity Inspector should now look like this:
   

Done. Now, when you run the game, the map will activate the script file's main() function.

Let's verify that it works. Test it by running the game, loading coolmap, and then opening the debug console. Somewhere in the debug text, it should read:

Let's add some further functionality. When the map starts, we'll give the player some starting equipment.

1. Use a text editor to open the coolmap.script file.
   
2. Find the main() function. Between the curly brackets, add these lines:
   $player1.giveInventoryItem( "weapon_deck" ); $player1.giveInventoryItem( "weapon_cctv" ); $player1.giveInventoryItem( "weapon_weevil" );
3. Save the file. The entire script file should now look like this:
   
   namespace coolmap { void main() { sys.println("hello coolmap world"); $player1.giveInventoryItem( "weapon_deck" ); $player1.giveInventoryItem( "weapon_cctv" ); $player1.giveInventoryItem( "weapon_weevil" ); } }

Run the game and load coolmap. The player should now auto-equip with the deck, the CCTV, and the weevil.

Now, what does all this mean? Let's break it down:

Let's create a custom texture for your mod.

1. Enter your mod's folder.
   
2. Create a new folder named: textures
   
3. Use an image program (i.e. Photoshop, paint .net, GIMP) to create a texture.

   • Ensure each dimension of the texture size is a power of 2.
     
     • Examples: 128x128, 64x64, 512x64, 32x1024
       
     • An easy way to verify this is to see if the dimension is divisible by 16. If yes, then it's valid.
   • Do not have a texture dimension size exceed past 1024.
     
   • Use the TGA file format.

4. Save the image inside the textures folder. For this example, let's name the file: cooltexture.tga

1. Enter your mod's folder.
   
2. Create a new folder named: materials
   
3. Inside this materials folder, create a text file: coolmaterials.mtr
   
4. Paste this into coolmaterials.mtr:
   textures/cooltexture { diffusemap textures/cooltexture }

We've just created a very basic texture. Restart DarkRadiant. Now when you browse the texture library, you should now see your new texture ready to use.

If you need a refresher on how to use textures in DarkRadiant, refer back to the Mapping: Texturing Your First Room section.

Feel like sharing? Upload and share your mod on the Steam Workshop.



To share mods, first install the Quadrilateral Cowboy Workshop Uploader.

1. In your Steam window, click LIBRARY.
   
2. Click TOOLS.
   
3. In the list, find Quadrilateral Cowboy Workshop Uploader. Double-click it to install.
   
4. Done! Quadrilateral Cowboy Workshop Uploader will now appear in your Steam library (in the TOOLS section).

Now that the tool is installed, let's upload your mod to the Steam Workshop.

1. Run Quadrilateral Cowboy Workshop Uploader.
   
2. Click the Add new mod button.
   

   • Fill out all the fields.
     
   • For the Thumbnail field, point it to an image file. This image will be the preview image for your workshop item. I suggest using a 512x512 PNG file.
     
   • For the Data folder field, point it to the folder that contains your mod.

3. Click the Add mod to Workshop button to start the upload. Done!

Upload changes and updates to your mod is also done through this tool.

1. Run Quadrilateral Cowboy Workshop Uploader.
   
2. Your published mods will appear in the list. Select the mod you wish to update.
   
3. Click the Update mod button.
   

   • If you wish to change the thumbnail, fill in the Thumbnail field. Or, leave the field empty if you don't want to change it.
     
   • If you wish to change any mod files, fill in the Mod folder field. Or, leave the field empty if you don't want to change it.
     
   • Optionally, fill in the Update note if you want to include notes for the update.

4. Click the Upload changes button to commit the changes. Done!

You can open any of Quadrilateral Cowboy's content files and examine how things were made. This is a great way to see how things work.

Here's how:

1. Enter Quadrilateral Cowboy's base folder.
   

   It will likely be something similar to: steam\steamapps\common\quadrilateralcowboy\base

2. Open the file: pak000.pk4
   

   A .pk4 file is identical to a .zip file. I personally use 7-zip[www.7-zip.org] but any file compression program will work fine.

3. Extract or examine any file you like.

Notable files:

Folder locations of common Quadrilateral Cowboy files.

Taking a look into Downloaded workshop mods is a great way to see how mods are packaged up.

Additional resources and further reading:

Here's how to make doors.

1. In the 2D window, make/arrange some brushes to create an opening for the door. The opening's dimensions should be: 104 units high x 56 units wide:
   
   

   When doing this, I suggest resizing the grid to grid size 8. The grid size indicator can be found on the status bar on the lower-right side of the screen.
   

2. In the 2D window, press RMB near the door opening. Select: Create Model
   
   
3. From the list, select: door/door.ase
   
   
4. In the 2D window, press and hold LMB on the door to drag the door into the door opening.
   
   

   You may also need to press the Z-Axis Rotate button to rotate the door:
   

5. With the door selected, press N to open the Entity Inspector.
   
6. Click on classname func_static and then click on Choose entity class:
   
7. From the list, select: func_door
   
   
8. Click the Add button to confirm the selection.
   
   
9. The final step is to tell the door which direction to open. In the 2D window, press ctrl+tab until it displays the top-down view. The move directions are as follows:
   

   • East = 0
     
   • North = 90
     
   • West = 180
     
   • South = 270
     
   • Up = -1
     
   • Down = -2

   
   
10. With the door selected, press N to open the Entity Inspector. Enter movedir into the top field and enter the desired move direction in the bottom field.
    
    
11. Press the enter key to confirm the selection.