[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6KRF8GZTG1TAS506MFBSGFC":3,"skill-same:01M6KRF8GZTG1TAS506MFBSGFC":78},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":36,"linkOnly":37,"markdownContent":38,"markdownBody":39,"frontMatter":40,"refName":41,"commitSha":42,"skillDirectory":43,"forksCount":44,"repositoryHtmlUrl":45,"repositoryHomepageUrl":6,"ownerHtmlUrl":46,"ownerBlogUrl":47,"ownerDescription":48,"updatedAt":49,"install":50,"resources":63},"01M6KRF8GZTG1TAS506MFBSGFC","web-services",null,"Use when a Godot game calls a web server — HTTPRequest, downloads, REST\u002FJSON APIs, auth headers, WebSocketPeer clients, TLS, retries, and keeping secrets out of the build. Not for game networking\u002FRPCs (multiplayer-basics) or browser export (web-export)","jame581\u002FGodotPrompter","jame581","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F21112138?v=4","01M6KR3KEQ9Z30WVJRR2E2ZVXE","Jan Mesarč","01M6KR3KJVRMPDSMASQPBCBVK3",964,"MIT","https:\u002F\u002Fgithub.com\u002Fjame581\u002FGodotPrompter\u002Fblob\u002Fmaster\u002Fskills\u002Fweb-services\u002FSKILL.md",[],[19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35],"web","web services","services","when","godot","clients","headers","secrets","json","build","REST","use","tls","retries","calling","auth","downloads","2026-11-10 10:12:30",false,"---\nname: web-services\ndescription: Use when a Godot game calls a web server — HTTPRequest, downloads, REST\u002FJSON APIs, auth headers, WebSocketPeer clients, TLS, retries, and keeping secrets out of the build. Not for game networking\u002FRPCs (multiplayer-basics) or browser export (web-export)\n---\n\n# Web Services in Godot 4.3+\n\nTalk to REST APIs, leaderboards, analytics, login services, and other HTTP\u002FWebSocket backends. All examples target Godot 4.3+ with no deprecated APIs. GDScript is shown first, then C#.\n\n> **Related skills:** **multiplayer-basics** for real-time game networking with WebSocketMultiplayerPeer, **save-load** for persisting tokens and cached responses, **web-export** for CORS and browser limits, **mobile-development** for Android export permissions, **multithreading** for heavy response parsing off the main thread.\n\n---\n\n## 1. Picking the Tool\n\n| Need | Use | Why |\n|---|---|---|\n| Ordinary REST call, file or image download | `HTTPRequest` node | Handles connect, redirects, gzip, timeout; emits one signal when done |\n| Streaming a response, custom keep-alive, many requests to one host | `HTTPClient` | Low-level; you call `poll()` and drive the state machine yourself |\n| Persistent two-way channel (chat, live events, lobby service) | `WebSocketPeer` | Client socket; call `poll()` every frame |\n| Real-time gameplay sync with RPCs | `WebSocketMultiplayerPeer` | Plugs into `MultiplayerAPI` — see **multiplayer-basics** |\n\n**One `HTTPRequest` node runs one request at a time.** A second `request()` while one is in flight returns `ERR_BUSY`. Create one node per concurrent request (Section 3) rather than queueing on a shared node.\n\n---\n\n## 2. A Single Request with `await`\n\n`request()` only *starts* the request; its return value says whether it could be sent, not whether the server answered. The result arrives on `request_completed(result, response_code, headers, body)`.\n\n```gdscript\nfunc fetch_motd() -> void:\n    var http := HTTPRequest.new()\n    http.timeout = 10.0 # Default 0.0 means wait forever.\n    add_child(http)\n\n    var err := http.request(\"https:\u002F\u002Fapi.example.com\u002Fv1\u002Fmotd\")\n    if err != OK:\n        push_error(\"Could not start request: %s\" % error_string(err))\n        http.queue_free()\n        return\n\n    var res: Array = await http.request_completed\n    http.queue_free()\n\n    var result: int = res[0]\n    var code: int = res[1]\n    var body: PackedByteArray = res[3]\n    if result != HTTPRequest.RESULT_SUCCESS:\n        push_warning(\"Network failure (HTTPRequest.Result %d)\" % result)\n    elif code != 200:\n        push_warning(\"Server answered HTTP %d\" % code)\n    else:\n        print(body.get_string_from_utf8())\n```\n\n```csharp\npublic async void FetchMotd()\n{\n    var http = new HttpRequest { Timeout = 10.0 }; \u002F\u002F Default 0.0 means wait forever.\n    AddChild(http);\n\n    Error err = http.Request(\"https:\u002F\u002Fapi.example.com\u002Fv1\u002Fmotd\");\n    if (err != Error.Ok)\n    {\n        GD.PushError($\"Could not start request: {err}\");\n        http.QueueFree();\n        return;\n    }\n\n    Variant[] res = await ToSignal(http, HttpRequest.SignalName.RequestCompleted);\n    http.QueueFree();\n\n    long result = res[0].AsInt64();\n    long code = res[1].AsInt64();\n    byte[] body = res[3].AsByteArray();\n    if (result != (long)HttpRequest.Result.Success)\n        GD.PushWarning($\"Network failure (HttpRequest.Result {result})\");\n    else if (code != 200)\n        GD.PushWarning($\"Server answered HTTP {code}\");\n    else\n        GD.Print(body.GetStringFromUtf8());\n}\n```\n\nCheck **both** values: `result` is the transport outcome (DNS, TLS, timeout — `RESULT_CANT_RESOLVE`, `RESULT_TLS_HANDSHAKE_ERROR`, `RESULT_TIMEOUT`, …), `response_code` is the HTTP status. A 404 or 500 arrives with `RESULT_SUCCESS`.\n\n---\n\n## 3. A Reusable JSON API Client (Autoload)\n\nWrap the boilerplate once. Register this as an autoload named `Api`; every call spawns its own `HTTPRequest`, so calls can overlap.\n\n```gdscript\n# api.gd — autoload \"Api\"\nextends Node\n\nconst BASE_URL := \"https:\u002F\u002Fapi.example.com\u002Fv1\"\nconst TIMEOUT_SEC := 10.0\n\nvar auth_token: String = \"\"\n\n\n## Returns {ok: bool, code: int, data: Variant, error: String}.\nfunc request_json(path: String, method: HTTPClient.Method = HTTPClient.METHOD_GET, payload: Variant = null) -> Dictionary:\n    var http := HTTPRequest.new()\n    http.timeout = TIMEOUT_SEC\n    add_child(http)\n\n    var headers := PackedStringArray([\"Accept: application\u002Fjson\"])\n    var body := \"\"\n    if payload != null:\n        headers.append(\"Content-Type: application\u002Fjson\")\n        body = JSON.stringify(payload)\n    if not auth_token.is_empty():\n        headers.append(\"Authorization: Bearer \" + auth_token)\n\n    var err := http.request(BASE_URL + path, headers, method, body)\n    if err != OK:\n        http.queue_free()\n        return {\"ok\": false, \"code\": 0, \"data\": null, \"error\": \"request() failed: \" + error_string(err)}\n\n    var res: Array = await http.request_completed\n    http.queue_free()\n    if res[0] != HTTPRequest.RESULT_SUCCESS:\n        return {\"ok\": false, \"code\": 0, \"data\": null, \"error\": \"transport error %d\" % res[0]}\n\n    var code: int = res[1]\n    var text := (res[3] as PackedByteArray).get_string_from_utf8()\n    var data: Variant = JSON.parse_string(text) if not text.is_empty() else null\n    return {\"ok\": code >= 200 and code \u003C 300, \"code\": code, \"data\": data, \"error\": \"\" if code \u003C 400 else text}\n```\n\n```csharp\n\u002F\u002F Api.cs — autoload \"Api\"\nusing System.Collections.Generic;\nusing System.Threading.Tasks;\nusing Godot;\n\npublic partial class Api : Node\n{\n    private const string BaseUrl = \"https:\u002F\u002Fapi.example.com\u002Fv1\";\n    private const double TimeoutSec = 10.0;\n\n    public string AuthToken { get; set; } = \"\";\n\n    public readonly record struct ApiResult(bool Ok, long Code, Variant Data, string Error);\n\n    public async Task\u003CApiResult> RequestJson(string path, HttpClient.Method method = HttpClient.Method.Get, Variant payload = default)\n    {\n        var http = new HttpRequest { Timeout = TimeoutSec };\n        AddChild(http);\n\n        var headers = new List\u003Cstring> { \"Accept: application\u002Fjson\" };\n        string body = \"\";\n        if (payload.VariantType != Variant.Type.Nil)\n        {\n            headers.Add(\"Content-Type: application\u002Fjson\");\n            body = Json.Stringify(payload);\n        }\n        if (AuthToken != \"\")\n            headers.Add(\"Authorization: Bearer \" + AuthToken);\n\n        Error err = http.Request(BaseUrl + path, headers.ToArray(), method, body);\n        if (err != Error.Ok)\n        {\n            http.QueueFree();\n            return new ApiResult(false, 0, default, $\"Request() failed: {err}\");\n        }\n\n        Variant[] res = await ToSignal(http, HttpRequest.SignalName.RequestCompleted);\n        http.QueueFree();\n        if (res[0].AsInt64() != (long)HttpRequest.Result.Success)\n            return new ApiResult(false, 0, default, $\"Transport error {res[0]}\");\n\n        long code = res[1].AsInt64();\n        string text = res[3].AsByteArray().GetStringFromUtf8();\n        Variant data = text == \"\" ? default : Json.ParseString(text);\n        return new ApiResult(code is >= 200 and \u003C 300, code, data, code \u003C 400 ? \"\" : text);\n    }\n}\n```\n\nCall it from anywhere:\n\n```gdscript\nvar res := await Api.request_json(\"\u002Fscores\", HTTPClient.METHOD_POST, {\"name\": \"Ada\", \"score\": 1200})\nif not res.ok:\n    show_error(res.error)\n```\n\n```csharp\nvar api = GetNode\u003CApi>(\"\u002Froot\u002FApi\");\nvar res = await api.RequestJson(\"\u002Fscores\", HttpClient.Method.Post, new Godot.Collections.Dictionary { { \"name\", \"Ada\" }, { \"score\", 1200 } });\nif (!res.Ok)\n    ShowError(res.Error);\n```\n\nRetries with exponential backoff, request cancellation on scene change, and an auth refresh flow: [references\u002Frest-client-patterns.md](references\u002Frest-client-patterns.md).\n\n---\n\n## 4. JSON Pitfalls\n\n- **Every JSON number parses as `float`.** `{\"id\": 5}` gives `5.0`. Cast before using it as an index, enum, or dictionary key: `int(data[\"id\"])` in GDScript, `data[\"id\"].AsInt32()` in C#. `==` compares `5.0 == 5` as true, but `match` patterns are type-strict, and a dictionary keyed by `5` has no entry for `5.0`.\n- **`JSON.parse_string()` returns `null` on bad input** and logs an error. When you need the line and message, use an instance: `var json := JSON.new(); if json.parse(text) != OK: print(json.get_error_message(), json.get_error_line())`.\n- **Validate shape before indexing.** Check `data is Dictionary and data.has(\"items\")` — a server error page in HTML parses to `null`, and an empty array is still `ok`.\n- **A stringify → parse round trip turns ints into floats** (`stringify` itself writes `5`, the parse brings back `5.0`), and `JSON.stringify(obj)` only works on Variant types — convert custom objects or Resources to a Dictionary first.\n\n---\n\n## 5. Downloads, Uploads, and Images\n\n| Task | How |\n|---|---|\n| Save straight to disk | Set `http.download_file = \"user:\u002F\u002Fcache\u002Fpack.zip\"` before `request()`; the body is written there, not returned |\n| Progress bar | Poll `get_downloaded_bytes()` against `get_body_size()` (`-1` when the server sends no length, and always `-1` on Web) |\n| Cap the size | `body_size_limit` (bytes) → `RESULT_BODY_SIZE_LIMIT_EXCEEDED` |\n| Binary upload | `request_raw(url, headers, HTTPClient.METHOD_PUT, bytes)` with a `Content-Type` header |\n| Show a remote image | `Image.new().load_png_from_buffer(body)` (or `_jpg_`, `_webp_`), then `ImageTexture.create_from_image(image)` |\n\nImage, form-encoded, and multipart recipes with C#: [references\u002Fdownloads-and-uploads.md](references\u002Fdownloads-and-uploads.md).\n\n---\n\n## 6. TLS and Secrets\n\n- **HTTPS works out of the box** against the bundled CA list. For a self-signed or private CA, load the `.crt` and pass `TLSOptions.client(cert)` via `http.set_tls_options()`. `TLSOptions.client_unsafe()` skips validation — never ship it.\n- **Anything in the export is readable.** API keys in scripts, `project.godot`, or an encrypted PCK can be pulled out by a determined player. Keep privileged keys (payment, admin, third-party paid APIs) on a server you control and have the game call that server.\n- **Per-player tokens** (session or refresh tokens) can live in `user:\u002F\u002F`; treat them as revocable, not secret.\n- **Send credentials in headers or a POST body**, never as GET query parameters — URLs end up in logs.\n- TLS 1.2 is supported everywhere and TLS 1.3 from **Godot 4.4**; on 4.3 a TLS 1.3-only server fails with `RESULT_TLS_HANDSHAKE_ERROR`, as does any server limited to TLS 1.1 or older.\n\n---\n\n## 7. Platform Notes\n\n| Platform | Gotcha |\n|---|---|\n| Android | Enable the **INTERNET** permission in the export preset, or every request fails |\n| Web | Requests go through the browser: the server must send CORS headers (`Access-Control-Allow-Origin`), and plain `http:\u002F\u002F` from an `https:\u002F\u002F` page is blocked as mixed content. See **web-export** |\n| Dedicated server | Same API; run requests from the server so keys never reach clients — see **dedicated-server** |\n\n---\n\n## 8. WebSocket Client\n\nUse `WebSocketPeer` for a persistent, server-pushed event stream; use `HTTPRequest` for request\u002Fresponse. Nothing happens unless you call `poll()` every frame (`_process`). Never put long-lived tokens in the URL — URLs end up in logs. Use `wss:\u002F\u002F` with the server's real hostname (not an IP) so the certificate matches. `handshake_headers` is ignored on Web exports, so authenticate with the first message after connecting.\n\n> See [references\u002Fwebsocket-client.md](references\u002Fwebsocket-client.md) for the GDScript and C# client, `wss:\u002F\u002F`, auth, heartbeat, and reconnect rules.\n\n---\n\n## 9. Common Pitfalls\n\n| Symptom | Cause | Fix |\n|---|---|---|\n| `request()` returns `ERR_BUSY` (44) | Reused one `HTTPRequest` for overlapping calls | One node per in-flight request |\n| `request()` returns `ERR_UNCONFIGURED` | Node not in the tree yet | `add_child()` before `request()` |\n| Request hangs forever | `timeout` left at `0.0` | Set `timeout` (5–15 s) on API calls; big downloads need a stall check instead (`timeout` covers the whole transfer) |\n| Works in editor, fails on Android | Missing INTERNET permission | Tick it in the export preset |\n| Works on desktop, fails on Web | CORS or mixed content | Fix server headers; use HTTPS\u002FWSS |\n| `id` is `5.0`, not `5` | JSON numbers are floats | Cast with `int()` |\n| Body empty, file appears in `user:\u002F\u002F` | `download_file` was set | Clear it for in-memory requests |\n| Request never completes after a scene change | The `HTTPRequest` was a child of a node that got freed, so the coroutine never resumes | Parent requests to an autoload (Section 3); don't touch freed nodes after the `await` |\n\n---\n\n## 10. Checklist\n\n- [ ] One `HTTPRequest` per concurrent request; each is `queue_free()`d after completion\n- [ ] `timeout` set on API calls; large downloads use a stall check or cancel button instead\n- [ ] Both the transport `result` and the HTTP `response_code` are checked\n- [ ] JSON numbers cast to `int` where integers are expected; parsed data shape validated\n- [ ] No privileged API keys in the client build; a server proxies paid or admin APIs\n- [ ] Credentials sent in headers or POST bodies over HTTPS, never in GET URLs\n- [ ] `TLSOptions.client_unsafe()` not used outside local testing\n- [ ] Android preset has the INTERNET permission\n- [ ] Web build tested against the real server (CORS headers, HTTPS\u002FWSS only)\n- [ ] WebSocket `poll()` called every frame; reconnects back off\n- [ ] Failures surface to the player (retry button, offline message) instead of failing silently\n","# Web Services in Godot 4.3+\n\nTalk to REST APIs, leaderboards, analytics, login services, and other HTTP\u002FWebSocket backends. All examples target Godot 4.3+ with no deprecated APIs. GDScript is shown first, then C#.\n\n> **Related skills:** **multiplayer-basics** for real-time game networking with WebSocketMultiplayerPeer, **save-load** for persisting tokens and cached responses, **web-export** for CORS and browser limits, **mobile-development** for Android export permissions, **multithreading** for heavy response parsing off the main thread.\n\n---\n\n## 1. Picking the Tool\n\n| Need | Use | Why |\n|---|---|---|\n| Ordinary REST call, file or image download | `HTTPRequest` node | Handles connect, redirects, gzip, timeout; emits one signal when done |\n| Streaming a response, custom keep-alive, many requests to one host | `HTTPClient` | Low-level; you call `poll()` and drive the state machine yourself |\n| Persistent two-way channel (chat, live events, lobby service) | `WebSocketPeer` | Client socket; call `poll()` every frame |\n| Real-time gameplay sync with RPCs | `WebSocketMultiplayerPeer` | Plugs into `MultiplayerAPI` — see **multiplayer-basics** |\n\n**One `HTTPRequest` node runs one request at a time.** A second `request()` while one is in flight returns `ERR_BUSY`. Create one node per concurrent request (Section 3) rather than queueing on a shared node.\n\n---\n\n## 2. A Single Request with `await`\n\n`request()` only *starts* the request; its return value says whether it could be sent, not whether the server answered. The result arrives on `request_completed(result, response_code, headers, body)`.\n\n```gdscript\nfunc fetch_motd() -> void:\n    var http := HTTPRequest.new()\n    http.timeout = 10.0 # Default 0.0 means wait forever.\n    add_child(http)\n\n    var err := http.request(\"https:\u002F\u002Fapi.example.com\u002Fv1\u002Fmotd\")\n    if err != OK:\n        push_error(\"Could not start request: %s\" % error_string(err))\n        http.queue_free()\n        return\n\n    var res: Array = await http.request_completed\n    http.queue_free()\n\n    var result: int = res[0]\n    var code: int = res[1]\n    var body: PackedByteArray = res[3]\n    if result != HTTPRequest.RESULT_SUCCESS:\n        push_warning(\"Network failure (HTTPRequest.Result %d)\" % result)\n    elif code != 200:\n        push_warning(\"Server answered HTTP %d\" % code)\n    else:\n        print(body.get_string_from_utf8())\n```\n\n```csharp\npublic async void FetchMotd()\n{\n    var http = new HttpRequest { Timeout = 10.0 }; \u002F\u002F Default 0.0 means wait forever.\n    AddChild(http);\n\n    Error err = http.Request(\"https:\u002F\u002Fapi.example.com\u002Fv1\u002Fmotd\");\n    if (err != Error.Ok)\n    {\n        GD.PushError($\"Could not start request: {err}\");\n        http.QueueFree();\n        return;\n    }\n\n    Variant[] res = await ToSignal(http, HttpRequest.SignalName.RequestCompleted);\n    http.QueueFree();\n\n    long result = res[0].AsInt64();\n    long code = res[1].AsInt64();\n    byte[] body = res[3].AsByteArray();\n    if (result != (long)HttpRequest.Result.Success)\n        GD.PushWarning($\"Network failure (HttpRequest.Result {result})\");\n    else if (code != 200)\n        GD.PushWarning($\"Server answered HTTP {code}\");\n    else\n        GD.Print(body.GetStringFromUtf8());\n}\n```\n\nCheck **both** values: `result` is the transport outcome (DNS, TLS, timeout — `RESULT_CANT_RESOLVE`, `RESULT_TLS_HANDSHAKE_ERROR`, `RESULT_TIMEOUT`, …), `response_code` is the HTTP status. A 404 or 500 arrives with `RESULT_SUCCESS`.\n\n---\n\n## 3. A Reusable JSON API Client (Autoload)\n\nWrap the boilerplate once. Register this as an autoload named `Api`; every call spawns its own `HTTPRequest`, so calls can overlap.\n\n```gdscript\n# api.gd — autoload \"Api\"\nextends Node\n\nconst BASE_URL := \"https:\u002F\u002Fapi.example.com\u002Fv1\"\nconst TIMEOUT_SEC := 10.0\n\nvar auth_token: String = \"\"\n\n\n## Returns {ok: bool, code: int, data: Variant, error: String}.\nfunc request_json(path: String, method: HTTPClient.Method = HTTPClient.METHOD_GET, payload: Variant = null) -> Dictionary:\n    var http := HTTPRequest.new()\n    http.timeout = TIMEOUT_SEC\n    add_child(http)\n\n    var headers := PackedStringArray([\"Accept: application\u002Fjson\"])\n    var body := \"\"\n    if payload != null:\n        headers.append(\"Content-Type: application\u002Fjson\")\n        body = JSON.stringify(payload)\n    if not auth_token.is_empty():\n        headers.append(\"Authorization: Bearer \" + auth_token)\n\n    var err := http.request(BASE_URL + path, headers, method, body)\n    if err != OK:\n        http.queue_free()\n        return {\"ok\": false, \"code\": 0, \"data\": null, \"error\": \"request() failed: \" + error_string(err)}\n\n    var res: Array = await http.request_completed\n    http.queue_free()\n    if res[0] != HTTPRequest.RESULT_SUCCESS:\n        return {\"ok\": false, \"code\": 0, \"data\": null, \"error\": \"transport error %d\" % res[0]}\n\n    var code: int = res[1]\n    var text := (res[3] as PackedByteArray).get_string_from_utf8()\n    var data: Variant = JSON.parse_string(text) if not text.is_empty() else null\n    return {\"ok\": code >= 200 and code \u003C 300, \"code\": code, \"data\": data, \"error\": \"\" if code \u003C 400 else text}\n```\n\n```csharp\n\u002F\u002F Api.cs — autoload \"Api\"\nusing System.Collections.Generic;\nusing System.Threading.Tasks;\nusing Godot;\n\npublic partial class Api : Node\n{\n    private const string BaseUrl = \"https:\u002F\u002Fapi.example.com\u002Fv1\";\n    private const double TimeoutSec = 10.0;\n\n    public string AuthToken { get; set; } = \"\";\n\n    public readonly record struct ApiResult(bool Ok, long Code, Variant Data, string Error);\n\n    public async Task\u003CApiResult> RequestJson(string path, HttpClient.Method method = HttpClient.Method.Get, Variant payload = default)\n    {\n        var http = new HttpRequest { Timeout = TimeoutSec };\n        AddChild(http);\n\n        var headers = new List\u003Cstring> { \"Accept: application\u002Fjson\" };\n        string body = \"\";\n        if (payload.VariantType != Variant.Type.Nil)\n        {\n            headers.Add(\"Content-Type: application\u002Fjson\");\n            body = Json.Stringify(payload);\n        }\n        if (AuthToken != \"\")\n            headers.Add(\"Authorization: Bearer \" + AuthToken);\n\n        Error err = http.Request(BaseUrl + path, headers.ToArray(), method, body);\n        if (err != Error.Ok)\n        {\n            http.QueueFree();\n            return new ApiResult(false, 0, default, $\"Request() failed: {err}\");\n        }\n\n        Variant[] res = await ToSignal(http, HttpRequest.SignalName.RequestCompleted);\n        http.QueueFree();\n        if (res[0].AsInt64() != (long)HttpRequest.Result.Success)\n            return new ApiResult(false, 0, default, $\"Transport error {res[0]}\");\n\n        long code = res[1].AsInt64();\n        string text = res[3].AsByteArray().GetStringFromUtf8();\n        Variant data = text == \"\" ? default : Json.ParseString(text);\n        return new ApiResult(code is >= 200 and \u003C 300, code, data, code \u003C 400 ? \"\" : text);\n    }\n}\n```\n\nCall it from anywhere:\n\n```gdscript\nvar res := await Api.request_json(\"\u002Fscores\", HTTPClient.METHOD_POST, {\"name\": \"Ada\", \"score\": 1200})\nif not res.ok:\n    show_error(res.error)\n```\n\n```csharp\nvar api = GetNode\u003CApi>(\"\u002Froot\u002FApi\");\nvar res = await api.RequestJson(\"\u002Fscores\", HttpClient.Method.Post, new Godot.Collections.Dictionary { { \"name\", \"Ada\" }, { \"score\", 1200 } });\nif (!res.Ok)\n    ShowError(res.Error);\n```\n\nRetries with exponential backoff, request cancellation on scene change, and an auth refresh flow: [references\u002Frest-client-patterns.md](references\u002Frest-client-patterns.md).\n\n---\n\n## 4. JSON Pitfalls\n\n- **Every JSON number parses as `float`.** `{\"id\": 5}` gives `5.0`. Cast before using it as an index, enum, or dictionary key: `int(data[\"id\"])` in GDScript, `data[\"id\"].AsInt32()` in C#. `==` compares `5.0 == 5` as true, but `match` patterns are type-strict, and a dictionary keyed by `5` has no entry for `5.0`.\n- **`JSON.parse_string()` returns `null` on bad input** and logs an error. When you need the line and message, use an instance: `var json := JSON.new(); if json.parse(text) != OK: print(json.get_error_message(), json.get_error_line())`.\n- **Validate shape before indexing.** Check `data is Dictionary and data.has(\"items\")` — a server error page in HTML parses to `null`, and an empty array is still `ok`.\n- **A stringify → parse round trip turns ints into floats** (`stringify` itself writes `5`, the parse brings back `5.0`), and `JSON.stringify(obj)` only works on Variant types — convert custom objects or Resources to a Dictionary first.\n\n---\n\n## 5. Downloads, Uploads, and Images\n\n| Task | How |\n|---|---|\n| Save straight to disk | Set `http.download_file = \"user:\u002F\u002Fcache\u002Fpack.zip\"` before `request()`; the body is written there, not returned |\n| Progress bar | Poll `get_downloaded_bytes()` against `get_body_size()` (`-1` when the server sends no length, and always `-1` on Web) |\n| Cap the size | `body_size_limit` (bytes) → `RESULT_BODY_SIZE_LIMIT_EXCEEDED` |\n| Binary upload | `request_raw(url, headers, HTTPClient.METHOD_PUT, bytes)` with a `Content-Type` header |\n| Show a remote image | `Image.new().load_png_from_buffer(body)` (or `_jpg_`, `_webp_`), then `ImageTexture.create_from_image(image)` |\n\nImage, form-encoded, and multipart recipes with C#: [references\u002Fdownloads-and-uploads.md](references\u002Fdownloads-and-uploads.md).\n\n---\n\n## 6. TLS and Secrets\n\n- **HTTPS works out of the box** against the bundled CA list. For a self-signed or private CA, load the `.crt` and pass `TLSOptions.client(cert)` via `http.set_tls_options()`. `TLSOptions.client_unsafe()` skips validation — never ship it.\n- **Anything in the export is readable.** API keys in scripts, `project.godot`, or an encrypted PCK can be pulled out by a determined player. Keep privileged keys (payment, admin, third-party paid APIs) on a server you control and have the game call that server.\n- **Per-player tokens** (session or refresh tokens) can live in `user:\u002F\u002F`; treat them as revocable, not secret.\n- **Send credentials in headers or a POST body**, never as GET query parameters — URLs end up in logs.\n- TLS 1.2 is supported everywhere and TLS 1.3 from **Godot 4.4**; on 4.3 a TLS 1.3-only server fails with `RESULT_TLS_HANDSHAKE_ERROR`, as does any server limited to TLS 1.1 or older.\n\n---\n\n## 7. Platform Notes\n\n| Platform | Gotcha |\n|---|---|\n| Android | Enable the **INTERNET** permission in the export preset, or every request fails |\n| Web | Requests go through the browser: the server must send CORS headers (`Access-Control-Allow-Origin`), and plain `http:\u002F\u002F` from an `https:\u002F\u002F` page is blocked as mixed content. See **web-export** |\n| Dedicated server | Same API; run requests from the server so keys never reach clients — see **dedicated-server** |\n\n---\n\n## 8. WebSocket Client\n\nUse `WebSocketPeer` for a persistent, server-pushed event stream; use `HTTPRequest` for request\u002Fresponse. Nothing happens unless you call `poll()` every frame (`_process`). Never put long-lived tokens in the URL — URLs end up in logs. Use `wss:\u002F\u002F` with the server's real hostname (not an IP) so the certificate matches. `handshake_headers` is ignored on Web exports, so authenticate with the first message after connecting.\n\n> See [references\u002Fwebsocket-client.md](references\u002Fwebsocket-client.md) for the GDScript and C# client, `wss:\u002F\u002F`, auth, heartbeat, and reconnect rules.\n\n---\n\n## 9. Common Pitfalls\n\n| Symptom | Cause | Fix |\n|---|---|---|\n| `request()` returns `ERR_BUSY` (44) | Reused one `HTTPRequest` for overlapping calls | One node per in-flight request |\n| `request()` returns `ERR_UNCONFIGURED` | Node not in the tree yet | `add_child()` before `request()` |\n| Request hangs forever | `timeout` left at `0.0` | Set `timeout` (5–15 s) on API calls; big downloads need a stall check instead (`timeout` covers the whole transfer) |\n| Works in editor, fails on Android | Missing INTERNET permission | Tick it in the export preset |\n| Works on desktop, fails on Web | CORS or mixed content | Fix server headers; use HTTPS\u002FWSS |\n| `id` is `5.0`, not `5` | JSON numbers are floats | Cast with `int()` |\n| Body empty, file appears in `user:\u002F\u002F` | `download_file` was set | Clear it for in-memory requests |\n| Request never completes after a scene change | The `HTTPRequest` was a child of a node that got freed, so the coroutine never resumes | Parent requests to an autoload (Section 3); don't touch freed nodes after the `await` |\n\n---\n\n## 10. Checklist\n\n- [ ] One `HTTPRequest` per concurrent request; each is `queue_free()`d after completion\n- [ ] `timeout` set on API calls; large downloads use a stall check or cancel button instead\n- [ ] Both the transport `result` and the HTTP `response_code` are checked\n- [ ] JSON numbers cast to `int` where integers are expected; parsed data shape validated\n- [ ] No privileged API keys in the client build; a server proxies paid or admin APIs\n- [ ] Credentials sent in headers or POST bodies over HTTPS, never in GET URLs\n- [ ] `TLSOptions.client_unsafe()` not used outside local testing\n- [ ] Android preset has the INTERNET permission\n- [ ] Web build tested against the real server (CORS headers, HTTPS\u002FWSS only)\n- [ ] WebSocket `poll()` called every frame; reconnects back off\n- [ ] Failures surface to the player (retry button, offline message) instead of failing silently\n",{"name":5,"description":7},"master","60c28fdc40706a24576731e9fb3508b9c95258ad","skills\u002Fweb-services",63,"https:\u002F\u002Fgithub.com\u002Fjame581\u002FGodotPrompter","https:\u002F\u002Fgithub.com\u002Fjame581","https:\u002F\u002Fjanmesarc.online\u002F","Software engineer. My biggest passion is game development.","2026-11-14 20:45:49",{"source":8,"skillName":5,"commands":51,"prompt":61,"zipAvailable":62},[52,55,58],{"tool":53,"command":54},"npx","npx skills add jame581\u002FGodotPrompter --skill web-services",{"tool":56,"command":57},"bunx","bunx skills add jame581\u002FGodotPrompter --skill web-services",{"tool":59,"command":60},"pnpm","pnpm dlx skills add jame581\u002FGodotPrompter --skill web-services","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fjame581\u002FGodotPrompter\u002Fblob\u002Fmaster\u002Fskills\u002Fweb-services\u002FSKILL.md",true,[64,70,74],{"path":65,"resourceType":66,"resourceTypeDesc":67,"sizeBytes":68,"sourceHtmlUrl":69},"references\u002Fdownloads-and-uploads.md","REFERENCE","参考文档",9301,"https:\u002F\u002Fgithub.com\u002Fjame581\u002FGodotPrompter\u002Fblob\u002Fmaster\u002Fskills\u002Fweb-services\u002Freferences\u002Fdownloads-and-uploads.md",{"path":71,"resourceType":66,"resourceTypeDesc":67,"sizeBytes":72,"sourceHtmlUrl":73},"references\u002Frest-client-patterns.md",7175,"https:\u002F\u002Fgithub.com\u002Fjame581\u002FGodotPrompter\u002Fblob\u002Fmaster\u002Fskills\u002Fweb-services\u002Freferences\u002Frest-client-patterns.md",{"path":75,"resourceType":66,"resourceTypeDesc":67,"sizeBytes":76,"sourceHtmlUrl":77},"references\u002Fwebsocket-client.md",3151,"https:\u002F\u002Fgithub.com\u002Fjame581\u002FGodotPrompter\u002Fblob\u002Fmaster\u002Fskills\u002Fweb-services\u002Freferences\u002Fwebsocket-client.md",[79,98,128,152,170,186],{"skillNo":80,"name":81,"nameZh":6,"description":82,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":83,"categories":84,"keywords":85,"publishedAt":36},"01M6KRFE5BR2PSD08ZKDAS66R7","xr-development","Use when building VR\u002FAR\u002FXR applications — OpenXR setup, XROrigin3D, hand tracking, controllers, passthrough, and Meta Quest deployment in Godot 4.3+","https:\u002F\u002Fgithub.com\u002Fjame581\u002FGodotPrompter\u002Fblob\u002Fmaster\u002Fskills\u002Fxr-development\u002FSKILL.md",[],[86,87,22,88,23,89,90,91,92,93,94,30,95,96,97],"xr development","development","deployment","vr","setup","tracking","godot 4","ar","hand","Meta","applications","quest",{"skillNo":99,"name":100,"nameZh":6,"description":101,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":102,"categories":103,"keywords":109,"publishedAt":36},"01M6KRF38Q4WSKAYFS56PG87T0","web-export","Use when shipping a Godot game to the browser — Web export preset options, threads vs no-threads and COOP\u002FCOEP headers, hosting on itch.io or your own server, PWA, JavaScriptBridge, user:\u002F\u002F persistence, audio and input limits, and load size","https:\u002F\u002Fgithub.com\u002Fjame581\u002FGodotPrompter\u002Fblob\u002Fmaster\u002Fskills\u002Fweb-export\u002FSKILL.md",[104],{"categoryNo":105,"categoryName":106,"taxonomyType":107,"taxonomyTypeDesc":108},"01JBSEEDCAT000000000000016","图像与多媒体","SCENARIO","使用场景",[110,111,19,112,113,114,115,116,117,118,30,119,120,121,122,22,123,124,25,125,126,127],"web export","export","server","Coop","preset","browser","game","io","load","pwa","Audio","threads","limits","input","hosting","options","size","shipping",{"skillNo":129,"name":130,"nameZh":6,"description":131,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":132,"categories":133,"keywords":142,"publishedAt":36},"01M6KREYFETEBH62ZTN6EZH2X3","using-godot-prompter","Bootstrap skill — establishes how to find and use GodotPrompter skills, with platform-specific tool mapping","https:\u002F\u002Fgithub.com\u002Fjame581\u002FGodotPrompter\u002Fblob\u002Fmaster\u002Fskills\u002Fusing-godot-prompter\u002FSKILL.md",[134,137],{"categoryNo":135,"categoryName":136,"taxonomyType":107,"taxonomyTypeDesc":108},"01JBSEEDCAT000000000000023","Skill与智能体开发",{"categoryNo":138,"categoryName":139,"taxonomyType":140,"taxonomyTypeDesc":141},"01JBSEEDCAT000000000000032","设计师","PROFESSION","适用职业",[143,23,144,145,146,147,148,149,150,151,30],"using godot prompter","bootstrap","with","find","tool","platform","mapping","how","how to",{"skillNo":153,"name":154,"nameZh":6,"description":155,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":156,"categories":157,"keywords":158,"publishedAt":36},"01M6KRER5G7EQWKGAFN8QJKQ69","tween-animation","Use when implementing tweens — property animation, method tweening, chaining, parallel sequences, easing, and common UI\u002Fgameplay motion recipes","https:\u002F\u002Fgithub.com\u002Fjame581\u002FGodotPrompter\u002Fblob\u002Fmaster\u002Fskills\u002Ftween-animation\u002FSKILL.md",[],[159,160,161,162,22,30,163,164,165,166,167,168,169],"Animation","tween animation","parallel","sequences","motion","gameplay","chaining","ui","recipes","common","implementing",{"skillNo":171,"name":172,"nameZh":6,"description":173,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":174,"categories":175,"keywords":176,"publishedAt":36},"01M6KREKGCQMVDV8WX7HWX8BZG","state-machine","Use when building a state machine or refactoring logic into one — enum, node, and resource-based FSM patterns with trade-offs. Not for adding states to an existing one","https:\u002F\u002Fgithub.com\u002Fjame581\u002FGodotPrompter\u002Fblob\u002Fmaster\u002Fskills\u002Fstate-machine\u002FSKILL.md",[],[177,178,179,180,181,182,145,30,169,183,184,22,23,185],"state machine","state","machine","fsm","state machines","trade","trade-offs","node","patterns",{"skillNo":187,"name":188,"nameZh":6,"description":189,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":190,"categories":191,"keywords":192,"publishedAt":36},"01M6KREE370Y80QK838PCRBA0S","shader-basics","Use when implementing shaders — Godot shader language, visual shaders, common visual recipes, and post-processing effects","https:\u002F\u002Fgithub.com\u002Fjame581\u002FGodotPrompter\u002Fblob\u002Fmaster\u002Fskills\u002Fshader-basics\u002FSKILL.md",[],[193,194,195,167,22,23,196,197,198,199,168,200,201,30,169,202],"shader","shader basics","basics","language","post-processing","shaders","post","visual","effects","processing"]