A more recent video demonstration is now available: https://www.youtube.com/watch?v=0q-Hdmeu9WQ

---

In this tutorial you will learn how to create a new vehicle using Photon 2's Lua API.

Vehicles in Photon 2 are spawnable from the default Sandbox spawn menu, and configure lighting, sirens, skins/liveries, and decorative equipment props.

This tutorial assumes you have read and followed the Getting Started (Creators) guide. If you haven't, read that first before coming back.

I will use and provide instructions for VSCode in this tutorial. You may use any text editor you wish, but you may need to adapt some of these instructions for the equivalent features and functions of your editor.

Note: Sometimes the example code blocks you see won't exactly match demonstration images/gifs. This is because minor tweaks were made to the code after the images were captured/recorded. Always reference the code text blocks, not the image.

1. Create a new file

Ensure Garry's Mod is open and you're loaded into a singleplayer game. Now minimize or move the window aside for now.

Browse to your custom addons folder you created during the setup tutorial. If you're on Windows, it's probably something like this:

C:\Program Files (x86)\Steam\steamapps\common\GarrysMod\garrysmod\addons\my-photon-2-addons\

Open the folder in VSCode. You can do that by right-clicking anywhere in the window in Explorer.

(If on Windows 11, click Show more options)

Then click "Open with Code" to open the folder as a workspace in a new VSCode window.

VSCode should load and you will see a window that looks like this:

Next, right-click on the vehicles folder and select "New File." Then give your file a name, like schmals_vehicle.lua.

IMPORTANT: Ensure your vehicle file is lowercase only and contains no spaces or special characters.

We will start by creating a basic vehicle without any special Photon 2 functionality. Copy and paste the code below into your newly created file.

if (Photon2.ReloadVehicleFile()) then return end
local VEHICLE = Photon2.LibraryVehicle()

-- The readable title of your vehicle
VEHICLE.Title 		= "My Vehicle's Title"
-- The vehicle from which yours is based upon
VEHICLE.Vehicle		= "vehicle_name_here"
-- The vehicle's spawn category
VEHICLE.Category 	= "My Category"
-- Your name
VEHICLE.Author		= "Me"

VEHICLE.Equipment = {}

Now, we need to find a normal vehicle to base this Photon 2 vehicle on. Open Garry's Mod and pull up the vehicle spawn menu. Find your desired vehicle, then right-click its icon and select "Copy to clipboard."

In this demonstration I am using Mighty's 2016 Ford Police Interceptor Utility.

In your vehicle file on VSCode, erase enter_vehicle_name_here and paste in the text you copied from the game.

Save your file and reload the game (by disconnecting and starting a new singleplayer game, or by using the retry console command.)

2. Spawn your new vehicle

Once you've loaded back in, let's make sure your the new vehicle file was successfully initialized.

Unless you've changed the name and category already, you should now see your vehicle in a new "My Category" vehicle category with a single vehicle with the title of "My Vehicle's Title."

Go ahead and click the icon to spawn it in.

It should appear as a plain vehicle, indistinguishable from the original base vehicle. You can further confirm that Photon 2 successfully loaded the vehicle by getting in and checking for Photon's HUD information in the bottom right of your screen.

You are able to press buttons and hear appropriate interaction sounds, but the vehicle will ultimately do nothing because it has no equipment.

Troubleshooting

If your vehicle does not appear in the spawn menu, these are the most common causes:

A. Invalid file name. Ensure you are only using lowercase letters, numbers and underscores.

B. Incorrect file path. Verify the exact spelling and order of the folders in your project's addons folder using Step 1 for reference.

C. Lua syntax error. You may have accidentally pressed another key while pasting the first block of code. Erase the contents of your file and paste in the example code again.

D. Incorrect or invalid vehicle name. Make sure the vehicle name you pasted in is correct. If it is, try using a different vehicle or test with "Jeep".

3. Add a lightbar

To give your car its first piece of emergency vehicle functionality, let's add a lightbar.

As Photon 2 is still undergoing active development, there is unfortunately no component browser at the time of writing this tutorial. To browse available components, look at the library components folder of the Photon 2 repository. The component's name is usually determined by the file name without the .lua extension (exceptions to this are covered later).

For example, the file library/components/photon_sos_nforce_48.lua has a component name of photon_sos_nforce_48.

Without needing to look these up yourself, here are some default lightbar components you can try:

• Whelen Liberty II: photon_sm_liberty_ii_suv
• SoundOff Signal nForce: photon_sos_nforce_48
• Federal Signal Valor: photon_fedsig_valor_suv
• Federal Signal Legend: photon_fedsig_legend
• Federal Signal Vision SLR: photon_fedsig_visionslr

For this tutorial, I have selected the SoundOff Signal nForce lightbar. Now, in your vehicle file, replace:

VEHICLE.Equipment = {}

With the code below:

VEHICLE.Equipment = {
   -- This is an equipment category. You can make categories for anything you want,
   -- but we're just working on the lightbar right now.
   {
      Category = "Lightbar",
      -- Options are different choices within the Lightbar category. We're starting off 
      -- with just a single option.
      Options = {
         {
            -- This is simply the text that players see. It can say whatever you like.
            Option = "SoundOff Signal nForce",
            Components = {
               {
                  -- Lightbar component name
                  Component = "photon_sos_nforce_48",
                  -- The X, Y, Z coordinates of the lightbar
                  Position = Vector( 0, 0, 100 ),
                  -- The pitch, yaw, and roll angle of the lightbar
                  Angles = Angle( 0, 0, 0 ),
                  -- The physical scale of the model. Values greater than one scale up, 
                  -- values less than one scale down.
                  Scale = 1,
               }
            }
         }
      }
   },
}

To apply these changes, simply save the file. You should see the lightbar suddenly appear and floating above your car.

4. Position the lightbar

To properly place and align the lightbar with the vehicle, we typically need to adjust three properties: the vector position, the orientation angles, and the size.

Position

The position uses a vector for X, Y and Z coordinates. This corresponds to three directions: left-right, forward-backward, and up-down. Change the individual numbers in the Position vector and save the file. Notice where and how the lightbar moves.

Angles

The orientation is determined by three different angles: the pitch (point up-down), yaw (face left-right), roll (rotate left-right). Note that the exact effect of these individual numbers will change depending on the lightbar's model orientation.

Scale

The scale affects how large the model is. By default, the scale is always 1 (which is 100%). Due to arbitrary differences in how the lightbar models and vehicle models were made, it is common to need to slightly increase or decrease the scale so it is proportionally realistic.

Result

Once you are acquainted with how these properties work, use them to carefully align the lightbar with the roof of the vehicle. (They are typically centered on the B-pillar, which is the divide between the driver door and passenger door.) Your end result should look similar to this:

Position = Vector( 0, -10, 86.7 ),
Angles = Angle( 0, 0, 0 ),
Scale = 1.05

Again, beware that different lightbar models have different orientations. The position, angles and scale of one well-placed lightbar won't necessarily be same for another.

(You may also notice that the feet and strap won't fit perfectly. That's okay for now. There are more advanced techniques and options you can explore later.)

To see your new, positioned lightbar in action, simply enter the vehicle activate the lights (F key by default).

5. Add a siren

In Photon 2, sirens are emitted by siren speaker components. Without a siren speaker, you won't be able to hear any siren. While this is significantly different from Photon LE, it allows siren behavior to be much more flexible and customizable. But for this tutorial, we're keeping it basic.

To start, add a siren index slot by inserting the following code above VEHICLE.Equipment = {.

VEHICLE.Siren = { [1] = "insert_siren_here" }

Like with components, there is unfortunately no siren asset browser at the moment. You can look at all default sirens here or try one of the following:

• SoundOff Signal nErgy 400: sos_nergy400
• Federal Signal PathFinder Unitrol: fedsig_pathfinder_unitrol
• Federal Signal PathFinder SSP: fedsig_pathfinder_ssp
• Whelen Epsilon Series: whelen_epsilon

Once you've chosen a siren set to use, replace insert_siren_here with the name. For this tutorial, I have chosen sos_nergy400.

Next, add a siren speaker using a component called siren_prototype, which offers generic functionality suitable for most normal emergency vehicles. For this, you will add a new equipment category below the "Lightbar" with the siren_prototype component configured.

VEHICLE.Equipment = {
   {
      Category = "Lightbar",
      -- This is the rest of lightbar code...
   },
   -- Siren code will go here --
}

Copy the block of code below in the position described above:

{
   Category = "Siren",
   Options = {
      {
         Option = "Speaker",
         Components = {
            {
               Component = "siren_prototype",
               Position = Vector( 0, 130, 50 ),
               Angles = Angle( 0, 0, 0 ),
               -- This refers to the the siren defined at VEHICLE.Siren[1]
               Siren = 1,
            }
         }
      },
   }
},

Now save the file. You should see a siren speaker suddenly appear positioned forward and above the hood of your vehicle.

Just as you did with the lightbar, adjust the siren speaker's position to an appropriate location. This is often just behind the vehicle grille.