Skip to content

Connecting Packages

M3rcena edited this page Nov 1, 2026 · 2 revisions

๐Ÿ”Œ Connecting Packages to @m3rcena/bridge

This guide demonstrates how package authors and developers connect their packages to @m3rcena/bridge using the Universal Package Router model.


๐ŸŽฏ The Philosophy: Decoupled State vs Custom Visuals

The core philosophy of @m3rcena/bridge is strict separation between mechanics and presentation:

  1. The Engine handles mechanics: Turn validation, board math, bank account balances, dice rolls, cooldowns, and win/loss states.
  2. The Dashboard handles presentation: React components, 3D Canvas, Tailwind styles, custom sprites, and interactive animations.
  3. The Bridge synchronizes everything: Dispatches actions from buttons/clicks, streams state updates over WebSockets, generates on-demand canvas cards, and notifies players.

Developers using the bridge can completely reskin games and economy dashboards without touching the underlying game logic!


๐Ÿ›๏ธ The BridgePackageRouter Interface

To connect any package to the bridge, create an object or class implementing BridgePackageRouter:

export interface BridgeRequest {
  method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
  url: string;        // Full original request URL (e.g., "/api/custom/stats?user=123")
  path: string;       // Full pathname (e.g., "/api/custom/stats")
  subPath: string;    // Path relative to package mount (e.g., "/stats")
  params: Record<string, string>;
  query: Record<string, string>;
  headers: Record<string, string | string[] | undefined>;
  body?: any;
}

export interface BridgeResponse {
  status: number;
  contentType?: string;
  isBuffer?: boolean;
  body: any;
  headers?: Record<string, string>;
}

export interface BridgePackageRouter {
  name: string;                                          // Unique package key (e.g., "weky", "eco")
  basePath: string;                                      // Base mount route (e.g., "/api/weky", "/api/eco")
  handleRequest(req: BridgeRequest): Promise<BridgeResponse | null> | BridgeResponse | null;
}

๐Ÿš€ Unified Package Connection Patterns

All official @m3rcena packages connect to @m3rcena/bridge using the exact same developer patterns. Choose whichever matches your coding style:

Pattern A: Constructor Injection (Recommended)

Pass bridge directly into the package options:

import { M3rcenaBridge } from "@m3rcena/bridge";
import { WekyManager } from "@m3rcena/weky";
import { EcoManager } from "@m3rcena/eco";

const bridge = new M3rcenaBridge();

// Both managers accept { bridge } directly!
export const weky = new WekyManager(client, { bridge });
export const eco = new EcoManager({ bridge });

Pattern B: Fluent Bridge Chaining (bridge.use)

Mount package managers directly to the bridge with Express/Fastify-style fluent chaining:

import { M3rcenaBridge } from "@m3rcena/bridge";
import { WekyManager } from "@m3rcena/weky";
import { EcoManager } from "@m3rcena/eco";

const bridge = new M3rcenaBridge();
const weky = new WekyManager(client);
const eco = new EcoManager();

// Mount both with zero router boilerplate!
bridge.use(weky).use(eco);

Pattern C: Explicit Method Handshake

weky.connectBridge(bridge);
eco.connectBridge(bridge);

๐ŸŽฎ What @m3rcena/weky Exposes via the Bridge:

  • GET /api/weky/games: Returns metadata and schemas for all 17 minigames.
  • POST /api/weky/games/start: Starts a headless game session.
  • POST /api/weky/games/action: Executes a game action (e.g. TicTacToe move, Connect4 drop, 2048 slide).
  • GET /api/weky/cards/gamer-profile: Generates a high-performance Rust canvas gamer card image.
  • GET /api/weky/cards/game-board: Renders on-demand PNG snapshots of current board states.

๐Ÿ’ฐ What @m3rcena/eco Exposes via the Bridge:

  • GET /api/eco/profile/:userId: Balance, bank, vault tier, credit score, inventory, job, and tax status.
  • POST /api/eco/vault/upgrade: Upgrades user bank vault tier.
  • POST /api/eco/loan/apply: Applies for a collateralized bank loan based on credit score.
  • POST /api/eco/casino/play: Headless casino round (Blackjack, Roulette, Slots, Crash).
  • GET /api/eco/cards/bank-card: Generates high-res PNG bank debit cards.
  • GET /api/eco/cards/candlestick: Generates live stock market candlestick charts.

๐Ÿ› ๏ธ Writing Your Own Custom Package Router

Here is how you can create a custom package router for your own system (e.g. an RPG / Leveling system):

import { BridgePackageRouter, BridgeRequest, BridgeResponse } from "@m3rcena/bridge";

export class LevelingBridgeRouter implements BridgePackageRouter {
  public name = "levels";
  public basePath = "/api/levels";

  constructor(private levelingEngine: any) {}

  public async handleRequest(req: BridgeRequest): Promise<BridgeResponse | null> {
    const { subPath, method, query, body } = req;

    // GET /api/levels/rank?userId=123
    if (method === "GET" && subPath === "/rank") {
      const userRank = await this.levelingEngine.getRank(query.userId);
      return {
        status: 200,
        body: userRank,
      };
    }

    // POST /api/levels/award-xp
    if (method === "POST" && subPath === "/award-xp") {
      const { userId, amount } = body;
      const updated = await this.levelingEngine.addXp(userId, amount);
      return {
        status: 200,
        body: { success: true, updated },
      };
    }

    // GET /api/levels/card?userId=123 (Canvas image response)
    if (method === "GET" && subPath === "/card") {
      const imageBuffer = await this.levelingEngine.renderRankCard(query.userId);
      return {
        status: 200,
        contentType: "image/png",
        isBuffer: true,
        body: imageBuffer,
      };
    }

    // Path not handled by this router
    return null;
  }
}

Mounting the Custom Router

bridge.mountPackage(new LevelingBridgeRouter(myLevelingEngine));

Now, any dashboard client connecting via HTTP or WebSocket can query /api/levels/rank or /api/levels/card seamlessly!


๐Ÿ”„ Bidirectional State Sync Flow

When a player clicks a button on the dashboard:

  1. Dashboard client sends dispatch_action over WebSocket or POST /action via REST.
  2. The Bridge locates the active session and invokes onAction(action).
  3. The underlying engine executes the game logic and calculates the new state.
  4. The Bridge emits a sync event.
  5. All connected dashboard clients and Discord message components update instantly with the new state.

Both Discord and Web users play simultaneously with zero latency!

Clone this wiki locally