Instances API (Draft WIP) - lolmaxz/vrc-ts GitHub Wiki

Instances API Documentation

The Instances API allows you to interact with VRChat instances—retrieve instance information, create new instances, manage group instances, and more.

Index

  1. getInstance - Retrieve information about a specific instance.
  2. getInstanceShortName - Get short and secure names for an instance.
  3. sendSelfInvite - Send an invite to yourself for an instance. Deprecated
  4. getInstanceByShortName - Get instance information by its short name.
  5. generateNormalInstance - Create a new regular instance.
  6. generateGroupInstance - Create a new group instance.
  7. generateNormalInstanceIdOnly - Generate an instance ID without creating it.
  8. getRandomNonce - Generate a random nonce (UUID v4).

Endpoints

1. getInstance

Retrieve information about a specific instance.

Purpose

Retrieve detailed information about an instance in VRChat. If an invalid instanceId is provided, this method will return null.

Method Signature

getInstance(options: {
  worldId: string;
  instanceId: string;
}): Promise<Instance>

Parameters

  • options (object):

    • worldId (string, required):
      The ID of the world where the instance is located.

    • instanceId (string, required):
      The ID of the instance.

Returns

  • Promise<Instance>: A promise that resolves to the instance object.

Example Usage

// Example: Get information about a specific instance
const instanceInfo = await vrchatApi.instanceApi.getInstance({
  worldId: 'wrld_12345678-1234-1234-1234-1234567890ab',
  instanceId: '12345~region(us)',
});
console.log(instanceInfo);

2. getInstanceShortName

Get short and secure names for an instance.

Purpose

Retrieve the short name and secure name of an instance. The secure name is primarily used for group instances. Only the instance owner can get the short name and secure name.

Method Signature

getInstanceShortName(options: {
  instanceId: string;
}): Promise<InstanceShortName>

Parameters

  • options (object):

    • instanceId (string, required):
      The full instance ID, including world ID and instance details.

Returns

  • Promise<InstanceShortName>: A promise that resolves to an object containing shortName and secureName.

Example Usage

// Example: Get short name for an instance
const instanceShortName = await vrchatApi.instanceApi.getInstanceShortName({
  instanceId: 'wrld_12345678-1234-1234-1234-1234567890ab:12345~region(us)',
});
console.log(instanceShortName);
// Output: { shortName: 'abc123', secureName: 'def456' }

3. sendSelfInvite

Send an invite to yourself for an instance. **Deprecated**

Purpose

Send an invitation to yourself to join a specific instance.

Method Signature

sendSelfInvite(options: {
  worldId: string;
  instanceId: string;
}): Promise<RequestSuccess>

Parameters

  • options (object):

    • worldId (string, required)

    • instanceId (string, required)

Returns

  • Promise<RequestSuccess>: A promise that resolves to a success object.

Deprecated

⚠️ This endpoint is deprecated and may be removed in future updates. Use alternative methods to join instances.

Example Usage

// Example: Send an invite to yourself (Deprecated)
const response = await vrchatApi.instanceApi.sendSelfInvite({
  worldId: 'wrld_12345678-1234-1234-1234-1234567890ab',
  instanceId: '12345~region(us)',
});
console.log(response);

4. getInstanceByShortName

Get instance information by its short name.

Purpose

Retrieve instance information using its short name.

Method Signature

getInstanceByShortName(options: {
  shortName: string;
}): Promise<InstanceShortName>

Parameters

  • options (object):

    • shortName (string, required):
      The short name of the instance.

Returns

  • Promise<InstanceShortName>: A promise that resolves to an object containing shortName and secureName.

Example Usage

// Example: Get instance by short name
const instanceInfo = await vrchatApi.instanceApi.getInstanceByShortName({
  shortName: 'abc123',
});
console.log(instanceInfo);

5. generateNormalInstance

Create a new regular instance.

Purpose

Create a new instance that is not a group instance. This method returns the instance object that was created.

Method Signature

generateNormalInstance(options: {
  worldId: string;
  region: 'us' | 'use' | 'eu' | 'jp';
  instanceType: 'public' | 'friends' | 'friends+' | 'invite' | 'invite+';
  ownerId?: string; // Required for non-public instances
  instanceCode?: string | number; // Optional, default is random code
}): Promise<Instance>

Parameters

  • options (object):

    • worldId (string, required):
      The ID of the world where the instance will be created.

    • region (string, required):
      The region for the instance. Options: 'us', 'use', 'eu', 'jp'.

    • instanceType (string, required):
      The type of instance. Options: 'public', 'friends', 'friends+', 'invite', 'invite+'.

    • ownerId (string, optional):
      The user ID of the instance owner. Required if instanceType is not 'public'.

    • instanceCode (string or number, optional):
      Custom code for the instance (1-5 characters). If not provided, a random code will be generated.

Returns

  • Promise<Instance>: A promise that resolves to the created instance object.

Important Notes

  • For non-public instances ('friends', 'friends+', 'invite', 'invite+'), the ownerId parameter is required.
  • The instanceCode must be between 1 to 5 characters or digits.

Example Usage

// Example: Create a public instance
const newInstance = await vrchatApi.instanceApi.generateNormalInstance({
  worldId: 'wrld_12345678-1234-1234-1234-1234567890ab',
  region: 'us',
  instanceType: 'public',
});
console.log(newInstance);
// Example: Create a friends-only instance
const newInstance = await vrchatApi.instanceApi.generateNormalInstance({
  worldId: 'wrld_12345678-1234-1234-1234-1234567890ab',
  region: 'eu',
  instanceType: 'friends',
  ownerId: 'usr_abcdef12-3456-7890-abcd-ef1234567890', // Your user ID
});
console.log(newInstance);

6. generateGroupInstance

Create a new group instance.

Purpose

Create a new instance specifically for a group. This method returns the instance object that was created.

Method Signature

generateGroupInstance(options: {
  worldId: string;
  groupId: string;
  groupAccessType: 'public' | 'plus' | 'members';
  region: 'us' | 'use' | 'eu' | 'jp';
  roleIds: string[];
  queueEnabled?: boolean; // Optional, default is false
  instanceCode?: string | number; // Optional, default is random code
}): Promise<Instance>

Parameters

  • options (object):

    • worldId (string, required):
      The ID of the world where the instance will be created.

    • groupId (string, required):
      The ID of the group for which the instance is being created.

    • groupAccessType (string, required):
      The type of group instance. Options: 'public', 'plus', 'members'.

    • region (string, required):
      The region for the instance. Options: 'us', 'use', 'eu', 'jp'.

    • roleIds (string array, required):
      An array of group role IDs that can join the instance.

    • queueEnabled (boolean, optional):
      Whether the queue is enabled for the instance. Default is false.

    • instanceCode (string or number, optional):
      Custom code for the instance (1-5 characters). If not provided, a random code will be generated.

Returns

  • Promise<Instance>: A promise that resolves to the created instance object.

Important Notes

  • The roleIds array must contain at least one role ID.
  • All roleIds must start with 'grol_'.
  • The ownerId is automatically set to the groupId.

Example Usage

// Example: Create a group members-only instance
const newGroupInstance = await vrchatApi.instanceApi.generateGroupInstance({
  worldId: 'wrld_12345678-1234-1234-1234-1234567890ab',
  groupId: 'grp_12345678-1234-1234-1234-1234567890ab',
  groupAccessType: 'members',
  region: 'jp',
  roleIds: ['grol_abcdef12-3456-7890-abcd-ef1234567890'], // Replace with actual role IDs
});
console.log(newGroupInstance);

7. generateNormalInstanceIdOnly

Generate an instance ID without creating it.

Purpose

Generate a new instance ID for a regular (non-group) instance without actually creating the instance on VRChat. This method does not make any requests to VRChat servers.

Method Signature

generateNormalInstanceIdOnly(options: {
  worldId: string;
  region: 'us' | 'use' | 'eu' | 'jp';
  instanceType: 'public' | 'friends' | 'friends+' | 'invite' | 'invite+';
  ownerId?: string; // Required for non-public instances
  instanceCode?: string | number; // Optional, default is random code
}): string

Parameters

  • Same as in generateNormalInstance

Returns

  • string: The generated instance ID string.

Important Notes

  • This method is useful for generating instance IDs that can be shared or used elsewhere.
  • You cannot generate instance IDs for group instances using this method.

Example Usage

// Example: Generate an instance ID for a friends+ instance
const instanceId = vrchatApi.instanceApi.generateNormalInstanceIdOnly({
  worldId: 'wrld_12345678-1234-1234-1234-1234567890ab',
  region: 'us',
  instanceType: 'friends+',
  ownerId: 'usr_abcdef12-3456-7890-abcd-ef1234567890', // Your user ID
});
console.log(instanceId);
// Output: 'wrld_12345678-1234-1234-1234-1234567890ab:12345~hidden(usr_abcdef12-3456-7890-abcd-ef1234567890)~region(us)~nonce(abcdef12-3456-7890-abcd-ef1234567890)'

8. getRandomNonce

Generate a random nonce (UUID v4).

Purpose

Generate a random nonce (UUID v4) required for creating certain types of instances.

Method Signature

getRandomNonce(): string

Returns

  • string: A randomly generated UUID v4 string.

Example Usage

// Example: Generate a random nonce
const nonce = vrchatApi.instanceApi.getRandomNonce();
console.log(nonce);
// Output: 'abcdef12-3456-7890-abcd-ef1234567890'

Additional Types and Enums

InstanceType Enum

enum InstanceType {
  Public = 'public',
  Friends = 'friends',
  Friends_Plus = 'hidden',
  Private = 'private',
  Group = 'group',
}
  • Public: Anyone can join.
  • Friends: Only your friends can join.
  • Friends_Plus: Friends of users in the instance can join.
  • Private: Invite-only instances (invite or invite+).
  • Group: Group-specific instances.

InstanceRegionType Enum

enum InstanceRegionType {
  US_WEST = 'us',
  US_EAST = 'use',
  EU = 'eu',
  JP = 'jp',
}
  • US_WEST: US West server.
  • US_EAST: US East server.
  • EU: Europe server.
  • JP: Japan server.

GroupAccessType Enum

enum GroupAccessType {
  Group_Public = 'public',
  Group_Plus = 'plus',
  Group_Members = 'members',
}
  • Group_Public: Anyone can join the group instance.
  • Group_Plus: Friends of users in the instance can join.
  • Group_Members: Only specific group roles can join.

InstanceAccessNormalType Enum

enum InstanceAccessNormalType {
  Public,
  Friends_Plus,
  Friends,
  Invite,
  Invite_Plus,
}
  • Public: Public instance.
  • Friends_Plus: Friends+ instance.
  • Friends: Friends-only instance.
  • Invite: Invite-only instance.
  • Invite_Plus: Invite+ instance.

Instance Object Structure

type Instance = {
  id: string;
  location: string;
  instanceId: string;
  name: string;
  worldId: string | 'offline';
  ownerId?: string;
  tags: string[];
  active: boolean;
  full: boolean;
  n_users: number;
  capacity: number;
  recommendedCapacity: number;
  userCount: number;
  queueEnabled: boolean;
  queueSize: number;
  platforms: {
    standalonewindows: number; // PC users
    android: number; // Quest users
  };
  gameServerVersion?: number | null;
  roleRestricted: boolean;
  secureName: string;
  shortName?: string | null;
  world: unknown; // World object
  clientNumber: 'unknown'; // Deprecated
  photonRegion: InstanceRegionType;
  region: InstanceRegionType;
  canRequestInvite: boolean;
  permanent: boolean;
  groupAccessType?: string;
  strict: boolean;
  nonce: string;
  users?: LimitedUser[];
  hidden?: string;
  friends?: string;
  private?: string;
  hardclose?: boolean;
  hasCapacityForYou?: boolean;
  closedAt?: string;
  ageGate?: boolean;
};

Additional Notes

  • Instance Creation Limits: There may be limits on how many instances you can create within a certain time frame.
  • Permissions: Some methods may require you to be the instance owner or have specific permissions.
  • Nonce: The nonce is a unique identifier required for creating non-public instances. It ensures that each instance is unique.
  • Group Instances: Group instances require you to specify roleIds and are associated with a group (groupId).
  • Deprecation: The sendSelfInvite method is deprecated and may be removed in future updates.

Short Summary

  • Endpoints:

    1. getInstance: Retrieve information about a specific instance.
    2. getInstanceShortName: Get short and secure names for an instance.
    3. sendSelfInvite: Send an invite to yourself for an instance. Deprecated
    4. getInstanceByShortName: Get instance information by its short name.
    5. generateNormalInstance: Create a new regular instance.
    6. generateGroupInstance: Create a new group instance.
    7. generateNormalInstanceIdOnly: Generate an instance ID without creating it.
    8. getRandomNonce: Generate a random nonce (UUID v4).

Note: Replace placeholder IDs like 'wrld_12345678-1234-1234-1234-1234567890ab' with actual IDs as needed.

⚠️ **GitHub.com Fallback** ⚠️