Tutorial: newbspguy editing basics Last edited 6 months ago2023-11-03 16:53:56 UTC

This tutorial will show you the basics of using newbspguy to edit already compiled BSP files.

This tutorial uses UnrealKaraulov's fork of wootguy's bspguy due to the many added features, and the decoupling from a strictly Sven Co-op focused workflow of the original.

Preface

The workflow of editing already-compiled maps is totally different from making a map from scratch.

In the past, it was easier to just decompile a BSP back to .MAP, and start building up from there, because the typical modding workflow assumes you start from a map in an editor. However, there are several drawbacks to this method:

• Decompilation is a messy process. Due to how the BSP data is structured, the entire level is chopped up across planes, which goes all over the place irrespective of the original brush shape. Decompilers faithfully follow the planes structure, resulting in brushes that likewise go all over the place. Many of them would also be invalid solids and need to be recreated.
• You lose all texture lighting data. 9 times out of 10 a custom map would be using custom texlights entries that are different, or absent, from the stock valve.rad. Your option is to recreate texlights by estimation and guesswork, which won't give you 100% of the original texlight values.
• You lose all clipping data, because no decompiler as of time of writing is able to recreate "Clip" brushes from the clipnode trees since clipnode trees are not technically part of the level geometry.

However, as of 2023, there now exists tools that let you edit already compiled BSPs directly, namely, bspguy and its fork newbspguy. The original tool was created exactly to port GoldSrc maps over to Sven Co-op, but both tools, especially the latter, can be used just as well to edit maps for any GoldSrc game/mod.

Pros, Cons, and Caveats

The advantages of editing BSPs in place are:

• Lightmaps are preserved.
• No messing with messy and invalid decompiled brushwork.
• No need to recreate clip brushes.
• Trivial brush entity duplication, that normally doesn't add to BSP model count.

The disadvantages are as follows:

• You cannot edit world brushes whatsoever.
• You cannot do crazy texture scaling since it's tied to the lightmap size.
• You cannot edit clip nodes.

Do note of these differences for compiled BSPs:

• func_detail is not a thing in compiled BSPs; they're transformed to normal brushes during compilation. You need to use func_wall or func_illusionary
• clip brushes are also not a thing; they're transformed into clip nodes which you cannot edit. You can however use the default BSP solid models the program creates to artificially add collision. Do note that this adds to the BSP model count so be conservative.
• origin brushes are not a thing; the BSP models already has its own origin on creation, which you can move.

---

Setting up newbspguy

1. Extract newbspguy into a folder.
2. Run the program.
3. Open File > Settings.
4. Under General, click Reset All Settings.
5. Under General > Game directory, set to location of your Half-Life installation.
6. Under FGDs, add the FGD of your target mod. Please note that [new]bspguy doesn't support JACK's extended FGD.
7. Under Asset paths, add relative paths in the following format: <mod folder>/. There should be at least these entries:
   • valve/
   • <the target mod>/ (if that isn't valve)
8. Click "Apply settings". Close the options window.

Editing maps

Provided you've set up the correct FGD and asset path(s), you are now set to edit the maps for your target mod. Here are some tasks that you should be able to master:

Adding point entities

1. Create > Entity
2. Right-click on the new entity > Properties
3. Click on class, and in the dropdown menu, select the target entity.
4. Edit the entity as you would in Hammer/JACK.

Adding and sizing trigger entities

1. Create > BSP Solid Model
2. Right-click on the new brush entity > Transform
3. Set Target: Object and 3D Axes: Scale
4. Grab the edge handle and drag it to the desired size. Repeat for all directions as required.
5. Reset to 3D Axes: Move. Close Transform window.
6. Right-click on the new entity > Properties
7. Click on class, and in the dropdown menu, select the target entity.
8. Edit the entity as you would in Hammer/JACK.

Duplicate entities

Simply copy and paste them. Both point and solid entities are supported.

You can also duplicate the BSP model of solid entities. This is only useful if the duplicated entity is in a different lighting condition from the original. You can then apply a different lightmap from the original BSP model. However do note that lightmap editing feature can be unstable. Duplicating a BSP model adds towards the BSP model count, so don't go wild on it.

Editing keyvalues

Editing keyvalues is the same as in Hammer or JACK. These notes might be useful:

• You can duplicate existing solid entities. They will share the same model, which is an index into their BSP model (in the form of *number).
• Be aware that compiler keyvalues e.g. zhlt_* do nothing.

[Re]texturing a face

1. Switch to face editing mode by clicking on the second icon on the top right corner.
2. Click on a face.
3. Edit the face's name and shift values.
4. Switch back to Object selection mode when you're done (first icon on top left).

Adding a sign

1. Create a solid model as shown above. Set the size to match the sign's size in pixels, and set the entity to be func_wall or func_illusionary.
2. Assign the texture to the front face of the entity.
3. Shift the texture to fit the face. Oftentimes it'd be easier to scale the model to fit the texture instead, then move it back to the intended position.
4. Uncheck "Special" flag. The face will turn black, because there is no lightmap data on it.
5. Select the face of the wall behind the sign. Be sure to pick a face roughly the same size or slightly larger as the sign (preferably the latter) in both dimensions.
6. Right click > Copy lightmap.
7. Select the sign face. Right click > Paste lightmap.

Adding brushes at an angle

You can either start by duplicating existing brush models, or creating a new one for scratch. For the latter, follow the previous method of applying a texture and lightmap to all faces.

Now the issue of turning the solid entity at an angle... The hard way would be to jump into the vertex editing mode and moving the vertices into position, with a lot of math if you want to keep the scale. A simpler way would be to turn the brush into a func_tank and set its angle and origin. it'd face the given direction at spawn. The default spawn flags should be sufficient; obviously don't set it to active.