> For the complete documentation index, see [llms.txt](https://wiki.playgama.com/playgama/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.playgama.com/playgama/guides/game-development/first-session.md).

# Loading and first session

Loading flow, the moment to send game\_ready, onboarding, and keeping players in the first minutes.

Most players decide in the first minute whether to stay. A game that loads slowly, opens on a wall of menus or does not explain itself loses them before they see the gameplay — and a low playtime keeps a game from wider distribution (see [How game moderation and distribution work](/playgama/guides/how-game-moderation-and-distribution-work-at-playgama.md)). This guide covers the path from the first byte to the first minutes of play.

## Loading

* **The Bridge first, then the game.** Load the SDK script first and wait for `bridge.initialize()` before the game starts loading its engine and assets — a [required step](/playgama/bridge-sdk/api.md#required-steps) of the SDK. The other order is easy to miss on a fast connection: throttle the network to slow 4G in the browser's developer tools and watch the requests — `playgama-bridge.js` must come before the game's own files. Loading the Bridge first also means the language, saved progress and audio state are known before the first scene is built.
* **Load little before the first playable moment.** Ship only what the first scene needs in the initial download, and load the rest — later levels, music, other languages — in the background once the game is playable. As a guideline, keep the initial download under about 5 MB and the time to the first playable frame under about 5 seconds; never let it exceed 10. See [Performance & Optimization](/playgama/guides/performance-and-optimization.md).
* **Show real progress.** A loading bar that moves smoothly with the actual download, not one that jumps or sits still. Avoid blank screens: the first thing the player sees is the game's own loading screen.
* **No splash screens in a row.** At most one short studio logo; never a chain of logos or an intro the player cannot skip.
* **Send `game_ready` at the right moment.** Call [`platform.sendMessage('game_ready')`](/playgama/bridge-sdk/api/platform.md#sending-a-message-to-the-platform) when the first playable frame is on screen — not when loading starts and not while the loading screen is still visible. The platform hides its own loading screen and starts counting the session from it.
* **Report later loading.** If the game loads heavy content after `game_ready`, such as a new world, wrap it in `in_game_loading_started` and `in_game_loading_stopped` messages.

## Into the game fast

* One click from the loading screen to gameplay, ideally zero. Put settings, the shop and the level map behind the first level, not in front of it.
* Do not ask for a name, a sign-in or a choice of options before playing (items 1.2.1–1.2.2 of the [Technical Requirements](/playgama/game-requirements/technical-requirements.md)).
* Make the language right from the first screen: take it from [`platform.language`](/playgama/bridge-sdk/api/platform.md#language) (item 3.4.2 of the [User Experience Requirements](/playgama/game-requirements/user-experience-requirements.md)).

## Teach by playing

* Teach the core mechanic in the first 30–60 seconds through play: a highlighted target, a hand animation, a ghosted path — not a page of text (item 3.1.3).
* Introduce one mechanic at a time, and let the player succeed at it before adding the next.
* Show the controls for the current device: a keyboard hint on desktop, gesture hints on touch (see [Controls and input](/playgama/guides/game-development/controls.md)).
* Let returning players skip the tutorial, and never replay it after a reload.

## Keep the player

* **Clear goal.** The player knows within the first minute what they are trying to do and how well they are doing.
* **Early wins.** The first levels are short and easy enough to finish; the difficulty rises gradually after that (item 3.1.2).
* **Progress that sticks.** Save after every meaningful step and restore it on the next visit (see [Saving progress](/playgama/guides/game-development/saving-progress.md)). A returning player continues where they stopped.
* **A reason to come back.** Daily rewards, unlocks, a next level teaser or a best score to beat — [Daily Rewards](/playgama/bridge-sdk/api/daily-rewards.md), [Achievements](/playgama/bridge-sdk/api/achievements.md) and [Leaderboards](/playgama/bridge-sdk/api/leaderboards.md) in the SDK help here.
* **Enough content.** Aim for at least 10 minutes of distinct gameplay before the game starts repeating itself.
* **Ads that respect the session.** Ads appear only at natural pauses, and the Bridge holds back the first one (see [Ads best practices](/playgama/guides/monetization/best-practices.md)).

## Measure it

Send product events — tutorial completed, level started, completed and failed — with [`analytics.send`](/playgama/bridge-sdk/api/analytics.md) to see where players drop off. Use stable event names and put the changing part, such as the level number, in the event data.