Godot Platform Web

# platform_web_patterns.gd
extends Node

# 1. Checking Web Browser Context
# EXPERT NOTE: Simple check to apply web-specific optimizations.
func is_web_runtime() -> bool:
    return OS.has_feature(&"web")

# 2. Safe Fullscreen Request
# EXPERT NOTE: Browsers block fullscreen/mouse-lock unless initiated by a direct user input event.
func _unhandled_input(event: InputEvent) -> void:
    if event.is_action_pressed(&"toggle_fullscreen"):
        # This occurs within an input call, satisfying the user-activation requirement.
        DisplayServer.window_set_mode(DisplayServer.WINDOW_MODE_FULLSCREEN)

# 3. Asynchronous HTTP Data Fetching
# EXPERT NOTE: Low-level TCP is forbidden in browsers. HTTPRequest is the safeFetch abstraction.
func fetch_api_data(url: String) -> void:
    var http := HTTPRequest.new()
    add_child(http)
    http.request_completed.connect(func(r, c, h, b): 
        print("Data received: ", b.get_string_from_utf8())
        http.queue_free()
    )
    http.request(url)

# 4. Checking WebXR Availability
# EXPERT NOTE: Not all desktop browsers support WebXR yet. Check supports signal.
func check_web_xr_support() -> void:
    var webxr := XRServer.find_interface("WebXR") as WebXRInterface
    if webxr:
        webxr.session_supported.connect(_on_webxr_supported)
        webxr.is_session_supported("immersive-vr")

func _on_webxr_supported(session_type: String, supported: bool) -> void:
    print("XR Session ", session_type, " supported: ", supported)

# 5. Handling WebXR Input Modalities
# EXPERT NOTE: Identify if input is gaze-based or a tracked pointer.
func process_webxr_input(source_id: int) -> void:
    var webxr := XRServer.find_interface("WebXR") as WebXRInterface
    if webxr:
        var mode := webxr.get_input_source_target_ray_mode(source_id)
        if mode == WebXRInterface.TARGET_RAY_MODE_TRACKED_POINTER:
            print("Tracked controller active.")

# 6. Lowering Visuals Dynamically for WebGL 2.0
# EXPERT NOTE: Disable expensive TAA/MSAA if the browser environment is struggling.
func optimize_visuals_for_web() -> void:
    if OS.has_feature(&"web"):
        get_viewport().use_taa = false
        get_viewport().msaa_3d = Viewport.MSAA_DISABLED

# 7. Safe Async Clipboard Usage
# EXPERT NOTE: Requires secure context (HTTPS). Check feature flag before use.
func copy_to_web_clipboard(text: String) -> void:
    if OS.has_feature(&"web") and DisplayServer.has_feature(DisplayServer.FEATURE_CLIPBOARD):
        DisplayServer.clipboard_set(text)

# 8. Handling Apple Web (iOS Safari)
# EXPERT NOTE: iOS Safari has specific quirks (like audio context locks).
func is_safari_ios() -> bool:
    return OS.has_feature(&"web_ios")

# 9. Establishing WebSocket Connectivity
# EXPERT NOTE: The ONLY viable real-time multiplayer protocol for standard web exports.
func connect_via_websocket(url: String) -> void:
    var peer := WebSocketMultiplayerPeer.new()
    if peer.create_client(url) == OK:
        multiplayer.multiplayer_peer = peer

# 10. Programmatic Canvas Resize Policy
# EXPERT NOTE: Control how the HTML canvas stretches within the browser container.
func set_web_canvas_policy() -> void:
    # 0 = Proportional, 1 = Full window, 2 = Programmatic
    ProjectSettings.set_setting("html/canvas_resize_policy", 2)

# skills/platform-web/scripts/web_bridge_sync.gd
extends Node

## Web Bridge Sync Expert Pattern
## JavaScriptBridge helpers for browser API integration (fullscreen, persistence, analytics).

class_name WebBridgeSync

# Persistence
static func save_to_local_storage(key: String, data: Dictionary) -> void:
	if not OS.has_feature("web"):
		return
	
	var json_str = JSON.stringify(data)
	# Encode to base64 to avoid character issues in JS string
	var b64_str = Marshalls.utf8_to_base64(json_str)
	
	var js_code = "localStorage.setItem('%s', '%s');" % [key, b64_str]
	JavaScriptBridge.eval(js_code)

static func load_from_local_storage(key: String) -> Dictionary:
	if not OS.has_feature("web"):
		return {}
	
	# JavaScriptBridge.eval returns the value directly
	var b64_str = JavaScriptBridge.eval("localStorage.getItem('%s');" % key)
	
	if b64_str and b64_str is String:
		var json_str = Marshalls.base64_to_utf8(b64_str)
		var result = JSON.parse_string(json_str)
		if result:
			return result
	
	return {}

# Browser Interaction
static func set_tab_title(title: String) -> void:
	if OS.has_feature("web"):
		JavaScriptBridge.eval("document.title = '%s';" % title)

# Analytics Hook (e.g. Google Analytics)
static func send_analytics_event(event_name: String, params: Dictionary = {}) -> void:
	if OS.has_feature("web"):
		# Ensure gtag is defined in index.html, safeguard against missing window.gtag
		# We construct a JS function call dynamically
		var json_params = JSON.stringify(params)
		var js = "if(typeof gtag !== 'undefined') { gtag('event', '%s', %s); }" % [event_name, json_params]
		JavaScriptBridge.eval(js)

## EXPERT USAGE:
## if OS.has_feature("web"): WebBridgeSync.save_to_local_storage("save1", data)

class_name WebBrowserInputGuard
extends Node

## Expert input guard to prevent browser default behaviors.
## Disables context menu (right-click) and spacebar scrolling.

func _ready() -> void:
	if not OS.has_feature("web"): return
	
	JavaScriptBridge.eval("""
		window.addEventListener('contextmenu', e => e.preventDefault());
		window.addEventListener('keydown', function(e) {
			if([32, 37, 38, 39, 40].indexOf(e.keyCode) > -1) {
				e.preventDefault();
			}
		}, false);
	""")

## Rule: Only disable defaults if your game fully handles these inputs.

class_name WebClipboardInterface
extends Node

## Expert browser clipboard integration via Navigator API.
## Handles asynchronous Copy and Paste operations.

func copy_text(text: String) -> void:
	if not OS.has_feature("web"): return
	
	JavaScriptBridge.eval("""
		navigator.clipboard.writeText('%s').then(() => {
			console.log('Web: Text copied to clipboard');
		});
	""" % text)

func paste_text_async(callback_obj: Object, callback_method: String) -> void:
	# Paste requires explicit user permission check in browsers
	var js_callback := JavaScriptBridge.create_callback(func(args):
		callback_obj.call(callback_method, args[0])
	)
	var window := JavaScriptBridge.get_interface("window")
	window.pasteToGodot(js_callback)

## Rule: 'navigator.clipboard' requires a secure (HTTPS) context.

class_name WebExternalURLOpener
extends Node

## Expert utility to open external URLs from a web export.
## Ensures 'noopener' and 'noreferrer' are used for security.

func open_url(url: String, new_tab: bool = true) -> void:
	if not OS.has_feature("web"):
		OS.shell_open(url)
		return
	
	var target := "_blank" if new_tab else "_self"
	JavaScriptBridge.eval("window.open('%s', '%s', 'noopener,noreferrer');" % [url, target])

## Rule: Most browsers block window.open unless triggered by a click/keypress.

class_name WebJavaScriptBridgeCallback
extends Node

## Expert two-way communication between GDScript and JavaScript.
## Demonstrates create_callback for receiving async data from browser APIs.

func _ready() -> void:
	if not OS.has_feature("web"): return
	
	# Create a persistent callback to JS
	var js_callback := JavaScriptBridge.create_callback(_on_js_called)
	
	# Pass the callback to a JS function (e.g., a custom analytic or login hook)
	var window := JavaScriptBridge.get_interface("window")
	if window:
		window.registerGodotCallback(js_callback)

func _on_js_called(args: Array) -> void:
	var message = args[0]
	print("Web: Received message from JavaScript: ", message)

## Rule: Always keep a reference to 'js_callback' to prevent garbage collection.

class_name WebLocalStorageWrapper
extends Node

## Expert wrapper for browser localStorage.
## Features JSON serialization, error handling, and quota checks.

func save_data(key: String, value: Variant) -> bool:
	if not OS.has_feature("web"): return false
	
	var json_str := JSON.stringify(value)
	var storage := JavaScriptBridge.get_interface("localStorage")
	
	try:
		storage.setItem(key, json_str)
		return true
	except: # Handles QuotaExceededError
		push_error("WebLocalStorage: Storage quota exceeded or blocked.")
		return false

func load_data(key: String) -> Variant:
	var storage := JavaScriptBridge.get_interface("localStorage")
	var data = storage.getItem(key)
	if data:
		return JSON.parse_string(data)
	return null

## Rule: Browsers may wipe localStorage; never use it for mission-critical core data.

class_name WebNavigationGuard
extends Node

## Expert navigation guard for web games with unsaved state.
## Triggers a browser confirmation dialog if the user tries to close the tab.

func set_unsaved_changes(has_changes: bool) -> void:
	if not OS.has_feature("web"): return
	
	if has_changes:
		JavaScriptBridge.eval("""
			window.onbeforeunload = function() {
				return "You have unsaved changes. Are you sure you want to leave?";
			};
		""")
	else:
		JavaScriptBridge.eval("window.onbeforeunload = null;")

## Rule: Only enable this during active gameplay or editing sessions.

class_name WebPerformanceProfiler
extends Node

## Expert performance profiler for WebGL/WebGPU.
## Logs memory and draw calls to the browser console.

func log_profle_data() -> void:
	if not OS.has_feature("web"): return
	
	var draw_calls := Performance.get_monitor(Performance.RENDER_TOTAL_DRAW_CALLS_IN_FRAME)
	var memory := OS.get_static_memory_usage() / 1024 / 1024
	
	JavaScriptBridge.eval("console.log('Godot Performance | Draw Calls: %d | Memory: %dMB');" % [draw_calls, memory])

## Tip: Keep draw calls under 500 for stable 60FPS on mid-range mobile browsers.

class_name WebResourceLazyLoader
extends Node

## Expert lazy loading of remote Godot resources/PCKs in the browser.
## Uses HTTPRequest but with browser cache awareness.

func load_remote_pck(url: String) -> void:
	var http := HTTPRequest.new()
	add_child(http)
	http.request_completed.connect(_on_pck_downloaded)
	http.request(url)

func _on_pck_downloaded(result: int, code: int, _headers: PackedStringArray, body: PackedByteArray) -> void:
	if result == HTTPRequest.RESULT_SUCCESS and code == 200:
		# ProjectSettings.load_resource_pack is expert for post-launch content
		ProjectSettings.load_resource_pack(body)
		print("Web: Remote PCK loaded successfully.")

class_name WebResponsiveCanvasAdaptor
extends Node

## Expert canvas resize management for responsive web games.
## Dynamically updates the HTML canvas size via JavaScriptBridge.

func _ready() -> void:
	get_window().size_changed.connect(_update_canvas_size)

func _update_canvas_size() -> void:
	if not OS.has_feature("web"): return
	
	# Force browser canvas to match window inner dimensions
	JavaScriptBridge.eval("""
		var canvas = document.getElementById('canvas');
		canvas.width = window.innerWidth;
		canvas.height = window.innerHeight;
	""")

## Tip: Set 'Stretch Mode' to 'canvas_items' and 'Aspect' to 'expand' in Project Settings.

class_name WebVisibilityAutoPause
extends Node

## Expert tab visibility manager for Web exports.
## Automatically pauses the engine and audio when the tab is hidden.

func _ready() -> void:
	if not OS.has_feature("web"): return
	
	var js_callback := JavaScriptBridge.create_callback(_on_visibility_changed)
	JavaScriptBridge.eval("""
		document.addEventListener('visibilitychange', function() {
			window.onVisibilityChange(document.hidden);
		});
	""")
	var window := JavaScriptBridge.get_interface("window")
	window.onVisibilityChange = js_callback

func _on_visibility_changed(args: Array) -> void:
	var is_hidden: bool = args[0]
	get_tree().paused = is_hidden
	AudioServer.set_bus_mute(0, is_hidden)

## Rule: Always pause audio on visibility change to respect browser user experience.