Campaign BSP Loading Guide

[Takka 13,377]

Disclaimer: This is not my tutorial, and it was not signed, however it does contain references to other contributors.

 

The Introduction

 

Many people have asked for it, here it is, the guide on how you too can load way more into your map than the original Xbox 360 ever intended. Be warned, this is not a guide for first time users of Assembly - you should have a good understanding of the program and modding the game in general as this guide will make assumptions on your knowledge. You should already have a map converted from Campaign to Multiplayer, if not take a look at the Campaign/Firefight Map Conversion Guide to learn how to get Campaign maps into Multiplayer

 

The syntax used in the guide will also be using a different naming convention to mainline Assembly, as it uses Camden’s custom made plugin with more information and different names.

There is a link to this in the Tools section, with thanks to Camden for allowing us to share it.

 

Whilst the first section will cover how to load into a different area of the map, loading more BSPs is a much more difficult task that will test your patience, willpower and desire. You have to be willing to put in days and very likely weeks of your time to get things right, because it does demand perfection.

 

The guide was put together with help from numerous members of the Halo Modding community, especially Camden who is a master of his craft. If you get your mod to work, make sure to remember him in the credits as without his help this guide would not even exist.

 

 

Tools

 

Assembly - You should have this already unless you believe you can do this with another tool

Adjutant - A similar tool to Assembly, it can be used to view models of objects however it only works on Xbox 360 maps. You can find Xbox 360 maps online for use with this.

Camden’s .scnr plugin - An alteration of Assembly’s plugin for the scnr tag made by Camden based on tags from Halo 5 which reveals some of the Unknowns and changes the names of a few things - it’s assumed throughout the guide you have this or have included it’s elements in your own plugin. Place into the assembly/plugins/ReachMCC folder.

Notepad - You’re probably going to need to do some note taking to remember what you’ve done

 

 

Common Terms

 

• BSP - Binary Space Partition, don’t worry too much about understanding it, just know that it refers to sections of a map

• Zone Sets - A group of BSPs and other elements

• Clusters - Portions of a Structure BSP

• Portals - Think of them as windows or doors from one BSP into another, lets you see from one BSP to another.

• PVS - Potential Visibility Set, once again don’t worry about understanding what it means

• Unknown - We don’t know what this is or what it does

 

 

Loading into a different Zone Set

 

Compared to the rest of this guide, just loading into another area is quite simple. For many people this will be enough, perhaps you only want a specific area and the game has that - but for some things such as the Corvette and New Alexandria’s buildings not all of it is loaded in at once.

 

For this section, we’re going to be working completely within the Zone Sets, or Scenario Zone Set Groups if you’re not using Camden’s plugin for scnr. When loading a campaign map as a multiplayer map, it always loads the first entry, as seen here:

 

 

Whilst the below section covers altering the Zone Sets, in this one we will simply be changing the first entry to match another so it loads that instead. As an example, we’re going to use m10’s first Zone Set which looks like this:

 

 

The name and name string don’t matter but everything else I would advise changing to match the Zone Set you want to load into instead. 

 

So, say we wanted to load into zoneset_outpost_interior, which is the Outpost interior section of m10 where you find Sorvad’s datapad - You’d need to copy the information from that entry to entry 0. A basic overview of what each one does follows:

 

• BSP Group Index - This refers to the Zone Set PVS - a block that covers what parts of the level are rendered in basic terms.
• BSP Zone Flags - Which BSPs should be loaded, these should always match what is in the Zone Set PVS
• Structure Design Zone Flags - these tell the game which sddt tags to use and should be the same as Runtime Structure Design Zone Flags
• Designer Zonesets, Loaded and Unloaded - This covers what objects will be loaded in the area, things like guns, vehicles and crates. For multiplayer, you will likely want everything in Loaded ticked and everything in Unloaded unticked.
• Cinematic Zonesets - This refers to cinematic objects -  It doesn’t need to be ticked as it only tells the game to load cutscenes beforehand like campaign does it
• Hint Previous Zone Set - Leave this at -1 unless you find a group that has otherwise.
• Audibility Index - this is what Zone Set Audibility the zone set uses, it determines what can be heard from where - if you can hear a gunshot from one room to another. If you plan on adding more BSPs in the later section set this to -1, otherwise just copy the entry from the Zone Set you want to use.
• Planar Fog Visibility - Covers planar fog and where it can be seen from, you can copy the address from the Zone Set or leave it alone if it’s not causing issues.

 

If you got it all right you should be able to load into the area of your choice - remember to set your spawn point to a new location if applicable or you could fail to spawn or show up in the middle of a void. You can use a tool called Adjutant to find the coordinates you want. It needs Xbox 360 maps but it has a BSP viewer you can use to get the correct coordinates down to the point. BSP positions didn’t change at all between the Xbox 360 version and MCC Reach.

 

One last thing to consider is Zone Set Switch Trigger Volumes.

 

 

This is what in the campaign allows you to walk from one area to the next and also go back, like in Sword Base where you visit the two areas then go back into the base. In multiplayer, this can disconnect your clients, so it’s recommended to set the Count to 0 lest you accidentally deload whoever you’re playing with, unless you just want to play the level by yourself.

 

 

Adding more BSPs to your Zone Set

 

This is the difficult part. Brace yourselves. The main determining factor in where you load into a map is it’s Zone Set PVS, a group of BSPs knitted together with PVA glue and duct tape. These are split into three sections:

 

• BSP Checksums - Each BSP has a checksum, just copy paste the number, the number can be also found in the sbsp tag of the BSP.
• Structure BSP PVS - The main meat of it, where it’s all put together.
• Portal=>Device Mappings, where doors and the like are linked to portals.

 

By large what you’re going to be dealing with is the Clusters located in Structure BSP PVS - each BSP is split into multiple clusters, though not always. Some have just the one, others have many more. To show you an example, this is the model of the Corvette BSP from m45 viewed in Adjutant:

 

 

As you can see on the left, the BSP has six clusters starting at zero. In Assembly, you can see these represented Cluster PVS which has an entry for each other BSP you have loaded which then have Bits determining what objects can be seen, there is also Cluster Skies, which determine whether the sky can be seen and Cluster Mappings which work a little differently but these are what shows the BSPs themselves.

 

 

There are five BSPs loaded in this particular Zone Set so Structure BSP PVS has five entries, found in the top right corner. The blocks within these have entries according to how many clusters the BSP has, in this example the 4th BSP has two clusters, so has two entries for everything but the unknown, which you can safely ignore.

 

The sections below go into more detail for each block.

 

 

Cluster PVS & Cluster PVS Doors Closed

 

Cluster PVS defines which objects can be shown, but sadly we don’t have documentation on which bit corresponds to what objects, or group of objects. I recommend keeping it matching with the original.

 

Each Cluster PVS entry has an entry for all the BSPs you have decided to load, you need to make sure to keep the order, first BSP on the active BSPs list, no matter if its BSP 0, BSP 12, BSP 15, whatever. As long as it’s the first one on the list, it will always be the first entry of Cluster PVS, second one on the list will always be the second entry inside the Cluster PVS.

 

Thank you to Camden for this helpful image:

 

 

 

Cluster Mappings

 

Whilst the Cluster PVS defines which objects can be shown, the Cluster Mappings determine the location of Portals which let you see from one BSP to the other - things like doorways and windows. It’s also how you can see the BSP inside of itself, if these aren’t done right you can walk into an area and not be able to see anything but the void. This will also cause crashes in campaign maps on areas that have loading triggers between BSPs, going around these triggers will let you pass but it’s not perfect. Still good for testing if you want to see how stuff loads at the moment and don’t have the loading triggers setup properly.

 

Once again, there’s an entry for each Cluster, but unlike the Cluster PVS there aren’t entries for each BSP, only the BSP you’re editing the mappings for, and any BSPs which are connected to it.

 

 

What often happens is that you have an area with an entrance, and then an exit to another area and only the exit or the entrance is ever normally loaded, meaning you have to add one yourself. Compared to the Cluster PVS this is fairly simple, you can simply add the numbers from a BSP with the area connected on top and there’s no need to make entries for each BSP, but it’s still worth rechecking everything is where it’s supposed to be afterwards.

 

 

Here you can see an altered Cluster Mappings, you can just add on to the existing one if it has some of the entries already and as always reuse addresses where you can but often reallocation will be necessary.

 

 

Cluster Skies, Unknown and Portal=>Device Mappings

 

If you could say that Zone Set PVS had an easy part, this would be it. The Cluster Skies are as simple as copy pasting the numbers from the origin group BSP, and the Unknown seems to always be set to 0x1C8D920F20. A chance look at Portal=>Device Mappings might make you think they’re like Cluster Mappings, but they’re easier than those - there’s just one Portal=>Device Mappings block for the whole Zone Set PVS and each entry represents a different BSP, so you simply need to set the addresses correctly for each BSP you plan on loading.

 

 

Since the portals are done per BSP, you should be fine to leave the contents of each block as is and just change the Device Portal Associations, Game Portal to Portal Map and Occluding Portal to Portal Map’s Count and Addresses to match their native groups.

 

 

Common Issues

 

• Many things can and will make your game crash. Check that everything is where it should be and after that check it again.
• Don’t despair when things don’t work right the first, second, or thirteenth time. It takes a lot of patience to get this right.

• If you cannot see through portals (like this) you need to double check your Cluster mappings, the problem is there.
• Make sure you double check your cluster PVS after you have set them up, adding entries can cause other entries to get nulled due to the cache optimization pass. All verifiably duplicate data in the tags buffer points to the same address instead of allocating it multiple times.
• Setting cluster PVS up improperly will also cause crashes in campaign maps on areas that have loading triggers between BSPs, going around these triggers will let you pass but don’t stop there and try to fix it the rest of the way. It’s still good for testing if you want to see how stuff loads at the moment and don’t have the loading triggers setup properly.

 

 

Final words and thanks

 

Apologies to anyone who has been waiting on this guide for a while now. It’s been taking quite a while as we are just two people diving into new territories with stuff that hasn’t been possible to explore much before (if we don’t count the work put into ED, ED developers have done way more than what we two can do). 

 

Feel free to leave comments here on stuff we should improve and we will get on that, also if you need more support feel free to ping me; @arttumiro in the halomods discord modding support chat

 

Major thanks goes out to Camden and Dany for being chill and good at providing support and help. (Also extra props for camden for the nice helper picture)

 

Gamecheat13 made both the Halo Mods Discord where we received advice, as well as Unearthed, the first multiplayer map conversion which provided great insight into the process of importing Campaign and Firefight maps to multiplayer.

 

Without XboxChaos, Lord Zedd, Thunder and the many other contributors to Assembly this would not be possible.

 

And of course, none of us would be here were it not for the efforts of Bungie in making the original game and 343 Industries porting the Halo games to PC.