⚙️ Configuration Variables Reference

This guide teaches you how to create customizable settings for your eggs. Want to learn how to use these variables in your eggs? See Extending and Creating Eggs.

Overview

Configuration variables let users customize egg behavior without touching core files. Each variable becomes an environment variable that your startup command and install scripts can read.

Related guides:

• Egg Basics - Start here if you're new
• Extending Eggs - How to use variables in eggs
• Wings Variables - Special variables from the panel

---

The Variable Structure

Every variable in an egg looks exactly like this:

{
    "name": "Max Players",
    "description": "How many players can join at the same time (1-64)",
    "env_variable": "MAX_PLAYERS",
    "default_value": "20",
    "user_viewable": true,
    "user_editable": true,
    "rules": "required|numeric|between:1,64",
    "field_type": "text"
}

Here's what every field means:

Field	Type	What it does
name	string	The human-readable label shown in the panel (e.g. "Max Players")
description	string	A helpful explanation shown to the user below the field
env_variable	string	The environment variable name — always UPPER_SNAKE_CASE
default_value	string	The starting value — always a string, even for numbers ("20" not 20)
user_viewable	boolean	true = the user can see this variable in the panel
user_editable	boolean	true = the user can change this variable in the panel
rules	string	Laravel validation rules that control what values are accepted
field_type	string	Always "text" — this never changes

💡 field_type is always "text" — there are no other valid values. The type of data (number, boolean, etc.) is controlled by the rules field instead.

---

The rules Field

The rules field uses Laravel validation syntax — a list of rules joined by | pipes. This is how eggs enforce that users enter valid values.

Common rules at a glance

What you want	Rules value
Required plain text	`"required
Optional text (can be left blank)	`"nullable
Optional text with a max length	`"nullable
Required text with a max length	`"required
Required number in a range	`"required
Required whole number (integer) in a range	`"required
Boolean toggle (0 or 1)	`"required
Must be one of a fixed set of words	`"required
Exact length, letters and numbers only	`"required
Must be a valid URL	`"required
Must match a regex pattern	`"required

How rules are combined

Rules are separated by | and are checked from left to right. For example:

• "required|numeric|between:1,64" means: the field must be filled in, must be a number, and must be between 1 and 64.
• "nullable|string|max:128" means: the field can be empty, but if filled in it must be a string no longer than 128 characters.

---

Variable Examples from Real Eggs

🎮 Player limit (number in a range)

{
    "name": "Max Players",
    "description": "Specifies the maximum amount of players that are able to join the server.",
    "env_variable": "MAX_PLAYERS",
    "default_value": "12",
    "user_viewable": true,
    "user_editable": true,
    "rules": "required|numeric|between:1,64",
    "field_type": "text"
}

Notice that default_value is "12" (a string), not 12 (a number). All default values are strings.

🔒 Boolean toggle (on/off with 0 or 1)

{
    "name": "Enable VAC",
    "description": "Enable / Disable VAC (Valve Anti Cheat) on your server. By default this will be enabled.",
    "env_variable": "VAC_ENABLED",
    "default_value": "1",
    "user_viewable": true,
    "user_editable": true,
    "rules": "required|boolean",
    "field_type": "text"
}

For boolean toggles, the value is "1" (on) or "0" (off). The required|boolean rule enforces this.

📦 Version string (optional text)

{
    "name": "Minecraft Version",
    "description": "The version of minecraft to download. Leave at latest to always get the latest version. Invalid versions will default to latest.",
    "env_variable": "MINECRAFT_VERSION",
    "default_value": "latest",
    "user_viewable": true,
    "user_editable": true,
    "rules": "nullable|string|max:20",
    "field_type": "text"
}

Using nullable means the user can leave this blank — useful for version fields where an empty value has a sensible meaning.

🔧 Admin-only variable (hidden from users)

{
    "name": "5e Tools Repository",
    "description": "Git Repository to use for cloning 5e Tools",
    "env_variable": "REPOSITORY",
    "default_value": "https://github.com/5etools-mirror-1/5etools-mirror-1.github.io",
    "user_viewable": false,
    "user_editable": false,
    "rules": "required|url",
    "field_type": "text"
}

Setting both user_viewable and user_editable to false makes this an admin-only variable. Users won't see it in the panel at all. It's still available to your scripts as an environment variable.

🎵 Fixed-choice value (must be one of a list)

{
    "name": "Autoplay",
    "description": "Autoplay similar songs when your music ends\nValue : true/false",
    "env_variable": "SPOTIFY_BOT_AUTOPLAY",
    "default_value": "false",
    "user_viewable": true,
    "user_editable": true,
    "rules": "required|string|in:true,false",
    "field_type": "text"
}

The in:true,false rule means the value must be exactly "true" or "false". You can extend the list: in:survival,creative,adventure,spectator for a Minecraft game mode, for example.

🔑 API key or token (exact format)

{
    "name": "Bot Token",
    "description": "Your Discord bot token from the Discord Developer Portal.",
    "env_variable": "BOT_TOKEN",
    "default_value": "",
    "user_viewable": true,
    "user_editable": true,
    "rules": "required|string|max:100",
    "field_type": "text"
}

🌐 Port number

{
    "name": "Query Port",
    "description": "The port used for server queries. Must be between 1025 and 65535.",
    "env_variable": "QUERY_PORT",
    "default_value": "25565",
    "user_viewable": true,
    "user_editable": true,
    "rules": "required|integer|between:1025,65535",
    "field_type": "text"
}

Use integer (not numeric) for ports since ports must be whole numbers.

---

user_viewable and user_editable

These two boolean fields control what server owners can do with a variable in the panel.

user_viewable	user_editable	What happens
true	true	User can see and change the value ✅
true	false	User can see the value but cannot change it 👀
false	false	Admin-only — user has no idea this variable exists 🔒

⚠️ Setting user_viewable: false but user_editable: true doesn't make sense — if the user can't see it, they can't edit it. Always keep user_editable as false when user_viewable is false.

---

Using Variables in Your Egg

In the startup command

Variables are referenced with double curly braces {{VARIABLE_NAME}}:

java -Xms128M -XX:MaxRAMPercentage=95.0 -jar {{SERVER_JARFILE}}

The panel substitutes the actual value before passing the command to Wings.

In install scripts

Inside bash install scripts, variables are available as normal shell environment variables with a $ prefix:

#!/bin/bash

echo "Installing server with max players: $MAX_PLAYERS"
echo "Server port: $SERVER_PORT"

# Use in a config file
cat > server.properties << EOF
max-players=$MAX_PLAYERS
server-port=$SERVER_PORT
EOF

# Conditional logic
if [ "$VAC_ENABLED" = "1" ]; then
    echo "VAC is enabled"
fi

In config file parsers (config.files)

When using the config.files section to automatically rewrite config files, reference variables with {{server.build.env.VARIABLE_NAME}}:

"server.properties": {
    "parser": "properties",
    "find": {
        "max-players": "{{server.build.env.MAX_PLAYERS}}",
        "server-port": "{{server.build.env.SERVER_PORT}}"
    }
}

See Wings Variables for more about the server.build.env namespace and other special panel variables.

---

Common Variable Patterns

Server name and description

{
    "name": "Server Name",
    "description": "The name displayed for your server.",
    "env_variable": "SERVER_NAME",
    "default_value": "My Game Server",
    "user_viewable": true,
    "user_editable": true,
    "rules": "required|string|max:64",
    "field_type": "text"
},
{
    "name": "Server Description",
    "description": "A short description or message of the day.",
    "env_variable": "SERVER_DESCRIPTION",
    "default_value": "Welcome to my server!",
    "user_viewable": true,
    "user_editable": true,
    "rules": "nullable|string|max:256",
    "field_type": "text"
}

JAR file selection (regex validation)

{
    "name": "Server Jar File",
    "description": "The name of the server jar file to run.",
    "env_variable": "SERVER_JARFILE",
    "default_value": "server.jar",
    "user_viewable": true,
    "user_editable": true,
    "rules": "required|regex:/^([\\w\\d._-]+)(\\.jar)$/",
    "field_type": "text"
}

Memory/heap size

{
    "name": "Initial Heap Size",
    "description": "The initial Java heap size in megabytes.",
    "env_variable": "INIT_MEMORY",
    "default_value": "1024",
    "user_viewable": true,
    "user_editable": true,
    "rules": "required|integer|between:256,16384",
    "field_type": "text"
}

---

Best Practices for Variables

1. Use clear, readable names

The name field is what users see in the panel. Make it obvious.

// ✅ Good
"name": "Maximum Player Count"

// ❌ Bad
"name": "max"

2. Write helpful descriptions

Tell the user what the variable does and what values are valid.

// ✅ Good
"description": "How many players can connect at once. Must be between 1 and 64."

// ❌ Bad
"description": "Players"

3. Always use string default values

Even for numbers, the default_value must be a string:

// ✅ Correct
"default_value": "20"

// ❌ Wrong — will cause errors
"default_value": 20

4. Match your rules to the actual data type

• Whole numbers → use integer
• Decimals allowed → use numeric
• Free text → use string
• Must be a specific word → use in:option1,option2
• Can be empty → start with nullable instead of required

5. Be intentional with user_viewable and user_editable

If a variable contains sensitive data (like a private API URL or an internal secret), set both to false so only admins can touch it.

---

Troubleshooting Variables

Variables not being substituted in the startup command

1. Check that env_variable is UPPER_SNAKE_CASE with no spaces
2. Make sure your startup command uses {{VARIABLE_NAME}} with double curly braces
3. Verify the JSON is valid — use a JSON linter if unsure

Variables not available in install scripts

1. In install scripts, use $VARIABLE_NAME (single dollar sign, no curly braces needed, though ${VARIABLE_NAME} also works)
2. Make sure the variable is defined in the egg's variables array

Validation errors when saving a server

The rules field controls what values are accepted. If a user sees a validation error, check:

Problem	Likely cause	Fix
"The field is required"	Field is empty and rules say required	Either fill it in or change to nullable
"The value must be between X and Y"	Value is out of the between:X,Y range	Adjust the value or widen the range
"The value must be one of ..."	Value doesn't match in:a,b,c	Check spelling — in: is case-sensitive
"The value must be an integer"	Non-whole number given for integer rule	Use numeric if decimals are allowed

JSON syntax errors

Variables live inside the variables array in the egg JSON. A missing comma or brace will break the whole egg. Always validate your JSON before importing. Common mistakes:

• Forgetting a comma between two variable objects
• Using true/false instead of "true"/"false" in default_value
• A trailing comma after the last variable in the array