Easy HTML Launcher Docs

EASY HTML LAUNCHER 2.0.0
Unreal Engine 5.7 and 5.8 | Windows (Win64)

PURPOSE
Show HTML in the external default browser, export UTF-8 HTML files, and receive commands from a trusted local HTML page through a localhost HTTP bridge. This does not embed a browser inside an Unreal widget.

SHOW A PAGE
Call Launch HTML In Browser with a self-contained HTML string. Include <meta charset="utf-8"> for predictable text rendering. Launch HTML In Browser With Result also returns Out File Path and Out Error. True means Windows accepted the open request; it does not certify page rendering. If writing succeeded but opening failed, Out File Path identifies the saved file.

Generated pages are retained under Project Saved/EasyHTMLLauncher so the browser can reload them. Repeated launches create more files and can open more tabs. External images/styles must use URLs or paths that work relative to the generated file; self-contained pages avoid those dependencies.

EXPORT HTML
Save HTML To File opens a folder picker. Default File Name must be a filename, not a path; empty uses output.html. The node appends .html unless .html or .htm is present. Invalid Windows names, reserved device names and path separators are rejected. This existing node replaces a same-named file. Auto Open After Save is optional. Its return value reports saving; a browser-open failure is logged separately. Failed or cancelled saves clear Out Saved File Path.

Save HTML To Path exports without a dialog. File Path can be absolute or relative to Project Saved, for example Reports/session.html. Overwrite Existing=false protects existing files; true explicitly replaces them. Out Saved File Path returns the absolute destination and Out Error explains failure. Parent folders are created. UTF-8 without a byte-order mark is used. Writing a temporary sibling before replacement protects existing reports from failed writes.

Open Folder Picker Dialog returns the selected directory. Cancellation or unavailable UI returns false and clears the output. Native dialogs and browser launching require the interactive game thread; they do not run in commandlets, dedicated servers or unattended runs. Direct export does not require UI.

Escape HTML Text converts ampersands, angle brackets and quotes to HTML entities. Use it for plain text inserted into HTML text or quoted attributes. It does not sanitize arbitrary HTML and is not JavaScript, CSS or URL escaping.

FIRST BROWSER-TO-BLUEPRINT TEST
Use a Level Blueprint, Player Controller or manager Actor's BeginPlay. GameInstance has no BeginPlay event, and its Init event runs before subsystem initialization finishes. For a receiver in a custom GameInstance, call its setup event from a ready gameplay object after BeginPlay.

1. Get Easy HTML Launcher Command Server and check Is Valid.
2. Bind a custom event to On Browser Command Received.
3. Call Start Command Server, normally with port 30010. Check Return Value; on false read Get Last Server Error.
4. On that subsystem, call Get Command Bridge Script.
5. Insert its returned script before </body> in your HTML.
6. Launch the combined HTML with Launch HTML In Browser.
7. Keep the game running, click a page button and inspect your bound Unreal event.

The static Get Browser Command Bridge Script node remains available: specify the same port as the running server. Both helpers return an empty string when that server is inactive. Start first, generate the helper second, open the page third.

EXAMPLE BUTTON
<button onclick="easyHTMLLauncher.sendCommand('StartGame', '', 'event').catch(error => alert(error.message))">Start Game</button>

This button needs the generated bridge script in the same document. In the bound Blueprint event, compare Command with StartGame and test with Print String before connecting gameplay. The plugin provides the interaction entry point; your Blueprint implements StartGame, level loading or other actions. Validate names and payloads before using them to change gameplay state.

PAYLOADS AND EVENTS
On Browser Command Received supplies Command, Payload, Request Type and HTTP Method. String payloads arrive as text. Objects, arrays, numbers, booleans and null arrive as JSON text. For example:
await easyHTMLLauncher.sendCommand('SelectItem', {id:'Potion', count:2}, 'event');

Request Type defaults to event. Custom request-type names preserve case; console is recognized without case sensitivity. HTTP 202 means accepted for dispatch, not confirmation that the Blueprint action finished successfully.

UPGRADING FROM 1.0: SESSION KEYS
Each new server session creates a private key. Command requests require the X-EasyHTMLLauncher-Token header. The generated helper includes it automatically. Existing direct-fetch pages must be updated; unauthenticated pages receive HTTP 403. Generate a fresh helper and reopen the page after stopping/restarting the bridge or beginning a new Play session. Starting the same already-running port is idempotent and keeps its key.

For custom trusted clients, Get Command Session Token returns the key. Put it in the request header, not a URL. Never publish the key or an HTML file containing it. Only combine the helper with HTML/scripts you trust: a page holding the key can send the commands your Blueprint accepts.

POST http://127.0.0.1:30010/easyhtmllauncher/command
Content-Type: application/json
X-EasyHTMLLauncher-Token: KEY_FROM_RUNNING_SUBSYSTEM
Body: {"command":"StartGame","payload":"","type":"event"}

Authenticated GET query requests remain available for compatibility. Percent-encode values: %20 for spaces, %2B for a literal plus. POST with the generated helper is the normal workflow.

CONSOLE COMMANDS
Automatic execution is off by default. Set Allow Console Commands(true) explicitly enables it for authenticated console requests through easyHTMLLauncher.runConsoleCommand(...). Disabled console requests return 403 without dispatching the event. Command availability depends on Unreal and build configuration; development commands may not exist in Shipping.

Execute Console Command String is a separate direct Blueprint/C++ call and does not use the browser permission toggle. Its result cannot certify completion of the requested action. Named Blueprint events give you explicit control over allowed gameplay actions.

LIFECYCLE AND LIMITS
- The subsystem belongs to a GameInstance and can persist through level travel. Keep the receiver alive or rebind after travel. Avoid duplicate event bindings.
- One game instance owns a bridge port in a process. Use different ports for simultaneous game/PIE instances. Another application occupying the port causes startup failure.
- Ports must be 1 through 65535. Invalid start requests leave an existing bridge running. Changing to a different valid port first stops the old bridge; a failed replacement remains stopped.
- Stop Command Server removes this plugin's routes, clears the key and cancels its queued dispatches. Shared Unreal HTTP listeners remain available to other HTTPServer users. An open TCP port alone does not mean the command bridge is active.
- Listener configuration must use localhost or 127.0.0.1. Non-loopback command requests are rejected. This is a local browser bridge, not a remote multiplayer service.
- Command-handler body limit: 64 KiB. Command limit: 4,096 characters. Request Type limit: 64 characters. Authenticated command traffic is limited to 64 requests per second per server. Unreal receives/buffers the HTTP request before handler limits apply.
- Invalid JSON, wrong field types, missing commands and oversized fields return 400. Oversized bodies return 413; rate-limited requests return 429.
- GET /easyhtmllauncher/health checks availability without exposing the key. Is Command Server Running reports plugin route state; health is the external connectivity check.

TROUBLESHOOTING
No subsystem: call from a valid gameplay world after GameInstance subsystem initialization.
Startup false: read Get Last Server Error; check port ownership and HTTPServer listener settings.
Page clicks fail: check the running game, event binding, inserted helper and current port/session key.
403: regenerate an expired helper or check whether console execution was intentionally disabled.
429: reduce request frequency; avoid sending commands every animation frame.
Native dialog unavailable: use an interactive Windows game/PIE session on the game thread. Use Save HTML To Path for unattended export.
Browser-open failure: check Windows' HTML file association. Saving successfully does not guarantee an external application will open the file.
Browser permission/CORS failure: inspect that browser's restrictions and error message. HTTP response headers do not override browser policy.

DEPENDENCIES AND SUPPORT
Module: EasyHTMLLauncher (Runtime).
No additional Unreal plugins are required. HTTPServer, Json and Sockets are bundled engine modules; native dialogs use Windows system libraries.
Blueprint assets: 0. Production C++ classes: 3, including two reflected classes and the module class. The HTTP bridge is not Unreal network replication.

Support: https://discord.gg/9Zc4wbwqG9