create-threenative 0.2.4 → 0.2.6

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.
Files changed (58) hide show
  1. package/README.md +23 -1
  2. package/agent-docs/references/assertion-reference.md +40 -1
  3. package/agent-docs/references/capability-reference.md +972 -66
  4. package/agent-docs/references/finding-assets.md +8 -1
  5. package/agent-docs/references/performance-basics.md +114 -0
  6. package/agent-docs/references/rigging-characters.md +51 -0
  7. package/agent-docs/references/webview-ui.md +3 -2
  8. package/agent-files/.agents/skills/ponytail/SKILL.md +68 -0
  9. package/agent-files/.agents/skills/threenative-assets/SKILL.md +8 -0
  10. package/agent-files/.agents/skills/threenative-context/SKILL.md +8 -0
  11. package/agent-files/.agents/skills/threenative-performance/SKILL.md +26 -10
  12. package/agent-files/.claude/hooks/ponytail-context.mjs +51 -0
  13. package/agent-files/.claude/settings.json +38 -0
  14. package/agent-files/.claude/skills/ponytail/SKILL.md +68 -0
  15. package/agent-files/.claude/skills/threenative-assets/SKILL.md +8 -0
  16. package/agent-files/.claude/skills/threenative-context/SKILL.md +8 -0
  17. package/agent-files/.claude/skills/threenative-performance/SKILL.md +26 -10
  18. package/agent-files/.codex/hooks.json +40 -0
  19. package/capabilities.json +1344 -88
  20. package/dist/index.d.ts +10 -1
  21. package/dist/index.js +186 -1
  22. package/dist/threenative.js +660 -150
  23. package/package.json +6 -6
  24. package/template-assets/patches/three@0.185.1.patch +179 -19
  25. package/templates/action-rpg/AGENTS.md +5 -5
  26. package/templates/action-rpg/CLAUDE.md +5 -5
  27. package/templates/action-rpg/package.json +8 -8
  28. package/templates/defense/AGENTS.md +5 -5
  29. package/templates/defense/CLAUDE.md +5 -5
  30. package/templates/defense/package.json +8 -8
  31. package/templates/minimal/AGENTS.md +5 -5
  32. package/templates/minimal/CLAUDE.md +5 -5
  33. package/templates/minimal/package.json +7 -7
  34. package/templates/minimal/threenative.config.ts +1 -0
  35. package/templates/platformer/AGENTS.md +5 -5
  36. package/templates/platformer/CLAUDE.md +5 -5
  37. package/templates/platformer/package.json +9 -9
  38. package/templates/puzzle/AGENTS.md +5 -5
  39. package/templates/puzzle/CLAUDE.md +5 -5
  40. package/templates/puzzle/package.json +8 -8
  41. package/templates/racing/AGENTS.md +5 -5
  42. package/templates/racing/CLAUDE.md +5 -5
  43. package/templates/racing/package.json +8 -8
  44. package/templates/runner/AGENTS.md +5 -5
  45. package/templates/runner/CLAUDE.md +5 -5
  46. package/templates/runner/package.json +8 -8
  47. package/templates/sailing/AGENTS.md +6 -6
  48. package/templates/sailing/CLAUDE.md +6 -6
  49. package/templates/sailing/package.json +8 -8
  50. package/templates/shooter/AGENTS.md +5 -5
  51. package/templates/shooter/CLAUDE.md +5 -5
  52. package/templates/shooter/package.json +8 -8
  53. package/templates/starter/AGENTS.md +8 -8
  54. package/templates/starter/CLAUDE.md +8 -8
  55. package/templates/starter/package.json +9 -9
  56. package/templates/starter/playtests/production-readiness.playtest.json +96 -0
  57. package/templates/starter/src/ui/Hud.tsx +2 -2
  58. package/templates/starter/src/ui/Menu.tsx +5 -1
package/dist/index.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  #!/usr/bin/env node
2
- import { IThreeNativeIconVariants, ThreeNativeOrientation, IThreeNativeBootSplash, ThreeNativeUiRenderer, IThreeNativeAudioConfig, IThreeNativeConfig, IThreeNativeTexturesConfig } from '@threenative/core';
2
+ import { IThreeNativeIconVariants, ThreeNativeOrientation, IThreeNativeBootSplash, ThreeNativeUiRenderer, IThreeNativeAudioConfig, IThreeNativeConfig, IThreeNativeLodConfig, IThreeNativeTexturesConfig } from '@threenative/core';
3
3
 
4
4
  interface IEngineFreshnessVitePlugin {
5
5
  readonly name: string;
@@ -26,6 +26,10 @@ interface IEngineFreshnessVitePlugin {
26
26
  } | string | null;
27
27
  } | null;
28
28
  }): void;
29
+ transform(code: string, id: string): {
30
+ code: string;
31
+ map: null;
32
+ } | null;
29
33
  }
30
34
  /** Content hash of every installed `@threenative/*` package's `dist/`, or null when none is installed. */
31
35
  declare function hashEngineDist(projectRoot: string): string | undefined;
@@ -61,6 +65,9 @@ interface IResolvedThreeNativeConfig {
61
65
  readonly resolutionScale?: number | "auto";
62
66
  readonly antialias?: boolean;
63
67
  readonly alphaAntialiasing?: boolean;
68
+ readonly projection?: boolean;
69
+ readonly minimumProjectedPixels?: number | false;
70
+ readonly matrixWorld?: "visible" | "all";
64
71
  readonly android?: {
65
72
  readonly resolutionScale?: number | "auto";
66
73
  readonly antialias?: boolean;
@@ -77,6 +84,8 @@ interface IResolvedThreeNativeConfig {
77
84
  readonly exclude?: readonly string[];
78
85
  /** The bound on how many workers a bake may use; absent means the driver's default. */
79
86
  readonly concurrency?: number;
87
+ /** Validated, not yet resolved: per-asset resolution happens where the asset is known. */
88
+ readonly lod?: boolean | IThreeNativeLodConfig;
80
89
  readonly models?: "none" | IThreeNativeModelsConfig;
81
90
  readonly output?: string;
82
91
  readonly source?: string;
package/dist/index.js CHANGED
@@ -391,6 +391,11 @@ function serverEntryPath(server) {
391
391
  }
392
392
  return entry;
393
393
  }
394
+ var DECODER_LOADER_ID = /[/\\]examples[/\\]jsm[/\\]loaders[/\\](?:KTX2Loader|DRACOLoader)\.js$/u;
395
+ var DECODER_LIB_ASSET_URL = /new URL\(\s*(['"])\.\.\/libs\/([^'"]+)\1\s*,\s*import\.meta\.url\s*\)(?:\.toString\s*\(\s*\)|\.href\s*)?/gu;
396
+ function rewriteDecoderAssetUrls(code) {
397
+ return code.replace(DECODER_LIB_ASSET_URL, '"../libs/$2"');
398
+ }
394
399
  var MARKER_RELATIVE = path5.join("node_modules", ".vite", "threenative-engine-build.json");
395
400
  function hashTree(hash, directory) {
396
401
  const entries = readdirSync(directory, { withFileTypes: true }).sort(
@@ -475,6 +480,11 @@ function createEngineFreshnessPlugin() {
475
480
  }
476
481
  return { resolve, optimizeDeps: { force: true } };
477
482
  },
483
+ transform(code, id) {
484
+ if (!DECODER_LOADER_ID.test(id)) return null;
485
+ const rewritten = rewriteDecoderAssetUrls(code);
486
+ return rewritten === code ? null : { code: rewritten, map: null };
487
+ },
478
488
  configureServer(server) {
479
489
  const root = rootOf(server.config);
480
490
  const file = markerPath(root);
@@ -1059,7 +1069,7 @@ var UI_RENDERERS = ["native", "web"];
1059
1069
  function validateUi(raw) {
1060
1070
  const ui = assertRecord(raw, "ui");
1061
1071
  assertKeys(ui, "ui", ["renderer"]);
1062
- const renderer = ui.renderer === void 0 ? "native" : ui.renderer;
1072
+ const renderer = ui.renderer === void 0 ? "web" : ui.renderer;
1063
1073
  if (typeof renderer !== "string" || !UI_RENDERERS.includes(renderer)) {
1064
1074
  fail("TN_CONFIG_UI_RENDERER_INVALID", "ui.renderer must be web or native.");
1065
1075
  }
@@ -1072,6 +1082,9 @@ function validateRenderer(raw) {
1072
1082
  "resolutionScale",
1073
1083
  "antialias",
1074
1084
  "alphaAntialiasing",
1085
+ "projection",
1086
+ "minimumProjectedPixels",
1087
+ "matrixWorld",
1075
1088
  "android"
1076
1089
  ]);
1077
1090
  const android = assertRecord(renderer.android, "renderer.android");
@@ -1100,6 +1113,15 @@ function validateRenderer(raw) {
1100
1113
  android.alphaAntialiasing,
1101
1114
  "renderer.android.alphaAntialiasing"
1102
1115
  );
1116
+ const projection = booleanOrUndefined(renderer.projection, "renderer.projection");
1117
+ const minimumProjectedPixels = numberOrFalse(
1118
+ renderer.minimumProjectedPixels,
1119
+ "renderer.minimumProjectedPixels"
1120
+ );
1121
+ const matrixWorld = renderer.matrixWorld;
1122
+ if (matrixWorld !== void 0 && matrixWorld !== "visible" && matrixWorld !== "all") {
1123
+ fail("TN_CONFIG_RENDERER_INVALID", 'renderer.matrixWorld must be "visible" or "all".');
1124
+ }
1103
1125
  const androidOverrides = {
1104
1126
  ...androidResolutionScale === void 0 ? {} : { resolutionScale: androidResolutionScale },
1105
1127
  ...androidAntialias === void 0 ? {} : { antialias: androidAntialias },
@@ -1114,6 +1136,9 @@ function validateRenderer(raw) {
1114
1136
  ),
1115
1137
  ...antialias === void 0 ? {} : { antialias },
1116
1138
  ...alphaAntialiasing === void 0 ? {} : { alphaAntialiasing },
1139
+ ...projection === void 0 ? {} : { projection },
1140
+ ...minimumProjectedPixels === void 0 ? {} : { minimumProjectedPixels },
1141
+ ...matrixWorld === void 0 ? {} : { matrixWorld },
1117
1142
  ...resolutionScale === void 0 ? {} : { resolutionScale },
1118
1143
  ...Object.keys(androidOverrides).length === 0 ? {} : { android: androidOverrides }
1119
1144
  };
@@ -1123,6 +1148,13 @@ function booleanOrUndefined(value, name) {
1123
1148
  if (typeof value !== "boolean") fail("TN_CONFIG_RENDERER_INVALID", `${name} must be a boolean.`);
1124
1149
  return value;
1125
1150
  }
1151
+ function numberOrFalse(value, name) {
1152
+ if (value === void 0 || value === false) return value;
1153
+ if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
1154
+ fail("TN_CONFIG_RENDERER_INVALID", `${name} must be false or a positive finite number.`);
1155
+ }
1156
+ return value;
1157
+ }
1126
1158
  var ASSET_TARGET_KEYS = [
1127
1159
  "maxMaterials",
1128
1160
  "maxTriangles",
@@ -1341,6 +1373,156 @@ function validateModels(raw) {
1341
1373
  ...virtual === void 0 ? {} : { virtual }
1342
1374
  };
1343
1375
  }
1376
+ var LOD_PRESETS = ["aggressive", "balanced", "quality"];
1377
+ var LOD_MIN_TRIANGLES_SCOPES = ["primitive", "asset"];
1378
+ var LOD_KEYS = ["enabled", "generation", "overrides", "preset", "runtime"];
1379
+ var LOD_GENERATION_KEYS = [
1380
+ "errorTargets",
1381
+ "join",
1382
+ "maxLevels",
1383
+ "minSaving",
1384
+ "minTriangles",
1385
+ "minTrianglesScope"
1386
+ ];
1387
+ var LOD_RUNTIME_KEYS = ["hysteresis", "maxPixelError"];
1388
+ var LOD_OVERRIDE_KEYS = ["enabled", "generation", "preset", "runtime"];
1389
+ function lodGeneration(raw, label) {
1390
+ const value = assertRecord(raw, label);
1391
+ assertKeys(value, label, LOD_GENERATION_KEYS);
1392
+ const generation = {};
1393
+ if (value.join !== void 0) {
1394
+ if (typeof value.join !== "boolean") {
1395
+ fail("TN_CONFIG_ASSETS_INVALID", `${label}.join must be a boolean.`);
1396
+ }
1397
+ generation.join = value.join;
1398
+ }
1399
+ if (value.maxLevels !== void 0) {
1400
+ if (!Number.isSafeInteger(value.maxLevels) || value.maxLevels < 1 || value.maxLevels > 8) {
1401
+ fail("TN_CONFIG_ASSETS_INVALID", `${label}.maxLevels must be an integer between 1 and 8.`);
1402
+ }
1403
+ generation.maxLevels = value.maxLevels;
1404
+ }
1405
+ if (value.minTriangles !== void 0) {
1406
+ generation.minTriangles = positiveInteger(
1407
+ value.minTriangles,
1408
+ 1,
1409
+ "TN_CONFIG_ASSETS_INVALID",
1410
+ `${label}.minTriangles`
1411
+ );
1412
+ }
1413
+ if (value.minTrianglesScope !== void 0) {
1414
+ if (typeof value.minTrianglesScope !== "string" || !LOD_MIN_TRIANGLES_SCOPES.includes(value.minTrianglesScope)) {
1415
+ fail(
1416
+ "TN_CONFIG_ASSETS_INVALID",
1417
+ `${label}.minTrianglesScope must be one of ${LOD_MIN_TRIANGLES_SCOPES.join(", ")}.`
1418
+ );
1419
+ }
1420
+ generation.minTrianglesScope = value.minTrianglesScope;
1421
+ }
1422
+ if (value.minSaving !== void 0) {
1423
+ if (typeof value.minSaving !== "number" || !Number.isFinite(value.minSaving) || value.minSaving < 0 || value.minSaving >= 1) {
1424
+ fail("TN_CONFIG_ASSETS_INVALID", `${label}.minSaving must be a finite number in [0, 1).`);
1425
+ }
1426
+ generation.minSaving = value.minSaving;
1427
+ }
1428
+ if (value.errorTargets !== void 0) {
1429
+ const targets = value.errorTargets;
1430
+ if (!Array.isArray(targets) || targets.length === 0 || targets.length > 16) {
1431
+ fail(
1432
+ "TN_CONFIG_ASSETS_INVALID",
1433
+ `${label}.errorTargets must be 1 to 16 geometric-error targets.`
1434
+ );
1435
+ }
1436
+ let previous = -1;
1437
+ for (const target of targets) {
1438
+ if (typeof target !== "number" || !Number.isFinite(target) || target <= 0) {
1439
+ fail("TN_CONFIG_ASSETS_INVALID", `${label}.errorTargets must be positive finite numbers.`);
1440
+ }
1441
+ if (target <= previous) {
1442
+ fail("TN_CONFIG_ASSETS_INVALID", `${label}.errorTargets must increase strictly.`);
1443
+ }
1444
+ previous = target;
1445
+ }
1446
+ generation.errorTargets = [...targets];
1447
+ }
1448
+ return generation;
1449
+ }
1450
+ function lodRuntime(raw, label) {
1451
+ const value = assertRecord(raw, label);
1452
+ assertKeys(value, label, LOD_RUNTIME_KEYS);
1453
+ const runtime = {};
1454
+ if (value.maxPixelError !== void 0) {
1455
+ if (typeof value.maxPixelError !== "number" || !Number.isFinite(value.maxPixelError) || value.maxPixelError <= 0) {
1456
+ fail("TN_CONFIG_ASSETS_INVALID", `${label}.maxPixelError must be a positive finite number.`);
1457
+ }
1458
+ runtime.maxPixelError = value.maxPixelError;
1459
+ }
1460
+ if (value.hysteresis !== void 0) {
1461
+ if (typeof value.hysteresis !== "number" || !Number.isFinite(value.hysteresis) || value.hysteresis < 0 || value.hysteresis >= 0.5) {
1462
+ fail("TN_CONFIG_ASSETS_INVALID", `${label}.hysteresis must be a finite number in [0, 0.5).`);
1463
+ }
1464
+ runtime.hysteresis = value.hysteresis;
1465
+ }
1466
+ return runtime;
1467
+ }
1468
+ function lodPreset(raw, label) {
1469
+ if (typeof raw !== "string" || !LOD_PRESETS.includes(raw)) {
1470
+ fail("TN_CONFIG_ASSETS_INVALID", `${label} must be one of ${LOD_PRESETS.join(", ")}.`);
1471
+ }
1472
+ return raw;
1473
+ }
1474
+ function lodOverride(raw, label) {
1475
+ if (typeof raw === "boolean") return raw;
1476
+ const value = assertRecord(raw, label);
1477
+ assertKeys(value, label, LOD_OVERRIDE_KEYS);
1478
+ return {
1479
+ ...value.enabled === void 0 ? {} : {
1480
+ enabled: booleanValue(
1481
+ value.enabled,
1482
+ true,
1483
+ "TN_CONFIG_ASSETS_INVALID",
1484
+ `${label}.enabled`
1485
+ )
1486
+ },
1487
+ ...value.generation === void 0 ? {} : { generation: lodGeneration(value.generation, `${label}.generation`) },
1488
+ ...value.preset === void 0 ? {} : { preset: lodPreset(value.preset, `${label}.preset`) },
1489
+ ...value.runtime === void 0 ? {} : { runtime: lodRuntime(value.runtime, `${label}.runtime`) }
1490
+ };
1491
+ }
1492
+ function validateLod(raw) {
1493
+ if (typeof raw === "boolean") return raw;
1494
+ const value = assertRecord(raw, "assets.lod");
1495
+ assertKeys(value, "assets.lod", LOD_KEYS);
1496
+ const overrides = {};
1497
+ if (value.overrides !== void 0) {
1498
+ if (!isRecord(value.overrides)) {
1499
+ fail("TN_CONFIG_ASSETS_INVALID", "assets.lod.overrides must be an object.");
1500
+ }
1501
+ for (const [key, entry] of Object.entries(value.overrides)) {
1502
+ if (key.trim() === "") {
1503
+ fail(
1504
+ "TN_CONFIG_ASSETS_INVALID",
1505
+ "assets.lod.overrides keys must be non-empty source asset paths."
1506
+ );
1507
+ }
1508
+ overrides[key] = lodOverride(entry, `assets.lod.overrides['${key}']`);
1509
+ }
1510
+ }
1511
+ return {
1512
+ ...value.enabled === void 0 ? {} : {
1513
+ enabled: booleanValue(
1514
+ value.enabled,
1515
+ true,
1516
+ "TN_CONFIG_ASSETS_INVALID",
1517
+ "assets.lod.enabled"
1518
+ )
1519
+ },
1520
+ ...value.generation === void 0 ? {} : { generation: lodGeneration(value.generation, "assets.lod.generation") },
1521
+ ...Object.keys(overrides).length === 0 ? {} : { overrides },
1522
+ ...value.preset === void 0 ? {} : { preset: lodPreset(value.preset, "assets.lod.preset") },
1523
+ ...value.runtime === void 0 ? {} : { runtime: lodRuntime(value.runtime, "assets.lod.runtime") }
1524
+ };
1525
+ }
1344
1526
  function validateBudget(raw) {
1345
1527
  const limit = (value) => value === "none" || typeof value === "number" && Number.isSafeInteger(value) && value > 0;
1346
1528
  if (limit(raw)) return raw;
@@ -1369,6 +1551,7 @@ function validateAssets(raw) {
1369
1551
  "budget",
1370
1552
  "exclude",
1371
1553
  "concurrency",
1554
+ "lod",
1372
1555
  "models",
1373
1556
  "source",
1374
1557
  "output",
@@ -1376,6 +1559,7 @@ function validateAssets(raw) {
1376
1559
  "textures"
1377
1560
  ]);
1378
1561
  const targets = assets.targets === void 0 ? void 0 : validateAssetTargets(assets.targets);
1562
+ const lod = assets.lod === void 0 ? void 0 : validateLod(assets.lod);
1379
1563
  const models = assets.models === void 0 ? void 0 : validateModels(assets.models);
1380
1564
  const textures = assets.textures === void 0 ? void 0 : validateTextures(assets.textures);
1381
1565
  if (assets.exclude !== void 0 && (!Array.isArray(assets.exclude) || assets.exclude.some((glob) => typeof glob !== "string" || glob.trim() === ""))) {
@@ -1399,6 +1583,7 @@ function validateAssets(raw) {
1399
1583
  ...assets.source === void 0 ? {} : { source: nonEmptyString(assets.source, "TN_CONFIG_ASSETS_INVALID", "assets.source") },
1400
1584
  ...assets.output === void 0 ? {} : { output: nonEmptyString(assets.output, "TN_CONFIG_ASSETS_INVALID", "assets.output") },
1401
1585
  ...targets === void 0 ? {} : { targets },
1586
+ ...lod === void 0 ? {} : { lod },
1402
1587
  ...models === void 0 ? {} : { models },
1403
1588
  ...textures === void 0 ? {} : { textures }
1404
1589
  };