br-metaverse/ARCHITECTURE.md

br-metaverse Architecture

Overview

br-metaverse is the presentation layer in a three-tier architecture:

┌─────────────────────────────────────┐
│  UNIVERSE (Physics Layer)           │
│  - Z-framework, constants, laws     │
│  - Blockchain consensus             │
└─────────────┬───────────────────────┘
              │ enforces rules
┌─────────────▼───────────────────────┐
│  LUCIDIA (Canonical World)          │
│  - Agent homes, memories, state     │
│  - "Ground truth" for 1,000 agents  │
└─────────────┬───────────────────────┘
              │ interfaces via NATS
┌─────────────▼───────────────────────┐
│  BR-METAVERSE (Spatial OS)          │  ← This layer
│  - Human interface                  │
│  - Multiple rendering modes         │
│  - Developer SDK                    │
└─────────────────────────────────────┘

Core Concepts

Spatial URLs

Navigate the metaverse via URLs that map to physical locations:

br-metaverse://terminal-street
br-metaverse://agent-park/alice
br-metaverse://lucidia/agent-homes/alice-home
br-metaverse://dev/github/BlackRoad-OS

Multi-Modal Rendering

Three art styles that dynamically switch:

1. Illustrated - Anime/story moments, important interactions
2. Pixel - Retro exploration, casual vibes
3. 3D Unity - Complex environments, agent homes

Powered by:

• Custom WebGL shaders for illustrated/pixel
• Ethereal Engine for 3D/multiplayer
• Seamless transitions via mode-switcher

Agent Presence

Agents from Lucidia "project" into metaverse spaces:

• Real-time state from NATS messages
• Visual avatars (characters, robots, NPCs)
• Natural language interaction
• Memory persistence via PS-SHA∞

Technical Stack

Frontend

• Vite - Build tool
• Three.js - WebGL rendering
• TypeScript - Type safety
• Tailwind CSS - Utility styling

Backend

• NATS - Agent message bus
• WebSocket - Real-time sync
• K3s - Container orchestration
• Cloudflare R2 - Asset storage

Rendering Pipelines

Illustrated Pipeline

// Custom toon shader with cel-shading
uniform vec3 lightDirection;
uniform vec3 baseColor;

// Stepped lighting for anime look
float intensity = dot(normal, lightDirection);
float toon = floor(intensity * 4.0) / 4.0;

Pixel Pipeline

// Downscale + nearest-neighbor upscale
renderTarget.setSize(width / pixelSize, height / pixelSize);
material.magFilter = THREE.NearestFilter;

Unity Bridge

// Import glTF scenes from Unity exports
import { EtherealEngine } from '@etherealengine/engine';

Package Structure

br-metaverse/
├── packages/
│   ├── core/                    # Main engine
│   │   ├── src/
│   │   │   ├── engine/          # Rendering core
│   │   │   ├── spatial-browser/ # URL navigation
│   │   │   └── agent-interface/ # NATS connection
│   │   ├── vite.config.ts
│   │   └── package.json
│   │
│   ├── illustrated/             # Anime renderer
│   │   ├── shaders/
│   │   └── materials/
│   │
│   ├── pixel/                   # Pixel art renderer
│   │   ├── shaders/
│   │   └── filters/
│   │
│   ├── sdk/                     # Developer tools
│   │   ├── scene-builder/
│   │   ├── agent-connector/
│   │   └── cli/
│   │
│   └── agent-bridge/            # Lucidia connection
│       ├── nats-client.ts
│       ├── agent-state.ts
│       └── memory-sync.ts
│
├── worlds/
│   ├── terminal-street/         # Command center
│   ├── agent-park/              # Casual space
│   ├── dev-office/              # Coding environment
│   └── templates/               # Starter templates
│
├── docs/
│   ├── world-building.md
│   ├── agent-integration.md
│   └── rendering-modes.md
│
└── deploy/
    ├── cloudflare-workers/
    ├── k3s-manifests/
    └── docker-compose.yml

Data Flow

User enters terminal-street
    ↓
Spatial browser resolves URL to scene
    ↓
Core engine loads world manifest
    ↓
Rendering pipeline (illustrated/pixel/3d) initializes
    ↓
Agent bridge connects to NATS
    ↓
Agents subscribe to world events
    ↓
Agent avatars spawn at positions
    ↓
User clicks agent → Chat interface
    ↓
Messages flow: User → NATS → Agent → Response
    ↓
Memory system records interaction (PS-SHA∞)

Deployment Strategy

Development

npm run dev
# Core engine: http://localhost:5173
# Storybook: http://localhost:6006

Production

npm run build
wrangler pages deploy dist --project-name=br-metaverse

Infrastructure

• Cloudflare Pages - Static WebGL app
• Cloudflare Workers - WebSocket gateway
• Alice/Octavia K3s - NATS cluster
• Cloudflare R2 - 3D assets, textures

Extension Points

Creating New Worlds

import { World } from '@br-metaverse/sdk';

const myWorld = new World({
  name: 'my-world',
  spawn: { x: 0, y: 0, z: 0 },
  style: 'illustrated',
});

myWorld.addAgent('alice', { x: 10, y: 0, z: 5 });
myWorld.addPortal('other-world', { x: 20, y: 0, z: 0 });

Custom Rendering Modes

import { RenderPipeline } from '@br-metaverse/core';

class VoxelPipeline extends RenderPipeline {
  render(scene: Scene) {
    // Custom voxel rendering
  }
}

Agent Behaviors

import { AgentConnector } from '@br-metaverse/agent-bridge';

const alice = new AgentConnector('alice');
alice.on('message', (msg) => {
  console.log('Alice says:', msg);
});

Security

• NATS authentication via JWT tokens
• Agent permissions enforced by Universe layer
• User actions validated server-side
• PS-SHA∞ memory encryption

Performance Targets

• 60 FPS on modern hardware
• 30 FPS minimum on integrated graphics
• < 5 sec initial load time
• < 100ms agent interaction latency
• 1000+ agents visible simultaneously

Future Roadmap

1. Phase 1 - Core engine + terminal-street (Q1 2026)
2. Phase 2 - Agent bridge + illustrated pipeline (Q2 2026)
3. Phase 3 - SDK + community worlds (Q3 2026)
4. Phase 4 - VR/AR support via Ethereal Engine (Q4 2026)