Skip to content

Eris

Jump to bottom
Maria Aurelia Heine edited this page May 29, 2026 · 11 revisions

🏹 Eris

Eris is rzeka's internal debugger princess. She records all spell lifecycle events (created, has mana, no mana, forgotten), every matter emission/receival occurence (along with their Circumstances) & every message/exception you send to rzeka.

📜🧚🏻‍♀️ She watches with curiosity how your project turns into chaos, but since she is its rather kind goddess, she can and will show you the way out. Only to wait for you to fall into it in a new fashion again - and so the lorentian butterfly cycle continues.

Live Debugger

intro_to_rzeka_debugger.mp4

Debugger is browser-based, it requires a separate Rzeka.Dev dependency and it connects to your game automatically over WebSocket when your game is running.

Current features:

  • matter flow
  • matter casuality tree
  • logging

It all works in real time and requires none in-game UI from you.

📜🌱 Godot sidenote: Eris is available both when you run the game in editor and just as well in your built game.

📜🚧 Live spell status visualisation - including mana state and lifecycle transitions - is planned but not yet implemented in the UI.

Setup

  1. Install the EternalGarden.Rzeka.Dev package in your game project (dev builds only - see Installation).

📜 Remove the EternalGarden.Rzeka.Dev reference for release builds - Eris continues recording internally, the WebSocket server simply isn't started. But for your development builds you might want to keep it since the browser debugger will work for you then aswell, might be handy.

  1. In your game initialization, call EnableDevServer on the Spring before creating the river:
// On startup:
var spring = new Spring();

#if DEBUG
IDisposable devServer = spring.EnableDevServer(); // starts WebSocket on ws://127.0.0.1:10470

// You can override the default 10470 port with:
[...] = spring.EnableDevServer(port: 9222)
// But then after opening browser debugger you must suffix its localhost url with: #port9222
#endif

IRzeka rzeka = spring.Create("MyGame");

// On quit:
rzeka.Dispose();

#if DEBUG
devServer.Dispose();
#endif
  1. Clone this repository and cd into rzeka/ui
  2. Start the Eris UI:
cd rzeka/ui
npm install   # first time only
npm run dev
  1. Go in your browser to the localhost url that got printed in your terminal after npm run dev, by default http://localhost:5173.

The debugger auto-connects to the game's WebSocket server. If the game isn't running, it attempts reconnection automatically every 3 seconds.

📜🧨 On Firefox you might want to go to about:config and set the setting network.websocket.delay-failed-reconnects to false. Otherwise there will be a big delay between reconnection attempts. Dunno if same thing happens on Chrome.

describeOwner

By default Eris groups whos (who emitted/received certain matter) by type only - so 50 instances of the same class look identical in the debugger. You can pass a describeOwner lambda to Spring.Create to give each instance a label:

IRzeka rzeka = spring.Create(
    name: "MyGame",
    describeOwner: who => (who as Node)?.Name   // Godot
);

📜 The hook is engine-specific - Unity callers can instead use MonoBehaviour.gameObject.name, plain C# callers can leave the hook off or implement something like a custom INamedOwner interface with a name getter.

Running the Demo

A demo test is included that spins up Rzeka with sample spells and emits matter on timers, useful for developing the UI or verifying the debug pipeline:

Terminal 1 - start the UI

  • cd rzeka/ui
  • npm run dev

Terminal 2 - run the demo (30 seconds)

  • cd rzeka/tests
  • dotnet test --filter "FullyQualifiedName~DebugServerDemo" -- xUnit.MaxParallelThreads=1

rzeka

Clone this wiki locally