Repository navigation
Connecting Packages
This guide demonstrates how package authors and developers connect their packages to @m3rcena/bridge using the Universal Package Router model.
The core philosophy of @m3rcena/bridge is strict separation between mechanics and presentation:
- The Engine handles mechanics: Turn validation, board math, bank account balances, dice rolls, cooldowns, and win/loss states.
- The Dashboard handles presentation: React components, 3D Canvas, Tailwind styles, custom sprites, and interactive animations.
- 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!
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;
}All official @m3rcena packages connect to @m3rcena/bridge using the exact same developer patterns. Choose whichever matches your coding style:
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 });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);weky.connectBridge(bridge);
eco.connectBridge(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.
-
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.
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;
}
}bridge.mountPackage(new LevelingBridgeRouter(myLevelingEngine));Now, any dashboard client connecting via HTTP or WebSocket can query /api/levels/rank or /api/levels/card seamlessly!
When a player clicks a button on the dashboard:
- Dashboard client sends
dispatch_actionover WebSocket orPOST /actionvia REST. - The Bridge locates the active session and invokes
onAction(action). - The underlying engine executes the game logic and calculates the new state.
- The Bridge emits a
syncevent. - All connected dashboard clients and Discord message components update instantly with the new state.
Both Discord and Web users play simultaneously with zero latency!
GitHub: M3rcena/m3rcena-bridge โข NPM: @m3rcena/bridge
- Connecting @m3rcena/weky
- Connecting @m3rcena/eco
- Mounting Custom Routers
- Universal Mounting Standard
- Standalone HTTP & WebSocket Server
- Attaching to Express / Fastify / Next.js
- Complete REST API Route Reference
- Real-Time WebSocket Frame Specification
- Browser & Node Client
- React Hooks & useBridgeSession
- Handling Audio Cues & Haptics
- Sending Inbound Moves