troubleshooting

Resource won't start / infinite hang

Symptom: Console shows WARNING: Resource name is changed!

Fix: Rename the folder to exactly s4-wheeldamage. The script blocks execution if the resource name differs.

Crash damage not triggering

Check:

1. Config.EnableMinCrashSpeed — Is your crash speed above Config.MinCrashSpeed (default 5.0 m/s)?

2. Config.Ignore — Is your vehicle class or model in the ignore list?

3. Config.HitIgnore — Is the raycast hitting a ped instead of a wall/object?

4. Config.DetectionTimeForNextCrash — Wait 1 second between consecutive crashes.

Debug: Set Config.TestMode = true to see 3D rays, speed, and surface material at each indicator point.

Wheels don't break off

Check:

1. Impact speed must be ≥ 21.0 m/s (Config.DamageLevels[2].min)

2. The wheel indicator ray must hit something (endCoords not zero)

3. Config.OldVersion = false uses BreakOffVehicleWheel (recommended)

4. If Config.OldVersion = true, uses legacy tire collider method

Toolbox won't place

Check:

1. You must be on foot (not inside a vehicle)

2. Only one toolbox can be active at a time

3. repair_toolbox item must be registered and usable via s4-bridge

4. Check F8 console for model load errors

Repair tools say "toolbox in use"

Another repair workflow is already active. Either:

• Complete the current repair

• Press X to cancel

• Target the toolbox and select Cancel

• Restart the resource as last resort

Hood/trunk target not working

Check:

1. Is qb-target installed? Target options require it.

2. Is the vehicle locked? canInteract checks GetVehicleDoorLockStatus(entity) ~= 2

3. For engine/radiator repair, hood must be open first

4. For fuel tank repair, trunk must be open first

Mechanic repair doesn't clear wheel damage

Check:

1. Config.EnableCompatible = true

2. Your mechanic script's event name is in compatible.lua

3. If using custom repair, call the export manually:

exports['s4-wheeldamage']:FullyRepairVehicle(vehicle)

Land restriction not applying

Check:

1. Config.EnableLandRestriction = true

2. landData.json exists and has data for your vehicle class

3. Run /editLandRes to verify settings

4. Speed limit of 0 means no limit for that surface

Notifications not showing

The script uses ox_lib notify via the 0r-core:notif event. Ensure:

1. ox_lib is started before s4-wheeldamage

2. @ox_lib/init.lua is loaded (defined in fxmanifest.lua)

Server sync issues

Damaged wheel state is stored in the Cars table and synced via syncCars server event.

If wheels appear fine for one player but broken for another:

1. Check server console for errors in server/server.lua

2. Ensure s4-bridge framework callbacks work (getSyncCars)

3. Restart the resource to clear stale state

Config.TireItem error

If you see errors about Config.TireItem being nil when repairing wheels:

Add to config.lua:

Config.TireItem = "repair_tire"

And register the item in your inventory. This is only needed when wheel repair consumes a standalone tire item from inventory.