MultiuserEditorPlugin

Inherits: EditorPlugin < Node < Object

Editor plugin that coordinates native multiuser editing sessions.

Description

MultiuserEditorPlugin is the editor-side coordinator for the Multiuser Editor module. It manages ENet session hosting and joining, routes collaboration packets, tracks connected peers, and wires the editor UI to the scene, script, lock, and cursor synchronization subsystems.

When enabled through the Blazium/Multiuser Editor editor settings, the plugin can host a local collaboration session or join a remote host. It synchronizes supported scene changes, selected-node locks, script attach and detach operations, CRDT-backed script edits, and remote script cursor positions. The plugin is intended for editor use and is registered so its generated documentation can describe the module surface.

Methods

bool	can_host_sessions() const
void	create_checkpoint(name: String)
String	get_local_peer_id() const
Array	get_recent_security_events_snapshot(max: int = 32) const
String	get_status_text() const
void	host_from_settings()
void	host_session(port: int, password: String = "")
bool	is_local_admin() const
bool	is_session_connected() const
void	join_from_settings()
void	join_session(host: String, port: int, password: String = "")
void	jump_to_peer(peer_id: String)
void	kick_peer(peer_id: String)
void	load_checkpoint(index: int)
void	load_session()
void	reload_access_list()
void	request_git_op(op: String)
void	request_git_op_commit(message: String)
void	request_git_op_with_branch(op: String, branch: String)
void	request_magic_repair()
void	save_session()
void	send_chat(message: String)
void	stop_session()
void	toggle_follow_peer(peer_id: String)
void	trigger_autowork()
Dictionary	validate_jwt_static(jwt: String, secret: String, config: Dictionary) static

---

Method Descriptions

bool can_host_sessions() const 🔗

Returns true when the local editor is configured to host Multiuser Editor sessions, taking into account the blazium/multiuser_editor/enabled killswitch, the blazium/multiuser_editor/role setting (must be Host), and the access-list configuration. Returns false when hosting is disabled or when the editor is currently connected as a client.

---

void create_checkpoint(name: String) 🔗

Captures a labeled snapshot of the current scene/script replication state and stores it in the in-memory checkpoint list. The captured state is built from the action interceptor's build_initial_state_actions output and is truncated to the blazium/multiuser_editor/limits/checkpoint_state_max entry cap when larger; a warning is logged when truncation occurs. name is stored alongside the snapshot's UNIX timestamp so users can later identify and restore the checkpoint via load_checkpoint().

---

String get_local_peer_id() const 🔗

Returns the stable per-installation peer identifier used by the Multiuser Editor module to identify this editor on the wire. The value is generated locally and is independent of the transport-level network id assigned by ENet, so it survives reconnects and is shared across host/join sessions. Returns an empty string when no session has been initialized yet.

---

Array get_recent_security_events_snapshot(max: int = 32) const 🔗

Returns up to max of the most recent security events captured by the Multiuser Editor dock as an Array of Dictionary. Each dictionary contains the keys when_msec (uint64 timestamp in milliseconds), severity (int) and its alias level (same int value, exposed for parity with the SecuritySink callback signature), category (int log category), kind (int matching the MultiuserEditorDock.KIND_* family), and message (String). The buffer is bounded by blazium/multiuser_editor/limits/security_events_max and is intended for tooling, MCP integrations, and automated diagnostics.

---

String get_status_text() const 🔗

Returns the human-readable status string the Multiuser Editor dock displays in its header (e.g. "Hosting on port 8910", "Connected to host:port as Editor", "Disconnected"). Useful for surfacing the current session state to GDScript-driven tooling, custom UIs, or MCP probes without needing to inspect individual settings or peer state.

---

void host_from_settings() 🔗

Convenience wrapper that starts hosting a Multiuser Editor session using the persisted editor settings (blazium/multiuser_editor/default_port, blazium/multiuser_editor/jwt_secret_key and friends) instead of explicit arguments. Equivalent to host_session() but reads the port and password from the registered editor settings; intended for the Begin Hosting dock action and for automation that respects user preferences.

---

void host_session(port: int, password: String = "") 🔗

Starts a new collaboration session as the host on the given UDP port. port must be in the range 1024 to 65535; out-of-range values are refused and logged. The optional password is used by the handshake to authenticate joining peers and is treated as opaque bytes by the transport.

The host enforces the inside-loaded-project and safe-branch guards before binding the port: if blazium/multiuser_editor/git_auto_branching is enabled, both the configured session branch and merge target branch must pass the internal MultiuserEditorActionInterceptor::is_safe_branch_name check or hosting is refused. On success, the local role becomes Admin, the project settings replication cache is seeded, and (when blazium/multiuser_editor/file_sync/enabled is true) the res:// snapshot is captured and the include/exclude patterns become active. Hosting is unavailable in web client-only builds; in that case the call is a no-op with a warning.

---

bool is_local_admin() const 🔗

Returns true when the local editor's effective role in the active session is Admin. The host always assumes the Admin role on successful host_session(); clients receive their role through the authentication handshake and the access list. Useful for gating editor UI such as kick controls, force-push, and other host-only operations.

---

bool is_session_connected() const 🔗

Returns true when the underlying ENet transport reports an active connection and the local peer has completed the Multiuser Editor authentication handshake (HMAC or JWT, depending on the blazium/multiuser_editor/require_jwt setting). A peer that is mid-handshake or stalled in the pending-challenge state returns false.

---

void join_from_settings() 🔗

Convenience wrapper that joins a Multiuser Editor session using the persisted editor settings (blazium/multiuser_editor/default_host, blazium/multiuser_editor/default_port, blazium/multiuser_editor/client_jwt) instead of explicit arguments. Equivalent to join_session() but reads the host, port, and password/JWT from the registered editor settings; intended for the Connect dock action and for automation that respects user preferences.

---

void join_session(host: String, port: int, password: String = "") 🔗

Connects to a remote multiuser session at host:port. The connection is refused (with an error log) when the call is made outside a loaded Godot project, when port is outside 1024-65535, when host is empty or longer than 253 characters, or when password exceeds the blazium/multiuser_editor/limits/multiuser_uri_password_max_chars cap. Any prior session is torn down before the join attempt.

After the transport connects, the editor must complete the authentication handshake before receiving its role; until then is_session_connected() returns false. The optional password is forwarded to the host's challenge/response authenticator.

---

void jump_to_peer(peer_id: String) 🔗

Snaps the local editor camera (3D viewport or 2D canvas) to the last reported position of the peer identified by the stable Multiuser Editor peer_id (the same identifier returned by get_local_peer_id() on each peer). Single-shot equivalent of toggle_follow_peer(): the local view jumps once and does not continue tracking. The call is silently ignored when peer_id is unknown or has not yet broadcast telemetry.

---

void kick_peer(peer_id: String) 🔗

Disconnects the peer identified by the stable Multiuser Editor peer_id (the same identifier returned by get_local_peer_id() on each peer). The call is silently ignored when the local editor is not the host, when peer_id is unknown, or when the resolved network id is reserved for the host itself (1). Kicking a peer immediately closes the underlying ENet connection; the kicked client receives the standard disconnect notification.

---

void load_checkpoint(index: int) 🔗

Restores the edited scene to the state captured by the indexth checkpoint (zero-based) previously created via create_checkpoint(). Out-of-range indices are silently ignored. The restore is broadcast to all peers when invoked on the host so that the entire session converges to the checkpoint state; on a client this method is a no-op.

---

void load_session() 🔗

Restores a previously saved Multiuser Editor session snapshot from disk (the file produced by save_session()) and re-applies it to the editor. Includes saved scene state, chat history, checkpoint list, and replicated project settings. Used by the dock's Load Session action and intended for resuming a collaborative session after editor restart.

---

void reload_access_list() 🔗

Reloads the local access list (codename, password hash, and role entries) from the file pointed to by blazium/multiuser_editor/access_list/path. The maximum number of entries is bounded by blazium/multiuser_editor/access_list/max_entries. When blazium/multiuser_editor/access_list/enabled is false, the in-memory list is cleared instead of read from disk. After reloading, the access-list file is re-marked as a protected path so it cannot be replicated through file sync.

---

void request_git_op(op: String) 🔗

Convenience wrapper around request_git_op_with_branch() that issues the git operation op without an explicit branch argument. Supported operations include pull, pull_rebase, push, force_push, status, and current_branch. When called on the host, the request is validated and executed locally and the result is broadcast to peers; when called on a client, the request is sent to the host as a git_request action. Operations require blazium/multiuser_editor/git_remote_actions_enabled to be enabled, and force_push additionally requires is_local_admin() (or blazium/multiuser_editor/allow_editor_force_push).

---

void request_git_op_commit(message: String) 🔗

Issues a git add . && git commit -m "message" sequence through the multiuser git pipeline using message as the commit message. On the host, the request is validated, throttled, and executed asynchronously by the git worker; on clients, the request is forwarded to the host as a git_request action. As with other git operations, blazium/multiuser_editor/git_remote_actions_enabled must be true, and any failure (validation, throttle, or git unavailability) is reported back through a broadcast git_response action.

---

void request_git_op_with_branch(op: String, branch: String) 🔗

Issues a git operation op with an explicit branch argument. Used by branch-aware operations such as branch_create and branch_switch; pass an empty string for branch when the operation does not need one (equivalent to calling request_git_op()). The remote name is taken from blazium/multiuser_editor/git_default_remote (defaulting to origin). On the host, the request is validated against the action permission matrix and the safe-branch-name rule before execution; on clients, the request is wrapped in a git_request action and sent to the host.

---

void request_magic_repair() 🔗

Sends a magic_repair_request action to the host containing the local scene's content hash. If the host detects a divergence from its own scene hash it responds with magic_repair_start and re-broadcasts an authoritative initial-state snapshot to this client, wiping and rebuilding the local edited scene. Used by the dock's Repair action when peers detect that they have drifted out of sync.

---

void save_session() 🔗

Serializes the current Multiuser Editor session (active scene, chat history, checkpoint list, replicated project settings) to the on-disk session file. The companion of load_session(); used by the dock's Save Session action and by automated CI flows that want to capture a session state before disconnecting.

---

void send_chat(message: String) 🔗

Broadcasts a text message to all connected peers in the active multiuser session. The message will be formatted and displayed in the shared chat interface of the Multiuser Dock across all clients.

---

void stop_session() 🔗

Tears down the active multiuser session, closing the ENet host or client, releasing all peer locks, clearing the per-peer cursor overlay, draining the git worker, and resetting the local role and authentication state. Safe to call when no session is active; in that case the call is a no-op. After stopping, is_session_connected() returns false and the dock UI returns to its idle state.

---

void toggle_follow_peer(peer_id: String) 🔗

Toggles the editor's viewport camera tracking for a specific peer. When tracking is enabled, the local editor view will continuously align and jump to match the target peer's 3D/2D camera perspective. Calling this method again with the same peer_id disables the tracking behavior.

---

void trigger_autowork() 🔗

Dispatches a network broadcast commanding external listeners or AI orchestration layers (such as JustAMCP) to evaluate and automatically resolve issues or fulfill requests regarding the current selection or environment state.

---

Dictionary validate_jwt_static(jwt: String, secret: String, config: Dictionary) static 🔗

Statically validates a Multiuser Editor JWT jwt against the shared HMAC secret using the validation parameters supplied in config. The config dictionary accepts the optional keys algorithms_csv (default "HS256"), expected_audience, expected_issuer, leeway_sec (float, default 30.0), max_token_age_sec (int, default 3600), require_jti (bool, default false), and jti_cache_max (int, default 4096). Returns a dictionary with the keys valid (bool), reason (String, set when valid is false), role (String role claim from the token), and jti (String JWT id, when present). The static form is intentionally side-effect-free and does not consult or update the running plugin's JTI replay cache.