abstrucked/hytopia-camera

HYTOPIA Camera

This skill helps you control camera perspectives in HYTOPIA SDK games.

Documentation: https://dev.hytopia.com/sdk-guides/camera

When to Use This Skill

Use this skill when the user:

• Wants to switch between first-person and third-person views
• Needs to attach camera to entities
• Asks about camera tracking or lock-on targeting
• Wants to implement zoom or FOV effects
• Needs over-the-shoulder camera positioning
• Asks about hiding player model parts in first-person

Core Camera Concepts

Accessing Player Camera

import { Player, PlayerCameraMode } from 'hytopia';

// Each player has a camera instance
const camera = player.camera;

Camera Modes

import { PlayerCameraMode } from 'hytopia';

// Switch to first-person
player.camera.setMode(PlayerCameraMode.FIRST_PERSON);

// Switch to third-person (default)
player.camera.setMode(PlayerCameraMode.THIRD_PERSON);

Camera Attachment & Tracking

// Attach camera origin to an entity
player.camera.setAttachedToEntity(targetEntity);

// Make camera look at/track an entity
player.camera.setTrackedEntity(enemyEntity);

// Can use both together for lock-on targeting
player.camera.setAttachedToEntity(player.entity);
player.camera.setTrackedEntity(bossEntity);

Camera Positioning

Offset Adjustments

// Offset camera position relative to attachment point
player.camera.setOffset({ x: 0, y: 2, z: 0 });  // 2 units above

// Move camera forward/backward (first-person only)
player.camera.setForwardOffset(0.5);

// Shift camera left/right for over-the-shoulder view
player.camera.setFilmOffset(0.3);  // Slight right offset

Zoom and FOV

// Set field of view (default: 75)
player.camera.setFov(90);  // Wider view

// Set zoom level (default: 2)
player.camera.setZoom(3);  // More zoomed in

// Dynamic zoom for aiming
function toggleAim(player: Player, isAiming: boolean) {
  if (isAiming) {
    player.camera.setFov(45);  // Narrow FOV for aiming
    player.camera.setZoom(4);
  } else {
    player.camera.setFov(75);  // Normal FOV
    player.camera.setZoom(2);
  }
}

Model Visibility

Hiding Model Parts

// Hide model nodes in first-person (only affects this player's view)
player.camera.setHiddenModelNodes(['head', 'hair']);

// Useful for first-person to prevent seeing inside player model
world.onPlayerJoin = (player) => {
  player.camera.setMode(PlayerCameraMode.FIRST_PERSON);
  player.camera.setHiddenModelNodes(['head']);
};

Common Patterns

First-Person Setup

world.onPlayerJoin = (player) => {
  // Switch to first-person
  player.camera.setMode(PlayerCameraMode.FIRST_PERSON);

  // Raise camera to eye level
  player.camera.setOffset({ x: 0, y: 1.6, z: 0 });

  // Hide head to prevent clipping
  player.camera.setHiddenModelNodes(['head']);

  // Slight forward offset
  player.camera.setForwardOffset(0.2);
};

Third-Person Over-Shoulder

function setupOverShoulderCamera(player: Player) {
  player.camera.setMode(PlayerCameraMode.THIRD_PERSON);
  player.camera.setOffset({ x: 0.5, y: 1.5, z: 0 });  // Right and up
  player.camera.setFilmOffset(0.2);  // Slight horizontal shift
  player.camera.setZoom(2.5);
}

Lock-On Targeting

function lockOnTarget(player: Player, target: Entity | null) {
  if (target) {
    player.camera.setTrackedEntity(target);
    player.camera.setZoom(3);  // Zoom in on target
  } else {
    player.camera.setTrackedEntity(null);
    player.camera.setZoom(2);  // Reset zoom
  }
}

Cinematic Camera

function playCinematic(player: Player, cameraEntity: Entity, lookAtEntity: Entity) {
  // Detach from player
  player.camera.setAttachedToEntity(cameraEntity);
  player.camera.setTrackedEntity(lookAtEntity);

  // Cinematic FOV
  player.camera.setFov(60);
}

function endCinematic(player: Player) {
  // Return to player
  player.camera.setAttachedToEntity(player.entity);
  player.camera.setTrackedEntity(null);
  player.camera.setFov(75);
}

Scope/Sniper Zoom

function toggleScope(player: Player, isScoped: boolean) {
  if (isScoped) {
    player.camera.setMode(PlayerCameraMode.FIRST_PERSON);
    player.camera.setFov(20);  // Very narrow for scope
    player.camera.setZoom(6);
  } else {
    player.camera.setFov(75);
    player.camera.setZoom(2);
  }
}

Best Practices

1. Smooth transitions - Camera changes interpolate automatically
2. Hide head in first-person - Prevents seeing inside the model
3. Use appropriate FOV - 60-90 for gameplay, lower for aiming
4. Consider motion sickness - Avoid rapid camera movements
5. Test both modes - Ensure game works in first and third person

Common Mistakes

• Forgetting to hide head nodes in first-person view
• Setting FOV too low (causes tunnel vision) or too high (causes distortion)
• Not resetting camera settings after cinematic sequences
• Forgetting that setForwardOffset only works in first-person mode