Sending Packets

Sending Packets

Currently there aren't much in terms of "sugar" for features. For now if something is missing, you can use the await client.send([packet]) method to send various packets.

You can find packets in the packets export.

import { packets } from "@gwigz/homunculus-core"

packets.ejec
ejectGroupMemberReply
ejectGroupMemberReplyMetadata
ejectGroupMemberRequest
ejectGroupMemberRequestMetadata
ejectUser
ejectUserMetadata

Validation

Packets are sent with minimal validation. The serializer only throws an error if it cannot serialize the packet. Otherwise, packets are sent as-is, and the server will typically ignore any invalid packets.

import { packets } from "@gwigz/homunculus-core"

client.send([
  packets.ejectUser({
    data: { targetId: "f09c1bae-df16-4413-93d7-251ed92c6d9a" },
Property 'flags' is missing in type '{ targetId: string; }' but required in type '{ targetId: string; flags: number; }'.
  }),
])

Note that ejecting a user is already implemented in the Nearby class.

client.nearby.eject("f09c1bae-df16-4413-93d7-251ed92c6d9a")

Reliable Packets

To ensure a packet is acknowledged by the server, use await client.sendReliable([packet]). This method should resolve quickly if the network is stable. However, you do not need to use reliable sending for every packet—only when acknowledgment is required.

Reliable packets will:

• Retry up to 3 times if no acknowledgment is received, using the same sequence number to prevent duplicates
• Timeout after 5 seconds, if the server does not respond in that time, the promise will reject

Examples

Optional values such as agentData.agentId which many packets require can be omitted, and the serializer will fill them in with defaults.

import { packets, UUID } from "@gwigz/homunculus-core"
import assert from "node:assert"

client.send([
  packets.soundTrigger({
    soundData: {
      soundId: "884f50ac-9a0b-5667-334f-78ce08f9402e",
      ownerId: UUID.zero,
      objectId: UUID.zero,
      parentId: UUID.zero,
      handle: client.region.handle,
      position: client.self.position,
      gain: 1,
    },
  }),
])

Now, as for how you'd figure out what the fields actually are, or their defaults, you'll want to check the official viewers source code.