intial push

README.md

@@ -0,0 +1,82 @@
+# Blockland Config
+
+**Version 1.7.0** · Author: RallyBlock
+
+A Pelican Panel plugin for managing Blockland dedicated server configuration directly from the panel UI.
+
+**Compatibility:** Pelican Panel (Filament 4.x, Laravel 12.x)
+
+## Features
+
+### Add-Ons
+- Toggle server add-ons on/off, grouped by category (Bricks, Vehicles, Weapons, etc.)
+- Categories are automatically detected from add-on names
+- Orphaned entries (add-ons removed from the server) are automatically cleaned up
+- Save changes or **Save & Restart** to apply immediately
+
+### ColorSet
+- Browse installed ColorSet add-ons and activate them with one click
+- Read-only preview of the currently active color palette with color swatches
+- Server restarts automatically after activating a new ColorSet
+- Supports up to 64 colors (Blockland's maximum)
+
+### Preferences
+- Edit server preferences (`prefs.cs`) with typed form fields (toggles, text, numeric, password)
+- Preferences are grouped by category (General, Bricks, Network, Quotas, etc.)
+- **Save** syncs prefs to server vars and runs `webcom_postserver()` for live effect; **Save & Restart** for immediate full reload
+
+### Admins
+- Manage AutoAdminList and AutoSuperAdminList in `prefs.cs`
+- **Add by BL_ID** with role (Admin or Super Admin) and mode: **Auto** (saved to prefs) or **Manual** (session only, no rejoin persistence)
+- **Demote by BL_ID** for manually granted admins (player must be online)
+- Apply changes to connected players immediately when adding Auto admins—no rejoin required (vanilla TorqueScript: `findClientByBL_ID`, `commandToClient setAdminLevel`, `messageAll`)
+- **Remove** button to remove BL_IDs from Super Admins or Admins lists; demotes connected players instantly if online
+- **Silent mode** toggle—when enabled, no `messageAll` announcements are sent for promotions, demotions, or preference updates
+
+### Add-On Browser
+- Browse and install community add-ons directly from [bl.kenko.dev](https://bl.kenko.dev/Add-ons/Retail/)
+- Browse by category with a searchable dropdown
+- Search and filter add-ons by name
+- Paginated results with a configurable page size (10, 25, 50, or 100 per page)
+- One-click install downloads add-ons directly into the server's `Add-Ons/` folder
+- **Note:** These add-ons are for Retail Blockland (v21+), are community-created, and have not been tested for safety
+
+### Save Loader
+- List .bls save files from the server's `saves/` folder with optional preview thumbnails
+- Copy any save to `base/server/temp/temp.bls` — then run /ReloadBricks in-game to load it
+- Upload new .bls files into the saves folder; optionally add a preview image (.jpg, .jpeg, or .png with the same filename)
+
+## Requirements
+
+- Pelican Panel with a Blockland server egg (must have `blockland` in egg tags or features)
+
+The plugin is **standalone** and works with vanilla Blockland—no Blockland Glass or Support Preferences (BLPrefs) required.
+
+## Enabling Pages Per Server
+
+Pages are controlled by **egg features** so you can choose which pages each server gets. Add these feature keys to your Blockland egg's `features` array:
+
+| Feature | Page | Description |
+|---------|------|-------------|
+| `blockland-all` | All pages | Enable all Blockland pages at once |
+| `blockland-addons` | Add-Ons | Toggle add-ons on/off, save or restart |
+| `blockland-colorset` | ColorSet | Activate ColorSet add-ons, preview palette |
+| `blockland-prefs` | Preferences | Edit prefs.cs with typed form fields |
+| `blockland-admins` | Admins | Manage admin lists, add/remove by BL_ID, demote, silent mode |
+| `blockland-addon-browser` | Add-On Browser | Browse and install add-ons from bl.kenko.dev |
+| `blockland-save-loader` | Save Loader | List saves with previews, copy to temp.bls, upload .bls and preview images |
+
+Only pages whose features are present on the server's egg will appear in the server panel. For example, adding only `blockland-addons` and `blockland-prefs` will show just those two pages for servers using that egg.
+
+## Server File Paths
+
+The plugin reads and writes the following files on the game server:
+
+- `config/server/ADD_ON_LIST.cs` — Add-on enable/disable list
+- `config/server/colorSet.txt` — Active color palette
+- `config/server/prefs.cs` — Server preferences
+- `config/server/.blockland-panel` — Panel config (e.g. silent mode)
+- `Add-Ons/` — Installed add-ons (folders or .zip files)
+- `Add-Ons/Colorset_*/` — Installed ColorSet add-ons
+- `saves/` — Save files (.bls) and optional preview images (.jpg, .jpeg, .png); Save Loader lists, uploads, and displays thumbnails
+- `base/server/temp/temp.bls` — Target for Save Loader "Copy to temp.bls" (run /ReloadBricks in-game to load)