¶ Introduction
This page will show you how to set up a BF3: Reality Mod development environment in simple to follow steps and escorts you while you create your first Venice Unleashed mod to get a feeling for modding with the framework and some RM coding conventions.
Some links that may be interesting for you:
- Github project of the mod that we will create today.
- Venice Unleashed Official Modding Documentation
- EBX dump or Powbacks EBX Webtool
For more in-depth guides on Venice Ext we recommend also taking a look at the official guides
To prevent unecessary questions we really encourage you to take a look at the official guides
If you haven´t taken a look at the official guides by now. Do it.
¶ Prerequisites
- Working Battlefield 3 / Venice Unleashed Install ( https://veniceunleashed.net/ )
- Guide written for Production Build #19006
- Visual Studio Code v1.70 or newer ( https://code.visualstudio.com/ )
- A basic understanding of the Lua Language 5.4 or other programming languages.
¶ Setting up a Venice Unleashed Server
- Navigate to
%HOMEPATH%\Documents\Battlefield 3\Server(create it if it doesn´t exist) - Download, extract the server folder and place the server example, files in the server folder or follow the official set-up guide from the Venice Unleashed Docs
- Navigate to the Venice Unleashed Website and login.
- Navigate to "Manage server keys"
- Create a key, download the server.key file and place it in
%HOMEPATH%\Documents\Battlefield 3\Server - Install VU Mod Manager optional
- You can now change the Startup.txt to your liking.
¶ Setting up Visual Studio Code
Lua Developers:
- Install Vua from the Visual Studio Marketplace.
UI Developers:
Both:
- Install EditorConfig
Always open Reality Mod via the workspace file, else Vua won´t get loaded.
¶ First steps with Vua and Vext
To get you started with coding using Vua and Venice Unleashed´s API VeniceExt (Vext) we will provide a small introduction guide here which you can follow to get yourself familiar with Vua and Vext.
- Open an empty project in Visual Studio Code.
- Open the command palette using Control+Shift+P.
- Type Vua, open the vua command list and select
Download and Build Contentand wait for it to download all VeniceExt types & support libraries.
- Type Vua, open the vua command list but this time select
Create New Project.
- Enter the project name. We will just call it
GettingStartedModhere.
- Enter the path you want to use for the mod. For me it will be:
- Select if you want to use WebUI. As we are only covering Lua first here we will choose
Nofor now.
- Vua will now have created some files for you:
- Before we continue with writing our mod we need to understand some basic things:
To use Vua after closing VSCode you will have to open the project via the created .code-workspace file - else it will not initialize!
¶ Mod Structure
¶ General Info
__init__.lua is always the first lua file to be loaded on initialization of the mod.
In high to low order:
¶ Mod Folder GettingStartedMod
Contains the mod.json
¶ ext Folder GettingStartedMod/ext
Root folder of the modding files. Contains the Shared, Server and Client folders.
¶ Shared Folder GettingStartedMod/ext/Shared
Compatible Code in this folder will be executed on Server & Client at the same time and also before any other code.
¶ Server Folder GettingStartedMod/ext/Server
Compatible Code in this folder will only be executed on the Server.
¶ Client Folder GettingStartedMod/ext/Client
Compatible Code in this folder will only be executed on the Client.
¶ Writing the mod
For the purpose of understanding the basics we will write a small and easy teleporter mod. This will include:
- Client to Server Communication (NetEvents)
- The principles of logging
- Using a raycast
- Working with Hooks
- Modifying a data container on the way so this is covered aswell
¶ Loading Libraries and Code Initiliazation
- Lets start by implementing some Utility libraries that we use in Reality Mod:
For today we will grab the Logger, DataContainer and Timer class from Reality Mod. - Create a
Utilsfolder inext/Shared(so it will be available everywhere) - Grab the class lua files and place them in
Utils - Create
Enums.lua&Settings.luainext/Shared - Initialize these files in
Shared/__init__.lualike such, we will also use this to take a look at the general class structure in Reality Mod:
--- A class description
---@class SomeSharedClass
---@overload fun():SomeSharedClass
SomeSharedClass = class "SomeSharedClass"
require "__shared/Utils/Enums"
require "__shared/Utils/Settings"
require "__shared/Utils/Logger"
require "__shared/Utils/DC"
require "__shared/Utils/RealityModTimer"
-- Define the logger: <Logger("Name", "Enabled <true/false>")>
---@type Logger
local m_Logger = Logger("SomeSharedClass", false)
-- the function that gets called on initialization of the class
function SomeSharedClass:__init()
m_Logger:Write("SomeSharedClass init.")
self:RegisterVars()
self:RegisterEvents()
self:RegisterHooks()
end
function SomeSharedClass:RegisterVars()
-- register variables here
end
function SomeSharedClass:RegisterEvents()
Events:Subscribe('Engine:Update', self, self.OnEngineUpdate)
end
function SomeSharedClass:RegisterHooks()
-- register hooks here
end
function SomeSharedClass:AnyOtherFunction()
-- any other function
end
-- specifically on shared because the timer needs the engine update to work
function SomeSharedClass:OnEngineUpdate(p_DeltaTime, p_SimulationDeltaTime)
RealityModTimer:OnEngineUpdate(p_DeltaTime, p_SimulationDeltaTime)
end
return SomeSharedClass()
- Now do the same on your own on
ServerandClient. Don´t forget we don´t have to require our libraries anymore because we already made them available globally inShared. Name your classes to something that makes sense, here you can just follow the guides naming or be creative. Also don´t subscribe to theEngine:Updateevent again, we won´t need it except for the RealityModTimer.
¶ Working with Events
You can find a more in-depth guide on Vext Events on the official guide
- Once this is done lets go to the Client Class and subscribe to the Player:UpdateInput Event, so we can check if the player presses any buttons and also redirect the callback to a custom function inside our class:
function ClientTeleporter:RegisterEvents()
Events:Subscribe('Player:UpdateInput', self, self.OnPlayerUpdateInput)
end
- Also add our Vua annotations to keep it clean.
---@param p_Player Player
---@param p_DeltaTime number
function ClientTeleporter:OnPlayerUpdateInput(p_Player, p_DeltaTime)
end
You can get the parameters returned in the callback from the official VU Docs
¶ Working with Client Input
- Check for the Key that is pressed with InputManager. We will use the key F (InputDeviceKeys) to teleport ourselves.
---@param p_Player Player
---@param p_DeltaTime number
function ClientTeleporter:OnPlayerUpdateInput(p_Player, p_DeltaTime)
if InputManager:WentKeyDown(InputDeviceKeys.IDK_F) and p_Player.soldier ~= nil and not p_Player.inVehicle then
self:TeleportRaycasted()
end
end
¶ Using a Raycast & Dispatching a Net Event
You can find a more in-depth guide on Vext Net Events on the official guide
- Create the new function to handle the teleport
function ClientTeleporter:TeleportRaycasted()
-- get the client camera transform
local s_Transform = ClientUtils:GetCameraTransform()
-- add security checks
if s_Transform == nil then return end
if s_Transform.trans == Vec3.zero then -- Camera is below the ground. Creating an entity here would be useless.
return
end
-- The freecam transform is inverted. Invert it back
local s_CameraForward = Vec3(s_Transform.forward.x * -1, s_Transform.forward.y * -1, s_Transform.forward.z * -1)
-- get the position in the world to raycast to
local s_CastPosition = Vec3(
s_Transform.trans.x + (s_CameraForward.x * SETTINGS.RAYCAST_DISTANCE),
s_Transform.trans.y + (s_CameraForward.y * SETTINGS.RAYCAST_DISTANCE),
s_Transform.trans.z + (s_CameraForward.z * SETTINGS.RAYCAST_DISTANCE)
)
-- Raycast
local s_Raycast = RaycastManager:Raycast(s_Transform.trans, s_CastPosition, RayCastFlags.IsAsyncRaycast)
if s_Raycast == nil then
return
end
-- lets add a meter to the position height to prevent spawning in the ground
local s_TeleportPosition = s_Raycast.position
s_TeleportPosition.y = s_TeleportPosition.y + 1
-- send our event to the server so it can handle the teleporting
NetEvents:SendLocal(NETEVENTS.TELEPORT_TO_POSITION, s_TeleportPosition)
m_Logger:Write("Teleport Request Sent")
end
¶ Config & Enums
- Create the netevent name enum & The raycast distance setting (also add the logger print all setting so it doesn´t throw an error):
Enums.lua
EVENTS = {}
NETEVENTS = {
TELEPORT_TO_POSITION = "Teleport:ToPosition"
}
Settings.lua
SETTINGS = {
LOGGER_PRINT_ALL = false,
RAYCAST_DISTANCE = 5000
}
¶ Subscribing to Net Events
You can find a more in-depth guide on Vext Net Events on the official guide
- Subscribe to the just created event on the Server:
function ServerTeleporter:RegisterEvents()
NetEvents:Subscribe(NETEVENTS.TELEPORT_TO_POSITION, self, self.OnTeleportToPositionRequest)
end
- Create the new callback function just defined and teleport the player soldier by using the server soldier method SetPosition()
---@param p_Player Player
---@param p_TeleportPosition Vec3
function ServerTeleporter:OnTeleportToPositionRequest(p_Player, p_TeleportPosition)
if not p_TeleportPosition then
m_Logger:Error("Teleport Position is invalid")
return
end
-- get the player soldier to teleport
local s_Soldier = p_Player.soldier
if not s_Soldier then
m_Logger:Warning("Soldier to teleport is nil")
return
end
s_Soldier:SetPosition(p_TeleportPosition)
m_Logger:Write("Teleported Player: " .. p_Player.name .. " to Position: " .. tostring(p_TeleportPosition))
end
- Don´t forget to add the Logger and Timer to this file!
---@type Logger
local m_Logger = Logger("ServerTeleporter", true)
---@type RealityModTimer
local m_Timer = RealityModTimer
function ServerTeleporter:__init()
- Nice you have now written your first Venice Unleashed Teleporter!
¶ Testing the mod
To test the mod, add it to the ModList.txt in the Server/Admin folder. This can be done by just entering the mods root folder name e.g. here GettingStartedMod. A successfully loaded mod will be displayed in the server window:
¶ Extending the mod
Now after you successfully tested the teleport mod you may or may have not experienced dying from teleporting. This can happen because fall damage still gets applied to the players soldier after teleporting. Lets take a look on how we can prevent that:
¶ Registering Hooks
- Register the Soldier:Damage Hook and create a callback function for it
function ServerTeleporter:RegisterHooks()
Hooks:Install('Soldier:Damage', 1, self, self.OnSoldierDamage)
end
function ServerTeleporter:OnSoldierDamage()
-- we will continue here later
end
¶ Creating Variables
- Now add this new variable to the class. We will use this table to check if the player has teleported and if the damage has already been blocked.
function ServerTeleporter:RegisterVars()
self.m_IgnoreSoldierDamageForPlayer = {}
end
¶ Adding a simple timer
- Add the player name (or the id) to the "Protection Table" and add a timer to automatically disable the teleport protection after some ms. We use the player name or id because we don´t want to store the Player Object into memory, since this can lead to crashes if it doesn´t cleaned up properly hence we try to avoid storing FB Objects in variables.
---@param p_Player Player
---@param p_TeleportPosition Vec3
function ServerTeleporter:OnTeleportToPositionRequest(p_Player, p_TeleportPosition)
if not p_TeleportPosition then
m_Logger:Error("Teleport Position is invalid")
return
end
-- get the player soldier to teleport
---@type SoldierEntity|nil
local s_Soldier = p_Player.soldier
if not s_Soldier then
m_Logger:Warning("Soldier to teleport is nil")
return
end
-- Set new position of the soldier
s_Soldier:SetPosition(p_TeleportPosition)
-- Add soldier to damage protection table
table.insert(self.m_IgnoreSoldierDamageForPlayer, p_Player.name)
-- remove protection after set time
m_Timer:Simple(SETTINGS.TELEPORT_PROTECTION_IN_S, function()
if self:_CheckIfSoldierIsProtected(s_Soldier) then
m_Logger:Write("Soldier Protection Lifted")
end
end)
-- log the teleported player and the position
m_Logger:Write("Teleported Player: " .. p_Player.name .. " to Position: " .. tostring(p_TeleportPosition))
end
- Don´t forget to add the timer setting to the
Settings.lua
SETTINGS = {
LOGGER_PRINT_ALL = false,
RAYCAST_DISTANCE = 5000,
TELEPORT_PROTECTION_IN_S = 0.2
}
¶ Finishing up
- Lets create a function to check if the soldier that received damage is protected. We do this so we don´t have to repeat the same code twice which will make it a bit cleaner. The
_in the function name describes the local use in the class.
---@param p_Soldier SoldierEntity|nil
function ServerTeleporter:_CheckIfSoldierIsProtected(p_Soldier)
if not p_Soldier then
return false
end
for l_Index, l_SoldierName in ipairs(self.m_IgnoreSoldierDamageForPlayer) do
if l_SoldierName == p_Soldier.player.name then
table.remove(self.m_IgnoreSoldierDamageForPlayer, l_Index)
return true
end
end
return false
end
- Now lets go back to the
OnSoldierDamagefunction and check there if the soldier is protected. If yes return nil in the hook context.
function ServerTeleporter:OnSoldierDamage(p_HookCtx, p_Soldier, p_Info, p_GiverInfo)
if self:_CheckIfSoldierIsProtected(p_Soldier) then
-- disable damage
p_HookCtx:Return(nil)
end
end
- Done. Now you won´t receive damage on teleporting
¶ Quick dive into DataContainer Modification
We will take a quick look into DataContainer modification using the Reality Mod DC class. You can grab that from the GettingStartedMod Repository we set up for you.
- Lets go to
Shared/__init__.lua. And initialize the DataContainers at the top of the file.
-- DataContainer we want to modify
---@type DC
local m_FiringFunctionM249 = DC(Guid("F37DBC84-F61B-11DF-829C-95F94E7154E3"), Guid("7FCFC3D7-49C2-477E-8952-664FDA86B41E"))
-- Projectile we want to replace its projectile with
---@type DC
local m_SMAWHEProjectileData = DC(Guid("168F529B-17F6-11E0-8CD8-85483A75A7C5"), Guid("168F529C-17F6-11E0-8CD8-85483A75A7C5"))
---@type DC
local m_SMAWHEProjectileBlueprint = DC(Guid("168F529B-17F6-11E0-8CD8-85483A75A7C5"), Guid("90BAEBC0-C9E6-CB0B-7531-110499218677"))
- DataContainer Example: DC(Guid("PartitionGuid"), Guid("InstanceGuid"))
- Add a RegisterCallbacks() function and register a load handler.
function SomeSharedClass:__init()
m_Logger:Write("SomeSharedClass init.")
self:RegisterVars()
self:RegisterEvents()
self:RegisterHooks()
self:RegisterCallbacks()
end
function SomeSharedClass:RegisterCallbacks()
m_FiringFunctionM249:RegisterLoadHandler(self, self.ModifyM249FiringFunctionData)
end
- Create the callback function:
---@param p_Instance FiringFunctionData
function SomeSharedClass:ModifyM249FiringFunctionData(p_FiringFunctionData)
end
- Lets replace the projectile shall we? To do that make
p_FiringFunctionDatawritable first.
p_FiringFunctionData:MakeWritable()
- Now modify the ShotConfig of the FiringFunctionData. This will replace the M249 NATO Projectile with the SMAW HE Projectile.
local s_ShotConfig = p_FiringFunctionData.shot
if s_ShotConfig then
s_ShotConfig.projectileData = m_SMAWHEProjectileData:GetInstance()
s_ShotConfig.projectile = m_SMAWHEProjectileBlueprint:GetInstance()
m_Logger:Write("Replaced M249 Projectile")
end
- Since we are on it we can also modify the FireLogic and AmmoConfig.
local s_FireLogic = p_FiringFunctionData.fireLogic
if s_FireLogic then
s_FireLogic.rateOfFire = 1200
m_Logger:Write("Modified M249 FireLogic")
end
local s_AmmoConfig = p_FiringFunctionData.ammo
if s_AmmoConfig then
s_AmmoConfig.magazineCapacity = 249
s_AmmoConfig.autoReplenishMagazine = true
s_AmmoConfig.autoReplenishDelay = 5.0
m_Logger:Write("Modified M249 AmmoConfig")
end
- Good job! You completed this small introduction into DataContainer modification! Enjoy raining mayhem onto your enemies with this M249 1200RPM Autoreloading Missile Launcher