The dashboard does not save a complete TypeScript file. It saves only the script body. The server injects that body into the CloudScript template after runtime objects have already been created.

Paste this into Cloud Script Function, save it with canExecute = true, then run pingCloudScript from Cloud Script Test.

handlers["pingCloudScript"] = async (args: any, context, log) => {
    const message = typeof args?.message === "string" && args.message.length > 0 ? args.message : "pong";

    log({
        action: "pingCloudScript",
        userId: context.userId,
        message: message
    });

    return {
        ok: true,
        gameId: gameId,
        userId: context.userId,
        customTags: context.customTags,
        message: message
    };
};

Use database when the script owns internal GearN data or custom game data. Prefer game-scoped collections for game-specific custom records.

const requireString = (value: unknown, fieldName: string): string => {
    if (typeof value !== "string" || value.trim().length === 0) {
        throw new Error(fieldName + " is required");
    }

    return value.trim();
};

handlers["saveCloudScriptSample"] = async (args: any, context, log) => {
    const key = requireString(args?.key, "key");
    const value = args?.value ?? null;
    const sampleCollection = database.runtimeGameCollection("CloudScript.Sample", gameId);

    await sampleCollection.updateOne(
        { key: key },
        {
            $set: {
                key: key,
                value: value,
                updatedByUserId: context.userId,
                tsUpdate: Date.now()
            }
        },
        { upsert: true }
    );

    const savedDocument = await sampleCollection.findOne(
        { key: key },
        { projection: { _id: 0 } }
    );

    return {
        gameId: gameId,
        savedDocument: savedDocument
    };
};

Use admin when GearN already has a typed API for the job. Always check response.hasReturnCodeError() before trusting response data.

const requireString = (value: unknown, fieldName: string): string => {
    if (typeof value !== "string" || value.trim().length === 0) {
        throw new Error(fieldName + " is required");
    }

    return value.trim();
};

handlers["adminGetPlayerDisplayName"] = async (args: any, context, log) => {
    const targetUserId = requireString(args?.userId, "userId");

    const response = await admin.gamePlayer.getDisplayNameAsync({
        userId: targetUserId
    });

    if (response.hasReturnCodeError()) {
        throw new Error(response.toString());
    }

    return {
        userId: targetUserId,
        errorCode: response.errorCode,
        responseData: response.responseData
    };
};

Use http for external REST APIs. Set a timeout and return only the fields the caller needs.

const requireString = (value: unknown, fieldName: string): string => {
    if (typeof value !== "string" || value.trim().length === 0) {
        throw new Error(fieldName + " is required");
    }

    return value.trim();
};

handlers["sendCloudScriptWebhook"] = async (args: any, context, log) => {
    const url = requireString(args?.url, "url");

    const response = await http.post(
        url,
        {
            eventName: "cloudScriptWebhook",
            gameId: gameId,
            userId: context.userId,
            payload: args?.payload ?? null,
            ts: Date.now()
        },
        {
            timeout: 8000,
            headers: {
                "content-type": "application/json"
            }
        }
    );

    return {
        status: response.status,
        data: response.data
    };
};

Use socket for online realtime delivery, mail for email, and pushNotification for mobile notification. Keep payloads small and do not log private tokens.

const requireString = (value: unknown, fieldName: string): string => {
    if (typeof value !== "string" || value.trim().length === 0) {
        throw new Error(fieldName + " is required");
    }

    return value.trim();
};

const createCloudScriptEvent = (eventName: string, payload: { [key: string]: any }) => {
    return new OperationEvent(
        eventName,
        GNHashtable.builder().addAll(payload).build()
    );
};

handlers["notifyPlayerFromCloudScript"] = async (args: any, context, log) => {
    const targetUserId = typeof args?.userId === "string" && args.userId.length > 0 ? args.userId : context.userId;
    const message = typeof args?.message === "string" && args.message.length > 0 ? args.message : "CloudScript notification";

    await socket.sendEventTo(
        targetUserId,
        createCloudScriptEvent("cloudScriptNotification", {
            message: message,
            sourceUserId: context.userId,
            ts: Date.now()
        })
    );

    if (typeof args?.email === "string" && args.email.length > 0) {
        await mail.send(args.email, "CloudScript notification", "<p>" + message + "</p>");
    }

    if (typeof args?.pushToken === "string" && args.pushToken.length > 0) {
        await pushNotification.send(args.pushToken, "CloudScript", message, 1, "default", "ic_notification", {
            source: "cloudScript",
            userId: targetUserId
        });
    }

    return {
        notified: true,
        userId: targetUserId
    };
};