@playabl/sdk 0.2.0 → 1.0.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 +188 -186
- package/dist/index.d.ts +456 -10
- package/dist/index.js +127 -6
- package/package.json +35 -32
package/README.md
CHANGED
|
@@ -1,186 +1,188 @@
|
|
|
1
|
-
# @playabl/sdk
|
|
2
|
-
|
|
3
|
-
Browser SDK for Playabl games providing parent-platform communication, game state persistence, device APIs, live tweaks, asset replacement, and iOS-friendly audio helpers.
|
|
4
|
-
|
|
5
|
-
## Installation
|
|
6
|
-
|
|
7
|
-
```bash
|
|
8
|
-
npm install @playabl/sdk
|
|
9
|
-
```
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
sdk.device.camera.
|
|
64
|
-
}
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
const
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
oscillator.
|
|
171
|
-
oscillator.
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
- `sdk.
|
|
181
|
-
- `sdk.
|
|
182
|
-
- `sdk.
|
|
183
|
-
- `sdk.
|
|
184
|
-
- `sdk.
|
|
185
|
-
|
|
186
|
-
|
|
1
|
+
# @playabl/sdk
|
|
2
|
+
|
|
3
|
+
Browser SDK for Playabl games providing parent-platform communication, game state persistence, device APIs, live tweaks, asset replacement, and iOS-friendly audio helpers.
|
|
4
|
+
|
|
5
|
+
## Installation
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npm install @playabl/sdk
|
|
9
|
+
```
|
|
10
|
+
|
|
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.
|
|
12
|
+
|
|
13
|
+
## Usage
|
|
14
|
+
|
|
15
|
+
### Core
|
|
16
|
+
|
|
17
|
+
```typescript
|
|
18
|
+
import sdk from '@playabl/sdk'
|
|
19
|
+
|
|
20
|
+
const ready = await sdk.ready()
|
|
21
|
+
console.log('Connected to Playabl parent:', ready.parentOrigin)
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
### Game State and Leaderboard
|
|
25
|
+
|
|
26
|
+
```typescript
|
|
27
|
+
import sdk from '@playabl/sdk'
|
|
28
|
+
|
|
29
|
+
type SaveData = {
|
|
30
|
+
highScore: number
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
const saved = await sdk.gameState.load<SaveData>()
|
|
34
|
+
let highScore = saved?.highScore ?? 0
|
|
35
|
+
|
|
36
|
+
async function submitScore(score: number): Promise<void> {
|
|
37
|
+
if (score > highScore) {
|
|
38
|
+
highScore = score
|
|
39
|
+
|
|
40
|
+
const result = await sdk.gameState.save({ highScore })
|
|
41
|
+
if (!result.ok) {
|
|
42
|
+
console.warn('Could not save game state:', result.error?.code)
|
|
43
|
+
}
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
const submitResult = await sdk.leaderboard.submit(score)
|
|
47
|
+
console.log('Score accepted:', submitResult.accepted)
|
|
48
|
+
}
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
### Device APIs
|
|
52
|
+
|
|
53
|
+
```typescript
|
|
54
|
+
import sdk from '@playabl/sdk'
|
|
55
|
+
|
|
56
|
+
// Haptics
|
|
57
|
+
if (sdk.device.haptics.isSupported()) {
|
|
58
|
+
await sdk.device.haptics.vibrate([100, 50, 100])
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
// Camera
|
|
62
|
+
if (sdk.device.camera.isSupported()) {
|
|
63
|
+
const stream = await sdk.device.camera.getStream({ facingMode: 'environment' })
|
|
64
|
+
const photo = await sdk.device.camera.capturePhoto({ quality: 'high' })
|
|
65
|
+
sdk.device.camera.stopStream()
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
// Geolocation
|
|
69
|
+
if (sdk.device.geolocation.isSupported()) {
|
|
70
|
+
const position = await sdk.device.geolocation.getCurrentPosition()
|
|
71
|
+
const stopWatching = sdk.device.geolocation.watchPosition((pos) => {
|
|
72
|
+
console.log('Position:', pos)
|
|
73
|
+
})
|
|
74
|
+
|
|
75
|
+
stopWatching()
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
// Sensors
|
|
79
|
+
if (sdk.device.sensors.isMotionSupported()) {
|
|
80
|
+
await sdk.device.sensors.requestMotionPermission()
|
|
81
|
+
|
|
82
|
+
const stopMotion = sdk.device.sensors.watchMotion((data) => {
|
|
83
|
+
console.log('Gravity:', data.gravity)
|
|
84
|
+
})
|
|
85
|
+
|
|
86
|
+
stopMotion()
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
if (sdk.device.sensors.isOrientationSupported()) {
|
|
90
|
+
const stopOrientation = sdk.device.sensors.watchOrientation((data) => {
|
|
91
|
+
console.log('Orientation:', data)
|
|
92
|
+
})
|
|
93
|
+
|
|
94
|
+
stopOrientation()
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
// File System
|
|
98
|
+
if (sdk.device.fileSystem.isSupported()) {
|
|
99
|
+
const { files } = await sdk.device.fileSystem.openFile({
|
|
100
|
+
accept: ['image/*'],
|
|
101
|
+
multiple: true,
|
|
102
|
+
})
|
|
103
|
+
|
|
104
|
+
const text = await sdk.device.fileSystem.readAsText(files[0]!)
|
|
105
|
+
await sdk.device.fileSystem.saveFile(new Blob([text]), 'save.txt')
|
|
106
|
+
}
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
### Tweaks
|
|
110
|
+
|
|
111
|
+
```typescript
|
|
112
|
+
import sdk from '@playabl/sdk'
|
|
113
|
+
|
|
114
|
+
const tweaks = await sdk.tweaks.init({
|
|
115
|
+
speed: {
|
|
116
|
+
type: 'number',
|
|
117
|
+
value: 1,
|
|
118
|
+
min: 0.5,
|
|
119
|
+
max: 3,
|
|
120
|
+
step: 0.1,
|
|
121
|
+
name: 'Player speed',
|
|
122
|
+
},
|
|
123
|
+
debugMode: {
|
|
124
|
+
type: 'boolean',
|
|
125
|
+
value: false,
|
|
126
|
+
},
|
|
127
|
+
playerColor: {
|
|
128
|
+
type: 'color',
|
|
129
|
+
value: '#00ff88',
|
|
130
|
+
},
|
|
131
|
+
})
|
|
132
|
+
|
|
133
|
+
const speed = tweaks.get('speed')
|
|
134
|
+
|
|
135
|
+
const unsubscribe = tweaks.subscribe('speed', (value, previous) => {
|
|
136
|
+
console.log('Speed changed:', previous, value)
|
|
137
|
+
})
|
|
138
|
+
|
|
139
|
+
unsubscribe()
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
### Assets
|
|
143
|
+
|
|
144
|
+
```typescript
|
|
145
|
+
import sdk from '@playabl/sdk'
|
|
146
|
+
|
|
147
|
+
const assets = await sdk.assets.register({
|
|
148
|
+
player: '/assets/player.png',
|
|
149
|
+
jump: '/assets/jump.mp3',
|
|
150
|
+
})
|
|
151
|
+
|
|
152
|
+
const playerUrl = assets.get('player')
|
|
153
|
+
const replacedUrl = assets.getReplacedUrl('/assets/player.png')
|
|
154
|
+
|
|
155
|
+
console.log('Current asset mapping:', assets.snapshot())
|
|
156
|
+
console.log(playerUrl, replacedUrl)
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
### Audio (iOS Silent Mode Compatible)
|
|
160
|
+
|
|
161
|
+
```typescript
|
|
162
|
+
import sdk from '@playabl/sdk'
|
|
163
|
+
|
|
164
|
+
if (sdk.audio.isSupported()) {
|
|
165
|
+
const audio = await sdk.audio.getContext()
|
|
166
|
+
|
|
167
|
+
button.onclick = async () => {
|
|
168
|
+
await audio.unlock()
|
|
169
|
+
|
|
170
|
+
const oscillator = audio.context.createOscillator()
|
|
171
|
+
oscillator.connect(audio.context.destination)
|
|
172
|
+
oscillator.start()
|
|
173
|
+
oscillator.stop(audio.context.currentTime + 1)
|
|
174
|
+
}
|
|
175
|
+
}
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
## API Surface
|
|
179
|
+
|
|
180
|
+
- `sdk.ready()` - Connects to the Playabl parent iframe host.
|
|
181
|
+
- `sdk.leaderboard.submit(score)` - Sends a score to the parent platform.
|
|
182
|
+
- `sdk.gameState.save/load/clear()` - Persists JSON-serializable game state with `localStorage`.
|
|
183
|
+
- `sdk.device` - Provides haptics, camera, geolocation, sensors, and file system helpers.
|
|
184
|
+
- `sdk.tweaks.init(schema)` - Registers live-tunable values controlled by the host.
|
|
185
|
+
- `sdk.assets.register(mapping)` - Registers game assets so the host can replace them.
|
|
186
|
+
- `sdk.audio` - Creates Web Audio contexts with an iOS Safari silent-mode patch.
|
|
187
|
+
|
|
188
|
+
|
package/dist/index.d.ts
CHANGED
|
@@ -1,3 +1,48 @@
|
|
|
1
|
+
interface CellGridOptions {
|
|
2
|
+
/** Cell size in game CSS px. Default 32. */
|
|
3
|
+
cell?: number;
|
|
4
|
+
/**
|
|
5
|
+
* Grid origin in game CSS px, matching SceneGrid.x/y. Default `{ x: 0, y: 0 }`.
|
|
6
|
+
* Read on each placement/move; update these coordinates when the grid moves.
|
|
7
|
+
*/
|
|
8
|
+
origin?: {
|
|
9
|
+
x: number;
|
|
10
|
+
y: number;
|
|
11
|
+
};
|
|
12
|
+
/** The payload key holding the instance list. Default `'instances'`. */
|
|
13
|
+
key?: string;
|
|
14
|
+
}
|
|
15
|
+
interface CellGridEntry {
|
|
16
|
+
id?: string;
|
|
17
|
+
defId: string;
|
|
18
|
+
/** Cell units, not px. */
|
|
19
|
+
x: number;
|
|
20
|
+
y: number;
|
|
21
|
+
[prop: string]: unknown;
|
|
22
|
+
}
|
|
23
|
+
type CellGridHooks = Required<Pick<ContentHooks, 'blankLevel' | 'placeInLevel' | 'moveInstance' | 'removeInstance'>>;
|
|
24
|
+
/**
|
|
25
|
+
* Opt-in synthesis of the placement hooks for a uniform-grid game (levels.json
|
|
26
|
+
* — Contract §3): one thing per cell, addressed by `{ cell, origin, key }` instead of a
|
|
27
|
+
* free-form payload. The payload shape is `{ cols?, rows?, [key]: CellGridEntry[] }`
|
|
28
|
+
* with `x`/`y` in CELL units — `placeInLevel` / `moveInstance` receive game CSS
|
|
29
|
+
* px, subtract `origin`, and floor-divide by `cell`. An entry without an explicit
|
|
30
|
+
* `id` is addressed positionally as `<defId>:<col>,<row>`; every entry `placeInLevel` creates gets
|
|
31
|
+
* one. `placeInLevel` and `moveInstance` also refuse an id collision — the
|
|
32
|
+
* positional id they would assign already belongs to a different entry's
|
|
33
|
+
* explicit `id` — returning `false` instead of minting a duplicate.
|
|
34
|
+
* A missing list is created only by placement; an existing
|
|
35
|
+
* non-array list or a list with an invalid entry refuses without replacing
|
|
36
|
+
* the game's data. Entries need a non-empty defId, finite x/y, and an optional
|
|
37
|
+
* string id. Effective ids and coordinate pairs must also be unique across
|
|
38
|
+
* the list; existing duplicates refuse all three mutations. Holes and
|
|
39
|
+
* accessors in consumed data refuse too. Non-finite
|
|
40
|
+
* coordinates or origins also refuse. Pure and synchronous, as every content
|
|
41
|
+
* hook must be; nothing here needs the runtime, so a game can call it while
|
|
42
|
+
* building its vocabulary.
|
|
43
|
+
*/
|
|
44
|
+
declare function cellGridHooks({ cell, origin, key, }?: CellGridOptions): CellGridHooks;
|
|
45
|
+
|
|
1
46
|
interface ReadyResult {
|
|
2
47
|
isLocalDev: boolean;
|
|
3
48
|
parentOrigin: string | null;
|
|
@@ -10,13 +55,19 @@ interface SaveResult {
|
|
|
10
55
|
fallback: 'localStorage' | 'none';
|
|
11
56
|
error?: PlayablError;
|
|
12
57
|
}
|
|
13
|
-
type TweakType = 'number' | 'boolean' | 'text' | 'color';
|
|
58
|
+
type TweakType = 'number' | 'boolean' | 'text' | 'enum' | 'color';
|
|
14
59
|
type TweakValue = number | string | boolean;
|
|
60
|
+
type TweakValues = Record<string, TweakValue>;
|
|
61
|
+
/** When a changed value reaches the game. Enforced by the runtime, not the game. */
|
|
62
|
+
type TweakAppliesOn = 'live' | 'restart';
|
|
15
63
|
interface BaseTweak {
|
|
16
64
|
name?: string;
|
|
17
65
|
description?: string;
|
|
18
66
|
group?: string;
|
|
19
67
|
index?: number;
|
|
68
|
+
appliesOn?: TweakAppliesOn;
|
|
69
|
+
/** Creator-only rendering hints. The runtime never reads it. */
|
|
70
|
+
ui?: Record<string, unknown>;
|
|
20
71
|
}
|
|
21
72
|
interface NumberTweak extends BaseTweak {
|
|
22
73
|
type: 'number';
|
|
@@ -33,14 +84,38 @@ interface TextTweak extends BaseTweak {
|
|
|
33
84
|
type: 'text';
|
|
34
85
|
value: string;
|
|
35
86
|
}
|
|
87
|
+
interface EnumTweak extends BaseTweak {
|
|
88
|
+
type: 'enum';
|
|
89
|
+
value: string;
|
|
90
|
+
/** Non-empty, unique. The closed set of allowed values. */
|
|
91
|
+
options: string[];
|
|
92
|
+
}
|
|
36
93
|
interface ColorTweak extends BaseTweak {
|
|
37
94
|
type: 'color';
|
|
38
95
|
value: string;
|
|
39
96
|
}
|
|
40
|
-
type TweakSchemaItem = NumberTweak | BooleanTweak | TextTweak | ColorTweak;
|
|
97
|
+
type TweakSchemaItem = NumberTweak | BooleanTweak | TextTweak | EnumTweak | ColorTweak;
|
|
41
98
|
interface TweakSchema {
|
|
42
99
|
[key: string]: TweakSchemaItem;
|
|
43
100
|
}
|
|
101
|
+
/** A creator value that no longer fits its definition, classified at merge time. */
|
|
102
|
+
interface TweakValueIssue {
|
|
103
|
+
key: string;
|
|
104
|
+
/** `incompatible`: the key exists but the value fails `isValid`. `orphaned`: the key is gone. */
|
|
105
|
+
kind: 'incompatible' | 'orphaned';
|
|
106
|
+
value: unknown;
|
|
107
|
+
reason: string;
|
|
108
|
+
}
|
|
109
|
+
/** An incoming live update the runtime refused. */
|
|
110
|
+
interface TweakValueRejection {
|
|
111
|
+
key: string;
|
|
112
|
+
value: unknown;
|
|
113
|
+
reason: string;
|
|
114
|
+
}
|
|
115
|
+
interface TweaksInitOptions {
|
|
116
|
+
/** The contents of `src/tweaks.values.json`. Missing → `{}`. */
|
|
117
|
+
values?: TweakValues;
|
|
118
|
+
}
|
|
44
119
|
interface PlayablTweaks {
|
|
45
120
|
readonly values: Readonly<Record<string, TweakValue>>;
|
|
46
121
|
get(key: string): TweakValue;
|
|
@@ -50,6 +125,52 @@ interface PlayablTweaks {
|
|
|
50
125
|
}
|
|
51
126
|
type AssetType = 'image' | 'audio' | 'video' | 'unknown';
|
|
52
127
|
type AssetStatus = 'original' | 'overridden';
|
|
128
|
+
/** v1 asset kinds. `video` is reserved and rejected. */
|
|
129
|
+
type AssetKind = 'image' | 'audio';
|
|
130
|
+
interface AssetRecipe {
|
|
131
|
+
prompt?: string;
|
|
132
|
+
refs?: string[];
|
|
133
|
+
style?: string;
|
|
134
|
+
seed?: number;
|
|
135
|
+
model?: string;
|
|
136
|
+
}
|
|
137
|
+
/** One `assets.json` entry in the v1 object shape. */
|
|
138
|
+
interface AssetEntry {
|
|
139
|
+
src: string;
|
|
140
|
+
kind?: AssetKind;
|
|
141
|
+
label?: string;
|
|
142
|
+
recipe?: AssetRecipe;
|
|
143
|
+
anchor?: [number, number];
|
|
144
|
+
}
|
|
145
|
+
/** `AssetEntry` after the runtime filled in `kind` and `label`. */
|
|
146
|
+
interface NormalizedAssetEntry {
|
|
147
|
+
src: string;
|
|
148
|
+
kind: AssetKind;
|
|
149
|
+
label: string;
|
|
150
|
+
recipe?: AssetRecipe;
|
|
151
|
+
anchor?: [number, number];
|
|
152
|
+
}
|
|
153
|
+
/** `assets.json`: a legacy bare `src` string, or a v1 entry. Both accepted forever. */
|
|
154
|
+
interface AssetsMapping {
|
|
155
|
+
[key: string]: string | AssetEntry;
|
|
156
|
+
}
|
|
157
|
+
/** Effective URL per asset id — what `snapshot()` returns. */
|
|
158
|
+
interface AssetsUrlMap {
|
|
159
|
+
[key: string]: string;
|
|
160
|
+
}
|
|
161
|
+
/** One `assets.values.json` entry (Creator-owned). */
|
|
162
|
+
interface AssetValueEntry {
|
|
163
|
+
src: string;
|
|
164
|
+
history?: string[];
|
|
165
|
+
recipe?: AssetRecipe;
|
|
166
|
+
}
|
|
167
|
+
interface AssetsValues {
|
|
168
|
+
[key: string]: AssetValueEntry;
|
|
169
|
+
}
|
|
170
|
+
interface AssetsRegisterOptions {
|
|
171
|
+
/** The contents of `src/assets.values.json`. Missing → `{}`. */
|
|
172
|
+
values?: AssetsValues;
|
|
173
|
+
}
|
|
53
174
|
interface AssetDescriptor {
|
|
54
175
|
id: string;
|
|
55
176
|
url: string;
|
|
@@ -57,18 +178,17 @@ interface AssetDescriptor {
|
|
|
57
178
|
type: AssetType;
|
|
58
179
|
status: AssetStatus;
|
|
59
180
|
index: number;
|
|
181
|
+
label?: string;
|
|
182
|
+
kind?: AssetKind;
|
|
60
183
|
}
|
|
61
184
|
interface AssetOverride {
|
|
62
185
|
id: string;
|
|
63
186
|
url: string;
|
|
64
187
|
}
|
|
65
|
-
interface AssetsMapping {
|
|
66
|
-
[key: string]: string;
|
|
67
|
-
}
|
|
68
188
|
interface PlayablAssets {
|
|
69
189
|
get(key: string): string;
|
|
70
190
|
getReplacedUrl(url: string): string;
|
|
71
|
-
snapshot():
|
|
191
|
+
snapshot(): AssetsUrlMap;
|
|
72
192
|
}
|
|
73
193
|
interface CameraOptions {
|
|
74
194
|
quality?: 'low' | 'medium' | 'high';
|
|
@@ -247,6 +367,330 @@ interface PlayablAudio {
|
|
|
247
367
|
getContext(options?: PlayablAudioOptions): Promise<PlayablAudioContext>;
|
|
248
368
|
createContext(options?: PlayablAudioOptions): Promise<PlayablAudioContext>;
|
|
249
369
|
}
|
|
370
|
+
type GameMode = 'play' | 'edit';
|
|
371
|
+
/**
|
|
372
|
+
* The three functions a game hands to `sdk.game.run`. The runtime owns the
|
|
373
|
+
* clock: it calls `update` with `dt` in seconds (already scaled), then
|
|
374
|
+
* `render`, every animation frame. While frozen only `render` runs.
|
|
375
|
+
*/
|
|
376
|
+
interface GameLoopHooks<S extends object = Record<string, unknown>> {
|
|
377
|
+
/** Build or reset the run. Called once at start and again on every restart. */
|
|
378
|
+
init(state: S): void;
|
|
379
|
+
/** Advance the simulation by `dt` seconds. Never called while frozen. */
|
|
380
|
+
update(state: S, dt: number): void;
|
|
381
|
+
/** Draw from `state`. Must not mutate it. Called every frame, frozen or not. */
|
|
382
|
+
render(state: S): void;
|
|
383
|
+
}
|
|
384
|
+
interface GameRunOptions<S extends object = Record<string, unknown>> {
|
|
385
|
+
/** The state object passed to every hook. Defaults to `{}`. */
|
|
386
|
+
state?: S;
|
|
387
|
+
/**
|
|
388
|
+
* Largest unscaled frame delta, in seconds, after a tab was hidden. Default
|
|
389
|
+
* `0.1`. Must be a finite number greater than 0 — `Infinity`, `NaN`, `0` or
|
|
390
|
+
* a negative value falls back to the default instead of disabling the cap.
|
|
391
|
+
*/
|
|
392
|
+
maxDt?: number;
|
|
393
|
+
}
|
|
394
|
+
interface GameRunHandle<S extends object = Record<string, unknown>> {
|
|
395
|
+
readonly state: S;
|
|
396
|
+
readonly frozen: boolean;
|
|
397
|
+
readonly timeScale: number;
|
|
398
|
+
/** The in-game "retry": calls `init(state)` again and resets the clock. */
|
|
399
|
+
restart(): void;
|
|
400
|
+
/** Stop the loop for good (page teardown). */
|
|
401
|
+
stop(): void;
|
|
402
|
+
}
|
|
403
|
+
interface PlayablGame {
|
|
404
|
+
run<S extends object = Record<string, unknown>>(hooks: GameLoopHooks<S>, options?: GameRunOptions<S>): Promise<GameRunHandle<S>>;
|
|
405
|
+
}
|
|
406
|
+
type CatalogCategory = 'characters' | 'hazards' | 'pickups' | 'world' | 'effects' | 'audio' | 'interface' | 'system' | 'other';
|
|
407
|
+
type LayoutRole = 'anchor' | 'x' | 'y' | 'w' | 'h' | 'rotation' | 'scale' | 'opacity' | 'z' | 'fontSize' | 'fontWeight' | 'align' | 'font' | 'padding' | 'radius' | 'text' | 'color' | 'background' | 'visible';
|
|
408
|
+
/** `{ role: tweakKey }` — each role names the tweak that holds that property. */
|
|
409
|
+
type LayoutRoleMap = Partial<Record<LayoutRole, string>>;
|
|
410
|
+
type ContentOwner = 'ai' | 'creator';
|
|
411
|
+
interface ContentGroup {
|
|
412
|
+
id: string;
|
|
413
|
+
name: string;
|
|
414
|
+
owner: ContentOwner;
|
|
415
|
+
}
|
|
416
|
+
interface ContentLevel {
|
|
417
|
+
/** `lv_<n>` when minted by the engine; any non-empty string is tolerated from disk. */
|
|
418
|
+
id: string;
|
|
419
|
+
name: string;
|
|
420
|
+
/** Names an entry in `ContentDocument.groups`. */
|
|
421
|
+
group?: string;
|
|
422
|
+
owner: ContentOwner;
|
|
423
|
+
/** Opaque to the engine: a plain JSON object or array. */
|
|
424
|
+
payload: Record<string, unknown> | unknown[];
|
|
425
|
+
}
|
|
426
|
+
interface ContentDocument {
|
|
427
|
+
version: 1;
|
|
428
|
+
groups: ContentGroup[];
|
|
429
|
+
/** Array order is play order. */
|
|
430
|
+
levels: ContentLevel[];
|
|
431
|
+
}
|
|
432
|
+
type ContentFieldType = 'number' | 'text' | 'boolean' | 'select';
|
|
433
|
+
/** One creator-editable payload key (levels.json — Contract §3, protocol §16.6). */
|
|
434
|
+
interface ContentFieldSpec {
|
|
435
|
+
type: ContentFieldType;
|
|
436
|
+
/** Filled from the key when the game omits it. */
|
|
437
|
+
label?: string;
|
|
438
|
+
description?: string;
|
|
439
|
+
min?: number;
|
|
440
|
+
max?: number;
|
|
441
|
+
step?: number;
|
|
442
|
+
/** `select` only; non-empty. */
|
|
443
|
+
options?: string[];
|
|
444
|
+
/** Informational only — never substituted for a missing payload key. */
|
|
445
|
+
default?: number | string | boolean;
|
|
446
|
+
}
|
|
447
|
+
type ContentFieldValue = string | number | boolean | null;
|
|
448
|
+
/**
|
|
449
|
+
* The 13 Creator → game content verbs (levels.json — Contract §5) plus
|
|
450
|
+
* `content-set-payload`, the `propose_level` carrier (D19).
|
|
451
|
+
*/
|
|
452
|
+
type ContentVerbType = 'content-add' | 'content-duplicate' | 'content-delete' | 'content-move' | 'place' | 'content-move-instance' | 'content-remove-instance' | 'content-set-field' | 'content-set-payload' | 'content-undo' | 'content-redo' | 'content-group-add' | 'content-group-rename' | 'content-group-delete';
|
|
453
|
+
type ProgressionNoun = 'level' | 'stage' | 'wave' | 'round' | 'day' | 'room' | 'chapter';
|
|
454
|
+
type ProgressionShape = 'sequence' | 'graph';
|
|
455
|
+
interface CatalogProgression {
|
|
456
|
+
noun: ProgressionNoun;
|
|
457
|
+
shape: ProgressionShape;
|
|
458
|
+
/** Engine-filled from the content document whenever one exists. */
|
|
459
|
+
groups: Array<{
|
|
460
|
+
id: string;
|
|
461
|
+
name: string;
|
|
462
|
+
}>;
|
|
463
|
+
}
|
|
464
|
+
interface LevelPreviewCell {
|
|
465
|
+
x: number;
|
|
466
|
+
y: number;
|
|
467
|
+
kind?: string;
|
|
468
|
+
defId?: string;
|
|
469
|
+
/** `#`-prefixed hex. */
|
|
470
|
+
color?: string;
|
|
471
|
+
}
|
|
472
|
+
/** A rendering of (part of) a level's payload for the Levels rail thumbnail. */
|
|
473
|
+
interface LevelPreview {
|
|
474
|
+
cols: number;
|
|
475
|
+
rows: number;
|
|
476
|
+
cells: LevelPreviewCell[];
|
|
477
|
+
}
|
|
478
|
+
/** A uniform placement grid over `[x, y, x+w, y+h]`, in game CSS px. */
|
|
479
|
+
interface SceneGrid {
|
|
480
|
+
x: number;
|
|
481
|
+
y: number;
|
|
482
|
+
w: number;
|
|
483
|
+
h: number;
|
|
484
|
+
cols: number;
|
|
485
|
+
rows: number;
|
|
486
|
+
}
|
|
487
|
+
/** The level the game reports as current; placement targets its `id`. */
|
|
488
|
+
interface StateLevel {
|
|
489
|
+
id: string;
|
|
490
|
+
index: number;
|
|
491
|
+
}
|
|
492
|
+
/** On the handle `sdk.devtools.init()` returns, only for a game with `content`. */
|
|
493
|
+
interface ContentHandle {
|
|
494
|
+
/**
|
|
495
|
+
* The echo rule (levels.json — Contract §4): a document JSON-equal to the
|
|
496
|
+
* engine's is ignored (`false`); a changed one becomes the new baseline,
|
|
497
|
+
* clears undo and redo, resends `catalog` (and `scene` while frozen) and
|
|
498
|
+
* never echoes `content` back. Wire it to `import.meta.hot.accept`.
|
|
499
|
+
*/
|
|
500
|
+
acceptExternal(next: unknown): boolean;
|
|
501
|
+
}
|
|
502
|
+
interface CatalogEntryBase {
|
|
503
|
+
/** `level:<id>` · `screen:<id>` · `def:<id>` — equals the `group` its tweaks use. */
|
|
504
|
+
id: string;
|
|
505
|
+
label: string;
|
|
506
|
+
tweakKeys: string[];
|
|
507
|
+
nodeKinds: string[];
|
|
508
|
+
/** Basename only. */
|
|
509
|
+
sprite?: string;
|
|
510
|
+
singleton: boolean;
|
|
511
|
+
}
|
|
512
|
+
interface CatalogLevel extends CatalogEntryBase {
|
|
513
|
+
/** Zero-based position the game's `gotoLevel(index)` accepts. */
|
|
514
|
+
index: number;
|
|
515
|
+
/** Names an id in `catalog.progression.groups`. */
|
|
516
|
+
group?: string;
|
|
517
|
+
/** The backing document level's `id` — present only for a document-backed level. */
|
|
518
|
+
contentId?: string;
|
|
519
|
+
/** `{ name, group, ...declared }`, engine-attached by `contentId` lookup; never from `catalog()`. */
|
|
520
|
+
fields?: Record<string, ContentFieldValue>;
|
|
521
|
+
preview?: LevelPreview;
|
|
522
|
+
}
|
|
523
|
+
type CatalogScreen = CatalogEntryBase;
|
|
524
|
+
interface CatalogDefinition extends CatalogEntryBase {
|
|
525
|
+
category?: CatalogCategory;
|
|
526
|
+
layout?: LayoutRoleMap;
|
|
527
|
+
/** Drag/drop into a level writes a durable instance through `content.hooks.placeInLevel`. */
|
|
528
|
+
placeable?: 'content';
|
|
529
|
+
}
|
|
530
|
+
interface SceneRect {
|
|
531
|
+
x: number;
|
|
532
|
+
y: number;
|
|
533
|
+
w: number;
|
|
534
|
+
h: number;
|
|
535
|
+
}
|
|
536
|
+
interface SceneNode {
|
|
537
|
+
/** Stable uid across frames. Never an array index. */
|
|
538
|
+
id: string;
|
|
539
|
+
/** Names a catalog entry. Unknown → dropped before the wire. */
|
|
540
|
+
defId: string;
|
|
541
|
+
kind: string;
|
|
542
|
+
label: string;
|
|
543
|
+
/** Viewport CSS px. */
|
|
544
|
+
rect: SceneRect;
|
|
545
|
+
instance: Record<string, unknown>;
|
|
546
|
+
/** Top level only. Marks a placed content instance; equals the instance id the placement hooks returned. */
|
|
547
|
+
contentId?: string;
|
|
548
|
+
}
|
|
549
|
+
interface CatalogEntryOptions {
|
|
550
|
+
tweakKeys?: string[];
|
|
551
|
+
nodeKinds?: string[];
|
|
552
|
+
/**
|
|
553
|
+
* An `assets.json` key; resolved to a basename through the merged mapping.
|
|
554
|
+
* `| undefined` on purpose: authors write `sprite: spriteFor('KEY')`, and
|
|
555
|
+
* `spriteFor` returns `undefined` for an unknown key — under
|
|
556
|
+
* `exactOptionalPropertyTypes` that would otherwise be a type error.
|
|
557
|
+
*/
|
|
558
|
+
sprite?: string | undefined;
|
|
559
|
+
}
|
|
560
|
+
interface CatalogLevelOptions extends CatalogEntryOptions {
|
|
561
|
+
index?: number;
|
|
562
|
+
group?: string | undefined;
|
|
563
|
+
contentId?: string | undefined;
|
|
564
|
+
preview?: LevelPreview | undefined;
|
|
565
|
+
}
|
|
566
|
+
interface CatalogDefinitionOptions extends CatalogEntryOptions {
|
|
567
|
+
singleton?: boolean;
|
|
568
|
+
category?: CatalogCategory;
|
|
569
|
+
layout?: LayoutRoleMap;
|
|
570
|
+
placeable?: 'content';
|
|
571
|
+
}
|
|
572
|
+
/** The helpers the runtime hands to `catalog(ctx)`. */
|
|
573
|
+
interface CatalogContext {
|
|
574
|
+
level(id: string, label: string, opts?: CatalogLevelOptions): CatalogLevel;
|
|
575
|
+
screen(id: string, label: string, opts?: CatalogEntryOptions): CatalogScreen;
|
|
576
|
+
definition(id: string, label: string, opts?: CatalogDefinitionOptions): CatalogDefinition;
|
|
577
|
+
/** Every `tweaks.json` key whose `group === id`, ordered by `index`. */
|
|
578
|
+
keysFor(id: string): string[];
|
|
579
|
+
/** Basename of the asset, resolved through the merged assets mapping. */
|
|
580
|
+
spriteFor(assetKey: string): string | undefined;
|
|
581
|
+
/** `{ x: 'hudScoreX', y: 'hudScoreY', … }` for the roles whose key exists in `tweaks.json`. */
|
|
582
|
+
layoutFor(prefix: string, roles?: LayoutRole[]): LayoutRoleMap;
|
|
583
|
+
/** The engine's CURRENT content document (a clone), or `null` without `content`. Map its `levels` — never the imported JSON. */
|
|
584
|
+
content: ContentDocument | null;
|
|
585
|
+
/** Builds `catalog.progression`; `groups` is overridden from the document when one exists. */
|
|
586
|
+
progression(opts?: {
|
|
587
|
+
noun?: ProgressionNoun;
|
|
588
|
+
shape?: ProgressionShape;
|
|
589
|
+
groups?: Array<{
|
|
590
|
+
id: string;
|
|
591
|
+
name: string;
|
|
592
|
+
}>;
|
|
593
|
+
}): CatalogProgression;
|
|
594
|
+
}
|
|
595
|
+
/**
|
|
596
|
+
* The functions the engine cannot write itself because they touch the
|
|
597
|
+
* opaque `payload` (levels.json — Contract §3). Every one is a **producer**
|
|
598
|
+
* (D28): it runs against a `structuredClone` of the target level's payload,
|
|
599
|
+
* shapes it and returns; it is committed only on success and it must touch
|
|
600
|
+
* no live game state — a refused commit (unknown id, the size cap, a check
|
|
601
|
+
* that fails after the hook) must leave the running game exactly as it was.
|
|
602
|
+
* The rebuild is the SDK's: after a commit the engine updates `state.content`
|
|
603
|
+
* and calls the loop's `init(state)`. Every hook must be synchronous — a
|
|
604
|
+
* returned promise is refused — and its clone is re-checked for plain JSON
|
|
605
|
+
* before it commits (D26).
|
|
606
|
+
*/
|
|
607
|
+
interface ContentHooks {
|
|
608
|
+
/** `prev` is the current last level's payload (a clone), or `undefined` for an empty document. */
|
|
609
|
+
blankLevel?(prev: unknown): {
|
|
610
|
+
name?: string;
|
|
611
|
+
payload: unknown;
|
|
612
|
+
};
|
|
613
|
+
/** `x`/`y` are game CSS px — the point the instance occupies. Returns the new instance id, or `false` to refuse (an occupied cell, an unplaceable point). */
|
|
614
|
+
placeInLevel?(payload: unknown, at: {
|
|
615
|
+
defId: string;
|
|
616
|
+
x: number;
|
|
617
|
+
y: number;
|
|
618
|
+
}): string | false;
|
|
619
|
+
/** May return a new id when ids are positional; `false` refuses (no such instance, an occupied target). */
|
|
620
|
+
moveInstance?(payload: unknown, instanceId: string, to: {
|
|
621
|
+
x: number;
|
|
622
|
+
y: number;
|
|
623
|
+
}): string | false;
|
|
624
|
+
/** `false` refuses — the hook's only way to say "no such instance" (D22). */
|
|
625
|
+
removeInstance?(payload: unknown, instanceId: string): boolean | void;
|
|
626
|
+
/**
|
|
627
|
+
* A declared field's write (never `name` / `group`), on the clone only.
|
|
628
|
+
* `false` refuses the whole write; `true` means the hook wrote
|
|
629
|
+
* `payload[field]` itself; anything else means the engine writes
|
|
630
|
+
* `payload[field] = value` after it. It shapes the payload — `init`
|
|
631
|
+
* rebuilds the board from it.
|
|
632
|
+
*/
|
|
633
|
+
applyField?(payload: unknown, field: string, value: ContentFieldValue, meta: {
|
|
634
|
+
id: string;
|
|
635
|
+
}): boolean | void;
|
|
636
|
+
/**
|
|
637
|
+
* Required for `content-set-payload` — the verb is advertised only when this
|
|
638
|
+
* exists (D19), because the engine cannot judge a game's payload shape.
|
|
639
|
+
* Runs against a clone of the proposed payload: `false` refuses; the hook
|
|
640
|
+
* may normalize the clone in place; anything else accepts.
|
|
641
|
+
*/
|
|
642
|
+
acceptPayload?(payload: unknown, meta: {
|
|
643
|
+
id: string;
|
|
644
|
+
}): boolean | void;
|
|
645
|
+
}
|
|
646
|
+
/** `content: { document, hooks, fields }` on `devtools.js` — opt-in. */
|
|
647
|
+
interface DevtoolsContent {
|
|
648
|
+
/** The parsed `src/game/levels.json` envelope. Cloned on intake; never aliased. */
|
|
649
|
+
document: unknown;
|
|
650
|
+
/** Every hook is optional and gates its verb (levels.json — Contract §3). */
|
|
651
|
+
hooks?: ContentHooks;
|
|
652
|
+
/** `Record<string, ContentFieldSpec>` as written; normalized fail-open per field. */
|
|
653
|
+
fields?: unknown;
|
|
654
|
+
}
|
|
655
|
+
interface DevtoolsCommand {
|
|
656
|
+
label: string;
|
|
657
|
+
icon?: string;
|
|
658
|
+
description?: string;
|
|
659
|
+
/** Marks a command that can move or add/remove nodes; the runtime resends `scene` after it while frozen. */
|
|
660
|
+
mutates?: boolean;
|
|
661
|
+
run(payload: unknown): void;
|
|
662
|
+
}
|
|
663
|
+
/** The object `createDevtools()` in `src/game/devtools.js` returns. */
|
|
664
|
+
interface DevtoolsVocabulary {
|
|
665
|
+
game: string;
|
|
666
|
+
catalog(ctx: CatalogContext): {
|
|
667
|
+
levels?: CatalogLevel[];
|
|
668
|
+
screens?: CatalogScreen[];
|
|
669
|
+
definitions?: CatalogDefinition[];
|
|
670
|
+
progression?: CatalogProgression;
|
|
671
|
+
};
|
|
672
|
+
describeScene?(): {
|
|
673
|
+
nodes: SceneNode[];
|
|
674
|
+
grid?: SceneGrid;
|
|
675
|
+
};
|
|
676
|
+
describeInstance?(nodeId: string): Record<string, unknown> | null | undefined;
|
|
677
|
+
getState?(): Record<string, unknown>;
|
|
678
|
+
getScreen?(): string | null;
|
|
679
|
+
gotoLevel?(index: number): void;
|
|
680
|
+
showScreen?(id: string | null): void;
|
|
681
|
+
setRunState?(patch: Record<string, number>): void;
|
|
682
|
+
commands?: Record<string, DevtoolsCommand>;
|
|
683
|
+
/** Levels the creator can edit (levels.json — Contract). Absent ⇒ no content verb is advertised. */
|
|
684
|
+
content?: DevtoolsContent;
|
|
685
|
+
}
|
|
686
|
+
interface DevtoolsHandle {
|
|
687
|
+
destroy(): void;
|
|
688
|
+
/** Present iff the vocabulary has a usable `content.document`. */
|
|
689
|
+
content?: ContentHandle;
|
|
690
|
+
}
|
|
691
|
+
interface PlayablDevtools {
|
|
692
|
+
init(vocabulary: DevtoolsVocabulary): Promise<DevtoolsHandle>;
|
|
693
|
+
}
|
|
250
694
|
interface PlayablSDK {
|
|
251
695
|
ready(): Promise<ReadyResult>;
|
|
252
696
|
leaderboard: {
|
|
@@ -258,15 +702,17 @@ interface PlayablSDK {
|
|
|
258
702
|
clear(): Promise<void>;
|
|
259
703
|
};
|
|
260
704
|
tweaks: {
|
|
261
|
-
init(schema: TweakSchema): Promise<PlayablTweaks>;
|
|
705
|
+
init(schema: TweakSchema, options?: TweaksInitOptions): Promise<PlayablTweaks>;
|
|
262
706
|
};
|
|
263
707
|
assets: {
|
|
264
|
-
register(mapping: AssetsMapping): Promise<PlayablAssets>;
|
|
708
|
+
register(mapping: AssetsMapping, options?: AssetsRegisterOptions): Promise<PlayablAssets>;
|
|
265
709
|
};
|
|
710
|
+
game: PlayablGame;
|
|
711
|
+
devtools: PlayablDevtools;
|
|
266
712
|
device: PlayablDevice;
|
|
267
713
|
audio: PlayablAudio;
|
|
268
714
|
}
|
|
269
|
-
type ErrorCode = 'NOT_IN_IFRAME' | 'PARENT_TIMEOUT' | 'SDK_NOT_READY' | 'STORAGE_SERIALIZE_ERROR' | 'STORAGE_QUOTA_EXCEEDED' | 'INVALID_SCHEMA' | 'INVALID_ASSETS' | 'NOT_SUPPORTED' | 'PERMISSION_DENIED' | 'TIMEOUT' | 'OPERATION_FAILED' | 'UNKNOWN_ERROR';
|
|
715
|
+
type ErrorCode = 'NOT_IN_IFRAME' | 'PARENT_TIMEOUT' | 'SDK_NOT_READY' | 'STORAGE_SERIALIZE_ERROR' | 'STORAGE_QUOTA_EXCEEDED' | 'INVALID_SCHEMA' | 'INVALID_ASSETS' | 'INVALID_DEVTOOLS' | 'NOT_SUPPORTED' | 'PERMISSION_DENIED' | 'TIMEOUT' | 'OPERATION_FAILED' | 'UNKNOWN_ERROR';
|
|
270
716
|
declare class PlayablError extends Error {
|
|
271
717
|
readonly code: ErrorCode;
|
|
272
718
|
readonly cause?: unknown;
|
|
@@ -289,4 +735,4 @@ declare const __testing: {
|
|
|
289
735
|
setRuntimeLoader(loader: RuntimeLoader): void;
|
|
290
736
|
};
|
|
291
737
|
|
|
292
|
-
export { type AssetDescriptor, type AssetOverride, type AssetStatus, type AssetType, type AssetsMapping, type BooleanTweak, type CameraAPI, type CameraOptions, type CameraResult, type ColorTweak, type ErrorCode, type FileSystemAPI, type FileSystemOptions, type FileSystemResult, type GeolocationAPI, type GeolocationOptions, type GeolocationResult, type HapticsAPI, type MicrophoneAPI, type MicrophoneRecordOptions, type MicrophoneResult, type MicrophoneStreamOptions, type MotionAttitude, type MotionData, type MotionRotation, type MotionVector, type NumberTweak, type OrientationData, type PlayablAssets, type PlayablAudio, type PlayablAudioAutoPauseOptions, type PlayablAudioContext, type PlayablAudioOptions, type PlayablDevice, PlayablError, type PlayablSDK, type PlayablTweaks, type ReadyResult, type SaveResult, type SensorsAPI, type SubmitResult, type TextTweak, type TweakSchema, type TweakSchemaItem, type TweakType, type TweakValue, __testing, configure, sdk as default };
|
|
738
|
+
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 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 LayoutRole, type LayoutRoleMap, 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 };
|
package/dist/index.js
CHANGED
|
@@ -37,6 +37,113 @@ async function resolveRuntimeUrl(options = {}) {
|
|
|
37
37
|
}
|
|
38
38
|
}
|
|
39
39
|
|
|
40
|
+
// src/content-helpers.ts
|
|
41
|
+
function isCellGridEntry(entry) {
|
|
42
|
+
if (typeof entry !== "object" || entry === null || Array.isArray(entry)) return false;
|
|
43
|
+
const prototype = Object.getPrototypeOf(entry);
|
|
44
|
+
if (prototype !== Object.prototype && prototype !== null) return false;
|
|
45
|
+
const id = Object.getOwnPropertyDescriptor(entry, "id");
|
|
46
|
+
const defId = Object.getOwnPropertyDescriptor(entry, "defId")?.value;
|
|
47
|
+
const x = Object.getOwnPropertyDescriptor(entry, "x")?.value;
|
|
48
|
+
const y = Object.getOwnPropertyDescriptor(entry, "y")?.value;
|
|
49
|
+
return (!id || "value" in id && (id.value === void 0 || typeof id.value === "string")) && typeof defId === "string" && defId.length > 0 && typeof x === "number" && Number.isFinite(x) && typeof y === "number" && Number.isFinite(y);
|
|
50
|
+
}
|
|
51
|
+
function cellGridHooks({
|
|
52
|
+
cell = 32,
|
|
53
|
+
origin = { x: 0, y: 0 },
|
|
54
|
+
key = "instances"
|
|
55
|
+
} = {}) {
|
|
56
|
+
const cellSize = typeof cell === "number" && Number.isFinite(cell) && cell > 0 ? cell : 32;
|
|
57
|
+
const toCell = (px, offset) => Math.floor((px - offset) / cellSize);
|
|
58
|
+
const entryId = (entry) => Object.hasOwn(entry, "id") && typeof entry.id === "string" && entry.id ? entry.id : `${entry.defId}:${entry.x},${entry.y}`;
|
|
59
|
+
const listOf = (payload, create = false) => {
|
|
60
|
+
try {
|
|
61
|
+
if (typeof payload !== "object" || payload === null || Array.isArray(payload)) return null;
|
|
62
|
+
const descriptor = Object.getOwnPropertyDescriptor(payload, key);
|
|
63
|
+
if (descriptor) {
|
|
64
|
+
const list2 = descriptor.value;
|
|
65
|
+
if (!Array.isArray(list2)) return null;
|
|
66
|
+
const ids = /* @__PURE__ */ new Set();
|
|
67
|
+
const cells = /* @__PURE__ */ new Set();
|
|
68
|
+
for (let index = 0; index < list2.length; index++) {
|
|
69
|
+
const entry = Object.getOwnPropertyDescriptor(list2, index);
|
|
70
|
+
if (!entry || !("value" in entry) || !isCellGridEntry(entry.value)) return null;
|
|
71
|
+
const id = entryId(entry.value);
|
|
72
|
+
const position = `${entry.value.x},${entry.value.y}`;
|
|
73
|
+
if (ids.has(id) || cells.has(position)) return null;
|
|
74
|
+
ids.add(id);
|
|
75
|
+
cells.add(position);
|
|
76
|
+
}
|
|
77
|
+
return list2;
|
|
78
|
+
}
|
|
79
|
+
if (!create) return null;
|
|
80
|
+
const list = [];
|
|
81
|
+
Object.defineProperty(payload, key, {
|
|
82
|
+
value: list,
|
|
83
|
+
writable: true,
|
|
84
|
+
enumerable: true,
|
|
85
|
+
configurable: true
|
|
86
|
+
});
|
|
87
|
+
return list;
|
|
88
|
+
} catch {
|
|
89
|
+
return null;
|
|
90
|
+
}
|
|
91
|
+
};
|
|
92
|
+
return {
|
|
93
|
+
blankLevel(prev) {
|
|
94
|
+
const source = prev;
|
|
95
|
+
const payload = {};
|
|
96
|
+
if (typeof source?.cols === "number" && Number.isFinite(source.cols))
|
|
97
|
+
payload.cols = source.cols;
|
|
98
|
+
if (typeof source?.rows === "number" && Number.isFinite(source.rows))
|
|
99
|
+
payload.rows = source.rows;
|
|
100
|
+
Object.defineProperty(payload, key, {
|
|
101
|
+
value: [],
|
|
102
|
+
writable: true,
|
|
103
|
+
enumerable: true,
|
|
104
|
+
configurable: true
|
|
105
|
+
});
|
|
106
|
+
return { name: "New Level", payload };
|
|
107
|
+
},
|
|
108
|
+
placeInLevel(payload, { defId, x, y }) {
|
|
109
|
+
const col = toCell(x, origin.x);
|
|
110
|
+
const row = toCell(y, origin.y);
|
|
111
|
+
if (!Number.isFinite(col) || !Number.isFinite(row)) return false;
|
|
112
|
+
const list = listOf(payload, true);
|
|
113
|
+
if (!list) return false;
|
|
114
|
+
if (list.some((item) => item.x === col && item.y === row)) return false;
|
|
115
|
+
const id = `${defId}:${col},${row}`;
|
|
116
|
+
if (list.some((item) => entryId(item) === id)) return false;
|
|
117
|
+
list.push({ id, defId, x: col, y: row });
|
|
118
|
+
return id;
|
|
119
|
+
},
|
|
120
|
+
moveInstance(payload, instanceId, { x, y }) {
|
|
121
|
+
const list = listOf(payload);
|
|
122
|
+
if (!list) return false;
|
|
123
|
+
const entry = list.find((item) => entryId(item) === instanceId);
|
|
124
|
+
if (!entry) return false;
|
|
125
|
+
const col = toCell(x, origin.x);
|
|
126
|
+
const row = toCell(y, origin.y);
|
|
127
|
+
if (!Number.isFinite(col) || !Number.isFinite(row)) return false;
|
|
128
|
+
if (list.some((item) => item !== entry && item.x === col && item.y === row)) return false;
|
|
129
|
+
const id = `${entry.defId}:${col},${row}`;
|
|
130
|
+
if (list.some((item) => item !== entry && entryId(item) === id)) return false;
|
|
131
|
+
entry.x = col;
|
|
132
|
+
entry.y = row;
|
|
133
|
+
entry.id = id;
|
|
134
|
+
return entry.id;
|
|
135
|
+
},
|
|
136
|
+
removeInstance(payload, instanceId) {
|
|
137
|
+
const list = listOf(payload);
|
|
138
|
+
if (!list) return false;
|
|
139
|
+
const index = list.findIndex((item) => entryId(item) === instanceId);
|
|
140
|
+
if (index === -1) return false;
|
|
141
|
+
list.splice(index, 1);
|
|
142
|
+
return true;
|
|
143
|
+
}
|
|
144
|
+
};
|
|
145
|
+
}
|
|
146
|
+
|
|
40
147
|
// src/index.ts
|
|
41
148
|
var PlayablError = class extends Error {
|
|
42
149
|
code;
|
|
@@ -81,10 +188,7 @@ function configure(options) {
|
|
|
81
188
|
}
|
|
82
189
|
async function getSDK() {
|
|
83
190
|
if (typeof window === "undefined") {
|
|
84
|
-
throw new PlayablError(
|
|
85
|
-
"SDK_NOT_READY",
|
|
86
|
-
"Playabl SDK runtime can only be loaded in a browser."
|
|
87
|
-
);
|
|
191
|
+
throw new PlayablError("SDK_NOT_READY", "Playabl SDK runtime can only be loaded in a browser.");
|
|
88
192
|
}
|
|
89
193
|
sdkPromise ??= runtimeLoader().then(
|
|
90
194
|
(runtime) => {
|
|
@@ -101,6 +205,16 @@ async function getSDK() {
|
|
|
101
205
|
function peekSDK() {
|
|
102
206
|
return loadedSDK;
|
|
103
207
|
}
|
|
208
|
+
function requireRuntimeMember(runtime, name) {
|
|
209
|
+
const member = runtime[name];
|
|
210
|
+
if (!member) {
|
|
211
|
+
throw new PlayablError(
|
|
212
|
+
"NOT_SUPPORTED",
|
|
213
|
+
`sdk.${name} needs a Playabl runtime that provides it; this environment serves an older runtime`
|
|
214
|
+
);
|
|
215
|
+
}
|
|
216
|
+
return member;
|
|
217
|
+
}
|
|
104
218
|
var sdk = {
|
|
105
219
|
ready: async () => (await getSDK()).ready(),
|
|
106
220
|
leaderboard: {
|
|
@@ -112,10 +226,16 @@ var sdk = {
|
|
|
112
226
|
clear: async () => (await getSDK()).gameState.clear()
|
|
113
227
|
},
|
|
114
228
|
tweaks: {
|
|
115
|
-
init: async (schema) => (await getSDK()).tweaks.init(schema)
|
|
229
|
+
init: async (schema, options) => (await getSDK()).tweaks.init(schema, options)
|
|
116
230
|
},
|
|
117
231
|
assets: {
|
|
118
|
-
register: async (mapping) => (await getSDK()).assets.register(mapping)
|
|
232
|
+
register: async (mapping, options) => (await getSDK()).assets.register(mapping, options)
|
|
233
|
+
},
|
|
234
|
+
game: {
|
|
235
|
+
run: async (hooks, options) => requireRuntimeMember(await getSDK(), "game").run(hooks, options)
|
|
236
|
+
},
|
|
237
|
+
devtools: {
|
|
238
|
+
init: async (vocabulary) => requireRuntimeMember(await getSDK(), "devtools").init(vocabulary)
|
|
119
239
|
},
|
|
120
240
|
device: {
|
|
121
241
|
haptics: {
|
|
@@ -253,6 +373,7 @@ var __testing = {
|
|
|
253
373
|
export {
|
|
254
374
|
PlayablError,
|
|
255
375
|
__testing,
|
|
376
|
+
cellGridHooks,
|
|
256
377
|
configure,
|
|
257
378
|
index_default as default
|
|
258
379
|
};
|
package/package.json
CHANGED
|
@@ -1,32 +1,35 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "@playabl/sdk",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"type": "module",
|
|
5
|
-
"main": "./dist/index.js",
|
|
6
|
-
"types": "./dist/index.d.ts",
|
|
7
|
-
"files": [
|
|
8
|
-
"dist/index.js",
|
|
9
|
-
"dist/index.d.ts",
|
|
10
|
-
"README.md"
|
|
11
|
-
],
|
|
12
|
-
"exports": {
|
|
13
|
-
".": {
|
|
14
|
-
"types": "./dist/index.d.ts",
|
|
15
|
-
"import": "./dist/index.js"
|
|
16
|
-
}
|
|
17
|
-
},
|
|
18
|
-
"sideEffects": [
|
|
19
|
-
"./dist/index.js"
|
|
20
|
-
],
|
|
21
|
-
"scripts": {
|
|
22
|
-
"build": "tsup",
|
|
23
|
-
"
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
"
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
"
|
|
30
|
-
"
|
|
31
|
-
|
|
32
|
-
|
|
1
|
+
{
|
|
2
|
+
"name": "@playabl/sdk",
|
|
3
|
+
"version": "1.0.0",
|
|
4
|
+
"type": "module",
|
|
5
|
+
"main": "./dist/index.js",
|
|
6
|
+
"types": "./dist/index.d.ts",
|
|
7
|
+
"files": [
|
|
8
|
+
"dist/index.js",
|
|
9
|
+
"dist/index.d.ts",
|
|
10
|
+
"README.md"
|
|
11
|
+
],
|
|
12
|
+
"exports": {
|
|
13
|
+
".": {
|
|
14
|
+
"types": "./dist/index.d.ts",
|
|
15
|
+
"import": "./dist/index.js"
|
|
16
|
+
}
|
|
17
|
+
},
|
|
18
|
+
"sideEffects": [
|
|
19
|
+
"./dist/index.js"
|
|
20
|
+
],
|
|
21
|
+
"scripts": {
|
|
22
|
+
"build": "tsup",
|
|
23
|
+
"release:check": "node scripts/check-release.mjs",
|
|
24
|
+
"type-check": "tsc --noEmit",
|
|
25
|
+
"test": "vitest run",
|
|
26
|
+
"prepublishOnly": "node scripts/check-release.mjs"
|
|
27
|
+
},
|
|
28
|
+
"devDependencies": {
|
|
29
|
+
"dotenv": "^17.4.2",
|
|
30
|
+
"happy-dom": "^18.0.1",
|
|
31
|
+
"tsup": "^8.5.0",
|
|
32
|
+
"typescript": "^5.9.2",
|
|
33
|
+
"vitest": "^3.2.4"
|
|
34
|
+
}
|
|
35
|
+
}
|