Rbxts Character Viewport

https://github.com/synergence/character-viewport
Admin
Rbxts Character Viewport is a live-updating character viewport component for Roblox that displays...
Tokens:3,282
Snippets:20
Trust Score:3.8
License:Unlicense
Update:6 months ago
Show doc for...
Tokens:
Raw
### Character Viewport with Custom Camera Offset

Source: https://context7.com/synergence/character-viewport/llms.txt

Allows customization of the camera's position relative to the character using the `Offset` prop. This example positions the camera further back and higher.

```tsx
import Roact from '@rbxts/roact';
import { CharacterViewport } from '@rbxts/character-viewport';

const Players = game.GetService('Players');

// With custom camera offset - position camera further back and higher
function CustomOffsetPreview() {
    const customOffset = new CFrame(new Vector3(0, 3, -15));

    return (
        <frame Size={new UDim2(0, 300, 0, 400)} BackgroundColor3={Color3.fromRGB(30, 30, 30)}>
            <CharacterViewport
                Player={Players.LocalPlayer}
                Offset={customOffset}
            />
        </frame>
    );
}
```

--------------------------------

### Basic Character Viewport Usage

Source: https://context7.com/synergence/character-viewport/llms.txt

Renders the local player's character within a ViewportFrame. Ensure the component is mounted to the PlayerGui.

```tsx
import Roact from '@rbxts/roact';
import { CharacterViewport } from '@rbxts/character-viewport';

const Players = game.GetService('Players');

// Basic usage - render local player's character
function PlayerPreview() {
    return (
        <frame Size={new UDim2(0, 200, 0, 300)} Position={new UDim2(0.5, -100, 0.5, -150)}>
            <CharacterViewport Player={Players.LocalPlayer} />
        </frame>
    );
}

// Mount the component
const playerGui = Players.LocalPlayer.WaitForChild('PlayerGui') as PlayerGui;
const handle = Roact.mount(<PlayerPreview />, playerGui, 'CharacterPreview');

// Unmount when not in use for performance
Roact.unmount(handle);
```

--------------------------------

### CharacterViewport Component

Source: https://context7.com/synergence/character-viewport/llms.txt

The main Roact component for rendering a player's character in a ViewportFrame with live animation updates. It handles character loading, appearance synchronization, and cleanup automatically.

```APIDOC
## CharacterViewport Component

### Description
The main Roact component that renders a player's character in a ViewportFrame with live animation updates. It accepts a required `Player` prop and an optional `Offset` prop (CFrame) to customize camera positioning. The component automatically handles character loading, appearance synchronization, and cleanup when unmounted.

### Props
- **Player** (Player) - Required - The player whose character will be rendered.
- **Offset** (CFrame) - Optional - A CFrame to customize the camera's position relative to the character.

### Request Example
```tsx
import Roact from '@rbxts/roact';
import { CharacterViewport } from '@rbxts/character-viewport';

const Players = game.GetService('Players');

// Basic usage - render local player's character
function PlayerPreview() {
    return (
        <frame Size={new UDim2(0, 200, 0, 300)} Position={new UDim2(0.5, -100, 0.5, -150)}>
            <CharacterViewport Player={Players.LocalPlayer} />
        </frame>
    );
}

// With custom camera offset - position camera further back and higher
function CustomOffsetPreview() {
    const customOffset = new CFrame(new Vector3(0, 3, -15));

    return (
        <frame Size={new UDim2(0, 300, 0, 400)} BackgroundColor3={Color3.fromRGB(30, 30, 30)}>
            <CharacterViewport
                Player={Players.LocalPlayer}
                Offset={customOffset}
            />
        </frame>
    );
}

// Render another player's character
function OtherPlayerPreview(props: { targetPlayer: Player }) {
    return (
        <frame Size={new UDim2(1, 0, 1, 0)}>
            <CharacterViewport Player={props.targetPlayer} />
        </frame>
    );
}

// Mount the component
const playerGui = Players.LocalPlayer.WaitForChild('PlayerGui') as PlayerGui;
const handle = Roact.mount(<PlayerPreview />, playerGui, 'CharacterPreview');

// Unmount when not in use for performance
// Roact.unmount(handle);
```

### Response Example
(This is a Roact component, not an API endpoint with a direct response. The output is a rendered ViewportFrame.)
```

--------------------------------

### Render Another Player's Character

Source: https://context7.com/synergence/character-viewport/llms.txt

Demonstrates how to render a character other than the local player's by passing a different `Player` object to the `CharacterViewport` component.

```tsx
import Roact from '@rbxts/roact';
import { CharacterViewport } from '@rbxts/character-viewport';

const Players = game.GetService('Players');

// Render another player's character
function OtherPlayerPreview(props: { targetPlayer: Player }) {
    return (
        <frame Size={new UDim2(1, 0, 1, 0)}>
            <CharacterViewport Player={props.targetPlayer} />
        </frame>
    );
}
```

--------------------------------

### Character Viewport Component Usage

Source: https://context7.com/synergence/character-viewport/llms.txt

Renders a character preview using the CharacterViewport component. Requires a Player object and an optional CFrame for camera offset. The component handles cloning, animation, and camera management.

```tsx
import Roact from '@rbxts/roact';
import { CharacterViewport } from '@rbxts/character-viewport';

const Players = game.GetService('Players');

// Interface definition (for reference)
interface CharacterViewportProps {
    Player: Player;           // Required: The player whose character to display
    Offset?: CFrame;          // Optional: Camera offset from HumanoidRootPart
}

// Different camera angles for various use cases
const CAMERA_OFFSETS = {
    // Default front view
    front: new CFrame(new Vector3(0, 1.5, -10)),

    // Close-up face view
    closeUp: new CFrame(new Vector3(0, 1.5, -3)),

    // Full body from distance
    fullBody: new CFrame(new Vector3(0, 2, -15)),

    // Side profile
    sideProfile: new CFrame(new Vector3(-8, 1.5, -5)),

    // Top-down view
    topDown: new CFrame(new Vector3(0, 15, -2)),
};

// Character preview with selectable camera angles
function CharacterPreviewWithAngles(props: { player: Player; viewType: keyof typeof CAMERA_OFFSETS }) {
    return (
        <CharacterViewport
            Player={props.player}
            Offset={CAMERA_OFFSETS[props.viewType]}
        />
    );
}

// Usage in a character customization screen
function CharacterCustomizationUI() {
    return (
        <frame Size={new UDim2(1, 0, 1, 0)}>
            {/* Main character preview */}
            <frame Size={new UDim2(0.5, 0, 1, 0)}>
                <CharacterViewport
                    Player={Players.LocalPlayer}
                    Offset={CAMERA_OFFSETS.fullBody}
                />
            </frame>

            {/* Close-up face preview */}
            <frame Size={new UDim2(0.2, 0, 0.3, 0)} Position={new UDim2(0.75, 0, 0, 0)}>
                <CharacterViewport
                    Player={Players.LocalPlayer}
                    Offset={CAMERA_OFFSETS.closeUp}
                />
            </frame>
        </frame>
    );
}
```

--------------------------------

### Manually Update Player Viewport

Source: https://github.com/synergence/character-viewport/blob/master/README.md

Call this static function to trigger a local re-render of a player's character viewport. This is useful for updating the viewport outside of Roact's lifecycle.

```ts
import { CharacterViewport } from '@rbxts/character-viewport';

const Players = game.GetService('Players');

CharacterViewport.updatePlayer(Players.LocalPlayer);
```

--------------------------------

### CharacterViewport.updatePlayer Static Method

Source: https://context7.com/synergence/character-viewport/llms.txt

A static method that forces a re-render of all CharacterViewport instances displaying a specific player's character. Use this when you need to manually refresh the viewport after the character's appearance changes.

```APIDOC
## CharacterViewport.updatePlayer Static Method

### Description
A static method that forces a re-render of all CharacterViewport instances displaying a specific player's character. Use this when you need to manually refresh the viewport after the character's appearance changes (e.g., equipping new accessories, changing outfits, or after character customization).

### Method
`CharacterViewport.updatePlayer(player: Player)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```typescript
import { CharacterViewport } from '@rbxts/character-viewport';

const Players = game.GetService('Players');

// Force refresh after character appearance change
function onAccessoryEquipped(player: Player) {
    // Wait a moment for the accessory to be fully applied
    wait(0.1);

    // Update all viewports showing this player
    CharacterViewport.updatePlayer(player);
}

// Example: Listen for MarketplaceService purchases
const MarketplaceService = game.GetService('MarketplaceService');

MarketplaceService.PromptPurchaseFinished.Connect((player, assetId, isPurchased) => {
    if (isPurchased) {
        // Refresh the character viewport after purchase
        CharacterViewport.updatePlayer(player);
    }
});

// Example: Refresh after custom outfit change
function changePlayerOutfit(player: Player, outfitId: number) {
    const humanoidDescription = Players.GetHumanoidDescriptionFromOutfitId(outfitId);
    const humanoid = player.Character?.FindFirstChildOfClass('Humanoid');

    if (humanoid) {
        humanoid.ApplyDescription(humanoidDescription);

        // Update viewport to reflect new appearance
        CharacterViewport.updatePlayer(player);
    }
}
```

### Response
#### Success Response (200)
None (This method performs an action, it does not return data.)

#### Response Example
None
```

--------------------------------

### Render Character Viewport with Roact

Source: https://github.com/synergence/character-viewport/blob/master/README.md

Use this component within your Roact code to display a player's character in a viewport. Ensure to unmount the component when not in use for performance.

```tsx
import { CharacterViewport } from '@rbxts/character-viewport';

const Players = game.GetService('Players');

// inside your Roact code
<CharacterViewport Player={Players.LocalPlayer}>
```

--------------------------------

### Force Character Viewport Refresh

Source: https://context7.com/synergence/character-viewport/llms.txt

Uses the static `CharacterViewport.updatePlayer` method to manually refresh all viewports displaying a specific player's character. This is useful after appearance changes.

```typescript
import { CharacterViewport } from '@rbxts/character-viewport';

const Players = game.GetService('Players');

// Force refresh after character appearance change
function onAccessoryEquipped(player: Player) {
    // Wait a moment for the accessory to be fully applied
    wait(0.1);

    // Update all viewports showing this player
    CharacterViewport.updatePlayer(player);
}

// Example: Listen for MarketplaceService purchases
const MarketplaceService = game.GetService('MarketplaceService');

MarketplaceService.PromptPurchaseFinished.Connect((player, assetId, isPurchased) => {
    if (isPurchased) {
        // Refresh the character viewport after purchase
        CharacterViewport.updatePlayer(player);
    }
});

// Example: Refresh after custom outfit change
function changePlayerOutfit(player: Player, outfitId: number) {
    const humanoidDescription = Players.GetHumanoidDescriptionFromOutfitId(outfitId);
    const humanoid = player.Character?.FindFirstChildOfClass('Humanoid');

    if (humanoid) {
        humanoid.ApplyDescription(humanoidDescription);

        // Update viewport to reflect new appearance
        CharacterViewport.updatePlayer(player);
    }
}
```

--------------------------------

### Checking Cloneable Classes with CLONEABLE_CLASSES

Source: https://context7.com/synergence/character-viewport/llms.txt

Accesses the static CLONEABLE_CLASSES set to check which Roblox instance classes are cloned into the viewport. This set is used for efficient filtering during character loading.

```tsx
import { CharacterViewport } from '@rbxts/character-viewport';

// Check which classes are supported
const supportedClasses = CharacterViewport.CLONEABLE_CLASSES;

// Verify a class is supported
print(supportedClasses.has('MeshPart'));      // true
print(supportedClasses.has('Part'));          // true
print(supportedClasses.has('Accoutrement'));  // true
print(supportedClasses.has('Pants'));         // true
print(supportedClasses.has('Shirt'));         // true
print(supportedClasses.has('Humanoid'));      // true
print(supportedClasses.has('Script'));        // false (not cloned)
print(supportedClasses.has('Tool'));          // false (not cloned)

// The set ensures only visual/essential character parts are rendered
// This optimizes performance by excluding unnecessary instances like:
// - Scripts and LocalScripts
// - Tools and other functional objects
// - Sound instances
// - Non-visual descendants
```
Tokens:
Raw