Modding Guide

Server Modding

https://github.com/broke-protocol
https://brokeprotocol.com/api

The links above offer documenentation and source code on modding the server. The server runs using an external GameSource.dll (placed within the Plugins directory) that you can compile and build custom for your server. The GameSource is built on in-game hooks to things like chat messages, deaths, etc. The GameSource also shows an example of how to create your own custom EventHandler for something like triggering a warning when a player enters an area. Though whatever modders want to make is limitless.

For UI rendering and client-side exectution, the game relies on HTML and JavaScript on the server rendered on the client via CEF. You can see an example of some usage in the demo present in [Game Directory]/www/cef/index.html. Client-side code can also be executed there using the following functions JavaScript functions:

  • trigger(string eventHandlerName, JsonObject arguments)
  • cursorShow()
  • cursorHide()
  • exec(string c#code)
  • getAsync(string c#code)

Try to form your expressions for exec() and getAsync() using a unchanging string input. You might use Linq for example instead of iterating over different array indices explicitly. This is because any new expression, even one character different will require a complete compilation of your input code, instead of running from a script cache.

Asset Modding

Welcome to the Broke Protocol asset modding guide. This will show you how to edit existing assets like weapons, items, vehicles, and even world objects. You can also create new ones altogether. Modded items will be synced to anyone connecting to your server or can optionally be shared on the Steam Workshop.

This guide will just cover the custom asset development process. It won’t cover server/client scripting, Custom UIs, or map editing itself. These topics will be covered in other guides.

If you’re a more visual learner, this guide is also presented in a video where you’ll see the entire modding workflow from start to finish. If you want more specifics however, read on.

Modding Environment

The first thing every mod developer needs is Unity. The free version will work just fine and you can grab the latest version here.

You don’t need to download any extra Modules or Documentation. Just the base package will be enough for modding along with Game Resources package BP provides as part of the base game.

Once you start Unity, you need to create a New Project. This will be your Modding Project that you will develop all your Mods/AssetBundles in. Create it as a 3D project, save it anywhere, and load it up.

Once you have the project loaded. Go to ‘Assets -> Import Package -> Custom Package.’ After that, find and import your BPResources.unitypackage.

This package contains the modding Resources you’ll need to create custom content for Broke Protocol. The next step is to import and wait a while for the package to decompress.

Import All

From the package window, make sure to click ‘All’ then ‘Import.’ If future BP releases have new features or assets you’d like to mod, you can repeat this same process for your modding project. The package importer is smart enough to detect and update modified BP resources, while leaving your mods alone. After the import, your development environment is good to go.

Package Tools

This the the Unity Project Window. All package tools, resources, and eventually, your mods will reside here. A quick overview of what’s included with BPResources by default.

  • AssetBundles-Browser – A tool that allows you to export your mods (*.assetbundle type) via ‘Window -> AssetBundle Browser.’
  • Character – Rigged model, clothing items, and EquipablePoser scene to help positioning items in player hands.
  • Editor – Scripts that set up the Unity environment (tags/layers) for Broke Protocol development and compatibility.
  • ExportEntities – All game entities that game be modded or used as a basic for new custom assets. Entities have scripts that define its properties.
  • ExportExampleAssets – Various types of assets showing recommended import settings for models, textures, and audio.
  • Resources – All static game objects and props that can be modded. Generally don’t have scripts.
  • Scripts – Broke Protocol constants and required classes.

Modding Workflow

There are a few different ways to develop your mods, and you’ll develop your own preference for doing so over time. The step I like to take first is to find a base object/entity similar to the one I want to mod/edit and create an Instance of it in the scene by dragging it into the Scene Hierarchy.

Broke Protocol uses names to identify all objects in-game. And there can only be one Object per name. So if we keep the AK47 gameobject name like in the example, any edits done to the properties, mesh, texture, or audio will modify the default AK47 item properties in-game.

If you want to create a new custom asset, you would change the name of the GameObject as shown. Either way, drag and drop your newly created object into the project view anywhere to create an Original Prefab that will serve as the basis for your mod.

The Inspector on the right side of the editor (with your object selected) contains every single property that defines what your object is, how it renders, the audio clips it plays, materials, meshes, particle systems, etc.

You can edit your custom GameObject either from the Scene instance or the Project/Prefab object. Though if you edit the Scene instance in any way, make sure you click ‘Overrides -> Apply All’ to save your changes back to the Prefab.

Properties may contain references to other entities in the game. Note you can also reference custom entities too. So a custom gun can use a custom ‘ammoItem’ reference. References are done simply by name so you type the GameObject you want to reference by name in these fields. Note: ‘self’ sets a reference back to itself and a blank field is a null reference for irrelevant fields or fields you don’t want to reference anything.

You might notice missing meshes and materials for nearly all default entities/objects in the game. This is done on purpose since if you want to edit an existing item’s parameters, you can just edit the properties and export without art/audio assets to reduce file & transfer size. Broke Protocol will automatically find the default materials, meshes, and audio assets for existing game objects/entities once its loaded in-game. Assigning these missing references will override default game assets for example if you want to replace a specific mesh, texture, or sound effect in-game.

Unity Particle Effects

For new items you want to introduce, you will need to fill in every missing field with your own meshes, audio clips and everything to fully produce a working item. Don’t forget all the particle effects too. Most just need the default material set to ‘Sprites-Default.’ Smoke particles generally need the ‘Trail Material’ set instead. You’ll know something isn’t set correctly when you get purple textures or effects in-game.

For new custom objects or new meshes, you might find that the colliders don’t match the new item bounds. These colliders are used not only for collision detection, but for hit-scanning and picking up items as well. So you want them to match your items exactly. To autofit a new collider, simply delete the existing collider. Then go to ‘Add Component’ and add a new Box Collider or similar to have an automatically fitted collider for your asset.

Items that can be equipped, like weapons, need to have a special setup to be positioned in player hands correctly. For this Find the ‘EquipablePoser’ Scene and click Play.

Make sure you have the correct Grip animation selected for your item, then go into Scene view. Drag and drop your prefab onto the model’s ‘Human_RightHand’ Transform. Use Unity’s controls to position and rotate the object correctly in the player’s hands. Copy the Transform component by ‘Right-Click -> Copy Component.’ Then, select your Prefab in the Project view below. Finally, paste the new Transform by ‘Right-Click -> Paste Component Values.’

Finishing Up

When your asset is ready, the time comes to Building your AssetBundle. Open your AssetBundle Browser by going to ‘Window -> AssetBundle Browser.’ Now you will want to make sure you have an AssetBundle defined by right-clicking in the Browser Window -> ‘Add new bundle.’ Name it anything related to your mod. Add your custom prefab to the AssetBundle from the DropDown at the bottom right of the Prefab Inspector. You can add multiple objects to a single AssetBundle and in fact that’s the recommended workflow to reduce filesize and complexity.

Once your AssetBundle is Configured, you can now Build. Target Standalone Windows 64 and set the Output Path to your Broke Protocol’s AssetBundles directory. Finally, click Build (Default settings should be fine here) and kick back! Your asset is complete 🙂

You should be able to find your custom asset in the World Builder within the ‘Custom’ directory. You can now place your modded objects anywhere in your map. It will work in Offline mode and will be automatically shared and cached with connecting players to your server. You can also use the Workshop uploader to share your custom asset on the Steam Workshop and have a chance to be promoted by the developers.

Tips

  • If you’re editing your item in the Scene view. Don’t forget to click on ‘Overrides -> Apply All’ in the Inspector to apply all current changes back to your prefab, else your changes won’t export in full.
  • Try to combine as many custom mods as you can into a single assetbundle. This way, items that share mesh, texture, material, or audio assets will share the single asset instead of being duplicated. This will result in smaller total AssetBundle size and faster connection for players on your server.
  • Most items should have the mesh origin set at the bottom of the object. Guns should have the origin set at the end of the barrel. If you use an assetpack with a different origin, you can make the gun mesh a sub-object of the parent and move it around until the gun barrel is at the origin. This must be done because (0, 0, 0) is where bullet trails and flash particles are spawned.
  • Keep your modding project! If a new BP release comes and you want to take advantage of new features, you can reimport the latest BPResources package, update your asset (don’t need to start from scratch), and Rebuild your AssetBundle. That’s it!