core.html

---
layout: default
title: Core
---

<div class="bubble">
  <h1>Core & UI</h1>
  <p>
    In order to create a viewer project, you need to establish a pathway between
    the user's UI, and the server the virtual world is running on. <br />
    One of the core design decisions about the benthic project was that the UI
    should be completely independent from the business logic of the project, and
    it should be possible for developers to easily swap out UI frameworks
    without much difficulty. Doing it this way has created three discrete layers
    in the benthic project.
  </p>

  <div class="center">
    <div class="bubble-row" style="max-width: 1100px">
      <div class="bubble contrast">
        <h2>User Interface</h2>
        The front end, which users can interact with. All this does is receive
        user input to send to the core, and display output it receives from the
        core. All interaction between the UI and the core should be done with
        messages as small as possible, to ensure that the least amount of logic
        is dependent on non-portable UI systems.
      </div>
      <div class="bubble contrast">
        <h2>Core</h2>
        The asyncronous runtime logic of the program. This handles all of the
        communication between the UI and the server, the parsing and
        manipulating of server data, and sending messages to the UI to display.
        The majority of the project lives here.
      </div>
      <div class="bubble contrast">
        <h2>Server</h2>
        The server that is running the upstream metaverse server code. This is
        the server that manages user connections, responds to requests from
        clients, and informs clients about state changes.
      </div>
    </div>
  </div>
  <p>
    The first thing that starts running is always the UI. The UI is the entry
    point to the viewer, and triggers the Core to begin accepting messages. In
    the debug UI, that is found in the
    <a
      href="https://github.com/benthic-mmo/metaverse_client/blob/7586490c87ca4e001d811be20673fc9b00e2a550/crates/ui/src/main.rs#L15"
      >main()</a
    >
    function in the main.rs file.
    <br />
    <br />
    The Bevy example UI contains a
    <a
      href="https://docs.rs/benthic_ui/latest/benthic_ui/plugin/struct.MetaversePlugin.html"
      >plugin</a
    >, which can be implemented by other bevy projects. This plugin is
    responsible for message handling between the core and the UI, along with
    receiving and rendering mesh data, and can be used by other projects by
    <a
      href="https://github.com/benthic-mmo/metaverse_client/blob/7586490c87ca4e001d811be20673fc9b00e2a550/crates/ui/src/main.rs#L32"
      >adding the plugin</a
    >
    in the main function. The main project is expected to handle viewer state,
    and events raised by the plugin.

    <br />
    <br />
    This plugin triggers the
    <a
      href="https://github.com/benthic-mmo/metaverse_client/blob/7586490c87ca4e001d811be20673fc9b00e2a550/crates/ui/src/plugin.rs#L319"
      >start_core()</a
    >
    and
    <a
      href="https://github.com/benthic-mmo/metaverse_client/blob/7586490c87ca4e001d811be20673fc9b00e2a550/crates/ui/src/plugin.rs#L306"
      >start_listener()</a
    >
    functions on startup.
    <br />
  </p>

  <hr />
  There are now three independent async processes running after startup.
  <div class="bubble-row">
    <a
      href="https://docs.rs/metaverse_core/latest/metaverse_core/initialize/fn.initialize.html"
    >
      <div class="bubble contrast small">
        <h3>Mailbox</h3>
      </div>
    </a>
    <a
      href="https://docs.rs/benthic_ui/latest/benthic_ui/subscriber/fn.listen_for_core_events.html"
    >
      <div class="bubble contrast small">
        <h3>Core Listener</h3>
      </div>
    </a>
    <a
      href="https://docs.rs/metaverse_core/latest/metaverse_core/transport/ui_event_listener/fn.listen_for_ui_messages.html"
    >
      <div class="bubble contrast small">
        <h3>UI Listener</h3>
      </div>
    </a>
  </div>
  The call order looks like this.
  <ol type="1">
    <li>
      <a
        href="https://github.com/benthic-mmo/metaverse_client/blob/7586490c87ca4e001d811be20673fc9b00e2a550/crates/ui/src/plugin.rs#L319"
        >start_core()</a
      >, which spawns an async task where the core will run until the UI is shut
      down
    </li>
    <li>
      <a
        href="https://github.com/benthic-mmo/metaverse_client/blob/7586490c87ca4e001d811be20673fc9b00e2a550/crates/core/src/initialize.rs#L56"
        >initialize()</a
      >, which instantiates the core's actix mailbox, and spawns an async task
      for listening to UI messages that runs until the core is shut down.
    </li>
    <li>
      <a
        href="https://github.com/benthic-mmo/metaverse_client/blob/7586490c87ca4e001d811be20673fc9b00e2a550/crates/core/src/transport/ui_event_listener.rs#L40"
        >listen_for_ui_messages()</a
      >
      which listens on the port specified at the UI's startup, and notifies the
      now-running mailbox for events from the UI.
    </li>
    <li>
      <a
        href="https://github.com/benthic-mmo/metaverse_client/blob/7586490c87ca4e001d811be20673fc9b00e2a550/crates/ui/src/subscriber.rs#L53"
        >Listen_for_core_events()</a
      >
      which listens on the port specified at the UI's startup, and notifies the
      UI for events from the core.
    </li>
  </ol>
</div>
<div class="bubble">
  <h1>UDP Sockets</h1>
  <p>
    The UI and Core communicate through local UDP sockets, which send byte data
    back and forth between the two components. Messages sent between the UI and
    core are defined in
    <a
      href="https://docs.rs/metaverse_messages/latest/metaverse_messages/ui/index.html"
      >messages/ui</a
    >, and are seperated into
    <a
      href="https://docs.rs/metaverse_messages/latest/metaverse_messages/packet/message/enum.UIMessage.html"
      >UIMessage</a
    >
    and
    <a
      href="https://docs.rs/metaverse_messages/latest/metaverse_messages/packet/message/enum.UIResponse.html"
      >UIResponse</a
    >
    objects. <br />
    <a
      href="https://docs.rs/metaverse_messages/latest/metaverse_messages/packet/message/enum.UIMessage.html"
      >UIMessages</a
    >
    are for messages coming from the core to the UI, and
    <a
      href="https://docs.rs/metaverse_messages/latest/metaverse_messages/packet/message/enum.UIResponse.html"
      >UIResponses</a
    >
    are for messages coming from the UI to the core. These types are
    <a
      href="https://github.com/benthic-mmo/metaverse_client/blob/7586490c87ca4e001d811be20673fc9b00e2a550/crates/messages/src/packet/message.rs#L64"
      >serialized</a
    >
    into JSON bytes bytes by serde, and
    <a
      href="https://github.com/benthic-mmo/metaverse_client/blob/7586490c87ca4e001d811be20673fc9b00e2a550/crates/messages/src/packet/message.rs#L69"
      >deserialized</a
    >
    in the same way. This allows the decoding to be a straightforward operation
    of parsing JSON bytes, which can be done easily in any language with
    existing libraries, allowing any UI framework to use the main rust core.
  </p>

  <div class="bubble good wavy">
    <h2>Example UI to core handling flow</h2>
    <div class="bubble-row">
      <div class="bubble contrast">
        <h3>
          <a
            href="https://github.com/benthic-mmo/metaverse_client/blob/7586490c87ca4e001d811be20673fc9b00e2a550/crates/core/src/transport/ui_event_listener.rs#L40"
          >
            Listen_for_ui_messages()</a
          >
        </h3>
        The core starts up, and begins listening for messages from the UI
      </div>
      <div class="bubble contrast">
        <h3>
          <a
            href="https://github.com/benthic-mmo/metaverse_client/blob/7586490c87ca4e001d811be20673fc9b00e2a550/crates/ui/src/login.rs#L103"
            >Send UIResponse</a
          >
        </h3>
        The UI
        <a
          href="https://github.com/benthic-mmo/metaverse_client/blob/7586490c87ca4e001d811be20673fc9b00e2a550/crates/ui/src/plugin.rs#L200"
          >sends a message</a
        >
        to the core
      </div>
      <div class="bubble contrast">
        <h3>
          <a
            href="https://github.com/benthic-mmo/metaverse_client/blob/7586490c87ca4e001d811be20673fc9b00e2a550/crates/core/src/transport/ui_event_listener.rs#L48"
          >
            Retrieve the UIResponse</a
          >
        </h3>
        Parse the response bytes coming from the UI, and then send that
        UIResponse to the mailbox
      </div>
      <div class="bubble contrast">
        <h3>
          <a
            href="https://github.com/benthic-mmo/metaverse_client/blob/7586490c87ca4e001d811be20673fc9b00e2a550/crates/core/src/session.rs#L255"
          >
            Handle the UIResponse message in the mailbox
          </a>
        </h3>
        This UIResponse was a Login, which begins the
        <a
          href="https://github.com/benthic-mmo/metaverse_client/blob/7586490c87ca4e001d811be20673fc9b00e2a550/crates/core/src/session.rs#L259?"
          >login process</a
        >, sending xml-rpc messages between the core and server.
      </div>
    </div>
  </div>

  <div class="bubble good wavy">
    <h2>Example Core to UI message handling flow</h2>
    <div class="bubble-row">
      <div class="bubble contrast">
        <h3>
          <a
            href="https://github.com/benthic-mmo/metaverse_client/blob/7586490c87ca4e001d811be20673fc9b00e2a550/crates/ui/src/subscriber.rs#L53"
          >
            Listen_for_core_events()</a
          >
        </h3>
        The UI starts up, listening to events from the core
      </div>
      <div class="bubble contrast">
        <h3>
          <a
            href="https://github.com/benthic-mmo/metaverse_client/blob/7586490c87ca4e001d811be20673fc9b00e2a550/crates/core/src/transport/udp_handler.rs#L84"
            >Core retrieves an event</a
          >
        </h3>
        Messages are retrieved from the server by the core. Those messages are
        handled as actix actors for processing. If the UI should be informed of
        a change, that message is sent.
      </div>
      <div class="bubble contrast">
        <h3>
          <a
            href="https://github.com/benthic-mmo/metaverse_client/blob/7586490c87ca4e001d811be20673fc9b00e2a550/crates/core/src/session.rs#L190"
          >
            Mailbox send to UI</a
          >
        </h3>
        The mailbox sends UIMessages to the UI using the UDP socket
      </div>
      <div class="bubble contrast">
        <h3>
          <a
            href="https://github.com/benthic-mmo/metaverse_client/blob/7586490c87ca4e001d811be20673fc9b00e2a550/crates/ui/src/subscriber.rs#L61"
          >
            Parse bytes as UIMessage
          </a>
        </h3>
        The UI handles the bytes, and adds it to the Sender. This is a crossbeam
        channel, which creates the message queue for the UI to go through.
        Crossbeam must be used, since this is an asyncronous program interfacing
        with a syncronous UI framework.
      </div>
      <div class="bubble contrast">
        <h3>
          <a
            href="https://github.com/benthic-mmo/metaverse_client/blob/7586490c87ca4e001d811be20673fc9b00e2a550/crates/ui/src/plugin.rs#L239"
          >
            Handle queue
          </a>
        </h3>
        Handle queue is
        <a
          href="https://github.com/benthic-mmo/metaverse_client/blob/7586490c87ca4e001d811be20673fc9b00e2a550/crates/ui/src/plugin.rs#L173"
          >registered</a
        >
        to run every tick of the UI. This means that once a frame, the message
        queue is checked, and any pending messages sent from the core are
        processed. In this example, a
        <a
          href="https://github.com/benthic-mmo/metaverse_client/blob/7586490c87ca4e001d811be20673fc9b00e2a550/crates/ui/src/plugin.rs#L292"
          >ChatFromSimulator</a
        >
        message, which adds the chat to the messages vector, and renders it.
      </div>
    </div>
  </div>
</div>