> ## Documentation Index
> Fetch the complete documentation index at: https://runelite.zip/llms.txt
> Use this file to discover all available pages before exploring further.

# Worlds and social

> World hopping, world-list and world-map reads, and social snapshots for friends chats, clans, and chat.

World state splits into a read SDK (`sdk.world`) and a result-aware write surface (`WorldActions`). Social surfaces are read-only snapshots for overlays, coordination, and diagnostics.

## World actions

`WorldActions` covers world-list queries, world-type checks, hopper access, and world-hop dispatch:

```java theme={null}
InteractionResult result = WorldActions.hopTo(302);
```

| Method                               | Behavior                                                                                                                   |
| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
| `openHopper()` / `openLobbyWorlds()` | Opens the world hopper                                                                                                     |
| `isHopperOpen()`                     | Checks the world-switcher container widget                                                                                 |
| `loadWorlds()`                       | Succeeds when the list is loaded; otherwise opens the hopper and returns `WORLD_NOT_FOUND` to signal loading was requested |
| `hopTo(int worldId)`                 | Resolves the world from the loaded list and hops                                                                           |
| `hopTo(World)`                       | Queues the hop request through the client                                                                                  |
| `closeLobbyWorlds()`                 | Clicks the world-switcher close widget when visible                                                                        |

Status codes: already on the target world returns success, a world missing from the list returns `WORLD_NOT_FOUND`, a client throw during the hop returns `WORLD_HOP_FAILED`, and logged-out states return the client guard statuses.

World selection policy (membership, PvP, total level, region, population) belongs to the caller: read and filter the world list through the SDK below, then pass the chosen world to `hopTo(...)`.

## World SDK reads

`com.n3plugins.sdk.world` is read-only. It adds no menu entries, starts no walking, and hops no worlds.

### WorldsApi

```java theme={null}
Optional<Integer> currentWorld = WorldsApi.currentWorldId();

List<WorldSnapshot> members = WorldsApi.worlds().stream()
        .filter(world -> world.hasType(WorldType.MEMBERS))
        .collect(Collectors.toList());

Optional<WorldSnapshot> current = WorldsApi.current();
```

`worlds()` returns an immutable snapshot list from the loaded client world list (empty before loading). `WorldSnapshot` carries `getId()`, `getPlayerCount()`, `getLocation()`, `getIndex()`, `getActivity()`, `getAddress()`, `getTypes()`, `hasType(type)`, and `isCurrent()`. `currentWorldHasType(type)` checks the live client's world type flags.

### WorldMapApi

```java theme={null}
boolean open = WorldMapApi.isOpen();
Optional<LocalPoint> local = WorldMapApi.toLocal(worldPoint);
Optional<WorldPoint> world = WorldMapApi.toWorld(localPoint);
```

`isOpen()`, `mapPosition()`, and `zoom()` read the world-map view. `toLocal(...)` converts a world tile to a scene `LocalPoint` (empty outside the current scene) and `toWorld(...)` converts back. These helpers convert coordinates only.

## Social snapshots

`com.n3plugins.sdk.social` reads friends chats, clan channels, and recent chat messages. These APIs do not send chat, join channels, rank members, or dispatch gameplay actions.

### FriendsApi

```java theme={null}
Optional<FriendsChatSnapshot> chat = FriendsApi.friendsChat();
boolean present = FriendsApi.isInFriendsChat("Player name");
```

`friendsChat()` returns a snapshot when the client has a friends-chat manager. The snapshot contains owner, chat name, local rank, kick rank, and an immutable member list; members carry name, world, and rank.

### ClanApi

```java theme={null}
Optional<ClanSnapshot> clan = ClanApi.clanChannel();
Optional<ClanSnapshot> guest = ClanApi.guestClanChannel();
```

Each snapshot contains the channel name and an immutable member list with names, worlds, and `ClanRank` values.

### ChatApi

```java theme={null}
List<ChatMessageSnapshot> recent = ChatApi.recentMessages();
```

`recentMessages()` returns immutable recent messages, newest first. The buffer retains at most 100 messages and `clearRecentMessages()` clears it. Packet Utils wiring feeds `record(...)` from the chat message listener; consume `recentMessages()` rather than recording events yourself.

## Minigame teleports

`Minigames` (`sdk.query`) reads both minigame teleport entry surfaces (the grouping interface and the Magic-book minigame rows); the teleport write lives in `Api.actions.minigame.MinigameTeleportActions`. See the [widgets playbook](/guides/widgets) for the read methods and snapshot fields.