Vehicle Lights - user-grinch/ModelExtras GitHub Wiki

To activate lights in-game using the Model Extras plugin, you need to assign a specific material with the correct color to the mesh of the vehicle model. The plugin recognizes the material's purpose (e.g. brake, turn, tail) based on its color and automatically adjusts its brightness to simulate the light being turned on.

Each light material has two states:

Off – the default texture is displayed.

On – the same texture is shown, but with increased brightness applied automatically.

💡 Tip: You can also assign a custom emissive texture for the "on" state. This is explained in the section below.

To simulate the light glow, place a node/dummy on the area of the mesh where a corresponding light material is applied. The name of the dummy determines the type of light. Based on this name, the plugin will know to enable a corona (glow effect) at that position.

The visual properties of each corona — such as its color, direction, size, and intensity — are defined in the vehicle’s .jsonc config file (e.g. burrito.jsonc).

• ⬅️ Z: Left turn signal
• ⏹ Left Shift: Turns off indicators
• 🔃 X: Activates hazard lights (both turn signals)
• ➡️ C: Right turn signal

• ☁️ J: Toggles fog lights
• 💡 G: Toggles long headlights (high beams)
• 🌆 B: Toggles Spotlights
• ➶ RMB: Rotates Spotlights

Indicator lights dynamically activate when turning or changing lanes, ensuring that vehicles visually communicate their intentions.

• 🟢 Supports both player & NPC vehicles
• 🏎️ AutoIndicatorsOnSteer (INI Setting): When enabled (AutoIndicatorsOnSteer = 1 in ModelExtras.ini), turning the steering wheel or holding steering keys (A / D / Arrow keys) automatically engages the corresponding turn signal, and cancels it once the steering wheel straightens out.

On stock vehicles that lack custom indicator dummies/materials, enabling StandardLights_GlobalIndicatorLights = 1 under [LIGHTS] in ModelExtras.ini will automatically flash the vehicle's rear taillights as turn signals, complete with synchronized real-time dynamic point lights!

• Long Lights (High Beams): Pressing G toggles high-beam headlights, amplifying headlight material intensity and extending dynamic point light range. High-beam toggle requires headlights to be active.
• Volumetric Beams: Controlled via HeadLightBeams = 1 under [LIGHTS] in ModelExtras.ini to render classic volumetric light beam cones extending from the headlights.

ModelExtras renders dynamic, real-time ground point lights across all vehicle lighting elements:

• Headlights & High-Beams
• Taillights & Brake Lights
• Turn Indicators & Hazard Lights
• Fog Lights & Reverse Lights
• Spotlights & Siren Strobes
• Ground shadows feature realistic 3D vehicle leaning orientation, tilting accurately as the vehicle turns, pitches, or navigates uneven terrain.

Fog lights improve visibility in foggy or low-light conditions by illuminating the road directly ahead.

• Manual Toggle: Can be toggled manually by the player using the FogLightKey (default: J).
• Weather-Reactive: When foggy weather occurs in San Andreas, fog lights automatically illuminate.
• FoglightTiedToHeadlight (INI Setting): When enabled (FoglightTiedToHeadlight = 1 in ModelExtras.ini), fog lights will only turn on if main headlights are active. Set to 0 for completely independent toggle.
• Note: FogLights don't cast shadows by default. Specify size in JSONC or _prm to enable ground shadows.

Reverse lights activate dynamically when the vehicle shifts into reverse gear, illuminating the ground and area behind the vehicle with white light and signaling reversing maneuvers.

• Brake Lights: Engage dynamically when the vehicle slows down, stops, or applies brakes. This is recommended if the vehicle has a separate mesh for brake lights. If the vehicle uses the same mesh for both taillights and brake lights, the game runs as vanilla.
• PlayerIdleBrakeLights (INI Setting): When enabled (PlayerIdleBrakeLights = 1 in ModelExtras.ini), the player's brake lights automatically remain illuminated while the vehicle is stopped and idling, releasing smoothly upon throttle input.

For vehicles equipped with pop-up retractable headlights (e.g. ZR-350, custom mod models), ModelExtras synchronizes light coronas, dynamic point lights, and volumetric beams with the pop-up cover animation, activating illumination only after the covers finish fully opening.

This is the modern rear lighting system commonly found on American vehicles from the 1990s to the present day. In this setup, the brake and turn signal functions share the same light unit, while the tail light is a completely separate element — often a thin strip or dedicated section of the rear light cluster (for those just use 🌙 light_night). This system is ideal for modern vehicles intended for use under North American traffic laws.

📃 How it works:

• 🔴 Stop Function: The main rear light turns on at full brightness when the brake pedal is pressed. (material + corona)
• 🔴 Turn Function: The same light flashes when turn signals are active. If braking and turning at the same time, one side flashes while the other stays steady. (material + corona)
• 🔴 Stop + Turn (Combined): The turning side flashes (turn signal has priority), the opposite side stays on as a brake light.

💡Tip: Stick to red materials and coronas for this setup — American cars don’t use amber indicators like most other countries do.

Stop-Tail-Turn Lights are multifunctional rear lights that combine brake lights, tail lights, and turn signals into a single unit. This system was widely used in American vehicles from the 1950s to the 1980s, especially in classic sedans, muscle cars, and pickups — making it ideal for retro-inspired cars in GTA San Andreas.

📃 How it works:

• 🔴 Stop Function: The light activates at full brightness when the brake pedal is pressed. (material + corona).
• 🟡 Tail Function: The light stays on when the lights are turned on, providing rear visibility at night. (material + corona).
• 🔀 Turn Function: The same light flashes on and off when the turn signals are active. (material + corona, At night, this light is never dim while braking or turning, only corona blinks).

💡Tip: Stick to red materials and coronas for this setup — American cars don’t use amber indicators like most other countries do.

Side lights work as marker lights on vehicle bodies, often used on trucks and trailers. They turn on automatically at night, just like the "light_night" dummy, casting light shadows to the left and right sides respectively.

Spot lights are high-intensity directional lights mounted on a vehicle to provide illumination in a specific direction. They are typically used for off-road driving, law enforcement, emergency response, and utility work. Unlike standard headlights, which are designed to illuminate the road ahead, spotlights can be aimed and rotated using the right mouse button.

Strobe lights are high-intensity flashing lights often used in emergency vehicles, law enforcement, or show vehicles. They create a distinctive flashing effect that grabs attention and enhances visibility in critical situations.

📃 How it works:

• ⚡ Strobes will automatically flash on and off at a rapid rate.
• 🔁 Each strobe is independent, allowing varied flashing patterns via configuration.
• 🎛️ Their flashing behavior can be adjusted via JSONC config (strobedelay).

💡Tip: Ideal for emergency vehicles like police cars, ambulances, fire trucks, or even futuristic custom vehicles.

They turn on according to the times indicated by their respective dummies, working automatically:

• 🔸 light_day: will remain on only during the day and will turn off at night.
• 🔹 light_night: will remain on during the night and will be off during the day.
• 🔸 light_allday: will always be on, regardless of the time.

Note: Night materials are off during daytime & day materials are off during night time.

• ⚪ headlights / headlights2 → Left Headlight Material Color: 255 175 0
• ⚪ headlights / headlights2 → Right Headlight Material Color: 0 255 200
• Note: You only need to add one headlights or headlights2 dummy to the right side of the vehicle. The game will automatically duplicate it to the left side.
• Note²: Pressing G (LongLightKey) toggles high beam mode, boosting headlight material brightness and casting extended pointlights.

• 🔴 taillights / taillights2 → Left Taillight Material Color: 185 255 0
• 🔴 taillights / taillights2 → Right Taillight Material Color: 255 60 0
• Note: You only need to add one taillights or taillights2 dummy to the right side of the vehicle. The game will automatically duplicate it to the left side.

• 🔸 indicator_lf / turnl_lf → Left Front Indicator Material Color: 183 255 0
• 🔹 indicator_rf / turnl_rf → Right Front Indicator Material Color: 255 58 0
• 🔸 indicator_lm / turnl_lm → Left Middle Indicator Material Color: 182 255 0
• 🔹 indicator_rm / turnl_rm → Right Middle Indicator Material Color: 255 57 0
• 🔸 indicator_lr / turnl_lr → Left Rear Indicator Material Color: 181 255 0
• 🔹 indicator_rr / turnl_rr → Right Rear Indicator Material Color: 255 56 0

• ⚪ foglight_l / fogl_l → Left Fog Light Material Color: 255 174 0
• ⚪ foglight_r / fogl_r → Right Fog Light Material Color: 0 255 199

• ⬅️ revl_l / reversingl_l / reversinglight_l → Left Reverse Light Material Color: 255 173 0
• ➡️ revl_r / reversingl_r / reversinglight_r → Right Reverse Light Material Color: 0 255 198

• 🔴 breaklight_l / breakl_l → Left Brake Light Material Color: 184 255 0
• 🔴 breaklight_r / breakl_r → Right Brake Light Material Color: 255 59 0

• ⬅️ sidelight_l → Left Side Light Material Color: 255 200 1
• ➡️ sidelight_r → Right Side Light Material Color: 255 200 2

• ⬅️ sttlight_l → Left STT Light Material Color: 255 200 3
• ➡️ sttlight_r → Right STT Light Material Color: 255 200 4

• 🔴 nabrakelight_l → Left Brake Light Material Color: 255 200 5
• 🔴 nabrakelight_r → Right Brake Light Material Color: 255 200 6

• 🔦 spotlight_lightX → X can be any number, allowing for multiple spotlights. Material Color: 255 200 7
• ⭯ spotlight_dummy → Object rotated from its pivot along with the spotlight beam.

• ⚡ strobe_light1 → Material Color: 255 199 1
• ⚡ strobe_light2 → Material Color: 255 199 2
• ⚡ strobe_light3 → Material Color: 255 199 3
• ⚡ strobe_light255 → Material Color: 255 199 255

Each strobe dummy must be paired with a specific material color for the plugin to recognize and animate them correctly. You can create up to 255 unique strobe light instances, by naming each dummy as strobe_light1, strobe_light2, ..., up to strobe_light255.

• 🔆 light_day → Day Light (Primary) Material Color: 0 18 255
• 🔆 light_day2 → Day Light (Secondary) Material Color: 255 7 128
• 🌙 light_night → Night Light (Primary) Material Color: 0 16 255
• 🌙 light_night2 → Night Light (Secondary) Material Color: 255 8 128
• ⏳ light_allday → All Day Light (Primary) Material Color: 0 17 255
• ⏳ light_allday2 → All Day Light (Secondary) Material Color: 255 9 128
• 🔆 light_<suffix> → Generic AVS light dummy; ModelExtras treats it as an all-day light. The light_em siren family is handled separately.

✨TIP: You can add an unlimited number of indices for the same light type to create separate configurations in the JSONC, such as "light_night3", "light_allday9", "light_night57" or "light_night72". However, they will not have linked materials, only coronas and shadows. Linked material colors work only for the primary and secondary light dummies.

You can assign a custom texture for any light, which is especially useful when simulating modern LED lighting. In real-world LEDs, the bulb itself is usually clear or white, while the emitted light can be any color.

🔧 To achieve this effect in-game:

1. Assign the material with a regular "off" texture, just like you would normally.
2. Add a custom _on texture to vehiclename.txd, vanilla vehicle.txd, or VehFuncs vehicle2.txd.

🧪 Example:

• led_indicator → used as the OFF state (assigned to the model material).
• led_indicator_on → acts as the ON state (glowing version).

You can place the texture led_indicator_on inside:

• banshee.txd → per-vehicle custom glow.
• vehicle.txd → shared glow for multiple vehicles.
• vehicle2.txd → shared glow for multiple vehicles with VehFuncs feature.

🔁 Notice: If both TXDs contain a texture with the same name, the version in vehiclename.txd will take priority.

Deactivates a light when a specific vehicle body part is damaged or detached. Simply place the light dummy as a child of the respective damageable node in the model hierarchy. 🧪 Example: Placing the revl_l dummy as a child of the boot_dummy node deactivates the left reverse light when the vehicle's boot is damaged or opens.

🚨 This method is for compatibility with older ImVehFt-adapted vehicles. Prefer switching to JSONC configuration for richer features and stability.

🔧 Parameters format: _prmRRGGBBXYZ

📌 Dummy name limit: Keep it under 23 characters to avoid crashes.

🔹 RR: Red color (HEX)
🔹 GG: Green color (HEX)
🔹 BB: Blue color (HEX)
🔹 X: Light type (0: Directional, 1: Inversed-Directional, 2: Non-Directional)
🔹 Y: Corona size (0-9)
🔹 Z: Shadow size (0-9)

Instead of renaming nodes in the model, use a JSONC file stored in ModelExtras/data/ or anywhere in modloader/:

📌 Path: ModelExtras/data/<FILENAME>.jsonc or modloader/AnyFolder/<FILENAME>.jsonc

Both model ID and model name are valid FILENAME (e.g. 602.jsonc or alpha.jsonc).
💡Tip: It is recommended to use model names instead of model IDs to avoid conflicts with other mods — especially when using added vehicles.

Every JSONC configuration requires a metadata specification before any other settings. See here: METADATA

{
  "lights": {
     "inertia": 0.45, // Global halogen bulb fade-in / fade-out time (seconds). Set 0.0 for instant LED response.
     "YOUR_DUMMY_NAME": {
       "inertia": 0.45, // Per-light override for halogen bulb fade time
       "material": {
           "color": { "red": 255, "green": 212, "blue": 95 },    // Custom RGB color applied to mesh material when light is ON
           "color_off": { "red": 40, "green": 40, "blue": 40 }   // Custom RGB color applied to mesh material when light is OFF
       },
       "corona": {
           "color": { "red": 255, "green": 212, "blue": 95, "alpha": 85 },
           "size": 0.4,
           "type": "directional"
       },
       "shadow": { 
           "color": { "red": 255, "green": 200, "blue": 80, "alpha": 70 },
           "rotationchecks": true,
           "size": 1.1,
           "texture": "headlight_short",
           "offset": { "x": 0.0, "y": 0.5 } // 2D ground shadow offset (supports number, object {x, y}, or array [x, y])
       }
     }
  }
}

📌 YOUR_DUMMY_NAME must match the model node/dummy name (e.g., indicator_lr, fogl_l, revl_r, taillights). For a strobe, put strobedelay inside that strobe's entry, such as "strobe_light1": { "strobedelay": 250 }.

• It must be the same name that exists in the model. If there is a _prm parameter in the dummy name, it should be ignored. JSONC will override it.
• You do not need to assign all parameters to every dummy. Omitted parameters use default configurations.

Defines the transition / fade-out time (in seconds) simulating incandescent and halogen bulb filament cooldown.

• Global Scope: "lights": { "inertia": 0.45 } applies to all lights on the vehicle unless overridden.
• Per-Light Scope: "taillights": { "inertia": 0.45 } overrides inertia specifically for that light.
• Instant LED Lights: Set "inertia": 0.0 for modern crisp LED indicators, strobes, or emergency flashers.

Defines the delay time for a strobe dummy in milliseconds (e.g. 100, 250, 500). Put it inside that dummy's lights entry. A root-level lights.strobedelay value is not read.

ModelExtras allows independently customizing both the active (ON) and idle (OFF) appearance of the 3D vehicle light mesh material, completely separate from floating corona flares.

Defines the emissive tint applied to the 3D mesh material when the light is turned ON:

"material": {
    "color": { "red": 255, "green": 212, "blue": 95 }
}

Also supports HEX strings ("#FFD45F", "0xFFD45F") and RGB arrays ([255, 212, 95]).

Defines the tint applied to the 3D mesh material when the light is turned OFF:

"material": {
    "color_off": { "red": 40, "green": 40, "blue": 40 }
}

💡 Decoupled Architecture: Corona flare colors (corona.color) only affect the floating glow effect and ground pointlights. They do not alter the 3D mesh material color. To tint the vehicle's glass or light lens itself, define the "material" block.

Define the corona brightness settings:

Defines corona color. red, green, blue, alpha (0–255).

Defines the size scale of the light corona (e.g. 0.2, 0.35, 0.5).

Sets the corona viewing direction:

• directional: Visible primarily from the direction the dummy is pointing.
• inversed-directional: Reverse corona display. Lights in the opposite direction (useful for rear-facing auxiliary lights).
• non-directional: The light is visible from all angles.

Defines the settings for the ground light shadow projection.
📌 Detail: Shadows for secondary dummies taillights2 and headlights2 are disabled by default. Putting a "shadow" section inside their JSONC entry will force enable it.

Defines shadow color. If omitted, inherits the corona color.

By default, ModelExtras casts shadows only outward from the vehicle, relative to its center. Set this to true to allow unrestricted 360° shadow orientation.

Defines the size scale of the ground shadow (e.g. 0.8, 1.0, 1.5).

Shadow texture loaded from me_texdb.txd (e.g. round, pointlight, foglight, taillight, narrow, tightfocused, spotlight).

✨​ TIP: Some shadows of lights are stretched within the code, like turn lights. So, the pointlight texture may appear oval-shaped. To fix this, use the oval texture to counteract the stretching, making it truly round in the game.

Defines a 2D positional displacement for the ground shadow projection relative to the light dummy point. This is particularly useful when dummies are placed deep inside bumper/headlamp recesses or when ground shadows need precise forward/backward or lateral alignment.

Supported formats:

• Number (Y axis offset / forward-backward):

  "offset": 0.5

• Object (X and Y axis offsets):

  "offset": { "x": -0.15, "y": 0.5 }

• Array ([X, Y]):

  "offset": [-0.15, 0.5]