The Advanced Gyms System is a comprehensive FiveM resource that adds realistic gym mechanics to your server. Players can purchase memberships, work out on various equipment, build skills like Stamina and Strength, and compete on punching machine leaderboards. The system includes a fatigue system to prevent spam and injury mechanics for added realism.
Can I use this without gym MLO maps?
While the system is designed to work with gym MLO interiors, you can technically configure zones in any location. However, for the best player experience, we recommend using dedicated gym MLO maps. Several free and paid options are compatible (see Installation guide).
Is this resource optimized?
Yes! The resource uses efficient zone detection, optimized database queries with proper indexing, and minimal performance impact during idle states. The skill degradation and fatigue recovery systems run on configurable timers to minimize server load.
Installation Questions
The resource won't start, what's wrong?
Common causes:
Missing Dependencies - Ensure TMC Framework core is loaded first
SQL Not Run - Verify you've executed the SQL file to create required tables
Incorrect Export - Check config.lua has the correct core export name
File Structure - Ensure all folders (gym/, punchingmachines/, html/, stream/) are present
Check your server console for specific error messages.
How do I add the membership items to my inventory?
Copy the item definitions from items.md (included with the resource) into your inventory system's item configuration file. Make sure the item names in your inventory config match exactly with the item names in configGyms.lua.
Don't forget to add the corresponding item images to your inventory's image directory!
Database tables aren't creating, help?
Check Permissions - Ensure your database user has CREATE and ALTER privileges
Manual Execution - Run the SQL commands one at a time to identify which fails
Existing Columns - If columns already exist, the IF NOT EXISTS clause should prevent errors
MySQL Version - Ensure you're running MySQL 5.7+ or MariaDB 10.2+
Do I need to install all three gym MLO maps?
No! You only need to install the MLO maps for gyms you want to enable. In configGyms.lua, set enabled = false for any gyms you don't have the MLO for. You can enable or disable gyms at any time.
Configuration Questions
How do I change skill progression speed?
Edit the Config.Gyms.Skills.ProgressionPerWorkout values in configGyms.lua:
Yes! Set enabled = false in the degradation config:
How do I adjust gym membership prices?
In the BusinessSetup.memberships section for each gym, modify the price value:
Can I create more than two membership tiers?
Yes! You can add as many membership tiers as you want. Just add new entries to the memberships table:
Make sure to create corresponding items in your inventory system for each new tier.
How do I add more equipment locations?
Simply add more coordinate vectors to the equipment array in the gym's Tasks section:
Use /getcoords or a similar command to find exact coordinates.
Can I change how long workouts take?
Yes! Edit the WorkoutTime value (in milliseconds) for each equipment type:
Gameplay Questions
Why can't I use gym equipment?
There are several possible reasons:
No Membership - You need a valid membership for that gym
Wrong Tier - Your membership tier doesn't include that equipment type
Too Fatigued - Your fatigue level is too high (rest or use energy drinks)
Already Working Out - You're currently using another piece of equipment
Not in Gym - You're outside the gym's boundary zone
Check the notification message for the specific reason.
How does the fatigue system work?
Every workout increases fatigue in a specific category (Push, Pull, Core, Cardio, or Boxing). When fatigue gets too high (default 85%), you can't work out anymore. Fatigue decreases naturally over time, or you can use energy drinks to reduce it instantly.
Working out with high fatigue (above 75%) has a chance to cause injuries!
How do I reduce fatigue quickly?
Wait - Fatigue recovers passively over time (default: 1 point per 5 minutes)
Energy Drinks - Use gym-branded energy drinks to instantly reduce fatigue by 20 points
Leave and Return - Consider working out at a different gym to use fresh muscle groups
What happens if I get injured?
Injuries occur when working out with very high fatigue. When injured, you may experience:
Temporary health reduction
Movement speed penalty
Notification warning you to rest
The injury effects will wear off after a short period. This encourages players to manage their fatigue properly.
Do skills decrease over time?
Yes, if skill degradation is enabled (default). Skills decay slowly when not being worked on. The default settings check every 24 hours and reduce each skill by 1 point, but skills won't fall below their starting values (default 20%).
This encourages regular gym visits to maintain peak physical condition!
How does the punching machine scoring work?
The punching machine minigame challenges you to press randomly shown keys as quickly as possible:
Start Machine - Interact with a punching machine
Watch Screen - Random keys will appear
Press Keys - Press the correct keys before time runs out
Scoring:
Perfect completion (all keys, no misses) = 999 points
Partial completion = based on keys hit × multiplier
Failed attempt = based on keys hit × lower multiplier
Scores are saved to a leaderboard that all players can view!
Can employees workout for free?
Yes, if EmployeeWorkoutFree = true in the gym's BusinessSetup. Employees with the configured job can use all equipment without needing a membership.
How do memberships work?
Purchase - Visit the membership desk and choose a tier
Duration - Pay per day (e.g., 100 per day for 7 days = 700 total)
Receive Card - Get a physical membership card item
Access Equipment - The system automatically checks your membership when using equipment
Expiration - Memberships expire after the purchased duration
Renewal - Return to the desk to extend your membership
Business/Management Questions
How do I give someone a membership as an employee?
As a gym employee:
Be near the membership desk
Open the interaction menu
Select "Manage Memberships"
Choose the player
Select membership tier
Set duration (in days)
Confirm - the player receives their membership card
Where do membership payments go?
Membership payments are divided based on the ReturnPaymentsPercent setting:
100% - All money goes to the business bank account
50% - Half goes to business, half goes to the employee who sold it
0% - All money goes to the employee (not typical)
Most gyms use 100% to centralize revenue in the business account.
Can I see who has active memberships?
Yes! Gym employees can view all active memberships through the management interface. This shows:
Player name
Membership tier
Expiration date
Days remaining
How do I revoke a membership?
As a gym employee:
Open the membership management interface
Find the player's active membership
Select "Revoke Membership"
Confirm the action
The player's membership will be immediately deactivated (but they keep the card item).
Technical Questions
Can I customize the UI?
Yes! The UI files are located in the html/ directory:
index.html - Main structure and styling
digital.ttf - Custom font for the punching machine display
Modify the HTML/CSS to match your server's branding. The UI communicates with the client via NUI callbacks.
How are gym skills stored in the database?
Skills are stored in JSON format in the gym_skills column of the players table:
This allows for flexible skill data and efficient queries.
Can I add custom workout equipment types?
Yes, but it requires some scripting knowledge:
Add the equipment type to Config.Gyms.Equipment
Define coordinates in gym Tasks sections
Add prompt configuration in Config.Gyms.Locale.Prompts
Optionally add new animations in the client script
You may also need to create custom skill categories if your equipment doesn't fit existing ones.
How do I add sound effects?
The script supports the interactsound resource (optional). If you have interactsound installed:
Add sound files to interactsound's html/sounds/ directory
The script automatically plays sounds for:
Coin insertion (coininsert)
Bell sounds (bell)
Punch impacts (punch)
If interactsound isn't detected, the script works fine without sounds.
Can I sync gym stats with other resources?
Yes! Gym stats are stored in the player database and can be accessed by other resources:
You can use these values to influence other gameplay systems (e.g., sprint speed, max health).
Admin Commands
How do I view a player's gym stats?
Use the command:
This displays their current skill levels and fatigue values.
How do I reset a player's gym stats?
Use the command:
This resets all their skills back to default starting values (default: 20 for each skill).
How do I manually set a specific gym stat?
Use the command:
Example:
This sets player ID 1's Stamina to 75%.
Available skill names: Stamina, Stength (note the typo, kept for consistency), Lung Capacity
How do I clean up old punching machine scores?
Use the command:
This removes old/duplicate scores from the database, keeping only the top 5 scores per player. Run this periodically to prevent database bloat.
Troubleshooting
Players are getting stuck in workout animations
This can happen if the script stops unexpectedly. To fix:
Restart the resource: restart gymsv2
Affected players may need to relog
Check for Lua errors in console
Consider adding error handling or automatic animation cleanup on resource stop.
Gym zones aren't detecting players
Possible solutions:
Check MLO Load Order - Ensure the gym MLO loads before tmc-gyms
Verify Coordinates - Double-check boundary points match your MLO location
Test Z-Heights - Adjust minZ and maxZ values if gym is on multiple floors
Restart Resources - Try restart gymsv2 after the MLO loads
Membership desk isn't working
Verify:
Membership Zone Exists - Check configGyms.lua has a ['Membership'] zone defined
Correct Job - Ensure the employee has the job defined in BusinessSetup.job
Inside Boundary - Player must be within the gym's boundary zone
Resource Permissions - Check the job has correct permissions
Punching machines aren't spawning
Check:
Stream Files - Ensure stream/punchmachine/ folder exists with .ytyp files
fxmanifest.lua - Verify the data_file entries for custom props are present
Coordinates - Confirm the machine coordinates match your gym layout
Gym Enabled - Ensure the gym is set to enabled = true
Database errors when purchasing memberships
Common causes:
Missing Tables - Run the SQL file to create gym_memberships table
Column Mismatch - Verify your database schema matches the SQL file
Connection Issues - Check your database resource (oxmysql) is running
Invalid Data - Ensure item names exist in your inventory system
Check server console for specific SQL error messages.
Skills aren't increasing after workouts
Troubleshooting steps:
Check Console - Look for Lua errors when completing workouts
Verify Membership - Ensure player has valid membership for that equipment
Database Writes - Confirm gym_skills column exists in players table
Progression Config - Check ProgressionPerWorkout values aren't set to 0
Max Level - Player may already be at MaxSkillLevel (default 100)
Energy drinks aren't reducing fatigue
Verify:
Item Names - Check item names match in both inventory and consumableReduction config
Item Usage - Ensure the item is properly configured as useable in your inventory
Hook/Export - The resource needs to hook into item use events
Fatigue Enabled - Confirm fatigue system is enabled in config
Best Practices
Server Performance
Limit the number of equipment locations to what you actually need
Increase check intervals for degradation and recovery if you have many players
Consider disabling unused gyms rather than deleting their config
Regularly run /cleanpunchscores to keep the database lean
Balancing
Start with default values and adjust based on player feedback
Monitor average skill levels to ensure progression feels rewarding
Balance membership prices against your server's economy
Test fatigue thresholds with various player activity levels
Player Experience
Place clear signage in gym MLOs pointing to membership desks
Educate players about the fatigue system through tutorials or guides
Consider weekly gym challenges or competitions
Reward consistent gym-goers with special perks or titles
Getting Help
Where can I report bugs?
Contact me through the appropriate support channels ie our discord or a tebex ticket provided with your purchase tebex id.
I found a typo in the database ("Stength")
This is intentional! Changing it now would break existing player data. The typo is maintained for database consistency across updates.
Common Error Messages
"You need a valid gym membership"
Cause: Player doesn't have an active membership for this gym Solution: Purchase a membership at the gym's membership desk
"Your membership does not include access to this equipment"
Cause: Player's membership tier doesn't allow this equipment type Solution: Upgrade to a higher membership tier
"You are too fatigued to continue"
Cause: Fatigue level is above the threshold (default 85%) Solution: Wait for passive recovery or use an energy drink
"This machine is currently in use"
Cause: Another player is using the punching machine Solution: Wait for the other player to finish
"Failed to create membership, inventory may be full"
Cause: Player's inventory doesn't have space for membership card Solution: Free up inventory space and try again
"Database hiccup while creating the membership"
Cause: Database error during membership creation Solution: Check server console for SQL errors, verify database connection
Still have questions? Check the Installation and Configuration guides for more detailed information.
-- Example: Reading a player's gym stats
local player = TMC.Functions.GetPlayer(source)
local gymSkills = json.decode(player.PlayerData.gym_skills)
local stamina = gymSkills['Stamina'].current
