Troubleshooting

Every failure mode surfaces in the debug overlay. Open it with /decals_debug (admin-only; /decals_debug <serverId> opens it on another player's screen so they can read values to you), then check the cards top to bottom.

1. DECALS.DAT PROBE says FAILED

The decal types from rm_decalv_assets never registered in this session, so nothing can render no matter what else is right. Two causes:

• The player joined while rm_decalv_assets wasn't running. Its decal types mount when the game level loads, i.e. at join. Make sure it starts at boot, then have the player reconnect. Restarting rm_decalv_assets does not fix already-connected players.

• Another resource owns the level meta. Check the GTA5.META OWNERS card: it must say rm_decalv_assets (expected). If a map/meta resource is listed instead, it wins the replace_level_meta conflict. Load it before rm_decalv_assets or remove its override.

2. DECAL TYPE SLOTS shows 31 instead of 280

Milder form of check 1, same causes: the player joined while rm_decalv_assets wasn't running, either because it never started at boot or because it was being restarted at that moment. The session then falls back to the game's own 31 built-in decal types, so decals render but only 31 distinct textures fit. Start rm_decalv_assets at boot, leave it running, and have the affected player reconnect to restore the full 280.

3. CATALOG isn't "Loaded"

The client never received the catalog. Read the server console from the last rm_decalv start:

• File not found: [x.webp] means the entry was pruned; the image is missing from rm_decalv/assets/.

• [x] has an unsupported file extension means only webp/png/jpg are accepted (gif when enabled).

• A Lua error in decals.lua stops the whole catalog. Fix the syntax and restart.

4. One specific decal is blank

While placing, a small preview sprite sits in the bottom-right corner showing the raw texture. Read it like this:

• Sprite visible, decal missing: the texture is fine; the decal types didn't register in this session. Back to checks 1 and 2.

• Sprite blank too: the texture never resolved. Wrong textureDict/textureName, the ytd isn't in rm_decalv_assets/stream/, or the dict was updated without players reconnecting. For image-file decals, check the RUNTIME TEXTURE POOL card: a full bucket (e.g. 512² 16/16) means too many distinct image decals are in range at once, so move the pack into a dictionary (recommended method).

5. Decals exist but don't draw right now

The RENDERING card counts what's loaded vs what's drawn:

• Graffiti rows > rendered: the extras are beyond cfg.rendering.distance or over cfg.rendering.graffitiBudget (farthest drop first).

• Sticker vehicles tracked > 0, rendered 0: the vehicles are out of render range, or currently hidden by visibility culling (blocked from view / behind the camera); they redraw as soon as they come back into view.

• Only one player affected: ask them to open the catalog and check the gear icon: players can turn sticker and graffiti rendering off for themselves, and the choice persists between sessions.

6. Decals vanish near a specific vehicle (ENGINE says Stalled)

The ENGINE cell in the status strip probes live whether GTA's decal engine is accepting new decals. If it reads Stalled, some vehicle model on your server is overloading the engine: unoptimized high-poly conversions make every decal cost many times more than it should, and past a budget the engine stops creating any new decals in that player's game (all decal types, other scripts' decals included) until the load drops. The stall is per client, but every player who renders that vehicle's stickers hits the same wall on their own screen, so in practice it reads as server-wide. Typical symptoms: previews stop rendering near a certain car, stickers on healthy cars blink out and return when that car is stored.

The script protects itself automatically (it sheds load and recovers), but the real fix is finding and blacklisting the model:

1. Add cfg.dev = true to cfg.lua and restart the resource.

2. Run /decals_meshprobe <model> for a suspect, or /decals_meshprobe all to sweep every vehicle model on the server (takes a while; /decals_meshprobe stop aborts).

3. The run ends with a summary and ready-to-paste cfg.blacklistModels lines for every model that stalled the engine. Paste them, remove cfg.dev, restart.

For the vehicle's creator: the fix on their side is lowering body-panel polygon density, adding real LODs, and making the collision match the visible body. Vanilla-quality models pass the probe with a wide margin.

7. Flip switch is greyed out

Expected in three cases: the decal is a GIF (no flip variant exists), the texture dictionary has no <dict>_f twin (build one with ytd-flip), or you're placing on a wall (graffiti has no flip).

8. Console warnings worth acting on

Since 3.3.0 routine self-healing messages sit behind verbose logging so consoles stay quiet; run setr ox:printlevel:rm_decalv verbose (before resource start) when you want the full diagnostic stream. The warnings below always print:

• decal capacity: X of 280 slots...: see check 2.

• Asset ... uses N MiB of physical memory: a custom ytd is oversized; split it into smaller dictionaries.

• no texture source registered for x.webp: a placed decal's catalog entry was removed. Delete the orphaned decal from the admin panel or restore the entry.

• N asset file(s) not referenced by decals.lua: imported files whose snippet never got pasted. Paste the entries or delete the files.

Still stuck? Open a ticket in our Discord with your server console output and a screenshot of the debug overlay. Those two cover nearly every case.