3D Scroll-Based Mario Experience with AI-Powered Crypto Utility Dashboard
Live Demo · Documentation · Architecture · Contributing
MarioClawd is a full-stack web application that combines a real-time 3D scroll experience with a retro pixel-art utility dashboard. Users scroll through an interactive Mario-themed level rendered with Three.js, and when Mario reaches the castle, the screen fades to black and boots into Mario OS — a desktop environment where every app is a conversational AI agent that handles real blockchain operations.
┌──────────────────────────────────────────────────────────────────┐
│ MarioClawd │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ 3D Scroll │ │ Mario OS │ │ Agent │ │
│ │ Engine │ │ Dashboard │ │ Framework │ │
│ │ │ │ │ │ │ │
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │
│ │ │ │ │
│ ┌──────┴────────────────┴────────────────┴──────┐ │
│ │ React + Three.js Frontend │ │
│ │ Scroll · Camera · Entities · Wallet │ │
│ └──────────────────────┬────────────────────────┘ │
│ │ │
│ ┌──────────────────────┴────────────────────────┐ │
│ │ Express.js API Backend │ │
│ │ Agents · Token Launches · Payments · Trade │ │
│ └───────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────┘
| Feature | Description |
|---|---|
| 3D Scroll World | Interactive Mario level with Catmull-Rom camera path, 20-second scroll duration, touch support |
| Mario OS Dashboard | Retro pixel-art desktop with boot sequence, app windows, taskbar, and animated sky backdrop |
| Five AI Agents | Conversational specialists for payments, trading, AI chat, agent management, and token launches |
| Token Factory | Launch tokens on Solana via pump.fun with client-side signing — keep 100% of creator fees |
| Wallet Integration | Phantom and Solflare support with non-custodial transaction signing |
| x402 Payments | HTTP-native USDC micropayments using the 402 Payment Required protocol |
| Solana Trading | Compose @bankrbot trading commands for on-chain execution via X/Twitter |
| Agent Network | Register and manage autonomous AI agents on Moltbook |
git clone https://github.com/MarioClawd/MarioClawd.git
cd MarioClawd
# Install all dependencies
npm install
cd client && npm install
cd ../server && npm install
cd ..
# Configure environment
cp .env.example .env
# Add your API keys to .env
# Start development
npm run devThe client runs on http://localhost:5000 and the API server on http://localhost:3001.
The scroll engine drives the entire 3D experience. It translates scroll input into smooth camera movement along a predefined spline path through the Mario world.
import { ScrollEngine } from './engine/ScrollEngine';
import { CameraPath, WORLD_CAMERA_KEYFRAMES } from './engine/CameraPath';
const engine = new ScrollEngine(controlPoints, {
maxSpeed: 1 / 20, // 20-second scroll duration
smoothingFactor: 0.08, // Input smoothing
duration: 20000, // Total duration in ms
});
engine.on('update', (state) => {
const camera = cameraPath.evaluate(state.progress);
// camera.position, camera.quaternion, camera.fov
});
engine.on('complete', () => {
// Fade to black → Navigate to /app → Boot sequence
});Key components:
ScrollEngine— Handles wheel/touch input, speed capping, smooth interpolationCameraPath— Catmull-Rom spline evaluation with FOV and roll interpolationEntityManager— Spatial grid for enemies, collectibles, and world objects with behavior patterns
Entities (crabs, platforms, decorations) use a behavior-driven animation system:
const entityManager = new EntityManager(cellSize: 16);
entityManager.register({
type: 'enemy',
position: [18, 5.2, 0],
behavior: { pattern: 'walk', speed: 1.8, range: 2.5 },
}, crabMesh);
// Per-frame update
entityManager.update(deltaTime, scrollProgress);
// Spatial queries
const nearby = entityManager.queryRadius(playerPos, radius: 10);Three behavior patterns for crab enemies:
- Walk — Patrol back and forth with wobble animation
- Hop — Bounce in place with squash/stretch deformation
- Clap — Pulse width with rocking motion (claw snapping)
For performance, SkinnedMesh geometry from GLB models is baked into static meshes at load time. The baked geometry is shared across all instances, with cloned materials for individual tinting:
const baked = EntityManager.bakeSkinnedMesh(skinnedMesh);
// baked.geometry — shared across 8 crab instances
// baked.material — cloned per instance for unique colorsThe dashboard is a React SPA styled as a retro operating system:
┌──────────────────────────────────────────┐
│ MARIO OS ●●●●● Connect Wallet ◎ 0 │
├──────────────────────────────────────────┤
│ │
│ ┌────────┐ ┌────────┐ ┌────────┐ │
│ │ Warp │ │Lobster │ │ World │ │
│ │ Zone │ │ Lab │ │ Chat │ │
│ └────────┘ └────────┘ └────────┘ │
│ ┌────────┐ ┌────────┐ │
│ │ Trade │ │ Token │ │
│ │ Zone │ │Factory │ │
│ └────────┘ └────────┘ │
│ │
├──────────────────────────────────────────┤
│ ★ START [🟢][🦀][🧱][⭐][🏰] 12:00 │
└──────────────────────────────────────────┘
Each app opens as a draggable window with a chat interface powered by a specialized AI agent.
All five agents share a unified conversation architecture:
User message → Claude (tool_use) → Tool execution → Result → Response
↕ ↕
System prompt Up to 5 iterations
+ tool definitions per conversation turn
| Agent | App | Tools | Purpose |
|---|---|---|---|
| Pipe Agent | Warp Zone | send_payment, get_payment_history |
x402 USDC payments |
| Crab Agent | Lobster Lab | register_agent, auto_post, list_agents |
Moltbook management |
| Clawd | World Chat | (none — knowledge only) | Crypto/DeFi Q&A |
| Star Agent | Trade Zone | compose_trade |
@bankrbot commands |
| Mint Agent | Token Factory | launch_token |
pump.fun token launches |
The Token Factory uses client-side signing — your wallet deploys the token, so you keep 100% of creator fees:
User provides details → Backend uploads to IPFS → PumpPortal builds tx
→ Server signs mint keypair → User wallet signs as creator → Submit to Solana
→ Token live on pump.fun → Banner uploaded automatically
// 1. Backend builds partially-signed transaction
const { transaction, mintPublicKey } = await prepareToken({
name: 'MoonCoin',
symbol: 'MOON',
description: 'A community token',
walletAddress: userWallet,
});
// 2. User's wallet signs and submits
const signed = await wallet.signTransaction(transaction);
const signature = await connection.sendRawTransaction(signed.serialize());MarioClawd/
├── client/ # React frontend
│ ├── src/
│ │ ├── components/ # React components
│ │ │ ├── ScrollWorld.tsx # 3D scroll experience
│ │ │ ├── MarioCharacter.tsx # Animated Mario model
│ │ │ ├── CrabEnemies.tsx # 8 enemy crabs
│ │ │ ├── SkyDome.tsx # Procedural sky shader
│ │ │ └── Dashboard.tsx # Mario OS desktop
│ │ ├── engine/ # 3D engine systems
│ │ │ ├── ScrollEngine.ts # Scroll input → progress
│ │ │ ├── CameraPath.ts # Spline camera movement
│ │ │ └── EntityManager.ts # Spatial entity system
│ │ ├── agents/ # Agent chat UI
│ │ │ └── AgentChat.tsx # Unified chat component
│ │ ├── wallet/ # Solana wallet integration
│ │ │ └── SolanaProvider.ts # Phantom/Solflare provider
│ │ ├── hooks/ # React hooks
│ │ ├── utils/ # Math utilities
│ │ ├── styles/ # CSS (pixel-art theme)
│ │ └── App.tsx # Router + entry point
│ ├── public/
│ │ ├── models/ # GLB 3D models
│ │ └── textures/ # Texture assets
│ ├── package.json
│ ├── tsconfig.json
│ └── vite.config.ts
├── server/ # Express.js backend
│ └── src/
│ ├── routes/ # API route handlers
│ ├── services/ # Agent + token services
│ └── middleware/ # Auth, CORS, rate limiting
├── shared/ # Shared types + constants
│ ├── types/
│ └── constants/
├── docs/ # GitBook documentation
├── .env.example
├── package.json
├── tsconfig.json
├── CONTRIBUTING.md
├── SECURITY.md
├── CODE_OF_CONDUCT.md
├── CHANGELOG.md
└── LICENSE
| Wallet | Detection | Status |
|---|---|---|
| Phantom | window.solana |
Supported |
| Solflare | window.solflare |
Supported |
Note: Wallet extensions don't work inside iframes. Open the published URL in a regular browser tab for wallet functionality.
| Layer | Technology |
|---|---|
| 3D Rendering | Three.js r182 via React Three Fiber |
| Frontend | React 19, TypeScript 5.8, Vite 7 |
| Styling | CSS with Press Start 2P pixel font |
| Backend | Express.js 5, Node.js 18+ |
| AI | Claude via tool_use architecture |
| Blockchain | Solana (mainnet), @solana/web3.js |
| Token Launches | PumpPortal API + pump.fun IPFS |
| Payments | x402 protocol (HTTP 402) |
| Routing | React Router v7 |
| Variable | Required | Description |
|---|---|---|
ANTHROPIC_API_KEY |
Yes | Powers all five AI agents |
X402_WALLET_ADDRESS |
Optional | x402 payment sender address |
X402_WALLET_KEY |
Optional | x402 wallet private key |
SOLANA_RPC_URL |
Optional | Custom RPC (defaults to public mainnet) |
This project is licensed under the MIT License.