Sync Tool (Dev-only)¶

The Raycin Sync plugin lives on the local dev WordPress only. It's a small workshop tool with two jobs:

Tab	What it does
1. Push to live	Lists tracks that exist on your dev FiveM but not on the live FiveM game DB, and packages the JSON files + a ready-to-paste SQL snippet into a single zip so you can upload them to live yourself.
2. Class report	Reads every dev track's JSON file and shows the allowed vehicle classes (Compact, Sedan, Super, …) per track, grouped by category, so you can audit gaps before pushing.

Important limitations — read first

This tool is deliberately manual and dev-only. It does NOT:

Auto-upload anything to the live web host or live game server.
Connect to the live SFTP / FiveM filesystem directly.
Write to the live game database automatically (you paste the SQL yourself).
Run on the public live site (it's guarded by a localhost check — if the folder ever lands on live, it stays inert).

What it gives you is a clean diff, a downloadable zip, and a step-by-step README inside the zip. You stay in full control of what reaches live.

Why it exists¶

When you build new tracks on dev (via raycin_creator on your local FiveM server), they're saved to:

A JSON file on disk under raycin_creator/custom_files/<your_license>/…json, and
A row in the dev FiveM MySQL database (custom_race_list table).

The live FiveM server has its own separate database — these don't talk to each other. So a track you built on dev won't appear on live until you copy both pieces across. This plugin makes that copy step deterministic and safe.

When NOT to use this

If you only changed an existing track's contents, just upload the JSON over the top via SFTP — no SQL needed. The Push-to-live flow is for brand-new tracks (the ones that don't have a row on live yet).

Tab 1 — Push to live¶

What you see¶

The page shows a table of tracks present on dev but missing on live, with columns:

Column	Meaning
Select	Checkbox — pick which tracks to include in the zip
⭐ NEW	Highlights tracks updated in the last 30 days (the ones you most likely just built)
Title / Category / License / CPs / Laps / Updated	Basic track facts so you can sanity-check before exporting

What "Download package" gives you¶

Clicking Download package generates a zip with three things inside:

The track JSON files — preserved at their original paths (custom_files/<license>/track_xxx.json) so you can drop them straight into the live raycin_creator folder structure.
push-to-live.sql — INSERT IGNORE statements that add the custom_race_list rows on live. INSERT IGNORE means if a row with the same raceid already exists, nothing happens — you can re-run it safely.
README.txt — the 5-step instructions repeated below.

Deploying the zip (the manual steps)¶

Unzip locally.
Upload the JSON files via SFTP to the live server, preserving the folder structure. They go into raycin_creator/custom_files/<license>/… on the live FiveM host.
Connect to the live FiveM MySQL (phpMyAdmin from your host's DirectAdmin / cPanel, or any MySQL client). Open the FiveM race database (e.g. s6_raycin1).
Paste the contents of push-to-live.sql into a query window and run it. It only adds rows; never touches existing tracks.
In the live FiveM server console, run restart raycin_creator (and restart raycin_races if needed). Pop into the game — the new tracks should appear in the track list.

Why this isn't fully automated

Auto-uploading to live would mean storing your live SFTP password and live DB password on the dev install. That's a security risk for a tool you only run a handful of times a month. The manual upload step is fast (drag-and-drop SFTP + one paste) and keeps the credentials in your head, not on disk.

Re-running is safe¶

The SQL uses INSERT IGNORE, so if you re-run the same package twice (or push a track that's already on live by some other route), nothing breaks — duplicates are skipped. If you genuinely want to update an existing track, just upload the new JSON over the top; no SQL re-run needed.

Tab 2 — Categories¶

What it does¶

Side-by-side track-category counts for dev vs live (Open / Circuit / Sprint / Stunt / F2F / Playground / Special, or whatever set you're running), plus a per-track diff list showing every track where the same raceid has a different category on each side. One click generates a downloadable categories-push.sql containing one UPDATE custom_race_list SET category = '...' WHERE raceid = N; per diff — you paste it into phpMyAdmin on the live FiveM database to bring live in line with dev.

When to use it¶

After you reorganise categories on dev (renamed a category, moved tracks between categories, added a new bucket). Use the Categories tab to roll those label changes onto live without touching individual tracks by hand.

How it works (matching rule)¶

Diffs are matched by raceid — both rows must have the same primary key. If dev and live have ever drifted in raceids (e.g. tracks added independently on each side), only the overlapping IDs get compared.

The generated SQL is idempotent: each UPDATE is keyed by raceid, so re-running the same script does nothing if live already matches. You can also re-download and re-run after fixing things — no risk of duplicate edits.

What it won't do¶

It won't change route_file, published, besttimes, or any column other than category — by design.
It won't fix raceid drift. If dev's "Stunt Pack VIII" is raceid 312 but live's "Stunt Pack VIII" is raceid 478, the diff won't include either row.
It won't restart your live FiveM server. After running the SQL, you do restart raycin_races in the live server console so the in-game category labels refresh.

Step-by-step¶

wp-admin → Raycin Sync → Categories — the Counts table shows dev vs live + delta. Live-only and new-on-dev categories are colour-highlighted.
Scroll down to Per-track diffs — confirm the changes look right.
Click ⬇ Download categories-push.sql.
Open the live FiveM race DB in phpMyAdmin → SQL tab → paste the file's contents → Go.
On the live FiveM server console: restart raycin_races.
Reload the Categories tab — the diff list should be empty.

Tab 3 — Class report¶

What it does¶

For each track on dev, the report opens the JSON file from disk and reads mission.race.avc — the allowed vehicle classes array. Then it groups tracks by category (F2F, Stunt, Drag, etc.) and shows you a compact table of which classes each track permits.

Why it's useful¶

You can spot at a glance whether a category has consistent class coverage. For example:

"All my F2F tracks should allow Supers and Sports — does the new one?"
"This Drag track is missing Motorcycle — was that on purpose?"
"This track has no classes at all — it'll be unselectable in-race."

What the flags mean¶

Flag	Meaning
⚠ No classes set	The track JSON exists but `mission.race.avc` is empty or missing. The track will be unraceable until you re-save it in raycin_creator with at least one class ticked.
⚠ JSON not on disk	The track has a row in the database but the JSON file can't be found at the expected path. Either the file was deleted, or `RVS_RACES_ROOT` / `RVS_CREATOR_ROOT` constants in `wp-config.php` point at the wrong folder.

This report is dev-only

Because the report has to read each track's JSON file off the local disk (the database alone doesn't store the class list), it only works for tracks whose JSON files are available on the same machine the plugin runs on. On dev, that's all of them. On live, the JSON files are on the FiveM game host (not the web host), so this report isn't useful there — which is fine, it's not designed to run there.

Configuration¶

Settings live at wp-admin → Tools → Raycin Sync → Settings. You set the live FiveM MySQL connection details (host / database / user / password). These are stored in a WordPress option and only used by Tab 1 when computing the diff.

If left blank, Tab 1 falls back to "dev only" mode and just shows you all dev tracks (no diff). Tab 2 doesn't need the live DB at all.

Read-only is fine

The live DB user only needs SELECT permission on the FiveM race database. The plugin never writes to live — all writes happen when you paste the SQL yourself in step 4 above. If you want belt-and-braces, give it a dedicated read-only MySQL user.

When it makes sense to expand this¶

If you ever want a one-button push, the next steps would be:

Add SFTP creds (or use the host's API) to upload JSONs automatically.
Run the SQL via a secure WP-CLI endpoint on the live site.
Schedule it as a cron so newly-saved tracks sync nightly.

For now, the friction of "drop the zip + paste the SQL" is deliberate — it's a once-a-month workshop task, not a continuous deploy pipeline.

Troubleshooting¶

Tab 1 shows "Live DB not configured" → Open Settings, fill in the live MySQL host / db / user / pass, save. Hit refresh.

Tab 1 shows 0 tracks → Either dev and live are in sync (great), or the diff key matching is off. The diff matches on the JSON filename basename (e.g. 1730_track.json). If your live install uses different filenames for the same logical track, that's a real mismatch worth investigating.

Download package fails → Check the PHP error log. Most common cause: a track's JSON file moved or was deleted on disk; the zip builder skips missing files and notes them in the README.

Tab 2 shows lots of "JSON not on disk" → Set RVS_RACES_ROOT and RVS_CREATOR_ROOT in wp-config.php to the absolute paths of your local raycin_races/local_files and raycin_creator folders. Without those constants, the plugin guesses — and the guess can be wrong if your FiveM folder isn't in the default location.

Plugin doesn't appear in the menu → It's working as intended. The plugin only registers its admin pages when the host is localhost / *.test / *.local. If you're on the live site, you won't see it (and won't be able to run it). To test on a live-like domain, use a .test hostname.