How to use the Query String Object

How to use Query String

The Query String object is used when your launcher needs to talk to something outside of itself. That could be a plain text file on your server, a small PHP endpoint, or a full API.

In simple terms, it sends a request to a URL, waits for a response, and then gives you that response back so you can use it inside your launcher.

What the Query String object is good for

You can use the Query String object for things like:

Checking a latest version number from a text file.
Loading a message of the day from your website.
Fetching patch notes from a remote file.
Sending a form request to an endpoint.
Talking to a JSON API and then reading the returned data with the JSON Parser object.

How it works

At its core, the Query String object has a few key settings:

URL – the address you want to request.
Method – usually GET or POST.
Post Values – values to send when using POST.
Loading Text – text shown while the request is running.
Error Text – text shown if the request fails.
Auto Start – whether it should run automatically when the page loads.

When the request completes, the object can then fire one of its events:

On Query Finished – the request worked and data came back.
On Query Error – the request failed.

Two ways to trigger it

1. Automatically

If Auto Start is enabled, the Query String object can begin the request on its own when the page loads. This is useful for things like loading news, a welcome message, or a version check as soon as the user opens the launcher page.

2. With an action

You can also trigger it manually using the GET Query action. This tells a specific Query String object to run its request when you want it to.

This is useful when you only want the request to happen after a button click, after another action finishes, or after the user enters some data first.

What comes back from the object

Once a Query String request has completed, the object exposes response-related values that can be read back and used elsewhere.

Useful properties include:

returnValue
text
textContent
innerHTML

This means you can:

Show the returned response directly in the Query String object itself.
Push the returned value into a variable.
Pass the response into a JSON Parser object.
Use the returned content to update labels, buttons, or other parts of the launcher.

Example 1: Read a simple text file from your server

This is the easiest way to understand the object.

Imagine you have a text file on your server called:

https://yourdomain.com/version.txt

And inside that file is just:

1.2.4

You could configure your Query String object like this:

URL: https://yourdomain.com/version.txt
Method: GET
Loading Text: Checking version...
Error Text: Could not check version.
Auto Start: On

When the page opens, the launcher requests the file. If it succeeds, the object now contains the returned text, which in this case would be 1.2.4.

From there, you could:

Push the value into a variable.
Compare it to your local version.
Show an update button if the values do not match.

Example 2: Load a welcome message from a text file

Let’s say you host a file called:

https://yourdomain.com/motd.txt

And the file contains:

Welcome to the launcher. Double XP weekend starts Friday.

Set your Query String object like this:

URL: https://yourdomain.com/motd.txt
Method: GET
Auto Start: On

Then, once the request finishes, use:

Push to Variable
Source Object: your Query String object
Source Property: text or returnValue
Target Variable: motd_text

After that, use:

Set Object Property from Variable
Source Variable: motd_text
Target Object: your Label object
Target Property: text

That gives you a simple remotely managed message system.

Example 3: Trigger a request only when a button is clicked

Sometimes you do not want the request to happen automatically. You may only want it to run when the user asks for it.

For example:

The user clicks a button called Check Server Status.
That button runs the GET Query action.
The action targets your Query String object.
The Query String object requests your remote endpoint.
When the request finishes, the object fires On Query Finished.

This is a good pattern for:

manual refresh buttons
check-for-updates buttons
load-more buttons
pulling live data only when needed

Example 4: Use POST to send data to an endpoint

The Query String object is not limited to GET. It also supports a Method setting and includes Post Values, which makes it suitable for POST requests too.

A basic use case could be sending a username and token to an endpoint.

For example, imagine your endpoint is:

https://yourdomain.com/api/check-access.php

You could configure the object like this:

URL: https://yourdomain.com/api/check-access.php
Method: POST
Post Values: your configured key/value pairs
Loading Text: Checking access...
Error Text: Access check failed.

A practical flow might look like this:

Push the username input into a variable.
Push the token into another variable.
Use those values in the Query String object’s POST values.
Trigger the object.
Wait for On Query Finished.
Use the returned result to decide what happens next.

This is useful for:

custom login-like checks
license validation
account lookups
feature access checks
sending form data to your own backend

Example 5: Talk to a JSON API

This is where the Query String object becomes much more powerful.

A lot of APIs return JSON rather than plain text. For example, an endpoint might return something like:

{ "status": "ok", "version": "1.2.4", "message": "Patch available" }

The Query String object can fetch that response, and then the JSON Parser object can read specific values from it.

A typical setup looks like this:

1. Query String requests the API.
2. The request finishes successfully.
3. Push the response into a variable.
4. Parse that variable with a JSON Parser object.
5. Read specific JSON paths into other variables.
6. Use those variables in your UI or logic.

Example 6: Query String + JSON Parser workflow

Imagine this endpoint:

https://yourdomain.com/api/launcher-status

And it returns:

{ "online": true, "motd": "Servers are live", "build": "1.2.4" }

A simple workflow could be:

Step 1: Create a Query String object and set its URL to the endpoint.
Step 2: Trigger it with Auto Start or GET Query.
Step 3: On Query Finished, use Push to Variable to store the returned response in a variable such as api_response.
Step 4: Use Parse JSON From Variable with your JSON Parser object and the api_response variable.
Step 5: Use Set Variable From JSON Path to read values like:

motd
build
online

You can then:

set a label to the message of the day
compare the returned build number to your local version
show or hide objects depending on whether the service is online

Example 7: Use it for a remote version check

This is one of the most useful real-world cases.

Let’s say your server returns:

{ "latest_version": "2.0.1", "download_url": "https://yourdomain.com/downloads/update.exe" }

You could:

Fetch the response using Query String.
Push the response into a variable.
Parse it with the JSON Parser.
Read latest_version into a variable.
Compare that variable against your current version variable.
If they do not match, show an Update button.

You could even read the download_url into another variable and use that later in a download action.

What event should you use afterwards?

On Query Finished

This should be your main success event. Use it when you want to continue the flow only after the request has worked.

Typical uses:

Push the result into a variable.
Parse JSON.
Update labels.
Show new objects.
Run compare logic based on the returned response.

On Query Error

Use this for your failure path.

Typical uses:

Show an error label.
Hide a loading indicator.
Show a Retry button.
Set a fallback message such as “Unable to load live data”.

Good beginner pattern

If you are new to Query String, this is a very safe pattern to follow:

1. Start with a plain text file on your server.
2. Make sure the object can fetch it successfully.
3. Push the returned value into a variable.
4. Display that variable somewhere in the launcher.
5. Once that works, move on to JSON.

That way, you understand the response flow before adding the extra layer of parsing.

Common use cases

Simple text file: latest version, launcher message, status text.
POST request: send a form or token to your backend.
JSON API: patch notes, news, account state, build data, access rules.
Remote UI data: banners, messages, notices, online status, feature flags.

Things to keep in mind

The Query String object is best thought of as the object that fetches the response. If you want to make decisions with that response, store it in variables and continue the logic from there.

If the response is plain text, you can usually work with it directly. If the response is structured JSON, pass it into a JSON Parser object and then extract the exact values you want.

Also remember that On Query Finished and On Query Error are important. They give you a clean success path and a clean failure path.

A simple full example

Here is a straightforward example using a JSON API:

Goal: Load a live message and show it in a label.

1. Create a Query String object.
2. Set URL to: https://yourdomain.com/api/message
3. Set Method to: GET
4. Turn Auto Start on.
5. On Query Finished, push the object’s returned response into a variable called message_json.
6. Parse message_json using a JSON Parser object.
7. Read JSON path message into a variable called live_message.
8. Set your Label’s text property from live_message.

That gives you a launcher message that can be changed remotely without republishing the launcher.

Final thoughts

The Query String object is one of the easiest ways to make your launcher feel live and connected. It can be as simple as loading one text file, or as advanced as driving whole parts of your launcher from remote API data.

If you are just starting out, begin with a simple GET request to a text file. Once that makes sense, move on to JSON responses and use the JSON Parser object to pull out the exact data you need.