Technology

VEML — Structure

VEML (Virtual Environment Markup Language) is an XML-based schema for describing 3D worlds. It defines entities, their positions, lighting, terrain, sky, and synchronization — all in a human-readable, declarative format.

Entity types include mesh, character, light, terrain, text, canvas, HTML overlays, buttons, water, and vehicles. Each entity has position, rotation, and scale as child elements.

<veml>
  <metadata>
    <title>My World</title>
    <capability>javascript</capability>
    <script>scripts/init.js</script>
  </metadata>
  <environment>
    <background>
      <color>white</color>
    </background>
    <entity xsi:type="mesh" tag="tree">
      <transform xsi:type="scaletransform">
        <position x="0" y="0" z="5" />
        <rotation x="0" y="0" z="0" w="1" />
        <scale x="2" y="2" z="2" />
      </transform>
      <mesh-name>tree.glb</mesh-name>
      <mesh-resource>tree.glb</mesh-resource>
    </entity>
  </environment>
</veml>

JavaScript — Behavior

Standard JavaScript adds interactivity to worlds. Scripts run inside a sandboxed interpreter (JINT) in the world browser — they cannot access the host system.

The World API provides globals for working with entities, input, networking, and world state: Entity, World, Input, HTTP, MQTT, WebSocket.

// Create a cube and make it interactive
var pos = new Vector3(0, 1, 3);
var rot = new Quaternion(0, 0, 0, 1);
var color = new Color(0.2, 0.6, 1, 1);

var box = MeshEntity.CreateCube(
    null, color, pos, rot, null,
    "onBoxLoaded"
);

function onBoxLoaded(entity) {
    entity.SetVisibility(true, true);
    entity.SetInteractionState(
        InteractionState.Physical
    );
}

Architecture

WorldOS is built around an MQTT message bus (Mosquitto). Everything beyond the bus is a plugin — a separate process that subscribes to topics, processes messages, and publishes results. Plugins are isolated from each other: if one crashes, the rest keep running.

Plugins can be written in any language. The framework provides SDKs for Node.js/TypeScript and Python. Plugins can also run as Docker containers or native binaries. Each plugin declares its MQTT topics in a manifest file (wos-plugin.yaml).

There are two plugin lifecycle models: persistent plugins run for the server's lifetime and are health-checked periodically. Transient plugins spin up on demand when a matching message arrives, then terminate after completing their task.

What Plugins Do

A plugin is any process that communicates over MQTT. Examples of what plugins handle:

• World state management and entity persistence
• ROS 2 robotics integration (via rosbridge protocol)
• Docker container lifecycle management
• USD scene interaction
• User identity and authentication
• Messaging, presence, and asset management
• Custom game logic, AI agents, terrain generation

Example Topics

wos/ros2-bridge/cmd_vel
wos/container-manager/start
world/zone01/enter
world/crate_01/trigger/open
worldsync/user/position

Plugins communicate through topics without knowing about each other. You compose a world server by choosing which plugins to run.