🌐 English | 简体中文
An immersive 3D multiplayer virtual world system built on Three.js + Express.js + PostgreSQL. Supports multi-world federation interconnection, character customization, 3D building construction and real-time multiplayer interaction. VWFP v2.1 Protocol | Copyright © 2026 Jining Miduo Information Technology Co., Ltd.
- Introduction
- Core Technical Features
- Why I Built This
- Key Features
- Tech Stack
- Quick Start
- Project Structure
- Deployment
- Federation System
- AI Agents
- Admin Console
- License & Subscription
- FAQ
- Related Docs
A 3D virtual world running in your browser — deployed on your own machine, with data fully owned by you.
Install it on your own computer or server, open the browser, and enter a complete 3D world: drag-and-drop to build scenes, customize characters, and invite friends in. Worlds deployed by different people can teleport to each other, with identities and assets following across worlds. It is not a cloud service hosted on a platform, but your own independent node. No account registration, no content moderation, no platform commission, code is unencrypted, modify it however you like.
Sorry for meeting you in an imperfect state. This product has reached the limit of what I can sustain. Sorry for meeting you in an imperfect state. Because I need to go make a living, then continue this project. If many people like it and subscribe, I will update quickly. Even if few people like it, I will keep updating — more means faster progress, less means slower. Making a living while building a dream!
- Independent World — 100% of data belongs to you. Whether on a computer or server, you can deploy this world. This world is your private asset. Place it on a server or an IPv6-enabled computer to make it public, accessible via domain name or IP.
- Asset Privatization — Virtual assets exist only on your computer or server.
- Cross-World Acquisition — Items obtained in other worlds are attributed to the server where the current user is registered.
- Cross-World Teleport — During cross-world teleport, the user's currently configured character style, skeleton, animations, sounds, model style, etc., still take effect in the target world, and appear to others as your configured style.
- Extreme Performance — Two-stage auto compression on upload (gltfpack geometry + sharp textures) cuts model size by 70%+ and VRAM by up to 75%, paired with a smart priority loading queue and graded progress feedback for a smooth experience even on low-end machines.
To let this idea be used more broadly, I now publish the defensive technical disclosure document: PATENT_DISCLOSURE_EN.md
Have you noticed that the current internet is bound by layers of constraints? After AI, programming is not difficult — everyone has the ability to develop software, but do you feel constrained everywhere? Read my article for details:
| User Group | Use Case |
|---|---|
| Individuals | Zero-cost ownership of a 3D virtual space to store images, videos, memories and various virtual assets. If digital immortality can be achieved, this might be your… |
| SMEs | Turn your store into a browsable, playable 3D virtual flagship store — dwell time increased 10× |
| Large Enterprises | Multi-branch federation interconnection, data security self-controlled |
| Educational Institutions | Turn textbooks into 3D worlds you can walk into — completion rate and engagement doubled |
| Scenic Spots/Museums | Never-closing, infinite-capacity, globally accessible digital twin scenic spots |
| Government/Public Organizations | 3D interactive interface for smart cities — digital governance citizens can see and touch |
| Exhibition Industry | 365-day never-ending global virtual expo with zero venue cost |
| Federation Multi-World Interconnection | Multiple independently deployed world instances interconnect, players can travel across worlds |
| User Home (3D World) | Admin Dashboard |
|---|---|
![]() |
![]() |
| Teleport | Teleport Button |
![]() |
![]() |
| World Layout Admin | World Info |
![]() |
![]() |
| Mobile Home | Mobile World |
![]() |
![]() |
- Three.js Powered: Complete 3D scene rendering engine, supports dynamic lighting, shadows and skybox
- Free Building Construction: Geometry buildings (cube/sphere/cylinder, etc.) and GLB/GLTF model upload
- Real-time Multiplayer Sync: WebSocket-driven character position, animation and scene change broadcast
- Mobile Adaptation: Virtual joystick + touchscreen controls
- Auto Model Compression: Uploaded GLBs get two-stage auto compression — gltfpack geometry (meshopt) + texture re-compression (lossless for normal/occlusion, quantized downscaling for color maps). Model size reduced by 70%~90% on average, VRAM usage cut by up to 75%
- Smart Loading Scheduler: Priority loading queue (geometry/media → small models → large models), large-model concurrency control, distance-based phased loading with auto-unload for a fast, smooth world entry
- Loading Progress Visualization: Top progress bar + in-scene 3D progress sprites (downloaded/total bytes), with simulated-progress fallback for clear feedback under any network condition
- World Interconnection: Multiple servers form a federation network, enabling cross-world teleport and access
- Peer-to-Peer Architecture: All worlds interconnect equally, no central coordination node required
- Secure Handshake: RSA-2048 public key exchange + JWT signature verification inter-world authentication mechanism
- VWFP v2.1 Protocol: Self-developed cross-virtual-world federation protocol
- Character Customization: Supports Mixamo, ReadyPlayerMe, VRoid and other multi-platform skeletons
- Animation System: Action library management, skeleton retargeting, weapon mount points
- Real-time Outfit Change: Switch character templates and appearances
- Cross-World Character Migration: Character configuration securely transferred across federation worlds
- NPC System: Custom NPC creation, dialogue and behavior configuration
- Monster System: Combat monster creation and management, item drops
- Portals: In-world and cross-world teleport
- Shop & Inventory: Complete virtual item trading and inventory management
- Skill System: Voice-triggered skills, effects, ranges, cooldowns
- Gallery System: 3D gallery display
- Unified Editor: Geometry + model library, two-in-one
- World Editor: Object placement/move/rotate/scale/spawn point setting
- Character Editor: Appearance customization (hair/face/clothing/equipment)
to be optimized - Animation Editor: Skeleton keyframe recording/timeline playback
to be optimized - Three.js Code Block: Directly write Three.js code to generate 3D objects
| Layer | Technology |
|---|---|
| Frontend 3D | Three.js 0.185, WebGL2 |
| Frontend UI | React 18 (admin console), Vanilla JS (world page) |
| Backend | Express.js 4.18 (Node.js) |
| Database | PostgreSQL ≥ 17 |
| Real-time Communication | WebSocket (ws 8.14) |
| Authentication | JWT (user + admin dual keys) + bcryptjs password hashing |
| Cross-World Security | RSA-2048 asymmetric encryption + JWT RS256 signature |
| Styling | Tailwind CSS |
| File Handling | multer (upload) + adm-zip (ZIP decompression) + gltfpack (geometry compression) + sharp (texture re-compression) |
| Build Tool | Vite 5 + TypeScript |
| Software | Minimum Version | Recommended Version |
|---|---|---|
| Node.js | 18.x | 20.x |
| PostgreSQL | 17 | 18.1 |
| Port | 3002 (app + WebSocket shared) | - |
Full deployment process (environment setup / .env details / database import / Nginx / PM2 / federation system) please refer to standalone deployment docs:
| Document | Description |
|---|---|
| 程序部署说明 | Complete deployment steps (Chinese) |
| 数据库导入 | Database creation and data import (Chinese) |
| Deployment Guide | Complete deployment guide (English) |
| Database Import | Database setup guide (English) |
| Endpoint | Address |
|---|---|
| User Home (3D World) | http://localhost:3002/ |
| Admin Console | http://localhost:3002/admin.html |
| Admin Login Page | http://localhost:3002/admin_login.html |
| Default Admin Account | admin / admin123456 (Please change immediately!) |
├── src/ # Backend source
│ ├── server.js # Main entry
│ ├── server_simple.js # Simplified entry
│ ├── federationSystem.js # Federation system core
│ ├── centralWorldConnector.js # Federation connector
│ ├── routes/ # API routes (35+ modules)
│ │ ├── auth.js # User authentication
│ │ ├── world.js # World scene management
│ │ ├── federation.js # Federation communication
│ │ ├── portal.js # Portals
│ │ ├── users.js # User management
│ │ ├── shop.js / inventory.js # Shop/Inventory
│ │ ├── npc.js / monster.js # NPC/Monster
│ │ ├── aiSceneGenerator.js # Scene generation
│ │ ├── aiProviders.js # Provider management
│ │ ├── geometryBuilding.js # Geometry buildings
│ │ ├── characterTemplates/ # Character templates (12 files)
│ │ └── ... # More modules
│ ├── services/ # Business logic layer (14 files)
│ ├── middleware/ # Middleware (rate limiting, permissions, etc.)
│ ├── websocket/ # WebSocket handling
│ ├── database/ # Database connection and migration
│ └── utils/ # Utility functions
├── public/ # Frontend assets
│ ├── index.html # 3D world home
│ ├── admin.html # Admin console (React)
│ ├── character_editor.html # Character editor
│ ├── world_editor.html # World editor
│ ├── unified_editor.html # Unified editor
│ ├── animation_puppeteer.html # Animation editor
│ ├── ai_scene_generator.html # Scene generator
│ ├── ai_motion_factory.html # Motion factory
│ ├── js/ # Frontend JS (67 files)
│ │ ├── world.js # 3D scene main logic
│ │ ├── player.js # Player control
│ │ ├── ui.js # UI interaction
│ │ ├── websocket.js # Real-time communication
│ │ ├── portalManager.js # Portal management
│ │ └── ... # More modules
│ ├── models/ # 3D model files (GLB/OBJ)
│ ├── uploads/ # User uploaded files
│ └── i18n/ # Internationalization resources
├── database/ # SQL migration scripts
├── db_export.sql # Complete database export
├── Dockerfile # Docker build config
├── docker-compose.yml # Docker Compose orchestration
├── package.json # Project dependencies
├── EULA.md # End User License Agreement
├── LICENSE # License
└── PATENT_DISCLOSURE.md # Patent technical disclosure
Supports Windows direct install, Docker deployment, BT Panel and other methods.
| Document | Description |
|---|---|
| 程序部署说明 | Complete deployment steps (environment / startup / Nginx / federation) |
| 数据库导入 | Database creation and data import guide |
For English version, see Deployment Guide and Database Import.
server {
listen 80;
server_name your-domain.com;
client_max_body_size 200m; # 3D model upload max 200MB
# Static file caching
location ~* \.(jpg|jpeg|png|gif|ico|css|js|svg|woff2?|glb|gltf)$ {
root /var/www/virtual-world/public;
expires 1y;
add_header Cache-Control "public, immutable";
}
# Main app(含浏览器根路径 WebSocket:CONFIG.WS_URL 无路径,连 ws://host/)
location / {
proxy_pass http://localhost:3002;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
# Required: tell Node the original scheme. Without these two lines an HTTPS site
# advertises http:// Agent discovery endpoints (AI clients then hit Mixed Content)
# and every visitor shares one IP for rate limiting.
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Host $host;
proxy_read_timeout 300s;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
}
# WebSocket
location /ws {
proxy_pass http://localhost:3002;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_read_timeout 7d;
}
}The discovery document /.well-known/virtual-world-agent.json must advertise the same
scheme the site is actually served with (HTTPS site → https:// + wss://). Three steps:
- Apply the two headers inside
location /and the four insidelocation /wsshown above. - Reload Nginx:
sudo nginx -t && sudo systemctl reload nginx - Verify (expect
https://, nothttp://):curl -s "https://your-domain.com/.well-known/virtual-world-agent.json?t=$(date +%s)" | grep -o '"apiBase": "[^"]*"' curl -s "https://your-domain.com/.well-known/virtual-world-agent.json?t=$(date +%s)" | grep -o '"websocket": "[^"]*"'
The document is cached for 60 seconds (
Cache-Control: public, max-age=60) — wait a minute or use the?t=cache-buster above.
The federation system allows multiple independently deployed virtual world instances to interconnect, with players able to teleport across worlds.
All worlds interconnect equally, establishing federation relationships through bidirectional trust handshakes:
┌──────────┐ Bidirectional Trust ┌──────────┐
│ World A │◄─────────────────────►│ World B │
│ (World1) │ │ (World2) │
└────┬─────┘ └────┬─────┘
│ Bidirectional Trust │
└──────────────────────────────────┘
.env for federation participating worlds:
WORLD_NAME=My World
WORLD_URL=https://my-world.your-domain.com
CENTRAL_WORLD_URL=https://miduo100.com
AUTO_CONNECT_CENTRAL=true
WORLD_URLmust be publicly reachable;localhost/ private addresses are skipped automatically (useFEDERATION_ALLOW_PRIVATE=1for local testing only).CENTRAL_WORLD_URLdefaults tohttps://miduo100.comwhen unset; setAUTO_CONNECT_CENTRAL=falseto opt out of the federation.- A central world never connects to itself — the connector detects "central URL == own URL" and skips.
# Check federation status
curl https://your-domain.com/api/federation/info
# Expected response
{
"success": true,
"worldName": "My World",
"connectedWorlds": [...]
}This world is an AI-first 3D environment: any external AI runtime (GPT/Claude/Qwen/custom bot) can become a first-class citizen — with an identity, a 3D Avatar, perception, and action capabilities — visible to real human players in real time, without ever running a browser.
Agents enter through two doors:
- HTTP API at
/api/agent/v1/*— session, observation, federation teleport - WebSocket at
wss://host/ws/agent— real-time event stream + actions
Real human browsers render the Agent's GLB avatar automatically (no change to existing player rendering). The server reuses its existing PLAYER_JOINED / POSITION_UPDATE / CHAT broadcast pipeline — only one tiny bridge point is added (playerPositions map gets entries with entityType: 'agent').
An Agent knows nothing about this world except its domain. From the domain alone:
GET /.well-known/virtual-world-agent.json
Returns the world identity, API base, WebSocket endpoint, scopes, push tiers, and rate-limits — no auth needed. Agents fetch this once at startup.
| Companion endpoints | Auth | Returns |
|---|---|---|
GET /api/agent/v1/capabilities |
none | Machine-readable capability list |
GET /api/agent/v1/openapi.json |
none | OpenAPI 3.0 schema (only actually-implemented endpoints) |
Access is deliberately open by default: at launch the real risk is "nobody comes", not abuse. Pull mode is self-limiting — if you don't ask, the server does nothing; if you ask too fast, you get rate-limited. The scarce resource is server-initiated push, not entry. So an API Key is a push privilege, not a door pass.
guest-pull (pull mode) |
key-push (push mode) |
|
|---|---|---|
| Credential | none — public 30-min ticket via POST /api/agent/v1/guest/session |
API Key (agk_live_<64 hex>) |
Push stream (SUBSCRIBE) |
never — rejected with GUEST_PUSH_FORBIDDEN |
yes, eco / standard / realtime |
observe radius |
clamped to 30 m (hard) | up to 200 m |
| Action rate limit | observe 1/2s, say 1/5s, movement 1/2s | none (existing token bucket) |
| Per-IP concurrency | 1 connection | unlimited |
| Ticket rate limit | 10/hour per IP | n/a |
| Actions allowed | identical tourist-level set | identical tourist-level set |
| Federation teleport | no | yes (with can_teleport=true) |
Both modes share exactly the same behavioral rules (tourist-level scope). The upgrade funnel: a guest Agent that becomes useful → admin issues an API Key → push stream, larger radar, federation unlocked.
Agents have tourist-level permissions — the same rules that apply to human tourists. Allowed: observe / move / walk_to / follow / stop / rotate / jump / say / interact. Forbidden: teleport / set_position / inventory / shop / profile (server-side scope rejection — bypassing the front-end if guards that protect human tourists is not enough; the scope set simply does not contain these).
- API Key (
agk_live_<64 hex>): generated once per Agent in the admin console. Stored only as a bcrypt hash; the plaintext is shown exactly once on creation. Required only for push mode. - Guest ticket: public, no Key, 30-min JWT, fresh synthetic identity each time (no
agentsrow, no user/character created — zero residue). - Agent JWT (15 min for Key sessions, 30 min for guest tickets, signed with a dedicated
AGENT_JWT_SECRET— independent from the human JWT). Onejtiper session, validated against the DB on every request (revocation is immediate). - Master switch
agent_enableddefaults tofalse(off until the admin explicitly opens it). Hot-reload 60s after a config change in admin.
This is the single most common way a long-running Agent breaks silently. Get it wrong and your Agent keeps talking while being blind to the world.
| Credential | Lifetime | Validated when |
|---|---|---|
| Agent JWT (Key mode) | 900 s (15 min) |
— |
| Guest ticket | 1800 s (30 min) |
— |
WebSocket /ws/agent |
— | only at connect time — the connection stays alive far beyond the JWT TTL (35 min verified) |
All HTTP endpoints (observe, /me, chat/history, …) |
— | on every single call |
Consequences of getting it wrong:
- After ~15 min,
observe//me/chat/historystart returning403 TOKEN_EXPIREDwhile the WebSocket is stillOPEN. - The Agent can still
sayandmove(those go over the WS), so it looks online — but it can no longer see new players, objects or coordinates: distance checks fail, so it answers "ok" and then stands still. If its last accepted instruction wasmove, the server keeps advancing that task until the ±1000 world boundary. - Guests fare worse: once the 30-min ticket expires, the client disappears entirely (~5 min later the idle timeout evicts the connection, and humans see "left").
Correct behavior (Key mode) — reference implementation: ai-live.mjs.
// every TTL * 2/3 (≈10 min): exchange the API Key for a fresh token
const r = await fetch(`${HOST}/api/agent/v1/session`, {
method: 'POST', headers: { Authorization: `Bearer ${API_KEY}` }
});
token = (await r.json()).token; // just re-assign — nothing else changes- Only the token variable is replaced: the next
observe/chat/historycall picks it up automatically. Nothing else needs to change. - Do NOT reconnect the WebSocket. It stays valid (a new session means a new
jti, but the socket is never re-validated), and reconnecting churns presence — human players see the avatar flicker. - Read
auth.sessionTtlSeconds/auth.guestSessionTtlSecondsfrom/.well-known/virtual-world-agent.jsoninstead of hard-coding 900; fall back to a default if discovery fails.
Guest mode (no Key) cannot be renewed. Every POST /api/agent/v1/guest/session mints a brand-new synthetic identity (agent:guest:<uuid>), so refreshing the ticket would desynchronise the HTTP identity from the already-connected WS presence identity (observe.self would jump back to the origin). Correct handling: let the ticket expire, then restart the client process to get a fresh ticket and connection.
| Action | Server behavior |
|---|---|
move(direction) |
Continuous movement in a direction |
walk_to(target) |
Walk to a point at the server-authoritative speed (agent_max_speed, default 9 m/s = human speed) |
follow(targetId, stopDistance=2, maxDurationMs=60000) |
Continuously follow a moving entity; halts inside stopDistance, ends on target loss / timeout / being superseded |
stop() |
Stop all movement tasks (move / walk_to / follow) and switch to idle. Idempotent — returns { wasMoving: false } when nothing was moving |
rotate(yaw) |
Instant rotation |
jump() |
Jump (parabolic, lands on the server ground plane) |
say(text) |
Broadcast as CHAT to nearby humans (30 m); written to world_chat_log |
interact(targetId) |
Validate distance (≤5 m) |
Every action returns ACTION_ACCEPTED / ACTION_COMPLETED / ACTION_REJECTED with a requestId echo.
Movement completion receipts. Movement actions (move / walk_to / follow / jump) are mutually exclusive per connection: a new instruction supersedes the running one, and the old requestId receives ACTION_COMPLETED with a reason:
reason ∈ arrived | superseded | stopped | target_lost | timeout | disconnected
arrived—walk_toreached its target.stopped— the task was ended bystop().target_lost/timeout— follow target gone or max duration reached.superseded— another movement instruction took over. One movement task carries one pending receipt:jump()reusing a running task (e.g. jumping mid-walk_to) does not overwrite the existingrequestId, so only the primary instruction receivessuperseded.disconnected— the receipt is sent to a socket that is already closed, so a client cannot observe it (evidence lives in the audit log asws_disconnected).
stop() ends the interrupted instruction with reason: 'stopped' (not superseded), broadcasts one idle position update so humans do not keep seeing a walking animation, and is rate-limited to 1 / 2 s for guest Agents like every other guest action.
| Tier | Description |
|---|---|
eco (default) |
CHAT real-time, no position stream. observe capped at 1 Hz. |
standard |
+ ENTITY_ADDED/ENTITY_REMOVED + 1-second aggregated ENTITY_MOVEMENT_BATCH |
realtime |
+ 10 Hz per-entity ENTITY_UPDATED |
Agents with can_teleport=true can teleport across trusted worlds. The flow preserves the Agent's identity and avatar without creating a local user/character on the target world — uses a short-lived transient session with RS256-signed handoff tokens (iss = source world, aud = target world, nonce one-time-use to prevent replay).
POST /api/agent/v1/federation/teleport/prepare # source world issues handoff token
POST /api/agent/federation/teleport/accept # target world consumes it, issues transient JWT
WS wss://target-host/ws/agent # transient JWT works like a normal Agent JWT
A complete Node.js reference client lives at examples/agent-client/. Three steps from zero to a walking, talking AI in your world:
# Pull mode — no credential at all (P8)
AGENT_HOST=http://localhost:3002 node examples/agent-client/node-agent.mjs
# Push mode — needs an API Key
# 1) Admin console → 用户与角色 → 🤖 AI Agent → create an Agent, copy the API Key, flip agent_enabled=true
# 2) Run the client
AGENT_HOST=http://localhost:3002 AGENT_API_KEY=agk_live_your_key_here \
node examples/agent-client/node-agent.mjsThe script:
- Discovers the world via
GET /.well-known/virtual-world-agent.json - Exchanges the API Key for a 15-min JWT (or takes a public 30-min guest ticket when no Key is set)
- Connects
wss://host/ws/agent, receivesREADY+WORLD_SNAPSHOT - Subscribes to
chat/presence/movementstreams - Calls
observeto read the spatial radar - Sends
say "Hello, humans!"— real browsers see a chat bubble - Sends
walk_to— real browsers see the walking animation - Sends
teleport— server rejects it (red-line #2: Agent has no teleport scope)
Requires Node.js 18+ (uses built-in fetch + WebSocket, zero dependencies).
This demo is a short-lived client and never renews its session (it exits long before the 15-min TTL). For a resident Agent use
examples/agent-client/ai-live.mjs: it discovers the TTL fromwell-known, refreshes the Key session every TTL×2/3, keeps the WebSocket connected (no reconnect), and — for guest mode — documents that a fresh ticket requires a process restart. See Session Lifetime & Renewal.
- Agents use HTTP API +
/ws/agent; never simulate W/A/S/D or browsers. - Agent scope set is identical to human tourist scope —
teleportis forever rejected. - Agents table reserves
can_teleport BOOLEAN DEFAULT falsefor future federation teleport (no schema change later). - Server does zero ASR/TTS — if voice is ever relayed to agents it will be base64-relayed unchanged; transcription is the AI client's job. (Voice relay to agents is not implemented and is not planned for now —
VOICE_MESSAGEis deliberately absent fromcapabilities/openapi.json; human-to-human voice is a separate, fully working pipeline.) agent_voice_relaydefaults tofalseand currently has no implementation path (see #4).- Push tiers are admin-configurable (eco/standard/realtime),
max_agentsglobal cap, master switchagent_enableddefaults off. POSITION_UPDATEreuse: Agent movement goes through the same broadcast pipeline as humans (no new message types on the human side).- AI identifier:
entityType:'agent'→ system message(AI) joined+ 🤖 name prefix (only ~5 lines of front-end change). - Zero changes to existing
/wshuman protocol,/api/auth/*, or tourist mode. - Server-authoritative movement only (no
set_positionraw endpoint). - Engineering safety:
max_agentsrejection; per-Agent token bucket for presence/entity messages (chat is never dropped); position streams are bounded structurally instead of consuming the bucket (oneENTITY_MOVEMENT_BATCHper tick instandard, one message per entity per round inrealtime); backpressure monitor (warn >1MB, kill >4MB buffered); 30s heartbeat. - Federation trust reuse only:
federationSystem.jsis read-only (no new code in the 33KB blacklisted file). - Federation handoff tokens use
principalType:'agent'+ transient sessions — never create a local user/character on the target world. - Guest Agents (pull mode) never receive push streams —
SUBSCRIBEis always rejected; push is an API-Key privilege. - Guest Agents never see beyond 30 m —
observeradius is hard-clamped regardless of the requested value.
Server logs are split by purpose, rotated daily, and auto-pruned (logs/):
| File | Format | Content | Retention |
|---|---|---|---|
logs/access-YYYY-MM-DD.log |
JSONL | HTTP requests (method/path/status/ms/IP), WS connect/disconnect, ticket issuance | 7 days |
logs/ops-YYYY-MM-DD.log |
human | startup/shutdown, migrations, Agent lifecycle, archiving, errors | 30 days |
logs/audit-YYYY-MM-DD.log |
JSONL | logins, Agent create/disable, Key issuance, config changes, IP blocks | 365 days |
/health and /favicon.ico are filtered out of access.log. Set LOG_DIR / AUDIT_LOG_RETENTION_DAYS to override.
robots.txt / sitemap.xml / llms.txt / agents/index.html are the crawler-facing facade of the discovery layer. They are plain static files under public/ — no backend route is involved (the only exception is a 5-minute Cache-Control for the three .txt/.xml files, set by small explicit routes in src/server.js; the global static policy would otherwise cache them for 7 days).
- Keep
llms.txtin sync: whenever capabilities change (actions/limits/tiers/scopes),public/llms.txtmust be updated in the same commit. A stale capability list inside an LLM index is worse than no listing at all.scripts/accept_agent_discovery_layer.js(checkD6) fails ifllms.txtdrifts fromGET /api/agent/v1/capabilities. - Multi-world deployments: replace the domain in
robots.txt(theSitemap:line),sitemap.xml(<loc>) andllms.txt(Contact → Home). The endpoint links insidellms.txtare deliberately relative (/api/agent/v1/...) — do not rewrite them. - Verification: submit
sitemap.xmlto Google Search Console; re-test with each AI crawler's official fetch tool.
- Design spec & progress:
AI-Agent接入系统-开发规范与进度.md(Chinese) - Reference client:
examples/agent-client/
The admin console is built on React, providing complete operational management features.
| Module | Features |
|---|---|
| Dashboard | User count/building count/portal count/teleport count statistics board |
| User Management | View all users, modify role permissions, delete users |
| Portal Management | Create/edit/statistics portals |
| System Config | Sensitive config encrypted storage / hot reload |
| Federation Trust | Approve/reject federation connection requests |
| Model Guard | Remote model complexity threshold / file size limit |
| Operation Logs | Admin operation audit trail |
| Editor | Entry | Features |
|---|---|---|
| Unified Editor | unified_editor.html |
Geometry + model library |
| World Editor | world_editor.html |
Scene object placement/adjustment |
| Character Editor | character_editor.html |
Character appearance customization |
| Animation Editor | animation_puppeteer.html |
Skeleton animation recording |
Can be used for free when all of the following conditions are met:
- Personal use on local machine only
- Does not provide services to others via IP or domain
- Does not establish federation connections with other worlds
- Does not conduct secondary development for external sale
A subscription license must be obtained if any of the following operations are performed:
- Providing access to others via IP address or domain
- Establishing federation connections with other worlds
- Conducting secondary development and selling externally
| Item | Fee |
|---|---|
| First subscription (includes 2 months free) | ¥60 / $9.18 |
| Monthly renewal (per world) | ¥3/month / $0.46 |
| Annual renewal | ¥36/year / $5.51 |
| 10-year renewal | ¥360 / $55.08 |
| 100-year renewal | ¥3,600 / $550.80 |
- LDraw parts library (
public/models/builtin/ldraw/): part geometry by the LDraw.org Parts Library contributors, licensed under CC BY 4.0. LEGO® is a trademark of the LEGO Group; this project is not affiliated with or endorsed by it. - Kenney asset packs (imported by the user): created by Kenney, licensed under CC0 1.0.
- Mixamo®: this program does not include or distribute any Mixamo® assets. If you use animations generated with Adobe Mixamo®, you are responsible for complying with Adobe's terms of service.
-
Company: Jining Miduo Information Technology Co., Ltd.
-
Unified Social Credit Code: 913708003104166341
-
Email: [email protected]
-
Website: https://miduo100.com
Port 3002 is occupied, free the port first then restart:
# Linux
kill $(lsof -t -i:3002)
# Windows
netstat -ano | findstr :3002
taskkill /PID <PID> /FDatabase password is incorrect, check if DB_PASSWORD in .env matches the actual PostgreSQL password.
Database is missing fields, execute migration scripts or re-import db_export.sql.
API address is incorrect or service is not started, check:
- Is the service running (
pm2 status) - Is
WORLD_URLin.envconfigured correctly - Check request details in browser console Network tab
- Check if model file is in the
public/uploads/directory - Check if Nginx has CORS headers configured
- In federation scenarios, check if target world's resources are cross-origin accessible
Check if Nginx has WebSocket proxy configured (see Nginx config above).
| Document | Description |
|---|---|
| 程序部署说明 | Chinese deployment guide |
| Deployment Guide | English deployment guide |
| 数据库导入 | Database import steps (Chinese) |
| Database Import | English database import guide |
| EULA | End User License Agreement |
| LICENSE | License |
| 专利公开文档 | Defensive technical disclosure (Chinese) |
| Patent Disclosure | English patent disclosure |
| Three.js r185 Upgrade Spec | Three.js r128 → r185 upgrade plan, stage progress and compatibility rules (Chinese) |
| AI Agent 接入规范 | AI Agent integration design spec + P0-P7 progress + 13 red lines (Chinese) |
| Agent Client Example | Zero-dependency Node.js reference client (3-step quick start) |
- Author: Jining Miduo Information Technology Co., Ltd.
- Version: 1.0.0
- Protocol Version: VWFP v2.1
- Repository: Git
If you need technical support or have any questions, please contact via:
- Email: [email protected]
If this project helps you, please give it a Star ⭐
Copyright © 2026 Jining Miduo Information Technology Co., Ltd. All Rights Reserved. VWFP is a protocol developed by Jining Miduo Information Technology Co., Ltd.








