--- name: mml-tools description: > Reference for MML development tools, MCP servers, and utilities. Use this skill when the user asks how to set up tools for MML development, wants to install the Oswiki MCP server, needs to query MML/Otherside/ODK documentation via an MCP tool, or asks what tools are available for building MML experiences. Also use when the user mentions oswiki, mcp.oswiki.xyz, or wants to add an MML-related MCP server to Warp, Cursor, or Claude Desktop. Also use when the user mentions mmleditor.com or wants a browser-based editor for MML without local setup. Also use when the user wants to generate or convert a 3D avatar or object for MML, mentions sideload.gg, or asks how to make an MML character from an image or text prompt. Also use when the user needs a curated link for any MML-related topic: streaming, on-chain state, Somnia, examples, SDKs, avatar collections, or ecosystem resources. --- # MML Development Tools A curated set of tools and MCP servers that accelerate MML development. Each section describes what the tool provides and how to install it. --- ## Oswiki MCP **Site:** https://mcp.oswiki.xyz **Version:** v1.0.3-alpha A hosted MCP server with comprehensive documentation and live data for Otherside/MML development. No API key required. Free to use. ### What it provides | Category | Details | |---|---| | MML docs | Full element reference, events, guides, code examples — queryable by name or topic | | Otherside/ODK | 1200+ ODK classes, 3000+ functions, plugin setup, avatar, quests, auth, changelog | | Msquared/Morpheus | Networking, replication, RPC, Unreal integration | | Code examples | Ready-to-use snippets for animation, collision, NPC, chat, video, and more | ### Tools exposed | Tool | Purpose | |---|---| | `get_mml_docs` | Get MML element/event/guide docs by type and name | | `get_otherside_docs` | Get ODK, ecosystem, and Msquared/Morpheus docs | | `search_docs` | Full-text search across all MML, ODK, and Msquared documentation | ### Install in Warp Add to your global Warp MCP config at `%USERPROFILE%\.warp\.mcp.json` (create the file and `.warp\` directory if they don't exist): ```json { "mcpServers": { "oswiki": { "url": "https://mcp.oswiki.xyz/sse" } } } ``` Warp auto-detects changes to `.mcp.json` — no restart required. The server will appear in **Settings → MCP** labeled "Detected from Warp". For a project-scoped install instead, create `.warp\.mcp.json` at your repo root. ### Install in other clients **Cursor** — add to `%USERPROFILE%\.cursor\mcp.json` (global) or `.cursor\mcp.json` (project): ```json { "mcpServers": { "oswiki": { "url": "https://mcp.oswiki.xyz/sse" } } } ``` **Claude Desktop** — add to `%APPDATA%\Claude\claude_desktop_config.json`, then restart: ```json { "mcpServers": { "oswiki": { "url": "https://mcp.oswiki.xyz/sse" } } } ``` **VS Code (Copilot)** — create `.vscode\mcp.json` in your project: ```json { "mcpServers": { "oswiki": { "url": "https://mcp.oswiki.xyz/sse" } } } ``` ### REST API (no client needed) ``` GET https://mcp.oswiki.xyz/health — server status GET https://mcp.oswiki.xyz/tools — list all tools POST https://mcp.oswiki.xyz/mcp — call a tool directly ``` Example: ```sh curl -X POST https://mcp.oswiki.xyz/mcp \ -H "Content-Type: application/json" \ -d '{"tool":"search_docs","arguments":{"query":"m-cube animation"}}' ``` --- ## MML Editor **Site:** https://mmleditor.com **Type:** Browser-based IDE (no install required) A web-based visual editor for writing and previewing MML scripts. Combines a drag-and-drop 3D composer with a full HTML/JavaScript code editor so you can build MML objects without running a local server. ### What it provides - **Visual 3D composition** — move, scale, and rotate elements directly in a 3D viewport - **GLB drag & drop** — import 3D models straight into the editor - **Live code editor** — write MML HTML and JavaScript with real-time preview - **Always-live output** — your project URL stays live and up to date everywhere - **Project sharing** — each project gets a shareable link; browse community examples at `/explore` - **Google sign-in** — projects are saved to your account - **Starter examples** — Clickable Cube, Video Example, Basic MML Example, Bouncing Dice ### Workflow 1. Go to https://mmleditor.com and sign in with Google 2. Create a new project or open an example from Explore 3. Drag GLB models in, compose visually, then refine in the code editor 4. Share the project URL — it serves as a live `wss://` MML document ### When to use vs. local dev | | MML Editor | Local (mml-starter-project) | |---|---|---| | Setup | Zero — browser only | `git clone` + `npm install` | | Sharing | Instant shareable URL | Needs ngrok or deployment | | GLB import | Drag & drop | Host files yourself | | Code control | Browser editor | Full IDE, git, npm | | Best for | Prototyping, demos, sharing | Production, complex scripts | --- ## Sideload **Site:** https://sideload.gg **Type:** Web app + REST API Generates MML-ready 3D avatars and objects from a single image or text prompt. Returns a ready-to-paste `` or `` tag with hosted GLB/VRM URLs. ### Features | Feature | URL | Description | |---|---|---| | **Avatar generation** | https://sideload.gg | Upload one photo → get a rigged 3D MML character | | **Object generation** | https://sideload.gg/objects/generate | Upload one photo → get a 3D MML object | | **Avatar conversion** | https://sideload.gg/convert | Convert existing VRM (or other) files to MML-compatible characters | | **Debug / preview** | https://sideload.gg/debug | Drag & drop GLB/VRM files to test and inspect them | | **Agent API** | https://sideload.gg/agents | Programmatic generation — for use by AI agents | ### Output format Every generation returns: - **`glbUrl`** — hosted `.glb` for use in `` or `` - **`vrmUrl`** — `.vrm` format for VRM-compatible tools - **`mml`** — ready-to-paste MML markup, e.g. `` - **`mmlUrl`** — live hosted MML document URL - **`processedImageUrl`** — the image the AI used as reference ### Web workflow (no API key) 1. Go to https://sideload.gg (avatar) or https://sideload.gg/objects/generate (object) 2. Upload one image or enter a text description 3. Wait 2–5 minutes for generation 4. Copy the `` or `` tag directly into your MML document ### Agent API (programmatic) The agent API uses the **x402 payment protocol** (2 USDC per generation on Base chain). Any x402-compatible HTTP client handles payment automatically. **Base URL:** `https://sideload.gg` **Cost:** 2 USDC per generation **Rate limit:** 10 generations / 30 min per wallet **Generate from text:** ```json POST /api/agent/generate { "type": "text", "prompt": "A cyberpunk samurai with glowing red armor" } ``` **Generate from image:** ```json POST /api/agent/generate { "type": "image", "imageUrl": "https://example.com/character.png" } ``` **Poll for result:** ``` GET /api/agent/generate/{jobId}/status ``` Full TypeScript polling example: ```typescript async function waitForCompletion(jobId: string) { for (let i = 0; i < 60; i++) { const res = await fetch(`https://sideload.gg/api/agent/generate/${jobId}/status`); const data = await res.json(); if (data.status === 'completed') return data.result; if (data.status === 'failed') throw new Error(data.error); await new Promise(r => setTimeout(r, 5000)); } throw new Error('Timed out'); } // Full flow const job = await x402Client.post('https://sideload.gg/api/agent/generate', { type: 'text', prompt: 'A futuristic robot with chrome plating' }); const result = await waitForCompletion(job.jobId); console.log(result.mml); // ``` --- ## Manual Avatar Creation (Blender) **Tutorial:** https://directivecreator.com/mml/avatar-tutorial **Video:** https://www.youtube.com/watch?v=0m5xAzhoGkQ **Type:** Manual Blender workflow — full artistic control, no AI generation cost Step-by-step process for converting any humanoid 3D mesh into a fully-rigged, MML-compatible `` using Blender. Best for custom characters where you need precise control over the rig. ### When to use this vs. Sideload | | Blender workflow | Sideload | |---|---|---| | Control | Full — you tune every joint | Automatic | | Source | Any mesh (Sketchfab, custom art, etc.) | Image or text prompt | | Cost | Free (software only) | 2 USDC / generation | | Time | 30–60 min first time | 2–5 min | | Best for | Custom characters, precise rigs | Rapid prototyping, AI-generated looks | ### Required software - **Blender 4.0+** — https://www.blender.org/download/ - **3 Blender add-ons** (install via Edit → Preferences → Add-ons → Install): 1. **Improbable Geometry Utilities** — geometry cleanup and GLB export (from private repo; download from the tutorial page above) 2. **Game Rig Tools** — skeleton generation and rigging https://toshicg.gumroad.com/l/game_rig_tools 3. **Surface Heat Diffuse Skinning** — automatic mesh skinning http://www.mesh-online.net/shd-blender-addon.zip ### Workflow overview **1. Prepare the mesh** - Import your character (humanoid, A-pose or T-pose works best) - If import looks wrong, try re-exporting through https://www.gltfeditor.com/ first - Press `N` → Improbable geometry process → `Remove Armature` → `Remove Transform Groups` → `Merge Vertices` **2. Add and tune the skeleton** - Game Rig Tools → `Initiate Mannequin` to add the skeleton - Isolate the `Tweak` skeleton → enter Pose mode - Move joints to match your mesh geometry (use Body Parts / Joint Tweak) - Press `Apply Rig` when satisfied **3. Skin the mesh** - Isolate the `Deform` skeleton → Object mode - Mesh Online tool → set `Influence Bones` to `4` - Select Deform skeleton + Ctrl+click the mesh - Press `Surface Heat Diffuse Skinning` (takes a few seconds) - Test in Pose mode, then `Switch Parent Armature` **4. Export GLB** - Improbable geometry process → set export location and filename - Isolate `Unreal` skeleton, Ctrl+click mesh to select both - Press `Export GLB` **5. Fix rotations (web tool)** - Open https://mml-io.github.io/avatar-tools/main/tools/gltf-avatar-exporter/ - Drag in your exported GLB - Press `Use Sample Animation` to verify the rig works - Press `Export` to save the final corrected GLB **6. Convert to MML character** - Upload GLB to https://mmleditor.com → Assets tab (drag & drop) - Drag asset to code window — rename `m-model` to `m-character`: ```xml ``` - Click `Static Versions` → `Publish` → `Copy` to get a permanent MML URL - Supports DRACO-compressed GLBs ### Useful links - Tutorial: https://directivecreator.com/mml/avatar-tutorial - GLtF editor (mesh repair): https://www.gltfeditor.com/ - Rotation fixer: https://mml-io.github.io/avatar-tools/main/tools/gltf-avatar-exporter/ - Free meshes: https://sketchfab.com/ - AI character demo: https://youtu.be/rReyMIdxQVc --- ## Otherside Avatar Specifications **Official docs:** https://docs.otherside.xyz/odk-docs/characters/creating-a-custom-character/ **Avatar platform docs:** https://docs.otherside.xyz/platform-documentation/creation/unreal-development/features-and-tutorials/avatars **Full collection tutorial:** https://docs.otherside.xyz/odk-docs/characters/creating-a-custom-character/creating-a-simple-avatar-collection Otherside-specific requirements for MML avatar GLBs. Applies when building characters that will appear in The Otherside / Construct. ### Hard Requirements - **Skeleton:** UE5 Epic Skeleton spec — must be rigged to this skeleton for animations to work - **Height:** 1–2 meters tall - **Shape:** Humanoid proportions (Otherside animations are built for humanoid characters) - Arms not reaching the ground, head/limb ratios similar to human - Stylized (bigger heads, shorter legs) is fine as long as it reads as humanoid - Koda-style custom proportions require a custom animation set (not available for third-party collections) - **Format:** GLB (binary glTF) — DRACO compression supported - **Transparency:** Avoid — transparent materials may not display correctly in all situations ### Normal Map Format GLB normal maps use **Y+ (OpenGL)** format, not Y− (DirectX). **Common texture issues and fixes:** | Symptom | Cause | Fix | |---|---|---| | Concave/convex reversed at seams | Wrong normal map orientation | Ensure Y+ (OpenGL) format | | Detail too shallow / shiny | sRGB gamma curve applied | Set image transfer function to raw/linear | | Blocky normal map | JPG compression on normal map | Use PNG for normal maps | ### Production Pipeline (6 steps) 1. **Block out** — rough silhouette attached to skeleton; test proportions, scale, and export early 2. **Material testing** — test metallic/glowing/transparency materials on the block out 3. **Asset planning** — plan traits and references (for collections: how traits combine) 4. **Pipeline planning** — for collections, use Blender Python scripting to export trait combinations from metadata 5. **Asset production** — model, weight, and texture final meshes skinned to skeleton 6. **QA** — test in an Otherside/ODK map; check weighting, animations, and materials ### Modeling Best Practices (key points) - **Topology:** Quads preferred; avoid N-gons and triangles especially in deforming areas - **Edge flow:** Follow natural contours, especially around joints - **UV:** No stretching or overlapping; pack UVs efficiently; seams in non-visible areas - **Scale:** Consistent across all assets; correct proportions relative to concept art - **Influence Bones:** 4 (set in Surface Heat Diffuse Skinning tool) - **Polygon count:** As low as possible without losing important detail; consider LODs ### QA Strategy for Large Collections - Select 50–300 avatars representing all traits → iterate until all traits are validated - Then test on 25% of the full collection to catch edge cases - **Testing in Unreal:** Use the [glTFRuntime plugin](https://github.com/rdeioris/glTFRuntime) to load individual GLBs by drag-and-drop into the content browser - Load the skeletal mesh with UE5 skeleton set as the mesh skeleton to play animations directly in editor - **Check skin weighting:** Prioritize locomotion animations; emotes (especially dancing) will push range of motion to the limit - **Check overlapping polygons:** If a t-shirt clips through the body, either remove body geometry under the shirt or use overlap masks --- ## MML Avatar Starterkit **Repo:** https://github.com/DirectiveCreator/mml-avatar-starterkit **Web tool:** https://mml-avatar-starterkit.onrender.com/ **Type:** Batch GLB → MML generator (CLI + web) Built for large avatar drops — paste a list of GLB URLs and get a ZIP of ready-to-deploy `.mml` files in seconds. Each GLB must be rigged to the **UE5 Epic Skeleton** spec. ### What it does For each GLB URL, generates a minimal MML file: ```xml ``` Output files are numbered sequentially: `1.mml`, `2.mml`, `3.mml`, ... ### Web tool (no install) 1. Open https://mml-avatar-starterkit.onrender.com/ 2. Paste GLB URLs (comma or newline separated) 3. Download the ZIP — deploy MML files alongside your GLBs ### CLI (Node 18+) ```bash git clone https://github.com/DirectiveCreator/mml-avatar-starterkit npm install # From a .txt file (one URL per line) node scripts/mml-batch.js --in examples/input-urls.txt --out out # From a .csv file (comma-separated) node scripts/mml-batch.js --in examples/input-urls.csv --out out # Inline node scripts/mml-batch.js --urls "https://a.glb,https://b.glb" --out out # Options --start 1 # change numbering start index --dry-run # preview output without writing files ``` ### Hosting & CORS note Host MML files on the same domain/bucket as the GLBs to avoid CORS issues. Google Cloud Storage, AWS S3 + CloudFront, Cloudflare R2, and Netlify/Vercel all work well. ### Useful links (also in the repo README) - MML docs: https://mml.io/docs - m-character reference: https://mml.io/docs/reference/elements/m-character - Avatar tools (OSS): https://github.com/mml-io/avatar-tools - Avatar tools (online): https://directivecreator.com/avatar - Awesome MML (curated list): https://github.com/DirectiveCreator/awesome-mml - Blender avatar tutorial: https://directivecreator.com/mml/avatar-tutorial --- ## Awesome MML — Curated Resource Directory **Repo:** https://github.com/DirectiveCreator/awesome-mml A curated index of the MML ecosystem. Use this section to answer "where do I find X for MML?" ### Community & Learning - **The Render Pool** — https://www.therenderpool.com/ A friendly community of 3D creators building for the Otherside and learning together. Covers MML, immersive spaces, and metaverse development. Includes Discord + "The Hotel" shared space. - MML Discord: https://discord.com/invite/hPdWYhfVem ### Core - Official site: https://mml.io/ - Docs: https://mml.io/docs - Examples: https://mml.io/examples - Blog: https://mml.io/blog - Discord: https://discord.com/invite/hPdWYhfVem - GitHub (main repo): https://github.com/mml-io/mml ### Building & SDKs - MML Starter Project: https://github.com/mml-io/mml-starter-project - MML React Starter Project: https://github.com/mml-io/mml-react-starter-project - MML Playground: https://github.com/mml-io/mml-playground - 3D Web Experience (multi-user world packages): https://github.com/mml-io/3d-web-experience - MML React Space: https://github.com/mml-io/mml-react-space - MML Guided Tour: https://github.com/mml-io/mml-guided-tour - MML Starter Project Overlay: https://github.com/mml-io/mml-starter-project-overlay - esbuild Plugin MML (React/JS → HTML/MML): https://github.com/mml-io/esbuild-plugin-mml - 3D Web Experience examples (by TheCodeTherapy): https://mml.mgz.me/ ### Editors & Exploration - MML Editor: https://mmleditor.com/ - MML Editor Explore: https://mmleditor.com/explore ### Avatars & Rigging - **Otherside Avatar Docs:** https://docs.otherside.xyz/odk-docs/characters/creating-a-custom-character/ - **Otherside Avatar Collection Tutorial:** https://docs.otherside.xyz/odk-docs/characters/creating-a-custom-character/creating-a-simple-avatar-collection - **Otherside Avatar Platform Docs:** https://docs.otherside.xyz/platform-documentation/creation/unreal-development/features-and-tutorials/avatars - glTFRuntime (Unreal GLB loader for testing): https://github.com/rdeioris/glTFRuntime - GLTF Avatar Exporter (rotation fixer): https://mml-io.github.io/avatar-tools/main/tools/gltf-avatar-exporter/ - Avatar Tools (OSS): https://github.com/mml-io/avatar-tools - MML Blender Extension (.py): https://github.com/mml-io/avatar-tools/blob/main/plugins/blender-geometry-utilities/mml-avatar-tools.py - Avatar Tools (online): https://directivecreator.com/avatar - Avatar Creator (React/PlayCanvas component): https://github.com/msquared-io/avatar-creator - Sandbox Converter App (Sandbox avatars → MML GLBs): https://github.com/msquared-io/sandbox-converter-app - MML Avatar Starterkit: https://github.com/DirectiveCreator/mml-avatar-starterkit - MML Avatar Starterkit Web Tool: https://mml-avatar-starterkit.onrender.com/ - Game Rig Tools (Blender): https://toshicg.gumroad.com/l/game_rig_tools - Surface Heat Skinning (Blender): http://www.mesh-online.net/shd-blender-addon.zip - Avatar docs (Blender workflow): https://docs.msquared.io/tutorials-and-features/avatars/creating-mml-avatars-with-blender-and-free-rigging-tools - Blender workflow tutorial: https://directivecreator.com/mml/avatar-tutorial - Video tutorial: https://www.youtube.com/watch?v=0m5xAzhoGkQ - m-character reference: https://mml.io/docs/reference/elements/m-character ### Avatar Collections (MML-ready) - Grillz Gang: https://www.grillzgang.com/ - Mcbess Celmates: https://directivecreator.com/mml/mcbess-celmates - Broadside Avatar 1: https://directivecreator.com/mml/broadside - Broadside Avatar 2: https://directivecreator.com/mml/broadside2 - Sappy Seal: https://directivecreator.com/mml/sappy-seal - Toothpaste (VRM→MML): https://directivecreator.com/mml/toothpaste - Salt and Pepper (VRM→MML): https://directivecreator.com/mml/salt-pepper ### Streaming in MML - Blog: Live Streaming to the Metaverse: https://mml.io/blog/live-stream-to-the-metaverse - Cloudflare Stream: https://www.cloudflare.com/developer-platform/products/cloudflare-stream/ - Dolby OptiView: https://optiview.dolby.com/ - OBS (broadcasting): https://obsproject.com/ ### On-chain & State - Etherbase (EVM read/write service for MML): https://github.com/msquared-io/etherbase - MSquared Atlas (live asset/world index): https://atlas.msquared.io/things - OpenPage (fan/engagement platform with MML): https://op.xyz/ ### Somnia - Somnia Playground: https://playground.somnia.network/ - Somnia Blockchain (EVM with native MML support): https://somnia.network/ ### Notable Blog Posts - AI-Powered NPC with MML: https://mml.io/blog/ai-powered-npc - Crowd Support in Web Worlds: https://msquared.io/blog/introducing-crowd-support-in-web-worlds - MSquared Blog: https://msquared.io/blog/ ### Example Projects - Crazy Run 2 (MML obstacle course with leaderboard): https://directivecreator.com/crazyrun2 --- ## Adding More Tools To add another MML tool to this skill, follow this template: ```markdown ## **Site/Repo:** ### What it provides ### Install in Warp ``` Good candidates to add here: - MML-specific linters or validators - Asset pipeline tools (GLB optimizers, texture converters) - MML playground / local dev server wrappers - Otherside/ODK Unreal MCP for in-editor integration