65 lines
2.2 KiB
Markdown
65 lines
2.2 KiB
Markdown
# WHMCS configurable options
|
|
|
|
Map WHMCS configurable options to GameCloud server parameters at provision and upgrade time.
|
|
|
|
## Overview
|
|
|
|
Configurable options let customers choose RAM tiers, Minecraft versions, or software types at order time. The server module reads selected options during `CreateAccount` and `ChangePackage`.
|
|
|
|
**Preferred approach:** Use addon product mappings for plan slugs; use configurable options for customer-visible upgrades that WHMCS invoices.
|
|
|
|
## Standard option layout
|
|
|
|
| Option name | Type | Maps to |
|
|
|-------------|------|---------|
|
|
| Plan | Dropdown | GameCloud plan slug (via mapping resolver) |
|
|
| Minecraft Version | Dropdown | `minecraftVersion` |
|
|
| Software | Dropdown | `softwareFamily` |
|
|
| Extra Backup Slot | Quantity | WHMCS addon product — see [addons](addons.md) |
|
|
|
|
Option order matters if using fallback config option indices in legacy setups. Mappings table overrides text fields when an active row exists.
|
|
|
|
## Dropdown values
|
|
|
|
### Software family
|
|
|
|
Values must match GameCloud enum exactly:
|
|
|
|
`VANILLA`, `PAPER`, `PURPUR`, `FABRIC`, `FORGE`, `NEOFORGE`, `QUILT`
|
|
|
|
### Minecraft version
|
|
|
|
Use semver strings present in GameCloud catalog. Invalid versions fail provisioning with module log error.
|
|
|
|
## Upgrade path
|
|
|
|
When a customer upgrades via WHMCS configurable option change:
|
|
|
|
1. WHMCS invokes `ChangePackage`
|
|
2. Module sends new `planSlug` to GameCloud
|
|
3. GameCloud resizes limits; may require server restart
|
|
|
|
Communicate restart requirement in WHMCS product description.
|
|
|
|
## Validation
|
|
|
|
The addon **Mappings** page validates plan slugs before save. Configurable option text is **not** validated until order time — typos cause provisioning failures.
|
|
|
|
## Pricing
|
|
|
|
WHMCS handles all pricing. GameCloud never stores invoice amounts in WHMCS mode (`BILLING_PROVIDER=whmcs`).
|
|
|
|
## Example: RAM upgrade option
|
|
|
|
1. WHMCS configurable option group "Upgrades"
|
|
2. Option "RAM Tier" with values mapping to plan slugs `starter`, `pro`, `enterprise`
|
|
3. Product mapping links WHMCS product + option combination to slug via `ProductMapping.php` resolver
|
|
|
|
For complex matrices, use separate WHMCS products instead of many conditional options.
|
|
|
|
## Related
|
|
|
|
- [Products](products.md)
|
|
- [Product mappings](../product-mappings.md)
|
|
- [Troubleshooting](troubleshooting.md)
|