@indiegems/gem-web-sdk 16.2.0 → 16.3.0

package/docs/api/api-reference-game.md

@@ -1,6 +1,6 @@
 # The browser surface — API reference
 
-Generated from `@indiegems/gem-web-sdk/sdk` v16.2.0, the version of the package this file ships in. Every symbol below carries an explicit anchor, its `anchor` in `reference.json` beside this file.
+Generated from `@indiegems/gem-web-sdk/sdk` v16.3.0, the version of the package this file ships in. Every symbol below carries an explicit anchor, its `anchor` in `reference.json` beside this file.
 
 `@indiegems/gem-web-sdk/sdk` is the one import a game writes, wherever its code runs. `@indiegems/gem-web-sdk/game` exports exactly the symbols on this page and nothing else, for a build that wants only this half.
 
@@ -5587,6 +5587,406 @@ only if you are instrumenting something that runs before the SDK exists.
 | --- | --- |
 | `options` | `BootTimelineOptions` |
 
+<a id="brandingtheme"></a>
+
+## BrandingTheme
+
+```ts
+type BrandingTheme = "light" | "dark"
+```
+
+A theme a variant is drawn for.
+
+<a id="brandingvariant"></a>
+
+## BrandingVariant
+
+```ts
+interface BrandingVariant
+```
+
+One file of a [BrandingAsset](#brandingasset): a render at one size and density, a
+scalable image, or the one file of a sound or a font.
+
+<a id="brandingvariant-url"></a>
+
+## BrandingVariant.url
+
+```ts
+readonly url: string
+```
+
+The file's URL, absolute and on the platform's own host. Content-hashed,
+so a re-render is a new URL: look it up each session rather than storing
+one in a save or your build.
+
+<a id="brandingvariant-type"></a>
+
+## BrandingVariant.type
+
+```ts
+readonly type: string
+```
+
+Its MIME type, such as `image/png` or `image/svg+xml`.
+
+<a id="brandingvariant-bytes"></a>
+
+## BrandingVariant.bytes
+
+```ts
+readonly bytes: number
+```
+
+Its size in bytes.
+
+<a id="brandingvariant-width"></a>
+
+## BrandingVariant.width
+
+```ts
+readonly width?: number
+```
+
+An image's width in pixels (an SVG's in its viewBox units).
+
+<a id="brandingvariant-height"></a>
+
+## BrandingVariant.height
+
+```ts
+readonly height?: number
+```
+
+An image's height in pixels (an SVG's in its viewBox units).
+
+<a id="brandingvariant-size"></a>
+
+## BrandingVariant.size
+
+```ts
+readonly size?: number
+```
+
+The CSS px box this render was made for, with [BrandingVariant.density](#brandingvariant-density).
+Absent on a render meant for any box up to its width.
+
+<a id="brandingvariant-density"></a>
+
+## BrandingVariant.density
+
+```ts
+readonly density?: number
+```
+
+Device pixels per CSS px of a render made for [BrandingVariant.size](#brandingvariant-size).
+
+<a id="brandingvariant-vector"></a>
+
+## BrandingVariant.vector
+
+```ts
+readonly vector?: true
+```
+
+`true` on a scalable image: it draws crisply at any size.
+
+<a id="brandingvariant-theme"></a>
+
+## BrandingVariant.theme
+
+```ts
+readonly theme?: BrandingTheme
+```
+
+The one theme the file is for. Absent: either theme.
+
+<a id="brandingasset"></a>
+
+## BrandingAsset
+
+```ts
+interface BrandingAsset
+```
+
+One asset in the platform's branding manifest.
+
+<a id="brandingasset-id"></a>
+
+## BrandingAsset.id
+
+```ts
+readonly id: string
+```
+
+What a game asks for: `'gem-logo'`, `'gems-mark'`. Never renamed.
+
+<a id="brandingasset-kind"></a>
+
+## BrandingAsset.kind
+
+```ts
+readonly kind: string
+```
+
+`'image'`, `'audio'` or `'font'` today. The platform may add more, so
+compare it rather than switching on it exhaustively.
+
+<a id="brandingasset-variants"></a>
+
+## BrandingAsset.variants
+
+```ts
+readonly variants: readonly BrandingVariant[]
+```
+
+Every file of it, smallest first. Never empty.
+
+<a id="brandinglookup"></a>
+
+## BrandingLookup
+
+```ts
+type BrandingLookup = { outcome: "ok"; url: string; variant: BrandingVariant; asset: BrandingAsset } | { outcome: "not_found" | "unavailable" }
+```
+
+What a branding lookup resolves with. Only `ok` carries a URL.
+
+- `ok`: the platform has it, and `url` is the file picked for what you asked.
+- `not_found`: the manifest was read and has no asset with that id and kind,
+  or none of its files fits the theme you asked for. Draw nothing for it.
+- `unavailable`: the manifest could not be read — offline, a network error,
+  a Content-Security-Policy that leaves out `https://gemarcade.com`. Draw the
+  copy you bundled from the package's `brand/` folder, if there is one.
+
+<a id="brandinglist"></a>
+
+## BrandingList
+
+```ts
+type BrandingList = { outcome: "ok"; assets: readonly BrandingAsset[] } | { outcome: "unavailable" }
+```
+
+What [BrandingApi.list](#brandingapi-list) resolves with.
+
+<a id="brandingimageoptions"></a>
+
+## BrandingImageOptions
+
+```ts
+interface BrandingImageOptions
+```
+
+How to pick one image from an asset's variants.
+
+<a id="brandingimageoptions-size"></a>
+
+## BrandingImageOptions.size
+
+```ts
+readonly size?: number
+```
+
+The CSS px box you draw it in. A render made for exactly that box wins;
+then a scalable image; then the narrowest render wide enough for
+`size × density`. Leave it out for the largest: the scalable image, or
+else the widest render.
+
+<a id="brandingimageoptions-density"></a>
+
+## BrandingImageOptions.density
+
+```ts
+readonly density?: number
+```
+
+Device pixels per CSS px. Defaults to the screen's `devicePixelRatio`;
+pass `3` for a canvas or texture you scale down yourself.
+
+<a id="brandingimageoptions-theme"></a>
+
+## BrandingImageOptions.theme
+
+```ts
+readonly theme?: BrandingTheme
+```
+
+Prefer a file drawn for this theme. Files for the other theme are never picked.
+
+<a id="brandingassetoptions"></a>
+
+## BrandingAssetOptions
+
+```ts
+interface BrandingAssetOptions
+```
+
+What [BrandingApi.get](#brandingapi-get) takes: the asset's kind, and how to pick a file.
+
+<a id="brandingassetoptions-size"></a>
+
+## BrandingAssetOptions.size
+
+```ts
+readonly size?: number
+```
+
+The CSS px box you draw it in. A render made for exactly that box wins;
+then a scalable image; then the narrowest render wide enough for
+`size × density`. Leave it out for the largest: the scalable image, or
+else the widest render.
+
+<a id="brandingassetoptions-density"></a>
+
+## BrandingAssetOptions.density
+
+```ts
+readonly density?: number
+```
+
+Device pixels per CSS px. Defaults to the screen's `devicePixelRatio`;
+pass `3` for a canvas or texture you scale down yourself.
+
+<a id="brandingassetoptions-theme"></a>
+
+## BrandingAssetOptions.theme
+
+```ts
+readonly theme?: BrandingTheme
+```
+
+Prefer a file drawn for this theme. Files for the other theme are never picked.
+
+<a id="brandingassetoptions-kind"></a>
+
+## BrandingAssetOptions.kind
+
+```ts
+readonly kind: string
+```
+
+The kind you expect: `'image'`, `'audio'` or `'font'`. An asset of another
+kind answers `not_found`. `size` and `density` apply to images only; for
+any other kind the first file wins.
+
+<a id="brandingcurrency"></a>
+
+## BrandingCurrency
+
+```ts
+type BrandingCurrency = "GEMS" | "ARCADE_TICKETS"
+```
+
+The platform currencies with a mark: Gems and Coins.
+
+<a id="brandingapi"></a>
+
+## BrandingApi
+
+```ts
+interface BrandingApi
+```
+
+The platform's branding, as the platform serves it now. `gem.branding` is
+one of these. Nothing here rejects but a bad argument.
+
+<a id="brandingapi-get"></a>
+
+## BrandingApi.get
+
+```ts
+get(id: string, options: BrandingAssetOptions): Promise<BrandingLookup>
+```
+
+Any asset in the platform's branding manifest, by id and kind — including
+ones added after this SDK was released.
+
+```js
+const logo = await gem.branding.get('gem-logo', { kind: 'image', size: 64 });
+if (logo.outcome === 'ok') img.src = logo.url;
+```
+
+| Parameter | Type |
+| --- | --- |
+| `id` | `string` |
+| `options` | `BrandingAssetOptions` |
+
+**Returns.** Resolves `ok`, `not_found` or `unavailable`. Rejects only for an
+  argument that is not one (an empty id, a size that is not a positive
+  number).
+
+<a id="brandingapi-logo"></a>
+
+## BrandingApi.logo
+
+```ts
+logo(options?: BrandingImageOptions): Promise<BrandingLookup>
+```
+
+The Indie Gems logo, the brand gem. Scalable: draw it at 32 CSS px or more,
+as served (`docs/branding.md` has the usage rules).
+
+| Parameter | Type |
+| --- | --- |
+| `options` | `BrandingImageOptions` |
+
+<a id="brandingapi-wordmark"></a>
+
+## BrandingApi.wordmark
+
+```ts
+wordmark(options?: BrandingImageOptions): Promise<BrandingLookup>
+```
+
+The Gem Arcade wordmark. Draw it at 60 CSS px wide or more, as served.
+
+| Parameter | Type |
+| --- | --- |
+| `options` | `BrandingImageOptions` |
+
+<a id="brandingapi-currencymark"></a>
+
+## BrandingApi.currencyMark
+
+```ts
+currencyMark(currency: BrandingCurrency, options?: BrandingImageOptions): Promise<BrandingLookup>
+```
+
+The mark of a platform currency, by its slug: `'GEMS'` or
+`'ARCADE_TICKETS'` (Coins). Pass `size: 20` or `32` for the inline icon
+beside an amount, or leave it out for the hero art of a reward screen.
+`docs/brand-art.md` says where each may be drawn.
+
+| Parameter | Type |
+| --- | --- |
+| `currency` | `BrandingCurrency` |
+| `options` | `BrandingImageOptions` |
+
+<a id="brandingapi-trophy"></a>
+
+## BrandingApi.trophy
+
+```ts
+trophy(options?: BrandingImageOptions): Promise<BrandingLookup>
+```
+
+The trophy, for where your game shows what a player has achieved.
+
+| Parameter | Type |
+| --- | --- |
+| `options` | `BrandingImageOptions` |
+
+<a id="brandingapi-list"></a>
+
+## BrandingApi.list
+
+```ts
+list(): Promise<BrandingList>
+```
+
+Every asset the platform serves, or `unavailable` when the manifest could
+not be read.
+
 <a id="listchallengesoptions"></a>
 
 ## ListChallengesOptions
@@ -10816,6 +11216,31 @@ exactly as given, and call `purchase(skuId)` from the player's press. After
 
 **Guides.** [arcade-and-store](../arcade-and-store.md)
 
+<a id="gem-branding"></a>
+
+## Gem.branding
+
+```ts
+readonly branding: BrandingApi
+```
+
+The platform's branding — the Indie Gems logo, the Gem Arcade wordmark,
+the Gems and Coins marks and the trophy — as the platform serves it now,
+so a changed mark reaches your game with no republish.
+
+Look up any asset by id and kind with `get`, or use `logo`, `wordmark`,
+`currencyMark` and `trophy`. Every URL is on the platform's own host.
+Nothing rejects but a bad argument: an asset the platform does not list is
+`not_found`, and a manifest that could not be read is `unavailable`, when
+you draw the copy you bundled from `brand/` instead.
+
+```js
+const logo = await gem.branding.logo();
+if (logo.outcome === 'ok') menuLogo.src = logo.url;
+```
+
+**Guides.** [branding](../branding.md)
+
 <a id="gem-avatarpickeravailable"></a>
 
 ## Gem.avatarPickerAvailable

package/docs/api/api-reference-server.md

@@ -1,6 +1,6 @@
 # The server surface — API reference
 
-Generated from `@indiegems/gem-web-sdk/sdk` v16.2.0, the version of the package this file ships in. Every symbol below carries an explicit anchor, its `anchor` in `reference.json` beside this file.
+Generated from `@indiegems/gem-web-sdk/sdk` v16.3.0, the version of the package this file ships in. Every symbol below carries an explicit anchor, its `anchor` in `reference.json` beside this file.
 
 `@indiegems/gem-web-sdk/sdk` is the one import a game writes, wherever its code runs. `@indiegems/gem-web-sdk/server` exports exactly the symbols on this page and nothing else, for a build that wants only this half.