MySQL Saving

Crystal Save supports MySQL as a cloud save backend through a secure Web API layer instead of direct database connections. This design ensures that your game never exposes database credentials to clients and allows you to enforce authentication, rate limits, and request validation on the server.

---

1. Requirements

Before setting up MySQL cloud saves, you will need:

• A MySQL or MariaDB server (local or remote).

• A web server capable of running PHP (LAMP stack recommended).

• Crystal Save installed in your Unity project.

• A configured SaveSettings asset.

---

2. Server Setup

Step 1 — Install the Database Schema

Crystal Save includes an installer script:

1. Locate Documentation/MySQL Server files/install.php in the package.

2. Edit the credentials at the top of the file to match your MySQL server (host, username, password, database name).

3. Upload install.php to your web server and run it via browser (or CLI). This will create the CrystalSaveData table if it does not already exist.

---

Step 2 — Deploy the Web API

The backend requires an API script to handle save/load requests:

• Use Documentation/MySQL Server files/mysql_api_sample.php as your starting point.

• Upload it to your server (and rename it, e.g., /var/www/html/crystal-save.php).

• This script implements the routes Crystal Save expects:

Route	Purpose
/save	Uploads a save slot blob and metadata.
/load	Downloads save data for a given slot.
/delete	Removes a slot from the database.
/metadata	Reads/writes the slot’s custom metadata without fetching full data.
/list	Returns the list of slots for the current user.

The script also stores CustomMetadata as JSON so your UI can display slot details without downloading the full save.

---

3. Unity Setup

Step 1 — Create or Edit SaveSettings

1. In Unity, go to Crystal Save Settings.

2. Under Cloud Save Settings:

   • Enable Cloud Save → ✅

   • Save Backend → MySQL

---

Step 2 — Configure MySQL Fields

Crystal Save exposes these MySQL configuration options:

Field	Description
My SQL API URL (mySqlApiUrl)	The base URL of your API script. Example: https://example.com/crystal-save.php
My SQL Auth API URL (mySqlAuthApiUrl)	Optional. URL for authentication calls. Defaults to mySqlApiUrl if empty.
My SQL API Key (mySqlApiKey)	Optional. Sent as an X-API-KEY header for security.
Table Name (tableName)	The MySQL table name where saves are stored (default: CrystalSaveData).

Example:

var settings = ScriptableObject.CreateInstance<SaveSettings>();
settings.backend           = SaveBackend.MySQL;
settings.mySqlApiUrl       = "https://example.com/crystal-save.php";
settings.mySqlAuthApiUrl   = "https://auth.example.com/login.php"; // optional
settings.mySqlApiKey       = "YOUR_SECRET_TOKEN"; // optional
settings.tableName         = "CrystalSaveData";

4. WebGL Notes

• WebGL builds work with the MySQL backend because the client talks to your PHP API via HTTP, not direct SQL.

• Ensure CORS is configured on your server to allow requests from your game’s domain.

• If using HTTPS, make sure your certificate is valid to avoid browser blocking requests. If you use HTTP because you don't have certificate, then be aware that this might only work on your own customized web server or in development builds and you are required to set in your Player Settings Allow HTTP to true.

---

5. Testing

1. Run your Unity project and perform a save.

2. Check your MySQL table (CrystalSaveData) for a new entry.

3. Load from the same slot to confirm the save was uploaded and downloaded correctly.

4. If screenshots or metadata are not appearing in UI:

   • Verify /metadata and /list routes return correct JSON.

   • Ensure your SaveSlotManagerWindow is refreshing after CloudSaveService.RefreshRemoteSlotsAsync().

   • Check chmod of the folder and your .htaccess files

---

6. Tips & Best Practices

• Security: Always restrict database access to your API server’s IP and use a strong mySqlApiKey for requests.

• Performance: If you expect many players, add indexing on user_id and slot_number columns.

• Metadata: Use CustomMetadata to store slot names, playtime, difficulty, etc., for display without loading the full save.

• Backups: Schedule periodic dumps of your CrystalSaveData table.

---

7. Related References

• mysql_api_sample.php – Minimal PHP API for MySQL backend.

• install.php – Database installer script.

• blazor_backend_sample.cs – ASP.NET Core backend alternative.

• blazor_frontend_sample.razor – Example frontend integration.