@scenoco-three/unity 1.4.0 → 1.6.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/dist/stub.js CHANGED
@@ -25,6 +25,8 @@ const KEYWORDS = new Set(('abstract as base bool break byte case catch char chec
25
25
  'static string struct switch this throw true try typeof uint ulong unchecked unsafe ushort using virtual void volatile while')
26
26
  .split(' '));
27
27
  const pascal = (name) => name.charAt(0).toUpperCase() + name.slice(1);
28
+ /** A member's C# name: PascalCase, and never its class's own — `Punch.punch()` is `Punch.DoPunch()`. */
29
+ const memberName = (name, owner) => (pascal(name) === owner ? `Do${pascal(name)}` : pascal(name));
28
30
  const safe = (name) => (KEYWORDS.has(name) ? `@${name}` : name);
29
31
  /** The class `name` declared in `code`, or undefined when it is not there. */
30
32
  export function readClass(code, file, name) {
@@ -66,7 +68,9 @@ export function readClass(code, file, name) {
66
68
  continue;
67
69
  const params = fn.params.map((p) => {
68
70
  const id = (p.type === 'AssignmentPattern' ? p.left : p.type === 'TSParameterProperty' ? p.parameter : p);
69
- return { name: id.name ?? 'arg', type: typeText(id.typeAnnotation) };
71
+ // Untyped with a default, it is the default's type: `step = 0` is a number.
72
+ const given = p.type === 'AssignmentPattern' ? literalType(p.right) : '';
73
+ return { name: id.name ?? 'arg', type: typeText(id.typeAnnotation) || given };
70
74
  });
71
75
  let returns = typeText(fn.returnType);
72
76
  if (!returns)
@@ -86,6 +90,31 @@ export function readClass(code, file, name) {
86
90
  const superClass = declaration.superClass;
87
91
  return { doc: docBefore(declaration.start), base: superClass ? code.slice(superClass.start, superClass.end) : undefined, members };
88
92
  }
93
+ /** The type of a literal default — `0`, `'a'`, `true` — or '' for anything else. */
94
+ function literalType(n) {
95
+ if (n.type === 'UnaryExpression' && n.operator === '-')
96
+ return literalType(n.argument);
97
+ if (n.type !== 'Literal')
98
+ return '';
99
+ const v = n.value;
100
+ return typeof v === 'number' ? 'number' : typeof v === 'string' ? 'string' : typeof v === 'boolean' ? 'boolean' : '';
101
+ }
102
+ /**
103
+ * Every type alias a module declares, by name: `type Bonus = 'none' | 'laser'` — what a signature that
104
+ * names one means, wherever in the game it was declared.
105
+ */
106
+ export function typeAliases(code, file) {
107
+ const out = new Map();
108
+ const { program } = parseSync(file, code, { lang: file.endsWith('.tsx') ? 'tsx' : 'ts' });
109
+ for (const statement of program.body) {
110
+ const inner = statement.declaration ?? statement;
111
+ if (inner.type !== 'TSTypeAliasDeclaration')
112
+ continue;
113
+ const t = inner.typeAnnotation;
114
+ out.set(inner.id.name, code.slice(t.start, t.end));
115
+ }
116
+ return out;
117
+ }
89
118
  /**
90
119
  * A module's code outside the classes named — its imports left out too: the interfaces, types,
91
120
  * constants and functions a behaviour's file holds beside it, which no stub carries.
@@ -150,23 +179,25 @@ function dedent(text) {
150
179
  * A TypeScript type as C#, where the type says it: `number` is `float`, a node is its `Transform`,
151
180
  * an element of the page is a `VisualElement`. Undefined when it does not.
152
181
  */
153
- export function csType(ts, classes) {
154
- const t = ts.trim().replace(/^readonly\s+/, '');
155
- if (!t)
182
+ export function csType(ts, classes, aliases = new Map(), depth = 0) {
183
+ const t = ts.trim().replace(/^readonly\s+/, '').replace(/^\|\s*/, '');
184
+ if (!t || depth > 8)
156
185
  return undefined;
186
+ const again = (text) => csType(text, classes, aliases, depth + 1);
157
187
  const parts = splitTop(t, '|').map((p) => p.trim()).filter((p) => p !== 'null' && p !== 'undefined');
158
188
  if (parts.length > 1) {
159
- if (parts.every((p) => /^(['"]).*\1$/.test(p)))
160
- return 'string';
161
- if (parts.every((p) => /^-?\d/.test(p)))
162
- return 'float';
163
- return undefined;
189
+ // A union of one C# type — names of a union of strings, aliases of numbers — is that type.
190
+ const types = new Set(parts.map((p) => (/^(['"]).*\1$/.test(p) ? 'string' : /^-?\d/.test(p) ? 'float' : again(p))));
191
+ return types.size === 1 ? [...types][0] : undefined;
164
192
  }
165
193
  const one = parts[0] ?? '';
166
194
  if (one.startsWith('(') && one.endsWith(')'))
167
- return csType(one.slice(1, -1), classes);
195
+ return again(one.slice(1, -1));
196
+ // The keys of an object are its names.
197
+ if (one.startsWith('keyof '))
198
+ return 'string';
168
199
  if (one.endsWith('[]')) {
169
- const inner = csType(one.slice(0, -2), classes);
200
+ const inner = again(one.slice(0, -2));
170
201
  return inner && inner !== 'void' ? `${inner}[]` : undefined;
171
202
  }
172
203
  if (/^(['"]).*\1$/.test(one))
@@ -186,11 +217,16 @@ export function csType(ts, classes) {
186
217
  return undefined;
187
218
  const [, name, args] = generic;
188
219
  if (name === 'Array' && args)
189
- return csType(`${args}[]`, classes);
220
+ return again(`${args}[]`);
221
+ // Narrowed, it is still what it narrows: `Exclude<Bonus, 'none'>` is a Bonus.
222
+ if (/^(Exclude|Extract|NonNullable|Readonly)$/.test(name) && args)
223
+ return again(splitTop(args, ',')[0]);
224
+ if (name === 'HTMLTemplateElement')
225
+ return 'VisualTreeAsset';
190
226
  if (name === 'Generator' || name === 'Iterator' || name === 'IterableIterator')
191
227
  return 'IEnumerator';
192
228
  if (name === 'Promise') {
193
- const inner = args ? csType(args, classes) : 'void';
229
+ const inner = args ? again(args) : 'void';
194
230
  return inner === 'void' ? 'Awaitable' : inner ? `Awaitable<${inner}>` : undefined;
195
231
  }
196
232
  if (SAME.has(name))
@@ -201,7 +237,10 @@ export function csType(ts, classes) {
201
237
  return 'MonoBehaviour';
202
238
  if (/^HTML\w*Element$/.test(name))
203
239
  return 'VisualElement';
204
- return classes.get(name);
240
+ if (classes.has(name))
241
+ return classes.get(name);
242
+ const alias = aliases.get(name);
243
+ return alias !== undefined && !args ? again(alias) : undefined;
205
244
  }
206
245
  /** `text` split at `separator` where it is not inside brackets of any kind. */
207
246
  function splitTop(text, separator) {
@@ -226,7 +265,7 @@ function splitTop(text, separator) {
226
265
  * The C# class for a behaviour: `wired` are the fields its scenes and prefabs set — real fields, with
227
266
  * the C# the exporter already chose for them — and everything else comes from its TypeScript.
228
267
  */
229
- export function stubClass(name, file, source, wired, classes, outside = []) {
268
+ export function stubClass(name, file, source, wired, classes, outside = [], aliases = new Map()) {
230
269
  const lines = [];
231
270
  const comment = (text, indent) => text.map((l) => (l ? `${indent}// ${l}` : `${indent}//`));
232
271
  const base = source.base === 'Behaviour' || !source.base ? 'MonoBehaviour' : (classes.get(source.base) ?? 'MonoBehaviour');
@@ -260,30 +299,32 @@ export function stubClass(name, file, source, wired, classes, outside = []) {
260
299
  continue;
261
300
  }
262
301
  else {
263
- block.push(...method(m, classes));
302
+ block.push(...method(m, classes, aliases, name));
264
303
  }
265
304
  body.push(block);
266
305
  }
267
- body.push(...properties(source.members, classes));
306
+ body.push(...properties(source.members, classes, aliases, name));
268
307
  lines.push(...body.flatMap((b, i) => (i ? ['', ...b] : b)), '}', '');
269
308
  if (outside.length) {
270
309
  lines.push(`// Outside the class, in ${file.replace(/^\//, '')}: port it where the game needs it — an enum, a static class, a`, '// ScriptableObject — then delete the comment.', '//', ...outside.map((l) => (l ? `// ${l}` : '//')), '');
271
310
  }
272
311
  const usings = ['using System.Collections;', 'using UnityEngine;'];
273
- if (lines.some((l) => !l.trimStart().startsWith('//') && l.includes('VisualElement')))
312
+ if (lines.some((l) => !l.trimStart().startsWith('//') && /\bVisual(Element|TreeAsset)\b/.test(l)))
274
313
  usings.push('using UnityEngine.UIElements;');
275
314
  return [...usings, '', ...lines].join('\n');
276
315
  }
277
- function method(m, classes) {
316
+ function method(m, classes, aliases, owner = '') {
278
317
  const message = MESSAGES.has(m.name) && !m.isStatic;
279
- const returns = csType(m.returns, classes) ?? 'object';
318
+ const returns = csType(m.returns, classes, aliases) ?? 'object';
280
319
  // Core hands `update` the frame's time; Unity's Update takes nothing and reads Time.deltaTime.
281
320
  const dropped = message && !WITH_ARGUMENT.test(m.name) ? m.params : [];
282
- const params = (dropped.length ? [] : m.params).map((p) => `${csType(p.type, classes) ?? 'object'} ${safe(p.name)}`).join(', ');
321
+ const params = (dropped.length ? [] : m.params).map((p) => `${csType(p.type, classes, aliases) ?? 'object'} ${safe(p.name)}`).join(', ');
283
322
  const modifiers = message ? '' : `${m.access} ${m.isStatic ? 'static ' : ''}`;
284
323
  const placeholder = returns === 'void' ? [] : returns === 'IEnumerator' ? [' yield break;'] : [' return default;'];
324
+ const own = memberName(m.name, owner);
285
325
  return [
286
- ` ${modifiers}${returns} ${pascal(m.name)}(${params})`,
326
+ ...(own !== pascal(m.name) ? [` // ${pascal(m.name)} in TypeScript: C# has no member named after its class.`] : []),
327
+ ` ${modifiers}${returns} ${own}(${params})`,
287
328
  ' {',
288
329
  ...dropped.map((p) => ` // Unity passes no ${p.name}: ${m.name === 'fixedUpdate' ? 'Time.fixedDeltaTime' : 'Time.deltaTime'} is the frame's time.`),
289
330
  ` // ${m.head} {`,
@@ -294,14 +335,14 @@ function method(m, classes) {
294
335
  ];
295
336
  }
296
337
  /** Getters and setters as C# properties, one per name. */
297
- function properties(members, classes) {
338
+ function properties(members, classes, aliases, owner = '') {
298
339
  const out = [];
299
340
  const names = [...new Set(members.filter((m) => m.kind === 'get' || m.kind === 'set').map((m) => m.name))];
300
341
  for (const name of names) {
301
342
  const get = members.find((m) => m.kind === 'get' && m.name === name);
302
343
  const set = members.find((m) => m.kind === 'set' && m.name === name);
303
344
  const first = get ?? set;
304
- const type = csType(get?.returns ?? set?.params?.[0]?.type ?? '', classes) ?? 'object';
345
+ const type = csType(get?.returns ?? set?.params?.[0]?.type ?? '', classes, aliases) ?? 'object';
305
346
  const accessor = (m, word, placeholder) => [
306
347
  ` ${word}`,
307
348
  ' {',
@@ -313,7 +354,7 @@ function properties(members, classes) {
313
354
  ];
314
355
  out.push([
315
356
  ...first.doc.map((l) => (l ? ` // ${l}` : ' //')),
316
- ` ${first.access} ${first.isStatic ? 'static ' : ''}${type} ${pascal(name)}`,
357
+ ` ${first.access} ${first.isStatic ? 'static ' : ''}${type} ${memberName(name, owner)}`,
317
358
  ' {',
318
359
  ...(get ? accessor(get, 'get', [' return default;']) : []),
319
360
  ...(set ? accessor(set, 'set', []) : []),
package/dist/twin.d.ts ADDED
@@ -0,0 +1,52 @@
1
+ import type { UnityExport, UnityValue } from './convert.js';
2
+ /** Assets the twins name, which the importer makes before Scenoco builds the twins. */
3
+ export interface TwinAssets {
4
+ /** Unity's PhysicsMaterial (3D) or PhysicsMaterial2D for a collider's friction and bounciness. */
5
+ physicsMaterials: {
6
+ path: string;
7
+ dimensions: 2 | 3;
8
+ friction: number;
9
+ bounciness: number;
10
+ }[];
11
+ /** One particle material per blending, `Assets/Materials/Particles-<blending>.mat`. */
12
+ particleMaterials: ('Additive' | 'Alpha')[];
13
+ /** A URP Volume's profile and the effects in it, by the component types SceNoCo names them by. */
14
+ volumes: {
15
+ path: string;
16
+ effects: {
17
+ type: string;
18
+ fields: Record<string, UnityValue>;
19
+ }[];
20
+ }[];
21
+ /** UI Toolkit's panel settings, one per UIDocument element, scaling as core's UIDocument does. */
22
+ panels: {
23
+ path: string;
24
+ referenceResolution: number[];
25
+ match: number;
26
+ sortingOrder: number;
27
+ }[];
28
+ /** URP's terrain material, which a Terrain needs or draws pink. */
29
+ terrainMaterial?: string;
30
+ }
31
+ export interface TwinOptions {
32
+ /** The page's UXML by the element a UIDocument names, in the page's order. */
33
+ documents?: Record<string, string>;
34
+ /** Whether a game behaviour's C# class declares a serialized field of that name. */
35
+ declares?: (type: string, field: string) => boolean;
36
+ /** The first scene gets the UI's EventSystem, kept across scenes (needs com.unity.ugui). */
37
+ eventSystem?: boolean;
38
+ }
39
+ export interface Twins {
40
+ /** Text by the twin's path in the Unity project: `Assets/Prefabs/Crate.uprefab`. */
41
+ files: Map<string, string>;
42
+ assets: TwinAssets;
43
+ warnings: string[];
44
+ }
45
+ /** A twin's path: the asset's, with `.prefab` → `.uprefab` and `.unity` → `.uscene`. */
46
+ export declare const twinPath: (asset: string) => string;
47
+ export declare function twins(data: UnityExport, options?: TwinOptions): Twins;
48
+ /**
49
+ * Unity's Euler angles for a quaternion, in degrees: Quaternion.Euler(x, y, z) turns about z, then x,
50
+ * then y — a matrix Ry·Rx·Rz, three's order 'YXZ' read in Unity's own space.
51
+ */
52
+ export declare function eulerAngles([x, y, z, w]: number[]): number[];