Getting Started with BF3 VU Modding

Prerequisites

Battlefield 3 (Premium/All map packs preferred)
Venice Unleashed

1.) Setting up Version Control (Optional)

If you are new to version control download Github Desktop and complete the 2 minute tutorial.

Version control is for storing "snapshots" of our code. This lets us see all the changes between snapshots, revert to a prior snapshot, etc. It also enables working on branches to keep our work organized. For example if you have a "bleeding" feature, do all the related work on the feat/bleeding branch, test that branch, and when it's good merge it into the main branch.

Commit messages should allow you to quickly find what you did. An example convention:

fix:

fix: fix a bug where player would keep bleeding after respawn

feat:

feat: enable player to take bleed damage if health falls below a threshold

tweak:

tweak: adjust bleed threshold from 90 -> 80

chore:

chore: update react to latest version

2.) Setting Up VSCode

Download and open Visual Studio Code. Right VSCode in the taskbar and pin it. Go back to VSCode and press CTRL + SHIFT + X to open the Extensions menu and add the following.

Extension 1: VUA

This extension is to be used for creating a new mod, and for access to VEXT types.

Creating a new mod with VUA

In VSCode press ctrl + k + o and select your server mod directory Battlefield 3/Admin/Mods. Right click in the whitespace and create a new folder with the name of your mod. Select the new folder and click select folder.

Press ctrl + shift + p to open the vscode command search. Type vua and hit enter. Select the Create New Mod option and hit enter. Use the same name as your folder from before and hit enter. Check the path is correct and hit enter. If you aren't making a webUI select no and hit enter.

This will open a VUA workspace, which lets VS Code use VEXT types. ALWAYS open the workspace otherwise the extension is useless. You can find the workspace inside Battlefield 3/Admin/Mods/YourMod/YourMod.vua.code-workspace and you can also find it in the recents of VSCode.

Open up Github Desktop and press ctrl + o to open a repository. Navigate to your mod location at Battlefield 3/admin/mods/yourModHere and click add repository. If it prompts you to create a repository, click that link and then click add repository. Now you can commit, make branches, push to github, etc.

Accessing VEXT types with VUA

If you press ctrl + space you won't get anything yet. This is because you must typecast variables. Basically tell VSCode what type the variable is and it will tell you what is inside.

There are two ways to tell VSCode what type the variable is

Option 1: Type cast the function parameters with `---@param varName type` (if it's an event or hook look at VU Docs for types)

Option 2: Type cast the variable with `---@cast varName type`

Extension 2: Prettier-Eslint

Prettier is a code formatter. Never worry about spacing again!

The reason we use the eslint variant of prettier is because if you make a WebUI you definitely want linting/error messages there.

Go to your VSCode user settings and search "format"

Change default formatter to Prettier ESLint.

Check the Editor: Format on Save Box

3.) Setting up Local VU Server

Login to Venice Unleashed and generate a key. Once the key is generated, download the key file and move it to your Battlefield 3/Server directory.

Inside Battlefield 3/Server/Admin are the following files:

startup.txt (Server Config)

1# RCON Password
2admin.password "adminRemotePassword"
3
4# Server
5vars.serverName "Your Server Name"
6vars.gamePassword "yourPassword"
7vars.maxPlayers 32
8vu.serverbanner yourWebsite.yourDomain
9vars.idleTimeout 9999
10
11# Teamkilling
12vars.teamKillCountForKick 0
13vars.teamKillValueForKick 2
14vars.teamKillValueIncrease 0.525
15vars.teamKillValueDecreasePerSecond 0.01
16vars.teamKillKickForBan 0
17
18# Reserved Slots
19reservedSlotsList.add "PlayerName1"
20reservedSlotsList.add "PlayerName2"

This is basic settings like banner URL (image in server browser), password, max players, etc. Full list of config values and commands is found on Venice Unleashed Docs.

maplist.txt (Setting Map)

1# SETS YOUR MAP AND GAMEMODE
2# FORMAT #
3# mapcode gamemode repeats
4
5# XP1_001 ConquestAssaultLarge0 1
6XP1_002 ConquestLarge0 1

All of the map codes and compatible gamemodes can be found on Venice Unleashed Docs.

modlist.txt (activates mods from `Battlefield 3/Admin/Mods`)

1# SETS YOUR MODS
2
3mapeditor
4rmbundles
5#funbots

Same as before, a # means ignore everything after this. This is just the name of the mod found in Mod.json.

Mod Files

Mod.json (mod metadata)

1{
2    "Name": "Your Mod Name",
3    "Description": "A sentence about your mod.",
4    "Version": "0.0.1",
5	"Authors": ["Author1Name", "Author2Name"],
6	"URL": "https://WebsiteName.YourDomain",
7	"Tags": "yourMod-Tag",
8    "HasVeniceEXT": true,
9	"HasWebUI": false,
10    "Dependencies": {
11        "veniceext": "^1.0.0"
12    }
13}

Tags are what show up in the VU Server Browser on your server listing.

Name is what modlist.txt is looking for.

Code Location

Code inside /ext/shared runs on both client and server

https://docs.veniceunleashed.net/vext/ref/shared/

Code inside /ext/server runs on just server

https://docs.veniceunleashed.net/vext/ref/server/

Code inside /ext/client runs on just client

https://docs.veniceunleashed.net/vext/ref/client/