SUMMER STARTS WITH 10% OFF | CODE: SUMMER10 SUMMER STARTS WITH 10% OFF | CODE: SUMMER10 SUMMER STARTS WITH 10% OFF | CODE: SUMMER10 SUMMER STARTS WITH 10% OFF | CODE: SUMMER10 SUMMER STARTS WITH 10% OFF | CODE: SUMMER10 SUMMER STARTS WITH 10% OFF | CODE: SUMMER10

Surf Activity Documentation

This guide explains how to install and configure Tdev Surfing for your FiveM server.

Compatibility

  • ESX Legacy
  • QBCore
  • Qbox
  • ox_inventory

Requirements

  • ESX Legacy, QBCore, Qbox, or ox_inventory
  • Framework resource if you use a framework mode
  • OneSync required for stable networked board entities
  • ox_lib optional for modern notifications
  • ox_inventory optional for item-based usage
  • Custom surfing animation included in the stream folder

Installation

  • Download the resource from your Tebex purchases.
  • Extract the folder.
  • Place the tdev_surfing folder inside your server resources folder.
  • Start your framework before the resource.
  • Start ox_inventory before the resource if you use ox_inventory.
  • Start ox_lib before the resource if you want ox_lib notifications.
  • Make sure stream/tdev@surfing.ycd stays inside the stream folder.
  • Open the config.lua file.
  • Select your framework or leave it on auto detection.
  • Select your inventory mode or leave it on auto detection.
  • Add the surfing_board item to your inventory system.
  • Configure the board model, carry position, water placement, controls, animations, movement, and safety settings.
  • Add the resource to your server.cfg.
  • Restart your server or run refresh followed by ensure tdev_surfing.
  • Give yourself the surfing_board item and test carrying, dropping, mounting, stance switching, exiting, cleanup, and item return.

Server CFG Example

ESX Example:

ensure es_extended

ensure ox_lib

ensure ox_inventory

ensure tdev_surfing

QBCore Example:

ensure qb-core

ensure ox_lib

ensure ox_inventory

ensure tdev_surfing

Qbox Example:

ensure qbx_core

ensure ox_lib

ensure ox_inventory

ensure tdev_surfing

Configuration

  • Set Config.Framework to auto, esx, qb, qbox, or standalone.
  • Set Config.Inventory to auto, framework, or ox_inventory.
  • Configure Config.Items.board if you want to rename the surfing_board item.
  • Configure Config.Commands for recovery, reset, and optional testing command names.
  • Configure Config.Controls for drop, mount, exit, stance switch, pickup, movement, and steering keys.
  • Configure Config.Carry for the surfboard model, back bone, carry offset, and carry rotation.
  • Keep Config.Carry.anim.enabled disabled if you want the player to walk normally with the board on their back.
  • Configure Config.Drop for water placement distance, water height offset, and water detection behavior.
  • Configure Config.Board for board model, hidden movement vehicle, enter distance, pickup distance, speed, steering, and stance transition behavior.
  • Configure Config.Animation for crawling/prone animation, paddle animation, standing surfing animation, and fallbacks.
  • Configure Config.Safety for cooldowns, maximum board distance, death cleanup, board missing cleanup, and production anti-abuse settings.

Item Setup

  • ox_inventory users should copy install/ox_inventory_items.lua into ox_inventory/data/items.lua.
  • QBCore users should copy install/qb-core_items.lua into qb-core/shared/items.lua.
  • Qbox users should use the ox_inventory item snippet or install/qbox_items.lua.
  • ESX users should run install/esx_items.sql.
  • The default item name is surfing_board.
  • The item is removed server-side only when the board is dropped over water.
  • The item is returned server-side when the player exits, picks up, resets, disconnects, dies, or cleanup is triggered.

Surfing System

  • Players use the surfing_board item from their inventory.
  • The player carries the surfboard on their back and can walk normally.
  • Players press Y to drop the board over water.
  • Players press F near the board to get on it.
  • The board supports two riding positions: crawling/prone and standing.
  • Players press E while mounted to switch between crawling/prone and standing.
  • Players use W/S for forward and reverse movement.
  • Players use A/D to steer the board.
  • Players press X while mounted to exit the board.
  • The surfing_board item automatically returns to the player inventory after exiting.
  • Players can use /surfingrecover if the item could not be returned because their inventory was full.
  • Players can use /surfingreset to force clean their active surfing session.

Custom Props and Animations

  • The resource uses GTA surfboard props by default.
  • The resource includes a custom streamed standing surfing animation.
  • Keep stream/tdev@surfing.ycd inside the stream folder.
  • Do not rename tdev@surfing.ycd unless you also update fxmanifest.lua and config.lua.
  • Do not rename board models unless you also update Config.Carry.model and Config.Board.model.
  • Fully restart the resource after changing streamed models or animation dictionaries.

Security

  • Do not move item remove or item return logic client-side.
  • Do not trust client-side inventory state.
  • Keep item usage, item removal, item return, recovery, and cleanup server-side.
  • Keep Config.Safety.actionCooldownMs enabled on production servers.
  • Keep Config.Safety.serverMaxDropDistance enabled on production servers.
  • Keep Config.Safety.forceReturnOnDeath enabled on production servers.
  • Keep Config.Safety.forceReturnWhenBoardMissing enabled on production servers.
  • Keep Config.Safety.cleanupPendingItemsOnResourceStop enabled on production servers.
  • Back up config.lua before updating the resource.

Anticheat Whitelist

If your anticheat blocks custom resource events, whitelist the Tdev Surfing events from the README.

Important server events include tdev_surfing:server:tryUseBoard, tdev_surfing:server:cancelCarry, tdev_surfing:server:tryDropBoard, tdev_surfing:server:returnBoard, and tdev_surfing:server:forceCleanup.

Important client events include tdev_surfing:client:notify, tdev_surfing:client:useBoard, tdev_surfing:client:carryApproved, tdev_surfing:client:boardApproved, and tdev_surfing:client:forceCleanup.

Common Issues

Item does nothing: Check that the surfing_board item exists, is marked usable, and that tdev_surfing starts after your framework or inventory.

ox_inventory item does nothing: Check that the item has client export tdev_surfing.useSurfingBoard and restart ox_inventory after editing items.lua.

Board does not drop: Make sure the player is standing over valid water and press Y while carrying the board.

Board does not appear: Check that the board model exists, OneSync is enabled, and there are no F8 errors.

Player cannot get on the board: Stand closer to the board and press F. You can increase Config.Board.enterDistance if needed.

Standing animation does not play: Check stream/tdev@surfing.ycd, Config.Animation.standing.dict, Config.Animation.standing.idle, and the fxmanifest.lua ANIM_DICT entry.

Player does not walk normally while carrying: Make sure Config.Carry.anim.enabled is false and Config.Carry.disableControls is false.

Board item does not return: Check inventory weight/slots. Free space and use /surfingrecover.

Framework detection is wrong: Set Config.Framework manually to esx, qb, or qbox.

Inventory detection is wrong: Set Config.Inventory manually to framework or ox_inventory.

Support

If you need help, open a support ticket in the Tdev Scripts Discord.

Provide your order ID, script name, framework, inventory, full F8 error, server console error, and a screenshot or video.

Support is only available for verified customers.

Support is not provided for leaked, resold, or heavily modified versions.

Discord: https://discord.gg/5MYzXemM4q