@wildshard/engine 0.1.18 → 0.1.20

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 (334) hide show
  1. package/CHANGELOG.md +16 -0
  2. package/budgets/shard-size-baseline.json +10 -4
  3. package/index.html +6 -4
  4. package/lint/engine-sides.json +18 -0
  5. package/lint/ratchet.json +0 -68
  6. package/lint/ratchet.mjs +1 -4
  7. package/package.json +19 -15
  8. package/scripts/agent-sync.mjs +27 -8
  9. package/scripts/app-build/appCook.ts +8 -2
  10. package/scripts/app-build/catalogue.ts +10 -7
  11. package/scripts/app-build/gen.ts +33 -2
  12. package/scripts/app-build/isolation.d.mts +10 -0
  13. package/scripts/app-build/isolation.mjs +47 -0
  14. package/scripts/app-build/outputProducts.mjs +4 -0
  15. package/scripts/app-build/previousDeploy.d.mts +2 -0
  16. package/scripts/app-build/previousDeploy.mjs +10 -1
  17. package/scripts/app-build/serviceWorker.ts +10 -3
  18. package/scripts/app-build/splitOutput.mjs +4 -2
  19. package/scripts/app-build/standaloneOutput.d.mts +1 -1
  20. package/scripts/app-build/standaloneOutput.mjs +5 -3
  21. package/scripts/app-build/titlePreloads.d.mts +8 -0
  22. package/scripts/app-build/titlePreloads.mjs +69 -0
  23. package/scripts/app-build/worldMapAtlas.ts +10 -6
  24. package/scripts/app-build-pipeline.mjs +31 -3
  25. package/scripts/built-product.mjs +1 -1
  26. package/scripts/cell-mem-bench.mjs +83 -23
  27. package/scripts/check-custom-sections-zero.mjs +1 -1
  28. package/scripts/check-devserver.mjs +2 -0
  29. package/scripts/check-models.mjs +2 -0
  30. package/scripts/check-paths.allow.json +0 -115
  31. package/scripts/check-paths.mjs +2 -2
  32. package/scripts/check-platform-ratchets.mjs +2 -3
  33. package/scripts/chromium-keychain.d.mts +1 -1
  34. package/scripts/ci-static.sh +1 -1
  35. package/scripts/committed-fast-checks.mjs +0 -2
  36. package/scripts/content-sw-proof.mjs +2 -1
  37. package/scripts/cook-worker.mjs +9 -3
  38. package/scripts/cook.mjs +18 -5
  39. package/scripts/docs-inputs-proof.mjs +6 -6
  40. package/scripts/e7-voice-staging-proof.mjs +1 -1
  41. package/scripts/gate-related-tests.mjs +1 -1
  42. package/scripts/git-source-view.mjs +1 -1
  43. package/scripts/goldens/capture.mjs +17 -5
  44. package/scripts/grid-crossing-nightly.mjs +59 -0
  45. package/scripts/grid-crossing-qa.mjs +44 -0
  46. package/scripts/grid-crossing-ratchet.d.mts +6 -0
  47. package/scripts/grid-crossing-ratchet.mjs +52 -0
  48. package/scripts/grid-crossing-report.mjs +122 -0
  49. package/scripts/grid-crossing-stages.mjs +47 -0
  50. package/scripts/grid-crossing-tour.mjs +284 -0
  51. package/scripts/grid-crossing-walk-proof.mjs +126 -17
  52. package/scripts/host-ruler/roots.mjs +2 -2
  53. package/scripts/host-ruler.d.mts +91 -0
  54. package/scripts/host-ruler.mjs +565 -0
  55. package/scripts/land.mjs +2 -1
  56. package/scripts/live-prepush.py +3 -5
  57. package/scripts/loading-flow/benchmax.mjs +37 -12
  58. package/scripts/loading-flow/deskbench.mjs +276 -0
  59. package/scripts/loading-flow/stalls.d.mts +17 -3
  60. package/scripts/loading-flow/stalls.mjs +82 -3
  61. package/scripts/look-loop/test_look_loop.py +1 -38
  62. package/scripts/memory-proof.mjs +61 -6
  63. package/scripts/mmo-bots.mjs +8 -2
  64. package/scripts/net-lag-proof.mjs +219 -0
  65. package/scripts/night-market-kit-budget.mjs +2 -2
  66. package/scripts/nightly-model.ts +9 -6
  67. package/scripts/offline-proof-rules.d.mts +2 -2
  68. package/scripts/offline-proof-rules.mjs +15 -4
  69. package/scripts/offline-proof.mjs +80 -13
  70. package/scripts/{shard-platform-output.mjs → output-reader.mjs} +1 -1
  71. package/scripts/page-release/content.d.mts +9 -1
  72. package/scripts/page-release/content.mjs +131 -17
  73. package/scripts/page-release/flow.mjs +36 -10
  74. package/scripts/page-release/stamp-content.mjs +24 -0
  75. package/scripts/page-release.mjs +28 -6
  76. package/scripts/page-size.mjs +2 -1
  77. package/scripts/parity/boot-smoke.mjs +13 -2
  78. package/scripts/pin-format.ts +5 -2
  79. package/scripts/pin-packs.ts +1 -1
  80. package/scripts/pins-reuse.d.mts +1 -0
  81. package/scripts/pins-reuse.mjs +22 -0
  82. package/scripts/pins.ts +4 -4
  83. package/scripts/precommit-checks.mjs +1 -7
  84. package/scripts/precommit-jobs.mjs +0 -1
  85. package/scripts/precommit-source.py +1 -9
  86. package/scripts/program-discovery.mjs +1 -1
  87. package/scripts/ring-cook.mjs +2 -1
  88. package/scripts/ring-step.ts +1 -1
  89. package/scripts/scratch-dir.mjs +95 -0
  90. package/scripts/scratch-sweep.mjs +182 -0
  91. package/scripts/script-scenario-metrics.mjs +1 -1
  92. package/scripts/shard-output-content.d.mts +1 -1
  93. package/scripts/shard-output-content.mjs +2 -2
  94. package/scripts/shard-outputs.mjs +1 -1
  95. package/scripts/shard-public.mjs +1 -1
  96. package/scripts/shard-wire-meter.mjs +24 -9
  97. package/scripts/side-parity.mjs +4 -2
  98. package/scripts/standalone-smoke.mjs +8 -3
  99. package/scripts/tier-textures.mjs +22 -4
  100. package/scripts/tile-bake-report.mjs +1 -1
  101. package/scripts/tile-bakes.mjs +1 -1
  102. package/scripts/title-assets.generated.json +2 -0
  103. package/scripts/tsconfig.json +2 -14
  104. package/scripts/vendor/basisu/LICENSE +201 -0
  105. package/scripts/vendor/basisu/basis_encoder.cjs +2 -0
  106. package/scripts/vendor/basisu/basis_encoder.wasm +0 -0
  107. package/scripts/vitest-push-guards.config.ts +1 -1
  108. package/scripts/vps/harden-apply.sh +4 -1
  109. package/scripts/vps/harden-prometheus.sh +179 -0
  110. package/scripts/vps/harden.sh +16 -0
  111. package/scripts/vps/rebuild.sh +18 -0
  112. package/scripts/vps/wildshard-config +6 -2
  113. package/scripts/worker-client-play.mjs +6 -2
  114. package/scripts/worktree-reap.mjs +59 -13
  115. package/scripts/worktree.mjs +19 -5
  116. package/src/.oxlintrc.json +3 -182
  117. package/src/client/app/entry.ts +10 -2
  118. package/src/client/engine/anim/rigParser.ts +2 -2
  119. package/src/client/engine/boot/bootCache.ts +2 -2
  120. package/src/client/engine/boot/bootTrace.ts +12 -4
  121. package/src/client/engine/boot/browserChunkRecovery.ts +4 -0
  122. package/src/client/engine/boot/clearDownloads.ts +5 -2
  123. package/src/client/engine/boot/contentRead.ts +11 -0
  124. package/src/client/engine/boot/gpuFiles.ts +4 -2
  125. package/src/client/engine/boot/lastEnd.ts +99 -12
  126. package/src/client/engine/boot/texturePack.ts +2 -2
  127. package/src/client/engine/core/Game.ts +63 -19
  128. package/src/client/engine/core/gpuOnly.ts +10 -0
  129. package/src/client/engine/core/renderBudget.ts +134 -0
  130. package/src/client/engine/net/netPlayer.ts +19 -2
  131. package/src/client/engine/net/otherPlayers.ts +55 -8
  132. package/src/client/engine/net/predictor.ts +33 -9
  133. package/src/client/engine/net/redial.ts +68 -10
  134. package/src/client/engine/pwa/cacheNames.ts +58 -1
  135. package/src/client/engine/pwa/sw.js +41 -11
  136. package/src/client/engine/render/dataLook.ts +219 -44
  137. package/src/client/engine/render/families/detail.ts +89 -0
  138. package/src/client/engine/render/families/pbr.ts +9 -1
  139. package/src/client/engine/render/families/registry.ts +11 -2
  140. package/src/client/engine/render/families/sceneSurface.ts +116 -0
  141. package/src/client/engine/render/look.ts +12 -0
  142. package/src/client/engine/render/lookLight.ts +103 -11
  143. package/src/client/engine/render/lookRender.ts +105 -0
  144. package/src/client/engine/render/precompile.ts +4 -2
  145. package/src/client/engine/render/tiers.ts +4 -1
  146. package/src/client/engine/saves/indexed.ts +2 -2
  147. package/src/client/engine/telemetry/browserErrors.ts +24 -3
  148. package/src/client/engine/telemetry/staleBuildReport.ts +22 -1
  149. package/src/client/engine/ui/debugOptions.ts +1 -1
  150. package/src/client/engine/ui/lookLightOption.ts +10 -6
  151. package/src/client/engine/ui/namePrompt.ts +7 -0
  152. package/src/client/engine/world/declaredProps.ts +5 -1
  153. package/src/client/engine/world/skyRig.ts +4 -1
  154. package/src/client/engine/world/terrainTileView.ts +64 -23
  155. package/src/client/game/boot/audio.generated.ts +114 -114
  156. package/src/client/game/boot/bytes.generated.ts +118 -220
  157. package/src/client/game/boot/placedSpawn.ts +35 -0
  158. package/src/client/game/boot/spawnDownload.ts +25 -6
  159. package/src/client/game/boot/versions.generated.ts +7 -5
  160. package/src/client/game/devScene/hook.ts +428 -0
  161. package/src/client/game/devScene/liveLook.ts +21 -0
  162. package/src/client/game/grid/cellLoading.ts +12 -2
  163. package/src/client/game/grid/live.ts +152 -19
  164. package/src/client/game/grid/liveSession.ts +53 -3
  165. package/src/client/game/grid/mapAtlas.ts +18 -4
  166. package/src/client/game/grid/minimapBlend.ts +15 -5
  167. package/src/client/game/grid/oneWayIn.ts +5 -1
  168. package/src/client/game/grid/pageEntry.ts +12 -1
  169. package/src/client/game/grid/placedCells.ts +114 -12
  170. package/src/client/game/grid/placedContent.ts +85 -0
  171. package/src/client/game/grid/prefetch.ts +9 -1
  172. package/src/client/game/grid/productInputs.ts +23 -10
  173. package/src/client/game/grid/productLeases.ts +4 -1
  174. package/src/client/game/grid/products.ts +8 -4
  175. package/src/client/game/grid/roadLook.ts +24 -15
  176. package/src/client/game/grid/roadLookPlatform.ts +4 -2
  177. package/src/client/game/grid/roadResources.ts +24 -0
  178. package/src/client/game/grid/roadSign.worker.ts +4 -3
  179. package/src/client/game/grid/roadSignPaint.ts +16 -5
  180. package/src/client/game/grid/roadSignPreparation.ts +4 -3
  181. package/src/client/game/grid/roadSignScale.ts +8 -0
  182. package/src/client/game/grid/roadTileCapture.worker.ts +3 -1
  183. package/src/client/game/grid/roadTileCaptureWorker.ts +2 -1
  184. package/src/client/game/grid/roadTileWrite.worker.ts +4 -2
  185. package/src/client/game/grid/roadTileWriter.ts +2 -1
  186. package/src/client/game/grid/screenReports.ts +39 -0
  187. package/src/client/game/grid/session.ts +32 -7
  188. package/src/client/game/grid/softWallLook.ts +25 -8
  189. package/src/client/game/mainMenu.ts +6 -2
  190. package/src/client/game/plugin/context.ts +2 -1
  191. package/src/client/game/plugin/followedMovers.ts +7 -1
  192. package/src/client/game/quest/figures.ts +2 -0
  193. package/src/client/game/session/finish.ts +9 -0
  194. package/src/client/game/shardfile/assetCache.ts +4 -4
  195. package/src/client/game/shardfile/client.ts +28 -8
  196. package/src/client/game/shardfile/clientAssets.ts +9 -5
  197. package/src/client/game/shardfile/clientLibrary.ts +1 -1
  198. package/src/client/game/shardfile/clientPropMaterials.ts +4 -1
  199. package/src/client/game/shardfile/clientViews.ts +36 -8
  200. package/src/client/game/shardfile/clientWater.ts +51 -9
  201. package/src/client/game/shardfile/clientWorker.ts +19 -7
  202. package/src/client/game/shardfile/constructionCheckpoint.ts +2 -2
  203. package/src/client/game/shardfile/groundMerge.ts +57 -5
  204. package/src/client/game/shardfile/hybrid.ts +2 -0
  205. package/src/client/game/shardfile/look.ts +8 -3
  206. package/src/client/game/shardfile/product.ts +34 -7
  207. package/src/client/game/shardfile/productChecks.ts +2 -2
  208. package/src/client/game/shardfile/productCost.ts +2 -2
  209. package/src/client/game/shardfile/readAsset.ts +2 -2
  210. package/src/client/game/shardfile/reflectingWater.ts +73 -0
  211. package/src/client/game/shardfile/seatGrace.ts +9 -0
  212. package/src/client/game/shardfile/skinPlayback.ts +1 -1
  213. package/src/client/game/shardfile/slabLibrary.ts +115 -49
  214. package/src/client/game/shardfile/tileContent.ts +1 -1
  215. package/src/client/game/shardfile/tileDriver.ts +38 -11
  216. package/src/client/game/shardfile/wirePage.ts +7 -3
  217. package/src/client/game/shardfile/worldScenes.ts +17 -10
  218. package/src/client/game/systems/npc/figureRows.ts +9 -0
  219. package/src/client/host/online/doctor.ts +22 -7
  220. package/src/client/host/online/doctorView.ts +2 -0
  221. package/src/client/host/online/linkScreens.ts +109 -5
  222. package/src/client/host/online/shell.ts +13 -4
  223. package/src/client/host/standalone/shell.ts +40 -0
  224. package/src/cook/game/astc6Encode.ts +55 -0
  225. package/src/cook/game/astc6Wasm.ts +176 -0
  226. package/src/cook/game/cookJob.ts +30 -6
  227. package/src/cook/game/cookWorker.ts +38 -11
  228. package/src/cook/game/entryTotals.ts +51 -24
  229. package/src/cook/game/shardCook.ts +35 -7
  230. package/src/cook/game/spawnParts.ts +33 -8
  231. package/src/cook/game/tierTextures.ts +87 -14
  232. package/src/server/engine/ai/bossContenders.ts +27 -3
  233. package/src/server/engine/ai/phases.ts +1 -1
  234. package/src/server/engine/entities/creatureRefill.ts +9 -2
  235. package/src/server/engine/net/ledgerBook.ts +2 -0
  236. package/src/server/engine/net/room.ts +15 -0
  237. package/src/server/engine/sim/respawn.ts +8 -0
  238. package/src/server/game/boss/arenaRoomEntry.ts +5 -1
  239. package/src/server/game/boss/arenaRoomNative.ts +2 -0
  240. package/src/server/game/boss/native.ts +2 -1
  241. package/src/server/game/boss/nativeWake.ts +9 -5
  242. package/src/server/game/boss/openArenaNative.ts +2 -2
  243. package/src/server/game/boss/openArenaRoom.ts +3 -1
  244. package/src/server/game/grid/room.ts +44 -3
  245. package/src/server/game/grid/simulation.ts +23 -0
  246. package/src/server/game/population/mixedRoster.ts +11 -3
  247. package/src/server/game/population/nativeBake.ts +8 -3
  248. package/src/server/game/population/nativeReturns.ts +6 -3
  249. package/src/server/game/population/roster.ts +5 -3
  250. package/src/server/game/quest/eliteDrops.ts +18 -3
  251. package/src/server/game/quest/nativeChapter.ts +1 -1
  252. package/src/server/game/quest/nativeComposition.ts +5 -1
  253. package/src/server/game/riding/nativeTaming.ts +22 -7
  254. package/src/server/game/riding/wildRefill.ts +3 -2
  255. package/src/server/game/shardfile/bossRow.ts +4 -2
  256. package/src/server/game/shardfile/homeKeeper.ts +4 -2
  257. package/src/server/host/bake/headlessWorker.ts +1 -1
  258. package/src/server/host/dedicated/cellHost.ts +112 -18
  259. package/src/server/host/dedicated/cellProtocol.ts +18 -1
  260. package/src/server/host/dedicated/cellWorker.ts +8 -5
  261. package/src/server/host/dedicated/dedicatedRoom.ts +38 -11
  262. package/src/server/host/dedicated/gridCells.ts +15 -6
  263. package/src/server/host/dedicated/loopLag.ts +21 -0
  264. package/src/server/host/dedicated/main.ts +13 -5
  265. package/src/server/host/dedicated/packReader.ts +3 -3
  266. package/src/server/host/dedicated/placementFile.ts +3 -2
  267. package/src/server/host/dedicated/roadRoom.ts +34 -4
  268. package/src/server/host/dedicated/serverMetrics.ts +135 -0
  269. package/src/server/host/dedicated/socketPump.ts +21 -4
  270. package/src/server/host/dedicated/workerTable.ts +32 -14
  271. package/src/server/host/dedicated/world.ts +65 -7
  272. package/src/server/host/headless.ts +1 -1
  273. package/src/server/host/headlessRuntime.ts +1 -1
  274. package/src/server/host/standalone/roadWorld.ts +15 -3
  275. package/src/server/host/standalone/serverHost.ts +57 -8
  276. package/src/server/host/standalone/serverProduct.ts +48 -16
  277. package/src/server/host/standalone/serverRuntime.ts +1 -1
  278. package/src/shared/engine/ai/BossBrain.ts +8 -0
  279. package/src/shared/engine/core/framePacing.ts +12 -1
  280. package/src/shared/engine/physics/terrainTiles.ts +20 -4
  281. package/src/shared/game/boss/wake.ts +6 -0
  282. package/src/shared/game/devColliders.ts +107 -0
  283. package/src/shared/game/devGameplay.ts +41 -0
  284. package/src/shared/game/eliteSystem.ts +8 -0
  285. package/src/shared/game/grid/allocator.ts +3 -0
  286. package/src/shared/game/grid/placementRows.ts +5 -2
  287. package/src/shared/game/plugin/bossRecord.ts +3 -2
  288. package/src/shared/game/shardfile/ktx2Targets.ts +23 -3
  289. package/src/shared/game/shardfile/outputDescriptor.ts +9 -5
  290. package/src/shared/game/shardfile/packReads.ts +28 -3
  291. package/src/shared/game/shardfile/serverPack.ts +9 -0
  292. package/src/shared/game/systems/looks/trampleField.ts +2 -0
  293. package/src/shared/host/formatJsonSchema.ts +2 -2
  294. package/src/tsconfig.json +1 -27
  295. package/lint/host-reviews.json +0 -14
  296. package/lint/listed-view-code.json +0 -13
  297. package/lint/platform-pending-users.json +0 -2520
  298. package/lint/platform-pending-users.md +0 -18
  299. package/scripts/cell-mem/metrics-preload.mjs +0 -65
  300. package/scripts/check-closed-components.d.mts +0 -7
  301. package/scripts/check-closed-components.mjs +0 -87
  302. package/scripts/g571-hosts.d.mts +0 -3
  303. package/scripts/g571-hosts.mjs +0 -54
  304. package/scripts/host-ruler/register-migrate.mjs +0 -242
  305. package/scripts/listed-view-code.d.mts +0 -7
  306. package/scripts/listed-view-code.mjs +0 -93
  307. package/scripts/look-loop/fit-lut.py +0 -142
  308. package/scripts/look-loop/palette-delta.py +0 -183
  309. package/scripts/look-loop/regions/driftwood-isle.json +0 -25
  310. package/scripts/look-loop/regions/far-reach.json +0 -225
  311. package/scripts/look-loop/regions/open-plot-night-market.json +0 -855
  312. package/scripts/look-loop/regions/pine-hollow.json +0 -22
  313. package/scripts/look-loop/regions/sunscar-dunes.json +0 -281
  314. package/scripts/platform-chargebacks.d.mts +0 -9
  315. package/scripts/platform-chargebacks.mjs +0 -135
  316. package/scripts/shard-component-spans.d.mts +0 -15
  317. package/scripts/shard-component-spans.mjs +0 -18
  318. package/scripts/shard-components.d.mts +0 -16
  319. package/scripts/shard-components.mjs +0 -363
  320. package/scripts/shard-platform-hosts.d.mts +0 -2
  321. package/scripts/shard-platform-hosts.mjs +0 -93
  322. package/scripts/shard-platform-sections.d.mts +0 -2
  323. package/scripts/shard-platform-sections.mjs +0 -9
  324. package/scripts/shard-platform.d.mts +0 -76
  325. package/scripts/shard-platform.mjs +0 -1072
  326. package/src/.oxfmtrc.json +0 -48
  327. package/src/scripts/ask-new.sh +0 -29
  328. package/src/scripts/asks.mjs +0 -142
  329. package/src/scripts/herdr-prompt.sh +0 -34
  330. package/src/scripts/herdr-question-open.sh +0 -67
  331. package/src/scripts/md-wrap.mjs +0 -229
  332. /package/scripts/{shard-platform-format.d.mts → node-format.d.mts} +0 -0
  333. /package/scripts/{shard-platform-format.mjs → node-format.mjs} +0 -0
  334. /package/scripts/{shard-platform-output.d.mts → output-reader.d.mts} +0 -0
@@ -0,0 +1,428 @@
1
+ import * as THREE from 'three';
2
+ import type { Scope } from '@wildshard/engine/app/scope';
3
+ import type { Physics } from '@wildshard/engine/physics/Physics';
4
+ import type { LookKey } from '@wildshard/engine/render/dataLook';
5
+ import type { LookStrategy } from '@wildshard/engine/render/look';
6
+ import { lampLights } from '@wildshard/engine/render/lookLight';
7
+ import type { LookLamp } from '@wildshard/format/look-light';
8
+ import type { ShardWater } from '@wildshard/format/water';
9
+ import { installClientWater } from '../shardfile/clientWater';
10
+ import { shardfileLiveLook } from './liveLook';
11
+ import type { Shardfile } from '@wildshard/format/shardSchema';
12
+ import { devGroundHeight, isDevColliders, liftedFeet, swapDevBoxes, type DevBox, type DevGround } from '@wildshard/engine/game/devColliders';
13
+ import { swapTerrainCollider } from '@wildshard/engine/physics/terrainTiles';
14
+ import type { HeightfieldBinding } from '@wildshard/engine/world/Heightfield';
15
+ import { decodeTerrainTile, type TerrainTileData } from '@wildshard/format/terrainTileBytes';
16
+ import { refreshTerrainTile } from '@wildshard/engine/world/terrainTileView';
17
+ import type { DevGameplay, DevPlace, DevRestarted } from '@wildshard/engine/game/devGameplay';
18
+ import { diagnosticNow } from '@wildshard/engine/core/clock';
19
+
20
+ /**
21
+ * SHARD-SOURCE AP5 (J347: engine is the deployed client and server; dev tooling is sharddev's). The dev hook: the one thing
22
+ * a DEVSERVER page carries for `wildshard watch`. sharddev owns the rest, its WebSocket server and protocol, the part diff
23
+ * and a page script `watch` injects into the page it serves; that script owns one scope per part and the swap order, and
24
+ * calls these functions on `window.__wildshardDevHook`:
25
+ *
26
+ * addPart(name, part) draw a new part: meshes, sprites, lamps (the look's lamp lights) and water (the client's water)
27
+ * replacePart(name, part) build the new part first, then dispose the old part's scope, in one call: no frame shows neither
28
+ * removePart(name) dispose the part's scope (its boxes stay: the page script calls swapColliders(name, []))
29
+ * setLook(look) v2 (AP17): the look section in place, as the shardfile would carry it: day keys (sky, fog, sun,
30
+ * ambient), the sun's arc, exposure, tone, vignette and bloom (`shardfileLiveLook`); v1 sent
31
+ * the keys only. True, or false when the page's look can't take it live and the page must reload
32
+ * swapColliders(name, boxes) the part's solid boxes, in the page's world and the in-page server's (the worker, by its
33
+ * harness port), new set first, then the old one goes; a player inside a new box is lifted
34
+ * onto it (v3)
35
+ * setGround(bytes) v3 (AP18): the whole ground as one terrain tile's wire bytes (`encodeTerrainTile`: the 257²
36
+ * heights and colours the shard's tiles and collider are cut from). The page's heightfield
37
+ * collider, its terrain field (`heightAt`) and every drawn ground tile whose samples changed are
38
+ * swapped; the in-page server takes the same heights; a player under the new ground is lifted
39
+ * onto it. True, or false when the page's ground can't take it (the page must reload)
40
+ * restartGameplay(gameplay) v4 (AP19): the shard's quests, encounters, spawns or scripts changed (`DEV_GAMEPLAY_SECTIONS`,
41
+ * the new rows of each). The in-page server saves, puts its world down and boots it again on
42
+ * the new rows from that save, with the player where the page has it; the page's client rejoins
43
+ * it, the held boxes and ground go to it again, and the quest views are built again from the new
44
+ * quest section. Resolves to what ran, or `ok: false` when the page must reload
45
+ *
46
+ * `version` is `DEV_HOOK_VERSION`; sharddev refuses a page with another (its page script) and a client whose build flags
47
+ * say another (`build-flags.json` `devHook`, written by `scripts/app-build-pipeline.mjs`). Bump it on any change to these
48
+ * signatures or to `DevPart`. A production build has none of this: `finish.ts` imports it only behind `__DEVSERVER__`, and
49
+ * `scripts/check-devserver.mjs` refuses a bundle that holds `DEV_HOOK_GLOBAL`.
50
+ */
51
+ export const DEV_HOOK_VERSION = 4;
52
+
53
+ // the in-page server's half of `setGround`, which the standalone shell puts on the window (client/host/standalone/shell.ts)
54
+ declare global { interface Window {
55
+ __workerClientDevGround?: (ground: DevGround) => void;
56
+ /** AP19: the in-page server's soft restart (client/host/standalone/shell.ts) and the quest views' (shardfile/client.ts) */
57
+ __workerClientDevRestart?: (gameplay: DevGameplay, at: DevPlace | null) => Promise<DevRestarted>;
58
+ __shardfileDevQuests?: (quests: NonNullable<DevGameplay['quests']>) => Promise<boolean>;
59
+ } }
60
+ export const DEV_HOOK_GLOBAL = '__wildshardDevHook';
61
+
62
+ export type Rgb = readonly [number, number, number];
63
+
64
+ export interface DevMaterial {
65
+ readonly key: string;
66
+ readonly name: string;
67
+ readonly kind: 'standard' | 'basic' | 'sprite';
68
+ readonly colour: Rgb;
69
+ readonly roughness: number;
70
+ readonly metalness: number;
71
+ readonly emissive: Rgb;
72
+ readonly emissiveIntensity: number;
73
+ /** a `DevTexture` key */
74
+ readonly map: string | null;
75
+ readonly repeat: readonly [number, number];
76
+ readonly offset: readonly [number, number];
77
+ readonly alphaTest: number;
78
+ readonly side: 'front' | 'back' | 'double';
79
+ readonly vertexColours: boolean;
80
+ readonly transparent: boolean;
81
+ readonly opacity: number;
82
+ readonly blending: 'normal' | 'additive';
83
+ readonly depthWrite: boolean;
84
+ readonly fog: boolean;
85
+ }
86
+
87
+ /** One RGBA8 raster, row 0 at v = 0. Immutable by key: a key the hook holds is not uploaded again. */
88
+ export interface DevTexture { readonly key: string; readonly width: number; readonly height: number; readonly colourSpace: 'srgb' | 'linear'; readonly rgba: Uint8Array }
89
+
90
+ /** One geometry in its own frame. Immutable by key, like a texture. */
91
+ export interface DevGeometry {
92
+ readonly key: string;
93
+ readonly position: Float32Array;
94
+ readonly normal: Float32Array;
95
+ readonly uv: Float32Array | null;
96
+ readonly colour: Float32Array | null;
97
+ readonly index: Uint32Array | null;
98
+ }
99
+
100
+ export interface DevDraw {
101
+ readonly geometry: string;
102
+ readonly material: string;
103
+ /** column-major world matrix */
104
+ readonly matrix: readonly number[];
105
+ readonly instances: { readonly count: number; readonly matrices: ArrayLike<number>; readonly colours: ArrayLike<number> | null } | null;
106
+ readonly castShadow: boolean;
107
+ readonly receiveShadow: boolean;
108
+ }
109
+
110
+ export interface DevSprite { readonly material: string; readonly position: readonly [number, number, number]; readonly scale: readonly [number, number]; readonly center: readonly [number, number] }
111
+
112
+ /** One part, decoded: every colour linear, every matrix column-major in world metres. Colliders come by `swapColliders`. */
113
+ export interface DevPart {
114
+ readonly materials: readonly DevMaterial[];
115
+ readonly textures: readonly DevTexture[];
116
+ readonly geometries: readonly DevGeometry[];
117
+ readonly draws: readonly DevDraw[];
118
+ readonly sprites: readonly DevSprite[];
119
+ /** the shardfile's lamp rows (`look.light.lamps`), drawn as the look's lamps are */
120
+ readonly lamps: readonly LookLamp[];
121
+ /** the shardfile's water rows, drawn as the client draws a shard's water */
122
+ readonly water: ShardWater;
123
+ }
124
+
125
+ /** The look a watched page takes live: its day keys, and (v2, AP17) the whole look section the page's shardfile would carry. */
126
+ export interface DevLook { readonly keys: readonly LookKey[]; readonly look?: Shardfile['look'] }
127
+
128
+ export interface DevHook {
129
+ readonly version: number;
130
+ addPart: (name: string, part: DevPart) => void;
131
+ replacePart: (name: string, part: DevPart) => void;
132
+ removePart: (name: string) => void;
133
+ setLook: (look: DevLook) => boolean;
134
+ swapColliders: (name: string, boxes: readonly DevBox[]) => void;
135
+ setGround: (ground: Uint8Array) => boolean;
136
+ restartGameplay: (gameplay: DevGameplay) => Promise<DevRestart>;
137
+ }
138
+
139
+ /** What a soft restart did: the server's world restart and the page's quest views, and how long each took (ms). */
140
+ export interface DevRestart { readonly ok: boolean; readonly serverMs: number; readonly questsMs: number | null; readonly reason?: string }
141
+
142
+ /** The page's player, as a dev swap lifts it out of new solids. */
143
+ export interface DevPlayer { readonly position: { readonly x: number; readonly y: number; readonly z: number }; readonly yaw: number; pitch: number; spawn: (x: number, z: number, yaw: number, y?: number) => void }
144
+
145
+ export interface DevHookPorts {
146
+ readonly scope: Scope;
147
+ readonly scene: THREE.Object3D;
148
+ /** the page's physics world now (the player's prediction): a grid crossing swaps it, so the hook reads it per call;
149
+ * null on a page without one */
150
+ readonly physics: () => Physics | null;
151
+ /** the page's look now */
152
+ readonly look: () => LookStrategy | null;
153
+ /** the in-page server's half of `swapColliders` (the worker page's harness port); null when the page has none */
154
+ readonly server: () => ((name: string, boxes: readonly DevBox[]) => void) | null;
155
+ /** the in-page server's half of `setGround` (v3); null when the page has none */
156
+ readonly serverGround?: () => ((ground: DevGround) => void) | null;
157
+ /** the page's player now, for the lift out of new solids (v3); null on a page without one */
158
+ readonly player?: () => DevPlayer | null;
159
+ /** the page's terrain field now (`captureHeightfield`), which a new ground installs into (v3); absent in a test */
160
+ readonly terrainField?: () => HeightfieldBinding;
161
+ /** the in-page server's soft restart (v4); null when the page has none */
162
+ readonly restart?: () => ((gameplay: DevGameplay, at: DevPlace | null) => Promise<DevRestarted>) | null;
163
+ /** the page's quest views, built again from a new quest section (v4); null when the page can't */
164
+ readonly quests?: () => ((quests: NonNullable<DevGameplay['quests']>) => Promise<boolean>) | null;
165
+ readonly watchFrames: (fn: (dt: number) => void) => () => void;
166
+ }
167
+
168
+ interface Held<T extends { dispose: () => void }> { readonly value: T; users: number }
169
+ interface LivePart { readonly scope: Scope; readonly geometries: readonly string[]; readonly textures: readonly string[] }
170
+
171
+ /** Build the hook over the page's scene and world; `installDevHook` puts it on the window. */
172
+ export function createDevHook(ports: DevHookPorts): DevHook & { readonly root: THREE.Group; held: () => { geometries: number; textures: number } } {
173
+ const { scope } = ports, root = new THREE.Group(), parts = new Map<string, LivePart>(), colliders = new Map<string, Scope>();
174
+ const boxesOf = new Map<string, readonly DevBox[]>();
175
+ let collidersIn: Physics | null = null;
176
+ const geometries = new Map<string, Held<THREE.BufferGeometry>>(), textures = new Map<string, Held<THREE.DataTexture>>();
177
+ root.name = 'devScene';
178
+ ports.scene.add(root);
179
+ scope.onDispose(() => {
180
+ for (const name of Array.from(parts.keys())) removePart(name);
181
+ root.removeFromParent();
182
+ });
183
+
184
+ const acquire = <T extends { dispose: () => void }>(map: Map<string, Held<T>>, key: string, make: () => T): T => {
185
+ const held = map.get(key);
186
+ if (held !== undefined) { held.users++; return held.value; }
187
+ const value = make();
188
+ map.set(key, { value, users: 1 });
189
+ return value;
190
+ };
191
+ const drop = <T extends { dispose: () => void }>(map: Map<string, Held<T>>, keys: readonly string[]): void => {
192
+ for (const key of keys) {
193
+ const held = map.get(key);
194
+ if (held !== undefined && --held.users === 0) { held.value.dispose(); map.delete(key); }
195
+ }
196
+ };
197
+ const release = (live: LivePart): void => { live.scope.dispose(); drop(geometries, live.geometries); drop(textures, live.textures); };
198
+
199
+ /** One part under its own scope, not yet in the scene; on a throw, everything it took is given back first. */
200
+ const build = (name: string, part: DevPart): { live: LivePart; group: THREE.Group } => {
201
+ const partScope = scope.child(`devScene.${name}`), group = new THREE.Group(), owned: { dispose: () => void }[] = [];
202
+ const geometryKeys: string[] = [], textureKeys: string[] = [], live: LivePart = { scope: partScope, geometries: geometryKeys, textures: textureKeys };
203
+ group.name = `devScene.${name}`;
204
+ partScope.onDispose(() => { group.removeFromParent(); for (const resource of owned) resource.dispose(); });
205
+ try {
206
+ const maps = new Map<string, THREE.DataTexture>(), shapes = new Map<string, THREE.BufferGeometry>();
207
+ for (const row of part.textures) { maps.set(row.key, acquire(textures, row.key, () => makeTexture(row))); textureKeys.push(row.key); }
208
+ for (const row of part.geometries) { shapes.set(row.key, acquire(geometries, row.key, () => makeGeometry(row))); geometryKeys.push(row.key); }
209
+ const need = <T>(map: Map<string, T>, key: string, what: string): T => { const value = map.get(key); if (value === undefined) throw new Error(`dev hook: part ${name} names ${what} ${key} it does not carry`); return value; };
210
+ const materials = new Map<string, THREE.Material>();
211
+ for (const row of part.materials) {
212
+ const material = makeMaterial(row, row.map === null ? null : need(maps, row.map, 'texture'), owned);
213
+ materials.set(row.key, material); owned.push(material);
214
+ }
215
+ for (const draw of part.draws) {
216
+ const material = need(materials, draw.material, 'material'), geometry = need(shapes, draw.geometry, 'geometry');
217
+ let mesh: THREE.Mesh;
218
+ if (draw.instances === null) mesh = new THREE.Mesh(geometry, material);
219
+ else {
220
+ if (draw.instances.matrices.length !== draw.instances.count * 16) throw new Error(`dev hook: part ${name} has ${draw.instances.matrices.length} instance matrix floats for ${draw.instances.count} instances`);
221
+ const instanced = new THREE.InstancedMesh(geometry, material, draw.instances.count);
222
+ owned.push(instanced);
223
+ instanced.instanceMatrix.array.set(draw.instances.matrices);
224
+ if (draw.instances.colours !== null) instanced.instanceColor = new THREE.InstancedBufferAttribute(Float32Array.from(draw.instances.colours), 3);
225
+ instanced.computeBoundingSphere();
226
+ mesh = instanced;
227
+ }
228
+ mesh.matrixAutoUpdate = false;
229
+ mesh.matrix.fromArray(draw.matrix);
230
+ mesh.castShadow = draw.castShadow; mesh.receiveShadow = draw.receiveShadow;
231
+ group.add(mesh);
232
+ }
233
+ for (const sprite of part.sprites) {
234
+ const card = new THREE.Sprite(need(materials, sprite.material, 'material') as THREE.SpriteMaterial);
235
+ card.position.set(...sprite.position); card.scale.set(sprite.scale[0], sprite.scale[1], 1); card.center.set(...sprite.center);
236
+ group.add(card);
237
+ }
238
+ if (part.lamps.length > 0) {
239
+ // the look's own lamp lights (B2, M4.3): what a baked shard's `look.light.lamps` draws
240
+ const lamps = lampLights(part.lamps);
241
+ group.add(lamps);
242
+ owned.push({ dispose: () => { for (const light of lamps.children) if (light instanceof THREE.Light) light.dispose(); } });
243
+ const { update } = lamps;
244
+ if (update !== null) { let time = 0; partScope.onDispose(ports.watchFrames(dt => { time += dt; update(time); })); }
245
+ }
246
+ // the client's own water surfaces, under this part's scope
247
+ installClientWater(part.water, { root: group, scope: partScope, frame: run => { partScope.onDispose(ports.watchFrames(run)); } });
248
+ group.updateMatrixWorld(true);
249
+ } catch (cause) { release(live); throw cause; }
250
+ return { live, group };
251
+ };
252
+
253
+ const replacePart = (name: string, part: DevPart): void => {
254
+ const { live, group } = build(name, part), old = parts.get(name);
255
+ root.add(group);
256
+ parts.set(name, live);
257
+ if (old !== undefined) release(old);
258
+ };
259
+ const addPart = (name: string, part: DevPart): void => {
260
+ if (parts.has(name)) throw new Error(`dev hook: part ${name} is already drawn (replacePart swaps it)`);
261
+ replacePart(name, part);
262
+ };
263
+ function removePart(name: string): void {
264
+ const live = parts.get(name);
265
+ if (live === undefined) return;
266
+ parts.delete(name);
267
+ release(live);
268
+ }
269
+ const setLook = (look: DevLook): boolean => {
270
+ const current = ports.look();
271
+ if (current === null || !('liveKeys' in current)) return false;
272
+ if (look.look !== undefined) return current.liveLook !== undefined && current.liveLook(shardfileLiveLook(look.look));
273
+ return current.liveKeys !== undefined && current.liveKeys(look.keys);
274
+ };
275
+ /** A player now inside new solids stands on them (the server lifts its own: `swapDevGround`). */
276
+ const lift = (heightAt: ((x: number, z: number) => number) | null, boxes: readonly DevBox[]): void => {
277
+ const player = ports.player?.() ?? null;
278
+ if (player === null) return;
279
+ const { x, y, z } = player.position, feet = liftedFeet(x, y, z, heightAt, boxes);
280
+ if (feet === null) return;
281
+ const pitch = player.pitch;
282
+ player.spawn(x, z, player.yaw, feet); player.pitch = pitch;
283
+ };
284
+
285
+ // The boxes go into the page's world as it is now. After a grid crossing that is a new world: every held part's boxes
286
+ // are made again in it, and the old world's sets are disposed (Physics skips removal from a freed world).
287
+ const swapColliders = (name: string, boxes: readonly DevBox[]): void => {
288
+ const message = { wildshardDevColliders: name, boxes };
289
+ if (!isDevColliders(message)) throw new Error(`dev hook: part ${name} has a malformed collider box`);
290
+ if (boxes.length === 0) boxesOf.delete(name); else boxesOf.set(name, boxes);
291
+ const physics = ports.physics();
292
+ if (physics !== collidersIn) {
293
+ for (const held of colliders.values()) held.dispose();
294
+ colliders.clear();
295
+ collidersIn = physics;
296
+ if (physics !== null) for (const [part, held] of boxesOf) if (part !== name) swapDevBoxes(physics, scope, colliders, part, held);
297
+ }
298
+ if (physics !== null) swapDevBoxes(physics, scope, colliders, name, boxes);
299
+ ports.server()?.(name, boxes);
300
+ lift(null, boxes);
301
+ };
302
+ // AP18: each drawn ground tile keeps a signature of the lattice samples it was last cut from; a swap cuts again only the
303
+ // tiles whose samples changed, and a tile the page streams in later (cut from the boot's bytes) is cut on the next frame.
304
+ let ground: TerrainTileData | null = null, groundScope: Scope | null = null, sweep = 0;
305
+ const cut = new WeakMap<THREE.Mesh, number>();
306
+ const tiles = (): THREE.Mesh[] => {
307
+ const out: THREE.Mesh[] = [];
308
+ ports.scene.traverse(object => { if (object instanceof THREE.Mesh && object.name.startsWith('terrain:')) out.push(object as THREE.Mesh); });
309
+ return out;
310
+ };
311
+ /** Cut every tile whose samples differ from the ones it holds; false when one can't be cut from this lattice. */
312
+ const recut = (lattice: TerrainTileData): boolean => {
313
+ let ok = true;
314
+ for (const mesh of tiles()) {
315
+ const signature = tileSignature(mesh, lattice);
316
+ if (signature === null) { ok = false; continue; }
317
+ if (cut.get(mesh) === signature) continue;
318
+ if (refreshTerrainTile(mesh, lattice)) cut.set(mesh, signature); else ok = false;
319
+ }
320
+ return ok;
321
+ };
322
+ const setGround = (bytes: Uint8Array): boolean => {
323
+ let lattice: TerrainTileData;
324
+ try { lattice = decodeTerrainTile(bytes); } catch { return false; }
325
+ if (lattice.colours === undefined) return false;
326
+ const heights: DevGround = { resolution: lattice.resolution, x: lattice.x, z: lattice.z, size: lattice.size, heights: lattice.heights };
327
+ if (!recut(lattice)) return false;
328
+ const physics = ports.physics(), next = scope.child('devGround');
329
+ if (physics !== null) swapTerrainCollider(physics, heights, next);
330
+ groundScope?.dispose(); groundScope = next;
331
+ const heightAt = devGroundHeight(heights), field = ports.terrainField?.();
332
+ const normalAt = (x: number, z: number, eps = 0.25): [number, number, number] => {
333
+ const dx = heightAt(x - eps, z) - heightAt(x + eps, z), dz = heightAt(x, z - eps) - heightAt(x, z + eps), length = Math.hypot(dx, 2 * eps, dz);
334
+ return [dx / length, 2 * eps / length, dz / length];
335
+ };
336
+ field?.install({ heightAt, normalAt, splatAt: field.field.splatAt });
337
+ ports.serverGround?.()?.(heights);
338
+ ground = lattice;
339
+ lift(heightAt, []);
340
+ return true;
341
+ };
342
+ // AP19: the server's world restarts on the new rows and the quest views are built again, side by side; then the new world
343
+ // takes the boxes and ground watch had swapped into the old one.
344
+ const restartGameplay = async (gameplay: DevGameplay): Promise<DevRestart> => {
345
+ const server = ports.restart?.() ?? null, views = gameplay.quests === undefined ? null : ports.quests?.() ?? null;
346
+ if (server === null) return { ok: false, serverMs: 0, questsMs: null, reason: 'the page has no in-page server' };
347
+ if (gameplay.quests !== undefined && views === null) return { ok: false, serverMs: 0, questsMs: null, reason: 'the page can\'t rebuild its quest views' };
348
+ const player = ports.player?.() ?? null, at = player === null ? null : { x: player.position.x, y: player.position.y, z: player.position.z, yaw: player.yaw };
349
+ const started = diagnosticNow();
350
+ const quests = views === null || gameplay.quests === undefined ? Promise.resolve(null) : views(gameplay.quests).then(ok => ok ? diagnosticNow() - started : -1);
351
+ const [restarted, questsMs] = await Promise.all([server(gameplay, at), quests]);
352
+ if (restarted.ok) {
353
+ for (const [name, boxes] of boxesOf) ports.server()?.(name, boxes);
354
+ if (ground !== null) ports.serverGround?.()?.({ resolution: ground.resolution, x: ground.x, z: ground.z, size: ground.size, heights: ground.heights });
355
+ }
356
+ const ok = restarted.ok && questsMs !== -1;
357
+ return { ok, serverMs: restarted.ms, questsMs: questsMs === null || questsMs < 0 ? null : Math.round(questsMs),
358
+ ...(restarted.reason !== undefined ? { reason: restarted.reason } : questsMs === -1 ? { reason: 'the quest views refused the new quests' } : {}) };
359
+ };
360
+ scope.onDispose(ports.watchFrames(() => { if (ground !== null && ++sweep % 15 === 0) recut(ground); }));
361
+ scope.onDispose(() => { for (const held of colliders.values()) held.dispose(); colliders.clear(); });
362
+ return { version: DEV_HOOK_VERSION, root, addPart, replacePart, removePart, setLook, swapColliders, setGround, restartGameplay,
363
+ held: () => ({ geometries: geometries.size, textures: textures.size }) };
364
+ }
365
+
366
+ /** Put the hook on the window for sharddev's page script, for the page's level. */
367
+ export function installDevHook(ports: DevHookPorts): DevHook {
368
+ const hook = createDevHook(ports), { version, addPart, replacePart, removePart, setLook, swapColliders, setGround, restartGameplay } = hook;
369
+ ports.scope.expose(window, DEV_HOOK_GLOBAL, Object.freeze({ version, addPart, replacePart, removePart, setLook, swapColliders, setGround, restartGameplay } satisfies DevHook));
370
+ return hook;
371
+ }
372
+
373
+ /** A tile's lattice window (heights and colours), as one number: the samples a tile at its place and size is cut from. Null
374
+ * when the tile's corners are off the lattice. */
375
+ function tileSignature(mesh: THREE.Mesh, lattice: TerrainTileData): number | null {
376
+ const box = mesh.geometry.boundingBox, colours = lattice.colours;
377
+ if (box === null || colours === undefined) return null;
378
+ const n = lattice.resolution, step = lattice.size / (n - 1), size = box.max.x - box.min.x;
379
+ const x0 = Math.round((mesh.position.x - lattice.x) / step), z0 = Math.round((mesh.position.z - lattice.z) / step), span = Math.round(size / step);
380
+ // one sample more on each side: a tile's normals read its neighbours' heights
381
+ if (x0 < 0 || z0 < 0 || x0 + span >= n || z0 + span >= n) return null;
382
+ let hash = 2166136261;
383
+ const bits = new Uint32Array(1), float = new Float32Array(bits.buffer);
384
+ const mix = (value: number): void => { float[0] = value; hash = Math.imul(hash ^ (bits[0] ?? 0), 16777619); };
385
+ for (let z = Math.max(0, z0 - 1); z <= Math.min(n - 1, z0 + span + 1); z++) for (let x = Math.max(0, x0 - 1); x <= Math.min(n - 1, x0 + span + 1); x++) {
386
+ const at = z * n + x;
387
+ mix(lattice.heights[at] ?? 0); mix(colours[at * 3] ?? 0); mix(colours[at * 3 + 1] ?? 0); mix(colours[at * 3 + 2] ?? 0);
388
+ }
389
+ return hash >>> 0;
390
+ }
391
+
392
+ function makeMaterial(row: DevMaterial, shared: THREE.DataTexture | null, owned: { dispose: () => void }[]): THREE.Material {
393
+ let map: THREE.Texture | null = null;
394
+ if (shared !== null) {
395
+ // a clone shares the raster (one upload) and keeps its own repeat and offset, as an author's `clone()` does
396
+ map = shared.clone(); owned.push(map); map.repeat.set(...row.repeat); map.offset.set(...row.offset); map.version++;
397
+ }
398
+ const colour = new THREE.Color().setRGB(...row.colour);
399
+ const common = { name: row.name, color: colour, map, alphaTest: row.alphaTest, transparent: row.transparent, opacity: row.opacity, depthWrite: row.depthWrite, fog: row.fog,
400
+ blending: row.blending === 'additive' ? THREE.AdditiveBlending : THREE.NormalBlending };
401
+ if (row.kind === 'sprite') return new THREE.SpriteMaterial(common);
402
+ const side = row.side === 'double' ? THREE.DoubleSide : row.side === 'back' ? THREE.BackSide : THREE.FrontSide;
403
+ if (row.kind === 'basic') return new THREE.MeshBasicMaterial({ ...common, side, vertexColors: row.vertexColours });
404
+ return new THREE.MeshStandardMaterial({ ...common, side, vertexColors: row.vertexColours, roughness: row.roughness, metalness: row.metalness,
405
+ emissive: new THREE.Color().setRGB(...row.emissive), emissiveIntensity: row.emissiveIntensity });
406
+ }
407
+
408
+ function makeGeometry(source: DevGeometry): THREE.BufferGeometry {
409
+ const geometry = new THREE.BufferGeometry();
410
+ geometry.setAttribute('position', new THREE.BufferAttribute(source.position, 3));
411
+ geometry.setAttribute('normal', new THREE.BufferAttribute(source.normal, 3));
412
+ if (source.uv !== null) geometry.setAttribute('uv', new THREE.BufferAttribute(source.uv, 2));
413
+ if (source.colour !== null) geometry.setAttribute('color', new THREE.BufferAttribute(source.colour, 3));
414
+ if (source.index !== null) geometry.setIndex(new THREE.BufferAttribute(source.index, 1));
415
+ geometry.computeBoundingSphere();
416
+ return geometry;
417
+ }
418
+
419
+ function makeTexture(row: DevTexture): THREE.DataTexture {
420
+ if (row.rgba.byteLength !== row.width * row.height * 4) throw new Error(`dev hook: texture ${row.key} is ${row.rgba.byteLength} bytes, not ${row.width}x${row.height} RGBA8`);
421
+ const texture = new THREE.DataTexture(row.rgba, row.width, row.height);
422
+ texture.colorSpace = row.colourSpace === 'linear' ? THREE.LinearSRGBColorSpace : THREE.SRGBColorSpace;
423
+ texture.wrapS = texture.wrapT = THREE.RepeatWrapping;
424
+ texture.magFilter = THREE.LinearFilter; texture.minFilter = THREE.LinearMipmapLinearFilter; texture.generateMipmaps = true;
425
+ texture.anisotropy = 4;
426
+ texture.needsUpdate = true;
427
+ return texture;
428
+ }
@@ -0,0 +1,21 @@
1
+ import { DATA_LOOK_DAY, type LiveLook } from '@wildshard/engine/render/dataLook';
2
+ import { lookLightManifest } from '@wildshard/engine/render/lookLight';
3
+ import { lookLightOn } from '@wildshard/engine/ui/lookLightOption';
4
+ import { TIER } from '@wildshard/engine/core/tier';
5
+ import type { Shardfile } from '@wildshard/format/shardSchema';
6
+ import { shardfileFileUrl } from '../shardfile/look';
7
+
8
+ /**
9
+ * SHARD-SOURCE AP17: a shardfile's look section as `shardfileLook` (`../shardfile/look.ts`) builds its data look, plus the
10
+ * engine bloom the level grade takes from it (`plugin/context.ts`), for the dev hook's `setLook`: a watched page's look set
11
+ * live from the same data a fresh shell would boot from. Kept beside the hook, not in `shardfile/`, so a dev-only change never
12
+ * moves the shardfile validation revision; `liveLook.test.ts` holds the two in step.
13
+ */
14
+ export function shardfileLiveLook(look: Shardfile['look'], light: boolean = lookLightOn()): LiveLook {
15
+ const resolved = lookLightManifest(look, light, TIER);
16
+ return { day: look.day ?? DATA_LOOK_DAY, dayOverride: look.dayOverride, keys: look.keys, lut: look.grade.lut === null ? null : shardfileFileUrl(look.grade.lut),
17
+ neutral: look.grade.tone === 'neutral', aces: look.grade.tone === 'aces', exposure: look.grade.exposure, vignette: look.grade.vignette ?? null, bloomRadius: resolved.bloom.radius,
18
+ bloom: resolved.bloom,
19
+ light: { rim: resolved.rim, pools: resolved.pools, heightFogDensity: resolved.atmosphere.fogHeightDensity, lamps: resolved.lamps, bounce: resolved.bounce, environment: resolved.environment,
20
+ shadow: resolved.shadow, motes: resolved.motes } };
21
+ }
@@ -49,6 +49,9 @@ export function cellLoadingStep(input: CellLoadingInput): CellLoadingStep {
49
49
  }
50
50
  const hooksDone = (last: string): boolean => !input.hybrid || input.hooks.has(last);
51
51
  if (!input.product) return { kind: 'step', key: 'world', detail: input.requested ? 'reading its region files' : 'requested as you approach' };
52
+ // QA 11-13 row 43: a resident product but no readiness request is a world nobody is building yet; its hooks are a past
53
+ // visit's, not progress (a return visit read "saved state and its systems" for 11 s while nothing built it)
54
+ if (!input.requested) return { kind: 'step', key: 'world', detail: 'waiting for its world to start' };
52
55
  const running = input.hook === null ? '' : ` · ${input.hook}`;
53
56
  if (!hooksDone('afterWorld')) return { kind: 'step', key: 'world', detail: `${input.claimedMB.toFixed(0)} MB admitted${running}` };
54
57
  if (!hooksDone('afterKit')) return { kind: 'step', key: 'loadout', detail: `weapons, held items and HUD${running}` };
@@ -71,6 +74,8 @@ export class CellLoading {
71
74
  /** the step shown: a running hook's own step, else the furthest reached (a region learns it has hooks only when they
72
75
  * start, so between hooks a row never goes back) */
73
76
  private reached = -1;
77
+ /** GC8: the step the screen shows now and its detail, for a harness to time each step (null while closed). */
78
+ private shown: { readonly step: string; readonly detail: string } | null = null;
74
79
  /** `known`: whether the waiting cell is one of this session's neighbours (no screen for one that is not) */
75
80
  constructor(private readonly screen: CellLoadingScreen, private readonly known: (instance: string) => boolean) {}
76
81
  /** Show, step or hide the screen from this cell's live state (null: no cell is waiting). */
@@ -87,14 +92,19 @@ export class CellLoading {
87
92
  }
88
93
  const rows = path.map((row, i): CellLoadingRow => ({ label: row.label, state: i < this.reached ? 'done' : i === this.reached ? 'now' : 'next' }));
89
94
  const detail = step.kind === 'step' ? step.detail : '';
90
- this.screen.show({ instance: input.instance, name: input.name, step: path[Math.max(0, this.reached)]?.key ?? '', rows, detail,
95
+ this.shown = { step: path[Math.max(0, this.reached)]?.key ?? '', detail };
96
+ this.screen.show({ instance: input.instance, name: input.name, step: this.shown.step, rows, detail,
91
97
  failed: step.kind === 'failed' ? step.reason : null });
92
98
  }
93
99
  /** The screen's cell (null: none shown). */
94
100
  get open(): string | null { return this.instance; }
101
+ /** NET-LAG NL7: the row the screen shows running now (its label), null when none is shown: a proof times each stage. */
102
+ get stage(): string | null { return this.instance === null || this.reached < 0 ? null : loadingPath('cell').steps[this.reached]?.label ?? null; }
103
+ /** GC8: the step shown now and its detail, or null. */
104
+ get now(): { readonly step: string; readonly detail: string } | null { return this.instance === null ? null : this.shown; }
95
105
  /** Hide the screen: `entered`, the cell is ready (the card completes and fades); else it was left or cancelled. */
96
106
  close(entered = false): void {
97
- const was = this.instance; this.instance = null; this.reached = -1;
107
+ const was = this.instance; this.instance = null; this.reached = -1; this.shown = null;
98
108
  if (was !== null) this.screen.hide(entered);
99
109
  }
100
110
  }