📌 RDE Placeable Items — V1.0.0 Alpha

Wall-mount weapons. Place props. Persist everything. Lose nothing.
Full ox_inventory metadata preservation — ammo, skins, components, tint, serial number, durability. Items survive server restarts. Weapons come back exactly as you left them.

Built on ox_core · ox_lib · ox_inventory · ox_target · oxmysql

Built by Red Dragon Elite | SerpentsByte

🎯 Overview

RDE Placeable Items V1.0.0 Alpha lets players remove any ox_inventory weapon (or configurable prop item) from their inventory and physically place it in the world — wall-mounted or floor-placed. The item persists in a database across server restarts. When a player picks it up, they receive the item back with 100% of its original metadata intact: ammo count, weapon skin, components (suppressor, extended clip, scope, etc.), tint index, serial number, and durability.

Admins get a full in-game CRUD panel, permanent respawn toggle (TSRP-style weapon racks), and per-item target options.

50+ GTA V weapons pre-configured out of the box. Custom props supported.

Why RDE Placeable Items?

Feature	Typical Placeable Scripts	RDE Placeable Items
Wall-mount mode	❌ or basic	✅ Toggle with rotation + tilt + height
Metadata preservation	❌ ammo only (if that)	✅ ammo, skin, tint, components, serial, durability
Component visual on wall	Broken	✅ Valid-hash filtered, deferred render
Permanent respawn (weapon racks)	❌	✅ Admin toggle, configurable delay
Proximity loading	❌ always spawned	✅ Render distance based, zero idle overhead
Gaze-based name display	❌	✅ 100ms raycast, only visible when aimed at
Admin CRUD panel	❌	✅ `/placedmenu` — list, teleport, delete, toggle respawn
Race condition on pickup	Crashes or dupes	✅ Server-side atomic remove + add
ox_target integration	Basic	✅ Per-item zones, 0.3m sphere (no zone overlap)
50+ pre-configured weapons	❌	✅ All GTA V weapons ready to use

✨ Features

📌 Placement System

Wall mode — press W during placement to switch between floor and wall mounting; weapon snaps to wall with correct orientation
Full rotation control — Z-axis rotation (← →), X-axis tilt (↑ ↓), height offset (Scroll)
Fast mode — hold SHIFT for coarse adjustments
Live ghost preview — semi-transparent weapon object follows your aim before confirmation; components and tint applied to preview via RequestWeaponAsset
Context menu on use — pressing F3 while holding a weapon opens Equip / Place — does NOT replace ox_inventory's equip behaviour

💾 Metadata Preservation

The entire ox_inventory metadata object is captured at placement time and restored on pickup:

Field	Preserved
Ammo count	✅ (live game-state override, not stored value)
Weapon tint / skin index	✅ (live game-state override)
Components (attachments)	✅ (stored array, hashes pre-filtered per weapon)
Serial number	✅
Durability / quality	✅
Registered owner	✅
Custom metadata fields	✅ (entire metadata object passed through)

🔁 Persistent Storage

All placed items are written to rde_placed_items on placement
Server restart → items reload from DB, re-spawn near players automatically
Items are only removed from DB when picked up or admin-deleted
Permanent Respawn — admin can mark any item to re-appear after pickup (Config.DefaultRespawnDelay seconds)

👁️ Proximity & Gaze

Entities spawn when a player enters Config.RenderDistance and despawn when they leave — no entities sitting idle across the map
Gaze detection via short raycast every 100ms — weapon name appears as 3D text only when you're looking directly at the item
Wait(0) draw loop only active while an item is actively gazed — zero idle CPU cost

🎯 ox_target Integration

Each placed item gets its own addSphereZone with a 0.3m radius (entity-tight, no zone overlap when weapons hang close together). Options per item:

🤲 Pick Up — owner or admin, returns item with full metadata
♻️ Toggle Permanent Respawn — admin only, cycles ON/OFF
🗑️ Delete — admin only, removes from world and DB permanently

📦 Dependencies

Resource	Required	Notes
oxmysql	✅ Required	Database layer
ox_core	✅ Required	Player/character framework
ox_lib	✅ Required	UI, keybinds, notifications
ox_inventory	✅ Required	Item removal, metadata, restore
ox_target	✅ Required	Pickup / admin interaction zones

🚀 Installation

1. Clone the repository

cd resources
git clone https://github.com/RedDragonElite/rde_placeable_items.git

2. Add to `server.cfg`

ensure oxmysql
ensure ox_core
ensure ox_lib
ensure ox_inventory
ensure ox_target
ensure rde_placeable_items

Order matters. rde_placeable_items must start after all its dependencies.

3. Register items in ox_inventory

Copy the entries from data/ox_inventory_items.lua into your ox_inventory items.lua. These add the client.export hook that triggers the Equip / Place context menu.

If you already have weapon items defined, just add the export line to your existing entries:

['weapon_pistol50'] = {
    -- ...your existing fields...
    client = { export = 'rde_placeable_items.use_WEAPON_PISTOL50' },
},

The export handler shows a context menu — it does not replace ox_inventory's normal equip behaviour.

4. Database

The table rde_placed_items is created automatically on first start. No manual SQL import required.

5. Restart and place your first weapon

restart rde_placeable_items

Equip any configured weapon → press F3 → select Place → position it → ENTER to confirm.

🕹️ Placement Controls

Key	Action
`LMB` / `ENTER`	Confirm placement
`BACKSPACE` / `ESC`	Cancel — item returned to inventory
`W`	Toggle Wall / Floor mode
`G`	Toggle collision
`← →`	Rotate Z axis
`↑ ↓`	Tilt (X axis)
`Scroll`	Adjust height
`SHIFT`	Fast mode (larger steps)

⚙️ Configuration

Core

Config.Debug             = false      -- verbose console + debug spheres
Config.RenderDistance    = 30.0       -- metres — entity spawns/despawns at this range
Config.ProximityCheckRate = 2000      -- ms between proximity checks
Config.GazeCheckRate     = 100        -- ms between gaze raycasts
Config.GazeDistance      = 4.0        -- metres — max range for name display
Config.PickupRange       = 2.5        -- metres — max range for ox_target options
Config.StatebagPrefix    = 'pi_item_' -- key prefix for server statebags
Config.DefaultRespawnDelay = 60       -- seconds — delay before permanent-respawn items re-appear

Admin Groups

Config.AdminGroups = { 'god', 'owner', 'admin', 'superadmin', 'moderator', 'mod', 'staff' }

Adding a Placeable Item

Config.PlaceableItems['your_item_name'] = {
    label         = 'My Item',
    model         = 'prop_some_model',  -- GTA V prop model name
    category      = 'item',             -- 'weapon' | 'item' | 'prop'
    isWallAllowed = false,              -- true = wall mode available during placement
    wallRotation  = vector3(0.0, 0.0, 0.0),
    floorRotation = vector3(0.0, 0.0, 0.0),
    wallOffset    = 0.0,                -- metres — how far from wall surface
    weight        = 500,
    stack         = false,
}

Then add the export to your ox_inventory items:

['your_item_name'] = {
    label  = 'My Item',
    weight = 500,
    stack  = false,
    close  = true,
    client = { export = 'rde_placeable_items.use_your_item_name' },
},

Prop model names: forge.plebmasters.de/objects

All 50+ pre-configured weapon entries are in data/ox_inventory_items.lua — ready to copy.

🛡️ Admin System

Admin access is verified against ox_core groups listed in Config.AdminGroups.

Admins have access to:

All target options on every placed item (Pick Up, Toggle Permanent Respawn, Delete) — regardless of ownership
/placedmenu — full CRUD panel: list all placed items, teleport to any, delete, toggle respawn
/placedstats — quick count of total items in DB

# server.cfg
add_ace group.admin rde_placeable_items.admin allow
add_principal identifier.steam:110000xxxxxxxx group.admin

📋 Commands

Command	Who	Description
`F3` (keybind)	Player	Place / equip equipped weapon
`/placedmenu`	Admin	Open CRUD panel — list, teleport, delete, toggle respawn
`/piamenu`	Admin	Alias for `/placedmenu`
`/placedstats`	Admin	Show total placed item count in chat

The F3 keybind is registered via lib.addKeybind — players can rebind it in their FiveM settings.

🗄️ Database

Table rde_placed_items is created automatically on first resource start.

Column	Type	Description
`id`	INT AUTO_INCREMENT	Unique item ID (used as statebag key prefix)
`item_name`	VARCHAR	ox_inventory item name
`item_label`	VARCHAR	Display label
`item_metadata`	TEXT	Full JSON metadata blob
`pos_x/y/z`	FLOAT	World position
`rot_x/y/z`	FLOAT	World rotation
`collision`	TINYINT	Collision enabled flag
`owner_id`	INT	ox_core character ID of placer
`permanent_respawn`	TINYINT	Respawn after pickup flag
`created_at`	TIMESTAMP	Creation time

⚠️ Known Limitations

Visual: Weapon Components After Server Restart

What happens: After a server restart and player rejoin, weapon attachment components (extended clip, suppressor, scope) may not visually appear on the weapon object for the first 1–2 seconds. They appear correctly once world asset streaming completes.

Root cause: GTA V's GiveWeaponComponentToWeaponObject requires the full asset streaming pipeline to be active. During the post-join fade-in phase the engine accepts the call without error but doesn't visually update the model. State.ready is now gated behind IsScreenFadedIn() + 1.5s buffer, which resolves the issue in most cases.

What always works correctly: All metadata (ammo, tint, components, serial) is preserved in the database and fully restored on pickup regardless of visual state.

Visual: VARMOD Skin Components

What happens: Weapon skin variants using COMPONENT_*_VARMOD_* (e.g. Pearl Weapon Kit → COMPONENT_PISTOL50_VARMOD_LUXE) do not render visually on weapon objects. The skin is stored and restored correctly on pickup.

Root cause: GTA V engine limitation — GiveWeaponComponentToWeaponObject does not apply VARMOD livery/texture components to world weapon objects. This affects all FiveM resources using this native, not specific to this script.

Workaround: None at engine level. If this is resolved in a future FiveM/GTA V update, the code already calls the correct native with pre-filtered valid hashes — it will work automatically.

📊 Performance

This script is built to have zero idle overhead:

Proximity check — single distance loop every 2000ms. No per-frame work when no players are near items.
Gaze raycast — every 100ms, short ray, flag 6. Wait(0) draw loop only activates when an item is actively gazed at.
Entities — client-side only, non-networked. No sync overhead.
Weapon assets — RequestWeaponAsset(hash, 31, 31) on spawn, released after creation via SetWeaponAssetAsNoLongerNeeded.
Component filter — DoesWeaponTakeWeaponComponent pre-filters all hashes before GiveWeaponComponentToWeaponObject. Invalid hashes from multi-weapon component items (e.g. extended pistol clip) are discarded — prevents visual state corruption.
ox_target zones — addSphereZone radius 0.3m (entity-tight). Adjacent wall-mounted weapons never produce overlapping target menus.

🐛 Troubleshooting

F3 opens context menu but placing does nothing
Make sure the item's client.export in ox_inventory items.lua matches the pattern rde_placeable_items.use_ITEMNAME. The export name must be uppercase for weapon items to match GTA V's weapon hash format.

Item placed but invisible after restart
This is the known streaming timing issue — wait 2 seconds after spawning in. If it persists indefinitely, check server console for [RDE | PlaceItems] errors on startup.

Weapon comes back without ammo
Ammo is restored via TriggerClientEvent('rde_pi:restoreAmmo') after AddItem. If the player doesn't have the weapon equipped immediately after pickup this is normal — equip it and the ammo will be at the correct count.

"You don't own this item" when trying to pick up
Only the original placer or an admin can pick up an item. If a different character placed it, use admin Delete + re-place, or have an admin Pick Up for them.

ox_target menu not appearing
Confirm ox_target is running and that Config.PickupRange is not set to 0. Target zones use addSphereZone with 0.3m radius — you need to be within roughly 2–3 metres.

Components not showing after restart (waited >5 seconds)
Enable Config.Debug = true and check F8 after rejoining. The [RDE_PI] logs will show whether HasWeaponAssetLoaded succeeded and whether GiveWeaponComponentToWeaponObject was called. If you are on FiveM Canary, see Known Limitations.

Admin commands not working
Verify the character's ox_core group is listed in Config.AdminGroups exactly (case-sensitive). Restart the resource after changing groups.

📝 Changelog

V1.0.0 Alpha — Initial Release (Current)

Core Features:

✅ Wall-mount and floor-place any ox_inventory weapon or prop item
✅ Full metadata preservation — ammo (live game-state), tint (live game-state), components, serial, durability, registered owner
✅ 50+ GTA V weapons pre-configured in data/ox_inventory_items.lua
✅ F3 keybind — Equip / Place context menu (non-destructive to existing equip flow)
✅ Live ghost preview with components and tint during placement
✅ Full placement controls: wall mode, rotation, tilt, height, fast mode
✅ Proximity loading — entities spawn/despawn at Config.RenderDistance
✅ Gaze-based 3D weapon name display — 100ms raycast, zero idle cost
✅ IsScreenFadedIn() gate — entities only spawn after world streaming is ready
✅ Permanent Respawn — admin toggle, configurable delay, TSRP weapon rack support
✅ ox_target integration — 0.3m entity-tight sphere zones, no overlap
✅ Admin CRUD panel — /placedmenu, teleport, delete, toggle respawn
✅ DB persistence — rde_placed_items table auto-created on first start
✅ DoesWeaponTakeWeaponComponent hash filtering — only valid component hashes applied per weapon, prevents visual state corruption from multi-weapon component items
✅ RequestWeaponAsset(hash, 31, 31) — full component variation asset load before weapon object creation

Known Limitations in this release:

⚠️ VARMOD skin components (e.g. Pearl Weapon Kit) do not visually render on world weapon objects — GTA V engine limitation. Metadata preserved and restored on pickup.
⚠️ Visual components may take 1–2 seconds to appear after fresh join on some configurations

📜 License

###################################################################################
#                                                                                 #
#      .:: RED DRAGON ELITE (RDE)  -  BLACK FLAG SOURCE LICENSE v6.66 ::.         #
#                                                                                 #
#   PROJECT:    RDE PLACEABLE ITEMS V1.0.0 ALPHA                                  #
#   ARCHITECT:  .:: RDE ⧌ Shin [△ ᛋᛅᚱᛒᛅᚾᛏᛋ ᛒᛁᛏᛅ ▽] ::. | https://rd-elite.com     #
#   ORIGIN:     https://github.com/RedDragonElite                                 #
#                                                                                 #
#   WARNING: THIS CODE IS PROTECTED BY DIGITAL VOODOO AND PURE HATRED FOR LEAKERS #
#                                                                                 #
#   [ THE RULES OF THE GAME ]                                                     #
#                                                                                 #
#   1. // THE "FUCK GREED" PROTOCOL (FREE USE)                                    #
#      You are free to use, edit, and abuse this code on your server.             #
#      Learn from it. Break it. Fix it. That is the hacker way.                   #
#      Cost: 0.00€. If you paid for this, you got scammed by a rat.               #
#                                                                                 #
#   2. // THE TEBEX KILL SWITCH (COMMERCIAL SUICIDE)                              #
#      If I find this script on Tebex, Patreon, or in a paid "Premium Pack":      #
#      > I will DMCA your store into oblivion.                                    #
#      > I will publicly shame your community.                                    #
#      > I hope your server lag spikes to 9999ms every time you blink.            #
#      SELLING FREE WORK IS THEFT. AND I AM THE JUDGE.                            #
#                                                                                 #
#   3. // THE CREDIT OATH                                                         #
#      Keep this header. If you remove my name, you admit you have no skill.      #
#      You can add "Edited by [YourName]", but never erase the original creator.  #
#      Don't be a skid. Respect the architecture.                                 #
#                                                                                 #
#   4. // THE CURSE OF THE COPY-PASTE                                             #
#      This code uses StateBags, ox_inventory metadata, and layered native calls. #
#      If you just copy-paste without reading, it WILL break.                     #
#      Don't come crying to my DMs. RTFM or learn to code.                        #
#                                                                                 #
#   --------------------------------------------------------------------------    #
#   "We build the future on the graves of paid resources."                        #
#   "REJECT MODERN MEDIOCRITY. EMBRACE RDE SUPERIORITY."                          #
#   --------------------------------------------------------------------------    #
###################################################################################

TL;DR:

✅ Free forever — use it, edit it, learn from it
✅ Keep the header — credit where it's due
❌ Don't sell it — commercial use = instant DMCA
❌ Don't be a skid — copy-paste without reading won't work anyway

🌐 Community & Support


🐙 GitHub	RedDragonElite
🌍 Website	rd-elite.com
🔵 Nostr (RDE)	RedDragonElite
🔵 Nostr (Shin)	SerpentsByte
🏪 RDE Shops	rde_shops
🚪 RDE Doors	rde_doors
🚗 RDE Car Service	rde_carservice
🔧 RDE Mechanic	rde_mechanic

When asking for help, always include:

Full error from server console or F8
Your server.cfg resource start order
ox_core / ox_lib / ox_inventory / ox_target versions in use
FiveM build number (top-right corner in-game)

"We build the future on the graves of paid resources."

REJECT MODERN MEDIOCRITY. EMBRACE RDE SUPERIORITY.

🐉 Made with 🔥 by Red Dragon Elite

⬆ Back to Top

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
client		client
data		data
server		server
README.md		README.md
config.lua		config.lua
fxmanifest.lua		fxmanifest.lua

Folders and files

Latest commit

History

Repository files navigation

📌 RDE Placeable Items — V1.0.0 Alpha

📖 Table of Contents

🎯 Overview

Why RDE Placeable Items?

✨ Features

📌 Placement System

💾 Metadata Preservation

🔁 Persistent Storage

👁️ Proximity & Gaze

🎯 ox_target Integration

📦 Dependencies

🚀 Installation

1. Clone the repository

2. Add to server.cfg

3. Register items in ox_inventory

4. Database

5. Restart and place your first weapon

🕹️ Placement Controls

⚙️ Configuration

Core

Admin Groups

Adding a Placeable Item

🛡️ Admin System

📋 Commands

🗄️ Database

⚠️ Known Limitations

Visual: Weapon Components After Server Restart

Visual: VARMOD Skin Components

📊 Performance

🐛 Troubleshooting

📝 Changelog

V1.0.0 Alpha — Initial Release (Current)

📜 License

🌐 Community & Support

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

2. Add to `server.cfg`

Packages