> For the complete documentation index, see [llms.txt](https://davedev.gitbook.io/wiki/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://davedev.gitbook.io/wiki/immersive-flashlight/info.md). # Resource Information Four flashlight types on their own models, a tracked battery, a light that mounts under a drawn pistol, and a quick holster that gets out of the way. ### Compatibility * **Framework Modes:** Qbox via the qbcore adapter (`qbx_core`), QBCore (`qb-core`), ox\_core, ESX (`es_extended`), and Standalone. * **Inventory Modes:** ox\_inventory, QBCore/QB-compatible inventory, QS-Inventory, ESX inventory, Standalone, and Custom. * **Notifications:** ox\_lib, QBCore notifications, chat fallback, custom client event, or a custom handler function. * **Audio:** `xsound`, `interact-sound`, or the included `DaveDev_SFX` resource. Each provider plays the same flashlight soundset. If more than one is installed, set `prefer = true` on only the one you want. * **Database:** none. Battery levels ride along with the item itself on every supported inventory. {% hint style="info" %} Most servers should leave `setup.framework` and `setup.inventory` on `auto`. Standard Qbox installations normally use `qbx_core` with `ox_inventory`; force `setup.framework = 'qbcore'` and `setup.inventory = 'ox_inventory'` only when auto-detection needs help. {% endhint %} {% hint style="success" %} Configurations written for the first release still load unchanged. Anything you have not set uses a pre-configured default that we felt was a good neutral position. Updates are simple: keep your old config and add the new values you want to change, leave it the way it was, or just use the new config and tweak it. It'll still work either way! {% endhint %} *** ### The four flashlights Each type is its own item, its own model and its own light. Rename them, drop the ones you do not want, or add your own. | Type | Item | Look | Battery | | ---------- | --------------------- | ----------------------------------------------------------------------- | ------- | | `vintage` | `flashlight` | Long, heavy police torch. Warm incandescent beam. | 90 min | | `modern` | `led_flashlight` | Mid-size duty LED. Clean white beam. | 120 min | | `tactical` | `tactical_flashlight` | Compact LED. Cool blue-white, tight and bright. | 120 min | | `evidence` | `evidence_flashlight` | Forensic blacklight on the tactical body. Purple, short distance/throw. | 90 min | {% hint style="info" %} The battery figure is beam-on time. A light only drains while it is actually lit, so a flashlight held but switched off costs nothing. {% endhint %} *** ### Features **Player Experience:** * Four flashlight types, each with its own model, hold animation, beam colour, brightness, throw, and battery life. * Synchronized prop, beam direction, beam state, and cone width for every player nearby. * Beam steering on aim: hold right-click to point the beam with the camera, release, and it stays where you left it. Scroll while steering to widen or tighten the cone. * A light that mounts under a drawn pistol and rides the support hand, so aiming, firing, and reloading all stay exactly as they were. * A battery that drains while the beam is on, dims and flickers as it runs down, and is changed with a battery item and a short swap animation. * A quick holster that puts the flashlight away and uses the item you actually reached for, without a second key press. * A small corner HUD showing battery and the flashlight in hand, which players can hide, move, and resize to taste. * Holster and toggle sounds, with duty-belt audio for characters dressed for it. * On servers that run on commands rather than items, a per-player pick of which flashlight they carry, remembered between sessions. * Automatic cleanup when the player dies, is restricted, loses the item, or the resource stops. **Server & Integration Experience:** * Automatic or forced framework and inventory selection, with a bridge for anything unsupported. * Items that add themselves automatically to QBCore (when unset/unconfigured), and/or copy-paste item definitions for QBCore and every other supported inventory. * Optional item ownership checks and consume-on-use for the inventories that support it. * Handcuff and restriction checks by framework, state bag, or your own export. * Per-type control over light colour, brightness, throw, battery life, beam travel, and whether a type may mount under a pistol. * An in-game alignment tool for fitting your own flashlight models. * Lifecycle hooks that fire your own events and exports as the flashlight comes out, goes away, the beam switches, the cone moves, or the battery runs low — so your HUD, radial menu or dispatch system can react without anybody editing the resource. * Public server and client exports, plus state bags, for HUDs, evidence systems and custom inventories. * Automatic audio routing between `xsound`, `interact-sound` and the included `DaveDev_SFX`. {% hint style="info" %} GTA V provides 16 spotlight shadow IDs per client. The resource manages and reuses those IDs, but if more than 16 visible flashlights require shadows at once, some lights may share an ID and display shadow artifacts. We're actively working on a system that will prevent this, even if some visual fidelity is lost — it's far better than what occurs when the 16 slots are surpassed. {% endhint %} *** ## Development Limitations During the development process, we've found a few limitations that prevented us from getting a perfectly flawless setup. Below are some transparency items and paired explanations that hopefully can answer any questions you may have regarding known or related issues with the resource. {% hint style="warning" %} *These discoveries may change based on our findings or fixes that we've pushed to the resource. Check our update patch notes for potential fixes/workarounds to these issues!* {% endhint %} {% tabs %} {% tab title="Resource Monitor" %} **Resource Monitor:** * Multiple Running Instances = `0.06ms`-`0.10ms` (depending on the number of people in the area utilizing the flashlight at the same time) * Not running = `0.00ms` **Server Performance:** We sparingly send data to the server, using client-side magic to provide fluid & seamless movement amongst nearby players. It truly is "magic", and a huge part of what makes this resource so immersive. After **countless** hours of refactoring and micro-optimizing our resource, we found that those numbers were the absolute best it could be without removing features or scrapping the light portion of the flashlight — and that would be quite ironic. Trust us when we say, *if we could optimize it further, it would've been done*. For modularity purposes and to allow the usage of ANY in-game model, we kept our current design for now, which suits the majority of community purposes. **If you're not sure what this means:** The performance impact itself is negligible and unnoticeable, but we still wish to remain as transparent as possible with current and future customers by disclosing our findings during the development of this resource to avoid unwanted surprises. {% hint style="info" %} ***TLDR;** Due to the fidelity of this resource, and like many similar light-related resources, performance for these resources can be difficult. We have taken every possible step to ensure the highest level of optimization throughout the entire process. As lights must be called each frame, they can be somewhat intensive and are the main performance impact. However, this impact is negligible and shouldn't cause any issues whatsoever for a regular FiveM community/server.* {% endhint %} {% endtab %} {% tab title="Pistol Mode" %} **Pistol Mode / Tactical Pose:** Mounting a light under a drawn pistol takes some liberties with how the game handles a weapon in the hands, and it is worth knowing where the edges are before you promise it to your players. * It works with the **Pistol, Combat Pistol, and Heavy Pistol**. Any other weapon stows the light. * Only the **LED** and **Evidence** flashlights offer it. The vintage torch and the duty light are physically too large to sit under a pistol and do not mount. * **Pistol mode is a third-person feature.** In first person the light is hidden and the beam goes dark, and the toggle is ignored while the player is in there. The flashlight stays mounted throughout and comes straight back when the camera returns — nothing is lost, and the battery does not drain while it is dark. * You must have a pistol in your hands when using the supported flashlight model. {% hint style="warning" %} First person is the honest compromise rather than a workaround. The engine chooses its own first-person weapon poses, and we would rather hide the light there than show you a broken one. If you would prefer it visible regardless, set `firstPerson = 'show'` on the type — just be aware the pose is then the game's, not ours. {% endhint %} {% hint style="info" %} It can be switched off server-wide, or left on for some flashlight types and not others. Regular hand-held flashlights are never affected by any of this functionality, in first person or third. {% endhint %} {% endtab %} {% tab title="Finite Shadow Slots (16)" %} **Shadow Slot Limitations:** Unfortunately, in GTA 5, Spotlight shadow IDs are finite. There are 16 slots/IDs available at one time, and if an entity shares a shadow ID, shadows from one spotlight will appear in the other.\ \ Visually, this is very noticeable, often creating strange patterns. To try to mitigate this limitation, we've built a system that smartly assigns IDs and handles them based on client priority. Each one reserves its own ID and frees up IDs for reuse as necessary. {% hint style="warning" %} This limitation affects a client only when more than 16 flashlights requiring shadows are visible at the same time. The flashlights will still operate, but excess lights may share a shadow ID and display unexpected shadow patterns.\ \ We're working on a potential solution that may create the spotlights differently if an ID isn't available or handle light attachment in an entirely different way. {% endhint %} {% endtab %} {% tab title="Player/World Height Limitations" %} **Player/World Height Limitations:** * We've discovered a strange limitation/bug with GTA 5 (something we unfortunately cannot control) when attaching a prop to a prop that is attached to a player — (Prop < Prop < Player) — When this occurs, strange offsets based on Z-Level (height in the game world) will apply. We've added an intelligent system that minimizes this issue as much as possible. * This should NOT disrupt any gameplay whatsoever — this is purely a small visual flaw that we wanted to personally document to be as transparent as possible. {% hint style="warning" %} This is barely noticeable, but you may see that when you're standing on a mountain, or walking up/down steps, the corona is slightly higher/lower than usual. This is unfortunately uncontrollable due to the issue described above. Many attempts were made to lessen this effect, but none were as good as the current system in terms of performance & visual effect, so this iteration was kept. {% endhint %} The lens glow also allows for characters wearing high heels, which sit the model higher off the ground than the game otherwise reports. That adjustment can be switched off if your server does not need it. {% endtab %} {% tab title="Rockstar Editor Issue(s)" %} **Rockstar Editor Limitation(s):** Unfortunately, due to the way the flashlight works, a significant part of the resource cannot be shown in Rockstar Editor. Luckily, a majority of the effect is still visible and convincing in environments with adequate lighting. {% hint style="info" %} *We're actively exploring methods to make this possible and even more convincing — so this isn't a lost cause; we just need some time to get it right!* {% endhint %} **What works:** When viewed through Rockstar Editor, the following things can be seen: * Flashlight Prop * Hold/equip Animation * Flashlight Tip Corona * Synchronized Position/Rotation **Discovered Limitation(s):** The **actual flashlight beam/light** does not appear during Rockstar Editor playback (This is the light you adjust and move around on the ground/in-front of the character). This is a GTA V/Rockstar Editor limitation rather than something in the resource: the beam has to be drawn every frame during live gameplay, and Rockstar Editor does not reproduce that during playback, so only the physical and visual supporting elements are visible. {% hint style="warning" %} For showcase footage where the beam must be visible, standard live gameplay recording is recommended instead of Rockstar Editor. Any other use, such as the flashlight prop, corona, rotation, etc., is still very convincing, and the effect translates well within Rockstar Editor. {% endhint %} {% endtab %} {% endtabs %} *** ## Frequently Asked Questions > ### **"Can I use my own inventory, or framework for this resource?"** Yes! We support custom inventory bridges and the documented framework adapters. More information and extra tips can be found in the installation guide. > ### **"Do I have to use all four flashlights?"** Not at all. Drop a type, and its items go with it; rename the items to whatever your server already calls them, or keep one and ignore the rest. You can also add your own type on top, with your own model. > ### **"Do batteries need a database?"** No. The level travels with the item itself, so a flashlight that is half-drained is still half-drained after it changes hands or the player reconnects. Batteries can also be switched off entirely if you would rather they never run down. > ### **"Do I need DaveDev\_SFX?"** Only if you are not already running `xsound` or `interact-sound`. It is included free with the download, and it plays the flashlight's sounds without anything to copy. If you do run one of the other two, skip it. > ### **"Will the flashlight get in the way of my other scripts?"** That is what the quick holster is for. Reach for a weapon or another item and the flashlight puts itself away first; then that item is used as normal. If you would rather it did not, it can be turned off. > ### **"Does pistol mode work in first person?"** Unfortunately, no. Due to the way pistol animations work, third-person view seems to be the only place where hands can be moved away from a weapon. When you switch to first person, both the light and animation stop. Hand-held flashlights are unaffected either way, as the animations aren't trying to glue the player's hands onto a weapon. > ### **"Can my HUD react when somebody takes a flashlight out?"** Yes, and without anybody touching the resource. Lifecycle hooks call your own events or exports at the moments that matter — the torch coming out, going away, the beam switching, the battery dying — so your HUD, radial menu, or dispatch system can react. There are exports and state bags too, if you would rather ask than be told. It is all on the [Development Resources](/wiki/immersive-flashlight/info/development-resources.md) page. > ### **"How do I install this resource?"** Steps to install this resource, and even how to download it from the CFX Portal, can be found in [Getting Started](/wiki/immersive-flashlight/info/getting-started.md)! > ### **"How do I get support for my products?"** Support is handled through our [**Discord**](https://discord.gg/wgPZTwFgaz)**.** While we’d love to be a big team, we’re unfortunately not, so please allow up to 48 hours for a response. *Response time varies depending on the volume of tickets we receive.* If you notice anything in the wiki that could be clearer or more helpful, please let us know in your ticket! We'd love to make the process easier for everyone, and your assistance would be greatly appreciated.