# Introduction Official documentation for BOII | Development resources and projects.\ This site is a work in progress — some content may be incomplete or subject to change.\ If you spot any issues or missing info, let us know on [**Discord**](https://discord.gg/MUckUyS5Kq). ## Stay Connected To keep up with everything BOII, make sure to join our [**Discord**](https://discord.gg/MUckUyS5Kq).\ For support requests, please note our hours below. **Support Hours:**\ Our support server is active **Monday to Friday, from 10am to 10pm GMT**.\ We aim to respond within 1 business day, though in rare cases it may take up to five. \ We're human too — thanks for your patience. *** ## Our Team BOII Development is currently a one-person operation — from code to documentation.\ Despite being solo, every effort goes into delivering clean, reliable, and production-ready tools.\ If you find the work useful, support is always appreciated.
https://github.com/CaseIRLhttps://ko-fi.com/case/files/ohFhEqGiCN3mAZN8qQ4Mhttps://github.com/CaseIRL
*** ## Support BOII Development Many BOII Development resources are released for **free** on [**GitHub**](https://github.com/boiidevelopment). \ These take **significant** time to create, maintain, and support if you’d like to show appreciation, you can support us through the options below.
Ko-Fi/files/VZ3zGooY8vmlXgegUbmehttps://ko-fi.com/boiidevelopment
Buy Me A Coffee/files/Nn8derPohnfb0R5OsNKjhttps://coff.ee/boiidevelopment
*** ## Tebex Creator Codes We partner with trusted creators through **Tebex Creator Codes** — a system that shares a small portion of purchases between creators. If you're buying from a BOII partner, using our creator code gives us a small cut **and** gives you a discount. You can apply creator codes during checkout on Tebex under **"Support A Creator."**
LUSTY94 SCRIPTSCode: boii10
Discount: 10%		Discount: 10%/files/nKCnGDaUO4SVd8UfrTyB
OOSAYEROO SCRIPTSCode: boii10
Discount: 10%		Discount 10%/files/suib98S409uiNdXIQAB4
# BDTK {% hint style="danger" %} **THIS SECTION IS A WORK IN PROGRESS BDTK WILL REPLACE BOII\_UTILS EVENTUALY.**\ **EVERYTHING WILL BE DOCUMENTED FIRST.** {% endhint %}
*** ## What is BDTK? Normally? **BOII Development Tool Kit**\ When it works? **Big Damn Time-saving Kit**\ When it doesn’t? **Broken Dumbass Time Killer** BDTK is the next evolution of `boii_utils` - rewritten, reorganized, and refined for modern FiveM scripting. It’s still modular, still framework-agnostic, but now with tighter internals, smarter structure, and a more focused set of tools. From framework bridging to utility wrappers, animation helpers to UI fallbacks - it’s built to slot into any dev stack and cut the busywork out of your workflow. No bloat. No gatekeeping. No nonsense.\ Just dependable functions, clean patterns, and a codebase that stays out of your way. *** ## Who Is It For? * **Framework developers** who need clean, reusable utility modules for base functionality. * **Script authors** who want their releases to support multiple frameworks with minimal effort. * **Solo scripters** tired of rewriting the same junk over and over again. * **Teams** looking for a shared library of tools to streamline development across projects. Whether you're writing scripts or an entire framework, BDTK helps cut the fat and scale the logic. *** ## Why Should I Use It? * **Framework Bridge** – Built to abstract and unify major frameworks (`qb`, `esx`, `ox`, `nd`, `boii`, etc.) so you don’t have to write double logic. * **Modular by Default** – Use only what you need. Every module is isolated, with no hard dependencies on the rest. * **Less Repetition** – Handles the common patterns and boring parts so you can focus on actual logic, not boilerplate. * **Consistent Conventions** – Shared structure and naming across modules keeps your code clean and predictable. * **Dev Time Saver** – Speeds up development with drop-in systems, helper functions, and sane defaults. *** ## What Does It Provide? BDTK is split into multiple categories of modules: #### Resource Bridges * **Framework Bridge** - Currently compatible with ESX, QB-Core, QBox, Ox Core, or ND Core. * **Notification Bridge** - Currently compatible with bduk, boii\_ui, es\_extended, okokNotify, ox\_lib, qb-core. * **DrawText UI Bridge** - Currently compatible with boii\_ui, es\_extended, okokNotify, ox\_lib, qb-core. #### Standalone Systems * **Callbacks** - Full client/server callback handling without framework dependencies. * **Commands** - Built-in permissions, Ace support, and command registration. * **Licences** - Theory/practical tests, points, revoking—DMV-style, but smarter. * **XP System** - Custom growth curves, XP types, and server-wide level tracking. #### Utility Modules * **Appearance** - Appearance, clothing, tattoos, and shared styling logic. * **Vehicles** - Entity-safe functions for customization, storage, and behavior. * **Items** - Usable item registry outside of any core system. * **Methods** - Attach runtime functions to players, vehicles, or anything else. * **Player Helpers** - Animations, props, directions, and ped-related helpers. * **Timestamps** - Server-safe date/time utils for consistent formatting. * **Environment** - Time, weather, seasonal effects, and sync helpers. * **Entities** - Utility functions for managing NPCs, vehicles, and objects. * **Profanity** - Handles profanity related filtering and replacing. * Buckets - Routing bucket handling and static data storage. #### Smart Libraries * **Geometry** - Vector math, angles, zones, distance, and shape logic. * **Maths** - Extended math with curves, clamping, interpolation, and more. * **Strings** - Pad, slugify, wrap, and format anything text-based. * **Tables** - Merge, clone, randomize, and clean up Lua tables. * **Keys** - Named constants for all common input keys, with helpers. *** ## How Is It Structured? Every module in BDTK is fully self-contained — no tangled dependencies, no weird global hacks.\ They’re designed to be loaded individually or accessed cleanly through the central `bdtk.get()` system. BDTK is: * **Bridge-Based** – Framework functions are abstracted and unified behind a common API. * **Environment-Aware** – Modules work on the client, server, or both depending on context. * **Drop-In Ready** – Use one module or all of them. It won’t break if you don’t use the full set. * **Scalable by Design** – Built to grow with your project without becoming a mess. *** ## Quick Install To get setup using **BDTK** follow these brief steps: {% stepper %} {% step %} **Download BDTK** Download the Latest Release of BDTK from GitHub. {% endstep %} {% step %} **Add It To Your Server** Drop `bdtk` into your server resources. {% endstep %} {% step %} #### Add It To Your Server Config Add `ensure bdtk` into your `server.cfg` make sure this line is **above** any resource requiring it. {% endstep %} {% step %} **Insert The SQL** Add the included `REQUIRED.sql` into your database, this is required for user accounts and some standalone systems. {% endstep %} {% step %} **Restart Your Server** Restart your server and BDTK will be up and running, all bridges run auto-detection and have safe fall backs if none of the supported resources are found. To change default configuration settings you can do this via `convars` for more on this read: **Configuring BDTK** {% endstep %} {% endstepper %} ***
Guides/files/mXGQlzqtxWDAWC63HwSh/pages/Z0V242UcuOSPwAiUTPfC
API Reference/files/lfc1oyGmqtwJalCePlXA/pages/lDrgX8pB2w41qtRbjGMA
# Guides # API # Bridges # Framework # Notifications # DrawText UI # Modules # Appearance ## Client ### get\_clothing\_and\_prop\_values Returns maximum values for clothing and prop UI sliders based on ped model. #### Parameters * sex: `string` #### Returns * `table` ```lua bdtk.get_clothing_and_prop_values(sex) ``` *** ### set\_ped\_appearance Applies genetics, hair, overlays, clothes, and tattoos to the player's ped. #### Parameters * player: `number` * data: `table` #### Returns * `void` ```lua bdtk.set_ped_appearance(player, data) ``` *** ### update\_ped\_appearance Updates the internal `ped_styles` table and re-applies the appearance. #### Parameters * sex: `string` * category: `string` * id: `string|nil` * value: `any` #### Returns * `void` ```lua bdtk.update_ped_appearance(sex, category, id, value) ``` *** ### change\_player\_ped Changes the player's model based on the given sex. #### Parameters * sex: `string` #### Returns * `void` ```lua bdtk.change_player_ped(sex) ``` *** ### appearance\_rotate\_ped Rotates the player's ped in a specific direction. #### Parameters * direction: `string` #### Returns * `void` ```lua bdtk.appearance_rotate_ped(direction) ``` *** ### load\_player\_appearance Loads and applies a full character model including clothing and features. #### Parameters * data: `table` #### Returns * `void` ```lua bdtk.load_player_appearance(data) ``` *** ## Shared ### get\_ped\_appearence Returns the current style data from `ped_styles` for a given sex. #### Parameters * sex: `string` #### Returns * `table` ```lua bdtk.get_ped_appearence(sex) ``` *** ### reset\_appearence\_styles Resets the internal `ped_styles` table to its default values. #### Returns * `void` ```lua bdtk.reset_appearence_styles() ``` # Buckets {% hint style="warning" %} **SERVER FUNCTIONS** {% endhint %} ## bucket\_list Stores bucket definitions for script use.\ If you need the full list for any reason you can access it this way. ```lua bdtk.bucket_list = { main = { label = "Main World", -- label for display bucket = 0, -- default bucket mode = "strict", -- https://docs.fivem.net/natives/?_0xA0F2201F population_enabled = false, -- https://docs.fivem.net/natives/?_0xCE51AC2C player_cap = false, -- false | number: If number players max players in bucket will be capped at value. staff_only = false, -- e.g. { "admin", "mod" } vip_only = false, -- e.g. 2 = VIP level 2 required spawn = vector4(-268.47, -956.98, 31.22, 208.54), -- spawn point respawn = vector4(341.28, -1396.83, 32.51, 48.78) -- respawn point } } ``` *** ## get\_bucket Returns the full bucket config for a given ID. #### Parameters * id: `string` #### Returns * `table | nil` ```lua bdtk.get_bucket(id) ``` *** ## get\_bucket\_by\_label Returns the bucket config matching a label. #### Parameters * label: `string` #### Returns * `table | nil` ```lua bdtk.get_bucket_by_label(label) ``` *** ## get\_bucket\_spawn Returns the spawn point for a bucket. #### Parameters * id: `string` #### Returns * `vector4 | nil` ```lua bdtk.get_bucket_spawn(id) ``` *** ## get\_bucket\_respawn Returns the respawn point for a bucket. #### Parameters * id: `string` #### Returns * `vector4 | nil` ```lua bdtk.get_bucket_respawn(id) ``` *** ## is\_bucket\_staff\_only Checks if a bucket is staff-only for a given role. #### Parameters * id: `string` * role: `string` #### Returns * `boolean` ```lua bdtk.is_bucket_staff_only(id, role) ``` *** ## is\_bucket\_vip\_only Checks if a bucket is VIP-only for a given level. #### Parameters * id: `string` * vip\_level: `number` #### Returns * `boolean` ```lua bdtk.is_bucket_vip_only(id, vip_level) ``` *** ## apply\_bucket\_settings Applies population and lockdown mode to all defined buckets. ```lua bdtk.apply_bucket_settings() ``` # Callbacks ## Server ### register\_callback Registers a server-side callback. #### Parameters * name: `string` * cb: `function` #### Returns * `void` ```lua bdtk.register_callback(name, cb) ``` *** ## Client ### trigger\_callback Triggers a server-side callback and handles the response. #### Parameters * name: `string` * data: `table` * cb: `function` #### Returns * `void` ```lua bdtk.trigger_callback(name, data, cb) ``` # Commands ## Server ### register\_command Registers a command with permission check and optional chat suggestions. #### Parameters * command: `string` * rank: `string|table|nil` * help: `string` * params: `table` * handler: `function` ```lua bdtk.register_command(command, rank, help, params, handler) ``` *** ## Client ### get\_command\_suggestions Requests command chat suggestions for users.\ These are the tooltips that display when typing commands. #### Returns * `table` ```lua bdtk.get_command_suggestions() ``` # Cooldowns {% hint style="warning" %} **SERVER FUNCTIONS** {% endhint %} ## add\_cooldown Adds a cooldown for a player or globally. #### Parameters * source: `number` * cooldown\_type: `string` * duration: `number` * is\_global: `boolean` ```lua bdtk.add_cooldown(source, cooldown_type, duration, is_global) ``` *** ## check\_cooldown Checks if a cooldown is active. #### Parameters * source: `number` * cooldown\_type: `string` * is\_global: `boolean` #### Returns * `boolean` ```lua bdtk.check_cooldown(source, cooldown_type, is_global) ``` *** ## clear\_cooldown Clears a specific cooldown. #### Parameters * source: `number` * cooldown\_type: `string` * is\_global: `boolean` ```lua bdtk.clear_cooldown(source, cooldown_type, is_global) ``` *** ## clear\_expired\_cooldowns Clears all expired cooldowns. ```lua bdtk.clear_expired_cooldowns() ``` *** ## clear\_resource\_cooldowns Clears all cooldowns for a given resource. #### Parameters * resource: `string` ```lua bdtk.clear_resource_cooldowns(resource) ``` # Debugging {% hint style="warning" %} **SHARED FUNCTIONS** {% endhint %} ## log Prints a formatted debug message to the console. #### parameters * level: `string` * message: `string` ```lua bdtk.log(level, message) ``` *** ## wait\_for Waits until a given function returns true or a timeout is reached. #### parameters * fn: `function` * timeout: `number|nil` * interval: `number|nil` #### returns * `boolean` ```lua bdtk.wait_for(fn, timeout, interval) ``` # Entities {% hint style="warning" %} **CLIENT FUNCTIONS** {% endhint %} ## get\_nearby\_entities Finds nearby entities based on pool and position. #### Parameters * pool: `string` * coords: `vector3` * max\_distance: `number` * filter: `function|nil` #### Returns * `table` ```lua bdtk.get_nearby_entities(pool, coords, max_distance, filter) ``` *** ## get\_nearby\_objects Returns nearby object entities. #### Parameters * coords: `vector3` * max\_distance: `number` #### Returns * `table` ```lua bdtk.get_nearby_objects(coords, max_distance) ``` *** ## get\_nearby\_peds Returns nearby peds, excluding players. #### Parameters * coords: `vector3` * max\_distance: `number` #### Returns * `table` ```lua bdtk.get_nearby_peds(coords, max_distance) ``` *** ## get\_nearby\_players Returns nearby players. #### Parameters * coords: `vector3` * max\_distance: `number` * include\_player: `boolean` #### Returns * `table` ```lua bdtk.get_nearby_players(coords, max_distance, include_player) ``` *** ## get\_nearby\_vehicles Returns nearby vehicles. #### Parameters * coords: `vector3` * max\_distance: `number` * include\_player\_vehicle: `boolean` #### Returns * `table` ```lua bdtk.get_nearby_vehicles(coords, max_distance, include_player_vehicle) ``` *** ## get\_closest\_object Gets the closest object entity. #### Parameters * coords: `vector3` * max\_distance: `number` #### Returns * `number`, `vector3` ```lua bdtkbdtk.get_closest_object(coords, max_distance) ``` *** ## get\_closest\_ped Gets the closest ped entity. #### Parameters * coords: `vector3` * max\_distance: `number` #### Returns * `number`, `vector3` ```lua bdtk.get_closest_ped(coords, max_distance) ``` *** ## get\_closest\_player Gets the closest player entity. #### Parameters * coords: `vector3` * max\_distance: `number` * include\_player: `boolean` #### Returns * `number`, `vector3` ```lua bdtk.get_closest_player(coords, max_distance, include_player) ``` *** ## get\_closest\_vehicle Gets the closest vehicle entity. #### Parameters * coords: `vector3` * max\_distance: `number` * include\_player\_vehicle: `boolean` #### Returns * `number`, `vector3` ```lua bdtk.get_closest_vehicle(coords, max_distance, include_player_vehicle) ``` *** ## get\_entities\_in\_front\_of\_player Returns the entity directly in front of the player. #### Parameters * fov: `number` * distance: `number` #### Returns * `number|nil` ```lua bdtk.get_entities_in_front_of_player(fov, distance) ``` *** ## get\_target\_ped Gets the ped in front of the player or the closest. #### Parameters * player\_ped: `number` * fov: `number` * distance: `number` #### Returns * `number`, `vector3` ```lua bdtk.get_target_ped(player_ped, fov, distance) ``` # Environment {% hint style="warning" %} **CLIENT FUNCTIONS** {% endhint %} ## get\_weather\_name Returns the weather name from a given hash. #### Parameters * hash: `number` #### Returns * `string` ```lua bdtk.get_weather_name(hash) ``` *** ## get\_game\_time Returns current game time and formatted version. #### Returns * `table` ```lua bdtk.get_game_time() ``` *** ## get\_game\_date Returns current game date and formatted version. #### Returns * `table` ```lua bdtk.get_game_date() ``` *** ## get\_sunrise\_sunset\_times Returns sunrise and sunset times for given weather. #### Parameters * weather: `string` #### Returns * `table` ```lua bdtk.get_sunrise_sunset_times(weather) ``` *** ## is\_daytime Checks if it is currently daytime. #### Returns * `boolean` ```lua bdtk.is_daytime() ``` *** ## is\_nighttime Checks if it is currently nighttime. #### Returns * `boolean` ```lua bdtk.is_nighttime() ``` *** ## is\_midday Checks if it is currently midday. #### Returns * `boolean` ```lua bdtk.is_midday() ``` *** ## get\_current\_season Returns current season. #### Returns * `string` ```lua bdtk.get_current_season() ``` *** ## get\_distance\_to\_water Returns distance from player to nearest water body. #### Returns * `number` ```lua bdtk.get_distance_to_water() ``` *** ## get\_zone\_scumminess Returns the zone scumminess level. #### Returns * `integer` ```lua bdtk.get_zone_scumminess() ``` *** ## get\_ground\_material Returns ground material hash at player's position. #### Returns * `number` ```lua bdtk.get_ground_material() ``` *** ## get\_wind\_direction Returns wind direction as a compass value. #### Returns * `string` ```lua bdtk.get_wind_direction() ``` *** ## get\_altitude Returns player's altitude above sea level. #### Returns * `number` ```lua bdtk.get_altitude() ``` *** ## get\_environment\_details Returns a summary of environmental data. #### Returns * `table` ```lua bdtk.get_environment_details() ``` # Geometry {% hint style="warning" %} **SHARED FUNCTIONS** {% endhint %} ## distance\_2d Calculates the distance between two 2D points. #### Parameters * p1: `table` * p2: `table` #### Returns * `number` ```lua bdtk.distance_2d(p1, p2) ``` *** ## distance\_3d Calculates the distance between two 3D points. #### Parameters * p1: `table` * p2: `table` #### Returns * `number` ```lua bdtk.distance_3d(p1, p2) ``` *** ## midpoint Returns the midpoint between two 3D points. #### Parameters * p1: `table` * p2: `table` #### Returns * `table` ```lua bdtk.midpoint(p1, p2) ``` *** ## is\_point\_in\_rect Determines if a point is inside a given 2D rectangle boundary. #### Parameters * point: `table` * rect: `table` #### Returns * `boolean` ```lua bdtk.is_point_in_rect(point, rect) ``` *** ## is\_point\_in\_box Determines if a point is inside a given 3D box boundary. #### Parameters * point: `table` * box: `table` #### Returns * `boolean` ```lua bdtk.is_point_in_box(point, box) ``` *** ## is\_point\_on\_line\_segment Determines if a point is on a line segment defined by two 2D points. #### Parameters * point: `table` * line\_start: `table` * line\_end: `table` #### Returns * `boolean` ```lua bdtk.is_point_on_line_segment(point, line_start, line_end) ``` *** ## project\_point\_on\_line Projects a point onto a line segment defined by two 2D points. #### Parameters * p: `table` * p1: `table` * p2: `table` #### Returns * `table` ```lua bdtk.project_point_on_line(p, p1, p2) ``` *** ## calculate\_slope Calculates the slope of a line given two 2D points. #### Parameters * p1: `table` * p2: `table` #### Returns * `number` ```lua bdtk.calculate_slope(p1, p2) ``` *** ## angle\_between\_points Returns the angle between two 2D points in degrees. #### Parameters * p1: `table` * p2: `table` #### Returns * `number` ```lua bdtk.angle_between_points(p1, p2) ``` *** ## angle\_between\_3\_points Calculates the angle between three 3D points (p1, p2 as center, p3). #### Parameters * p1: `table` * p2: `table` * p3: `table` #### Returns * `number` ```lua bdtk.angle_between_3_points(p1, p2, p3) ``` *** ## do\_circles\_intersect Determines if two circles defined by center and radius intersect. #### Parameters * c1\_center: `table` * c1\_radius: `number` * c2\_center: `table` * c2\_radius: `number` #### Returns * `boolean` ```lua bdtk.do_circles_intersect(c1_center, c1_radius, c2_center, c2_radius) ``` *** ## is\_point\_in\_circle Determines if a point is inside a circle defined by center and radius. #### Parameters * point: `table` * circle\_center: `table` * circle\_radius: `number` #### Returns * `boolean` ```lua bdtk.is_point_in_circle(point, circle_center, circle_radius) ``` *** ## do\_lines\_intersect Determines if two 2D line segments intersect. #### Parameters * l1\_start: `table` * l1\_end: `table` * l2\_start: `table` * l2\_end: `table` #### Returns * `boolean` ```lua bdtkbdtk.do_lines_intersect(l1_start, l1_end, l2_start, l2_end) ``` *** ## line\_intersects\_circle Determines if a line segment intersects a circle. #### Parameters * line\_start: `table` * line\_end: `table` * circle\_center: `table` * circle\_radius: `number` #### Returns * `boolean` ```lua bdtk.line_intersects_circle(line_start, line_end, circle_center, circle_radius) ``` *** ## does\_rect\_intersect\_line Determines if a rectangle intersects with a 2D line segment. #### Parameters * rect: `table` * line\_start: `table` * line\_end: `table` #### Returns * `boolean` ```lua bdtk.does_rect_intersect_line(rect, line_start, line_end) ``` *** ## closest\_point\_on\_line\_segment Determines the closest point on a 2D line segment to a given point. #### Parameters * point: `table` * line\_start: `table` * line\_end: `table` #### Returns * `table` ```lua bdtk.closest_point_on_line_segment(point, line_start, line_end) ``` *** ## triangle\_area\_3d Calculates the area of a 3D triangle given three points. #### Parameters * p1: `table` * p2: `table` * p3: `table` #### Returns * `number` ```lua bdtk.triangle_area_3d(p1, p2, p3) ``` *** ## is\_point\_in\_sphere Determines if a point is inside a 3D sphere defined by center and radius. #### Parameters * point: `table` * sphere\_center: `table` * sphere\_radius: `number` #### Returns * `boolean` ```lua bdtk.is_point_in_sphere(point, sphere_center, sphere_radius) ``` *** ## do\_spheres\_intersect Determines if two spheres intersect. #### Parameters * s1\_center: `table` * s1\_radius: `number` * s2\_center: `table` * s2\_radius: `number` #### Returns * `boolean` ```lua bdtk.do_spheres_intersect(s1_center, s1_radius, s2_center, s2_radius) ``` *** ## is\_point\_in\_convex\_polygon Determines if a point is inside a 2D convex polygon. #### Parameters * point: `table` * polygon: `table` #### Returns * `boolean` ```lua bdtk.is_point_in_convex_polygon(point, polygon) ``` *** ## rotate\_point\_around\_point\_2d Rotates a point around another point in 2D by a given angle in degrees. #### Parameters * point: `table` * pivot: `table` * angle\_degrees: `number` #### Returns * `table` ```lua bdtk.rotate_point_around_point_2d(point, pivot, angle_degrees) ``` *** ## distance\_point\_to\_plane Calculates the distance from a point to a plane. #### Parameters * point: `table` * plane\_point: `table` * plane\_normal: `table` #### Returns * `number` ```lua bdtk.distance_point_to_plane(point, plane_point, plane_normal) ``` *** ## rotation\_to\_direction Converts a rotation vector to a direction vector. #### Parameters * rotation: `table` #### Returns * `table` ```lua bdtk.rotation_to_direction(rotation) ``` *** ## rotate\_box Rotates a box around a central point in 3D by a given heading. #### Parameters * center: `table` * width: `number` * length: `number` * heading: `number` #### Returns * `table` ```lua bdtk.rotate_box(center, width, length, heading) ``` *** ## calculate\_rotation\_matrix Calculates a rotation matrix from heading, pitch, and roll. #### Parameters * heading: `number` * pitch: `number` * roll: `number` #### Returns * `table` ```lua geometry.calculate_rotation_matrix(heading, pitch, roll) ``` *** ## translate\_point\_to\_local\_space Translates a point to a box's local coordinate system using a rotation matrix. #### Parameters * point: `table` * box\_origin: `table` * rot\_matrix: `table` #### Returns * `table` ```lua bdtk.translate_point_to_local_space(point, box_origin, rot_matrix) ``` *** ## is\_point\_in\_oriented\_box Determines if a point is inside an oriented 3D box. #### Parameters * point: `table` * box: `table` #### Returns * `boolean` ```lua bdtk.is_point_in_oriented_box(point, box) ``` # BDUK {% hint style="danger" %} ### ALPHA RELEASE The current version is an alpha release, some things may change and things will definitely be added.\ Most changes to core logic will be small if any, however in cases of larger changes be prepared to have to update your code a little. {% endhint %}
*** ## What is BDUK? Normally? **BOII Development UI Kit**\ When it’s working so well it feels like magic? **BIG D\*CK UI KUNG-FU!**\ When it refuses to cooperate? **Buggy Dumbass Useless Kit** Tired of learning front end UI code? \ Well now you don’t have to. **BDUK** is a front-end toolkit built to cover all your scripting needs.\ It builds full UIs from Lua — no HTML, no CSS, no JavaScript knowledge required.\ Think of a context menu resource — but bigger.. a lot bigger. Headers, footers, modals, cards, buttons, tooltips, themes — it’s all handled.\ Pick what you need, leave what you don’t, and build whatever the hell you can come up with. *** ## **Who’s It For?** * People who can’t code UI — and don’t want to. * Script authors who’d rather build actual gameplay. * UI nerds can use it too — but this one’s built for the rest of you folks. * You. Because you're done with context menus controlling everything. *** ## Why Bother Using It? * **No Bloat** — Only includes what you add. * **No Guesswork —** Modals, buttons, and tooltips just work. * **Reusability** — Build once, use everywhere. * **Uniformity —** You want the same uniform look, across all your scripts. *** ## What’s Included? **Main UI Frame:** * **Header** **—** With slots for branding, buttons, and maybe one day a picture of your nan's cat. * **Footer** **—** Button hints, status text, and keybind rows for people who forget controls. * **Sidebar** **—** Optional side menu with submenu support. * **Content** **—** Where your actual UI goes.. the meat and veg so to speak. * **Tooltip** **—** Hover text system. Originally from my inventory UI. Now universal. **Components:** * **Buttons —** Generates buttons with optional modal injection built-in. * **Cards** — Reusable building blocks. Use for stores, jobs, menus, etc. * **Input Groups** **— I**n optional expandable containers. Use for clothing menus, vehicle customs, etc. * **Modal** **—** Text inputs, selects, numbers, textareas, colour pickers. It’s a modal. * **Namecards** — Stylised name-card display for character profiles with avatar, name, title, level. * **Notify —** Small notification system for in-UI alerts. **Extras:** * **Themes** – One file to override fonts, colours, spacing, and general look. * **Layouts (soon)** – Premade store, job centre, and panel setups coming when I feel like it. *** ## Quick Install The quickest way to get setup is following the instructions below. \ For more detailed installation instructions, or configuring BDUK head here: [**Guides**](/fivem-free-resources/bduk/guides) {% stepper %} {% step %} #### Download Download the [**LATEST RELEASE**](https://github.com/boiidevelopment/bduk/releases) from GitHub {% endstep %} {% step %} #### Add The Resource Add the `bduk` resource into your server resources. {% endstep %} {% step %} #### Add To Server.cfg Add the following line into your `server.cfg` file: `ensure bduk` {% endstep %} {% step %} #### Restart / Start Resource Restart your server or press `F8` and type `refresh; ensure bduk` and the resource will be started. {% endstep %} {% step %} #### Configuration Configuration generally boils down to themes, you can modify the defaults or create your own. \ More on themes: [**Creating Your First Theme**](/fivem-free-resources/bduk/guides/creating-your-first-theme) {% endstep %} {% endstepper %} # Guides This section covers how to use BDUK to build and manage your UI layouts. You'll find quick guides on: * Creating your first UI * Making and applying themes * ... more to come Start with [**Making Your First UI**](/fivem-free-resources/bduk/guides/making-your-first-ui) if you're new. ***
Making Your First UI/files/kJ1zmPXhMiBrth5ysJX8/pages/Jn70Y4pTISBHYzdMJ7u3
Creating Your First Theme/files/yxOzlqEdMd14gt50gMIh/pages/dK28SAEuUemECEk6PObF
# Making Your First UI This guide walks you through how to build your first UI layout using BDUK’s Lua-based config system.\ No HTML or JS needed — just declare what you want using simple tables, then call `build()`. *** ## Basic Structure A complete UI is made up of: * `header` – sits at the top of your UI with 3 sections (left/center/right) * `footer` – fixed to the bottom, also with left/center/right * `content` – contains all main pages and components * *(optional)* `sidebar` – can be added later for tools or quick actions *** ## Step 1: Define a UI Layout Here’s a stripped-down version to start with: ```lua local my_ui = { header = { layout = { left = { justify = "flex-start" }, center = { justify = "center" }, right = { justify = "flex-end" }, }, elements = { left = { { type = "group", items = { { type = "logo", image = "bd_100.png" }, { type = "text", title = "My UI", subtitle = "Made with BDUK" } } } }, center = { { type = "tabs" } }, right = { { type = "namecard", avatar = "avatar_placeholder.jpg", name = "Player", title = "Developer", level = 1, tier = "gold" } } } }, content = { pages = { main_page = { index = 1, title = "Main Page", layout = { center = 6 }, center = { type = "input_groups", title = "Options", id = "basic_inputs", layout = { columns = 1 }, groups = { { header = "General Settings", inputs = { { id = "setting_1", type = "text", label = "Your Name" }, { id = "setting_2", type = "number", label = "Age" } } } }, buttons = { { id = "save", label = "Save", on_click = function(data) ... end, class = "primary" } } } } } }, footer = { layout = { left = { justify = "flex-start" }, center = { justify = "center" }, right = { justify = "flex-end" }, }, elements = { left = { { type = "buttons", buttons = { { id = "back", label = "Back", on_click = function(data) ... end, class = "secondary" } } } }, center = { { type = "text", text = "Made with 💙 by BOII Development" } }, right = { { type = "actions", actions = { { key = "E", label = "Confirm", on_keypress = function(data) ... end, }, { key = "ESC", label = "Close", on_keypress = function(data) ... end, } } } } } } } ``` *** ## Step 2: Show the UI Just trigger it using: ```lua RegisterCommand("open_my_ui", function() exports.bduk:build(my_ui) end) ``` *** ## Adding Components Here’s a few things you can use inside your layout sections: | **Type** | **Description** | | -------------- | ------------------------------------------- | | `text` | Shows a label or info line | | `logo` | Displays a logo image | | `tabs` | Adds tabbed navigation (auto-handled) | | `namecard` | Shows a styled player profile card | | `buttons` | One or more clickable buttons | | `input_groups` | Grouped form fields (number/text/etc.) | | `cards` | Panel cards with image, info, and buttons | | `actions` | Shows keys like `E` or `ESC` to guide users | *** ## Pages Explained The `content.pages` section defines every page in your UI: ```lua content = { pages = { my_page = { index = 1, title = "My Page", layout = { left = 3, center = 6, right = 3 }, center = { type = "cards", title = "Items", layout = { columns = 2 }, cards = { ... } } } } } ``` #### Each page has: * `index`: Page order * `title`: Page label (used in tabs) * `layout`: Grid sizes for `left`, `center`, and `right` (adds up to 12) * `left`, `center`, `right`: Each holds a single component (e.g. `cards`, `input_groups`, etc.) *** ## Tips * All `buttons` can include modals or datasets * Tooltips and keybinds are built into cards via `on_hover` * Use `dataset` fields to pass IDs, source names, or action context *** ## You’re Ready! Try running: ```bash /test_ui_builder ``` Or rename your config and register it under your own command to test. # Creating Your First Theme Themes in BDUK define the overall look and feel of your UI — including fonts, colors, borders, gradients, and effects.\ You can create your own themes by editing a simple CSS file and registering it in the system config. *** ## Step 1: Copy the Default Theme Start with the default theme located at: ``` /ui/css/themes/default.css ``` Make a copy, give it a name like: ``` /ui/css/themes/mytheme.css ``` > **Keep the credit line at the top** — support honest development. don't be that guy...\ > Don't forget to add your own credit note below. *** ## Step 2: Edit Your Theme Open your new CSS file and change any of the variables inside the `body.YOUR_THEME_NAME` block. Below is a complete list of available CSS variables you can use when customizing your theme: | **Category** | **Variable** | **Description** | | ------------------ | ----------------------------------------- | -------------------------------------------- | | **Fonts** | `--header_font` | Font used in headers | | | `--text_font` | Font used for regular text | | **Border Radius** | `--border_radius_outer` | Radius for card/panel corners | | | `--border_radius_inner` | Radius for inner elements like inputs | | **Backgrounds** | `--background_main` | Main background color | | | `--background_panel` | Panels/containers background | | | `--background_hover` | Background when hovered | | | `--background_overlay` | Overlay background for modals/tooltips | | **Text Colors** | `--text_primary` | Main text color | | | `--text_secondary` | Subtext or secondary UI text | | | `--text_tertiary` | Placeholder or hint text | | **Accents** | `--accent` | Primary accent color | | | `--accent2` | Secondary accent | | | `--accent3` | Used for alerts/danger zones | | | `--accent4` | Extra accent (often for icons or details) | | **Borders** | `--border_dark` | Dark border (used for cards/panels) | | | `--border_light` | Light border (used for separation lines) | | | `--border_dashed` | Dashed border for debugging/separators | | **Shadows** | `--shadow_soft` | Soft drop shadow | | | `--shadow_medium` | Medium drop shadow | | | `--shadow_large` | Large drop shadow | | | `--inset_shadow_large` | Large inset shadow for panels/inputs | | | `--inset_shadow_small` | Small inset shadow for inputs | | | `--text_shadow_hard` | Strong black outline around text | | **Gradients** | `--gradient_fade_left` | Fade from left | | | `--gradient_fade_right` | Fade from right | | | `--gradient_fade_both` | Symmetrical fade in from both sides | | **Buttons** | `--button_padding` | Padding inside buttons | | **Scrollbars** | `--scrollbar_track` | Background of scrollbars | | | `--scrollbar_thumb` | Scrollbar draggable section | | **Icons** | `--icon_primary` | Color for primary icons | | | `--icon_secondary` | Color for secondary icons | | **Tooltips** | `--tooltip_title` | Background/text color for tooltip title | | | `--tooltip_rarity_badge` | Background color for rarity badge in tooltip | | **Namecard Ranks** | `--rank_bronze` to `--rank_legend` | Rank color coding on namecards | | **Item Rarity** | `--rarity_common` to `--rarity_legendary` | Color overlays for item rarity | | **Notifications** | `--notify_success` | Color for success notifications | | | `--notify_error` | Color for error notifications | | | `--notify_info` | Color for info notifications | | | `--notify_warning` | Color for warning notifications | | | `--notify_primary` | Used for general or system notices | *** ## Step 3: Register Your Theme Open `manifest.json` and make sure your theme is properly registered. #### 1. Add your theme to the list: ```json "themes": ["dark", "light", "mytheme"] ``` #### 2. Add the CSS file: ```json "css": [ ... "/ui/css/themes/mytheme.css" ] ``` #### 3. Set it as the default if you want it active: ```json "default_theme": "mytheme" ``` > **Note:** Theme switching is not supported live yet — only the **default** theme is applied on load. *** ## That's It! Your theme will now be used automatically when the UI loads.\ You can build as many themes as you want and change the default in the manifest to test each. *** ## Coming Soon * Support for dynamic theme switching in the builder * Theme preview and selection components * Theme-specific overrides for cards, modals, namecards, and more # Core UI

All core UI elements

**BDUK** is split into two sections `core/` and `components` the core UI covers the following. * **Header** **—** With slots for branding, buttons, and maybe one day a picture of your nan's cat. * **Footer** **—** Button hints, status text, and keybind rows for people who forget controls. * **Sidebar** **—** Optional side menu with submenu support. * **Content** **—** Where your actual UI goes.. the meat and veg so to speak. * **Tooltip** **—** Hover text system. Originally from my inventory UI. Now universal. *** {% hint style="info" %} Header sections can support any of the support components they are entirely interchangeable, you are not fixed to the layout shown in the example image. {% endhint %} ## 🟨 1. Header (Left) Used here for branding — includes: * A `group` with a `logo` and `text` *** ## 🟥 2. Header (Center) Used here for **tabs** navigation: * Dynamically switch between pages using a `tabs` element. *** ## 🟩 3. Header (Right) This section contains a **namecard** and optional **buttons** like `Save` and `Exit`. *** ## 🟦 4. Content (Left) The core content section is broken down into 3 sections `left|center|right`, like the header and footer. \ You have full control over the layout of this section. Currently covers two pre-built components: * Cards * Displays item cards in a grid layout. * Each card supports images, labels, embedded actions tooltips.. etc. * Can be used to make anything from crafting script UI's to vehicle stores. * Input Groups * Displays groups of inputs in optional expandable containers. * Can be used to make clothing menus, vehicle custom options or anything else you can think of. *** ## 🟥 5. Tooltip Tooltips display **on-hover** for cards or other items: * Includes structured info: description, value pairs, actions. * Can display arrays of lines and metadata like rarity. * Supports key press actions on hover — Similar to how some survival games work. This system is global and reusable — not limited to cards. *** ## 🟪 6. Sidebar Optional and modular vertical menu: * Contains sections with label + item groups. * Items can have submenus and trigger actions. * Perfect for admin menus or editor tools. *** {% hint style="info" %} Footer sections can support any of the support components they are entirely interchangeable, you are not fixed to the layout shown in the example image. {% endhint %} ## 🟨 7. Footer (Left) Standard **button group** placed on the left: * `Deploy`, `Cancel`, etc. * Can be any number of buttons and can include `modal` or `on_click` actions. *** ## 🟥 8. Footer (Centre) Here it's a **text** element ("Ready to deploy"), but you can swap it with: * Progress bar * Page indicator * Custom HTML/text component *** ## 🟩 9. Footer (Right) A simple **keybind display** using `actions`: * Shows user what key does what * Like `ESC = Close`, `E = Confirm` Supports dynamic binding for different workflows. *** ## Recap Each section supports three alignment zones: * `left`, `centre`, `right` * Each zone can contain any number of supported components | Area | Description | | ------- | ----------------------------------- | | Header | Branding, controls, nav, info | | Footer | Actions, messaging, keybinds | | Content | The main view (multi-pane optional) | | Sidebar | Expandable category menu | | Tooltip | Dynamic hover info popup | # Header
The `header` is the topmost part of the BDUK layout system. It is fully modular, with **three alignable sections** (`left`, `center`, and `right`) — you can place any supported component into any section. *** ## Structure You define a `header` section using the following structure: ```lua header = { layout = { left = { justify = "flex-start" }, center = { justify = "center" }, right = { justify = "flex-end" }, }, elements = { left = { { type = "group", items = { { type = "logo", image = "bd_100.png" }, { type = "text", title = "BOII", subtitle = "UI Builder" } } } }, center = { { type = "tabs" } }, right = { { type = "namecard", avatar = "avatar_placeholder.jpg", background = "namecard_bg_4.jpg", name = "Player Name", title = "Some Player Title", level = 99, tier = "bronze" } } } } ``` Each section (`left`, `center`, `right`) can be **included or omitted**, and you can insert any UI components inside — no limitations. *** ## Supported Elements You can use any of the following types in **any** of the three header sections: | `type` | Description | | ---------- | ------------------------------------------------------------ | | `logo` | Displays a logo image via background. | | `text` | Title + optional subtitle, stacked vertically. | | `tabs` | Auto-generated tab navigation from `content.pages`. | | `button` | Single-action button element. | | `buttons` | Button group using the `Buttons` class. | | `group` | A horizontal wrapper that nests multiple child elements. | | `namecard` | Visual identity block with avatar, name, title, tier, level. | *** ## Alignment Control Each section's alignment can be styled independently using: ```lua layout = { left = { justify = "flex-start", align = "center", gap = "1vw" }, ... } ``` These values map directly to Flexbox properties for layout precision. # Content
The `content` section defines the **main UI area**, supporting **left**, **centre**, and **right** regions. \ Each region can display structured components like input groups or cards, and the layout is fully configurable. It acts as the core of your UI layout system, with full support for modular pages and responsive content updates. *** The above image shows the following: 🟩 1. Cards in column layout. \ 🟥 2. Input Groups \ 🟦 3. Cards in Row layout *** ## Configuration Each content page consists of: * `index`: (optional) Determines order or default tab position. * `title`: Displayed in tabs or page headers. * `layout`: Defines column spans (`left`, `center`, `right`). * `left`, `center`, `right`: Each region may contain a component block. ```lua content = { pages = { my_page = { title = "My Page", index = 1, layout = { left = 2, center = 6, right = 4 }, left = { type = "cards", title = "Left Section", cards = { ... } }, center = { type = "input_groups", title = "Center Section", groups = { ... } }, right = { type = "cards", title = "Right Section", cards = { ... } } } } } ``` *** ## Content Types ### Cards Used for displaying visual blocks with optional images, descriptions, hover tooltips, and buttons. **Example:** ```lua { type = "cards", layout = { columns = 1, flex = "row", scroll_x = "scroll", scroll_y = "scroll" }, title = "Right Section", cards = { { image = "https://placehold.co/64x64", title = "Card In Row", description = "Card Description.", layout = "row", on_hover = { title = "Card Info", description = { "Info descriptions can support arrays", "- like so", "- you get the idea" }, values = { { key = "Key", value = "Value Pairs" }, { key = "Name", value = "Case" } }, actions = { { id = "test_action", key = "E", label = "Action on Keypress", on_keypress = function(data) ... end } }, rarity = "common" }, buttons = { { id = "modal_btn", label = "Modal Button", class = "primary", on_action = function(data) ... end, dataset = { target_id = "example_card", source = "cards_test" }, modal = { title = "Modal Title", options = { { id = "name", label = "Name", type = "text" } }, buttons = { { id = "modal_button", label = "Modal Button 2", on_action = function(data) ... end } } } } } } } } ``` *** ### Input Groups Used to organize structured form inputs into expandable groupings. \ Can include buttons for submitting or interacting with input data. **Example:** ```lua { type = "input_groups", title = "Input Groups", id = "inputs_id", layout = { columns = 1 }, groups = { { header = "Some Options", expandable = false, inputs = { { id = "opt_1", type = "text", label = "Some Option" }, { id = "opt_2", type = "number", label = "Another Option" } } } }, buttons = { { id = "input_btn", label = "Input Button", class = "primary", on_action = function(data) ... end } } } ``` # Footer
The `footer` sits at the bottom of the BDUK UI layout and serves as a **flexible, function-rich area** for actions, buttons, hotkeys, tooltips, and even profile info. It follows the same `left`, `center`, and `right` layout system as the `header`. *** ## Structure You define a `footer` like so: ```lua footer = { layout = { left = { justify = "flex-start", gap = "1vw" }, center = { justify = "center" }, right = { justify = "flex-end", gap = "1vw" }, }, elements = { left = { { type = "buttons", buttons = { { id = "deploy", label = "Deploy", on_action = function(data) ... end, class = "primary" }, { id = "cancel", label = "Cancel", action = "close_builder", class = "secondary" } } } }, center = { { type = "text", text = "Ready to deploy." } }, right = { { type = "actions", actions = { { key = "ESC", label = "Close" }, { key = "E", label = "Confirm" } } } } } } ``` You may omit or include any section (`left`, `center`, `right`) and place elements in whichever position you need. All elements are fully swappable. *** ## Supported Elements The `footer` supports a range of useful UI components: | `type` | Description | | ---------- | ------------------------------------------------------- | | `text` | Simple centered or aligned string label. | | `action` | Single hotkey + label (e.g. `ESC = Close`). | | `actions` | Group of hotkeys displayed inline. | | `buttons` | One or more clickable buttons with callbacks. | | `group` | Inline wrapper for grouping elements together. | | `namecard` | Same identity block used in the header (optional here). | Each type is handled internally by the `Footer` class with intelligent layout styling and optional click hooks. *** ## Alignment Control You can define layout styles for each section using `justify`, `align`, and `gap` just like in the header: ```lua left = { justify = "flex-start", align = "center", gap = "1vw" } ``` These map directly to CSS flexbox properties. # Sidebar
The `sidebar` is a **vertical action menu** placed to the left or right of your UI layout. \ It supports nested submenus, icons, images, and dataset-driven interactivity. *** ## Structure ```lua sidebar = { layout = { side = "right" }, -- or "left" sections = { { id = "test_1", label = "Sidebar Category", items = { { id = "some_option", label = "Some Option", image = "assets/logos/bd_100.png", action = "some_action" }, { id = "some_other_option", label = "Some Other Option", icon = "fas fa-box", action = "some_other_action", submenu = { { id = "some_submenu_option_1", label = "Some Submenu Option", on_action = function(data) ... end }, { id = "some_submenu_option_2", label = "Some Other Submenu Option", on_action = function(data) ... end } } } } } } } ``` You can define multiple `sections` and group your interactions logically by category. *** ## Item Options Each `section` contains a list of `items`. These support: | Field | Description | | --------- | --------------------------------------------------- | | `id` | Unique identifier used for click callbacks. | | `label` | Text label shown in the sidebar. | | `action` | Action string sent to the client (Lua) for routing. | | `icon` | Font Awesome icon class. | | `image` | Local or web image path. | | `submenu` | Optional array of sub-options, shown on click. | Submenu items are structured identically but don’t support icons or images. *** ## Layout You can place the sidebar on either side: ```lua layout = { side = "left" } -- or "right" ``` Internally, this maps to a `.sidebar.left` or `.sidebar.right` class with automatic CSS control. # Tooltip
The `tooltip` is a dynamic info panel that follows the mouse and displays contextual data for any UI element that has hover metadata. It supports: * **Title, description, and key-value fields** * **Rarity styling** * **Future keypress-based action hints** * Full integration using `on_hover` blocks *** ## Structure Tooltips are defined on any UI element via the `on_hover` table: ```lua { title = "Card Info", description = { "Info descriptions can support arrays", "- like so", "- you get the idea" }, values = { { key = "Key", value = "Value Pairs" }, { key = "Name", value = "Case" } }, actions = { { id = "test_action", key = "E", label = "Action on Keypress", on_action = function(data) ... end } }, rarity = "common" } ``` Attach this block using `on_hover` key in UI config. *** ## Rarity Themes Tooltip headers adapt colours based on `rarity`. \ This uses `var(--rarity_x)` theming for visual identity. | Value | Style CSS Variable | | ----------- | -------------------- | | `uncommon` | `--rarity_uncommon` | | `common` | `--rarity_common` | | `rare` | `--rarity_rare` | | `epic` | `--rarity_epic` | | `legendary` | `--rarity_legendary` | ```css --rarity_common: rgba(255, 255, 255, 0.8); --rarity_uncommon: rgba(38, 189, 38, 0.8); --rarity_rare: rgba(66, 135, 245, 0.8); --rarity_epic: rgba(119, 45, 189, 0.8); --rarity_legendary: rgba(219, 144, 57, 0.8); ``` *** ## Tooltip Sections Each tooltip supports 4 sections: | Section | Description | | ------------- | -------------------------------------------------- | | `title` | The main tooltip title with optional rarity label. | | `description` | Array of text lines shown as a paragraph block. | | `values` | Key-value display for stats, attributes, etc. | | `actions` | Shows a list of interactive keypresses. | # Components
**BDUK** includes a growing list of UI components that you can mix, match, and reuse across headers, footers, sidebars, and main content areas. This example layout showcases multiple core components working together in one interface. \ Each element is modular and can be placed anywhere **that supports that type of component**. {% hint style="info" %} The layout shown is just an example — you are not locked into any positioning. {% endhint %} *** ## 🟩 **1. Cards (Column)** Displayed in the **left section** of the content layout.\ Cards are visual containers that support: * Images, labels, descriptions * Embedded buttons or modals * Hover tooltips for extra info * Flexible layouts: column or row **Usage:** Content only *** ## 🟥 **2. Input Groups** Displayed in the **centre section**.\ Grouped input elements under titled headers: * Supports expanding/collapsing groups * Includes text, number, select and more * Pre-styled and layout-ready **Usage:** Content only *** ## 🟦 **3. Cards (Row)** Displayed in the **right section**, using a scrollable row layout.\ Behaves like column cards but flows horizontally: * Set `layout.flex = "row"` * Combine with scroll for carousels or horizontal menus **Usage:** Content only *** ## 🟨 **4. Namecard** Displayed in the **top right** of the header, but can also go in the footer.\ Compact user block showing: * Player name/title * Optional avatar, tier, or badge **Usage:** Header or Footer *** ## 🟪 **5. Notifications** Shown as floating stack elements — typically top right.\ Display system-wide messages or alerts: * Color-coded by type or rarity * Icon, border, and shadow support * Auto-dismiss or persist as needed **Usage:** Global (top-level only) *** ## 🟫 **6. Modal** Popup displayed in centre of screen on action.\ Used for inline editing, confirmation, or input: * Title, inputs, and action buttons * Optional dataset for advanced logic **Usage:** Triggered from any component button or keypress. *** ## 🟥 **7. Buttons** Buttons are one of the most flexible and essential components in BDUK.\ They can be used anywhere that accepts components, including: * Headers * Footers * Content sections * Sidebars * Modals Each button supports: * Dataset attributes passed to Lua or other NUI handlers * Optional modals defined inline (`data-modal`) * Optional `should_close` flag to auto-close the UI builder after action Buttons are automatically bound to handle modal opening and NUI callbacks without any extra setup. You can define as many as you want in a group. **Usage:** Any layout section or modal *** ## Recap Every component in BDUK is modular, but not every component belongs everywhere: {% hint style="info" %} Notifications and Modals are top level elements, they are not placed inside any specific section. {% endhint %} | Component | Header | Footer | Content | Sidebar | | ------------ | ------ | ------ | ------- | ------- | | Cards | ❌ | ❌ | ✅ | ❌ | | Input Groups | ❌ | ❌ | ✅ | ❌ | | Namecard | ✅ | ✅ | ❌ | ❌ | | Buttons | ✅ | ✅ | ✅ | ✅ | # Buttons
Adds one or more clickable buttons to your layout.\ Use these for confirming actions, opening modals, or triggering logic through custom `on_action` handlers. *** ## Structure ```lua buttons = { { id = "confirm_btn", label = "Confirm", on_action = function(data) -- Custom logic for confirming a purchase end, should_close = true, class = "primary" }, { id = "cancel_btn", label = "Cancel", action = "close_builder", class = "danger" } } ``` *** ## Options | Key | Description | | -------------- | --------------------------------------------------------------------------- | | `id` | Unique identifier for the button. | | `label` | Text shown on the button. | | `action` | (Optional) Use `"close_builder"` to close the UI safely. | | `on_action` | (Optional) A function to run when clicked. Receives `data` if needed. | | `should_close` | (Optional) Closes the UI builder after clicking. Default: `false`. | | `class` | (Optional) Style of button — try `"primary"`, `"danger"`, `"success"`, etc. | | `icon` | (Optional) Add an icon, e.g., `"fas fa-check"`. | | `modal` | (Optional) Show a confirmation modal before running the action. | | `dataset` | (Optional) Extra data to pass to the `on_action` function. | *** ## Notes * Use multiple buttons in a row by adding more entries to the `buttons` table. * `dataset = {}` gets passed into your `on_action` function. * Use `should_close = true` if the UI should close after pressing the button. * Use `modal = { title = "...", description = "..." }` to prompt confirmation before the button runs its logic. * For closing the UI, use the special global action: ```lua action = "close_builder" ``` # Cards
Displays one or more card-style panels in a grid or list format.\ Cards can contain an image, a title, a description, tooltips on hover, and interactive buttons or keybind actions. *** ## Structure ```lua left = { type = "cards", title = "Items", layout = { columns = 2, flex = "column", scroll_x = "none" }, cards = { { image = "https://placehold.co/252x126", title = "My Card", description = "This is a test card.", layout = "column", on_hover = { title = "Extra Info", description = { "You can use", "- multiple lines", "- like this" }, values = { { key = "Item", value = "Something" }, { key = "Owner", value = "Case" } }, actions = { { id = "inspect_item", key = "E", label = "Inspect", on_action = function(data) -- Inspect logic end } }, rarity = "common" }, buttons = { { id = "edit_card", label = "Edit", class = "primary", on_action = function(data) -- Edit card logic end, dataset = { card_id = "card_1" } }, { id = "close_ui", label = "Close", action = "close_builder", class = "danger" } } } } } ``` *** ## Card Options Each card supports the following fields: | Key | Description | | --------------- | ------------------------------------------------------------------------- | | `title` | Title text for the card. | | `description` | Text shown below the title. | | `image` | (Optional) Image shown at the top. Full URLs or `nui://` paths supported. | | `layout` | (Optional) `"column"` or `"row"` layout inside the card. | | `on_hover` | (Optional) Shows tooltip with extra info: | | → `title` | Tooltip header. | | → `description` | List of lines for the tooltip. | | → `values` | Array of `{ key, value }` to show below tooltip. | | → `actions` | Keybinding actions with `on_action` support. | | → `rarity` | (Optional) A style tag such as `"common"`, `"rare"`, etc. | | `buttons` | (Optional) Array of button objects (same structure as Buttons component). | *** ## Layout Options | Key | Description | | ---------- | ---------------------------------------------------------- | | `columns` | Number of columns in the card layout (e.g., `2`). | | `flex` | `"row"` or `"column"` for internal card layout. | | `scroll_x` | `"auto"`, `"on"`, or `"none"` to enable horizontal scroll. | | `scroll_y` | `"auto"`, `"on"`, or `"none"` to enable vertical scroll. | *** ## Notes * Cards are perfect for displaying item lists, inventories, player entries, or shops. * You can freely mix images, hover tooltips, and buttons per card. * Each `button` or `action` supports: * `on_action = function(data)` — your custom logic. * `action = "close_builder"` — a built-in safe UI close. * Optional `dataset = {}` to pass values to the function. * This structure keeps your logic uniform across both `cards.buttons` and `cards.on_hover.actions`. # Input Groups
Organize grouped input fields in structured containers.\ Supports expandable sections, number inputs with increment/decrement handlers, and custom action buttons. *** ## Structure ```lua center = { type = "input_groups", id = "test_inputs", title = "Input Groups Test", layout = { columns = 1, scroll_x = "none", scroll_y = "auto" }, groups = { { header = "Some Group", expandable = false, inputs = { { id = "option_1", type = "number", label = "Some Option", category = "group_1", on_increment = function(data) print("Incremented") end, on_decrement = function(data) print("Decremented") end } } } }, buttons = { { id = "confirm_options", label = "Confirm", action = "confirm_options", class = "primary", dataset = { target_id = "test_inputs", source = "input_groups_test" } }, { id = "reset_options", label = "Reset", action = "reset_options", class = "secondary", dataset = { target_id = "test_inputs", source = "input_groups_test" } } } } ``` *** ## Group Options | Key | Description | | ------------ | ------------------------------------ | | `header` | Title displayed above the group. | | `expandable` | Allows the group to collapse/expand. | | `inputs` | Array of fields in the group. | *** ## Input Options | Key | Description | | -------------- | --------------------------------------------------------------------------- | | `id` | Unique input identifier. | | `type` | `"number"` or `"text"`. | | `label` | Label shown next to the input. | | `category` | (Optional) Logical grouping for identification. | | `default` | (Text only) Initial value shown in the input. | | `placeholder` | (Text only) Shown when the field is empty. | | `on_increment` | (Number only) Function triggered when + button is pressed. Receives `data`. | | `on_decrement` | (Number only) Function triggered when – button is pressed. Receives `data`. | > Number inputs automatically include + and – buttons for value adjustment. These fire your attached callbacks with context-aware `data` from `dataset`. *** ## Button Options | Key | Description | | -------------- | --------------------------------------------------------------------- | | `id` | Unique button name. | | `label` | Text shown on the button. | | `action` | Action to trigger — e.g., `"close_builder"` or your own NUI callback. | | `on_action` | (Optional) Function to run instead of action. | | `class` | (Optional) Button style: `"primary"`, `"danger"`, etc. | | `should_close` | (Optional) Whether to close the UI on press. Default: `false`. | | `dataset` | (Optional) Custom data passed to the action or function. | *** ## Layout Options | Key | Description | | ---------- | ---------------------------------------------------- | | `columns` | Number of input columns (e.g., 2 = side by side). | | `scroll_x` | `"none"`, `"auto"`, or `"on"` for horizontal scroll. | | `scroll_y` | `"none"`, `"auto"`, or `"on"` for vertical scroll. | *** ## Notes * `on_increment` and `on_decrement` are the preferred way to handle number field changes. * Group sections can be collapsed by setting `expandable = true`. * Use `dataset` to pass `target_id`, `source`, or custom flags with buttons. * Button logic and dataset handling are identical to the Buttons component for consistency. * Use `action = "close_builder"` if you want to safely exit the UI. # Modal
A popup window that shows a title, input fields, and action buttons.\ Modals can appear when you press a key, hover over a card, or click a button. *** ## Structure ```lua modal = { title = "Edit Item", options = { { id = "item_name", label = "Item Name", type = "text" }, { id = "amount", label = "Amount", type = "number", min = 1, max = 100 } }, buttons = { { id = "save_item", label = "Save", on_action = function(data) -- do something with data.dataset.item_name, data.dataset.amount end, dataset = { -- additional data if required source = "inventory", item_id = "some_id" } }, { id = "cancel", label = "Cancel" -- No action needed — this will auto-close the modal } } } ``` *** ## Modal Options | Key | Description | | --------- | ------------------------------------------------------------ | | `title` | Title text shown at the top of the modal. | | `options` | A list of inputs to show inside the modal (see Input Types). | | `buttons` | Buttons shown at the bottom — use `on_action` or `action`. | *** ## Input Types | Type | Description | | ---------- | ---------------------------------------------------------------- | | `text` | A single-line text input. | | `number` | A number input. You can include `min` and `max`. | | `textarea` | A larger, multiline input. | | `select` | A dropdown menu — include `options = { { label, value }, ... }`. | ## Each input requires: | Key | Description | | ------- | ---------------------------------- | | `id` | Unique field name. | | `label` | Label displayed next to the input. | *** ## Button Options | Key | Description | | ----------- | --------------------------------------------------------------------- | | `id` | Unique button ID. | | `label` | Button text. | | `on_action` | Custom handler function that receives `{ input = {}, dataset = {} }`. | | `action` | Optional named action (e.g., `"close_builder"`). | | `dataset` | Optional values passed alongside the input data. | | *(none)* | If no `on_action` or `action` is given, the button closes the modal. | *** ## Notes * Modal input values are **automatically collected** when a button is clicked. * Values are passed to your handler function or action as `data.input`. * You can show one modal per interaction or button — they do not conflict. * Use `on_action = function(data)` for fully custom behavior. * Use `action = "close_builder"` to safely close the UI entirely. * Simply leave out the action on any button to close the modal. # Namecard
Displays a clean, styled player profile — including avatar, name, title, level, and tier.\ Used in headers or footers to show who's logged in, their status, or game rank. *** ## Structure ```lua { type = "namecard", avatar = "avatar_1.jpg", background = "namecard_bg_2.jpg", name = "Player Name", title = "Some Player Title", level = 99, tier = "silver" } ``` *** ## Where to Use You can place a namecard in: * `header.left`, or `header.right` * `footer.left`, or `footer.right` *** ## Fields * **`type`**: Always `"namecard"` to use this component. * **`avatar`**: File name or path for the avatar image (stored in `/ui/assets/namecards/avatars/`). If a full URL or `nui://` path is provided, it will be used directly. * **`background`** *(optional)*: Background image file (stored in `/ui/assets/namecards/backgrounds/`). Defaults to `"avatar_placeholder.png"`. Full links or `nui://` paths are supported. * **`name`** *(optional)*: The player’s name. Defaults to `"Player Name"`. * **`title`** *(optional)*: Role or description (e.g., "Founder", "Police Chief"). * **`level`** *(optional)*: Player level — displayed as `Lv. 99`. * **`tier`** *(optional)*: Style pre-set (`"bronze"`, `"silver"`, `"gold"`, etc.) for colouring and badges. *** ## Notes * `avatar` and `background` must match filenames in the asset folders. * Tiers can be styled via CSS — each one has a visual style (`.bronze`, `.gold`, etc.). # Notify
Shows floating notifications on the screen to alert the player.\ Use these for messages like success, errors, info, warnings, etc.\ \ These were added mainly to provide a built in way for notifying from within the UI, however you can use the notifications externally if you wish. *** ## Usage You **trigger notifications** using component `notify` sections, directly though `exports.bduk:notify(opts)`, or by firing the client event `bduk:notify` *** ## Structure ```lua { type = "success", message = "Item added to inventory!", header = "Success", icon = "fa-solid fa-check-circle", duration = 5000, match_border = true, match_shadow = true } ``` *** ## Notification Options * **`type`**: `"info"`, `"success"`, `"warning"`, or `"error"` — changes the color. * **`header`** *(optional)*: Bold title at the top. * **`message`**: Main text body. * **`icon`** *(optional)*: Font Awesome icon class (e.g. `"fa-solid fa-check"`). * **`duration`** *(optional)*: How long it stays on screen (in ms). `0` = sticky. * **`match_border`** *(optional)*: Color the border to match the type. * **`match_shadow`** *(optional)*: Color the shadow to match the type. *** ## Position & Direction You can configure where and how notifications appear using within the main builder config: 
notify = {
    position = "top-right",      -- top-left, top-center, bottom-right, etc.
    fill_direction = "down"      -- "down" (default) or "up"
}
If you don't specify this, it defaults to `"right-center"` filling **downward**. *** #### Notes * Notifications are **always floating** — they don’t go in layout slots. * Supports multiple styles and customizable timing. * Can stack multiple at once. # API This page documents the public exports and events provided by BDUK. *** ## Events ### bduk:notify Fires a UI notification to the client. ```lua TriggerEvent("bduk:notify", { type = "success", message = "Item added!", header = "Done", icon = "fa-solid fa-check-circle", duration = 5000, match_border = true, match_shadow = false }) ``` #### Parameters * `type`: `"success"`, `"error"`, `"info"`, `"warning"` — *(default: `"info"`)* * `message`: Body text (required) * `header`: Optional title * `icon`: Font Awesome class (e.g. `"fa-solid fa-bell"`) * `duration`: Time in ms (default `5000`, `0` = sticky) * `match_border`: Whether to color the border based on type * `match_shadow`: Whether to color the shadow based on type *** ## Exports ### build Builds and displays a full BDUK UI layout. ```lua exports.bduk:build(layout) ``` #### Parameters * `layout`: The full Lua config table for your UI (see: [**Making Your First UI**](/fivem-free-resources/bduk/guides/making-your-first-ui)) *** ### notify Triggers a notification programmatically (same as the `bduk:notify` event). ```lua exports.bduk:notify({ type = "error", message = "Something went wrong!" }) ``` #### Parameters * Same structure as `bduk:notify` event (see above) # BDSC A **lightweight**, **modern** server core designed for maximum flexibility. {% hint style="danger" %} ### Not a Roleplay Framework BDSC is **not** a traditional server framework.\ It ships with **no jobs, inventories, or gameplay logic**. What your server does is **entirely defined** by the plugins you choose to load — or build yourself. {% endhint %} *** ## What Is BDSC? Normally? **BOII Development Server Core**\ When it’s running smoothly? **Barebones Done Smart & Clean**\ When it refuses to co-operate? **Bug-Driven Sh\*tfest of Chaos.** BDSC is a lightweight server foundation designed for developers who want control.\ It doesn’t care what your server does — it just gives you a clean, flexible structure to build on. No jobs.\ No inventory.\ No economy.\ No drama. You get the boring but essential stuff: * Player management * Object extensions * A couple of handy utilities\ Everything else? You decide. *** ## Who It’s For BDSC was built for internal use on BOII projects — survival, minigames, experiments.\ But it’s now open and modular enough to support anything. If you're tired of bloated RP frameworks or want a **clean, no-bullshit starting point**, this is for you. You get: * A stable foundation * A consistent object system * A fully extensible runtime * Zero assumptions about your gameplay Use it. Fork it. Rewrite it. Just don’t make it worse. *** ## What It Provides BDSC handles: * Player management and object lifecycle * Extension hooks for runtime systems * Server/client-safe data syncing * Core exports for structured access * Some basic utlity functions No hardcoded gameplay.\ No required systems.\ No enforced dependencies.\ You build what matters — BDSC stays out of the way. *** ## Ideal Use Cases BDSC is framework-agnostic and gameplay-neutral.\ Perfect for: * Custom survival servers * Minigame or PvP modes * Custom RP frameworks * Experimental mechanics * Hybrid / mashup servers If you’re building something new, this is the foundation to do it clean. *** ## Player Extensions BDSC supports extending player objects at runtime - without breaking structure: ```lua player:add_data("stats", { health = 100 }, true) player:add_method("stats", "get_health", function(self) return self:get_data("stats").health end) player:run_method("stats", "get_health") ``` All data/methods are namespaced, and replicated data syncs automatically to clients if marked as such. *** ## Structure Everything is modular and clearly separated. ``` bashCopyEditcore/ │ ├── lib/ # Utility functions (e.g. utils.lua) │ ├── player/ # Main player system │ ├── events.lua # Join/leave, sync, client handlers │ ├── factory.lua # Creates player objects │ ├── methods.lua # Public/private extension logic │ ├── registry.lua # Player storage, save/remove/get │ ├── locales/ # Translation files │ └── en.lua │ ├── finalise.lua # Exports and locks bdsc namespace ├── fxmanifest.lua # Resource manifest └── init.lua # Core bootloader ``` Want to add inventory? Authentication? Stats?\ Just attach logic using `add_data` and `add_method` on player objects - no plugin boilerplate required. *** ## Quick Install BDSC isn’t a full framework — it’s a clean server **core**. \ You don’t need to install databases, jobs, inventories, or other bloated systems. To get started: {% stepper %} {% step %} #### **Drop It Into Your Server** Place the `bdsc` resource into your `resources/` folder.\ Make sure it starts after `bdtk` (required for user accounts, you could change this). ``` ensure bdtk ensure bdsc ``` {% endstep %} {% step %} #### **Start The Server** BDSC will automatically initialize and log connected players.\ It doesn’t require SQL or any config to boot. {% endstep %} {% step %} #### Extend It Write your own logic using the exposed player API, or import it into your systems via: ```lua local core = exports.bdsc:import() ``` That’s it. No setup wizard. No bloated dependencies.\ Just a clean foundation for your own logic. {% endstep %} {% endstepper %} ***
Important Guides/files/mXGQlzqtxWDAWC63HwSh/pages/ReibOVNagqQM9oAUvXBH
API Reference/files/lfc1oyGmqtwJalCePlXA/pages/tG7Hg9wkmpdNXg3iRGpY
# Guides Welcome to the BDSC Guides section.\ This area covers everything you need to know to **extend**, **modify**, and **interact** with player objects using the BDSC server core. Whether you're adding custom stats, building a role system, or just syncing data. \ These guides walk you through the process with real examples. > All guides assume you’ve already set up the core system and are familiar with Lua in a server-side FiveM environment. ***
Extending Players/pages/TXP11MeT8ciDKyMYjPd9/files/KQrHHTGU9BKAX4iXpBCC
Working Examples/pages/aX2lseLrF4SEupqEaJAd/files/JJZ7xyl93OBMA1aPd1fs
# Extending Players BDSC supports dynamic, runtime-safe extension of player objects with custom data and methods. \ This lets you build modular logic without touching the core. *** ## Add Data Adds custom data to the player. Optionally replicated to the client. **Example** ```lua player:add_data("stats", { health = 100, stamina = 50 }, true) ``` **Parameters** * `stats` – key name for the data entry. * `{ health = 100, stamina = 50 }` – table to store. * `true` – replicate to client (optional). *** ## Add Methods Attach custom methods that can later be executed via `run_method`. **Example** ```lua player:add_method("stats", "get_health", function(self) local stats = self:get_data("stats") return stats and stats.health or 0 end) ``` **Usage** ```lua player:run_method("stats", "get_health") ``` *** ## Update Data Modify an existing data block and optionally sync it. **Example** ```lua local stats = player:get_data("stats") stats.health = stats.health - 10 player:set_data("stats", stats, true) ``` *** ## Remove Data Removes a data key. **Example** ```lua player:remove_data("job") ``` *** ## Sync Data Force a sync of all replicated data to the client. **Example** ```lua player:sync_data() ``` *** ## Dump All Data Logs all currently stored player data. **Example** ```lua local data = player:get_data() for k, v in pairs(data) do print(k .. ": " .. json.encode(v)) end ``` *** Here’s a concise section explaining how the `on_save` and `on_destroy` methods work when registered via namespaces: *** ## Lifecycle Hooks BDSC supports **namespace-specific lifecycle methods** that automatically run when certain player events occur. These methods are defined under a specific namespace using `add_method` and are called internally during key moments in the player's lifecycle. #### Supported Hooks | Hook Name | Description | | ------------ | --------------------------------------------------------------------------- | | `on_save` | Called when `player:save()` is triggered (e.g., on disconnect or manually). | | `on_destroy` | Called when `player:destroy()` is triggered (e.g., on player drop). | #### How It Works When a lifecycle event runs, BDSC will automatically check each namespace for these methods and call them in order. #### Example ```lua player:add_method("stats", "on_save", function(self) print("Saving stats for player:", self.meta.username) end) player:add_method("inventory", "on_destroy", function(self) print("Cleaning up inventory for:", self.meta.username) end) ``` You **do not** need to manually call these - BDSC will handle them as long as they are added under a namespace using `add_method(namespace, "on_save" | "on_destroy", fn)`. > Avoid long-running operations inside these hooks — keep them lightweight for stability. *** ## Missing Method Safety Calling a non-existent method will return `nil`. **Example** ```lua local result = player:run_method("missing") print("Result:", result or "nil") ``` *** ## No Internal Access Only the `meta` table is exposed. All other functionality data, methods, syncing - must be accessed via the public API. Direct access to `_extensions._data`, `_extensions._methods`, or other internals is not possible and never required. *** ## Quick Example Below is a minimal, self-contained example that demonstrates how to create a player object and extend it externally using basic commands. This includes: * Adding a `stats` data block * Defining custom methods (like `get_health`) * Syncing data to the client * Simulating damage * Handling save logic ```lua local core = exports.bdsc:import() -- Create and initialize a new player RegisterCommand("make", function(src) local player = core.create_player(src) if not player then print("Failed to create player") return end -- Add initial stats player:add_data("stats", { health = 100, stamina = 50 }, true) -- Add method to retrieve health player:add_method("stats", "get_health", function(self) local stats = self:get_data("stats") return stats and stats.health or 0 end) -- Add save lifecycle method player:add_method("stats", "on_save", function() print("saving player stats") end) print("Player created and methods attached.") end, false) -- Check player health RegisterCommand("hp", function(src) local player = core.get_player(src) if not player then print("No player found.") return end local hp = player:run_method("stats", "get_health") print("Health:", hp) end, false) -- Apply damage to the player RegisterCommand("damage", function(src, args) local player = core.get_player(src) if not player then print("No player found.") return end local amount = tonumber(args[1]) or 10 local stats = player:get_data("stats") stats.health = stats.health - amount player:set_data("stats", stats, true) print("Damaged player for", amount) end, false) ``` > **Tip:** Every player object supports runtime extension. You can safely add new data or methods at any point — even after creation. # Full Working Example This example demonstrates how to use BDSC to create and interact with custom player data and methods. It includes: * Creating a player instance * Attaching data (`add_data`, `set_data`, `remove_data`) * Adding custom methods (`add_method`) * Running methods (`run_method`) * Lifecycle support (`on_save`, `on_destroy`) * Syncing data to the client * Safe protections against modifying internal structures > T**ip:** This file can be placed directly into a test resource and will work as-is with a functioning BDSC + BDTK environment. *** #### 📄 `example.lua` ```lua --[[ This file is part of BDSC (BOII Development Server Core) and is licensed under the MIT License. See the LICENSE file in the root directory for full terms. © 2025 Case @ BOII Development Support honest development — retain this credit. Don't be that guy... ]] --- @script example --- @description BDSC Example Integration File --- This file demonstrates how to: --- - Create a player instance --- - Add custom data and methods --- - Access and modify data --- - Trigger lifecycle and sync logic --- Importing the bdsc namespace --- It does not matter what you name this "bdsc", "core", "banana".. up to you *(may sound dumb to point that out but ive been asked a few times)*. local core = exports.bdsc:import() --- Create and setup a new player instance RegisterCommand("make", function(src) local player = core.create_player(src) if not player then print("Failed to create player") return end -- Attach initial data player:add_data("stats", { health = 100, stamina = 50 }, true) -- if true will replicate to client -- Add a method to get player health player:add_method("stats", "get_health", function(self) local stats = self:get_data("stats") return stats and stats.health or 0 end) -- Lifecycle method triggered on save player:add_method("stats", "on_save", function() print("saving player stats") end) -- Lifecycle method triggered on destroy player:add_method("stats", "on_destroy", function() print("destroying player, do something with stats?") end) print("Player created and method added.") end, false) --- Print the players current health RegisterCommand("hp", function(src) local player = core.get_player(src) if not player then print("No player found.") return end print("Health:", player:run_method("stats", "get_health")) end, false) --- Deal damage to the player by reducing health --- Run /hp command again after to check if damaged RegisterCommand("damage", function(src, args) local player = core.get_player(src) if not player then print("No player found.") return end local amount = tonumber(args[1]) or 10 local stats = player:get_data("stats") stats.health = stats.health - amount player:set_data("stats", stats, true) print("Damaged player for", amount) end, false) --- Add a method to uppercase the job name RegisterCommand("add_upper", function(src) local player = core.get_player(src) if not player then print("No player found.") return end player:add_method("get_upper_job", function(self) local job = self:get_data("job") return job and string.upper(job) or "NONE" end) print("Method get_upper_job added.") end, false) --- Call the uppercased job method RegisterCommand("call_upper", function(src) local player = core.get_player(src) if not player then print("No player found.") return end print("Upper Job:", player:run_method("get_upper_job")) end, false) --- Assign a job to the player RegisterCommand("job", function(src, args) local player = core.get_player(src) if not player then print("No player found.") return end local job = args[1] or "thief" player:add_data("job", job, true) print("Job set to:", job) end, false) --- Remove the players job RegisterCommand("clearjob", function(src) local player = core.get_player(src) if not player then print("No player found.") return end player:remove_data("job") print("Job removed.") end, false) --- Dump all stored data for the player RegisterCommand("dump", function(src) local player = core.get_player(src) if not player then print("No player found.") return end local data = player:get_data() print("Data dump:") for k, v in pairs(data) do print(k .. ": " .. json.encode(v)) end end, false) --- Force a manual sync of all replicated data RegisterCommand("sync", function(src) local player = core.get_player(src) if not player then print("No player found.") return end player:sync_data() end, false) --- Attempt to call a method that doesn't exist RegisterCommand("badcall", function(src) local player = core.get_player(src) if not player then print("No player found.") return end print("Calling missing method:") local result = player:run_method("nonexistent") print("Result:", result or "nil") end, false) --- Attempt to write directly to the _data table (should be blocked) RegisterCommand("overwrite", function(src) local player = core.get_player(src) if not player then print("No player found.") return end print("Trying to write to _data (should error)...") player._data["hack"] = true end, false) --- Attempt to read directly from the _data table (should error) RegisterCommand("read", function(src) local player = core.get_player(src) if not player then print("No player found.") return end print("Trying to read _data directly (should error)...") local value = player._data["stats"] end, false) --- Attempt to save player --- Should print "saving player stats" from the `on_save` method we added in `/make` RegisterCommand("save", function(src) local player = core.get_player(src) if not player then print("No player found.") return end print("Trying to save player") player:save() end) --- Attempt to destroy player --- Should print "destroying player, do something with stats?" from the `on_destroy` method we added in `/make` RegisterCommand("save", function(src) local player = core.get_player(src) if not player then print("No player found.") return end print("Trying to destroy player") player:destroy() end) ``` *** # API The **BOII Development Server Core (BDSC)** exposes a clean, structured API designed to give you controlled access to essential systems - without enforcing how your server should work. It focuses on **player handling**, **server registry**, and **utility helpers**, giving you full control over your gameplay logic through modular extensions. *** ## What It Covers The API is split into three main areas: #### **1. Registry** Manage the core player lifecycle. * Create and register player objects * Retrieve players by source * Maintain the live player registry #### **2. Player API** Interact with a player object via its public-facing interface. * Add data or methods dynamically * Sync data to clients when needed * Trigger save/destroy lifecycle events #### **3. Utility Functions** Access core helpers for logging, and translations. *** ## Design Philosophy BDSC is built for developers who want flexibility without the baggage. * Clean, minimal API * Lifecycle and data sync built-in * Fully extensible from external resources * No forced framework rules * No prebuilt gameplay logic *** ## How to Use the API BDSC exposes its full API via a single namespace import. #### **Namespace Import** Use `exports.bdsc:import()` to get access to all available functions and objects: ```lua local bdsc = exports.bdsc:import() local player = bdsc.get_player(source) player:add_data("custom", { foo = "bar" }, true) ``` > All player objects support the full public API, including `add_data`, `run_method`, and `save`. ***
Player Registry/files/p74L34Q7wphkJXWHab48/pages/x3Fl6t9j4MWactzQWlSQ
Player Object/files/KQrHHTGU9BKAX4iXpBCC/pages/Y5meDzXaD8uaE629pU4y
Utility Functions/files/4dK946byRmmvxHpcPH1e/pages/BBgGtpTQvejMJWvFxbKS
# Registry The player registry handles the creation, tracking, and lifecycle of all active player objects in BDSC. It provides functions to: * Create and register new players * Access and remove player objects * Save player state * Retrieve client-side replicated data This system is core to how BDSC manages players internally. \ Use these functions to safely access and interact with player objects. *** ## Server *** Creates and registers a player object from a source ID. #### Parameters * `source`: `number` #### Returns * `boolean` ```lua bdsc.create_player(source) ``` *** ### add\_player Adds a player object to the internal registry.\ Realistically this should never need to be called externally, this is handled internally on object creation. #### Parameters * `player`: `table` #### Returns * `boolean` ```lua bdsc.add_player(player) ``` *** ### remove\_player Removes a player from the internal registry. #### Parameters * `source`: `number` #### Returns * `boolean` ```lua bdsc.remove_player(source) ``` *** ### get\_players Retrieves all currently registered players. #### Returns * `table` ```lua local all_players = bdsc.get_players() ``` *** ### get\_player Retrieves a specific player object from the registry. #### Parameters * `source`: `number` #### Returns * `table|nil` ```lua local player = bdsc.get_player(source) ``` *** ### save\_players Calls `:save()` ```lua bdsc.save_players() ``` *** ## Client *** ### get\_player\_data Retrieves replicated client-side player data. #### Returns * `table` ```lua local data = bdsc.get_player_data() ``` # Player Object The player object provides a clean public interface for interacting with a specific player in BDSC. Each player is represented by a dynamically extendable object that supports: * Accessing and modifying custom data * Syncing values to the client * Adding and running namespaced methods * Lifecycle functions like `save()` and `destroy()` All logic attached to a player should go through this API — not directly via internal tables.\ Use `bdsc.get_player(source)` to retrieve the player object, then call methods like `player:get_data()` or `player:run_method(...)` to interact with it. *** ## has\_data Check if the player has a data namespace assigned. #### Parameters * namespace: `string` #### Returns * `boolean` – True if it exists. ```lua player:has_data("stats") ``` *** ## get\_data Retrieve data from a specific namespace. #### Parameters * namespace: `string` #### Returns * `table|any` ```lua local stats = player:get_data("stats") ``` *** ## add\_data Add a new data namespace to the player. #### Parameters * namespace: `string` * value: `any` * replicated?: `boolean` #### Returns * `boolean|nil` ```lua player:add_data("stats", { health = 100 }, true) ``` *** ## remove\_data Delete an existing data namespace. #### Parameters * namespace: `string` ```lua player:remove_data("stats") ``` *** ## set\_data Update values inside an existing namespace (must be a table). #### Parameters * namespace: `string` * updates: `table` * sync?: `boolean` #### Returns * `boolean` ```lua player:set_data("stats", { health = 80 }, true) ``` *** ## sync\_data Force replication of a namespace to the client. #### Parameters * namespace?: `string` ```lua player:sync_data("stats") ``` *** ## update\_user\_data Update a value inside the persistent user block and propagate it to storage. #### Parameters * key: `string` * value: `any` ```lua player:update_user_data("rank", "admin") ``` *** ## add\_method Add a new dynamic method to the player. #### Parameters * namespace: `string` * name: `string` * fn: `function(player, ...)` ```lua player:add_method("combat", "take_damage", function(self, amount) local stats = self:get_data("stats") stats.health = stats.health - amount end) ``` *** ## remove\_method Remove a method from the player. #### Parameters * namespace: `string` * name: `string` ```lua player:remove_method("combat", "take_damage") ``` *** ## has\_method Check if a player has a method defined. #### Parameters * namespace: `string` * name: `string` #### Returns * `boolean` ```lua if player:has_method("combat", "take_damage") then ... end ``` *** ## run\_method Execute a method that was added to the player. #### Parameters * namespace: `string` * name: `string` * ...: any #### Returns * `any` ```lua player:run_method("combat", "take_damage", 25) ``` *** ## save Call `on_save()` method for all namespaces if defined. ```lua player:save() ``` *** ## destroy Triggers `on_destroy()` for all namespaces if defined, saves the player, and unregisters it. ```lua player:destroy() ``` *** # Utility BDSC includes a small set of shared utility functions to support logging, translation, and time formatting. \ \ These functions are available globally under the `bdsc` namespace and work in both server and client environments. They are intentionally minimal, with no external dependencies or unnecessary abstraction. *** ## get\_current\_time Returns the current system time as a formatted string. #### Returns * `string` ```lua bdsc.get_current_time() ``` *** ## log Prints a debug message to the console if `bdsc.debug_mode` is enabled.\ Supports standard log levels for easier development debugging. #### Parameters * level: `string` * message: `string` ```lua bdsc.log(level, message) ``` *** ## translate Retrieves a translation string by key and applies optional formatting arguments.\ Falls back to key and values if translation is missing. #### Parameters * key: `string` * ...: `any` #### Returns * `string` ```lua bdsc.translate(key, ...) ``` *** # Vendors {% hint style="warning" %} ### Beta Release Script is currently a BETA release until some customer feedback has been received. Things may change and be adjusted. {% endhint %}
*** # Guides # Creating Vendors Creating new vendors is straight forward.\ Follow the steps below and you will have as many vendors as you want setup in no time at all. *** ## Step 1. Setting Up Locations The order of the steps does not really matter but for tutorial sake we will start here. Open the `data` folder followed by the `locations.lua` file.\ Here you can define new locations within the module: ```lua return { some_general_store = { type = "general", label = "Some General Store", coords = vector4(-306.99, -971.24, 31.08, 159.15), payment_types = { "balance", "item" }, can_access = function() return true end, } } ``` #### Options * **key** - A unique key ID to represent the store. * **type** - A type for the store, this is important, it connects with your items. * **label** - A readable label for UI display. * **coords** - Coordinates to spawn the store ped and display blip if enabled, this is also used for server side validation. * **payment\_type** - The types of payment the vendor will accept. * **balance** - Any balance type for frameworks; "cash", "crypto", "bank", etc. * **item** - Any item registered in your server, trade bread for pistols if you really want. * **can\_access** - Function used for adding custom restrictions to open the vendor. #### Restricting Vendor Access You can restrict access to a vendor by utilising the `can_access` function.\ Here is a quick example of restricting a vendor so players cannot access it from within a vehicle. ```lua can_access = function() return not IsPedInAnyVehicle(PlayerPedId()) end ``` *** ## Step 2. Setting Up Peds Once you have setup a location and decided what `type` you are using for your vendors, open the `peds.lua` file and create an entry for your new vendor type: ```lua return { general = { model = "mp_m_shopkeep_01", scenario = "WORLD_HUMAN_AA_COFFEE", networked = false } } ``` #### Options * **key** - The connects to your vendor type created in Step 1. * **model** - The ped model to spawn. * **scenario** - The world scenario to run on the ped. * **networked** - Network flag for ped spawning *** ## Step 3. Setting Up Blips The next step is setting up your blip for the vendor: ```lua return { general = { label = "General Store", sprite = 52, colour = 0, scale = 0.6, enabled = true } } ``` #### Options * **key** - The connects to your vendor type created in Step 1. * **label** - A readable label for UI display. * **sprite** - ID of sprite to use. * **colour** - Colour for sprite. * **scale** - The scale of blip on the map. * **enabled** - If false blip will not be added to locations. *** ## Step 4. Setting Up Items Now the main sauce of the script.\ You can set any items you want, define whatever prices you want, using any money type or other item you want. You can build up your items list like so: ```lua return { test_item = { label = "Test Item", image = "test_item.png", description = "This is just an example test item.", locations = { "general", "medical" }, categories = { "test", "food" }, stock = 500, prices = { cash = { type = "balance", value = 5 }, bank = { type = "balance", value = 10 }, crypto = { type = "balance", value = 2 }, bread = { type = "item", value = 5 }, water = { type = "item", value = 5 } } } } ``` Options * **key** - Unique identifier for the item. * **label** - A readable label for UI display. * **description** - A readable description for the item. * **locations** - The vendor types the item can be shown in, e.g. this item could be purchased from "general" or "medical" vendors. * **categories** - Categories to place the item in, any unique categories will generate the UI page tabs. * **stock** - The amount of stock the item has this is refreshed every 5 minutes by 25% on default settings. * **prices** - The prices the item can be purchased for * **key** - Unique item or balance for your server * **type** - The money type players can purchase for * **balance** - Any framework balance type; "cash", "crypto", "bank" etc. * **item** - Any registered item in your server. * **value** - The price of the item Thats it now your good to go! *** ## Summary * Create a new location in `locations.lua` * Setup blips and peds for the vendor type in `blips.lua` and `peds.lua` * Define your items within `items.lua` * Restart and go. *** # Installation Getting setup with the Vendor script is straight forward.\ Just follow the steps below and you'll be selling your nan's favourite cat in no time. *** {% stepper %} {% step %} ### Download Once you have purchased your resource download it from **Keymaster** {% endstep %} {% step %} ### Adding The Resource After downloading the resource extract and add it into your server resources. {% endstep %} {% step %} ### Ensure It Add `ensure vendors` to your `server.cfg` {% endstep %} {% step %} ### Downloading Dependencies Get the latest release versions of our dependency resources if you do not already have them: * [**BOII Development Tool Kit**](https://github.com/boiidevelopment/bdtk/releases) * [**BOII Development UI Kit**](https://github.com/boiidevelopment/bduk/releases) {% endstep %} {% step %} ### Adding The Dependencies Add the `bdtk` & `bduk` resource into your server, and ensure them.\ Your order should be like so: ``` ensure bduk ensure bdtk # must be started before vendors ensure vendors ``` {% endstep %} {% step %} ### Resource Configuration For resource configuration read the following guide: [**Creating Vendors**](/fivem-paid-resources/vendors/guides/creating-vendors) {% endstep %} {% step %} ### Restart Your Server Restart your server and you will be good to go, start buying guns for beans, or fake ids for empty bottles... skies the limit. {% endstep %} {% endstepper %} # Configuration Script configuration boils down to a small set of `convars` and static data files.\ Convars overrides can be set in your `server.cfg` or you can leave them as default. Defining new locations, items, blips and peds can be done through the `data` files.\ For more on this read [**Creating Vendors**](/fivem-paid-resources/vendors/guides/creating-vendors). *** ## Convar Settings You can override the default settings of these convars within your `server.cfg` for more about convars read: [**FiveM Docs - Convars**](https://docs.fivem.net/docs/scripting-reference/convars/). ```lua vendors.language = GetConvar("vendors:language", "en") vendors.locale = exports.bdtk:get("locales." .. vendors.language, true) or {} vendors.image_file_path = GetConvar("vendors:image_file_path", "nui://vendors/images/") vendors.debug_mode = GetConvar("vendors:debug_mode", "false") == "true" vendors.debug_colours = { reset = "^7", debug = "^6", info = "^5", success = "^2", warn = "^3", error = "^8", critical = "^1", dev = "^9" } vendors.restock_time = GetConvar("vendors:restock_time", "5") vendors.restock_percentage = GetConvar("vendors:restock_percentage", "25") vendors.force_dui = GetConvar("vendors:force_dui", "false") == "true" vendors.target = not vendors.force_dui and (GetResourceState("ox_target") == "started" and "ox_target" or GetResourceState("qb-target") == "started" and "qb-target") or nil ``` *** # List Inventory {% hint style="danger" %} ### BETA RELEASE This is currently a **BETA** release, some issues are to be expected but they will be fixed asap!\ Any additional systems requested can be added down the line. \ \ If you have purchased the **BETA**, you're appreciated :heart: {% endhint %}
**A flashback to inventory systems that made sense — now modernized, modularized, and way less ugly.** **Not a Grid. Not a Puzzle. Just an Inventory.** Built using BDUK’s flexible card UI - think old-school MMOs with 2025 - level extensibility. \ It’s everything you liked about classic inventories, without the trash fires. *** ## What Is This Inventory? A clean, fully modular inventory system that works out of the box with: * Player inventories * Containers (trunks, fridges, drops, whatever) * Item rarities * Item degradation * Containers providing quality preservation * Stack splitting & transfers * Props, animations, and usable item logic * Weapon handling with ammo + attachments * Weapon serial codes * Weapon allow-list and clearing Oh, and it looks good too. Because we're not savages. *** ## Who It’s For It was built mainly as a working project to learn about inventory systems and provide a different take on to inventory scene, so for anyone tired of inventory systems that: * Fight you at every turn * Are bolted onto old RP frameworks * Have 8000 exports to transfer a sandwich If you’re building a survival system, hardcore PvP loot loop, or just want something actually usable without 40 dependencies - this is it. #### You get: * Simple list-based logic (no weight shenanigans) * Clean object-oriented design * Proper registry-based item actions * A working item degradation system (yes, actually works) * Support for quick use, props, tooltips, and serials *** ## What It Supports * **Player + Container Inventories**\ Uses factory-based logic and clean public/private method splitting.\ Containers include drops, trunks, gloveboxes, fridges, lockers, etc. * **Modular Actions**\ Each item can have custom `use`, `modify`, whatever.\ Global actions include: * Use * Drop (full/partial) * Split * Transfer (all/amount) * Modify (attachments, plus more soon..) * **Attachments & Weapons**\ Weapons support: * Serial numbers * Ammo types (via items) * Attachments (client component sync) * Persistent state per item * **Item Degradation**\ Items can lose quality over time - some containers block degrade to preserve items (like fridges).\ That moldy sandwich? Yeah, it’s coming for you. * **Stylized Tooltip Cards**\ Hover. Flex. Cry at the quality stat slowly ticking down. * **BDUK UI Integration**\ Uses the full power of the modal and card system. Minimal performance cost. Max vibes. *** ## Structure ```bash list_inventory/ │ ├── core/ │ ├── actions/ # All transferable/useable logic: use, drop, split, transfer, modify │ ├── containers/ # Container logic: creation, syncing, methods │ ├── lib/ # Utility functions (slots, item formatting) │ ├── player/ # Player inventory logic │ ├── client.lua # UI and client-side actions │ ├── degrade.lua # Quality / durability logic │ └── registry.lua # Item registry (on_use hooks etc.) │ ├── data/ # Preloaded definitions (items, containers, vehicles) ├── images/ # Item icons ├── locales/ # i18n (default: en.lua) ├── wrappers/ # Framework support (QBCore, bdsc, + more asap) ├── fxmanifest.lua # Manifest ├── install.sql # Install schema └── init.lua # Boot logic and base configuration ``` *** ## Quick Install No 300-step wizard. Just drop and go. 1. Drop into your resources folder 2. Ensure your framework wrapper is configured (`qb.lua`, `bdsc.lua`) 3. `ensure list_inventory` in your server.cfg 4. Run the included SQL file 5. Enjoy. *** ## Why List, Though? Grid inventories are fine… if you like visual Sudoku every time you pick up a bottle of water. This isn’t for that. `list_inventory` is: * **Fast to use** * **Easy to extend** * **Good for gameplay loops where layout doesn’t matter** * **Still sexy enough to feel modern** Want a grid or slot inventory? Go write one *(or wait for ours)*. \ Want to *play* your game? Use this. *** ## Notes This is a **beta** release. That means: * There *will* be edge cases. * We *might* bully you if you ignore the docs. * But we’re also here to fix bugs and improve it. This isn’t a toy system — it’s powering survival, PvP, and loot-heavy servers already.\ You get full source access. Extend it. Break it. Fork it. Just don’t complain when your fridges explode because you renamed a method called `degrade_item`. # Guides These guides cover how to get started using the list inventory system from core functionality like creating containers and adding items, to more advanced setups like custom items, weapon logic, and integration with vehicles. Whether you're building a survival system, a loot-based PvP mode, or just want clean inventory logic — start here. Use the cards below to dive into each guide. ***
Creating & Using Containers/files/LPciOP66eipXdqlq5QWC/pages/iZKfMe2Fysue5LfvEu0U
Creating Items/files/zcj7sPMp1vekeVxf226W/pages/ya0wpRE8wyv9rVZUWaNY
Customising Vehicle Inventories/files/NLCpFC68DmhT03aLvATr/pages/7U9Nc380iWCcGTbhAXVz
# Creating & Using Containers Containers are shared, slot-based inventories that can be created dynamically or pre-defined for vehicles, world drops, fridges, etc. They support the same clean method API as player inventories. *** ## Creating a Container Use the `create_container` export **from the server** to create any container: ```lua local data, err = exports.list_inventory:create_container("world", "fridge", { owner = "house_7", coords = vector3(123.4, 456.7, 789.0), persist = true }) ``` #### Params | Name | Type | Description | | ---------- | -------- | -------------------------------------------- | | `category` | `string` | Logical group (`world`, `vehicle`, etc.) | | `subtype` | `string` | Container type (`fridge`, `drop`, etc.) | | `options` | `table` | Metadata: `owner`, `coords`, `persist`, etc. | *** ## Getting a Container Use `get_container(id)` to retrieve an active container object: ```lua local container = exports.list_inventory:get_container("trunk:ABC123") if not container then return end ``` Once retrieved, you can use any container method: ```lua container:add_item("bandage", 2) ``` *** ## Container Methods All container objects support these public methods: * `add_item(id, amount, metadata)` * `remove_item(lookup, amount)` * `split_item(slot, amount)` * `get_items()` / `get_item(lookup)` * `has_item(lookup, amount)` * `clear_items()` * `save()` / `sync()` * `get_data(key)` / `set_data(key, value)` *** ## Default Container Types Container types and defaults are defined in `data/containers.lua`. You can modify these or add your own. #### Vehicles | Type | Default Slots | Category | | ---------- | ------------- | --------- | | `trunk` | 100 | `vehicle` | | `glovebox` | 10 | `vehicle` | | `trailer` | 120 | `vehicle` | #### Loot & Drops | Type | Default Slots | Category | Extras | | --------- | ------------- | -------- | ------------------------- | | `drop` | 200 | `loot` | Bag prop, outlines red | | `airdrop` | 50 | `loot` | Crate prop, outlines blue | #### Storage Containers | Type | Default Slots | Category | Notes | | ------------- | ------------- | --------- | --------------------------- | | `desk_fridge` | 5 | `storage` | quality\_preservation = 1.5 | | `mini_fridge` | 40 | `storage` | quality\_preservation = 2.0 | | `fridge` | 40 | `storage` | prevent\_spoil = true | You can define props, outline styles, and special logic like spoilage blocking or preservation multipliers. *** ## Temporary Drops Drop containers (category `loot`, subtype `drop`) are temporary. When emptied, they are: * Deleted from server memory * Removed from the client UI These are handled internally when a player drops an item however you could make one if you want too, why not? Who said you cant. ```lua local coords = GetEntityCoords(GetPlayerPed(source)) exports.list_inventory:create_container("loot", "drop", { owner = "drop_" .. source, coords = coords, persist = false }) ``` *** ## Notes * Containers use **slot limits**, not weights * Some types (like fridges) can prevent degradation or slow it if enabled * If a persistent container already exists for an `owner`, it will be loaded instead of recreated * You can define **your own** container types freely, provided ones are purely example Stay slotted, stay chill.™ # Creating Items Items are defined via a shared `item_list` table, stored in `data/items.lua`. \ Each item is fully data-driven and supports data, actions, props, degradation, attachments, and more. Below are fully built examples covering the major item types: *** {% hint style="warning" %} Statuses support is coming very soon please bare rebuilding another system currently, once complete a `modifiers.statuses = {}` section will be added. {% endhint %} ## Consumable Items A stackable consumable item with an animation and prop attachment. ```lua water = { id = "water", label = "Water", description = { "A refreshing bottle of clean water.." }, image = "water.png", stackable = 10, data = { rarity = "common", degrade_rate = 0.25, quality = 100 }, actions = { use = { animation = { progress = { type = "circle", message = "Drinking Water..", segments = 30, gap = 3 }, dict = "mp_player_intdrink", anim = "loop_bottle", flags = 49, duration = 5000, freeze = false, continuous = false, props = { { model = "ba_prop_club_water_bottle", bone = 60309, coords = { x = 0.0, y = 0.0, z = -0.05 }, rotation = { x = 0.0, y = 0.0, z = 0.0 }, is_ped = true, sync_rot = true } }, callback = function(_src, slot) TriggerEvent("list_inventory:sv:remove_item", _src, slot) end } }, drop = true } } ``` *** ## Ammo Items Ammo items store bullet count and are used to reload compatible weapons. ```lua ammo_pistol = { id = "ammo_pistol", label = "Pistol Ammo", description = { "A clip of pistol ammo" }, image = "ammo_pistol.png", data = { rarity = "common", ammo_count = 12 }, actions = { use = function(source, slot, id, def) add_ammo_to_weapon(source, slot, id, def) end, drop = true } } ``` *** ## Weapons Weapons track serials, ammo, durability, and can be modified with attachments.\ Serials are automatically assigned to weapons if one does not already exist. ```lua weapon_pistol = { id = "weapon_pistol", label = "Pistol", description = { "A standard semi-automatic 9mm handgun.", "Can be purchased from any ammunation." }, image = "weapon_pistol.png", data = { rarity = "common", serial = "", -- assigned on add_item ammo = 0, ammo_types = { "ammo_pistol" }, attachments = {}, degrade_rate = 0.25, durability = 100 }, actions = { use = function(source, slot, id, def) use_weapon(source, slot, id, def) end, modify = true, drop = true } } ``` *** ## Weapon Attachments Attachments use `modifiers.attachments` to define compatibility with weapons and GTA components. ```lua pistol_mag_extended = { id = "pistol_mag_extended", label = "Extended Mag: Pistol", description = { "Extended magazine for supported 9mm pistols." }, image = "pistol_mag_extended.png", data = { rarity = "rare" }, modifiers = { attachments = { { weapon = "weapon_pistol", component = "COMPONENT_PISTOL_CLIP_02" }, { weapon = "weapon_heavypistol", component = "COMPONENT_HEAVYPISTOL_CLIP_02" } } }, actions = { drop = true } } ``` *** ## Notes * Use `data` to define any item-specific metadata (quality, ammo, serials, etc.) * `actions.use` supports either a full animation table or a function * Use `modify = true` on weapon actions to enable the modification UI * Attachments are matched to weapons using `modifiers.attachments` * Avoid mixing `quality` and `durability` in a single item (visual conflict) * Clothing as items & consumables status modifying coming **very soon** This structure supports **deep customization** with minimal boilerplate. New item types can be added by following these patterns. Want to define a new item? Just copy one of these and tweak the fields. # Customising Vehicle Inventories Vehicle inventories (trunk + glovebox) are automatically assigned based on vehicle class or model. \ You can override defaults for specific vehicles, or rely on fallback class-based sizes. *** ## Defaults (By Class) If a specific vehicle model is **not defined**, the system will fall back to these default sizes: | Class | Trunk | Glovebox | | ------------ | ----- | -------- | | `compact` | 60 | 4 | | `sedan` | 70 | 6 | | `suv` | 80 | 6 | | `coupe` | 60 | 4 | | `muscle` | 70 | 5 | | `sports` | 50 | 5 | | `super` | 40 | 4 | | `motorcycle` | 16 | 2 | | `offroad` | 90 | 6 | | `industrial` | 120 | 6 | | `utility` | 100 | 6 | | `van` | 110 | 6 | | `service` | 90 | 6 | | `emergency` | 100 | 8 | | `military` | 130 | 10 | | `commercial` | 120 | 8 | *** ## Custom Model Overrides To override default inventory for a **specific vehicle**, just define it directly by model name: ```lua adder = { trunk = 35, glovebox = 10 } ``` This will override both the class defaults and any fallback behavior. *** ## Notes * All values are **slot-based**, not weight-based. * Containers are created automatically when you access the vehicle trunk or glovebox. * Custom sizes allow better balancing for loot-heavy or RP-specific vehicles. * Do have plans to add in a `trailer` type for vehicles, soon as I get round to it, if people want it. To modify these, just update `data/vehicles.lua` with new entries or changes. # API The API documentation covers two main API sections: #### Player This section covers all available methods for working with player inventories. * Add / remove / split items * Get or check item presence * Sync and save player data * Use metadata, durability, attachments, and more #### Container This section handles logic for world containers, such as: * Loot drops * Vehicle trunks * Fridges or persistent storage Supports all standard inventory functions: * Add, remove, split, sync * Metadata support * Optional persistence to MySQL ***
/files/KQrHHTGU9BKAX4iXpBCC/pages/AAegA9IM9ROjp8WPVEt6
/files/LPciOP66eipXdqlq5QWC/pages/0wmBwonz10mHjl4FVuC0
# Player Before using any **player inventory methods** (`add_item`, `has_item`, `get_item`, etc.), you **must first retrieve the player inventory object** using the provided export: ```lua local player = exports.list_inventory:get_player(source) ``` This returns the full player inventory object, with all public methods attached.\ Then you can use the methods below like so: ```lua RegisterCommand("give_bread", function(source) local player = exports.list_inventory:get_player(source) if not player then print("Inventory not found") return end player:add_item("bread", 1) end) ``` *** ## create\_player\_inventory Create a player inventory object and attach methods/data. #### Params * `source` (number): The player source #### Returns * Player inventory object or `false` ```lua local player = exports.list_inventory:create_player_inventory(source) ``` *** ## get\_player Returns the inventory object for the given player. #### Params * `source` (number): The player source #### Returns * Player inventory object or `nil` ```lua local inv = exports.list_inventory:get_player(source) ``` *** ## add\_item Adds an item to the inventory, optionally with metadata. #### Params * `id` (string): Item ID * `amount` (number): Quantity * `item_data` (table, optional): Item metadata (e.g., quality, serial) #### Returns * `true` on success, or `false, reason` on failure ```lua player:add_item("water", 2, { quality = 100 }) ``` *** ## remove\_item Removes item(s) by slot, ID, or metadata. #### Params * `lookup` (number|string|table): Slot number, item ID, or metadata table * `amount` (number): Amount to remove #### Returns * `true` on success, `false` otherwise ```lua player:remove_item(1, 1) -- slot player:remove_item("bread", 1) -- ID player:remove_item({ quality = 50 }, 1) -- metadata ``` *** ## has\_item Checks if inventory contains item by slot, ID, or metadata. #### Params * `lookup` (number|string|table): Slot number, item ID, or metadata table * `amount` (number): Amount required (default: 1) #### Returns * `true` if found, otherwise `false` ```lua player:has_item("water", 2) ``` *** ## get\_item Returns the first matching item by slot, ID, or metadata. #### Params * `lookup` (number|string|table): Slot number, item ID, or metadata table #### Returns * Item object or `nil` ```lua local item = player:get_item("water") ``` *** ## get\_items Returns a table of all items in the inventory. #### Returns * `table`: All items indexed by slot ```lua local items = player:get_items() ``` *** ## set\_data Sets a custom data field on the inventory. #### Params * `key` (string): Field name * `value` (any): Value to store #### Returns * `true` ```lua player:set_data("weight", 500) ``` *** ## get\_data Gets a specific or all data values from the inventory. #### Params * `key` (string, optional): Field name #### Returns * Value of the field or full data table ```lua local weight = player:get_data("weight") ``` *** ## has\_data Checks whether a custom data key exists. #### Params * `key` (string): Field name #### Returns * `true` if exists, `false` otherwise ```lua if player:has_data("slots") then ... end ``` *** ## update\_item\_data Updates the metadata for a specific slot. #### Params * `slot` (number|string): Slot number * `new_data` (table): New metadata to merge in #### Returns * `true` on success, `false` on failure ```lua player:update_item_data(1, { durability = 80 }) ``` *** ## split\_item Splits a stack in one slot into a new one. #### Params * `slot` (number|string): Source slot * `amount` (number): Amount to split #### Returns * `true` on success, `false` otherwise ```lua player:split_item(1, 3) ``` *** ## clear\_items Removes all items from the inventory. #### Returns * `true` ```lua player:clear_items() ``` *** ## save Saves the current inventory state to the database. #### Returns * `true` on success, `false` on failure ```lua player:save() ``` *** ## sync Syncs the inventory with the client. ```lua player:sync() ``` # Containers Before using any **container methods** (`add_item`, `remove_item`, `has_item`, etc.), you must first retrieve the container object using the following export: ```lua local container = exports.list_inventory:get_container(id) ``` This returns the active container object for the given `id`, complete with all public methods.\ Then you can use the methods below on the container like so: ```lua local container = exports.list_inventory:get_container("some_container_id") if not container then print("No container found for that ID") return end container:add_item("bandage", 2) ``` *** ## get\_data Get a specific field or the full container data. #### Params * `key` (string, optional): The key to fetch #### Returns * Value of the key or full data table ```lua local coords = container:get_data("coords") ``` *** ## set\_data Set a custom field on the container. #### Params * `key` (string): Field name * `value` (any): Value to store #### Returns * `true` ```lua container:set_data("custom_label", "Loot Crate") ``` *** ## get\_items Returns a table of all items in the container. #### Returns * `table`: All container items indexed by slot ```lua local items = container:get_items() ``` *** ## get\_item Returns the first matching item by slot, ID, or metadata. #### Params * `lookup` (number|string|table): Slot number, item ID, or metadata table #### Returns * Item object or `nil` ```lua local item = container:get_item("bandage") ``` *** ## has\_item Checks if container contains an item by slot, ID, or metadata. #### Params * `lookup` (number|string|table): Slot number, item ID, or metadata table * `amount` (number): Amount required (default: 1) #### Returns * `true` if found, otherwise `false` ```lua if container:has_item("weapon_pistol", 1) then ... end ``` *** ## add\_item Adds an item to the container. #### Params * `id` (string): Item ID * `amount` (number): Quantity * `item_data` (table, optional): Item metadata (e.g., quality, custom props) #### Returns * `true` on success, or `false, reason` on failure ```lua container:add_item("ammo_pistol", 24) ``` *** ## remove\_item Removes item(s) by slot, ID, or metadata. #### Params * `lookup` (number|string|table): Slot number, item ID, or metadata table * `amount` (number): Amount to remove #### Returns * `true` on success, `false` otherwise ```lua container:remove_item("bandage", 2) ``` *** ## split\_item Splits a stack in one slot into a new slot. #### Params * `slot` (number|string): Source slot * `amount` (number): Amount to split #### Returns * `true` on success, `false` otherwise ```lua container:split_item(1, 5) ``` *** ## clear\_items Removes all items from the container. #### Returns * `true` ```lua container:clear_items() ``` *** ## save Persists the container to the database (if marked as persistent). #### Returns * `true` on success, `false` on failure ```lua container:save() ``` *** ## sync Sends container inventory state to all clients. ```lua container:sync() ``` # Planting System {% hint style="danger" %} ### BETA RELEASE Resource is currently a BETA release.\ It will be moved away from this as soon as some feedback has been received. {% endhint %}
A planting and growing system that actually feels like part of a game not just a background timer with a leaf prop on it. Players plant seeds. \ They water them, feed them, cure them, and eventually harvest crops.\ \ It works in survival. \ It works in roleplay. \ It works in your weird PvEvRP crafting wasteland. No spaghetti timers. \ No bloated “greenhouse frameworks.” \ Just a sane, configurable system for growing, harvesting, and enabling your virtual agriculture dreams. *** ## Who It’s For #### Anyone building: * Survival systems with food loops * Farming jobs that aren’t just "press E to get paid" * Drug production (yes, you can grow weed with it if you want) * Anything where players interact with the environment and want stuff to grow over time #### Built for people who: * Want plants that change, not just sit there * Need growth systems that respect environment (altitude, weather, soil) * Like reward balancing (yield, XP, condition chances) * Hate systems that make you duplicate 400 lines to add a single tomato *** ## What It Does * Plant seeds, grow crops, harvest rewards * Water, fertilize, cure, repeat * Dynamic model stages with thresholds * Supports pests and diseases with progressive effects * Environmental modifiers (altitude, weather, ground type) * Yield tuning (min/max, seed drop chance, etc) * XP rewards for every action * Optional item dependencies (shears, watering cans, fertilizer) * DUI or target-based interaction support * Fully data-driven. Define 1 plant or 50 — no extra logic needed. *** ## What It Doesn’t Do * Doesn’t force you into a farming simulator * Doesn’t care what framework core you're running * Doesn’t hardcode map zones or interaction logic * Doesn’t blow up if someone forgets to water once * Doesn’t assume every crop is weed *** ## Quick Setup 1. Drop into your server 2. Add or adjust plant/pest/disease definitions 3. Trigger interactions via DUI or targeting 4. Watch stuff grow No bizarre state machines. No obscure exports. Just simple straight forward code. *** ## In Summary If you want players to actually **plant** and **grow** things and not just spam use a bush, this is for you.\ \ It’s fully configurable. \ It plays nice with your server. \ And it makes planting not suck as much.. maybe... # Guides This section covers everything you need to configure, extend, and actually use the growing system. Whether you're adding new crops, tweaking yield balance, introducing pests, or tying it into your own survival or economy systems these guides break it down by topic. ***
Adding Plants/files/cZNCydEyjjGk9Q8CQJ7B/pages/lYhwtZFi7e1r2cJRaZ7y
Adding Pests & Diseases/files/Zf9823LvEC8JkyR861EI/pages/VZEBvQ0fI5A3EpHFNedw
Adjusting Environment/files/KAcpbxZLC7zNu039waZe/pages/LzvyGZ6u9lDIMtDnDcZ4
# Adding Plants This guide covers how to define new plant types in the `data/plants.lua` static configuration file. Each plant entry defines how that plant behaves in the growing system covering growth stages, item requirements, XP rewards, environmental resistances, and yield. *** ## Default Values The `defaults` table defines shared values that are inherited by all plants unless explicitly overridden. #### Example: `defaults` ```lua plants.defaults = { image = "plant_icon.png", should_outline = true, outline_colour = { r = 100, g = 200, b = 100 }, preferred_altitude = { min = 0, max = 2000 }, stages = { { stage = 1, model = "prop_veg_crop_03_cab", threshold = 0 }, { stage = 2, model = "prop_veg_crop_03_cab", threshold = 25 }, { stage = 3, model = "prop_veg_crop_03_cab", threshold = 50 }, { stage = 4, model = "prop_veg_crop_03_cab", threshold = 75 }, { stage = 5, model = "prop_veg_crop_03_cab", threshold = 100 } }, resistances = { altitude = 1, disease = 1, pest = 1, soil = 1, weather = 1 }, yield = { min = 2, max = 6, seed_chance = 0.2, seed_factor = 0.2 }, xp = { water = { min = 2, max = 6 }, fertilize = { min = 2, max = 6 }, harvest = { min = 3, max = 9 }, plant = { min = 1, max = 4 }, cure = { min = 1, max = 4 } }, water_item = { id = "watering_can_full", label = "Watering Can (Full)", min = 10, max = 20 }, fertilizer_item = { id = "fertilizer", label = "Basic Fertilizer", min = 5, max = 10 }, harvest_item = { id = "trimming_shears", label = "Trimming Shears" } } ``` *** ## Adding a New Plant Each plant is defined as a key in the returned table. All properties are optional and will fall back to `defaults` if omitted. #### Example: Cabbage ```lua plants.cabbage = { label = "Cabbage", image = "cabbage.png", xp = { water = { min = 2, max = 5 }, fertilize = { min = 2, max = 5 }, harvest = { min = 4, max = 8 }, plant = { min = 2, max = 4 }, cure = { min = 1, max = 3 } } } ``` Only XP values and image are overridden. All other values will use the shared `defaults`. #### Example: Tomato with Custom Stages ```lua plants.tomato = { label = "Tomato", image = "tomato.png", stages = { { stage = 1, model = "prop_veg_crop_01", threshold = 0 }, { stage = 2, model = "prop_veg_crop_01", threshold = 25 }, { stage = 3, model = "prop_veg_crop_01", threshold = 50 }, { stage = 4, model = "prop_veg_crop_01", threshold = 75 }, { stage = 5, model = "prop_veg_crop_01", threshold = 100 } } } ``` This overrides the stage models but inherits everything else. *** ## Automatic Rewards Each plant automatically generates two reward items unless manually defined: * A crop item: `{id = "_crop", label = "