Skip to main content

useWorld()

A React hook that provides access to the underlying engine.

import React from "react";
import { useWorld } from "hyperfy";

export default function Box() {
  const world = useWorld();
  world.chat("Hello world!");

  return <app></app>;
}

.isServer​

Whether the app is currently running on the server

.isClient​

Whether the app is currently running on a client

.isDesktop​

Whether we are running on desktop

.isMobile​

Whether we are running on mobile / touch device

.isVR​

Whether we are running on a VR device

.getSlug()​

Returns the slug of the current world.

Example: when in https://hyperfy.io/meadow world.getSlug() will return meadow

.getShard()​

Returns the shard (instance) ID of the current world server

Example: when in https://hyperfy.io/meadow/~k0h1 world.getShard() will return ~k0h1

.getTime()​

Returns the current time of the server in milliseconds. This time is also synchronized across and available to all clients.

import React from "react";
import { useWorld } from "hyperfy";

export default function Box() {
  const world = useWorld();

  if (world.isServer) {
    console.log(`I'm running on the server!`);
  }
  if (world.isClient) {
    console.log(`I'm running on a client!`);
  }

  return (
    <app>
      <text
        color="white"
        value={`
        isServer: ${world.isServer}
        isClient: ${world.isClient}
        isDesktop: ${world.isDesktop}
        isMobile: ${world.isMobile}
        isVR: ${world.isVR}
        worldSlug: ${world.getSlug()}
        worldShard: ${world.getShard()}
        worldTime: ${world.getTime()}
      `}
      />
    </app>
  );
}

.getAvatar(avatarUid)​

Returns an Avatar reference. If no avatarUid is provided it returns the local avatar.

.getAvatars()​

Returns an array of Avatar references

.chat(text, localOnly)​

Posts an event into the chat. If localOnly is true only the current client will see it. Has no effect on the server.

import React, { useEffect } from "react";
import { useWorld } from "hyperfy";

export default function App() {
  const world = useWorld();

  function getAvatars() {
    const localAvatar = world.getAvatar();
    world.chat(`Your avatar name: ${localAvatar.name}`, true); //local chat only

    world.getAvatars().forEach((avatar) => {
      if (avatar.uid !== localAvatar.uid) {
        world.chat(`Remote avatar name: ${avatar.name}`);
      }
    });
  }

  return (
    <app>
      <box onPointerDown={getAvatars} />
    </app>
  );
}

.open(url, newTab=false)​

Opens a URL or Hyperfy world.

.http(options)​

Performs an HTTP request similar to fetch()

import React, { useEffect } from "react";
import { useWorld } from "hyperfy";

export default function App() {
  const world = useWorld();

  function switchWorld() {
    world.open("/world");
  }

  function openWorld() {
    world.open("/world", true);
  }

  function openLink() {
    world.open("https://google.com", true);
  }

  async function getHttp() {
    const response = await world.http({
      method: "GET",
      url: "https://cat-fact.herokuapp.com/facts",
      //data: { foo: "bar" },
    });
    console.log(response);
  }

  return (
    <app>
      <text
        color="white"
        position={[0, 0, 0]}
        value="switch world"
        onPointerDown={switchWorld}
      />
      <text
        color="white"
        position={[2, 0, 0]}
        value="open world"
        onPointerDown={openWorld}
      />
      <text
        color="white"
        position={[4, 0, 0]}
        value="open link"
        onPointerDown={openLink}
      />
      <text
        color="white"
        position={[6, 0, 0]}
        value="http request"
        onPointerDown={getHttp}
      />
    </app>
  );
}

.onUpdate(callback)​

Subscribes to frame updates. Returns a function that unsubscribes.

import React, { useEffect } from "react";
import { useWorld } from "hyperfy";

export default function App() {
  const world = useWorld();

  useEffect(() => {
    return world.onUpdate((delta) => {
      console.log(delta);
    });
  }, []);

  return <app></app>;
}

.on(eventName, callback)​

Subscribes to a world event. Events can be system based such as join, leave and chat, or custom events emitted by another app.

Returns a function that unsubscribes from the event.

.off(eventName, callback)​

Unsubscribes from a world event.

.once(eventName, callback)​

Subscribes to a world event just once.

import React, { useEffect } from "react";
import { useWorld } from "hyperfy";

export default function App() {
  const world = useWorld();

  useEffect(() => {
    return world.on("join", onJoin);
  }, []);

  const onJoin = (avatar) => {
    console.log(`${avatar.name} joined.`);
  };

  function off() {
    world.off("join");
  }

  function once() {
    world.once("join", onJoin);
  }

  return (
    <app>
      <text
        color="white"
        position={[0, 0, 0]}
        value="unsubscribe from join events"
        onPointerDown={off}
      />
      <text
        color="white"
        position={[2, 0, 0]}
        value="subscribe to a single join event"
        onPointerDown={once}
      />
    </app>
  );
}

.emit(eventName, ...args)​

Emits a world event that other apps might be listening for.

Some system event names are reserved: join, leave and chat

.notify(eventName, ...args)​

Sends an event directly to the server. If the caller is already on the server this acts the same as .emit().

Some system event names are reserved: join, leave and chat

.broadcast(eventName, ...args)​

Sends an event to the server and all other clients.

Some system event names are reserved: join, leave and chat

import React, { useEffect } from "react";
import { useWorld } from "hyperfy";

export default function App() {
  const world = useWorld();

  useEffect(() => {
    return world.on("customEvent", (event) => {
      console.log("custom event received");
    });
  }, []);

  function emit() {
    world.emit("customEvent");
  }

  function notify() {
    world.notify("customEvent");
  }

  function broadcast() {
    world.broadcast("customEvent");
  }

  return (
    <app>
      <text
        color="white"
        position={[0, 0, 0]}
        value="emit event to local apps"
        onPointerDown={emit}
      />
      <text
        color="white"
        position={[2, 0, 0]}
        value="notify server apps"
        onPointerDown={notify}
      />
      <text
        color="white"
        position={[4, 0, 0]}
        value="broadcast event to server and all other clients"
        onPointerDown={broadcast}
      />
    </app>
  );
}

.getAudioAnalyser(sourceId)​

Returns an AudioAnalyser that targets a sourceId from <video audioSourceId> or <audio sourceId>.

If the source doesn't exist, it will be connected when it becomes available.

AudioAnalyser currently has a single method .getByteFrequencyData() which returns a Uint8Array of values sampled from the audio source.

import React, { useEffect } from "react";
import { useWorld } from "hyperfy";

export default function App() {
  const world = useWorld();
  const analyser = world.getAudioAnalyser("source1");

  useEffect(() => {
    return world.onUpdate((_) => {
      const frequencyData = analyser.getByteFrequencyData();
      console.log(frequencyData);
    });
  }, []);

  return (
    <app>
      <audio
        autoplay
        loop
        sourceId="source1"
        src="https://archive.org/download/kmart-the-lost-tapes-pdgxxn/Donut%20Specialist%20-%20Kmart-%20The%20Lost%20Tapes%20-%2007%20K%20Funk.mp3"
      />
    </app>
  );
}