How Homegames works

Play in your browser, make a game in Studio, or run a game server at home. This guide explains which option to choose, what gets saved, and how the pieces fit together.

What is Homegames?

Homegames is an open-source platform for making, sharing, and playing JavaScript games. Players use a browser; game authors use the Squish game framework. A game can run inside one browser tab or on a server shared by several players. Each connected device provides its own screen and input. Controls depend on the game: touch, mouse, keyboard, and supported gamepads are available, but a keyboard-only game still needs a keyboard.

• Play now: open Browse games, pick a game, and press Play. You don't need an account.
• Make something: open Studio, choose New game or Import game, and press Play to try it. No account is needed to edit, save, export or share. Follow the game-making guide.
• Host at home: run the Homegames server on one computer and let other devices on your network connect. See self-hosting.

Choose how to play

The game's rules determine whether it is playable alone.

Play downloads the game pack first and keeps a copy in your browser, so the game also works offline. The player and Studio can download a standalone HTML copy you can open without the website. Automatic invitations use our connection server and may need a relay. Manual connection can exchange offers/answers without Homegames signaling when both players have a player already loaded or downloaded; it still depends on a reachable network path.

The website build selects the included games and generates their HTML pages and downloadable packs. Browsing and downloading work without JavaScript; playing and editing need it. Updating the website does not change already-running games.

Play together and share a session

1. Open a game from Browse games.
2. Press Play to start the game in your browser.
3. Press Invite in the bar above the game. Friends can scan the QR code or open the invitation link.

Keep the host tab open and awake. Closing it ends the game for everyone. Returning Home from a guest leaves only that guest; returning Home from the host ends its session.

Invitations are private links. Anyone with the invitation can join while the host remains available, inside or outside the house. There are no public rooms.

Invite in a Studio preview adds players without restarting the preview. Previews and downloaded games are unlisted. Invitations last only while the host is available; games cannot be pinned or moved between hosts.

Automatic invitations currently disconnect peers if their signaling connection ends, even though gameplay goes directly between browsers. Manual pairing is a separate path without that signaling connection. Automatic rooms allow at most 17 participants including the host; games can set a lower limit.

Progress, identity, and downloads

A running session is temporary. Progress survives only if the game implements saving. Games you play on the website save in browser storage; clearing site data or switching browser, device, or website address can leave you without that save. A downloaded HTML file is a copy of the game, not an export of your current progress: use Download save and Load save to move progress. Homegames does not sync saves between devices.

A home server can save game data on disk. A server with disk saves disabled can send saves to connected browsers instead; restoring them also requires the launch flow to supply the saved data. Do not assume that reopening any hosted join link restores an old game. See the saving reference for the authoring contract.

Your in-game player ID identifies a participant in a session, not a permanent account or reserved seat. Games decide how to handle people leaving and returning.

When play does not work

• Invalid/expired invitation: check that the host still has the game open, or ask for a new invitation. Private rooms need the complete invitation link.
• Connection error: check that the host is still connected. Some networks block direct connections and need a relay. A self-hosted WebSocket game instead needs access to its server port.
• Missing project or progress: use the same browser/profile/address; restore the project ZIP and compatible save file if browser data was cleared.
• No sound: interact with the game to unlock browser audio and check volume.
• No phone controls: the game must implement touch or compatible input.
• Report a game issue: email joseph@homegames.io or post in the Discord with the game's name, your browser/device and what happened.

Games describe a scene tree

A game exports a JavaScript class from index.js. It builds a tree of Shape, Text, and Asset nodes and returns its roots from getLayers(). Most games use a 0–100 coordinate plane with a declared aspect ratio. The framework handles drawing the scene and delivering input.

When game code changes a node, it notifies the framework. In a hosted session, one game instance receives input from every connected player and produces the visual state for each screen. playerIds selects the audience of a node and its descendants. The runtime filters every recipient, including spectators, before delivery. Authors still validate actions and keep unrevealed state out of the tree; asset bytes may be shared room-wide. See the multiplayer guide.

Squish: from game state to screen

Squish serializes the scene into binary frames containing coordinates, text, colors, and asset references. The browser's homegames-client decodes those frames and renders to a canvas. Images, sounds, and fonts arrive in separate asset bundles. Hosted input travels back as JSON messages tagged with the connection's player ID.

A game chooses its Squish version through its import, for example require('squish-150'); don't repeat it in metadata. Both the server and the browser must support that version. The current website, Studio and server all run Squish 1.5.0 (squish-150).

Where games run

Local sessions

The browser loads the game's CommonJS files, creates the game instance, runs its Squish serializer, and renders the result in the same tab. No game server is needed for this loop. Studio runs this inside a sandboxed frame and supports real guests through Invite.

Write to the shared game API rather than browser globals or Node built-ins. Local and hosted execution have different environments: local platform services are empty, while hosted games receive the services the server provides. A game that works in a local preview still needs testing before you rely on it on a self-hosted server.

Optional Node/WebSocket sessions

Homenames, the session-management HTTP service in homegames-core, creates and lists sessions. The shared session manager allocates a port and starts the game in Docker when available. Running it as a plain child process requires the host to enable the fork option. Players connect directly to that session's WebSocket; no Homegames website service forwards game frames.

Game logic runs on the host, but authors still need to validate moves: check whose turn it is, whether a player owns the affected object, and whether an action is allowed. Centralized game state does not make arbitrary client input trustworthy.

The services behind the product

There are no accounts, no game database and no publishing service. Games, projects and saves live in each player's browser or on a self-hosted server.

Browser projects and Studio

Studio saves source and media in your browser (IndexedDB). New game starts from a template, and Import game adds a game from a ZIP or HTML file as a separate project. Edits stay in your working copy until you press Save (or Cmd/Ctrl+S), which stores the game and adds a snapshot to History. You can open any snapshot to look at it, and Restore brings it back into the editor. None of this requires an account.

Keep backups: browser storage can be cleared or evicted, and there is no cloud sync. Settings → Download backup saves every Studio project with its history in one file, and Export ZIP saves a single game. Snapshots and progress are separate. Download save/Load save transfers compatible progress for games that implement saving. Another tab's conflicting write or a quota failure is shown instead of claiming the game was saved.

Studio's Learn menu has interactive examples, a getting-started guide, the game API reference and code snippets.

Portable game packs

Export ZIP contains the selected project files and an integrity inventory. Download HTML contains a playable copy and runtime. Both include authored media; neither includes full source history or current game progress. Send files to give someone their own copy, use Share a copy to send it straight to their browser, or use Invite to bring them into your current game.

Portable validation checks structure, imports, runtime compatibility and media. Studio and downloaded HTML run game code in a sandboxed frame that can't reach Studio's storage. That is not a CPU limit or a guarantee of code quality. Test controls, rules, saves and multiple players.

The games on this website are chosen when the site is built. Edit this game saves an editable copy in your browser; exporting it creates a pack you can share directly. It doesn't add the game to the website.

Homegames-authored code and media are MIT licensed. Keep copyright, license and attribution notices when sharing or changing them. Third-party material and imported projects retain their own terms. Playable HTML includes the runtime notices, and source ZIPs preserve the project's notices.

Homegames on your network

One computer runs the dashboard and shared sessions. Other devices open that computer's LAN address and game port. The current downloadable server bundle uses http://<server LAN IP>:7001 and leaves link discovery and HTTPS off initially.

• Discovery: when enabled, your server registers its LAN address and port with homegames.link over an outbound WebSocket. The service matches visitors and servers by their observed public IP, then redirects the browser to the LAN server.
• HTTPS: when enabled, the server generates its TLS key locally and sends a certificate signing request to the API, which obtains a certificate for the network's homegames.link hostname. The hostname points at the private LAN address.
• Connectivity: discovery is not a tunnel or relay. Friends outside your LAN cannot reach a private address merely because they have its link. Use a browser invitation for internet play; it connects through a separate path.

For Node-hosted games, WebSocket traffic goes directly to your server. Browser-hosted games connect the host tab and guests directly. Discovery, certificate requests and error reporting (when you turn them on) contact online services. Offline play needs the game's files and assets to be on the server.

Follow the self-hosting guide for downloads, explicit configuration, firewall ports, backups, and troubleshooting.

Find the implementation

The source is split across repositories. Start with the code responsible for the behavior you want to change; older repository descriptions may describe superseded components.

Browse the Homegames GitHub organization. For an issue, include the page or game version and the steps to reproduce it, or email joseph@homegames.io.