Packet Client

packet-client is a TypeScript WebSocket client for Habbo-based retros and emulators.

It connects like a normal user session, performs the initial handshake, encodes outgoing packets, decodes incoming packets, tracks room state, and can react to room chat in real time. It also includes a terminal UI for sending commands and an optional OpenAI-powered reply flow.

What This Project Does

• Connects to a server over WSS_URL
• Logs in using an auth token and SSO flow
• Sends protocol packets that look like a real client session
• Decodes incoming packets such as room users, room status, chat, friends, and errors
• Tracks room users, positions, aliases, and friend data in memory
• Supports live room actions like chat, move, follow, sign, dance, action, friend request, and respect
• Can auto-reply to room chat with OpenAI
• Stores conversation/session state under sessions/
• Provides a terminal UI when LIVE_STDIN=1

Requirements

• A valid auth token for the target server
• A reachable websocket endpoint

TUI Commands

When LIVE_STDIN=1, the terminal UI is enabled.

Session:

• /quit - close the websocket and exit the client
• /mute - stop automatic room replies
• /unmute - resume automatic room replies

Room State:

• /units - print known room units, usernames, user IDs, and positions
• /friends - print the loaded friend list with online and in-room state
• /alias <roomUnit> <username> - manually map a room unit ID to a username

Chat:

• /bubble <int> - set the chat bubble style used for outgoing room chat

Movement:

• /move <x> <y> - move to room coordinates; also accepts /move <x>,<y>
• /auto <username> - auto-move near a visible room user; run /auto with no username to disable it

Social:

• /addfriend <username> - send a friend request
• /respect <userId|username> - send respect packets to a user ID or room username
• /follow <username> - send :follow <username> as room chat; this is for same-room follow behavior if the hotel supports that chat command
• /stalk <username> - send StalkFriendEvent for a loaded friend; this switches/forwards to the friend's current room

Avatar Actions:

• /sign <signId> - show a room sign
• /dance <danceId> - set the avatar dance
• /action <actionId> - trigger an avatar action

Any non-command line is sent as room chat when the session is ready.

Keyboard controls:

• Esc - pause or resume live log scrolling; buffered logs are printed when resumed
• Ctrl+C - close the websocket and exit
• Left / Right / Home / End - move the input cursor
• Backspace / Delete - edit the current input line

Notes

• SSO token handling can vary between hotels; update the auth flow as needed for the target hotel
• This project is provided as-is; use it only where you have permission to connect and test
• Session history is stored locally in sessions/
• Packet decoding helpers live in src/protocol/
• Room send helpers live in src/room/
• TUI code lives in src/tui/
• The client currently uses a real-user style login/session flow rather than acting as a server-side integration