troubleshooting

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.

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.

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

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

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

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

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)

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

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)

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

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.