@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
@@ -12,18 +12,22 @@ import * as THREE from 'three';
12
12
  import type { PaintedNumbers } from '@wildshard/format/paintedLook';
13
13
  import { BlendFunction, Effect, LookupTexture, ToneMappingMode } from 'postprocessing';
14
14
  import { DEFAULT_NORMALIZED_DAY, normalizedDayClock, DayCycle } from '../../../shared/engine/world/dayCycle';
15
- import type { LookStrategy, SkyBackdropTargets, TerrainPainter } from './look';
15
+ import type { EngineEffects, LookStrategy, SkyBackdropTargets, TerrainPainter } from './look';
16
16
  import { LUT_SIZE, fetchLut } from './lut';
17
17
  import { PATCH_ORDER, patchShader, setInheritedPatch, type ShaderSource } from './shaderPatches';
18
18
  import { Scope } from '../../../shared/engine/app/scope';
19
19
  import { curveAt, type Curve } from '@wildshard/format/materials';
20
- import type { GraphIr } from '@wildshard/format/materialGraph';
20
+ import type { GraphBudget, GraphIr } from '@wildshard/format/materialGraph';
21
21
  import { loadLookGraphCompiler } from './graphBackend';
22
+ import { LOOK_SKY_BUDGET } from '@wildshard/format/look-sky';
22
23
  import { EmissiveLook } from './families/emissive';
23
24
  import { familyMaterial } from './families/registry';
24
25
  import { ToonLook } from './families/toon';
25
- import { LOOK_RIM_PATCH, lightPools, rimPatch } from './lookLight';
26
- import type { LookPools, LookRim } from '@wildshard/format/look-light';
26
+ import { LOOK_RIM_PATCH, bounceLight, environmentScene, lampLights, lightPools, rimPatch } from './lookLight';
27
+ import { ExposureEffect, lampHalos, lookMotes, tickGlow } from './lookRender';
28
+ import type { LookMotes, LookShadow, LookVignette } from '@wildshard/format/look-render';
29
+ import type { LookBounce, LookEnvironment, LookLamp, LookPools, LookRim } from '@wildshard/format/look-light';
30
+ import { tierPmremGenerator } from './pmremSize';
27
31
 
28
32
  type Rgb = readonly [number, number, number];
29
33
  const mesh = (object: THREE.Object3D): object is THREE.Mesh => object instanceof THREE.Mesh;
@@ -59,7 +63,28 @@ export interface DataLookSpec {
59
63
  * its light settings as they resolved at load (LF1-4, `render/lookLight.ts`): a rim patched into every lit material, the
60
64
  * light pools' decal draw and the fog program's height density; absent: none of them
61
65
  */
62
- readonly light?: { readonly rim: LookRim | null; readonly pools: LookPools | null; readonly heightFogDensity: number };
66
+ readonly light?: {
67
+ readonly rim: LookRim | null; readonly pools: LookPools | null; readonly heightFogDensity: number;
68
+ /** B2: real lamps, a warm bounce and a sky-derived environment; absent or null: none */
69
+ readonly lamps?: readonly LookLamp[] | null; readonly bounce?: LookBounce | null; readonly environment?: LookEnvironment | null;
70
+ /** TEMPLATES-CLEANROOM M4: the sun's shadow look and glow motes; absent or null: the engine's shadows, no motes */
71
+ readonly shadow?: LookShadow | null; readonly motes?: LookMotes | null;
72
+ };
73
+ /** B2 (`look.grade.tone` neutral): the Neutral display curve in place of the engine's AgX */
74
+ readonly neutral?: boolean;
75
+ /** M4.7 (`look.grade.tone` aces): the ACES filmic curve in place of the engine's AgX */
76
+ readonly aces?: boolean;
77
+ /** M4.7: `look.grade.exposure` in stops ahead of the tone curve (absent or 0: none), its vignette and bloom radius */
78
+ readonly exposure?: number;
79
+ readonly vignette?: LookVignette | null;
80
+ readonly bloomRadius?: number | null;
81
+ /**
82
+ * SHARD-SOURCE AP14 (`look.sky`): the dome's painted sky, an unlit material graph over the dome's direction
83
+ * (`normalize(positionLocal)`), compiled on the page's renderer with the backdrop in place of the gradient. The
84
+ * environment (`light.environment`) is filtered from the same dome, so reflections show the painted sky. Absent or
85
+ * null: the gradient of the keys' zenith and horizon.
86
+ */
87
+ readonly sky?: GraphIr | null;
63
88
  }
64
89
 
65
90
  /** A sampled look: plain numbers, blended between the two keys around a time of day. */
@@ -101,13 +126,23 @@ export function sampleLook(keys: readonly LookKey[], time: number, out: LookSamp
101
126
  return out;
102
127
  }
103
128
 
129
+
130
+ /**
131
+ * SHARD-SOURCE AP17: what a data look takes in place (`LookStrategy.liveLook`, driven by `wildshard watch` through engine's
132
+ * dev hook v2): its spec as a fresh build would read it, plus the engine bloom's intensity and threshold (the level grade's
133
+ * at boot). The keys, the sun's arc, exposure, tone, vignette and bloom go live; the light rows and the LUT must not change.
134
+ */
135
+ export interface LiveLook extends Omit<DataLookSpec, 'lut'> {
136
+ readonly lut: string | null;
137
+ readonly bloom: { readonly intensity: number; readonly threshold: number; readonly radius: number | null };
138
+ }
104
139
  /** The engine clock for a data look (an hour clock with one day-long segment, the sun on the day's arc). */
105
140
  export function dataLookClock(day: LookDay, dayOverride: number | null): DayCycle {
106
141
  return normalizedDayClock(day, dayOverride);
107
142
  }
108
143
 
109
144
  /** The engine's gradient dome: radius 600 m, drawn first, unfogged, kept on the camera by Game (the backdrop's `clouds`). */
110
- function gradientDome(): { dome: THREE.Mesh<THREE.SphereGeometry, THREE.ShaderMaterial>; zenith: THREE.Color; horizon: THREE.Color } {
145
+ function gradientDome(): { dome: THREE.Mesh<THREE.SphereGeometry, THREE.Material>; zenith: THREE.Color; horizon: THREE.Color } {
111
146
  const zenith = new THREE.Color(), horizon = new THREE.Color();
112
147
  const material = new THREE.ShaderMaterial({ side: THREE.BackSide, depthWrite: false, fog: false,
113
148
  uniforms: { uZenith: { value: zenith }, uHorizon: { value: horizon } },
@@ -119,6 +154,18 @@ function gradientDome(): { dome: THREE.Mesh<THREE.SphereGeometry, THREE.ShaderMa
119
154
  return { dome, zenith, horizon };
120
155
  }
121
156
 
157
+ /**
158
+ * AP14: a look's painted sky on the dome: its graph compiled (by `compile`, the page's look-graph compiler) as an unlit
159
+ * material drawn on the inside of the sphere, first, unfogged and writing no depth, as the gradient's material is (the
160
+ * old material is freed).
161
+ */
162
+ export function paintDome(dome: THREE.Mesh<THREE.SphereGeometry, THREE.Material>, sky: GraphIr, compile: (ir: GraphIr, opts: { readonly budget: GraphBudget }) => { readonly material: THREE.Material }): void {
163
+ const { material } = compile(sky, { budget: LOOK_SKY_BUDGET });
164
+ material.side = THREE.BackSide; material.depthWrite = false; material.name = 'engine.look.sky';
165
+ if ('fog' in material) material.fog = false;
166
+ dome.material.dispose(); dome.material = material;
167
+ }
168
+
122
169
  async function lutTexture(url: string | Uint8Array | null): Promise<LookupTexture | null> {
123
170
  if (url === null) return null;
124
171
  const data = typeof url === 'string' ? await fetchLut(url) : Uint8Array.from(url);
@@ -129,6 +176,63 @@ async function lutTexture(url: string | Uint8Array | null): Promise<LookupTextur
129
176
  return lut;
130
177
  }
131
178
 
179
+ const NEUTRAL_FRAGMENT = `
180
+ vec3 neutralCurve(vec3 color) {
181
+ const float startCompression = 0.8 - 0.04;
182
+ const float desaturation = 0.15;
183
+ float x = min(color.r, min(color.g, color.b));
184
+ float offset = x < 0.08 ? x - 6.25 * x * x : 0.04;
185
+ color -= offset;
186
+ float peak = max(color.r, max(color.g, color.b));
187
+ if (peak < startCompression) return color;
188
+ float d = 1.0 - startCompression;
189
+ float newPeak = 1.0 - d * d / (peak + d - startCompression);
190
+ color *= newPeak / peak;
191
+ float g = 1.0 - 1.0 / (desaturation * (peak - newPeak) + 1.0);
192
+ return mix(color, vec3(newPeak), g);
193
+ }
194
+ void mainImage(const in vec4 inputColor, const in vec2 uv, out vec4 outputColor) {
195
+ outputColor = vec4(neutralCurve(inputColor.rgb), inputColor.a);
196
+ }
197
+ `;
198
+
199
+ /**
200
+ * The NEUTRAL tone curve (Khronos PBR Neutral, three's `NeutralToneMapping` at exposure 1) as a grid cell's display: the
201
+ * page's colour pass already holds a ToneMappingEffect, and a second one includes three's tone-mapping chunk twice
202
+ * ('toneMappingExposure' redefinition), so the merged pass would never compile; this is the same curve under its own name.
203
+ */
204
+ export class NeutralToneEffect extends Effect {
205
+ constructor() { super('NeutralToneEffect', NEUTRAL_FRAGMENT, { blendFunction: BlendFunction.NORMAL }); }
206
+ }
207
+
208
+ const ACES_FRAGMENT = `
209
+ uniform float uExposure;
210
+ vec3 acesFit(vec3 v) { vec3 a = v * (v + 0.0245786) - 0.000090537; vec3 b = v * (0.983729 * v + 0.4329510) + 0.238081; return a / b; }
211
+ void mainImage(const in vec4 inputColor, const in vec2 uv, out vec4 outputColor) {
212
+ const mat3 inputMat = mat3(vec3(0.59719, 0.07600, 0.02840), vec3(0.35458, 0.90834, 0.13383), vec3(0.04823, 0.01566, 0.83777));
213
+ const mat3 outputMat = mat3(vec3(1.60475, -0.10208, -0.00327), vec3(-0.53108, 1.10813, -0.07276), vec3(-0.07367, -0.00605, 1.07602));
214
+ vec3 color = outputMat * acesFit(inputMat * (inputColor.rgb * uExposure / 0.6));
215
+ outputColor = vec4(clamp(color, 0.0, 1.0), inputColor.a);
216
+ }
217
+ `;
218
+
219
+ /**
220
+ * M4.7 (review MUST): the ACES filmic curve (three's `ACESFilmicToneMapping`) as a grid cell's display, with the look's
221
+ * exposure folded in, for the reason `NeutralToneEffect` exists: a cell never runs `compose`, so the page chain's tone
222
+ * mode and the spliced `ExposureEffect` never reach it.
223
+ */
224
+ export class AcesToneEffect extends Effect {
225
+ constructor(stops: number) {
226
+ super('AcesToneEffect', ACES_FRAGMENT, { blendFunction: BlendFunction.NORMAL, uniforms: new Map([['uExposure', new THREE.Uniform(2 ** stops)]]) });
227
+ }
228
+ }
229
+
230
+ /** a data look's grid-cell display: its own tone curve, when it names one (Neutral, or ACES with its exposure) */
231
+ function cellTone(spec: { readonly neutral?: boolean; readonly aces?: boolean; readonly exposure?: number }): { readonly cell: { readonly replaces: 'tone'; readonly build: () => { display: Effect } } } | Record<string, never> {
232
+ if (spec.aces === true) { const stops = spec.exposure ?? 0; return { cell: { replaces: 'tone', build: () => ({ display: new AcesToneEffect(stops) }) } }; }
233
+ return spec.neutral === true ? { cell: { replaces: 'tone', build: () => ({ display: new NeutralToneEffect() }) } } : {};
234
+ }
235
+
132
236
  /**
133
237
  * A level look from data: the engine's clean chain, the gradient dome, the engine fog, key light and ambient turned by
134
238
  * the keys on the engine clock, and the LUT last in the grade. Nothing is patched into another material.
@@ -136,6 +240,8 @@ async function lutTexture(url: string | Uint8Array | null): Promise<LookupTextur
136
240
  export function dataLook(spec: DataLookSpec): LookStrategy {
137
241
  if (spec.keys.length === 0) throw new Error('[look] a data look needs at least one key');
138
242
  const linear = spec.keys[0]?.fog.near !== undefined;
243
+ // the keys the frame samples: a `liveKeys` call (sharddev `watch`, through engine's dev hook) replaces them in place
244
+ let keys = spec.keys;
139
245
  // the mist's GLSL is in the linear fog only when the look declares it (LF1-4): off, the shader text is as before
140
246
  const mist = (spec.light?.heightFogDensity ?? 0) > 0;
141
247
  const fog = { wsLookFogNear: new THREE.Uniform(0), wsLookFogFar: new THREE.Uniform(1), wsLookFogEnabled: new THREE.Uniform(0) };
@@ -163,11 +269,51 @@ ${mist ? `
163
269
  #endif`);
164
270
  shader.fragmentShader = `#ifdef USE_FOG\nuniform float wsLookFogNear; uniform float wsLookFogFar; uniform float wsLookFogEnabled;\n#endif\n${patched}`;
165
271
  };
166
- const owned: { dome: THREE.Mesh<THREE.SphereGeometry, THREE.ShaderMaterial> | null; lut: LookupTexture | null; pools: THREE.Object3D | null; rim: boolean } = { dome: null, lut: null, pools: null, rim: false };
272
+ const owned: { dome: THREE.Mesh<THREE.SphereGeometry, THREE.Material> | null; lut: LookupTexture | null; pools: THREE.Object3D | null; rim: boolean;
273
+ lamps: ReturnType<typeof lampLights> | null; bounce: ReturnType<typeof bounceLight> | null; environment: THREE.WebGLRenderTarget | null;
274
+ glow: THREE.Object3D[] | null; fx: EngineEffects | null; exposure: ExposureEffect | null; clock: DayCycle | null;
275
+ chain: { vignette: { offset: number; darkness: number }; radius: number } | null } = { dome: null, lut: null, pools: null, rim: false, lamps: null, bounce: null, environment: null, glow: null,
276
+ fx: null, exposure: null, clock: null, chain: null };
277
+ // AP17: what `liveLook` last set (the light rows and the LUT are compared with the build's, never set)
278
+ let day = spec.day, dayOverride = spec.dayOverride;
279
+ const fixedOf = (light: DataLookSpec['light'], lut: unknown): string => JSON.stringify({ light: light ?? null, lut: typeof lut === 'string' || lut === null ? lut : 'bytes' });
280
+ const fixed = fixedOf(spec.light, spec.lut);
281
+ const shadow = spec.light?.shadow ?? null;
282
+ const bounceRow = spec.light?.bounce ?? null;
283
+ // the bounce exists from the backdrop on (it follows the clock's sun there); compose adds it to the scene
284
+ if (bounceRow !== null) owned.bounce = bounceLight(bounceRow);
167
285
  return {
286
+ ...cellTone(spec),
287
+ liveKeys: (next) => {
288
+ // a fog kind change (exponential to linear, or back) changes the fog patch's shader text: that needs a new look
289
+ if (next.length === 0 || next.some((key) => (key.fog.near !== undefined) !== linear)) return false;
290
+ keys = next;
291
+ return true;
292
+ },
293
+ liveLook: (next) => {
294
+ const { fx, clock, chain } = owned;
295
+ // check everything first: a refusal changes nothing
296
+ if (fx === null || clock === null || chain === null) return false;
297
+ if (next.keys.length === 0 || next.keys.some((key) => (key.fog.near !== undefined) !== linear)) return false;
298
+ // the light rows and the LUT are built once; an exposure on a chain built without one, a new day length or a new fixed
299
+ // time of day each need a new look
300
+ if (fixedOf(next.light, next.lut) !== fixed || ((next.exposure ?? 0) !== 0 && owned.exposure === null)) return false;
301
+ if (next.day.minutes !== day.minutes || next.dayOverride !== dayOverride) return false;
302
+ keys = next.keys; day = next.day; dayOverride = next.dayOverride;
303
+ Object.assign(clock.spec.sun as { maxElevation: number; azimuthOffset: number }, { maxElevation: next.day.maxElevation, azimuthOffset: next.day.azimuth });
304
+ const exposure = owned.exposure?.uniforms.get('uExposure');
305
+ if (exposure !== undefined) exposure.value = 2 ** (next.exposure ?? 0);
306
+ const tone = next.aces === true ? ToneMappingMode.ACES_FILMIC : next.neutral === true ? ToneMappingMode.NEUTRAL : ToneMappingMode.AGX;
307
+ if (fx.tone.mode !== tone) fx.tone.mode = tone;
308
+ const vignette = next.vignette ?? chain.vignette;
309
+ fx.vignette.offset = vignette.offset; fx.vignette.darkness = vignette.darkness;
310
+ fx.bloom.intensity = next.bloom.intensity; fx.bloom.luminanceMaterial.threshold = next.bloom.threshold;
311
+ fx.bloom.mipmapBlurPass.radius = next.bloom.radius ?? next.bloomRadius ?? chain.radius;
312
+ return true;
313
+ },
168
314
  // the sky builds before the composer: the level scope takes the dome and the LUT here
169
- mode: 'extend', chain: 'clean', compose: ({ engineChain, scene, scope }) => {
170
- const rim = spec.light?.rim ?? null, pools = spec.light?.pools ?? null;
315
+ mode: 'extend', chain: 'clean', compose: ({ engineChain, scene, scope, fx, renderer }) => {
316
+ const rim = spec.light?.rim ?? null, pools = spec.light?.pools ?? null, lamps = spec.light?.lamps ?? null;
171
317
  if (rim !== null && !owned.rim) {
172
318
  owned.rim = true; scope.onDispose(() => { owned.rim = false; });
173
319
  // LF1-4: one rim patch over every lit material, present and later (its values are uniforms: one shader text)
@@ -187,6 +333,43 @@ ${mist ? `
187
333
  owned.pools = decal;
188
334
  scene.add(decal); scope.own(decal.geometry); scope.own(decal.material); scope.onDispose(() => { decal.removeFromParent(); decal.dispose(); if (owned.pools === decal) owned.pools = null; });
189
335
  }
336
+ if (lamps !== null && owned.lamps === null) {
337
+ // B2: real lamps, once per look like the pools
338
+ const group = lampLights(lamps);
339
+ owned.lamps = group;
340
+ scene.add(group); scope.onDispose(() => { group.removeFromParent(); for (const light of group.children) if (light instanceof THREE.Light) light.dispose(); if (owned.lamps === group) owned.lamps = null; });
341
+ }
342
+ const motes = spec.light?.motes ?? null;
343
+ if (owned.glow === null && ((lamps?.some((lamp) => lamp.halo !== undefined) ?? false) || motes !== null)) {
344
+ // M4.8: the lamps' halos (one instanced draw) and the motes (one points draw), once per look like the lamps
345
+ const glow: (THREE.Mesh | THREE.Points)[] = [];
346
+ const halos = lamps === null ? null : lampHalos(lamps);
347
+ if (halos !== null) glow.push(halos);
348
+ if (motes !== null) glow.push(lookMotes(motes));
349
+ owned.glow = glow;
350
+ for (const draw of glow) { scene.add(draw); scope.own(draw.geometry); scope.own(draw.material as THREE.Material); }
351
+ scope.onDispose(() => { for (const draw of glow) { draw.removeFromParent(); if (draw instanceof THREE.InstancedMesh) draw.dispose(); } if (owned.glow === glow) owned.glow = null; });
352
+ }
353
+ const bounce = owned.bounce;
354
+ if (bounce !== null && bounce.light.parent !== scene) {
355
+ scene.add(bounce.light, bounce.light.target); scope.onDispose(() => { bounce.light.removeFromParent(); bounce.light.target.removeFromParent(); });
356
+ }
357
+ const envRow = spec.light?.environment ?? null;
358
+ if (envRow !== null && owned.environment === null && owned.dome !== null) {
359
+ // B2: sky-derived ambient, filtered once from the dome at the look's start (a clock that runs keeps this one). Built
360
+ // here, not in the backdrop: a grid cell runs only the backdrop and must not hold an unused cube (review MUST 2).
361
+ // The far plane clears the 600 m dome (fromScene's default 100 m clips it to black).
362
+ const made = environmentScene(owned.dome, envRow), pmrem = tierPmremGenerator(renderer);
363
+ let target: THREE.WebGLRenderTarget;
364
+ try { target = pmrem.fromScene(made.scene, 0.02, 0.1, 1000); } finally { pmrem.dispose(); made.dispose(); }
365
+ const before = { environment: scene.environment, intensity: scene.environmentIntensity };
366
+ owned.environment = target;
367
+ scene.environment = target.texture; scene.environmentIntensity = envRow.intensity;
368
+ scope.onDispose(() => {
369
+ if (scene.environment === target.texture) { scene.environment = before.environment; scene.environmentIntensity = before.intensity; }
370
+ target.dispose(); if (owned.environment === target) owned.environment = null;
371
+ });
372
+ }
190
373
  if (linear) {
191
374
  setInheritedPatch(patchFog, { scope, chain: true });
192
375
  const seen = new Set<THREE.Material>();
@@ -201,20 +384,40 @@ ${mist ? `
201
384
  const { dome, lut } = owned;
202
385
  if (dome !== null) { scope.own(dome.geometry); scope.own(dome.material); scope.onDispose(() => { dome.removeFromParent(); }); }
203
386
  if (lut !== null) scope.own(lut);
204
- return { chain: engineChain('clean') };
387
+ const chain = engineChain('clean');
388
+ // AP17: the chain as the engine built it, before this look's own vignette and bloom spread, for `liveLook`
389
+ owned.fx = fx; owned.chain = { vignette: { offset: fx.vignette.offset, darkness: fx.vignette.darkness }, radius: fx.bloom.mipmapBlurPass.radius };
390
+ scope.onDispose(() => { if (owned.fx === fx) { owned.fx = null; owned.chain = null; owned.exposure = null; } });
391
+ // B2: the Neutral curve keeps the look's saturated albedo saturated, where AgX would grey it (asked after the clean chain)
392
+ if (spec.neutral === true) fx.tone.mode = ToneMappingMode.NEUTRAL;
393
+ // M4.7: ACES, the look's own vignette and bloom spread, and its exposure ahead of the curve
394
+ if (spec.aces === true) fx.tone.mode = ToneMappingMode.ACES_FILMIC;
395
+ if (spec.vignette !== undefined && spec.vignette !== null) { fx.vignette.offset = spec.vignette.offset; fx.vignette.darkness = spec.vignette.darkness; }
396
+ if (spec.bloomRadius !== undefined && spec.bloomRadius !== null) fx.bloom.mipmapBlurPass.radius = spec.bloomRadius;
397
+ const stops = spec.exposure ?? 0, at = chain.indexOf(fx.tone);
398
+ if (stops !== 0 && at !== -1) { const exposure = new ExposureEffect(stops); scope.own(exposure); chain.splice(at, 0, exposure); owned.exposure = exposure; }
399
+ return { chain };
205
400
  },
206
401
  // G992: no sun disc or corona over the gradient dome. A 1° disc read as a blurred speck with a halo ("half-assed moon
207
402
  // or sun", Jake), and a crisp disc alone as a 3 px dot (art/open-plots/sun-disc-g992/board.jpg); the key light is unchanged.
208
403
  sky: { clouds: false, planet: false, sun: { disc: false, halo: false } },
209
- backdrop: async ({ sky }) => {
404
+ // M4.7: the look's shadow radius and normal bias (its strength is set on the cascades each frame, below)
405
+ ...(shadow === null ? {} : { shadows: { rig: 'tier' as const, radius: shadow.radius, normalBias: shadow.normalBias } }),
406
+ backdrop: async ({ sky, renderer }) => {
210
407
  const clock = dataLookClock(spec.day, spec.dayOverride), now = lookSample();
408
+ owned.clock = clock;
211
409
  const { dome, zenith, horizon } = gradientDome();
410
+ // AP14: the painted sky replaces the gradient before the compose filters the environment from the dome
411
+ if (spec.sky !== undefined && spec.sky !== null) paintDome(dome, spec.sky, (await loadLookGraphCompiler(renderer)).compileGraph);
212
412
  owned.dome = dome;
213
- let targets: SkyBackdropTargets | null = null;
413
+ const bounce = owned.bounce;
414
+ let targets: SkyBackdropTargets | null = null, flicker = 0;
214
415
  const apply = (): void => {
215
- sampleLook(spec.keys, clock.hour / 24, now);
416
+ sampleLook(keys, clock.hour / 24, now);
216
417
  zenith.copy(now.zenith); horizon.copy(now.horizon);
217
418
  sky.setKeyLight(clock.sunDir, now.sun, now.sunIntensity);
419
+ bounce?.aim(clock.sunDir);
420
+ if (shadow !== null) for (const light of (sky.csm as { lights?: readonly THREE.DirectionalLight[] } | undefined)?.lights ?? []) light.shadow.intensity = shadow.intensity;
218
421
  if (targets === null) return;
219
422
  targets.hemi.color.copy(now.ambientSky); targets.hemi.groundColor.copy(now.ambientGround); targets.hemi.intensity = now.ambientIntensity;
220
423
  fog.wsLookFogEnabled.value = targets.underwater() ? 0 : Number(linear);
@@ -227,12 +430,13 @@ ${mist ? `
227
430
  targets.fogU.fogDistDensity.value = now.fogDensity; targets.fogU.fogHeightDensity.value = spec.light?.heightFogDensity ?? 0;
228
431
  targets.fogU.fogSunColor.value.copy(now.sun);
229
432
  };
230
- sampleLook(spec.keys, clock.hour / 24, now);
433
+ sampleLook(keys, clock.hour / 24, now);
231
434
  zenith.copy(now.zenith); horizon.copy(now.horizon);
435
+ bounce?.aim(clock.sunDir);
232
436
  owned.lut = await lutTexture(spec.lut);
233
437
  return { clock, horizon: now.fog.clone(), lut: owned.lut, clouds: dome,
234
438
  bind: (t) => { targets = t; apply(); },
235
- update: (dt) => { clock.update(dt); apply(); },
439
+ update: (dt) => { clock.update(dt); apply(); flicker += dt; owned.lamps?.update?.(flicker); if (owned.glow !== null) tickGlow(owned.glow, flicker); },
236
440
  rebuild: () => undefined, attachPost: () => undefined };
237
441
  },
238
442
  };
@@ -373,35 +577,6 @@ export function headingHaze(row: HeadingHazeRow, sun: LookVec3): (shader: Shader
373
577
  };
374
578
  }
375
579
 
376
- const NEUTRAL_FRAGMENT = `
377
- vec3 neutralCurve(vec3 color) {
378
- const float startCompression = 0.8 - 0.04;
379
- const float desaturation = 0.15;
380
- float x = min(color.r, min(color.g, color.b));
381
- float offset = x < 0.08 ? x - 6.25 * x * x : 0.04;
382
- color -= offset;
383
- float peak = max(color.r, max(color.g, color.b));
384
- if (peak < startCompression) return color;
385
- float d = 1.0 - startCompression;
386
- float newPeak = 1.0 - d * d / (peak + d - startCompression);
387
- color *= newPeak / peak;
388
- float g = 1.0 - 1.0 / (desaturation * (peak - newPeak) + 1.0);
389
- return mix(color, vec3(newPeak), g);
390
- }
391
- void mainImage(const in vec4 inputColor, const in vec2 uv, out vec4 outputColor) {
392
- outputColor = vec4(neutralCurve(inputColor.rgb), inputColor.a);
393
- }
394
- `;
395
-
396
- /**
397
- * The NEUTRAL tone curve (Khronos PBR Neutral, three's `NeutralToneMapping` at exposure 1) as a grid cell's display: the
398
- * page's colour pass already holds a ToneMappingEffect, and a second one includes three's tone-mapping chunk twice
399
- * ('toneMappingExposure' redefinition), so the merged pass would never compile; this is the same curve under its own name.
400
- */
401
- export class NeutralToneEffect extends Effect {
402
- constructor() { super('NeutralToneEffect', NEUTRAL_FRAGMENT, { blendFunction: BlendFunction.NORMAL }); }
403
- }
404
-
405
580
  /** A painted look's dome (its sky layer) and the heading strip its haze reads (null on a painted-strip sky). */
406
581
  export interface PaintedSky { readonly dome: THREE.Mesh<THREE.BufferGeometry, THREE.Material>; readonly strip: THREE.Texture | null }
407
582
  /** A painted look's dressing: the sky pieces that stand in the world (a sea of cloud, the sun's glow) and their tick. */
@@ -0,0 +1,89 @@
1
+ /**
2
+ * The PBR family's detail layer (meta TEMPLATES-CLEANROOM M4.11, `@wildshard/format/detail-layer`, J338's procedural
3
+ * route): the stone, slab, wood and moss texture a cleanroom paints on canvases, drawn by the shader from world position,
4
+ * so it costs no bytes and needs no UVs. Per pixel:
5
+ * - broad value-noise blotches swing the albedo by `mottle`, a fine speckle by `grain`;
6
+ * - the same pattern, read as a height in metres, tilts the shading normal by `relief` (screen-space bump, Mikkelsen's
7
+ * surface-gradient method, as three's bump map);
8
+ * - `moss` grows on up-facing faces where a second, coarser noise passes `1 - amount`.
9
+ * Every knob is a uniform over one shader text, so all detailed surfaces share one program. Identifiers carry a `famD`
10
+ * prefix. A surface takes a detail layer alone, not with a ground or measure layer (each owns the albedo).
11
+ */
12
+ import * as THREE from 'three';
13
+ import { patchShader, PATCH_ORDER } from '../shaderPatches';
14
+ import type { PbrMaterialParams } from '@wildshard/format/materialFamilies';
15
+
16
+ /** a PBR surface's detail layer (`@wildshard/format/detail-layer`'s `DetailLayer`) */
17
+ type DetailLayer = NonNullable<PbrMaterialParams['detail']>;
18
+
19
+ /** the program-cache key of every PBR material with a detail layer */
20
+ export const DETAIL_PROGRAM_KEY = 'family.pbr.detail.v1';
21
+ /** the speckle's frequency over the blotches' */
22
+ const GRAIN_OCTAVE = 9;
23
+ /** the relief's height (m) per metre of pattern scale at `relief` 1 */
24
+ const RELIEF_HEIGHT = 0.12;
25
+
26
+ const VERT_PARS = 'varying vec3 vFamDPos;\nvarying vec3 vFamDN;';
27
+ const VERT_WORLD = /* glsl */`#include <worldpos_vertex>
28
+ vec4 famDW = vec4( transformed, 1.0 );
29
+ vec3 famDN = objectNormal;
30
+ #ifdef USE_INSTANCING
31
+ famDW = instanceMatrix * famDW;
32
+ famDN = mat3( instanceMatrix ) * famDN;
33
+ #endif
34
+ vFamDPos = ( modelMatrix * famDW ).xyz;
35
+ vFamDN = normalize( mat3( modelMatrix ) * famDN );`;
36
+
37
+ const FRAG_PARS = /* glsl */`
38
+ varying vec3 vFamDPos;
39
+ varying vec3 vFamDN;
40
+ uniform vec4 famDK; // 1 / scale (1/m), mottle, grain, relief height (m)
41
+ uniform vec4 famDMoss; // linear colour, amount (0 = none)
42
+ float famDHash( vec3 p ) { p = fract( p * 0.1031 ); p += dot( p, p.zyx + 31.32 ); return fract( ( p.x + p.y ) * p.z ); }
43
+ float famDNoise( vec3 p ) {
44
+ vec3 i = floor( p ), f = fract( p );
45
+ f = f * f * ( 3.0 - 2.0 * f );
46
+ float a = mix( famDHash( i ), famDHash( i + vec3( 1.0, 0.0, 0.0 ) ), f.x );
47
+ float b = mix( famDHash( i + vec3( 0.0, 1.0, 0.0 ) ), famDHash( i + vec3( 1.0, 1.0, 0.0 ) ), f.x );
48
+ float c = mix( famDHash( i + vec3( 0.0, 0.0, 1.0 ) ), famDHash( i + vec3( 1.0, 0.0, 1.0 ) ), f.x );
49
+ float d = mix( famDHash( i + vec3( 0.0, 1.0, 1.0 ) ), famDHash( i + vec3( 1.0, 1.0, 1.0 ) ), f.x );
50
+ return mix( mix( a, b, f.y ), mix( c, d, f.y ), f.z );
51
+ }
52
+ float famDFbm( vec3 p ) { return 0.5 * famDNoise( p ) + 0.3 * famDNoise( p * 2.03 + 11.0 ) + 0.2 * famDNoise( p * 4.01 + 23.0 ); }`;
53
+
54
+ const FRAG_COLOUR = /* glsl */`#include <color_fragment>
55
+ vec3 famDP = vFamDPos * famDK.x;
56
+ float famDM = famDFbm( famDP );
57
+ float famDG = famDNoise( famDP * ${GRAIN_OCTAVE.toFixed(1)} );
58
+ diffuseColor.rgb *= max( 0.0, 1.0 + ( famDM - 0.5 ) * 2.0 * famDK.y + ( famDG - 0.5 ) * famDK.z );
59
+ float famDMossK = 0.0;
60
+ if ( famDMoss.w > 0.0 ) {
61
+ float famDUp = smoothstep( 0.5, 0.85, normalize( vFamDN ).y );
62
+ famDMossK = famDUp * smoothstep( 1.0 - famDMoss.w, 1.0 - famDMoss.w + 0.2, famDFbm( famDP * 0.6 + 7.0 ) * 0.7 + famDM * 0.3 );
63
+ diffuseColor.rgb = mix( diffuseColor.rgb, famDMoss.rgb * ( 0.8 + 0.4 * famDG ), famDMossK );
64
+ }`;
65
+
66
+ const FRAG_NORMAL = /* glsl */`#include <normal_fragment_maps>
67
+ if ( famDK.w > 0.0 ) {
68
+ float famDH = ( famDM + ( famDG - 0.5 ) * 0.3 + famDMossK * 0.4 ) * famDK.w;
69
+ vec3 famDSx = dFdx( -vViewPosition ), famDSy = dFdy( -vViewPosition );
70
+ vec3 famDR1 = cross( famDSy, normal ), famDR2 = cross( normal, famDSx );
71
+ float famDDet = dot( famDSx, famDR1 ) * faceDirection;
72
+ vec3 famDGrad = sign( famDDet ) * ( dFdx( famDH ) * famDR1 + dFdy( famDH ) * famDR2 );
73
+ normal = normalize( abs( famDDet ) * normal - famDGrad );
74
+ }`;
75
+
76
+ /** Draw a detail layer on a PBR material (in place). */
77
+ export function applyDetail(m: THREE.MeshStandardMaterial, detail: DetailLayer): void {
78
+ const moss = detail.moss;
79
+ const mossColour = moss === undefined ? new THREE.Color(0, 0, 0) : new THREE.Color().setRGB(moss.colour[0], moss.colour[1], moss.colour[2], THREE.SRGBColorSpace);
80
+ const uniforms: Record<string, { value: unknown }> = {
81
+ famDK: { value: new THREE.Vector4(1 / detail.scale, detail.mottle, detail.grain, detail.relief * detail.scale * RELIEF_HEIGHT) },
82
+ famDMoss: { value: new THREE.Vector4(mossColour.r, mossColour.g, mossColour.b, moss?.amount ?? 0) },
83
+ };
84
+ patchShader(m, 'engine.family.detail', PATCH_ORDER.material, (shader) => {
85
+ Object.assign(shader.uniforms, uniforms);
86
+ shader.vertexShader = shader.vertexShader.replace('#include <common>', `#include <common>\n${VERT_PARS}`).replace('#include <worldpos_vertex>', VERT_WORLD);
87
+ shader.fragmentShader = shader.fragmentShader.replace('#include <common>', `#include <common>\n${FRAG_PARS}`).replace('#include <color_fragment>', FRAG_COLOUR).replace('#include <normal_fragment_maps>', FRAG_NORMAL);
88
+ }, { key: DETAIL_PROGRAM_KEY });
89
+ }
@@ -7,9 +7,11 @@
7
7
  * shares one program per object variant and a missing map is a uniform, not a recompile (the same trick the sky rig
8
8
  * plays on loaded models). Program changes come only from `vertexColours`, `faceted`, `doubleSided`, `alphaCutoff > 0` and a
9
9
  * procedural `ground` layer (ground.ts: wind ripples, grain and terrain light shaping, Signal Dunes' sand) or `measure`
10
- * layer (measure.ts: SF56's dev-map grid, roles and size labels).
10
+ * layer (measure.ts: SF56's dev-map grid, roles and size labels) or `detail` layer (detail.ts: M4.11's world-space
11
+ * mottling, grain, bumps and moss).
11
12
  */
12
13
  import * as THREE from 'three';
14
+ import { applyDetail } from './detail';
13
15
  import { applyGround } from './ground';
14
16
  import { applyMeasure } from './measure';
15
17
  import type { PbrMaterialParams } from '@wildshard/format/materialFamilies';
@@ -60,8 +62,14 @@ export function compilePbr(params: PbrMaterialParams, textures: TextureResolver,
60
62
  alphaTest: params.alphaCutoff,
61
63
  });
62
64
  m.name = 'family:pbr';
65
+ // M4.3: the surface's own glow, added over its lit colour (lamp glass that the sun still lights); absent = black
66
+ if (params.emissive !== undefined) { m.emissive.setRGB(...params.emissive, THREE.SRGBColorSpace); m.emissiveIntensity = params.emissiveIntensity ?? 1; }
63
67
  if (params.ground !== null && params.measure !== null) throw new Error('material family: a PBR surface takes a ground or a measure layer, not both');
64
68
  if (params.ground !== null) applyGround(m, params.ground, textures, emitterPools);
65
69
  if (params.measure !== null) applyMeasure(m, params.measure);
70
+ if (params.detail !== undefined) {
71
+ if (params.ground !== null || params.measure !== null) throw new Error('material family: a PBR surface takes a detail layer alone, not with a ground or measure layer');
72
+ applyDetail(m, params.detail);
73
+ }
66
74
  return m;
67
75
  }
@@ -16,6 +16,7 @@ import { parseFamilyMaterial, type FamilyMaterialParams } from '@wildshard/forma
16
16
  import { compileEmissive, type EmissiveLook } from './emissive';
17
17
  import { compilePainterly, type PainterlyLook } from './painterly';
18
18
  import { compilePbr, type TextureResolver } from './pbr';
19
+ import { applySceneEmissive, applySceneSurface } from './sceneSurface';
19
20
  import { updateGround } from './ground';
20
21
  import { compileToon, type ToonLook } from './toon';
21
22
 
@@ -39,13 +40,21 @@ const live = new Map<THREE.Material, FamilyMaterialParams>();
39
40
 
40
41
  function compile(params: FamilyMaterialParams, ctx: FamilyContext): THREE.Material {
41
42
  if (params.family === 'toon') return compileToon(params, ctx.toon);
42
- if (params.family === 'pbr') return compilePbr(params, ctx.textures, ctx.emitterPools);
43
+ if (params.family === 'pbr') {
44
+ // SHARD-SOURCE AP10, AP12: a scene's alpha, decal offset, sway and uv scroll, on the emissive look's clock
45
+ const m = compilePbr(params, ctx.textures, ctx.emitterPools);
46
+ applySceneSurface(m, params, ctx.emissive?.uniforms.famEmitTime);
47
+ return m;
48
+ }
43
49
  if (params.family === 'painterly') {
44
50
  if (ctx.painterly === undefined) throw new Error('material family: a painterly entry needs a painterly look in its family context');
45
51
  return compilePainterly(params, ctx.painterly, ctx.textures);
46
52
  }
47
53
  if (ctx.emissive === undefined) throw new Error('material family: an emissive entry needs an emissive look in its family context');
48
- return compileEmissive(params, ctx.emissive, ctx.textures);
54
+ const m = compileEmissive(params, ctx.emissive, ctx.textures);
55
+ // SHARD-SOURCE AP11, AP12: alpha cards, camera-facing cards and their declared motion
56
+ applySceneEmissive(m, params, ctx.emissive.uniforms.famEmitTime);
57
+ return m;
49
58
  }
50
59
 
51
60
  /**
@@ -0,0 +1,116 @@
1
+ /**
2
+ * What a three.js scene says about a surface (meta SHARD-SOURCE AP10 to AP12, `@wildshard/format/scene-render`), drawn on
3
+ * the family's own material after it compiles (`registry.ts`):
4
+ *
5
+ * - **PBR** `blend: 'alpha'` and `opacity`: a see-through surface (a stencil, a sign), drawn after the opaque world with
6
+ * no depth write (three sorts it back to front); `depthOffset`: a polygon offset (a decal on a wall); `sway`: each vertex
7
+ * moves by its `wsSway` attribute (the GLB's `_SWAY` channel, metres) along the wind at about `rate` hertz, phased by
8
+ * where it stands; `uvScroll`: the colour map's uv moves on the look's clock.
9
+ * - **Emissive** `blend: 'alpha'`: an unlit card blended over what is behind it; `card`: every vertex is a camera-facing
10
+ * card corner, `position` its seat and `wsCorner` (the GLB's `_CORNER` channel) the corner's view-space offset;
11
+ * `motion`: the card's `pulse`, `drift` or `rise`, phased by its seat.
12
+ *
13
+ * A see-through surface is marked `userData.sceneAlpha`, so a prop's GLB (opaque by default) never turns it opaque
14
+ * (`declaredProps.ts`). Every number is a uniform; the program changes only with which of these a surface uses. The clock is the emissive
15
+ * look's (`famEmitTime`): with no emissive look the surface holds still.
16
+ */
17
+ import * as THREE from 'three';
18
+ import type { EmissiveMaterialParams, PbrMaterialParams } from '@wildshard/format/materialFamilies';
19
+ import { patchShader, PATCH_ORDER } from '../shaderPatches';
20
+
21
+ /** the attribute a swaying surface reads (GLTFLoader's `_sway`, renamed by its binding's channels) */
22
+ export const SWAY_ATTRIBUTE = 'wsSway';
23
+ /** the attribute a card reads (GLTFLoader's `_corner`) */
24
+ export const CORNER_ATTRIBUTE = 'wsCorner';
25
+
26
+ /** The vertex channels a surface reads, as `PropSurfaceBinding.channels`; null when it reads none. */
27
+ export function sceneSurfaceChannels(entry: unknown): Readonly<Record<string, { readonly attribute: string; readonly itemSize: number }>> | null {
28
+ if (typeof entry !== 'object' || entry === null) return null;
29
+ const row = entry as { readonly family?: unknown; readonly sway?: unknown; readonly card?: unknown };
30
+ if (row.family === 'pbr' && row.sway !== undefined) return { _sway: { attribute: SWAY_ATTRIBUTE, itemSize: 1 } };
31
+ if (row.family === 'emissive' && row.card === true) return { _corner: { attribute: CORNER_ATTRIBUTE, itemSize: 2 } };
32
+ return null;
33
+ }
34
+
35
+ const STILL: THREE.IUniform<number> = { value: 0 };
36
+
37
+ const SWAY_VERTEX = /* glsl */`
38
+ #include <begin_vertex>
39
+ {
40
+ mat4 wsSwayM = modelMatrix;
41
+ vec3 wsSwayAt = ( wsSwayM * vec4( transformed, 1.0 ) ).xyz;
42
+ float wsSwayPh = wsSceneTime * wsSwayWind.z * 6.2831853 + wsSwayAt.x * 0.37 + wsSwayAt.z * 0.29;
43
+ float wsSwayAmt = wsSway * ( 0.7 * sin( wsSwayPh ) + 0.3 * sin( wsSwayPh * 2.3 + 1.7 ) );
44
+ vec3 wsSwayDir = transpose( mat3( wsSwayM ) ) * vec3( wsSwayWind.x, 0.0, wsSwayWind.y );
45
+ transformed += wsSwayDir * wsSwayAmt;
46
+ }
47
+ `;
48
+
49
+ /** PBR: alpha, depth offset, sway and uv scroll (a no-op for a surface with none of them). */
50
+ export function applySceneSurface(m: THREE.MeshStandardMaterial, params: PbrMaterialParams, clock: THREE.IUniform<number> = STILL): void {
51
+ if (params.blend === 'alpha') { m.transparent = true; m.depthWrite = false; m.opacity = params.opacity ?? 1; m.userData['sceneAlpha'] = true; }
52
+ const offset = params.depthOffset ?? 0;
53
+ if (offset !== 0) { m.polygonOffset = true; m.polygonOffsetFactor = offset; m.polygonOffsetUnits = offset; }
54
+ const sway = params.sway, scroll = params.uvScroll;
55
+ if (sway === undefined && scroll === undefined) return;
56
+ const uniforms: Record<string, THREE.IUniform> = {
57
+ wsSceneTime: clock,
58
+ wsSwayWind: { value: new THREE.Vector3(sway?.direction[0] ?? 0, sway?.direction[1] ?? 0, sway?.rate ?? 0) },
59
+ wsUvScroll: { value: new THREE.Vector2(scroll?.[0] ?? 0, scroll?.[1] ?? 0) },
60
+ };
61
+ patchShader(m, 'engine.family.sceneSurface', PATCH_ORDER.material, (shader) => {
62
+ Object.assign(shader.uniforms, uniforms);
63
+ let vs = shader.vertexShader.replace('#include <common>', `#include <common>\nuniform float wsSceneTime;\nuniform vec3 wsSwayWind;\nuniform vec2 wsUvScroll;\n${sway === undefined ? '' : `attribute float ${SWAY_ATTRIBUTE};`}`);
64
+ if (sway !== undefined) vs = vs.replace('#include <begin_vertex>', SWAY_VERTEX);
65
+ if (scroll !== undefined) vs = vs.replace('#include <uv_vertex>', '#include <uv_vertex>\n#ifdef USE_MAP\n\tvMapUv += wsUvScroll * wsSceneTime;\n#endif');
66
+ shader.vertexShader = vs;
67
+ }, { key: (before) => `${before}|scene-surface|${sway === undefined ? '' : 's'}${scroll === undefined ? '' : 'u'}` });
68
+ }
69
+
70
+ const CARD_VERTEX = /* glsl */`
71
+ vec3 wsSeat = transformed;
72
+ float wsPh = fract( sin( dot( wsSeat, vec3( 127.1, 311.7, 74.7 ) ) ) * 43758.5453 );
73
+ vec2 wsC = ${CORNER_ATTRIBUTE};
74
+ float wsT = wsCardTime * wsCardMotion.y;
75
+ wsCardFade = 1.0;
76
+ if ( wsCardMotion.x > 0.5 && wsCardMotion.x < 1.5 ) {
77
+ float s = 0.6 * sin( wsT * 6.2831853 + wsPh * 6.2831853 ) + 0.4 * sin( wsT * 15.1 + wsPh * 12.0 );
78
+ wsC.y *= 1.0 + wsCardMotion.z * s;
79
+ wsC.x *= 1.0 - 0.5 * wsCardMotion.z * s;
80
+ } else if ( wsCardMotion.x > 1.5 && wsCardMotion.x < 2.5 ) {
81
+ wsSeat += vec3( sin( wsT + wsPh * 6.2831853 ), 0.42 * sin( wsT * 2.3 + wsPh * 12.5 ), cos( wsT * 0.83 + wsPh * 6.2831853 ) ) * wsCardMotion.z;
82
+ } else if ( wsCardMotion.x > 2.5 ) {
83
+ float k = fract( wsPh * 7.0 + wsT );
84
+ float a = wsPh * 40.0;
85
+ wsSeat += vec3( cos( a ) * wsCardMotion.w * k, wsCardMotion.z * k, sin( a ) * wsCardMotion.w * k );
86
+ wsCardFade = 1.0 - k;
87
+ wsC *= 1.0 - 0.5 * k;
88
+ }
89
+ vec4 mvPosition = modelViewMatrix * vec4( wsSeat, 1.0 );
90
+ mvPosition.xy += wsC;
91
+ gl_Position = projectionMatrix * mvPosition;
92
+ `;
93
+
94
+ const MOTION_KIND: Readonly<Record<string, number>> = { pulse: 1, drift: 2, rise: 3 };
95
+
96
+ /** Emissive: alpha blend, cards and their motion (a no-op for a plain surface). `clock` is the emissive look's. */
97
+ export function applySceneEmissive(m: THREE.MeshBasicMaterial, params: EmissiveMaterialParams, clock: THREE.IUniform<number>): void {
98
+ if (params.blend === 'alpha') { m.transparent = true; m.depthWrite = false; m.alphaTest = Math.max(m.alphaTest, 0.01); m.userData['sceneAlpha'] = true; }
99
+ if (params.card !== true) return;
100
+ const motion = params.motion;
101
+ const vector = new THREE.Vector4(motion === undefined ? 0 : MOTION_KIND[motion.kind] ?? 0, motion?.rate ?? 0,
102
+ motion === undefined ? 0 : motion.kind === 'pulse' ? motion.amount : motion.kind === 'drift' ? motion.radius : motion.height,
103
+ motion?.kind === 'rise' ? motion.spread : 0);
104
+ const uniforms: Record<string, THREE.IUniform> = { wsCardTime: clock, wsCardMotion: { value: vector } };
105
+ m.userData['sceneCard'] = true;
106
+ patchShader(m, 'engine.family.sceneCard', PATCH_ORDER.material, (shader) => {
107
+ Object.assign(shader.uniforms, uniforms);
108
+ if (!shader.vertexShader.includes('#include <project_vertex>')) throw new Error('scene card: the basic vertex source has no <project_vertex>');
109
+ shader.vertexShader = shader.vertexShader
110
+ .replace('#include <common>', `#include <common>\nuniform float wsCardTime;\nuniform vec4 wsCardMotion;\nattribute vec2 ${CORNER_ATTRIBUTE};\nvarying float wsCardFade;`)
111
+ .replace('#include <project_vertex>', CARD_VERTEX);
112
+ shader.fragmentShader = shader.fragmentShader
113
+ .replace('#include <common>', '#include <common>\nvarying float wsCardFade;')
114
+ .replace('#include <opaque_fragment>', 'outgoingLight *= wsCardFade;\ndiffuseColor.a *= wsCardFade;\n#include <opaque_fragment>');
115
+ }, { key: (before) => `${before}|scene-card` });
116
+ }