@playabl/sdk 1.1.0-beta.0 → 1.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +7 -8
- package/dist/index.d.ts +266 -8
- package/dist/index.js +54 -6
- package/package.json +1 -4
package/README.md
CHANGED
|
@@ -8,14 +8,7 @@ Browser SDK for Playabl games providing parent-platform communication, game stat
|
|
|
8
8
|
npm install @playabl/sdk
|
|
9
9
|
```
|
|
10
10
|
|
|
11
|
-
|
|
12
|
-
the layout types are on the `beta` dist-tag:
|
|
13
|
-
|
|
14
|
-
```bash
|
|
15
|
-
npm install @playabl/sdk@beta
|
|
16
|
-
```
|
|
17
|
-
|
|
18
|
-
`sdk.game` and `sdk.devtools` need runtime 1.0.0 or newer in the environment the game loads from. That runtime is live on dev, staging and production.
|
|
11
|
+
`sdk.game` and `sdk.devtools` need runtime 1.0.0 or newer in the environment the game loads from. That runtime is live on dev, staging and production. What 1.1.0 adds needs runtime 1.6.0 or newer there.
|
|
19
12
|
|
|
20
13
|
## Usage
|
|
21
14
|
|
|
@@ -194,6 +187,12 @@ const { items, entries } = synthesiseLayout(layout, tweaksSchema, {}, DEFAULT_FR
|
|
|
194
187
|
|
|
195
188
|
It is an ES module: `import` loads it anywhere, and `require()` on Node 20.19+ or 22.12+. TypeScript finds its types with `moduleResolution` set to `node16`, `nodenext` or `bundler` in an ES module project, and only with `nodenext` (TypeScript 5.8 or newer) in a CommonJS one; `node10` does not read `exports`, so it is not supported. Besides `synthesiseLayout` and `DEFAULT_FRAME`, it exports the role table (`LAYOUT_ROLES`, `LAYOUT_ANCHORS`, `LAYOUT_WEIGHTS`, `LAYOUT_ALIGNS`, `ENTRY_FIELDS`), `layoutKey`, `defaultPrefix` and `roleLimits`; every table is frozen.
|
|
196
189
|
|
|
190
|
+
### Runtime resolution
|
|
191
|
+
|
|
192
|
+
Most games never configure the runtime. Call `configure({ runtimeUrl })` or `configure({ manifestUrl })` before any other SDK call to import a specific runtime build or read a specific manifest.
|
|
193
|
+
|
|
194
|
+
A page can instead name its environment's manifest in `window.__PLAYABL_MANIFEST_URL__`, set before any module script runs. The Playabl workspace preview does this: it is served from `localhost` but belongs to dev, staging or production, so without it the wrapper would take `localhost` for SDK development and import its build-time fallback runtime. The order is `configure({ runtimeUrl })`, `configure({ manifestUrl })`, a valid `?env=` on the game URL (`?env=local` keeps the fallback), the global, then the hostname. The global is used only when it is a string holding an `https:` URL on `cdn.playabl.ai`, `cdn-staging.playabl.ai` or `cdn-dev.playabl.ai` on the default port; any other value is ignored with one console warning. It needs 1.1.0-beta.1 or newer.
|
|
195
|
+
|
|
197
196
|
## API Surface
|
|
198
197
|
|
|
199
198
|
- `sdk.ready()` - Connects to the Playabl parent iframe host.
|
package/dist/index.d.ts
CHANGED
|
@@ -40,6 +40,7 @@ type CellGridHooks = Required<Pick<ContentHooks, 'blankLevel' | 'placeInLevel' |
|
|
|
40
40
|
* coordinates or origins also refuse. Pure and synchronous, as every content
|
|
41
41
|
* hook must be; nothing here needs the runtime, so a game can call it while
|
|
42
42
|
* building its vocabulary.
|
|
43
|
+
* A game that declares `describeScene().grid` with `cols`/`rows` needs none of this: the runtime's board profile (runtime 1.6.0+) supplies the three hooks itself; this helper stays for games on the raw-hook path.
|
|
43
44
|
*/
|
|
44
45
|
declare function cellGridHooks({ cell, origin, key, }?: CellGridOptions): CellGridHooks;
|
|
45
46
|
|
|
@@ -476,11 +477,25 @@ interface ContentLevel {
|
|
|
476
477
|
/** `lv_<n>` when minted by the engine; any non-empty string is tolerated from disk. */
|
|
477
478
|
id: string;
|
|
478
479
|
name: string;
|
|
479
|
-
/** Names an entry in `ContentDocument.groups`. */
|
|
480
|
+
/** Names an entry in `ContentDocument.groups`. Absent only on a level a file had before every level had to be in a group; the engine never makes one (PLA-1849). */
|
|
480
481
|
group?: string;
|
|
481
482
|
owner: ContentOwner;
|
|
482
483
|
/** Opaque to the engine: a plain JSON object or array. */
|
|
483
484
|
payload: Record<string, unknown> | unknown[];
|
|
485
|
+
/**
|
|
486
|
+
* Present while the game's `acceptPayload` refuses this level's payload:
|
|
487
|
+
* the verdict taken right after the engine's last edit of it. Always last.
|
|
488
|
+
*/
|
|
489
|
+
refusal?: LevelRefusal;
|
|
490
|
+
}
|
|
491
|
+
/**
|
|
492
|
+
* A level `acceptPayload` refused after an edit (PLA-1842). The edit stands;
|
|
493
|
+
* the mark says the level is not playable as it is. `reason` is the game's,
|
|
494
|
+
* one line of at most 200 UTF-16 code units, absent when it gave none.
|
|
495
|
+
* Runtime 1.4.5 or newer.
|
|
496
|
+
*/
|
|
497
|
+
interface LevelRefusal {
|
|
498
|
+
reason?: string;
|
|
484
499
|
}
|
|
485
500
|
interface ContentDocument {
|
|
486
501
|
version: 1;
|
|
@@ -502,6 +517,13 @@ interface ContentFieldSpec {
|
|
|
502
517
|
options?: string[];
|
|
503
518
|
/** Informational only — never substituted for a missing payload key. */
|
|
504
519
|
default?: number | string | boolean;
|
|
520
|
+
/**
|
|
521
|
+
* `text` only: a `def:` id with a drawable `layout.json` entry. The SDK
|
|
522
|
+
* writes the active level's value of this field into every element marked
|
|
523
|
+
* with that id. On `name` the value is `level.name`, and the spec is not
|
|
524
|
+
* listed in `catalog.content.fields`.
|
|
525
|
+
*/
|
|
526
|
+
layout?: string;
|
|
505
527
|
}
|
|
506
528
|
type ContentFieldValue = string | number | boolean | null;
|
|
507
529
|
/**
|
|
@@ -534,6 +556,27 @@ interface LevelPreview {
|
|
|
534
556
|
rows: number;
|
|
535
557
|
cells: LevelPreviewCell[];
|
|
536
558
|
}
|
|
559
|
+
/** The two layers a placed instance can be on; two of one layer never share a cell. */
|
|
560
|
+
type BoardLayer = 'floor' | 'object';
|
|
561
|
+
/**
|
|
562
|
+
* One placed instance of a level on a board the runtime owns (a game whose
|
|
563
|
+
* `describeScene()` returns a `grid` with `cols` / `rows` and writes fewer
|
|
564
|
+
* than the three placement hooks — a hook the game wrote keeps its verb, and
|
|
565
|
+
* the runtime supplies the rest): `payload.instances[]`. `x` / `y` are the
|
|
566
|
+
* top-left cell; `w` / `h` are written only when they differ from the
|
|
567
|
+
* definition's `footprint`. Every other field is the game's and passes
|
|
568
|
+
* through every mutation untouched.
|
|
569
|
+
*/
|
|
570
|
+
interface BoardInstance {
|
|
571
|
+
/** Minted by the runtime (`i_<n>`, unique in the level, never from its position), or whatever the file holds. */
|
|
572
|
+
id: string;
|
|
573
|
+
defId: string;
|
|
574
|
+
x: number;
|
|
575
|
+
y: number;
|
|
576
|
+
w?: number;
|
|
577
|
+
h?: number;
|
|
578
|
+
[field: string]: unknown;
|
|
579
|
+
}
|
|
537
580
|
/** A uniform placement grid over `[x, y, x+w, y+h]`, in game CSS px. */
|
|
538
581
|
interface SceneGrid {
|
|
539
582
|
x: number;
|
|
@@ -543,6 +586,13 @@ interface SceneGrid {
|
|
|
543
586
|
cols: number;
|
|
544
587
|
rows: number;
|
|
545
588
|
}
|
|
589
|
+
/**
|
|
590
|
+
* Why the runtime's own board refused `place` / `content-move-instance` /
|
|
591
|
+
* `content-remove-instance`: a cell already held by an instance of the same
|
|
592
|
+
* layer, a second instance of a `singleton` definition, or the last instance
|
|
593
|
+
* of a `required` one. A refusal for any other reason carries none.
|
|
594
|
+
*/
|
|
595
|
+
type ContentRefusalCause = 'occupied' | 'singleton' | 'required';
|
|
546
596
|
/** The level the game reports as current; placement targets its `id`. */
|
|
547
597
|
interface StateLevel {
|
|
548
598
|
id: string;
|
|
@@ -566,6 +616,13 @@ interface CatalogEntryBase {
|
|
|
566
616
|
nodeKinds: string[];
|
|
567
617
|
/** Basename only. */
|
|
568
618
|
sprite?: string;
|
|
619
|
+
/**
|
|
620
|
+
* The `assets.json` key `sprite` was resolved through — set only when the
|
|
621
|
+
* builder's `sprite` option named a key, never for a file name. It may name
|
|
622
|
+
* a key `catalog.assets` does not list (a legacy video); fall back to
|
|
623
|
+
* `sprite` then.
|
|
624
|
+
*/
|
|
625
|
+
assetId?: string;
|
|
569
626
|
singleton: boolean;
|
|
570
627
|
}
|
|
571
628
|
interface CatalogLevel extends CatalogEntryBase {
|
|
@@ -577,6 +634,8 @@ interface CatalogLevel extends CatalogEntryBase {
|
|
|
577
634
|
contentId?: string;
|
|
578
635
|
/** `{ name, group, ...declared }`, engine-attached by `contentId` lookup; never from `catalog()`. */
|
|
579
636
|
fields?: Record<string, ContentFieldValue>;
|
|
637
|
+
/** The document level's mark (PLA-1842), engine-attached by `contentId` lookup; never from `catalog()`. */
|
|
638
|
+
refusal?: LevelRefusal;
|
|
580
639
|
preview?: LevelPreview;
|
|
581
640
|
}
|
|
582
641
|
type CatalogScreen = CatalogEntryBase;
|
|
@@ -590,12 +649,35 @@ interface CatalogDefinition extends CatalogEntryBase {
|
|
|
590
649
|
layout?: LayoutRoleMap;
|
|
591
650
|
/** Drag/drop into a level writes a durable instance through `content.hooks.placeInLevel`. */
|
|
592
651
|
placeable?: 'content';
|
|
652
|
+
/**
|
|
653
|
+
* The cells a placed instance covers, `[w, h]`, positive integers. On the
|
|
654
|
+
* wire it is present on every `placeable: "content"` definition, resolved
|
|
655
|
+
* to `[1, 1]` when undeclared, and absent on every other.
|
|
656
|
+
*/
|
|
657
|
+
footprint?: [number, number];
|
|
658
|
+
/**
|
|
659
|
+
* Which instances a placed instance may share cells with: two instances of
|
|
660
|
+
* one layer never overlap, an `object` may sit on a `floor`. Present on the
|
|
661
|
+
* wire for every placeable definition (`"object"` when undeclared).
|
|
662
|
+
*/
|
|
663
|
+
layer?: BoardLayer;
|
|
664
|
+
/** Whether the Creator may resize an instance's footprint. Present on the wire for every placeable definition (`false` when undeclared). */
|
|
665
|
+
resizable?: boolean;
|
|
666
|
+
/** A level keeps at least one instance of this definition: removing the last refuses. Present on the wire for every placeable definition (`false` when undeclared). */
|
|
667
|
+
required?: boolean;
|
|
593
668
|
/**
|
|
594
669
|
* Buttons the Creator shows on this definition's card. On the wire every item
|
|
595
670
|
* is checked and the array is never empty; the value `definition()` returns
|
|
596
671
|
* is the author's array, unchecked.
|
|
597
672
|
*/
|
|
598
673
|
actions?: CatalogEntryAction[];
|
|
674
|
+
/**
|
|
675
|
+
* The catalog screen this definition is drawn on: the one whose id its
|
|
676
|
+
* `def:screen-<screen id>-…` id continues, the longest such
|
|
677
|
+
* (`def:screen-<screen id>` itself included), or `null`. The runtime stamps
|
|
678
|
+
* it on every definition it sends, replacing any value the game gave.
|
|
679
|
+
*/
|
|
680
|
+
screen?: string | null;
|
|
599
681
|
}
|
|
600
682
|
/**
|
|
601
683
|
* A button the Creator shows on a definition's card that fires a game
|
|
@@ -630,12 +712,146 @@ interface SceneNode {
|
|
|
630
712
|
instance: Record<string, unknown>;
|
|
631
713
|
/** Top level only. Marks a placed content instance; equals the instance id the placement hooks returned. */
|
|
632
714
|
contentId?: string;
|
|
715
|
+
/**
|
|
716
|
+
* SDK-stamped on an interface node the runtime derived from an element
|
|
717
|
+
* carrying `data-layout-instance`: the attribute's trimmed value, usually
|
|
718
|
+
* the content id of what the element shows, the node's id then being
|
|
719
|
+
* `<key>@<value>` (`def:hud-card@lv_3` carries `lv_3`). A game-supplied one
|
|
720
|
+
* is ignored. Never `contentId`, which marks a placed level piece.
|
|
721
|
+
*/
|
|
722
|
+
instanceKey?: string;
|
|
723
|
+
/**
|
|
724
|
+
* SDK-stamped on a node whose definition a level field is bound to: spread
|
|
725
|
+
* it into `content-set-field { ...levelField, value }`. A game-supplied one
|
|
726
|
+
* is ignored.
|
|
727
|
+
*/
|
|
728
|
+
levelField?: {
|
|
729
|
+
id: string;
|
|
730
|
+
field: string;
|
|
731
|
+
};
|
|
732
|
+
/**
|
|
733
|
+
* SDK-stamped on a node whose definition declares a `text` layout role, or
|
|
734
|
+
* has a level field bound to it, when the runtime could read the copy: how
|
|
735
|
+
* it is set on the page now. A game-supplied one is ignored. It needs a
|
|
736
|
+
* runtime with the scene text stamp.
|
|
737
|
+
*/
|
|
738
|
+
text?: TextStyleStamp;
|
|
739
|
+
}
|
|
740
|
+
/**
|
|
741
|
+
* The type of the copy a scene node's element holds, read from the live DOM
|
|
742
|
+
* when the `scene` is sent. Every length is in game CSS px: the computed
|
|
743
|
+
* values untransformed, `box` in the space of the node's `rect`, so a host
|
|
744
|
+
* turns the first into rendered px with `scale`. None is sent for a holder that
|
|
745
|
+
* is rotated or skewed. Not carried, though each can move a line break:
|
|
746
|
+
* `text-wrap-style` (`balance`, `pretty`), `word-break`, `overflow-wrap`,
|
|
747
|
+
* `hyphens` and `font-variation-settings`; where the game sets one, a host that
|
|
748
|
+
* lays the copy out greedily can break lines elsewhere.
|
|
749
|
+
*/
|
|
750
|
+
interface TextStyleStamp {
|
|
751
|
+
/** The computed `font-family`, verbatim: the game's own stack. */
|
|
752
|
+
fontFamily: string;
|
|
753
|
+
/**
|
|
754
|
+
* The first family of `fontFamily` the game document can actually render, as
|
|
755
|
+
* one CSS family token: a generic keyword (`system-ui`), a plain name
|
|
756
|
+
* (`PlayablProbe`) or a name in double quotes (`"Bree Serif"`). A host that
|
|
757
|
+
* has a face the game lacks, its own Inter, sets copy in this family so it
|
|
758
|
+
* wraps as the game's does. A family counts when this copy's characters are
|
|
759
|
+
* set differently in front of the stack after it than by that stack alone,
|
|
760
|
+
* in advance or in the shape of the glyphs, a web face as well as an
|
|
761
|
+
* installed one: an installed Arabic family with no Latin letters is named
|
|
762
|
+
* for Arabic copy, and skipped for Latin letters, though not for a space or
|
|
763
|
+
* digit it holds, which the game draws in the first family that has them.
|
|
764
|
+
* One that sets the copy as wide as the next family but draws other glyphs
|
|
765
|
+
* (a CJK face against a serif) is named, not the one after it, and a web
|
|
766
|
+
* face the game has not used, or whose unicode-range leaves the copy out, is
|
|
767
|
+
* skipped. One token cannot say that copy in two scripts is drawn in two
|
|
768
|
+
* families, and names the first. Absent when no family of the stack
|
|
769
|
+
* resolves, or a face of one that this copy needs (its weight, its style,
|
|
770
|
+
* the slice its characters fall in) is still loading; use `fontFamily` then.
|
|
771
|
+
*/
|
|
772
|
+
renderedFamily?: string;
|
|
773
|
+
fontWeight: string;
|
|
774
|
+
fontStyle: string;
|
|
775
|
+
fontSizePx: number;
|
|
776
|
+
/**
|
|
777
|
+
* The line pitch: the computed `line-height` when it is a px length, else
|
|
778
|
+
* measured from the lines themselves (never from the holder's box, which can
|
|
779
|
+
* be taller than its copy).
|
|
780
|
+
*/
|
|
781
|
+
lineHeightPx: number;
|
|
782
|
+
/** 0 when the computed value is `normal`, or a percentage the engine leaves unresolved. */
|
|
783
|
+
letterSpacingPx: number;
|
|
784
|
+
/** 0 when the computed value is `normal`, or a percentage the engine leaves unresolved. */
|
|
785
|
+
wordSpacingPx: number;
|
|
786
|
+
/**
|
|
787
|
+
* The computed `text-indent` of the block container the copy sits in, when it
|
|
788
|
+
* is a px length, else 0. An inline holder that shares its lines with other
|
|
789
|
+
* content carries 0: the indent acts on the block's first line, and the
|
|
790
|
+
* holder's place along it is already in `box.x`.
|
|
791
|
+
*/
|
|
792
|
+
textIndentPx: number;
|
|
793
|
+
/** The computed `font-stretch`, verbatim. */
|
|
794
|
+
fontStretch: string;
|
|
795
|
+
/** The computed `font-kerning`, verbatim. */
|
|
796
|
+
fontKerning: string;
|
|
797
|
+
/** The computed `font-variant`, verbatim. */
|
|
798
|
+
fontVariant: string;
|
|
799
|
+
/** The computed `font-feature-settings`, verbatim: `normal` when there are none. */
|
|
800
|
+
fontFeatureSettings: string;
|
|
801
|
+
textTransform: string;
|
|
802
|
+
/**
|
|
803
|
+
* The computed `text-align` of the block container the copy sits in: for an
|
|
804
|
+
* inline holder, its block's, since the property acts on block containers.
|
|
805
|
+
*/
|
|
806
|
+
textAlign: string;
|
|
807
|
+
direction: 'ltr' | 'rtl';
|
|
808
|
+
whiteSpace: string;
|
|
809
|
+
/** Line boxes the copy occupies now, at least 1. */
|
|
810
|
+
lines: number;
|
|
811
|
+
/**
|
|
812
|
+
* Whether copy typed here breaks onto a new line at `box.w` as it grows: the
|
|
813
|
+
* holder's `white-space` allows wrapping, and the copy either already
|
|
814
|
+
* occupies two lines or the box `box.x` and `box.w` come from has a width
|
|
815
|
+
* that does not follow its copy. That is a block-level box in flow, not
|
|
816
|
+
* floated and not a flex or grid item (past any `display: contents`
|
|
817
|
+
* wrapper), and, whatever its display and position, one measured wider than
|
|
818
|
+
* its one line of copy by more than 1px: an absolutely positioned box with a
|
|
819
|
+
* width, a stretched flex or grid item, a flex item that grows to its row. A
|
|
820
|
+
* box held as wide as its `min-width`, or one that shares its line with other
|
|
821
|
+
* content, is not counted. An inline-block, a float, an absolutely positioned
|
|
822
|
+
* box and a flex or grid item that sizes to its copy are as wide as it. A
|
|
823
|
+
* field that wraps only at `lines >= 2` scrolls sideways while a one-line
|
|
824
|
+
* title is typed.
|
|
825
|
+
*/
|
|
826
|
+
wraps: boolean;
|
|
827
|
+
/**
|
|
828
|
+
* Where the copy sits, as `rect` is measured. `x` and `w` are the content
|
|
829
|
+
* box (border box less border and padding) of the holder, which wraps the
|
|
830
|
+
* copy; when the holder is `display: inline`, whose own box is the union of
|
|
831
|
+
* its line fragments, or `contents`, which has none, they are the content box
|
|
832
|
+
* of the nearest ancestor that is neither, the block its lines sit in, but
|
|
833
|
+
* only when the holder's words are all that is in those lines. Sharing them
|
|
834
|
+
* (words, an icon or image, `::before` or `::after` content), the copy starts
|
|
835
|
+
* partway along the line, so they are the span of the holder's own words.
|
|
836
|
+
* `y` and `h` are the copy's own line boxes, `lines` times `lineHeightPx`,
|
|
837
|
+
* even where the holder's box is taller than its copy or, for an inline
|
|
838
|
+
* holder, shorter than its line. `w` and `h` are at least 2: the runtime
|
|
839
|
+
* sends no stamp for a smaller box.
|
|
840
|
+
*/
|
|
841
|
+
box: SceneRect;
|
|
842
|
+
/**
|
|
843
|
+
* Rendered size over layout size of the holder: 1 untransformed. Read on both
|
|
844
|
+
* sides; no stamp is sent when they disagree (a rotation or skew).
|
|
845
|
+
*/
|
|
846
|
+
scale: number;
|
|
633
847
|
}
|
|
634
848
|
interface CatalogEntryOptions {
|
|
635
849
|
tweakKeys?: string[];
|
|
636
850
|
nodeKinds?: string[];
|
|
637
851
|
/**
|
|
638
|
-
* An `assets.json` key
|
|
852
|
+
* An `assets.json` key, resolved to a basename through the merged mapping
|
|
853
|
+
* and recorded as the entry's `assetId`; or a bare image file name, which
|
|
854
|
+
* gets no `assetId`. A value that is neither is dropped with a warning.
|
|
639
855
|
* `| undefined` on purpose: authors write `sprite: spriteFor('KEY')`, and
|
|
640
856
|
* `spriteFor` returns `undefined` for an unknown key — under
|
|
641
857
|
* `exactOptionalPropertyTypes` that would otherwise be a type error.
|
|
@@ -657,10 +873,19 @@ interface CatalogDefinitionOptions extends CatalogEntryOptions {
|
|
|
657
873
|
* here. Ignored without `sprite`; a path (`/` or `\`) is dropped with a warning.
|
|
658
874
|
*/
|
|
659
875
|
spriteFrame?: string | undefined;
|
|
876
|
+
/** Defaults to `false` for a `placeable: 'content'` definition and `true` for any other. */
|
|
660
877
|
singleton?: boolean;
|
|
661
878
|
category?: CatalogCategory;
|
|
662
879
|
layout?: LayoutRoleMap;
|
|
663
880
|
placeable?: 'content';
|
|
881
|
+
/** Cells a placed instance covers; `[1, 1]` when omitted. Read only with `placeable: 'content'`. */
|
|
882
|
+
footprint?: [number, number] | undefined;
|
|
883
|
+
/** `'object'` when omitted. Read only with `placeable: 'content'`. */
|
|
884
|
+
layer?: BoardLayer | undefined;
|
|
885
|
+
/** `false` when omitted. Read only with `placeable: 'content'`. */
|
|
886
|
+
resizable?: boolean | undefined;
|
|
887
|
+
/** `false` when omitted. Read only with `placeable: 'content'`. */
|
|
888
|
+
required?: boolean | undefined;
|
|
664
889
|
/**
|
|
665
890
|
* Buttons the Creator shows on this definition's card — for an `effects`
|
|
666
891
|
* definition, `[{ kind: 'preview', command: 'preview-splash' }]`. A malformed
|
|
@@ -736,12 +961,32 @@ interface ContentHooks {
|
|
|
736
961
|
/**
|
|
737
962
|
* Required for `content-set-payload` — the verb is advertised only when this
|
|
738
963
|
* exists (D19), because the engine cannot judge a game's payload shape.
|
|
739
|
-
* Runs against a clone of the proposed payload: `false` refuses;
|
|
740
|
-
* may normalize the clone in
|
|
964
|
+
* Runs against a clone of the proposed payload: `false` refuses; a
|
|
965
|
+
* `PayloadRefusal` refuses and says why; the hook may normalize the clone in
|
|
966
|
+
* place; anything else accepts. A refusal's `reason`, or the message the hook
|
|
967
|
+
* threw, becomes the verb's `command-refused.reason`.
|
|
968
|
+
*
|
|
969
|
+
* It also judges every payload an accepted edit produces, and every level on
|
|
970
|
+
* intake (PLA-1842; runtime 1.4.5 or newer): a refusal there never refuses
|
|
971
|
+
* the edit, it marks the level `refusal`. That clone is discarded, so a hook
|
|
972
|
+
* that has to change it to accept it marks the level too, without a reason.
|
|
741
973
|
*/
|
|
742
974
|
acceptPayload?(payload: unknown, meta: {
|
|
743
975
|
id: string;
|
|
744
|
-
}): boolean | void;
|
|
976
|
+
}): boolean | void | PayloadRefusal;
|
|
977
|
+
}
|
|
978
|
+
/**
|
|
979
|
+
* `acceptPayload`'s refusal with a reason: exactly `accept: false` and an
|
|
980
|
+
* optional string `reason`, as own data properties, in a new object (never
|
|
981
|
+
* the payload clone the hook was handed). Any other key makes it an ordinary
|
|
982
|
+
* return, which accepts. The reason is sent as one line of at most 200 UTF-16
|
|
983
|
+
* code units (control characters become spaces; longer text is cut with `…`);
|
|
984
|
+
* a `reason` that is not a string is ignored and reported. Runtime 1.4.3 or
|
|
985
|
+
* newer: an older runtime accepts the payload.
|
|
986
|
+
*/
|
|
987
|
+
interface PayloadRefusal {
|
|
988
|
+
accept: false;
|
|
989
|
+
reason?: string;
|
|
745
990
|
}
|
|
746
991
|
/** `content: { document, hooks, fields }` on `devtools.js` — opt-in. */
|
|
747
992
|
interface DevtoolsContent {
|
|
@@ -769,8 +1014,20 @@ interface DevtoolsVocabulary {
|
|
|
769
1014
|
definitions?: CatalogDefinition[];
|
|
770
1015
|
progression?: CatalogProgression;
|
|
771
1016
|
};
|
|
1017
|
+
/**
|
|
1018
|
+
* What the runtime cannot see from the page: the `grid` and the objects drawn
|
|
1019
|
+
* on a canvas. Every element marked `data-layout` whose `layout.json` entry is
|
|
1020
|
+
* drawn on the page and names a catalog definition is derived by the runtime,
|
|
1021
|
+
* which owns its identity and rect: a node listed here for one leaves the
|
|
1022
|
+
* scene and contributes at most its `instance`. Optional for a game with such
|
|
1023
|
+
* an entry, which gets a scene of its interface without it. A runtime of
|
|
1024
|
+
* 1.4.8 or older derives nothing and reports only the nodes listed here.
|
|
1025
|
+
* `nodes` is optional for a game whose pieces the runtime's board places
|
|
1026
|
+
* (runtime 1.6.0+): `{ grid }` alone, with a well-formed grid, lists the
|
|
1027
|
+
* active level's instances; a malformed grid alone keeps the previous scene.
|
|
1028
|
+
*/
|
|
772
1029
|
describeScene?(): {
|
|
773
|
-
nodes
|
|
1030
|
+
nodes?: SceneNode[];
|
|
774
1031
|
grid?: SceneGrid;
|
|
775
1032
|
};
|
|
776
1033
|
describeInstance?(nodeId: string): Record<string, unknown> | null | undefined;
|
|
@@ -822,7 +1079,8 @@ type RuntimeLoader = () => Promise<PlayablSDK>;
|
|
|
822
1079
|
/**
|
|
823
1080
|
* Override runtime resolution. `runtimeUrl` imports a specific runtime build
|
|
824
1081
|
* directly; `manifestUrl` points at a specific manifest. Both bypass the
|
|
825
|
-
* automatic environment detection
|
|
1082
|
+
* automatic environment detection and `window.__PLAYABL_MANIFEST_URL__` —
|
|
1083
|
+
* useful for QA or self-hosting.
|
|
826
1084
|
*/
|
|
827
1085
|
declare function configure(options: {
|
|
828
1086
|
runtimeUrl?: string;
|
|
@@ -835,4 +1093,4 @@ declare const __testing: {
|
|
|
835
1093
|
setRuntimeLoader(loader: RuntimeLoader): void;
|
|
836
1094
|
};
|
|
837
1095
|
|
|
838
|
-
export { type AssetDescriptor, type AssetEntry, type AssetKind, type AssetOverride, type AssetRecipe, type AssetStatus, type AssetType, type AssetValueEntry, type AssetsMapping, type AssetsRegisterOptions, type AssetsUrlMap, type AssetsValues, type BooleanTweak, type CameraAPI, type CameraOptions, type CameraResult, type CatalogCategory, type CatalogContext, type CatalogDefinition, type CatalogDefinitionOptions, type CatalogEntryAction, type CatalogEntryBase, type CatalogEntryOptions, type CatalogLevel, type CatalogLevelOptions, type CatalogProgression, type CatalogScreen, type CellGridEntry, type CellGridHooks, type CellGridOptions, type ColorTweak, type ContentDocument, type ContentFieldSpec, type ContentFieldType, type ContentFieldValue, type ContentGroup, type ContentHandle, type ContentHooks, type ContentLevel, type ContentOwner, type ContentVerbType, type DevtoolsCommand, type DevtoolsContent, type DevtoolsHandle, type DevtoolsVocabulary, type EnumTweak, type ErrorCode, type FileSystemAPI, type FileSystemOptions, type FileSystemResult, type GameLoopHooks, type GameMode, type GameRunHandle, type GameRunOptions, type GeolocationAPI, type GeolocationOptions, type GeolocationResult, type HapticsAPI, type LayoutEntry, type LayoutFile, type LayoutRole, type LayoutRoleMap, type LayoutValues, type LevelPreview, type LevelPreviewCell, type MicrophoneAPI, type MicrophoneRecordOptions, type MicrophoneResult, type MicrophoneStreamOptions, type MotionAttitude, type MotionData, type MotionRotation, type MotionVector, type NormalizedAssetEntry, type NumberTweak, type OrientationData, type PlayablAssets, type PlayablAudio, type PlayablAudioAutoPauseOptions, type PlayablAudioContext, type PlayablAudioOptions, type PlayablDevice, type PlayablDevtools, PlayablError, type PlayablGame, type PlayablSDK, type PlayablTweaks, type ProgressionNoun, type ProgressionShape, type ReadyResult, type SaveResult, type SceneGrid, type SceneNode, type SceneRect, type SensorsAPI, type StateLevel, type SubmitResult, type TextTweak, type TweakAppliesOn, type TweakSchema, type TweakSchemaItem, type TweakType, type TweakValue, type TweakValueIssue, type TweakValueRejection, type TweakValues, type TweaksInitOptions, __testing, cellGridHooks, configure, sdk as default };
|
|
1096
|
+
export { type AssetDescriptor, type AssetEntry, type AssetKind, type AssetOverride, type AssetRecipe, type AssetStatus, type AssetType, type AssetValueEntry, type AssetsMapping, type AssetsRegisterOptions, type AssetsUrlMap, type AssetsValues, type BoardInstance, type BoardLayer, type BooleanTweak, type CameraAPI, type CameraOptions, type CameraResult, type CatalogCategory, type CatalogContext, type CatalogDefinition, type CatalogDefinitionOptions, type CatalogEntryAction, type CatalogEntryBase, type CatalogEntryOptions, type CatalogLevel, type CatalogLevelOptions, type CatalogProgression, type CatalogScreen, type CellGridEntry, type CellGridHooks, type CellGridOptions, type ColorTweak, type ContentDocument, type ContentFieldSpec, type ContentFieldType, type ContentFieldValue, type ContentGroup, type ContentHandle, type ContentHooks, type ContentLevel, type ContentOwner, type ContentRefusalCause, type ContentVerbType, type DevtoolsCommand, type DevtoolsContent, type DevtoolsHandle, type DevtoolsVocabulary, type EnumTweak, type ErrorCode, type FileSystemAPI, type FileSystemOptions, type FileSystemResult, type GameLoopHooks, type GameMode, type GameRunHandle, type GameRunOptions, type GeolocationAPI, type GeolocationOptions, type GeolocationResult, type HapticsAPI, type LayoutEntry, type LayoutFile, type LayoutRole, type LayoutRoleMap, type LayoutValues, type LevelPreview, type LevelPreviewCell, type LevelRefusal, type MicrophoneAPI, type MicrophoneRecordOptions, type MicrophoneResult, type MicrophoneStreamOptions, type MotionAttitude, type MotionData, type MotionRotation, type MotionVector, type NormalizedAssetEntry, type NumberTweak, type OrientationData, type PayloadRefusal, type PlayablAssets, type PlayablAudio, type PlayablAudioAutoPauseOptions, type PlayablAudioContext, type PlayablAudioOptions, type PlayablDevice, type PlayablDevtools, PlayablError, type PlayablGame, type PlayablSDK, type PlayablTweaks, type ProgressionNoun, type ProgressionShape, type ReadyResult, type SaveResult, type SceneGrid, type SceneNode, type SceneRect, type SensorsAPI, type StateLevel, type SubmitResult, type TextStyleStamp, type TextTweak, type TweakAppliesOn, type TweakSchema, type TweakSchemaItem, type TweakType, type TweakValue, type TweakValueIssue, type TweakValueRejection, type TweakValues, type TweaksInitOptions, __testing, cellGridHooks, configure, sdk as default };
|
package/dist/index.js
CHANGED
|
@@ -3,13 +3,20 @@ var LOG_PREFIX = "[playabl/sdk]";
|
|
|
3
3
|
var BASE_DOMAIN = "playabl.ai";
|
|
4
4
|
var MANIFEST_PATH = "/Runtime-Script/sdk/v1/version.json";
|
|
5
5
|
var ENV_HOST_RE = /\.(dev|staging)\.playabl\.ai$/;
|
|
6
|
-
var
|
|
6
|
+
var CDN_HOSTS = /* @__PURE__ */ new Set([
|
|
7
|
+
"cdn.playabl.ai",
|
|
8
|
+
"cdn-staging.playabl.ai",
|
|
9
|
+
"cdn-dev.playabl.ai"
|
|
10
|
+
]);
|
|
11
|
+
var FALLBACK_RUNTIME_URL = "https://cdn.playabl.ai/Runtime-Script/sdk/v1/runtime.js?v=sdk-1.1.0";
|
|
7
12
|
function isEnv(value) {
|
|
8
13
|
return value === "local" || value === "dev" || value === "staging" || value === "prod";
|
|
9
14
|
}
|
|
10
|
-
function
|
|
15
|
+
function forcedEnv(search = typeof window !== "undefined" ? window.location.search : "") {
|
|
11
16
|
const forced = new URLSearchParams(search).get("env");
|
|
12
|
-
|
|
17
|
+
return isEnv(forced) ? forced : null;
|
|
18
|
+
}
|
|
19
|
+
function envFromHostname(hostname = typeof window !== "undefined" ? window.location.hostname : "") {
|
|
13
20
|
if (hostname === "localhost" || hostname === "127.0.0.1") return "local";
|
|
14
21
|
const match = hostname.match(ENV_HOST_RE);
|
|
15
22
|
return match ? match[1] : "prod";
|
|
@@ -18,11 +25,52 @@ function manifestUrlForEnv(env) {
|
|
|
18
25
|
const cdnHost = env === "prod" ? "cdn" : `cdn-${env}`;
|
|
19
26
|
return `https://${cdnHost}.${BASE_DOMAIN}${MANIFEST_PATH}`;
|
|
20
27
|
}
|
|
28
|
+
function isPlayablCdnUrl(value) {
|
|
29
|
+
let parsed;
|
|
30
|
+
try {
|
|
31
|
+
parsed = new URL(value);
|
|
32
|
+
} catch {
|
|
33
|
+
return false;
|
|
34
|
+
}
|
|
35
|
+
return parsed.protocol === "https:" && parsed.port === "" && CDN_HOSTS.has(parsed.hostname);
|
|
36
|
+
}
|
|
37
|
+
function describe(value) {
|
|
38
|
+
try {
|
|
39
|
+
return typeof value === "string" ? JSON.stringify(value) : `(${typeof value}) ${String(value)}`;
|
|
40
|
+
} catch {
|
|
41
|
+
return `(${typeof value}) (unprintable)`;
|
|
42
|
+
}
|
|
43
|
+
}
|
|
44
|
+
function injectedManifestUrl(source = typeof window !== "undefined" ? window : void 0) {
|
|
45
|
+
if (source === void 0) return void 0;
|
|
46
|
+
let value;
|
|
47
|
+
try {
|
|
48
|
+
value = source.__PLAYABL_MANIFEST_URL__;
|
|
49
|
+
} catch (error) {
|
|
50
|
+
console.warn(`${LOG_PREFIX} could not read window.__PLAYABL_MANIFEST_URL__; ignoring it`, error);
|
|
51
|
+
return void 0;
|
|
52
|
+
}
|
|
53
|
+
if (value === void 0) return void 0;
|
|
54
|
+
if (typeof value === "string" && isPlayablCdnUrl(value)) return value;
|
|
55
|
+
console.warn(
|
|
56
|
+
`${LOG_PREFIX} ignoring window.__PLAYABL_MANIFEST_URL__ ${describe(value)}: not an https URL on cdn.playabl.ai, cdn-staging.playabl.ai or cdn-dev.playabl.ai`
|
|
57
|
+
);
|
|
58
|
+
return void 0;
|
|
59
|
+
}
|
|
21
60
|
async function resolveRuntimeUrl(options = {}) {
|
|
22
61
|
if (options.runtimeUrl) return options.runtimeUrl;
|
|
23
|
-
|
|
24
|
-
if (!
|
|
25
|
-
|
|
62
|
+
let manifestUrl = options.manifestUrl;
|
|
63
|
+
if (!manifestUrl) {
|
|
64
|
+
const forced = forcedEnv();
|
|
65
|
+
const injected = forced === null ? injectedManifestUrl() : void 0;
|
|
66
|
+
if (injected) {
|
|
67
|
+
manifestUrl = injected;
|
|
68
|
+
} else {
|
|
69
|
+
const env = forced ?? envFromHostname();
|
|
70
|
+
if (env === "local") return FALLBACK_RUNTIME_URL;
|
|
71
|
+
manifestUrl = options.manifestUrl ?? manifestUrlForEnv(env);
|
|
72
|
+
}
|
|
73
|
+
}
|
|
26
74
|
try {
|
|
27
75
|
const response = await fetch(manifestUrl, { cache: "no-store" });
|
|
28
76
|
if (!response.ok) throw new Error(`manifest HTTP ${response.status}`);
|
package/package.json
CHANGED
|
@@ -1,12 +1,9 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@playabl/sdk",
|
|
3
|
-
"version": "1.1.0
|
|
3
|
+
"version": "1.1.0",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"main": "./dist/index.js",
|
|
6
6
|
"types": "./dist/index.d.ts",
|
|
7
|
-
"publishConfig": {
|
|
8
|
-
"tag": "beta"
|
|
9
|
-
},
|
|
10
7
|
"files": [
|
|
11
8
|
"dist/index.js",
|
|
12
9
|
"dist/index.d.ts",
|