@playabl/sdk 1.0.0 → 1.1.0-beta.1
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 +26 -0
- package/dist/index.d.ts +366 -8
- package/dist/index.js +78 -7
- package/dist/layout.d.ts +113 -0
- package/dist/layout.js +648 -0
- package/package.json +13 -2
package/dist/layout.d.ts
ADDED
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
/** When a changed value reaches the game. Enforced by the runtime, not the game. */
|
|
2
|
+
type TweakAppliesOn = 'live' | 'restart';
|
|
3
|
+
interface BaseTweak {
|
|
4
|
+
name?: string;
|
|
5
|
+
description?: string;
|
|
6
|
+
group?: string;
|
|
7
|
+
index?: number;
|
|
8
|
+
appliesOn?: TweakAppliesOn;
|
|
9
|
+
/** Creator-only rendering hints. The runtime never reads it. */
|
|
10
|
+
ui?: Record<string, unknown>;
|
|
11
|
+
}
|
|
12
|
+
interface NumberTweak extends BaseTweak {
|
|
13
|
+
type: 'number';
|
|
14
|
+
value: number;
|
|
15
|
+
min?: number;
|
|
16
|
+
max?: number;
|
|
17
|
+
step?: number;
|
|
18
|
+
}
|
|
19
|
+
interface BooleanTweak extends BaseTweak {
|
|
20
|
+
type: 'boolean';
|
|
21
|
+
value: boolean;
|
|
22
|
+
}
|
|
23
|
+
interface TextTweak extends BaseTweak {
|
|
24
|
+
type: 'text';
|
|
25
|
+
value: string;
|
|
26
|
+
}
|
|
27
|
+
interface EnumTweak extends BaseTweak {
|
|
28
|
+
type: 'enum';
|
|
29
|
+
value: string;
|
|
30
|
+
/** Non-empty, unique. The closed set of allowed values. */
|
|
31
|
+
options: string[];
|
|
32
|
+
}
|
|
33
|
+
interface ColorTweak extends BaseTweak {
|
|
34
|
+
type: 'color';
|
|
35
|
+
value: string;
|
|
36
|
+
}
|
|
37
|
+
type TweakSchemaItem = NumberTweak | BooleanTweak | TextTweak | EnumTweak | ColorTweak;
|
|
38
|
+
interface TweakSchema {
|
|
39
|
+
[key: string]: TweakSchemaItem;
|
|
40
|
+
}
|
|
41
|
+
type LayoutRole = 'anchor' | 'x' | 'y' | 'w' | 'h' | 'rotation' | 'scale' | 'opacity' | 'z' | 'fontSize' | 'fontWeight' | 'align' | 'font' | 'padding' | 'radius' | 'text' | 'color' | 'background' | 'visible';
|
|
42
|
+
/** `{ role: tweakKey }` — each role names the tweak that holds that property. */
|
|
43
|
+
type LayoutRoleMap = Partial<Record<LayoutRole, string>>;
|
|
44
|
+
|
|
45
|
+
/**
|
|
46
|
+
* devtools.js — Contract §3a: the closed role set, in the spec's order. The one
|
|
47
|
+
* role table (Layout Roles Review, rule 5): the catalog, the synthesis below
|
|
48
|
+
* and `contract/layout.schema.json` all read these lists. The npm wrapper also
|
|
49
|
+
* bundles this file as `@playabl/sdk/layout` for Node tools, so it must load
|
|
50
|
+
* without a DOM, and a change here reaches those tools only with an npm release.
|
|
51
|
+
*/
|
|
52
|
+
declare const LAYOUT_ROLES: ReadonlyArray<LayoutRole>;
|
|
53
|
+
declare const LAYOUT_ANCHORS: ReadonlyArray<string>;
|
|
54
|
+
declare const LAYOUT_WEIGHTS: ReadonlyArray<string>;
|
|
55
|
+
declare const LAYOUT_ALIGNS: ReadonlyArray<string>;
|
|
56
|
+
interface LayoutFrame {
|
|
57
|
+
w: number;
|
|
58
|
+
h: number;
|
|
59
|
+
}
|
|
60
|
+
/** The frame ranges are sized to when the window reports none (a hidden or not-yet-laid-out iframe). */
|
|
61
|
+
declare const DEFAULT_FRAME: Readonly<LayoutFrame>;
|
|
62
|
+
/** `layout.json` fields that are not roles. */
|
|
63
|
+
declare const ENTRY_FIELDS: ReadonlyArray<string>;
|
|
64
|
+
/** The tweak key for one role: `layoutKey('hudScore', 'fontSize')` is `hudScoreFontSize`. */
|
|
65
|
+
declare function layoutKey(prefix: string, role: string): string;
|
|
66
|
+
/**
|
|
67
|
+
* `def:hud-score` → `hudScore`: the id without `def:`, in camelCase (the template's
|
|
68
|
+
* existing key naming, D7). An id whose first segment starts with a digit gives a
|
|
69
|
+
* result that is not a key prefix (`def:2-player` → `2Player`); `readPrefix` handles it.
|
|
70
|
+
*/
|
|
71
|
+
declare function defaultPrefix(id: string): string;
|
|
72
|
+
/**
|
|
73
|
+
* The hard limits of a number role — the ones that hold whatever the frame,
|
|
74
|
+
* and that `contract/layout.schema.json` states as `minimum` / `maximum` — or
|
|
75
|
+
* `undefined` for a role that is not a number. x and y have none.
|
|
76
|
+
*/
|
|
77
|
+
declare function roleLimits(role: LayoutRole): {
|
|
78
|
+
min?: number;
|
|
79
|
+
max?: number;
|
|
80
|
+
} | undefined;
|
|
81
|
+
|
|
82
|
+
/**
|
|
83
|
+
* `@playabl/sdk/layout`: the runtime's own `layout.json` synthesis, for Node
|
|
84
|
+
* tools that read `tweaks.json` from disk. Games never import it. The CDN
|
|
85
|
+
* runtime and this entry share one source file, so a change to the role table
|
|
86
|
+
* reaches template tools only with an npm release of this package.
|
|
87
|
+
*/
|
|
88
|
+
|
|
89
|
+
/** What `synthesiseLayout` returns to a tool; the runtime's own result carries more, for itself. */
|
|
90
|
+
interface LayoutSynthesis {
|
|
91
|
+
/** The tweak items `tweaks.init` adds, per entry in role-table order. It has no prototype: test keys with `Object.hasOwn`. */
|
|
92
|
+
items: TweakSchema;
|
|
93
|
+
/** `def id → { role → tweak key }`, including a role mapped onto a key `tweaks.json` already owns. */
|
|
94
|
+
entries: ReadonlyMap<string, LayoutRoleMap>;
|
|
95
|
+
/** The keys of `items`. */
|
|
96
|
+
synthesised: ReadonlySet<string>;
|
|
97
|
+
/**
|
|
98
|
+
* x/y/w/h keys whose `min`/`max` only size the control: the runtime accepts
|
|
99
|
+
* any value for a `both` key, and any value from `min` up for a `max` key.
|
|
100
|
+
*/
|
|
101
|
+
softBounds: ReadonlyMap<string, 'both' | 'max'>;
|
|
102
|
+
/** Rotation keys: the runtime wraps a saved, host or live value into (−180, 180] before checking it. */
|
|
103
|
+
angles: ReadonlySet<string>;
|
|
104
|
+
/**
|
|
105
|
+
* Keys of roles the file declared but the synthesis dropped, and every key of `creatorValues`
|
|
106
|
+
* outside `schema` when the file is not an object; the runtime never reports a saved value
|
|
107
|
+
* for one as orphaned.
|
|
108
|
+
*/
|
|
109
|
+
declined: ReadonlySet<string>;
|
|
110
|
+
}
|
|
111
|
+
declare const synthesiseLayout: (layout: unknown, schema: TweakSchema, creatorValues: Record<string, unknown>, frame: LayoutFrame, warn?: (message: string) => void) => LayoutSynthesis;
|
|
112
|
+
|
|
113
|
+
export { DEFAULT_FRAME, ENTRY_FIELDS, LAYOUT_ALIGNS, LAYOUT_ANCHORS, LAYOUT_ROLES, LAYOUT_WEIGHTS, type LayoutFrame, type LayoutRole, type LayoutRoleMap, type LayoutSynthesis, type TweakSchema, type TweakSchemaItem, defaultPrefix, layoutKey, roleLimits, synthesiseLayout };
|