Glue Live Edit

Glue Live Edit

Lets a user run a game launched by Glue, switch it into edit mode, and move/resize/tweak objects live. Edits push back to Glue for persistence + codegen. This is FRB1-only — not being redesigned for FRB2, so treat its foundation as fixed rather than something to refactor.

Architecture

Two processes talk over two raw TCP sockets on loopback (GameConnectionManager, one per direction), port from CompilerSettings.json (random 8000-8999 per project). Messages are plain text: "{DtoTypeName}:{json payload}".

• Glue → game: CommandSender.Self.Send(dto) (FRBDK\Glue\GameCommunicationPlugin\GlueControl\CommandSending\CommandSender.cs) serializes a DTO and sends it. Game's CommandReceiver.Receive splits on the first :, reflects over its own HandleDto overloads to find one whose single parameter type name matches, deserializes, and dispatches.
• Game → Glue (e.g. drag/resize results): the game enqueues onto GlueControlManager.GameToGlueCommands (a ConcurrentQueue); GlueControlManager's socket loop drains it and writes to the gameToGlueSocket.
• RefreshManager (Glue side) is the hub that decides, for every kind of Glue-side change (new object, renamed element, variable edit, state created, file changed...), whether to push an incremental command or fall back to CreateStopAndRestartTask (kill + rebuild + relaunch the game) when a live update isn't supported.
• VariableSendingManager turns a Glue property-grid change into GlueVariableSetData DTOs (handles X/Y/Z → RelativeX/Y/Z when attached, collision relationships, tile shape collections, states, etc.) before CommandSender ships them.

The "{DtoTypeName}:{json}" string above is the inner payload. It's wrapped in a JSON Packet {PacketType, Payload} (PacketType "OldDTO") and carried by the actual transport, GameJsonCommunicationPlugin.Common.GameConnectionManager (Common\GameConnectionManager.cs, Glue side) ↔ its embedded twin (Embedded\GameConnectionManager.cs, game side). CommandSender.SendPacketInternal builds the Packet; each direction is a length-prefixed (8-byte size, then ASCII body) blocking send. Connection handshake: game connects two sockets and sends one identifying byte each — 1 = glueToGame, 2 = gameToGlue; Glue's listener Accepts exactly two and routes by that byte.

Connection lifecycle & self-heal (landmine)

Each side runs a 100ms StatusCheck that reconnects (game side) / re-listens (Glue side) whenever the connection is marked dead — but the dead-marking is the bug surface. Both sides track health with a single _isConnected/IsConnected flag that historically was cleared in only one place: the finally of the game→Glue receive loop. A failure on the send direction (glueToGameSocket.Send throwing SocketException 10054 "forcibly closed") did not clear the flag, so StatusCheck never re-listened and every subsequent send hit the same dead socket forever — the classic "live edit connected once, now every Play/Edit switch fails and never recovers." The trigger is usually the other process's reconnect: when the game's receive loop throws, its StartConnecting disposes both sockets before reconnecting, and that dispose is the 10054 the still-"connected" Glue side sees.

Fix pattern (already applied in both GameConnectionManager.cs files): any send-path socket failure calls a ResetConnection(reason) that disposes both sockets and clears the flag, letting the existing StatusCheck re-handshake. Must be symmetric — reset both directions together, because the handshake is order-dependent (byte 1 then byte 2, two accepts); a half-reset desyncs. Diagnostics: the Glue side logs connect/disconnect/reset transitions via PluginManager.CallPluginMethod("Compiler Plugin", "HandleOutput", ...) (game side only reaches Debug.WriteLine, since its output can't cross the broken socket).

Never log or raise a plugin event while holding _lock (Glue side). That log reaches BuildTabView.PrintOutput, and the plugin event reaches arbitrary plugin code — both can end up waiting on the editor's UI thread, while StatusCheck takes the same _lock every 100ms. Background thread holds the lock and waits on the UI thread; UI thread waits on the lock. Glue then freezes with no CPU use, no memory growth, nothing in the output, and a dead close button — indistinguishable from a plain hang, which is why it is expensive to find. Mutate state under the lock, collect the notifications, invoke them after releasing. StatusCheckTask's Task.Delay also needs ConfigureAwait(false): without it the loop resumes on the captured WinForms context and takes the lock on the UI thread in the first place.

The two receive directions need opposite timeout semantics, and one shared Receive helper cannot serve both. The request/response read (SendItemImmediately waiting for the game's reply) must time out, or a game that died mid-request leaves the caller awaiting forever. The inbound game→Glue loop must not — that socket is idle whenever the user is not interacting with the game, so a timeout there tears down a healthy connection and re-handshakes on a fixed period forever, which then drives repeated embedded-game window repositioning (Runner_MoveWindow, GameHostView.ForceRefreshGameArea's deliberate ±1 panel jiggle). If you touch the receive path, check which caller you are changing.

Suspecting a hard-to-repro live-edit bug rather than a socket problem? EmbeddedDiagnosticsLogger (game-side, Embedded\Editing\EditingManager.cs) always runs - no toggle, so a bug that already happened doesn't need logging predicted in advance. It keeps a capped in-memory buffer (Capacity, currently 2000 entries) of every DTO the game receives and its response, click attempts, and selection changes. The Build tab's View Diagnostics Log button fetches the current buffer via GetEmbeddedDiagnosticsLogDto/CommandReceiver.HandleDto, writes it to a fresh timestamped file under %LOCALAPPDATA%\FlatRedBall\Glue\Diagnostics\, and opens it - a snapshot per click, not a continuously-appended file, so it only works while the game is still connected.

Embedded → Generated: how "the editor injects code" works

FRBDK\Glue\GameCommunicationPlugin\GlueControl\Embedded\**\*.cs are the master source templates for the entire runtime live-edit system (command receiver, DTOs, editing manager, variable assignment, models, etc.) — hand-edit these, never the copies.

EmbeddedCodeManager.EmbedAll() (CodeGeneration\EmbeddedCodeManager.cs) copies each listed file into the game project under GlueControl/, converting Editing.Managers.GlueCommands.cs → Editing/Managers/GlueCommands.Generated.cs (dots become path separators, .Generated suffix added). This is what runs on Glux load / whenever live-edit settings change (HandleGluxLoaded, HandlePortOrGenerateCheckedChanged in MainCompilerPlugin.cs). The game project therefore contains a full mirrored copy of the DTOs and runtime logic — there is no shared assembly between Glue and the game.

Landmine: every file in EmbeddedCodeManager.filesToSave is <Compile Remove>d from GameCommunicationPlugin.csproj. They only compile inside a game project, so a clean build of Glue with All.sln proves nothing about them and a typo ships to every live-edit user. Only a game-project build — the BuildSmoke tests that run EmbedAll and compile the output, or launching a sample into edit mode — verifies them.

Gotchas

• A reply's Succeeded is the only readiness signal; its payload is not. Most HandleDto overloads return void, so a healthy game answers them with an empty body — "did it send anything back?" is not a test for whether the command landed. The game marks a command it cannot dispatch yet (GlueControlManager.Self still null during Game1.Initialize) with GameConnectionManager.NotReadyPayload, which SendItemWithResponse turns into an unsuccessful GeneralResponse. CommandSender.Send<T> additionally fails an empty reply, since a typed caller asked for data.
• The debug/edit-mode hook is CustomActivityEditMode(), not "CustomDebugActivity." ScreenManager calls Screen.ActivityEditMode() (virtual, Engines\FlatRedBallXNA\FlatRedBall\Screens\Screen.cs) instead of normal Activity while ScreenManager.IsInEditMode is true. Per-element codegen (CodeWriter.GenerateActivityEditMode, FRBDK\Glue\Glue\CodeGeneration\CodeWriter.cs:1422) calls each named object's own ActivityEditMode() and then CustomActivityEditMode() — an empty partial void users can implement in their hand-written partial class, following the normal generated/custom partial-class split.
• Variable edits during live play are an overlay, not real codegen. Since the game can't reload generated code while running, edited values are applied through GlueControl.Editing.VariableAssignmentLogic.SetVariable (Embedded\Editing\VariableAssignmentLogic.cs) — a large, manually-maintained switch over variable name/type/target-instance-kind (collision relationships, tile shape collections, states, lists, AttachToContainer, etc.) that reflects/screen.ApplyVariables the value onto the live instance. Any variable kind not special-cased here either falls through to generic reflection (works for simple properties) or silently fails to apply — this is the brittleness the user should expect: a new variable type showing up correctly in Glue but not visually updating live almost always means this file needs a new case, not that the DTO plumbing is broken. Actual codegen only happens on the next full rebuild.
• Adding an object type to live edit takes two halves; creation alone is useless. A case in InstanceLogic.HandleCreateInstanceCommandFromGlueInner's switch makes the instance, but VariableAssignmentLogic.GetRuntimeInstance still has to find it by name — and it searches the FRB managers (SpriteManager.ManagedPositionedObjects, ShapeManager.Visible*, InstanceLogic.Self.*AddedAtRuntime), not the screen's fields, which don't exist until the next rebuild. A type living outside those managers (Camera, in SpriteManager.Cameras) needs its own tracking list and lookup probe or every variable set on it fails.
• Edits made while no game is connected (mid-build, or during a reconnect) are caught up on connect by Managers\CompiledElementSweep.cs. It compares each element's GlueSourceHash, compiled into the generated code as an AssemblyMetadata attribute, with Glue's current hash. Only element CustomVariables are resent, and only when hot reload is available; it never restarts the game, since a spurious hash mismatch would restart it in a loop.
• RefreshManager.ShouldRestartOnChange / CreateStopAndRestartTask is the "give up and restart" escape valve. Many Glue-side changes (new variable on an existing type, excluding a variable from a state category, failed object-add/remove round trips) aren't attempted live at all — they just queue a stop+rebuild+relaunch. If a live-edit feature "doesn't work," check whether the relevant RefreshManager/VariableSendingManager handler actually attempts a live push or just restarts.
• An exception on the Glue side of a variable push kills Glue, not just the push. RefreshManager's ReactTo* handlers are async void, so anything VariableSendingManager.ConvertValue throws (a TypeManager.GetDefaultForType on a non-primitive type, for one) skips the output tab and ends the process; the only trace is the crash-*.log Program.HandleExceptionsUnified writes under %LOCALAPPDATA%\FlatRedBall\Glue\Diagnostics. A "Glue crashes during live edit" report almost always means one of these.
• A restart is only lossless if the glux already holds the user's full intent. Every CreateStopAndRestartTask call site abandons whatever the in-flight operation had not yet persisted, so anything a live command implies must be written to the glux before the command is sent, never in a success-only branch after it.
• File-change filtering: RefreshManager.GetIfShouldReactToFileChange explicitly ignores *.Generated.cs/*.Generated.xml changes so that codegen's own file writes don't trigger a feedback loop of restarts.
• ReactToPlayOrEditSet() (MainCompilerPlugin.cs) fires twice per launch-into-edit-mode — once too early. GameHostController.StartRunInEditMode sets IsEditChecked = true before Compile()/DoRun run (so the toolbar shows edit mode while building), which fires PlayOrEdit's change handler and calls ReactToPlayOrEditSet() while the game process doesn't exist yet — guarded with an IsRunning early-out now, since the real send happens later via Runner_GameStarted. The command-line IsInEditMode= launch arg (Game1GlueControlGenerator.cs) looks like an alternate path but its handling is commented out/dead — the socket DTO is the only mechanism.