GameMaker Studio · GML · Players

gmda_setNewname

Changes the player's display name (server validates uniqueness and charset).

Asynchronous (result via event)

Signature

gmda_setNewname(new_name) -> real

What it does

Sanitizes the name locally, then PATCHes /players/name so the server can validate uniqueness. On success the queued newname_completed event has success:true and player_name (the applied name). On failure it has success:false plus status and error, where status is -1 when the name is already taken and 0 for a generic failure.

Parameters

Name	Type	Default	Description
new_name	string	required	Desired name. Sanitized locally and capped at 30 chars; must be at least 2 chars after sanitizing or the call is rejected.

How to call it

Returns 1 once the request is queued, or 0 immediately (with no event) if there is no active session or the sanitized name is shorter than 2 characters. Read the outcome from the event queue.

Result event: newname_completed { success, player_name }

Example

if (gmda_setNewname("Hero123") == 0) {
    show_debug_message("rejected locally (no session or too short)");
}

var e = gmda_pollEvent();
while (!is_undefined(e)) {
    if (e.event == "newname_completed") {
        if (e.success) {
            show_debug_message("renamed to " + e.player_name);
        } else if (e.status == -1) {
            show_debug_message("that name is taken");
        } else {
            show_debug_message("could not change name: " + e.error);
        }
    }
    e = gmda_pollEvent();
}

Use cases

Let the player pick a nickname during onboarding.
Offer a rename option in a settings screen.

Reference des fonctions