Vibe Starter 3D

This project is a foundational library for 3D projects used in Verse8. It provides essential components to start 3D development.

Introduction

Vibe Starter 3D is a library designed to easily integrate 3D elements into React applications. Built on Three.js, React Three Fiber, and related technologies, it specifically offers functionality for easily rendering and animating 3D character models in VRM and GLTF/GLB formats.

Installation

npm install vibe-starter-3d

Key Features

Components

• CharacterRenderer: Unified component for rendering VRM and GLTF/GLB models
  • CharacterRendererRef: Reference interface providing bounding box information of the model
• View Controllers: Components providing various camera perspectives
  • FreeViewController: Free camera perspective
  • FirstPersonViewController: First-person perspective
  • QuarterViewController: Quarter view perspective
  • SideViewController: Side view perspective
  • FlightViewController: Flight perspective with configurable handle
• NetworkObject: Component for handling network-connected objects
  • NetworkObjectProps: Defines network object properties
  • NetworkObjectHandle: Handle for manipulating network objects

Utilities

• controllerUtils: Controller-related utilities
  • position, camInitDis, camMinDis, camMaxDis, targetHeight, capsuleRadius, etc.
• collisionUtils: Collision detection and handling utilities
  • isInCollisionGroup, createLocalPlayerCollisionGroups, collisionGroups, etc.
• typeUtils: Type conversion utilities between Three.js and React Three Fiber
  • toVector3, toVector3Array, etc.

Types

• Animation-related Types:

  • AnimationType: Defines animation types such as 'IDLE', 'WALK', 'RUN', 'JUMP', etc.
  • AnimationConfig: Provides animation settings (loop, duration, clampWhenFinished, etc.)
  • AnimationConfigMap: Maps action types to animation settings

• CharacterResource Type:

  • Interface defining character model information (name, url, animations)

• Controller-related Types:

  • ControllerProps: Defines controller component properties
  • ControllerHandle: Controller handle interface for rigid body reference, offset, etc.
  • FollowLightProps: Settings for following light (position, intensity, color, etc.)
  • ControllerMode: Controller modes such as 'CameraBasedMovement', 'FixedCamera', 'PointToMove', etc.

Constants

• Animation Constants:

  • ANIMATION_KEYWORDS: Keyword mapping for identifying animation types

• Collision Group Constants:

  • CollisionGroup: Defines collision detection groups (Default, Player, Enemy, NPC, Projectile, etc.)

Collision Groups (CollisionGroup)

Below is the complete list of collision groups used in the Rapier physics engine. Each value represents a group index between 0 and 15.

| Group | Value | Description | | -------------- | ----- | ----------------------------------------------- | | Default | 0 | General object (default) | | Player | 1 | Player character | | Enemy | 2 | Enemy character | | NPC | 3 | Neutral character | | Projectile | 4 | Projectile | | Environment | 5 | Walls, floors, roads, structures, etc. | | Item | 6 | Interactive or acquirable item | | Trigger | 7 | Event trigger | | UI | 8 | For UI raycast | | Sensor | 9 | Invisible sensor (vision, proximity, etc.) | | DeadBody | 10 | Deceased unit | | LocalPlayer | 11 | Self in multiplayer | | RemotePlayer | 12 | Other user characters in multiplayer | | Vehicle | 13 | Vehicle/mount | | Terrain | 14 | Terrain for special judgment | | Particle | 15 | Particle effect (for hit judgment or to ignore) |

Note: The rigid bodies of all controller components (FreeViewController, FirstPersonViewController, QuarterViewController, SideViewController, FlightViewController) are automatically set to the LocalPlayer collision group. This is handled internally through the createLocalPlayerCollisionGroups function.

Detailed Interface Descriptions

ControllerHandle

Interface exposed externally by the controller component.

| Property | Type | Description | | -------------- | ---------------------------------------- | ----------------------------------- | | rigidBodyRef | React.RefObject<CustomEcctrlRigidBody> | Reference to the physics rigid body | | offsetY | number | Y-axis offset value |

ControllerProps

Defines the basic properties of all controller components. FreeViewController, FirstPersonViewController, QuarterViewController, and SideViewController all inherit (extend) this interface.

| Property | Type | Description | Default Value | | --------------------- | ------------------ | ---------------------------------- | ------------- | | position | Vector3 | Initial position of the rigid body | [0, 5, 0] | | camInitDis | number | Initial camera distance | -4 | | camMinDis | number | Minimum camera zoom-in distance | -4 | | camMaxDis | number | Maximum camera zoom-out distance | -4 | | targetHeight | number | Character height (m) | 1.6 | | floatHeight | number | Height above ground (m) | 0.01 | | followLight | FollowLightProps | Settings for the following light | - | | followCameraForward | boolean | Whether to follow camera direction | false | | children | React.ReactNode | Child components to render inside | - |

QuarterViewControllerProps

Defines properties for the quarter view controller. (extends ControllerProps)

| Property | Type | Description | Default Value | | ----------------- | ----------------------------------- | ------------------------------- | --------------- | | followCharacter | boolean | Whether to follow the character | false | | inputMode | 'keyboard' | 'pointToMove' | Input mode | 'pointToMove' | | cameraMode | 'perspective' | 'orthographic' | Camera mode | 'perspective' |

Note: This interface inherits all properties from ControllerProps.

SideViewControllerProps

Defines properties for the side view controller. (extends ControllerProps)

| Property | Type | Description | Default Value | | ----------------- | ----------------------------------- | ----------------------- | ---------------------------------- | | cameraMode | 'perspective' | 'orthographic' | Camera mode | 'orthographic' | | collisionGroups | number | Collision group bitmask | (0x00000001 << 16) \| 0x00000004 |

Note: This interface inherits all properties from ControllerProps.

FlightViewControllerProps

Defines properties for the flight view controller. (Does not inherit ControllerProps)

| Property | Type | Description | Default Value | | ------------------------------- | ----------------------------------- | --------------------------------- | -------------- | | minSpeed | number | Minimum flight speed (m/s) | 0 | | maxSpeed | number | Maximum flight speed (m/s) | 120 | | speedIncreasePerSecond | number | Speed increase per second (m/s) | 20 | | speedDecreasePerSecond | number | Speed decrease per second (m/s) | 80 | | pitchRotationSpeed | number | Pitch rotation speed | 0.5 | | rollRotationSpeed | number | Roll rotation speed | Math.PI | | directionRotationAcceleration | number | Direction rotation acceleration | 0.3 | | maxRollAngle | number | Maximum roll angle | Math.PI / 2 | | maxPitchAngle | number | Maximum pitch angle | Math.PI / 2 | | hitBodySize | Vector3 | Body size for collision detection | [1, 0.6, 3] | | followLightOffset | Vector3 | Light offset position | [-20, 30, 0] | | cameraOffset | Vector3 | Camera offset position | [0, 3, 15] | | onIntersectionEnter | (event: CollisionPayload) => void | Callback when collision starts | - | | onIntersectionExit | (event: CollisionPayload) => void | Callback when collision ends | - |

FlightViewControllerHandle

Interface exposed externally by the flight view controller.

| Property | Type | Description | | ---------------- | ----------------------------------------- | ----------------------------------- | | position | THREE.Vector3 | Current position | | orientation | THREE.Quaternion | Current orientation (quaternion) | | speed | number | Current speed | | rigidBodyRef | React.RefObject<RapierRigidBody> | Reference to the physics rigid body | | followLightRef | React.RefObject<THREE.DirectionalLight> | Reference to directional light |

Usage Examples

Basic Character Rendering

import { CharacterRenderer } from 'vibe-starter-3d';
import { useRef } from 'react';

function MyCharacter() {
  const actionRef = useRef<string>();

  const characterResource = {
    url: '/models/my-character.vrm',
    animations: {
      idle: '/animations/idle.fbx',
    },
  };

  const animationConfig = {
    idle: { loop: true },
  };

  return <CharacterRenderer characterResource={characterResource} animationConfigMap={animationConfig} currentActionRef={actionRef} />;
}

Free View Camera Application

import { FreeViewController } from 'vibe-starter-3d';

function My3DScene() {
  return <FreeViewController>{/* Typically place Player objects here */}</FreeViewController>;
}

First-Person View Camera Application

import { FirstPersonViewController } from 'vibe-starter-3d';

function My3DScene() {
  return <FirstPersonViewController>{/* Important: Never place character models here! */}</FirstPersonViewController>;
}

Important: Since FirstPersonViewController provides a first-person perspective, you should not place character models inside the controller. This is because the camera would be positioned inside the character model, causing obscured vision or camera clipping issues. In first-person perspective, the controller itself already acts as the player, so a separate character model is not needed. If necessary, place only weapon or hand models separately, and use full character models only in third-person perspectives.

Technology Stack

• React
• Three.js
• React Three Fiber
• React Three Drei
• Rapier Physics Engine
• VRM (Virtual Reality Model)