XR Publisher

XR Publisher is a powerful JavaScript library for creating immersive 3D virtual worlds with support for VR, networking, and AI-powered NPCs. Built on top of React and Three.js, it provides a declarative way to build interactive 3D environments.

STILL IN DEVELOPMENT USE AT YOUR OWN RISK OF FREQENT CHANGES - DEVELOPMENT IS ON THE BRANCH "development" wait until there is a release before using in production

Features

• Virtual Reality Support: Built-in VR compatibility with device targeting
• Multiplayer Networking: Support for multi-user environments with voice chat capabilities
• AI-Powered NPCs: Integration with AI characters that can interact with users
• Physics Engine: Integrated physics system for realistic object interactions
• Component-Based Architecture: Modular design using custom HTML elements
• Asset Management: Support for various 3D models, textures, and audio
• Environment Controls: Camera collisions, teleportation, and player movement
• Customizable Avatars: VRM model support for player avatars

Installation

Quick Start

1. Import the library:

1import { XRPublisher } from 'xr-publisher';

2. Initialize with your configuration:

1const publisher = new XRPublisher({
2    threeObjectPlugin: 'path/to/plugin',
3    defaultAvatarAnimation: '',
4    defaultAvatar: 'path/to/default/avatar.vrm',
5    multiplayerAccess: 'loggedIn',
6    camCollisions: true,
7    enableAI: true,
8    enableNetworking: false,
9    enableVoiceChat: false
10});
11
12publisher.init();

Building a World

Worlds are constructed using custom HTML web componentsgit. Here's a basic example:

1<three-environment-block 
2    devicetarget="vr" 
3    threeobjecturl="path/to/world.glb"
4    scale="1" 
5    positiony="-1" 
6    rotationy="0" 
7    animations="" 
8    camcollisions="1">
9    
10    <!-- Networking configuration -->
11    <three-networking-block 
12        participantlimit="5" 
13        customavatars="1">
14    </three-networking-block>
15    
16    <!-- 3D Models -->
17    <three-model-block 
18        threeobjecturl="path/to/model.glb"
19        scalex="1" 
20        scaley="1" 
21        scalez="1" 
22        positionx="0" 
23        positiony="0" 
24        positionz="0"
25        animations="" 
26        collidable="1">
27    </three-model-block>
28    
29    <!-- Sky configuration -->
30    <three-sky-block 
31        distance="170000" 
32        rayleigh="1" 
33        sunpositionx="0" 
34        sunpositiony="1" 
35        sunpositionz="-10000">
36    </three-sky-block>
37</three-environment-block>

Available Components

Environment Block

The main container for your 3D world:

1<three-environment-block>
2    <!-- World contents go here -->
3</three-environment-block>

Attributes:

• devicetarget: Set to "vr" for VR support
• threeobjecturl: URL to the main world model (GLB format)
• scale: World scale factor
• positiony: Vertical position
• rotationy: Rotation around Y axis
• camcollisions: Enable/disable camera collisions

Networking Block

Enables multiplayer functionality:

1<three-networking-block>
2</three-networking-block>

Attributes:

• participantlimit: Maximum number of concurrent users
• customavatars: Enable custom avatar uploads

Model Block

Add 3D models to your world:

1<three-model-block>
2</three-model-block>

Attributes:

• threeobjecturl: URL to the model file
• scalex/y/z: Scale in each dimension
• positionx/y/z: Position in 3D space
• rotationx/y/z: Rotation around each axis
• animations: Animation names to play
• collidable: Enable physics collisions

NPC Block

Add interactive AI characters:

1<three-npc-block
2    threeobjecturl="path/to/avatar.vrm"
3    name="NPCName"
4    defaultmessage="Hello!"
5    personality="..."
6    objectawareness="1">
7</three-npc-block>

Additional Components

• <three-sky-block>: Configure skybox and lighting
• <three-audio-block>: Add spatial audio
• <three-video-block>: Add video elements
• <three-image-block>: Add image planes
• <three-text-block>: Add 3D text
• <three-portal-block>: Create teleport points

Physics and Collisions

The library includes a physics system based on Rapier. To make objects collidable:

1. Set the collidable attribute on model blocks
2. Enable camera collisions with camcollisions="1"
3. Physics will automatically initialize when the world loads

Avatar System

Players can customize their appearance using VRM models:

• Default avatar can be specified in configuration
• Custom avatar URLs can be provided if enabled
• Avatars support animations and physics interactions

Advanced Features

AI NPCs

NPCs can be configured with personality traits and conversation topics:

@todo HIGH RISK TO CHANGE SOON: update to offer the ability to point to the new Character API to create NPCs

1const npcConfig = {
2    name: "Character",
3    topics: ["topic1", "topic2"],
4    personality: {
5        adjectives: ["friendly", "helpful"],
6        style: {
7            chat: ["Be enthusiastic", "Use emojis"]
8        }
9    }
10};

Networking

For multiplayer environments:

1. Enable networking in configuration
2. Set participant limits
3. Configure voice chat settings
4. Handle player synchronization automatically (TODO: need to write up the p2pcf setup or offer the public one)

Browser Support

• Modern browsers with WebGL support
• WebXR-compatible browsers for VR features
• Mobile support with touch controls

License

GPL-3.0

Support

For questions and support:

• File an issue on GitHub