Library System & Index

Photon 2 uses a custom content and library system to load and manage user-created data. This includes vehicle profiles, components, input configurations, user commands, and more. It allows for content to be easily exported and drastically reduces "data duplication" between multiple objects.

For example, a "fleet" of alike vehicles can use a custom siren configuration that only needs to be defined once. This configuration can be edited or updated without any need to subsequently update each vehicle file.

Data Sources and Types

Photon 2 library objects can both load from Lua files and import from JSON.

Dedicated Lua Files

garrysmod/addons/my_photon_addon/lua/photon_v2/library/LIBRARY_TYPE/my_vehicle_file.lua

A dedicated Lua file is a Lua file that configures one library entry and one entry only. The name of the file is used as the entry name. This is the recommended method for Components and Vehicles for its conciseness, simplicity and ease-of-locating.

-- The line below MUST be used for a dedicated file to work
if (Photon2.ReloadVehicleFile()) then return end
local VEHICLE = Photon2.LibraryVehicle()

VEHICLE.Title = "Dedicated Vehicle File"

-- All code below relates only to this file...

Lua Library Files

garrysmod/addons/my_photon_addon/lua/photon_v2/library/LIBRARY_TYPE/my_vehicle_library_file.lua

Normal Lua library files can be used to declare multiple entries in the same file. They can be utilized to reduce the total number of Lua files (if it becomes a concern) or group related components together (e.g. different sizes of the same component).

Because saving a file with multiple entries causes all of them to reload simultaneously, it may be modestly more sluggish than using a dedicated Lua file (for end-users this is mostly irrelevant because loading is an otherwise one-time operation).

Entries defined in a normal library file need to explicitly define a name and call the corresponding Photon2.Register...( ENTRY ) function.

-- Create a new vehicle table
local VEHICLE = Photon2.LibraryVehicle()

VEHICLE.Name = "normal_library_vehicle"
VEHICLE.Title = "My Normal Library Vehicle"

-- Additional vehicle code here...

-- Register the vehicle table
Photon2.RegisterVehicle( VEHICLE )


-- Repeat steps above for the next entry...
VEHICLE = Photon2.LibraryVehicle()

VEHICLE.Name = "normal_library_vehicle_2"
VEHICLE.Title = "My Normal Library Vehicle #2"

Photon2.RegisterVehicle( VEHICLE )

Most Library entries can be loaded through both Lua and user-writable JSON files. (Note: as of writing (December 13th, 2023), components and vehicle profiles do not yet support loading from JSON due to their complexity, but the feature is planned.)

Advanced

The Library system is actually paired with a discreet system called the Index, which manages "compiled" entries from the Library. Raw data is kept within the Library, while compiled versions are kept within the Index. The "compilation" process performs optimizations and mapping, and adds underlying functionality to the objects.

Data from the Library entry is also frequently mutated to more appropriate data types for internal operations (although the original Library entry is kept intact).

The Index system also supports a "lazy-loading" pattern, which prevents unused Library entries from unnecessarily compiling and using more memory than necessary.