Discord

How It Works

System Architecture

The GOD - Nail Trap System operates through a client-server architecture that ensures synchronized nail placement and damage detection across all players.

Core Mechanics

1. Nail Deployment

Single Nail (screw_nail)

When a player uses a single nail item:

On Foot:

  • Player performs a planting animation

  • Progress bar displays: "Planting Nails On Ground...."

  • Nail is placed directly at player's current position

  • Item is consumed from inventory

In Vehicle:

  • Player performs a throwing animation

  • Progress bar displays: "Throwing Nails On Ground...."

  • Nail is spawned forward from player's position based on heading

  • Perfect for pursuits: Illegal players can throw nails out the window while driving to disable pursuing police vehicles

  • Nails land behind the throwing vehicle, ready to puncture tires of following vehicles

  • Item is consumed from inventory

Nail Package (nailspackage)

When a player uses a nail package:

  • Interactive mode activates with on-screen instructions

  • Player can press E (INPUT_CONTEXT) to place nails repeatedly

  • Maximum of 20 nails can be placed per package

  • Each placement uses a placement animation

  • Player can cancel with BACKSPACE (INPUT_CELLPHONE_CANCEL)

  • Package is consumed after completion or cancellation

2. Nail Synchronization

Server-Side:

  • All nail positions are stored in a server-side table (nails)

  • Each nail receives a unique ID based on table length

  • When a nail is placed, all clients receive synchronization event

  • When a nail is removed, all clients are notified

Client-Side:

  • Clients maintain a local table of nail objects

  • On player load, client requests current nail positions from server

  • Nail objects are created using a custom prop model

  • Objects are frozen in place after physics activation

3. Nail Object Creation

When a nail is synchronized to a client:

  1. Object Creation: Custom prop model is spawned at coordinates

  2. Physics Activation: Entity physics are activated for proper placement

  3. Ground Alignment: Object is properly aligned with the ground surface

  4. Freezing: Object is frozen after a short delay to prevent movement

  5. Targeting: Interaction option is added for nail removal

  6. Cleanup Timer: Automatic removal timer starts (configurable duration)

4. Tire Damage Detection

The system continuously monitors vehicles for nail contact:

Detection Loop:

  • Runs while player is in a vehicle seat

  • Checks all nails within 10 units of vehicle

  • For each nail, checks all 6 wheel positions:

    • wheel_lf (Left Front) - Index 0

    • wheel_rf (Right Front) - Index 1

    • wheel_lm (Left Middle) - Index 2

    • wheel_rm (Right Middle) - Index 3

    • wheel_lr (Left Rear) - Index 4

    • wheel_rr (Right Rear) - Index 5

Damage Calculation:

  • Distance threshold: 0.5 units between tire bone and nail position

  • Damage is tracked per vehicle plate and tire index

  • Each nail contact adds DamagePerNail percentage (default: 33.335%)

  • When damage reaches 100%, tire bursts instantly

  • Nail is deleted upon contact to prevent multiple hits

Damage Tracking:

  • Vehicle damage is stored per plate number

  • Prevents same nail from damaging tire multiple times

  • Resets when vehicle is destroyed or player leaves

5. Nail Removal

Players can remove deployed nails:

  • Targeting Interaction: "Remove Nails" option appears when targeting nail

  • Animation: Planting animation plays during removal

  • Progress Bar: "Taking Out Nails From Ground...." displays

  • Item Return: Player receives screw_nail item back

  • Synchronization: All clients are notified of removal

6. Automatic Cleanup

Timer-Based Removal:

  • Each nail has an automatic cleanup timer

  • Default duration: 10 minutes (configurable in J0.NailsCfg.CleanUp)

  • Timer starts when nail is created

  • On expiration: nail object is deleted and server is notified

  • Prevents server memory buildup from abandoned nails

Resource Stop Cleanup:

  • When resource stops, all client-side nail objects are deleted

  • Prevents orphaned objects in the game world

Framework Integration

QBCore / Qbox

  • Uses qb-core exports for core object

  • CreateUseableItem for item usage registration

  • Functions.Notify for notifications

  • Functions.AddItem / Functions.RemoveItem for inventory

ESX

  • Uses es_extended exports for core object

  • lib.notify for notifications (via ox_lib)

  • Custom inventory functions via server events

Inventory Integration

ox_inventory

  • Uses export functions: exports.ox_inventory:AddItem / RemoveItem

  • Client-side export: J0-nailScript.useNail / useNailPackage

  • Item configuration in data/items.lua

qb-inventory

  • Uses framework functions: Functions.AddItem / RemoveItem

  • Server-side useable item registration

  • Item configuration in shared/items.lua

Targeting Integration

ox_target

  • exports.ox_target:addLocalEntity() for nail interaction

  • exports.ox_target:removeLocalEntity() for cleanup

qb-target

  • exports['qb-target']:AddTargetEntity() for interaction

  • exports['qb-target']:RemoveTargetEntity() for cleanup

interact

  • exports.interact:AddLocalEntityInteraction() for interaction

  • exports.interact:RemoveLocalEntityInteraction() for cleanup

Pursuit Escape Mechanics

Vehicle-Based Nail Deployment

One of the most exciting features for illegal roleplay is the ability to throw nails from a moving vehicle:

How It Works:

  1. Detection: System detects when player is inside a vehicle

  2. Throwing Animation: Player performs throwing animation

  3. Forward Placement: Nail is calculated forward from player's position based on vehicle heading

  4. Landing: Nail lands on the road surface behind the throwing vehicle

  5. Pursuit Defense: Any vehicle following behind (police, rivals, etc.) will drive over the nail

  6. Tire Damage: When pursuing vehicle's wheels contact the nail, progressive damage is applied

Strategic Use:

  • Illegal Players: Perfect for escaping police chases by disabling pursuing vehicles

  • High-Speed Chases: Throw nails while maintaining speed to create distance

  • Multiple Pursuers: Deploy multiple nails to disable multiple pursuing vehicles

  • Tactical Placement: Time your throws to maximize effectiveness

Mechanics:

  • Nail spawns based on vehicle's current heading (direction of travel)

  • Forward offset ensures nail lands behind the vehicle

  • Physics-based placement ensures nail stays on road surface

  • Works at any speed - nail placement is instant

Performance Optimization

  • Efficient Loops: Damage detection uses optimized distance checks

  • Conditional Updates: Only processes nails within range (10 units)

  • Memory Management: Automatic cleanup prevents object accumulation

  • Network Optimization: Minimal server events, efficient synchronization

  • Collision Optimization: Precise distance thresholds (0.5 units)

Technical Specifications

  • Update Rate: Damage detection runs at optimized intervals while in vehicle

  • Sync Range: Configurable radius for damage detection

  • Contact Threshold: Precise distance threshold for tire-to-nail contact

  • Forward Distance: Calculated forward offset for vehicle nail throwing

  • Physics Delay: Short delay before freezing nail object for proper placement

This system provides a realistic and performant solution for road spike deployment in FiveM roleplay servers.

PreviousGOD - Nail Trap SystemNextInstallation Guide: Nail Trap System

Last updated