JAVASCRIPT SDKv0.3.38

Bring your Playmos to the couch.

Try it first

Join and leave a couch session#

You need A TV or host browser, a phone and a supported game.

Open the couch experience and follow the controller pairing flow.
Join a player, choose a slot and check visible focus and input.
Leave and reconnect, checking that the old player no longer controls the slot.

Check your result Each joined player controls only their assigned seat.

Couch mode puts the Hub on your TV. Playmos Controller keeps your account on your phone. Buddy Mode gives up to four players their own place on the couch.

Open Couch mode on your TV#

Select the TV icon labeled Couch mode beside your profile in the upper-right corner of the Hub. On phones, the icon stays visible when navigation collapses.

Open Couch mode beside your profileActual local Hub preview. The TV launcher sits at the far right of the header.

Open Couch mode in the TV browser, or display the Hub from your computer. The games run in that browser. Choose My games, All games or Play again. Pair your phone to bring a limited profile view to the TV; your phone registration remains on your account when you leave.

**Couch mode with Buddy Mode open**Local browser preview. The invitation shown here is an example, not a reusable pairing code.

One Playmos app on your phone#

Mobile Hub browsing and the installed Controller app share My games, Discover, Controller, Profile and Wallet in one bottom navigation. Sign-in returns you to the view you chose. Device registration stays out of your game library.

**One mobile Playmos experience**Actual local mobile browser preview. Discover uses the same shell as your games, profile, wallet and controller.

Use the controller icon in the bottom center to connect to a TV. It guides installation, sign-in and phone registration when needed, then opens the scanner. You can browse games before installing; TV controls and scanning require the installed app.

Install Playmos Controller once#

Scan the TV’s QR code with your phone’s normal camera to open Playmos Controller.
Tap the controller icon in the bottom center, then install Playmos Controller or use your browser’s Add to Home Screen option. On iPhone, use Safari’s Share menu.
Launch it from the home-screen icon. The center Controller tab stays at setup until the app runs in standalone mode; your other tabs remain available.
Sign in to your Playmos account and register this phone. Its registration is saved to your account.
For future TVs, open the installed app and tap the controller icon in the bottom navigation. Allow the camera and scan the TV from inside the app.

**Controller setup in the center tab**Actual local browser preview of setup inside the unified app. This is not an installed-phone screenshot.

Camera scanning and service workers require a secure HTTPS site on your phone. An ordinary LAN HTTP address is useful for reviewing the TV layout, but does not prove the phone installation flow.

Your games, profile and wallet#

Signed out, Couch mode shows a large QR to connect your phone and sign in before booting your console. Signed in, it loads your console and waits for an online phone or physical controller. A controller already connected opens home immediately. Remembered offline phones remain on the connection screen. Guest play is an explicit choice after a controller connects. Your profile names the console; recently played games lead the horizontal game rail, and the selected game supplies the backdrop. Open Controllers in the action dock to invite friends and manage the four-player lineup. Console phone settings inside that panel handles personal pairing, disconnecting and switching to a guest.

**Your connected TV puts games first**Local layout fixture with a sample profile, not a real account or physical pairing. Personal QR setup is tucked into Controllers.

The installed app brings together your saved and recent games, profile and account controls. Account → Controllers lets you rename or revoke registered phones. A registered phone can request a limited TV profile session; the TV approves that request. Controller registration alone never signs a TV into your full account or wallet.

Use Leave TV when you finish. This removes the TV profile session while keeping your phone registered for next time. Your wallet stays on the phone. Buying IAP from a friend’s TV with phone approval and keeping the entitlement on your account remains a follow-up.

**Connect your phone to boot**Local presentation fixture. The sample QR grants no access.

**Your console, waiting for controls**Local presentation fixture with a sample signed-in profile and offline remembered phone.

Your Friends List#

Friends List is separate from Controllers. Open it from desktop navigation, your mobile app header, or the console dock and guide. Add someone by their player tag; they must accept before activity is shared. The list shows online, away, busy or offline, their custom profile status and their current game when they enable game activity sharing. Invisible hides presence. Editing your status uses the same profile status as the rest of Playmos.

Select a text field on the TV, then tap Type on TV on your approved phone. That tap opens a native phone input. Use on TV copies plain text into the selected field; it does not submit friend requests or account forms automatically. Passwords and wallet fields are not eligible. Physical phone keyboard presentation remains a device acceptance check.

**Your people on the console**Local presentation fixture with sample contacts, statuses and game activity.

Fit the TV display#

TV Setup adjusts the safe area, with visible corner guides and plus/minus controls. The inset is saved on that TV and applies to console content, the guide and the game viewport. Use Reset to return to the default. The clock and controls are sized for distant TV viewing; physical readability at 25 feet remains unverified.

Console sounds#

Open Audio in the console dock to turn Menu sounds and Background music on or off independently. Your choices are saved on this device. Soft bloops mark selection and confirmation; an original pentatonic score plays quietly in the menus after browser audio is activated by a gesture. Music stops during games and when the page is hidden.

**Console audio settings**Local presentation fixture. Sound and music toggles save independently on this device.

Your console guide#

Games fill the display. Couch mode requests browser fullscreen when you launch; browsers can require a direct user gesture. Press Start + Select together on a phone or physical controller to open the side guide. Resume returns to the game, Friends List opens your contacts, Controllers & players opens the lineup, and Return to console home closes the game. Escape is a keyboard fallback when the console has keyboard focus. The guide releases controller input; game simulation can continue behind it.

**The console guide**Local presentation fixture with a sample game viewport. Not gameplay, native fullscreen or physical-controller evidence.

Choose players in Buddy Mode#

Open Buddy Mode for the separate couch co-op experience. The Who’s playing? screen has four player slots. Friends can join before or during a game.

The Controllers screen shows physical controllers detected by the browser. Wake a gamepad by pressing a button. Choose an unused gamepad for an open slot, or change an existing player’s Controls selector. Physical controllers can swap places without moving player profiles. A registered phone player can return to their own phone; a guest needs to scan and join with a registered phone before using phone controls. To take a guest’s only gamepad for a phone player, first move or remove that guest.

**Four players, one console**Local layout fixture. The invitation is deliberately nonfunctional; no physical gamepads are connected.

**Who’s playing? — four open player slots**Actual local player selection screen. No signed-in players or simulated hardware are shown.

How you join	What happens
Physical controller	Connect it to the TV computer and press L + R to take an open slot as a guest.
Phone with your profile	Open the installed Playmos Controller, tap the controller scanner and scan the Buddy QR. The TV approves your request.
Profile plus physical controller	Join with your phone, then select an available physical controller for your player slot.
Virtual controller	Keep using your phone’s controls when there is no spare physical controller.

Choose Done to return to the game shelves; the room stays open and the QR remains visible. Open Players from Couch mode or the game toolbar whenever someone joins, changes controllers or leaves. A game must explicitly support Buddy controls to receive separate player inputs.

Drop in and out anytime#

A player can leave from their phone, or the host can remove them from the player screen. Other players keep their slots. A new arrival takes an open slot with a new player identity. After removing a physical controller, release L + R before pressing it again to rejoin.

Lost input updates release held controls. A disconnected phone’s seat retires after 60 seconds; a room without a TV heartbeat expires after two minutes. End Buddy Mode closes the room and removes its guest profiles. Leaving a room does not revoke the phone’s account registration.

Returning to Playmos#

A service worker caches the generic app shell and versioned static files, including the scanner worker and decoder. QR decoding runs in a dedicated worker. Returning players can reopen the shell offline; library updates, sign-in, pairing, live controller input and game downloads still need a connection. Account, wallet and API responses are excluded from this shell cache. Updates wait until existing app windows close.

Adding Buddy support to a game#

The game-side adapter is a source candidate at apps/hub/public/buddy-client.mjs, not a published SDK release. Bundle it with your game, configure the exact trusted Hub origin and use connectBuddyHost with onPlayers, onInput and onStatus. Track players by ID and keep their stable slot numbers. Release controls when a player leaves or the host disconnects. Profile display is not login, purchase or score authority.

Existing single-player games do not become multiplayer automatically. The local game preview also needs its game server reachable from the TV browser; a loopback-only game URL can fail from another device. See Phone & gamepad controllers for the separate portable controller SDK and managed party-room integrations.

If it did not work#

If pairing expires, create a new pairing session; never reuse another player’s profile or seat identity.

Try one variation Leave one seat while another keeps playing. Only the departing seat should lose control.

Continue with the next guide →